@assembly-js/app-foundation 0.2.4 → 0.2.6

package/CHANGELOG.md

@@ -15,7 +15,15 @@ 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.6
+- [fix] The app keeps connecting to a portal on a custom domain, and keeps telling the editor when it has loaded, without relying on a platform setting that is being retired. Nothing visible changes.
+
+## 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/foundation-exports.mjs

@@ -30,7 +30,7 @@ export const NON_CLIENT_EXPORTS = new Set([
   'InternalUserAccess', 'LEGACY_APP_IDS', 'MintFailure', 'MintOutcome', 'MintSessionOptions', 'MintedAppBearer',
   'MintedBearer', 'NETWORK_CAPTURE_MESSAGE_TYPE', 'NetworkCaptureHeaderFingerprint',
   'NetworkCaptureRecord', 'PAINTED_BEACON_EVENT', 'PAINTED_BEACON_PATH',
-  'PORTAL_ORIGIN_COOKIE_NAME', 'PREVIEW_V2_FLAG', 'PdfText', 'PrincipalAllow', 'PrincipalKind',
+  'PORTAL_ORIGIN_COOKIE_NAME', 'PdfText', 'PrincipalAllow', 'PrincipalKind',
   'Provider', 'ProxyOpts', 'RENEW_OUTCOME_EVENT', 'RenewOutcome', 'ReplaceChildRowsResult',
   'RequestSource', 'ResolveResourceOpts', 'ResourceError', 'ResourceFieldMap',
   'ResourceOption', 'ResourcePage', 'ScheduleCadence', 'SlackChannel',

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/dist/origin-bootstrap.d.ts

@@ -1,6 +1,5 @@
 export declare const PORTAL_ORIGIN_COOKIE_NAME = "assembly-portal-origin";
 export declare const CLIENT_FLAGS_COOKIE_NAME = "assembly-flags";
-export declare const PREVIEW_V2_FLAG = "app-builder-preview-v2";
 /**
  * Reads a single cookie by name from a cookie string (defaults to
  * `document.cookie`). Shared by every module that reads a proxy-mirrored
@@ -9,14 +8,13 @@ export declare const PREVIEW_V2_FLAG = "app-builder-preview-v2";
 export declare function readCookie(name: string, cookieString?: string): string | null;
 /**
  * Whether the given flag key is present in the proxy-mirrored flags cookie.
- * Exported for other vNext modules (e.g. the paint beacon) to check the same
- * cookie without re-parsing it themselves.
+ * Exported so client modules can gate on a flag without re-parsing the cookie.
  */
 export declare function hasClientFlag(key: string, cookieString?: string): boolean;
 /**
  * Register the workspace's portal origin with the bridge allowlist — from the
- * proxy-set cookie when the preview-v2 flag is on, from the legacy framing
- * origin otherwise. Returns the origin it registered, or null when there was
- * nothing to do. Exported for tests; runs once at module load in the browser.
+ * proxy-set cookie when it is readable, from the framing origin otherwise.
+ * Returns the origin it registered, or null when there was nothing to do.
+ * Exported for tests; runs once at module load in the browser.
  */
 export declare function bootstrapPortalOrigin(cookieString?: string): string | null;

package/dist/origin-bootstrap.js

@@ -2,20 +2,18 @@
 // evaluation precedes hydration — so the workspace's portal origin joins the
 // bridge allowlist before any component's first header/session-token call.
 //
-// The preview-v2 flag selects WHICH trust source registers the origin — it
-// never selects whether anything registers at all (flag-off must keep custom
-// portal domains working exactly as pre-vNext package versions did):
+// Two trust sources, in order:
 //
-//  - flag ON: the proxy-set cookie. The value is platform-resolved, never
-//    inferred client-side — the proxy already fetches workspace.portalUrl for
-//    its CSP frame-ancestors header and mirrors it into this client-readable
-//    cookie. Immune to the navigation-state poisoning below.
-//  - flag OFF (or flags cookie unreadable): the legacy browser-reported
-//    framing origin (ancestorOrigins, referrer fallback). Trusting it is
-//    sound because the proxy's CSP frame-ancestors already gates who may
-//    frame the app, but it rides navigation state — strip-able by privacy
-//    modes and poisoned by in-iframe reloads — which is why the cookie path
-//    replaces it.
+//  - the proxy-set cookie. The value is platform-resolved, never inferred
+//    client-side — the proxy already fetches workspace.portalUrl for its CSP
+//    frame-ancestors header and mirrors it into this client-readable cookie.
+//    Immune to the navigation-state poisoning below.
+//  - when that cookie is unreadable (a browser blocking the app's cookies):
+//    the browser-reported framing origin (ancestorOrigins, referrer
+//    fallback). Trusting it is sound because the proxy's CSP frame-ancestors
+//    already gates who may frame the app, but it rides navigation state —
+//    strip-able by privacy modes and poisoned by in-iframe reloads — which is
+//    why the cookie comes first.
 //
 // The bridge has no trust bypass, so one of these registrations is the only
 // way a custom portal domain becomes a valid parent (dashboard/platform
@@ -29,7 +27,6 @@ export const PORTAL_ORIGIN_COOKIE_NAME = 'assembly-portal-origin';
 // plain, comma-separated cookie on every request (set or cleared, never
 // left stale).
 export const CLIENT_FLAGS_COOKIE_NAME = 'assembly-flags';
-export const PREVIEW_V2_FLAG = 'app-builder-preview-v2';
 /**
  * Reads a single cookie by name from a cookie string (defaults to
  * `document.cookie`). Shared by every module that reads a proxy-mirrored
@@ -51,8 +48,7 @@ export function readCookie(name, cookieString) {
 }
 /**
  * Whether the given flag key is present in the proxy-mirrored flags cookie.
- * Exported for other vNext modules (e.g. the paint beacon) to check the same
- * cookie without re-parsing it themselves.
+ * Exported so client modules can gate on a flag without re-parsing the cookie.
  */
 export function hasClientFlag(key, cookieString) {
     const raw = readCookie(CLIENT_FLAGS_COOKIE_NAME, cookieString);
@@ -61,11 +57,11 @@ export function hasClientFlag(key, cookieString) {
     return raw.split(',').includes(key);
 }
 /**
- * Legacy (pre-vNext) framing-origin resolution: `location.ancestorOrigins`
+ * Framing-origin resolution for when the portal-origin cookie is unreadable: `location.ancestorOrigins`
  * (browser-attested; Chromium/WebKit), falling back to `document.referrer`
  * (Firefox). Null outside an iframe or when neither source is available.
  */
-function resolveLegacyParentOrigin() {
+function resolveFramingOrigin() {
     if (typeof window === 'undefined')
         return null;
     if (window.parent === window)
@@ -85,25 +81,20 @@ function resolveLegacyParentOrigin() {
 }
 /**
  * Register the workspace's portal origin with the bridge allowlist — from the
- * proxy-set cookie when the preview-v2 flag is on, from the legacy framing
- * origin otherwise. Returns the origin it registered, or null when there was
- * nothing to do. Exported for tests; runs once at module load in the browser.
+ * proxy-set cookie when it is readable, from the framing origin otherwise.
+ * Returns the origin it registered, or null when there was nothing to do.
+ * Exported for tests; runs once at module load in the browser.
  */
 export function bootstrapPortalOrigin(cookieString) {
-    if (!hasClientFlag(PREVIEW_V2_FLAG, cookieString)) {
-        // Flag off: behave exactly like pre-vNext package versions so custom
-        // portal domains keep a working bridge — and so turning the flag OFF is
-        // a true rollback, not a third state. Https-only: local dev origins are
-        // already on the default allowlist.
-        const origin = resolveLegacyParentOrigin();
+    const record = readCookie(PORTAL_ORIGIN_COOKIE_NAME, cookieString);
+    if (!record) {
+        // Https-only: local dev origins are already on the default allowlist.
+        const origin = resolveFramingOrigin();
         if (!origin || !origin.startsWith('https://'))
             return null;
         AssemblyBridge.configure({ additionalOrigins: [origin] });
         return origin;
     }
-    const record = readCookie(PORTAL_ORIGIN_COOKIE_NAME, cookieString);
-    if (!record)
-        return null;
     // Accept only a bare https origin — anything else (paths, http, garbage)
     // is not a value the proxy writes and must not reach the allowlist.
     try {

package/dist/paint-beacon.js

@@ -6,13 +6,7 @@
 // The HTTP route is handled in proxy.ts via the helpers below (same
 // package-delegation pattern as session-exchange). The bridge post rides
 // buffer-until-learned, so a paint that beats the parent's hello is not lost.
-//
-// Gated on the preview-v2 flag (see origin-bootstrap.ts's hasClientFlag):
-// installPaintBeacon() no-ops for a flag-off workspace, so the client never
-// calls sendBeacon and the proxy's route never sees a request — no need to
-// separately gate handlePaintedBeacon() below.
 import { AssemblyBridge } from '@assembly-js/app-bridge';
-import { hasClientFlag, PREVIEW_V2_FLAG } from './origin-bootstrap.js';
 export const PAINTED_BEACON_PATH = '/__assembly/painted';
 export const PAINTED_BEACON_EVENT = 'assembly.painted';
 let scheduled = false;
@@ -46,9 +40,7 @@ function firePaintBeacon() {
  * hydration + rAF wins. Does nothing on the server.
  */
 export function installPaintBeacon() {
-    if (typeof window === 'undefined' || scheduled)
-        return;
-    if (!hasClientFlag(PREVIEW_V2_FLAG))
+    if (typeof window === 'undefined' || typeof document === 'undefined' || scheduled)
         return;
     scheduled = true;
     const afterPaint = () => {

package/package.json

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