@safekb/mcp 0.12.1 → 0.14.0

package/README.md

@@ -377,15 +377,19 @@ 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.
+- Entering a secret without the agent seeing it: `insert_sealed_credential` and
+  `update_sealed_credential` take `typed_at_sidecar`, e.g. `["custom:number", "custom:cvc", "password"]`.
+  The call waits while you type each field at the sidecar (`safekb-mcp --sidecar`), hidden and twice;
+  the agent passes only the visible fields. Or enter it in the SafeKB web app.
+- 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.14.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";
@@ -9903,6 +9895,47 @@ class CredentialMigration {
   }
 }
 
+// src/sealed/typedFields.ts
+var NAMED = ["password", "totp", "sealed_notes"];
+var CUSTOM_PREFIX3 = customFieldName("");
+var NOTHING_TYPED = { named: {}, custom: [] };
+function checked(fields2, passed) {
+  if (new Set(fields2).size !== fields2.length) {
+    throw new ClientError("typed_at_sidecar names a field twice");
+  }
+  for (const field of fields2) {
+    if (NAMED.includes(field)) {
+      if (passed[field] !== undefined) {
+        throw new ClientError(`${field} is both passed and typed_at_sidecar: pass it one way only`);
+      }
+    } else if (field.startsWith(CUSTOM_PREFIX3) && field.length > CUSTOM_PREFIX3.length) {
+      const key = field.slice(CUSTOM_PREFIX3.length);
+      if (passed.custom?.some((item) => item.key === key)) {
+        throw new ClientError(`custom field '${key}' is both in custom and typed_at_sidecar: pass it one way only`);
+      }
+    } else {
+      throw new ClientError(`typed_at_sidecar: '${field}' is not a sealed field. Use password, totp, sealed_notes or custom:{key}.`);
+    }
+  }
+}
+async function typeAtSidecar(entry, credential2, fields2, passed) {
+  checked(fields2, passed);
+  const typed = { named: {}, custom: [] };
+  for (const field of fields2) {
+    const value = await entry.secret(credential2, field);
+    if (field.startsWith(CUSTOM_PREFIX3)) {
+      typed.custom.push({ key: field.slice(CUSTOM_PREFIX3.length), value });
+    } else {
+      typed.named[field] = value;
+    }
+  }
+  return typed;
+}
+function withTypedCustom(sealed, typed) {
+  const keys = new Set(typed.custom.map(({ key }) => key));
+  return [...sealed.filter(({ key }) => !keys.has(key)), ...typed.custom];
+}
+
 // src/sealed/credentialService.ts
 var NOT_FOUND2 = 404;
 var VISIBLE_NAMES = [
@@ -10014,6 +10047,7 @@ class CredentialService {
     const id = newObjectId();
     const custom = splitCustom(args.custom ?? []);
     const { dek, encDek } = await this.access.newDek(args.root_id, id);
+    const typed = await this.typed(args.title, args);
     const save = await this.access.seal(id, dek, {
       title: args.title,
       username: textOrNull(args.username, null),
@@ -10022,10 +10056,10 @@ class CredentialService {
       notes: textOrNull(args.notes, null),
       custom: custom.visible
     }, {
-      password: textOrNull(args.password, null),
-      totp: this.checkedTotp(textOrNull(args.totp, null)),
-      sealed_notes: textOrNull(args.sealed_notes, null),
-      custom: custom.sealed
+      password: typed.named.password ?? textOrNull(args.password, null),
+      totp: this.checkedTotp(typed.named.totp ?? textOrNull(args.totp, null)),
+      sealed_notes: typed.named.sealed_notes ?? textOrNull(args.sealed_notes, null),
+      custom: withTypedCustom(custom.sealed, typed)
     });
     const sigs = await this.access.sign({
       op: "credential_create",
@@ -10059,6 +10093,7 @@ class CredentialService {
       throw new ClientError(`${attestation.warning} ${describeChanges(attestation.changed_visible_fields, current)} ` + "Show this to the user. Only after they have reviewed it, repeat with accept_visible_changes: true (and pass the right values for any field to correct).");
     }
     const custom = args.custom === undefined ? { visible: current.custom, sealed: values.custom } : splitCustom(args.custom);
+    const typed = await this.typed(args.title ?? current.title, args);
     const save = await this.access.seal(credential2.id, dek, {
       title: args.title ?? current.title,
       username: textOrNull(args.username, current.username),
@@ -10067,10 +10102,10 @@ class CredentialService {
       notes: textOrNull(args.notes, current.notes),
       custom: custom.visible
     }, {
-      password: textOrNull(args.password, values.password),
-      totp: this.checkedTotp(textOrNull(args.totp, values.totp)),
-      sealed_notes: textOrNull(args.sealed_notes, values.sealed_notes),
-      custom: custom.sealed
+      password: typed.named.password ?? textOrNull(args.password, values.password),
+      totp: this.checkedTotp(typed.named.totp ?? textOrNull(args.totp, values.totp)),
+      sealed_notes: typed.named.sealed_notes ?? textOrNull(args.sealed_notes, values.sealed_notes),
+      custom: withTypedCustom(custom.sealed, typed)
     });
     const sigs = await this.access.sign({
       op: "credential_update",
@@ -10128,6 +10163,10 @@ class CredentialService {
     });
     return { id: credentialId, deleted: true };
   }
+  typed(title, args) {
+    const atSidecar = args.typed_at_sidecar;
+    return atSidecar === undefined || atSidecar.fields.length === 0 ? Promise.resolve(NOTHING_TYPED) : typeAtSidecar(atSidecar.entry, title, atSidecar.fields, args);
+  }
   checkedTotp(value) {
     if (value !== null)
       parseTotp(value);
@@ -31321,7 +31360,7 @@ function decodeDirective(html) {
 
 // ../shared/js/canvas-markdown/src/html.ts
 var ENTITY = /&(#x[0-9a-fA-F]+|#[0-9]+|amp|lt|gt|quot|apos);/g;
-var NAMED = {
+var NAMED2 = {
   amp: "&",
   lt: "<",
   gt: ">",
@@ -31337,7 +31376,7 @@ function unescapeHtmlText(text2) {
       return String.fromCodePoint(Number.parseInt(body.slice(2), 16));
     if (body.startsWith("#"))
       return String.fromCodePoint(Number(body.slice(1)));
-    return NAMED[body];
+    return NAMED2[body];
   });
 }
 
@@ -31668,12 +31707,12 @@ class BlockParser {
   }
   item(taskable) {
     this.pos++;
-    const checked = taskable ? this.takeTaskMarker() : null;
+    const checked2 = taskable ? this.takeTaskMarker() : null;
     const children = this.blocks((token) => token.type === "list_item_close");
     this.pos++;
     return {
-      task: checked !== null,
-      checked: checked === true,
+      task: checked2 !== null,
+      checked: checked2 === true,
       children: children.length > 0 ? children : [node("paragraph")]
     };
   }
@@ -34482,7 +34521,7 @@ import { connect } from "node:net";
 
 // src/sidecar/protocol.ts
 import { dirname as dirname4, join as join6 } from "node:path";
-var SIDECAR_PROTOCOL_VERSION = 2;
+var SIDECAR_PROTOCOL_VERSION = 3;
 var SIDECAR_SOCKET_NAME = "sidecar.sock";
 var SIDECAR_SUPPORTED = process.platform !== "win32";
 function defaultSidecarSocket(configPath) {
@@ -34627,6 +34666,10 @@ class SidecarQuestions {
     const { passphrase } = await this.asking("The passphrase", () => this.client.request({ op: "passphrase", of }));
     return passphrase;
   }
+  async secret(credential2, field2) {
+    const { value } = await this.asking(`The value of ${field2}`, () => this.client.request({ op: "secret", credential: credential2, field: field2 }));
+    return value;
+  }
   async ask(notice, question) {
     const { typed: typed2 } = await this.asking("The confirmation", () => this.client.request({ op: "confirm", notice, question }));
     return typed2;
@@ -34656,6 +34699,9 @@ class NoSidecarQuestions {
   ask() {
     return this.refuse();
   }
+  secret() {
+    return Promise.reject(new ClientError("Typing a secret at the sidecar is not available on this platform. Ask the user to enter it in the SafeKB web app (Credentials)."));
+  }
   refuse() {
     return Promise.reject(new ClientError(`This needs the user to type at the sidecar, which is not available on this platform. Ask them to run it at a terminal: ${this.commandLine}`));
   }
@@ -34729,6 +34775,15 @@ The MCP client asks for the passphrase of ${printable2(of)}. It is used for this
       return typed2.length === 0 ? null : typed2;
     });
   }
+  secret({ credential: credential2, field: field2 }, signal) {
+    return this.inTurn(async () => {
+      signal.throwIfAborted();
+      this.reader.write(`
+The MCP client asks for ${printable2(field2)} of credential "${printable2(credential2)}". It is sealed on this machine; the model never sees it.
+`);
+      return this.readTwice(`${printable2(field2)} (not shown; empty to decline): `, signal);
+    });
+  }
   typed(notice, question, signal) {
     return this.inTurn(async () => {
       signal.throwIfAborted();
@@ -34860,9 +34915,12 @@ ${printableLines(notice)}`);
 ` : `Forgotten.
 `);
   }
-  async readNewPassphrase(signal) {
+  readNewPassphrase(signal) {
+    return this.readTwice("New passphrase (not shown; empty to decline): ", signal);
+  }
+  async readTwice(prompt, signal) {
     for (;; ) {
-      const first = await this.reader.read("New passphrase (not shown; empty to decline): ", { hidden: true, signal });
+      const first = await this.reader.read(prompt, { hidden: true, signal });
       if (first.length === 0)
         return null;
       const second = await this.reader.read("Repeat it: ", {
@@ -35126,6 +35184,8 @@ class SidecarServer {
         return {};
       case "passphrase":
         return { passphrase: await this.passphrase(request, clientGone) };
+      case "secret":
+        return { value: await this.secret(request, clientGone) };
       case "confirm":
         return {
           typed: await this.prompter.typed(requireText(request.notice, "notice"), requireText(request.question, "question"), clientGone)
@@ -35152,6 +35212,16 @@ class SidecarServer {
     }
     return typed2;
   }
+  async secret(request, clientGone) {
+    const credential2 = requireText(request.credential, "credential");
+    const field2 = requireText(request.field, "field");
+    const typed2 = await this.prompter.secret({ credential: credential2, field: field2 }, clientGone);
+    clientGone.throwIfAborted();
+    if (typed2 === null) {
+      throw new ClientError(`The sidecar's user entered no ${field2} for credential "${credential2}"`);
+    }
+    return typed2;
+  }
   async create(rootId, label2, clientGone) {
     const chosen = await this.prompter.newSecret(rootId, label2, clientGone);
     clientGone.throwIfAborted();
@@ -35921,6 +35991,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 +36080,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 +36090,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 });
     }
   }
 }
@@ -36224,13 +36175,15 @@ var sealedFields = {
   password: exports_external.string().describe(`Sealed. ${CLEARABLE}`).optional(),
   totp: exports_external.string().describe(`Sealed TOTP seed (base32) or otpauth://totp URI. ${CLEARABLE}`).optional(),
   sealed_notes: exports_external.string().describe(`Sealed notes. ${CLEARABLE}`).optional(),
+  typed_at_sidecar: exports_external.array(exports_external.string().min(1)).describe(`Sealed fields the user types at the sidecar instead of you passing them: password, totp, sealed_notes or custom:{key} (a new or replaced sealed custom field). The call waits while they type each one, hidden and twice. ${SIDECAR_TYPING} Use this for any secret the user has not already given you, e.g. a card number, CVC or PIN; set the visible fields (title, holder name, last 4 digits) yourself.`).optional(),
   custom: exports_external.array(exports_external.strictObject({
     key: exports_external.string().min(1).describe("Field name. Always stored in clear, also for a sealed field: never put a secret in it."),
     value: exports_external.string(),
     sealed: exports_external.boolean().describe("true: the value is encrypted on this machine (the key name is not). false: visible to the server.")
   })).describe("The complete list of custom fields; it replaces the stored list.").optional()
 };
-function credentialTools(credentials, migration, names) {
+function credentialTools(credentials, migration, names, entry) {
+  const atSidecar = (fields2) => fields2 === undefined ? undefined : { fields: fields2, entry };
   return [
     defineTool("reveal_sealed_credential", `Decrypt one sealed field of a sealed credential on this machine. The server only sees that the ciphertext was fetched. Find credentials and their visible fields with the standard credential tools (search_credentials, get_credential). Refused unless its llm_visibility is visible. ${EXPOSURE_NOTE}`, {
       credential_id: credentialId,
@@ -36250,7 +36203,8 @@ function credentialTools(credentials, migration, names) {
       ...sealedFields
     }, async (args) => credentials.insert({
       ...args,
-      root_id: await names.resolve(args.root_id)
+      root_id: await names.resolve(args.root_id),
+      typed_at_sidecar: atSidecar(args.typed_at_sidecar)
     })),
     defineTool("update_sealed_credential", `Change a sealed credential with its seal root's signature. Pass only the fields to change; the save also attests the visible fields as they are now. If visible fields were changed without the key since the last sealed save, the call fails and names them until accept_visible_changes is true. ${SECRET_ARGUMENT_NOTE}`, {
       credential_id: credentialId,
@@ -36259,7 +36213,10 @@ function credentialTools(credentials, migration, names) {
       title: exports_external.string().min(1).describe("Visible to the server.").optional(),
       ...visibleFields,
       ...sealedFields
-    }, (args) => credentials.update(args)),
+    }, (args) => credentials.update({
+      ...args,
+      typed_at_sidecar: atSidecar(args.typed_at_sidecar)
+    })),
     defineTool("move_sealed_credential", "Move a sealed credential to another seal root of its space. Both roots must be openable here: its key is re-wrapped under the new root and both roots sign. Afterwards only the new root's secret opens it. Whoever held the old root's secret keeps what they already read.", {
       credential_id: credentialId,
       expected_version: expectedVersion,
@@ -36381,30 +36338,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))
   ];
 }
 
@@ -36460,11 +36419,12 @@ The keys of this machine, and backups, are handled by tools that never take or r
 
 A credential with \`sealed: true\` belongs to a seal root. Its title, username, url, tags, notes and visible custom fields are readable by the server: find it with the standard credential tools. Its password, TOTP seed, sealed_notes and sealed custom fields open only here: reveal_sealed_credential, get_sealed_totp, insert_sealed_credential, update_sealed_credential.
 
+- A secret the user has not given you yet (a card number, a PIN, a new password): never ask for it in the conversation. Call insert_sealed_credential or update_sealed_credential with typed_at_sidecar naming the fields; the user types them at the sidecar (safekb-mcp --sidecar) while the call waits. Or they enter it in the SafeKB web app.
 - 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) {
+function createSealedTools(ctx, entry) {
   const services = createSealedServices(ctx);
   const { names } = ctx;
   return [
@@ -36473,8 +36433,8 @@ function createSealedTools(ctx) {
     ...treeTools(services.tree, names),
     ...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))
+    ...credentialTools(services.credentials, services.migration, names, entry),
+    ...sinkTools(new ExecSink(services.secrets))
   ];
 }
 
@@ -36819,7 +36779,7 @@ async function openTools(options, config3, session, systemKeyring, chosen) {
   };
   const conversions = createConversions(sealed, new KbApi(http), sharedCanvasMarkdown);
   const localTools = [
-    ...createSealedTools(sealed),
+    ...createSealedTools(sealed, userQuestionsOf(options)("")),
     ...unsealTools(conversions.unseal),
     ...options.sealedOnly ? [] : sealTools(conversions.seal),
     ...await adminTools({ options, config: config3, systemKeyring, chosen })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@safekb/mcp",
-  "version": "0.12.1",
+  "version": "0.14.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",