deepdebug-local-agent 1.3.0 → 1.5.0

package/src/la-protocol-v2/content-handlers/handler.js

@@ -0,0 +1,170 @@
+/**
+ * handler.js - `content.request` handlers of the Local Agent (F3-07). Registered by runtime.js only when
+ * LOCAL_AGENT_PROTOCOL_V2=true AND LOCAL_AGENT_CONTENT_HANDLERS=true.
+ *
+ * Order of every request (nothing is read before the checks, nothing leaves before the DLP):
+ *   1. accept: the handler answers the session at once ({accept:true} = ack `accepted`); the work goes on in the
+ *      background (the first chunk may take seconds, the ack timeout is 5 s). A request without requestId is refused.
+ *   2. admission: at most `maxConcurrent` requests and `maxInFlightBytes` in memory; above it -> `rate_limited`.
+ *   3. kind: `file` and `diff` are served; every other kind of the allowlist -> status `error` + `protocol_unsupported`
+ *      (the contract has no "not supported" status; this is the code already used for "no handler").
+ *   4. workspace: the envelope's workspace must be registered here (and belong to this tenant) -> else `not_found`.
+ *   5. ref: an opaque id (ref-registry.js) valid for this tenant+workspace+root+kind -> else `not_found`, whatever the
+ *      reason (unknown, expired, other workspace, or "../etc/passwd": no oracle, nothing echoed). The ref is never
+ *      interpreted as a path.
+ *   6. path (file): realpath inside the root, not sensitive, regular file, <= maxBytes (path-guard.js) -> `forbidden` /
+ *      `not_found` / `payload_too_large`.
+ *   7. DLP + range + size (egress.js), then 8. sendContent: <= 32 KiB per chunk, <= 64 chunks, window + backpressure of the
+ *      session, aborted by cancel()/deadline/connection loss.
+ * Answers carry a status and a wire code only. Logs, errors and the audit never contain a path, a ref or content.
+ */
+import { ProtocolError } from "../errors.js";
+import { sendContent, sendContentFailure } from "../content.js";
+import { REF_KINDS } from "./ref-registry.js";
+import { normalizeRel, resolveInside, readRegular } from "./path-guard.js";
+import { worktreeDiff } from "./git-diff.js";
+import { prepareOutgoing, contentTypeOf, decodeText } from "./egress.js";
+import { createAudit, short } from "./audit.js";
+
+export const SERVED_KINDS = Object.freeze(["file", "diff"]);
+/** Symbolic ref of kind `diff`: the whole work tree of the envelope's workspace (carries no client data). */
+export const WORKTREE_REF = "worktree";
+
+export function createContentHandler({ session, tenantId, resolveWorkspace, registry, config, env = process.env, log = console, audit = null, now = Date.now }) {
+    const inflight = new Map(); // requestId -> { ac, timer }
+    let reservedBytes = 0;
+    const auditor = audit || createAudit({ file: config.auditFile, now });
+    const reserveEach = 2 * config.maxBytes;
+    const warn = (m) => (log.warn || log.log).call(log, m);
+
+    const stats = { received: 0, ok: 0, notFound: 0, forbidden: 0, error: 0, cancelled: 0, byCode: {} };
+    const bump = (k) => { stats.byCode[k] = (stats.byCode[k] || 0) + 1; };
+
+    /** @returns {Promise<{status:string, errorCode?:string, buffer?:Buffer, contentType?:string, dlp?:object}>} */
+    async function produce(ctx, p, signal) {
+        if (!SERVED_KINDS.includes(p.kind)) return { status: "error", errorCode: "protocol_unsupported" };
+        const ws = await resolveWorkspace(ctx.workspaceId);
+        if (!ws || !ws.root) return { status: "not_found" };
+        const target = registry.resolve(p.ref, { workspaceId: ctx.workspaceId, root: ws.root, kind: p.kind });
+        if (p.kind === "diff" && !target && p.ref === WORKTREE_REF) return produceDiff(p, ws, null, signal);
+        if (!target) return { status: "not_found" };
+        if (p.kind === "diff") return produceDiff(p, ws, target.rel, signal);
+        return produceFile(p, ws, target.rel, signal);
+    }
+
+    async function produceFile(p, ws, rel, signal) {
+        const norm = rel && normalizeRel(rel);
+        if (!norm) return { status: "not_found" };
+        const resolved = await resolveInside(ws.root, norm, config.extraDenyGlobs);
+        if (!resolved.ok) return { status: resolved.status };
+        if (signal.aborted) return { status: "error", errorCode: "agent_offline" };
+        const read = await readRegular(resolved, config.maxBytes, signal);
+        if (!read.ok) return read.status === "too_large" ? { status: "error", errorCode: "payload_too_large" } : { status: read.status };
+        const isText = decodeText(read.buffer) !== null;
+        return finish(p, read.buffer, contentTypeOf(norm, isText), "content.file");
+    }
+
+    async function produceDiff(p, ws, rel, signal) {
+        const d = await worktreeDiff({ root: ws.root, rel, maxBytes: config.maxBytes, maxFiles: config.maxDiffFiles,
+            timeoutMs: config.gitTimeoutMs, denyGlobs: config.extraDenyGlobs, signal });
+        if (!d.ok) return d;
+        return finish(p, Buffer.from(d.text, "utf8"), "text/x-diff", "content.diff");
+    }
+
+    function finish(p, buffer, contentType, source) {
+        const out = prepareOutgoing({ buffer, contentType, range: p.range, maxBytes: config.maxBytes, env, source });
+        return out.ok ? { status: "ok", buffer: out.buffer, contentType: out.contentType, dlp: out.dlp }
+            : { status: out.status, errorCode: out.errorCode, dlp: out.dlp };
+    }
+
+    async function run(ctx, p, entry) {
+        const t0 = now();
+        let result;
+        let sent = null;
+        let errorCode;
+        try {
+            if (inflight.size > config.maxConcurrent || reservedBytes + reserveEach > config.maxInFlightBytes) {
+                result = { status: "error", errorCode: "rate_limited" };
+            } else {
+                reservedBytes += reserveEach;
+                entry.reserved = true;
+                result = await produce(ctx, p, entry.ac.signal);
+            }
+            if (entry.ac.signal.aborted) {
+                errorCode = "cancelled";
+                // out of time before the first chunk: the gateway still waits for an answer, give it one (a code only)
+                if (entry.reason === "deadline") {
+                    await sendContentFailure(session, { requestId: ctx.requestId, status: "error", errorCode: "timeout", workspaceId: ctx.workspaceId }).catch(() => {});
+                    errorCode = "timeout";
+                }
+            } else if (result.status === "ok") {
+                try {
+                    sent = await sendContent(session, { requestId: ctx.requestId, source: result.buffer, contentType: result.contentType,
+                        workspaceId: ctx.workspaceId, signal: entry.ac.signal });
+                } catch (e) {
+                    errorCode = e instanceof ProtocolError ? (entry.ac.signal.aborted ? "cancelled" : e.code) : "internal";
+                }
+            } else {
+                await sendContentFailure(session, { requestId: ctx.requestId, status: result.status,
+                    errorCode: result.errorCode || null, workspaceId: ctx.workspaceId });
+            }
+        } catch (e) {
+            errorCode = e instanceof ProtocolError ? e.code : "internal";
+        } finally {
+            clearTimeout(entry.timer);
+            if (entry.reserved) reservedBytes -= reserveEach;
+            inflight.delete(ctx.requestId);
+        }
+        const status = errorCode === "cancelled" || errorCode === "timeout" ? errorCode : errorCode ? "send_failed" : result.status;
+        if (status === "ok") stats.ok++;
+        else if (status === "not_found") stats.notFound++;
+        else if (status === "forbidden") stats.forbidden++;
+        else if (status === "cancelled" || status === "timeout") stats.cancelled++;
+        else stats.error++;
+        bump(errorCode || result.errorCode || status);
+        auditor.record({
+            requestId: ctx.requestId, workspaceId: ctx.workspaceId, kind: p.kind, status, errorCode: errorCode || result.errorCode || null,
+            bytes: sent ? sent.bytes : 0, chunks: sent ? sent.chunks : 0, ms: now() - t0,
+            dlpMode: result.dlp ? result.dlp.mode : null, dlpHits: result.dlp ? result.dlp.total : 0, dlpRules: result.dlp ? result.dlp.redactions : {},
+            refSha: short(p.ref), actorRole: p.actor && p.actor.role, actorSha: short(p.actor && p.actor.userId),
+        });
+        if (status === "send_failed") warn(`[la-content] ${p.kind} not delivered: ${errorCode}`);
+    }
+
+    return {
+        stats,
+        audit: auditor,
+        get inflight() { return inflight.size; },
+        get reservedBytes() { return reservedBytes; },
+
+        /** The session handler for `content.request` (session.setHandler). */
+        handle(ctx) {
+            stats.received++;
+            const p = ctx.params;
+            if (!ctx.requestId) return { reject: "schema_violation" };
+            if (inflight.has(ctx.requestId)) return { accept: true }; // already working on it (a retransmission with another seq)
+            const entry = { ac: new AbortController(), timer: null, reserved: false, reason: null };
+            entry.timer = setTimeout(() => { entry.reason = "deadline"; entry.ac.abort(); }, config.totalMs);
+            inflight.set(ctx.requestId, entry);
+            // background: ack first, answer later
+            queueMicrotask(() => { run(ctx, p, entry).catch(() => {}); });
+            return { accept: true };
+        },
+
+        /** Stops one request (no further chunk is read or written). There is no content.cancel frame in the contract. */
+        cancel(requestId) {
+            const e = inflight.get(requestId);
+            if (!e) return false;
+            e.reason = e.reason || "cancel";
+            e.ac.abort();
+            session.cancelWaiting(requestId);
+            return true;
+        },
+
+        cancelAll() {
+            for (const id of [...inflight.keys()]) this.cancel(id);
+        },
+    };
+}
+
+export { REF_KINDS };

