@assembly-js/app-foundation 0.0.37-rc.0 → 0.0.37

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()` returns the viewer the platform verified for it. 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()` decodes the viewer. 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. 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.
+`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.
 
 #### Identity — who is the viewer?
 
-Server-side, `getSessionIdentity()` returns the viewer the platform verified for the bearer (no token to pass; the check is cached briefly per server instance):
+Server-side, `getSessionIdentity()` returns the viewer decoded from the bearer (no token, no API call):
 
 ```ts
 import { getSessionIdentity } from '@assembly-js/app-foundation/server';
@@ -714,9 +714,25 @@ For an imperative one-off (button handler, mutation), use `callAction` from `use
 - **Actions take no token.** Never accept, read, or pass a token — `getAssembly()` resolves the bearer itself. Never touch `AssemblyBridge.sessionToken.*` in a component or copy anything into your own `useState`/`useRef`.
 - **Data actions must let `TokenInvalidError` propagate** — never `try/catch` it into `null`/empty. The auto-retry only fires if the action surfaces the expiry. And never hand-roll refresh/retry; `useServerAction`/`callAction` already do it.
 
+#### Server action or route handler?
+
+A client-to-server call is a server action by default. Its argument is a TypeScript parameter, so a payload that does not match the signature fails `tsc` in your inner loop. A route handler's body is an untyped wire contract — `JSON.stringify` on one side, `request.json()` on the other — and nothing checks that the two agree until a user sends the first request, which you cannot do from the sandbox. A mismatch `tsc` would catch in an action ships silently through a route and 400s for every user.
+
+Write a route handler only when the caller needs a raw `Response` — streamed bytes, a file download, a webhook or cron entry point — or when the caller is not this app's own client component. When you do, define the body schema in a shared `lib/` module with no server-only imports, and type the client's payload with `z.input<typeof schema>` so the compiler checks the wire shape:
+
+```ts
+// lib/reply-contract.ts — imported by both the route and the component (`bun add zod` if it is not installed yet)
+import { z } from 'zod';
+export const replyBody = z.object({ parentId: z.string().uuid().nullish(), text: z.string().min(1) });
+export type ReplyBody = z.input<typeof replyBody>;
+
+// app/api/replies/route.ts: const parsed = replyBody.safeParse(await request.json());
+// component:               const body: ReplyBody = { parentId, text }; // tsc rejects what the route would 400
+```
+
 #### Client → server via route handlers — `authFetch`
 
-For mutations and route-handler calls from client components, use `authFetch` from `app/components/lib-client.ts`. The bearer rides the cookie automatically; `authFetch` adds the required CSRF header and re-exchanges + retries once on a bearer expiry:
+For the route-handler calls that remain, use `authFetch` from `app/components/lib-client.ts`. The bearer rides the cookie automatically; `authFetch` adds the required CSRF header and re-exchanges + retries once on a bearer expiry:
 
 ```tsx
 'use client';
@@ -800,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)`** 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.
+**`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.
 
 **`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`.
 
@@ -870,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()` returns the platform-verified viewer; no token to pass):
+Server-side (`getSessionIdentity()` decodes the bearer; no API call):
 
 ```ts
 import { getSessionIdentity } from '@assembly-js/app-foundation/server';
@@ -1160,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 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).
+- ❌ 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).
 <!-- !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,5 +1,4 @@
 import { NextResponse } from 'next/server';
-import { AuthUnavailableError, authUnavailableResponse } from './assembly.js';
 export function badRequest(message) {
     return NextResponse.json({ error: message }, { status: 400 });
 }
@@ -27,10 +26,6 @@ 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,17 +19,6 @@ 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.
- */
-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-
@@ -59,8 +48,6 @@ 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,55 +3,33 @@ 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 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() {
+// 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() {
     try {
         const fromProxy = (await headers()).get(BEARER_HEADER_NAME);
+        if (fromProxy && decodeBearer(fromProxy))
+            return fromProxy;
         const fromCookie = (await cookies()).get(BEARER_COOKIE_NAME)?.value;
-        return [fromProxy, fromCookie].filter((b) => Boolean(b));
+        if (fromCookie && decodeBearer(fromCookie))
+            return fromCookie;
     }
     catch {
-        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;
     }
     return undefined;
 }
