@intentius/chant 0.90.0 → 0.91.0

package/src/workspace/box-isolation.ts

@@ -0,0 +1,205 @@
+/**
+ * Box isolation (#2727): the ports, state paths and cookie names each box
+ * uses, derived from its identity and its host, never chosen by a runtime.
+ *
+ * A box is a member with a `box` block (#2726), and its name is the
+ * member's. A box's identity is its host, its name and its slot, from the
+ * block's `host` and `slot`. Everything else
+ * follows from those and the host's declaration, and nothing else goes in:
+ *
+ * - port `p` is `host.ports.from + slot * host.ports.perBox + offset(p)`;
+ * - the state directory is `<host.stateRoot>/<box name>`, and state entry
+ *   `k` is that directory joined with the entry's relative path;
+ * - cookie `c` is `<c>_<box name>`.
+ *
+ * So the same declaration gives the same values on every machine and every
+ * run, and adding or removing a box changes no other box's values. The state
+ * paths keep their environment reference (`${XDG_STATE_HOME}` by default):
+ * the runtime that sets them expands it on its machine, and chant never
+ * reads the machine.
+ *
+ * Distinct names on one host give distinct state paths and cookie names by
+ * construction (a member name has no `_`, so `<c>_<box>` splits one way).
+ * Ports are the only value two boxes can share: two boxes on one host with
+ * the same slot, or two ports in one box at the same offset. `chant
+ * workspace check` compares every value anyway (WSP123), so an entry whose
+ * path escapes its directory is caught too.
+ */
+
+import { DEFAULT_STATE_ROOT, type BoxIsolationDeclaration, type Declaration, type Host, type Member } from "./declaration";
+import { pointerToken } from "./jsonc";
+
+/** A box's isolation, resolved: what `chant workspace status --json` prints in the member's box block. */
+export interface ResolvedIsolation {
+  host: string;
+  slot: number;
+  /** The box's block of its host's range, inclusive. */
+  portRange: { from: number; to: number };
+  /** Each declared port's number, in file order. */
+  ports: Record<string, number>;
+  /** `<stateRoot>/<box name>`, with the environment reference unexpanded. */
+  stateDir: string;
+  /** Each declared state entry's path, under `stateDir`. */
+  state: Record<string, string>;
+  /** Each declared cookie's name for this box. */
+  cookies: Record<string, string>;
+}
+
+/** The host's state root as written, or the default. */
+export function stateRootOf(host: Host): string {
+  return host.stateRoot ?? DEFAULT_STATE_ROOT;
+}
+
+const trimSlash = (s: string) => s.replace(/\/+$/, "");
+
+/** Resolve the isolation of the box named `name` on its host. */
+export function resolveIsolation(name: string, box: BoxIsolationDeclaration, host: Host): ResolvedIsolation {
+  const first = host.ports.from + box.slot * host.ports.perBox;
+  const stateDir = `${trimSlash(stateRootOf(host))}/${name}`;
+  return {
+    host: box.host,
+    slot: box.slot,
+    portRange: { from: first, to: first + host.ports.perBox - 1 },
+    ports: Object.fromEntries(Object.entries(box.ports).map(([name, offset]) => [name, first + offset])),
+    stateDir,
+    state: Object.fromEntries(Object.entries(box.state).map(([name, path]) => [name, `${stateDir}/${path.replace(/^\.\/+/, "")}`])),
+    cookies: Object.fromEntries(box.cookies.map((c) => [c, `${c}_${name}`])),
+  };
+}
+
+/** A member whose box block declares its isolation, with it resolved. */
+export interface IsolatedBox {
+  member: Member;
+  isolation: ResolvedIsolation;
+}
+
+/** Every box that declares its isolation, resolved, in member order. The declaration read already checked each box's host exists. */
+export function resolveBoxes(declaration: Declaration): IsolatedBox[] {
+  const hosts = new Map(declaration.hosts.map((h) => [h.name, h]));
+  const out: IsolatedBox[] = [];
+  for (const m of declaration.members) {
+    const iso = m.box?.isolation;
+    if (iso) out.push({ member: m, isolation: resolveIsolation(m.name, iso, hosts.get(iso.host)!) });
+  }
+  return out;
+}
+
+// ── Literal machine paths (WSP124) ───────────────────────────────────────────
+
+const ENV_REF = /^\$(\{[A-Za-z_][A-Za-z0-9_]*\}|[A-Za-z_][A-Za-z0-9_]*)/;
+const HOME_REF = /^\$(\{HOME\}|HOME)(?![A-Za-z0-9_])/;
+
+/**
+ * Why a host's `stateRoot` is a literal machine path, or undefined when it is
+ * not. A state root starts with an environment reference the runtime expands,
+ * and that reference is not `$HOME`: a path under a home directory names one
+ * person's machine layout (`${HOME}/<user>/...`), where `${XDG_STATE_HOME}`
+ * names the place the machine keeps state.
+ */
+export function stateRootLiteral(root: string): string | undefined {
+  if (HOME_REF.test(root)) return "starts at $HOME, which names one person's machine layout; use ${XDG_STATE_HOME} or another variable the runtime sets";
+  if (!ENV_REF.test(root)) return "does not start with an environment reference such as ${XDG_STATE_HOME}, so it names one machine's layout";
+  if (root.split("/").includes("..")) return "has a .. segment";
+  return undefined;
+}
+
+/**
+ * Why a state entry's path is not one relative to the box's state directory,
+ * or undefined when it is: absolute, home-relative, starting with an
+ * environment reference, a Windows drive path, or with a `..` segment.
+ */
+export function statePathLiteral(path: string): string | undefined {
+  if (path.startsWith("/")) return "is absolute";
+  if (path.startsWith("~")) return "starts at a home directory";
+  if (path.startsWith("$")) return "starts with an environment reference";
+  if (/^[A-Za-z]:[\\/]/.test(path) || path.includes("\\")) return "is a Windows path";
+  if (path.split("/").includes("..")) return "has a .. segment, which leaves the box's state directory";
+  return undefined;
+}
+
+export interface BoxLiteral {
+  /** The box, or null for a host's state root. */
+  box: string | null;
+  message: string;
+  pointer: string;
+}
+
+/** Every literal machine path in the hosts and boxes. */
+export function boxLiterals(declaration: Declaration): BoxLiteral[] {
+  const out: BoxLiteral[] = [];
+  for (const h of declaration.hosts) {
+    if (h.stateRoot === null) continue;
+    const why = stateRootLiteral(h.stateRoot);
+    if (why) out.push({ box: null, message: `host ${h.name}'s stateRoot ${JSON.stringify(h.stateRoot)} ${why}`, pointer: `${h.pointer}/stateRoot` });
+  }
+  for (const m of declaration.members) {
+    for (const [name, path] of Object.entries(m.box?.isolation?.state ?? {})) {
+      const why = statePathLiteral(path);
+      if (why) {
+        out.push({
+          box: m.name,
+          message: `member ${m.name}'s box gives state ${name} the path ${JSON.stringify(path)}, which ${why}; state paths are relative to the box's state directory, which chant derives from the host's stateRoot and the member's name`,
+          pointer: `${m.box!.pointer}/state/${pointerToken(name)}`,
+        });
+      }
+    }
+  }
+  return out;
+}
+
+// ── Collisions (WSP123) ──────────────────────────────────────────────────────
+
+export interface BoxCollision {
+  host: string;
+  what: "port" | "state" | "cookie";
+  /** The shared value. */
+  value: string;
+  /** Each holder as `<box>.<name>`, in declaration order. */
+  holders: { box: string; name: string; pointer: string }[];
+}
+
+/** Collapse `.`, `..` and repeated slashes, so two spellings of one path compare equal. */
+function normalizePath(path: string): string {
+  const out: string[] = [];
+  for (const seg of path.split("/")) {
+    if (seg === "" || seg === ".") continue;
+    if (seg === ".." && out.length > 0 && out[out.length - 1] !== "..") out.pop();
+    else out.push(seg);
+  }
+  return (path.startsWith("/") ? "/" : "") + out.join("/");
+}
+
+/**
+ * Every value two holders on one host resolve to. Ports collide within a box
+ * too, since two listeners can't share a port; state entries in one box may
+ * name one file on purpose (a runtime and the door both reading hud's
+ * identity), and cookies are unique in a box by the schema.
+ */
+export function boxCollisions(declaration: Declaration): BoxCollision[] {
+  const resolved = resolveBoxes(declaration);
+  const seen = new Map<string, BoxCollision>();
+  const add = (host: string, what: BoxCollision["what"], value: string, box: string, name: string, pointer: string) => {
+    const key = `${host}\u0000${what}\u0000${value}`;
+    let c = seen.get(key);
+    if (!c) {
+      c = { host, what, value, holders: [] };
+      seen.set(key, c);
+    }
+    c.holders.push({ box, name, pointer });
+  };
+  for (const { member, isolation: r } of resolved) {
+    const at = member.box!.pointer;
+    const box = member.name;
+    for (const [name, port] of Object.entries(r.ports)) add(r.host, "port", String(port), box, name, `${at}/ports/${pointerToken(name)}`);
+    const files = new Set<string>();
+    for (const [name, path] of Object.entries(r.state)) {
+      const file = normalizePath(path);
+      if (files.has(file)) continue;
+      files.add(file);
+      add(r.host, "state", file, box, name, `${at}/state/${pointerToken(name)}`);
+    }
+    Object.entries(r.cookies).forEach(([name, cookie], i) => add(r.host, "cookie", cookie, box, name, `${at}/cookies/${i}`));
+  }
+  // A state file is counted once per box above, so two holders are two boxes.
+  return [...seen.values()].filter((c) => c.holders.length > 1);
+}

