File Uploads & Supabase Storage

# Attachment security checklist

- Private bucket by default.
- Service-role key only in NestJS/server environment.
- NestJS authorizes Task membership before issuing upload/download capabilities.
- Server generates object paths; never trust client-supplied paths.
- Allowlist MIME types and cap size in API + bucket.
- Original name is display metadata only.
- Finalize verifies object existence, size and content type.
- Signed download URLs are short-lived.
- Do not store signed URLs in PostgreSQL.
- Do not mutate `storage.objects` directly.
- Add malware/quarantine scanning for higher-risk file classes.
- Clean abandoned PENDING uploads and failed DELETING records.

# TaskFlow Phase 27 - File Uploads and Supabase Storage

Reference snapshot for a signed-upload-intent architecture. NestJS authorizes attachment operations, Supabase Storage holds bytes, and PostgreSQL stores application metadata.

Default bucket: `task-attachments` (private). Default app limit: 20 MB.

# Official sources

- Supabase Storage overview: https://supabase.com/docs/guides/storage
- Supabase Standard Uploads: https://supabase.com/docs/guides/storage/uploads/standard-uploads
- Supabase Resumable Uploads: https://supabase.com/docs/guides/storage/uploads/resumable-uploads
- Supabase Storage Access Control: https://supabase.com/docs/guides/storage/security/access-control
- Supabase Storage Ownership: https://supabase.com/docs/guides/storage/security/ownership
- Supabase Storage Schema: https://supabase.com/docs/guides/storage/schema/design
- Supabase File Limits: https://supabase.com/docs/guides/storage/uploads/file-limits
- Supabase createSignedUploadUrl: https://supabase.com/docs/reference/javascript/file-buckets-createsigneduploadurl
- Supabase uploadToSignedUrl: https://supabase.com/docs/reference/javascript/file-buckets-uploadtosignedurl
- Supabase createSignedUrl: https://supabase.com/docs/reference/javascript/file-buckets-createsignedurl
- Supabase info: https://supabase.com/docs/reference/javascript/file-buckets-info
- Supabase createBucket: https://supabase.com/docs/reference/javascript/file-buckets-createbucket
- tus-js-client npm: https://www.npmjs.com/package/tus-js-client

SUPABASE_URL=https://YOUR_PROJECT.supabase.co
SUPABASE_SERVICE_ROLE_KEY=SERVER_ONLY_SECRET
TASK_ATTACHMENT_BUCKET=task-attachments

enum AttachmentStatus {
  PENDING
  READY
  DELETING
}

