Storage

Storage in packages/storage is a thin layer over the AWS S3 SDK, intentionally provider-agnostic. Any S3-compatible store works because the only configuration that changes is the endpoint URL.

Uploads go directly from the browser to the bucket via a presigned URL, so serverless body-size limits never apply. The server is not in the upload path but it is in the validation path: a finalize step re-fetches the bytes, validates them with sharp, re-encodes the result to a stable final key, and cleans up the temporary key in every server-observable failure mode.

How An Upload Flows

Why three round-trips. It moves bytes off the serverless boundary (no Vercel 4.5 MB body limit, no equivalent platform cap) while still letting the server validate the content. The presigned URL expires in 6 minutes, so if a user walks away mid-upload the URL stops working before any infinite-write window is opened.

Why finalize re-encodes. Re-encoding through sharp is the security boundary. A file that decodes cleanly in sharp is unambiguously an image. Anything else throws and the temp key is deleted automatically.

The diagram source lives at apps/docs/diagrams/storage-upload.mmd. Rerun pnpm --filter @syntaxkit/docs diagrams:build after editing it to refresh both SVG variants.

Package Layout

The storage package owns the entire upload subsystem: key conventions, policy, the sharp pipeline, and the presign + finalize S3 orchestration. presignImageUpload and finalizeImageUpload are plain functions here, throwing a framework-agnostic StorageError. The oRPC endpoints in packages/api/src/router/storage.ts are a thin adapter: they enforce auth and abuse policy, resolve the bucket from the environment, call into the storage package, and map StorageError to ORPCError. The storage package owns the workflow; the API package owns the transport.

Configuring Storage

The provider-specific env blocks (AWS S3, Cloudflare R2, MinIO) plus a verification step live on Setup: Storage. The kit doesn't care which S3-compatible store you pick: same SDK, same code path, only the endpoint and credentials differ.

The full per-variable reference is on Environment Variables: Object Storage (S3).

File Constraints And Server-Side Validation

Client-side checks reject the wrong size or MIME before presign. Server-side sharp is the source of truth: anything that doesn't decode (or that exceeds the dimension limit) returns an error and the temp object is removed. Final outputs are always re-encoded; original bytes never become the served file.

The size limit is enforced in three layers, because presigned PUT URLs do not reliably enforce Content-Length across S3-compatible providers:

1. The client and the presign Zod schema reject anything larger than MAX_FILE_SIZE before a URL is signed.
2. finalize issues a HeadObject first and refuses any temp key whose Content-Length exceeds the limit (or is missing). No body bytes are downloaded in that path.
3. The GetObject body is then read with a hard byte cap. If the streamed payload exceeds the cap mid-read (for example because a non-conformant backend understated the size, or the user re-uploaded between HEAD and GET), the read aborts and the temp key is deleted. The worker never materializes more than MAX_FILE_SIZE in memory.

What Gets Uploaded

Required Bucket Configuration

The kit doesn't and can't auto-provision your bucket. Two settings are easy to miss because they're operational rather than code-level. Both rules are copy-pasteable.

CORS. The browser PUTs directly to a presigned URL. Without CORS allowing PUT from your app origin, every upload fails silently (or with an opaque "Failed to upload to S3" toast). Recommended rule:

[
  {
    "AllowedOrigins": ["https://your-app.com"],
    "AllowedMethods": ["PUT"],
    "AllowedHeaders": ["*"],
    "ExposeHeaders": ["ETag"]
  }
]

Lifecycle rule for tmp/. The kit deletes temp objects when finalize succeeds, when image processing fails, or when the final upload to the long-term key fails. The one case it cannot catch is the user abandoning the upload between presign and finalize; the server is never called again, so app code has no event to react to. A bucket lifecycle rule that expires tmp/ after 1 day catches that residual case (and is a sensible safety net regardless):

{
  "Rules": [
    {
      "ID": "expire-tmp-uploads",
      "Status": "Enabled",
      "Filter": { "Prefix": "tmp/" },
      "Expiration": { "Days": 1 }
    }
  ]
}

Graceful Degradation

When the storage env block is missing, isStorageEnabled returns false and the dashboard handles it differently per surface:

• Personal settings and organization settings replace the avatar form with a placeholder card explaining that storage isn't configured.
• The AI chat composer hides the image-attachment button entirely. The rest of the chat keeps working.

pnpm setup:doctor reports storage status alongside every other capability. See Environment Variables for the full env matrix.

Cleanup Behavior

Four cleanup helpers cover the lifecycle, in order from "single key" to "everything a principal ever uploaded".

Why The Org-Delete Hook Runs Before The Cascade

afterDeleteOrganization can't read the messages: by the time it fires, Prisma has already cascaded Chat/Message rows away. Reading Message.parts therefore happens in beforeDeleteOrganization, alongside the existing afterDeleteOrganization logo cleanup. Together they cover every S3 byte tied to the org.

Single-Reference Assumption

Every presign + finalize round trip mints a fresh crypto.randomUUID() key, and the chat composer never reuses a previous upload, so each images/{userId}/<uuid> key is referenced by at most one message in practice. Cleanup deletes by key without reference counting. If you ever build a "send same image again" / attachment library / cross-chat reuse feature, replace this with a chat_attachment table that tracks (key, userId, refCount) and only deletes from S3 when refCount drops to zero.

IAM

Both cleanup paths require list and delete on the bucket. The IAM role that the app runs under needs s3:ListBucket, s3:DeleteObject, and s3:DeleteObjects on arn:aws:s3:::<bucket> and arn:aws:s3:::<bucket>/* (or the equivalent on R2/MinIO). Without s3:ListBucket the user-delete prefix wipe degrades to a silent no-op.

Adding A New Upload Surface

The pattern is the same for any new file-upload feature.

Where To Go Next