Storage module

Beginner walkthrough

Prerequisites: Read the two beginner guides below, finish Web local setup, and open this monorepo at its root in your editor. Web settings belong in apps/web/.env.local; Next.js does not read the root .env. /dashboard in the default fake mode is a no-database demo; /auth needs a migrated database.

Quick terms: a workspace is one team's separate users, data, and settings. The server is the trusted backend; keep provider keys out of browser and phone code. A migration is a versioned database change that creates or updates tables. An AI model is the engine that answers; the model catalog is the server's list of available model IDs and prices. A provider is an outside service such as an AI, email, or billing service. An entitlement is a grant that lets a workspace use a feature. A webhook is a message one service sends to another service's URL.

1. For a no-credential trial, keep STORAGE_PROVIDER=memory. If this checkout has no visible upload control, ask your coding agent to inspect apps/web/app/api/storage/avatar/route.ts, apps/web/app/api/storage/logo/route.ts, apps/web/app/api/storage/organization-logo/route.ts, and the matching settings page before wiring a small sample image.

2. To check persistence, set STORAGE_PROVIDER=s3, STORAGE_REGION, and STORAGE_BUCKET in apps/web/.env.local, add server-only test credentials locally, and restart.

3. The image should reload from storage. Memory files disappear when the process restarts; for S3 errors, check bucket, endpoint, and access policy.

For custom code, start with the supplied prompts/README.md and copy the closest prompt: prompts/new-app-screen.md for an app screen or prompts/new-landing-page.md for a public page. For server, database, or provider work, give your coding agent this guide's task and ask it to read AGENTS.md, .ai/PROJECT_CONTEXT.md, and matching .ai/ mirrors; inspect the exact source files named here; list files and checks before editing; preserve workspace ownership and server-only secrets; and show you the diff. Tell it the behavior you want, input and output fields, allowed roles, expected success and errors, and the test account, provider, or device. Use sample values; never paste a real secret.

• Before you start
• Terminal basics
• Web local setup
• Agent prompts & project memory

Select the storage backend

STORAGE_PROVIDER=memory is the credential-free default. local writes objects to disk under STORAGE_LOCAL_DIR (default ./.data/storage, required explicitly in production) and streams them through HMAC-signed expiring URLs at /api/storage/local/[...key] (STORAGE_LOCAL_SIGNING_SECRET, falling back to AUTH_SECRET) for single-server deployments. s3 uses apps/web/src/storage-runtime.ts to compose the AWS SDK client over the narrow @supastack/storage contract, supporting Supabase Storage and MinIO with path-style URLs enabled by default.

STORAGE_PROVIDER=s3
STORAGE_REGION=us-east-1
STORAGE_BUCKET=your-product-bucket
# Set STORAGE_ACCESS_KEY_ID and STORAGE_SECRET_ACCESS_KEY on the server.
# Optional: STORAGE_ENDPOINT, STORAGE_FORCE_PATH_STYLE, STORAGE_PUBLIC_BASE_URL
# Self-hosted single-server disk storage:
# STORAGE_PROVIDER=local
# STORAGE_LOCAL_DIR=./.data/storage
# STORAGE_LOCAL_SIGNING_SECRET=

Reuse the upload boundaries

The shipped routes cover objects, avatars, profile logos and organization logos under /api/storage/. They resolve identity/workspace permissions and validate upload shape before storage. Inspect the chosen route's size/type policy rather than accepting arbitrary client object keys.

Public URLs are presentation, not authorization. Keep protected content behind the application's verified read boundary and configure bucket/CDN policy for your product's data.

Test real storage behavior

Test allowed/denied uploads, MIME and size rejection, foreign-workspace paths, missing objects and provider failure. Memory mode does not persist across processes; verify storage and retrieval against the selected backend before release.

• Supabase Storage setup
• Upload route inventory

Setup and configuration

packages/storage defines the ObjectStorage interface — putObject, getObject, and deleteObject against object locators — with MemoryObjectStorage for deterministic tests and S3CompatibleObjectStorage for production buckets.

Object keys are built with buildWorkspaceObjectKey and checked with assertWorkspaceObjectKey, so every stored file is namespaced by workspace and purpose (avatar, file, logo). WorkspaceScopedStorageError fires when a key escapes its workspace.

interface ObjectStorage {
  putObject(input: PutObjectInput): Promise<StoredObject>
  getObject(locator: ObjectLocator): Promise<StoredObject | undefined>
  deleteObject(locator: ObjectLocator): Promise<boolean>
  getPublicUrl(locator: ObjectLocator): string
}

key = {workspaceId}/{purpose}/{safeName}

Implementation workflow

Application routes resolve the workspace, validate the upload, build the scoped key, and call the adapter — storage never sees a raw client path. Select the adapter in the server environment through STORAGE_PROVIDER and its credentials.

Expose reads through the same authorization boundary; only serve public URLs for objects the product deliberately publishes.

Verification and troubleshooting

MemoryObjectStorage keeps unit tests deterministic — assert keys, content types, and cross-workspace denials there. Verify the S3 adapter through the opted-in smoke path against a real bucket before shipping uploads.