@assembly-js/app-foundation 0.8.2 → 0.10.0

package/skills/assembly-auth/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: assembly-auth
+description: Use before writing an app/api route (every [id] route, GET included), a server action, a client call to the server or background work, or touching auth, session, token or identity. requireAuth → requireCompanyScope → handleRouteError, getAssemblyForRequest, useServerAction, authFetch.
+---
+
+`CLAUDE.md` → **Auth** has the lifecycle and the rules. This is the how-to. Everything below comes from `@assembly-js/app-foundation/server` unless it says otherwise.
+
+Use `getAssembly()` for anything shown to or done for the person using the app, and `getInstallerAssembly()` for staff-wide reads and writes the app is entitled to on its own, including notification helpers.
+
+## Client → server: a server action, by default
+
+A server action's argument is a TypeScript parameter, so `tsc` checks the payload. A route handler's body is an untyped wire contract that nothing checks until a user sends the first request, which you cannot do from the sandbox. Write a route handler only when the caller needs a raw `Response` (streamed bytes, a file download, a webhook or cron entry point) or isn't this app's own client component.
+
+```ts
+// app/actions/projects.ts
+'use server';
+import { getAssembly } from '@assembly-js/app-foundation/server';
+
+export async function loadClients() {
+  const assembly = await getAssembly(); // no token; throws TokenInvalidError on expiry, let it propagate
+  return assembly.listClients({});
+}
+```
+
+```tsx
+'use client';
+import { useServerAction } from '@/app/components/use-server-action';
+import { useAssembly } from '@/app/components/assembly-context';
+
+const { data, isLoading, error, reload } = useServerAction(() => loadClients(), []);
+const { callAction } = useAssembly();
+const onArchive = () => callAction(() => archiveProject(id)); // a button or mutation
+```
+
+`deps` work like `useEffect` deps and 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. Never `try/catch` an SDK call into `null` inside a data action; the silent re-exchange fires only if the expiry surfaces.
+
+When a route handler is the right tool, call it with `authFetch` from `@/app/components/lib-client`. It adds the CSRF header and re-exchanges and retries once on expiry; a plain `fetch` to a state-changing route gets a 403. Never put a token or the bearer in a URL or header. 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.
+
+An inbound third-party call (a webhook) carries no cookies, and current `proxy.ts` lets a cookie-less request skip the CSRF check, so it needs no proxy change; an older `proxy.ts` still answers 403 to a header-less POST. Authenticate the caller inside the route (signature or shared secret) and fail closed when its secret is unset.
+
+## Route handlers
+
+`requireAuth(request)` verifies the bearer and returns the viewer's identity. `getAssemblyForRequest(request)` returns the viewer's SDK client. Each returns a `NextResponse` instead when it can't: a 401 carrying `x-assembly-token-expired` (so `authFetch` re-exchanges and retries) or a 503 `auth_unavailable` when the platform can't be reached (nothing re-exchanges). Return it as is. Never use `getAssembly()` in a route handler.
+
+A route that must stay human-only passes `{ allow: ['internal', 'client'] }` to `requireAuth` and `requireCompanyScope`. With no option an app caller is allowed too; an app caller on a route that doesn't list `'app'` gets 403. When you branch on `viewer.kind`, keep a default branch: the set of kinds can grow.
+
+Routes listed in `privateRoutes` in `.assembly/app.json` (globs such as `/internal/**`, matched against the route template; `*` stays within a segment, `**` crosses segments) are not offered to other apps.
+
+### Every `[id]` route: `requireAuth` → `requireCompanyScope` → `handleRouteError`
+
+Every `app/api/.../[id]/route.ts` handler, **GET included** and at every nesting depth, runs this sequence before returning or mutating data. Skipping it on a GET is a cross-tenant IDOR: a user in company A reads company B's records by changing the id in the URL.
+
+```ts
+// app/api/projects/[id]/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import { eq } from 'drizzle-orm';
+import {
+  getAssemblyForRequest,
+  handleRouteError,
+  parseUuid,
+  requireAuth,
+  requireCompanyScope,
+} from '@assembly-js/app-foundation/server';
+import { db } from '@/lib/db';
+import { projects } from '@/lib/schema';
+
+export async function PATCH(request: NextRequest, { params }: { params: Promise<{ id: string }> }) {
+  const auth = await requireAuth(request);
+  if (auth instanceof NextResponse) return auth;
+
+  const id = parseUuid((await params).id); // only because projects.id is a uuid column
+  if (id instanceof NextResponse) return id;
+
+  try {
+    const project = await db.query.projects.findFirst({ where: eq(projects.id, id) });
+    if (!project) return NextResponse.json({ error: 'Not found' }, { status: 404 });
+
+    const assembly = await getAssemblyForRequest(request);
+    if (assembly instanceof NextResponse) return assembly;
+    const scopeError = await requireCompanyScope(
+      auth,
+      { companyId: project.companyId, clientId: project.clientId },
+      assembly,
+    );
+    if (scopeError) return scopeError;
+
+    // Never spread the full body: a caller could send companyId or id and reparent the row.
+    const { status } = await request.json();
+    await db.update(projects).set({ status }).where(eq(projects.id, id));
+    return NextResponse.json({ ok: true });
+  } catch (err) {
+    return handleRouteError(err, 'Update failed');
+  }
+}
+```
+
+- **GET is the same** without the body. A sub-resource (`/projects/[id]/notes/[noteId]`) loads the **sub-resource** and scopes on its own `companyId` and `clientId`, never on the parent's.
+- Do not treat every `[id]` param as a UUID: only validate as UUID when the next step is a uuid-column lookup (`parseUuid`). Catch blocks use `handleRouteError` and never return `err.message` (`assembly-route-errors`).
+
+### How `requireCompanyScope(identity, resource, assembly?)` decides
+
+- Internal users always pass (client-vs-staff isolation only, **not** Client Access: limited internal users still reach another company's row unless you filter app-owned queries yourself; see `assembly-internal-users`).
+- A company-scoped row (`companyId` set) is checked against `identity.companyId`; when that is absent (a multi-company client), the `assembly` argument lets the helper fetch the client's `companyIds`.
+- A client-scoped row (`companyId` null) passes only for its `clientId`. A row carrying **both** columns requires both, so a sibling client in the same company gets a 404; add no ownership check of your own.
+- Returns `null`, or a 403/404 `NextResponse`. A 403 is permanent; a re-exchange will not fix it.
+
+**Always select and pass both scope columns.** Without `clientId`, a client-scoped row 404s for the very client it belongs to; give tables both columns (`assembly-clients-companies`).
+
+### A page or action that reads one scoped record
+
+The same check, with identity from `getSessionIdentity()` and the client from `getAssembly()`:
+
+```tsx
+// app/projects/[id]/page.tsx
+const identity = await getSessionIdentity();
+if (!identity) notFound();
+const project = await db.query.projects.findFirst({ where: eq(projects.id, id) });
+if (!project) notFound();
+if (await requireCompanyScope(identity, { companyId: project.companyId, clientId: project.clientId }, await getAssembly())) notFound();
+```
+
+A list a client sees filters on the same columns in the query (`assembly-clients-companies`).
+
+## Background work: the offline bearer
+
+A cron job or webhook has no viewer and no cookie. Call `getOfflineAssembly()`: it mints an app-scoped bearer from `ASSEMBLY_API_KEY`. Anything on a schedule reads `assembly-scheduled-work` first; that skill has the cron route and its `CRON_SECRET` check.
+
+```ts
+const assembly = await getOfflineAssembly();
+const clients = await listAll((nextToken) => assembly.listClients({ nextToken, limit: 100 }));
+```
+
+- Only with genuinely no user. Inside a request a person triggered it bypasses the viewer's scope, and it refuses when a viewer is present.
+- It throws when the key is missing or the mint fails. Let it propagate: there is no client to re-exchange in the background.
+- `getSessionIdentity()` is `null` here, so a user id (a notification `senderId`) must be chosen explicitly.

package/skills/assembly-client-users/SKILL.md

@@ -19,7 +19,7 @@ if (identity?.clientId) {
 }
 ```
 
-Never call `assembly.getTokenPayload()` for this — see `assembly-session-token`.
+Never call `assembly.getTokenPayload()` for this — see `assembly-auth`.
 
 (`internalUserId` is set instead for staff — see `assembly-internal-users` skill.)
 

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-auth`. 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]`.
 
@@ -112,7 +112,7 @@ That reads as: this client's rows **within the active company**, plus the compan
 
 **On writes, validate the target company.** Before storing a row under a `companyId` the request supplied rather than the viewer's own, confirm it is actually one of the client's: `client.companyIds.includes(companyId)`. Otherwise a client can write into a company they don't belong to.
 
-**On `[id]` route handlers, pass both scope columns to `requireCompanyScope`.** It authorizes the intersection, so a row that also carries a `clientId` is reachable only by that client — never by a sibling in the same company. See `assembly-route-auth`.
+**On `[id]` route handlers, pass both scope columns to `requireCompanyScope`.** It authorizes the intersection, so a row that also carries a `clientId` is reachable only by that client — never by a sibling in the same company. See `assembly-auth`.
 
 ## Pattern 3 — the placeholder pitfall
 
@@ -138,6 +138,5 @@ You cannot infer "this app should be company-scoped" (or "this client has a real
 
 - `assembly-companies` — company CRUD, placeholder companies (excluded from `listCompanies` by default for these apps).
 - `assembly-client-users` — identifying the current client viewer and client identity in general.
-- `assembly-session-token` — reading the viewer with `getSessionIdentity()` / `useAssembly()`.
-- `assembly-route-auth` — `requireCompanyScope` for `[id]` route handlers; pass both scope columns there too.
+- `assembly-auth` — reading the viewer with `getSessionIdentity()` / `useAssembly()`, and `requireCompanyScope` for `[id]` route handlers; pass both scope columns there too.
 - `assembly-user-company-selector` — pre-built `UserCompanySelector` component for picker UIs; its `Entity` type still accepts a singular `companyId` for grouping purposes, which is fine for the component API but is not a substitute for `companyIds[]` in scope/storage decisions.

package/skills/assembly-internal-users/SKILL.md

@@ -14,7 +14,7 @@ const identity = await getSessionIdentity();
 const isInternal = !!identity?.internalUserId;
 ```
 
