Object storage

Authorize files through project metadata

Object storage explains RLS-authorized metadata plus short-lived provider operations for file bytes.

Separating authoritative metadata from provider bytes keeps authorization and quota checks inside the project boundary.

Use it for buckets, uploads, downloads, listings, versions, deletes, or cleanup.

Requirements for Object storage

• Prerequisite — Configured internal/public S3 endpoints, bucket, credentials, and browser CORS.
• Prerequisite — A project table/policy model that defines who may access each object.
• Required value — Bucket name, object key, content type, exact size, checksum where required, and project session.
• Required value — For browser operations, the exact public S3 origin allowed by CSP and CORS.

Storage model

Bytes live in an S3-compatible provider. Buckets, object metadata, ownership, checksums, versions, quotas, reservations, and multipart state live in the project database. Provider listings are never an authorization source.

await ffdb.storage.upload(
  "avatars",
  "users/" + userId + "/avatar.png",
  file,
  { sizeBytes: file.size, contentType: file.type },
);

const page = await ffdb.storage.list("avatars", {
  prefix: "users/" + userId + "/", limit: 50,
});

Authorization sequence

• Validate the logical bucket and key.
• Evaluate operation-specific RLS with immutable auth context.
• Reserve quota and a single-use operation durably in SQLite.
• Mint a short-lived grant and method/key-bound provider URL.
• Commit metadata only after the provider succeeds.

Object storage workflow

• 1. Create or select a logical bucket.
• 2. Request an upload authorization with declared metadata.
• 3. Send bytes directly to the returned provider URL without logging it.
• 4. Commit or verify the upload through FFDB.
• 5. Request a fresh download URL only after RLS authorization.

Verify object storage

Object bytes exist in S3 while FFDB metadata, quota, versions, and visibility remain authoritative and RLS constrained.

Troubleshoot object storage

• Provider upload succeeds but commit fails — preserve the request ID and use bounded cleanup/retry.
• Browser upload is blocked — align exact S3 CORS and gateway CSP origins.

Continue from Object storage

• Use multipart uploads for large objects.
• Add storage lifecycle and quota monitoring.