← All decisions

Storage uploads route through the API, not direct from the browser

accepted

0017 — Storage uploads route through the API, not direct from the browser

Context

Ark uses Supabase Storage as its canonical image store (ADR 0015). Supabase Storage supports two upload paths: the browser calls Supabase directly using the anon key and a row-level-security (RLS) policy approves or denies the write, or the browser calls ark’s own API which in turn calls Supabase using a privileged service-role key.

During Workstream D (branding — logo upload), we first implemented the direct path. RLS policies were written, tested locally, and passed manual checks against the predicate logic. In the live production environment, every upload attempt was rejected — even when the session looked correct and the policy predicates were satisfied in isolation.

The root cause is structural, not incidental: the JWT that the browser sends to Supabase Storage must carry a custom claim (org_roles) that identifies which organisations the member administers. That claim is stamped into the token by a database hook that fires at sign-in. Production JWT issuance, caching, and claim propagation have subtle timing and edge conditions. Any mismatch between what the claim says and what the storage policy expects — including clock skew, token age, or hook misconfiguration — silently rejects the write. The policy evaluates a stored value in the JWT; it cannot recover from a stale or missing claim by re-querying the database at upload time.

The API does not have that constraint. It authenticates the user, re-queries the current membership table to confirm the upload is authorised right now, and then calls Supabase using the service-role key — which bypasses Storage RLS entirely. The authorisation decision lives in code we own and can test with real database rows, not in a JWT claim we cannot introspect from the browser.

Decision

For every new storage upload surface in ark, the upload path goes through the ark API. The browser never calls Supabase Storage directly.

Concretely, for each surface that accepts an uploaded file:

  1. A dedicated API route (POST /<surface>/<filename>) accepts the raw bytes in the request body.
  2. The route resolves the caller’s organisation from their session, then re-queries org_members to confirm the required role. If the check fails, it returns a 403 before touching storage.
  3. On success the route calls supabase.storage.from('org-public').upload(path, bytes, { upsert: true }) using the service-role client — no RLS evaluation in the storage layer.
  4. Any authorisation logic is covered by an integration test that signs in as an unauthorised role and asserts a 403, and separately as an authorised role and asserts a 200. That test uses the real database; it does not mock the membership query.

The reference implementations are apps/api/src/routes/branding.ts (logo upload) and apps/api/src/routes/cms.ts + apps/api/src/routes/profile.ts (CMS hero images and member avatars, added in Workstream B). New upload surfaces mirror these files.

Consequences

Easier:

Harder:

Alternatives considered

Direct browser upload with RLS. The natural Supabase pattern; fewer moving parts in the happy path. Failed in production due to JWT claim propagation behaviour described above. Even if the immediate cause were fixed, it would remain fragile: production RLS evaluations happen inside the database with no visibility from the browser at the time of failure. Rejected.

Direct browser upload with a short-lived signed upload URL issued by the API. The API verifies auth, generates a time-limited Supabase Storage upload URL, and returns it to the browser. The browser uploads directly to that URL. Keeps the large-byte transfer off the API server. Reasonable at higher file volumes. Deferred — ark’s current asset sizes don’t justify the additional moving part (signed URL TTLs, presign/upload race conditions), and the simpler proxy path is easier to test. Revisit if CMS assets grow large enough to make API throughput a concern.

Trip-wires

We revisit this if: