@assembly-js/app-foundation 0.5.3 → 0.6.0

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.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.
+
 ## 0.5.3
 - [fix] Sign-in renewal is now bounded to one attempt per 30 seconds per tab, so a burst of expired requests renews once and a late response can no longer undo a fresh renewal.
 

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/foundation-exports.mjs

@@ -17,11 +17,11 @@
 // 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',
-  'BEARER_COOKIE_NAME', 'BEARER_HEADER_NAME', 'BEARER_IN_BODY_HEADER', 'BEARER_TTL_MS',
+  'BEARER_COOKIE_NAME', 'BEARER_EXPIRY_COOKIE_NAME', 'BEARER_HEADER_NAME', 'BEARER_IN_BODY_HEADER', 'BEARER_TTL_MS',
   'CLIENT_BEARER_HEADER', 'CLIENT_FLAGS_COOKIE_NAME', 'COOKIE_OUTCOME_EVENT',
   'COOKIE_PROBE_NAME', 'Caller', 'ClearClientNotificationsInput', 'ClientAccessScope',
   'ConnectionStatus', 'ConnectorError', 'ContractDocumentError', 'ConnectorErrorCode', 'CookieOutcome', 'CronHandler',
@@ -53,9 +53,9 @@ export const NON_CLIENT_EXPORTS = new Set([
   'isValidHexColor', 'listAll', 'logCookieOutcome', 'logFailures', 'logPaintedBeacon',
   'logRenewOutcome', 'makeTestActionContext', 'mintBearerFromAppKey',
   'mintBearerFromSessionToken', 'nextRunAfter', 'normalizeResourcePage', 'notFound', 'notifyInternalUsers',
-  'parseExchangeRejection', 'parseUuid', 'principalKind', 'readCookie', 'recordNetworkCapture',
+  'parseExchangeRejection', 'parseUuid', 'principalKind', 'readBearerExpiry', 'readCookie', 'recordNetworkCapture',
   'redactUrl', 'replaceChildRows', 'requireAuth', 'requireCompanyScope', 'resolveFont',
-  'resolveResource', 'sendThrottled', 'serializeBearerCookie', 'serializeCookieProbe',
+  'resolveResource', 'sendThrottled', 'serializeBearerCookie', 'serializeBearerExpiryCookie', 'serializeCookieProbe',
   'setCookielessBearer', 'slackErrorCode', 'slackFindChannelId', 'slackListChannels',
   'slackPostMessage', 'slackResolveMentions', 'snippetFromRequestBody', 'verifyBearer',
 ]);

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/lib-client.d.ts

@@ -11,6 +11,13 @@ export declare function downloadViaBlob(url: string, filename: string): Promise<
  * Exported for tests; runs once at module load in the browser.
  */
 export declare function bootstrapCookielessBearer(): Promise<boolean>;
