@safekb/mcp 0.12.1 → 0.13.0

package/README.md

@@ -377,15 +377,15 @@ custom fields and the key name of every custom field (sealed ones too) stay read
   sealed credentials start with the tenant default (Settings → Sealed credentials; `use_only` until
   set). Only you make anything more visible, in the SafeKB app; `set_sealed_credential_llm_visibility`
   only tightens. The client enforces this: a client older than 0.11.0 reveals every sealed credential, and 0.11.0 ignores field overrides.
-- Using a secret without showing it (0.12.0): `secret_exec` runs a program with it in env or stdin
-  (never argv), `secret_http` sends one request with it in the url, headers or body (redirects are not
-  followed), and `secret_adb_input` types it on an Android device (`adb shell input text`, value on stdin;
-  printable ASCII only). The agent names it by handle, `{{secret://<credential_id>/<field>}}`; a `totp`
-  handle becomes the current code. `|form`, `|json` or `|url` encodes the value for where it goes
-  (`{{secret://<id>/password|form}}` in a form body); without one it goes in as is, URL-encoded in a url.
-  `visible` and `use_only` fields can be used; `human_only` fields never.
-  Output comes back scrubbed of the value, in any mix of percent-, form-, JSON- and adb-encoding and as
-  base64 or hex, with the credentials and fields used. Scrubbing stops careless leaks, not a program written to leak one.
+- Using a secret without showing it: SafeKB only provides the value. `secret_exec` runs your own
+  program with it in env, stdin or a temp file (`files`, mode 0600, deleted afterwards), never argv;
+  every integration (HTTP API, browser form, `adb shell input text`, ssh, wallet, `cryptsetup`, …) is
+  that program. The agent names a secret by handle, `{{secret://<credential_id>/<field>}}`; a `totp`
+  handle becomes the current code, and `|form`, `|json` or `|url` encodes the value for where the
+  program puts it unchanged. `visible` and `use_only` fields can be used; `human_only` fields never.
+  Output comes back scrubbed of the value, in any mix of percent-, form- and JSON-encoding and as
+  base64 or hex, with the credentials and fields used. Scrubbing stops careless leaks, not a program
+  written to leak one.
 - Visible fields can be edited without the secret. Such an edit is flagged (`visible_tampered`) with the
   changed fields until a signed save accepts it (`accept_visible_changes`).
 

package/dist/safekb-mcp.js

