@sandprivacy/sandgate 0.1.8 → 0.2.1

package/README.md

@@ -44,13 +44,18 @@ claude mcp add sandgate -e SANDGATE_PASSPHRASE=your-passphrase -- sandgate serve
 
 That's it. Your agent now has four new tools.
 
-## The four tools
+## The five tools
 
 - **`request_approval`** — "May I pay €300 on this site?" → push to your phone → approve/deny. No answer = denied.
+- **`ask_human`** — "What's the code you received by SMS?" → your phone shows an input field → your typed answer returns over the same encrypted channel. Covers SMS codes on your *real* number (no VoIP numbers that sites reject), security questions, choices.
 - **`get_totp`** — the current 6-digit code for a domain. Per-domain policy: `auto` (trusted sites), `approve` (buzz first — the default), or `deny`. The seed itself is never exposed.
 - **`create_identity`** — a disposable email inbox so the agent can sign up for services without your real address.
 - **`wait_for_verification`** — long-polls that inbox and returns the extracted verification code and links the moment they arrive.
 
+## Recipes
+
+**CAPTCHAs.** sandgate will never auto-solve a CAPTCHA — that's the point of a CAPTCHA. The pattern that works today, by composition: tell your agent that on hitting one it should call `request_approval("CAPTCHA on <site> — solve it at the computer, then approve to continue")`. Your phone buzzes, you solve it where the browser is, you tap approve, the agent resumes. Same behavior as OpenAI's Operator, plus the notification.
+
 ## Policies
 
 ```bash
@@ -85,7 +90,7 @@ How the trust works: the pairing secret travels once, inside the URL **fragment*
 
 ## Security notes, honestly
 
-- `SANDGATE_PASSPHRASE` in the MCP client config is a deliberate tradeoff: MCP clients launch servers non-interactively, so the passphrase lives in your agent's config file. It protects the vault *at rest* (a stolen `vault.enc` alone is useless); OS keychain integration is on the roadmap.
+- MCP clients launch servers non-interactively, so the vault passphrase must come from the environment. `SANDGATE_PASSPHRASE` (the value, cleartext in your config) protects the vault *at rest* — a stolen `vault.enc` alone is useless. For more, `SANDGATE_PASSPHRASE_CMD` runs a command whose stdout is the passphrase, so it can live in your OS secret store: Windows DPAPI (`ConvertFrom-SecureString` once, decrypt in the command), macOS `security find-generic-password`, Linux `secret-tool lookup`, or any password manager CLI. Either way, a fully compromised machine defeats any local secret store — that threat class is out of scope for all of them.
 - Approval taps are only accepted from your own Telegram chat; anything else — including silence — is a deny. Agent-supplied text in approval messages is escaped and truncated.
 - Email content handled by `wait_for_verification` is untrusted third-party input. The tool description tells agents so; only the extracted code and hint-filtered links are returned, never the raw body.
 - Several agents can wait on you at once: approvals are served by a single dispatcher, first tap wins per request.
@@ -94,9 +99,12 @@ How the trust works: the pairing secret travels once, inside the URL **fragment*
 
 - [x] Generic IMAP backend for verification emails (`sandgate connect-imap`)
 - [x] `sandgate audit` — pretty-print the audit trail
-- [x] Mobile PWA with end-to-end-encrypted push (`sandgate relay` + `sandgate pair`)
-- [ ] Team policies (shared vault, multiple approvers)
-- [ ] Framework guides: browser-use, LangGraph, Agno
+- [x] Mobile PWA with end-to-end-encrypted push (`sandgate relay` + `sandgate pair`), multi-vault, on-device history
+- [x] `ask_human` — free-text answers (SMS codes on your real number, security questions)
+- [ ] OS keychain for the vault passphrase
+- [ ] Slack approval channel with multiple approvers (teams)
+- [ ] Team policies (shared vault, centralized audit)
+- [x] Framework guides: [Claude Code](docs/integrations/claude-code.md), [browser-use](docs/integrations/browser-use.md), [Playwright MCP](docs/integrations/playwright-mcp.md), [LangGraph](docs/integrations/langgraph.md)
 
 ## License
 

package/dist/index.js

@@ -5,6 +5,7 @@ import { join } from "node:path";
 import { read } from "read";
 import { getQuota } from "./sandmail.js";
 import { testImapConnection } from "./inbox.js";
+import { resolvePassphrase } from "./passphrase.js";
 import { auditPath } from "./paths.js";
 import { vaultExists, loadVault, saveVault, } from "./vault.js";
 import { loadConfig, saveConfig } from "./config.js";
@@ -391,10 +392,19 @@ async function main() {
             return cmdAudit(args[0]);
         case undefined:
         case "serve": {
-            const pass = process.env.SANDGATE_PASSPHRASE;
+            let pass;
+            try {
+                pass = resolvePassphrase(process.env);
+            }
+            catch (err) {
+                console.error(`SANDGATE_PASSPHRASE_CMD failed: ${err instanceof Error ? err.message : err}`);
+                process.exit(1);
+            }
             if (!pass) {
-                console.error("SANDGATE_PASSPHRASE is not set. MCP clients launch sandgate non-interactively;\n" +
-                    'add it to the server config, e.g. {"env": {"SANDGATE_PASSPHRASE": "..."}}');
+                console.error("No vault passphrase. MCP clients launch sandgate non-interactively; provide either\n" +
+                    '  SANDGATE_PASSPHRASE      the value itself, or\n' +
+                    "  SANDGATE_PASSPHRASE_CMD  a command printing it (OS keychain, DPAPI, password manager CLI)\n" +
+                    "in the MCP server config env.");
                 process.exit(1);
             }
             return serve(pass);

package/dist/passphrase.js

@@ -0,0 +1,29 @@
+import { execSync } from "node:child_process";
+/**
+ * Resolve the vault passphrase for non-interactive runs (MCP clients
+ * launching `sandgate serve`). Two sources, in order:
+ *
+ *  - SANDGATE_PASSPHRASE: the value itself. Simple, but sits in cleartext
+ *    in whatever config launches the server.
+ *  - SANDGATE_PASSPHRASE_CMD: a command whose stdout is the passphrase —
+ *    the git-credential/restic pattern. Point it at the OS secret store:
+ *    DPAPI on Windows, `security find-generic-password` on macOS,
+ *    `secret-tool lookup` on Linux, or any password manager CLI.
+ *
+ * Either way the model never sees it: it lives in the launcher's
+ * environment, not in the agent's context.
+ */
+export function resolvePassphrase(env) {
+    if (env.SANDGATE_PASSPHRASE)
+        return env.SANDGATE_PASSPHRASE;
+    const command = env.SANDGATE_PASSPHRASE_CMD;
+    if (!command)
+        return undefined;
+    const output = execSync(command, {
+        encoding: "utf8",
+        windowsHide: true,
+        timeout: 15_000,
+    });
+    const pass = output.trim();
+    return pass.length > 0 ? pass : undefined;
+}

package/dist/pwa-approver.js

@@ -10,9 +10,10 @@ export class PwaApprover {
     url(path) {
         return this.config.relayUrl.replace(/\/$/, "") + path;
     }
-    async request(req) {
+    /** Post a sealed request and long-poll its sealed decision (or null on timeout). */
+    async roundTrip(kind, req) {
         const requestId = randomBytes(16).toString("base64url");
-        const sealed = seal(this.key, { title: req.title, body: req.body, timeoutSec: req.timeoutSec, ts: Date.now() }, aadForRequest(requestId));
+        const sealed = seal(this.key, { kind, title: req.title, body: req.body, timeoutSec: req.timeoutSec, ts: Date.now() }, aadForRequest(requestId));
         const post = await fetch(this.url("/api/request"), {
             method: "POST",
             headers: { "Content-Type": "application/json" },
@@ -33,11 +34,26 @@ export class PwaApprover {
             const decision = open(this.key, payload, aadForDecision(requestId));
             if (decision.requestId !== requestId)
                 continue; // belt and suspenders; AAD already binds it
-            return {
-                approved: decision.approved,
-                decision: decision.approved ? "approved" : "denied",
-            };
+            return decision;
+        }
+        return null;
+    }
+    async request(req) {
+        const decision = await this.roundTrip("approval", req);
+        if (!decision)
+            return { approved: false, decision: "timeout" };
+        return {
+            approved: decision.approved,
+            decision: decision.approved ? "approved" : "denied",
+        };
+    }
+    async ask(req) {
+        const decision = await this.roundTrip("input", req);
+        if (!decision)
+            return { answer: null, decision: "timeout" };
+        if (!decision.approved || typeof decision.answer !== "string") {
+            return { answer: null, decision: "denied" };
         }
-        return { approved: false, decision: "timeout" };
+        return { answer: decision.answer, decision: "answered" };
     }
 }

package/dist/relay/pwa-page.js

@@ -211,8 +211,18 @@ export const PWA_HTML = `<!doctype html>
   .hrow .t { flex: 1; color: #cfc6b2; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
   .hrow .d { font-weight: 650; font-size: 10.5px; letter-spacing: .05em; text-transform: uppercase; }
   .d.approved { color: #7fbf9a; }
+  .d.answered { color: #7fbf9a; }
   .d.denied { color: #d98a76; }
   .d.expired { color: var(--soft); }
+
+  .answer-input {
+    width: 100%; box-sizing: border-box; padding: 12px 14px; margin: 0 0 12px;
+    background: var(--panel-raised); border: 1px solid var(--line); border-radius: 10px;
+    /* 16px minimum: below that, iOS Safari auto-zooms into focused inputs. */
+    color: var(--ink); font: 16px ui-monospace, monospace;
+  }
+  .answer-input:focus { outline: 2px solid var(--accent); outline-offset: -1px; }
+  .answer-input:disabled { opacity: .5; }
 </style>
 </head>
 <body>
@@ -582,17 +592,29 @@ export const PWA_HTML = `<!doctype html>
   }
 
   function addCard(id, p, requestId, req) {
+    var isInput = req.kind === "input";
     var card = document.createElement("div");
     card.className = "card";
 
     var who = document.createElement("div"); who.className = "who";
-    who.textContent = (pairs.length > 1 ? p.name + " · " : "") + "agent · approval request";
+    who.textContent =
+      (pairs.length > 1 ? p.name + " · " : "") +
+      (isInput ? "agent · question" : "agent · approval request");
     card.appendChild(who);
     var h = document.createElement("h2"); h.textContent = req.title; card.appendChild(h);
     // NOTE: never name this variable p — var is function-scoped and would
     // shadow the pairing parameter for the rest of addCard (real bug once).
     if (req.body) { var bodyP = document.createElement("p"); bodyP.textContent = req.body; card.appendChild(bodyP); }
 
+    var input = null;
+    if (isInput) {
+      input = document.createElement("input");
+      input.className = "answer-input";
+      input.placeholder = "Your answer";
+      input.autocomplete = "off";
+      card.appendChild(input);
+    }
+
     var timer = document.createElement("div"); timer.className = "timer";
     var left = document.createElement("div"); left.className = "left";
     var bar = document.createElement("div"); bar.className = "bar";
@@ -601,13 +623,32 @@ export const PWA_HTML = `<!doctype html>
     card.appendChild(timer);
 
     var row = document.createElement("div"); row.className = "row";
-    row.appendChild(makeBtn("Approve", "ok", CHECK, id));
-    row.appendChild(makeBtn("Deny", "no", CROSS, id));
+    if (isInput) {
+      var sendBtn = makeActionBtn("Send", "ok", CHECK, function (btn) {
+        var value = input.value.trim();
+        if (!value) { input.focus(); return; }
+        submitDecision(id, { requestId: requestId, approved: true, answer: value, ts: Date.now() }, "answered", btn);
+      });
+      input.addEventListener("keydown", function (e) {
+        if (e.key === "Enter") sendBtn.click();
+      });
+      row.appendChild(sendBtn);
+      row.appendChild(makeActionBtn("Deny", "no", CROSS, function (btn) {
+        submitDecision(id, { requestId: requestId, approved: false, ts: Date.now() }, "denied", btn);
+      }));
+    } else {
+      row.appendChild(makeActionBtn("Approve", "ok", CHECK, function (btn) {
+        submitDecision(id, { requestId: requestId, approved: true, ts: Date.now() }, "approved", btn);
+      }));
+      row.appendChild(makeActionBtn("Deny", "no", CROSS, function (btn) {
+        submitDecision(id, { requestId: requestId, approved: false, ts: Date.now() }, "denied", btn);
+      }));
+    }
     card.appendChild(row);
 
     ensureEmpty(false);
     listEl.appendChild(card);
-    cards[id] = { el: card, leftEl: left, fillEl: fill, barEl: bar, rowEl: row, req: req, pair: p, requestId: requestId, done: false };
+    cards[id] = { el: card, leftEl: left, fillEl: fill, barEl: bar, rowEl: row, inputEl: input, req: req, pair: p, requestId: requestId, done: false };
     tickOne(cards[id]);
   }
 
@@ -619,6 +660,7 @@ export const PWA_HTML = `<!doctype html>
         c.done = true;
         c.el.classList.add("expired");
         c.rowEl.remove();
+        if (c.inputEl) c.inputEl.disabled = true;
         c.leftEl.textContent = "expired — denied";
         c.fillEl.style.width = "0%";
         recordHist(histLabel(c), "expired");
@@ -633,41 +675,39 @@ export const PWA_HTML = `<!doctype html>
     for (var id in cards) tickOne(cards[id]);
   }, 1000);
 
-  function makeBtn(label, cls, icon, id) {
+  function makeActionBtn(label, cls, icon, onTap) {
     var b = document.createElement("button");
     b.className = cls;
     b.innerHTML = icon + "<span></span>";
     b.querySelector("span").textContent = label;
-    b.onclick = async function () {
-      var c = cards[id];
-      if (!c || c.done) return;
-      b.disabled = true;
-      try {
-        var payload = await sealPayload(
-          c.pair,
-          { requestId: c.requestId, approved: cls === "ok", ts: Date.now() },
-          "dec:" + c.requestId
-        );
-        var res = await fetch("/api/decision", {
-          method: "POST",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({ pairId: c.pair.pairId, requestId: c.requestId, payload: payload }),
-        });
-        if (!res.ok) throw new Error("relay answered HTTP " + res.status);
-        if (cards[id]) {
-          recordHist(histLabel(c), cls === "ok" ? "approved" : "denied");
-          cards[id].el.remove();
-          delete cards[id];
-        }
-        ensureEmpty(Object.keys(cards).length === 0);
-      } catch (err) {
-        b.disabled = false;
-        alert("Could not send your decision: " + (err && err.message ? err.message : err));
-      }
-    };
+    b.onclick = function () { onTap(b); };
     return b;
   }
 
+  async function submitDecision(id, decisionBody, histDecision, btn) {
+    var c = cards[id];
+    if (!c || c.done) return;
+    btn.disabled = true;
+    try {
+      var payload = await sealPayload(c.pair, decisionBody, "dec:" + c.requestId);
+      var res = await fetch("/api/decision", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ pairId: c.pair.pairId, requestId: c.requestId, payload: payload }),
+      });
+      if (!res.ok) throw new Error("relay answered HTTP " + res.status);
+      if (cards[id]) {
+        recordHist(histLabel(c), histDecision);
+        cards[id].el.remove();
+        delete cards[id];
+      }
+      ensureEmpty(Object.keys(cards).length === 0);
+    } catch (err) {
+      btn.disabled = false;
+      alert("Could not send your decision: " + (err && err.message ? err.message : err));
+    }
+  }
+
   function histLabel(c) {
     return (pairs.length > 1 ? c.pair.name + ": " : "") + c.req.title;
   }