package/src/la-protocol-v2/content-handlers/index.js

@@ -0,0 +1,6 @@
+export { CONTENT_HANDLERS_FLAG, resolveContentHandlersConfig } from "./config.js";
+export { ContentRefRegistry, REF_PATTERN } from "./ref-registry.js";
+export { createContentHandler, SERVED_KINDS, WORKTREE_REF } from "./handler.js";
+export { installContentHandlers, CONTENT_CAPABILITIES } from "./install.js";
+export { isSensitivePath, normalizeRel, resolveInside, DEFAULT_DENY_GLOBS } from "./path-guard.js";
+export { createAudit } from "./audit.js";

package/src/la-protocol-v2/content-handlers/install.js

@@ -0,0 +1,50 @@
+/**
+ * install.js - puts the content handlers on a v2 link (F3-07). Called by runtime.js only when
+ * LOCAL_AGENT_CONTENT_HANDLERS=true (and v2 is on). Returns what the rest of the agent needs:
+ *
+ *   mintRef({workspaceId, kind, rel})  the HOOK for whoever reports metadata to the control plane (file lists,
+ *                                      diff summaries): returns an opaque id for that item, or null (sensitive
+ *                                      path, unknown workspace). Nothing calls it yet: the contract has no
+ *                                      LA->CP frame that carries an inventory (see the F3-07 note, open questions).
+ */
+import { dlpConfigFromEnv } from "../../dlp/index.js";
+import { ContentRefRegistry } from "./ref-registry.js";
+import { createContentHandler, SERVED_KINDS } from "./handler.js";
+
+export const CONTENT_CAPABILITIES = Object.freeze(SERVED_KINDS.map((k) => `content.${k}`));
+
+export function installContentHandlers({ link, tenantId, wsManager, getWorkspaceRoot, config, env = process.env, log = console }) {
+    const tenant = String(tenantId).toLowerCase();
+    const registry = new ContentRefRegistry({ tenantId: tenant, ttlMs: config.refTtlMs, maxEntries: config.maxRefs, denyGlobs: config.extraDenyGlobs });
+
+    /** A workspace "registered here": open in the manager (of this tenant, or of none yet) or the default root. */
+    const resolveWorkspace = (workspaceId) => {
+        if (typeof workspaceId !== "string" || !workspaceId) return null;
+        const listed = (wsManager?.list?.() || []).find((w) => w && w.id === workspaceId);
+        if (listed) {
+            if (listed.tenantId && String(listed.tenantId).toLowerCase() !== tenant) return null;
+            return listed.root ? { root: listed.root } : null;
+        }
+        if (workspaceId === "default") { const root = getWorkspaceRoot(); return root ? { root } : null; }
+        return null;
+    };
+
+    const handler = createContentHandler({ session: link.session, tenantId: tenant, resolveWorkspace, registry, config, env, log });
+    link.session.setHandler("content.request", (ctx) => handler.handle(ctx));
+
+    const closeLink = link.close.bind(link);
+    link.close = () => { handler.cancelAll(); registry.clear(); closeLink(); };
+
+    if (dlpConfigFromEnv(env).mode !== "enforce") {
+        (log.warn || log.log).call(log, "[la-content] content handlers are on but LOCAL_AGENT_DLP_MODE is not enforce: file content leaves this machine unmasked");
+    }
+    link.content = {
+        registry,
+        handler,
+        mintRef: ({ workspaceId, kind, rel }) => {
+            const ws = resolveWorkspace(workspaceId);
+            return ws ? registry.mint({ workspaceId, root: ws.root, kind, rel }) : null;
+        },
+    };
+    return link.content;
+}

