deepdebug-local-agent 1.4.0 → 1.5.0

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

@@ -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/runtime.js

@@ -7,6 +7,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { createV2Link } from "./link.js";
+import { resolveContentHandlersConfig } from "./content-handlers/config.js";
 
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 const WORKSPACE_ID = /^[A-Za-z0-9_.-]{0,64}$/;
@@ -32,9 +33,9 @@ async function diskFreeBytes(dir) {
 }
 
 /**
- * @returns the link, or null (with a warning) when v2 cannot run here: then the tunnel is the plain v1 client.
+ * @returns {Promise} the link, or null (with a warning) when v2 cannot run here: then the tunnel is the plain v1 client.
  */
-export function buildV2Link({ tenantId, agentId, signing, wsManager, getWorkspaceRoot, log = console, env = process.env }) {
+export async function buildV2Link({ tenantId, agentId, signing, wsManager, getWorkspaceRoot, log = console, env = process.env }) {
     const tenant = String(tenantId || "").toLowerCase();
     if (!UUID.test(tenant)) { log.warn("[la-v2] off: the tenant id is not a UUID"); return null; }
     if (!agentId) { log.warn("[la-v2] off: no agent id (authorizationId in ~/.deepdebug/config.json or LOCAL_AGENT_ID)"); return null; }
@@ -42,7 +43,10 @@ export function buildV2Link({ tenantId, agentId, signing, wsManager, getWorkspac
     let lastDisk = 0;
     const refreshDisk = () => diskFreeBytes(getWorkspaceRoot() || process.cwd()).then((v) => { lastDisk = v; });
     refreshDisk();
-    return createV2Link({
+    // F3-07: content.request handlers, behind LOCAL_AGENT_CONTENT_HANDLERS (default off: nothing below changes anything)
+    const contentCfg = resolveContentHandlersConfig(env, (m) => log.warn(m));
+    const contentCaps = contentCfg.enabled ? ["content.diff", "content.file"] : [];
+    const link = createV2Link({
         log,
         sessionOptions: {
             tenantId: tenant,
@@ -51,7 +55,7 @@ export function buildV2Link({ tenantId, agentId, signing, wsManager, getWorkspac
             signing,
             laVersion: agentVersion(),
             // only what this build implements: the transport, the handshake and the v1 commands on the same connection
-            capabilities: ["protocol.v2", "v1.commands", "chunk.base64"],
+            capabilities: ["protocol.v2", "v1.commands", "chunk.base64", ...contentCaps],
             getWorkspaces: () => {
                 const open = (wsManager?.list?.() || []).map((w) => ({
                     workspaceId: String(w.id || ""),
@@ -69,4 +73,9 @@ export function buildV2Link({ tenantId, agentId, signing, wsManager, getWorkspac
             },
         },
     });
+    if (contentCfg.enabled) {
+        const { installContentHandlers } = await import("./content-handlers/install.js");
+        installContentHandlers({ link, tenantId: tenant, wsManager, getWorkspaceRoot, config: contentCfg, env, log });
+    }
+    return link;
 }

package/src/server.js

@@ -647,6 +647,9 @@ const WS_METADATA = resolveWsMetadataConfig();
 const WS_CONNECTION = createConnectionState();
 // LOCAL_AGENT_PROTOCOL_V2 (F3-05b, default off): with it off the tunnel below is the v1 client, untouched.
 const PROTOCOL_V2 = resolveProtocolV2Config();
+if (!PROTOCOL_V2.enabled && /^(true|1|yes|on)$/i.test(String(process.env.LOCAL_AGENT_CONTENT_HANDLERS ?? '').trim())) {
+    console.warn('[la-v2] LOCAL_AGENT_CONTENT_HANDLERS is set but LOCAL_AGENT_PROTOCOL_V2 is off: content handlers stay off');
+}
 if (WS_METADATA.mode === "enforce") {
     EXEC_POLICY.offlineGuard = createOfflinePolicyGuard({
         connection: WS_CONNECTION,
@@ -6985,7 +6988,7 @@ async function startWebSocketTunnel(port, gatewayUrl, authToken, tenantId, agent
     if (PROTOCOL_V2.enabled) {
         try {
             const { buildV2Link } = await import('./la-protocol-v2/runtime.js');
-            v2Link = buildV2Link({ tenantId, agentId, signing: SIGNING, wsManager, getWorkspaceRoot: () => WORKSPACE_ROOT });
+            v2Link = await buildV2Link({ tenantId, agentId, signing: SIGNING, wsManager, getWorkspaceRoot: () => WORKSPACE_ROOT });
         } catch (err) {
             console.warn(`[la-v2] off: ${err.code || err.name} while loading the protocol module`);
         }