package/dist/server.js

@@ -62,6 +62,43 @@ export async function serve(passphrase) {
             return refusal(String(err));
         }
     });
+    server.registerTool("ask_human", {
+        title: "Ask the human a question",
+        description: "Ask the human for a short piece of information only they have: a " +
+            "code received by SMS on their real phone number, the answer to a " +
+            "security question, a choice between options. Their answer is typed " +
+            "on their phone and returned over the same end-to-end-encrypted " +
+            "channel as approvals. No answer within the timeout means denied.",
+        inputSchema: {
+            question: z.string().describe("The question shown to the human"),
+            context: z.string().optional().describe("Extra context shown under the question"),
+            timeout_sec: z.number().int().min(10).max(600).optional(),
+        },
+    }, async ({ question, context, timeout_sec }) => {
+        try {
+            const approver = needApprover();
+            if (!approver.ask) {
+                return refusal("Input requests need the PWA approval channel. Pair a phone with `sandgate pair <relay-url>`.");
+            }
+            const result = await approver.ask({
+                title: question,
+                body: context,
+                timeoutSec: timeout_sec ?? config.approvalTimeoutSec,
+            });
+            // The answer itself is never audited — it may be a code or a secret.
+            audit({ tool: "ask_human", action: question, decision: result.decision === "answered" ? "approved" : result.decision === "denied" ? "denied" : "timeout" });
+            if (result.decision !== "answered") {
+                return refusal(result.decision === "timeout"
+                    ? "The human did not answer in time."
+                    : "The human declined to answer.");
+            }
+            return text({ ok: true, answered: true, answer: result.answer });
+        }
+        catch (err) {
+            audit({ tool: "ask_human", action: question, decision: "error", detail: String(err) });
+            return refusal(String(err));
+        }
+    });
     server.registerTool("get_totp", {
         title: "Get a 2FA code",
         description: "Get the current 6-digit 2FA (TOTP) code for a domain whose seed the " +

package/dist/test/passphrase.test.js

@@ -0,0 +1,20 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { resolvePassphrase } from "../passphrase.js";
+test("direct SANDGATE_PASSPHRASE wins", () => {
+    assert.equal(resolvePassphrase({ SANDGATE_PASSPHRASE: "direct", SANDGATE_PASSPHRASE_CMD: "echo nope" }), "direct");
+});
+test("SANDGATE_PASSPHRASE_CMD output is used, trimmed", () => {
+    const cmd = `node -e "console.log('  from-command  ')"`;
+    assert.equal(resolvePassphrase({ SANDGATE_PASSPHRASE_CMD: cmd }), "from-command");
+});
+test("empty command output resolves to undefined", () => {
+    const cmd = `node -e "console.log('')"`;
+    assert.equal(resolvePassphrase({ SANDGATE_PASSPHRASE_CMD: cmd }), undefined);
+});
+test("neither variable set resolves to undefined", () => {
+    assert.equal(resolvePassphrase({}), undefined);
+});
+test("a failing command throws", () => {
+    assert.throws(() => resolvePassphrase({ SANDGATE_PASSPHRASE_CMD: `node -e "process.exit(3)"` }));
+});

package/dist/test/pwa-browser.test.js

@@ -104,6 +104,78 @@ for (const scenario of ["fragment", "legacy-storage"]) {
         }
     });
 }