package/src/la-protocol-v2/content-handlers/path-guard.js

@@ -0,0 +1,142 @@
+/**
+ * path-guard.js - the Local Agent is the authority on what a content.request may read (F3-07).
+ * The gateway lets anything through (it only sees an opaque id); every check that matters is here.
+ *
+ *   normalizeRel     a relative path as the agent itself minted it: no NUL/control chars, not absolute, no `..`.
+ *   isSensitivePath  deny list (built-in + LOCAL_AGENT_CONTENT_DENY_GLOBS): .env*, private keys, .git/, .ssh/, ...
+ *   resolveInside    realpath of root and target; the real target must stay inside the real root (a symlink that
+ *                    leaves the workspace is `forbidden`), must not be sensitive under its REAL name either
+ *                    (a harmless-looking link to .env), and must be a regular file.
+ *   readRegular      opens with O_NOFOLLOW, checks it is the same inode that was checked, reads at most `maxBytes`.
+ *
+ * Failures are small codes ("not_found" | "forbidden" | "too_large"); no message ever carries a path.
+ * Limits that remain (documented in the note): a directory swapped for a symlink between the check and the open
+ * (TOCTOU on parents), hard links to files outside the root (not detectable cheaply).
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+const O_NOFOLLOW = fs.constants.O_NOFOLLOW ?? 0;
+
+/** Built-in deny list. A pattern with no `/` matches any path segment; with `/` it matches a path (or its prefix). */
+export const DEFAULT_DENY_GLOBS = Object.freeze([
+    // secrets by name
+    ".env", ".env.*", "*.env",
+    "*.pem", "*.key", "*.p12", "*.pfx", "*.jks", "*.keystore", "*.p8", "*.ppk", "*.kdbx", "*.gpg", "*.crt.key",
+    "id_rsa*", "id_dsa*", "id_ecdsa*", "id_ed25519*",
+    ".npmrc", ".pypirc", ".netrc", "_netrc", ".pgpass", ".my.cnf", ".git-credentials", ".htpasswd", ".vault-token",
+    "credentials", "credentials.json", "service-account*.json", "serviceaccount*.json", "secrets.json", "secrets.yml", "secrets.yaml",
+    "*.secret", "*.secrets", "*.tfstate", "*.tfstate.*", "*.tfvars", "*.tfvars.json", "terraform.rc",
+    // directories that hold credentials or the repository internals (.git/config may carry a token in a URL)
+    ".git/", ".ssh/", ".aws/", ".gnupg/", ".kube/", ".docker/", ".azure/", ".terraform/", ".config/gcloud/",
+]);
+
+const RE_CACHE = new Map();
+
+function globToRegExp(glob) {
+    const g = glob.toLowerCase();
+    const dir = g.endsWith("/");
+    const body = dir ? g.slice(0, -1) : g;
+    let re = "";
+    for (let i = 0; i < body.length; i++) {
+        const c = body[i];
+        if (c === "*") {
+            if (body[i + 1] === "*") { re += ".*"; i++; } else re += "[^/]*";
+        } else if (c === "?") re += "[^/]";
+        else re += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    }
+    // anchored at a segment boundary on the left; on the right it must end the path or be followed by `/` (a directory prefix)
+    return new RegExp(`(?:^|/)${re}(?:/|$)`);
+}
+
+function regexFor(glob) {
+    let r = RE_CACHE.get(glob);
+    if (!r) { r = globToRegExp(glob); RE_CACHE.set(glob, r); if (RE_CACHE.size > 1000) RE_CACHE.delete(RE_CACHE.keys().next().value); }
+    return r;
+}
+
+/** Lower-case, posix, and without the trailing dots/spaces that Windows ignores (".env." is ".env"). */
+function foldForMatch(rel) {
+    return rel.split("/").map((seg) => seg.replace(/[. ]+$/, "") || seg).join("/").toLowerCase();
+}
+
+export function isSensitivePath(rel, extraGlobs = []) {
+    if (typeof rel !== "string") return true;
+    const folded = foldForMatch(rel.replace(/\\/g, "/"));
+    for (const g of DEFAULT_DENY_GLOBS) if (regexFor(g).test(folded)) return true;
+    for (const g of extraGlobs) if (typeof g === "string" && g && regexFor(g).test(folded)) return true;
+    return false;
+}
+
+const CONTROL = /[\u0000-\u001f\u007f]/;
+
+/** @returns {string | null} posix relative path, or null when it is not an acceptable relative path */
+export function normalizeRel(rel) {
+    if (typeof rel !== "string" || rel.length === 0 || rel.length > 1024) return null;
+    if (CONTROL.test(rel)) return null;
+    const p = rel.replace(/\\/g, "/");
+    if (p.startsWith("/") || /^[A-Za-z]:/.test(p)) return null;
+    const parts = [];
+    for (const seg of p.split("/")) {
+        if (seg === "" || seg === ".") continue;
+        if (seg === "..") return null;
+        parts.push(seg);
+    }
+    return parts.length ? parts.join("/") : null;
+}
+
+const toPosix = (p) => p.split(path.sep).join("/");
+const inside = (root, abs) => abs === root || abs.startsWith(root.endsWith(path.sep) ? root : root + path.sep);
+
+/**
+ * @param {string} root      the workspace root as registered
+ * @param {string} rel       relative path already normalized (normalizeRel)
+ * @returns {Promise<{ok:true, real:string, relReal:string, stat:fs.Stats} | {ok:false, status:"not_found"|"forbidden"}>}
+ */
+export async function resolveInside(root, rel, extraGlobs = []) {
+    let rootReal;
+    try { rootReal = await fs.promises.realpath(root); } catch { return { ok: false, status: "not_found" }; }
+    const abs = path.join(rootReal, ...rel.split("/"));
+    if (!inside(rootReal, abs)) return { ok: false, status: "forbidden" };
+    if (isSensitivePath(rel, extraGlobs)) return { ok: false, status: "forbidden" };
+    let real;
+    try { real = await fs.promises.realpath(abs); } catch (e) { return { ok: false, status: e && (e.code === "EACCES" || e.code === "EPERM") ? "forbidden" : "not_found" }; }
+    if (!inside(rootReal, real)) return { ok: false, status: "forbidden" };          // symlink that leaves the workspace
+    const relReal = toPosix(path.relative(rootReal, real));
+    if (!relReal || isSensitivePath(relReal, extraGlobs)) return { ok: false, status: "forbidden" }; // link to a sensitive file
+    let st;
+    try { st = await fs.promises.lstat(real); } catch { return { ok: false, status: "not_found" }; }
+    if (!st.isFile()) return { ok: false, status: "not_found" };
+    return { ok: true, real, relReal, stat: st };
+}
+
+/**
+ * Reads the whole file (<= maxBytes) through a descriptor opened without following links and verified to be the
+ * file that resolveInside() checked.
+ * @returns {Promise<{ok:true, buffer:Buffer} | {ok:false, status:"not_found"|"forbidden"|"too_large"}>}
+ */
+export async function readRegular(resolved, maxBytes, signal) {
+    if (resolved.stat.size > maxBytes) return { ok: false, status: "too_large" };
+    let fh;
+    try {
+        fh = await fs.promises.open(resolved.real, fs.constants.O_RDONLY | O_NOFOLLOW);
+        const st = await fh.stat();
+        if (!st.isFile()) return { ok: false, status: "not_found" };
+        if (resolved.stat.ino !== 0 && (st.ino !== resolved.stat.ino || st.dev !== resolved.stat.dev)) return { ok: false, status: "forbidden" };
+        if (st.size > maxBytes) return { ok: false, status: "too_large" };
+        const buf = Buffer.allocUnsafe(Math.min(st.size, maxBytes) + 1);
+        let n = 0;
+        while (n < buf.length) {
+            if (signal && signal.aborted) return { ok: false, status: "not_found" };
+            const { bytesRead } = await fh.read(buf, n, buf.length - n, n);
+            if (bytesRead === 0) break;
+            n += bytesRead;
+        }
+        if (n > maxBytes) return { ok: false, status: "too_large" }; // grew while reading
+        return { ok: true, buffer: Buffer.from(buf.subarray(0, n)) };
+    } catch (e) {
+        return { ok: false, status: e && (e.code === "ELOOP" || e.code === "EACCES" || e.code === "EPERM") ? "forbidden" : "not_found" };
+    } finally {
+        if (fh) await fh.close().catch(() => {});
+    }
+}

