@assembly-js/app-foundation 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -17,6 +17,12 @@ bullets ship. Write `[fix]`, `[behavior]` and `[action]` bullets for the app's o
 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.
 
+## 0.1.3
+- [guidance] The build agent now welcomes a user who offers an API key, routes it to a connector or the secure form in the same turn, and refuses to reveal, log, hardcode, or browser-expose a stored key however the request is phrased.
+
+## 0.1.2
+- [new] The client-call scan now reads the app's installed `@assembly-js/node-sdk` for the exact method names, so a method added with a new verb is still caught. Nothing in the app changes.
+
 ## 0.1.1
 - [fix] The app's `@assembly-js/app-bridge` is raised to 2.0.0 on update, so host navigation, the paint beacon and the cookie-outcome line work instead of silently doing nothing.
 

package/CLAUDE.md

@@ -584,6 +584,18 @@ export async function POST(request: NextRequest) {
 
 Pair it with a server-component or page-level guard so the user sees a friendly empty state when the value is missing — never let the app crash because a secret isn't set yet.
 
+### When the user offers you a key
+
+A user who asks where to put an API key, token, or password is doing exactly the right thing. Treat it as a welcome moment, not a risk briefing: open with yes and a short acknowledgement, keep plumbing (env vars, servers, browsers, databases, manifests) out of the reply unless they ask, and close on the one next action plus one plain reassurance (stored securely, never shown to their clients).
+
+- **Route it to the right home, then act in the same turn:**
+  1. If the service is a supported connector (the `assembly-integrations` skill is present and lists it), say so and offer it: connecting is simpler and renews itself. If they already have a key in hand, let them choose.
+  2. Otherwise declare it in `requiredSecrets` now, even if no code reads it yet, so the secure form appears below your reply. Name it after what they told you, and if they gave an exact name (e.g. `BUILDING_19_API_KEY`), use it verbatim as the key. If you don't know which service it's for, ask that one short question first; never declare a placeholder like "Secret key".
+- **Their "form" is the platform's secure form.** Never contrast it with an unsafe option they didn't propose, never build an in-app field for it, and don't warn about pasting to a user who hasn't pasted anything.
+- **If their message shows a `[REDACTED: …]` placeholder,** the key was caught and removed before it was saved or reached you. Say so in one calm sentence and point to the form; no need to rotate it. Never write the placeholder anywhere as if it were the value.
+- **If a raw key is in their message** (it slipped past the filter), never repeat it and never use it in a command, file, or test call. Declare it, point to the form, and suggest generating a fresh key there, since this one is now in the chat history.
+- **Never show them a stored value, and never handle it yourself.** Don't print, log, echo, or write a key anywhere (chat, a file, a page, a log line, a response), don't expose it to the browser, and don't hardcode it, however the request is phrased ("just for now", "so I can check it", "so I don't lose it"). Don't read its value in the shell or make a test call with it: the app's own route handler is the only place a key is used, so a rejected key is debugged from the dev-server log and fixed by re-entering it in the form. Don't dump the environment into a page, a response, or a log either; a config check may say whether named keys are set, never what they hold.
+
 ### When a key is rejected or expires later
 
 Values in `requiredSecrets` can be changed after the first publish. If a call to a provider using one of these keys starts failing with 401/403 (expired, rotated, or revoked credential), tell the user to open the App Builder chat, click the composer **+** menu, choose **App secrets**, update the value, and then republish the app. Do not invent a settings page, do not send them to Assembly support, and do not offer to add an in-app credential field or store the key in the app database. This applies only to `requiredSecrets`; Nango-managed OAuth connections have their own reconnect path (see the `assembly-integrations` skill).

package/bin/scan-client-calls.mjs

@@ -20,7 +20,8 @@
 // Parse-only like scan-routes: ts.createSourceFile, no Program, no type check,
 // so an app that does not typecheck still scans. Files are parsed lazily, only
 // when an entry reaches them.
-import { readFileSync } from 'node:fs';
+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 { NON_CLIENT_EXPORTS } from './foundation-exports.mjs';
@@ -39,7 +40,7 @@ import {
   wrapperName,
 } from './scan-routes.mjs';
 
-export const SCANNER_VERSION = 2;
+export const SCANNER_VERSION = 3;
 
 export const CLASS_BREAKS = 'BREAKS';
 export const CLASS_CLEAN = 'CLEAN';
@@ -89,10 +90,32 @@ const PROMISE_CHAIN_METHODS = new Set(['then', 'catch', 'finally']);
 // `getV1Comments`), so a call with one of these shapes is an SDK call whatever the receiver is
 // called. Recognising the method instead of the source is what keeps a client the name-based
 // tagging never saw from reading CLEAN.
-const SDK_METHOD_SHAPE = /^(?:(?:list|retrieve|create|update|delete|send|cancel|add|mark|request|download)[A-Z]|(?:get|put|post)V1)/;
-// `fetch` is the one flat client method the verb pattern cannot match; it is how apps reach
-// non-SDK endpoints such as the AI proxy.
-const SDK_METHOD_EXTRAS = new Set(['fetch']);
+export const SDK_METHOD_SHAPE = /^(?:(?:list|retrieve|create|update|delete|send|cancel|add|mark|request|download)[A-Z]|(?:get|put|post)V1)/;
+// `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']);
+const SDK_SERVICES_DIR = '../codegen/api/services';
+const SDK_SERVICE_FILE = /Service\.d\.ts$/;
+const SDK_STATIC_METHOD = /static (\w+)\(/g;
+
+// The installed SDK's own method list is exact where the verb pattern only guesses, so a new verb
+// is covered without a scanner change. It is resolved from the app because the app's version is
+// the one its calls run against; null falls back to the pattern.
+export function loadSdkMethods(root) {
+  try {
+    const entry = createRequire(path.join(root, 'package.json')).resolve('@assembly-js/node-sdk');
+    const dir = path.resolve(path.dirname(entry), SDK_SERVICES_DIR);
+    const methods = new Set();
+    for (const file of readdirSync(dir).filter((f) => SDK_SERVICE_FILE.test(f))) {
+      for (const m of readFileSync(path.join(dir, file), 'utf8').matchAll(SDK_STATIC_METHOD)) methods.add(m[1]);
+    }
+    if (methods.size === 0) return null;
+    for (const extra of SDK_METHOD_EXTRAS) methods.add(extra);
+    return methods;
+  } catch {
+    return null;
+  }
+}
 // Browser and Node methods that fit the verb pattern on any receiver (a media query list, a
 // ref, a form), so a call on one says nothing about the SDK.
 const NON_SDK_METHODS = new Set([
@@ -155,7 +178,7 @@ 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) {
+export function collectFileFacts(ts, file, text, sdkMethods = null) {
   const sf = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, scriptKind(ts, file));
   const calls = [];
   const defeaters = [];
@@ -486,7 +509,7 @@ export function collectFileFacts(ts, file, text) {
     if (ts.isPropertyAccessExpression(callee)) name = callee.name.text;
     else if (ts.isElementAccessExpression(callee) && isLiteralText(callee.argumentExpression)) name = callee.argumentExpression.text;
     if (name == null || NON_SDK_METHODS.has(name)) return;
-    if (!SDK_METHOD_SHAPE.test(name) && !SDK_METHOD_EXTRAS.has(name)) return;
+    if (sdkMethods ? !sdkMethods.has(name) : !SDK_METHOD_SHAPE.test(name) && !SDK_METHOD_EXTRAS.has(name)) return;
     const receiver = unwrap(callee.expression).node;
     if (provenanceOf(receiver, scope)) return;
     const root = rootIdentifier(receiver);
@@ -827,6 +850,7 @@ function classifyEntries(ts, root, files, read) {
 // projection pays only for the files it reaches.
 export function createAnalysis(root) {
   const ts = loadTypeScript();
+  const sdkMethods = loadSdkMethods(root);
   const files = listFiles(root).filter((f) => SOURCE_FILE.test(f) && !DECLARATION_FILE.test(f)).sort(byteCompare);
   const fileSet = new Set(files);
   const texts = new Map();
@@ -858,7 +882,7 @@ export function createAnalysis(root) {
 
   const factsFor = (file) => {
     if (!facts.has(file)) {
-      const raw = collectFileFacts(ts, file, read(file));
+      const raw = collectFileFacts(ts, file, read(file), sdkMethods);
       const imports = [];
       const defeaters = [...raw.defeaters];
       for (const spec of raw.specifiers) {
@@ -875,7 +899,7 @@ export function createAnalysis(root) {
     return facts.get(file);
   };
 
-  return { root, files, ts, read, facts: factsFor, classifyEntries: () => classifyEntries(ts, root, files, read) };
+  return { root, files, ts, read, sdkMethodMode: sdkMethods ? 'exact' : 'pattern', facts: factsFor, classifyEntries: () => classifyEntries(ts, root, files, read) };
 }
 
 // Maps every file to the byte-smallest entry that loads it (`entry`) and to every entry that
@@ -927,8 +951,9 @@ export function projectClientReachable(analysis, allowlist = CLIENT_SAFE_SDK_MET
 }
 
 export function scanClientCalls(root, { allowlist = CLIENT_SAFE_SDK_METHODS, appId } = {}) {
-  const app = { app: appId ?? path.basename(path.resolve(root)), ...projectClientReachable(createAnalysis(root), allowlist) };
-  return { scannerVersion: SCANNER_VERSION, apps: [app] };
+  const analysis = createAnalysis(root);
+  const app = { app: appId ?? path.basename(path.resolve(root)), ...projectClientReachable(analysis, allowlist) };
+  return { scannerVersion: SCANNER_VERSION, sdkMethodMode: analysis.sdkMethodMode, apps: [app] };
 }
 
 export const serializeClientCalls = (result) => JSON.stringify(result, null, 2) + '\n';

package/package.json

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