@assembly-js/app-foundation 0.0.39 → 0.0.40

package/CLAUDE.md

@@ -254,7 +254,7 @@ Two things flow into the running app from Assembly:
 | | Where | Visibility |
 |---|---|---|
 | `ASSEMBLY_API_KEY` | `process.env.ASSEMBLY_API_KEY` | **Server only.** Never expose. Identifies the *app*, not the user. Used by the foundation to mint bearers — you don't touch it. |
-| User bearer | HttpOnly cookie, set by the middleware after the one-time `?token=` exchange | **You never handle it.** `getAssembly()` reads it to act as the current user; `getSessionIdentity()` decodes the viewer. See "How auth works". |
+| User bearer | HttpOnly cookie, set by the middleware after the one-time `?token=` exchange | **You never handle it.** `getAssembly()` reads it to act as the current user; `getSessionIdentity()` returns the viewer the platform verified for it. See "How auth works". |
 
 ---
 
@@ -647,11 +647,11 @@ const assembly = await getAssembly();      // no token — the bearer comes from
 const items = await assembly.listItems({});
 ```
 
-`getAssembly()` is async — always `await` it. If the bearer is missing or expired it throws `TokenInvalidError`; let it propagate, and the client helpers (`useServerAction` / `authFetch`) re-exchange and retry for you.
+`getAssembly()` is async — always `await` it. If the bearer is missing or expired it throws `TokenInvalidError`; let it propagate, and the client helpers (`useServerAction` / `authFetch`) re-exchange and retry for you. If the platform cannot be reached to verify the bearer it throws `AuthUnavailableError` (and `getSessionIdentity()` does too) — a different error on purpose: it is not an expiry, so never catch it into `null`/signed-out and never re-exchange on it; let a route return 503, and render a retry state ("Couldn't load, try again" with a retry button) wherever a server component reads identity.
 
 #### Identity — who is the viewer?
 
-Server-side, `getSessionIdentity()` returns the viewer decoded from the bearer (no token, no API call):
+Server-side, `getSessionIdentity()` returns the viewer the platform verified for the bearer (no token to pass; the check is cached briefly per server instance):
 
 ```ts
 import { getSessionIdentity } from '@assembly-js/app-foundation/server';
@@ -816,7 +816,7 @@ Two pre-built helpers guard API routes that operate on company-scoped resources:
 import { requireAuth, requireCompanyScope } from '@assembly-js/app-foundation/server';
 ```
 
-**`requireAuth(req)`** decodes the viewer's identity from the bearer and returns it. Returns a 401 `NextResponse` with a `{ code: 'token_expired' }` body **and** `x-assembly-token-expired: 1` header when the bearer is missing/expired — `authFetch` detects this and re-exchanges + retries automatically.
+**`requireAuth(req)`** verifies the bearer with the platform and returns the identity from the platform's verification response. Returns a 401 `NextResponse` with a `{ code: 'token_expired' }` body **and** `x-assembly-token-expired: 1` header when the bearer is missing, expired or not accepted — `authFetch` detects this and re-exchanges + retries automatically. When the platform cannot be reached to verify, it returns a 503 with `{ code: 'auth_unavailable' }` and **no** expiry marker, so nothing re-exchanges; the 503 reaches the app, which should render a retry state or let the user retry.
 
 **`requireCompanyScope(identity, resource, assembly?)`** asserts the viewer can access a resource scoped to a company **or to a client**. Internal users always pass (client-vs-staff isolation only — not Client Access; filter app-owned data for limited internal users per `assembly-internal-users`). For a company-scoped resource, client access is checked against `identity.companyId`; when that is absent (a multi-company client not loaded in a CRM tab), pass the bearer client from `getAssemblyForRequest` as the third argument and the helper fetches the client's full `companyIds` list to verify membership. For a **client-scoped resource** (`companyId` null), pass the resource's `clientId` too — `{ companyId: item.companyId, clientId: item.clientId }` — so the owning client passes; without it every client gets a 404, including the one the record is assigned to. Returns `null` on success, or a 403/404 `NextResponse` on mismatch. A 403 from `requireCompanyScope` is a permanent authorization failure — a re-exchange will not fix cross-tenant access. When a row carries **both** scope columns the helper requires both to match, so a client-owned row is never reachable by a sibling client in the same company — see `assembly-route-auth`.
 
@@ -886,7 +886,7 @@ So there is nothing to refresh, subscribe to, or thread. Don't touch `AssemblyBr
 
 Use identity to branch your UI *before* making data calls — don't infer the viewer by catching a 403 (slow, and any unrelated 403 misclassifies).
 
-Server-side (`getSessionIdentity()` decodes the bearer; no API call):
+Server-side (`getSessionIdentity()` returns the platform-verified viewer; no token to pass):
 
 ```ts
 import { getSessionIdentity } from '@assembly-js/app-foundation/server';
@@ -1176,7 +1176,7 @@ Use `AssemblyBridge.header.*` for breadcrumbs, CTAs, and actions menu. See `.cla
 - ❌ Don't make Assembly API calls from client components without a server-side proxy. The apiKey can't leave the server.
 - ❌ Don't reinvent Clients, Companies, or custom fields — they are always available via the SDK. For Messages, Files, Forms, Tasks, Billing, Contracts, Notes, or Knowledge Base: confirm the module is installed (`listAppInstalls`) first; if it is, call the SDK methods listed above rather than rebuilding it. If it is not installed, do not suggest it or plan around it.
 - ❌ Don't use `assembly.clients.list()` — the SDK is flat. Use `assembly.listClients(...)`.