@@ -2581,7 +2581,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 // package.json
 var package_default = {
   name: "@safekb/mcp",
-  version: "0.12.1",
+  version: "0.13.0",
   description: "SafeKB local MCP client: proxies the hosted SafeKB tools and adds zero-knowledge sealed documents.",
   license: "SEE LICENSE IN LICENSE",
   author: "Mustafa Öztürk",
@@ -8971,7 +8971,7 @@ class CredentialAccess {
     return this.decrypt(await this.ctx.api.fetchSealedCredential(credentialId));
   }
   async openForReveal(credentialId, field) {
-    return this.openAllowing(credentialId, field, REVEALABLE, (visibility) => visibility === "use_only" ? "it is never shown to an LLM. Use it without seeing it: secret_exec, secret_http or secret_adb_input with the handle secret://<credential_id>/<field>." : "it is never shown to an LLM and never handed to a tool: ask the user to enter it.");
+    return this.openAllowing(credentialId, field, REVEALABLE, (visibility) => visibility === "use_only" ? "it is never shown to an LLM. Use it without seeing it: secret_exec hands it to your own program with the handle {{secret://<credential_id>/<field>}}." : "it is never shown to an LLM and never handed to a tool: ask the user to enter it.");
   }
   async openForUse(credentialId, field) {
     return this.openAllowing(credentialId, field, USABLE, () => "no tool may use it: ask the user to enter it.");
@@ -9105,14 +9105,6 @@ function hasHandle(text) {
 function fillHandles(text, lookup, fallback = "raw") {
   return text.replace(HANDLE, (_, credentialId, field, encoding2) => ENCODINGS[encodingOf(encoding2, fallback)](lookup({ credentialId, field })));
 }
-function requireHandlesAfterOrigin(url) {
-  const first = url.search(ANY_HANDLE);
-  if (first === -1)
-    return;
-  if (!/^https?:\/\/[^/?#{}]+[/?#]/.test(url.slice(0, first))) {
-    throw new ClientError("A secret handle can go in the path, query or fragment of a url, never in its scheme, host or port.");
-  }
-}
 
 // src/sinks/secretResolver.ts
 var TOTP_FIELD = "totp";
@@ -35921,6 +35913,11 @@ function keyTools(parts) {
   ];
 }
 
+// src/sinks/execSink.ts
+import { mkdtemp, rm as rm4, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join as join9 } from "node:path";
+
 // src/sinks/processRunner.ts
 import { spawn as spawn3 } from "node:child_process";
 var MAX_CAPTURE_BYTES = 1024 * 1024;
@@ -36005,74 +36002,9 @@ async function runProcess(request) {
   });
 }
 
-// src/sinks/adbSink.ts
-var ADB_TIMEOUT_MS = 15000;
-var PRINTABLE_ASCII = /^[\x20-\x7e]*$/;
-var FOCUSED_PACKAGE = /mCurrentFocus=Window\{\S+ \S+ ([^/\s}]+)/;
-function adbInputCommand(value) {
-  if (!PRINTABLE_ASCII.test(value)) {
-    throw new ClientError("adb input text types printable ASCII only; this value has other characters. The user has to enter it.");
-  }
-  if (value.includes("%s")) {
-    throw new ClientError("adb input text reads %s as a space, so this value cannot be typed exactly. The user has to enter it.");
-  }
-  const quoted = value.replaceAll(" ", "%s").replaceAll("'", `'\\''`);
-  return `input text '${quoted}'
-`;
-}
-
-class AdbSink {
-  resolver;
-  adb;
-  constructor(resolver, adb = "adb") {
-    this.resolver = resolver;
-    this.adb = adb;
-  }
-  async input(args) {
-    if (refsIn(args.text).length === 0) {
-      throw new ClientError("text needs a secret handle: {{secret://<credential_id>/<field>}}");
-    }
-    const target = args.serial === undefined ? [] : ["-s", args.serial];
-    const secrets = await this.resolver.resolve([args.text]);
-    const value = secrets.fill(args.text);
-    const command = adbInputCommand(value);
-    await this.requireFocus(target, args.expect_package);
-    await this.shell(target, command, secrets);
-    return {
-      entered_length: value.length,
-      package: args.expect_package,
-      used: secrets.used()
-    };
-  }
-  async requireFocus(target, expected) {
-    const outcome = await runProcess({
-      argv: [this.adb, ...target, "shell", "dumpsys", "window"],
-      timeoutMs: ADB_TIMEOUT_MS
-    });
-    if (outcome.exitCode !== 0) {
-      throw new ClientError(`adb could not read the focused window: ${outcome.stderr.trim()}`);
-    }
-    const focused = FOCUSED_PACKAGE.exec(outcome.stdout)?.[1];
-    if (focused === undefined) {
-      throw new ClientError("No focused app found on the device (is it locked?); nothing was typed.");
-    }
-    if (focused !== expected) {
-      throw new ClientError(`The focused app is ${focused}, not ${expected}; nothing was typed.`);
-    }
-  }
-  async shell(target, command, secrets) {
-    const outcome = await runProcess({
-      argv: [this.adb, ...target, "shell", "-T"],
-      stdin: command,
-      timeoutMs: ADB_TIMEOUT_MS
-    });
-    if (outcome.exitCode !== 0 || outcome.timedOut) {
-      throw new ClientError(`adb input text failed (exit ${outcome.exitCode}${outcome.timedOut ? ", timed out" : ""}): ${secrets.redact(`${outcome.stderr}${outcome.stdout}`).trim()}`);
-    }
-  }
-}
-
 // src/sinks/execSink.ts
+var filled = (texts, secrets) => Object.fromEntries(Object.entries(texts).map(([name, text2]) => [name, secrets.fill(text2)]));
+
 class ExecSink {
   resolver;
   constructor(resolver) {
@@ -36080,108 +36012,49 @@ class ExecSink {
   }
   async run(args) {
     if (args.argv.some(hasHandle)) {
-      throw new ClientError("A secret handle cannot go in argv, which other processes can read: pass it in env or stdin.");
+      throw new ClientError("A secret handle cannot go in argv, which other processes can read: pass it in env, stdin or files.");
     }
     const env = args.env ?? {};
+    const files = args.files ?? {};
+    const clash = Object.keys(files).find((name) => Object.hasOwn(env, name));
+    if (clash !== undefined) {
+      throw new ClientError(`${clash} is named in both env and files`);
+    }
     const secrets = await this.resolver.resolve([
       ...Object.values(env),
+      ...Object.values(files),
       args.stdin ?? ""
     ]);
     if (secrets.used().length === 0) {
-      throw new ClientError("secret_exec needs a secret handle in env or stdin; run other programs without it.");
-    }
-    const outcome = await runProcess({
-      argv: args.argv,
-      cwd: args.cwd,
-      env: Object.fromEntries(Object.entries(env).map(([name, value]) => [name, secrets.fill(value)])),
-      stdin: args.stdin === undefined ? undefined : secrets.fill(args.stdin),
-      timeoutMs: args.timeout_s * 1000
-    });
-    const stdout = secrets.shown(outcome.stdout, outcome.stdoutCut);
-    const stderr = secrets.shown(outcome.stderr, outcome.stderrCut);
-    return {
-      exit_code: outcome.exitCode,
-      signal: outcome.signal,
-      timed_out: outcome.timedOut,
-      stdout: stdout.text,
-      stderr: stderr.text,
-      output_truncated: stdout.truncated || stderr.truncated,
-      used: secrets.used()
-    };
-  }
-}
-
-// src/sinks/httpSink.ts
-var MAX_READ_BYTES = 1024 * 1024;
-async function cappedText(response) {
-  const reader = response.body?.getReader();
-  if (reader === undefined)
-    return { text: "", cut: false };
-  const chunks = [];
-  let size = 0;
-  while (size < MAX_READ_BYTES) {
-    const { done, value } = await reader.read();
-    if (done) {
-      return { text: Buffer.concat(chunks).toString("utf8"), cut: false };
+      throw new ClientError("secret_exec needs a secret handle in env, stdin or files; run other programs without it.");
     }
-    chunks.push(value);
-    size += value.length;
-  }
-  await reader.cancel();
-  return {
-    text: Buffer.concat(chunks).subarray(0, MAX_READ_BYTES).toString("utf8"),
-    cut: true
-  };
-}
-function causeOf(error48) {
-  if (!(error48 instanceof Error))
-    return String(error48);
-  const cause = error48.cause instanceof Error ? `: ${error48.cause.message}` : "";
-  return `${error48.message}${cause}`;
-}
-
-class HttpSink {
-  resolver;
-  constructor(resolver) {
-    this.resolver = resolver;
-  }
-  async send(args) {
-    requireHandlesAfterOrigin(args.url);
-    const headers = args.headers ?? {};
-    const secrets = await this.resolver.resolve([
-      args.url,
-      ...Object.keys(headers),
-      ...Object.values(headers),
-      args.body ?? ""
-    ]);
-    const { response, text: text2, cut } = await this.exchange(args, headers, secrets);
-    const body = secrets.shown(text2, cut);
-    return {
-      status: response.status,
-      headers: Object.fromEntries([...response.headers].map(([name, value]) => [
-        name,
-        secrets.redact(value)
-      ])),
-      body: body.text,
-      body_truncated: body.truncated,
-      used: secrets.used()
-    };
-  }
-  async exchange(args, headers, secrets) {
+    const dir = await mkdtemp(join9(tmpdir(), "safekb-secret-"));
     try {
-      const response = await fetch(secrets.fill(args.url, "url"), {
-        method: args.method,
-        headers: Object.fromEntries(Object.entries(headers).map(([name, value]) => [
-          secrets.fill(name),
-          secrets.fill(value)
-        ])),
-        body: args.body === undefined ? undefined : secrets.fill(args.body),
-        redirect: "manual",
-        signal: AbortSignal.timeout(args.timeout_s * 1000)
+      const paths = {};
+      for (const [name, content] of Object.entries(filled(files, secrets))) {
+        paths[name] = join9(dir, name);
+        await writeFile(paths[name], content, { mode: 384, flag: "wx" });
+      }
+      const outcome = await runProcess({
+        argv: args.argv,
+        cwd: args.cwd,
+        env: { ...filled(env, secrets), ...paths },
+        stdin: args.stdin === undefined ? undefined : secrets.fill(args.stdin),
+        timeoutMs: args.timeout_s * 1000
       });
-      return { response, ...await cappedText(response) };
-    } catch (error48) {
-      throw new ClientError(`The request failed: ${secrets.redact(causeOf(error48))}`);
+      const stdout = secrets.shown(outcome.stdout, outcome.stdoutCut);
+      const stderr = secrets.shown(outcome.stderr, outcome.stderrCut);
+      return {
+        exit_code: outcome.exitCode,
+        signal: outcome.signal,
+        timed_out: outcome.timedOut,
+        stdout: stdout.text,
+        stderr: stderr.text,
+        output_truncated: stdout.truncated || stderr.truncated,
+        used: secrets.used()
+      };
+    } finally {
+      await rm4(dir, { recursive: true, force: true });
     }
   }
 }
@@ -36381,30 +36254,32 @@ function documentTools(creator, documents, search, names) {
 }
 
 // src/tools/sinkTools.ts
-var HANDLE_NOTE = "Name a secret by its handle {{secret://<credential_id>/<field>}} (field: password, totp, sealed_notes or custom:{key}); it is decrypted on this machine and the value never enters the conversation. A totp handle becomes the current code. Add |form, |json or |url to encode the value for where it goes, e.g. {{secret://<id>/password|form}} in a form body; without it the value goes in as is (in a url: URL-encoded). Fields whose llm_visibility is human_only are refused.";
-var SCRUB_NOTE = "What comes back is scrubbed of the values (as is, URL-encoded, base64, hex, JSON-escaped) and names the secrets used. Scrubbing guards against careless output, not against a program written to leak: run only code you trust.";
-var timeout = (fallback) => exports_external.number().int().min(1).max(600).default(fallback).describe("Seconds.");
-function sinkTools(exec, http, adb) {
+var ENV_NAME = exports_external.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/);
+var DESCRIPTION = `Use a sealed secret without seeing it: run your own program with the secret in its environment, on its stdin or in a temp file. This is the only way to use a secret without revealing it. SafeKB only provides the value; every integration (HTTP API, browser form, Android typing, ssh, wallet, disk unlock, radio, ...) is your own program.
+
+Name a secret by its handle {{secret://<credential_id>/<field>}} (field: password, totp, sealed_notes or custom:{key}). It is decrypted on this machine and never enters the conversation. A totp handle becomes the current code. Add |url, |form or |json to encode the value for where your program puts it unchanged (e.g. a form body in stdin: "a={{secret://<id>/password|form}}"); without one it goes in as is. Fields whose llm_visibility is human_only are refused.
+
+Examples:
+- HTTP API key: env {"API_KEY": "{{secret://<id>/password}}"}, argv ["uv", "run", "call_api.py"]
+- Android typing: env {"PW": "{{secret://<id>/password}}"}, argv ["uv", "run", "adb_type.py", "--expect-package", "com.example.bank"] (your script runs adb shell input text)
+- Browser form: env {"PW": "{{secret://<id>/password}}"}, argv ["node", "fill.js"] (your script attaches to the open browser with patchright over CDP)
+- ssh with a key: files {"KEY_FILE": "{{secret://<id>/custom:private key}}"}, argv ["sh", "-c", "ssh -i \\"$KEY_FILE\\" host uptime"]
+- ssh with a password: env {"SSHPASS": "{{secret://<id>/password}}"}, argv ["sshpass", "-e", "ssh", "host", "uptime"]
+- LUKS: stdin "{{secret://<id>/password}}", argv ["sudo", "cryptsetup", "open", "--key-file=-", "/dev/sdb1", "vault"]
+- Wallet unlock, a LoRa radio write, anything else: your script reads the value from env, stdin or a file
+- One-time code: env {"OTP": "{{secret://<id>/totp}}"}
+
+Rules: never put a handle in argv (other processes can read it; it is refused). Your program must not print the value. What comes back is scrubbed of it (as is, in any mix of percent-, form- and JSON-encoding, as base64 or hex) and names the secrets used, but scrubbing is a guard against carelessness, not a guarantee: a program can still leak a value it transforms. The program inherits this client's environment and runs without a shell.`;
+function sinkTools(exec) {
   return [
-    defineTool("secret_exec", `Run a program with secrets in its environment or on its stdin, without seeing them. ${HANDLE_NOTE} At least one handle is needed; handles are refused in argv, which other processes can read. The program inherits this client's environment. No shell: argv is run as is. ${SCRUB_NOTE}`, {
+    defineTool("secret_exec", DESCRIPTION, {
       argv: exports_external.array(exports_external.string()).min(1).describe('Program and arguments, e.g. ["uv", "run", "script.py"].'),
       cwd: absolutePath("Working directory."),
-      env: exports_external.record(exports_external.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/), exports_external.string()).describe('Added to the environment; values may hold handles, e.g. {"API_KEY": "{{secret://<id>/password}}"}.').optional(),
+      env: exports_external.record(ENV_NAME, exports_external.string()).describe('Added to the environment; values may hold handles, e.g. {"API_KEY": "{{secret://<id>/password}}"}.').optional(),
       stdin: exports_external.string().describe("Written to stdin, then closed; may hold handles.").optional(),
-      timeout_s: timeout(60)
-    }, (args) => exec.run(args)),
-    defineTool("secret_http", `Send one HTTP request with secrets in its url, headers or body, without seeing them. ${HANDLE_NOTE} Handles go in the path, query or fragment of the url (URL-encoded for you), never its host. A redirect is returned, not followed. ${SCRUB_NOTE}`, {
-      method: exports_external.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"]),
-      url: exports_external.string().url().describe("May hold handles, e.g. in the query."),
-      headers: exports_external.record(exports_external.string(), exports_external.string()).describe('e.g. {"Authorization": "Bearer {{secret://<id>/password}}"}.').optional(),
-      body: exports_external.string().describe("May hold handles.").optional(),
-      timeout_s: timeout(30)
-    }, (args) => http.send(args)),
-    defineTool("secret_adb_input", `Type a secret into the focused field of an Android device with adb (input text), without seeing it. ${HANDLE_NOTE} Only printable ASCII can be typed; anything else is refused, never typed differently. Returns only the length typed.`, {
-      text: exports_external.string().min(1).describe("What to type, holding a handle: {{secret://<id>/password}}."),
-      serial: exports_external.string().min(1).describe("adb -s: which device, when several are connected.").optional(),
-      expect_package: exports_external.string().min(1).describe("Type only if this app has the focus, e.g. com.example.bank.")
-    }, (args) => adb.input(args))
+      files: exports_external.record(ENV_NAME, exports_external.string()).describe('Each value (holding handles) is written to a temp file only you can read and deleted when the program ends; the env variable of that name holds its path, e.g. {"KEY_FILE": "{{secret://<id>/custom:private key}}"}.').optional(),
+      timeout_s: exports_external.number().int().min(1).max(600).default(60).describe("Seconds.")
+    }, (args) => exec.run(args))
   ];
 }
 
@@ -36462,7 +36337,7 @@ A credential with \`sealed: true\` belongs to a seal root. Its title, username,
 
 - Reveal a secret only when the task needs it, and prefer get_sealed_totp over revealing a TOTP seed.
 - llm_visibility is set per credential, and llm_field_visibility overrides it for single sealed fields. reveal_sealed_credential and get_sealed_totp work only on a field that is visible. Only the user makes anything visible, in the SafeKB app.
-- To use a secret without seeing it (visible or use_only fields): secret_exec (a program gets it in env or stdin), secret_http (one request gets it in url, headers or body) or secret_adb_input (typed on an Android device). Name it by handle, {{secret://<credential_id>/<field>}}; a totp handle becomes the current code. Prefer these over revealing, even for a visible field. A human_only field is never used by a tool: ask the user to enter it.
+- To use a secret without seeing it (visible or use_only fields): secret_exec runs your own program with it in env, stdin or a temp file; every integration (HTTP, browser, adb, ssh, ...) is that program. Name it by handle, {{secret://<credential_id>/<field>}}; a totp handle becomes the current code. Prefer this over revealing, even for a visible field. A human_only field is never used by a tool: ask the user to enter it.
 - visible_tampered means the visible fields were changed without the key since the last sealed save. Do not trust the url or username of such a credential until the user has reviewed the change.`;
 function createSealedTools(ctx) {
   const services = createSealedServices(ctx);
@@ -36474,7 +36349,7 @@ function createSealedTools(ctx) {
     ...attachmentTools(services.attachments),
     ...depositTools(services.deposits, names),
     ...credentialTools(services.credentials, services.migration, names),
-    ...sinkTools(new ExecSink(services.secrets), new HttpSink(services.secrets), new AdbSink(services.secrets))
+    ...sinkTools(new ExecSink(services.secrets))
   ];
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@safekb/mcp",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "description": "SafeKB local MCP client: proxies the hosted SafeKB tools and adds zero-knowledge sealed documents.",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Mustafa Öztürk",