@sandprivacy/sandgate 0.2.0 → 0.2.1

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,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/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/package.json

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