@assembly-js/app-foundation 0.5.2 → 0.5.4

package/CHANGELOG.md

@@ -19,6 +19,12 @@ 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.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.
+
 ## 0.5.2
 - [fix] The builder preview no longer counts a page marked as an error document in its server HTML as the app having painted, even when it streams in before the page finishes hydrating.
 

package/bin/foundation-exports.mjs

@@ -21,7 +21,7 @@ export const NON_CLIENT_EXPORTS = new Set([
   '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/lib-client.d.ts

@@ -1,4 +1,5 @@
 import type { NavigateDestination, NavigateToOptions } from './bridge-vnext.js';
+export declare function resetRenewalStateForTests(): void;
 export declare function reexchangeBearer(): Promise<boolean>;
 export declare function authFetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
 export declare function downloadViaBlob(url: string, filename: string): Promise<void>;
@@ -10,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

@@ -5,7 +5,8 @@
 // never be dragged into the Edge middleware bundle that imports ./client
 // (proxy.ts pulls constants from that barrel).
 import { AssemblyBridge } from '@assembly-js/app-bridge';
-import { APP_CSRF_HEADER, logRenewOutcome, TOKEN_EXPIRED_HEADER, } from './session-exchange.js';
+import { APP_CSRF_HEADER, COOKIE_PROBE_NAME, logRenewOutcome, TOKEN_EXPIRED_HEADER, } from './session-exchange.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:
@@ -13,18 +14,72 @@ const REEXCHANGE_PATH = '/api/assembly-reexchange';
 // once, and uncoordinated renewals would race each other for the token — the
 // first mints the bearer and the losers surface their original 401 even though
 // a valid bearer was just installed. All concurrent callers share this one
-// promise instead; it is cleared on settle so a later expiry renews afresh.
+// promise instead.
 let renewalInFlight = null;
+// After a renewal POST settles, its verdict stands for this long so a burst of
+// 401s (and a failing route that keeps answering 401) costs one mint, not one
+// per response.
+const RENEWAL_WINDOW_MS = 30_000;
+let lastVerdict = null;
+let probeEverSet = false;
+const probeIsSet = () => {
+    const set = readCookie(COOKIE_PROBE_NAME) !== null;
+    if (set)
+        probeEverSet = true;
+    return set;
+};
+// The probe is gone by the time the first 401 triggers a renewal, so it has to
+// be seen while the page still holds a valid bearer: at load and before each
+// request.
+probeIsSet();
+// Test seam: module state otherwise outlives a single test.
+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
+// bearer and is readable from script (the bearer is HttpOnly), so its absence
+// is the only signal that the cached success no longer holds.
+function verdictInWindow() {
+    if (!lastVerdict || Date.now() - lastVerdict.at >= RENEWAL_WINDOW_MS) {
+        return null;
+    }
+    if (lastVerdict.ok && lastVerdict.probeSeen && !probeIsSet())
+        return null;
+    return lastVerdict.ok;
+}
 // Silently renews the bearer cookie after a 60-minute expiry. Asks the bridge
 // for the freshest session token (the parent keeps it alive) and posts it to the
 // re-exchange route, which mints a new bearer and sets the HttpOnly cookie — no
-// page reload. Returns true iff a fresh bearer was set. This is the only place
-// app code touches the raw session token, to re-mint and keep the URL aligned
-// with the cookie; it is never sent to the platform API.
+// page reload. Returns true iff a fresh bearer is in place. Inside the window
+// after a POST it answers from that POST's outcome without sending another, so
+// authFetch gets false for the window after a failed renewal instead of a fresh
+// mint per 401. A no_token outcome sends nothing and starts no window. This is
+// the only place app code touches the raw session token, to re-mint and keep the
+// URL aligned with the cookie; it is never sent to the platform API.
 export function reexchangeBearer() {
     if (renewalInFlight)
         return renewalInFlight;
-    const renewal = renewBearer().finally(() => {
+    probeIsSet();
+    const cached = verdictInWindow();
+    if (cached !== null)
+        return Promise.resolve(cached);
+    const renewal = renewBearer()
+        .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(() => {
         renewalInFlight = null;
     });
     renewalInFlight = renewal;
@@ -52,7 +107,7 @@ async function renewBearer() {
     }
     if (!token) {
         logRenewOutcome('no_token', { bridgeRefreshFailed, cookieless });
-        return false;
+        return { ok: false, sent: false };
     }
     try {
         const res = await fetch(REEXCHANGE_PATH, {
@@ -91,11 +146,11 @@ async function renewBearer() {
                 // A history update failure must not invalidate the cookie just renewed.
             }
         }
-        return res.ok;
+        return { ok: res.ok, sent: true };
     }
     catch {
         logRenewOutcome('unavailable', { bridgeRefreshFailed, cookieless });
-        return false;
+        return { ok: false, sent: true };
     }
 }
 // Whether a denial is worth a renew-and-retry. A 401 is an authentication
@@ -116,6 +171,7 @@ function shouldRenewBearer(res) {
 // once via reexchangeBearer and retries; a genuine forbidden just returns.
 export async function authFetch(input, init) {
     const headers = { ...(init?.headers ?? {}), [APP_CSRF_HEADER]: '1' };
+    probeIsSet();
     const res = await fetch(input, { ...init, headers });
     if (!shouldRenewBearer(res)) {
         return res;
@@ -166,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,8 @@ 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 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,16 @@ 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`;
+}
 // 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.2",
+  "version": "0.5.4",
   "description": "Versioned foundation helpers and build context for Assembly generated apps",
   "type": "module",
   "files": [