@assembly-js/app-foundation 0.0.28 → 0.0.30

package/CLAUDE.md

@@ -20,7 +20,7 @@ When a request implies a scope or permission change, apply it and report the pro
 
 Assembly-specific gotchas live in `.claude/skills/<name>/SKILL.md`. Invoke them by name as you reach for the relevant concept — don't re-read this file's general sections when a skill exists. Available skills:
 
-- `assembly-internal-users` — staff in the Dashboard; Client Access permissions (`isClientAccessLimited`, `companyAccessList`) and scoping internal views to allowed companies
+- `assembly-internal-users` — staff in the Dashboard; workspace role (`admin` or `staff`) for admin-only features; Client Access permissions (`isClientAccessLimited`, `companyAccessList`) and scoping internal views to allowed companies
 - `assembly-client-users` — customers in the Client Portal
 - `assembly-companies` — many-to-many with clients; placeholder companies (excluded from `listCompanies` by default for these apps)
 - `assembly-clients-companies` — REQUIRED when the app stores or scopes data by client or company: scoped tables carry BOTH a `clientId` and a `companyId` column and are filtered on the intersection (never one dimension); a client viewer always has an active `companyId`; `companyIds[]` builds pickers only and `client.companyId` is deprecated

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/client-access.d.ts

@@ -3,6 +3,11 @@ export interface ClientAccessScope {
     isLimited: boolean;
     allowedCompanyIds: Set<string>;
 }
