@assembly-js/app-foundation 0.2.4 → 0.2.5

package/CHANGELOG.md

@@ -15,7 +15,12 @@ from every bullet except `[guidance]`, agent work from the check scripts those `
 bullets ship. Write `[fix]`, `[behavior]` and `[action]` bullets for the app's owner.
 
 A patch release never changes what an app's build requires; a minor release may add or change a
-`bin/check-*.mjs` script. CI fails a PR that changes a check script without a minor bump over main.
+`bin/check-*.mjs` script. Sections are written by the release workflow from the files in `changes/`,
+not by hand; see `changes/README.md`. CI fails a PR that changes a check script without a
+`bump: minor` change file.
+
+## 0.2.5
+- [new] The client-call scan no longer reports reading the session's token details, a client's allowed fetch routes, or a harmless local namespace import as breaking; nothing in the app changes.
 
 ## 0.2.4
 - [new] Add `@assembly-js/app-foundation/codegen`, which turns another app's API description into a typed client the app can call by verb and path, and `appProxyOptions` in `/server`, which that client uses to reach the other app through the platform. Nothing in the app changes until a client is generated for it.

package/bin/client-safe-sdk-methods.mjs

@@ -1,28 +1,38 @@
-// The routes a client bearer may keep calling once clients stop acting as admin,
-// as SDK method names (the SDK is flat: `retrieveClient`, not `clients.retrieve`).
+// The routes a client bearer may keep calling once clients stop acting as admin.
 // Mirrors every route the platform marks with ClientAccessOpen, ClientAccessSelf or
 // ClientAccessGuarded under backend/platform-api; scan-client-calls.test.mjs fails when
-// the marker count drifts from this list.
-//
-//   GET  /v1/me                         -> retrieveMe
-//   GET  /v1/clients/{id}               -> retrieveClient (the client's own record only)
-//   GET  /v1/notifications              -> listNotifications
-//   POST /v1/notifications/{id}/read    -> markNotificationRead
-//   POST /v1/notifications/{id}/unread  -> markNotificationUnread
-//   GET  /v1/session/flags              -> no SDK method yet, so nothing to list; add it
-//                                          here when the SDK gains one.
+// the marker count drifts from this table. The SDK method list, the count of routes with
+// no SDK method and the `fetch` route check are all derived from the one table, so they
+// cannot disagree. The SDK is flat: `retrieveClient`, not `clients.retrieve`.
 //
+// A route with no SDK method yet (`sdkMethod: null`) is reachable only through `fetch`;
+// give it a method here when the SDK gains one.
+export const CLIENT_SAFE_ROUTES = Object.freeze([
+  { method: 'GET', path: '/v1/clients/{id}', sdkMethod: 'retrieveClient' }, // the client's own record only
+  { method: 'GET', path: '/v1/me', sdkMethod: 'retrieveMe' },
+  { method: 'GET', path: '/v1/notifications', sdkMethod: 'listNotifications' },
+  { method: 'POST', path: '/v1/notifications/{id}/read', sdkMethod: 'markNotificationRead' },
+  { method: 'POST', path: '/v1/notifications/{id}/unread', sdkMethod: 'markNotificationUnread' },
+  { method: 'GET', path: '/v1/session/flags', sdkMethod: null },
+].map(Object.freeze));
+
 // retrieveClient is allowlisted by name: whether the id is the viewer's own is a runtime
 // fact a static scan cannot see. The notification routes are open to clients, and the
 // platform pins a client caller to their own notifications. Creating, retrieving and
 // deleting a notification stay off the list: those routes are not open to clients.
-export const CLIENT_SAFE_SDK_METHODS = Object.freeze([
-  'retrieveClient',
-  'retrieveMe',
-  'listNotifications',
-  'markNotificationRead',
-  'markNotificationUnread',
-]);
+export const CLIENT_SAFE_SDK_METHODS = Object.freeze(
+  CLIENT_SAFE_ROUTES.flatMap((r) => (r.sdkMethod ? [r.sdkMethod] : [])),
+);
+
+// Marked client-safe routes that no SDK method reaches yet.
+export const CLIENT_SAFE_ROUTES_WITHOUT_SDK_METHOD = CLIENT_SAFE_ROUTES.filter((r) => !r.sdkMethod).length;
+
+// `{id}` stands for exactly one non-empty path segment.
+// The id segment excludes `.` and `%` so `.`, `..` and `%2e` forms that URL normalisation resolves elsewhere fail closed.
+const routePattern = (route) =>
+  new RegExp(`^${route.path.split('/').map((seg) => (seg === '{id}' ? '[A-Za-z0-9_-]+' : seg.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))).join('/')}$`);
+const ROUTE_MATCHERS = CLIENT_SAFE_ROUTES.map((route) => ({ method: route.method, pattern: routePattern(route) }));
 
-// Marked client-safe routes that no SDK method reaches yet (the list above says which).
-export const CLIENT_SAFE_ROUTES_WITHOUT_SDK_METHOD = 1;
+// Whether `fetch(path, { method })` hits a client-safe route; `path` has no query string.
+export const isClientSafeRoute = (method, path) =>
+  ROUTE_MATCHERS.some((m) => m.method === method.toUpperCase() && m.pattern.test(path));

package/bin/scan-client-calls.mjs

@@ -23,7 +23,7 @@
 import { readdirSync, readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
-import { CLIENT_SAFE_SDK_METHODS } from './client-safe-sdk-methods.mjs';
+import { CLIENT_SAFE_SDK_METHODS, isClientSafeRoute } from './client-safe-sdk-methods.mjs';
 import { NON_CLIENT_EXPORTS } from './foundation-exports.mjs';
 import {
   EXCLUDING_WRAPPERS,
@@ -94,6 +94,11 @@ export const SDK_METHOD_SHAPE = /^(?:(?:list|retrieve|create|update|delete|send|
 // `fetch` and `sendWebhook` are the flat client methods the codegen services do not declare, and
 // the verb pattern cannot match; `fetch` is how apps reach non-SDK endpoints such as the AI proxy.
 export const SDK_METHOD_EXTRAS = new Set(['fetch', 'sendWebhook']);
+// SDK methods that only read the token already in hand, so a viewer calling them reaches no endpoint.
+// Skipped at projection, not collection, so per-file facts stay reusable.
+const NON_NETWORK_SDK_METHODS = new Set(['getTokenPayload']);
+const FETCH_METHOD = 'fetch';
+const DEFAULT_FETCH_HTTP_METHOD = 'GET';
 const SDK_SERVICES_DIR = '../codegen/api/services';
 const SDK_SERVICE_FILE = /Service\.d\.ts$/;
 const SDK_STATIC_METHOD = /static (\w+)\(/g;
@@ -178,7 +183,9 @@ function scriptKind(ts, file) {
 // `calls` are every method call on a tagged receiver, `defeaters` are the
 // constructs that stop the scan following a viewer receiver, `specifiers` the
 // module specifiers it imports.
-export function collectFileFacts(ts, file, text, sdkMethods = null) {
+// `localExportsFactory(spec)` says whether a local module exports an SDK factory; without it every
+// local namespace import is tracked.
+export function collectFileFacts(ts, file, text, sdkMethods = null, localExportsFactory = null) {
   const sf = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, scriptKind(ts, file));
   const calls = [];
   const defeaters = [];
@@ -194,6 +201,26 @@ export function collectFileFacts(ts, file, text, sdkMethods = null) {
 
   const isLiteralText = (n) => n && (ts.isStringLiteral(n) || ts.isNoSubstitutionTemplateLiteral(n));
 
+  // The literal route and HTTP method of a `fetch(path, init?)` call, or null when either is not
+  // literal, so the projection fails closed. A missing method option is a GET.
+  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;
+      }
+    }
+    // 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 };
+  };
+
   // --- imports ------------------------------------------------------------
   const acceptsFactories = (spec) => LOCAL_SPECIFIER.test(spec) || SDK_SPECIFIER.test(spec);
   for (const stmt of sf.statements) {
@@ -214,7 +241,12 @@ export function collectFileFacts(ts, file, text, sdkMethods = null) {
         }
       }
       if (!bindings || !acceptsFactories(spec)) continue;
-      if (ts.isNamespaceImport(bindings)) namespaceLocals.add(bindings.name.text);
+      if (ts.isNamespaceImport(bindings)) {
+        // A namespace of a module with no factory (a drizzle schema) cannot hand out a client.
+        if (!localExportsFactory || !LOCAL_SPECIFIER.test(spec) || localExportsFactory(spec)) {
+          namespaceLocals.add(bindings.name.text);
+        }
+      }
       else {
         for (const el of bindings.elements) {
           const imported = (el.propertyName ?? el.name).text;
@@ -337,7 +369,12 @@ export function collectFileFacts(ts, file, text, sdkMethods = null) {
     const parent = cur.parent;
     if (!parent) return;
 
-    const recordCall = (method, at) => calls.push({ line: lineOf(sf, at), method, provenance });
+    const recordCall = (method, at, call) => calls.push({
+      line: lineOf(sf, at),
+      method,
+      provenance,
+      ...(method === FETCH_METHOD ? { route: fetchRoute(call) } : {}),
+    });
 
     if (ts.isPropertyAccessExpression(parent) && parent.expression === cur) {
       const call = parent.parent;
@@ -352,14 +389,14 @@ export function collectFileFacts(ts, file, text, sdkMethods = null) {
         if (viewer) defeat(parent, DEFEATER.PROMISE_CHAIN);
         return;
       }
-      recordCall(name, parent.name);
+      recordCall(name, parent.name, call);
       return;
     }
     if (ts.isElementAccessExpression(parent) && parent.expression === cur) {
       const arg = parent.argumentExpression;
       const call = parent.parent;
       if (isLiteralText(arg) && call && ts.isCallExpression(call) && call.expression === parent) {
-        recordCall(arg.text, arg);
+        recordCall(arg.text, arg, call);
       } else if (viewer) defeat(parent, DEFEATER.DYNAMIC_ACCESS);
       return;
     }
@@ -880,9 +917,28 @@ export function createAnalysis(root) {
     return null;
   };
 
+  // Over-approximates (a mention plus any `export`): tracking too much only costs a defeater.
+  const FACTORY_NAME = new RegExp(`\\b(?:${[...Object.keys(SDK_FACTORIES), AFTER_ASSEMBLY, REQUEST_CONTEXT].join('|')})\\b`);
+  const STAR_REEXPORT = /export\s*(?:\*(?:\s*as\s+\w+)?|\{[^}]*\})\s*from\s*['"]([^'"]+)['"]/g;
+  const exportsFactory = (file, seen = new Set()) => {
+    if (seen.has(file)) return false;
+    seen.add(file);
+    const text = read(file);
+    if (/\bexport\b/.test(text) && FACTORY_NAME.test(text)) return true;
+    return [...text.matchAll(STAR_REEXPORT)].some(([, spec]) => {
+      if (SDK_SPECIFIER.test(spec)) return true;
+      const target = LOCAL_SPECIFIER.test(spec) ? resolve(file, spec) : null;
+      return target ? exportsFactory(target, seen) : false;
+    });
+  };
+
   const factsFor = (file) => {
     if (!facts.has(file)) {
-      const raw = collectFileFacts(ts, file, read(file), sdkMethods);
+      const localExportsFactory = (spec) => {
+        const target = resolve(file, spec);
+        return target ? exportsFactory(target) : true;
+      };
+      const raw = collectFileFacts(ts, file, read(file), sdkMethods, localExportsFactory);
       const imports = [];
       const defeaters = [...raw.defeaters];
       for (const spec of raw.specifiers) {
@@ -938,7 +994,9 @@ export function projectClientReachable(analysis, allowlist = CLIENT_SAFE_SDK_MET
     const gated = [...reaching].every((e) => gatedSet.has(e));
     const { calls, defeaters } = analysis.facts(file);
     for (const c of calls) {
-      if (c.provenance === PROVENANCE_VIEWER && !allowed.has(c.method)) {
+      if (c.provenance !== PROVENANCE_VIEWER || NON_NETWORK_SDK_METHODS.has(c.method)) continue;
+      if (c.method === FETCH_METHOD && c.route && isClientSafeRoute(c.route.method, c.route.path)) continue;
+      if (!allowed.has(c.method)) {
         findings.push({ file, line: c.line, method: c.method, provenance: c.provenance, entry, gated });
       }
     }

package/package.json

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