Supabase + Cloudflare Workers Infrastructure

┌──────────────────────────────────────────────────────────────────┐
│                          iOS Client                                │
│              (URLSession only — never talks to Supabase)           │
└──────────────────────────────┬─────────────────────────────────────┘
                               │ HTTPS (REST + Bearer JWT)
                               ▼
┌──────────────────────────────────────────────────────────────────┐
│                 Cloudflare Workers  (Hono backend)                 │
│   src/index.ts → routes → middleware (verify JWT) → supabase-js    │
│   compatibility_flags: ["nodejs_compat"]                           │
└───────────────┬───────────────────────────────┬────────────────────┘
                │ service_role (bypass RLS)      │ user JWT (RLS on)
                ▼                                ▼
┌──────────────────────────────────────────────────────────────────┐
│                        Supabase project                            │
│   Auth (GoTrue)   ·   Postgres + RLS   ·   Storage (private)       │
│   region: chosen at creation — IMMUTABLE                           │
└──────────────────────────────────────────────────────────────────┘

        Deploy / provision path (two independent pipelines):
        ┌─────────────────────┐        ┌──────────────────────────┐
        │  supabase CLI       │        │  wrangler / GitHub CI     │
        │  db push → Postgres │        │  deploy → Workers runtime │
        └─────────────────────┘        └──────────────────────────┘

Component roles:

iOS stays dependency-free: the client only ever talks to the Worker over REST. It never imports supabase-swift and never holds the service_role key. The Worker is the only thing that touches Supabase. See auth-supabase-anonymous.

1. Tooling

npm install hono @supabase/supabase-js jose zod
npm install --save-dev wrangler @cloudflare/workers-types typescript
brew install supabase/tap/supabase

2. Supabase project (one-time)

supabase login
# Create the project in the correct region (IMMUTABLE) — dashboard or CLI.
supabase link --project-ref <project-ref>

• Project created in the correct, immutable region
• (Recommended) migrated to ES256 signing keys; SUPABASE_JWT_SECRET left empty
• supabase/config.toml committed with auth toggles

3. Schema

• Migrations authored idempotently in supabase/migrations/
• npm run db:push applies cleanly to the linked project
• RLS enabled on every user-data table (see infra-supabase-rls)

4. Secrets

• .dev.vars populated locally and confirmed in .gitignore
• .dev.vars.example committed with placeholders only
• All secrets set in Cloudflare as Secret type (wrangler secret put or dashboard)
• grep -rn "sb_secret_\|service_role" . returns nothing in tracked files

5. Deploy

• npm run typecheck passes
• npm run deploy succeeds; /health returns 200
• (Optional) GitHub connected for auto-deploy on push

1. Supabase project region is immutable

Symptom: latency is poor for your users, or a compliance requirement is unmet, and you cannot change it.

Fix: the region is chosen at project creation and cannot be changed afterwards. Pick it correctly on step one. Moving regions later means creating a new project and migrating data.

2. Missing nodejs_compat → supabase-js crashes on Workers

Symptom: runtime error about a missing Node built-in (e.g. stream, crypto) as soon as a route calls supabase-js.

Fix: set "compatibility_flags": ["nodejs_compat"] in wrangler.jsonc. supabase-js depends on Node polyfills that Workers only exposes behind this flag.

3. Using process.env instead of c.env

Symptom: undefined config at the edge; secrets never load.

Fix: Workers inject bindings into the Hono context. Read c.env.SUPABASE_URL, never process.env. Type them in Env (src/types.ts).

4. service_role key committed to git or shipped to the client

Symptom: full-database compromise — the key bypasses every RLS policy.

Fix: the key lives only in .dev.vars (gitignored) and Cloudflare Secret. It is never in wrangler.jsonc, never in a tracked file, never in the iOS app. .dev.vars.example carries placeholders only.

5. Secret set as a plaintext "build" var instead of a runtime Secret

Symptom: the secret is visible in the dashboard and/or logs; it does not reach c.env at runtime as expected.

Fix: use wrangler secret put or the dashboard's Variables and Secrets → Secret (encrypted, runtime) section. Do not paste secrets into vars in wrangler.jsonc (those are plaintext, build-time).

6. service_role used to reliably bypass RLS but requests still hit RLS

Symptom: a system operation (e.g. initializing a profile row) is unexpectedly blocked by RLS.

Cause: with the new sb_secret_ key format, passing the key only as the createClient apikey arg does not always set the PostgREST role — requests fall back to an RLS-constrained role.

Fix: put the key explicitly in the Authorization: Bearer header (as serviceClient does above). PostgREST decides the role from Authorization, not apikey.

7. Migration applied by hand diverges from the file

Symptom: a fresh project (or teammate) can't reproduce the schema; something works only on your project.

Fix: every schema change is a file in supabase/migrations/, applied with supabase db push. Never make a change only in the dashboard SQL Editor without capturing it as a migration. Write files idempotently so re-apply is a no-op.

8. npm install -g supabase fails or misbehaves

Symptom: the global npm install of the Supabase CLI errors or is flagged unsupported.

Fix: install the CLI via Homebrew (brew install supabase/tap/supabase) or as a project devDependency. The npm global install path is not supported.

Production Readiness Checklist

• Project in the correct immutable region, migrated to ES256 signing keys
• RLS enabled and tested on every user-data table (infra-supabase-rls)
• Private buckets + signed URLs for any user files (infra-supabase-storage)
• All secrets are Cloudflare Secret type; nothing sensitive in git or wrangler.jsonc
• enable_refresh_token_rotation = true and an anonymous-sign-in rate limit set
• Edge Rate Limiting / WAF in front of the Worker
• pg_cron job purging empty, expired anonymous users
• Workers observability enabled; a staging project separate from production