@assembly-js/app-foundation 0.3.3 → 0.3.5

package/CHANGELOG.md

@@ -19,6 +19,12 @@ 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.3.5
+- [behavior] At the end of every turn the platform records which other apps' operations the app calls by literal API path in `.assembly/app-deps.json`. Publishing an app that other apps depend on is refused while that file is out of date. Nothing in the app changes.
+
+## 0.3.4
+- [guidance] The build agent is now taught to authenticate inbound webhook calls inside the route, fail closed when the secret is unset, and never add an unauthenticated test endpoint.
+
 ## 0.3.3
 - [new] `notifyInternalUsers` (from `@assembly-js/app-foundation/server`) notifies every internal user, or a given `recipientIds` list, on behalf of the current viewer using the installer client.
 - [guidance] The notifications skill now directs every client-triggered send to staff through `notifyInternalUsers`, since a client's own `getAssembly()` client cannot create notifications or list staff.

package/CLAUDE.md

@@ -1037,6 +1037,8 @@ async function saveFlavor(clientId: string, flavor: string) {
 
 Every state-changing request (POST/PUT/PATCH/DELETE) **must** go through `authFetch` (or a Next server action) — a plain `fetch` is rejected with 403 (CSRF). Never put a token or the bearer in a URL or a manual header; the cookie carries it.
 
+In current apps `proxy.ts` lets a request that carries no cookies skip the CSRF check, so an inbound third-party call (a webhook) needs no proxy change; an older `proxy.ts` without that rule still answers 403 to a header-less POST. Authenticate the caller inside the route (signature or shared secret), fail closed when its secret is unset, and never add an unauthenticated test endpoint.
+
 #### Route handlers — `getAssemblyForRequest`
 
 ```ts

package/bin/scan-app-deps.mjs

@@ -0,0 +1,201 @@
+// Finds which other apps' operations an app calls by literal proxy path and
+// describes them as `.assembly/app-deps.json`, so publish reads one file
+// instead of Go parsing TypeScript.
+//
+// A second projection beside scan-client-calls: it reuses that detector's
+// parse setup and `fetch` method reading, but looks for literals rather than
+// SDK receivers. A path is reported when the file alone fixes it: a literal, or a
+// template or `+` built from literals and same-file string consts (the usual way an
+// app names the provider's id). Anything else is computed and left to observed traffic.
+//
+// `files` hashes every .ts/.tsx, not only the ones with a hit, so Go can tell
+// a new file the scan never saw from one it saw and found irrelevant.
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { literalFetchMethod, scriptKind } from './scan-client-calls.mjs';
+import { PROXY_METHODS, byteCompare, hashFiles, listFiles, loadTypeScript } from './scan-routes.mjs';
+
+export const APP_DEPS_OUTPUT = '.assembly/app-deps.json';
+export const CODE_SCAN_FAILED = 'app_deps_scan_failed';
+
+// Mirrored in Go (appdepsfile): the one place a scanned source file is recognised.
+const SOURCE_FILE = /\.tsx?$/;
+const PREFILTER = ['/v1/apps/', 'generated/apps/'];
+const PROXY_PATH = /^\/v1\/apps\/([^/?#]+)\/api(?:\/([^?#]*))?(?:[?#].*)?$/;
+const VIA_PROXY_PATH = 'proxy-path';
+// One file per installed provider app, written by the platform; each operation carries
+// `- Method: \`X\`` then `- Path: \`/t\``. Absent for a provider that is not callable.
+const PROVIDER_DOCS_DIR = '.assembly/docs/apps';
+const DOC_OPERATION = /^- Method: `([A-Z]+)`\n- Path: `([^`]+)`$/m;
+const DOC_CATCH_ALL = 'This operation is a catch-all.';
+// An inferred route (handlers the scan could not name) has no method to record.
+const INFERRED_METHOD = 'ANY';
+const TEMPLATE_PARAM = /^\{[^}]+\}$/;
+const CLIENT_VERBS = new Set(['get', 'post', 'put', 'patch', 'delete']);
+
+const isLiteral = (ts, n) => ts.isStringLiteral(n) || ts.isNoSubstitutionTemplateLiteral(n);
+
+// The method a literal's call site states, or null when it is not evident.
+function callSiteMethod(ts, literal) {
+  const call = literal.parent;
+  if (!ts.isCallExpression(call) || call.arguments[0] !== literal) return null;
+  const callee = call.expression;
+  const name = ts.isIdentifier(callee) ? callee.text : ts.isPropertyAccessExpression(callee) ? callee.name.text : null;
+  if (name === 'fetch') return literalFetchMethod(ts, call.arguments[1])?.toUpperCase() ?? null;
+  return CLIENT_VERBS.has(name) && ts.isPropertyAccessExpression(callee) ? name.toUpperCase() : null;
+}
+
+// A name the file binds exactly once, as a `const` initialised with a literal, is the string
+// it spells; any other binding of the same name (a `let`, a parameter) may shadow it.
+function constStrings(ts, sf) {
+  const bindings = new Map(); // name -> declaration, or null once bound a second time
+  const bind = (name, decl) => bindings.set(name, bindings.has(name) ? null : decl);
+  const walk = (node) => {
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name)) bind(node.name.text, node);
+    else if (ts.isParameter(node) && ts.isIdentifier(node.name)) bind(node.name.text, null);
+    ts.forEachChild(node, walk);
+  };
+  walk(sf);
+  const values = new Map();
+  const resolve = (node) => resolveString(ts, node, values);
+  // Source order, so a const built from an earlier one resolves too.
+  for (const [name, decl] of bindings) {
+    if (!decl || !(decl.parent.flags & ts.NodeFlags.Const) || !decl.initializer) continue;
+    const value = resolve(decl.initializer);
+    if (value !== null) values.set(name, value);
+  }
+  return values;
+}
+
+// The string an expression always evaluates to, or null when any part of it is not known.
+function resolveString(ts, node, consts) {
+  if (isLiteral(ts, node)) return node.text;
+  if (ts.isParenthesizedExpression(node) || ts.isAsExpression(node)) return resolveString(ts, node.expression, consts);
+  if (ts.isIdentifier(node)) return consts.get(node.text) ?? null;
+  if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.PlusToken) {
+    const [left, right] = [resolveString(ts, node.left, consts), resolveString(ts, node.right, consts)];
+    return left !== null && right !== null ? left + right : null;
+  }
+  if (ts.isTemplateExpression(node)) {
+    let out = node.head.text;
+    for (const span of node.templateSpans) {
+      const value = resolveString(ts, span.expression, consts);
+      if (value === null) return null;
+      out += value + span.literal.text;
+    }
+    return out;
+  }
+  return null;
+}
+
+function collectDeps(ts, file, text) {
+  const sf = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, scriptKind(ts, file));
+  const consts = constStrings(ts, sf);
+  const found = [];
+  const visit = (node) => {
+    // A bare name is read where its const is declared, not at every use.
+    const value = ts.isIdentifier(node) ? null : resolveString(ts, node, consts);
+    if (value !== null) {
+      const match = PROXY_PATH.exec(value);
+      // `'/v1/apps/x/api/items/' + id` is only the start of a path.
+      const concatenated = ts.isBinaryExpression(node.parent) && node.parent.left === node;
+      // `const BASE = `/v1/apps/${id}/api`` names the provider, it does not call its root.
+      const base = ts.isVariableDeclaration(node.parent) && !match?.[2];
+      // The proxy drops one trailing slash before routing.
+      const template = `/${match?.[2] ?? ''}`.replace(/(.)\/$/, '$1');
+      if (match && !concatenated && !base) found.push({ appId: match[1], template, method: callSiteMethod(ts, node) });
+      // A resolved expression is one path: its parts are not separate calls.
+      return;
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sf);
+  return found;
+}
+
+function providerOps(root, appId) {
+  try {
+    const doc = readFileSync(path.join(root, PROVIDER_DOCS_DIR, `${appId}.md`), 'utf8');
+    return doc.split(/\n(?=#{3,4} )/).flatMap((section) => {
+      const m = DOC_OPERATION.exec(section);
+      return m ? [{ method: m[1], template: m[2], catchAll: section.includes(DOC_CATCH_ALL) }] : [];
+    });
+  } catch {
+    return null;
+  }
+}
+
+// A `{param}` segment in the provider's template stands for any one segment of the call; the
+// last one of a catch-all stands for one or more.
+const templateMatches = ({ template, catchAll }, literal) => {
+  const a = template.split('/');
+  const b = literal.split('/');
+  if (!(catchAll ? b.length >= a.length : b.length === a.length)) return false;
+  return a.every((seg, i) => seg === b[i] || TEMPLATE_PARAM.test(seg));
+};
+
+// The proxy serves the most specific route: per segment static, then dynamic, then catch-all.
+const specificity = ({ template, catchAll }, literal) => {
+  const a = template.split('/');
+  return literal.split('/').map((_, i) => {
+    if (i >= a.length || (catchAll && i === a.length - 1)) return 2;
+    return TEMPLATE_PARAM.test(a[i]) ? 1 : 0;
+  });
+};
+const bySpecificity = (literal) => (x, y) => {
+  const [a, b] = [specificity(x, literal), specificity(y, literal)];
+  const i = a.findIndex((r, k) => r !== b[k]);
+  return i < 0 ? 0 : a[i] - b[i];
+};
+
+// The ops one literal path stands for: the provider's winning template with every method it
+// exposes, or the literal path itself when the provider's operations are not on disk.
+function opsFor(provider, { template, method }) {
+  const matched = (provider ?? []).filter((op) => templateMatches(op, template)).sort(bySpecificity(template));
+  if (matched.length === 0) return (method ? [method] : PROXY_METHODS).map((m) => `${m} ${template}`);
+  const winner = matched.filter((op) => op.template === matched[0].template);
+  if (winner.every((op) => op.method === INFERRED_METHOD)) return [];
+  if (method) return [`${method} ${winner[0].template}`];
+  return winner.filter((op) => op.method !== INFERRED_METHOD).map((op) => `${op.method} ${op.template}`);
+}
+
+export function scanAppDeps(root, { loadTs = loadTypeScript } = {}) {
+  const files = listFiles(root).filter((f) => SOURCE_FILE.test(f)).sort(byteCompare);
+  const contents = new Map(files.map((f) => [f, readFileSync(path.join(root, f))]));
+  const candidates = files.filter((f) => PREFILTER.some((s) => contents.get(f).includes(s)));
+  const ops = new Map(); // appId -> Set of "<METHOD> <template>"
+  const providers = new Map(); // appId -> provider operations, or null
+  // Loaded only when there is something to parse, but a missing typescript must
+  // still stop the file being written for a tree that has candidates.
+  const ts = candidates.length ? loadTs() : null;
+  for (const file of candidates) {
+    for (const dep of collectDeps(ts, file, contents.get(file).toString('utf8'))) {
+      if (!ops.has(dep.appId)) ops.set(dep.appId, new Set());
+      if (!providers.has(dep.appId)) providers.set(dep.appId, providerOps(root, dep.appId));
+      for (const op of opsFor(providers.get(dep.appId), dep)) ops.get(dep.appId).add(op);
+    }
+  }
+  const apps = {};
+  for (const appId of [...ops.keys()].filter((id) => ops.get(id).size).sort(byteCompare)) {
+    apps[appId] = { ops: [...ops.get(appId)].sort(byteCompare), via: [VIA_PROXY_PATH] };
+  }
+  const hashes = hashFiles(root, files, contents);
+  return { apps, files: Object.fromEntries(files.map((f) => [f, hashes.get(f)])) };
+}
+
+export const serializeAppDeps = (result) => JSON.stringify(result, null, 2) + '\n';
+
+// Plug-in row for bin/scan.mjs. Any failure returns a warning and no content,
+// so the previous file stays and publish sees it as stale rather than trusting
+// a scan that did not finish.
+export const appDepsScanner = {
+  name: 'app-deps',
+  output: APP_DEPS_OUTPUT,
+  run: (root, options) => {
+    try {
+      return { content: serializeAppDeps(scanAppDeps(root, options)), warnings: [] };
+    } catch (err) {
+      return { warnings: [{ code: CODE_SCAN_FAILED, message: `${err && err.message ? err.message : err}` }] };
+    }
+  },
+};

package/bin/scan-client-calls.mjs

@@ -163,6 +163,22 @@ const isViewerSource = (name) =>
 
 const lineOf = (sf, node) => sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
 
+// The HTTP method a `fetch` init object states, shared with the cross-app scan. A missing init or
+// method option is a GET; null means the method is not statically evident.
+export function literalFetchMethod(ts, init) {
+  const literal = (n) => n && (ts.isStringLiteral(n) || ts.isNoSubstitutionTemplateLiteral(n));
+  if (!init) return DEFAULT_FETCH_HTTP_METHOD;
+  if (!ts.isObjectLiteralExpression(init)) return null;
+  let method = DEFAULT_FETCH_HTTP_METHOD;
+  for (const prop of init.properties) {
+    if (ts.isSpreadAssignment(prop) || (prop.name && ts.isComputedPropertyName(prop.name))) return null;
+    if (prop.name?.text !== 'method') continue;
+    if (!ts.isPropertyAssignment(prop) || !literal(prop.initializer)) return null;
+    method = prop.initializer.text;
+  }
+  return method;
+}
+
 class Scope {
   constructor(parent) {
     this.parent = parent;
@@ -174,7 +190,7 @@ class Scope {
   }
 }
 
-function scriptKind(ts, file) {
+export function scriptKind(ts, file) {
   if (/\.(?:tsx|jsx)$/.test(file)) return ts.ScriptKind.TSX;
   return /\.[cm]?js$/.test(file) ? ts.ScriptKind.JS : ts.ScriptKind.TS;
 }
@@ -206,16 +222,8 @@ export function collectFileFacts(ts, file, text, sdkMethods = null, localExports
   const fetchRoute = (call) => {
     const [pathArg, init] = call.arguments;
     if (!isLiteralText(pathArg)) return null;
-    let method = DEFAULT_FETCH_HTTP_METHOD;
-    if (init) {
-      if (!ts.isObjectLiteralExpression(init)) return null;
-      for (const prop of init.properties) {
-        if (ts.isSpreadAssignment(prop) || (prop.name && ts.isComputedPropertyName(prop.name))) return null;
-        if (prop.name?.text !== 'method') continue;
-        if (!ts.isPropertyAssignment(prop) || !isLiteralText(prop.initializer)) return null;
-        method = prop.initializer.text;
-      }
-    }
+    const method = literalFetchMethod(ts, init);
+    if (method === null) return null;
     // The SDK prepends the slash a path is missing, so `v1/me` requests `/v1/me`.
     const routePath = pathArg.text.startsWith('/') ? pathArg.text : `/${pathArg.text}`;
     return { path: routePath.replace(/[?#].*$/, ''), method };

package/bin/scan-routes.mjs

@@ -80,7 +80,7 @@ const gitBlobSha = (bytes) =>
 // `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) {
+export 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();

package/bin/scan.mjs

@@ -9,6 +9,7 @@
 import { mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { appDepsScanner } from './scan-app-deps.mjs';
 import { clientCallScanner } from './scan-client-calls.mjs';
 import { scanRoutes, serializeRoutes } from './scan-routes.mjs';
 
@@ -21,6 +22,7 @@ const SCANNERS = [
       return { content: serializeRoutes(result), warnings: result.warnings };
     },
   },
+  appDepsScanner,
 ];
 
 // Scanners whose result goes to the caller, not to a committed file. They run
@@ -48,8 +50,9 @@ export function runScanners(root = process.cwd(), scanners = SCANNERS) {
   const warnings = [];
   const outputs = {};
   for (const { scanner, content, result, warnings: found } of results) {
-    if (scanner.output) writeIfChanged(path.join(root, scanner.output), content);
-    else outputs[scanner.name] = result;
+    // A scanner that failed has no content; its previous file stays, so publish sees it as stale.
+    if (scanner.output && content !== undefined) writeIfChanged(path.join(root, scanner.output), content);
+    else if (!scanner.output) outputs[scanner.name] = result;
     warnings.push(...found.map((w) => ({ scanner: scanner.name, ...w })));
   }
   return { warnings, outputs };

package/package.json

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