deepdebug-local-agent 1.7.0 → 1.9.0

package/test/la-protocol-v2/llm-key.test.js

@@ -0,0 +1,509 @@
+// F3-09 consumer (contract 2.1 (a)): config.update.llmKey on the Local Agent. The key is held in memory (or a 0600 file outside every
+// workspace), is never returned in an ack and never reaches a log, a metric, the audit or any frame the agent sends: a test that SWEEPS
+// every output channel for the key and for its id. Strict validation (id = sha256(key), expiry), rotation, revocation, flag off.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import util from "node:util";
+import { ReferenceCp, TENANT, AGENT, waitFor } from "./helpers/reference-cp.js";
+import { signingFor } from "./helpers/la-rig.js";
+import { buildV2Link } from "../../src/la-protocol-v2/runtime.js";
+import { createLlmKeyHolder, LlmKeyError, insideAny } from "../../src/la-protocol-v2/llm-key/store.js";
+import { resolveLlmKeyConfig } from "../../src/la-protocol-v2/llm-key/config.js";
+
+const tmp = () => fs.mkdtempSync(path.join(os.tmpdir(), "la-llm-"));
+const sha = (s) => crypto.createHash("sha256").update(Buffer.from(s, "utf8")).digest("hex");
+const mkKey = (tag = "A") => `sk-CANARY-LLMKEY-${tag}-${crypto.randomBytes(12).toString("hex")}`;
+const FUTURE = () => new Date(Date.now() + 3_600_000).toISOString();
+const setOf = (key, over = {}) => ({ op: "set", keyId: sha(key), endpoint: "https://ai.visionhammer.io/litellm", key, models: ["vh-claude-sonnet", "vh-embed"], expiresAt: FUTURE(), ...over });
+const noop = () => {};
+
+// ------------------------------------------------------------------------------------------ the flag and the config
+
+test("config: flag off by default (unset, empty, unknown value -> off); on only with true/1/yes/on; the key file must be an absolute path", () => {
+    for (const v of [undefined, "", "false", "0", "off", "nope"]) assert.deepEqual(resolveLlmKeyConfig({ LOCAL_AGENT_LLM_KEY: v }, noop), { enabled: false });
+    for (const v of ["true", "1", "YES", "on"]) assert.equal(resolveLlmKeyConfig({ LOCAL_AGENT_LLM_KEY: v }, noop).enabled, true);
+    const warns = [];
+    assert.equal(resolveLlmKeyConfig({ LOCAL_AGENT_LLM_KEY: "true", LOCAL_AGENT_LLM_KEY_FILE: "relative/key.json" }, (m) => warns.push(m)).file, null);
+    assert.ok(warns.length === 1);
+    assert.equal(resolveLlmKeyConfig({ LOCAL_AGENT_LLM_KEY: "true", LOCAL_AGENT_LLM_KEY_FILE: "/var/lib/la/llm.json" }, noop).file, "/var/lib/la/llm.json");
+});
+
+// ------------------------------------------------------------------------------------------ the holder
+
+function holderWith(extra = {}) {
+    let t = 1_700_000_000_000;
+    const scheduled = [];
+    const timers = { setTimeout: (fn, ms) => { const h = { fn, ms, cleared: false }; scheduled.push(h); return h; }, clearTimeout: (h) => { if (h) h.cleared = true; } };
+    const h = createLlmKeyHolder({ now: () => t, timers, log: { warn: noop }, ...extra });
+    return { h, scheduled, advance: (ms) => { t += ms; }, at: () => new Date(t).toISOString(), now: () => t };
+}
+
+test("holder: set keeps the key, describe() is metadata only, nothing of the key shows in JSON / inspect / enumerable state", () => {
+    const { h, now } = holderWith();
+    const key = mkKey();
+    assert.deepEqual(h.set(setOf(key, { expiresAt: new Date(now() + 60_000).toISOString() })), { ok: true, replaced: false });
+    assert.equal(h.held, true);
+    const d = h.describe();
+    assert.deepEqual(Object.keys(d).sort(), ["expiresAt", "held", "models"]);
+    for (const view of [JSON.stringify(h), util.inspect(h, { depth: 6, showHidden: true }), JSON.stringify(d), JSON.stringify(Object.entries(h)), String(h)]) {
+        assert.ok(!view.includes(key) && !view.includes(sha(key)), "no key, no id");
+    }
+});
+
+test("holder: strict validation: id must be the sha256 of the key, the key must not be expired, shapes are re-checked (schema_violation, nothing stored)", () => {
+    const { h, now } = holderWith();
+    const key = mkKey();
+    for (const bad of [
+        setOf(key, { keyId: sha("another key") }),
+        setOf(key, { expiresAt: new Date(now() - 1000).toISOString() }),
+        setOf(key, { endpoint: "http://ai.visionhammer.io" }),
+        setOf(key, { endpoint: "https://user:pw@ai.visionhammer.io" }),
+        setOf(key, { models: [] }),
+        setOf("short", {}),
+        setOf(key, { key: "with space in the key 1234567890" }),
+    ]) {
+        assert.deepEqual(h.set(bad), { ok: false, code: "schema_violation" });
+    }
+    assert.equal(h.held, false);
+    assert.equal(h.stats.refused, 7);
+});
+
+test("holder: rotation replaces atomically (one key per agent); the same id again is idempotent; the old key is gone", () => {
+    const { h, now } = holderWith();
+    const k1 = mkKey("1"); const k2 = mkKey("2");
+    const exp = new Date(now() + 60_000).toISOString();
+    assert.equal(h.set(setOf(k1, { expiresAt: exp })).replaced, false);
+    assert.equal(h.set(setOf(k1, { expiresAt: exp })).replaced, false, "same keyId again");
+    assert.equal(h.set(setOf(k2, { expiresAt: exp })).replaced, true);
+    assert.equal(h.stats.replaced, 1);
+    assert.deepEqual(h.revoke(sha(k1)), { ok: true, dropped: false }, "the old id is not held any more: a no-op");
+    assert.equal(h.held, true);
+    assert.deepEqual(h.revoke(sha(k2)), { ok: true, dropped: true });
+    assert.equal(h.held, false);
+});
+
+test("holder: revoke of an id it does not hold is a no-op (it never says which key it has)", () => {
+    const { h, now } = holderWith();
+    h.set(setOf(mkKey(), { expiresAt: new Date(now() + 60_000).toISOString() }));
+    assert.deepEqual(h.revoke("f".repeat(64)), { ok: true, dropped: false });
+    assert.equal(h.held, true);
+});
+
+test("holder: the key expires by itself at expiresAt (timer, and a check at every use)", async () => {
+    const { h, scheduled, advance, now } = holderWith();
+    const key = mkKey();
+    h.set(setOf(key, { expiresAt: new Date(now() + 10_000).toISOString() }));
+    assert.equal(scheduled.at(-1).ms, 10_000);
+    advance(10_001);
+    scheduled.at(-1).fn();
+    assert.equal(h.held, false);
+    assert.equal(h.stats.expired, 1);
+    await assert.rejects(h.request("/v1/chat/completions", {}, { fetchImpl: noop }), (e) => e instanceof LlmKeyError && e.code === "no_key");
+    // no timer at all: the use itself notices
+    const b = holderWith();
+    b.h.set(setOf(key, { expiresAt: new Date(b.now() + 10_000).toISOString() }));
+    b.advance(11_000);
+    await assert.rejects(b.h.request("/x", {}, { fetchImpl: noop }), (e) => e.code === "no_key" || e.code === "expired");
+});
+
+test("request(): the hook for a future LLM client: Authorization is set by the holder, redirects refused, the host is never the caller's, paths are checked", async () => {
+    const { h, now } = holderWith();
+    const key = mkKey();
+    h.set(setOf(key, { endpoint: "https://ai.visionhammer.io:8443/litellm/", expiresAt: new Date(now() + 60_000).toISOString() }));
+    const seen = [];
+    const fetchImpl = async (url, init) => { seen.push({ url, init }); return { status: 200 }; };
+    await h.request("/v1/chat/completions?x=1", { method: "POST", headers: { authorization: "Bearer attacker", "content-type": "application/json" }, body: "{}" }, { fetchImpl });
+    assert.equal(seen[0].url, "https://ai.visionhammer.io:8443/litellm/v1/chat/completions?x=1");
+    assert.equal(seen[0].init.headers.get("authorization"), `Bearer ${key}`, "the caller's header is replaced");
+    assert.equal(seen[0].init.headers.get("content-type"), "application/json");
+    assert.equal(seen[0].init.redirect, "error");
+    for (const bad of ["//evil.example/x", "http://evil.example/x", "v1/x", "/a/../b", "/x y", "/x\n", "", null, "/" + "a".repeat(2100)]) {
+        await assert.rejects(h.request(bad, {}, { fetchImpl }), (e) => e instanceof LlmKeyError && e.code === "bad_path", String(bad).slice(0, 20));
+    }
+    assert.equal(seen.length, 1);
+});
+
+test("holder file: mode 0600 in a 0700 directory, atomic replace, overwritten with zeros and unlinked on revoke, reloaded after a restart", () => {
+    const root = tmp();
+    const file = path.join(root, "secrets", "llm.json");
+    const now = Date.now();
+    const key = mkKey();
+    const a = createLlmKeyHolder({ file, log: { warn: noop } });
+    a.set(setOf(key, { expiresAt: new Date(now + 3_600_000).toISOString() }));
+    assert.equal(fs.statSync(file).mode & 0o777, 0o600);
+    assert.equal(fs.statSync(path.dirname(file)).mode & 0o777, 0o700);
+    assert.deepEqual(fs.readdirSync(path.dirname(file)), ["llm.json"], "no temp file left behind");
+    // a restart: a new holder loads it
+    a.close();
+    const b = createLlmKeyHolder({ file, log: { warn: noop } });
+    assert.equal(b.load(), true);
+    assert.equal(b.held, true);
+    assert.equal(b.stats.set, 0, "a reload is not a new delivery");
+    // revoke: the bytes are overwritten before the unlink
+    const size = fs.statSync(file).size;
+    let overwritten = null;
+    const realUnlink = fs.unlinkSync;
+    fs.unlinkSync = (p) => { if (p === file) overwritten = fs.readFileSync(file); return realUnlink(p); };
+    try { b.revoke(sha(key)); } finally { fs.unlinkSync = realUnlink; }
+    assert.equal(fs.existsSync(file), false);
+    assert.equal(overwritten.length, size);
+    assert.ok(overwritten.every((x) => x === 0), "zeros before the unlink");
+});
+
+test("holder file: a file readable by others, an expired one, or a corrupt one is never trusted: wiped, nothing loaded", () => {
+    const root = tmp();
+    const file = path.join(root, "llm.json");
+    const key = mkKey();
+    const body = (over = {}) => JSON.stringify({ v: 1, keyId: sha(key), endpoint: "https://ai.visionhammer.io", key, models: ["m"], expiresAt: FUTURE(), ...over });
+    fs.writeFileSync(file, body(), { mode: 0o644 });
+    fs.chmodSync(file, 0o644);
+    assert.equal(createLlmKeyHolder({ file, log: { warn: noop } }).load(), false);
+    assert.equal(fs.existsSync(file), false, "world-readable key file: wiped");
+    fs.writeFileSync(file, body({ expiresAt: new Date(Date.now() - 1000).toISOString() }), { mode: 0o600 });
+    assert.equal(createLlmKeyHolder({ file, log: { warn: noop } }).load(), false);
+    assert.equal(fs.existsSync(file), false);
+    fs.writeFileSync(file, "{not json", { mode: 0o600 });
+    assert.equal(createLlmKeyHolder({ file, log: { warn: noop } }).load(), false);
+    fs.writeFileSync(file, body({ keyId: sha("other") }), { mode: 0o600 });
+    assert.equal(createLlmKeyHolder({ file, log: { warn: noop } }).load(), false, "id is not the sha256 of the key");
+});
+
+test("holder file: a path inside a workspace is refused (the key stays in memory only, nothing is written there)", () => {
+    const ws = tmp();
+    const warns = [];
+    const file = path.join(ws, "sub", "llm.json");
+    const h = createLlmKeyHolder({ file, workspaceRoots: () => [ws], log: { warn: (m) => warns.push(m) } });
+    h.set(setOf(mkKey(), { expiresAt: FUTURE() }));
+    assert.equal(h.held, true, "memory");
+    assert.equal(fs.existsSync(path.join(ws, "sub")), false, "nothing written inside the workspace");
+    assert.ok(warns.some((m) => /inside a workspace/.test(m)));
+    assert.ok(!warns.join("\n").includes(ws), "the warning does not print the path");
+    assert.equal(insideAny(path.join(tmp(), "x.json"), [ws]), false);
+    assert.equal(insideAny(path.join(ws, "x.json"), [ws]), true);
+});
+
+// ------------------------------------------------------------------------------------------ the handler on the real link
+
+async function linkFor(cp, env, root = tmp()) {
+    const logs = [];
+    const log = { info: (m) => logs.push(String(m)), log: (m) => logs.push(String(m)), warn: (m) => logs.push(String(m)), error: (m) => logs.push(String(m)) };
+    const wsManager = { list: () => [{ id: "ws-1", root, tenantId: TENANT }] };
+    const link = await buildV2Link({ tenantId: TENANT, agentId: AGENT, signing: signingFor({ keyId: cp.keyId, publicKeyRaw: cp.publicKeyRaw }, "enforce"), wsManager, getWorkspaceRoot: () => root, log, env });
+    const transport = { send: (t) => cp.feed(t), close() {}, bufferedAmount: () => 0 };
+    cp.attach((t) => queueMicrotask(() => link.session.handleText(t, transport)), () => {});
+    link.session.attach(transport);
+    await waitFor(() => link.session.state === "ready");
+    return { link, logs, transport, root };
+}
+
+/** Everything the process printed while `fn` ran: console.* and the two std streams. */
+async function capturingOutput(fn) {
+    const out = [];
+    const saved = {};
+    for (const m of ["log", "info", "warn", "error", "debug"]) { saved[m] = console[m]; console[m] = (...a) => out.push(util.format(...a)); }
+    const so = process.stdout.write; const se = process.stderr.write;
+    process.stdout.write = (c, ...r) => { out.push(String(c)); const cb = r.find((x) => typeof x === "function"); if (cb) cb(); return true; };
+    process.stderr.write = (c, ...r) => { out.push(String(c)); const cb = r.find((x) => typeof x === "function"); if (cb) cb(); return true; };
+    try { await fn(); } finally { for (const m of Object.keys(saved)) console[m] = saved[m]; process.stdout.write = so; process.stderr.write = se; }
+    return out;
+}
+
+test("flag off (unset or any non-true value): `llm.key` is not announced, config.update is acked protocol_unsupported, no holder, nothing stored", async () => {
+    for (const v of [undefined, "false", "maybe"]) {
+        const dir = tmp();
+        const file = path.join(dir, "llm.json");
+        const cp = new ReferenceCp();
+        const { link } = await linkFor(cp, { LOCAL_AGENT_LLM_KEY: v, LOCAL_AGENT_LLM_KEY_FILE: file });
+        assert.deepEqual([...cp.registers[0].capabilities].sort(), ["chunk.base64", "protocol.v2", "v1.commands"], "register is exactly the baseline");
+        assert.equal(link.llm, undefined);
+        cp.sendData("config.update", { llmKey: setOf(mkKey()) });
+        await waitFor(() => cp.acksFromLa.length === 1);
+        assert.deepEqual(cp.acksFromLa[0], { ackSeq: 1, status: "rejected", errorCode: "protocol_unsupported" });
+        assert.equal(fs.existsSync(file), false);
+        link.close();
+    }
+});
+
+test("flag on: llm.key + contract.v2.1 announced; set -> accepted; the ack is the plain ack; the holder has the key; rotation and revoke work end to end (real signatures)", async () => {
+    const cp = new ReferenceCp();
+    const { link } = await linkFor(cp, { LOCAL_AGENT_LLM_KEY: "true" });
+    assert.ok(cp.registers[0].capabilities.includes("llm.key"));
+    assert.ok(cp.registers[0].capabilities.includes("contract.v2.1"));
+    assert.ok(cp.hellos[0].capabilities.includes("llm.key"));
+    const k1 = mkKey("1"); const k2 = mkKey("2");
+    cp.sendData("config.update", { llmKey: setOf(k1) });
+    await waitFor(() => cp.acksFromLa.length === 1);
+    assert.deepEqual(cp.acksFromLa[0], { ackSeq: 1, status: "accepted", errorCode: undefined });
+    assert.equal(link.llm.holder.held, true);
+    cp.sendData("config.update", { llmKey: setOf(k2) });
+    await waitFor(() => cp.acksFromLa.length === 2);
+    assert.equal(cp.acksFromLa[1].status, "accepted");
+    assert.equal(link.llm.holder.stats.replaced, 1);
+    // the old key's revoke is a no-op, the new key stays
+    cp.sendData("config.update", { llmKey: { op: "revoke", keyId: sha(k1) } });
+    await waitFor(() => cp.acksFromLa.length === 3);
+    assert.equal(cp.acksFromLa[2].status, "accepted");
+    assert.equal(link.llm.holder.held, true);
+    cp.sendData("config.update", { llmKey: { op: "revoke", keyId: sha(k2) } });
+    await waitFor(() => cp.acksFromLa.length === 4);
+    assert.equal(cp.acksFromLa[3].status, "accepted");
+    assert.equal(link.llm.holder.held, false);
+    link.close();
+});
+
+test("flag on: a key that the LA refuses is `rejected schema_violation` (non-fatal): id is not the sha256, already expired; a config.update without llmKey is protocol_unsupported as before", async () => {
+    const cp = new ReferenceCp();
+    const { link } = await linkFor(cp, { LOCAL_AGENT_LLM_KEY: "true" });
+    cp.sendData("config.update", { llmKey: setOf(mkKey(), { keyId: sha("not the key") }) });
+    cp.sendData("config.update", { llmKey: setOf(mkKey(), { expiresAt: new Date(Date.now() - 5000).toISOString() }) });
+    cp.sendData("config.update", { flags: [{ name: "some.flag", enabled: true }] });
+    await waitFor(() => cp.acksFromLa.length === 3);
+    assert.deepEqual(cp.acksFromLa.map((a) => [a.status, a.errorCode]), [["rejected", "schema_violation"], ["rejected", "schema_violation"], ["rejected", "protocol_unsupported"]]);
+    assert.equal(link.llm.holder.held, false);
+    assert.equal(link.session.state, "ready", "not fatal");
+    assert.deepEqual(cp.errorsSent, []);
+    link.close();
+});
+
+test("cross-tenant: a config.update of another tenant is refused before the handler and no key is stored", async () => {
+    const cp = new ReferenceCp();
+    const { link, transport } = await linkFor(cp, { LOCAL_AGENT_LLM_KEY: "true" });
+    try {
+        const frame = cp.frameWith("config.update", { llmKey: setOf(mkKey()) });
+        frame.tenantId = "99999999-5a4d-4e7b-9c21-0a1b2c3d4e5f";
+        link.session.handleText(JSON.stringify(frame), transport);
+        await waitFor(() => cp.peerErrors.length > 0);
+        assert.ok(["tenant_mismatch", "unauthorized", "params_mismatch"].includes(cp.peerErrors[0]), cp.peerErrors[0]);
+        assert.equal(link.llm.holder.held, false);
+        assert.equal(link.llm.handler.stats.frames, 0);
+    } finally { link.close(); }
+});
+
+test("two links (two tenants) never share a holder: a key set on one is not on the other", async () => {
+    const cp = new ReferenceCp();
+    const a = await linkFor(cp, { LOCAL_AGENT_LLM_KEY: "true" });
+    const cp2 = new ReferenceCp();
+    const b = await linkFor(cp2, { LOCAL_AGENT_LLM_KEY: "true" });
+    try {
+        cp.sendData("config.update", { llmKey: setOf(mkKey()) });
+        await waitFor(() => cp.acksFromLa.length >= 1);
+        assert.equal(a.link.llm.holder.held, true);
+        assert.equal(b.link.llm.holder.held, false);
+    } finally { a.link.close(); b.link.close(); }
+});
+
+test("SWEEP: the key and its id appear in no ack, no frame the agent sends, no log, no console/stdout/stderr output, no audit record, no stats, no file but the 0600 one", async () => {
+    const dir = tmp();
+    const file = path.join(dir, "secrets", "llm.json");
+    const audit = path.join(dir, "audit.jsonl");
+    const cp = new ReferenceCp();
+    const keys = [mkKey("sweep-1"), mkKey("sweep-2"), mkKey("sweep-3")];
+    const secrets = keys.flatMap((k) => [k, sha(k)]);
+    let linkRef;
+    const printed = await capturingOutput(async () => {
+        const { link, logs } = await linkFor(cp, { LOCAL_AGENT_LLM_KEY: "true", LOCAL_AGENT_LLM_KEY_FILE: file, LOCAL_AGENT_CONTENT_AUDIT_FILE: audit });
+        linkRef = { link, logs };
+        cp.sendData("config.update", { llmKey: setOf(keys[0]) });                                    // set
+        cp.sendData("config.update", { llmKey: setOf(keys[1]) });                                    // rotation
+        cp.sendData("config.update", { llmKey: setOf(keys[2], { keyId: sha("wrong") }) });           // refused
+        cp.sendData("config.update", { llmKey: setOf(keys[2], { expiresAt: new Date(Date.now() - 1000).toISOString() }) });   // refused (expired)
+        cp.sendData("config.update", { llmKey: { op: "revoke", keyId: sha(keys[0]) } });             // revoke of an old id
+        await waitFor(() => cp.acksFromLa.length === 5);
+        await link.llm.request("/v1/models", {}, { fetchImpl: async () => ({ status: 200 }) }).catch(noop);
+        cp.sendData("config.update", { llmKey: { op: "revoke", keyId: sha(keys[1]) } });             // revoke the held one
+        await waitFor(() => cp.acksFromLa.length === 6);
+    });
+    const { link, logs } = linkRef;
+    const channels = {
+        "frames the agent sent": cp.rawIn.join("\n"),
+        "acks": JSON.stringify(cp.acksFromLa),
+        "agent logs": logs.join("\n"),
+        "console and std streams": printed.join("\n"),
+        "audit ring": JSON.stringify(link.llm.audit.tail(1000)),
+        "handler/holder/session stats": JSON.stringify([link.llm.holder.stats, link.llm.handler.stats, link.session.snapshot, link.session.stats]),
+        "the holder object": JSON.stringify(link.llm.holder) + util.inspect(link.llm, { depth: 8, showHidden: true }),
+    };
+    if (fs.existsSync(audit)) channels["audit file"] = fs.readFileSync(audit, "utf8");
+    for (const [name, text] of Object.entries(channels)) {
+        for (const s of secrets) assert.ok(!text.includes(s), `a secret leaked into: ${name}`);
+    }
+    // the acks have exactly the ack shape, and no LA->CP frame has a key / llmKey / keyId field (contract pin)
+    for (const raw of cp.rawIn) {
+        const f = JSON.parse(raw);
+        const walk = (o) => { if (o && typeof o === "object") for (const [k, v] of Object.entries(o)) { assert.ok(!["key", "llmKey", "keyId"].includes(k), `field ${k} in a ${f.type} frame`); walk(v); } };
+        walk(f);
+    }
+    for (const a of cp.acksFromLa) assert.deepEqual(Object.keys(a).filter((k) => a[k] !== undefined).sort(), a.status === "rejected" ? ["ackSeq", "errorCode", "status"] : ["ackSeq", "status"]);
+    // after the revoke nothing is left on disk, and the file was never readable by others
+    assert.equal(fs.existsSync(file), false);
+    assert.equal(link.llm.holder.held, false);
+    // no key material anywhere under the temp dir
+    const stack = [dir]; const found = [];
+    while (stack.length) { const d = stack.pop(); for (const e of fs.readdirSync(d, { withFileTypes: true })) { const p = path.join(d, e.name); if (e.isDirectory()) stack.push(p); else found.push(p); } }
+    for (const p of found) for (const s of secrets) assert.ok(!fs.readFileSync(p, "utf8").includes(s), "a secret is on disk");
+    link.close();
+});
+
+test("flag on with a key file: the key survives a restart (loaded when the link is built), file 0600 outside the workspace, and is dropped at revoke", async () => {
+    const dir = tmp();
+    const root = path.join(dir, "ws");
+    fs.mkdirSync(root);
+    const file = path.join(dir, "secrets", "llm.json");
+    const cp = new ReferenceCp();
+    const key = mkKey("restart");
+    const a = await linkFor(cp, { LOCAL_AGENT_LLM_KEY: "true", LOCAL_AGENT_LLM_KEY_FILE: file }, root);
+    cp.sendData("config.update", { llmKey: setOf(key) });
+    await waitFor(() => cp.acksFromLa.length === 1);
+    assert.equal(fs.statSync(file).mode & 0o777, 0o600);
+    a.link.close();
+    const cp2 = new ReferenceCp();
+    const b = await linkFor(cp2, { LOCAL_AGENT_LLM_KEY: "true", LOCAL_AGENT_LLM_KEY_FILE: file }, root);
+    assert.equal(b.link.llm.holder.held, true, "loaded from the file");
+    cp2.sendData("config.update", { llmKey: { op: "revoke", keyId: sha(key) } });
+    await waitFor(() => cp2.acksFromLa.length === 1);
+    assert.equal(fs.existsSync(file), false);
+    b.link.close();
+    // a file path inside the workspace is refused
+    const c = await linkFor(new ReferenceCp(), { LOCAL_AGENT_LLM_KEY: "true", LOCAL_AGENT_LLM_KEY_FILE: path.join(root, "llm.json") }, root);
+    assert.ok(c.logs.some((l) => /inside a workspace/.test(l)));
+    c.link.close();
+});
+
+// ------------------------------------------------------------------------------------------ llm.key.held (contract 2.1 (e))
+
+/** A new connection of the same link (what the tunnel does after a dropped socket): detach, the CP sees a new attach, register + hello again. */
+async function reconnect(cp, link, transport) {
+    const before = cp.registers.length;
+    link.session.detach(transport);
+    cp.attach((t) => queueMicrotask(() => link.session.handleText(t, transport)), () => {});
+    link.session.attach(transport);
+    await waitFor(() => link.session.state === "ready" && cp.registers.length === before + 1 && cp.hellos.length === before + 1);
+}
+const HELD = "llm.key.held";
+
+test("llm.key.held: not announced without a key (flag on, nothing delivered yet); announced from the NEXT connection once a valid key is held, in register AND hello", async () => {
+    const cp = new ReferenceCp();
+    const { link, transport } = await linkFor(cp, { LOCAL_AGENT_LLM_KEY: "true" });
+    assert.ok(cp.registers[0].capabilities.includes("llm.key") && !cp.registers[0].capabilities.includes(HELD));
+    assert.ok(cp.hellos[0].capabilities.includes("llm.key") && !cp.hellos[0].capabilities.includes(HELD));
+    cp.sendData("config.update", { llmKey: setOf(mkKey("held-1")) });
+    await waitFor(() => cp.acksFromLa.length === 1);
+    assert.equal(cp.registers[0].capabilities.includes(HELD), false, "the announcement is a snapshot taken at connect time");
+    await reconnect(cp, link, transport);
+    for (const frame of [cp.registers[1], cp.hellos[1]]) {
+        assert.ok(frame.capabilities.includes(HELD), "held");
+        assert.ok(frame.capabilities.includes("llm.key"), "never without llm.key (the CP's schema refuses it alone)");
+    }
+    assert.deepEqual(cp.registers[1].capabilities, cp.hellos[1].capabilities, "register and hello of one session carry the same answer");
+    assert.deepEqual(cp.errorsSent, [], "the real CP schema accepted both frames");
+    link.close();
+});
+
+test("llm.key.held: a revoked key is no longer announced from the next connection; a refused or expired one never was", async () => {
+    const cp = new ReferenceCp();
+    const { link, transport } = await linkFor(cp, { LOCAL_AGENT_LLM_KEY: "true" });
+    const key = mkKey("held-2");
+    cp.sendData("config.update", { llmKey: setOf(key) });
+    cp.sendData("config.update", { llmKey: setOf(mkKey("bad"), { keyId: sha("not the key") }) });   // refused: the held key stays
+    await waitFor(() => cp.acksFromLa.length === 2);
+    await reconnect(cp, link, transport);
+    assert.ok(cp.registers[1].capabilities.includes(HELD));
+    cp.sendData("config.update", { llmKey: { op: "revoke", keyId: sha(key) } });
+    await waitFor(() => cp.acksFromLa.length === 3);
+    await reconnect(cp, link, transport);
+    assert.ok(!cp.registers[2].capabilities.includes(HELD) && !cp.hellos[2].capabilities.includes(HELD), "revoked");
+    assert.ok(cp.registers[2].capabilities.includes("llm.key"), "it can still receive a new key");
+    link.close();
+});
+
+test("llm.key.held: a key that EXPIRED while connected is not announced on the next connection (the holder checks the clock, not only its timer)", async () => {
+    const cp = new ReferenceCp();
+    const { link, transport } = await linkFor(cp, { LOCAL_AGENT_LLM_KEY: "true" });
+    cp.sendData("config.update", { llmKey: setOf(mkKey("held-3"), { expiresAt: new Date(Date.now() + 350).toISOString() }) });
+    await waitFor(() => cp.acksFromLa.length === 1);
+    assert.equal(link.llm.holder.held, true);
+    await new Promise((r) => setTimeout(r, 450));
+    await reconnect(cp, link, transport);
+    assert.ok(!cp.registers[1].capabilities.includes(HELD));
+    assert.equal(link.llm.holder.held, false);
+    link.close();
+});
+
+test("llm.key.held: after a restart a file key is announced at once (the first register), a memory-only agent is not; the file is 0600 in a 0700 directory", async () => {
+    const dir = tmp();
+    const root = path.join(dir, "ws");
+    fs.mkdirSync(root);
+    const file = path.join(dir, "secrets", "llm.json");
+    const key = mkKey("held-4");
+    const cp = new ReferenceCp();
+    const a = await linkFor(cp, { LOCAL_AGENT_LLM_KEY: "true", LOCAL_AGENT_LLM_KEY_FILE: file }, root);
+    cp.sendData("config.update", { llmKey: setOf(key) });
+    await waitFor(() => cp.acksFromLa.length === 1);
+    assert.equal(fs.statSync(file).mode & 0o777, 0o600, "file 0600");
+    assert.equal(fs.statSync(path.dirname(file)).mode & 0o777, 0o700, "directory 0700");
+    a.link.close();
+    // restart WITH the file: held from the first frame
+    const cp2 = new ReferenceCp();
+    const b = await linkFor(cp2, { LOCAL_AGENT_LLM_KEY: "true", LOCAL_AGENT_LLM_KEY_FILE: file }, root);
+    assert.ok(cp2.registers[0].capabilities.includes(HELD) && cp2.hellos[0].capabilities.includes(HELD));
+    b.link.close();
+    // restart WITHOUT a file (memory only): the key is gone, so it is not announced and the CP delivers again
+    const cp3 = new ReferenceCp();
+    const c = await linkFor(cp3, { LOCAL_AGENT_LLM_KEY: "true" }, root);
+    assert.ok(!cp3.registers[0].capabilities.includes(HELD));
+    assert.ok(cp3.registers[0].capabilities.includes("llm.key"));
+    c.link.close();
+    fs.rmSync(dir, { recursive: true, force: true });
+});
+
+test("llm.key.held: flag off = never announced (not even a leftover key file), and the capability string carries no key material", async () => {
+    const dir = tmp();
+    const file = path.join(dir, "llm.json");
+    const key = mkKey("held-5");
+    const cp = new ReferenceCp();
+    const a = await linkFor(cp, { LOCAL_AGENT_LLM_KEY: "true", LOCAL_AGENT_LLM_KEY_FILE: file });
+    cp.sendData("config.update", { llmKey: setOf(key) });
+    await waitFor(() => cp.acksFromLa.length === 1);
+    await reconnect(cp, a.link, a.transport);
+    const wire = JSON.stringify([cp.registers[1], cp.hellos[1]]);
+    assert.ok(wire.includes(HELD) && !wire.includes(key) && !wire.includes(sha(key)), "the announcement is a name, never the key or its id");
+    a.link.close();
+    const cp2 = new ReferenceCp();
+    const b = await linkFor(cp2, { LOCAL_AGENT_LLM_KEY: "false", LOCAL_AGENT_LLM_KEY_FILE: file });
+    assert.deepEqual([...cp2.registers[0].capabilities].sort(), ["chunk.base64", "protocol.v2", "v1.commands"]);
+    b.link.close();
+});
+
+test("session: dynamic capabilities are evaluated at EVERY attach; a throwing provider announces nothing extra; llm.key.held never goes out without llm.key", async () => {
+    const { ReferenceCp: Cp } = await import("./helpers/reference-cp.js");
+    const { inMemory } = await import("./helpers/la-rig.js");
+    let extra = [];
+    const cp = new Cp();
+    const env = inMemory(cp, { sessionOptions: { capabilities: ["protocol.v2", "llm.key"], dynamicCapabilities: () => extra } }).start();
+    await waitFor(() => env.session.state === "ready");
+    assert.deepEqual(cp.registers[0].capabilities, ["llm.key", "protocol.v2"]);
+    extra = [HELD, "BAD NAME", 7, HELD];
+    env.session.detach(env.transport);
+    cp.attach((t) => queueMicrotask(() => env.session.handleText(t, env.transport)), () => {});
+    env.session.attach(env.transport);
+    await waitFor(() => cp.registers.length === 2);
+    assert.deepEqual(cp.registers[1].capabilities, ["llm.key", HELD, "protocol.v2"], "deduplicated, valid names only, sorted");
+    assert.deepEqual(cp.registers[1].capabilities, JSON.parse(env.wire.toCp.filter((t) => JSON.parse(t).type === "hello").at(-1)).payload.capabilities);
+    env.session.close();
+    // no llm.key: the dependent capability is dropped instead of producing a frame the CP would refuse
+    const cp2 = new Cp();
+    const env2 = inMemory(cp2, { sessionOptions: { capabilities: ["protocol.v2"], dynamicCapabilities: () => { throw new Error("boom"); } } }).start();
+    await waitFor(() => env2.session.state === "ready");
+    assert.deepEqual(cp2.registers[0].capabilities, ["protocol.v2"]);
+    env2.session.close();
+    const cp3 = new Cp();
+    const env3 = inMemory(cp3, { sessionOptions: { capabilities: ["protocol.v2"], dynamicCapabilities: () => [HELD] } }).start();
+    await waitFor(() => env3.session.state === "ready");
+    assert.deepEqual(cp3.registers[0].capabilities, ["protocol.v2"]);
+    assert.deepEqual(cp3.errorsSent, []);
+    env3.session.close();
+});

package/test/la-protocol-v2/traces.test.js

@@ -18,9 +18,9 @@ import { V2Session } from "../../src/la-protocol-v2/session.js";
 const DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), "../contract/la-protocol-v2/vectors/traces");
 const traces = fs.readdirSync(DIR).filter((f) => f.endsWith(".json")).sort().map((f) => ({ file: f, name: f.replace(".json", ""), ...JSON.parse(fs.readFileSync(path.join(DIR, f), "utf8")) }));
 
-test("the suite has all 26 traces (21 invalid, 5 valid)", () => {
-    assert.equal(traces.length, 26);
-    assert.equal(traces.filter((t) => t.expect.ok).length, 5);
+test("the suite has all 34 traces (28 invalid, 6 valid: 26 of 2.0 + 8 of the chunked webhooks of 2.1)", () => {
+    assert.equal(traces.length, 34);
+    assert.equal(traces.filter((t) => t.expect.ok).length, 6);
 });
 
 const textOf = (fr) => {