+export interface InternalUserAccess {
+    isWorkspaceAdmin: boolean;
+    scope: ClientAccessScope;
+}
+export declare function getInternalUserAccess(internalUserId: string, tokenOrAssembly?: string | AssemblyAPI): Promise<InternalUserAccess>;
 export declare function getClientAccessScope(internalUserId: string, tokenOrAssembly?: string | AssemblyAPI): Promise<ClientAccessScope>;
 export declare function canAccessCompanies(scope: ClientAccessScope, companyIds: string[] | null | undefined): boolean;
 export declare function canAccessClient<T extends {

package/dist/client-access.js

@@ -9,17 +9,16 @@ const DENY_ALL = {
     isLimited: true,
     allowedCompanyIds: new Set(),
 };
-// Resolves the Client Access scope for an internal user.
-//
-// Fails closed: if the lookup fails we return DENY_ALL rather than treating the
-// viewer as unrestricted. An unverified viewer must not be handed the access of
-// a full-access one — the caller sees empty lists (or a 404 via
+const NO_ACCESS = { isWorkspaceAdmin: false, scope: DENY_ALL };
+// Fails closed: if the lookup fails we return NO_ACCESS rather than treating the
+// viewer as an unrestricted admin. An unverified viewer must not be handed the
+// access of a full-access one — the caller sees empty lists (or a 404 via
 // canAccessCompanies) instead of another workspace member's data. Callers that
 // prefer to surface a transient failure should catch it upstream and retry.
 //
-// The session token carries only `internalUserId`, never the access fields, so
-// this costs one `retrieveInternalUser` per request that needs it.
-export async function getClientAccessScope(internalUserId, tokenOrAssembly) {
+// The session token carries only `internalUserId`, never the role or access
+// fields, so this costs one `retrieveInternalUser` per request that needs it.
+export async function getInternalUserAccess(internalUserId, tokenOrAssembly) {
     try {
         // Same narrowing as requireCompanyScope: a session token string on the
         // legacy path, an already-authenticated instance on the bearer path.
@@ -27,17 +26,19 @@ export async function getClientAccessScope(internalUserId, tokenOrAssembly) {
             ? await getAssembly(tokenOrAssembly)
             : tokenOrAssembly;
         const user = await assembly.retrieveInternalUser({ id: internalUserId });
-        if (user.isClientAccessLimited !== true)
-            return UNRESTRICTED;
-        return {
-            isLimited: true,
-            allowedCompanyIds: new Set(user.companyAccessList ?? []),
-        };
+        const scope = user.isClientAccessLimited === true
+            ? { isLimited: true, allowedCompanyIds: new Set(user.companyAccessList ?? []) }
+            : UNRESTRICTED;
+        return { isWorkspaceAdmin: user.role === 'admin', scope };
     }
     catch {
-        return DENY_ALL;
+        return NO_ACCESS;
     }
 }
+// Resolves only the Client Access scope, for callers that never gate on role.
+export async function getClientAccessScope(internalUserId, tokenOrAssembly) {
+    return (await getInternalUserAccess(internalUserId, tokenOrAssembly)).scope;
+}
 // True when the viewer may see a resource belonging to any of `companyIds`.
 //
 // Mirrors the platform's own users.User.IsAccessAllowed: access is company-scoped,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assembly-js/app-foundation",
-  "version": "0.0.28",
+  "version": "0.0.30",
   "description": "Versioned foundation helpers and build context for Assembly generated apps",
   "type": "module",
   "files": [
@@ -43,7 +43,7 @@
   },
   "devDependencies": {
     "@assembly-js/app-bridge": "1.3.0",
-    "@assembly-js/node-sdk": "4.2.3-beta.2",
+    "@assembly-js/node-sdk": "4.2.4",
     "@types/bun": "^1.1.0",
     "@types/node": "^22",
     "next": "^15.5.0",

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

@@ -1,6 +1,6 @@
 ---
 name: assembly-internal-users
-description: Use when the app reads/lists internal users, or an internal viewer browses clients/companies in the Dashboard. Covers Client Access (isClientAccessLimited, companyAccessList) scoping. Internal users sign into the Dashboard only. Detect via tokenPayload.internalUserId.
+description: Use when the app reads/lists internal users, gates a feature to workspace admins (role is "admin" or "staff"), or an internal viewer browses clients/companies in the Dashboard. Covers Client Access (isClientAccessLimited, companyAccessList) scoping. Internal users sign into the Dashboard only. Detect via tokenPayload.internalUserId.
 ---
 
 Internal users are the **business team** running the Assembly workspace. They sign into the Dashboard at the workspace's domain, never the branded Client Portal. They have full read/write power over clients, companies, files, etc. — **within their Client Access scope** (see below).
@@ -23,6 +23,24 @@ If `internalUserId` is set, the current viewer is staff. (`clientId` is set for
 - `listInternalUsers({ nextToken, limit })` — paged list of all staff in the workspace
 - `retrieveInternalUser({ id })` — single record by id
 
+## Workspace role — admins vs staff
+
+Every internal user has a workspace role: `"admin"` or `"staff"`. The workspace owner is an admin. When the app has admin-only features ("admins manage templates", "only admins can change settings"), gate them on this role. Do not invent an app-level role table or admin list for this, and never leave the check stubbed off until a role source is "confirmed": this is the role source.
+
+```ts
+import { getInternalUserAccess, getSessionIdentity } from '@assembly-js/app-foundation/server';
+
+const identity = await getSessionIdentity();
+if (!identity?.internalUserId) return { ok: false, message: 'Only your team can manage templates.' };
+
+const access = await getInternalUserAccess(identity.internalUserId);
+if (!access.isWorkspaceAdmin) {
+  return { ok: false, message: 'Only workspace admins can manage templates.' };
+}
+```
+
+Apply the same check on the server action or route, not only in the UI. `access.scope` is the viewer's Client Access scope from the same lookup (below). If the app needs its own job titles beyond admin and staff (approver, manager), store those in the app; workspace admins must still be able to manage them.
+
 ## Client Access permissions
 
 Client Access is a **workspace-level** setting (configured in workspace settings, not inside your app). By default every internal user can see all clients and companies. Admins can limit an internal user to specific companies; that limit ripples through the platform.
@@ -36,7 +54,7 @@ Access is **company-scoped**: a limited user can see a client iff **any** of the
 
 ## Pre-built helpers
 
-`@assembly-js/app-foundation/server` exports these — import them, do not rewrite the check.
+`@assembly-js/app-foundation/server` exports these — import them, do not rewrite the check. When the request also needs the admin check, call `getInternalUserAccess` once and use its `scope` instead of a second lookup.
 
 ```ts
 import {

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';
 ```