@retasc/cli 1.22.0 → 1.23.0

package/CHANGELOG.md

@@ -6,6 +6,22 @@ release commits and the issues they reference.
 
 Dates are the npm publish date. Each entry names the RTSC issue behind it.
 
+## 1.23.0 (2026-08-17)
+
+- **RTSC-660** — the proxy attaches files for you. Attaching a file was the one Retasc write
+  an agent could not finish on its own: the server handed back an upload URL and told the
+  caller to POST the bytes with "your API key", which under MCP lives in the proxy, not in
+  the model. Agents were resorting to reading the key out of `~/.retasc/bindings.json`, and
+  harnesses were blocking that as credential harvesting. The proxy now serves
+  `save_attachment_file(issue, path, title?)` itself: it reads the file and uploads it with
+  the key it already holds, so nothing about the credential reaches the model and the bytes
+  never pass through its context. Readable paths are confined to a root — `RETASC_ATTACH_ROOT`
+  if set, otherwise the proxy's working directory — compared after resolving symlinks on both
+  sides, with `.git` and non-regular files refused, because reading a file on the agent's
+  behalf skips the harness's own file-access prompt. Every accepted read is logged to stderr
+  with its resolved path. Calls that pass `contentBase64` instead are forwarded to the server
+  untouched.
+
 ## 1.22.0 (2026-08-12)
 
 - **RTSC-646** — the watchdog now says when it is **not** renewing a lease. Its lease set is

package/dist/lib/attachFile.js

