deepdebug-local-agent 1.4.0 → 1.6.0

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

@@ -0,0 +1,182 @@
+/**
+ * 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";
+import { dlpConfigFromEnv } from "../../dlp/index.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" };
+        // F3-07b: content never leaves unmasked. runtime.js does not even register this handler without DLP enforce; this is the
+        // same rule at the moment of the request (the env is read per request), so a changed mode can not open the door.
+        if (dlpConfigFromEnv(env).mode !== "enforce") 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, { allowHardlinks: config.allowHardlinks });
+        if (!resolved.ok) return { status: resolved.status };
+        if (signal.aborted) return { status: "error", errorCode: "agent_offline" };
+        const read = await readRegular(resolved, config.maxBytes, signal, { allowHardlinks: config.allowHardlinks });
+        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, allowHardlinks: config.allowHardlinks, 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();
+        // F3-07b: always defined. If produce() throws, the gateway still gets an answer (a code, never the message of the
+        // exception: it may carry a path) and the request is audited like any other.
+        let result = { status: "error", errorCode: "internal" };
+        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;
+                try {
+                    result = await produce(ctx, p, entry.ac.signal);
+                } catch {
+                    result = { status: "error", errorCode: "internal" };
+                }
+            }
+            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);
+        try {
+            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),
+            });
+        } catch { /* the audit must never take the data path down (nor leave a request without its answer) */ }
+        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(() => warn("[la-content] request failed internally")); });
+            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,65 @@
+/**
+ * install.js - puts the content handlers on a v2 link (F3-07, F3-07b). Called by runtime.js only when
+ * LOCAL_AGENT_CONTENT_HANDLERS=true, v2 is on AND LOCAL_AGENT_DLP_MODE=enforce. Returns what the rest of the agent needs:
+ *
+ *   mintRef({workspaceId, kind, rel, size?})  the HOOK for whoever reports metadata to the control plane (file lists, diff
+ *                                      summaries): returns {id, expiresAt} for that item (id = 43 base64url chars), or null
+ *                                      (sensitive path, unknown workspace). The id is also announced to the control plane in a
+ *                                      `content.index` frame ({kind, ref, size}: no name, no path). Nothing in the agent calls
+ *                                      it yet (the inventory producer is a later increment); `announce()` re-sends what is live.
+ */
+import { dlpConfigFromEnv } from "../../dlp/index.js";
+import { ContentRefRegistry } from "./ref-registry.js";
+import { createContentHandler, SERVED_KINDS } from "./handler.js";
+import { createContentIndexer } from "./content-index.js";
+import { sizeInsideSync } from "./path-guard.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 }) {
+    // F3-07b, defence in depth: runtime.js already refuses; nobody can install the handlers without DLP enforce
+    if (dlpConfigFromEnv(env).mode !== "enforce") throw new Error("content handlers need LOCAL_AGENT_DLP_MODE=enforce");
+    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 indexer = createContentIndexer({ session: link.session, registry, config, log });
+
+    const closeLink = link.close.bind(link);
+    link.close = () => { handler.cancelAll(); indexer.close(); registry.clear(); closeLink(); };
+
+    link.content = {
+        registry,
+        handler,
+        indexer,
+        mintRef: ({ workspaceId, kind, rel, size }) => {
+            try {
+                const ws = resolveWorkspace(workspaceId);
+                if (!ws) return null;
+                const bytes = Number.isSafeInteger(size) ? size
+                    : kind === "file" && typeof rel === "string" ? sizeInsideSync(ws.root, rel.replace(/\\/g, "/"), { allowHardlinks: config.allowHardlinks }) : 0;
+                const minted = registry.mint({ workspaceId, root: ws.root, kind, rel, size: bytes });
+                if (minted) indexer.add({ workspaceId, kind, ref: minted.id, size: bytes, expiresAt: minted.expiresAt });
+                return minted;
+            } catch {
+                return null; // a failing workspace manager means "no id", never an exception with a path in it
+            }
+        },
+        /** Announces again the live ids (of one workspace or all) that the gateway does not know yet. */
+        announce: (opts) => indexer.announce(opts),
+    };
+    return link.content;
+}

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

