@assembly-js/app-foundation 0.0.5 → 0.0.7

package/CLAUDE.md

@@ -733,7 +733,7 @@ import { requireAuth, requireCompanyScope } from '@assembly-js/app-foundation/se
 
 **`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. **The two legs are either/or:** a non-null `resource.companyId` selects the company check and `clientId` is never compared, so a client-owned row (both columns set) needs an explicit ownership check in the handler after the guard — see `assembly-route-auth`.
+**`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
@@ -776,11 +776,6 @@ export async function GET(
       assembly,
     );
     if (scopeError) return scopeError;
-    // The guard checked the company leg only — a client-owned row must also be
-    // this viewer's, or any client in the company could read it.
-    if (item.clientId && auth.clientId && item.clientId !== auth.clientId) {
-      return NextResponse.json({ error: 'Not found' }, { status: 404 });
-    }
 
     return NextResponse.json(item);
   } catch (err) {

package/dist/assembly.js

@@ -1,7 +1,7 @@
 import { assemblyApi } from '@assembly-js/node-sdk';
 import { cookies, headers } from 'next/headers';
 import { NextResponse } from 'next/server';
-import { BEARER_COOKIE_NAME, BEARER_HEADER_NAME, decodeBearer, isSessionExchangeEnabled, } from './session-exchange.js';
+import { BEARER_COOKIE_NAME, BEARER_HEADER_NAME, decodeBearer, isSessionExchangeEnabled, TOKEN_EXPIRED_HEADER, } from './session-exchange.js';
 import { mintBearerFromAppKey } from './mint-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
@@ -148,7 +148,7 @@ export async function getAssembly(input) {
 }
 // Duplicated from lib/auth.ts to avoid a circular import.
 function tokenExpiredResponse() {
-    return NextResponse.json({ error: 'Unauthorized', code: 'token_expired' }, { status: 401, headers: { 'x-assembly-token-expired': '1' } });
+    return NextResponse.json({ error: 'Unauthorized', code: 'token_expired' }, { status: 401, headers: { [TOKEN_EXPIRED_HEADER]: '1' } });
 }
 // Builds a bearer-only SDK client. The SDK's native `bearer` option sends
 // Authorization: Bearer on every request — generated service methods and fetch

package/dist/auth.js

@@ -1,6 +1,6 @@
 import { NextResponse } from 'next/server';
 import { getAssembly } from './assembly.js';
-import { BEARER_COOKIE_NAME, BEARER_HEADER_NAME, decodeBearer, isSessionExchangeEnabled, } from './session-exchange.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.
@@ -11,7 +11,7 @@ function isTokenInvalid(err) {
     return e.name === 'TokenInvalidError' || e.code === 'TOKEN_INVALID';
 }
 function tokenExpiredResponse() {
-    return NextResponse.json({ error: 'Unauthorized', code: 'token_expired' }, { status: 401, headers: { 'x-assembly-token-expired': '1' } });
+    return NextResponse.json({ error: 'Unauthorized', code: 'token_expired' }, { status: 401, headers: { [TOKEN_EXPIRED_HEADER]: '1' } });
 }
 // Resolves the current viewer's identity for a route handler.
 // Exchange on: bearer-only — decodes the bearer (proxy-forwarded header on first
@@ -60,13 +60,15 @@ export async function requireAuth(req) {
         return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
     }
 }
-// Asserts the viewer can access a resource scoped to a company OR to a client.
-// Internal users always pass. For a company-scoped resource (companyId set),
-// clients must belong to that company: if payload.companyId is present it must
-// match; otherwise membership is confirmed by fetching the client record.
-// For a client-scoped resource (companyId null), pass the resource's clientId
-// so the owning client can be matched against the viewer — without it a
-// client-scoped record 404s for the very client it is assigned to.
+// Asserts the viewer can access a resource scoped to a company, to a client, or
+// to both. Internal users always pass. For a company-scoped resource (companyId
+// set), clients must belong to that company: if payload.companyId is present it
+// must match; otherwise membership is confirmed by fetching the client record.
+// Whenever the resource names a clientId it must also be the viewer's, so a row
+// carrying both columns is authorized on the intersection rather than on company
+// alone — otherwise any client in the company could reach a sibling's row.
+// Always pass both scope columns: without clientId a client-scoped record
+// (companyId null) 404s for the very client it is assigned to.
 // Pass a session token string (legacy path) or a bearer-authenticated AssemblyAPI
 // instance from getAssemblyForRequest (bearer path) to enable the membership lookup.
 // Returns null on success, or a 403/404 NextResponse on mismatch.
