@ninemind/agentgem 0.1.1 → 0.3.0

package/dist/gem/safeFetch.js

@@ -0,0 +1,112 @@
+// src/gem/safeFetch.ts
+// SSRF guard for installing a .gem from a URL. A localhost-bound dev server is still
+// reachable by a malicious page via CSRF, so an unguarded server-side fetch lets an
+// attacker reach cloud metadata (169.254.169.254) or internal hosts. We resolve the
+// host and refuse any non-public address, re-validate every redirect hop, AND pin the
+// socket to the validated IP via an undici dispatcher so a DNS rebind between the
+// validation and the connect cannot swing the request onto a blocked address.
+import { lookup } from "node:dns/promises";
+import { Agent } from "undici";
+import { InvalidInputError } from "./inputError.js";
+// True for loopback, RFC1918, CGNAT, link-local/metadata, and IPv6 loopback/link-local/ULA.
+export function isBlockedAddress(ip) {
+    const v4 = ip.match(/^(\d+)\.(\d+)\.(\d+)\.(\d+)$/);
+    if (v4) {
+        const a = Number(v4[1]), b = Number(v4[2]);
+        if (a === 0 || a === 127)
+            return true; // 0.0.0.0/8, loopback
+        if (a === 10)
+            return true; // RFC1918
+        if (a === 172 && b >= 16 && b <= 31)
+            return true; // RFC1918
+        if (a === 192 && b === 168)
+            return true; // RFC1918
+        if (a === 169 && b === 254)
+            return true; // link-local + cloud metadata
+        if (a === 100 && b >= 64 && b <= 127)
+            return true; // CGNAT 100.64/10
+        return false;
+    }
+    const v6 = ip.toLowerCase().replace(/^\[/, "").replace(/\]$/, "");
+    if (v6 === "::1" || v6 === "::")
+        return true; // loopback / unspecified
+    if (v6.startsWith("fe80"))
+        return true; // link-local
+    if (v6.startsWith("fc") || v6.startsWith("fd"))
+        return true; // unique-local fc00::/7
+    const mapped = v6.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/); // IPv4-mapped
+    if (mapped)
+        return isBlockedAddress(mapped[1]);
+    return false;
+}
+// Parse + scheme-check + DNS-resolve a URL, rejecting any non-public address.
+// Returns the URL plus the validated addresses (null when allowPrivate skips resolution).
+async function validatePublic(raw, opts) {
+    let u;
+    try {
+        u = new URL(raw);
+    }
+    catch {
+        throw new InvalidInputError(`invalid gem URL: ${raw}`);
+    }
+    if (u.protocol !== "http:" && u.protocol !== "https:") {
+        throw new InvalidInputError(`gem URL must be http(s), got ${u.protocol}`);
+    }
+    if (opts.allowPrivate)
+        return { url: u, validated: null };
+    const host = u.hostname.replace(/^\[/, "").replace(/\]$/, "");
+    const results = await lookup(host, { all: true });
+    if (results.length === 0)
+        throw new InvalidInputError(`could not resolve gem URL host: ${host}`);
+    for (const r of results) {
+        if (isBlockedAddress(r.address))
+            throw new InvalidInputError(`refusing to fetch gem from non-public address ${r.address} (${host})`);
+    }
+    return { url: u, validated: results };
+}
+export async function assertPublicUrl(raw, opts = {}) {
+    return (await validatePublic(raw, opts)).url;
+}
+// A Node lookup function pinned to the validated addresses — it ignores the hostname it is
+// asked to resolve, so a host that rebinds to a blocked IP after validation cannot redirect
+// the socket. This is the piece that actually closes the validate→connect race.
+export function makePinnedLookup(validated) {
+    return (_hostname, options, callback) => {
+        const cb = (typeof options === "function" ? options : callback);
+        const all = typeof options === "object" && options.all;
+        if (all)
+            cb(null, validated);
+        else
+            cb(null, validated[0].address, validated[0].family);
+    };
+}
+// Fetch a .gem over http(s): validate the URL + every redirect hop, and pin each connection
+// to the validated IP set via an undici dispatcher. Size-capped.
+export async function fetchGemBytes(raw, opts = {}) {
+    const maxRedirects = opts.maxRedirects ?? 3;
+    const maxBytes = opts.maxBytes ?? 50 * 1024 * 1024;
+    let target = raw;
+    for (let hop = 0;; hop++) {
+        const { url, validated } = await validatePublic(target, opts);
+        const dispatcher = validated ? new Agent({ connect: { lookup: makePinnedLookup(validated) } }) : undefined;
+        try {
+            const res = await fetch(url.toString(), { redirect: "manual", ...(dispatcher ? { dispatcher } : {}) });
+            const loc = res.headers.get("location");
+            if (res.status >= 300 && res.status < 400 && loc) {
+                if (hop >= maxRedirects)
+                    throw new Error("too many redirects fetching gem");
+                target = new URL(loc, url).toString();
+                continue;
+            }
+            if (!res.ok)
+                throw new Error(`gem fetch failed: HTTP ${res.status}`);
+            const buf = Buffer.from(await res.arrayBuffer());
+            if (buf.length > maxBytes)
+                throw new Error(`gem exceeds max size (${buf.length} > ${maxBytes} bytes)`);
+            return buf;
+        }
+        finally {
+            await dispatcher?.close();
+        }
+    }
+}

