deepdebug-local-agent 1.3.0 → 1.5.0

package/test/la-protocol-v2/content-path-guard.test.js

@@ -0,0 +1,214 @@
+// F3-07: the Local Agent is the authority on paths. normalizeRel, the deny list, symlinks, the opaque ids.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { normalizeRel, isSensitivePath, resolveInside, readRegular, DEFAULT_DENY_GLOBS } from "../../src/la-protocol-v2/content-handlers/path-guard.js";
+import { ContentRefRegistry, REF_PATTERN } from "../../src/la-protocol-v2/content-handlers/ref-registry.js";
+import { tmpDir, write } from "./helpers/content-rig.js";
+
+// ------------------------------------------------------------------------------------------ normalizeRel
+
+test("normalizeRel: plain relative paths pass, normalized to posix", () => {
+    assert.equal(normalizeRel("src/a.js"), "src/a.js");
+    assert.equal(normalizeRel("./src//a.js"), "src/a.js");
+    assert.equal(normalizeRel("src\\sub\\a.js"), "src/sub/a.js");
+    assert.equal(normalizeRel("ficheiro-ção-日本.txt"), "ficheiro-ção-日本.txt");
+});
+
+test("normalizeRel: traversal, absolutes, NUL and control characters, empty and huge are refused", () => {
+    for (const bad of ["../x", "a/../../x", "a/..", "..", "..\\x", "a\\..\\..\\x", "/etc/passwd", "\\\\server\\share", "C:\\Windows\\win.ini", "c:/x",
+        "a\u0000b", "a\nb", "a\u001fb", "a\u007fb", "", ".", "./", "//", "x".repeat(1025), null, undefined, 42, {}, ["a"]]) {
+        assert.equal(normalizeRel(bad), null, JSON.stringify(bad)?.slice(0, 40));
+    }
+});
+
+test("normalizeRel: a literal %2e%2e is just a file name (nothing is ever URL-decoded)", () => {
+    assert.equal(normalizeRel("%2e%2e/etc/passwd"), "%2e%2e/etc/passwd");
+    assert.equal(normalizeRel("a/%2e%2e"), "a/%2e%2e");
+    assert.equal(normalizeRel("..%2f..%2fx"), "..%2f..%2fx");
+});
+
+// ------------------------------------------------------------------------------------------ deny list
+
+test("deny list: secrets by name, keys, credentials, VCS internals (case-insensitive, any depth)", () => {
+    for (const p of [".env", ".env.local", ".env.production", "app/.ENV", "config/prod.env", "certs/server.pem", "k/private.KEY", "a/b/id_rsa", "id_ed25519.pub",
+        "keystore.jks", ".npmrc", "web/.npmrc", ".netrc", ".git/config", "sub/.git/config", ".git/hooks/pre-commit", ".ssh/id_rsa", "home/.ssh/known_hosts",
+        ".aws/credentials", ".docker/config.json", "terraform.tfstate", "infra/prod.tfvars", "service-account-prod.json", "secrets.yaml", ".htpasswd",
+        ".env.", ".env ", "x/.ENV.", ".config/gcloud/credentials.db"]) {
+        assert.equal(isSensitivePath(p), true, p);
+    }
+});
+
+test("deny list: ordinary files are not caught (no false positives on look-alikes)", () => {
+    for (const p of ["src/environment.js", "README.md", "src/keyboard.js", "src/monkey.js", "docs/pem-format.md", "environment/readme.txt", "src/secretary.js", "gitignore.txt", "src/.github/workflows/ci.yml", "src/auth/credentials.js"]) {
+        assert.equal(isSensitivePath(p), false, p);
+    }
+});
+
+test("deny list: LOCAL_AGENT_CONTENT_DENY_GLOBS adds to the built-in list, never replaces it", () => {
+    assert.equal(isSensitivePath("vault/data.txt", ["vault/"]), true);
+    assert.equal(isSensitivePath("docs/internal-*.md".replace("*", "x"), ["internal-*.md"]), true);
+    assert.equal(isSensitivePath(".env", ["vault/"]), true);
+    assert.equal(isSensitivePath("src/a.js", ["vault/"]), false);
+    assert.ok(DEFAULT_DENY_GLOBS.includes(".env.*"));
+});
+
+// ------------------------------------------------------------------------------------------ resolveInside
+
+function fixture() {
+    const base = tmpDir();
+    const root = path.join(base, "ws"); fs.mkdirSync(root);
+    const outside = path.join(base, "outside"); fs.mkdirSync(outside);
+    write(root, "src/a.txt", "hello");
+    write(root, "src/ü ñ 日本.txt", "unicode");
+    write(root, ".env", "TOKEN=1");
+    write(root, ".git/config", "[remote]\nurl=https://u:p@h/r");
+    write(outside, "secret.txt", "TOP SECRET OUTSIDE");
+    write(outside, "inner/more.txt", "outside dir file");
+    return { base, root, outside, done: () => fs.rmSync(base, { recursive: true, force: true }) };
+}
+
+test("resolveInside: a regular file inside the root resolves; unicode names work", async () => {
+    const f = fixture();
+    try {
+        const r = await resolveInside(f.root, "src/a.txt");
+        assert.equal(r.ok, true);
+        assert.equal(r.relReal, "src/a.txt");
+        assert.equal((await resolveInside(f.root, "src/ü ñ 日本.txt")).ok, true);
+    } finally { f.done(); }
+});
+
+test("resolveInside: symlinks that leave the workspace are forbidden (file, directory, chained, relative)", async () => {
+    const f = fixture();
+    try {
+        fs.symlinkSync(path.join(f.outside, "secret.txt"), path.join(f.root, "link-file"));
+        fs.symlinkSync(f.outside, path.join(f.root, "link-dir"));
+        fs.symlinkSync("../outside/secret.txt", path.join(f.root, "link-rel"));
+        fs.symlinkSync("link-file", path.join(f.root, "link-chain"));
+        fs.symlinkSync("/etc/passwd", path.join(f.root, "link-etc"));
+        for (const rel of ["link-file", "link-dir/secret.txt", "link-dir/inner/more.txt", "link-rel", "link-chain", "link-etc"]) {
+            const r = await resolveInside(f.root, rel);
+            assert.deepEqual(r, { ok: false, status: "forbidden" }, rel);
+        }
+    } finally { f.done(); }
+});
+
+test("resolveInside: a link inside the root to a file inside the root is fine, but not when the real target is sensitive", async () => {
+    const f = fixture();
+    try {
+        fs.symlinkSync("a.txt", path.join(f.root, "src", "alias.txt"));
+        assert.equal((await resolveInside(f.root, "src/alias.txt")).ok, true);
+        fs.symlinkSync("../.env", path.join(f.root, "src", "innocent.txt"));
+        assert.deepEqual(await resolveInside(f.root, "src/innocent.txt"), { ok: false, status: "forbidden" });
+        fs.symlinkSync("../.git/config", path.join(f.root, "src", "gitcfg.txt"));
+        assert.deepEqual(await resolveInside(f.root, "src/gitcfg.txt"), { ok: false, status: "forbidden" });
+    } finally { f.done(); }
+});
+
+test("resolveInside: a root that is itself reached through a symlink works (/var -> /private/var style), and a sibling dir with the same prefix is NOT inside", async () => {
+    const f = fixture();
+    try {
+        const viaLink = path.join(f.base, "root-link");
+        fs.symlinkSync(f.root, viaLink);
+        assert.equal((await resolveInside(viaLink, "src/a.txt")).ok, true);
+        // /base/ws vs /base/ws-evil: startsWith without a separator would accept it
+        const evil = path.join(f.base, "ws-evil"); fs.mkdirSync(evil);
+        write(evil, "x.txt", "evil");
+        fs.symlinkSync(path.join(evil, "x.txt"), path.join(f.root, "to-evil"));
+        assert.deepEqual(await resolveInside(f.root, "to-evil"), { ok: false, status: "forbidden" });
+    } finally { f.done(); }
+});
+
+test("resolveInside: missing, directories and sensitive names; no message ever carries a path", async () => {
+    const f = fixture();
+    try {
+        assert.deepEqual(await resolveInside(f.root, "src/missing.txt"), { ok: false, status: "not_found" });
+        assert.deepEqual(await resolveInside(f.root, "src"), { ok: false, status: "not_found" });
+        assert.deepEqual(await resolveInside(f.root, ".env"), { ok: false, status: "forbidden" });
+        assert.deepEqual(await resolveInside(f.root, ".git/config"), { ok: false, status: "forbidden" });
+        assert.deepEqual(await resolveInside(path.join(f.base, "nope"), "a"), { ok: false, status: "not_found" });
+        // a sensitive name is forbidden whether or not it exists: no oracle on what a workspace contains
+        assert.deepEqual(await resolveInside(f.root, ".env.production"), { ok: false, status: "forbidden" });
+        assert.deepEqual(await resolveInside(f.root, "deep/er/id_rsa"), { ok: false, status: "forbidden" });
+        assert.deepEqual(Object.keys(await resolveInside(f.root, ".env")).sort(), ["ok", "status"]);
+    } finally { f.done(); }
+});
+
+test("readRegular: size cap before reading, exact bytes, the file swapped for a link after the check is refused", async () => {
+    const f = fixture();
+    try {
+        write(f.root, "big.bin", Buffer.alloc(5000, 7));
+        const big = await resolveInside(f.root, "big.bin");
+        assert.deepEqual(await readRegular(big, 4999), { ok: false, status: "too_large" });
+        const ok = await readRegular(big, 5000);
+        assert.equal(ok.ok, true);
+        assert.equal(ok.buffer.length, 5000);
+        // TOCTOU on the last component: checked as a file, swapped for a link to a file outside before the open
+        const a = await resolveInside(f.root, "src/a.txt");
+        fs.rmSync(path.join(f.root, "src/a.txt"));
+        fs.symlinkSync(path.join(f.outside, "secret.txt"), path.join(f.root, "src/a.txt"));
+        const swapped = await readRegular(a, 1000);
+        assert.equal(swapped.ok, false);
+        assert.ok(swapped.status === "forbidden" || swapped.status === "not_found");
+    } finally { f.done(); }
+});
+
+// ------------------------------------------------------------------------------------------ ids
+
+test("ids: 128 random bits, not derived from the path, a fresh id per mint", () => {
+    const reg = new ContentRefRegistry({ tenantId: "t1" });
+    const a = reg.mint({ workspaceId: "w", root: "/r", kind: "file", rel: "src/a.txt" });
+    const b = reg.mint({ workspaceId: "w", root: "/r", kind: "file", rel: "src/a.txt" });
+    assert.match(a.id, REF_PATTERN);
+    assert.equal(a.id.length, 4 + 22);
+    assert.notEqual(a.id, b.id);
+    assert.equal(a.id.includes("a.txt") || a.id.includes("src"), false);
+    const ids = new Set(Array.from({ length: 2000 }, () => reg.mint({ workspaceId: "w", root: "/r", kind: "file", rel: "x" }).id));
+    assert.equal(ids.size, 2000);
+});
+
+test("ids: resolve only for the same tenant, workspace, root and kind; anything else is null (indistinguishable from unknown)", () => {
+    const reg = new ContentRefRegistry({ tenantId: "t1" });
+    const { id } = reg.mint({ workspaceId: "w1", root: "/r1", kind: "file", rel: "src/a.txt" });
+    assert.deepEqual(reg.resolve(id, { workspaceId: "w1", root: "/r1", kind: "file" }), { rel: "src/a.txt" });
+    assert.equal(reg.resolve(id, { workspaceId: "w2", root: "/r1", kind: "file" }), null, "other workspace");
+    assert.equal(reg.resolve(id, { workspaceId: "w1", root: "/r2", kind: "file" }), null, "same workspace id, re-opened on another root");
+    assert.equal(reg.resolve(id, { workspaceId: "w1", root: "/r1", kind: "diff" }), null, "other kind");
+    const other = new ContentRefRegistry({ tenantId: "t2" });
+    assert.equal(other.resolve(id, { workspaceId: "w1", root: "/r1", kind: "file" }), null, "other tenant's registry");
+    for (const junk of ["", "x", "cr1_", "cr1_short", `${id}0`, `${id.slice(0, -1)}!`, "../etc/passwd", "/etc/passwd", "src/a.txt", "%2e%2e", "a\u0000b", 42, null, undefined, {}]) {
+        assert.equal(reg.resolve(junk, { workspaceId: "w1", root: "/r1", kind: "file" }), null);
+    }
+});
+
+test("ids: TTL (expired = gone for good), capacity (oldest first), revoke", () => {
+    let t = 1_000_000;
+    const reg = new ContentRefRegistry({ tenantId: "t1", ttlMs: 10_000, maxEntries: 3, now: () => t });
+    const q = { workspaceId: "w", root: "/r", kind: "file" };
+    const { id } = reg.mint({ ...q, rel: "a" });
+    t += 9_999;
+    assert.ok(reg.resolve(id, q));
+    t += 2;
+    assert.equal(reg.resolve(id, q), null);
+    assert.equal(reg.size, 0, "expired entry removed on access");
+    const ids = ["a", "b", "c", "d"].map((rel) => reg.mint({ ...q, rel }).id);
+    assert.equal(reg.size, 3);
+    assert.equal(reg.resolve(ids[0], q), null, "oldest evicted");
+    assert.ok(reg.resolve(ids[3], q));
+    assert.equal(reg.revoke(ids[3]), true);
+    assert.equal(reg.resolve(ids[3], q), null);
+    reg.mint({ ...q, rel: "e" });
+    assert.equal(reg.revokeWorkspace("w") >= 1, true);
+});
+
+test("ids: nothing is minted for a bad path, a sensitive file or an unknown kind", () => {
+    const reg = new ContentRefRegistry({ tenantId: "t1", denyGlobs: ["vault/"] });
+    const q = { workspaceId: "w", root: "/r" };
+    for (const rel of ["../x", "/etc/passwd", "a\u0000b", "", ".env", "src/.env.local", "id_rsa", ".git/config", "vault/x.txt", null]) {
+        assert.equal(reg.mint({ ...q, kind: "file", rel }), null, String(rel));
+    }
+    assert.equal(reg.mint({ ...q, kind: "chat.session", rel: "a" }), null);
+    assert.equal(reg.mint({ ...q, kind: "diff", rel: null }) !== null, true, "the whole work tree diff has no path");
+    assert.equal(reg.mint({ workspaceId: "", root: "/r", kind: "file", rel: "a" }), null);
+});

