@assembly-js/app-foundation 0.0.41 → 0.0.42

package/bin/check-paint-beacon.mjs

@@ -57,22 +57,21 @@ if (existsSync(join(ROOT, PROXY_FILE))) {
   // like 'https://*.assembly.com' in the CSP list, and dependency-free means
   // no real tokenizer.
   const proxy = readFileSync(join(ROOT, PROXY_FILE), 'utf8').replace(/^\s*\/\/.*$/gm, '');
+  // The package's proxy routes the beacon itself.
+  const usesPackageProxy = /createAssemblyProxy\s*\(/.test(proxy);
   const importsHelpers =
     /isPaintedBeaconPath/.test(proxy) && /handlePaintedBeacon/.test(proxy);
   const usesHelpers =
     /isPaintedBeaconPath\s*\(/.test(proxy) && /handlePaintedBeacon\s*\(/.test(proxy);
 
-  if (!importsHelpers || !usesHelpers) {
+  if (!usesPackageProxy && (!importsHelpers || !usesHelpers)) {
     console.error(
-      `check-paint-beacon: ${PROXY_FILE} must route the beacon's POST before CSRF/exchange:\n\n` +
-        "  import { isPaintedBeaconPath, handlePaintedBeacon } from '@assembly-js/app-foundation/client';\n" +
-        '  // …first thing in the proxy function:\n' +
-        "  if (request.method === 'POST' && isPaintedBeaconPath(request.nextUrl.pathname)) {\n" +
-        '    return handlePaintedBeacon();\n' +
-        '  }\n\n' +
+      `check-paint-beacon: ${PROXY_FILE} must route the beacon's POST before CSRF/exchange. ` +
+        'The platform sign-in proxy does this; restore it:\n\n' +
+        "  import { createAssemblyProxy } from '@assembly-js/app-foundation/server';\n" +
+        '  export const proxy = createAssemblyProxy();\n\n' +
         "sendBeacon is a headerless POST — routing it through the normal CSRF/exchange path 403s it, " +
-        'silently breaking the paint signal. POST only: a GET to the path must fall through, not ' +
-        'mint a fake painted line.',
+        'silently breaking the paint signal.',
     );
     process.exit(1);
   }

package/bin/check-proxy-csrf.mjs

@@ -0,0 +1,387 @@
+#!/usr/bin/env node
+// Fails the build when the app's proxy does not behave like the sign-in proxy:
+// it must reject a state-changing request that lacks the CSRF header, forward
+// one that carries it without the proxy ever adding the header itself, leave
+// the re-exchange route reachable, and accept the cookieless (Safari) bearer.
+// A text check cannot tell a gate from a bypass — an update turn once satisfied
+// "proxy.ts contains APP_CSRF_HEADER" by stamping the header on every request —
+// so this loads the app's real proxy and sends it requests.
+//
+// Runs under node like the other checks, then re-executes itself under bun,
+// which can import the app's TypeScript proxy directly. In that child
+// `server-only` and the node SDK are stubbed and fetch is disabled: no probe
+// carries a session token, so nothing here needs the network.
+//
+// Like check-crons, a broken proxy fails the build only when the current turn
+// changed it (or with --strict, which the update acceptance passes); otherwise
+// the findings are warnings, since there is no agent to act on them. An app
+// still on the pre-bearer foundation only ever warns outside --strict: the
+// platform security update is what fixes it, not an ordinary turn.
+import { existsSync, readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const ROOT = process.cwd();
+const STRICT = process.argv.includes('--strict');
+const PROXY_FILES = ['proxy.ts', 'middleware.ts'];
+const REEXCHANGE_ROUTE = 'app/api/assembly-reexchange/route.ts';
+const REEXCHANGE_PATH = '/api/assembly-reexchange';
+const PRE_BEARER_MARKER = 'lib/assembly.ts';
+const VENDORED_BEARER_MARKER = 'lib/mint-bearer.ts';
+const RESULT_PREFIX = 'check-proxy-csrf-result ';
+const CHILD_TIMEOUT_MS = 60_000;
+
+const TURN_BASELINE_ENV = 'ASSEMBLY_TURN_BASELINE_SHA';
+const PROXY_WIRING_PATHS = [...PROXY_FILES, 'app/api/assembly-reexchange/'];
+
+// Each finding id is a fixed string with a fixed explanation; the request that
+// produced it travels as JSON detail, so reports group by id.
+const FINDINGS = {
+  proxy_missing: 'no proxy.ts at the app root',
+  proxy_unloadable: 'the proxy module could not be loaded',
+  proxy_threw: 'the proxy threw while handling a request',
+  proxy_skips_path: 'the proxy matcher leaves a path that serves app requests unprotected',
+  csrf_gate_missing: 'a state-changing request without the CSRF header was forwarded',
+  csrf_header_stamped: 'the proxy added the CSRF header to a request that did not carry it',
+  csrf_request_blocked: 'a state-changing request carrying the CSRF header was not forwarded',
+  csrf_header_stripped: 'the proxy removed the CSRF header from a forwarded request',
+  server_action_blocked: 'a Next server action was not forwarded',
+  reexchange_not_excluded: 'the proxy matcher does not exclude the re-exchange route',
+  reexchange_blocked_by_proxy: 'the proxy does not pass a re-exchange request through with its CSRF header',
+  reexchange_route_missing: `${REEXCHANGE_ROUTE} is missing`,
+  reexchange_csrf_missing: 'the re-exchange route accepts a request without the CSRF header',
+  reexchange_always_forbidden: 'the re-exchange route rejects a request that carries the CSRF header',
+  cookieless_fallback_missing: 'a bearer sent in the client-bearer header was not forwarded to the render',
+};
+
+if (process.env.ASSEMBLY_PROXY_CHECK_CHILD === '1') {
+  await runProbes();
+} else {
+  runCheck();
+}
+
+// --- parent (node) ---------------------------------------------------------
+
+function runCheck() {
+  const proxyFile = PROXY_FILES.find((f) => existsSync(join(ROOT, f)));
+  // An app still on the pre-bearer foundation (lib/assembly.ts without
+  // lib/mint-bearer.ts, the same markers check-token-usage reads, and no
+  // package proxy) cannot pass this check by an ordinary turn's edits: the platform
+  // security update is what moves it. Its findings stay warnings that say so,
+  // unless --strict (the update's own acceptance) asks for a verdict.
+  const usesPackageProxy =
+    Boolean(proxyFile) && /createAssemblyProxy\s*\(/.test(readFileSync(join(ROOT, proxyFile), 'utf8'));
+  const preBearer =
+    existsSync(join(ROOT, PRE_BEARER_MARKER)) &&
+    !existsSync(join(ROOT, VENDORED_BEARER_MARKER)) &&
+    !usesPackageProxy;
+  const fatal = STRICT || (!preBearer && proxyChangedThisTurn());
+  const report = (findings) => reportFindings(findings, fatal, preBearer);
+  if (!proxyFile) {
+    report([{ id: 'proxy_missing', detail: {} }]);
+    return;
+  }
+
+  const bun = findBun();
+  const child = spawnSync(bun, [fileURLToPath(import.meta.url), ...process.argv.slice(2)], {
+    cwd: ROOT,
+    encoding: 'utf8',
+    timeout: CHILD_TIMEOUT_MS,
+    env: {
+      ...process.env,
+      ASSEMBLY_PROXY_CHECK_CHILD: '1',
+      ASSEMBLY_PROXY_CHECK_FILE: proxyFile,
+      // The gate is dormant while the exchange is off, so probe it switched on.
+      ENABLE_APP_SESSION_TOKEN_EXCHANGE: 'true',
+      ASSEMBLY_API_KEY: '',
+    },
+  });
+  if (child.error) {
+    // No bun to load TypeScript with (e.g. a deploy builder): nothing to prove
+    // here, and the turn that wrote the proxy already ran this in the sandbox.
+    const line = `check-proxy-csrf: skipped, bun is not available (${child.error.code ?? 'spawn error'})`;
+    if (fatal) {
+      console.error(line);
+      process.exit(1);
+    }
+    console.warn(line);
+    return;
+  }
+  const resultLine = (child.stdout ?? '')
+    .split('\n')
+    .reverse()
+    .find((l) => l.startsWith(RESULT_PREFIX));
+  if (!resultLine) {
+    const stderrTail = (child.stderr ?? '').trim().split('\n').slice(-8).join('\n');
+    report([{ id: 'proxy_unloadable', detail: { file: proxyFile, stderr: stderrTail } }]);
+    return;
+  }
+  const { findings } = JSON.parse(resultLine.slice(RESULT_PREFIX.length));
+  if (findings.length > 0) report(findings);
+}
+
+function reportFindings(findings, fatal, preBearer) {
+  const out = fatal ? console.error : console.warn;
+  out('');
+  out(
+    fatal
+      ? 'check-proxy-csrf: the app proxy does not enforce the sign-in CSRF gate:'
+      : 'check-proxy-csrf: the app proxy does not enforce the sign-in CSRF gate (pre-existing; this build is not failed for it):',
+  );
+  out('');
+  for (const { id, detail } of findings) {
+    out(`  - ${id}: ${FINDINGS[id] ?? id} ${JSON.stringify(detail)}`);
+  }
+  out('');
+  if (preBearer && !fatal) {
+    out('This app predates the platform sign-in proxy. The platform security update moves it onto that');
+    out('proxy; do not rewrite proxy.ts in this turn to satisfy this check.');
+    return;
+  }
+  out('proxy.ts is the platform sign-in proxy. It must be exactly this, plus the app\'s own additions in onForward:');
+  out('');
+  out("  import { createAssemblyProxy } from '@assembly-js/app-foundation/server';");
+  out('');
+  out('  export const proxy = createAssemblyProxy({');
+  out('    // optional: onForward({ request, headers, session }) { headers.set(...) },');
+  out('  });');
+  out('');
+  out('  export const config = {');
+  out('    matcher: [');
+  out("      '/((?!_next/static(?:/|$)|_next/image(?:/|$)|api/assembly-reexchange(?:/|$)).*)',");
+  out('    ],');
+  out('  };');
+  out('');
+  out('Never set or delete the CSRF header in the proxy, and never write your own gate.');
+  if (fatal) process.exit(1);
+}
+
+function findBun() {
+  const execPath = process.env.npm_execpath ?? '';
+  if (/\bbun(\.exe)?$/.test(execPath)) return execPath;
+  const installed = join(process.env.BUN_INSTALL ?? join(homedir(), '.bun'), 'bin', 'bun');
+  return existsSync(installed) ? installed : 'bun';
+}
+
+function proxyChangedThisTurn() {
+  const baseline = (process.env[TURN_BASELINE_ENV] ?? '').trim();
+  if (!baseline) return false;
+  const listings = [
+    { args: ['diff', '--name-only', `${baseline}..HEAD`], parse: (line) => line },
+    // Porcelain rows are "XY path", or "XY old -> new" for a rename.
+    { args: ['status', '--porcelain', '--untracked-files=all'], parse: (line) => line.slice(3).split(' -> ').pop() },
+  ];
+  for (const { args, parse } of listings) {
+    const result = spawnSync('git', args, { cwd: ROOT, encoding: 'utf8' });
+    if (result.status !== 0) return true;
+    const changed = result.stdout.split('\n').map((line) => parse(line).trim()).filter(Boolean);
+    if (changed.some((file) => PROXY_WIRING_PATHS.some((p) => (p.endsWith('/') ? file.startsWith(p) : file === p)))) {
+      return true;
+    }
+  }
+  return false;
+}
+
+// --- child (bun) -----------------------------------------------------------
+
+async function runProbes() {
+  const findings = [];
+  const add = (id, detail) => findings.push({ id, detail });
+  const finish = () => {
+    console.log(RESULT_PREFIX + JSON.stringify({ findings }));
+    process.exit(0);
+  };
+
+  stubServerModules();
+  // Next's server runtime installs this global before any app module loads;
+  // its request-scoped helpers (after, headers) throw at import without it.
+  globalThis.AsyncLocalStorage ??= (await import('node:async_hooks')).AsyncLocalStorage;
+  globalThis.fetch = () => Promise.reject(new Error('network is disabled in check-proxy-csrf'));
+
+  const appRequire = createRequire(join(ROOT, 'package.json'));
+  const { NextRequest } = await import(appRequire.resolve('next/server'));
+  const { APP_CSRF_HEADER, BEARER_HEADER_NAME, CLIENT_BEARER_HEADER } = await import(
+    appRequire.resolve('@assembly-js/app-foundation/client')
+  );
+  const proxyFile = process.env.ASSEMBLY_PROXY_CHECK_FILE;
+  const mod = await import(pathToFileURL(join(ROOT, proxyFile)).href);
+  const handler = mod.proxy ?? mod.middleware ?? mod.default;
+  if (typeof handler !== 'function') {
+    add('proxy_unloadable', { file: proxyFile, reason: 'no proxy export' });
+    finish();
+  }
+
+  const origin = 'http://localhost:3000';
+  const send = async (fn, probe, method, path, headers = {}) => {
+    const request = new NextRequest(new URL(path, origin), { method, headers });
+    try {
+      return describeOutcome(await fn(request), headers);
+    } catch (err) {
+      add('proxy_threw', { probe, method, path, error: String(err?.message ?? err) });
+      return null;
+    }
+  };
+  const apiPath = '/api/proxy-check';
+  // CSRF rides on ambient credentials, so the forged-write probes carry a
+  // cookie; a cookieless write (an inbound webhook) is allowed through.
+  const AMBIENT_COOKIE = 'assembly-proxy-check=1';
+  const CROSS_SITE_FORM = {
+    cookie: AMBIENT_COOKIE,
+    origin: 'https://attacker.example',
+    'sec-fetch-site': 'cross-site',
+    'content-type': 'application/x-www-form-urlencoded',
+  };
+  // Next only runs the proxy where config.matcher says, so a probe on any other
+  // path would pass against a gate no real request reaches.
+  const skipped = new Set();
+  for (const path of [apiPath, '/']) {
+    if (!(await proxyRunsOn(appRequire, mod.config, path))) {
+      skipped.add(path);
+      add('proxy_skips_path', { path });
+    }
+  }
+  const proxy = async (probe, method, path, headers) =>
+    skipped.has(path) ? null : send(handler, probe, method, path, headers);
+
+  for (const [method, path] of [
+    ['POST', apiPath],
+    ['PUT', apiPath],
+    ['PATCH', apiPath],
+    ['DELETE', apiPath],
+    ['POST', '/'],
+  ]) {
+    const out = await proxy('no_csrf_header', method, path, { cookie: AMBIENT_COOKIE });
+    if (out && !out.rejected) add('csrf_gate_missing', { method, path, status: out.status, variant: 'cookie' });
+  }
+  // What a cross-site form post actually sends: a gate keyed on any of these
+  // (e.g. trusting a request because it has an Origin) must still reject it.
+  for (const path of [apiPath, '/']) {
+    const out = await proxy('cross_site_form', 'POST', path, CROSS_SITE_FORM);
+    if (out && !out.rejected) add('csrf_gate_missing', { method: 'POST', path, status: out.status, variant: 'cross_site_form' });
+  }
+
+  const read = await proxy('get_without_header', 'GET', apiPath);
+  if (read?.forwarded && read.forwardedHeader(APP_CSRF_HEADER) !== null) {
+    add('csrf_header_stamped', { method: 'GET', path: apiPath });
+  }
+
+  // Legitimate writes come from a signed-in browser, so they carry its cookies too.
+  const write = await proxy('with_csrf_header', 'POST', apiPath, { cookie: AMBIENT_COOKIE, [APP_CSRF_HEADER]: '1' });
+  if (write && !write.forwarded) {
+    add('csrf_request_blocked', { method: 'POST', path: apiPath, status: write.status });
+  } else if (write && write.forwardedHeader(APP_CSRF_HEADER) === null) {
+    add('csrf_header_stripped', { method: 'POST', path: apiPath });
+  }
+
+  const action = await proxy('server_action', 'POST', '/', { cookie: AMBIENT_COOKIE, 'next-action': 'proxy-check' });
+  if (action && !action.forwarded) add('server_action_blocked', { status: action.status });
+
+  // The route enforces CSRF itself; the proxy must either not run on it or
+  // pass it through untouched, else silent renewal is dead after the bearer's
+  // first hour.
+  if (await proxyRunsOn(appRequire, mod.config, REEXCHANGE_PATH)) {
+    add('reexchange_not_excluded', { path: REEXCHANGE_PATH });
+    const out = await proxy('reexchange', 'POST', REEXCHANGE_PATH, { [APP_CSRF_HEADER]: '1' });
+    if (out && (!out.forwarded || out.forwardedHeader(APP_CSRF_HEADER) === null)) {
+      add('reexchange_blocked_by_proxy', { status: out.status });
+    }
+  }
+  if (!existsSync(join(ROOT, REEXCHANGE_ROUTE))) {
+    add('reexchange_route_missing', {});
+  } else {
+    const route = await import(pathToFileURL(join(ROOT, REEXCHANGE_ROUTE)).href);
+    if (typeof route.POST !== 'function') {
+      add('reexchange_route_missing', { reason: 'no POST export' });
+    } else {
+      const bare = await send(route.POST, 'reexchange_route', 'POST', REEXCHANGE_PATH);
+      if (bare && bare.status !== 403) add('reexchange_csrf_missing', { status: bare.status });
+      const headed = await send(route.POST, 'reexchange_route', 'POST', REEXCHANGE_PATH, {
+        [APP_CSRF_HEADER]: '1',
+      });
+      if (headed && headed.status === 403) add('reexchange_always_forbidden', { status: headed.status });
+    }
+  }
+
+  // Browsers that refuse the partitioned cookie (Safari) hold the bearer in
+  // memory and send it as a header; the proxy must hand it to the render.
+  const bearer = unsignedBearer({ workspace_id: 'proxy-check', exp: Math.floor(Date.now() / 1000) + 3600 });
+  const cookieless = await proxy('cookieless_bearer', 'GET', '/', { [CLIENT_BEARER_HEADER]: bearer });
+  if (cookieless && (!cookieless.forwarded || cookieless.forwardedHeader(BEARER_HEADER_NAME) !== bearer)) {
+    add('cookieless_fallback_missing', { status: cookieless.status });
+  }
+
+  finish();
+}
+
+// What the proxy did with a request: forwarded (NextResponse.next / rewrite, or
+// no response at all) or answered itself, and for a forward, the headers the
+// render would see. NextResponse.next({ request: { headers } }) lists every
+// forwarded header in x-middleware-override-headers; without that header the
+// inbound request passes through unchanged.
+function describeOutcome(response, inbound) {
+  if (!response) {
+    return { forwarded: true, rejected: false, status: 200, forwardedHeader: (n) => inbound[n] ?? null };
+  }
+  const forwarded =
+    response.headers.get('x-middleware-next') === '1' || response.headers.has('x-middleware-rewrite');
+  const override = response.headers.get('x-middleware-override-headers');
+  const forwardedHeader = (name) => {
+    if (override === null) return inbound[name] ?? null;
+    return override.split(',').map((h) => h.trim()).includes(name)
+      ? response.headers.get(`x-middleware-request-${name}`)
+      : null;
+  };
+  return {
+    forwarded,
+    rejected: !forwarded && response.status >= 400 && response.status < 500,
+    status: response.status,
+    forwardedHeader,
+  };
+}
+
+async function proxyRunsOn(appRequire, config, path) {
+  if (!config?.matcher) return true;
+  try {
+    const { unstable_doesMiddlewareMatch } = await import(
+      appRequire.resolve('next/experimental/testing/server')
+    );
+    return unstable_doesMiddlewareMatch({ config, url: path });
+  } catch {
+    // No matcher helper in this Next version: assume the proxy runs there.
+    return true;
+  }
+}
+
+function unsignedBearer(claims) {
+  const b64 = (o) => Buffer.from(JSON.stringify(o)).toString('base64url');
+  return `${b64({ alg: 'none', typ: 'JWT' })}.${b64(claims)}.proxy-check`;
+}
+
+// `server-only` throws outside a React Server Component bundle, and the SDK
+// would reach the network; neither has anything to do with the CSRF gate. Bun
+// runtime plugins intercept by resolved file path, not by specifier.
+function stubServerModules() {
+  const stub = (dir, contents) => ({
+    filter: new RegExp(`node_modules[\\\\/]${dir}[\\\\/].*\\.[cm]?js$`),
+    contents,
+  });
+  const stubs = [
+    stub('server-only', 'export {};'),
+    stub(
+      '@assembly-js[\\\\/]node-sdk',
+      "export const OpenAPI = { BASE: 'http://127.0.0.1:9' };\n" +
+        "export async function assemblyApi() { throw new Error('network is disabled in check-proxy-csrf'); }\n",
+    ),
+  ];
+  Bun.plugin({
+    name: 'check-proxy-csrf-stubs',
+    setup(build) {
+      for (const { filter, contents } of stubs) {
+        build.onLoad({ filter }, () => ({ contents, loader: 'js' }));
+      }
+    },
+  });
+}

package/dist/proxy.d.ts

@@ -0,0 +1,11 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { type ExchangedSession } from './session-exchange.js';
+export interface AssemblyProxyForwardContext {
+    request: NextRequest;
+    headers: Headers;
+    session: ExchangedSession | null;
+}
+export interface AssemblyProxyOptions {
+    onForward?: (context: AssemblyProxyForwardContext) => void | Promise<void>;
+}
+export declare function createAssemblyProxy(options?: AssemblyProxyOptions): (request: NextRequest) => Promise<NextResponse | Response>;

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;
+}

package/dist/server.d.ts

@@ -12,6 +12,7 @@ export * from './labels.js';
 export * from './notifications.js';
 export * from './cron.js';
 export * from './replace-rows.js';
+export * from './proxy.js';
 export * from './api-errors.js';
 export * from './params.js';
 export * from './client.js';

package/dist/server.js

@@ -16,6 +16,7 @@ export * from './labels.js';
 export * from './notifications.js';
 export * from './cron.js';
 export * from './replace-rows.js';
+export * from './proxy.js';
 // Returns NextResponse, so route handlers only — but nothing here reads a
 // secret, which is why a client file may still `import type` from them.
 export * from './api-errors.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assembly-js/app-foundation",
-  "version": "0.0.41",
+  "version": "0.0.42",
   "description": "Versioned foundation helpers and build context for Assembly generated apps",
   "type": "module",
   "files": [
@@ -30,7 +30,7 @@
   },
   "scripts": {
     "build": "tsc && tsc-alias",
-    "test": "bun test && tsc -p tsconfig.replace-rows.json",
+    "test": "npm run build && bun test --path-ignore-patterns='**/proxy.test.ts' && bun test ./src/proxy.test.ts && tsc -p tsconfig.replace-rows.json",
     "prepublishOnly": "npm run build && npm run verify:dist && npm run verify:bin",
     "verify:dist": "node scripts/verify-dist-resolves.mjs",
     "verify:bin": "node scripts/verify-bin.mjs"