@assembly-js/app-foundation 0.0.41 → 0.0.43

package/dist/proxy.js

@@ -0,0 +1,669 @@
+// The app's root proxy (Next middleware): first-load session-token exchange, the
+// bearer cookie, the CSRF gate, and the cookieless fallback. It lives in the
+// package rather than in each app because it is security-critical code an agent
+// must never re-author; an app's proxy.ts only calls createAssemblyProxy and
+// adds its own extras through onForward.
+import { assemblyApi } from '@assembly-js/node-sdk';
+import { NextResponse } from 'next/server';
+import { APP_CSRF_HEADER, BEARER_COOKIE_NAME, BEARER_HEADER_NAME, CLIENT_BEARER_HEADER, decodeBearer, isDocumentRequest, isSessionExchangeEnabled, logCookieOutcome, serializeBearerCookie, serializeCookieProbe, } from './session-exchange.js';
+import { CLIENT_FLAGS_COOKIE_NAME } from './origin-bootstrap.js';
+import { handlePaintedBeacon, isPaintedBeaconPath } from './paint-beacon.js';
+import { fetchSessionFlags, mintBearerFromAppKey, mintBearerFromSessionToken, } from './mint-bearer.js';
+// Freshness knob for the client-readable flags cookie: how long a flag flip
+// can take to reach an app (at its next document load) without a re-mint.
+const FLAGS_COOKIE_TTL_SECONDS = 300;
+// Trusted API origin for this stack (build-env supplied). Passed to the SDK so
+// tokenless/bearer calls reach the right stack; empty in prod where the SDK
+// default is correct.
+const proxyBaseUrl = process.env.ASSEMBLY_API_BASE_URL || undefined;
+// Decrypts a session token into a raw SDK client for the proxy's own use
+// (reading the payload, driving the exchange). Deliberately bypasses the
+// foundation's strict getAssembly(): the proxy runs in edge middleware where
+// next/headers isn't available, and it must be able to decrypt even a token
+// that strict auth would later reject — that rejection is the app's job, not
+// the exchange's.
+async function decryptSessionToken(token) {
+    return assemblyApi({
+        apiKey: process.env.ASSEMBLY_API_KEY ?? '',
+        token,
+        baseUrl: proxyBaseUrl,
+    });
+}
+const STATIC_FRAME_ANCESTORS = [
+    "'self'",
+    'https://*.assembly.com',
+    'https://*.assembly-staging.com',
+    'https://*.myassembly.com',
+    'https://*.myassembly-staging.com',
+    'https://*.copilot.app',
+    'https://*.copilot-staging.app',
+    'http://localhost:*',
+    'http://127.0.0.1:*',
+];
+// Short TTL for workspace theme/label data — independent of bearer session TTL.
+const WORKSPACE_TTL_MS = 5 * 60 * 1_000;
+// Bound for the non-destructive workspace-theme fetch: on timeout the render
+// just falls back to neutral branding and re-attempts next request. Generous
+// enough to survive a cold platform-api lambda / normal network latency.
+const FETCH_TIMEOUT_MS = 10_000;
+const STATE_CHANGING_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+// Identity/branding headers the proxy sets from its own resolution and the
+// layout reads. Stripped from every inbound request so they can't be spoofed.
+const PROXY_OWNED_IDENTITY_HEADERS = [
+    'x-assembly-is-client',
+    'x-assembly-color-accent',
+    'x-assembly-font',
+    'x-assembly-label-client-one',
+    'x-assembly-label-client-many',
+    'x-assembly-label-company-one',
+    'x-assembly-label-company-many',
+    'x-assembly-distinct-id',
+    'x-assembly-workspace-id',
+];
+function stripProxyOwnedHeaders(headers) {
+    headers.delete(BEARER_HEADER_NAME);
+    headers.delete(CLIENT_BEARER_HEADER);
+    for (const header of PROXY_OWNED_IDENTITY_HEADERS) {
+        headers.delete(header);
+    }
+}
+// Neutral branding for the exchange path when the workspace fetch fails but the
+// bearer exchange itself succeeds: the session token is single-use, so we must
+// keep the minted bearer and return neutral branding rather than drop it. The
+// legacy path instead returns null and caches nothing (pre-AI-260 behavior).
+const NO_BRANDING = {
+    portalUrl: null,
+    colorAccent: null,
+    font: null,
+    labelClientOne: 'Client',
+    labelClientMany: 'Clients',
+    labelCompanyOne: 'Company',
+    labelCompanyMany: 'Companies',
+};
+const MAX_WORKSPACE_THEME_CACHE_SIZE = 500;
+const MAX_LEGACY_TOKEN_CACHE_SIZE = 1_000;
+// Workspace theme cache keyed by workspace ID (NOT by any credential). Shared
+// across users in the same portal; a miss just re-fetches, so a cold serverless
+// instance degrades to one extra theme read, never to wrong auth.
+const workspaceThemeCache = new Map();
+// Bearer-first workspace branding read with an app-scoped bearer fallback.
+// New apps run with session exchange on; a viewer bearer can fail
+// retrieveWorkspace while auth still succeeds (client-scoped tokens often
+// cannot read workspace branding). assemblyApi({ apiKey }) throws on current
+// SDK versions outside local/staging ("Unable to authorize Assembly SDK"), so
+// the old key-only fallback was a landmine: any viewer miss constructed that
+// client and 500'd the render. Mint an app bearer instead — the same
+// primitive getOfflineAssembly uses — then read with it.
+//
+// Branding is cosmetic and this runs AFTER the single-use session token was
+// consumed by the mint, so nothing here may throw: an uncaught throw fails the
+// whole SSR render as a 500, the Set-Cookie is lost, and the burned token makes
+// every retry render the null-identity fallback. Client construction sits
+// inside the same catch as its read because assemblyApi itself throws when it
+// cannot derive an auth key.
+async function fetchWorkspaceThemeWithBearer(bearer, workspaceId) {
+    try {
+        const client = await assemblyApi({ bearer, baseUrl: proxyBaseUrl });
+        return await fetchWorkspaceTheme(client, workspaceId);
+    }
+    catch {
+        return null;
+    }
+}
+async function fetchWorkspaceThemeForIdentity(workspaceId, bearer) {
+    if (bearer) {
+        const fromViewer = await fetchWorkspaceThemeWithBearer(bearer, workspaceId);
+        if (fromViewer)
+            return fromViewer;
+    }
+    // Viewer miss: mint an app-scoped bearer. mintBearerFromAppKey already
+    // fails closed (null), but the path must stay throw-proof even if a mock
+    // or future change surfaces an exception.
+    try {
+        const minted = await mintBearerFromAppKey();
+        if (!minted?.bearer)
+            return null;
+        return await fetchWorkspaceThemeWithBearer(minted.bearer, workspaceId);
+    }
+    catch {
+        return null;
+    }
+}
+async function fetchWorkspaceTheme(assembly, workspaceId) {
+    const now = Date.now();
+    const cached = workspaceThemeCache.get(workspaceId);
+    if (cached && cached.expiresAt > now)
+        return cached;
+    let timeoutId;
+    try {
+        const timeoutPromise = new Promise((_, reject) => {
+            timeoutId = setTimeout(() => reject(new Error('retrieveWorkspace timeout')), FETCH_TIMEOUT_MS);
+        });
+        const workspace = await Promise.race([assembly.retrieveWorkspace(), timeoutPromise]);
+        clearTimeout(timeoutId);
+        const rawPortalUrl = workspace.portalUrl ?? null;
+        const theme = {
+            portalUrl: rawPortalUrl ? rawPortalUrl.replace(/^https?:\/\//, '') : null,
+            colorAccent: workspace.colorAccent ?? null,
+            font: workspace.font ?? null,
+            labelClientOne: workspace.labels?.individualTerm || 'Client',
+            labelClientMany: workspace.labels?.individualTermPlural || 'Clients',
+            labelCompanyOne: workspace.labels?.groupTerm || 'Company',
+            labelCompanyMany: workspace.labels?.groupTermPlural || 'Companies',
+            expiresAt: now + WORKSPACE_TTL_MS,
+        };
+        if (workspaceThemeCache.size >= MAX_WORKSPACE_THEME_CACHE_SIZE) {
+            const oldest = workspaceThemeCache.keys().next().value;
+            if (oldest !== undefined)
+                workspaceThemeCache.delete(oldest);
+        }
+        workspaceThemeCache.set(workspaceId, theme);
+        return theme;
+    }
+    catch {
+        // Fetch failed — cache nothing and return null so the next request re-attempts,
+        // exactly as the pre-AI-260 proxy did. We never persist placeholder branding.
+        clearTimeout(timeoutId);
+        return null;
+    }
+}
+// Performs the server-side token exchange on the first request from the iframe:
+// trades the session token for a short-lived bearer (via mintBearerFromSessionToken)
+// and fetches the workspace theme WITH that bearer. Returns the identity + theme
+// for THIS response's headers/cookie only — nothing is cached per-bearer; every
+// later request re-derives identity by decoding the bearer cookie.
+async function resolveAndExchange(token, cookieSessionId) {
+    const minted = await mintBearerFromSessionToken(token, { cookieSessionId });
+    // No bearer: undecodable, not exchange-capable (no tokenId), a consumed/
+    // replayed/expired single-use token, or an exchange that could not be
+    // completed. Fail closed — a bearer-capable app never renders from a raw
+    // token. The reason travels with the rejection because it decides whether a
+    // warm cookie may answer for this token — as does the viewer verdict the
+    // exchange returns when it was told which session the cookie came from.
+    if (!minted.ok) {
+        return {
+            kind: 'reject',
+            reason: minted.reason,
+            rejectedViewer: minted.rejectedViewer,
+        };
+    }
+    const { bearer, bearerExpiresAt, session } = minted;
+    // Theme is cosmetic: a viewer-bearer miss falls back to an app-scoped mint
+    // (or NO_BRANDING) inside fetchWorkspaceThemeForIdentity. The viewer bearer
+    // is kept regardless — the single-use session token was already consumed.
+    const theme = await fetchWorkspaceThemeForIdentity(session.workspaceId, bearer);
+    return { kind: 'exchanged', session, theme, bearer, bearerExpiresAt };
+}
+// Legacy resolve path for session tokens that do not carry a tokenId (older
+// SDK versions). Keeps behaviour identical to pre-AI-260 for those callers.
+const legacyTokenCache = new Map();
+// Deduplicates concurrent first-load requests that carry the same session token
+// so only one /v1/session call is made per token.
+const exchangeInFlight = new Map();
+async function resolveLegacyToken(token) {
+    const now = Date.now();
+    const cached = legacyTokenCache.get(token);
+    if (cached && cached.expiresAt > now)
+        return cached;
+    if (cached)
+        legacyTokenCache.delete(token);
+    let assembly;
+    try {
+        assembly = await decryptSessionToken(token);
+    }
+    catch {
+        return null;
+    }
+    let workspaceId = null;
+    let clientId;
+    let internalUserId;
+    let companyId;
+    if (typeof assembly.getTokenPayload === 'function') {
+        try {
+            const p = await assembly.getTokenPayload();
+            workspaceId = p.workspaceId ?? null;
+            clientId = p.clientId || undefined;
+            internalUserId = p.internalUserId || undefined;
+            companyId = p.companyId || undefined;
+        }
+        catch { }
+    }
+    if (!workspaceId)
+        return null;
+    const theme = await fetchWorkspaceTheme(assembly, workspaceId);
+    // Branding fetch failed — return null without caching so the next request
+    // re-attempts, matching the pre-AI-260 proxy (no placeholder branding served).
+    if (!theme)
+        return null;
+    const data = {
+        workspaceId,
+        clientId,
+        internalUserId,
+        companyId,
+        ...theme,
+        expiresAt: now + WORKSPACE_TTL_MS,
+    };
+    if (legacyTokenCache.size >= MAX_LEGACY_TOKEN_CACHE_SIZE) {
+        const oldest = legacyTokenCache.keys().next().value;
+        if (oldest !== undefined)
+            legacyTokenCache.delete(oldest);
+    }
+    legacyTokenCache.set(token, data);
+    return data;
+}
+async function decodeSessionTokenPayload(token) {
+    let assembly;
+    try {
+        assembly = await decryptSessionToken(token);
+    }
+    catch {
+        return null;
+    }
+    if (typeof assembly.getTokenPayload !== 'function')
+        return null;
+    try {
+        const payload = await assembly.getTokenPayload();
+        if (!payload?.workspaceId)
+            return null;
+        return {
+            workspaceId: payload.workspaceId,
+            sessionId: payload.tokenId || undefined,
+            clientId: payload.clientId || undefined,
+            internalUserId: payload.internalUserId || undefined,
+            companyId: payload.companyId || undefined,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+// Whether this payload's identity may be compared against the cookie's at all.
+// A payload carrying no identity claim at all had it stripped deliberately, so
+// its missing clientId says nothing about the viewer — on a client surface that
+// describes every single request, not a switch. Identity is only meaningful on a
+// payload that carries some, or one with no session id and so predating session
+// tokens entirely.
+function payloadIdentityIsAuthoritative(decoded) {
+    return Boolean(decoded.clientId ||
+        decoded.internalUserId ||
+        decoded.companyId ||
+        !decoded.sessionId);
+}
+function previewIdentitiesMatch(cookieIdentity, decoded) {
+    return (cookieIdentity.workspaceId === decoded.workspaceId &&
+        (cookieIdentity.clientId ?? '') === (decoded.clientId ?? '') &&
+        (cookieIdentity.companyId ?? '') === (decoded.companyId ?? ''));
+}
+async function exchangeUrlToken(token, cookieSessionId) {
+    // Keyed on both inputs: the same token exchanged with a different cookie
+    // context is a different question, and must not reuse the other's verdict.
+    const key = `${cookieSessionId ?? ''}|${token}`;
+    const inFlight = exchangeInFlight.get(key);
+    if (inFlight)
+        return inFlight;
+    const promise = resolveAndExchange(token, cookieSessionId);
+    exchangeInFlight.set(key, promise);
+    try {
+        return await promise;
+    }
+    finally {
+        exchangeInFlight.delete(key);
+    }
+}
+// Returns the app's proxy function. The app's proxy.ts must still declare its
+// own `export const config` literal: Next reads the matcher statically from that
+// file and ignores an imported value.
+export function createAssemblyProxy(options = {}) {
+    return (request) => handleRequest(request, options);
+}
+async function handleRequest(request, options) {
+    // Before CSRF / exchange: sendBeacon is a headerless POST and must not 403.
+    // POST only — a GET/HEAD to the path (crawler, prefetch, curious user) must
+    // not mint a fake painted line; it falls through to the normal proxy path.
+    if (request.method === 'POST' && isPaintedBeaconPath(request.nextUrl.pathname)) {
+        return handlePaintedBeacon();
+    }
+    const frameAncestors = [...STATIC_FRAME_ANCESTORS];
+    const requestHeaders = new Headers(request.headers);
+    // Never trust inbound values for the headers this proxy owns — the bearer it
+    // forwards, and the identity/branding headers the layout reads. Each is set
+    // below strictly from this proxy's own exchange/cookie resolution; stripping
+    // them first means a request that resolves to no identity can't inject a
+    // spoofed viewer (e.g. forcing client accent/font on an internal render).
+    stripProxyOwnedHeaders(requestHeaders);
+    let identity = null;
+    let theme = null;
+    let newBearer = null;
+    let newBearerExpiresAt = 0;
+    let failClosedReason = null;
+    // Master switch: while off, skip the exchange entirely and behave exactly as
+    // the pre-AI-260 legacy path. This keeps every foundation snapshot dormant
+    // until the exchange is deliberately enabled + the snapshot rebuilt.
+    const exchangeEnabled = isSessionExchangeEnabled();
+    // CSRF mitigation: when exchange is enabled the bearer travels as an
+    // HttpOnly SameSite=None cookie (required for cross-site iframe embedding),
+    // which the browser attaches to every request — including forged cross-site
+    // ones. A custom header cannot be set by a cross-site request without a
+    // CORS preflight, and this app never grants one, so requiring it here is
+    // sufficient to block CSRF. Server actions are managed by Next.js with its
+    // own Origin-based protection and cannot carry a custom header.
+    //
+    // The check only protects against ambient credentials, so a request carrying
+    // no cookie at all has nothing to protect: an inbound webhook or API client
+    // sends none. Such a request is passed to the route with identity stripped
+    // (the strip above already ran), skipping the token exchange and writing no
+    // cookies, so a forged `?token=` cannot mint a session through it. Any
+    // cookie, not only the bearer, keeps the request under the check.
+    if (exchangeEnabled && STATE_CHANGING_METHODS.has(request.method.toUpperCase())) {
+        const isServerAction = request.headers.has('next-action');
+        if (!isServerAction && !request.headers.has(APP_CSRF_HEADER)) {
+            if (request.headers.get('cookie')) {
+                return new NextResponse(null, { status: 403 });
+            }
+            return NextResponse.next({ request: { headers: requestHeaders } });
+        }
+    }
+    // Primary path: read bearer from the HttpOnly cookie set on first load.
+    const bearerCookie = exchangeEnabled
+        ? request.cookies.get(BEARER_COOKIE_NAME)?.value
+        : undefined;
+    let clearBearerCookie = false;
+    if (bearerCookie) {
+        // Derive identity from the self-describing bearer on EVERY request — no
+        // cache (a per-instance Map is worthless across serverless instances, and
+        // caching credentials is needless). A failed decode (expired/malformed
+        // bearer) clears the cookie so the next full-page load re-exchanges via
+        // ?token= instead of looping on 401.
+        identity = decodeBearer(bearerCookie);
+        if (!identity)
+            clearBearerCookie = true;
+    }
+    // Fallback for browsers that refuse to store the cookie (Safari blocks every
+    // cross-site-iframe cookie and has no CHIPS): the client holds the bearer in
+    // memory and sends it as a header. Only consulted when the cookie yielded no
+    // identity, so a browser with a working cookie takes exactly the same path as
+    // before. An undecodable value simply leaves identity null — there is no
+    // cookie here to clear, and the resulting 401 is what drives a re-exchange.
+    const clientBearer = exchangeEnabled
+        ? request.headers.get(CLIENT_BEARER_HEADER)
+        : null;
+    let servedFromClientBearer = false;
+    if (!identity && clientBearer) {
+        identity = decodeBearer(clientBearer);
+        servedFromClientBearer = Boolean(identity);
+    }
+    const urlToken = request.nextUrl.searchParams.get('token');
+    // One exchange attempt per request: the fallback below must not re-hit
+    // /v1/session for a token the block above already tried and failed on.
+    let urlTokenExchanged = false;
+    // A valid cookie does not always answer for an incoming ?token=. Two cases
+    // force a re-exchange:
+    //  1. New open: the token denotes a session we have not exchanged. Its
+    //     context (notificationId/instanceId, and the viewer itself) lives on the
+    //     server-side session record, so exchanging is the only way to pick it up
+    //     — without this a Notification Center embed opened against a warm cookie
+    //     never sees its notificationId. Anything that merely replays the URL (a
+    //     reload, a server-action POST) re-sends the same session and keeps the
+    //     cookie.
+    //  2. Viewer switch: the editor swaps Team/Client preview by updating iframe
+    //     ?token=. Only consulted where identity is meaningful; case 1 catches the
+    //     switch anyway, since a new preview always mints a new session.
+    if (exchangeEnabled && urlToken && identity && !clearBearerCookie) {
+        const decoded = await decodeSessionTokenPayload(urlToken);
+        const isNewOpen = Boolean(decoded?.sessionId && decoded.sessionId !== identity.sessionId);
+        const isViewerSwitch = Boolean(decoded &&
+            payloadIdentityIsAuthoritative(decoded) &&
+            !previewIdentitiesMatch(identity, decoded));
+        if (isNewOpen || isViewerSwitch) {
+            urlTokenExchanged = true;
+            // Send the cookie's session id with the exchange: on a slim token a
+            // viewer switch is not provable pre-exchange, so a rejected replay's
+            // consumer is compared server-side against the cookie's viewer instead.
+            const outcome = await exchangeUrlToken(urlToken, identity.sessionId);
+            if (outcome.kind === 'exchanged') {
+                identity = outcome.session;
+                theme = outcome.theme;
+                newBearer = outcome.bearer;
+                newBearerExpiresAt = outcome.bearerExpiresAt;
+            }
+            else {
+                failClosedReason = outcome.reason;
+                // A different-viewer verdict on the rejection is a proven mismatch:
+                // the spent token belonged to another viewer, so the cookie's bearer
+                // must not answer for it — same handling as a pre-exchange-provable
+                // viewer switch.
+                const provenViewerSwitch = isViewerSwitch || outcome.rejectedViewer === 'different_viewer';
+                if (provenViewerSwitch || outcome.reason === 'unavailable') {
+                    if (provenViewerSwitch)
+                        failClosedReason = 'viewer_switch';
+                    // All ways to get here mean the cookie must not answer:
+                    //  - a different viewer is proven and no bearer could be minted;
+                    //  - the exchange could not be completed, so this token may still be
+                    //    unspent — a genuinely new session we merely failed to establish,
+                    //    not a replay. Rendering as the cookie's viewer would serve the
+                    //    previous session (and its stale notification/instance context).
+                    identity = null;
+                    theme = null;
+                    // Only a proven mismatch justifies telling the browser to drop its
+                    // bearer; a transient exchange failure must not log a live session out.
+                    clearBearerCookie = provenViewerSwitch;
+                }
+            }
+            // isNewOpen-only + 'rejected' with no different-viewer verdict: the
+            // token is definitively spent by this same viewer (or by an exchange too
+            // old to say), i.e. a stale remount replaying one an earlier request
+            // already exchanged. Keep the cookie bearer — platform-api re-validates
+            // its signature on every real call, so dropping it buys no safety and
+            // locks the app out until the parent pushes a fresh token.
+        }
+    }
+    // Nothing resolved from a cookie and the block above did not already try this
+    // token (first load, or an undecodable/expired bearer) — resolve from ?token=.
+    if (!identity && urlToken && !urlTokenExchanged) {
+        if (!exchangeEnabled) {
+            // Exchange disabled: legacy per-request decrypt path (identity + theme).
+            const legacy = await resolveLegacyToken(urlToken);
+            if (legacy) {
+                identity = legacy;
+                theme = legacy;
+            }
+        }
+        else {
+            const outcome = await exchangeUrlToken(urlToken);
+            if (outcome.kind === 'exchanged') {
+                identity = outcome.session;
+                theme = outcome.theme;
+                newBearer = outcome.bearer;
+                newBearerExpiresAt = outcome.bearerExpiresAt;
+            }
+            else {
+                failClosedReason = outcome.reason;
+            }
+            // outcome.kind === 'reject': no bearer for this token (undecodable,
+            // tokenId-less, or a consumed/replayed single-use token). Leave identity
+            // null so no branding/identity headers are set and no bearer is
+            // forwarded. The app's getAssembly() then finds no bearer and
+            // re-authenticates instead of rendering.
+        }
+    }
+    // Cookie path: identity came from decoding the bearer, but branding did not.
+    // Fetch the workspace theme (cache-backed) for the CSP frame-ancestors +
+    // branding headers, authenticating with the bearer cookie itself.
+    // The already-valid bearer this request arrived with, from whichever source
+    // answered above.
+    const warmBearer = servedFromClientBearer
+        ? clientBearer
+        : bearerCookie && !clearBearerCookie
+            ? bearerCookie
+            : null;
+    if (exchangeEnabled && identity && !theme && warmBearer) {
+        theme = await fetchWorkspaceThemeForIdentity(identity.workspaceId, warmBearer);
+    }
+    if (options.onForward) {
+        // An app hook must not fail the request: by now a single-use session token
+        // may have been spent on the bearer this response carries, and a 500 would
+        // drop its Set-Cookie and leave the viewer with nothing to retry with.
+        try {
+            await options.onForward({ request, headers: requestHeaders, session: identity });
+        }
+        catch (err) {
+            console.error('assembly proxy onForward hook threw', err);
+        }
+        // The hook may copy inbound headers wholesale; the proxy-owned ones below
+        // must still come only from this proxy, including when no viewer resolved.
+        stripProxyOwnedHeaders(requestHeaders);
+    }
+    // Only an accepted identity (a decodable bearer cookie or a successful mint)
+    // drives branding. A token that decrypts but fails the exchange leaves
+    // identity null and sets no branding/isClient headers — the render falls back
+    // to neutral, matching the fail-closed data path, rather than letting an
+    // unaccepted token pick the accent/font.
+    let portalOrigin = null;
+    if (identity) {
+        const branding = theme ?? NO_BRANDING;
+        if (branding.portalUrl) {
+            portalOrigin = 'https://' + branding.portalUrl;
+            frameAncestors.push(portalOrigin);
+        }
+        // Branding (workspace theme) isn't carried by the bearer, and the proxy
+        // already fetched it for the CSP above — forward it so the app doesn't
+        // re-fetch the theme on every render. (The layout gates custom font/accent
+        // to client views.)
+        requestHeaders.set('x-assembly-color-accent', branding.colorAccent ?? '');
+        requestHeaders.set('x-assembly-font', branding.font ?? '');
+        requestHeaders.set('x-assembly-label-client-one', branding.labelClientOne);
+        requestHeaders.set('x-assembly-label-client-many', branding.labelClientMany);
+        requestHeaders.set('x-assembly-label-company-one', branding.labelCompanyOne);
+        requestHeaders.set('x-assembly-label-company-many', branding.labelCompanyMany);
+        // isClient gates accent/font in layout SSR. Always forward it so layout can
+        // fall back when getSessionIdentity() cannot read the bearer on first paint.
+        requestHeaders.set('x-assembly-is-client', identity.clientId ? 'true' : 'false');
+        // Distinct/workspace headers are legacy-only — bearer path reads them from
+        // the self-describing bearer via getSessionIdentity().
+        if (!exchangeEnabled) {
+            requestHeaders.set('x-assembly-distinct-id', identity.clientId ?? '');
+            requestHeaders.set('x-assembly-workspace-id', identity.workspaceId ?? '');
+        }
+    }
+    // Hand the active bearer to the render as a request header. On first load the
+    // bearer exists nowhere else the render can see it (the Set-Cookie below isn't
+    // visible to this same request); on later requests this simply mirrors the
+    // still-valid cookie. This is what lets a capable app render first-load from
+    // the bearer instead of decrypting the (now single-use-consumed) raw token.
+    const activeBearer = newBearer ?? (identity ? warmBearer : null);
+    if (activeBearer) {
+        requestHeaders.set(BEARER_HEADER_NAME, activeBearer);
+    }
+    // No accepted identity and no fresh bearer (an undecodable cookie, a viewer
+    // switch whose re-exchange minted nothing, an exchange that could not be
+    // completed): drop the bearer cookie from the FORWARDED request, so the
+    // render's getSessionIdentity() cannot resolve a viewer this request did not
+    // accept and bleed the previous view's data or branding into it. Keyed on
+    // identity rather than on clearBearerCookie — whether we tell the BROWSER to
+    // drop its cookie is a separate decision, and a transient exchange failure
+    // deliberately keeps the cookie while still refusing to render from it.
+    // A successful re-exchange sets BEARER_HEADER_NAME above (which the render
+    // prefers), so it is never stripped.
+    if (!identity && !newBearer) {
+        const cookieHeader = requestHeaders.get('cookie');
+        if (cookieHeader) {
+            const filtered = cookieHeader
+                .split(/; */)
+                .filter((c) => c && !c.startsWith(`${BEARER_COOKIE_NAME}=`))
+                .join('; ');
+            if (filtered)
+                requestHeaders.set('cookie', filtered);
+            else
+                requestHeaders.delete('cookie');
+        }
+    }
+    const response = NextResponse.next({ request: { headers: requestHeaders } });
+    response.headers.set('Content-Security-Policy', 'frame-ancestors ' + frameAncestors.join(' '));
+    // Write the bearer cookie via raw appended Set-Cookie headers (not
+    // response.cookies.set) so the partitioned record and the legacy-unpartitioned
+    // clear are emitted as TWO separate headers — ResponseCookies keys by name and
+    // would collapse them into one. The bearer is Partitioned (CHIPS) because the
+    // app renders in a cross-site iframe, where a plain SameSite=None cookie is a
+    // third-party cookie Chrome blocks under the 3P-cookie phase-out. CHIPS does
+    // NOT rescue Safari, which implements no such thing and blocks cross-site
+    // iframe cookies outright — that browser never stores the bearer at all and is
+    // carried by the client-held bearer above instead. We always also clear the
+    // unpartitioned record so a pre-rollout legacy cookie can't shadow this one.
+    // The probe is a client-readable twin written and cleared in lockstep: it is
+    // how the client learns the bearer was dropped.
+    if (newBearer) {
+        const maxAge = Math.max(0, Math.floor((newBearerExpiresAt - Date.now()) / 1_000));
+        response.headers.append('Set-Cookie', serializeBearerCookie('', 0, false));
+        response.headers.append('Set-Cookie', serializeBearerCookie(newBearer, maxAge, true));
+        response.headers.append('Set-Cookie', serializeCookieProbe(true));
+    }
+    else if (clearBearerCookie) {
+        response.headers.append('Set-Cookie', serializeBearerCookie('', 0, false));
+        response.headers.append('Set-Cookie', serializeBearerCookie('', 0, true));
+        response.headers.append('Set-Cookie', serializeCookieProbe(true, true));
+    }
+    else if (bearerCookie && isDocumentRequest(request)) {
+        // Refresh the probe on a document served from a live cookie: it outlives the
+        // bearer, so without this it would eventually lapse on a browser whose
+        // cookies work and send that browser down the cookie-less path.
+        response.headers.append('Set-Cookie', serializeCookieProbe(true));
+    }
+    // Mirror the workspace's portal origin (the same platform-resolved value the
+    // CSP above uses) into a client-READABLE cookie: the foundation's
+    // origin-bootstrap module reads it at bundle load and registers it with the
+    // bridge allowlist. The bridge has no trust bypass, so this is the only path
+    // by which a custom portal domain becomes a valid postMessage parent.
+    // Partitioned + SameSite=None for the same CHIPS reasons as the bearer;
+    // deliberately NOT HttpOnly — being JS-readable is the point, and the value
+    // is not a secret (it is served in the CSP header of every response).
+    if (portalOrigin && isDocumentRequest(request)) {
+        response.headers.append('Set-Cookie', `assembly-portal-origin=${encodeURIComponent(portalOrigin)}; Path=/; Max-Age=86400; SameSite=None; Secure; Partitioned`);
+    }
+    // Client-readable flags cookie for foundation modules gated on a specific
+    // flag (origin bootstrap, the paint beacon) — the bearer cookie is HttpOnly,
+    // so they can't derive this themselves. Two sources, one writer:
+    //  - a fresh mint: the exchange response carries the evaluated allowlist, so
+    //    seeding costs no extra call;
+    //  - an expired/absent cookie on a live session: re-read via
+    //    GET /v1/session/flags on the existing bearer.
+    // The short Max-Age is the freshness knob: a flag flip (including OFF — this
+    // is also the rollback lever) reaches every app within one cookie TTL at its
+    // next document load, without re-minting bearers. A null re-read means
+    // "undetermined" (network blip, expired bearer) — keep whatever the browser
+    // holds rather than treating the miss as all-flags-off. Same CHIPS reasoning
+    // as the portal-origin cookie above.
+    if (isDocumentRequest(request)) {
+        let flags = null;
+        if (newBearer) {
+            flags = identity?.flags ?? [];
+        }
+        else if (identity &&
+            bearerCookie &&
+            !clearBearerCookie &&
+            !request.cookies.has(CLIENT_FLAGS_COOKIE_NAME)) {
+            flags = await fetchSessionFlags(bearerCookie);
+        }
+        if (flags !== null) {
+            response.headers.append('Set-Cookie', `${CLIENT_FLAGS_COOKIE_NAME}=${encodeURIComponent(flags.join(','))}; Path=/; Max-Age=${FLAGS_COOKIE_TTL_SECONDS}; SameSite=None; Secure; Partitioned`);
+        }
+    }
+    if (exchangeEnabled && isDocumentRequest(request)) {
+        if (newBearer) {
+            logCookieOutcome('minted');
+        }
+        else if (identity && servedFromClientBearer) {
+            logCookieOutcome('served_from_client_bearer', failClosedReason ? { rejectedToken: failClosedReason } : undefined);
+        }
+        else if (identity && bearerCookie && !clearBearerCookie) {
+            // A rejected ?token= that the warm cookie answered for is still worth
+            // surfacing (replay signal) — carry the reason instead of dropping it.
+            logCookieOutcome('served_from_cookie', failClosedReason ? { rejectedToken: failClosedReason } : undefined);
+        }
+        else {
+            const reason = failClosedReason ??
+                (clearBearerCookie ? 'undecodable' : urlToken ? 'rejected' : 'no_session');
+            logCookieOutcome(`fail_closed:${reason}`);
+        }
+    }
+    return response;
+}