@assembly-js/app-foundation 0.8.2 → 0.10.0

package/CHANGELOG.md

@@ -19,6 +19,16 @@ 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.10.0
+- [behavior] A call to another app through the installer client or a raw `fetch` to `/v1/apps/...` made inside a client's request now carries that client, so the platform checks the client could open the other app and the other app sees a client whose calling app is this one. A client who cannot open it gets the platform's `viewer_cannot_open_app` refusal as an error value; staff requests, cron, webhooks and queues are unchanged and send no parent.
+- [behavior] A cross-app call from a client's request whose session cannot be verified (exchange off, a rejected header or expired cookie) now throws the token-invalid error instead of running as the installing admin, and a cross-app call where the request cannot be read (`'use cache'`, prerender, `after()`) throws. Storage, connector, notification and AI proxy installer calls are untouched.
+- [action] A route that allows app callers but not clients (`allow: ['app']` or `['internal', 'app']`) now answers 403 to a client-originated installer call, because the person wins over the calling app. Add `'client'` to the list if clients should reach the route, and scope what it returns to that client; `bin/check-app-only-routes.mjs` lists the routes; mark one that should stay app-only with a `check-app-only-routes: intended` comment.
+- [behavior] The action context's `caller.chain` and `caller.hops` now come from the verified bearer instead of a fixed single hop; they are advisory.
+
+## 0.9.0
+- [guidance] The build agent's auth guidance is one `## Auth` section and one `assembly-auth` skill instead of two sections and two skills that retold the same rules: about 3.1k tokens instead of 10k. A page or server action that reads one scoped record now checks it with `requireCompanyScope`, like an `[id]` route.
+- [guidance] `check-token-usage` points at the `assembly-auth` skill.
+
 ## 0.8.2
 - [guidance] The build agent states its reading of an ambiguous rule about money or stored records before building it, asks before writing that reading into live records, and enforces a rule the user has stated instead of warning about it.
 

package/CLAUDE.md

@@ -69,8 +69,7 @@ Assembly-specific gotchas live in `.claude/skills/<name>/SKILL.md`. Invoke them
 - `assembly-workspace-labels` — workspace-customized display labels for clients/companies. The server helper comes from `@assembly-js/app-foundation/server`, the `useLabels()` hook from the repo — import them, don't rewrite them.
 - `assembly-db-transactions` — REQUIRED when a route makes more than one DB write: `db.transaction()` is unsupported on neon-http and 500s. Use `db.batch([...])` for atomic multi-writes, sequential awaits otherwise.
 - `assembly-record-writes` — REQUIRED when a form creates a record that a later save also writes, especially with nested rows (packages, add-ons, line items, blocks): create and save call one writer so create cannot drop submitted fields.
-- `assembly-session-token` — the bearer lifecycle and how to read identity or fetch data: `getSessionIdentity()`/`useAssembly()`, `useServerAction`/`callAction`, `authFetch`. You never handle a token yourself.
-- `assembly-route-auth` — REQUIRED on every `app/api/.../[id]/route.ts` handler: `requireAuth` + `requireCompanyScope` before returning or mutating data.
+- `assembly-auth` — REQUIRED before writing any `app/api` route, server action or client call to the server: `requireAuth` → `requireCompanyScope` → `handleRouteError` on every `[id]` handler (GET included), `getAssemblyForRequest`, `useServerAction`/`callAction`/`authFetch`, the offline bearer. You never handle a token yourself.
 - `assembly-scheduled-work` — REQUIRED when the prompt implies anything on a schedule or while nobody has the app open (remind, daily digest, every week, follow up in N days, at a specific time): one `*/30 * * * *` Vercel cron in `vercel.json` hitting one dispatcher route, every scheduled action a row in a schedule table, `CRON_SECRET` declared in `requiredSecrets` and verified on every tick, `getOfflineAssembly()` for platform calls. Checking for due work on page load ships a schedule that never fires.
 - `assembly-route-errors` — REQUIRED in every route handler: use `handleRouteError` from `@assembly-js/app-foundation/server` in catch blocks — never return `err.message`. Validate values before they hit typed DB columns (e.g. `parseUuid` before a uuid-column lookup).
 - `assembly-api-contract` — REQUIRED whenever an `app/api` route is added, removed, or changes its request or response shape: keep `.assembly/openapi.json` (OpenAPI 3.1, `servers: [{"url": "/api"}]`, paths without the `/api` prefix) in step; cron, webhook, `assembly-*` and `privateRoutes` routes stay out.