package/src/workspace/check-contract.test.ts

@@ -10,6 +10,7 @@ import { join } from "node:path";
 import { afterAll, describe, expect, test } from "vitest";
 import { cleanScratch, commitAll, contract, declaration, git, REPO, repo, scratchDir, validSchema } from "./__fixtures__/contract-repo";
 import schema from "./check.schema.json";
+import { BOX_FINDING_CODES } from "./checks/boxes";
 import { WORKSPACE_ERROR_CODES } from "./declaration";
 import { CHECK_CODES, CHECK_CONTRACT_VERSION, CHECK_ERROR_CODES, CHECK_OUTPUT_SCHEMA_ID, runChecks, type CheckDocument } from "./lineage-check";
 
@@ -35,7 +36,8 @@ describe("check output schema", () => {
   test("lists exactly the codes the code can return", () => {
     expect(schema.$defs.lockFinding.properties.code.enum).toEqual([...CHECK_CODES]);
     expect(schema.$defs.failure.properties.error.properties.code.enum).toEqual([...CHECK_ERROR_CODES]);
-    expect(schema.$defs.diagnostic.properties.code.enum).toEqual([...WORKSPACE_ERROR_CODES]);
+    expect(schema.$defs.diagnostic.properties.code.enum).toEqual([...WORKSPACE_ERROR_CODES, ...BOX_FINDING_CODES]);
+    expect(schema.$defs.suppressed.properties.code.enum).toEqual([...WORKSPACE_ERROR_CODES, ...BOX_FINDING_CODES]);
   });
 });
 