-// 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.
+// 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).
 async function resolveRequestBearer() {
     if (!isSessionExchangeEnabled())
         return undefined;
@@ -86,22 +64,15 @@ async function hasViewerRequest() {
         return false;
     }
 }
-// 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.
+// 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).
 export async function getSessionIdentity() {
-    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 };
+    const bearer = await resolveRequestBearer();
+    return bearer ? decodeBearer(bearer) : null;
 }
 /**
  * Thrown when a session token is required but missing, or was supplied but
@@ -120,20 +91,6 @@ 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.
- */
-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
@@ -147,25 +104,31 @@ 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()) {
-        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 bearer = token ?? (await resolveRequestBearer());
+        if (!bearer) {
+            throw new TokenInvalidError('Assembly bearer is required');
         }
-        else {
-            viewer = await resolveRequestViewer();
+        const assembly = await assemblyApi({ bearer, baseUrl: trustedBaseUrl });
+        const payload = await assembly.getTokenPayload?.();
+        if (!payload?.workspaceId) {
+            throw new TokenInvalidError();
         }
-        if (!viewer) {
-            throw new TokenInvalidError(token ? undefined : 'Assembly bearer is required');
+        // 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);
         }
-        return getBearerAssembly(viewer.bearer, viewer.identity);
+        return assembly;
     }
     // 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
@@ -235,35 +198,13 @@ 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. 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;
+// 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 });
 }
 /**
  * OFFLINE / BACKGROUND ONLY — cron jobs, webhook handlers, and any other code
@@ -309,30 +250,23 @@ export async function getOfflineAssembly() {
 }
 // Returns a request-scoped SDK client authenticated for the current user.
 //
-// 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 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 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. 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.
+        // 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.
         const bearer = req.headers.get(BEARER_HEADER_NAME) ??
             req.cookies.get(BEARER_COOKIE_NAME)?.value;
-        if (!bearer) {
+        if (!bearer || !decodeBearer(bearer)) {
             return tokenExpiredResponse();
         }
-        const result = await verifyBearer(bearer);
-        if (!result.ok) {
-            return result.reason === 'rejected'
-                ? tokenExpiredResponse()
-                : authUnavailableResponse();
-        }
-        return getBearerAssembly(bearer, result.identity);
+        return getBearerAssembly(bearer);
     }
     // Legacy (exchange disabled): authenticate from the session-token header,
     // sent as X-API-Key. Missing token ⇒ 401 marker.

package/dist/auth.js

@@ -1,7 +1,6 @@
 import { NextResponse } from 'next/server';
-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';
+import { getAssembly } from './assembly.js';
+import { BEARER_COOKIE_NAME, BEARER_HEADER_NAME, decodeBearer, isSessionExchangeEnabled, TOKEN_EXPIRED_HEADER, } from './session-exchange.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.
@@ -15,35 +14,26 @@ 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 — 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 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 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;
-        if (!bearer) {
+        const session = bearer ? decodeBearer(bearer) : null;
+        if (!session) {
             return tokenExpiredResponse();
         }
-        const result = await verifyBearer(bearer);
-        if (!result.ok) {
-            return result.reason === 'rejected'
-                ? tokenExpiredResponse()
-                : authUnavailableResponse();
-        }
-        const { identity } = result;
         return {
-            workspaceId: identity.workspaceId,
-            clientId: identity.clientId,
-            internalUserId: identity.internalUserId,
-            companyId: identity.companyId,
-            notificationId: identity.notificationId,
-            instanceId: identity.instanceId,
+            workspaceId: session.workspaceId,
+            clientId: session.clientId,
+            internalUserId: session.internalUserId,
+            companyId: session.companyId,
+            notificationId: session.notificationId,
+            instanceId: session.instanceId,
         };
     }
     const token = req.headers.get('x-assembly-token');

package/dist/replace-rows.js

@@ -33,7 +33,8 @@ async function runStatements(db, statements) {
         return;
     }
     const batch = db.batch;
-    await batch([first, ...rest]);
+    // drizzle's batch reads this.session, so it must be invoked on db, never as a bare function.
+    await batch.call(db, [first, ...rest]);
 }
 export async function replaceChildRows(db, spec) {
     // Ids exist before the delete is built, so a row added in this save is on the keep-list.

package/dist/resource-resolution.d.ts

@@ -86,5 +86,4 @@ 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,7 +139,4 @@ export class TtlCache {
         }
         this.entries.set(key, { value, expiresAt: Date.now() + ttlMs });
     }
-    delete(key) {
-        this.entries.delete(key);
-    }
 }

package/dist/server.d.ts

@@ -3,7 +3,6 @@ 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,7 +7,6 @@ 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,13 +1,15 @@
 // 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. 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.
+// 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.
 //
-// decodeBearer is a no-network shape and expiry precheck.
+// 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.
 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:
@@ -174,10 +176,11 @@ function decodeBase64UrlJson(segment) {
     const bytes = Uint8Array.from(binary, (ch) => ch.charCodeAt(0));
     return JSON.parse(new TextDecoder().decode(bytes));
 }
-// 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.
+// 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.
 export function decodeBearer(bearer) {
     const parts = bearer.split('.');
     if (parts.length !== 3)

package/package.json

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

package/skills/assembly-ai/SKILL.md

@@ -37,25 +37,26 @@ export async function chatCompletion(messages: Array<{ role: string; content: st
 
 ## Server-side only
 
-ALL AI calls MUST happen server-side (API routes, server components, server actions). Never call the AI proxy from client components.
+ALL AI calls MUST happen server-side (server actions, server components, route handlers). Never call the AI proxy from client components.
 
-Example Next.js API route:
+Expose an AI call to the client as a server action — its arguments are type-checked end to end, so a payload mismatch fails `tsc` instead of the user's first request. Reserve a route handler for the streaming case below, where the client needs the raw `Response`.
 
 ```typescript
-// app/api/ai/summarize/route.ts
-import { NextRequest, NextResponse } from 'next/server';
+// app/actions/summarize.ts
+'use server';
 import { chatCompletion } from '@/lib/ai';
 
-export async function POST(request: NextRequest) {
-  const { text } = await request.json();
+export async function summarize(text: string): Promise<string> {
   const response = await chatCompletion([
     { role: 'user', content: `Summarize the following:\n\n${text}` },
   ]);
   const data = await response.json();
-  return NextResponse.json({ summary: data.choices[0].message.content });
+  return data.choices[0].message.content;
 }
 ```
 
+From a client component: `const summary = await callAction(() => summarize(text), { idempotent: true });` — the call writes nothing, so it is safe to re-run after a bearer renewal.
+
 ## Vision (image inputs)
 
 The proxy supports OpenAI's vision API. Use `gpt-4o` with the multi-part content format to analyze images. The `content` field becomes an array of typed parts instead of a plain string:

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` (the platform-verified identity) — `internalUserId`, else `clientId` |
+| `X-Assembly-Actor-Id` | the viewer's id from `requireAuth` — `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. 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.
+Read identity with `getSessionIdentity()` (server) or `useAssembly()` (client) — see `assembly-session-token`. Never call `assembly.getTokenPayload()` in app code.
 
 **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)`** 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.
+**`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.
 
 **`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()` 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:
+Server-side, `getSessionIdentity()` decodes the viewer from the bearer (no token, no API call). It returns `null` when unauthenticated:
 
 ```ts
 import { getSessionIdentity } from '@assembly-js/app-foundation/server';

package/dist/verify-bearer.d.ts

@@ -1,29 +0,0 @@
-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

@@ -1,170 +0,0 @@
-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 }) };
-}
-async function fetchVerdict(bearer) {
-    const apiKey = process.env.ASSEMBLY_API_KEY;
-    if (!apiKey)
-        return { ok: false, reason: 'unavailable' };
-    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 {
-        const resp = await fetch(`${base}${VERIFY_PATH}`, {
-            headers,
-            signal: controller.signal,
-        });
-        if (resp.status === 200) {
-            const identity = parseIdentity(await resp.json());
-            return identity
-                ? { ok: true, identity }
-                : { ok: false, reason: 'unavailable' };
-        }
-        if (resp.status === 401) {
-            const body = (await resp.json());
-            if (typeof body?.code === 'string' && REJECTION_CODES.has(body.code)) {
-                return { ok: false, reason: 'rejected' };
-            }
-        }
-        return { ok: false, reason: 'unavailable' };
-    }
-    catch {
-        // Network failure, timeout, or a non-JSON body (gateway HTML).
-        return { ok: false, reason: 'unavailable' };
-    }
-    finally {
-        clearTimeout(timeoutId);
-    }
-}
-async function verifyUncached(bearer, key, startedAt) {
-    const result = 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 {
-        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;
-}