@@ -525,7 +524,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()` returns the viewer the platform verified for it. See "Auth". |
 
 ---
 
@@ -915,315 +914,29 @@ export async function GET(request: NextRequest) {
 }
 ```
 
-## How auth works — read this first (it's automatic, and not what you'd guess)
+## Auth — automatic; read the `assembly-auth` skill before writing any route, server action or client call
 
-Your app authenticates every API call with a short-lived, user-scoped **bearer token**. You never handle the raw session token and you never pass a token to anything — the foundation manages the whole lifecycle:
+The foundation runs the whole session; you write none of it:
 
-1. **On the first load only**, the parent opens your app at `…/?token=<session-token>`.
-2. The foundation middleware (`proxy.ts`) **exchanges that session token exactly once** for a bearer: it calls `POST /v1/session` server-side and stores the returned bearer in an HttpOnly, `SameSite=None` cookie. This mint is the only time the session token is ever used.
-3. Every server call your app makes uses that bearer. `getAssembly()` reads the cookie and returns an authenticated client; the platform validates the bearer on each call.
-4. The bearer lasts 60 minutes. When it expires, `authFetch` and `useServerAction` **silently re-exchange** (mint a fresh bearer from the parent's current session token via `/api/assembly-reexchange`) and retry — no page reload, no code from you.
+- The parent opens your app **once** at `…/?token=<session-token>`; the middleware (`proxy.ts`) exchanges it at `POST /v1/session` for a 60-minute, user-scoped **bearer** in an HttpOnly cookie. That mint is the only use of the session token.
+- Every server call reads the bearer from the cookie. Nothing takes a token argument: not `getAssembly()`, not a server action, not a route handler.
+- On expiry, `useServerAction`, `callAction` and `authFetch` silently re-exchange through `/api/assembly-reexchange` and retry. Nothing to refresh, subscribe to or reload; a "people get logged out" request needs no code.
+- So: never read `searchParams.token`, never put `?token=` in a `<Link>`/`router.push`, never store or decode a token, never touch `AssemblyBridge.sessionToken.*`, never set an auth cookie, never hand-roll refresh or retry, never call `assemblyApi` or authenticate on the client.
+- Data actions let `TokenInvalidError` propagate (the retry fires only if the expiry surfaces). `AuthUnavailableError` means the platform couldn't verify the bearer: not an expiry, so never catch it into `null`; render a retry state.
 
-Internalize these consequences — they are exactly what generated apps get wrong:
-- **Never read `searchParams.token`, never put `?token=` in a `<Link>`/`router.push`, never store a token.** By the time your code runs the bearer is already in the cookie; the URL token is the middleware's business, not yours. Inner pages need nothing from the URL to be authenticated.
-- **Never pass a token to any function.** `getAssembly()`, server actions, and route handlers all take **no** token argument.
-- **Never call `assemblyApi` yourself, and never authenticate on the client.** Every API call is server-side through `getAssembly()` / `getAssemblyForRequest()`.
+**Which client.** `getAssembly` and its siblings come from `@assembly-js/app-foundation/server` (a `'use client'` module imports only from `/client`); import them, never edit or reimplement them.
 
-Every authenticated call your app makes is one of exactly three kinds:
-1. **User bearer** — the default. `getAssembly()` acts as the current viewer. Use it for anything shown to or done for the person using the app.
-2. **Installer client** — `getInstallerAssembly()`, allowed inside a user request. Use it for staff-wide reads and writes the app is entitled to on its own, including notification helpers, app storage and connectors. It acts as the installing admin, so filter anything from it before showing it to a client. A viewer cookie does not make it refuse; `getOfflineAssembly()` does.
-3. **Offline bearer** — for background work with no user in the loop (cron, webhooks). Call `getOfflineAssembly()` (see "Offline bearer" below); it mints an app-scoped bearer from your API key server-side. Only needed outside a request; it refuses when a viewer is present.
+- `getAssembly()` — the viewer, in server components and server actions. The default for anything shown to or done for the person using the app.
+- `getAssemblyForRequest(request)` — the viewer, in a route handler; returns the client or a 401 to return as is.
+- `getInstallerAssembly()` — the installing admin, inside a user request, for staff-wide reads and writes the app is entitled to on its own (notification helpers, app storage, connectors). Filter what it returns before showing it to a client.
+- `getOfflineAssembly()` — no viewer at all (cron, webhooks): an app-scoped bearer minted from `ASSEMBLY_API_KEY`. It refuses inside a viewer request.
 
-### `getAssembly()` — the only auth helper you need
+**Identity.** Branch on who the viewer is before making data calls, never by catching a 403: server-side `const id = await getSessionIdentity()` (`{ workspaceId, internalUserId?, clientId?, companyId? } | null`), client-side `useAssembly()` (`isClient`, `internalUserId`, `clientId`, seeded from the server, no loading state). A client may read only its own record and its active company.
 
-`getAssembly` comes from `@assembly-js/app-foundation/server`, an installed dependency — import from it, never edit or reimplement it. (Its `/client` subpath is the subset a `'use client'` module may import; `/server` covers everything server-side.) Call `getAssembly()` with **no arguments** anywhere server-side (server component, server action, route handler). It reads the bearer for the current request and returns an authenticated, per-request client:
-
-```ts
-import { getAssembly } from '@assembly-js/app-foundation/server';
-
-const assembly = await getAssembly();      // no token — the bearer comes from the cookie
-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.
-
-### 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):
-
-```ts
-import { getSessionIdentity } from '@assembly-js/app-foundation/server';
-
-const id = await getSessionIdentity();
-// { workspaceId, clientId?, companyId?, internalUserId? } | null
-if (id?.internalUserId) {
-  // internal staff — render the staff view
-} else if (id?.clientId) {
-  // client user — render their own view
-}
-```
-
-Client-side, `useAssembly()` exposes the same identity, seeded from the server — **no token, no loading state**:
-
-```tsx
-'use client';
-import { useAssembly } from '@/app/components/assembly-context';
-
-export default function MyWidget() {
-  const { workspaceId, clientId, internalUserId, isClient } = useAssembly();
-  return <div>{isClient ? 'Client view' : 'Staff view'}</div>;
-}
-```
-
-Branch your UI on identity **before** making data calls — it's faster and more reliable than catching a 403.
-
-### Fetching data — server actions via `useServerAction`
-
-Put SDK calls in `'use server'` actions that take **no token** and call `getAssembly()`. From the client, run them through `useServerAction` (`app/components/use-server-action.ts`) — it manages loading/error state and **silently re-exchanges + retries once** on a 60-minute bearer expiry, so you never write refresh logic:
-
-```ts
-// app/actions/items.ts
-'use server';
-import { getAssembly } from '@assembly-js/app-foundation/server';
-
-export async function loadItems() {
-  const assembly = await getAssembly(); // throws TokenInvalidError if the bearer is gone
-  return assembly.listItems({});
-}
-```
-
-```tsx
-// app/components/my-widget.tsx
-'use client';
-import { useServerAction } from '@/app/components/use-server-action';
-import { loadItems } from '@/app/actions/items';
-
-export default function MyWidget() {
-  const { data: items, isLoading, error, reload } = useServerAction(() => loadItems(), []);
-  // `deps` ([]) works like useEffect deps — list anything the action closes over.
-  // Deps must be primitives (an id, a cursor, `items.length`). A derived array or
-  // object is a new identity every render and spins the page in a fetch loop.
-}
-```
-
-For an imperative one-off (button handler, mutation), use `callAction` from `useAssembly()` — same silent re-exchange + retry, no hook: `await callAction(() => updateItem(values))`.
-
-**Two hard rules** (this is exactly what generated apps get wrong):
-- **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 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';
-import { authFetch } from '@/app/components/lib-client';
-
-async function saveFlavor(clientId: string, flavor: string) {
-  const res = await authFetch(`/api/clients/${clientId}/flavor`, {
-    method: 'PATCH',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ flavor }),
-  });
-  if (!res.ok) throw new Error(await res.text());
-  return res.json();
-}
-```
-
-Every state-changing request (POST/PUT/PATCH/DELETE) **must** go through `authFetch` (or a Next server action) — a plain `fetch` is rejected with 403 (CSRF). Never put a token or the bearer in a URL or a manual header; the cookie carries it.
-
-In current apps `proxy.ts` lets a request that carries no cookies skip the CSRF check, so an inbound third-party call (a webhook) needs no proxy change; an older `proxy.ts` without that rule still answers 403 to a header-less POST. Authenticate the caller inside the route (signature or shared secret), fail closed when its secret is unset, and never add an unauthenticated test endpoint.
-
-### Route handlers — `getAssemblyForRequest`
-
-```ts
-// app/api/clients/[clientId]/flavor/route.ts
-import { NextRequest, NextResponse } from 'next/server';
-import { getAssemblyForRequest } from '@assembly-js/app-foundation/server';
-
-export async function PATCH(
-  request: NextRequest,
-  { params }: { params: Promise<{ clientId: string }> },
-) {
-  const { clientId } = await params;
-  const assembly = await getAssemblyForRequest(request);
-  if (assembly instanceof NextResponse) return assembly; // 401 → authFetch re-exchanges
-
-  const { flavor } = await request.json();
-  await assembly.updateClient({
-    id: clientId,
-    requestBody: {
-      customFields: { pizza_flavor: flavor },
-    },
-  });
-  return NextResponse.json({ ok: true });
-}
-```
-
-`getAssemblyForRequest(req)` returns a bearer-authenticated client, or a 401 `NextResponse` (carrying the `x-assembly-token-expired` marker) when the bearer is missing/expired — just return it, and `authFetch` re-exchanges and retries. For an identity-only check use `requireAuth(req)` (below).
-
-**Auth is entirely cookie-borne: no `?token=`, no `x-assembly-token` header, no token proxy, no `TokenLink`/`useWithToken`, no client-side token at all.** The middleware put the bearer in the cookie; `getAssembly()` / `getAssemblyForRequest()` read it. That's the whole story.
+**Scoped records.** Anything that loads one record by id for a client — a route handler, a page, a server action — checks it with `requireCompanyScope(identity, { companyId: row.companyId, clientId: row.clientId }, assembly)` and returns or renders "not found" on a non-null result. Never compare company or client ids by hand: the helper handles multi-company clients and client-owned rows. Every `app/api/.../[id]/route.ts` handler, GET included, runs `requireAuth` → `requireCompanyScope` → `handleRouteError`; the recipe is in `assembly-auth`.
 
 **Never add a route that skips the session check, and never loosen one.** Every handler under `app/api` that a viewer calls uses `requireAuth(…)` or `getAssemblyForRequest(…)`; a cron or webhook route has no viewer and verifies its own secret instead (below). The rule covers a route gated on `NODE_ENV`, a `DEBUG` or `SKIP_AUTH` flag, a secret path or `localhost`, and a route you mean to delete later: every preview deployment is reachable by anyone with its URL, so a dev-only route is a public one. It holds when the user asks for it ("just for now", "so I can test it"). You cannot sign in as staff or as a client from the sandbox, and a test route cannot make that possible either; say that you can't verify the page end to end from here, keep the guard, and test the handler's logic by calling its function with a plain argument. Never build a session, token or cookie yourself to get past a check.
 
-### Offline bearer — background work with no user (cron, webhooks)
-
-**Anything on a schedule — a reminder, a digest, a recurring send — must first read the `assembly-scheduled-work` skill.** The route below only ever runs if `vercel.json` declares a cron for it and the route verifies `CRON_SECRET`; the offline bearer is the auth half, the skill is the scheduling half.
-
-Everything above resolves the **viewer's** bearer from the request cookie. Some code runs with **no user in the loop and no cookie**: a scheduled job, or an incoming third-party webhook. There, call `getOfflineAssembly()` — it mints a short-lived, **app-scoped** bearer from your app API key (`ASSEMBLY_API_KEY`) via `POST /v1/token` and returns a bearer-only client, exactly like the user path but authenticated as the app rather than a viewer.
-
-```ts
-// app/api/cron/digest/route.ts — Vercel cron or a webhook handler
-import { getOfflineAssembly, listAll } from '@assembly-js/app-foundation/server';
-
-export async function GET() {
-  const assembly = await getOfflineAssembly(); // app-scoped, no cookie needed
-  // Background work must cover everyone — walk every page (see Pagination).
-  const clients = await listAll((nextToken) =>
-    assembly.listClients({ nextToken, limit: 100 }),
-  );
-  // …do the background work (send a digest, reconcile state, etc.)…
-  return Response.json({ ok: true });
-}
-```
-
-Rules for the offline path:
-- **Use it ONLY when there is genuinely no user.** Any request a person triggered — a page, a server action, an `authFetch` route — uses `getAssembly()` / `getAssemblyForRequest()` so the call acts as that viewer. Reaching for the offline bearer inside a user request bypasses the viewer's scope.
-- **It throws on failure** (missing `ASSEMBLY_API_KEY`, or a failed mint) rather than returning null — there is no client to re-exchange in the background, so a missing credential must be loud. Let it propagate; don't swallow it into a partial run.
-- **`getSessionIdentity()` returns `null`** here — the bearer is the app, not a person. Anything that needs a user id (e.g. a notification `senderId`) must be chosen explicitly (a system/admin internal user), not read from identity.
-- Still bearer-only: no `?token=`, no `x-assembly-token`, no X-API-Key on data calls. The app key is used solely to mint the bearer.
-
-### Auth guards for `[id]`-nested routes — `requireAuth` and `requireCompanyScope`
-
-Two pre-built helpers guard API routes that operate on company-scoped resources:
-
-```ts
-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.
-
-**`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`.
-
-```ts
-// app/api/items/[id]/route.ts
-import { NextRequest, NextResponse } from 'next/server';
-import {
-  requireAuth,
-  requireCompanyScope,
-  getAssemblyForRequest,
-  handleRouteError,
-  parseUuid,
-} from '@assembly-js/app-foundation/server';
-import { db } from '@/lib/db';
-import { items } from '@/lib/schema';
-import { eq } from 'drizzle-orm';
-
-export async function GET(
-  request: NextRequest,
-  { params }: { params: Promise<{ id: string }> },
-) {
-  const auth = await requireAuth(request);
-  if (auth instanceof NextResponse) return auth;
-
-  const { id: rawId } = await params;
-  // items.id is uuid — validate at the lookup, not because the segment is named [id]
-  const id = parseUuid(rawId);
-  if (id instanceof NextResponse) return id;
-
-  try {
-    const item = await db.query.items.findFirst({ where: eq(items.id, id) });
-    if (!item) return NextResponse.json({ error: 'Not found' }, { status: 404 });
-
-    // Only needed for the multi-company membership check; omit otherwise.
-    const assembly = await getAssemblyForRequest(request);
-    if (assembly instanceof NextResponse) return assembly;
-    // Pass both scope columns — clientId is what lets a client-scoped row
-    // (companyId null) pass for its owning client.
-    const scopeError = await requireCompanyScope(
-      auth,
-      { companyId: item.companyId, clientId: item.clientId },
-      assembly,
-    );
-    if (scopeError) return scopeError;
-
-    return NextResponse.json(item);
-  } catch (err) {
-    return handleRouteError(err);
-  }
-}
-```
-
----
-
-## Session & bearer lifecycle (under the hood — you write none of it)
-
-You don't manage sessions; the foundation does. This is the flow so you understand where auth comes from:
-
-- The parent opens your app with `?token=<session-token>` **once** (5-minute TTL, encrypted, rotated by the parent).
-- The middleware exchanges it at `POST /v1/session` for a **60-minute user-scoped bearer** and stores it in an HttpOnly cookie. The session token is used only for this mint.
-- Every server call uses the bearer; `getAssembly()` reads the cookie.
-- On bearer expiry, `authFetch` / `useServerAction` post the parent's current session token to `/api/assembly-reexchange`, which mints a fresh bearer and updates the cookie — then retries. Silent; no reload.
-
-So there is nothing to refresh, subscribe to, or thread. Don't touch `AssemblyBridge.sessionToken.*`, don't read `searchParams.token`, don't decode anything client-side.
-
-### Identify the viewer
-
-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):
-
-```ts
-import { getSessionIdentity } from '@assembly-js/app-foundation/server';
-
-const id = await getSessionIdentity();
-// { workspaceId, internalUserId?, clientId?, companyId? } | null
-if (id?.internalUserId) {
-  // internal staff — render the staff view (lists, tables, admin actions)
-} else if (id?.clientId) {
-  // client user — render their own view (profile / settings)
-} else {
-  // no session — render an unauthenticated state
-}
-```
-
-Client-side, the same fields come from `useAssembly()` (seeded from the server, no token). If you also need the full record (a client may read only its own record and its active company, `id.companyId`; any other company id is refused):
-
-```ts
-const assembly = await getAssembly();
-const id = await getSessionIdentity();
-
-if (id?.internalUserId) {
-  const me = await assembly.retrieveInternalUser({ id: id.internalUserId });
-  return { type: 'internal' as const, user: me };
-}
-if (id?.clientId) {
-  const me = await assembly.retrieveClient({ id: id.clientId });
-  const company = id.companyId
-    ? await assembly.retrieveCompany({ id: id.companyId })
-    : null;
-  return { type: 'client' as const, user: me, company };
-}
-return { type: 'app' as const };
-```
-
 ---
 
 ## Server-side SDK: `@assembly-js/node-sdk`
@@ -1467,7 +1180,7 @@ Use `AssemblyBridge.header.*` for breadcrumbs, CTAs, and actions menu. See `.cla
 
 ### Session token — the foundation uses this, not you
 
-`AssemblyBridge.sessionToken.*` exists, but **your app never calls it.** The foundation reads it internally to mint/re-exchange the bearer (see "Session & bearer lifecycle"). Authenticate with `getAssembly()` / `getAssemblyForRequest()`; identify the viewer with `getSessionIdentity()` / `useAssembly()`.
+`AssemblyBridge.sessionToken.*` exists, but **your app never calls it.** The foundation reads it internally to mint/re-exchange the bearer (see "Auth"). Authenticate with `getAssembly()` / `getAssemblyForRequest()`; identify the viewer with `getSessionIdentity()` / `useAssembly()`.
 
 ---
 

package/bin/check-app-only-routes.mjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+// Flags routes whose allow list admits app callers but not clients. A client who
+// reaches this app through another app's installer call carries the client, and
+// a person wins over a calling app, so such a route now answers 403 to that
+// call. Dependency-free on purpose: it runs inside the generated app's sandbox
+// before any deps beyond Node exist.
+//
+// A route that should stay app-only says so with a comment on the list's line or
+// the line above, `check-app-only-routes: intended`, and passes.
+//
+// A hit is a warning on an ordinary turn and fails the build with --strict (the
+// update acceptance), on a platform update turn, or when
+// ASSEMBLY_TURN_BASELINE_SHA says this turn changed the file. An app with no
+// such list passes.
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { join, relative } from 'node:path';
+
+const ROOT = process.cwd();
+const STRICT = process.argv.includes('--strict') || process.env.ASSEMBLY_UPDATE_TURN === '1';
+const TURN_BASELINE_ENV = 'ASSEMBLY_TURN_BASELINE_SHA';
+
+// Route code lives under app/ and shared auth wrappers under lib/.
+const SCAN_DIRS = ['app', 'lib'];
+const SOURCE_FILE = /\.(ts|tsx|js|jsx|mjs)$/;
+const SKIP_DIRS = new Set(['node_modules', '.next', '.git', 'generated']);
+const ALLOW_LIST = /\ballow\s*:\s*\[([^\]]*)\]/g;
+const ENTRY = /['"`]([a-z]+)['"`]/g;
+const LINE_COMMENT = /^\s*\/\//;
+const ACKNOWLEDGED = /check-app-only-routes:\s*intended/;
+
+function appOnlyAllowLists(source) {
+  // Whole-line comments only: stripping a trailing `//` would eat the `//` in a URL.
+  const code = source
+    .split('\n')
+    .map((line) => (LINE_COMMENT.test(line) ? '' : line))
+    .join('\n');
+  const lines = source.split('\n');
+  const hits = [];
+  for (const match of code.matchAll(ALLOW_LIST)) {
+    const kinds = [...match[1].matchAll(ENTRY)].map((m) => m[1]);
+    if (kinds.includes('app') && !kinds.includes('client')) {
+      const line = code.slice(0, match.index).split('\n').length;
+      if (ACKNOWLEDGED.test(`${lines[line - 2] ?? ''}\n${lines[line - 1] ?? ''}`)) continue;
+      hits.push({ list: match[0].replace(/\s+/g, ' '), line });
+    }
+  }
+  return hits;
+}
+
+function* sourceFiles(dir) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (!SKIP_DIRS.has(entry.name)) yield* sourceFiles(join(dir, entry.name));
+    } else if (SOURCE_FILE.test(entry.name)) {
+      yield join(dir, entry.name);
+    }
+  }
+}
+
+function changedFiles() {
+  const baseline = (process.env[TURN_BASELINE_ENV] ?? '').trim();
+  if (!baseline) return new Set();
+  const listings = [
+    { args: ['diff', '--name-only', `${baseline}..HEAD`], parse: (line) => line },
+    { args: ['status', '--porcelain', '--untracked-files=all'], parse: (line) => line.slice(3).split(' -> ').pop() },
+  ];
+  const changed = new Set();
+  for (const { args, parse } of listings) {
+    const result = spawnSync('git', args, { cwd: ROOT, encoding: 'utf8' });
+    // Cannot tell what changed: treat every file as changed rather than pass quietly.
+    if (result.status !== 0) return null;
+    for (const line of result.stdout.split('\n')) changed.add(parse(line).trim());
+  }
+  return changed;
+}
+
+const findings = [];
+for (const dir of SCAN_DIRS) {
+  if (!existsSync(join(ROOT, dir))) continue;
+  for (const file of sourceFiles(join(ROOT, dir))) {
+    const hits = appOnlyAllowLists(readFileSync(file, 'utf8'));
+    for (const hit of hits) findings.push({ file: relative(ROOT, file), ...hit });
+  }
+}
+if (findings.length === 0) process.exit(0);
+
+const changed = changedFiles();
+const fatal = STRICT || changed === null || findings.some((f) => changed.has(f.file));
+const out = fatal ? console.error : console.warn;
+out('');
+out(
+  fatal
+    ? 'check-app-only-routes: these allow lists admit app callers but not clients:'
+    : 'check-app-only-routes: these allow lists admit app callers but not clients (pre-existing; this build is not failed for them):',
+);
+out('');
+for (const f of findings) out(`  ${f.file}:${f.line}  ${f.list}`);
+out('');
+out('A client who reaches this app through another app now arrives as that client, and a person');
+out('wins over a calling app, so a route that omits `client` answers 403 to the call. If clients');
+out("may reach the route, add 'client' to the list and scope what it returns to that client;");
+out('if only the app should reach it, add a comment `check-app-only-routes: intended` on the list or the line above.');
+if (fatal) process.exit(1);