+/**
+ * Arms one timer for RENEWAL_LEAD_MS before the expiry in the cookie, replacing
+ * any pending one. Exported for tests; runs at module load and, with
+ * afterRenewal, after every successful renewal.
+ */
+export declare function scheduleProactiveRenewal(afterRenewal?: boolean): void;
+export declare function handleVisibilityChangeForTests(): void;
 /**
  * Returns an onClick handler that navigates the parent Assembly portal to the
  * given typed destination. Use in button or anchor onClick props.

package/dist/lib-client.js

@@ -6,7 +6,7 @@
 // (proxy.ts pulls constants from that barrel).
 import { AssemblyBridge } from '@assembly-js/app-bridge';
 import { APP_CSRF_HEADER, COOKIE_PROBE_NAME, logRenewOutcome, TOKEN_EXPIRED_HEADER, } from './session-exchange.js';
-import { readCookie } from './origin-bootstrap.js';
+import { readBearerExpiry, readCookie } from './origin-bootstrap.js';
 import { cookielessReexchangeHeaders, cookiesAreBlocked, getCookielessBearer, setCookielessBearer, } from './cookieless-bearer.js';
 const REEXCHANGE_PATH = '/api/assembly-reexchange';
 // Single-flight gate for renewals. Session tokens are single-use for exchange:
@@ -37,6 +37,9 @@ export function resetRenewalStateForTests() {
     renewalInFlight = null;
     lastVerdict = null;
     probeEverSet = false;
+    clearProactiveRenewal();
+    scheduledExpiry = null;
+    expiryEverSeen = false;
 }
 // A late 401 response carries the proxy's cookie deletion and can erase the
 // bearer a sibling call just renewed. The probe is cleared together with the
@@ -70,6 +73,10 @@ export function reexchangeBearer() {
         .then(({ ok, sent }) => {
         probeIsSet();
         lastVerdict = sent ? { at: Date.now(), ok, probeSeen: probeEverSet } : null;
+        // The route re-set the expiry cookie, so the next proactive renewal is
+        // timed from it whichever path asked for this one.
+        if (ok)
+            scheduleProactiveRenewal(true);
         return ok;
     })
         .finally(() => {
@@ -215,6 +222,103 @@ export function bootstrapCookielessBearer() {
 // Self-running, mirroring origin-bootstrap: module evaluation precedes
 // hydration, so the bearer is in hand before any component's first fetch.
 void bootstrapCookielessBearer();
+// Proactive renewal. The reactive paths above only mint a bearer after a fetch
+// or action has already failed on its expiry; a server-rendered navigation
+// never fails that way, it renders as no viewer. So a tab that stays open
+// renews shortly before the expiry the proxy mirrors into the client-readable
+// cookie, while it is visible. Without that cookie (an older proxy, the
+// cookieless path) nothing is scheduled and the reactive paths stay the only
+// renewal, as before.
+const RENEWAL_LEAD_MS = 2 * 60_000;
+const MIN_RENEWAL_DELAY_MS = 5_000;
+// A timed renewal that fails (a network blip at minute 58) is retried at this
+// pace until the bearer's expiry passes, so a brief outage inside the lead does
+// not cost the tab its sign-in. Matches the renewal window, so each retry is a
+// real POST rather than the cached verdict.
+const RENEWAL_RETRY_MS = RENEWAL_WINDOW_MS;
+let renewalTimer = null;
+// The expiry the pending (or last fired) timer was taken from, so a successful
+// renewal whose route never refreshed the cookie (a hand-written reexchange
+// route) does not re-arm a timer on the same stale value every few seconds.
+let scheduledExpiry = null;
+// Whether this page has ever read the cookie. Only then can its absence mean
+// the bearer lapsed (a laptop closed past expiry); a proxy that predates the
+// cookie never sets it, and must not be renewed on every tab switch.
+let expiryEverSeen = false;
+function clearProactiveRenewal() {
+    if (renewalTimer !== null)
+        clearTimeout(renewalTimer);
+    renewalTimer = null;
+}
+const tabIsVisible = () => typeof document === 'undefined' || document.visibilityState !== 'hidden';
+/**
+ * Arms one timer for RENEWAL_LEAD_MS before the expiry in the cookie, replacing
+ * any pending one. Exported for tests; runs at module load and, with
+ * afterRenewal, after every successful renewal.
+ */
+export function scheduleProactiveRenewal(afterRenewal = false) {
+    if (typeof window === 'undefined')
+        return;
+    clearProactiveRenewal();
+    const expiresAt = readBearerExpiry();
+    if (expiresAt === null)
+        return;
+    expiryEverSeen = true;
+    if (afterRenewal && expiresAt === scheduledExpiry)
+        return;
+    scheduledExpiry = expiresAt;
+    const delay = Math.max(MIN_RENEWAL_DELAY_MS, expiresAt - RENEWAL_LEAD_MS - Date.now());
+    renewalTimer = setTimeout(renewOnTimer, delay);
+}
+function renewOnTimer() {
+    renewalTimer = null;
+    // A hidden tab has no bridge parent to refresh the session token from and
+    // nothing to render; the visibility handler renews it on return.
+    if (!tabIsVisible())
+        return;
+    void reexchangeBearer().then((renewed) => {
+        // Success re-armed the timer from the refreshed cookie. A failure retries
+        // while the current bearer is still alive; once it has expired the
+        // reactive paths and the visibility handler take over, as before.
+        if (renewed || renewalTimer !== null)
+            return;
+        const expiresAt = readBearerExpiry();
+        // A retry inside the window would only get the cached verdict back.
+        if (expiresAt === null || expiresAt - Date.now() <= RENEWAL_RETRY_MS)
+            return;
+        renewalTimer = setTimeout(renewOnTimer, RENEWAL_RETRY_MS);
+    });
+}
+// A tab that comes back after the lead, or after the cookie itself lapsed, gets
+// a fresh bearer now. The page it shows keeps its stale render until the next
+// navigation, which then lands signed in; forcing a reload is deliberately not
+// done here.
+function renewOnVisible() {
+    if (!tabIsVisible())
+        return;
+    const expiresAt = readBearerExpiry();
+    if (expiresAt === null) {
+        if (expiryEverSeen)
+            void reexchangeBearer();
+        return;
+    }
+    expiryEverSeen = true;
+    if (expiresAt - Date.now() < RENEWAL_LEAD_MS) {
+        void reexchangeBearer();
+    }
+    else if (renewalTimer === null) {
+        scheduleProactiveRenewal();
+    }
+}
+if (typeof window !== 'undefined' && typeof document !== 'undefined') {
+    scheduleProactiveRenewal();
+    document.addEventListener('visibilitychange', renewOnVisible);
+}
+// Test seam for the visibility handler, which is otherwise reachable only
+// through the real document event.
+export function handleVisibilityChangeForTests() {
+    renewOnVisible();
+}
 /**
  * Returns an onClick handler that navigates the parent Assembly portal to the
  * given typed destination. Use in button or anchor onClick props.

package/dist/origin-bootstrap.d.ts

@@ -11,6 +11,12 @@ export declare function readCookie(name: string, cookieString?: string): string
  * Exported so client modules can gate on a flag without re-parsing the cookie.
  */
 export declare function hasClientFlag(key: string, cookieString?: string): boolean;
