@assembly-js/app-foundation 0.9.0 → 0.11.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.11.0
+- [behavior] `check:record-urls` now checks each surface on its own: a record opened on the client portal needs its own `/c` route or `useUrlState`, and an internal dynamic route no longer exempts it. It also catches a list/detail view switch held in `useState`, so a client's request page keeps its own URL that can be reloaded or shared.
+- [guidance] `assembly-app-inner-location` says the record URL rule applies to the client portal too, with `app/c/[id]/page.tsx` or `?id=` through `useUrlState` as the two valid shapes.
+
+## 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.

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-record-urls.mjs

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
-// Fails the build when a record opened from a list (a Dialog, Sheet, Drawer or
-// detail panel) is driven by React state alone: the host URL never changes, so a
-// reload or a shared link lands on the list instead of the record. The fix is
-// either `useUrlState('id')` from `@assembly-js/app-foundation/client` or a
-// dynamic route for the record on the internal surface. The match is a
-// heuristic on a `selected*`-style `useState` that feeds a panel-like element.
+// Fails the build when a record opened from a list (a Dialog, Sheet, Drawer,
+// detail panel or a list/detail view switch) is driven by React state alone: the
+// host URL never changes, so a reload or a shared link lands on the list instead
+// of the record. The fix is either `useUrlState('id')` from
+// `@assembly-js/app-foundation/client` or a dynamic route for the record on the
+// surface that renders it. The match is a heuristic on a `selected*`-style
+// `useState` that feeds a panel-like element, or a `useState<View>` whose type
+// has a detail-like variant carrying an `id`.
 // Dependency free on purpose: it runs inside the generated app's sandbox before
 // any deps beyond Node are guaranteed.
 //
@@ -14,7 +16,7 @@
 // On a platform update turn (ASSEMBLY_UPDATE_TURN=1) it only warns, because an
 // update never rewrites how an app navigates.
 import { readFileSync, readdirSync, existsSync } from 'node:fs';
-import { join, relative, sep } from 'node:path';
+import { dirname, join, relative, sep } from 'node:path';
 
 const ROOT = process.cwd();
 const UPDATE_TURN = process.env.ASSEMBLY_UPDATE_TURN === '1';
@@ -23,13 +25,24 @@ const MANIFEST = join(ROOT, '.assembly', 'app.json');
 const INNER_LOCATION_SKILL = join(ROOT, '.claude', 'skills', 'assembly-app-inner-location', 'SKILL.md');
 const SOURCE_FILE = /\.(tsx|jsx)$/;
 const PAGE_FILE = /^page\.(tsx|ts|jsx|js)$/;