package/src/la-protocol-v2/content-handlers/ref-registry.js

@@ -0,0 +1,87 @@
+/**
+ * ref-registry.js - opaque content ids (F3-07).
+ *
+ * The control plane never sees a path: the `ref` of a `content.request` is an id that THIS agent minted when it
+ * reported metadata (a file list, a diff summary) and that only this agent can map back to (workspace, relative path).
+ *
+ *   id        "cr1_" + 22 base64url chars = 128 random bits from crypto.randomBytes. NOT derived from the path
+ *             (no hash, no HMAC of it): knowing a path tells nothing about its id and the other way round.
+ *   validity  `ttlMs` from the mint (default 15 min); expired ids are gone (not_found), the CP asks for a new listing.
+ *             In memory only: a restart of the agent forgets every id (also not_found), by design.
+ *   binding   an id is valid for ONE tenant, ONE workspace (and the root that workspace had when it was minted),
+ *             ONE kind. Any other combination resolves to null, indistinguishable from "never existed".
+ *   size      at most `maxEntries`; the oldest go first.
+ *
+ * Nothing here logs, throws a message with a path, or exposes an id's target to anything but resolve().
+ */
+import crypto from "node:crypto";
+import { normalizeRel, isSensitivePath } from "./path-guard.js";
+
+export const REF_PATTERN = /^cr1_[A-Za-z0-9_-]{22}$/;
+export const REF_KINDS = Object.freeze(["file", "diff"]);
+
+export class ContentRefRegistry {
+    constructor({ tenantId, ttlMs = 15 * 60_000, maxEntries = 20_000, now = Date.now, denyGlobs = [] } = {}) {
+        this.tenantId = tenantId;
+        this.ttlMs = ttlMs;
+        this.maxEntries = maxEntries;
+        this.now = now;
+        this.denyGlobs = denyGlobs;
+        this.entries = new Map(); // id -> { tenantId, workspaceId, root, kind, rel, expiresAt }   (insertion order = age)
+    }
+
+    get size() { return this.entries.size; }
+
+    #purge() {
+        const t = this.now();
+        for (const [id, e] of this.entries) {
+            if (e.expiresAt > t) break; // insertion order is expiry order (one ttl for all)
+            this.entries.delete(id);
+        }
+        while (this.entries.size > this.maxEntries) this.entries.delete(this.entries.keys().next().value);
+    }
+
+    /**
+     * @param {{workspaceId:string, root:string, kind:"file"|"diff", rel?:string|null}} o
+     *        rel = path relative to the workspace root (file: required; diff: optional, null = the whole work tree)
+     * @returns {{id:string, expiresAt:number} | null}  null = refused (bad kind/path or a sensitive file): no id exists
+     */
+    mint({ workspaceId, root, kind, rel = null }) {
+        if (!REF_KINDS.includes(kind) || typeof workspaceId !== "string" || !workspaceId || typeof root !== "string" || !root) return null;
+        let norm = null;
+        if (rel !== null && rel !== undefined) {
+            norm = normalizeRel(rel);
+            if (!norm || isSensitivePath(norm, this.denyGlobs)) return null; // never hand out an id for a file we would refuse
+        } else if (kind === "file") {
+            return null;
+        }
+        this.#purge();
+        const id = `cr1_${crypto.randomBytes(16).toString("base64url")}`;
+        const expiresAt = this.now() + this.ttlMs;
+        this.entries.set(id, { tenantId: this.tenantId, workspaceId, root, kind, rel: norm, expiresAt });
+        this.#purge(); // capacity includes the new entry
+        return { id, expiresAt };
+    }
+
+    /**
+     * @returns {{rel:string|null}} | null   null for: not an id, unknown, expired, other tenant/workspace/root/kind
+     */
+    resolve(id, { workspaceId, root, kind }) {
+        if (typeof id !== "string" || !REF_PATTERN.test(id)) return null;
+        const e = this.entries.get(id);
+        if (!e) return null;
+        if (e.expiresAt <= this.now()) { this.entries.delete(id); return null; }
+        if (e.tenantId !== this.tenantId || e.workspaceId !== workspaceId || e.root !== root || e.kind !== kind) return null;
+        return { rel: e.rel };
+    }
+
+    revoke(id) { return this.entries.delete(id); }
+
+    revokeWorkspace(workspaceId) {
+        let n = 0;
+        for (const [id, e] of this.entries) if (e.workspaceId === workspaceId) { this.entries.delete(id); n++; }
+        return n;
+    }
+
+    clear() { this.entries.clear(); }
+}