package/test/la-protocol-v2/content-wiring.test.js

@@ -0,0 +1,225 @@
+// F3-07: the flag and the wiring. LOCAL_AGENT_CONTENT_HANDLERS off (default, unknown values) = content.request is still
+// acked `rejected protocol_unsupported`; on = served. In process (buildV2Link) and end to end (the real src/server.js).
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { ReferenceCp, ReferenceCpServer, TENANT, AGENT, uuid, waitFor } from "./helpers/reference-cp.js";
+import { signingFor } from "./helpers/la-rig.js";
+import { runAgent } from "./helpers/spawn-agent.js";
+import { write, git, tmpDir, ACTOR } from "./helpers/content-rig.js";
+import { buildV2Link } from "../../src/la-protocol-v2/runtime.js";
+import { resolveContentHandlersConfig } from "../../src/la-protocol-v2/content-handlers/config.js";
+import { createAudit } from "../../src/la-protocol-v2/content-handlers/audit.js";
+
+const GH = "ghp_" + "A1b2C3d4E5f6G7h8I9j0K1l2M3n4O5p6Q7r8";
+
+// ------------------------------------------------------------------------------------------ config
+
+test("config: only true/1/yes/on enable it; unset, empty, false and unknown values keep it off (unknown warns)", () => {
+    for (const v of [undefined, "", "false", "0", "no", "off", "  OFF ", "maybe", "2", "enabled", "tru"]) {
+        const warns = [];
+        assert.deepEqual(resolveContentHandlersConfig({ LOCAL_AGENT_CONTENT_HANDLERS: v }, (m) => warns.push(m)), { enabled: false }, String(v));
+        assert.equal(warns.length, ["maybe", "2", "enabled", "tru"].includes(v) ? 1 : 0, String(v));
+    }
+    for (const v of ["true", "TRUE", "1", "yes", "on", " On "]) assert.equal(resolveContentHandlersConfig({ LOCAL_AGENT_CONTENT_HANDLERS: v }, () => {}).enabled, true, v);
+});
+
+test("config: every number is clamped to a sane range; a bad value falls back to the default, never to unlimited", () => {
+    const c = resolveContentHandlersConfig({ LOCAL_AGENT_CONTENT_HANDLERS: "true", LOCAL_AGENT_CONTENT_MAX_BYTES: "999999999", LOCAL_AGENT_CONTENT_MAX_CONCURRENT: "0",
+        LOCAL_AGENT_CONTENT_REF_TTL_MS: "-5", LOCAL_AGENT_CONTENT_TOTAL_MS: "abc", LOCAL_AGENT_CONTENT_MAX_REFS: "1" }, () => {});
+    assert.equal(c.maxBytes, 1024 * 1024);
+    assert.equal(c.maxConcurrent, 4);
+    assert.equal(c.refTtlMs, 15 * 60_000);
+    assert.equal(c.totalMs, 25_000);
+    assert.equal(c.maxRefs, 20_000);
+    const big = resolveContentHandlersConfig({ LOCAL_AGENT_CONTENT_HANDLERS: "true", LOCAL_AGENT_CONTENT_MAX_BYTES: String(2 * 1024 * 1024) }, () => {});
+    assert.equal(big.maxBytes, 2 * 1024 * 1024, "the contract's 2 MiB is the ceiling");
+    assert.deepEqual(resolveContentHandlersConfig({ LOCAL_AGENT_CONTENT_HANDLERS: "true", LOCAL_AGENT_CONTENT_DENY_GLOBS: " a/ , ,*.x" }, () => {}).extraDenyGlobs, ["a/", "*.x"]);
+});
+
+// ------------------------------------------------------------------------------------------ in process (runtime.js)
+
+async function linkFor(cp, { env, root, tenantWs } = {}) {
+    const logs = [];
+    const log = { info: (m) => logs.push(m), log: (m) => logs.push(m), warn: (m) => logs.push(m) };
+    const wsManager = { list: () => [{ id: "ws-1", root, tenantId: tenantWs ?? 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 };
+}
+
+test("flag off (unset or any non-true value): content.request is acked `rejected protocol_unsupported` and the register has no content capability", async () => {
+    for (const v of [undefined, "false", "maybe"]) {
+        const root = tmpDir(); write(root, "a.txt", "x");
+        const cp = new ReferenceCp();
+        const { link } = await linkFor(cp, { root, env: { LOCAL_AGENT_CONTENT_HANDLERS: v } });
+        assert.equal(link.content, undefined);
+        assert.deepEqual(cp.registers[0].capabilities, ["chunk.base64", "protocol.v2", "v1.commands"]);
+        cp.sendData("content.request", { kind: "file", ref: "cr1_" + "A".repeat(22), actor: ACTOR }, { workspaceId: "ws-1", requestId: uuid() });
+        await waitFor(() => cp.acksFromLa.length > 0);
+        assert.deepEqual(cp.acksFromLa[0], { ackSeq: 1, status: "rejected", errorCode: "protocol_unsupported" });
+        assert.equal(cp.received.filter((f) => f.type === "content.response").length, 0);
+        link.close();
+        fs.rmSync(root, { recursive: true, force: true });
+    }
+});
+
+test("flag on: the handler is installed, the register announces content.file and content.diff, mintRef gives the hook for future inventories", async () => {
+    const root = tmpDir(); write(root, "src/a.txt", "hello"); write(root, ".env", "X=1");
+    const cp = new ReferenceCp();
+    const { link, logs } = await linkFor(cp, { root, env: { LOCAL_AGENT_CONTENT_HANDLERS: "true", LOCAL_AGENT_DLP_MODE: "enforce" } });
+    assert.deepEqual(cp.registers[0].capabilities, ["chunk.base64", "content.diff", "content.file", "protocol.v2", "v1.commands"]);
+    assert.equal(logs.some((l) => l.includes("not enforce")), false, "enforce: no warning");
+    const m = link.content.mintRef({ workspaceId: "ws-1", kind: "file", rel: "src/a.txt" });
+    assert.match(m.id, /^cr1_[A-Za-z0-9_-]{22}$/);
+    assert.equal(link.content.mintRef({ workspaceId: "ws-1", kind: "file", rel: ".env" }), null);
+    assert.equal(link.content.mintRef({ workspaceId: "ws-unknown", kind: "file", rel: "src/a.txt" }), null);
+    const requestId = uuid();
+    cp.sendData("content.request", { kind: "file", ref: m.id, actor: ACTOR }, { workspaceId: "ws-1", requestId });
+    await waitFor(() => cp.contentRequests.get(requestId)?.done);
+    assert.equal(Buffer.concat(cp.contentRequests.get(requestId).chunks).toString(), "hello");
+    link.close();
+    assert.equal(link.content.registry.size, 0, "closing the link forgets every id");
+    fs.rmSync(root, { recursive: true, force: true });
+});
+
+test("flag on with the DLP not in enforce: the agent says so at install time (the operator chose, but it is visible)", async () => {
+    const root = tmpDir();
+    const cp = new ReferenceCp();
+    const { link, logs } = await linkFor(cp, { root, env: { LOCAL_AGENT_CONTENT_HANDLERS: "true" } });
+    assert.ok(logs.some((l) => l.includes("LOCAL_AGENT_DLP_MODE is not enforce")));
+    link.close();
+    fs.rmSync(root, { recursive: true, force: true });
+});
+
+test("flag on: a workspace of another tenant (per the agent's own registry) is not served", async () => {
+    const root = tmpDir(); write(root, "a.txt", "x");
+    const cp = new ReferenceCp();
+    const { link } = await linkFor(cp, { root, tenantWs: "9d1f6a2c-0000-4000-8000-000000000000", env: { LOCAL_AGENT_CONTENT_HANDLERS: "true", LOCAL_AGENT_DLP_MODE: "enforce" } });
+    assert.equal(link.content.mintRef({ workspaceId: "ws-1", kind: "file", rel: "a.txt" }), null);
+    const requestId = uuid();
+    cp.sendData("content.request", { kind: "diff", ref: "worktree", actor: ACTOR }, { workspaceId: "ws-1", requestId });
+    await waitFor(() => cp.contentRequests.get(requestId)?.done);
+    assert.equal(cp.received.find((f) => f.requestId === requestId).payload.status, "not_found");
+    link.close();
+    fs.rmSync(root, { recursive: true, force: true });
+});
+
+test("closing the link while a stream is in flight cancels it (no work left behind)", async () => {
+    const root = tmpDir(); write(root, "big.txt", Buffer.alloc(900_000, 0x61));
+    const cp = new ReferenceCp();
+    const { link } = await linkFor(cp, { root, env: { LOCAL_AGENT_CONTENT_HANDLERS: "true", LOCAL_AGENT_DLP_MODE: "off" } });
+    const id = link.content.mintRef({ workspaceId: "ws-1", kind: "file", rel: "big.txt" }).id;
+    cp.silent = true;
+    cp.sendData("content.request", { kind: "file", ref: id, actor: ACTOR }, { workspaceId: "ws-1", requestId: uuid() });
+    await waitFor(() => link.content.handler.inflight === 1 && cp.received.filter((f) => f.type === "content.response").length === 8);
+    const handler = link.content.handler;
+    link.close();
+    await waitFor(() => handler.inflight === 0 && handler.reservedBytes === 0);
+    fs.rmSync(root, { recursive: true, force: true });
+});
+
+// ------------------------------------------------------------------------------------------ audit file
+
+test("audit: optional JSONL file, mode 0600, rotates at the size cap; a broken path never breaks the data path", () => {
+    const dir = tmpDir(); const file = path.join(dir, "audit.jsonl");
+    const a = createAudit({ file, maxFileBytes: 400 });
+    for (let i = 0; i < 6; i++) a.record({ kind: "file", status: "ok", bytes: i });
+    assert.ok(fs.existsSync(file) && fs.existsSync(`${file}.1`), "rotated");
+    assert.equal(fs.statSync(file).mode & 0o777, 0o600);
+    for (const l of fs.readFileSync(file, "utf8").trim().split("\n")) assert.equal(JSON.parse(l).kind, "file");
+    assert.equal(a.tail(100).length, 6);
+    const broken = createAudit({ file: path.join(dir, "no/such/dir/audit.jsonl") });
+    assert.doesNotThrow(() => broken.record({ kind: "file" }));
+    assert.equal(broken.brokenFile, true);
+    assert.equal(broken.tail(1).length, 1, "the ring still has it");
+    fs.rmSync(dir, { recursive: true, force: true });
+});
+
+// ------------------------------------------------------------------------------------------ end to end: the real src/server.js
+
+const baseEnv = (srv) => ({
+    TENANT_ID: TENANT,
+    LOCAL_AGENT_SIGNATURE_MODE: "enforce",
+    LOCAL_AGENT_SIGNING_PUBLIC_KEYS: `${srv.keyId}=${srv.publicKeyRaw}`,
+});
+
+function prepareRepo(ws) {
+    write(ws, "src/app.js", "const a = 1;\n");
+    write(ws, ".env", "API=old\n");
+    git(ws, "init", "-q", "-b", "main"); git(ws, "add", "-f", "-A"); git(ws, "commit", "-q", "-m", "init");
+    write(ws, "src/app.js", `const a = 2;\nconst token = "${GH}";\n`);
+    write(ws, ".env", "API=NEW-SECRET-VALUE-0123456789\n");
+}
+
+async function e2e(env, requests) {
+    const srv = await new ReferenceCpServer({ requireEnforce: true }).start();
+    const out = { ids: [] };
+    try {
+        await runAgent({
+            srv, cfg: { authorizationId: AGENT, tenantId: TENANT }, prepare: prepareRepo,
+            env: { ...baseEnv(srv), LOCAL_AGENT_PROTOCOL_V2: "true", ...env },
+            until: async () => {
+                if (srv.cp.state === "ready" && !srv.sent) {
+                    srv.sent = true;
+                    out.workspaceId = srv.cp.registers[0].workspaces[0].workspaceId;
+                    for (const r of requests) {
+                        const requestId = uuid(); out.ids.push(requestId);
+                        srv.cp.sendData("content.request", { ...r, actor: ACTOR }, { workspaceId: out.workspaceId, requestId });
+                    }
+                }
+                return srv.sent && out.ids.every((id) => srv.cp.contentRequests.get(id)?.done) || (srv.sent && srv.cp.acksFromLa.filter((a) => a.status === "rejected").length >= requests.length);
+            },
+        });
+        out.cp = srv.cp;
+        out.registers = srv.cp.registers;
+        out.errors = srv.cp.errorsSent;
+    } finally { await srv.stop(); }
+    return out;
+}
+
+test("e2e (real server.js): flags on + DLP enforce: the diff of the work tree comes back masked, without the .env, and file ids that were never minted are not_found", async () => {
+    const o = await e2e({ LOCAL_AGENT_CONTENT_HANDLERS: "true", LOCAL_AGENT_DLP_MODE: "enforce" },
+        [{ kind: "diff", ref: "worktree" }, { kind: "file", ref: "src/app.js" }, { kind: "file", ref: "../../etc/passwd" }, { kind: "report", ref: "x" }]);
+    assert.deepEqual(o.errors, []);
+    assert.ok(o.registers[0].capabilities.includes("content.diff"));
+    const answer = (i) => {
+        const id = o.ids[i]; const fr = o.cp.received.filter((f) => f.requestId === id);
+        return { status: fr[0].payload.status, errorCode: fr[0].payload.errorCode, text: Buffer.concat(o.cp.contentRequests.get(id).chunks).toString() };
+    };
+    const d = answer(0);
+    assert.equal(d.status, "ok");
+    assert.match(d.text, /src\/app\.js/);
+    assert.match(d.text, /REDACTED:github_token/);
+    assert.equal(d.text.includes(GH), false);
+    assert.equal(d.text.includes("NEW-SECRET-VALUE") || d.text.includes(".env"), false);
+    assert.equal(answer(1).status, "not_found", "a path is not an id");
+    assert.equal(answer(2).status, "not_found");
+    assert.deepEqual([answer(3).status, answer(3).errorCode], ["error", "protocol_unsupported"]);
+    const wire = JSON.stringify(o.cp.rawIn);
+    assert.equal(wire.includes("v2e2e-ws"), false, "no workspace path on the wire");
+    assert.equal(wire.includes(GH), false);
+});
+
+test("e2e (real server.js): flag off: content.request is acked rejected protocol_unsupported, exactly as before F3-07", async () => {
+    for (const v of [undefined, "false"]) {
+        const o = await e2e({ LOCAL_AGENT_CONTENT_HANDLERS: v, LOCAL_AGENT_DLP_MODE: "enforce" }, [{ kind: "diff", ref: "worktree" }]);
+        assert.deepEqual(o.registers[0].capabilities, ["chunk.base64", "protocol.v2", "v1.commands"]);
+        assert.deepEqual(o.cp.acksFromLa.map((a) => [a.status, a.errorCode]), [["rejected", "protocol_unsupported"]]);
+        assert.equal(o.cp.received.filter((f) => f.type === "content.response").length, 0);
+    }
+});
+
+test("e2e (real server.js): content flag on but protocol v2 off: nothing is served (v1 client), the agent only warns", async () => {
+    const srv = await new ReferenceCpServer({}).start();
+    try {
+        await runAgent({ srv, cfg: { authorizationId: AGENT, tenantId: TENANT }, env: { ...baseEnv(srv), LOCAL_AGENT_CONTENT_HANDLERS: "true" },
+            until: async () => srv.legacy.some((f) => f.type === "register") });
+        assert.equal(srv.cp.rawIn.length, 0, "no v2 frame");
+    } finally { await srv.stop(); }
+});

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

@@ -0,0 +1,131 @@
+// F3-05b: the contract as the Local Agent applies it. Every vector of the gateway's F3-22 suite (valid AND
+// invalid) must be classified the way the vector declares, the copy must be the gateway's, and the
+// tables the LA keeps by hand (error codes, fatal set) must match the schema.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadContract } from "../../src/la-protocol-v2/contract.js";
+import { ERROR_CODES, closeCodeOf, isFatal, isRetryable } from "../../src/la-protocol-v2/errors.js";
+import { parseStrict } from "../../src/la-protocol-v2/strict-json.js";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+const RUNTIME = path.join(ROOT, "src/la-protocol-v2/contract");
+const VECTORS = path.join(ROOT, "test/contract/la-protocol-v2/vectors");
+const contract = loadContract();
+const sha = (b) => crypto.createHash("sha256").update(b).digest("hex");
+
+test("the copy is the gateway's: CONTRACT_SOURCE.json hashes every file and names the commit", () => {
+    const src = JSON.parse(fs.readFileSync(path.join(RUNTIME, "CONTRACT_SOURCE.json"), "utf8"));
+    assert.match(src.commit, /^[0-9a-f]{40}$/);
+    assert.equal(src.repo, "VISIONHAMMER/vh-api-gateway");
+    let n = 0;
+    for (const [rel, hash] of Object.entries(src.files)) {
+        const file = rel.startsWith("vectors/") ? path.join(ROOT, "test/contract/la-protocol-v2", rel) : path.join(RUNTIME, rel);
+        assert.equal(sha(fs.readFileSync(file)), hash, `${rel} was edited after the sync`);
+        n++;
+    }
+    assert.ok(n >= 60, `expected the schemas and all vectors, got ${n}`);
+    // nothing extra sneaked in next to the copy
+    const onDisk = fs.readdirSync(RUNTIME).filter((f) => f !== "CONTRACT_SOURCE.json");
+    for (const f of onDisk) assert.ok(src.files[f], `${f} is not part of the synced contract`);
+});
+
+test("VH_GATEWAY_CONTRACT_DIR (optional): the copy equals a gateway checkout byte for byte", { skip: !process.env.VH_GATEWAY_CONTRACT_DIR }, () => {
+    const dir = process.env.VH_GATEWAY_CONTRACT_DIR;
+    for (const f of fs.readdirSync(dir).filter((n) => n.endsWith(".schema.json") || n === "index.json")) {
+        assert.equal(sha(fs.readFileSync(path.join(dir, f))), sha(fs.readFileSync(path.join(RUNTIME, f))), f);
+    }
+});
+
+// ------------------------------------------------------------------------------------------------ vectors
+
+const vectorFiles = fs.readdirSync(VECTORS).filter((f) => f.endsWith(".vectors.json"));
+
+test("vectors: the suite is complete (every type has a file, plus cross-type)", () => {
+    const types = Object.keys(contract.index.types);
+    for (const t of types) assert.ok(vectorFiles.includes(`${t}.vectors.json`), `no vectors for ${t}`);
+    assert.ok(vectorFiles.includes("cross-type.vectors.json"));
+});
+
+let valid = 0;
+let invalid = 0;
+for (const file of vectorFiles) {
+    const doc = JSON.parse(fs.readFileSync(path.join(VECTORS, file), "utf8"));
+    for (const v of doc.vectors) {
+        test(`vector ${file.replace(".vectors.json", "")} :: ${v.name}`, () => {
+            const r = contract.validateFrame(v.message);
+            if (v.expect.valid) {
+                valid++;
+                assert.equal(r.ok, true, `expected valid, got ${r.code} ${r.keywords}`);
+                return;
+            }
+            invalid++;
+            assert.equal(r.ok, false, "expected the frame to be refused");
+            // payload_too_large is the session-level refinement of schema_violation for maxLength under /payload (gateway rule)
+            const refined = v.expect.code === "schema_violation" && r.code === "payload_too_large" && r.keywords.includes("maxLength");
+            assert.ok(r.code === v.expect.code || refined, `code ${r.code} != ${v.expect.code}`);
+            if (v.expect.keyword) assert.ok(r.keywords.includes(v.expect.keyword), `keyword ${v.expect.keyword} not in ${r.keywords}`);
+            if (v.expect.rule) assert.ok(r.rules.includes(v.expect.rule), `rule ${v.expect.rule} not in ${r.rules}`);
+        });
+    }
+}
+
+test("vectors: counts (134 = 24 valid + 110 invalid in this copy)", () => {
+    assert.equal(valid + invalid, 134);
+    assert.equal(valid, 24);
+    assert.equal(invalid, 110);
+});
+
+// ------------------------------------------------------------------------------------------------ tables
+
+test("error codes: the LA table is the schema enum, in the same order; close code = 4400 + position (timeout = 4420)", () => {
+    assert.deepEqual([...ERROR_CODES], contract.errorCodes);
+    assert.equal(closeCodeOf("timeout"), 4420);
+    assert.equal(closeCodeOf("bad_frame"), 4400);
+    for (const c of ERROR_CODES) {
+        const cc = closeCodeOf(c);
+        assert.ok(cc >= 4400 && cc <= 4499, c);
+    }
+});
+
+test("error codes: fatal and retryable sets mirror the gateway (LaV2ErrorCode)", () => {
+    const nonFatal = ERROR_CODES.filter((c) => !isFatal(c)).sort();
+    assert.deepEqual(nonFatal, ["agent_offline", "internal", "protocol_unsupported", "rate_limited", "timeout"]);
+    assert.deepEqual(ERROR_CODES.filter(isRetryable).sort(), ["agent_offline", "internal", "rate_limited", "seq_gap", "timeout"]);
+});
+
+test("allowlist: the LA receives only cp->la/both types and sends only la->cp/both types; v1 commands are not types", () => {
+    assert.deepEqual([...contract.inboundTypes].sort(), ["ack", "approval.decision", "config.update", "content.request", "error", "job.assign", "job.cancel", "ready", "scan.upload", "webhook.forward"]);
+    assert.deepEqual([...contract.outboundTypes].sort(), ["ack", "alert", "audit.event", "content.response", "error", "heartbeat", "hello", "incident.candidate", "job.event", "job.result", "log.stats", "register", "scan.uploaded"]);
+    for (const v1 of ["mcp.execute-command", "workspace.open", "health", "shell.exec", "__proto__", "constructor", "toString"]) {
+        assert.equal(contract.canReceive(v1), false, v1);
+        assert.equal(contract.canSend(v1), false, v1);
+    }
+});
+
+test("limits come from index.json and are the documented ones", () => {
+    assert.deepEqual({ ...contract.limits }, {
+        maxFrameBytes: 49152, chunkRawBytes: 32768, maxChunks: 64, maxContentBytes: 2097152, maxRetries: 3, ackTimeoutMs: 5000,
+        handshakeTimeoutMs: 10000, heartbeatSeconds: 30, sessionDeadSeconds: 90, dedupeWindowSeconds: 600, clockSkewSeconds: 60,
+    });
+});
+
+// ------------------------------------------------------------------------------------------------ strict JSON
+
+test("parseStrict: valid JSON is returned as JSON.parse would", () => {
+    assert.deepEqual(parseStrict('{"a":1,"b":{"c":[1,2,{"d":"x,\\"y\\":z"}]},"e":"{\\"a\\":1,\\"a\\":2}"}'), { a: 1, b: { c: [1, 2, { d: 'x,"y":z' }] }, e: '{"a":1,"a":2}' });
+});
+test("parseStrict: a duplicate key at any depth is refused", () => {
+    assert.throws(() => parseStrict('{"a":1,"a":2}'));
+    assert.throws(() => parseStrict('{"x":{"a":1,"b":2,"a":3}}'));
+    assert.throws(() => parseStrict('[{"k":1},{"k":2,"k":3}]'));
+    assert.doesNotThrow(() => parseStrict('[{"k":1},{"k":2}]'));
+    assert.doesNotThrow(() => parseStrict('{"a":{"k":1},"b":{"k":2}}'));
+});
+test("parseStrict: invalid JSON throws", () => {
+    assert.throws(() => parseStrict("{"));
+    assert.throws(() => parseStrict("not json"));
+});