-- ❌ Don't cache decoded payloads for >30s — token rotates every 5 min and the user could be different on the next call (rare, but possible if a session is shared across tabs).
+- ❌ Don't cache a viewer's identity yourself. The foundation already caches the platform's verification for up to 60 seconds per server instance; a longer cache of your own can outlive a session change (a shared session across tabs can switch viewers).
 <!-- !feature:app-owned-header -->
 - ❌ Don't render your own breadcrumbs / titles in the DOM — use `AssemblyBridge.header.*`.
 - ❌ Don't render primary page-level actions (Submit, Save, Edit, Create) as `<Button>` elements inside the page body. These MUST go in the header via the `useAssemblyHeader` hook's `primaryCta`. Contextual inline actions (e.g. row-level edit icons, list "Add item" buttons) may stay in-page. In-page primary CTAs make the UX inconsistent with the rest of the portal. **Exception: the notification surface (`/n`).** The Notification Center renders `/n` in a headerless iframe — `useAssemblyHeader` is ignored. On this surface, primary actions MUST be inline `<Button>` elements.

package/dist/api-errors.js

@@ -1,4 +1,5 @@
 import { NextResponse } from 'next/server';
+import { AuthUnavailableError, authUnavailableResponse } from './assembly.js';
 export function badRequest(message) {
     return NextResponse.json({ error: message }, { status: 400 });
 }