+test("ask_human: the input card round-trips a typed answer", async () => {
+    const relay = await startRelay({
+        port: 0,
+        stateDir: mkdtempSync(join(tmpdir(), "sandgate-relay-")),
+    });
+    const relayUrl = `http://localhost:${relay.port}`;
+    try {
+        const pairing = newPairing();
+        const { window, alerts, close } = await loadPage(relayUrl, {
+            hash: `#p=${pairing.pairId}&s=${pairing.secret}`,
+        });
+        try {
+            const approver = new PwaApprover({
+                relayUrl,
+                pairId: pairing.pairId,
+                secret: pairing.secret,
+            });
+            const asked = approver.ask({
+                title: "What is the SMS code?",
+                body: "Sent to your real number",
+                timeoutSec: 15,
+            });
+            const input = await waitFor(() => window.document.querySelector(".card .answer-input"));
+            assert.match(window.document.querySelector(".card .who").textContent, /question/);
+            input.value = "  847291 ";
+            const sendBtn = window.document.querySelector(".card button.ok");
+            sendBtn.click();
+            const result = await asked;
+            assert.deepEqual(alerts, [], `page alerted: ${alerts.join(" | ")}`);
+            assert.deepEqual(result, { answer: "847291", decision: "answered" });
+            await waitFor(() => window.document.querySelector(".hrow .d.answered"));
+        }
+        finally {
+            close();
+        }
+    }
+    finally {
+        relay.close();
+    }
+});
+test("ask_human: denying returns no answer", async () => {
+    const relay = await startRelay({
+        port: 0,
+        stateDir: mkdtempSync(join(tmpdir(), "sandgate-relay-")),
+    });
+    const relayUrl = `http://localhost:${relay.port}`;
+    try {
+        const pairing = newPairing();
+        const { window, alerts, close } = await loadPage(relayUrl, {
+            hash: `#p=${pairing.pairId}&s=${pairing.secret}`,
+        });
+        try {
+            const approver = new PwaApprover({
+                relayUrl,
+                pairId: pairing.pairId,
+                secret: pairing.secret,
+            });
+            const asked = approver.ask({ title: "Secret question", timeoutSec: 15 });
+            const denyBtn = await waitFor(() => window.document.querySelector(".card button.no"));
+            denyBtn.click();
+            const result = await asked;
+            assert.deepEqual(result, { answer: null, decision: "denied" });
+            assert.deepEqual(alerts, [], `page alerted: ${alerts.join(" | ")}`);
+        }
+        finally {
+            close();
+        }
+    }
+    finally {
+        relay.close();
+    }
+});
 test("Deny works and corrupt stored pairings do not break the page", async () => {
     const relay = await startRelay({
         port: 0,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sandprivacy/sandgate",
-  "version": "0.1.8",
+  "version": "0.2.1",
   "description": "The human gateway for AI agents — approvals, 2FA codes and email verification, self-hosted. Your agent asks; you decide; secrets never touch the LLM.",
   "license": "AGPL-3.0-only",
   "type": "module",