+/**
+ * When the current bearer expires, as epoch milliseconds, from the cookie the
+ * proxy and the reexchange route mirror beside it. Null when no such cookie is
+ * readable (older proxy, cookieless browser, or already expired).
+ */
+export declare function readBearerExpiry(cookieString?: string): number | null;
 /**
  * Register the workspace's portal origin with the bridge allowlist — from the
  * proxy-set cookie when it is readable, from the framing origin otherwise.

package/dist/origin-bootstrap.js

@@ -20,6 +20,7 @@
 // domains are built into the bridge's defaults). Nothing resolvable → no-op:
 // the app still works on every default-allowlisted surface.
 import { AssemblyBridge } from '@assembly-js/app-bridge';
+import { BEARER_EXPIRY_COOKIE_NAME } from './session-exchange.js';
 export const PORTAL_ORIGIN_COOKIE_NAME = 'assembly-portal-origin';
 // Mirrors the bearer's `flags` claim (see session-exchange.ts's
 // ExchangedSession.flags / hasFlag) — the bearer itself is HttpOnly and
@@ -56,6 +57,18 @@ export function hasClientFlag(key, cookieString) {
         return false;
     return raw.split(',').includes(key);
 }
+/**
+ * When the current bearer expires, as epoch milliseconds, from the cookie the
+ * proxy and the reexchange route mirror beside it. Null when no such cookie is
+ * readable (older proxy, cookieless browser, or already expired).
+ */
+export function readBearerExpiry(cookieString) {
+    const raw = readCookie(BEARER_EXPIRY_COOKIE_NAME, cookieString);
+    if (!raw)
+        return null;
+    const seconds = Number(raw);
+    return Number.isFinite(seconds) && seconds > 0 ? seconds * 1_000 : null;
+}
 /**
  * Framing-origin resolution for when the portal-origin cookie is unreadable: `location.ancestorOrigins`
  * (browser-attested; Chromium/WebKit), falling back to `document.referrer`

package/dist/proxy.js

@@ -5,7 +5,7 @@
 // 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 { APP_CSRF_HEADER, BEARER_COOKIE_NAME, BEARER_HEADER_NAME, CLIENT_BEARER_HEADER, decodeBearer, isDocumentRequest, isSessionExchangeEnabled, logCookieOutcome, serializeBearerCookie, serializeBearerExpiryCookie, 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';
@@ -594,11 +594,13 @@ async function handleRequest(request, options) {
         response.headers.append('Set-Cookie', serializeBearerCookie('', 0, false));
         response.headers.append('Set-Cookie', serializeBearerCookie(newBearer, maxAge, true));
         response.headers.append('Set-Cookie', serializeCookieProbe(true));
+        response.headers.append('Set-Cookie', serializeBearerExpiryCookie(newBearerExpiresAt, maxAge));
     }
     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));
+        response.headers.append('Set-Cookie', serializeBearerExpiryCookie(0, 0));
     }
     else if (bearerCookie && isDocumentRequest(request)) {
         // Refresh the probe on a document served from a live cookie: it outlives the

package/dist/reexchange.js

@@ -2,7 +2,7 @@
 // each app because it is security-critical code an agent must never re-author;
 // an app's route file only calls createAssemblyReexchangeHandler.
 import { NextResponse } from 'next/server';
-import { APP_CSRF_HEADER, BEARER_IN_BODY_HEADER, isSessionExchangeEnabled, serializeBearerCookie, serializeCookieProbe, } from './session-exchange.js';
+import { APP_CSRF_HEADER, BEARER_IN_BODY_HEADER, isSessionExchangeEnabled, serializeBearerCookie, serializeBearerExpiryCookie, serializeCookieProbe, } from './session-exchange.js';
 import { mintBearerFromSessionToken } from './mint-bearer.js';
 // The only header any route may read a session token from.
 const SESSION_TOKEN_HEADER = 'x-assembly-token';
@@ -50,6 +50,8 @@ export function createAssemblyReexchangeHandler() {
         response.headers.append('Set-Cookie', serializeBearerCookie('', 0, false));
         response.headers.append('Set-Cookie', serializeBearerCookie(minted.bearer, maxAge, true));
         response.headers.append('Set-Cookie', serializeCookieProbe(true));
+        // The client schedules its next proactive renewal from this.
+        response.headers.append('Set-Cookie', serializeBearerExpiryCookie(minted.bearerExpiresAt, maxAge));
         return response;
     };
 }

package/dist/session-exchange.d.ts

@@ -9,6 +9,9 @@ export declare const CLIENT_BEARER_HEADER = "x-assembly-client-bearer";
 export declare const BEARER_IN_BODY_HEADER = "x-assembly-bearer-in-body";
 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

@@ -77,6 +77,21 @@ export function serializeCookieProbe(partitioned, clear = false) {
         cookie += '; Partitioned';
     return cookie;
 }
+// Client-readable twin of the bearer's expiry. The bearer is HttpOnly, so this
+// is how the browser learns when to renew it before a server-rendered
+// navigation would find it expired. Epoch seconds, not a secret; written and
+// cleared in lockstep with the bearer, attributes as the other client-readable
+// cookies (Partitioned, no HttpOnly).
+export const BEARER_EXPIRY_COOKIE_NAME = 'assembly-bearer-exp';
+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.3",
+  "version": "0.6.0",
   "description": "Versioned foundation helpers and build context for Assembly generated apps",
   "type": "module",
   "files": [