deepdebug-local-agent 1.5.0 → 1.7.0

package/src/la-protocol-v2/content-handlers/git-diff.js

@@ -2,16 +2,34 @@
  * git-diff.js - `diff` kind: the work tree against HEAD, for the files that may be shown (F3-07).
  *
  * No shell. git runs with the agent's env minus secret-looking variables and minus every GIT_* variable (a stray
- * GIT_DIR must not point it at another repository), without external diff drivers, textconv filters or fsmonitor
- * hooks (a malicious repo config could name a command for each), with literal pathspecs. The file list is taken
- * first and filtered (sensitive and out-of-root names never reach the second call), then diffed with that explicit list
- * (at most `maxFiles` names and 128 KiB of arguments). Output is capped while it streams (the process is killed above the cap).
+ * GIT_DIR must not point it at another repository), without external diff drivers, textconv or fsmonitor hooks
+ * (a malicious repo config could name a command for each), with literal pathspecs. The file list is taken
+ * first and filtered (sensitive names, and hard-linked files unless allowed, never reach the second call), then diffed
+ * with that explicit list (at most `maxFiles` names and 128 KiB of arguments). Output is capped while it streams (the
+ * process is killed above the cap).
+ *
+ * Clean/smudge filters (F3-07b). `--no-ext-diff` and `--no-textconv` do NOT stop `git diff` from running the
+ * `filter.<name>.clean` command (and `process`, the long-running filter) of the repository config: to compare a work tree file with
+ * the index git first converts it with the clean filter its .gitattributes names, and that is a command line chosen
+ * by whoever wrote the repository. Before the two diff calls the filters the config defines are listed (`git config
+ * --get-regexp '^filter\.'`, which runs nothing) and every one of them is overridden on the command line with an empty
+ * clean, smudge and process and `required=false` (git treats an empty command as "no filter"; a still-required one
+ * would abort). Fail closed: if the list cannot be read, or has more than MAX_FILTERS names, there is no diff.
+ * Consequence: a work tree that depends on a filter (git-lfs, keyword expansion) is diffed as stored, unfiltered.
+ *
+ * Symlinks (F3-07c). The hunk of a tracked symlink ("new file mode 120000", "+/abs/target") prints the TARGET of the link, i.e. an
+ * absolute path on this machine. Entries whose mode is 120000 on either side (git diff --raw: a link added, changed, removed, or a file
+ * replaced by a link and the other way round) never reach the second call; the names are also lstat-ed (a file turned into a link in
+ * between) and, as a last net, `dropSymlinkBlocks()` removes from the text any per-file block whose header says 120000.
  */
 import { spawn } from "node:child_process";
 import fs from "node:fs";
 import { sanitizedChildEnv } from "../../utils/child-env.js";
+import path from "node:path";
 import { isSensitivePath, normalizeRel } from "./path-guard.js";
 
+const MAX_FILTERS = 64;
+
 const GIT_SAFE = ["--literal-pathspecs", "-c", "core.quotepath=off", "-c", "core.fsmonitor=false", "-c", "core.pager=cat", "-c", "diff.external="];
 
 function gitEnv() {
@@ -53,11 +71,36 @@ function runGit(args, { cwd, input, maxBytes, timeoutMs, signal }) {
     });
 }
 