package/dist/gem/sandbox.js

@@ -0,0 +1,37 @@
+// src/gem/sandbox.ts
+// Pluggable sandbox-backend registry in front of the RunConnectFn seam. Each backend
+// produces a RunConnectFn pre-scoped to a run dir. Auto-allow is capability-gated:
+// isolated backends run permission:"allow" (the FS boundary bounds blast radius);
+// the child-spawn fallback stays deny unless AGENTGEM_GEM_RUN_AUTOALLOW=1.
+import { connectRunSession } from "./acpRun.js"; // value used at call-time (safe ESM cycle)
+import { wrapWithSandbox } from "./sandboxLaunch.js";
+import { binOnPath } from "./binPath.js";
+export function envPermission(env = process.env) {
+    return env.AGENTGEM_GEM_RUN_AUTOALLOW === "1" ? "allow" : "deny";
+}
+// An isolated backend: wrap the agent command with the OS sandbox launcher (so the
+// agent AND its child shells inherit the jail) and auto-allow tool calls. `bin` is the
+// launcher resolved on PATH (not a hard-coded absolute path — distros place bwrap in
+// /usr/bin or /usr/local/bin), matching the bare name `wrapWithSandbox` actually spawns.
+function isolatedBackend(id, kind, bin, supported) {
+    return {
+        id, isolated: true,
+        available: () => supported() && binOnPath(bin),
+        connectFn: (runDir) => (descriptor, app) => connectRunSession({ ...descriptor, command: wrapWithSandbox(kind, runDir, descriptor.command) }, "allow", app),
+    };
+}
+export const childSpawnBackend = {
+    id: "child-spawn",
+    isolated: false,
+    available: () => true,
+    connectFn: () => (descriptor, app) => connectRunSession(descriptor, envPermission(), app),
+};
+export const RUN_BACKENDS = [
+    isolatedBackend("macos-seatbelt", "macos-seatbelt", "sandbox-exec", () => process.platform === "darwin"),
+    isolatedBackend("linux-bubblewrap", "linux-bubblewrap", "bwrap", () => process.platform === "linux"),
+    childSpawnBackend,
+];
+export function selectRunBackend(runDir, registry = RUN_BACKENDS) {
+    const backend = registry.find((b) => b.isolated && b.available()) ?? registry[registry.length - 1] ?? childSpawnBackend;
+    return { backend, connectFn: backend.connectFn(runDir) };
+}

package/dist/gem/sandboxLaunch.js

