@assembly-js/app-foundation 0.5.4 → 0.6.1

package/CHANGELOG.md

@@ -19,6 +19,13 @@ A patch release never changes what an app's build requires; a minor release may
 not by hand; see `changes/README.md`. CI fails a PR that changes a check script without a
 `bump: minor` change file.
 
+## 0.6.1
+- [fix] The client-call scan no longer reports a `fetch` to the AI proxy (`POST /v1/ai/openai/...`) as breaking: the platform now admits a client bearer on that route. Nothing in the app changes.
+
+## 0.6.0
+- [new] `AuthUnavailableError` carries a fixed digest (`AUTH_UNAVAILABLE_DIGEST`), so an app's error boundary can recognise a platform outage after production has redacted the error.
+- [action] A platform outage reaches the retry screen from every page, not only the root layout: `app/error.tsx` renders it on that digest and no helper or route may swallow the error; the renewal limiter earlier updates copied into the app is removed now that the package bounds renewal itself.
+
 ## 0.5.4
 - [fix] A tab left open renews its sign-in before it expires, so clicking into a page after an hour no longer shows the signed-out screen.
 

package/bin/check-identity-outage-states.mjs

@@ -4,131 +4,277 @@
 // before any deps beyond Node exist.
 //
 // Since foundation 0.0.40, getSessionIdentity() throws AuthUnavailableError
-// when the platform can't be reached. The app must catch it in the root layout
-// and render a retry screen, and its client context must bound session renewal
-// with createRenewalGate — otherwise an outage fails every page and every
-// failed action renews the session without limit.
+// when the platform can't be reached, and the error carries a fixed digest
+// (AUTH_UNAVAILABLE_DIGEST) that survives production's error redaction. The
+// contract is therefore small: app/error.tsx renders the retry screen on that
+// digest, so a page or nested layout that throws it is covered without code of
+// its own; the root layout catches it itself, because its errors bypass the
+// boundary; and nothing in between swallows it — a catch around the call (or a
+// .catch() chained onto it) rethrows AuthUnavailableError, or a route handler
+// returns handleRouteError(err)
+// (a retryable 503). A helper with no catch propagates and passes; the pages
+// that call such a helper are not followed, so a page that swallows a helper's
+// error is only caught when the page itself calls getSessionIdentity().
 //
-// An app whose root layout never calls getSessionIdentity predates identity
-// confirmation, so the contract never applied and this check exits 0.
+// An app with no getSessionIdentity() call predates identity confirmation, so
+// the contract never applied and this check exits 0.
+//
+// Session renewal is bounded inside the package since 0.5.3, so the vendored
+// app/components/renewal-gate.ts that earlier updates copied in is superseded:
+// --strict (the update acceptance) asks for its removal, an ordinary turn only
+// mentions it.
 //
 // A gap is a warning on an ordinary turn (no agent there can act on an app
-// that was already behind) and fails the build with --strict (the update
-// acceptance) or when ASSEMBLY_TURN_BASELINE_SHA says this turn changed one of
-// the contract files.
-import { existsSync, readFileSync } from 'node:fs';
+// that was already behind) and fails the build with --strict or when
+// ASSEMBLY_TURN_BASELINE_SHA says this turn changed one of the contract files.
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
-import { join } from 'node:path';
+import { join, relative } from 'node:path';
 
 const ROOT = process.cwd();
 const STRICT = process.argv.includes('--strict');
 const TURN_BASELINE_ENV = 'ASSEMBLY_TURN_BASELINE_SHA';
 
 const LAYOUT_FILE = 'app/layout.tsx';
+const ERROR_BOUNDARY_FILE = 'app/error.tsx';
 const CONTEXT_FILE = 'app/components/assembly-context.tsx';
 const RETRY_SCREEN_FILE = 'app/components/auth-unavailable.tsx';
 const RENEWAL_GATE_FILE = 'app/components/renewal-gate.ts';
