@sandprivacy/sandgate 0.2.0 → 0.2.2

package/README.md

@@ -90,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.
@@ -104,7 +104,7 @@ How the trust works: the pairing secret travels once, inside the URL **fragment*
 - [ ] OS keychain for the vault passphrase
 - [ ] Slack approval channel with multiple approvers (teams)
 - [ ] Team policies (shared vault, centralized audit)
-- [ ] Framework guides: browser-use, LangGraph, Agno
+- [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,8 +5,9 @@ import { join } from "node:path";
 import { read } from "read";
 import { getQuota } from "./sandmail.js";
 import { testImapConnection } from "./inbox.js";
+import { resolvePassphrase, protectPassphraseDpapi, dpapiDecryptCommand } from "./passphrase.js";
 import { auditPath } from "./paths.js";
-import { vaultExists, loadVault, saveVault, } from "./vault.js";
+import { vaultExists, loadVault, saveVault, rekeyVault, } from "./vault.js";
 import { loadConfig, saveConfig } from "./config.js";
 import { normalizeSecret, generateCode } from "./totp.js";
 import { TelegramApprover, discoverChatId } from "./telegram.js";
@@ -24,6 +25,8 @@ Usage:
   sandgate connect-sandmail <api-key>    Connect the sandmail inbox backend
   sandgate connect-imap                  Connect your own IMAP mailbox instead (self-hosted)
   sandgate test-approval                 Send a test approval to your phone
+  sandgate rekey                         Change the vault passphrase
+  sandgate protect                       Store the passphrase in the OS store (Windows DPAPI)
   sandgate status                        Show what is configured and active
   sandgate audit [n]                     Show the last n audit entries (default 20)
   sandgate serve                         Run the MCP server (stdio)
@@ -220,6 +223,37 @@ async function cmdConnectImap() {
         : "";
     console.log(`IMAP connected (${config.user}@${config.host}).${note}`);
 }
+async function cmdRekey() {
+    const prompter = new Prompter();
+    const current = await prompter.ask("Current passphrase: ", { hidden: true });
+    const next = await prompter.ask("New passphrase: ", { hidden: true });
+    const confirm = await prompter.ask("Confirm new passphrase: ", { hidden: true });
+    prompter.close();
+    if (!next) {
+        console.error("A passphrase is required.");
+        process.exit(1);
+    }
+    if (next !== confirm) {
+        console.error("Passphrases do not match.");
+        process.exit(1);
+    }
+    rekeyVault(current, next); // throws "wrong passphrase" if current is bad
+    console.log("Vault re-encrypted. Update SANDGATE_PASSPHRASE (or your passphrase command's store) everywhere sandgate serve is launched.");
+}
+async function cmdProtect() {
+    const prompter = new Prompter();
+    const pass = await prompter.ask("Vault passphrase: ", { hidden: true });
+    prompter.close();
+    if (!pass) {
+        console.error("A passphrase is required.");
+        process.exit(1);
+    }
+    loadVault(pass); // validate before storing — a typo here would be silent later
+    const target = join(sandgateDir(), "pass.dpapi");
+    protectPassphraseDpapi(pass, target);
+    console.log(`Passphrase verified against the vault and stored, DPAPI-encrypted, at:\n  ${target}\n\n` +
+        `Point your MCP config at it with:\n  SANDGATE_PASSPHRASE_CMD = ${dpapiDecryptCommand(target)}`);
+}
 async function cmdStatus() {
     if (!vaultExists()) {
         console.log("No vault. Run `sandgate init` to get started.");
@@ -385,16 +419,29 @@ async function main() {
             return cmdRelay(args[0]);
         case "pair":
             return cmdPair(args[0]);
+        case "rekey":
+            return cmdRekey();
+        case "protect":
+            return cmdProtect();
         case "status":
             return cmdStatus();
         case "audit":
             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,55 @@
+import { execSync, spawnSync } 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.
+ */
+/**
+ * Windows only: encrypt the passphrase with DPAPI (bound to the current
+ * Windows session) and write the blob to filePath. The plaintext travels
+ * to PowerShell via stdin — never argv, never env.
+ */
+export function protectPassphraseDpapi(passphrase, filePath) {
+    if (process.platform !== "win32") {
+        throw new Error("DPAPI is Windows-only. On macOS use the keychain (`security add-generic-password`), on Linux `secret-tool store` — see docs/integrations/claude-code.md.");
+    }
+    const script = "$plain = [Console]::In.ReadToEnd().TrimEnd([char]13, [char]10); " +
+        "if ($plain.Length -eq 0) { exit 2 }; " +
+        "$ss = ConvertTo-SecureString $plain -AsPlainText -Force; " +
+        `$ss | ConvertFrom-SecureString | Out-File -Encoding ascii '${filePath.replace(/'/g, "''")}'`;
+    const result = spawnSync("powershell", ["-NoProfile", "-Command", script], {
+        input: passphrase,
+        windowsHide: true,
+        timeout: 30_000,
+    });
+    if (result.status !== 0) {
+        throw new Error(`DPAPI protection failed (exit ${result.status}): ${result.stderr?.toString().slice(0, 300)}`);
+    }
+}
+/** The command that decrypts what protectPassphraseDpapi wrote. */
+export function dpapiDecryptCommand(filePath) {
+    return `powershell -NoProfile -Command "[Net.NetworkCredential]::new('', (Get-Content '${filePath}' | ConvertTo-SecureString)).Password"`;
+}
+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/test/core.test.js

@@ -5,7 +5,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 // Point sandgate at a throwaway home before importing modules that use it.
 process.env.SANDGATE_HOME = mkdtempSync(join(tmpdir(), "sandgate-test-"));
-const { saveVault, loadVault } = await import("../vault.js");
+const { saveVault, loadVault, rekeyVault } = await import("../vault.js");
 const { generateCode, normalizeSecret } = await import("../totp.js");
 const { loadConfig, saveConfig, totpPolicy } = await import("../config.js");
 test("vault round-trips and rejects a wrong passphrase", () => {
@@ -17,6 +17,14 @@ test("vault round-trips and rejects a wrong passphrase", () => {
     assert.deepEqual(loadVault("correct horse"), data);
     assert.throws(() => loadVault("wrong"), /wrong passphrase/);
 });
+test("rekey re-encrypts under the new passphrase and retires the old one", () => {
+    const data = { totp: { "site.com": { secret: "JBSWY3DPEHPK3PXP" } } };
+    saveVault("old-pass", data);
+    rekeyVault("old-pass", "new-pass");
+    assert.deepEqual(loadVault("new-pass"), data);
+    assert.throws(() => loadVault("old-pass"), /wrong passphrase/);
+    assert.throws(() => rekeyVault("old-pass", "whatever"), /wrong passphrase/);
+});
 test("totp generates stable 6-digit codes", () => {
     const a = generateCode("JBSWY3DPEHPK3PXP");
     const b = generateCode("JBSWY3DPEHPK3PXP");

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/protect.test.js

@@ -0,0 +1,18 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { execSync } from "node:child_process";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { protectPassphraseDpapi, dpapiDecryptCommand } from "../passphrase.js";
+// DPAPI is Windows-only; the CI matrix covers both, so skip cleanly elsewhere.
+const windowsOnly = { skip: process.platform !== "win32" };
+test("DPAPI protect/decrypt round-trips the passphrase", windowsOnly, () => {
+    const file = join(mkdtempSync(join(tmpdir(), "sandgate-dpapi-")), "pass.dpapi");
+    protectPassphraseDpapi("correct horse battery staple", file);
+    const decrypted = execSync(dpapiDecryptCommand(file), { encoding: "utf8" }).trim();
+    assert.equal(decrypted, "correct horse battery staple");
+});
+test("protect refuses on non-Windows platforms", { skip: process.platform === "win32" }, () => {
+    assert.throws(() => protectPassphraseDpapi("x", "/tmp/x"), /Windows-only/);
+});

package/dist/vault.js

@@ -25,6 +25,11 @@ export function saveVault(passphrase, data) {
     };
     writeFileSync(vaultPath(), JSON.stringify(file), { mode: 0o600 });
 }
+/** Change the vault passphrase in place: decrypt with the old, re-encrypt with the new. */
+export function rekeyVault(oldPassphrase, newPassphrase) {
+    const data = loadVault(oldPassphrase);
+    saveVault(newPassphrase, data);
+}
 export function loadVault(passphrase) {
     if (!vaultExists()) {
         throw new Error(`No vault found at ${vaultPath()}. Run \`sandgate init\` first.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sandprivacy/sandgate",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "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",