package/src/workspace/check.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://intentius.io/chant/schemas/workspace/check/v1/check.schema.json",
   "title": "chant workspace check output",
-  "description": "What `chant workspace check --format json` prints, version 1 of the read contract for checking a workspace (#2524 D9, D15, D16, #2535, #2536). The lineage lock findings carry reason codes; the declaration findings carry WSP ids from the check catalog, and WSP001, a declaration that can't be read, also carries the declaration's reason code. Readers ignore fields they do not know; a field is only ever added within a version. The reason and error codes are closed lists: a new code is a new contract version. Contract version 1 is written by chant 0.81.0 and newer; a reader that needs it refuses output whose `contract` it doesn't know. Every code is in the one closed list of `reason-codes.ts`.",
+  "description": "What `chant workspace check --format json` prints, version 1 of the read contract for checking a workspace (#2524 D9, D15, D16, #2535, #2536). The lineage lock findings carry reason codes; the declaration findings carry WSP ids from the check catalog, WSP001, a declaration that can't be read, also carries the declaration's reason code, and the box checks WSP121 to WSP124 carry theirs. Readers ignore fields they do not know; a field is only ever added within a version. The reason and error codes are closed lists: a new code is a new contract version. Contract version 1 is written by chant 0.81.0 and newer; a reader that needs it refuses output whose `contract` it doesn't know. Every code is in the one closed list of `reason-codes.ts`.",
   "oneOf": [
     {
       "$ref": "#/$defs/result"
@@ -210,7 +210,7 @@
         },
         "entity": {
           "type": "string",
-          "description": "The member or group the finding is about."
+          "description": "The member or group the finding is about. For a box check, the box member."
         },
         "code": {
           "enum": [
@@ -222,9 +222,13 @@
             "reader-too-old",
             "root-chant-required",
             "not-a-git-repository",
-            "revision-unknown"
+            "revision-unknown",
+            "box-credential-declared",
+            "box-capability-unbrokered",
+            "box-isolation-collision",
+            "box-isolation-literal"
           ],
-          "description": "For WSP001: why the declaration can't be read."
+          "description": "For WSP001: why the declaration can't be read. For WSP121 to WSP124, the box finding (#2726, #2727)."
         }
       }
     },