@@ -0,0 +1,55 @@
+// src/gem/sandboxLaunch.ts
+// Pure generators for the OS-native sandbox launchers. The v1 boundary contains
+// FILESYSTEM WRITES to the run dir (+ temp); reads, exec, and network stay open. This
+// "write-deny" shape (allow-all, then deny writes, then re-allow under runDir) avoids
+// the deny-default trap that kills the agent's own runtime before it can start.
+import { tmpdir } from "node:os";
+import { realpathSync } from "node:fs";
+// Resolve symlinks when the path exists; fall back to the original string otherwise.
+function tryRealpath(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
+export function seatbeltPolicy(runDir, tmpDir = tmpdir()) {
+    // Resolve symlinks so the SBPL subpath clause matches the kernel's canonical path.
+    // On macOS, tmpdir() returns /var/folders/... but the kernel sees /private/var/folders/...
+    // Fall back to the original path if the directory doesn't exist yet.
+    const realRun = tryRealpath(runDir);
+    const realTmp = tryRealpath(tmpDir);
+    return [
+        "(version 1)",
+        "(allow default)",
+        "(deny file-write*)",
+        "(allow file-write*",
+        `  (subpath ${q(realRun)})`,
+        `  (subpath ${q(realTmp)})`,
+        '  (literal "/dev/null") (literal "/dev/stdout") (literal "/dev/stderr")',
+        '  (subpath "/dev/tty") (regex #"^/dev/fd/"))',
+    ].join("\n");
+}
+// SBPL string literal: wrap in double quotes (paths under our control have no quotes).
+function q(p) { return `"${p}"`; }
+export function bwrapArgs(runDir, tmpDir = tmpdir()) {
+    // Resolve symlinks so the writable bind matches the kernel's canonical path
+    // (mirrors seatbeltPolicy); fall back to the original if the dir doesn't exist yet.
+    const realRun = tryRealpath(runDir);
+    const realTmp = tryRealpath(tmpDir);
+    return [
+        "--ro-bind", "/", "/", // everything readable, nothing writable…
+        "--bind", realRun, realRun, // …except the run dir…
+        "--bind", realTmp, realTmp, // …and temp.
+        "--dev", "/dev",
+        "--unshare-pid", // own PID namespace: the agent can't see/signal host processes
+        "--proc", "/proc", // fresh procfs for that namespace (must follow --unshare-pid)
+        "--die-with-parent",
+    ];
+}
+export function wrapWithSandbox(kind, runDir, command) {
+    if (kind === "macos-seatbelt")
+        return ["sandbox-exec", "-p", seatbeltPolicy(runDir), ...command];
+    return ["bwrap", ...bwrapArgs(runDir), "--", ...command];
+}

package/dist/gem/scrub.js

@@ -0,0 +1,108 @@
+// src/gem/scrub.ts
+//
+// Field-aware, default-deny scrubber for builtin tool_use inputs captured during
+// transcript distillation (see docs/proposals/skill-distillation-from-transcripts.md
+// §3a). Unlike redact.ts (which redacts secret VALUES in a structured config),
+// this keeps only an allowlisted structural slice per builtin and DROPS everything
+// else — removing the file-content/PII class by construction rather than blocklist.
+//
+// Output per step: { verb, arg } — a coarse low-cardinality `verb` for procedure
+// recurrence (§3c) and a minimal scrubbed `arg` for the agent.
+// Token-level secret detection. redact.ts redacts the WHOLE value and can lean on
+// bare keywords because it has key/value structure; here we scrub free-text command
+// tokens, where bare words like "secret"/"token"/"password" legitimately appear in
+// filenames and commit messages (`cat secret.env`). So the rule is intentionally
+// narrower: a token is secret only if it is HIGH-ENTROPY or carries a known secret
+// PREFIX — never a plain dictionary keyword. (Short keyword-less secrets survive;
+// that residual risk is accepted under the draft-only review gate — proposal §3a.)
+const SECRET_PREFIX_RE = /^(sk-|ghp_|gho_|ghu_|ghs_|github_pat_|xox[a-z]-|AKIA|ASIA|glpat-)/;
+function looksLikeSecretToken(t) {
+    if (t.length >= 32 && /^[A-Za-z0-9_-]+$/.test(t))
+        return true; // high entropy
+    if (t.length >= 8 && SECRET_PREFIX_RE.test(t))
+        return true; // prefixed token
+    return false;
+}
+// Rewrite $HOME-absolute prefixes to ~ and any /Users/<name>/ to ~/, so paths
+// never carry a username. Applied before token scrub.
+function dehomePaths(s) {
+    const home = process.env.HOME;
+    let out = home ? s.split(home).join("~") : s;
+    out = out.replace(/\/Users\/[^/\s]+\//g, "~/");
+    return out;
+}
+// Token-scrub a free-text arg: de-home paths, then replace any secret-looking
+// whitespace token with <redacted>, leaving the rest of the command intact.
+function scrubText(s) {
+    return dehomePaths(s)
+        .split(/(\s+)/) // keep separators so spacing is preserved
+        .map((tok) => (/\s/.test(tok) ? tok : redactToken(tok)))
+        .join("");
+}
+// A token may carry a secret embedded in surrounding syntax (https://SECRET@host).
+// Redact the embedded secret, not the whole token, so structure survives.
+function redactToken(tok) {
+    if (!tok)
+        return tok;
+    return tok
+        .split(/([^A-Za-z0-9_-]+)/) // split on non-identifier runs, keep them
+        .map((part) => (/^[A-Za-z0-9_-]+$/.test(part) && looksLikeSecretToken(part) ? "<redacted>" : part))
+        .join("");
+}
+// Scrub free-text prose (mission-hint task/outcome). Same token scrub + de-home as
+// command args, plus a hard length cap — this is the one place free text is kept,
+// so it is deliberately short and low-detail (proposal §3b).
+export function scrubProse(s, maxLen = 280) {
+    const scrubbed = scrubText(s).trim();
+    if (scrubbed.length <= maxLen)
+        return scrubbed;
+    return scrubbed.slice(0, maxLen) + "…";
+}
+// Coarse procedure verb: "git commit -m fix" -> "Bash:git commit", "cd /x" ->
+// "Bash:cd", "/usr/bin/npx vitest" -> "Bash:npx vitest". argv0 is basenamed; the
+// 2nd token counts as a subcommand ONLY if it's a clean lowercase word — a path,
+// filename, flag, or quoted arg is NOT a subcommand, so it never inflates the verb.
+function bashVerb(command) {
+    const toks = command.trim().split(/\s+/).filter(Boolean);
+    if (!toks.length)
+        return "Bash";
+    const argv0 = (toks[0].split("/").pop() || toks[0]).replace(/[;|&]+$/, "");
+    if (!argv0)
+        return "Bash";
+    const sub = toks[1] && /^[a-z][a-z0-9-]*$/.test(toks[1]) ? ` ${toks[1]}` : "";
+    return `Bash:${argv0}${sub}`;
+}
+function str(input, key) {
+    const v = input?.[key];
+    return typeof v === "string" ? v : "";
+}
+// Default-deny: each builtin keeps only an allowlisted structural slice; every
+// other field (file contents, agent prompts, tool output, unknown fields) is
+// dropped, not scrubbed — so the file-content/PII class is removed by construction.
+export function scrubStep(tool, input) {
+    switch (tool) {
+        case "Bash": {
+            const command = str(input, "command");
+            return { verb: bashVerb(command), arg: scrubText(command) };
+        }
+        // Edit/Write/NotebookEdit: keep the path; DROP old_string/new_string/content.
+        case "Edit":
+        case "Write":
+        case "NotebookEdit":
+            return { verb: tool, arg: scrubText(str(input, "file_path") || str(input, "notebook_path")) };
+        // Read/Grep/Glob: keep the path/pattern; DROP file contents and match output.
+        case "Read":
+        case "Grep":
+        case "Glob":
+            return { verb: tool, arg: scrubText(str(input, "file_path") || str(input, "path") || str(input, "pattern")) };
+        // Task/agent spawns: keep the short description; DROP the prompt.
+        case "Task":
+        case "Agent": {
+            const sub = str(input, "subagent_type");
+            return { verb: sub ? `${tool}:${sub}` : tool, arg: scrubText(str(input, "description")) };
+        }
+        // Unknown tool: verb only, entire input dropped.
+        default:
+            return { verb: tool, arg: "" };
+    }
+}

package/dist/gem/search.js

@@ -0,0 +1,34 @@
+// Weighted field match: name >> tags > description. An empty query (with optional
+// kind/tag filter) browses the catalog — every gem returns, score 0.
+export function searchIndex(index, query, opts = {}) {
+    const terms = query.trim().toLowerCase().split(/\s+/).filter(Boolean);
+    const hits = [];
+    for (const [key, item] of Object.entries(index.items)) {
+        const d = item.discovery ?? {};
+        if (opts.kind && !(d.artifactKinds ?? []).includes(opts.kind))
+            continue;
+        if (opts.tag && !(d.tags ?? []).includes(opts.tag))
+            continue;
+        const name = key.toLowerCase();
+        const tags = (d.tags ?? []).join(" ").toLowerCase();
+        const desc = (d.description ?? "").toLowerCase();
+        let score = 0;
+        for (const t of terms) {
+            if (name === t)
+                score += 100;
+            else if (name.includes(t))
+                score += 10;
+            if (tags.split(/\s+/).includes(t))
+                score += 5;
+            else if (tags.includes(t))
+                score += 3;
+            if (desc.includes(t))
+                score += 1;
+        }
+        if (terms.length && score === 0)
+            continue; // query given but nothing matched
+        hits.push({ key, latest: item.latest, score, description: d.description, tags: d.tags, author: d.author, artifactKinds: d.artifactKinds, updatedAt: d.updatedAt });
+    }
+    hits.sort((a, b) => b.score - a.score || a.key.localeCompare(b.key));
+    return hits.slice(0, opts.limit ?? 25);
+}

package/dist/gem/share.js

@@ -0,0 +1,21 @@
+// src/gem/share.ts
+// The registry-optional "easy share" loop: turn a Gem into one portable .gem file
+// and install one back. Pure + in-process — no disk/network — so it composes with
+// any transport (file, URL, gist, paste). Integrity is inherited from readGemArchive,
+// which verifies gem.lock and throws on any mismatch, so a tampered .gem never installs.
+import { writeGemArchive, readGemArchive, readGemMeta } from "./archive.js";
+import { packTar, unpackTar } from "./archiveTar.js";
+import { safePathSegment } from "./targets.js";
+// Gem -> a single self-verifying .gem (gzipped tar of the archive file tree).
+export function exportGem(gem, opts = {}) {
+    const { files, skipped } = writeGemArchive(gem, opts);
+    const version = opts.version ?? "0.1.0";
+    return { filename: `${safePathSegment(gem.name)}-${version}.gem`, bytes: packTar(files), skipped };
+}
+// A .gem's bytes -> the verified Gem. Throws if the bytes aren't a valid archive
+// or if gem.lock verification fails (tampering / corruption).
+export function importGem(bytes) {
+    const files = unpackTar(bytes);
+    const gem = readGemArchive(files); // verifies gem.lock; throws on mismatch
+    return { gem, meta: readGemMeta(files) };
+}