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

80 lines
4.9 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# ADR-001 Feature Flags
Single source of truth for all feature flags introduced by
[ADR-0001](architecture/decisions/adr-0001-decentralized-plugin-auth-and-ssrf-mitigation.md)
(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.