@assembly-js/app-foundation 0.0.29 → 0.0.31

package/CLAUDE.md

@@ -1162,7 +1162,7 @@ Use `AssemblyBridge.header.*` for breadcrumbs, CTAs, and actions menu. See `.cla
 <!-- /feature:app-owned-header -->
 - ❌ Don't let two mounted components call `useAssemblyHeader` at once — e.g. a parent shell's scaffolding-era stub CTA left in place after a child took real ownership. Strict Mode hides the race in dev; the hook throws in dev and ignores the second caller in production. Delete the parent's stub the moment a child owns the slot.
 - ❌ Don't `window.open(url, '_self')` or set `window.location` for external links — use `<a target="_blank" rel="noreferrer">`.
-- ❌ Don't open one of your own route handlers by plain navigation for a download or export — `<a href="/api/…/pdf" target="_blank">`, `window.open('/api/…')`. The bearer cookie is partitioned to the portal iframe, so a new tab arrives signed out and `requireAuth` rejects it; the build passes and the link only fails in a live test. Fetch it with `authFetch`, read the response with `res.blob()`, and click a programmatic anchor on `URL.createObjectURL(blob)` with a `download` name. (`assembly-storage` shows the same flow for a route that returns a pre-signed URL as JSON rather than the bytes.)
+- ❌ Don't open one of your own route handlers by plain navigation for a download or export — `<a href="/api/…/pdf" target="_blank">`, `window.open('/api/…')`. The bearer cookie is partitioned to the portal iframe, so a new tab arrives signed out and `requireAuth` rejects it; the build passes and the link only fails in a live test. Use `downloadViaBlob(url, filename)` from `app/components/lib-client.ts` — it calls `authFetch`, reads `res.blob()`, and triggers the download via a programmatic anchor on `URL.createObjectURL(blob)`. (`assembly-storage` shows the same flow for a route that returns a pre-signed URL as JSON rather than the bytes.)
 - ❌ Don't hardcode brand colors. The portal applies the workspace theme.
 - ❌ Don't add dark mode support (`dark:` classes, `.dark` class toggling, `next-themes`, `ThemeProvider`, or `prefers-color-scheme` media queries). The assembly-ui registry is light-only and the layout forces `colorScheme: 'light'`.
 - ❌ Don't handle the session token at all — no cookie you set, no `useAssembly().token`, no `x-assembly-token` header, no `searchParams.token`. The middleware already exchanged it for a bearer cookie; call `getAssembly()` / `getAssemblyForRequest(req)` server-side and the call is authenticated.

package/bin/scan-routes.mjs

@@ -0,0 +1,351 @@
+// Finds an app's API route files and describes them as `.assembly/routes.json`.
+//
+// The output is a pure function of the committed file contents: no timestamps,
+// absolute paths or package version, so an unchanged tree rescans to the same
+// bytes and a package bump never dirties every repo. The format is frozen (see
+// route contract); Go re-derives the template and reserved-segment rules
+// from the same constants, so change them here and there together.
+//
+// Parse-only on purpose: ts.createSourceFile, no Program, no type check, no
+// module resolution. The scanner runs on every turn and must stay cheap and
+// unable to fail on an app that does not typecheck.
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, readdirSync, readFileSync, readlinkSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+export const SCHEMA_VERSION = 1;
+
+// Shared with Go: the one place a route file is recognised.
+export const ROUTE_FILE_PREDICATE = /^app\/api\/(?:.+\/)?route\.(?:ts|tsx|js|jsx)$/;
+const UNSUPPORTED_ROUTE_FILE = /^(?:src\/app\/api\/(?:.+\/)?route|pages\/api\/.+)\.(?:ts|tsx|js|jsx)$/;
+const API_PREFIX = 'app/api/';
+
+// The only methods the platform proxy mounts.
+export const PROXY_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
+const IGNORED_METHODS = ['HEAD', 'OPTIONS'];
+
+// Infrastructure routes are opt-out of cross-app exposure. Mirrored in Go; a
+// parity test pins both lists.
+export const RESERVED_SEGMENTS = ['cron', 'webhook', 'webhooks'];
+export const RESERVED_SEGMENT_PREFIX = 'assembly-';
+export const EXCLUDING_WRAPPERS = ['cronRoute', 'automationActionRoute'];
+
+const APP_JSON_PATH = '.assembly/app.json';
+const NEXT_CONFIG_FILES = ['next.config.js', 'next.config.mjs', 'next.config.cjs', 'next.config.ts', 'next.config.mts'];
+const SKIPPED_DIRS = new Set(['node_modules', '.git', '.next', '.vercel', '.turbo']);
+
+const byteCompare = (a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b));
+
+function loadTypeScript() {
+  // Resolved from this file, so an installed package finds the app's own
+  // typescript and this repo's tests find the devDependency.
+  return createRequire(import.meta.url)('typescript');
+}
+
+// ---------------------------------------------------------------------------
+// Tree listing and hashing
+// ---------------------------------------------------------------------------
+
+function walk(root, dir = '') {
+  const out = [];
+  for (const entry of readdirSync(path.join(root, dir), { withFileTypes: true })) {
+    if (SKIPPED_DIRS.has(entry.name)) continue;
+    const rel = dir ? `${dir}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) out.push(...walk(root, rel));
+    else if (entry.isFile()) out.push(rel);
+  }
+  return out;
+}
+
+// What `git add -A` would stage, so the scan describes the commit it rides in.
+function listFiles(root) {
+  if (existsSync(path.join(root, '.git'))) {
+    const res = spawnSync('git', ['ls-files', '-z', '--cached', '--others', '--exclude-standard'], {
+      cwd: root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024,
+    });
+    if (res.status === 0) {
+      const listed = res.stdout.split('\0').filter(Boolean);
+      // A tracked file deleted from the working tree is still listed by --cached.
+      return [...new Set(listed)].filter((f) => existsSync(path.join(root, f)));
+    }
+  }
+  return walk(root);
+}
+
+const gitBlobSha = (bytes) =>
+  createHash('sha1').update(`blob ${bytes.length}\0`).update(bytes).digest('hex');
+
+// `git hash-object` applies the repo's clean filters (autocrlf, .gitattributes),
+// so asking git yields the blob that will actually be committed; hashing raw
+// working-tree bytes would not under those filters.
+function hashFiles(root, files, contents) {
+  const hashes = new Map();
+  const inRepo = existsSync(path.join(root, '.git'));
+  const isLink = (f) => lstatSync(path.join(root, f)).isSymbolicLink();
+  // Git stores a symlink as a blob of its target path, not of the file it points at.
+  for (const f of files) if (isLink(f)) hashes.set(f, gitBlobSha(Buffer.from(readlinkSync(path.join(root, f)))));
+
+  const viaGit = files.filter((f) => !hashes.has(f) && !/[\n\r]/.test(f));
+  if (viaGit.length > 0 && inRepo) {
+    const res = spawnSync('git', ['hash-object', '--stdin-paths'], {
+      cwd: root, input: viaGit.join('\n') + '\n', encoding: 'utf8', maxBuffer: 16 * 1024 * 1024,
+    });
+    const shas = res.status === 0 ? res.stdout.split('\n').filter(Boolean) : [];
+    if (shas.length === viaGit.length) viaGit.forEach((f, i) => hashes.set(f, shas[i]));
+    else {
+      // The batch is all-or-nothing; retry per file so one bad path does not
+      // drop every other file to an unfiltered hash.
+      for (const f of viaGit) {
+        const one = spawnSync('git', ['hash-object', '--', f], { cwd: root, encoding: 'utf8' });
+        if (one.status === 0 && one.stdout.trim()) hashes.set(f, one.stdout.trim());
+      }
+    }
+  }
+  for (const f of files) if (!hashes.has(f)) hashes.set(f, gitBlobSha(contents.get(f)));
+  return hashes;
+}
+
+// ---------------------------------------------------------------------------
+// Template derivation
+// ---------------------------------------------------------------------------
+
+const GROUP = /^\([^()]*\)$/;
+const INTERCEPTING = /^\(\.{1,3}\)/;
+const SLOT = /^@/;
+const OPTIONAL_CATCH_ALL = /^\[\[\.\.\.([^\]]+)\]\]$/;
+const CATCH_ALL = /^\[\.\.\.([^\]]+)\]$/;
+const DYNAMIC = /^\[([^\].]+)\]$/;
+
+// Pure function of the relative route-file path. Returns null for a layout the
+// proxy cannot serve (parallel-route slots, intercepting routes); an optional
+// catch-all yields two templates.
+export function templatesForFile(file) {
+  const dirs = file.slice(API_PREFIX.length).split('/').slice(0, -1);
+  let templates = [{ segments: [], catchAll: false }];
+  for (const seg of dirs) {
+    if (SLOT.test(seg) || INTERCEPTING.test(seg)) return null;
+    if (GROUP.test(seg)) continue;
+    let m;
+    if ((m = OPTIONAL_CATCH_ALL.exec(seg))) {
+      templates = [
+        ...templates,
+        ...templates.map((t) => ({ segments: [...t.segments, `{${m[1]}}`], catchAll: true })),
+      ];
+    } else if ((m = CATCH_ALL.exec(seg))) {
+      templates = templates.map((t) => ({ segments: [...t.segments, `{${m[1]}}`], catchAll: true }));
+    } else if ((m = DYNAMIC.exec(seg))) {
+      templates = templates.map((t) => ({ ...t, segments: [...t.segments, `{${m[1]}}`] }));
+    } else {
+      templates = templates.map((t) => ({ ...t, segments: [...t.segments, seg] }));
+    }
+  }
+  return templates.map((t) => ({
+    template: t.segments.length ? `/${t.segments.join('/')}` : '',
+    ...(t.catchAll ? { catchAll: true } : {}),
+  }));
+}
+
+export function isReservedTemplate(template) {
+  return template
+    .split('/')
+    .filter(Boolean)
+    .some((seg) => RESERVED_SEGMENTS.includes(seg) || seg.startsWith(RESERVED_SEGMENT_PREFIX));
+}
+
+// `*` stays inside a segment, `**` crosses segments.
+function globToRegExp(glob) {
+  let re = '';
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === '*') {
+      if (glob[i + 1] === '*') {
+        re += '.*';
+        i++;
+      } else re += '[^/]*';
+    } else re += c.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+  }
+  return new RegExp(`^${re}$`);
+}
+
+function readPrivateRoutes(root) {
+  try {
+    const parsed = JSON.parse(readFileSync(path.join(root, APP_JSON_PATH), 'utf8'));
+    const list = parsed?.privateRoutes;
+    return Array.isArray(list) ? list.filter((g) => typeof g === 'string').map(globToRegExp) : [];
+  } catch {
+    return [];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Export analysis
+// ---------------------------------------------------------------------------
+
+const hasModifier = (ts, node, kind) => node.modifiers?.some((m) => m.kind === kind) ?? false;
+
+// Returns the exported handler bindings and whether the export surface is
+// opaque (`export *`, CommonJS) so names cannot be read statically.
+function analyseExports(ts, file, text) {
+  const sf = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, false, file.endsWith('x') ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+  const names = new Map(); // exported name -> initializer expression | null
+  let opaque = false;
+
+  const add = (name, init = null) => {
+    if (!names.has(name) || init) names.set(name, init);
+  };
+
+  // Initializers of local bindings, so `const GET = cronRoute(...); export { GET }`
+  // is still recognised as wrapped.
+  const locals = new Map();
+  for (const stmt of sf.statements) {
+    if (ts.isVariableStatement(stmt) && !hasModifier(ts, stmt, ts.SyntaxKind.ExportKeyword)) {
+      for (const decl of stmt.declarationList.declarations) {
+        if (ts.isIdentifier(decl.name) && decl.initializer) locals.set(decl.name.text, decl.initializer);
+      }
+    }
+  }
+
+  for (const stmt of sf.statements) {
+    if (ts.isFunctionDeclaration(stmt) && hasModifier(ts, stmt, ts.SyntaxKind.ExportKeyword) && stmt.name) {
+      add(stmt.name.text);
+    } else if (ts.isVariableStatement(stmt) && hasModifier(ts, stmt, ts.SyntaxKind.ExportKeyword)) {
+      for (const decl of stmt.declarationList.declarations) {
+        if (ts.isIdentifier(decl.name)) add(decl.name.text, decl.initializer ?? null);
+        else if (ts.isObjectBindingPattern(decl.name)) {
+          for (const el of decl.name.elements) if (ts.isIdentifier(el.name)) add(el.name.text);
+        }
+      }
+    } else if (ts.isExportDeclaration(stmt)) {
+      if (!stmt.exportClause) opaque = true; // export * from '...'
+      else if (ts.isNamedExports(stmt.exportClause)) {
+        for (const el of stmt.exportClause.elements) {
+          const local = stmt.moduleSpecifier ? null : locals.get((el.propertyName ?? el.name).text);
+          add(el.name.text, local ?? null);
+        }
+      } else if (ts.isNamespaceExport(stmt.exportClause)) opaque = true;
+    } else if (ts.isExpressionStatement(stmt) && ts.isBinaryExpression(stmt.expression)) {
+      const left = stmt.expression.left.getText(sf);
+      if (/^(?:module\.)?exports(?:\.|\[|$)/.test(left)) opaque = true;
+    }
+  }
+  return { names, opaque };
+}
+
+// The callee identifier of a handler initializer, matched by name only: no
+// resolution, so `export const POST = cronRoute(...)` is recognised without
+// following the import.
+function wrapperName(ts, init) {
+  let node = init;
+  while (node && (ts.isParenthesizedExpression(node) || ts.isAwaitExpression(node) || ts.isAsExpression(node) || ts.isSatisfiesExpression?.(node))) {
+    node = node.expression;
+  }
+  if (node && ts.isCallExpression(node) && ts.isIdentifier(node.expression)) return node.expression.text;
+  return null;
+}
+
+function nextConfigSetsBasePath(ts, file, text) {
+  const sf = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, false);
+  let found = false;
+  const visit = (node) => {
+    if (found) return;
+    if ((ts.isPropertyAssignment(node) || ts.isShorthandPropertyAssignment(node)) && node.name?.getText(sf) === 'basePath') {
+      found = true;
+      return;
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sf);
+  return found;
+}
+
+// ---------------------------------------------------------------------------
+// Scan
+// ---------------------------------------------------------------------------
+
+export function scanRoutes(root) {
+  const ts = loadTypeScript();
+  const all = listFiles(root);
+  const operations = [];
+  const excluded = [];
+  const warnings = [];
+  const routeFiles = [];
+  const contents = new Map();
+  const privateRoutes = readPrivateRoutes(root);
+
+  for (const file of all) {
+    if (UNSUPPORTED_ROUTE_FILE.test(file)) {
+      warnings.push({ code: 'unsupported_location', file, message: 'Route files are only read from app/api; this location is not served.' });
+    } else if (ROUTE_FILE_PREDICATE.test(file)) {
+      const templates = templatesForFile(file);
+      if (!templates) {
+        warnings.push({ code: 'unsupported_location', file, message: 'Parallel-route slots and intercepting routes are not served.' });
+      } else routeFiles.push({ file, templates });
+    }
+  }
+
+  for (const { file, templates } of routeFiles) {
+    const bytes = readFileSync(path.join(root, file));
+    contents.set(file, bytes);
+    const { names, opaque } = analyseExports(ts, file, bytes.toString('utf8'));
+
+    if (IGNORED_METHODS.some((m) => names.has(m))) {
+      warnings.push({ code: 'head_options_ignored', file, message: 'HEAD and OPTIONS exports are not proxied.' });
+    }
+
+    const wrapper = [...names.entries()]
+      .filter(([name]) => PROXY_METHODS.includes(name))
+      .map(([, init]) => (init ? wrapperName(ts, init) : null))
+      .find((w) => w && EXCLUDING_WRAPPERS.includes(w));
+
+    let methods;
+    let kind = 'static';
+    if (opaque) {
+      methods = ['ANY'];
+      kind = 'inferred';
+      warnings.push({ code: 'unresolved_export', file, message: 'Handlers are re-exported in a way that hides their names; recorded as ANY.' });
+    } else {
+      methods = PROXY_METHODS.filter((m) => names.has(m));
+    }
+
+    for (const { template, catchAll } of templates) {
+      const reason = isReservedTemplate(template)
+        ? 'reserved-segment'
+        : wrapper
+          ? `wrapper:${wrapper}`
+          : privateRoutes.some((re) => re.test(template))
+            ? 'private-routes'
+            : null;
+      if (reason) {
+        excluded.push({ template, file, reason });
+        continue;
+      }
+      for (const method of methods) {
+        operations.push({ method, template, file, ...(catchAll ? { catchAll: true } : {}), methods: kind });
+      }
+    }
+  }
+
+  for (const cfg of NEXT_CONFIG_FILES) {
+    if (!all.includes(cfg)) continue;
+    if (nextConfigSetsBasePath(ts, cfg, readFileSync(path.join(root, cfg), 'utf8'))) {
+      warnings.push({ code: 'base_path_set', file: cfg, message: 'basePath is set; route templates are not prefixed with it.' });
+    }
+  }
+
+  const files = routeFiles.map((r) => r.file);
+  const hashes = hashFiles(root, files, contents);
+
+  operations.sort((a, b) =>
+    byteCompare(a.template, b.template) || byteCompare(a.method, b.method) || byteCompare(a.file, b.file));
+  excluded.sort((a, b) => byteCompare(a.file, b.file) || byteCompare(a.template, b.template));
+  warnings.sort((a, b) => byteCompare(a.file, b.file) || byteCompare(a.code, b.code));
+
+  const sortedFiles = {};
+  for (const f of [...files].sort(byteCompare)) sortedFiles[f] = hashes.get(f);
+
+  return { schema: SCHEMA_VERSION, operations, excluded, warnings, files: sortedFiles };
+}
+
+export const serializeRoutes = (result) => JSON.stringify(result, null, 2) + '\n';

package/bin/scan.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+// The single per-turn scan entry point. The turn program runs this once on the
+// app's main checkout before each commit; adding another scanner means adding a
+// row to SCANNERS, not touching the turn program.
+//
+// Each scanner writes one `.assembly/*.json`, only when its bytes change so an
+// unchanged tree stays a no-op commit. Prints `{"warnings":[...]}` on stdout.
+// An app with no routes is not an error: it scans to an empty file and exits 0.
+import { mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { scanRoutes, serializeRoutes } from './scan-routes.mjs';
+
+const SCANNERS = [
+  {
+    name: 'routes',
+    output: '.assembly/routes.json',
+    run: (root) => {
+      const result = scanRoutes(root);
+      return { content: serializeRoutes(result), warnings: result.warnings };
+    },
+  },
+];
+
+function writeIfChanged(file, content) {
+  try {
+    if (readFileSync(file, 'utf8') === content) return;
+  } catch {
+    // Not there yet.
+  }
+  mkdirSync(path.dirname(file), { recursive: true });
+  // Rename so a crash mid-write can never leave a half file for `git add -A`.
+  const tmp = `${file}.tmp-${process.pid}`;
+  writeFileSync(tmp, content);
+  renameSync(tmp, file);
+}
+
+export function runScanners(root = process.cwd()) {
+  // Every scanner runs before any file is written, so one throwing leaves all
+  // previous outputs intact rather than a mix of old and new.
+  const results = SCANNERS.map((scanner) => ({ scanner, ...scanner.run(root) }));
+  const warnings = [];
+  for (const { scanner, content, warnings: found } of results) {
+    writeIfChanged(path.join(root, scanner.output), content);
+    warnings.push(...found.map((w) => ({ scanner: scanner.name, ...w })));
+  }
+  return { warnings };
+}
+
+// argv[1] is not realpathed but import.meta.url is, so a symlinked path would skip the run.
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+  try {
+    process.stdout.write(JSON.stringify(runScanners()) + '\n');
+  } catch (err) {
+    console.error(`scan: ${err && err.stack ? err.stack : err}`);
+    process.exit(1);
+  }
+}

package/bin/validate-manifest.mjs

@@ -11,7 +11,7 @@ const MANIFEST = join(process.cwd(), '.assembly', 'app.json');
 // requiredIntegrations and notificationSettings are parsed by the platform's
 // deploy pipeline; rejecting them here would fail builds for manifests the
 // platform understands.
-const TOP_LEVEL_KEYS = ['surfaces', 'requiredSecrets', 'requiredIntegrations', 'notificationSettings'];
+const TOP_LEVEL_KEYS = ['surfaces', 'requiredSecrets', 'requiredIntegrations', 'notificationSettings', 'privateRoutes'];
 const SURFACE_KEYS = ['internal', 'client', 'notification'];
 const NOTIFICATION_SURFACES = ['product', 'email'];
 const MAX_NOTIFICATION_SETTINGS = 50;
@@ -34,7 +34,7 @@ function fail(lines) {
   console.error('    "requiredIntegrations": [{ "provider": "slack", "scopes": ["chat:write"] }]');
   console.error('  }');
   console.error('Only "internal" is required. "client" and "notification" are optional and MUST live under "surfaces".');
-  console.error('Optional top-level keys: "requiredSecrets", "requiredIntegrations", "notificationSettings" (schemas in .claude/skills).');
+  console.error('Optional top-level keys: "requiredSecrets", "requiredIntegrations", "notificationSettings", "privateRoutes" (schemas in .claude/skills).');
   process.exit(1);
 }
 
@@ -242,6 +242,21 @@ if (doc.notificationSettings !== undefined) {
   }
 }
 
+// privateRoutes (optional; a list of glob strings scan-routes.mjs matches
+// against route templates to exclude them from cross-app exposure).
+if (doc.privateRoutes !== undefined) {
+  const pr = doc.privateRoutes;
+  if (!Array.isArray(pr)) {
+    errors.push('"privateRoutes" must be an array.');
+  } else {
+    pr.forEach((item, i) => {
+      if (typeof item !== 'string') {
+        errors.push('privateRoutes[' + i + '] must be a string (a glob like "/internal/**").');
+      }
+    });
+  }
+}
+
 // requiredIntegrations (optional; mirrors the deploy-side structural rules —
 // the provider whitelist itself is enforced at deploy from the live catalog).
 // connectionScope/cardinality are reserved hinges: only their v1 values pass,

package/dist/app-storage.js

@@ -1,9 +1,21 @@
 import { getAssembly } from './assembly.js';
+// A bearer token is a JWT: three base64url segments separated by dots, the
+// first always decoding to a JSON header (so it starts with 'eyJ'). Matching
+// the whole-string shape — not just the 'eyJ' prefix — avoids rejecting a
+// legitimate file name or storage key that happens to start with 'eyJ'.
+const JWT_SHAPE = /^eyJ[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+$/;
 // fileName must be a bare file name (e.g. 'invoice.pdf'), never a path:
 // the platform rejects any value containing '/' or '..'. Do NOT prefix
 // folders or construct the S3 key yourself — the platform scopes the key
 // to the workspace and makes it unique. Store the key it returns.
+// NOTE: takes ONE argument. If you are calling this as getUploadUrl(token, fileName)
+// (the old two-arg shape), remove the token — auth is in the bearer cookie.
 export async function getUploadUrl(fileName) {
+    // Catches the old (token, fileName) call shape where a JWT ends up as the file name.
+    if (JWT_SHAPE.test(fileName)) {
+        throw new Error('getUploadUrl: first argument looks like a session token. ' +
+            'The token argument was removed — call getUploadUrl(fileName) with the file name only.');
+    }
     const assembly = await getAssembly();
     const res = await assembly.fetch('/v1/app-storage/upload-url', {
         method: 'POST',
@@ -13,7 +25,14 @@ export async function getUploadUrl(fileName) {
         throw new Error('Upload URL request failed: ' + res.status);
     return res.json();
 }
+// NOTE: takes ONE argument. If you are calling this as getDownloadUrl(token, key)
+// (the old two-arg shape), remove the token — auth is in the bearer cookie.
 export async function getDownloadUrl(key) {
+    // Catches the old (token, key) call shape where a JWT ends up as the storage key.
+    if (JWT_SHAPE.test(key)) {
+        throw new Error('getDownloadUrl: first argument looks like a session token. ' +
+            'The token argument was removed — call getDownloadUrl(key) with the storage key only.');
+    }
     const assembly = await getAssembly();
     const res = await assembly.fetch('/v1/app-storage/download-url?key=' + encodeURIComponent(key));
     if (!res.ok)

package/dist/lib-client.d.ts

@@ -1,5 +1,6 @@
 export declare function reexchangeBearer(): Promise<boolean>;
 export declare function authFetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+export declare function downloadViaBlob(url: string, filename: string): Promise<void>;
 /**
  * Mint an in-memory bearer at load when the browser is refusing to store the
  * cookie, so the first client-side navigation is already authenticated instead

package/dist/lib-client.js

@@ -126,6 +126,28 @@ export async function authFetch(input, init) {
     }
     return fetch(input, { ...init, headers });
 }
+// Downloads a file from url via authFetch (bearer cookie, same-origin), then
+// triggers a browser download without opening a new tab. Use this instead of
+// window.open or <a download href=url>: a new top-level tab is a different cookie
+// partition under CHIPS, so the bearer is absent and the route 401s.
+export async function downloadViaBlob(url, filename) {
+    const res = await authFetch(url);
+    if (!res.ok)
+        throw new Error(`Download failed: ${res.status}`);
+    const blob = await res.blob();
+    const objectUrl = URL.createObjectURL(blob);
+    try {
+        const a = document.createElement('a');
+        a.href = objectUrl;
+        a.download = filename;
+        document.body.appendChild(a);
+        a.click();
+        document.body.removeChild(a);
+    }
+    finally {
+        URL.revokeObjectURL(objectUrl);
+    }
+}
 /**
  * Mint an in-memory bearer at load when the browser is refusing to store the
  * cookie, so the first client-side navigation is already authenticated instead

package/package.json

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

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

@@ -5,6 +5,8 @@ description: Use for every app/api/.../[id]/route.ts handler — GET and write a
 
 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.
+
 ```ts
 import { requireAuth, requireCompanyScope, handleRouteError } from '@assembly-js/app-foundation/server';
 ```

package/skills/assembly-storage/SKILL.md

@@ -13,8 +13,8 @@ Use app-storage for files that belong to YOUR app. For files the user expects to
 
 **Both helpers ship in `@assembly-js/app-foundation/server`, an installed dependency** — import them; do NOT recreate or rewrite them:
 
-- `getUploadUrl(fileName)` → `{ key, uploadUrl }` — POSTs `{ fileName }` to the platform.
-- `getDownloadUrl(key)` → `{ downloadUrl }` — mints a fresh pre-signed GET.
+- `getUploadUrl(fileName)` → `{ key, uploadUrl }` — POSTs `{ fileName }` to the platform. Takes **one argument** (the file name only). If you were calling it as `getUploadUrl(token, fileName)` (an old two-arg shape), remove the token — auth is in the bearer cookie and the function will throw if a token is passed as the file name.
+- `getDownloadUrl(key)` → `{ downloadUrl }` — mints a fresh pre-signed GET. Takes **one argument** (the storage key only). Same note: remove any leading token argument.
 
 Store the `key` it returns; never construct an S3 key yourself, and never parse the original file name back out of the key — the platform normalizes the name when forming the key, so the stored `key` is not guaranteed to contain your exact `fileName`. Keep the display name as your own metadata (see "Storing and downloading"). `fileName` must be a bare file name (`invoice.pdf`), never a path — the platform rejects any fileName containing `/` or `..`. Don't prefix folders or namespaces onto it; the platform already scopes the key to the workspace and makes it unique. If you need grouping, store that in your own database alongside the key.
 
@@ -26,7 +26,7 @@ The pre-signed URL does not lock the `Content-Type`, so any value works — set
 
 ```typescript
 'use client';
-import { authFetch } from './lib-client';
+import { authFetch } from '@/app/components/lib-client';
 
 export async function uploadFile(file: File) {
   const res = await authFetch('/api/app-storage/upload-url', {
@@ -70,7 +70,9 @@ export async function POST(request: NextRequest) {
 
 Save the returned `key` (plus any metadata like `fileName`/`size`) in your app's own database. Pre-signed download URLs expire within hours, so generate them on demand — never embed one in rendered HTML or a cached server component.
 
-Create a route that returns the pre-signed URL as JSON, then trigger the download from a client component via `authFetch` + a programmatic anchor click. `authFetch` adds the CSRF header and the bearer rides the cookie, so the download route stays authenticated without any token in the URL.
+### Pattern A — route returns a pre-signed S3 URL (no proxy of bytes)
+
+Create a route that returns the pre-signed URL as JSON, then open that URL via a programmatic anchor click. The pre-signed URL carries S3 credentials directly, so no auth cookie is needed to access S3. Use `authFetch` only for the initial request to get the URL.
 
 **Route handler** (`app/api/app-storage/download/route.ts`):
 
@@ -92,6 +94,8 @@ export async function GET(request: NextRequest) {
 **Client-side download trigger:**
 
 ```typescript
+import { authFetch } from '@/app/components/lib-client';
+
 async function downloadFile(key: string) {
   const res = await authFetch(`/api/app-storage/download?key=${encodeURIComponent(key)}`);
   if (!res.ok) throw new Error('Failed to get download URL');
@@ -106,7 +110,18 @@ async function downloadFile(key: string) {
 }
 ```
 
-Do NOT use `<a href>` links to the download route — plain links can't send the CSRF header `authFetch` adds, so the route rejects them with 403. Always use a button with an `onClick` that calls `authFetch`.
+### Pattern B — route returns bytes directly (use `downloadViaBlob`)
+
+When your route fetches from S3 and streams the bytes back instead of a pre-signed URL, use `downloadViaBlob` from `app/components/lib-client.ts`. It calls `authFetch`, reads `res.blob()`, and triggers the download via a programmatic anchor — the bearer cookie is sent because the fetch is same-origin, avoiding the CHIPS partition problem that breaks `window.open` and `<a download href=…>` to a new tab.
+
+```typescript
+import { downloadViaBlob } from '@/app/components/lib-client';
+
+// In a button onClick handler:
+await downloadViaBlob(`/api/items/${id}/download`, 'report.pdf');
+```
+
+Do NOT use `<a href>` links to the download route — plain links can't send the CSRF header `authFetch` adds, so the route rejects them with 403. Always use a button with an `onClick` that calls `authFetch` or `downloadViaBlob`.
 
 ## Server needs the bytes (parse / process an uploaded file)