+const RESOLVE_EXTENSIONS = ['.tsx', '.ts', '.jsx', '.js'];
+const IMPORT_SPECIFIER = /(?:\bfrom\s*|\bimport\s*\(\s*)['"]([^'"]+)['"]/g;
 
 // `const [selectedRequest, setSelectedRequest] = useState(...)`; the setter name is not trusted.
 const USE_STATE = /const\s+\[\s*([A-Za-z_$][\w$]*)\s*,\s*[A-Za-z_$][\w$]*\s*\]\s*=\s*useState\b/g;
 const RECORD_SELECTION = /^(?:selected|active|viewing|viewed|current|detail|open(?:ed)?)[A-Z_]/;
 // Selection of something that is not a record, or that is genuinely transient.
-const NOT_A_RECORD = /(?:Tab|Filter|Status|Sort|View|Option|Date|Range|Column|Mode|Step|Page|Menu)s?$|^(?:confirm|delete|remove|menu|pending)/i;
+const TRANSIENT_NAME = /^(?:confirm|delete|remove|menu|pending)/i;
+const NOT_A_RECORD = new RegExp(
+  `(?:Tab|Filter|Status|Sort|View|Option|Date|Range|Column|Mode|Step|Page|Menu)s?$|${TRANSIENT_NAME.source}`,
+  'i',
+);
 const PANEL_ELEMENT = /<\w*(?:Dialog|Sheet|Drawer|Panel|Modal|Detail)\w*[\s>/]/;
+// `const [view, setView] = useState<View>(...)`; the generic is read by scanning, since it can nest.
+const TYPED_USE_STATE = /const\s+\[\s*([A-Za-z_$][\w$]*)\s*,\s*[A-Za-z_$][\w$]*\s*\]\s*=\s*useState\s*</g;
+// A view switch that can show one record: a variant naming a detail-like view, and an `id` field.
+const DETAIL_VARIANT = /['"`](?:detail|show|view|open|record|item)['"`]/i;
+const ID_FIELD = /\bid\??\s*:/;
 const OPT_OUT = /record-urls:\s*transient/;
 
 function sourceFiles(dir) {
@@ -47,15 +60,15 @@ function sourceFiles(dir) {
   return out;
 }
 
-// Prefixes of the client and notification surfaces; a dynamic route there does
-// not give the internal dashboard a record URL.
-function nonInternalPrefixes() {
-  const prefixes = new Set(['/c', '/n']);
+// Prefixes of the client and notification surfaces; a dynamic route on one
+// surface does not give another surface a record URL.
+function surfacePrefixes() {
+  const prefixes = { client: new Set(['/c']), notification: new Set(['/n']) };
   try {
     const manifest = JSON.parse(readFileSync(MANIFEST, 'utf8'));
     for (const key of ['client', 'notification']) {
       const p = manifest?.surfaces?.[key]?.path;
-      if (typeof p === 'string' && p.startsWith('/') && p !== '/') prefixes.add(p.replace(/\/+$/, ''));
+      if (typeof p === 'string' && p.startsWith('/') && p !== '/') prefixes[key].add(p.replace(/\/+$/, ''));
     }
   } catch {
     // defaults
@@ -63,6 +76,10 @@ function nonInternalPrefixes() {
   return prefixes;
 }
 
+function underPrefix(route, prefixes) {
+  return [...prefixes].some((p) => route === p || route.startsWith(`${p}/`));
+}
+
 function routeForPageFile(file) {
   const segments = relative(APP_DIR, file).split(sep).slice(0, -1);
   const urlSegments = segments.filter(
@@ -78,31 +95,133 @@ const contents = new Map(files.map((f) => [f, readFileSync(f, 'utf8')]));
 
 if (!existsSync(INNER_LOCATION_SKILL)) process.exit(0);
 
-const prefixes = nonInternalPrefixes();
-const hasInternalRecordRoute = files.some((f) => {
-  if (!PAGE_FILE.test(f.split(sep).pop())) return false;
-  const route = routeForPageFile(f);
-  if (!route.includes('[')) return false;
-  return ![...prefixes].some((p) => route === p || route.startsWith(`${p}/`));
-});
-if (hasInternalRecordRoute) process.exit(0);
-
 function escapeRe(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
+function relPath(file) {
+  return relative(ROOT, file).split(sep).join('/');
+}
+
+function resolveImport(from, spec) {
+  let base;
+  if (spec.startsWith('./') || spec.startsWith('../')) base = join(dirname(from), spec);
+  else if (spec.startsWith('@/')) base = join(ROOT, spec.slice(2));
+  else return null;
+  const candidates = [
+    base,
+    ...RESOLVE_EXTENSIONS.map((ext) => base + ext),
+    ...RESOLVE_EXTENSIONS.map((ext) => join(base, 'index' + ext)),
+  ];
+  return candidates.find((c) => contents.has(c)) ?? null;
+}
+
+// Files reachable from `roots` through relative and `@/` imports. An import the
+// regex misses (a barrel re-export, a computed path) only shrinks the set.
+function reachableFrom(roots) {
+  const seen = new Set(roots);
+  const queue = [...roots];
+  while (queue.length) {
+    const file = queue.pop();
+    for (const m of contents.get(file).matchAll(IMPORT_SPECIFIER)) {
+      const target = resolveImport(file, m[1]);
+      if (target && !seen.has(target)) {
+        seen.add(target);
+        queue.push(target);
+      }
+    }
+  }
+  return seen;
+}
+
+// The text between the `<` before `start` and its matching `>`, skipping `=>`.
+function genericArgument(src, start) {
+  let depth = 1;
+  for (let i = start; i < src.length; i++) {
+    const ch = src[i];
+    if (ch === '<') depth++;
+    else if (ch === '>' && src[i - 1] !== '=' && --depth === 0) return src.slice(start, i);
+  }
+  return '';
+}
+
+// The body of `type Name = …` or `interface Name {…}` declared in this file.
+function localTypeBody(src, name) {
+  const n = escapeRe(name);
+  const decl = new RegExp(`\\btype\\s+${n}\\b(?:<[^=]*>)?\\s*=|\\binterface\\s+${n}\\b[^{]*`).exec(src);
+  if (!decl) return '';
+  const isInterface = decl[0].startsWith('interface');
+  const start = decl.index + decl[0].length;
+  let depth = 0;
+  for (let i = start; i < src.length; i++) {
+    const ch = src[i];
+    if ('{(['.includes(ch)) depth++;
+    else if ('})]'.includes(ch)) {
+      depth--;
+      if (depth === 0 && isInterface) return src.slice(start, i + 1);
+    } else if (depth === 0 && !isInterface && ch === ';') {
+      return src.slice(start, i);
+    } else if (depth === 0 && !isInterface && ch === '\n' && src.slice(start, i).trim() && !/^\s*[|&]/.test(src.slice(i + 1))) {
+      return src.slice(start, i);
+    }
+  }
+  return src.slice(start);
+}
+
+function isDetailViewType(src, typeText) {
+  let text = typeText;
+  for (const ident of new Set(typeText.match(/\b[A-Z][\w$]*\b/g) ?? [])) text += '\n' + localTypeBody(src, ident);
+  return ID_FIELD.test(text) && DETAIL_VARIANT.test(text);
+}
+
+const prefixes = surfacePrefixes();
+const clientPages = [];
+const internalPages = [];
+let hasClientRecordRoute = false;
+let hasInternalRecordRoute = false;
+for (const f of files) {
+  if (!PAGE_FILE.test(f.split(sep).pop())) continue;
+  const route = routeForPageFile(f);
+  if (underPrefix(route, prefixes.client)) {
+    clientPages.push(f);
+    if (route.includes('[')) hasClientRecordRoute = true;
+  } else if (!underPrefix(route, prefixes.notification)) {
+    internalPages.push(f);
+    if (route.includes('[')) hasInternalRecordRoute = true;
+  }
+}
+const clientReachable = reachableFrom(clientPages);
+const internalReachable = reachableFrom(internalPages);
+
+// A route exempts a file only when every surface that renders it has one. A file
+// no page reaches is judged as internal, as it was before the check followed imports.
+function exemptByRoute(file) {
+  const onClient = clientReachable.has(file);
+  const onInternal = internalReachable.has(file) || !onClient;
+  return (!onClient || hasClientRecordRoute) && (!onInternal || hasInternalRecordRoute);
+}
+
 const violations = [];
 for (const file of files) {
   if (!SOURCE_FILE.test(file)) continue;
   const src = contents.get(file);
-  if (/\buseUrlState\b/.test(src) || OPT_OUT.test(src) || !PANEL_ELEMENT.test(src)) continue;
-  for (const match of src.matchAll(USE_STATE)) {
+  if (/\buseUrlState\b/.test(src) || OPT_OUT.test(src) || exemptByRoute(file)) continue;
+  const where = clientReachable.has(file) ? `${relPath(file)}  [client surface]` : relPath(file);
+  if (PANEL_ELEMENT.test(src)) {
+    for (const match of src.matchAll(USE_STATE)) {
+      const name = match[1];
+      if (!RECORD_SELECTION.test(name) || NOT_A_RECORD.test(name)) continue;
+      // Declared and read somewhere else in the file, i.e. it feeds the panel.
+      const uses = src.match(new RegExp(`(?<![\\w$.])${escapeRe(name)}(?![\\w$])`, 'g')) ?? [];
+      if (uses.length < 3) continue;
+      violations.push(`${where}  (useState: ${name})`);
+    }
+  }
+  for (const match of src.matchAll(TYPED_USE_STATE)) {
     const name = match[1];
-    if (!RECORD_SELECTION.test(name) || NOT_A_RECORD.test(name)) continue;
-    // Declared and read somewhere else in the file, i.e. it feeds the panel.
-    const uses = src.match(new RegExp(`(?<![\\w$.])${escapeRe(name)}(?![\\w$])`, 'g')) ?? [];
-    if (uses.length < 3) continue;
-    violations.push(`${relative(ROOT, file).split(sep).join('/')}  (useState: ${name})`);
+    if (TRANSIENT_NAME.test(name)) continue;
+    if (!isDetailViewType(src, genericArgument(src, match.index + match[0].length))) continue;
+    violations.push(`${where}  (useState view switch: ${name})`);
   }
 }
 
@@ -121,7 +240,12 @@ if (violations.length > 0 && UPDATE_TURN) {
   console.error("  - Replace the useState with `const [id, setId] = useUrlState('id')` from");
   console.error("    '@assembly-js/app-foundation/client' and render the record from `id`;");
   console.error('    a cold load with ?id= must open it, and Back must close it.');
-  console.error('  - Give the record its own route (app/requests/[id]/page.tsx) and link to it.');
+  console.error('  - Give the record its own route on the surface that lists it and link to it:');
+  console.error('    app/requests/[id]/page.tsx on the internal surface.');
+  console.error('A file marked [client surface] needs the same fix there: call');
+  console.error("`useUrlState('requestId')` in the client page component instead of a view state,");
+  console.error('or add app/c/[id]/page.tsx and link to it from the list. A cold load of that URL');
+  console.error('must open the record and Back must close it.');
   console.error('A genuinely transient UI (confirm dialog, menu) can add the comment');
   console.error('`// record-urls: transient` to the file.');
   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>;

package/dist/assembly.js

@@ -270,8 +270,10 @@ export function authUnavailableResponse() {
 // from the trusted build-env baseUrl, never a token/bearer claim. When the
 // caller has a verified identity, getTokenPayload() answers with it rather than
 // with the SDK's read of the bearer's claims.
-async function getBearerAssembly(bearer, identity) {
+async function getBearerAssembly(bearer, identity, options) {
     const assembly = await assemblyApi({ bearer, baseUrl: trustedBaseUrl });
+    if (options?.crossAppAsInstaller)
+        routeCrossAppFetchThroughInstaller(assembly);
     if (identity) {
         // Includes the embed-context ids the SDK's bearer-mode payload omits, so
         // payload.notificationId still marks the Notification Center surface.
@@ -325,7 +327,7 @@ export async function getOfflineAssembly() {
         throw new Error('getOfflineAssembly: ASSEMBLY_API_KEY is not set — cannot mint an app-scoped bearer');
     }
     const minted = await mintBearerFromAppKey();
-    if (!minted) {
+    if (!minted.ok) {
         throw new Error('getOfflineAssembly: failed to mint an app-scoped bearer from the app API key');
     }
     return getBearerAssembly(minted.bearer);
@@ -340,7 +342,7 @@ async function mintInstallerBearer() {
         throw new Error('getInstallerAssembly: ASSEMBLY_API_KEY is not set — cannot mint an app-scoped bearer');
     }
     const minted = await mintBearerFromAppKey();
-    if (!minted) {
+    if (!minted.ok) {
         throw new Error('getInstallerAssembly: failed to mint an app-scoped bearer from the app API key');
     }
     return minted.bearer;
@@ -377,11 +379,156 @@ async function getInstallerBearer() {
  * 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 async function getInstallerAssembly() {
-    return getBearerAssembly(await getInstallerBearer());
+    return getBearerAssembly(await getInstallerBearer(), undefined, {
+        crossAppAsInstaller: true,
+    });
+}
+// The platform's cross-app proxy lives under this prefix; nothing else gets a parent.
+const CROSS_APP_PATH_PREFIX = '/v1/apps/';
+// The platform's code for a mint whose parent bearer it refused outright, as
+// opposed to one that merely expired (which a re-exchange fixes).
+const PARENT_INVALID_CODE = 'parent_invalid';
+const PARENT_EXPIRED_CODE = 'parent_expired';
+// One cross-app bearer per request, keyed on the memoized headers object like the
+// installer bearer: a process-wide cache would hand one client's bearer to the next.
+const crossAppBearerByRequest = new WeakMap();
+// Whether `path`, as the SDK will concatenate it onto the base, lands on the
+// cross-app proxy. Resolved with URL first so `/v1/apps/../session` and encoded
+// dot-segments are judged by where they actually go.
+function isCrossAppPath(path) {
+    const base = (trustedBaseUrl ?? OpenAPI.BASE).replace(/\/+$/, '');
+    try {
+        const resolved = new URL(`${base}${path.startsWith('/') ? path : `/${path}`}`);
+        const baseUrl = new URL(base);
+        if (resolved.origin !== baseUrl.origin)
+            return false;
+        const basePath = baseUrl.pathname.replace(/\/+$/, '');
+        return resolved.pathname.slice(basePath.length).startsWith(CROSS_APP_PATH_PREFIX);
+    }
+    catch {
+        return false;
+    }
+}
+// The viewer bearer to present as the mint's parent, or undefined when this
+// request has no person to speak for. The decision rests only on what the
+// platform verifies for the one credential the request carries: the header when
+// present, else the cookie, never the cookie after a rejected header. A viewer
+// that is present but cannot be verified throws instead of quietly becoming app
+// authority.
+async function resolveCrossAppParent(headerStore, cookieStore) {
+    const candidate = headerStore.get(BEARER_HEADER_NAME) ||
+        cookieStore.get(BEARER_COOKIE_NAME)?.value ||
+        undefined;
+    const legacyViewer = Boolean(headerStore.get(LEGACY_TOKEN_HEADER) || headerStore.get(LEGACY_WORKSPACE_HEADER));
+    if (!candidate) {
+        if (legacyViewer)
+            throw new TokenInvalidError('Assembly bearer is required');
+        return undefined;
+    }
+    // Exchange off: a viewer is present and nothing can verify it.
+    if (!isSessionExchangeEnabled()) {
+        throw new TokenInvalidError('Assembly bearer is required');
+    }
+    const result = await verifyBearer(candidate);
+    if (!result.ok) {
+        if (result.reason === 'unavailable')
+            throw new AuthUnavailableError();
+        throw new TokenInvalidError('Assembly bearer is required');
+    }
+    const { identity } = result;
+    // The platform refuses an impersonation or assistant-run bearer as a parent.
+    if (identity.tokenKind !== 'viewer')
+        return undefined;
+    // Staff stay app authority; only a client is forwarded.
+    if (!identity.clientId)
+        return undefined;
+    return candidate;
+}
+async function mintCrossAppBearer(headerStore, cookieStore) {
+    const parent = await resolveCrossAppParent(headerStore, cookieStore);
+    // Without a person this is the plain installer bearer, so a request that also
+    // calls the installer's other endpoints still mints once.
+    if (!parent)
+        return { bearer: await getInstallerBearer() };
+    if (!process.env.ASSEMBLY_API_KEY) {
+        throw new Error('getInstallerAssembly: ASSEMBLY_API_KEY is not set — cannot mint an app-scoped bearer');
+    }
+    const minted = await mintBearerFromAppKey({ parent });
+    if (minted.ok)
+        return { bearer: minted.bearer };
+    // Never retried without the parent: that would be the fallback to app authority.
+    if (minted.code === PARENT_EXPIRED_CODE) {
+        throw new TokenInvalidError('Assembly bearer expired');
+    }
+    if (minted.code === PARENT_INVALID_CODE && minted.status !== undefined) {
+        return {
+            refusal: {
+                status: minted.status,
+                body: minted.body ?? JSON.stringify({ code: PARENT_INVALID_CODE }),
+            },
+        };
+    }
+    // A throttled mint says nothing about the parent, so it is an outage, not a refusal.
+    if (minted.status === undefined || minted.status >= 500 || minted.status === 429) {
+        throw new AuthUnavailableError();
+    }
+    throw new Error('getInstallerAssembly: failed to mint a cross-app bearer from the app API key');
+}
+// The bearer for a call to another app: the installer's, carrying the client when
+// this is a client's request. Throws where the request cannot be read (`'use cache'`,
+// prerender, `after()`), because a bearer minted there would be unattributed while
+// the page may still be serving a client.
+async function getCrossAppBearer() {
+    let headerStore;
+    let cookieStore;
+    try {
+        [headerStore, cookieStore] = await Promise.all([headers(), cookies()]);
+    }
+    catch {
+        throw new Error('A call to another app needs the current request, which cannot be read here (a cached component, prerender or after()). Make the call from a page, server action or route handler.');
+    }
+    const existing = crossAppBearerByRequest.get(headerStore);
+    if (existing)
+        return existing;
+    const pending = mintCrossAppBearer(headerStore, cookieStore);
+    crossAppBearerByRequest.set(headerStore, pending);
+    try {
+        return await pending;
+    }
+    catch (err) {
+        // A failed mint must not stick for the rest of the request.
+        crossAppBearerByRequest.delete(headerStore);
+        throw err;
+    }
+}
+function refusalResponse(refusal) {
+    return new Response(refusal.body, {
+        status: refusal.status,
+        headers: { 'Content-Type': 'application/json' },
+    });
+}
+// Wraps `fetch` on an installer SDK object so a raw call to another app uses the
+// cross-app bearer, and every other path is left exactly as the SDK sends it.
+function routeCrossAppFetchThroughInstaller(assembly) {
+    const original = assembly.fetch;
+    if (typeof original !== 'function')
+        return;
+    assembly.fetch = async (path, init) => {
+        if (!isCrossAppPath(path))
+            return original.call(assembly, path, init);
+        const outcome = await getCrossAppBearer();
+        if ('refusal' in outcome)
+            return refusalResponse(outcome.refusal);
+        const headers = new Headers(init?.headers);
+        headers.set('Authorization', `Bearer ${outcome.bearer}`);
+        return original.call(assembly, path, { ...init, headers, cache: 'no-store' });
+    };
 }
 /**
  * Options for calling another app's API through the platform, shaped for an
@@ -389,19 +536,30 @@ export async function getInstallerAssembly() {
  * `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 function appProxyOptions(appId, caller) {
     const origin = (trustedBaseUrl ?? OpenAPI.BASE).replace(/\/+$/, '');
     return {
         baseUrl: `${origin}/v1/apps/${encodeURIComponent(appId)}/api`,
         fetch: async (input) => {
-            const bearer = caller === 'installer' ? await getInstallerBearer() : await requireViewerBearer();
+            let bearer;
+            if (caller === 'installer') {
+                const outcome = await getCrossAppBearer();
+                if ('refusal' in outcome)
+                    return refusalResponse(outcome.refusal);
+                bearer = outcome.bearer;
+            }
+            else {
+                bearer = await requireViewerBearer();
+            }
             const request = new Request(input);
             request.headers.set('Authorization', `Bearer ${bearer}`);
-            return fetch(request);
+            return fetch(request, { cache: 'no-store' });
         },
     };
 }

package/dist/mint-bearer.d.ts

@@ -22,8 +22,35 @@ export interface MintSessionOptions {
 }
 export declare function mintBearerFromSessionToken(token: string, options?: MintSessionOptions): Promise<MintOutcome>;
 export declare function fetchSessionFlags(bearer: string): Promise<string[] | null>;
+/** The person a minted bearer is attributed to, echoed by the platform. */
+export interface MintedOnBehalfOf {
+    /** "client" or "internal_user". */
+    kind: string;
+    clientId?: string;
+    internalUserId?: string;
+    companyId?: string;
+}
 export interface MintedAppBearer {
     bearer: string;
     bearerExpiresAt: number;
+    /** Present only when the mint carried a parent the platform accepted. */
+    onBehalfOf?: MintedOnBehalfOf;
+}
+export type AppKeyMintOutcome = ({
+    ok: true;
+} & MintedAppBearer) | {
+    ok: false;
+    /** HTTP status of a refusal; absent when no response arrived (no key,
+     *  network failure, timeout) or the 2xx body was unusable. */
+    status?: number;
+    /** The platform's error code, when its body carried one. */
+    code?: string;
+    /** The platform's raw error body, so a refusal can be handed on verbatim. */
+    body?: string;
+};
+export interface MintAppKeyOptions {
+    /** Viewer bearer of the person whose request this app is serving. The platform
+     *  refuses a present-but-invalid parent; it is never silently dropped. */
+    parent?: string;
 }
-export declare function mintBearerFromAppKey(): Promise<MintedAppBearer | null>;
+export declare function mintBearerFromAppKey(options?: MintAppKeyOptions): Promise<AppKeyMintOutcome>;

package/dist/mint-bearer.js

@@ -145,20 +145,38 @@ export async function fetchSessionFlags(bearer) {
         clearTimeout(timeoutId);
     }
 }
+function parseOnBehalfOf(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const v = value;
+    if (typeof v.kind !== 'string' || v.kind === '')
+        return undefined;
+    const str = (x) => (typeof x === 'string' && x !== '' ? x : undefined);
+    return {
+        kind: v.kind,
+        clientId: str(v.clientId),
+        internalUserId: str(v.internalUserId),
+        companyId: str(v.companyId),
+    };
+}
 // Mints a short-lived, APP-scoped bearer from the app API key ALONE by calling
 // platform-api POST /v1/token (client-credentials). There is NO session token
 // and NO user in the loop: this is the OFFLINE/background path (cron, webhooks)
 // where no iframe ever handed us a session token to exchange. The app key mints
 // the bearer once; every subsequent data call then uses that bearer alone.
 //
+// With `parent`, the mint is attributed to the person that parent names (see
+// MintAppKeyOptions). Callers decide whether a parent exists; this only sends it.
+//
 // Uses a runtime-agnostic fetch (safe in BOTH the Edge middleware and Node route-
 // handler runtimes) with the same abort-based timeout as the session exchange,
-// and fails closed (null) on any error — including a malformed 2xx — so a caller
-// never proceeds with a missing or bad credential.
-export async function mintBearerFromAppKey() {
+// and fails closed on any error — including a malformed 2xx — so a caller
+// never proceeds with a missing or bad credential. The failure carries the
+// platform's status and code so a caller can tell a refused parent from an outage.
+export async function mintBearerFromAppKey(options) {
     const apiKey = process.env.ASSEMBLY_API_KEY;
     if (!apiKey)
-        return null;
+        return { ok: false };
     // Client-credentials mint: POST /v1/token authenticated by the app key sent as
     // X-API-Key. Unlike mintBearerFromSessionToken (which decrypts a session token
     // and lets the SDK derive the header), there is no token here, and the SDK only
@@ -174,16 +192,31 @@ export async function mintBearerFromAppKey() {
         // Present only in the app's sandbox (written to .env.local, never to the deployed
         // env); it lets the platform tell a sandbox call from a deployed one.
         const sandboxGrant = process.env.ASSEMBLY_SANDBOX_GRANT;
+        const body = {
+            ...(sandboxGrant ? { sandboxGrant } : {}),
+            ...(options?.parent ? { parent: options.parent } : {}),
+        };
+        const hasBody = Object.keys(body).length > 0;
         const resp = await fetch(`${base}/v1/token`, {
             method: 'POST',
-            headers: sandboxGrant
+            headers: hasBody
                 ? { 'X-API-Key': apiKey, 'Content-Type': 'application/json' }
                 : { 'X-API-Key': apiKey },
-            ...(sandboxGrant ? { body: JSON.stringify({ sandboxGrant }) } : {}),
+            ...(hasBody ? { body: JSON.stringify(body) } : {}),
             signal: controller.signal,
         });
-        if (!resp.ok)
-            return null;
+        if (!resp.ok) {
+            let text;
+            let code;
+            try {
+                text = await resp.text();
+                const parsed = JSON.parse(text);
+                if (typeof parsed?.code === 'string')
+                    code = parsed.code;
+            }
+            catch { }
+            return { ok: false, status: resp.status, code, body: text };
+        }
         const json = (await resp.json());
         // Fail closed on a malformed or already-expired 2xx: a missing/mistyped token
         // would yield a client that sends `Authorization: Bearer undefined`, a
@@ -195,13 +228,19 @@ export async function mintBearerFromAppKey() {
             typeof json.tokenExpiresAt !== 'number' ||
             !Number.isFinite(json.tokenExpiresAt) ||
             json.tokenExpiresAt * 1_000 <= now) {
-            return null;
+            return { ok: false, status: resp.status };
         }
         const bearerExpiresAt = Math.min(json.tokenExpiresAt * 1_000, now + BEARER_TTL_MS);
-        return { bearer: json.token, bearerExpiresAt };
+        const onBehalfOf = parseOnBehalfOf(json.onBehalfOf);
+        return {
+            ok: true,
+            bearer: json.token,
+            bearerExpiresAt,
+            ...(onBehalfOf ? { onBehalfOf } : {}),
+        };
     }
     catch {
-        return null;
+        return { ok: false };
     }
     finally {
         clearTimeout(timeoutId);

package/dist/proxy.js

@@ -121,7 +121,7 @@ async function fetchWorkspaceThemeForIdentity(workspaceId, bearer) {
     // or future change surfaces an exception.
     try {
         const minted = await mintBearerFromAppKey();
-        if (!minted?.bearer)
+        if (!minted.ok)
             return null;
         return await fetchWorkspaceThemeWithBearer(minted.bearer, workspaceId);
     }

package/dist/scripts.js

@@ -4644,33 +4644,66 @@ var COOKIE_PROBE_TTL_SECONDS = 24 * 60 * 60;
 // src/mint-bearer.ts
 var mintBaseUrl = process.env.ASSEMBLY_API_BASE_URL || void 0;
 var EXCHANGE_TIMEOUT_MS = 15e3;
-async function mintBearerFromAppKey() {
+function parseOnBehalfOf(value) {
+  if (!value || typeof value !== "object") return void 0;
+  const v = value;
+  if (typeof v.kind !== "string" || v.kind === "") return void 0;
+  const str = (x) => typeof x === "string" && x !== "" ? x : void 0;
+  return {
+    kind: v.kind,
+    clientId: str(v.clientId),
+    internalUserId: str(v.internalUserId),
+    companyId: str(v.companyId)
+  };
+}
+async function mintBearerFromAppKey(options) {
   const apiKey = process.env.ASSEMBLY_API_KEY;
-  if (!apiKey) return null;
+  if (!apiKey) return { ok: false };
   const base = (mintBaseUrl ?? OpenAPI2.BASE).replace(/\/$/, "");
   const now = Date.now();
   const controller = new AbortController();
   const timeoutId = setTimeout(() => controller.abort(), EXCHANGE_TIMEOUT_MS);
   try {
     const sandboxGrant = process.env.ASSEMBLY_SANDBOX_GRANT;
+    const body = {
+      ...sandboxGrant ? { sandboxGrant } : {},
+      ...options?.parent ? { parent: options.parent } : {}
+    };
+    const hasBody = Object.keys(body).length > 0;
     const resp = await fetch(`${base}/v1/token`, {
       method: "POST",
-      headers: sandboxGrant ? { "X-API-Key": apiKey, "Content-Type": "application/json" } : { "X-API-Key": apiKey },
-      ...sandboxGrant ? { body: JSON.stringify({ sandboxGrant }) } : {},
+      headers: hasBody ? { "X-API-Key": apiKey, "Content-Type": "application/json" } : { "X-API-Key": apiKey },
+      ...hasBody ? { body: JSON.stringify(body) } : {},
       signal: controller.signal
     });
-    if (!resp.ok) return null;
+    if (!resp.ok) {
+      let text;
+      let code;
+      try {
+        text = await resp.text();
+        const parsed = JSON.parse(text);
+        if (typeof parsed?.code === "string") code = parsed.code;
+      } catch {
+      }
+      return { ok: false, status: resp.status, code, body: text };
+    }
     const json = await resp.json();
     if (typeof json.token !== "string" || json.token.length === 0 || typeof json.tokenExpiresAt !== "number" || !Number.isFinite(json.tokenExpiresAt) || json.tokenExpiresAt * 1e3 <= now) {
-      return null;
+      return { ok: false, status: resp.status };
     }
     const bearerExpiresAt = Math.min(
       json.tokenExpiresAt * 1e3,
       now + BEARER_TTL_MS
     );
-    return { bearer: json.token, bearerExpiresAt };
+    const onBehalfOf = parseOnBehalfOf(json.onBehalfOf);
+    return {
+      ok: true,
+      bearer: json.token,
+      bearerExpiresAt,
+      ...onBehalfOf ? { onBehalfOf } : {}
+    };
   } catch {
-    return null;
+    return { ok: false };
   } finally {
     clearTimeout(timeoutId);
   }
@@ -4689,7 +4722,7 @@ async function getOfflineAssembly() {
     );
   }
   const minted = await mintBearerFromAppKey();
-  if (!minted) {
+  if (!minted.ok) {
     throw new Error(
       "getOfflineAssembly: failed to mint an app-scoped bearer from the app API key"
     );

package/dist/verify-bearer.d.ts

@@ -9,6 +9,11 @@ export interface VerifiedIdentity {
     callerAppId?: string;
     installerUserId?: string;
     tokenKind?: string;
+    /** Apps an app-to-app call passed through to reach this request, read from the
+     *  verified bearer's own claims. Advisory: display and logging only, never a
+     *  decision (the platform's depth cap is the control). */
+    chain?: string[];
+    hops?: number;
     /** Epoch SECONDS at which the verified bearer expires. */
     expiresAt: number;
 }
@@ -24,6 +29,7 @@ export declare const VIEWER_BEARER_HEADER = "X-Assembly-Viewer-Bearer";
 export declare const VERIFY_OUTCOME_EVENT = "assembly.verify_outcome";
 /**
  * Resolves a viewer bearer to the identity the platform vouches for. Identity
- * must come from here, never from the bearer's decoded claims.
+ * must come from here, never from the bearer's decoded claims. The one
+ * exception is the advisory call chain, which only the bearer carries.
  */
 export declare function verifyBearer(bearer: string): Promise<VerifyResult>;

package/dist/verify-bearer.js

@@ -156,11 +156,45 @@ async function verifyUncached(bearer, key, startedAt) {
     logOutcome(result.reason, startedAt);
     return result;
 }
+// Reads the advisory call-chain claims off a bearer the platform has just
+// verified. Never used to decide anything: a bearer that fails to decode simply
+// has no chain.
+function readChainClaims(bearer) {
+    try {
+        const segment = bearer.split('.')[1];
+        const b64 = segment.replace(/-/g, '+').replace(/_/g, '/');
+        const padded = b64 + '='.repeat((4 - (b64.length % 4)) % 4);
+        const claims = JSON.parse(new TextDecoder().decode(Uint8Array.from(atob(padded), (ch) => ch.charCodeAt(0))));
+        const chain = Array.isArray(claims.chain)
+            ? claims.chain.filter((a) => typeof a === 'string' && a !== '')
+            : [];
+        const hops = typeof claims.hops === 'number' && Number.isInteger(claims.hops) && claims.hops > 0
+            ? claims.hops
+            : undefined;
+        return {
+            ...(chain.length ? { chain } : {}),
+            ...(hops ? { hops } : {}),
+        };
+    }
+    catch {
+        return {};
+    }
+}
 /**
  * Resolves a viewer bearer to the identity the platform vouches for. Identity
- * must come from here, never from the bearer's decoded claims.
+ * must come from here, never from the bearer's decoded claims. The one
+ * exception is the advisory call chain, which only the bearer carries.
  */
 export async function verifyBearer(bearer) {
+    const result = await verifyBearerWithPlatform(bearer);
+    if (!result.ok)
+        return result;
+    return {
+        ok: true,
+        identity: Object.freeze({ ...result.identity, ...readChainClaims(bearer) }),
+    };
+}
+async function verifyBearerWithPlatform(bearer) {
     const startedAt = Date.now();
     // The decode is a no-network precheck: shape, expiry and workspace claim.
     if (!decodeBearer(bearer)) {

package/package.json

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

package/skills/assembly-app-inner-location/SKILL.md

@@ -13,7 +13,7 @@ The host mirrors the app's inner page in its own address bar and can open the ap
 
 ## Records get a URL
 
-Keep which record is open in the URL, not in `useState`: `const [id, setId] = useUrlState('id')` from `@assembly-js/app-foundation/client` for a panel, Sheet or Dialog, or a route like `app/requests/[id]/page.tsx`. A record opened from a list must load cold from its URL and Back must close it. `bun run build` fails `check:record-urls` for a `selectedId`-style `useState` feeding a record panel; use the helper or a route to fix it.
+Keep which record is open in the URL, not in `useState`: `const [id, setId] = useUrlState('id')` from `@assembly-js/app-foundation/client` for a panel, Sheet or Dialog, or a route like `app/requests/[id]/page.tsx`. A record opened from a list must load cold from its URL and Back must close it. `bun run build` fails `check:record-urls` for a `selectedId`-style `useState` feeding a record panel; use the helper or a route to fix it. This applies to the client surface (`/c`) as much as the internal one: a record a client opens from a list is `app/c/[id]/page.tsx` or `?id=` through `useUrlState`, never a `useState<View>` that switches between list and detail; the check fails that too.
 
 ## Notifications deep-link to the record, not the app root