@@ -0,0 +1,207 @@
+// Local file attachment for the MCP proxy (RTSC-660) — path resolution + the tool it advertises.
+//
+// Why this exists: every other Retasc write is ONE MCP tool call, because the credential
+// lives in the server and the model only names a tool. File upload was the exception.
+// `prepare_attachment_upload` handed back a URL and told the caller to Bearer it with "your
+// API key", which under MCP the model structurally does not have. What that produced in the
+// field (the customer report behind RTSC-660): the agent shelled out to read
+// `~/.retasc/bindings.json`, and its harness blocked that twice as credential harvesting.
+// Our happy path required the agent to do something indistinguishable from an attack.
+//
+// The proxy is the one component that can close this without moving the credential: it
+// already holds the key and already sees every JSON-RPC message. So the agent names a PATH,
+// the proxy reads the bytes and POSTs them. The key never approaches the model and the file
+// never passes through its context (a 300KB screenshot as base64 in a tool argument is ~100k
+// output tokens, which is why the bytes-over-HTTP design exists in the first place).
+//
+// The cost of that convenience is the reason this module is mostly rules: a proxy-side read
+// bypasses the harness's OWN file-access prompt. Whatever this module agrees to open, a model
+// can attach with nobody approving it, so a prompt-injected agent told to "attach the config"
+// would otherwise be a clean exfiltration primitive. The confinement below IS the security
+// boundary, not hygiene — keep it strict, and keep it here where it is unit-tested, rather
+// than inline in the proxy's I/O path.
+import { realpathSync, statSync } from "node:fs";
+import { basename, resolve, sep } from "node:path";
+/** The one tool name for "attach a file", whichever transport can carry the bytes. The
+ *  server publishes a base64 variant under this SAME name for clients with no proxy; when a
+ *  proxy is present it overrides the entry in `tools/list` with the path form below. One
+ *  name, the best shape the environment can actually support — the model never has to know
+ *  which it got, it just reads the schema it was handed. */
+export const ATTACH_TOOL_NAME = "save_attachment_file";
+/** Matches the server's `MAX_ENCRYPTED_BLOB_BYTES`. Checked locally too so an oversized file
+ *  fails before we spend the upload, and with a message that names the size. */
+export const MAX_ATTACH_BYTES = 50 * 1024 * 1024;
+/** Env var that widens the root a path may live under. Set it deliberately (a worktree
+ *  layout, a screenshots dir); unset, the root is the proxy's cwd. */
+export const ATTACH_ROOT_ENV = "RETASC_ATTACH_ROOT";
+/**
+ * The directory a file must live under to be attachable. `RETASC_ATTACH_ROOT` if set (a
+ * human's deliberate choice — the fleet case is real: agents work in sibling worktrees, so
+ * the proxy's cwd is often the main checkout while the file is next door), else the proxy's
+ * cwd. Resolved through `realpathSync` so the containment check below compares like with
+ * like on macOS, where `/tmp` is a symlink to `/private/tmp` and a naive prefix test on the
+ * unresolved root rejects every legitimate path under it.
+ */
+export function attachRoot(env, cwd) {
+    const configured = (env[ATTACH_ROOT_ENV] ?? "").trim();
+    const raw = configured || cwd;
+    try {
+        return realpathSync(raw);
+    }
+    catch {
+        return resolve(raw); // non-existent root: nothing will resolve inside it anyway
+    }
+}
+/**
+ * Resolve a caller-supplied path against `root` and decide whether we are willing to read it.
+ *
+ * Refusals, and what each one is actually for:
+ *  - outside `root` — the containment rule. Compared AFTER `realpathSync` on both sides, so a
+ *    symlink inside the root pointing at `~/.ssh/id_rsa` is caught: resolving only the
+ *    requested path (or neither) is the classic way this check is defeated.
+ *  - anything under a `.git` directory — inside the root by construction, and `.git/config`
+ *    routinely holds credentials in remote URLs. No legitimate attachment lives there.
+ *  - not a regular file — a directory, fifo or device isn't an attachment, and reading a fifo
+ *    would hang the proxy's stdio loop rather than fail.
+ *  - empty / oversized — the server rejects both; failing here costs one round trip less and
+ *    can say how big the file actually was.
+ *
+ * A `~` is deliberately NOT expanded: the home directory is precisely what the root confines
+ * away from, so silently reaching it would undo the boundary.
+ */
+export function resolveAttachPath(input, root) {
+    const requested = typeof input === "string" ? input.trim() : "";
+    if (!requested)
+        return { ok: false, error: "path is required" };
+    if (requested.startsWith("~")) {
+        return {
+            ok: false,
+            error: `path "${requested}" starts with ~, which is not expanded. Attachable files must live ` +
+                `under ${root}; give a path inside it (relative paths resolve against it).`,
+        };
+    }
+    const candidate = resolve(root, requested);
+    let real;
+    try {
+        real = realpathSync(candidate);
+    }
+    catch {
+        return { ok: false, error: `no such file: ${candidate}` };
+    }
+    // `root + sep` would be "//" for a root of "/", which nothing starts with — so a root of
+    // "/" would refuse everything instead of allowing everything. Fail-closed is the right
+    // direction, but silently, and only for that one root; normalize instead.
+    const prefix = root.endsWith(sep) ? root : root + sep;
+    if (real !== root && !real.startsWith(prefix)) {
+        return {
+            ok: false,
+            error: `refusing to read ${real}: it resolves outside ${root}. Only files under that root can ` +
+                `be attached (set ${ATTACH_ROOT_ENV} to widen it deliberately).`,
+        };
+    }
+    if (real.split(sep).includes(".git")) {
+        return { ok: false, error: `refusing to read ${real}: paths inside a .git directory are not attachable.` };
+    }
+    let size;
+    try {
+        const st = statSync(real);
+        if (!st.isFile())
+            return { ok: false, error: `not a regular file: ${real}` };
+        size = st.size;
+    }
+    catch {
+        return { ok: false, error: `cannot stat ${real}` };
+    }
+    if (size === 0)
+        return { ok: false, error: `refusing to attach an empty file: ${real}` };
+    if (size > MAX_ATTACH_BYTES) {
+        return {
+            ok: false,
+            error: `file is ${size} bytes, over the ${MAX_ATTACH_BYTES}-byte attachment limit: ${real}`,
+        };
+    }
+    // The display name comes from what the caller ASKED for, not from the resolved target: a
+    // symlink's own name is the one the human recognizes, and it only ever becomes a label.
+    return { ok: true, path: real, filename: basename(candidate), size };
+}
+/** The tool the proxy advertises in place of (or in addition to) the server's base64 variant.
+ *  It names the root in the description because the model has no other way to learn where it
+ *  may read from, and a refusal it could have avoided costs a whole turn. */
+export function localAttachToolDef(root) {
+    return {
+        name: ATTACH_TOOL_NAME,
+        description: "Attach a FILE on this machine to an issue, in ONE call. Give the path; your local retasc " +
+            "proxy reads the bytes and uploads them with the credential it already holds. You do NOT " +
+            "need an API key for this and must not go looking for one — the whole point is that the " +
+            `key stays in the proxy. Readable paths are confined to ${root} (relative paths resolve ` +
+            "against it, symlinks out of it are refused, as is anything under .git). For a plain URL " +
+            "rather than a file, use save_attachment instead.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                issue: { type: "string", description: "Issue ID, e.g. RTSC-12" },
+                path: { type: "string", description: `File path, absolute or relative to ${root}.` },
+                title: { type: "string", description: "Optional label; also the download name." },
+            },
+            required: ["issue", "path"],
+        },
+    };
+}
+/**
+ * Put the local tool into a `tools/list` result: replace the server's entry of the same name
+ * (so the agent sees the shape this environment can actually serve, not the base64 fallback)
+ * or append it when the server has none. Appending matters — the proxy only needs
+ * `prepare_attachment_upload` to do its job, so it can offer one-call attachment against a
+ * server deployed before the base64 variant existed.
+ */
+export function mergeAttachTool(tools, root) {
+    if (!Array.isArray(tools))
+        return tools;
+    const local = localAttachToolDef(root);
+    const idx = tools.findIndex((t) => t && typeof t === "object" && t.name === ATTACH_TOOL_NAME);
+    if (idx === -1)
+        return [...tools, local];
+    const merged = [...tools];
+    merged[idx] = local;
+    return merged;
+}
+/** Does this JSON-RPC message want a LOCAL file upload? Only a `path` argument does: an agent
+ *  that sends `contentBase64` is using the server's variant and must be forwarded untouched,
+ *  so an older or hand-written client keeps working through a newer proxy. */
+export function isLocalAttachCall(msg) {
+    const m = msg;
+    if (!m || m.method !== "tools/call" || m.params?.name !== ATTACH_TOOL_NAME)
+        return false;
+    const args = m.params?.arguments;
+    return typeof args?.path === "string" && args.path.trim() !== "";
+}
+/** Build the upload URL: the server hands back a per-issue endpoint, we add the download-name
+ *  hints. `filename` drives the stored name and the server's content-type inference; `title`
+ *  is the human label. Both are query params because the endpoint takes the raw bytes as its
+ *  entire body. */
+export function uploadUrlWith(uploadUrl, filename, title) {
+    const sepChar = uploadUrl.includes("?") ? "&" : "?";
+    const parts = [`filename=${encodeURIComponent(filename)}`];
+    if (title && title.trim())
+        parts.push(`title=${encodeURIComponent(title.trim())}`);
+    return `${uploadUrl}${sepChar}${parts.join("&")}`;
+}
+/** Turn an upload HTTP failure into something the agent can act on. The endpoint answers in
+ *  plain text, so the status is what carries the meaning; a bare "HTTP 402" tells an agent
+ *  nothing it can relay to the human who alone can fix it. */
+export function uploadFailureMessage(status, body) {
+    const detail = body.trim() ? ` — ${body.trim()}` : "";
+    switch (status) {
+        case 401:
+            return `upload rejected: this proxy's key no longer authenticates${detail}`;
+        case 402:
+            return (`upload refused for billing${detail}. PASS THIS TO YOUR HUMAN — you cannot fix it ` +
+                `yourself, only an owner can, and until they do every write will keep failing.`);
+        case 404:
+            return `upload rejected: no such issue in this project${detail}`;
+        case 413:
+            return `upload rejected: file too large${detail}`;
+        default:
+            return `upload failed with HTTP ${status}${detail}`;
+    }
+}