+/**
+ * `-c` overrides that switch off every filter the repository (or the user's global config) defines.
+ * @returns {Promise<{ok:true, args:string[]} | {ok:false, status:"error", errorCode:string}>}
+ */
+export async function filterOverrides({ cwd, timeoutMs, signal }) {
+    const r = await runGit([...GIT_SAFE, "config", "--null", "--get-regexp", "^filter\\."], { cwd, maxBytes: 1024 * 1024, timeoutMs, signal });
+    if (r.aborted) return { ok: false, status: "error", errorCode: "agent_offline" };
+    if (r.timedOut) return { ok: false, status: "error", errorCode: "timeout" };
+    if (r.code === 1 && !r.overflow) return { ok: true, args: [] };   // exit 1 = no such key: no filter is defined
+    if (r.code !== 0 || r.overflow) return { ok: false, status: "error", errorCode: "internal" };
+    const names = new Set();
+    for (const entry of r.out.toString("utf8").split("\0")) {
+        const key = entry.split("\n", 1)[0];                          // "filter.<name>.<variable>" (name may contain dots)
+        if (!key.toLowerCase().startsWith("filter.")) continue;
+        const last = key.lastIndexOf(".");
+        if (last <= "filter.".length) continue;                        // "filter.x": a variable without a name, nothing to run
+        names.add(key.slice("filter.".length, last));
+    }
+    if (names.size > MAX_FILTERS) return { ok: false, status: "error", errorCode: "internal" };
+    const args = [];
+    for (const n of names) for (const v of ["clean", "smudge", "process"]) args.push("-c", `filter.${n}.${v}=`);
+    for (const n of names) args.push("-c", `filter.${n}.required=false`);
+    return { ok: true, args };
+}
+
 /**
  * @param {{root:string, rel?:string|null, maxBytes:number, maxFiles:number, timeoutMs:number, denyGlobs?:string[], signal?:AbortSignal}} o
  * @returns {Promise<{ok:true, text:string} | {ok:false, status:"not_found"|"forbidden"|"error", errorCode?:string}>}
  */
