ADR-0017: Isolate and authenticate Firecall application previews
Date: 2026-08-29 Status: accepted Decider: OpenMined platform owner
Context
ADR-0016 resolves one Firecall preview to one exact Pod and declared port. It keeps the Kubernetes credential, Pod address, and loopback port on the ephemeral Firecall box.
That private process is not a browser access path. A browser path must preserve the exact target binding while it handles untrusted application content. It must not place application content on the portal or workspace registrable domain.
Application cookies, redirects, authorization headers, large bodies, slow responses, and service workers can cross or weaken browser trust boundaries. A preview URL can also be copied to a second human. Cloudflare authentication alone does not prove that the human acknowledged the exact Firecall session and target.
Decision
Firecall uses a separate registered domain and Cloudflare Access application for application previews.
The proxy accepts only this canonical preview host:
<preview-id>--<session-id>.<preview-apex>
The proxy parses and validates that host before it reads identity, session, authorization, preview, or agent state. The preview identifier is the canonical 26-character lowercase unpadded Base32 identifier created by the agent. The session identifier and preview record must match the host exactly.
At startup, the proxy validates the workspace and preview apices with one pinned Public Suffix List snapshot. Their effective registrable domains must differ. Startup fails when the list, either apex, or that separation is invalid.
The workspace lists target choices that the agent derives from current Kubernetes objects. A Service choice names one exact ready backing Pod. It does not describe every selector match as an eligible endpoint. The user selects one validated target and protocol. The create response binds the resulting preview to the complete resolved-target SHA-256 digest.
An acknowledged workspace user requests a 60-second preview handoff. The proxy
signs the handoff with the preview-handoff subkey derived from the existing
session HMAC master. It binds:
- Subject key.
- Access subject key.
- Session identifier.
- Profile digest.
- Scope digest.
- Preview identifier.
- Target digest.
- Authorization kind and identifier.
- Platform-owner list revision, when applicable.
- Issue and expiry times.
The workspace puts the handoff only in the preview URL fragment. The fragment does not enter an HTTP request or referrer.
The preview origin first serves a trusted interstitial. The interstitial removes
the fragment with history.replaceState, then posts the handoff to:
POST /.firecall/v1/preview-acknowledgements
The proxy validates the separate preview Access audience, exact Origin, fetch
site, current subject, handoff claims, target record, and current authorization.
It consumes the handoff once across proxy replicas. It then sets a host-only
__Host-firecall_preview_ack cookie.
The proxy creates one conditional, create-only Blob marker for each consumed handoff. The marker must remain longer than the 60-second token lifetime. Live activation must define an owner-approved lifecycle rule. The rule must retain these markers for at least one day.
The acknowledgement cookie uses the preview-ack subkey. It repeats the host,
subject, session, preview, target, authorization, revision, and expiry bindings.
Its expiry cannot exceed the session expiry. Each request also requires the
current preview record, so access cannot exceed the current preview idle expiry.
The cookie is Secure, HttpOnly, SameSite Strict, host-only, and scoped to /.
Every application request requires that acknowledgement. The proxy rechecks the session, requester, platform owner, or exact invitation before it contacts the agent. It sends only the opaque session actor handle to the box.
The proxy uses a separate streaming agent interface for preview traffic. It selects the agent through the signed session status and mutual TLS. It never accepts an upstream host, address, port, or agent identity from the browser.
The internal agent route identifies only the namespace, preview identifier, target digest, canonical application path, raw query, actor, session, and scope. The agent looks up the private loopback endpoint from its own manager. It revalidates the target and digest before use. It records activity only for an accepted request or transferred response.
This slice supports bounded HTTP and HTTPS application requests. It rejects
CONNECT and TRACE. It defers WebSockets and application Authorization
forwarding. Both fail closed.
HTTPS requires a system-trusted certificate for the exact Service DNS name. This slice has no certificate bypass or profile-specific CA input.
The proxy and agent enforce independent request, response, header, concurrency, queue, rate, byte, progress, idle, and total-time limits. The agent owns the cross-replica actor, preview, and session totals. Proxy-local limits provide a lower defensive ceiling.
Each proxy replica permits 30 handoff mints per subject, 12 per preview, and 60 per session each minute. It permits at most 256 mints per subject, 256 per preview, and 512 per session during one session. Acknowledgements permit 60 attempts per subject, 30 per preview, and 120 per session each minute. Expired session state is removed from the bounded local limiter.
The preview path removes all browser cookies after Firecall cookie validation.
It removes Cloudflare identity headers, forwarding headers, proxy headers, and
all X-Firecall-* browser headers. It does not forward application
Authorization in this slice. It rejects every upstream Set-Cookie header and
all unsafe hop-by-hop response headers.
The proxy reserves the complete /.firecall/ prefix. It replaces an upstream
Content Security Policy with the fixed untrusted-preview policy. It sets the
fixed no-store, HSTS, referrer, permissions, opener, resource, and content-type
headers. Applications that need cookies, inline scripts, external scripts,
external connections, frames, or service workers are unsupported.
The workspace preview view shows target identity, state, idle expiry, safe errors, and Open, Copy URL, and Stop actions. It keeps handoffs in memory only. It warns that cookies, login flows, and service workers do not work.
This decision adds source contracts only. It does not create a domain, DNS record, Cloudflare zone, tunnel route, Access application, policy, audience, secret, or Kubernetes deployment. Live activation requires separate owner approval and a complete lifecycle canary.
Options considered
Serve previews below the workspace apex
- It needs no second registered domain.
- Untrusted applications can set parent-domain cookies that affect Firecall.
- Content isolation is not sufficient for activation.
Give each preview a direct tunnel or Kubernetes credential
- It bypasses the Firecall application proxy.
- It exposes target and credential authority to more components.
- It cannot enforce one shared session, authorization, and traffic boundary.
Use one authenticated preview origin
- It preserves one reviewed browser and agent boundary.
- It needs a separate domain, Access audience, parser, proxy, and traffic limits.
- Source can remain disabled until live edge dependencies exist.
Consequences
- The agent must expose exact eligible targets and bounded HTTP transport.
- Preview records must include the target digest and idle timestamps.
- The proxy must support the separate apex, audience, interstitial, and cookie.
- The workspace must implement target selection and preview lifecycle controls.
- Tests must cover host parsing, Public Suffix List rules, purpose substitution, replay, subject mismatch, target drift, expiry, header removal, reserved paths, limits, and complete in-process traffic.
- A live canary must prove the separate domain, Access policy, tunnel, proxy, agent, exact Pod target, stop, drift, idle, close, and expiry paths.
- Cookie-dependent and service-worker-dependent applications remain unsupported.
Supersession and rollback
A later ADR can add bounded WebSockets or confirmed application authorization. It must preserve the separate registrable-domain and exact-target boundaries.
Removing the preview-origin routes and /previews controls restores the
fail-closed private-process state from ADR-0016.
Program links
- Program decision: The delivery-program workflow is suspended by ADR-0013.
- Dependent work packages: None.