-Never call `assembly.getTokenPayload()` for this — see `assembly-session-token`.
+Never call `assembly.getTokenPayload()` for this — see `assembly-auth`.
 
 If `internalUserId` is set, the current viewer is staff. (`clientId` is set for client viewers — see `assembly-client-users` skill.)
 
@@ -82,7 +82,7 @@ everything rather than falling back to full access. Do not catch and widen that
 ### What to scope
 
 - **SDK lists and pickers** — `listClients`, `listCompanies`, and any UI built from them (tables, `UserCompanySelector` options) must only include clients/companies the viewer can access. Filter each page after fetch, or skip rows that fail `canAccessClient` / `canAccessCompanies`. Do not assume the platform API filtered the list for you.
-- **App-owned data** — queries against your Postgres tables must apply the same rule: when the viewer is limited, restrict rows to `companyId IN companyAccessList` (and for client-owned rows, ensure the client is accessible). `requireCompanyScope` lets every internal user through — it enforces client-vs-staff isolation, not Client Access. See `assembly-route-auth` and `assembly-clients-companies`.
+- **App-owned data** — queries against your Postgres tables must apply the same rule: when the viewer is limited, restrict rows to `companyId IN companyAccessList` (and for client-owned rows, ensure the client is accessible). `requireCompanyScope` lets every internal user through — it enforces client-vs-staff isolation, not Client Access. See `assembly-auth` and `assembly-clients-companies`.
 - **CRM-tab context** — when the token already carries a `clientId` or `companyId`, the viewer was routed to a record they can access; scope to that tab as usual. The global Dashboard main view still needs the filters above.
 - **Fan-out to other internal users** (notifications, assignments) — filter recipients by their access to the relevant client/company.
 