-export async function worktreeDiff({ root, rel = null, maxBytes, maxFiles, timeoutMs, denyGlobs = [], signal }) {
+export async function worktreeDiff({ root, rel = null, maxBytes, maxFiles, timeoutMs, denyGlobs = [], allowHardlinks = false, signal }) {
     let cwd;
     try { cwd = await fs.promises.realpath(root); } catch { return { ok: false, status: "not_found" }; }
     let only = null;
@@ -66,7 +109,10 @@ export async function worktreeDiff({ root, rel = null, maxBytes, maxFiles, timeo
         if (!only) return { ok: false, status: "not_found" };
         if (isSensitivePath(only, denyGlobs)) return { ok: false, status: "forbidden" };
     }
-    const listArgs = [...GIT_SAFE, "diff", "--name-only", "-z", "--no-renames", "--no-ext-diff", "--relative", "HEAD", "--", ...(only ? [only] : ["."])];
+    const filters = await filterOverrides({ cwd, timeoutMs, signal });
+    if (!filters.ok) return filters;
+    const safe = [...GIT_SAFE, ...filters.args];
+    const listArgs = [...safe, "diff", "--raw", "-z", "--no-abbrev", "--no-renames", "--no-ext-diff", "--relative", "HEAD", "--", ...(only ? [only] : ["."])];
     const listed = await runGit(listArgs, { cwd, maxBytes: 4 * 1024 * 1024, timeoutMs, signal });
     if (listed.aborted) return { ok: false, status: "error", errorCode: "agent_offline" };
     if (listed.timedOut) return { ok: false, status: "error", errorCode: "timeout" };
@@ -74,19 +120,58 @@ export async function worktreeDiff({ root, rel = null, maxBytes, maxFiles, timeo
     if (listed.code !== 0) return { ok: false, status: "not_found" }; // not a repository, no HEAD yet, unsafe directory...
     const names = [];
     let argBytes = 0;
-    for (const n of listed.out.toString("utf8").split("\0")) {
-        const norm = n ? normalizeRel(n) : null;
+    for (const n of rawPaths(listed.out.toString("utf8"))) {
+        if (n.symlink) continue;                                           // the hunk would print the target of the link
+        const norm = n.path ? normalizeRel(n.path) : null;
         if (!norm || isSensitivePath(norm, denyGlobs)) continue;
+        if (await isLinkOnDisk(cwd, norm, allowHardlinks)) continue;       // a link (or a hard link) now, whatever git remembers
         argBytes += Buffer.byteLength(norm) + 1;
         if (names.length >= maxFiles || argBytes > 128 * 1024) break;
         names.push(norm);
     }
     if (names.length === 0) return { ok: true, text: "" };
-    const diffArgs = [...GIT_SAFE, "diff", "--no-color", "--no-ext-diff", "--no-textconv", "--no-renames", "--relative", "-U3", "HEAD", "--", ...names];
+    const diffArgs = [...safe, "diff", "--no-color", "--no-ext-diff", "--no-textconv", "--no-renames", "--relative", "-U3", "HEAD", "--", ...names];
     const diff = await runGit(diffArgs, { cwd, maxBytes: maxBytes + 1, timeoutMs, signal });
     if (diff.aborted) return { ok: false, status: "error", errorCode: "agent_offline" };
     if (diff.timedOut) return { ok: false, status: "error", errorCode: "timeout" };
     if (diff.overflow) return { ok: false, status: "error", errorCode: "payload_too_large" };
     if (diff.code !== 0) return { ok: false, status: "error", errorCode: "internal" };
-    return { ok: true, text: diff.out.toString("utf8") };
+    return { ok: true, text: dropSymlinkBlocks(diff.out.toString("utf8")) };
+}
+
+/**
+ * `git diff --raw -z` -> [{path, symlink}]: ":<oldmode> <newmode> <oldsha> <newsha> <status>\0<path>\0" per entry (no renames: one path).
+ * @returns {{path:string, symlink:boolean}[]}
+ */
+export function rawPaths(out) {
+    const parts = out.split("\0");
+    const res = [];
+    for (let i = 0; i < parts.length; i++) {
+        const meta = parts[i];
+        if (!meta.startsWith(":")) continue;
+        const f = meta.slice(1).split(" ");
+        const p = parts[i + 1];
+        i++;
+        if (typeof p !== "string") break;
+        res.push({ path: p, symlink: f[0] === "120000" || f[1] === "120000" });
+    }
+    return res;
+}
+
+/** Removes the per-file blocks of a diff whose header (up to the first hunk) names mode 120000 (a symlink): they print the link target. */
+export function dropSymlinkBlocks(text) {
+    if (!text.includes("120000")) return text;
+    const blocks = text.split(/^(?=diff --git )/m);
+    return blocks.filter((b) => {
+        const head = b.split(/^@@/m, 1)[0];
+        return !/^(?:(?:new file|deleted file|old|new) mode 120000|index [0-9a-f]+\.\.[0-9a-f]+ 120000)\s*$/m.test(head);
+    }).join("");
+}
+
+/** True for a symlink, or (unless allowed) a regular file with more than one link. A name that no longer exists (a deletion) is neither. */
+async function isLinkOnDisk(cwd, rel, allowHardlinks) {
+    try {
+        const st = await fs.promises.lstat(path.join(cwd, ...rel.split("/")));
+        return st.isSymbolicLink() || (!allowHardlinks && st.isFile() && st.nlink > 1);
+    } catch { return false; }
 }

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

@@ -6,7 +6,7 @@
  *   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`
+ *   3. kind: `file`, `diff` and `file.list` (F3-07c: a folder listing that mints the ids of what it shows) 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
@@ -22,15 +22,19 @@ 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 { listFolder, ROOT_REF, clampLimit, MAX_LIST_BYTES } from "./file-list.js";
 import { worktreeDiff } from "./git-diff.js";
-import { prepareOutgoing, contentTypeOf, decodeText } from "./egress.js";
+import { prepareOutgoing, prepareList, maskName, 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"]);
+export const SERVED_KINDS = Object.freeze(["file", "diff", "file.list"]);
 /** 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 }) {
+export function createContentHandler({ session, tenantId, resolveWorkspace, registry, config, env = process.env, log = console, audit = null, now = Date.now, mint = null }) {
+    // F3-07c: where the ids of a listing come from. install.js passes mintRef (registry + content.index); without it (tests) the registry alone.
+    const mintFor = (workspaceId, root) => (o) => (mint ? mint({ workspaceId, ...o }) : registry.mint({ workspaceId, root, ...o }));
     const inflight = new Map(); // requestId -> { ac, timer }
     let reservedBytes = 0;
     const auditor = audit || createAudit({ file: config.auditFile, now });
@@ -43,8 +47,12 @@ export function createContentHandler({ session, tenantId, resolveWorkspace, regi
     /** @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" };
+        if (p.kind === "file.list") return produceList(ctx, p, ws, signal);
         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" };
@@ -55,18 +63,38 @@ export function createContentHandler({ session, tenantId, resolveWorkspace, regi
     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);
+        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);
+        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");
     }
 
+    /** F3-07c: `root` or a folder id (or the nextRef of a previous page) -> one page of names with the ids to ask for them. */
+    async function produceList(ctx, p, ws, signal) {
+        if (p.range) return { status: "error", errorCode: "protocol_unsupported" }; // a listing has no byte range
+        let rel = null;
+        let after = null;
+        if (p.ref !== ROOT_REF) {
+            const target = registry.resolve(p.ref, { workspaceId: ctx.workspaceId, root: ws.root, kind: "file.list" });
+            if (!target) return { status: "not_found" };
+            rel = target.rel && normalizeRel(target.rel);
+            if (target.rel && !rel) return { status: "not_found" };
+            after = target.after;
+        }
+        const r = await listFolder({ root: ws.root, rel, after, limit: clampLimit(p.limit), maxBytes: config.maxBytes, maxDirEntries: config.maxDirEntries,
+            denyGlobs: config.extraDenyGlobs, allowHardlinks: config.allowHardlinks, signal, mint: mintFor(ctx.workspaceId, ws.root),
+            maskName: (n) => maskName(n, { env }) });
+        if (!r.ok) return r;
+        const out = prepareList({ buffer: r.body, maxBytes: Math.min(config.maxBytes, MAX_LIST_BYTES), dlp: { mode: "enforce", total: r.dlp.total, redactions: r.dlp.redactions } });
+        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 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 });
+            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");
     }
@@ -79,7 +107,9 @@ export function createContentHandler({ session, tenantId, resolveWorkspace, regi
 
     async function run(ctx, p, entry) {
         const t0 = now();
-        let result;
+        // 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 {
@@ -88,7 +118,11 @@ export function createContentHandler({ session, tenantId, resolveWorkspace, regi
             } else {
                 reservedBytes += reserveEach;
                 entry.reserved = true;
-                result = await produce(ctx, p, entry.ac.signal);
+                try {
+                    result = await produce(ctx, p, entry.ac.signal);
+                } catch {
+                    result = { status: "error", errorCode: "internal" };
+                }
             }
             if (entry.ac.signal.aborted) {
                 errorCode = "cancelled";
@@ -122,12 +156,14 @@ export function createContentHandler({ session, tenantId, resolveWorkspace, regi
         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),
-        });
+        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}`);
     }
 
@@ -147,7 +183,7 @@ export function createContentHandler({ session, tenantId, resolveWorkspace, regi
             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(() => {}); });
+            queueMicrotask(() => { run(ctx, p, entry).catch(() => warn("[la-content] request failed internally")); });
             return { accept: true };
         },
 

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

@@ -1,19 +1,24 @@
 /**
- * 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:
+ * 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})  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).
+ *   mintRef({workspaceId, kind, rel, size?, after?})  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). F3-07c: the real caller is the
+ *                                      `file.list` handler (handler.js / file-list.js), which mints one id per entry it lists;
+ *                                      `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 });
 
@@ -29,22 +34,37 @@ export function installContentHandlers({ link, tenantId, wsManager, getWorkspace
         return null;
     };
 
-    const handler = createContentHandler({ session: link.session, tenantId: tenant, resolveWorkspace, registry, config, env, log });
+    // `indexer` is created below (it needs the session only); mintRef and the handler use it through this binding
+    let indexer = null;
+    const mintRef = ({ workspaceId, kind, rel, size, after }) => {
+        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, after });
+            if (minted && indexer) 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
+        }
+    };
+
+    // F3-07c: the listing handler mints through mintRef, so every id it hands out is also announced with content.index
+    const handler = createContentHandler({ session: link.session, tenantId: tenant, resolveWorkspace, registry, config, env, log, mint: mintRef });
     link.session.setHandler("content.request", (ctx) => handler.handle(ctx));
+    indexer = createContentIndexer({ session: link.session, registry, config, log });
 
     const closeLink = link.close.bind(link);
-    link.close = () => { handler.cancelAll(); registry.clear(); closeLink(); };
+    link.close = () => { handler.cancelAll(); indexer.close(); 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;
-        },
+        indexer,
+        mintRef,
+        /** 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

@@ -3,15 +3,22 @@
  * 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/, ...
+ *   isSensitivePath  deny list (built-in globs + name rules + LOCAL_AGENT_CONTENT_DENY_GLOBS): .env*, private keys, .git/, .ssh/, ...
+ *                    F3-07c: names that merely MENTION a credential (credentials.service.ts, CredentialsController.java) are
+ *                    code and are served; files that ARE credentials (credentials, credentials.json, .credentials,
+ *                    application_default_credentials.json, ...) are not. See sensitiveByName(). The DLP stays the 2nd layer.
  *   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).
+ * 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";
@@ -21,12 +28,35 @@ 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",
+    ".env", ".env.*", "*.env", ".envs/",
     "*.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",
+    "service-account*.json", "serviceaccount*.json", "secrets.json", "secrets.yml", "secrets.yaml",
+    // F3-07c: directories named for secrets (everything under them), by Edu's decision of 2026-11-03
+    "secrets/", ".secrets/", ".credentials/",
     "*.secret", "*.secrets", "*.tfstate", "*.tfstate.*", "*.tfvars", "*.tfvars.json", "terraform.rc",
+    // F3-07b: editor backups / autosaves of the env file, kubeconfig files
+    ".env~", ".env#", ".#.env", "*.kubeconfig",
+    // (F3-07c: .envrc, .env_backup, .env-prod, env.production, kubeconfig-prod, credentials* ... are name RULES, sensitiveByName() below)
+    // 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",
+    // F3-07c review: credential files that no rule above names (the DLP is only the second layer: it masks known token shapes, not plain values)
+    ".dockercfg", ".yarnrc", ".yarnrc.yml", ".pnpmrc", ".s3cfg", ".boto", ".terraformrc", ".renviron", "auth.json",
+    "client_secret*.json", "firebase-adminsdk*.json", "gha-creds-*.json", "local.settings.json", "wp-config.php",
+    "application-prod.properties", "application-prod.yml", "application-prod.yaml",
+    "*_rsa", "*_dsa", "*_ecdsa", "*_ed25519", "ssh_host_*_key",
+    ".m2/settings.xml", ".m2/settings-security.xml",
+    // family names that are also directories: everything under them is blocked (a bare `.env_backup/a.txt` was readable)
+    ".envrc/", ".env_backup/", ".env-prod/", "env.production/", "kubeconfig-prod/",
+    // 8.3 aliases of .envrc / .envs
+    "envrc~?*", "envs~?*",
     // 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/",
 ]);
@@ -60,11 +90,74 @@ function foldForMatch(rel) {
     return rel.split("/").map((seg) => seg.replace(/[. ]+$/, "") || seg).join("/").toLowerCase();
 }
 
-export function isSensitivePath(rel, extraGlobs = []) {
+/**
+ * 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("/");
+}
+
+/**
+ * Extensions of SOURCE / documentation files (F3-07c). A name that mentions a credential, a kubeconfig or an env file is
+ * served only when its last extension is one of these: credentials.service.ts, CredentialsController.java, credentials_test.py
+ * are code about credentials; credentials, credentials.json, .credentials, credentials.bak are credentials. Everything that is not
+ * known code fails closed (an unknown extension is NOT a reason to serve). Not in the list on purpose: data and config formats
+ * (json, yml, yaml, xml, toml, ini, cfg, conf, csv, txt, properties, db, sqlite, enc, env ...), shell/batch scripts and gradle
+ * (they export or hold values), key stores, backups (bak, old, orig, tmp, swp) and anything with no extension.
+ */
+export const CODE_EXTENSIONS = Object.freeze(new Set([
+    "ts", "tsx", "mts", "cts", "js", "jsx", "mjs", "cjs", "java", "kt", "kts", "py", "go", "rb", "cs", "rs", "php", "scala", "swift",
+    "vue", "svelte", "astro", "c", "cc", "cpp", "cxx", "h", "hh", "hpp", "m", "mm", "sql", "md", "markdown", "rst", "adoc", "html", "htm",
+    "css", "scss", "sass", "less", "dart", "ex", "exs", "erl", "hrl", "clj", "cljs", "lua", "pl", "pm", "r", "jl", "hs", "ml", "fs", "fsx",
+    "vb", "groovy", "proto", "graphql", "gql", "tf", "cshtml", "razor", "jsp", "ejs", "hbs", "pug", "zig", "nim", "sol",
+]));
+
+/** Last extension of a (folded) file name; "" for no extension and for a name that only starts with a dot. */
+function extOf(name) {
+    const i = name.lastIndexOf(".");
+    return i > 0 ? name.slice(i + 1) : "";
+}
+const isCodeName = (name) => CODE_EXTENSIONS.has(extOf(name));
+
+/**
+ * Name rules (on top of the globs): the families whose names have to be told apart from source code. `segs` are the folded path
+ * segments; the last one is a directory when `dir` is true (a listing entry), a file otherwise.
+ *   - .env family: `.env`, `.envrc`, then end or a separator (. _ - # ~): .env_backup, .env-prod, .env.local~, .envrc.local. Not .environment.
+ *   - env.<x> / env_<x> / env-<x> and a bare `env` file: env.production, env_prod: unless code (env.ts, env.d.ts, env.config.mjs).
+ *   - names with "credential" or "kubeconfig": unless code (credentials.service.ts) ... a DIRECTORY with such a name is fine
+ *     (src/credentials/), but a file under one has to be code (credentials/prod.json is not), and `.credentials` is never fine.
+ */
+function sensitiveByName(segs, dir) {
+    const last = segs.length - 1;
+    for (let i = 0; i < segs.length; i++) {
+        const seg = segs[i];
+        const asDir = i < last || dir;
+        if (asDir) {
+            if (seg === ".credentials") return true;
+            continue;
+        }
+        if (/^\.env(?:rc)?(?![a-z])/.test(seg)) return true;
+        if (seg === "env" || (/^env[._-]/.test(seg) && !isCodeName(seg))) return true;
+        if ((seg.includes("credential") || seg.includes("kubeconfig")) && !isCodeName(seg)) return true;
+        if (i > 0 && segs.slice(0, i).some((d) => d.includes("credential")) && !isCodeName(seg)) return true;
+    }
+    return false;
+}
+
+/**
+ * @param {string} rel
+ * @param {string[]} [extraGlobs]
+ * @param {{dir?: boolean}} [o]  dir: the last segment is a directory (a listing entry, a folder id): file-only name rules do not apply to it
+ */
+export function isSensitivePath(rel, extraGlobs = [], { dir = false } = {}) {
     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;
+    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 f of forms) if (sensitiveByName(f.split("/"), dir)) 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;
 }
 
@@ -93,7 +186,7 @@ const inside = (root, abs) => abs === root || abs.startsWith(root.endsWith(path.
  * @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 = []) {
+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("/"));
@@ -107,21 +200,38 @@ export async function resolveInside(root, rel, extraGlobs = []) {
     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) {
+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);