@@ -82,12 +84,20 @@ export async function requireCompanyScope(payload, resource, tokenOrAssembly) {
             ? null
             : NextResponse.json({ error: 'Not found' }, { status: 404 });
     }
+    // A row carrying both columns belongs to one client inside the company, so the
+    // company match alone would let any sibling client in it through.
+    const clientMatches = !resource.clientId || resource.clientId === payload.clientId;
     if (payload.companyId) {
-        return payload.companyId === resource.companyId
+        return payload.companyId === resource.companyId && clientMatches
             ? null
             : NextResponse.json({ error: 'Not found' }, { status: 404 });
     }
     // No companyId in payload: client has multiple companies, verify membership.
+    // Ownership is decided from the token first so a sibling client fails here
+    // rather than after a round-trip that could only widen the answer.
+    if (!clientMatches) {
+        return NextResponse.json({ error: 'Not found' }, { status: 404 });
+    }
     if (!tokenOrAssembly) {
         return NextResponse.json({ error: 'Forbidden' }, { status: 403 });
     }

package/dist/lib-client.d.ts

@@ -0,0 +1,2 @@
+export declare function reexchangeBearer(): Promise<boolean>;
+export declare function authFetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;

package/dist/lib-client.js

@@ -0,0 +1,83 @@
+'use client';
+// Browser-side bearer renewal for generated apps. Exported via the dedicated
+// `@assembly-js/app-foundation/lib-client` subpath rather than the ./client
+// barrel: this module imports the app bridge, which is browser-only and must
+// never be dragged into the Edge middleware bundle that imports ./client
+// (proxy.ts pulls constants from that barrel).
+import { AssemblyBridge } from '@assembly-js/app-bridge';
+import { APP_CSRF_HEADER, TOKEN_EXPIRED_HEADER } from './session-exchange.js';
+const REEXCHANGE_PATH = '/api/assembly-reexchange';
+// Single-flight gate for renewals. Session tokens are single-use for exchange:
+// when the 60-minute bearer expires, every in-flight fetch on the page 401s at
+// once, and uncoordinated renewals would race each other for the token — the
+// first mints the bearer and the losers surface their original 401 even though
+// a valid bearer was just installed. All concurrent callers share this one
+// promise instead; it is cleared on settle so a later expiry renews afresh.
+let renewalInFlight = null;
+// Silently renews the bearer cookie after a 60-minute expiry. Asks the bridge
+// for the freshest session token (the parent keeps it alive) and posts it to the
+// re-exchange route, which mints a new bearer and sets the HttpOnly cookie — no
+// page reload. Returns true iff a fresh bearer was set. This is the only place
+// app code touches the raw session token, and only to re-mint; it is never sent
+// to the platform API.
+export function reexchangeBearer() {
+    if (renewalInFlight)
+        return renewalInFlight;
+    const renewal = renewBearer().finally(() => {
+        renewalInFlight = null;
+    });
+    renewalInFlight = renewal;
+    return renewal;
+}
+async function renewBearer() {
+    let token = AssemblyBridge.sessionToken.getCurrent()?.token ?? '';
+    // Proactively refresh: we're recovering from an expiry, so avoid re-minting
+    // from a session token that may itself be stale.
+    try {
+        const refreshed = await AssemblyBridge.sessionToken.refresh();
+        token = refreshed?.token ?? token;
+    }
+    catch {
+        // Ignore: fall back to the current token below.
+    }
+    if (!token)
+        return false;
+    try {
+        const res = await fetch(REEXCHANGE_PATH, {
+            method: 'POST',
+            headers: { 'x-assembly-token': token, [APP_CSRF_HEADER]: '1' },
+        });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+// Whether a denial is worth a renew-and-retry. A 401 is an authentication
+// failure — overwhelmingly an expired bearer, and foundation helpers mark
+// theirs with the expiry header — so it always renews; unmarked 401s renew too
+// because deployed apps hand-roll bare 401s on expiry paths, and gating those
+// would hard-fail their users at the 60-minute expiry. A 403 is an
+// authorization denial (requireCompanyScope, admin gates) that a fresh bearer
+// cannot fix, so it renews only when it explicitly carries the expiry marker.
+function shouldRenewBearer(res) {
+    if (res.status === 401)
+        return true;
+    return res.status === 403 && res.headers.has(TOKEN_EXPIRED_HEADER);
+}
+// fetch() for the app's own route handlers. The bearer travels automatically in
+// the HttpOnly cookie (same-origin), so this adds only the CSRF header — never a
+// token. On an expiry-shaped denial (see shouldRenewBearer) it renews the bearer
+// once via reexchangeBearer and retries; a genuine forbidden just returns.
+export async function authFetch(input, init) {
+    const headers = { ...(init?.headers ?? {}), [APP_CSRF_HEADER]: '1' };
+    const res = await fetch(input, { ...init, headers });
+    if (!shouldRenewBearer(res)) {
+        return res;
+    }
+    const renewed = await reexchangeBearer();
+    if (!renewed) {
+        return res;
+    }
+    return fetch(input, { ...init, headers });
+}

package/dist/mint-bearer.d.ts

@@ -1,4 +1,4 @@
-import { type ExchangedSession, type MintFailure } from './session-exchange.js';
+import { type ExchangedSession, type ExchangeRejectedViewer, type MintFailure } from './session-exchange.js';
 export interface MintedBearer {
     bearer: string;
     bearerExpiresAt: number;
@@ -9,8 +9,18 @@ export type MintOutcome = ({
 } & MintedBearer) | {
     ok: false;
     reason: MintFailure;
+    /** On a 'rejected' replay, whether the viewer who consumed the token
+     *  matches the caller's cookie session (only when the caller passed
+     *  cookieSessionId; absent on legacy rejections). */
+    rejectedViewer?: ExchangeRejectedViewer;
 };
-export declare function mintBearerFromSessionToken(token: string): Promise<MintOutcome>;
+export interface MintSessionOptions {
+    /** Session id behind the bearer the caller already holds. Forwarded with the
+     *  exchange so a rejected replay can say whether the consumer was the same
+     *  viewer (see MintOutcome.rejectedViewer). */
+    cookieSessionId?: string;
+}
+export declare function mintBearerFromSessionToken(token: string, options?: MintSessionOptions): Promise<MintOutcome>;
 export interface MintedAppBearer {
     bearer: string;
     bearerExpiresAt: number;

package/dist/mint-bearer.js

@@ -1,5 +1,5 @@
 import { assemblyApi, OpenAPI } from '@assembly-js/node-sdk';
-import { BEARER_TTL_MS, classifyExchangeFailure, } from './session-exchange.js';
+import { BEARER_TTL_MS, classifyExchangeFailure, EXCHANGE_REJECTION_HEADER, parseExchangeRejection, } from './session-exchange.js';
 // Trusted API origin for this stack (build-env supplied); empty in prod where
 // the SDK default is correct.
 const mintBaseUrl = process.env.ASSEMBLY_API_BASE_URL || undefined;
@@ -20,7 +20,7 @@ const EXCHANGE_TIMEOUT_MS = 15_000;
 //
 // On failure returns ok:false with a reason (see MintFailure) so the caller can
 // tell a spent token from an exchange it simply could not complete.
-export async function mintBearerFromSessionToken(token) {
+export async function mintBearerFromSessionToken(token, options) {
     let assembly;
     try {
         assembly = await assemblyApi({
@@ -56,14 +56,22 @@ export async function mintBearerFromSessionToken(token) {
         const resp = await assembly.fetch('/v1/session', {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ sessionId: payload.tokenId }),
+            body: JSON.stringify({
+                sessionId: payload.tokenId,
+                ...(options?.cookieSessionId
+                    ? { cookieSessionId: options.cookieSessionId }
+                    : {}),
+            }),
             signal: controller.signal,
         });
         if (!resp.ok) {
-            return {
-                ok: false,
-                reason: classifyExchangeFailure(resp.status),
-            };
+            const reason = classifyExchangeFailure(resp.status);
+            // Only a definitive rejection can carry a viewer verdict; on
+            // 'unavailable' the token may be unspent and no comparison happened.
+            const rejectedViewer = reason === 'rejected'
+                ? parseExchangeRejection(resp.headers.get(EXCHANGE_REJECTION_HEADER))
+                : undefined;
+            return { ok: false, reason, rejectedViewer };
         }
         // session.* mirrors platform-api's ExchangeResponse.Session — the
         // authoritative server-side record backing the (possibly slim) token, so

package/dist/session-exchange.d.ts

@@ -5,6 +5,10 @@ export declare function classifyExchangeFailure(status: number): MintFailure;
 export declare function serializeBearerCookie(value: string, maxAgeSeconds: number, partitioned: boolean): string;
 export declare const BEARER_HEADER_NAME = "x-assembly-request-bearer";
 export declare const APP_CSRF_HEADER = "x-assembly-app";
+export declare const TOKEN_EXPIRED_HEADER = "x-assembly-token-expired";
+export declare const EXCHANGE_REJECTION_HEADER = "x-assembly-exchange-rejection";
+export type ExchangeRejectedViewer = 'same_viewer' | 'different_viewer';
+export declare function parseExchangeRejection(value: string | null): ExchangeRejectedViewer | undefined;
 export declare function isSessionExchangeEnabled(): boolean;
 export interface ExchangedSession {
     workspaceId: string;

package/dist/session-exchange.js

@@ -47,6 +47,22 @@ export const BEARER_HEADER_NAME = 'x-assembly-request-bearer';
 // presence is sufficient: a cross-site request physically cannot carry a
 // custom header without a CORS preflight, and this app grants none.
 export const APP_CSRF_HEADER = 'x-assembly-app';
+// Marker header on 401s that mean "the bearer expired — re-exchange and retry",
+// emitted by requireAuth / getAssemblyForRequest / the re-exchange route. Its
+// absence on a denial is what lets authFetch skip renewal for genuine
+// authorization failures.
+export const TOKEN_EXPIRED_HEADER = 'x-assembly-token-expired';
+// Response header platform-api sets on a rejected exchange of an
+// already-consumed session token, when the caller supplied its cookie
+// session id for comparison: says whether the consumer was the same viewer.
+export const EXCHANGE_REJECTION_HEADER = 'x-assembly-exchange-rejection';
+// Narrows the raw header value; an absent or unrecognized value yields
+// undefined, which callers treat as the legacy opaque rejection.
+export function parseExchangeRejection(value) {
+    return value === 'same_viewer' || value === 'different_viewer'
+        ? value
+        : undefined;
+}
 // Master switch for the AI-260 server-side token exchange (bearer cookie flow).
 // Defaults OFF so the exchange stays dormant in every foundation snapshot:
 // merging this code — or any coworker rebuilding the snapshot for unrelated

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assembly-js/app-foundation",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "Versioned foundation helpers and build context for Assembly generated apps",
   "type": "module",
   "files": [
@@ -18,6 +18,10 @@
     "./client": {
       "types": "./dist/client.d.ts",
       "default": "./dist/client.js"
+    },
+    "./lib-client": {
+      "types": "./dist/lib-client.d.ts",
+      "default": "./dist/lib-client.js"
     }
   },
   "scripts": {
@@ -28,11 +32,13 @@
     "verify:bin": "node scripts/verify-bin.mjs"
   },
   "peerDependencies": {
+    "@assembly-js/app-bridge": ">=1.3.0",
     "@assembly-js/node-sdk": ">=4.2.3-beta.2",
     "next": ">=15",
     "server-only": "*"
   },
   "devDependencies": {
+    "@assembly-js/app-bridge": "1.3.0",
     "@assembly-js/node-sdk": "4.2.3-beta.2",
     "@types/bun": "^1.1.0",
     "@types/node": "^22",

package/skills/assembly-app-bridge-header/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: assembly-app-bridge-header
-description: Use any time the app sets breadcrumbs, primary CTA, secondary CTA, or actions menu in the Assembly header chrome. Always drive the header through the useAssemblyHeader hook — never call AssemblyBridge.header.set* from your own useEffect. Critical: the parent automatically prepends the app's name as breadcrumb 0 — never include it yourself, or it renders twice.
+description: Use any time the app sets breadcrumbs, primary CTA, secondary CTA, or actions menu in the Assembly header chrome. Always drive the header through the useAssemblyHeader hook — never call AssemblyBridge.header.set* from your own useEffect. Critical — the parent automatically prepends the app's name as breadcrumb 0; never include it yourself, or it renders twice.
 ---
 
 The Assembly header (breadcrumbs, primary/secondary CTA buttons, overflow actions menu) is controlled from your app. **Drive it with the `useAssemblyHeader` hook** — it ships in the foundation at `app/components/use-assembly-header.ts`.

package/skills/assembly-automations/SKILL.md

@@ -1,7 +1,7 @@
 <!-- feature:api-resources -->
 ---
 name: assembly-automations
-description: Use when the request describes a workflow that integrates with the Assembly platform — messaging a client, updating a CRM custom field, sending a contract or form, sharing a file, anything landing on Assembly's own data rather than only the app's tables — and it should happen in reaction to something happening in the app rather than because the user pressed a button. "When a time entry is logged, message the contact" and "completing a project should update the client's status field" both qualify. Both halves are required, and the word "automation" is not: a reaction that only writes the app's own tables is ordinary app code, and so is a platform write the user triggers directly in the app UI. Also use when the request asks the app to fire webhooks, drive or react to another tool, or expose operations others can invoke. Declare those events and operations in .assembly/api-resources.json so they appear as automation triggers and actions, emit each declared event at runtime with assembly.fetch, and serve each exposed operation with automationActionRoute. Covers the manifest schema, the two field shapes, event naming, the recipient-id contract, trigger configuration, dropdown option sources for action inputs, runtime event emission, and the action route contract.
+description: Use when the request describes a workflow that integrates with the Assembly platform — messaging a client, updating a CRM custom field, sending a contract or form, sharing a file, anything landing on Assembly's own data rather than only the app's tables — and it should happen in reaction to something happening in the app rather than because the user pressed a button. "When a time entry is logged, message the contact" and "completing a project should update the client's status field" both qualify. Both halves are required, and the word "automation" is not — a reaction that only writes the app's own tables is ordinary app code, and so is a platform write the user triggers directly in the app UI. Also use when the request asks the app to fire webhooks, drive or react to another tool, or expose operations others can invoke. Declare those events and operations in .assembly/api-resources.json so they appear as automation triggers and actions, emit each declared event at runtime with assembly.fetch, and serve each exposed operation with automationActionRoute. Covers the manifest schema, the two field shapes, event naming, the recipient-id contract, trigger configuration, dropdown option sources for action inputs, runtime event emission, and the action route contract.
 ---
 
 An app's API contract — the events it emits and the operations workspace automations can invoke — is declared in **`.assembly/api-resources.json`** at the repo root. The platform reads it at publish and registers the app's triggers and actions. Which file owns what: `.assembly/app.json` = how the platform runs the app (surfaces, secrets, integrations); `.assembly/api-resources.json` = the API contract the app exposes. Never mix their keys.
@@ -484,7 +484,7 @@ export const GET = automationActionRoute(async (_input, { workspaceId }) => {
 
 **Call it an automation, not a webhook.** In the product this feature is Automations; "webhook" is the wire format underneath it. `sendWebhook` and the `webhooks` manifest key keep their names in code — this is about what you say in chat. "I added a *Time entry logged* trigger you can build automations on" lands; "I set up a webhook" reads as plumbing nobody asked for.
 
-**Say what is left for them to do.** Declaring a trigger does not create the automation — the workspace still has to build it. When you finish, name the trigger you registered, name **each** automation they need to build, and point them at the **Automations** module (`/automations` in the dashboard). Count the actions the request asked for, not the triggers: "completing a project should message the client and update their status field" is one trigger and two actions, so say both. Skip this and the app looks like it ignored the request: the trigger exists, nothing is wired to it, and nothing happens.
+**Say what is left for them to do.** Declaring a trigger does not create the automation — the workspace still has to build it. When you finish, name the trigger you registered, name **each** automation they need to build, and hyperlink them to the **Automations** module at `https://dashboard.assembly.com/settings/automations`. Count the actions the request asked for, not the triggers: "completing a project should message the client and update their status field" is one trigger and two actions, so say both. Skip this and the app looks like it ignored the request: the trigger exists, nothing is wired to it, and nothing happens.
 
 ## Validation
 

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

@@ -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, `requireCompanyScope` is not enough by itself.** It authorizes the *company* leg; for a row that also has a `clientId`, add the client-ownership check yourself. 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-route-auth`.
 
 ## Pattern 3 — the placeholder pitfall
 

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

@@ -18,33 +18,14 @@ import { requireAuth, requireCompanyScope, handleRouteError } from '@assembly-js
 - 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`.
-- Those two are **either/or** — it never checks both, which is why a client-owned row needs the extra check below.
+- 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`).
 
-### `requireCompanyScope` does not check client ownership on a company-scoped row
+### Client-owned rows are covered by the guard
 
-The two legs are **either/or**, not both: when `resource.companyId` is non-null the helper authorizes on the company match alone and never compares `clientId`. It only compares `clientId` when `resource.companyId` is null.
-
-So for a **client-owned row** — one carrying both a `companyId` and a `clientId`, which is the shape `assembly-clients-companies` prescribes — `requireCompanyScope` alone lets **any client in that company** read or mutate it. Add the ownership check in the handler, right after the scope guard:
-
-```ts
-const scopeError = await requireCompanyScope(
-  auth,
-  { companyId: item.companyId, clientId: item.clientId },
-  assembly,
-);
-if (scopeError) return scopeError;
-
-// requireCompanyScope only checked the company leg. A row owned by a specific
-// client must also belong to this viewer, or any client in the company can read it.
-if (item.clientId && auth.clientId && item.clientId !== auth.clientId) {
-  return NextResponse.json({ error: 'Not found' }, { status: 404 });
-}
-```
-
-Guard on `auth.clientId` being present so internal users (who legitimately see every row in the workspace) still pass. A company-wide row (`clientId` null) skips the check, as it should.
+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.
 
@@ -91,11 +72,6 @@ export async function GET(
       assembly,
     );
     if (scopeError) return scopeError;
-    // The guard checked the company leg only — a client-owned row must also be
-    // this viewer's, or any client in the company could read it.
-    if (item.clientId && auth.clientId && item.clientId !== auth.clientId) {
-      return NextResponse.json({ error: 'Not found' }, { status: 404 });
-    }
 
     return NextResponse.json(item);
   } catch (err) {
@@ -133,9 +109,6 @@ export async function PATCH(
       assembly,
     );
     if (scopeError) return scopeError;
-    if (item.clientId && auth.clientId && item.clientId !== auth.clientId) {
-      return NextResponse.json({ error: 'Not found' }, { status: 404 });
-    }
 
     const body = await request.json();
     // Never spread the full body — callers could include companyId or id
@@ -195,9 +168,6 @@ export async function GET(
       assembly,
     );
     if (scopeError) return scopeError;
-    if (highlight.clientId && auth.clientId && highlight.clientId !== auth.clientId) {
-      return NextResponse.json({ error: 'Not found' }, { status: 404 });
-    }
 
     return NextResponse.json(highlight);
   } catch (err) {
@@ -217,7 +187,6 @@ Every `[id]`-nested route handler — regardless of HTTP method or nesting depth
 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. If the row is client-owned, check ownership — the guard above only covered the company leg: `if (resource.clientId && auth.clientId && resource.clientId !== auth.clientId) return NextResponse.json({ error: 'Not found' }, { status: 404 });`
-7. Return data or perform the mutation.
+6. Return data or perform the mutation.
 
-Never skip steps 1, 5, or 6, even on GET handlers.
+Never skip steps 1 or 5, even on GET handlers.