@auth-craft/aws-cf-stack 1.3.0 → 1.6.0

package/.env.example

@@ -46,6 +46,13 @@ LAMBDA_APP_BASE_PATH=         # recommended — set a stable, non-guessable valu
                               #   changes between deploys, so clients/workers don't break.
 
 # ─── Cloudflare gateway workers ──────────────────────────────────────────────
+# Deploy model: 'multi' (default — 3 workers, one scope each; AUTH_SCOPE fixed per worker,
+# so scope is ENFORCED) or 'shared' (1 worker that derives scope from the path's first
+# segment). Shared is simpler (1 deploy/binding) but does NOT enforce scope on its own —
+# pair it with a scope-locked Pages proxy (@auth-craft/pages-auth-proxy `scope` option) if
+# customer apps must never reach system/tenant. In shared mode CORS unions all scopes and
+# the CORS_KV uses CF_CORS_KV_ID_SHARED (or falls back to CF_CORS_KV_ID_CUSTOMER).
+CF_GATEWAY_MODE=multi         # multi | shared
 CLOUDFLARE_API_TOKEN=         # required for gateway (flag --cf-api-token)
 CLOUDFLARE_ACCOUNT_ID=        # required for gateway (flag --cf-account-id)
 CF_EDGE_GATE_SECRET=          # required for gateway (flag --edge-gate-secret) — Client → Worker gate
@@ -84,6 +91,15 @@ CF_WORKER_DISABLE_PUBLIC_URL=          # shared default (e.g. true to disable al
 CF_WORKER_DISABLE_PUBLIC_URL_SYSTEM=   # e.g. true — admin app via Pages proxy
 CF_WORKER_DISABLE_PUBLIC_URL_TENANT=
 CF_WORKER_DISABLE_PUBLIC_URL_CUSTOMER=
+# Skip the X-Edge-Gate (Client → Worker) check. Redundant when the worker has NO public
+# URL and is reached only via a Service Binding (Pages proxy) — so it's ONLY honored when
+# CF_WORKER_DISABLE_PUBLIC_URL is also set for that scope (else ignored with a warning).
+# Does NOT affect the Worker → Backend secret (X-Gateway-Secret stays required). Truthy:
+# 1/true/yes. When skipped, EDGE_GATE_SECRET is not needed.
+CF_WORKER_SKIP_EDGE_GATE=              # shared default
+CF_WORKER_SKIP_EDGE_GATE_SYSTEM=      # e.g. true (pairs with DISABLE_PUBLIC_URL_SYSTEM)
+CF_WORKER_SKIP_EDGE_GATE_TENANT=
+CF_WORKER_SKIP_EDGE_GATE_CUSTOMER=
 
 # ─── Internal service JWT (optional — enables /internal/* + service worker verify) ─
 LAMBDA_INTERNAL_JWT_PUBLIC_KEY=          # optional — also fed to workers as SERVICE_JWT_PUBLIC_KEY
@@ -149,8 +165,10 @@ LAMBDA_FACEBOOK_CLIENT_ID=
 LAMBDA_FACEBOOK_CLIENT_SECRET=
 LAMBDA_FACEBOOK_REDIRECT_URI=
 
-# ─── Super-admin bootstrap (optional — skipped if any are unset) ─────────────
+# ─── Super-admin bootstrap (optional — the `admin` stage is skipped unless BOTH ───
+# EMAIL and PASSWORD are set; the skip message names which are missing). The admin CLI
+# talks to DynamoDB DIRECTLY and is idempotent: if an active owner already exists in the
+# system tenant it's a no-op, so re-runs are safe. No setup token is needed.
 LAMBDA_SUPER_ADMIN_EMAIL=
 LAMBDA_SUPER_ADMIN_PASSWORD=
 LAMBDA_SUPER_ADMIN_NAME=Super Admin
-LAMBDA_AUTH_SETUP_TOKEN=

package/README.md

@@ -17,7 +17,9 @@ or building the auth-craft repo** — just pass env and run.
 
 1. **DynamoDB + Lambda** (CDK) — the auth backend. Emits a Function URL + a base path.
 2. **Super-admin** (idempotent) — bootstraps the `__system__` tenant owner.
