Files
worldwideview/docs/feature-flags.md
SilvertakanaandClaude Opus 4.7 26568429bc feat(auth): ADR-001 Workstream C — ticket auth, SSRF protection, and pre-flight audit (#171)
* feat(auth): implement ADR-001 Workstream C — ticket auth, SSRF, and pre-flight audit

C1: Boot-time ENCRYPTION_MASTER_KEY / AUTH_SECRET validation (instrumentation.ts);
    remove silent fallback in encryption.ts; guard marketplace token from data-plane misuse.
C2: SSRF host-allowlist (PROXY_HOST_ALLOWLIST) in ssrf.ts; route iframe proxy through safeFetch.
C3: ticketClient.ts — exchanges long-lived API key for 5-min EdDSA ticket from Marketplace;
    audience fixed to ENGINE_AUDIENCE='wwv-data-engine'; cache keyed by engine not plugin.
C4: WsClient.ts first-message auth — sends {type:'auth',v:1,token} on open; queues subscribes
    until {type:'welcome'}; gated by ticketAuthEnabledForPlugin.
C5: edition.ts — ticketAuthEnabledForPlugin reads NEXT_PUBLIC_WWV_TICKET_AUTH_PLUGINS flag.
Step 0: docs/deploys/2026-05-21-adr-001-preflight.md + docs/feature-flags.md audit artifacts.
Tests: ticketClient.spec, WsClient.spec, ssrf.spec updated (342 passing).

Co-Authored-By: Claude Opus 4.7 <[email protected]>

* fix(ci): resolve three PR #171 type-check and startup failures

- auth-contracts.spec.ts: assert WebSocketAuthMessage.token as PluginTicket
  (not SensitiveString — distinct branded types fail toEqualTypeOf equality)
- pkce.spec.ts: replace function(){return this} mock with arrow fn to fix
  TS2683 implicit-this error in strict mode
- test-local-dev.yml: add ENCRYPTION_MASTER_KEY so instrumentation.ts boot
  validation doesn't crash the startup test in CI

Co-Authored-By: Claude Opus 4.7 <[email protected]>

* fix(ci): fix pkce mock constructor and env injection for startup test

- pkce.spec.ts: use function(this: object) instead of arrow fn so the
  mock can be called with `new Configuration(...)` (arrow functions are
  not constructors)
- test-local-dev.yml: sed-replace ENCRYPTION_MASTER_KEY in .env after
  cp .env.example so Next.js instrumentation boot check passes in CI

Co-Authored-By: Claude Opus 4.7 <[email protected]>

* fix(ci): also sed-replace AUTH_SECRET in .env for startup test

.env.example has AUTH_SECRET= (empty), which Next.js loads and overrides
the system env var, causing the same boot crash as ENCRYPTION_MASTER_KEY.

Co-Authored-By: Claude Opus 4.7 <[email protected]>

* fix(setup): auto-generate ENCRYPTION_MASTER_KEY in setup.mjs

The Playwright CI workflow uses `pnpm run setup` which previously only
generated AUTH_SECRET. ENCRYPTION_MASTER_KEY remained empty from
.env.example, causing instrumentation.ts boot validation to crash.

This fix also improves the new-developer onboarding experience — both
required secrets are now generated in a single setup step.

Co-Authored-By: Claude Opus 4.7 <[email protected]>

---------

Co-authored-by: Claude Opus 4.7 <[email protected]>
2026-05-21 17:00:24 +12:00

4.9 KiB
Raw Permalink Blame History

ADR-001 Feature Flags

Single source of truth for all feature flags introduced by ADR-0001 (Decentralized Plugin Auth + SSRF Mitigation).

Keep the per-environment table current whenever a flag is set, changed, or removed in Coolify. Drift between staging and production is the primary paper-cut this doc exists to prevent.


Flag Inventory

5 Master-Plan Flags

Flag Repo Default Meaning
NEXT_PUBLIC_WWV_TICKET_AUTH_PLUGINS Local App "" (empty = dormant) Comma-separated plugin IDs that require WS first-message auth (e.g. aviation,maritime). Empty or unset → ticket auth disabled for all plugins. Set after Marketplace + Data Engine are deployed (step 6).
REQUIRE_TICKET_AUTH Data Engine false When true, the engine rejects any WS connection that does not present a valid ticket. Global — applies to all plugins. Replaces WWV_SKIP_WS_AUTH=false once JWKS is wired (step 7a).
REQUIRE_TICKET_AUTH_PLUGINS Data Engine "" Comma-separated plugin IDs for per-plugin enforcement before enabling the global flag. Not yet implemented (see Divergence Note below).
ENFORCE_ORIGIN_ALLOWLIST Data Engine false When true, the engine rejects connections from Origins not in its configured allowlist. Enable after populating the allowlist from observed traffic (step 7b).
PROXY_HOST_ALLOWLIST Local App "" (deny all) SSRF allowlist for the camera / iframe proxy route. "" or unset = deny all (safe default). "*" = permissive + logs WARN per host (observation mode). Comma-separated list = explicit allowlist. Ship "*" initially; tighten to an explicit list after one week of log observation (step 7c).

Deployed Reality: WWV_SKIP_WS_AUTH

Divergence note: The Data Engine workstream implemented a single global bypass flag (WWV_SKIP_WS_AUTH) instead of the three granular master-plan flags (REQUIRE_TICKET_AUTH, REQUIRE_TICKET_AUTH_PLUGINS, ENFORCE_ORIGIN_ALLOWLIST). The master-plan flags remain the target architecture and must be implemented before step 7. WWV_SKIP_WS_AUTH is the current interim control.

Flag Repo Default Meaning
WWV_SKIP_WS_AUTH Data Engine false When true, every WS connection is pre-authenticated — no JWT is checked. Currently true in production and load-bearing (JWKS not yet wired; the engine cannot verify real tokens). Must stay true until deploy step 4 wires JWKS. Flip to false as part of step 5 smoke test, replacing it with REQUIRE_TICKET_AUTH=true.

Per-Environment Table

Update this table whenever a flag changes in Coolify.

Flag Local dev Staging Production Last updated
NEXT_PUBLIC_WWV_TICKET_AUTH_PLUGINS "" (.env.example) "" (not set) "" (not set) 2026-05-21
REQUIRE_TICKET_AUTH N/A N/A N/A (not yet implemented) —
REQUIRE_TICKET_AUTH_PLUGINS N/A N/A N/A (not yet implemented) —
ENFORCE_ORIGIN_ALLOWLIST N/A N/A N/A (not yet implemented) —
PROXY_HOST_ALLOWLIST "*" (.env.example) TBD — set before step 5 not set (= deny all) 2026-05-21
WWV_SKIP_WS_AUTH false TBD — set before step 4 true (load-bearing) 2026-05-20

Rollout Sequence

The sequence in which flags are set during the ADR-001 deploy order:

Deploy step Service Flag change Notes
Step 1 Local App Set PROXY_HOST_ALLOWLIST="*" Observation mode — watch WARN logs for one week
Step 3 Local App NEXT_PUBLIC_WWV_TICKET_AUTH_PLUGINS="" confirmed empty Dormant — no change needed, just confirm
Step 4 Data Engine JWKS wired; WWV_SKIP_WS_AUTH remains true Both paths exist, neither enforced
Step 5 (staging) Local App NEXT_PUBLIC_WWV_TICKET_AUTH_PLUGINS=test-synthetic Smoke test only — revert after
Step 5 (staging) Data Engine WWV_SKIP_WS_AUTH=false Prove real JWT verification end-to-end
Step 6 Local App NEXT_PUBLIC_WWV_TICKET_AUTH_PLUGINS=<first-real-plugin> One plugin at a time, 24 h soak
Step 6 Data Engine REQUIRE_TICKET_AUTH_PLUGINS=<same-plugin> Mirror Local App change
Step 7a Data Engine REQUIRE_TICKET_AUTH=true Global default-deny; 24 h soak
Step 7b Data Engine ENFORCE_ORIGIN_ALLOWLIST=true After populating allowlist from observed connections
Step 7c Local App PROXY_HOST_ALLOWLIST=<observed-list> Replace "*" with explicit host list

Rollback

Every step is independently revertable by flipping its single flag back. The old no-auth data path remains wired throughout steps 1–6 and is only superseded at step 7a. If anything breaks, removing the plugin from NEXT_PUBLIC_WWV_TICKET_AUTH_PLUGINS immediately restores the old path for that plugin.