@@ -26,6 +27,10 @@ function isInvalidInputDbError(err) {
 // to the UI when handlers do that.
 export function handleRouteError(err, fallback = 'Something went wrong') {
     console.error(err);
+    // A platform outage is not an app bug; surface it as a retryable 503.
+    if (err instanceof AuthUnavailableError) {
+        return authUnavailableResponse();
+    }
     if (isInvalidInputDbError(err)) {
         return badRequest('Invalid request');
     }

package/dist/assembly.d.ts

@@ -19,6 +19,21 @@ export declare class TokenInvalidError extends Error {
     readonly code = "TOKEN_INVALID";
     constructor(message?: string);
 }
+/**
+ * Thrown when the platform could not be reached to verify the viewer's bearer
+ * (outage, throttle, timeout). It says nothing about the bearer, so it is NOT a
+ * token-invalid error: do not re-exchange on it (that would spend a single-use
+ * session token for nothing) and do not render a signed-out state. Render a
+ * retry state instead. Distinct `name`/`code` from TokenInvalidError on purpose.
+ *
+ * Code you write follows that. The Server Action helper cannot: production redacts
+ * the error across the boundary, so it renews on any failure and instead bounds
+ * how often (one renewal per window per tab).
+ */
+export declare class AuthUnavailableError extends Error {
+    readonly code = "AUTH_UNAVAILABLE";
+    constructor(message?: string);
+}
 export declare function getAssembly(input?: AssemblyInput): Promise<AssemblyAPI>;
 /**
  * Runs `task` after the response is sent (Next's `after()`), with a viewer-
@@ -48,6 +63,8 @@ export declare function getAssembly(input?: AssemblyInput): Promise<AssemblyAPI>
 export declare function afterAssembly(task: (assembly: AssemblyAPI) => Promise<unknown>, options?: {
     token?: string;
 }): void;
+export declare const AUTH_UNAVAILABLE_CODE = "auth_unavailable";
+export declare function authUnavailableResponse(): NextResponse;
 /**
  * OFFLINE / BACKGROUND ONLY — cron jobs, webhook handlers, and any other code
  * path where there is NO user in the loop and thus no session token or bearer

package/dist/assembly.js

@@ -3,33 +3,55 @@ 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 { mintBearerFromAppKey } from './mint-bearer.js';
+import { verifyBearer } from './verify-bearer.js';
 // Trusted API origin for this stack, supplied by the build environment — NOT by
 // a token claim. Empty in prod/shared-staging (the SDK's env default is already
 // correct); set to a per-dev private stack's platform-api URL otherwise. Passed
 // to the SDK as `baseUrl` so tokenless (cookie-only) calls reach the right stack.
 const trustedBaseUrl = process.env.ASSEMBLY_API_BASE_URL || undefined;
-// Reads the viewer bearer for the current request, independent of the exchange
-// flag. First the header the proxy forwards on first load (the exchange just
-// minted it; the Set-Cookie isn't yet visible), then the HttpOnly cookie on every
-// later request. Returns undefined outside a request scope (e.g. build-time
-// prerender) — not an error. Used both to resolve identity and, in
-// getOfflineAssembly, to detect that a viewer is present.
-async function readViewerBearer() {
+// Reads the viewer bearer candidates for the current request, independent of the
+// exchange flag: first the header the proxy forwards on first load (the exchange
+// just minted it; the Set-Cookie isn't yet visible), then the HttpOnly cookie on
+// every later request. Returns [] outside a request scope (e.g. build-time
+// prerender) — not an error.
+async function readBearerCandidates() {
     try {
         const fromProxy = (await headers()).get(BEARER_HEADER_NAME);
-        if (fromProxy && decodeBearer(fromProxy))
-            return fromProxy;
         const fromCookie = (await cookies()).get(BEARER_COOKIE_NAME)?.value;
-        if (fromCookie && decodeBearer(fromCookie))
-            return fromCookie;
+        return [fromProxy, fromCookie].filter((b) => Boolean(b));
     }
     catch {
-        return undefined;
+        return [];
+    }
+}
+// First candidate that survives the no-network precheck, unverified. For callers
+// that only need to carry the credential across a boundary (afterAssembly) and
+// verify it where it is used.
+async function readViewerBearer() {
+    return (await readBearerCandidates()).find((b) => decodeBearer(b));
+}
+// The viewer's bearer together with the identity the platform verified for it.
+// A rejected candidate falls through to the next one, as an undecodable one
+// always did. An unverifiable one stops the walk: it says nothing about the
+// bearer, so the request must neither be treated as signed out nor re-exchanged.
+async function readVerifiedViewer() {
+    for (const bearer of await readBearerCandidates()) {
+        const result = await verifyBearer(bearer);
+        if (result.ok)
+            return { bearer, identity: result.identity };
+        if (result.reason === 'unavailable')
+            throw new AuthUnavailableError();
     }
     return undefined;
 }
-// Viewer bearer for request-scoped auth: only consulted when the exchange flow is
-// on (the legacy path carries identity in proxy headers, not a bearer cookie).
+// Verified viewer for request-scoped auth: only consulted when the exchange flow
+// is on (the legacy path carries identity in proxy headers, not a bearer cookie).
+async function resolveRequestViewer() {
+    if (!isSessionExchangeEnabled())
+        return undefined;
+    return readVerifiedViewer();
+}
+// Unverified bearer for deferred work; see readViewerBearer.
 async function resolveRequestBearer() {
     if (!isSessionExchangeEnabled())
         return undefined;
@@ -64,15 +86,22 @@ async function hasViewerRequest() {
         return false;
     }
 }
-// Server-only: the current user's identity, resolved from the bearer (the
-// proxy-forwarded header on first load, else the HttpOnly cookie). This is how
-// the app learns who the viewer is — workspace, client/company, internal user —
-// without ever handling the raw session token. Used to seed the client provider
-// and by server components. Returns null when unauthenticated or when the
-// exchange is disabled (the legacy path carries identity in proxy headers).
+// Server-only: the current user's identity, verified by the platform for the
+// bearer (the proxy-forwarded header on first load, else the HttpOnly cookie).
+// This is how the app learns who the viewer is — workspace, client/company,
+// internal user — without ever handling the raw session token. Used to seed the
+// client provider and by server components. Returns null when unauthenticated or
+// when the exchange is disabled (the legacy path carries identity in proxy
+// headers). Throws AuthUnavailableError when the platform could not be reached
+// to verify, so a layout can render a retry state rather than a signed-out one.
 export async function getSessionIdentity() {
-    const bearer = await resolveRequestBearer();
-    return bearer ? decodeBearer(bearer) : null;
+    const viewer = await resolveRequestViewer();
+    if (!viewer)
+        return null;
+    // Project to the documented shape so layouts that pass the whole object to a
+    // client provider don't serialize server-side fields to the browser.
+    const { workspaceId, clientId, internalUserId, companyId, notificationId, instanceId, sessionId } = viewer.identity;
+    return { workspaceId, clientId, internalUserId, companyId, notificationId, instanceId, sessionId };
 }
 /**
  * Thrown when a session token is required but missing, or was supplied but
@@ -91,6 +120,24 @@ export class TokenInvalidError extends Error {
         this.name = 'TokenInvalidError';
     }
 }
+/**
+ * Thrown when the platform could not be reached to verify the viewer's bearer
+ * (outage, throttle, timeout). It says nothing about the bearer, so it is NOT a
+ * token-invalid error: do not re-exchange on it (that would spend a single-use
+ * session token for nothing) and do not render a signed-out state. Render a
+ * retry state instead. Distinct `name`/`code` from TokenInvalidError on purpose.
+ *
+ * Code you write follows that. The Server Action helper cannot: production redacts
+ * the error across the boundary, so it renews on any failure and instead bounds
+ * how often (one renewal per window per tab).
+ */
+export class AuthUnavailableError extends Error {
+    code = 'AUTH_UNAVAILABLE';
+    constructor(message = 'Assembly could not verify the session right now') {
+        super(message);
+        this.name = 'AuthUnavailableError';
+    }
+}
 export async function getAssembly(input) {
     const token = typeof input === 'string' ? input : input?.token;
     // Exchange enabled ⇒ this is a bearer-capable app, and it authenticates via
@@ -104,31 +151,25 @@ export async function getAssembly(input) {
     // after() and pass it through explicitly as `input.token`; this honors that
     // pre-resolved bearer instead of re-deriving it from request scope. The
     // common case (no explicit token) is unchanged: derive from the request.
+    // Either way the identity is the one the platform verified for the bearer.
     if (isSessionExchangeEnabled()) {
-        const bearer = token ?? (await resolveRequestBearer());
-        if (!bearer) {
-            throw new TokenInvalidError('Assembly bearer is required');
+        let viewer;
+        if (token) {
+            const result = await verifyBearer(token);
+            if (result.ok) {
+                viewer = { bearer: token, identity: result.identity };
+            }
+            else if (result.reason === 'unavailable') {
+                throw new AuthUnavailableError();
+            }
         }
-        const assembly = await assemblyApi({ bearer, baseUrl: trustedBaseUrl });
-        const payload = await assembly.getTokenPayload?.();
-        if (!payload?.workspaceId) {
-            throw new TokenInvalidError();
+        else {
+            viewer = await resolveRequestViewer();
         }
-        // The published SDK's bearer-mode payload maps only the identity claims,
-        // so overlay the embed-context claims here to keep getTokenPayload()'s
-        // documented contract (payload.notificationId marks the Notification
-        // Center surface) intact for exchange-capable apps. Becomes a harmless
-        // no-op once the SDK maps these claims natively.
-        const session = decodeBearer(bearer);
-        if (session?.notificationId || session?.instanceId) {
-            const merged = {
-                ...payload,
-                notificationId: session.notificationId,
-                instanceId: session.instanceId,
-            };
-            assembly.getTokenPayload = () => Promise.resolve(merged);
+        if (!viewer) {
+            throw new TokenInvalidError(token ? undefined : 'Assembly bearer is required');
         }
-        return assembly;
+        return getBearerAssembly(viewer.bearer, viewer.identity);
     }
     // Exchange disabled (legacy apps built before this feature, or a rollback):
     // the raw session token is the credential and is sent as X-API-Key, exactly
@@ -198,13 +239,35 @@ export function afterAssembly(task, options) {
 function tokenExpiredResponse() {
     return NextResponse.json({ error: 'Unauthorized', code: 'token_expired' }, { status: 401, headers: { [TOKEN_EXPIRED_HEADER]: '1' } });
 }
+export const AUTH_UNAVAILABLE_CODE = 'auth_unavailable';
+// 503 with deliberately NO token-expired marker: the bearer was never judged, so
+// authFetch must not re-exchange (which would spend a single-use session token)
+// and the client should retry the same request instead.
+export function authUnavailableResponse() {
+    return NextResponse.json({ error: 'Service unavailable', code: AUTH_UNAVAILABLE_CODE }, { status: 503 });
+}
 // Builds a bearer-only SDK client. The SDK's native `bearer` option sends
 // Authorization: Bearer on every request — generated service methods and fetch
-// alike — and, with no apiKey supplied, sends NO X-API-Key. Identity comes from
-// the bearer's own signed claims (getTokenPayload() reads them); the API origin
-// comes from the trusted build-env baseUrl, never a token/bearer claim.
-async function getBearerAssembly(bearer) {
-    return assemblyApi({ bearer, baseUrl: trustedBaseUrl });
+// alike — and, with no apiKey supplied, sends NO X-API-Key. The API origin comes
+// from the trusted build-env baseUrl, never a token/bearer claim. When the
+// caller has a verified identity, getTokenPayload() answers with it rather than
+// with the SDK's read of the bearer's claims.
+async function getBearerAssembly(bearer, identity) {
+    const assembly = await assemblyApi({ bearer, baseUrl: trustedBaseUrl });
+    if (identity) {
+        // Includes the embed-context ids the SDK's bearer-mode payload omits, so
+        // payload.notificationId still marks the Notification Center surface.
+        const payload = {
+            workspaceId: identity.workspaceId,
+            clientId: identity.clientId,
+            companyId: identity.companyId,
+            internalUserId: identity.internalUserId,
+            notificationId: identity.notificationId,
+            instanceId: identity.instanceId,
+        };
+        assembly.getTokenPayload = () => Promise.resolve(payload);
+    }
+    return assembly;
 }
 /**
  * OFFLINE / BACKGROUND ONLY — cron jobs, webhook handlers, and any other code
@@ -250,23 +313,30 @@ export async function getOfflineAssembly() {
 }
 // Returns a request-scoped SDK client authenticated for the current user.
 //
-// Exchange enabled: bearer-only. A valid bearer (proxy header or cookie) yields
-// a client that carries Authorization: Bearer on every request; a missing or
-// undecodable bearer yields a 401 NextResponse so the client re-exchanges via
-// the x-assembly-token-expired convention. There is no session-token fallback.
+// Exchange enabled: bearer-only. A bearer the platform verifies (proxy header or
+// cookie) yields a client that carries Authorization: Bearer on every request; a
+// missing or rejected bearer yields a 401 NextResponse so the client re-exchanges
+// via the x-assembly-token-expired convention, and a bearer that could not be
+// verified yields a 503 without that marker. There is no session-token fallback.
 // Exchange disabled: the legacy session-token (X-API-Key) path.
 export async function getAssemblyForRequest(req) {
     if (isSessionExchangeEnabled()) {
         // Bearer-only: the proxy-forwarded header on first load, else the HttpOnly
-        // cookie. Its signed claims carry identity for SDK init. No bearer (or an
-        // undecodable/expired one) ⇒ 401 marker so the client re-exchanges; there
-        // is no X-API-Key / session-token fallback for a bearer-capable app.
+        // cookie. No bearer (or a rejected/expired one) ⇒ 401 marker so the client
+        // re-exchanges; there is no X-API-Key / session-token fallback for a
+        // bearer-capable app.
         const bearer = req.headers.get(BEARER_HEADER_NAME) ??
             req.cookies.get(BEARER_COOKIE_NAME)?.value;
-        if (!bearer || !decodeBearer(bearer)) {
+        if (!bearer) {
             return tokenExpiredResponse();
         }
-        return getBearerAssembly(bearer);
+        const result = await verifyBearer(bearer);
+        if (!result.ok) {
+            return result.reason === 'rejected'
+                ? tokenExpiredResponse()
+                : authUnavailableResponse();
+        }
+        return getBearerAssembly(bearer, result.identity);
     }
     // Legacy (exchange disabled): authenticate from the session-token header,
     // sent as X-API-Key. Missing token ⇒ 401 marker.

package/dist/auth.js

@@ -1,6 +1,7 @@
 import { NextResponse } from 'next/server';
-import { getAssembly } from './assembly.js';
-import { BEARER_COOKIE_NAME, BEARER_HEADER_NAME, decodeBearer, isSessionExchangeEnabled, TOKEN_EXPIRED_HEADER, } from './session-exchange.js';
+import { authUnavailableResponse, getAssembly } from './assembly.js';
+import { BEARER_COOKIE_NAME, BEARER_HEADER_NAME, isSessionExchangeEnabled, TOKEN_EXPIRED_HEADER, } from './session-exchange.js';
+import { verifyBearer } from './verify-bearer.js';
 // Detect an expired/undecryptable-token error from the SDK by shape rather than
 // by importing a concrete class — the foundation builds against whatever SDK
 // version is published, which may not export the error type.
@@ -14,26 +15,35 @@ function tokenExpiredResponse() {
     return NextResponse.json({ error: 'Unauthorized', code: 'token_expired' }, { status: 401, headers: { [TOKEN_EXPIRED_HEADER]: '1' } });
 }
 // Resolves the current viewer's identity for a route handler.
-// Exchange on: bearer-only — decodes the bearer (proxy-forwarded header on first
-// load, else the HttpOnly cookie); a missing/undecodable bearer returns a 401
-// with the x-assembly-token-expired marker so the client re-exchanges. There is
-// no session-token fallback for a bearer-capable app.
+// Exchange on: bearer-only — verifies the bearer with the platform (proxy-
+// forwarded header on first load, else the HttpOnly cookie) and builds the
+// payload from the verified identity, never from the bearer's claims. A
+// missing/rejected bearer returns a 401 with the x-assembly-token-expired marker
+// so the client re-exchanges; a bearer that could not be verified returns a 503
+// without the marker, so nothing re-exchanges. There is no session-token
+// fallback for a bearer-capable app.
 // Exchange off (legacy): reads and decodes the x-assembly-token header.
 export async function requireAuth(req) {
     if (isSessionExchangeEnabled()) {
         const bearer = req.headers.get(BEARER_HEADER_NAME) ??
             req.cookies.get(BEARER_COOKIE_NAME)?.value;
-        const session = bearer ? decodeBearer(bearer) : null;
-        if (!session) {
+        if (!bearer) {
             return tokenExpiredResponse();
         }
+        const result = await verifyBearer(bearer);
+        if (!result.ok) {
+            return result.reason === 'rejected'
+                ? tokenExpiredResponse()
+                : authUnavailableResponse();
+        }
+        const { identity } = result;
         return {
-            workspaceId: session.workspaceId,
-            clientId: session.clientId,
-            internalUserId: session.internalUserId,
-            companyId: session.companyId,
-            notificationId: session.notificationId,
-            instanceId: session.instanceId,
+            workspaceId: identity.workspaceId,
+            clientId: identity.clientId,
+            internalUserId: identity.internalUserId,
+            companyId: identity.companyId,
+            notificationId: identity.notificationId,
+            instanceId: identity.instanceId,
         };
     }
     const token = req.headers.get('x-assembly-token');

package/dist/resource-resolution.d.ts

@@ -86,4 +86,5 @@ export declare class TtlCache<V> {
     constructor(maxEntries: number);
     get(key: string): V | undefined;
     set(key: string, value: V, ttlMs: number): void;
+    delete(key: string): void;
 }

package/dist/resource-resolution.js

@@ -139,4 +139,7 @@ export class TtlCache {
         }
         this.entries.set(key, { value, expiresAt: Date.now() + ttlMs });
     }
+    delete(key) {
+        this.entries.delete(key);
+    }
 }

package/dist/server.d.ts

@@ -3,6 +3,7 @@ export * from './assembly.js';
 export * from './auth.js';
 export * from './client-access.js';
 export * from './mint-bearer.js';
+export * from './verify-bearer.js';
 export * from './nango.js';
 export * from './airtable.js';
 export * from './gmail.js';

package/dist/server.js

@@ -7,6 +7,7 @@ export * from './assembly.js';
 export * from './auth.js';
 export * from './client-access.js';
 export * from './mint-bearer.js';
+export * from './verify-bearer.js';
 export * from './nango.js';
 export * from './airtable.js';
 export * from './gmail.js';

package/dist/session-exchange.js

@@ -1,15 +1,13 @@
 // Stateless bearer helpers for the token-exchange flow (AI-260).
 // The proxy exchanges the session token once and sets the returned bearer as an
 // HttpOnly cookie. That bearer is a signed JWT carrying the caller's identity as
-// claims, so requireAuth()/getAssemblyForRequest() resolve identity by DECODING
-// the cookie — no server-side cache. A cache can't work here anyway: on Vercel
-// the middleware that would populate it and the route handlers that read it run
-// in separate runtimes/instances and never share memory.
+// claims. decodeBearer reads those claims without any network call, so it serves
+// as a cheap precheck (shape, expiry, workspace claim); identity itself comes
+// from verifyBearer, which asks the platform. Each runtime instance verifies a
+// given bearer once per cache window, because on Vercel the middleware and the
+// route handlers run in separate instances that never share memory.
 //
-// decodeBearer does NOT verify the signature. The platform-api authorizer
-// re-validates the token's signature and scope on every real API call, which is
-// the security boundary; these decoded claims are advisory to the app (SDK init,
-// early authz rejects) and never the sole gate.
+// decodeBearer is a no-network shape and expiry precheck.
 export const BEARER_COOKIE_NAME = 'x-assembly-bearer';
 export const BEARER_TTL_MS = 60 * 60 * 1_000; // 60 minutes, matches bearer TTL
 // The only statuses that prove the session token ITSELF is spent or invalid:
@@ -176,11 +174,10 @@ function decodeBase64UrlJson(segment) {
     const bytes = Uint8Array.from(binary, (ch) => ch.charCodeAt(0));
     return JSON.parse(new TextDecoder().decode(bytes));
 }
-// Decodes the identity claims from a bearer JWT. Signature is NOT verified here
-// (the platform-api authorizer re-validates it on every real call — the true
-// boundary); these claims are advisory for SDK init and early authz. Returns
-// null when the token is malformed, expired, or carries no workspace — callers
-// then return 401 / re-exchange.
+// Reads the bearer's claims locally (shape and expiry precheck only). Identity
+// for authorization comes from verifyBearer. Returns null when the token is
+// malformed, expired, or carries no workspace — callers then return 401 /
+// re-exchange.
 export function decodeBearer(bearer) {
     const parts = bearer.split('.');
     if (parts.length !== 3)

package/dist/verify-bearer.d.ts

@@ -0,0 +1,29 @@
+export interface VerifiedIdentity {
+    workspaceId: string;
+    clientId?: string;
+    companyId?: string;
+    internalUserId?: string;
+    notificationId?: string;
+    instanceId?: string;
+    sessionId?: string;
+    callerAppId?: string;
+    installerUserId?: string;
+    tokenKind?: string;
+    /** Epoch SECONDS at which the verified bearer expires. */
+    expiresAt: number;
+}
+export type VerifyResult = {
+    ok: true;
+    identity: VerifiedIdentity;
+} | {
+    ok: false;
+    reason: 'rejected' | 'unavailable';
+};
+export declare const VERIFY_PATH = "/v1/session/verify";
+export declare const VIEWER_BEARER_HEADER = "X-Assembly-Viewer-Bearer";
+export declare const VERIFY_OUTCOME_EVENT = "assembly.verify_outcome";
+/**
+ * Resolves a viewer bearer to the identity the platform vouches for. Identity
+ * must come from here, never from the bearer's decoded claims.
+ */
+export declare function verifyBearer(bearer: string): Promise<VerifyResult>;

package/dist/verify-bearer.js

@@ -0,0 +1,191 @@
+import { OpenAPI } from '@assembly-js/node-sdk';
+import { TtlCache } from './resource-resolution.js';
+import { decodeBearer } from './session-exchange.js';
+export const VERIFY_PATH = '/v1/session/verify';
+export const VIEWER_BEARER_HEADER = 'X-Assembly-Viewer-Bearer';
+export const VERIFY_OUTCOME_EVENT = 'assembly.verify_outcome';
+// A verify sits on every authenticated request's critical path, so it gets far
+// less rope than the exchange.
+const VERIFY_TIMEOUT_MS = 2_000;
+// Bounds how long a verdict can outlive a revocation on this instance.
+const POSITIVE_TTL_MS = 60_000;
+// Short enough that a bearer rejected during a transient state recovers quickly,
+// long enough to absorb a burst of requests carrying the same bad bearer.
+const REJECTED_TTL_MS = 10_000;
+const STALE_GRACE_MS = 5 * 60_000;
+// Separate bounds so rejected entries can never evict positive ones.
+const MAX_POSITIVE_ENTRIES = 1_000;
+const MAX_REJECTED_ENTRIES = 1_000;
+// The only 401 codes that prove the bearer itself is refused; any other 401
+// (a gateway or authorizer response) says nothing about it.
+const REJECTION_CODES = new Set(['invalid_token', 'token_expired']);
+// One cache per runtime instance: instances never share memory, so each
+// verifies a given bearer once per TTL.
+const positiveCache = new TtlCache(MAX_POSITIVE_ENTRIES);
+const rejectedCache = new TtlCache(MAX_REJECTED_ENTRIES);
+// The last verdict the platform gave, kept for a short grace period (never past
+// the bearer's own expiry). Only consulted when the platform cannot be reached,
+// so a blip does not take down viewers it had just vouched for; an explicit
+// rejection evicts it. Bounded tightly because during an outage a revocation
+// cannot be seen.
+const lastGoodCache = new TtlCache(MAX_POSITIVE_ENTRIES);
+const inFlight = new Map();
+// Raw bearers are never held in memory beyond the call; the digest is the key.
+async function hashBearer(bearer) {
+    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(bearer));
+    return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, '0')).join('');
+}
+function optionalString(value) {
+    return typeof value === 'string' && value !== '' ? value : undefined;
+}
+function parseIdentity(body) {
+    if (!body || typeof body !== 'object')
+        return null;
+    const b = body;
+    const workspaceId = optionalString(b.workspaceId);
+    if (!workspaceId)
+        return null;
+    if (typeof b.expiresAt !== 'number' || !Number.isFinite(b.expiresAt)) {
+        return null;
+    }
+    return {
+        workspaceId,
+        clientId: optionalString(b.clientId),
+        companyId: optionalString(b.companyId),
+        internalUserId: optionalString(b.internalUserId),
+        notificationId: optionalString(b.notificationId),
+        instanceId: optionalString(b.instanceId),
+        sessionId: optionalString(b.sessionId),
+        callerAppId: optionalString(b.callerAppId),
+        installerUserId: optionalString(b.installerUserId),
+        tokenKind: optionalString(b.tokenKind),
+        expiresAt: b.expiresAt,
+    };
+}
+function logOutcome(outcome, startedAt) {
+    console.log(JSON.stringify({
+        event_type: VERIFY_OUTCOME_EVENT,
+        outcome,
+        duration_ms: Date.now() - startedAt,
+    }));
+}
+// Callers get a copy so a mutation can never reach the cached identity.
+function frozenOk(identity) {
+    return { ok: true, identity: Object.freeze({ ...identity }) };
+}
+const UNUSABLE = {
+    result: { ok: false, reason: 'unavailable' },
+    platformDown: false,
+};
+const DOWN = {
+    result: { ok: false, reason: 'unavailable' },
+    platformDown: true,
+};
+async function fetchVerdict(bearer) {
+    const apiKey = process.env.ASSEMBLY_API_KEY;
+    if (!apiKey)
+        return UNUSABLE;
+    const base = (process.env.ASSEMBLY_API_BASE_URL || OpenAPI.BASE).replace(/\/$/, '');
+    const headers = {
+        'X-API-Key': apiKey,
+        [VIEWER_BEARER_HEADER]: bearer,
+    };
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), VERIFY_TIMEOUT_MS);
+    try {
+        let resp;
+        try {
+            resp = await fetch(`${base}${VERIFY_PATH}`, {
+                headers,
+                signal: controller.signal,
+            });
+        }
+        catch {
+            // Network failure or the timeout.
+            return DOWN;
+        }
+        if (resp.status >= 500)
+            return DOWN;
+        try {
+            if (resp.status === 200) {
+                const identity = parseIdentity(await resp.json());
+                return identity
+                    ? { result: { ok: true, identity }, platformDown: false }
+                    : UNUSABLE;
+            }
+            if (resp.status === 401) {
+                const body = (await resp.json());
+                if (typeof body?.code === 'string' && REJECTION_CODES.has(body.code)) {
+                    return {
+                        result: { ok: false, reason: 'rejected' },
+                        platformDown: false,
+                    };
+                }
+            }
+        }
+        catch {
+            // A non-JSON body (gateway HTML).
+        }
+        return UNUSABLE;
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+async function verifyUncached(bearer, key, startedAt) {
+    const { result, platformDown } = await fetchVerdict(bearer);
+    if (result.ok) {
+        // Never outlive the bearer itself.
+        const ttl = Math.min(POSITIVE_TTL_MS, result.identity.expiresAt * 1_000 - Date.now());
+        positiveCache.set(key, result.identity, ttl);
+        lastGoodCache.set(key, result.identity, Math.min(STALE_GRACE_MS, result.identity.expiresAt * 1_000 - Date.now()));
+        logOutcome('miss', startedAt);
+        return frozenOk(result.identity);
+    }
+    if (result.reason === 'rejected') {
+        rejectedCache.set(key, true, REJECTED_TTL_MS);
+        lastGoodCache.delete(key);
+    }
+    else if (platformDown) {
+        const lastGood = lastGoodCache.get(key);
+        if (lastGood) {
+            logOutcome('stale', startedAt);
+            return frozenOk(lastGood);
+        }
+    }
+    logOutcome(result.reason, startedAt);
+    return result;
+}
+/**
+ * Resolves a viewer bearer to the identity the platform vouches for. Identity
+ * must come from here, never from the bearer's decoded claims.
+ */
+export async function verifyBearer(bearer) {
+    const startedAt = Date.now();
+    // The decode is a no-network precheck: shape, expiry and workspace claim.
+    if (!decodeBearer(bearer)) {
+        logOutcome('rejected', startedAt);
+        return { ok: false, reason: 'rejected' };
+    }
+    const key = await hashBearer(bearer);
+    const cached = positiveCache.get(key);
+    if (cached && cached.expiresAt * 1_000 > Date.now()) {
+        logOutcome('hit', startedAt);
+        return frozenOk(cached);
+    }
+    if (rejectedCache.get(key)) {
+        logOutcome('rejected', startedAt);
+        return { ok: false, reason: 'rejected' };
+    }
+    // Concurrent requests carrying one bearer share a single platform call.
+    const pending = inFlight.get(key);
+    if (pending) {
+        const shared = await pending;
+        return shared.ok ? frozenOk(shared.identity) : shared;
+    }
+    const request = verifyUncached(bearer, key, startedAt).finally(() => {
+        inFlight.delete(key);
+    });
+    inFlight.set(key, request);
+    return request;
+}

package/package.json

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

package/skills/assembly-automations/SKILL.md

@@ -256,7 +256,7 @@ Every event also lands in the workspace's audit log, where a workspace admin rea
 
 | Header | Value |
 |---|---|
-| `X-Assembly-Actor-Id` | the viewer's id from `requireAuth` — `internalUserId`, else `clientId` |
+| `X-Assembly-Actor-Id` | the viewer's id from `requireAuth` (the platform-verified identity) — `internalUserId`, else `clientId` |
 | `X-Assembly-Source` | `web` when a person did this in the app's UI |
 | `X-Assembly-Client-IP` | the request's `x-forwarded-for` |
 | `X-Assembly-User-Agent` | the request's `user-agent` |

package/skills/assembly-clients-companies/SKILL.md

@@ -14,7 +14,7 @@ const identity = await getSessionIdentity();
 // → { workspaceId, clientId?, companyId?, internalUserId? } | null
 ```
 
-Read identity with `getSessionIdentity()` (server) or `useAssembly()` (client) — see `assembly-session-token`. Never call `assembly.getTokenPayload()` in app code.
+Read identity with `getSessionIdentity()` (server) or `useAssembly()` (client) — see `assembly-session-token`. Never call `assembly.getTokenPayload()` in app code. The identity is the one the platform verified for the bearer, so `clientId` and `companyId` can be trusted for scoping; if verification is unavailable, `getSessionIdentity()` throws `AuthUnavailableError` — render a retry state rather than treating the viewer as signed out.
 
 **A client viewer always carries both ids.** `identity.clientId` is who they are; `identity.companyId` is the company they currently have active in the portal switcher. The platform guarantees the active company is populated for a client session, so **treat a client viewer with no `companyId` as an error, not as a case to fall back on** — do not widen the query to the client's other companies, and do not substitute `companyIds[0]`.
 

package/skills/assembly-route-auth/SKILL.md

@@ -13,7 +13,7 @@ import { requireAuth, requireCompanyScope, handleRouteError } from '@assembly-js
 
 ## How the helpers work
 
-**`requireAuth(req)`** decodes the viewer's identity from the bearer (read from the request cookie — no `x-assembly-token` header) and returns it. Returns a 401 `NextResponse` (with a `{ code: 'token_expired' }` body and an `x-assembly-token-expired: 1` header) when the bearer is missing or expired — `authFetch` detects this and re-exchanges + retries automatically.
+**`requireAuth(req)`** verifies the bearer (read from the request cookie — no `x-assembly-token` header) with the platform and returns the identity from the platform's verification response. Returns a 401 `NextResponse` (with a `{ code: 'token_expired' }` body and an `x-assembly-token-expired: 1` header) when the bearer is missing, expired or not accepted — `authFetch` detects this and re-exchanges + retries automatically. When the platform cannot be reached to verify, it returns a 503 with `{ code: 'auth_unavailable' }` and no expiry marker: return it as is. The 503 reaches the app, which should render a retry state or let the user retry; it never triggers a re-exchange.
 
 **`requireCompanyScope(identity, resource, assembly?)`** asserts the viewer can access a resource scoped to a company **or to a client**:
 

package/skills/assembly-session-token/SKILL.md

@@ -11,7 +11,7 @@ Your job is to follow three rules.
 
 Never decode a token yourself and never call `AssemblyBridge.sessionToken.*` — that API is the foundation's, not yours.
 
-Server-side, `getSessionIdentity()` decodes the viewer from the bearer (no token, no API call). It returns `null` when unauthenticated:
+Server-side, `getSessionIdentity()` returns the viewer the platform verified for the bearer (no token to pass; the check is cached briefly per server instance). It returns `null` when unauthenticated, and throws `AuthUnavailableError` when the platform could not be reached to verify — that is not an expiry, so don't catch it into `null`, don't re-exchange on it, and render a retry state ("Couldn't load, try again" with a retry button) where a server component reads identity:
 
 ```ts
 import { getSessionIdentity } from '@assembly-js/app-foundation/server';