@@ -0,0 +1,183 @@
+/**
+ * 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.
+ * Hard links (F3-07b): a file with more than one link (st.nlink > 1) is `forbidden` by default, because a hard link
+ * is indistinguishable from the file itself and may be a second name of a file OUTSIDE the root (the realpath check
+ * cannot see it). LOCAL_AGENT_CONTENT_ALLOW_HARDLINKS=true lifts it (pnpm stores and some build trees hard-link
+ * every file). It is checked twice: on the path (resolveInside) and again on the open descriptor (readRegular).
+ * Limit that remains (documented in the note): a directory swapped for a symlink between the check and the open
+ * (TOCTOU on parents).
+ */
+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*", "service-account*.json", "serviceaccount*.json", "secrets.json", "secrets.yml", "secrets.yaml",
+    "*.secret", "*.secrets", "*.tfstate", "*.tfstate.*", "*.tfvars", "*.tfvars.json", "terraform.rc",
+    // F3-07b: editor backups / autosaves of the env file, kubeconfig files
+    ".env~", ".env#", ".#.env", "kubeconfig", "kubeconfig.*", "*.kubeconfig",
+    // F3-07b: Windows 8.3 aliases ("short names") of the files above: ".env" is also reachable as ENV~1, ".npmrc" as NPMRC~1,
+    // "credentials.json" as CREDEN~1.JSO, "id_ed25519" as ID_ED2~1 ... The real name is checked as well (resolveInside), this
+    // covers the alias form on its own. `~?*` = "~" + at least one more character.
+    "env~?*", "npmrc~?*", "pypirc~?*", "netrc~?*", "pgpass~?*", "htpass~?*", "git-cr~?*", "vault-~?*", "kubeco~?*", "creden~?*",
+    "servic~?*", "secret~?*", "id_rsa~?*", "id_dsa~?*", "id_ecd~?*", "id_ed2~?*", "terraf~?*",
+    // (an alias keeps the first 3 characters of the extension: `*.pem`, `*.key`, `*.p12`... already catch their aliases; these are the ones whose
+    // extension is longer than 3: .tfstate -> .TFS, .tfvars -> .TFV, .kdbx -> .KDB, .secret(s) -> .SEC)
+    "*~?*.tfs", "*~?*.tfv", "*~?*.kdb", "*~?*.sec",
+    // 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();
+}
+
+/**
+ * NTFS alternate data streams: ".env::$DATA" and ".env:stream" read the data of ".env". Matching also uses the name without
+ * the stream part of every segment (the original is matched too: on POSIX a colon is an ordinary character).
+ */
+function withoutStreams(folded) {
+    return folded.split("/").map((seg) => { const i = seg.indexOf(":"); return i > 0 ? seg.slice(0, i) : seg; }).join("/");
+}
+
+export function isSensitivePath(rel, extraGlobs = []) {
+    if (typeof rel !== "string") return true;
+    const folded = foldForMatch(rel.replace(/\\/g, "/"));
+    const stripped = withoutStreams(folded);
+    const forms = stripped === folded ? [folded] : [folded, stripped];
+    for (const g of DEFAULT_DENY_GLOBS) { const re = regexFor(g); if (forms.some((f) => re.test(f))) return true; }
+    for (const g of extraGlobs) if (typeof g === "string" && g) { const re = regexFor(g); if (forms.some((f) => re.test(f))) 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 = [], { allowHardlinks = false } = {}) {
+    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" };
+    if (st.nlink > 1 && !allowHardlinks) return { ok: false, status: "forbidden" };   // a hard link may be a second name of a file outside the root
+    return { ok: true, real, relReal, stat: st };
+}
+
+/**
+ * Size of a regular file inside the root, for content.index (informative). 0 for anything else: a link that leaves the
+ * root, a missing file, a hard link (when refused). Nothing is read and nothing but a number comes back.
+ */
+export function sizeInsideSync(root, rel, { allowHardlinks = false } = {}) {
+    try {
+        const rootReal = fs.realpathSync(root);
+        const real = fs.realpathSync(path.join(rootReal, ...rel.split("/")));
+        if (!inside(rootReal, real) || real === rootReal) return 0;
+        const st = fs.lstatSync(real);
+        if (!st.isFile() || (st.nlink > 1 && !allowHardlinks)) return 0;
+        return st.size;
+    } catch { return 0; }
+}
+
+/**
+ * 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, { allowHardlinks = false } = {}) {
+    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 (st.nlink > 1 && !allowHardlinks) return { ok: false, status: "forbidden" };  // linked again after the path check
+        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,105 @@
+/**
+ * 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        43 base64url chars, NO prefix = 256 random bits from crypto.randomBytes(32) (F3-07b: this is the shape
+ *             the gateway and the contract require; the F3-07 form `cr1_` + 22 chars is no longer minted nor accepted).
+ *             NOT derived from the path (no hash, no HMAC of it): knowing a path tells nothing about its id and the
+ *             other way round. The only symbolic ref is `worktree` (kind diff), handled by handler.js, never minted.
+ *   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 = /^[A-Za-z0-9_-]{43}$/;
+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, size, 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, size?:number}} o
+     *        rel  = path relative to the workspace root (file: required; diff: optional, null = the whole work tree)
+     *        size = informative size in bytes that content.index announces (0 when unknown); never a name or a path
+     * @returns {{id:string, expiresAt:number} | null}  null = refused (bad kind/path or a sensitive file): no id exists
+     */
+    mint({ workspaceId, root, kind, rel = null, size = 0 }) {
+        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();
+        let id;
+        do { id = crypto.randomBytes(32).toString("base64url"); } while (this.entries.has(id)); // 43 chars; a repeat is astronomically unlikely, never reused
+        const expiresAt = this.now() + this.ttlMs;
+        const sz = Number.isSafeInteger(size) && size >= 0 && size <= 2 ** 40 ? size : 0;
+        this.entries.set(id, { tenantId: this.tenantId, workspaceId, root, kind, rel: norm, size: sz, 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 };
+    }
+
+    /**
+     * The live ids of this tenant, oldest first, for content.index (re-announcing after a reconnect). Only what that
+     * frame may carry: workspace, kind, id, size. The path stays here.
+     * @returns {{workspaceId:string, kind:string, id:string, size:number, expiresAt:number}[]}
+     */
+    live() {
+        this.#purge();
+        const t = this.now();
+        const out = [];
+        for (const [id, e] of this.entries) if (e.expiresAt > t) out.push({ workspaceId: e.workspaceId, kind: e.kind, id, size: e.size, expiresAt: e.expiresAt });
+        return out;
+    }
+
+    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

@@ -28,6 +28,9 @@ export async function sendContent(session, { requestId, source, contentType = "a
     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");
@@ -44,6 +47,8 @@ export async function sendContent(session, { requestId, source, contentType = "a
         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 };
@@ -51,7 +56,8 @@ export async function sendContent(session, { requestId, source, contentType = "a
 
 /** 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, encoding: "base64", data: "", byteLength: 0,
+        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

@@ -1,26 +1,26 @@
 {
   "repo": "VISIONHAMMER/vh-api-gateway",
   "path": "docs/contracts/la-protocol-v2",
-  "branch": "release/qa",
-  "commit": "b090144e19b1da0182554553b18f321452f03bd6",
-  "branchTip": "7043f75e3ed1b201e2c958fd52f721b5a1177efe",
+  "branch": "feat/edu/f3-07b-gateway-contract",
+  "commit": "55921963e461464b34daf8be604bae162a1c3289",
   "note": "Copied by scripts/sync-la-protocol-v2-contract.mjs. Do not edit: change the gateway folder and sync again.",
   "files": {
-    "README.md": "41dd3cbceccb487ca30da5838841f04d8abffcc81c31424da833114ab646b291",
+    "README.md": "77e95e25b4fa0eb5eb82c1bb3d9676fed4d946d8ce0e02838d8c3f7f57f972a9",
     "ack.schema.json": "d6dfdaa8b1ec2dd47db9e858cd047ca860196ab6b0ad350f8ccb5d2596441ccf",
     "alert.schema.json": "01a8a77840be8ab7901ed7d07c3d68a2295bfaeb638694564e19e60be1747054",
     "approval.decision.schema.json": "a9c7bc74d146465afde1d5830839165a02f232b830b5f6cfd8c8e91fb6da1563",
     "audit.event.schema.json": "e9ceb58ea00077151373955957b8319324de488c80da4063f6d0dcb40a8b3ed0",
     "config.update.schema.json": "f5318f24230f542c76a3cb996d08f33210c0b2cc2fc55ad73c4f95648582033f",
+    "content.index.schema.json": "ba770a0b429331cc801b7b402b74c4e73d229d3b72f3052781720b34c14fb777",
     "content.request.schema.json": "9966b55ec051832ac93ee43e9cd226e4f0efaeb49741947bfc48193e40e00a32",
     "content.response.schema.json": "c9a66ac9cbbcaec7fc182b3e3fa23b34877bd342592521c7e393779230332231",
     "defs.schema.json": "f19fd27fd103d8da02de4506c086263c6236250c5c127aa3aab41833a90b743a",
-    "envelope.schema.json": "670fb26c7d532475da144185e5100b3a2ffe0d267451b1ef9debadf31b33ab79",
+    "envelope.schema.json": "92b3e5b31e6235689a1c22fae1d1eab3f93d377a19032809e47ee014c0ce67e1",
     "error.schema.json": "b1fd663d4a1ea73d88cb575422f15f8c7279001f9385ebb2d5e1889b5d5ef878",
     "heartbeat.schema.json": "8aff84a1ef3ca56bdff8819abb3b0ab01a2547814c2ea2f9ee893cb08f7a08f1",
     "hello.schema.json": "bd500320f01ff10da49ded6f99c7e8081252019984afb3c178e27003df20b963",
     "incident.candidate.schema.json": "b292a85917b5958fc6de10a2895732e30a35420385623930c78e47341862dc62",
-    "index.json": "55543ecf492b1ffe2b9a78075890ee05518d3539fbcaeb04e8b2da8ff37c9130",
+    "index.json": "cf8f05e70b6265a169b0117d4577f78b699818eb5091df6cd4c7c7416385582a",
     "job.assign.schema.json": "fdebb4ae98bf38a2c723281c1cf9477f71d877171df9a55b0baeb0b65244f60c",
     "job.cancel.schema.json": "40ef64373283e17306d857c9a40081689786015294b0b88ab8f68f063bd2cfb8",
     "job.event.schema.json": "493d08f9db4f7ffd4a97403ee33ca4a73a65dc8f774d8f18ef0a137fdb5fc470",
@@ -36,6 +36,7 @@
     "vectors/approval.decision.vectors.json": "338115973bf2c4390d2bb33ce8f4079f3132cd739cd5505e1e873fdc252d2271",
     "vectors/audit.event.vectors.json": "d05c1820103eef041a84eb8b13d9a67a8a5b54b9b54ee3b6e43fd4ef15ed7000",
     "vectors/config.update.vectors.json": "8a5088d547e3eb4e460b25a5e413caaa02d4402a601340e279166d8c17758e1c",
+    "vectors/content.index.vectors.json": "0a59f6b633388d0d1dcb1ebfc6fa6b5e9ad5e399b5a9d8c60b625a9f318f99f9",
     "vectors/content.request.vectors.json": "6922748edfc630ce881a1b79d24827de03f849e05c441ef7eecc684bf2238e58",
     "vectors/content.response.vectors.json": "35ef18edbcec24c029781e97d60dcb0b9111697fa3a5a2a8dfd159744e7f8258",
     "vectors/cross-type.vectors.json": "f7ed403d3e3f53150b715a5423fde1bed708e8c6245709ed4ad74389dc8c3307",
@@ -59,6 +60,7 @@
     "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-content-index-before-ready.json": "360ea95992bdc7f0530c4983db0035d73eb0a4c15db952b8c3d9886f4bd00ad7",
     "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",
@@ -73,6 +75,7 @@
     "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-content-index.json": "9305dc955c4cca1f09158a9c8cf21d9e89d6a6b03646088c547f64a61cd59c30",
     "vectors/traces/valid-handshake-and-job.json": "9aa3c423c496403ca77d63965f1805f0a57ea9f6f8a01351310515b265aeb9cc",
     "vectors/traces/valid-resume-continues-seq.json": "8aa90f24598f8f2d87a5355ec58c3531d16fd11ad41c782f53eca063372b704a",
     "vectors/traces/valid-retransmit-is-idempotent.json": "924e9d296a67f0006c289e7cc978b9529ae1aa03bec2cd331a62f31354a90257",