* 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]>
80 lines
4.9 KiB
Markdown
80 lines
4.9 KiB
Markdown
# 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.
|