-3. **3 gateway workers** (system / tenant / customer) on Cloudflare, via wrangler.
+3. **Gateway worker(s)** on Cloudflare, via wrangler. Default `multi` = **3 workers**
+   (system / tenant / customer); `CF_GATEWAY_MODE=shared` = **1 worker**. See
+   [Deploy model](#deploy-model-multi-vs-shared).
 
 The gateway's `BACKEND_URL` is computed as `FunctionURL + ApiBasePath` read back from the
 **live CDK outputs** of the same deploy — so the worker config can never drift from the
@@ -33,18 +35,38 @@ Everything is named from `--stage` (`dev|staging|prod`) and `--project` (default
 |----------|------|
 | CDK stacks | `<app>-<stage>-data`, `<app>-<stage>-api` |
 | Lambda fn + DynamoDB table | `<app>-<stage>` |
-| Gateway workers | `<app>-<stage>-system` / `-tenant` / `-customer` |
+| Gateway workers (`multi`) | `<app>-<stage>-system` / `-tenant` / `-customer` |
+| Gateway worker (`shared`) | `<app>-<stage>` |
 
 So `outputs`/`gateway` look up the api stack `<app>-<stage>-api`. The CDK output keys are
 `LambdaFunctionUrl`, `ApiBasePath`, `AuthSystemName`, `DynamoDBTableName`.
 
+### Deploy model (multi vs shared)
+
+`CF_GATEWAY_MODE` picks how the gateway is deployed:
+
+- **`multi`** (default) — 3 workers, one scope each. Each worker has a fixed `AUTH_SCOPE`,
+  so the scope is **enforced server-side**: a customer worker can never act as system,
+  whatever path the client sends. Strongest isolation; 3 deploys + 3 Service Bindings.
+- **`shared`** — 1 worker. Scope is derived from the path's first segment
+  (`/system/...` → `system`), so the worker by itself does **not** enforce scope (a client
+  could send `/system/...`). Simpler: 1 deploy, 1 binding, unioned CORS. **Pair it with a
+  scope-locked Pages proxy** (`createPagesAuthProxy({ scope: 'customer' })` from
+  [@auth-craft/pages-auth-proxy](../pages-auth-proxy/README.md)) so the *proxy* prepends
+  the scope and the client never picks it — that restores the "customer can't reach
+  system" guarantee at the edge.
+
+In `shared` mode CORS unions all per-scope origins/suffixes, and the dynamic-CORS KV uses
+`CF_CORS_KV_ID_SHARED` (falling back to `CF_CORS_KV_ID_CUSTOMER`). `outputs.workerNames.*`
+all point at the single worker.
+
 ## Commands
 
 | Command | Does |
 |---------|------|
 | `lambda`  | Deploy the DynamoDB + Lambda CDK stacks. `--outputs-file <p>` writes the raw CDK outputs JSON. Runs a best-effort `/health` check. |
-| `admin`   | Create the super-admin (idempotent; **skips** if `LAMBDA_SUPER_ADMIN_*` / `LAMBDA_AUTH_SETUP_TOKEN` unset; "already exists" = success). |
-| `gateway` | Deploy the 3 gateway workers. Re-reads the Lambda outputs from CloudFormation if run as a separate invocation. |
+| `admin`   | Create the super-admin (idempotent; **skips** if `LAMBDA_SUPER_ADMIN_EMAIL`/`LAMBDA_SUPER_ADMIN_PASSWORD` unset; "already exists" = success). |
+| `gateway` | Deploy the gateway worker(s) — 3 (`multi`, default) or 1 (`CF_GATEWAY_MODE=shared`). Re-reads the Lambda outputs from CloudFormation if run as a separate invocation. |
 | `all`     | `lambda` → `admin` → `gateway`, one run. |
 | `outputs` | Print the live api-stack outputs as JSON (no deploy): `backendUrl`, `apiBasePath`, `dynamodbTable`, and the auth keys read **from the live Lambda config** (`jwtPublicKey`, `jwtIssuer`, `jwtAlgorithm`, `serviceJwtPublicKey`) + `gatewayUrls`/`routePrefixes`. Self-contained — works standalone (no env), so an orchestrator can auto-fill its `*_AUTH_*` vars. |
 
@@ -76,7 +98,7 @@ Inputs come from **flags or environment variables** (flag wins, then env, then
 | Stage | Required |
 |-------|----------|
 | `lambda`  | `LAMBDA_JWT_PRIVATE_KEY`, `LAMBDA_JWT_PUBLIC_KEY`, and `LAMBDA_GATEWAY_SECRET` (required for staging/prod; optional in dev). AWS creds in env. |
-| `admin`   | `LAMBDA_SUPER_ADMIN_EMAIL`, `LAMBDA_SUPER_ADMIN_PASSWORD`, `LAMBDA_AUTH_SETUP_TOKEN` (else skipped). AWS creds. |
+| `admin`   | `LAMBDA_SUPER_ADMIN_EMAIL`, `LAMBDA_SUPER_ADMIN_PASSWORD` (else skipped). AWS creds. |
 | `gateway` | Hard-required: `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID`. Needed in practice (pushed as worker secrets; empty ones are skipped but the gateway then rejects clients / can't reach the backend): `CF_EDGE_GATE_SECRET`, `LAMBDA_GATEWAY_SECRET`, `LAMBDA_JWT_PUBLIC_KEY`. |
 
 Set `LAMBDA_APP_BASE_PATH` to a **stable** value — if unset, a random base path is generated
@@ -230,6 +252,16 @@ domain). This applies only when no `CF_WORKER_CUSTOM_DOMAIN_<SCOPE>` is set for
 if you're using `AUTH_GATEWAY_URL` (no binding) leave it off, since that path needs the
 public URL.
 
+**Skip the edge gate (optional).** The `X-Edge-Gate` secret exists to stop the public
+internet from hitting the worker. Once the public URL is disabled and the worker is
+reached only via a Service Binding, that gate is redundant — set
+`CF_WORKER_SKIP_EDGE_GATE=true` (or per scope) to drop it; the Pages proxy then needs no
+`EDGE_GATE_SECRET`. For safety it's **only honored when the public URL is also disabled**
+for that scope (otherwise ignored with a warning). It does **not** touch the
+Worker → Backend secret: `X-Gateway-Secret` stays required because the backend (Lambda
+Function URL) is still on the public internet — without it, anyone could call the Lambda
+directly.
+
 ### Per-scope token transport
 
 `REFRESH_TOKEN_STRATEGY` sets the transport for every scope. To mix, use the per-scope