package/src/la-protocol-v2/content.js

@@ -0,0 +1,63 @@
+/**
+ * content.js - sends content to the control plane as a stream of `content.response` chunks (the relay of
+ * the design: never persisted or logged by the CP). TRANSPORT ONLY: no handler of `content.request` lives
+ * here (F3-07) and nothing here decides what may leave the machine (DLP is F3-09, before this is called).
+ *
+ * Rules (contract): <= 32 KiB raw per chunk (43692 base64 chars, frame <= 48 KiB), <= 64 chunks (2 MiB per
+ * response), chunk.index from 0, total constant, last only on the final one, byteLength = decoded size.
+ * Each chunk is its own data frame: numbered, acked, retransmitted. At most `maxInFlight` chunks are in
+ * flight and the next one is not even read until a slot opens (bounded memory for any size).
+ */
+import { ProtocolError } from "./errors.js";
+import { chunkCount } from "./chunks.js";
+
+/**
+ * @param {import("./session.js").V2Session} session
+ * @param {object} o
+ * @param {string} o.requestId           the content.request being answered (lower-case UUID)
+ * @param {Buffer | {size:number, read:(offset:number, length:number)=>Promise<Buffer>}} o.source
+ * @param {string} [o.contentType]       one of the contract's content types
+ * @param {string} [o.workspaceId]
+ * @param {AbortSignal} [o.signal]       abort stops reading and drops the chunks still waiting for a slot
+ * @returns {Promise<{chunks:number, bytes:number}>} resolves when the last chunk was acked
+ */
+export async function sendContent(session, { requestId, source, contentType = "application/octet-stream", workspaceId, signal }) {
+    const size = Buffer.isBuffer(source) ? source.length : source.size;
+    if (!Number.isSafeInteger(size) || size < 0) throw new ProtocolError("internal", "source size");
+    const { chunkRawBytes, maxChunks } = session.limits;
+    const total = chunkCount(size, chunkRawBytes);
+    if (total > maxChunks) throw new ProtocolError("payload_too_large", "response above the chunk limit");
+    const acks = [];
+    // an abort must also free a chunk that is waiting for a window slot (enqueue() does not look at the signal)
+    const onAbort = () => session.cancelWaiting(requestId);
+    if (signal) { if (signal.aborted) onAbort(); else signal.addEventListener("abort", onAbort, { once: true }); }
+    try {
+        for (let index = 0; index < total; index++) {
+            if (signal && signal.aborted) throw new ProtocolError("agent_offline", "cancelled");
+            const offset = index * chunkRawBytes;
+            const length = Math.min(chunkRawBytes, size - offset);
+            const bytes = Buffer.isBuffer(source) ? source.subarray(offset, offset + length) : await source.read(offset, length);
+            if (!Buffer.isBuffer(bytes) || bytes.length !== length) throw new ProtocolError("internal", "source returned a wrong length");
+            const h = await session.enqueue("content.response", {
+                status: "ok", contentType, encoding: "base64", data: bytes.toString("base64"), byteLength: length, totalBytes: size,
+            }, { requestId, workspaceId, chunk: { index, total, last: index === total - 1 } });
+            acks.push(h.acked);
+        }
+    } catch (e) {
+        session.cancelWaiting(requestId);
+        for (const a of acks) a.catch(() => {});
+        throw e;
+    } finally {
+        if (signal) signal.removeEventListener("abort", onAbort);
+    }
+    await Promise.all(acks);
+    return { chunks: total, bytes: size };
+}
+
+/** A failed answer: one empty chunk with the status (error | not_found | forbidden) and a wire error code. */
+export async function sendContentFailure(session, { requestId, status = "error", errorCode = "internal", workspaceId }) {
+    // errorCode: null = none on the wire (not_found / forbidden need no code); undefined = "internal" (as before F3-07)
+    await session.send("content.response", {
+        status, ...(errorCode === null ? {} : { errorCode }), encoding: "base64", data: "", byteLength: 0,
+    }, { requestId, workspaceId, chunk: { index: 0, total: 1, last: true } });
+}