model TaskAttachment {
  id           String           @id @default(uuid())
  taskId       String
  uploadedById String
  bucket       String           @default("task-attachments")
  objectPath   String           @unique
  originalName String
  mimeType     String
  sizeBytes    Int
  status       AttachmentStatus @default(PENDING)
  createdAt    DateTime         @default(now())
  readyAt      DateTime?

  task       Task @relation(fields: [taskId], references: [id], onDelete: Cascade)

import { ATTACHMENT_EXTENSION_BY_MIME } from "./attachment.constants"

export function buildAttachmentObjectPath(input: {
  workspaceId: string
  taskId: string
  attachmentId: string
  mimeType: keyof typeof ATTACHMENT_EXTENSION_BY_MIME
}) {
  const ext = ATTACHMENT_EXTENSION_BY_MIME[input.mimeType]
  return `workspaces/${input.workspaceId}/tasks/${input.taskId}/${input.attachmentId}.${ext}`
}

export const ATTACHMENT_BUCKET = "task-attachments"
export const MAX_ATTACHMENT_BYTES = 20 * 1024 * 1024

export const ALLOWED_ATTACHMENT_MIME_TYPES = [
  "application/pdf",
  "image/png",
  "image/jpeg",
  "text/plain",
] as const

export const ATTACHMENT_EXTENSION_BY_MIME = {
  "application/pdf": "pdf",
  "image/png": "png",
  "image/jpeg": "jpg",
  "text/plain": "txt",
} as const

import { z } from "zod"
import { ALLOWED_ATTACHMENT_MIME_TYPES, MAX_ATTACHMENT_BYTES } from "./attachment.constants"

export const createAttachmentIntentSchema = z.strictObject({
  originalName: z.string().trim().min(1).max(255),
  mimeType: z.enum(ALLOWED_ATTACHMENT_MIME_TYPES),
  sizeBytes: z.number().int().positive().max(MAX_ATTACHMENT_BYTES),
})

export type CreateAttachmentIntent = z.infer<typeof createAttachmentIntentSchema>

import { Body, Controller, Param, Post, UseGuards } from "@nestjs/common"
import { StandardSchemaValidationPipe } from "@nestjs/common"
import { SupabaseAuthGuard } from "../auth/supabase-auth.guard"
import { CurrentUser } from "../common/decorators/current-user.decorator"
import type { AuthenticatedUser } from "../auth/authenticated-user"
import { createAttachmentIntentSchema, type CreateAttachmentIntent } from "./attachment.schemas"
import { AttachmentsService } from "./attachments.service"

@Controller()
@UseGuards(SupabaseAuthGuard)
export class AttachmentsController {
  constructor(private readonly attachments: AttachmentsService) {}

  @Post("tasks/:taskId/attachments/upload-intents")
  createIntent(
    @Param("taskId") taskId: string,
    @CurrentUser() user: AuthenticatedUser,
    @Body(new StandardSchemaValidationPipe(createAttachmentIntentSchema))
    body: CreateAttachmentIntent,
  ) {

import { Module } from "@nestjs/common"
import { AttachmentsController } from "./attachments.controller"
import { AttachmentsService } from "./attachments.service"
import { SupabaseStorageService } from "../storage/supabase-storage.service"

@Module({
  controllers: [AttachmentsController],
  providers: [AttachmentsService, SupabaseStorageService],
})
export class AttachmentsModule {}

import { randomUUID } from "node:crypto"
import { Injectable } from "@nestjs/common"
import { ATTACHMENT_BUCKET } from "./attachment.constants"
import { buildAttachmentObjectPath } from "./attachment-path"
import type { CreateAttachmentIntent } from "./attachment.schemas"
import type { AuthenticatedUser } from "../auth/authenticated-user"
import { SupabaseStorageService } from "../storage/supabase-storage.service"

@Injectable()
export class AttachmentsService {
  constructor(
    private readonly storage: SupabaseStorageService,
    // inject Task/Attachment repositories used by the real application
  ) {}

  async createIntent(taskId: string, user: AuthenticatedUser, input: CreateAttachmentIntent) {
    // 1. Load Task inside the caller's authorized scope.
    // 2. Generate attachmentId + trusted objectPath.
    // 3. Insert PENDING TaskAttachment metadata row.
    // 4. Ask Storage for a signed upload token.

import { Injectable } from "@nestjs/common"
import { ConfigService } from "@nestjs/config"
import { createClient, SupabaseClient } from "@supabase/supabase-js"

@Injectable()
export class SupabaseStorageService {
  private readonly client: SupabaseClient

  constructor(config: ConfigService) {
    this.client = createClient(
      config.getOrThrow("SUPABASE_URL"),
      config.getOrThrow("SUPABASE_SERVICE_ROLE_KEY"),
      { auth: { persistSession: false, autoRefreshToken: false } },
    )
  }

  async createSignedUploadUrl(bucket: string, path: string) {
    const { data, error } = await this.client.storage
      .from(bucket)
      .createSignedUploadUrl(path, { upsert: false })

"use client"

import { useState } from "react"
import { useMutation, useQueryClient } from "@tanstack/react-query"

export function TaskAttachmentUploader({ taskId }: { taskId: string }) {
  const [progress, setProgress] = useState(0)
  const queryClient = useQueryClient()

  const mutation = useMutation({
    mutationFn: async (file: File) => {
      // create intent -> upload bytes -> complete attachment
      // use standard upload for small files; TUS when progress/resume is needed
      return { fileName: file.name }
    },
    onSuccess: async () => {
      setProgress(0)
      await queryClient.invalidateQueries({
        queryKey: ["tasks", taskId, "attachments"],
      })

import { createBrowserSupabaseClient } from "@/lib/supabase/client"

export async function uploadAttachmentFile(intent: {
  bucket: string
  objectPath: string
  token: string
}, file: File) {
  const supabase = createBrowserSupabaseClient()
  const { error } = await supabase.storage
    .from(intent.bucket)
    .uploadToSignedUrl(intent.objectPath, intent.token, file, {
      contentType: file.type,
    })
  if (error) throw error
}

import * as tus from "tus-js-client"

export function uploadFileTus(input: {
  projectRef: string
  signedUploadToken: string
  bucket: string
  objectPath: string
  file: File
  onProgress: (ratio: number) => void
}) {
  return new Promise<void>((resolve, reject) => {
    const upload = new tus.Upload(input.file, {
      endpoint: `https://${input.projectRef}.storage.supabase.co/storage/v1/upload/resumable`,
      headers: { "x-signature": input.signedUploadToken },
      metadata: {
        bucketName: input.bucket,
        objectName: input.objectPath,
        contentType: input.file.type,
      },
      chunkSize: 6 * 1024 * 1024,

import { createClient } from "@supabase/supabase-js"

const supabase = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_SERVICE_ROLE_KEY!,
  { auth: { persistSession: false, autoRefreshToken: false } },
)

const { error } = await supabase.storage.createBucket("task-attachments", {
  public: false,
  allowedMimeTypes: [
    "application/pdf",
    "image/png",
    "image/jpeg",
    "text/plain",
  ],
  fileSizeLimit: "20MB",
})

if (error && !String(error.message).toLowerCase().includes("already")) {

# Phase 27 test matrix

## Authorization
- No token cannot create an upload intent.
- Member outside the Task Workspace cannot attach/download/delete.
- Valid member can create an intent for an authorized Task.

## Validation
- Zero-byte, >20MB and disallowed MIME are rejected.
- Client cannot choose an object path.
- Generated paths are unique and Workspace/Task scoped.

## Lifecycle
- Intent creates PENDING metadata.
- Successful upload + matching Storage info becomes READY.
- Missing object cannot finalize.
- Metadata mismatch cannot finalize.
- Signed download expires.
- Delete removes bytes then metadata or leaves a recoverable DELETING state.
- Stale PENDING intents are cleaned.