package/bin/check-token-usage.mjs

@@ -154,6 +154,6 @@ if (violations.length > 0) {
   console.error('entry page, should read searchParams.token. getAssembly() and');
   console.error('getSessionIdentity() read the bearer cookie; fetch per-user data via');
   console.error('server actions (useServerAction) or authFetch route handlers.');
-  console.error('See CLAUDE.md and the assembly-session-token skill.');
+  console.error('See CLAUDE.md and the assembly-auth skill.');
   process.exit(1);
 }

package/bin/foundation-exports.mjs

@@ -18,7 +18,7 @@
 // renews the bearer cookie; it never hands out a client.
 export const NON_CLIENT_EXPORTS = new Set([
   'APP_CSRF_HEADER', 'AUTH_UNAVAILABLE_CODE', 'AUTH_UNAVAILABLE_DIGEST', 'ActionContext', 'ActionError',
-  'ActionErrorStatus', 'AirtableFieldSchema', 'AppProxyCaller', 'AppProxyOptions', 'AirtableFormattedField',
+  'ActionErrorStatus', 'AirtableFieldSchema', 'AppKeyMintOutcome', 'AppProxyCaller', 'AppProxyOptions', 'AirtableFormattedField',
   'AirtableFormattedRecord', 'AirtableRecord', 'AirtableSchemaResult', 'AirtableTableSchema',
   'AssemblyProxyForwardContext', 'AssemblyProxyOptions', 'AuthUnavailableError',
   'BEARER_COOKIE_NAME', 'BEARER_EXPIRY_COOKIE_NAME', 'BEARER_HEADER_NAME', 'BEARER_IN_BODY_HEADER', 'BEARER_TTL_MS',
@@ -27,8 +27,8 @@ export const NON_CLIENT_EXPORTS = new Set([
   'ConnectionStatus', 'ConnectorError', 'ContractDocumentError', 'ConnectorErrorCode', 'CookieOutcome', 'CronHandler',
   'DEFAULT_LABELS', 'EXCHANGE_REJECTION_HEADER', 'ExchangeRejectedViewer', 'ExchangedSession',
   'FormatAirtableRecordsOpts', 'GenerateAppClientInput', 'GeneratedAppClient', 'GmailSendArgs', 'GmailSendResult', 'IntegrationClient',
-  'InternalUserAccess', 'LEGACY_APP_IDS', 'LocationReporter', 'MintFailure', 'MintOutcome', 'MintSessionOptions', 'MintedAppBearer',
-  'MintedBearer', 'NETWORK_CAPTURE_MESSAGE_TYPE', 'NetworkCaptureHeaderFingerprint',
+  'InternalUserAccess', 'LEGACY_APP_IDS', 'LocationReporter', 'MintAppKeyOptions', 'MintFailure', 'MintOutcome', 'MintSessionOptions', 'MintedAppBearer',
+  'MintedBearer', 'MintedOnBehalfOf', 'NETWORK_CAPTURE_MESSAGE_TYPE', 'NetworkCaptureHeaderFingerprint',
   'NetworkCaptureRecord', 'NotifyInternalUsersInput', 'PAINTED_BEACON_EVENT', 'PAINTED_BEACON_PATH',
   'PORTAL_ORIGIN_COOKIE_NAME', 'PdfText', 'DetectedPdfField', 'PdfFieldDetection', 'PdfFieldDetectionMethod', 'PdfFieldKind', 'PdfUnreadableError', 'PrincipalAllow', 'PrincipalKind',
   'Provider', 'ProxyOpts', 'RENEW_OUTCOME_EVENT', 'RenewOutcome', 'ReplaceChildRowsResult',

package/dist/action-route.js

@@ -14,13 +14,21 @@ export class ActionError extends Error {
         this.status = status;
     }
 }
-// One hop until the bearer carries a real chain. Not a measured depth.
-const PLACEHOLDER_HOPS = 1;
+// Used only when the verified bearer names a calling app but carries no chain
+// (a bearer minted before the platform stamped one). Not a measured depth.
+const FALLBACK_HOPS = 1;
 const trustedBaseUrl = process.env.ASSEMBLY_API_BASE_URL || undefined;
-function callerFrom(callerAppId) {
-    if (!callerAppId)
+// Chain and hops come from the verified bearer and are advisory: they label the
+// request, they never gate it.
+function callerFrom(identity) {
+    if (!identity.callerAppId)
         return undefined;
-    return { appId: callerAppId, chain: [callerAppId], hops: PLACEHOLDER_HOPS };
+    const chain = identity.chain?.length ? identity.chain : [identity.callerAppId];
+    return {
+        appId: identity.callerAppId,
+        chain,
+        hops: identity.hops ?? (identity.chain?.length ? chain.length : FALLBACK_HOPS),
+    };
 }
 // A calling app is the viewer only when the bearer names no person. A human
 // id wins so a staff or client session that also carries a caller stays human.
@@ -78,7 +86,7 @@ export async function getRequestContext() {
     if (!identity?.workspaceId) {
         throw new TokenInvalidError('Assembly bearer is required');
     }
-    const caller = callerFrom(identity.callerAppId);
+    const caller = callerFrom(identity);
     const viewer = viewerFrom(identity);
     if (!viewer) {
         throw new TokenInvalidError('Assembly bearer is required');

package/dist/assembly.d.ts

@@ -99,8 +99,10 @@ export declare function getOfflineAssembly(): Promise<AssemblyAPI>;
  * shown to a client must be filtered by the caller. Unlike getOfflineAssembly,
  * a viewer cookie does not make this throw — that is the point of it.
  *
- * Does not attach the viewer's bearer. Each request mints once; a second call
- * in the same request reuses that bearer.
+ * Does not attach the viewer's bearer to its own calls. Each request mints once;
+ * a second call in the same request reuses that bearer. A call through `fetch` to
+ * another app (`/v1/apps/...`) is the exception: in a client's request it is made
+ * as that client (see getCrossAppBearer), in a staff request as this app.
  */
 export declare function getInstallerAssembly(): Promise<AssemblyAPI>;
 export type AppProxyCaller = 'viewer' | 'installer';
@@ -114,9 +116,11 @@ export interface AppProxyOptions {
  * `createClient`. The bearer is resolved on every call, so a client built at
  * module scope still authenticates as the current request.
  *
- * `installer` calls as this app, with the same per-request mint as
- * getInstallerAssembly. `viewer` forwards the signed-in user's verified bearer,
- * which the platform scopes to that contact and refuses for a team member.
+ * `installer` calls as this app. In a client's request it also carries that
+ * client, so the platform checks the client could open the other app and the
+ * other app sees a client; in a staff request it is this app alone. `viewer`
+ * forwards the signed-in user's verified bearer, which the platform scopes to
+ * that contact and refuses for a team member.
  */
 export declare function appProxyOptions(appId: string, caller: AppProxyCaller): AppProxyOptions;
 export declare function getAssemblyForRequest(req: NextRequest): Promise<AssemblyAPI | NextResponse>;