package/src/la-protocol-v2/contract/CONTRACT_SOURCE.json

@@ -0,0 +1,81 @@
+{
+  "repo": "VISIONHAMMER/vh-api-gateway",
+  "path": "docs/contracts/la-protocol-v2",
+  "branch": "release/qa",
+  "commit": "b090144e19b1da0182554553b18f321452f03bd6",
+  "branchTip": "7043f75e3ed1b201e2c958fd52f721b5a1177efe",
+  "note": "Copied by scripts/sync-la-protocol-v2-contract.mjs. Do not edit: change the gateway folder and sync again.",
+  "files": {
+    "README.md": "41dd3cbceccb487ca30da5838841f04d8abffcc81c31424da833114ab646b291",
+    "ack.schema.json": "d6dfdaa8b1ec2dd47db9e858cd047ca860196ab6b0ad350f8ccb5d2596441ccf",
+    "alert.schema.json": "01a8a77840be8ab7901ed7d07c3d68a2295bfaeb638694564e19e60be1747054",
+    "approval.decision.schema.json": "a9c7bc74d146465afde1d5830839165a02f232b830b5f6cfd8c8e91fb6da1563",
+    "audit.event.schema.json": "e9ceb58ea00077151373955957b8319324de488c80da4063f6d0dcb40a8b3ed0",
+    "config.update.schema.json": "f5318f24230f542c76a3cb996d08f33210c0b2cc2fc55ad73c4f95648582033f",
+    "content.request.schema.json": "9966b55ec051832ac93ee43e9cd226e4f0efaeb49741947bfc48193e40e00a32",
+    "content.response.schema.json": "c9a66ac9cbbcaec7fc182b3e3fa23b34877bd342592521c7e393779230332231",
+    "defs.schema.json": "f19fd27fd103d8da02de4506c086263c6236250c5c127aa3aab41833a90b743a",
+    "envelope.schema.json": "670fb26c7d532475da144185e5100b3a2ffe0d267451b1ef9debadf31b33ab79",
+    "error.schema.json": "b1fd663d4a1ea73d88cb575422f15f8c7279001f9385ebb2d5e1889b5d5ef878",
+    "heartbeat.schema.json": "8aff84a1ef3ca56bdff8819abb3b0ab01a2547814c2ea2f9ee893cb08f7a08f1",
+    "hello.schema.json": "bd500320f01ff10da49ded6f99c7e8081252019984afb3c178e27003df20b963",
+    "incident.candidate.schema.json": "b292a85917b5958fc6de10a2895732e30a35420385623930c78e47341862dc62",
+    "index.json": "55543ecf492b1ffe2b9a78075890ee05518d3539fbcaeb04e8b2da8ff37c9130",
+    "job.assign.schema.json": "fdebb4ae98bf38a2c723281c1cf9477f71d877171df9a55b0baeb0b65244f60c",
+    "job.cancel.schema.json": "40ef64373283e17306d857c9a40081689786015294b0b88ab8f68f063bd2cfb8",
+    "job.event.schema.json": "493d08f9db4f7ffd4a97403ee33ca4a73a65dc8f774d8f18ef0a137fdb5fc470",
+    "job.result.schema.json": "9cbc61211482557283b8f4df44e79011ead1abbacdb2d986138199c747edc043",
+    "log.stats.schema.json": "4b33b111946a19793a60756793294e90911b06f7050e48821759f2497ec17641",
+    "ready.schema.json": "6e8bd8e1a5ce1b840d35af911ae09b8f58ad9de59eb33cd2b7777859892813f4",
+    "register.schema.json": "e75a4aa9d5d750e1473f71ab2f37d8e9a82fcfab3e8ff1c35118d0c08916e795",
+    "scan.upload.schema.json": "b1bba86ee362f73afc94c8c216977c12f67f770490e81002d14789397692f23b",
+    "scan.uploaded.schema.json": "f4c6aed7b9363b3ce1a9e14f9c4f4fb003bcf104b60acf74421dd0c75fc5d229",
+    "webhook.forward.schema.json": "33d4ee238855339850ff198d1078087f3b2f48c8f290b71def93cc02dd32c985",
+    "vectors/ack.vectors.json": "242ec2b8ff0c748eaaedce63e0015cf5bd9a7092d1055b0670ce6b95403b54b2",
+    "vectors/alert.vectors.json": "0bf179ff390bbecf07a117b80237cb7ac8778864e5780f36d68c8c9a64db8f04",
+    "vectors/approval.decision.vectors.json": "338115973bf2c4390d2bb33ce8f4079f3132cd739cd5505e1e873fdc252d2271",
+    "vectors/audit.event.vectors.json": "d05c1820103eef041a84eb8b13d9a67a8a5b54b9b54ee3b6e43fd4ef15ed7000",
+    "vectors/config.update.vectors.json": "8a5088d547e3eb4e460b25a5e413caaa02d4402a601340e279166d8c17758e1c",
+    "vectors/content.request.vectors.json": "6922748edfc630ce881a1b79d24827de03f849e05c441ef7eecc684bf2238e58",
+    "vectors/content.response.vectors.json": "35ef18edbcec24c029781e97d60dcb0b9111697fa3a5a2a8dfd159744e7f8258",
+    "vectors/cross-type.vectors.json": "f7ed403d3e3f53150b715a5423fde1bed708e8c6245709ed4ad74389dc8c3307",
+    "vectors/error.vectors.json": "f5fd7954f2c1736ee0943eb330c2f85b7fdd7a8959e4f043f9cc9e9bcda39aa5",
+    "vectors/heartbeat.vectors.json": "cfd2e048139c67aa925f1fa94c05326e75248839645c1a1e4d6d3bb60cafa624",
+    "vectors/hello.vectors.json": "51067dc645a2e9d8116997b36e6f3fe36401d27f3ee3c18de32ec30f8a052c5f",
+    "vectors/incident.candidate.vectors.json": "0dd75ef396bf7b7911d20b3ab220469701f07866bb032ee31af58523c3633ab6",
+    "vectors/job.assign.vectors.json": "e510c2cc6d17238d477429c255d828c0339b504e39a3a50d4b6ca980e262d9ef",
+    "vectors/job.cancel.vectors.json": "0fc9f99c8662435e9425389068adf418273489dc73928a21eae1b283256b9bc5",
+    "vectors/job.event.vectors.json": "03a2a2435918ba561821916bf4e435f2780210900139ecf68091acac6abf200c",
+    "vectors/job.result.vectors.json": "05995fbe65e5357705d75e9b660b517f54c6902069d36b62190b1b79f283e7a5",
+    "vectors/log.stats.vectors.json": "a8a67e09ef0f87b81f4028b77427ed7afd809c3f8534b8423a712b2ceef9a27f",
+    "vectors/ready.vectors.json": "a584da17e714a13c3583256773ef0be007660c33c62a456e27568def391e7cef",
+    "vectors/register.vectors.json": "e2a696efc547aa2f7242128d1a860238954f9e9a1330f10b567122d7b3da0365",
+    "vectors/scan.upload.vectors.json": "e8a6f73fe91ac58a3222b68cf28124c1254aa4f00c3ef8f472deb7de31cab76e",
+    "vectors/scan.uploaded.vectors.json": "7314ea15b1afa7b9625048fb7e245492d8910bc0dae8a52ea62afe2a1e240382",
+    "vectors/traces/invalid-agent-mismatch.json": "5f17b867de71c1bcc6c42723acb53a50338c0e491193499ea25c2220ea4fa558",
+    "vectors/traces/invalid-chunk-after-last.json": "0dcc3f3cce605a490d65e96592668381fa9a191d908a26ede998717494eb2f2e",
+    "vectors/traces/invalid-chunk-byte-length-mismatch.json": "d328ad05b22d3abaf0497ee8482a07a08ac90a4ede94edf754e8962ca8ea201e",
+    "vectors/traces/invalid-chunk-last-flag.json": "6c59a361313e966999ec25c80733758d86befb5f3607528634a148291844d212",
+    "vectors/traces/invalid-chunk-out-of-order.json": "c6560290755d86b524316823d32fcbd1420c170b13e198813c3b7e7b7f32ecb6",
+    "vectors/traces/invalid-chunk-total-changes.json": "9b7ade197252275725bc0754e40eadc12a289c063fed13a2905c55583a27a767",
+    "vectors/traces/invalid-clock-skew.json": "de16e0bd72e08bb03d44d5f2f04a238dcd38447ff1690f8acfe712ca3fe2028b",
+    "vectors/traces/invalid-event-before-ready.json": "17081f197fab5f4490b15a088f2bce620921007b5fdd7ed63bd988899d674883",
+    "vectors/traces/invalid-first-frame-not-register.json": "cf41c2d0e67f6df382790dab13bb9e49db99a34a88c1f9d108214be5df1e4ea3",
+    "vectors/traces/invalid-frame-over-48kib.json": "912e37c9a326ad92284ba22af752269cb5dd52ed06cdc22b17fd3b74a8423734",
+    "vectors/traces/invalid-la-sends-job-assign.json": "4ce5313e125e2afa920e923c2b5b524f627f47d06961a250a8dc642b79225252",
+    "vectors/traces/invalid-params-raw-differs-from-payload.json": "1220630372c78a41d77b2653b8f9025cb87d601c199adb03edbf007e6e727ad1",
+    "vectors/traces/invalid-payload-above-limit.json": "99f3834cfea69bc6ffa169bd6a2ed915377331205f8e991ceacbf21b3525fe96",
+    "vectors/traces/invalid-resume-restarts-seq.json": "795964093051511c00538f88774956b471a35338b92a0a180bedb33d460f2d83",
+    "vectors/traces/invalid-seq-gap.json": "9c85719b07cb7309752ffaa33b6c6cb1b278c45cd72e21dbc788c56af5e4502f",
+    "vectors/traces/invalid-seq-repeated.json": "4a4dd18d5b9de61a6cec735229b7991d6de4f3598acd7b16541eaca44be4556d",
+    "vectors/traces/invalid-sig-tenant-mismatch.json": "5d8895cbc9c1b91be31a851d009d1f2b832f9735c3713b131ac9837c90b4a8e7",
+    "vectors/traces/invalid-signature-warn-with-enforce-required.json": "71b5b3dc5dce52417173934db1e0de6542ecae5798e87124d54a8017493312e1",
+    "vectors/traces/invalid-tenant-mismatch.json": "dcc04ea423bddef20524ead7bfd146a5d9c42fe474c9216dc38c90544d291151",
+    "vectors/traces/invalid-type-outside-allowlist.json": "e492d326cfa044d3fc9f7e48dee63a52b715a62ba4867fc5ce21f1d86e3c435f",
+    "vectors/traces/valid-content-chunks-in-order.json": "c5fc301527b062b30c625da2798c7cfab3e3debac29a36f6ec7c699705267ab3",
+    "vectors/traces/valid-handshake-and-job.json": "9aa3c423c496403ca77d63965f1805f0a57ea9f6f8a01351310515b265aeb9cc",
+    "vectors/traces/valid-resume-continues-seq.json": "8aa90f24598f8f2d87a5355ec58c3531d16fd11ad41c782f53eca063372b704a",
+    "vectors/traces/valid-retransmit-is-idempotent.json": "924e9d296a67f0006c289e7cc978b9529ae1aa03bec2cd331a62f31354a90257",
+    "vectors/webhook.forward.vectors.json": "38d5b53b8fb4ecdb051e2c594afc52eb8b2044e4e6aae6ffb0057fbda33bcd46"
+  }
+}