@@ -277,7 +281,7 @@
         },
         "entity": {
           "type": "string",
-          "description": "The member or group the finding is about."
+          "description": "The member or group the finding is about. For a box check, the box member."
         },
         "code": {
           "enum": [
@@ -289,9 +293,13 @@
             "reader-too-old",
             "root-chant-required",
             "not-a-git-repository",
-            "revision-unknown"
+            "revision-unknown",
+            "box-credential-declared",
+            "box-capability-unbrokered",
+            "box-isolation-collision",
+            "box-isolation-literal"
           ],
-          "description": "For WSP001: why the declaration can't be read."
+          "description": "For WSP001: why the declaration can't be read. For WSP121 to WSP124, the box finding (#2726, #2727)."
         },
         "reason": {
           "type": "string"

package/src/workspace/checks/box-isolation.ts

@@ -0,0 +1,68 @@
+/**
+ * The box isolation checks, WSP123 and WSP124 (#2727).
+ *
+ * | Id | Code | Fails when |
+ * |---|---|---|
+ * | WSP123 | `box-isolation-collision` | two boxes on one host, or two ports in one box, resolve to the same port, state path or cookie name |
+ * | WSP124 | `box-isolation-literal` | a host's state root or a box's state entry is a literal machine path |
+ *
+ * Both are fixed errors. A collision means one box signs another's people out
+ * or reads another's identity (arugula-salad/studio#39), and a literal path
+ * means the declaration only holds on one machine. Neither has a case where
+ * turning the check down is the fix.
+ */
+
+import type { WorkspaceCheck } from "../checks";
+import { boxCollisions, boxLiterals } from "../box-isolation";
+
+export const WSP_BOX_COLLISION = "WSP123";
+export const WSP_BOX_LITERAL = "WSP124";
+
+const WHAT = { port: "port", state: "state path", cookie: "cookie name" } as const;
+
+export const BOX_ISOLATION_CHECKS: readonly WorkspaceCheck[] = [
+  {
+    id: WSP_BOX_COLLISION,
+    name: "box-isolation-collision",
+    description: "No two boxes on one host resolve to the same port, state path or cookie name, and no two ports in one box share an offset.",
+    severity: "error",
+    configurable: false,
+    check(ctx) {
+      return boxCollisions(ctx.declaration).map((c) => {
+        const [first, ...rest] = c.holders;
+        const names = c.holders.map((h) => `${h.box}.${h.name}`).join(" and ");
+        const hint =
+          c.what === "port"
+            ? new Set(c.holders.map((h) => h.box)).size > 1
+              ? "; give each box on a host its own slot"
+              : "; give each port in a box its own offset"
+            : "";
+        return {
+          checkId: this.id,
+          severity: this.severity,
+          code: "box-isolation-collision" as const,
+          message: `box-isolation-collision: ${names} on host ${c.host} resolve to the same ${WHAT[c.what]} ${c.value}${hint}`,
+          entity: rest.find((h) => h.box !== first.box)?.box ?? first.box,
+          pointer: (rest[0] ?? first).pointer,
+        };
+      });
+    },
+  },
+  {
+    id: WSP_BOX_LITERAL,
+    name: "box-isolation-literal",
+    description: "No host's state root and no box's state entry is a literal machine path: state paths derive from an environment reference and the member's name.",
+    severity: "error",
+    configurable: false,
+    check(ctx) {
+      return boxLiterals(ctx.declaration).map((l) => ({
+        checkId: this.id,
+        severity: this.severity,
+        code: "box-isolation-literal" as const,
+        message: `box-isolation-literal: ${l.message}`,
+        ...(l.box !== null ? { entity: l.box } : {}),
+        pointer: l.pointer,
+      }));
+    },
+  },
+];

package/src/workspace/checks/boxes.test.ts

@@ -0,0 +1,197 @@
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import * as ts from "typescript";
+import { afterAll, describe, expect, test } from "vitest";
+import { runDeclarationChecks } from "../checks";
+import { parseDeclaration, WorkspaceReadError } from "../declaration";
+import { gitTree } from "../tree";
+import { isCredentialKey, isSecretReference, literalSecretsInCode, literalSecretsInText } from "./boxes";
+
+const scratch: string[] = [];
+afterAll(() => {
+  for (const d of scratch) rmSync(d, { recursive: true, force: true });
+});
+function repo(files: Record<string, string>): string {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "chant-box-")));
+  scratch.push(root);
+  execFileSync("git", ["init", "-q"], { cwd: root });
+  for (const [path, text] of Object.entries(files)) {
+    mkdirSync(dirname(join(root, path)), { recursive: true });
+    writeFileSync(join(root, path), text);
+  }
+  return root;
+}
+
+// Built at run time so no credential-shaped literal sits in this file.
+const ANTHROPIC_KEY = ["sk", "ant", "api03", "A".repeat(40)].join("-");
+const GITHUB_TOKEN = ["ghp", "B".repeat(36)].join("_");
+
+const BROKERED = { capabilities: [{ name: "inference", broker: "lobby", scope: ["agent", "vault", "conversations", "sandboxes"] }] };
+
+const declaration = (box: unknown, extra: Record<string, unknown> = {}) =>
+  JSON.stringify({ name: "acme", schema: 1, members: [{ name: "spec", dir: "spec", kind: "other", because: "the box's declarations", box, ...extra }] }, null, 2);
+
+/** A chaff-style box declaration: a service whose env has `apiKey`. */
+const spec = (apiKey: string) => `import { Service, Capability } from "@intentius/chant-lexicon-chaff";
+
+export const app = new Service({
+  start: ["node", "app/server.mjs"],
+  env: {
+    HUD_SRC: "\${HOME}/alecraso/hud-live",
+    ANTHROPIC_API_KEY: ${JSON.stringify(apiKey)},
+  },
+});
+
+export const inference = new Capability({ provider: "brokered", credential: "$INFERENCE_TOKEN", endpoint: "$INFERENCE_URL" });
+`;
+
+/** The findings, less WSP009, which every member of kind other gets. */
+const found = async (root: string) => (await runDeclarationChecks(root, (f) => f, { gather: false })).diagnostics.filter((d) => d.ruleId !== "WSP009");
+
+describe("box-credential-declared (WSP121)", () => {
+  test("a literal API key in a service's env fails the box", async () => {
+    const root = repo({ "chant.workspace.json": declaration(BROKERED), "spec/box.ts": spec(ANTHROPIC_KEY) });
+    const d = await found(root);
+    expect(d.map((x) => [x.ruleId, x.code, x.entity, x.file, x.line])).toEqual([["WSP121", "box-credential-declared", "spec", "spec/box.ts", 7]]);
+    expect(d[0].message).toContain("an Anthropic API key");
+    // The message names what was found, never the value.
+    expect(d[0].message).not.toContain(ANTHROPIC_KEY);
+  });
+
+  test("the same box with the key as a reference and the capability brokered passes", async () => {
+    for (const ref of ["${ANTHROPIC_API_KEY}", "$ANTHROPIC_API_KEY", "op://box/anthropic/key", "bws://0f5b/anthropic", "infisical:///dev/ANTHROPIC_API_KEY"]) {
+      const root = repo({ "chant.workspace.json": declaration(BROKERED), "spec/box.ts": spec(ref) });
+      expect(await found(root), ref).toEqual([]);
+    }
+  });
+
+  test("a literal of no known shape under a credential key fails, and so does a vault secret's literal value", async () => {
+    const root = repo({
+      "chant.workspace.json": declaration(BROKERED),
+      "spec/box.ts": `export const box = Box({
+  envVars: { GITHUB_TOKEN: "hunter2hunter2" },
+  vault: { secrets: [{ key: "STUDIO_SECRET", value: "plain-text" }, { key: "OK", value: "\${STUDIO_SECRET}" }] },
+  repo: { url: "https://github.com/x/y", secretKey: "GIT_TOKEN" },
+  names: { credential: "INFERENCE_TOKEN", tokenPath: "/run/secrets/t", token: "~/box/llm-token", endpoint: { apiKey: "https://broker.local/key" } },
+  process: { token: process.env.TOKEN! },
+});
+`,
+    });
+    const d = await found(root);
+    expect(d.map((x) => `${x.line}: ${x.message.split(" holds ")[1].split(", and")[0]}`)).toEqual([
+      "2: a literal value for GITHUB_TOKEN",
+      "3: a literal vault secret value for STUDIO_SECRET",
+    ]);
+  });
+
+  test("an env file and a shell script in the box's directory are read too; prose only for credential shapes", async () => {
+    const root = repo({
+      "chant.workspace.json": declaration(BROKERED),
+      "spec/.env": `FOUNTAIN_API_KEY=abc123def456\nPORT=8080\nGIT_TOKEN=\${CHUD_GIT_TOKEN}\n`,
+      "spec/run.sh": `#!/bin/sh\nexport GITHUB_TOKEN=${GITHUB_TOKEN}\necho "password=$GIT_TOKEN"\nTOKEN=$1\ntoken=~/box/llm-token\nSECRET=/run/secrets/x\n`,
+      "spec/README.md": `Token: rotate it monthly.\n`,
+      "spec/node_modules/pkg/index.js": `export const k = ${JSON.stringify(ANTHROPIC_KEY)};\n`,
+    });
+    const d = await found(root);
+    expect(d.map((x) => `${x.file}:${x.line}`)).toEqual(["spec/.env:1", "spec/run.sh:2"]);
+  });
+
+  test("a member without a box block is not read, and a box's finding can't be suppressed", async () => {
+    const plain = repo({
+      "chant.workspace.json": JSON.stringify({ name: "acme", schema: 1, members: [{ name: "spec", dir: "spec", kind: "other", because: "x" }] }),
+      "spec/box.ts": spec(ANTHROPIC_KEY),
+    });
+    expect(await found(plain)).toEqual([]);
+    const suppressed = repo({
+      "chant.workspace.json": declaration(BROKERED, { suppress: [{ check: "WSP121", because: "a test key" }] }),
+      "spec/box.ts": spec(ANTHROPIC_KEY),
+    });
+    expect((await found(suppressed)).map((x) => x.ruleId).sort()).toEqual(["WSP011", "WSP121"]);
+  });
+
+  test("under --at the revision's files are read", async () => {
+    const root = repo({ "chant.workspace.json": declaration(BROKERED), "spec/box.ts": spec(ANTHROPIC_KEY) });
+    execFileSync("git", ["add", "-A"], { cwd: root });
+    execFileSync("git", ["-c", "user.email=t@t", "-c", "user.name=t", "commit", "-qm", "box"], { cwd: root });
+    const commit = execFileSync("git", ["rev-parse", "HEAD"], { cwd: root, encoding: "utf8" }).trim();
+    writeFileSync(join(root, "spec/box.ts"), spec("${ANTHROPIC_API_KEY}"));
+    expect(await found(root)).toEqual([]);
+    const at = await runDeclarationChecks(root, (f) => f, { tree: gitTree(root, commit) });
+    expect(at.diagnostics.map((x) => x.ruleId).filter((id) => id !== "WSP009")).toEqual(["WSP121"]);
+  });
+});
+
+describe("box-capability-unbrokered (WSP122)", () => {
+  test("a capability with no broker fails, at the capability", async () => {
+    const root = repo({
+      "chant.workspace.json": declaration({ capabilities: [{ name: "fountain", broker: "lobby", scope: ["agent"] }, { name: "inference" }] }),
+      "spec/box.ts": spec("${ANTHROPIC_API_KEY}"),
+    });
+    const d = await found(root);
+    expect(d.map((x) => [x.ruleId, x.code, x.entity])).toEqual([["WSP122", "box-capability-unbrokered", "spec"]]);
+    expect(d[0].message).toContain("needs inference and names no broker");
+  });
+
+  test("it can be turned down, since a box may be moving to a broker", async () => {
+    const root = repo({
+      "chant.workspace.json": JSON.stringify({
+        name: "acme",
+        schema: 1,
+        checks: { WSP122: "warning" },
+        members: [{ name: "spec", dir: "spec", kind: "other", because: "x", box: { capabilities: [{ name: "inference" }] } }],
+      }),
+      "spec/box.ts": "",
+    });
+    const report = await runDeclarationChecks(root, (f) => f, { gather: false });
+    expect(report.ok).toBe(true);
+    expect(report.diagnostics.filter((x) => x.ruleId !== "WSP009").map((x) => `${x.ruleId}:${x.severity}`)).toEqual(["WSP122:warning"]);
+  });
+});
+
+describe("the box block in the declaration", () => {
+  test("parses, with the broker null and the scope empty when left out", () => {
+    const d = parseDeclaration(declaration({ capabilities: [{ name: "fountain", broker: "lobby", scope: ["agent", "vault"] }, { name: "inference" }] }), "chant.workspace.json");
+    expect(d.members[0].box).toEqual({
+      pointer: "/members/0/box",
+      isolation: null,
+      capabilities: [
+        { name: "fountain", broker: "lobby", scope: ["agent", "vault"], pointer: "/members/0/box/capabilities/0" },
+        { name: "inference", broker: null, scope: [], pointer: "/members/0/box/capabilities/1" },
+      ],
+    });
+    expect(parseDeclaration(JSON.stringify({ name: "a", schema: 1, members: [{ name: "m", dir: "m", kind: "chant" }] }), "chant.workspace.json").members[0].box).toBeNull();
+  });
+
+  test("a capability named twice, or an unknown field, is declaration-invalid", () => {
+    const twice = () => parseDeclaration(declaration({ capabilities: [{ name: "fountain", broker: "lobby" }, { name: "fountain", broker: "door" }] }), "chant.workspace.json");
+    expect(twice).toThrow(WorkspaceReadError);
+    expect(twice).toThrow(/lists the capability fountain twice/);
+    expect(() => parseDeclaration(declaration({ capabilities: [{ name: "fountain", credential: "x" }] }), "chant.workspace.json")).toThrow(/unknown field "credential"/);
+  });
+});
+
+describe("what counts as a literal secret", () => {
+  test("references are not secrets", () => {
+    for (const v of ["${X}", "${HOME}/.config", "$X", "$1", "$(cat f)", "op://v/i/f", "bws://id", "infisical:///dev/X", "{{chant:name}}", ""]) {
+      expect(isSecretReference(v), v).toBe(true);
+    }
+    for (const v of ["hunter2", "abc${", "sk-live"]) expect(isSecretReference(v), v).toBe(v === "abc${");
+  });
+
+  test("keys that name a credential, and keys that name where one is", () => {
+    for (const k of ["API_KEY", "ANTHROPIC_API_KEY", "GITHUB_TOKEN", "apiKey", "token", "credential", "password", "AWS_SECRET_ACCESS_KEY", "authToken", "clientSecret"]) {
+      expect(isCredentialKey(k), k).toBe(true);
+    }
+    for (const k of ["secretKey", "secret_key", "TOKEN_FILE", "tokenHash", "HUD_IDENTITY_PATH", "CHAFF_AGENT_VAULT", "key", "value", "maxTokens"]) {
+      expect(isCredentialKey(k), k).toBe(false);
+    }
+  });
+
+  test("a credential shape is found anywhere in code, and not in a template with a substitution", () => {
+    const code = `const a = [${JSON.stringify(GITHUB_TOKEN)}];\nconst b = \`\${prefix}${"x".repeat(3)}\`;\n`;
+    expect(literalSecretsInCode(code, "a.ts", ts.ScriptKind.TS).map((s) => [s.line, s.what])).toEqual([[1, "a GitHub token"]]);
+    expect(literalSecretsInText(`# nothing\nkey: ${GITHUB_TOKEN}\n`).map((s) => s.line)).toEqual([2]);
+  });
+});