package/dist/proxy.js

@@ -6,6 +6,7 @@
 // reclaims the lease (the correct default) — a broken watchdog is never worse than
 // no watchdog. Self-enforcing: no proxy → no Retasc tools → can't orphan a lease.
 import { createInterface } from "node:readline";
+import { readFile } from "node:fs/promises";
 import { hostname } from "node:os";
 import { spawn, spawnSync } from "node:child_process";
 import { dirname, resolve } from "node:path";
@@ -14,6 +15,7 @@ import { applyObservation, heartbeatRequest, isClaimLost, isUnauthorized, should
 import { resolveConn } from "./lib/keystore.js";
 import { toolResult as parseTool } from "./lib/toolresult.js";
 import { mintSessionKey, appendFallbackNotice } from "./lib/session.js";
+import { attachRoot, isLocalAttachCall, mergeAttachTool, resolveAttachPath, uploadFailureMessage, uploadUrlWith, } from "./lib/attachFile.js";
 // RTSC-92/98: resolve the workspace key via the SHARED resolver, so the proxy and
 // the direct commands (claim/tidy/done) can never diverge. The proxy carries its
 // binding in its own env (RETASC_MCP_KEY legacy, or RETASC_WORKSPACE → keystore).
@@ -33,6 +35,9 @@ let activeKey = KEY;
 // Set when session-key minting failed and we fell back to the workspace key —
 // whoami responses get a warning block appended so the agent sees the degraded state.
 let sessionKeyFallback = false;
+// RTSC-660: the directory a `save_attachment_file` path must live under. Resolved ONCE at
+// startup, not per call, so the boundary can't be moved mid-session by anything the model says.
+const ATTACH_ROOT = attachRoot(process.env, process.cwd());
 // stderr only: stdout is the MCP channel and must carry ONLY protocol messages.
 function log(msg) {
     process.stderr.write(`[retasc-watchdog] ${msg}\n`);
@@ -179,6 +184,82 @@ async function announceBinding() {
 function toolResult(resp, tool) {
     return parseTool(resp, (msg) => log(tool ? `${tool}: ${msg}` : msg));
 }
+/** Write one JSON-RPC tool result back to the harness (the local half of a tools/call). */
+function replyToolResult(id, text, isError) {
+    process.stdout.write(JSON.stringify({
+        jsonrpc: "2.0",
+        id,
+        result: { content: [{ type: "text", text }], ...(isError ? { isError: true } : {}) },
+    }) + "\n");
+}
+/**
+ * Serve `save_attachment_file` LOCALLY (RTSC-660): the agent names a path, we read the bytes
+ * and POST them with the key we already hold. This is the whole fix — it turns the one write
+ * an agent could not complete on its own into a single tool call, and removes the step where
+ * a well-behaved agent had to go reading a credential file off disk.
+ *
+ * The upload URL is fetched from the server rather than composed here, so the issue check,
+ * the project boundary and the endpoint's shape all stay server-authoritative and this side
+ * holds no policy it could get wrong. The path is validated first, before we spend a round
+ * trip on a file we would refuse to read anyway.
+ *
+ * Every accepted read is logged to stderr with its resolved path: a proxy-side read bypasses
+ * the harness's own file-access prompt, so the MCP log is where a human can see what was
+ * actually opened on their behalf.
+ */
+async function handleLocalAttach(msg) {
+    const args = (msg.params?.arguments ?? {});
+    const issue = typeof args.issue === "string" ? args.issue.trim() : "";
+    if (!issue)
+        return replyToolResult(msg.id, "issue is required (e.g. RTSC-12)", true);
+    const resolved = resolveAttachPath(String(args.path ?? ""), ATTACH_ROOT);
+    if (!resolved.ok) {
+        log(`refused attachment for ${issue}: ${resolved.error}`);
+        return replyToolResult(msg.id, resolved.error, true);
+    }
+    // Ask the server where this issue's bytes go. Doubles as the auth + issue-exists check, so
+    // a bad id or a foreign project fails before we open anything.
+    let prepared;
+    try {
+        prepared = toolResult(await postRemote({
+            jsonrpc: "2.0",
+            id: hbSeq--,
+            method: "tools/call",
+            params: { name: "prepare_attachment_upload", arguments: { issue } },
+        }), "prepare_attachment_upload");
+    }
+    catch (e) {
+        return replyToolResult(msg.id, `could not reach Retasc: ${String(e?.message ?? e)}`, true);
+    }
+    const uploadUrl = typeof prepared?.uploadUrl === "string" ? prepared.uploadUrl : "";
+    if (!uploadUrl) {
+        // Relay what the server said rather than a generic failure: it is usually NOT_FOUND for
+        // this issue, and that is the sentence the agent needs to see.
+        const detail = typeof prepared === "string" ? prepared : JSON.stringify(prepared ?? null);
+        return replyToolResult(msg.id, `could not prepare an upload for ${issue}: ${detail}`, true);
+    }
+    const title = typeof args.title === "string" ? args.title : undefined;
+    log(`attaching ${resolved.path} (${resolved.size} bytes) to ${issue}`);
+    try {
+        const res = await fetch(uploadUrlWith(uploadUrl, resolved.filename, title), {
+            method: "POST",
+            // No Content-Type on purpose: the server infers it from `filename`, and that inference
+            // is better than anything guessed here — declaring octet-stream would REPLACE it and
+            // cost the attachment its inline preview.
+            headers: { Authorization: `Bearer ${activeKey}` },
+            body: await readFile(resolved.path),
+        });
+        const body = await res.text();
+        if (!res.ok) {
+            log(`upload of ${resolved.filename} to ${issue} failed: HTTP ${res.status}`);
+            return replyToolResult(msg.id, uploadFailureMessage(res.status, body), true);
+        }
+        return replyToolResult(msg.id, body, false);
+    }
+    catch (e) {
+        return replyToolResult(msg.id, `upload failed: ${String(e?.message ?? e)}`, true);
+    }
+}
 async function handleLine(line) {
     const trimmed = line.trim();
     if (!trimmed)
@@ -190,6 +271,11 @@ async function handleLine(line) {
     catch {
         return; // not a JSON-RPC message — ignore
     }
+    // RTSC-660: a file attachment by PATH is served here, not forwarded — the bytes are on
+    // THIS machine and the credential is in this process. Anything else (including the same
+    // tool called with `contentBase64`, the server's own variant) goes remote untouched.
+    if (isLocalAttachCall(msg))
+        return await handleLocalAttach(msg);
     let resp;
     try {
         resp = await postRemote(msg);
@@ -205,6 +291,14 @@ async function handleLine(line) {
         }
         return;
     }
+    // RTSC-660: advertise the PATH form of save_attachment_file in place of the server's
+    // base64 one. A tool list is fetched once at startup, so this is the only moment we get to
+    // tell the agent which shape this environment can actually serve.
+    if (msg.method === "tools/list" && resp && typeof resp === "object") {
+        const result = resp.result;
+        if (result && Array.isArray(result.tools))
+            result.tools = mergeAttachTool(result.tools, ATTACH_ROOT);
+    }
     // Watch tools/call traffic for claims/releases (request args + result), and
     // flag the workspace-key fallback on whoami so the AGENT sees the degraded
     // state (RTSC-143) — the startup stderr warning only reaches the MCP logs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retasc/cli",
-  "version": "1.22.0",
+  "version": "1.23.0",
   "description": "Retasc CLI — the issue tracker AI agents pull work from. Sign in with GitHub or Google, create projects, mint agent API keys, and wire your agent to the Retasc MCP server in one command.",
   "type": "module",
   "bin": {