FRAME_ANCESTORS: embed the admin console, and nothing else

[distronode-com]

Second of the features split out of #30.

FRAME_ANCESTORS is a space-separated list of origins allowed to embed /admin/ in a frame. When set, the admin routes send Content-Security-Policy: frame-ancestors <list>. Unset, nothing is sent and /admin/ behaves exactly as it does today.

FRAME_ANCESTORS="https://console.example.com 'self'"

Space-separated rather than comma-separated because the value goes into a CSP source list verbatim, so it reads the same in the environment as it does in the header.

The three refusals, which are the interesting half

⛔ Scoped to the admin SPA, and it has to stay that way. The public booking pages set frame-ancestors 'none' plus X-Frame-Options: DENY in their own handlers (book.go, manage_handler.go, tracking_settings.go's publicCSP) and this middleware never reaches them. They are unauthenticated pages that collect names, emails and card details; clickjacking one is worth more to an attacker than framing a console nobody can open without a session.

⛔ A malformed entry stops the process booting rather than being dropped. A browser discards a source list it cannot parse, so a single typo would leave the admin UI more embeddable than leaving the setting unset. That is the one failure mode a validation error must not have, so Validate refuses http:// on a public host, a wildcard, a path, a query, credentials, 'none', 'unsafe-inline', and a bare scheme. One bad entry beside a good one still fails: a half-applied source list is a policy nobody wrote.

⛔ No X-Frame-Options is sent beside the CSP. That header has no allow-list form — its ALLOW-FROM was implemented by one browser and is dead — so the only value it could carry here is SAMEORIGIN, which every browser that reads it applies instead of honouring frame-ancestors. Setting it would break the embedding this exists to enable. Every browser that can frame anything today supports frame-ancestors.

No default deny

With the list empty the wrapped handler sends no frame header at all, which is what /admin/ has always sent. It does not add a default deny, because that would be a behaviour change smuggled in on an opt-in setting, and someone framing the console today for their own reasons would find it broken by an upgrade they did not opt into. TestAdminSPA_sendsNoFrameHeadersWhenUnset pins it.

Verification

Mutation-checked rather than assumed: with w.Header().Set("Content-Security-Policy", policy) replaced by a discard, TestAdminSPA_frameAncestorsWhenConfigured and TestAdminSPA_frameAncestorsOnSPAFallback both fail. Restored, they pass.

go vet ./... and go test ./... are both clean on this branch — 26 packages, zero failures.

Nine files, +283/−1. No schema, no new dependency, no change to any public surface.

🤖 Generated with Claude Code

[pullfrog]

Important

FRAME_ANCESTORS only unlocks framing. Cross-site iframe sessions still fail under the existing SameSite=Lax cookie — document the same-site constraint (or plan a cookie change) before operators treat this as a working embed.

Reviewed changes
Initial review of the full PR (1 commit): opt-in admin-only frame-ancestors via env, boot-time validation, and docs.

• FRAME_ANCESTORS config + Validate — Space-separated sources; only 'self' / https://host[:port]; any bad entry fails boot so a typo cannot silently widen embeddability.
• FrameAncestors middleware — Sets CSP on the admin SPA only; empty list is a no-op (no default deny); deliberately omits X-Frame-Options.
• Wiring + tests — Applied solely around frontend.Handler() under /admin/; config + response header tests pin unset vs configured behaviour.
• Docs — CHANGELOG, DEPLOY, ARCHITECTURE describe scope and the three refusals.

⚠️ Authenticated embed needs same-site (or a cookie redesign)

CSP is necessary but not sufficient. Admin sessions are SameSite=Lax (createSession in internal/handler/session.go). Browsers withhold Lax cookies on cross-site nested navigations and subrequests, so a parent on another registrable domain can frame /admin/ after this PR and still get an unauthenticated shell (and no session on /v1 calls). Same-site parents (shared eTLD+1) and 'self' work; true third-party consoles do not without SameSite=None + Secure (and a CSRF story that already partially exists via SameOriginCheck) or a partitioned-cookie approach. The PR never states that limit, so operators can configure a green CSP and still hit a dead embed.

Technical details

# Document same-site embed constraint (or extend cookie model)

## Affected sites
- `internal/handler/session.go` — `SameSite: http.SameSiteLaxMode` on `calnode_session`
- `DEPLOY.md` / `CHANGELOG.md` / `docs/ARCHITECTURE.md` — feature described as embed-ready without cookie caveats
- OAuth-in-iframe is a secondary footgun (IdP pages often deny framing); optional to mention

## Required outcome
- Operators reading DEPLOY/ARCHITECTURE understand that working authenticated embeds require the parent to be **same-site** with `BASE_URL` (or `'self'`), unless/until cookies change
- If third-party embed is an intentional goal, that is a separate design (SameSite=None + Secure, CSRF, third-party cookie / CHIPS deprecation) — not silent fallout of this CSP-only PR

## Suggested approach (optional)
- Prefer documenting the same-site constraint in this PR; do not flip SameSite here without an explicit CSRF/third-party plan

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Grok ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes since the prior Pullfrog review: docs-only amendment on 6177596 documenting the same-site embed constraint raised before. No behavior or middleware changes.

• DEPLOY FRAME_ANCESTORS row — States same-site only in practice: Lax session cookie means a cross-site parent gets the frame and the login screen.
• ARCHITECTURE §9 — Adds a ⛔ paragraph beside the CSP refusals: CSP is half the story; SameSite=None is deliberately not offered because it drops Lax CSRF cover.
• FrameAncestors field comment — Same constraint on the config surface operators and future editors read first.

Prior same-site documentation threads resolved against this head.

  ^{｜ View workflow run ｜ Using Grok ｜ 𝕏}