-const CONTRACT_FILES = [LAYOUT_FILE, CONTEXT_FILE, RETRY_SCREEN_FILE, RENEWAL_GATE_FILE];
+const RENEWAL_GATE_TEST_FILE = 'app/components/renewal-gate.test.ts';
+const SCAN_DIRS = ['app', 'lib'];
+const SKIP_DIRS = new Set(['node_modules', '.next']);
+
+const IDENTITY_CALL = /getSessionIdentity\s*\(/;
+const HANDLED = /AuthUnavailableError|handleRouteError\s*\(/;
+// A catch that rethrows at all lets the outage through to the boundary.
+const CATCH_LETS_THROUGH = /\bthrow\b|AuthUnavailableError|handleRouteError\s*\(/;
+const BOUNDARY_COMPARES_DIGEST = /\.digest\s*===?\s*AUTH_UNAVAILABLE_DIGEST|AUTH_UNAVAILABLE_DIGEST\s*===?\s*[\w.]*digest/;
+const BOUNDARY_RENDERS_RETRY = /<AuthUnavailable\s*\/?>/;
 
 const read = (file) => (existsSync(join(ROOT, file)) ? readFileSync(join(ROOT, file), 'utf8') : null);
 
-const layout = read(LAYOUT_FILE);
-if (layout === null || !/\bgetSessionIdentity\b/.test(layout)) {
-  process.exit(0); // pre-identity app: not this check's contract
+// Server .ts/.tsx files under app/ and lib/: no 'use client' directive, no tests.
+function serverFiles() {
+  const files = [];
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir)) {
+      if (SKIP_DIRS.has(entry)) continue;
+      const full = join(dir, entry);
+      if (statSync(full).isDirectory()) {
+        walk(full);
+        continue;
+      }
+      if (!/\.tsx?$/.test(entry) || /\.(test|spec)\.tsx?$/.test(entry) || /\.d\.ts$/.test(entry)) continue;
+      files.push(relative(ROOT, full).split('\\').join('/'));
+    }
+  };
+  for (const dir of SCAN_DIRS) {
+    if (existsSync(join(ROOT, dir))) walk(join(ROOT, dir));
+  }
+  return files.filter((file) => !/^\s*['"]use client['"]/m.test(read(file)));
+}
+
+function callsIdentity(source) {
+  return source
+    .split('\n')
+    .some((line) => !/^\s*(\/\/|\/\*|\*)/.test(line) && IDENTITY_CALL.test(line));
+}
+
+// Index of the bracket that closes the one at `open` (a brace or a paren),
+// skipping brackets inside strings, template literals and comments. -1 when
+// unbalanced.
+function closingBracket(source, open) {
+  const opener = source[open];
+  const closer = opener === '(' ? ')' : '}';
+  let depth = 0;
+  for (let i = open; i < source.length; i++) {
+    const ch = source[i];
+    const next = source[i + 1];
+    if (ch === '/' && next === '/') {
+      i = source.indexOf('\n', i);
+      if (i === -1) return -1;
+      continue;
+    }
+    if (ch === '/' && next === '*') {
+      i = source.indexOf('*/', i + 2);
+      if (i === -1) return -1;
+      i += 1;
+      continue;
+    }
+    if (ch === "'" || ch === '"' || ch === '`') {
+      for (i += 1; i < source.length && source[i] !== ch; i++) if (source[i] === '\\') i++;
+      continue;
+    }
+    if (ch === opener) depth++;
+    else if (ch === closer && --depth === 0) return i;
+  }
+  return -1;
 }
 
-const context = read(CONTEXT_FILE);
+// The handlers that can swallow a getSessionIdentity() call: the catch block
+// of a try that contains the call, and a .catch() chained onto the call. A
+// catch elsewhere in the file (JSON parsing, a fallback) is not this contract's
+// business, and a call outside either propagates on its own.
+function catchBlocksAround(source) {
+  const blocks = [];
+  const calls = [...source.matchAll(/getSessionIdentity\s*\(/g)].map((m) => m.index);
+  for (const match of source.matchAll(/\btry\s*\{/g)) {
+    const open = match.index + match[0].length - 1;
+    const close = closingBracket(source, open);
+    if (close === -1 || !calls.some((at) => at > open && at < close)) continue;
+    const catchMatch = /^\s*catch\b[^{]*\{/.exec(source.slice(close + 1));
+    if (!catchMatch) continue;
+    const catchOpen = close + 1 + catchMatch[0].length - 1;
+    const catchClose = closingBracket(source, catchOpen);
+    if (catchClose === -1) continue;
+    blocks.push(source.slice(catchOpen + 1, catchClose));
+  }
+  for (const at of calls) {
+    const argsOpen = source.indexOf('(', at);
+    const argsClose = closingBracket(source, argsOpen);
+    if (argsClose === -1) continue;
+    const chained = /^\s*\.catch\s*\(/.exec(source.slice(argsClose + 1));
+    if (!chained) continue;
+    const handlerOpen = argsClose + 1 + chained[0].length - 1;
+    const handlerClose = closingBracket(source, handlerOpen);
+    if (handlerClose === -1) continue;
+    blocks.push(source.slice(handlerOpen + 1, handlerClose));
+  }
+  return blocks;
+}
+
+const callSites = serverFiles().filter((file) => callsIdentity(read(file)));
+if (callSites.length === 0) process.exit(0); // pre-identity app: not this check's contract
+
+const CONTRACT_FILES = [
+  ...new Set([LAYOUT_FILE, ERROR_BOUNDARY_FILE, CONTEXT_FILE, RETRY_SCREEN_FILE, ...callSites]),
+];
+
 const problems = [];
 if (read(RETRY_SCREEN_FILE) === null) problems.push(`${RETRY_SCREEN_FILE} is missing`);
-if (!/AuthUnavailableError/.test(layout)) {
-  problems.push(`${LAYOUT_FILE} does not handle AuthUnavailableError from getSessionIdentity()`);
+const boundary = read(ERROR_BOUNDARY_FILE);
+if (boundary === null) {
+  problems.push(`${ERROR_BOUNDARY_FILE} is missing`);
+} else if (!BOUNDARY_COMPARES_DIGEST.test(boundary) || !BOUNDARY_RENDERS_RETRY.test(boundary)) {
+  problems.push(`${ERROR_BOUNDARY_FILE} does not render <AuthUnavailable /> when error.digest is AUTH_UNAVAILABLE_DIGEST`);
 }
-if (read(RENEWAL_GATE_FILE) === null) problems.push(`${RENEWAL_GATE_FILE} is missing`);
-if (context !== null && !/createRenewalGate\s*\(/.test(context)) {
-  problems.push(`${CONTEXT_FILE} does not bound session renewal with createRenewalGate(`);
+for (const file of callSites) {
+  const source = read(file);
+  if (file === LAYOUT_FILE) {
+    if (!HANDLED.test(source)) {
+      problems.push(`${file} calls getSessionIdentity() without handling AuthUnavailableError`);
+    }
+  } else if (catchBlocksAround(source).some((block) => !CATCH_LETS_THROUGH.test(block))) {
+    problems.push(`${file} catches around getSessionIdentity() without rethrowing AuthUnavailableError`);
+  }
 }
+const gateVendored = read(RENEWAL_GATE_FILE) !== null;
 
-if (problems.length === 0) process.exit(0);
+if (problems.length === 0 && !gateVendored) process.exit(0);
 
-const fatal = STRICT || contractChangedThisTurn();
+const fatal = (problems.length > 0 && (STRICT || contractChangedThisTurn())) || (gateVendored && STRICT);
 const out = fatal ? console.error : console.warn;
 out('');
-out(
-  fatal
-    ? 'check-identity-outage-states: the app does not handle the platform being unable to confirm the viewer:'
-    : 'check-identity-outage-states: the app does not handle the platform being unable to confirm the viewer (pre-existing; this build is not failed for it):',
-);
-out('');
-for (const problem of problems) out(`  - ${problem}`);
-out('');
-out('Since @assembly-js/app-foundation 0.0.40, getSessionIdentity() throws AuthUnavailableError when the');
-out('platform cannot be reached. Bring these app-owned files to the foundation shape:');
-out('');
-out(`1. Create ${RETRY_SCREEN_FILE}:`);
-out('');
-out("   'use client';");
-out('');
-out('   export default function AuthUnavailable() {');
-out('     return (');
-out('       <main className="flex min-h-screen flex-col items-center justify-center gap-3 px-4 text-center">');
-out('         <p className="text-sm text-muted-foreground">');
-out('           We couldn&apos;t load this right now. Please try again.');
-out('         </p>');
-out('         <button');
-out('           type="button"');
-out('           className="rounded-md border px-3 py-1.5 text-sm"');
-out('           onClick={() => window.location.reload()}');
-out('         >');
-out('           Try again');
-out('         </button>');
-out('       </main>');
-out('     );');
-out('   }');
-out('');
-out(`2. In ${LAYOUT_FILE}, import it (import AuthUnavailable from '@/app/components/auth-unavailable';)`);
-out('   and replace `const identity = await getSessionIdentity();` with:');
-out('');
-out('   let identity: Awaited<ReturnType<typeof getSessionIdentity>> = null;');
-out('   let authUnavailable = false;');
-out('   try {');
-out('     identity = await getSessionIdentity();');
-out('   } catch (err) {');
-out("     if (!(err instanceof Error && err.name === 'AuthUnavailableError')) throw err;");
-out('     authUnavailable = true;');
-out('   }');
-out('   if (authUnavailable) {');
-out('     return (');
-out("       <html lang=\"en\" style={{ colorScheme: 'light' }}>");
-out('         <body className="font-sans antialiased">');
-out('           <AuthUnavailable />');
-out('         </body>');
-out('       </html>');
-out('     );');
-out('   }');
-out('');
-out(`3. Create ${RENEWAL_GATE_FILE}:`);
-out('');
-out('   export function createRenewalGate(');
-out('     renew: () => Promise<boolean>,');
-out('     windowMs: number,');
-out('     now: () => number = Date.now,');
-out('   ): () => Promise<boolean> {');
-out('     let inFlight: Promise<boolean> | null = null;');
-out('     let lastStartedAt = Number.NEGATIVE_INFINITY;');
-out('     return () => {');
-out('       if (inFlight) return inFlight;');
-out('       if (now() - lastStartedAt < windowMs) return Promise.resolve(false);');
-out('       lastStartedAt = now();');
-out('       inFlight = renew().finally(() => {');
-out('         inFlight = null;');
-out('       });');
-out('       return inFlight;');
-out('     };');
-out('   }');
-out('');
-out(`   Then in ${CONTEXT_FILE} add \`import { createRenewalGate } from './renewal-gate';\`, define`);
-out('   `const renewOnce = createRenewalGate(reexchangeBearer, 30_000);` at module scope, and change the');
-out("   retry path's `await reexchangeBearer()` to `await renewOnce()`. Change nothing else in that file.");
+if (problems.length > 0) {
+  out(
+    fatal
+      ? 'check-identity-outage-states: the app does not handle the platform being unable to confirm the viewer:'
+      : 'check-identity-outage-states: the app does not handle the platform being unable to confirm the viewer (pre-existing; this build is not failed for it):',
+  );
+  out('');
+  for (const problem of problems) out(`  - ${problem}`);
+  out('');
+  out('Since @assembly-js/app-foundation 0.0.40, getSessionIdentity() throws AuthUnavailableError when the');
+  out('platform cannot be reached. Wherever the app calls it, that error must reach the retry screen:');
+  out('');
+  out(`1. Create ${RETRY_SCREEN_FILE}:`);
+  out('');
+  out("   'use client';");
+  out('');
+  out('   export default function AuthUnavailable() {');
+  out('     return (');
+  out('       <main className="flex min-h-screen flex-col items-center justify-center gap-3 px-4 text-center">');
+  out('         <p className="text-sm text-muted-foreground">');
+  out('           We couldn&apos;t load this right now. Please try again.');
+  out('         </p>');
+  out('         <button');
+  out('           type="button"');
+  out('           className="rounded-md border px-3 py-1.5 text-sm"');
+  out('           onClick={() => window.location.reload()}');
+  out('         >');
+  out('           Try again');
+  out('         </button>');
+  out('       </main>');
+  out('     );');
+  out('   }');
+  out('');
+  out(`2. In ${LAYOUT_FILE}, import it (import AuthUnavailable from '@/app/components/auth-unavailable';)`);
+  out('   and replace `const identity = await getSessionIdentity();` with:');
+  out('');
+  out('   let identity: Awaited<ReturnType<typeof getSessionIdentity>> = null;');
+  out('   let authUnavailable = false;');
+  out('   try {');
+  out('     identity = await getSessionIdentity();');
+  out('   } catch (err) {');
+  out("     if (!(err instanceof Error && err.name === 'AuthUnavailableError')) throw err;");
+  out('     authUnavailable = true;');
+  out('   }');
+  out('   if (authUnavailable) {');
+  out('     return (');
+  out("       <html lang=\"en\" style={{ colorScheme: 'light' }}>");
+  out('         <body className="font-sans antialiased">');
+  out('           <AuthUnavailable />');
+  out('         </body>');
+  out('       </html>');
+  out('     );');
+  out('   }');
+  out('');
+  out(`3. Make ${ERROR_BOUNDARY_FILE} render the retry screen on the outage digest. Every page and nested`);
+  out('   layout that throws AuthUnavailableError is then covered without code of its own. If the file');
+  out('   exists, add the first two lines of the component body; otherwise create it:');
+  out('');
+  out("   'use client';");
+  out('');
+  out("   import { AUTH_UNAVAILABLE_DIGEST } from '@assembly-js/app-foundation/client';");
+  out("   import AuthUnavailable from '@/app/components/auth-unavailable';");
+  out('');
+  out('   export default function AppError({');
+  out('     error,');
+  out('     reset,');
+  out('   }: {');
+  out('     error: Error & { digest?: string };');
+  out('     reset: () => void;');
+  out('   }) {');
+  out('     if (error.digest === AUTH_UNAVAILABLE_DIGEST) return <AuthUnavailable />;');
+  out('     return (');
+  out('       <main className="flex min-h-screen flex-col items-center justify-center gap-3 px-4 text-center">');
+  out('         <p className="text-sm text-muted-foreground">Something went wrong.</p>');
+  out('         <button type="button" className="rounded-md border px-3 py-1.5 text-sm" onClick={() => reset()}>');
+  out('           Try again');
+  out('         </button>');
+  out('       </main>');
+  out('     );');
+  out('   }');
+  out('');
+  out('4. Nothing else may swallow the error on its way to that boundary. A page, lib/ helper or route');
+  out('   that catches around getSessionIdentity() (try/catch or a chained .catch()) rethrows it first');
+  out("   (`if (err instanceof Error && err.name === 'AuthUnavailableError') throw err;`); a route handler");
+  out('   that returns handleRouteError(err) from its catch already answers a retryable 503 and needs no change.');
+}
+if (gateVendored) {
+  out('');
+  out(
+    fatal
+      ? `check-identity-outage-states: ${RENEWAL_GATE_FILE} is superseded and must be removed:`
+      : `check-identity-outage-states: ${RENEWAL_GATE_FILE} is superseded (pre-existing; this build is not failed for it):`,
+  );
+  out('');
+  out('@assembly-js/app-foundation bounds session renewal inside reexchangeBearer() since 0.5.3, so the copied');
+  out(`gate only adds a known flaw (it answers false inside its window even after a renewal succeeded).`);
+  out(`Delete ${RENEWAL_GATE_FILE} and ${RENEWAL_GATE_TEST_FILE} if present. In ${CONTEXT_FILE}, change`);
+  out("`await renewOnce()` back to `await reexchangeBearer()` and remove the `createRenewalGate` import and");
+  out('the `renewOnce` constant. Change nothing else in that file.');
+}
 if (fatal) process.exit(1);
 
 function contractChangedThisTurn() {

package/bin/client-safe-sdk-methods.mjs

@@ -14,6 +14,7 @@ export const CLIENT_SAFE_ROUTES = Object.freeze([
   { method: 'POST', path: '/v1/notifications/{id}/read', sdkMethod: 'markNotificationRead' },
   { method: 'POST', path: '/v1/notifications/{id}/unread', sdkMethod: 'markNotificationUnread' },
   { method: 'GET', path: '/v1/session/flags', sdkMethod: null },
+  { method: 'POST', path: '/v1/ai/openai/*proxyPath', sdkMethod: null }, // the AI proxy; reached through `fetch`
 ].map(Object.freeze));
 
 // retrieveClient is allowlisted by name: whether the id is the viewer's own is a runtime
@@ -27,10 +28,15 @@ export const CLIENT_SAFE_SDK_METHODS = Object.freeze(
 // Marked client-safe routes that no SDK method reaches yet.
 export const CLIENT_SAFE_ROUTES_WITHOUT_SDK_METHOD = CLIENT_SAFE_ROUTES.filter((r) => !r.sdkMethod).length;
 
-// `{id}` stands for exactly one non-empty path segment.
+// `{id}` stands for exactly one non-empty path segment; a trailing `*name` stands for the rest of
+// the path, as the platform's wildcard does.
 // The id segment excludes `.` and `%` so `.`, `..` and `%2e` forms that URL normalisation resolves elsewhere fail closed.
-const routePattern = (route) =>
-  new RegExp(`^${route.path.split('/').map((seg) => (seg === '{id}' ? '[A-Za-z0-9_-]+' : seg.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))).join('/')}$`);
+const segmentPattern = (seg) => {
+  if (seg === '{id}') return '[A-Za-z0-9_-]+';
+  if (seg.startsWith('*')) return '.+';
+  return seg.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+};
+const routePattern = (route) => new RegExp(`^${route.path.split('/').map(segmentPattern).join('/')}$`);
 const ROUTE_MATCHERS = CLIENT_SAFE_ROUTES.map((route) => ({ method: route.method, pattern: routePattern(route) }));
 
 // Whether `fetch(path, { method })` hits a client-safe route; `path` has no query string.

package/bin/foundation-exports.mjs

@@ -17,7 +17,7 @@
 // none of them returns one. createAssemblyReexchangeHandler returns a route handler that
 // renews the bearer cookie; it never hands out a client.
 export const NON_CLIENT_EXPORTS = new Set([
-  'APP_CSRF_HEADER', 'AUTH_UNAVAILABLE_CODE', 'ActionContext', 'ActionError',
+  'APP_CSRF_HEADER', 'AUTH_UNAVAILABLE_CODE', 'AUTH_UNAVAILABLE_DIGEST', 'ActionContext', 'ActionError',
   'ActionErrorStatus', 'AirtableFieldSchema', 'AppProxyCaller', 'AppProxyOptions', 'AirtableFormattedField',
   'AirtableFormattedRecord', 'AirtableRecord', 'AirtableSchemaResult', 'AirtableTableSchema',
   'AssemblyProxyForwardContext', 'AssemblyProxyOptions', 'AuthUnavailableError',

package/dist/assembly.d.ts

@@ -34,6 +34,7 @@ export declare class TokenInvalidError extends Error {
  */
 export declare class AuthUnavailableError extends Error {
     readonly code = "AUTH_UNAVAILABLE";
+    readonly digest = "ASSEMBLY_AUTH_UNAVAILABLE";
     constructor(message?: string);
 }
 export declare function getAssembly(input?: AssemblyInput): Promise<AssemblyAPI>;

package/dist/assembly.js

@@ -1,7 +1,7 @@
 import { assemblyApi, OpenAPI } from '@assembly-js/node-sdk';
 import { cookies, headers } from 'next/headers';
 import { after, NextResponse } from 'next/server';
-import { BEARER_COOKIE_NAME, BEARER_HEADER_NAME, decodeBearer, isSessionExchangeEnabled, TOKEN_EXPIRED_HEADER, } from './session-exchange.js';
+import { BEARER_COOKIE_NAME, BEARER_HEADER_NAME, decodeBearer, isSessionExchangeEnabled, TOKEN_EXPIRED_HEADER, AUTH_UNAVAILABLE_DIGEST, } from './session-exchange.js';
 import { mintBearerFromAppKey } from './mint-bearer.js';
 import { verifyBearer } from './verify-bearer.js';
 // Trusted API origin for this stack, supplied by the build environment — NOT by
@@ -149,6 +149,8 @@ export class TokenInvalidError extends Error {
  */
 export class AuthUnavailableError extends Error {
     code = 'AUTH_UNAVAILABLE';
+    // Survives production redaction, unlike name/code: see session-exchange.ts.
+    digest = AUTH_UNAVAILABLE_DIGEST;
     constructor(message = 'Assembly could not verify the session right now') {
         super(message);
         this.name = 'AuthUnavailableError';

package/dist/session-exchange.d.ts

@@ -11,6 +11,7 @@ export declare const COOKIE_PROBE_NAME = "assembly-cookie-probe";
 export declare function serializeCookieProbe(partitioned: boolean, clear?: boolean): string;
 export declare const BEARER_EXPIRY_COOKIE_NAME = "assembly-bearer-exp";
 export declare function serializeBearerExpiryCookie(expiresAtMs: number, maxAgeSeconds: number): string;
+export declare const AUTH_UNAVAILABLE_DIGEST = "ASSEMBLY_AUTH_UNAVAILABLE";
 export declare const TOKEN_EXPIRED_HEADER = "x-assembly-token-expired";
 export declare const EXCHANGE_REJECTION_HEADER = "x-assembly-exchange-rejection";
 export type ExchangeRejectedViewer = 'same_viewer' | 'different_viewer';

package/dist/session-exchange.js

@@ -87,6 +87,11 @@ export function serializeBearerExpiryCookie(expiresAtMs, maxAgeSeconds) {
     const value = maxAgeSeconds > 0 ? String(Math.floor(expiresAtMs / 1_000)) : '';
     return `${BEARER_EXPIRY_COOKIE_NAME}=${value}; Path=/; Secure; SameSite=None; Max-Age=${maxAgeSeconds}; Partitioned`;
 }
+// Digest AuthUnavailableError carries so a client error boundary can recognise
+// an outage. Production redacts a server error's name, code and message before
+// the boundary sees it, but Next keeps a digest the error already has; this is
+// the one field that survives, so app/error.tsx matches on it.
+export const AUTH_UNAVAILABLE_DIGEST = 'ASSEMBLY_AUTH_UNAVAILABLE';
 // Marker header on 401s that mean "the bearer expired — re-exchange and retry",
 // emitted by requireAuth / getAssemblyForRequest / the re-exchange route. Its
 // absence on a denial is what lets authFetch skip renewal for genuine

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assembly-js/app-foundation",
-  "version": "0.5.4",
+  "version": "0.6.1",
   "description": "Versioned foundation helpers and build context for Assembly generated apps",
   "type": "module",
   "files": [