package/skills/assembly-native-resources/SKILL.md

@@ -122,4 +122,4 @@ Render an explicit, honest empty state and stop — "The intake form hasn't been
 - **List responses are paginated envelopes**, and `data` is nullable: destructure with a default and still index defensively (`const { data: forms = [] } = …; forms?.[0]`).
 - **Narrow before you index.** Taking `[0]` off an unfiltered list is the same guess as a hardcoded id. Filter by `membershipType` (and `companyId` for a client in multiple companies); if two candidates genuinely remain, surface the choice rather than picking one.
 - **Creating a channel is not a substitute for finding one.** `createMessageChannel` requires a `membershipType`, and its type is a string enum the SDK does not re-export from its package root — you cannot satisfy it with a plain `'individual'` string. Work with the channels the workspace already has; check the SDK types first if you genuinely need to create one.
-- **Ids from the app bridge or a route param** are runtime values, not literals — those are fine to pass straight to `retrieve*`, after the usual auth and scope checks (see `assembly-route-auth`).
+- **Ids from the app bridge or a route param** are runtime values, not literals — those are fine to pass straight to `retrieve*`, after the usual auth and scope checks (see `assembly-auth`).

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

@@ -1,198 +0,0 @@
----
-name: assembly-route-auth
-description: Use for every app/api/.../[id]/route.ts handler — GET and write alike. Every handler must call requireAuth then requireCompanyScope from @assembly-js/app-foundation/server before returning or mutating data, at parity with the page-level ownership guard.
----
-
-Every `app/api/.../[id]/route.ts` handler — **GET included** — must call `requireAuth` then `requireCompanyScope` (from `@assembly-js/app-foundation/server`) before returning or mutating data. Skipping either guard on a GET handler is a cross-tenant IDOR: an authenticated user in company A can read company B's records by changing the id in the URL.
-
-Routes listed in the `privateRoutes` array of `.assembly/app.json` (globs such as `/internal/**`, matched against the route template, not the file path; `*` stays within a segment, `**` crosses segments) are not offered to other apps.
-
-Use `getAssembly()` for anything shown to or done for the person using the app, and `getInstallerAssembly()` for staff-wide reads and writes the app is entitled to on its own, including notification helpers.
-
-A route that must stay human-only passes `{ allow: ['internal', 'client'] }` to `requireAuth` and `requireCompanyScope`. With no option, an app caller is allowed too; an app caller on a route that does not list `'app'` gets 403. When you branch on `viewer.kind`, keep a default branch — the set of kinds can grow.
-
-```ts
-import { requireAuth, requireCompanyScope, handleRouteError } from '@assembly-js/app-foundation/server';
-```
-
-## 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.
-
-**`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; limited internal users can still read another company's row unless you filter app-owned queries and lists yourself; see `assembly-internal-users`).
-- For a **company-scoped** resource (`companyId` set), 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), the helper matches `resource.clientId` against `identity.clientId`.
-- When a row carries **both** columns the helper requires both to match, so the company leg alone never admits a sibling client.
-- Returns `null` on success, or a 403/404 `NextResponse` on mismatch. A 403 is a permanent authorization failure — a re-exchange will not fix cross-tenant access.
-
-The `resource` argument is `{ companyId: string | null; clientId?: string | null }` — the same shape you already loaded from the database. **Always select and pass both columns.** Omitting `clientId` makes every client-scoped record 404 for the very client it is assigned to, and a table with no `clientId` column cannot express client scope at all — so give records both a `companyId` and a `clientId` column in the schema, even when only one is populated for a given row (see `assembly-clients-companies`).
-
-### Client-owned rows are covered by the guard
-
-A **client-owned row** — one carrying both a `companyId` and a `clientId`, the shape `assembly-clients-companies` prescribes — is authorized on the intersection: a sibling client in the same company gets a 404. Pass both columns and add no ownership check of your own. Internal users still pass, and a company-wide row (`clientId` null) is reachable by every client in the company, as it should be.
-
-For safe catch blocks and validating values before typed DB lookups (e.g. `parseUuid` before a uuid-column query), see `assembly-route-errors`. Do not treat every `[id]` route param as a UUID — only validate as UUID when the next step is a uuid-column lookup.
-
-## GET example
-
-```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);
-  }
-}
-```
-
-## Write (POST/PATCH) example
-
-Apply the same guard before any mutation. Mutating without it lets an authenticated user from company A modify company B's data.
-
-```ts
-// app/api/items/[id]/route.ts — PATCH handler in the same file
-export async function PATCH(
-  request: NextRequest,
-  { params }: { params: Promise<{ id: string }> },
-) {
-  const auth = await requireAuth(request);
-  if (auth instanceof NextResponse) return auth;
-
-  const { id: rawId } = await params;
-  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 });
-
-    const assembly = await getAssemblyForRequest(request);
-    if (assembly instanceof NextResponse) return assembly;
-    const scopeError = await requireCompanyScope(
-      auth,
-      { companyId: item.companyId, clientId: item.clientId },
-      assembly,
-    );
-    if (scopeError) return scopeError;
-
-    const body = await request.json();
-    // Never spread the full body — callers could include companyId or id
-    // and reparent / re-identify the resource. Extract only mutable fields.
-    const { name, description } = body; // replace with the actual mutable fields
-    await db.update(items).set({ name, description }).where(eq(items.id, id));
-    return NextResponse.json({ ok: true });
-  } catch (err) {
-    return handleRouteError(err, 'Update failed');
-  }
-}
-```
-
-## Sub-resource routes
-
-The same guard applies to **every level of nesting**. If a project has highlights, the highlight handler must scope to the highlight's own owning company or client — not just the parent project.
-
-Load the **sub-resource** from the database first, then call `requireCompanyScope` with the sub-resource's own `companyId` and `clientId`. Do NOT skip the scope check on the assumption that the parent route already guards access.
-
-```ts
-// app/api/projects/[id]/highlights/[highlightId]/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 { highlights } from '@/lib/schema';
-import { eq } from 'drizzle-orm';
-
-export async function GET(
-  request: NextRequest,
-  { params }: { params: Promise<{ id: string; highlightId: string }> },
-) {
-  const auth = await requireAuth(request);
-  if (auth instanceof NextResponse) return auth;
-
-  const { highlightId: rawHighlightId } = await params;
-  // highlights.id is uuid — validate at the lookup
-  const highlightId = parseUuid(rawHighlightId, 'highlight id');
-  if (highlightId instanceof NextResponse) return highlightId;
-
-  try {
-    const highlight = await db.query.highlights.findFirst({
-      where: eq(highlights.id, highlightId),
-    });
-    if (!highlight) return NextResponse.json({ error: 'Not found' }, { status: 404 });
-
-    const assembly = await getAssemblyForRequest(request);
-    if (assembly instanceof NextResponse) return assembly;
-    const scopeError = await requireCompanyScope(
-      auth,
-      { companyId: highlight.companyId, clientId: highlight.clientId },
-      assembly,
-    );
-    if (scopeError) return scopeError;
-
-    return NextResponse.json(highlight);
-  } catch (err) {
-    return handleRouteError(err);
-  }
-}
-```
-
-The same pattern applies to milestones, comments, assets, or any other sub-resource nested under a parent `[id]` route.
-
-## The rule
-
-Every `[id]`-nested route handler — regardless of HTTP method or nesting depth — must follow this sequence:
-
-1. `const auth = await requireAuth(request); if (auth instanceof NextResponse) return auth;`
-2. Load the resource (or sub-resource) from the database inside `try/catch`. If the lookup uses a uuid column, validate with `parseUuid` first (see `assembly-route-errors`). Use `handleRouteError` in the catch — never return `err.message`.
-3. Return 404 if not found.
-4. `const assembly = await getAssemblyForRequest(request); if (assembly instanceof NextResponse) return assembly;`
-5. `const scopeError = await requireCompanyScope(auth, { companyId: resource.companyId, clientId: resource.clientId }, assembly); if (scopeError) return scopeError;`
-6. Return data or perform the mutation.
-
-Never skip steps 1 or 5, even on GET handlers.

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

@@ -1,156 +0,0 @@
----
-name: assembly-session-token
-description: Use any time the app reads identity, fetches data, or touches auth/token handling. Covers the bearer lifecycle (session token, bearer cookie, getAssembly(), silent re-exchange), getSessionIdentity/useAssembly, useServerAction, authFetch. See assembly-route-auth for requireAuth/requireCompanyScope.
----
-
-Auth is **cookie-borne and automatic** — you never handle the session token and you never pass a token to anything. On the first load only, the parent opens your app at `…/?token=<session-token>`. The foundation middleware (`proxy.ts`) exchanges that session token exactly once (server-side, via `POST /v1/session`) for a short-lived **user-scoped bearer** and stores it in an HttpOnly, `SameSite=None` cookie. That mint is the only time the session token is ever used. Every server call your app makes reads the bearer from that cookie — `getAssembly()` returns an authenticated client with no token argument. 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 reload, no code from you.
-
-Your job is to follow three rules.
-
-## Rule 1 — read identity from `getSessionIdentity()` (server) or `useAssembly()` (client)
-
-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:
-
-```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, the same fields come from `useAssembly()` — seeded from the server, so there's no token and no loading race:
-
-```tsx
-'use client';
-import { useAssembly } from '@/app/components/assembly-context';
-
-export function Greeting() {
-  const { isClient, internalUserId, clientId, workspaceId } = useAssembly();
-  return <p>{isClient ? 'Welcome' : 'Hello, teammate'}</p>;
-}
-```
-
-Branch your UI on identity **before** making data calls — it's faster and more reliable than catching a 403.
-
-## Rule 2 — fetch data with `useServerAction` (the bearer rides the cookie for you)
-
-Data fetching is done with **SDK methods inside server actions**, not by calling the Assembly API from the browser. Write a `'use server'` action that takes **no token** and calls `getAssembly()`, then run it from the client through `useServerAction` — which manages loading/error state and transparently re-exchanges + retries once if the bearer has expired:
-
-```ts
-// app/actions/clients.ts
-'use server';
-import { getAssembly } from '@assembly-js/app-foundation/server';
-
-export async function listClients() {
-  const assembly = await getAssembly(); // throws TokenInvalidError if the bearer is gone
-  return assembly.listClients({});
-}
-```
-
-```tsx
-// app/components/client-list.tsx
-'use client';
-import { useServerAction } from '@/app/components/use-server-action';
-import { listClients } from '@/app/actions/clients';
-
-export function ClientList() {
-  const { data, isLoading, error, reload } = useServerAction(() => listClients(), []);
-  // ...
-}
-```
-
-`deps` works like a `useEffect` dependency array, with one rule: **deps must be primitives** — an id, a cursor, a `length`, a boolean. A derived array or object (`records`, `{ baseId }`, `items.filter(...)`) is a new identity on every render, so the action re-runs, its state update re-renders, and the page spins forever without a network call or an error to point at. Pass `records.length` or the id the array came from instead.
-
-`deps` works like a `useEffect` dependency array — list any values your action closes over so it re-runs when they change.
-
-For an imperative one-off (a button handler, a mutation), use `callAction` from `useAssembly()` — same re-exchange-and-retry behavior, no hook:
-
-```tsx
-const { callAction } = useAssembly();
-async function save(values: FormData) {
-  await callAction(() => updateClient(values));
-}
-```
-
-**Data server actions must let `TokenInvalidError` propagate** — do not wrap `getAssembly`/SDK calls in a `try/catch` that swallows the error into `null` or an empty result. The silent re-exchange only fires if the action *surfaces* the expiry.
-
-Do **not** hand-roll refresh logic: no bridge polling, no manual re-exchange + retry, no token subscriptions in components. `useServerAction`/`callAction` already do it.
-
-## Rule 3 — never touch the token in app code
-
-By the time your code runs, the bearer is already in the cookie. So:
-
-- **Never read `searchParams.token`** — not even on the entry route. The `?token=` on first load is the middleware's to consume, once. `getAssembly()` / `getSessionIdentity()` read the bearer cookie instead.
-- **Never put `?token=` in a `<Link>` / `router.push`.** Inner pages need nothing from the URL to be authenticated — auth is in the cookie. There is no `TokenLink`/`useWithToken`.
-- **Never pass a token to any function.** `getAssembly()`, server actions, and route handlers all take **no** token argument.
-- **Never store a token** in `useState`/`useRef`, a cookie you set, or anywhere else.
-
-```tsx
-// app/page.tsx — the entry page reads NO token; auth is already in the cookie.
-import { getAssembly } from '@assembly-js/app-foundation/server';
-
-export default async function Page() {
-  const assembly = await getAssembly();
-  // ...render initial server data, then hand off to client components that use useAssembly()
-}
-```
-
-## Route handlers — `authFetch` + `getAssemblyForRequest` (only when a route handler is the right tool)
-
-Server actions are the default. Use a route handler + `authFetch` only when you actually need one (streaming responses, file uploads, third-party webhooks). `authFetch` (from `app/components/lib-client.ts`) adds the required CSRF header; the bearer rides the cookie; it re-exchanges + retries once on a 401/403 from a bearer expiry:
-
-```tsx
-'use client';
-import { authFetch } from '@/app/components/lib-client';
-const res = await authFetch('/api/upload', { method: 'POST', body });
-```
-
-The handler authenticates with `getAssemblyForRequest(request)`, which returns a bearer-authenticated client or a 401 `NextResponse` (carrying the `x-assembly-token-expired` marker) — just return the `NextResponse` and `authFetch` re-exchanges and retries:
-
-```ts
-import { getAssemblyForRequest } from '@assembly-js/app-foundation/server';
-
-export async function POST(request: NextRequest) {
-  const assembly = await getAssemblyForRequest(request);
-  if (assembly instanceof NextResponse) return assembly;
-  // ...use assembly
-}
-```
-
-For `[id]`-scoped routes, guard with `requireAuth` then `requireCompanyScope` (see [[assembly-route-auth]]). `requireAuth` returns 401 (+ `x-assembly-token-expired` header) on an expired bearer; a 403 from `requireCompanyScope` is a permanent cross-tenant denial — a re-exchange will not fix it.
-
-## Background / offline work (cron, webhooks — no user present)
-
-Everything above is **request-scoped**: a user is in the loop and `getAssembly()` acts as that viewer. When there is no user session — a scheduled job or an incoming webhook — there's no bearer cookie to read. For those, call `getOfflineAssembly()` from `@assembly-js/app-foundation/server`: it mints an **app-scoped offline bearer** from your API key server-side and returns a bearer-only client.
-
-```ts
-// app/api/cron/sync/route.ts — no viewer, no cookie
-import { getOfflineAssembly, listAll } from '@assembly-js/app-foundation/server';
-
-export async function GET() {
-  const assembly = await getOfflineAssembly();
-  // Background work must cover everyone — walk every page, not just the first.
-  const clients = await listAll((nextToken) => assembly.listClients({ nextToken, limit: 100 }));
-  // …background work…
-  return Response.json({ ok: true });
-}
-```
-
-It **throws** (not returns null) if `ASSEMBLY_API_KEY` is missing or the mint fails — there's no client to re-exchange in the background, so let it propagate. `getSessionIdentity()` returns `null` on this path (the bearer is the app, not a person). Only reach for this outside a request — using it inside a user request bypasses that viewer's own scope; ignore it for normal UI work.
-
-## What NOT to do
-
-- **No `AssemblyBridge.sessionToken.*` in app components** — the foundation owns the bridge; you authenticate with `getAssembly()`.
-- **No token in component `useState`/`useRef`** — there's no client-side token at all.
-- **No hand-rolled refresh/retry** — `useServerAction`/`callAction`/`authFetch` handle bearer expiry.
-- **No client-side `assemblyApi` calls** — every API call is server-side through `getAssembly()` / `getAssemblyForRequest()`.
-- **No cookies you set, no `x-assembly-token` header, no `?token=` proxy, no `TokenLink`/`useWithToken`** — the bearer cookie is the whole story.
-- **No `searchParams.token` anywhere** — not even the entry route.
-- **Don't swallow `TokenInvalidError` in data actions** — let it propagate so the re-exchange-and-retry can fire.