@sandprivacy/sandgate 0.1.0

package/README.md

@@ -0,0 +1,103 @@
+# sandgate
+
+**The human gateway for AI agents.** Approvals, 2FA codes and email verification — one self-hosted MCP server. Your agent asks; your phone buzzes; you decide. Secrets never touch the LLM.
+
+<!-- TODO(launch): hero GIF — agent hits a 2FA screen → phone buzzes → tap Approve → agent finishes the task -->
+
+```
+Agent: "I need the 2FA code for github.com"
+   │
+   ▼
+sandgate ──► your phone: [✅ Approve] [❌ Deny]
+   │
+   ▼  (approved)
+Agent gets: 483 921        ← a 30-second code
+Agent never gets: the seed ← stays AES-256-GCM encrypted in your vault
+```
+
+## Why
+
+Agents stall on everything that needs a human: TOTP prompts, verification emails, magic links, "are you sure?" moments. Today the workarounds are ugly — TOTP seeds in plaintext `.env` files, agents with full access to your inbox, or a human babysitting the terminal. sandgate replaces all of that with one MCP server any agent can call:
+
+| | DIY (`.env` + custom tools) | sandgate |
+|---|---|---|
+| TOTP seed storage | plaintext | encrypted vault (AES-256-GCM, scrypt) |
+| What the LLM sees | the seed | a 30-second code, after policy check |
+| Sensitive actions | agent decides | your phone decides |
+| Verification emails | build it yourself | `create_identity` + `wait_for_verification` |
+| Audit trail | none | every request, decision and outcome |
+
+## Quickstart
+
+```bash
+npm install -g @sandprivacy/sandgate
+sandgate init                          # vault passphrase + Telegram bot + inbox backend
+sandgate add-totp github.com JBSWY3DPEHPK3PXP
+sandgate test-approval                 # your phone should buzz
+```
+
+Register it with your agent (Claude Code shown; any MCP client works):
+
+```bash
+claude mcp add sandgate -e SANDGATE_PASSPHRASE=your-passphrase -- sandgate serve
+```
+
+That's it. Your agent now has four new tools.
+
+## The four tools
+
+- **`request_approval`** — "May I pay €300 on this site?" → push to your phone → approve/deny. No answer = denied.
+- **`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.
+
+## Policies
+
+```bash
+sandgate policy github.com auto      # trusted: no buzz, code released instantly
+sandgate policy mybank.com deny      # never
+# everything else defaults to "approve" — your phone decides
+```
+
+## What's in `~/.sandgate/`
+
+- `vault.enc` — TOTP seeds, bot token, API keys. AES-256-GCM, key derived from your passphrase with scrypt. Nothing sensitive is ever written in clear.
+- `config.json` — policies and preferences, plaintext, hand-editable.
+- `audit.jsonl` — append-only log of every request: which tool, which domain, what was decided, when. Codes and secrets are never logged.
+
+## Design principles
+
+1. **Zero disclosure.** The LLM sees derived, short-lived values (a 6-digit code, an approval verdict) — never seeds, tokens or passwords.
+2. **Deny by default.** Unknown domains refuse. Unanswered approvals refuse. Policy gaps refuse.
+3. **Self-hosted.** Runs on your machine; the vault and the audit trail never leave it. The email backend is pluggable: [sandmail](https://sandmail.dev) works out of the box (managed disposable inboxes), or bring your own mailbox with `sandgate connect-imap` — identities become plus-addressed aliases (`you+sg1a2b@domain`) and codes/links are extracted locally.
+4. **Everything audited.** If an agent asked for it, it's in the log.
+
+## The PWA approval channel (E2EE)
+
+Telegram is the quick start; the PWA is the destination. Run your own relay and pair your phone:
+
+```bash
+sandgate relay                    # serves the PWA + forwards sealed blobs (port 8787)
+sandgate pair https://your-relay  # prints a link + QR — open it on your phone
+```
+
+How the trust works: the pairing secret travels once, inside the URL **fragment** (never sent to any server). Both ends derive an AES-256-GCM key (HKDF); every approval request and every tap is sealed with the request id bound into the AAD. The relay stores and forwards blobs it cannot read, and cannot forge — a malicious relay can at worst drop or delay an answer, which is just a deny. Push notifications wake the phone; if push is unavailable the PWA polls while open. A real phone needs the relay behind TLS (service workers require it); `http://localhost:8787` works for a desktop-browser test.
+
+## 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.
+- 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.
+
+## Roadmap
+
+- [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
+
+## License
+
+AGPL-3.0. Part of the [sandprivacy](https://github.com/sandprivacy) suite — your data and your agents, under your control.

package/dist/audit.js

@@ -0,0 +1,6 @@
+import { appendFileSync } from "node:fs";
+import { auditPath } from "./paths.js";
+export function audit(event) {
+    const line = JSON.stringify({ ts: new Date().toISOString(), ...event });
+    appendFileSync(auditPath(), line + "\n");
+}

package/dist/config.js

@@ -0,0 +1,27 @@
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { configPath } from "./paths.js";
+export const DEFAULT_CONFIG = {
+    policies: {
+        totp: {},
+        totpDefault: "approve",
+        verificationDefault: "auto",
+        identityDefault: "auto",
+    },
+    approvalTimeoutSec: 120,
+};
+export function loadConfig() {
+    if (!existsSync(configPath()))
+        return structuredClone(DEFAULT_CONFIG);
+    const raw = JSON.parse(readFileSync(configPath(), "utf8"));
+    return {
+        ...structuredClone(DEFAULT_CONFIG),
+        ...raw,
+        policies: { ...structuredClone(DEFAULT_CONFIG.policies), ...raw.policies },
+    };
+}
+export function saveConfig(config) {
+    writeFileSync(configPath(), JSON.stringify(config, null, 2) + "\n");
+}
+export function totpPolicy(config, domain) {
+    return config.policies.totp[domain] ?? config.policies.totpDefault;
+}

package/dist/extract.js

@@ -0,0 +1,31 @@
+/**
+ * Local OTP/verification extraction for the IMAP backend (sandmail does
+ * this server-side; self-hosters get the same result locally).
+ */
+const CODE_CONTEXT = /(?:code|otp|pin|password|passcode|vérification|verification|confirm|2fa|authentif)/i;
+const LINK_HINT = /(?:verify|confirm|activate|validate|auth|token=|code=)/i;
+export function extractVerification(subject, text) {
+    const links = [];
+    for (const match of text.matchAll(/https?:\/\/[^\s<>"')\]]+/g)) {
+        if (LINK_HINT.test(match[0]) && !links.includes(match[0]))
+            links.push(match[0]);
+    }
+    // Prefer codes near context words; fall back to a lone 4-8 digit group in
+    // the subject (the "Your code is 774412" pattern).
+    const haystacks = [subject, text];
+    for (const haystack of haystacks) {
+        for (const line of haystack.split(/\r?\n/)) {
+            if (!CODE_CONTEXT.test(line))
+                continue;
+            const m = line.match(/\b(\d{4,8})\b/);
+            if (m)
+                return { code: m[1], links };
+        }
+    }
+    const subjectOnly = subject.match(/\b(\d{4,8})\b/);
+    if (subjectOnly)
+        return { code: subjectOnly[1], links };
+    // Standalone code on its own line (many emails put the code alone).
+    const alone = text.match(/^\s*(\d{4,8})\s*$/m);
+    return { code: alone ? alone[1] : null, links };
+}

package/dist/inbox.js

@@ -0,0 +1,104 @@
+import { ImapFlow } from "imapflow";
+import { simpleParser } from "mailparser";
+import { randomBytes } from "node:crypto";
+import * as sandmail from "./sandmail.js";
+import { extractVerification } from "./extract.js";
+export function backendFromVault(vault) {
+    if (vault.sandmail)
+        return new SandmailBackend(vault.sandmail.apiKey);
+    if (vault.imap)
+        return new ImapBackend(vault.imap);
+    return null;
+}
+class SandmailBackend {
+    apiKey;
+    kind = "sandmail";
+    constructor(apiKey) {
+        this.apiKey = apiKey;
+    }
+    createIdentity(ttlHours) {
+        return sandmail.createInbox(this.apiKey, { ttlHours });
+    }
+    async waitForVerification(email, timeoutSec) {
+        const res = await sandmail.waitForOTP(this.apiKey, email, timeoutSec);
+        return {
+            found: res.found,
+            timedOut: res.timedOut,
+            code: res.code,
+            from: res.from,
+            subject: res.subject,
+            links: res.verificationLinks ?? [],
+        };
+    }
+}
+class ImapBackend {
+    config;
+    kind = "imap";
+    constructor(config) {
+        this.config = config;
+    }
+    async createIdentity() {
+        const base = this.config.baseEmail ?? this.config.user;
+        const [local, domain] = base.split("@");
+        if (!domain)
+            throw new Error(`Cannot derive an alias from "${base}".`);
+        const tag = randomBytes(3).toString("hex");
+        return { email: `${local}+sg${tag}@${domain}`, expiresAt: null };
+    }
+    async waitForVerification(email, timeoutSec) {
+        const client = new ImapFlow({
+            host: this.config.host,
+            port: this.config.port ?? 993,
+            secure: (this.config.port ?? 993) === 993,
+            auth: { user: this.config.user, pass: this.config.pass },
+            logger: false,
+        });
+        const deadline = Date.now() + timeoutSec * 1000;
+        const since = new Date(Date.now() - 5 * 60 * 1000);
+        await client.connect();
+        try {
+            const lock = await client.getMailboxLock("INBOX");
+            try {
+                while (Date.now() < deadline) {
+                    const uids = await client.search({ to: email, since }, { uid: true });
+                    if (uids && uids.length) {
+                        const uid = uids[uids.length - 1];
+                        const dl = await client.download(String(uid), undefined, { uid: true });
+                        const parsed = await simpleParser(dl.content);
+                        const subject = parsed.subject ?? "";
+                        const text = (parsed.text ?? "") + "\n" + (parsed.html || "");
+                        const { code, links } = extractVerification(subject, text);
+                        return {
+                            found: true,
+                            timedOut: false,
+                            code,
+                            from: parsed.from?.text,
+                            subject,
+                            links,
+                        };
+                    }
+                    await new Promise((r) => setTimeout(r, 5000));
+                }
+                return { found: false, timedOut: true, code: null, links: [] };
+            }
+            finally {
+                lock.release();
+            }
+        }
+        finally {
+            await client.logout().catch(() => { });
+        }
+    }
+}
+/** Used by `sandgate connect-imap` to validate credentials before saving. */
+export async function testImapConnection(config) {
+    const client = new ImapFlow({
+        host: config.host,
+        port: config.port ?? 993,
+        secure: (config.port ?? 993) === 993,
+        auth: { user: config.user, pass: config.pass },
+        logger: false,
+    });
+    await client.connect();
+    await client.logout().catch(() => { });
+}

package/dist/index.js

@@ -0,0 +1,408 @@
+#!/usr/bin/env node
+import { stdin, stdout } from "node:process";
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { read } from "read";
+import { getQuota } from "./sandmail.js";
+import { testImapConnection } from "./inbox.js";
+import { auditPath } from "./paths.js";
+import { vaultExists, loadVault, saveVault, } from "./vault.js";
+import { loadConfig, saveConfig } from "./config.js";
+import { normalizeSecret, generateCode } from "./totp.js";
+import { TelegramApprover, discoverChatId } from "./telegram.js";
+import { serve } from "./server.js";
+import { sandgateDir } from "./paths.js";
+const HELP = `sandgate — the human gateway for AI agents
+
+Usage:
+  sandgate init                          Create the vault, connect Telegram & sandmail
+  sandgate add-totp <domain> <secret>    Store a 2FA seed (base32 or otpauth:// URI)
+  sandgate policy <domain> <auto|approve|deny>   Set the 2FA policy for a domain
+  sandgate connect-telegram <bot-token>  Connect (or fix) the Telegram approval channel
+  sandgate relay [port]                  Run the approval relay (serves the phone PWA)
+  sandgate pair <relay-url>              Pair your phone via the relay (E2EE, replaces Telegram)
+  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 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)
+
+The vault passphrase is read from SANDGATE_PASSPHRASE when running non-interactively
+(which is how MCP clients launch \`sandgate serve\`).`;
+/**
+ * Prompts that work in both worlds. Interactive TTY: the `read` package —
+ * the same battle-tested prompt npm itself uses for `npm login`, with
+ * asterisk masking for secrets. Piped/scripted stdin: the whole input is
+ * read upfront and answers are consumed line by line (readline drops lines
+ * that arrive between two questions, which silently killed piped `init`).
+ */
+class Prompter {
+    queue = null;
+    async ensureReady() {
+        if (stdin.isTTY || this.queue)
+            return;
+        let data = "";
+        for await (const chunk of stdin)
+            data += chunk;
+        this.queue = data.split(/\r?\n/);
+    }
+    async ask(query, opts) {
+        await this.ensureReady();
+        if (this.queue) {
+            const value = (this.queue.shift() ?? "").trim();
+            stdout.write(query + (opts?.hidden ? "(hidden)" : value) + "\n");
+            return value;
+        }
+        const answer = await read({
+            prompt: query,
+            silent: opts?.hidden ?? false,
+            replace: opts?.hidden ? "*" : undefined,
+        });
+        return answer.trim();
+    }
+    close() {
+        // `read` cleans up after each prompt; nothing to release.
+    }
+}
+async function getPassphrase(prompter, confirm = false) {
+    const env = process.env.SANDGATE_PASSPHRASE;
+    if (env)
+        return env;
+    const pass = await prompter.ask("Vault passphrase: ", { hidden: true });
+    if (!pass) {
+        console.error("A passphrase is required.");
+        process.exit(1);
+    }
+    if (confirm) {
+        const again = await prompter.ask("Confirm passphrase: ", { hidden: true });
+        if (again !== pass) {
+            console.error("Passphrases do not match.");
+            process.exit(1);
+        }
+    }
+    return pass;
+}
+async function cmdInit() {
+    console.log(`sandgate init — files live in ${sandgateDir()}\n`);
+    if (vaultExists()) {
+        console.error("A vault already exists. Delete ~/.sandgate/vault.enc to start over.");
+        process.exit(1);
+    }
+    const prompter = new Prompter();
+    console.log("The vault passphrase is sandgate's master password: it encrypts your 2FA\n" +
+        "seeds and API keys (AES-256-GCM). Choose it well — it cannot be recovered.\n");
+    const pass = await getPassphrase(prompter, true);
+    const data = { totp: {} };
+    console.log("\nApproval channel (Telegram) — create a bot with @BotFather, then send it any message.");
+    const botToken = await prompter.ask("Bot token (empty to skip): ");
+    if (botToken) {
+        const chatId = await discoverChatId(botToken);
+        if (chatId) {
+            data.telegram = { botToken, chatId };
+            console.log(`Connected: chat ${chatId}.`);
+        }
+        else {
+            console.log("No message found — send your bot a message first, then run: sandgate connect-telegram <token>");
+        }
+    }
+    console.log("\nInbox backend (sandmail) — for create_identity / wait_for_verification.");
+    const apiKey = await prompter.ask("sandmail API key (empty to skip): ");
+    if (apiKey)
+        data.sandmail = { apiKey };
+    prompter.close();
+    saveVault(pass, data);
+    saveConfig(loadConfig());
+    console.log(`\nVault created. Next steps:\n` +
+        `  sandgate add-totp github.com <secret>\n` +
+        `  sandgate test-approval\n` +
+        `Then register the MCP server in your agent (see README).`);
+}
+async function cmdAddTotp(domain, secret) {
+    if (!domain || !secret) {
+        console.error("Usage: sandgate add-totp <domain> <secret>");
+        process.exit(1);
+    }
+    const prompter = new Prompter();
+    const pass = await getPassphrase(prompter);
+    prompter.close();
+    const data = loadVault(pass);
+    const key = domain.toLowerCase().replace(/^www\./, "");
+    const normalized = normalizeSecret(secret);
+    const { code } = generateCode(normalized); // validates the seed
+    data.totp[key] = { secret: normalized };
+    saveVault(pass, data);
+    console.log(`Stored 2FA seed for ${key}. Current code: ${code} (sanity check against your authenticator).`);
+}
+async function cmdPolicy(domain, policy) {
+    const valid = ["auto", "approve", "deny"];
+    if (!domain || !valid.includes(policy)) {
+        console.error("Usage: sandgate policy <domain> <auto|approve|deny>");
+        process.exit(1);
+    }
+    const config = loadConfig();
+    config.policies.totp[domain.toLowerCase()] = policy;
+    saveConfig(config);
+    console.log(`2FA policy for ${domain}: ${policy}`);
+}
+async function cmdConnectTelegram(botToken) {
+    if (!botToken) {
+        console.error("Usage: sandgate connect-telegram <bot-token>");
+        process.exit(1);
+    }
+    const prompter = new Prompter();
+    const pass = await getPassphrase(prompter);
+    prompter.close();
+    const data = loadVault(pass);
+    const chatId = await discoverChatId(botToken);
+    if (!chatId) {
+        console.error("No message found for this bot. Open Telegram, send your bot any message, then rerun this command.");
+        process.exit(1);
+    }
+    data.telegram = { botToken, chatId };
+    saveVault(pass, data);
+    console.log(`Telegram connected (chat ${chatId}). Try: sandgate test-approval`);
+}
+async function cmdConnectSandmail(apiKey) {
+    if (!apiKey) {
+        console.error("Usage: sandgate connect-sandmail <api-key>");
+        process.exit(1);
+    }
+    const prompter = new Prompter();
+    const pass = await getPassphrase(prompter);
+    prompter.close();
+    const data = loadVault(pass);
+    try {
+        const quota = await getQuota(apiKey);
+        data.sandmail = { apiKey };
+        saveVault(pass, data);
+        console.log(`sandmail connected (quota: ${quota.remaining}/${quota.limit} remaining). ` +
+            `Agents can now use create_identity and wait_for_verification.`);
+    }
+    catch (err) {
+        console.error(`Could not validate the sandmail key: ${err instanceof Error ? err.message : err}`);
+        process.exit(1);
+    }
+}
+async function cmdConnectImap() {
+    const prompter = new Prompter();
+    const pass = await getPassphrase(prompter);
+    const data = loadVault(pass);
+    console.log("\nYour own IMAP mailbox as the inbox backend. Agent identities become\n" +
+        "plus-addressed aliases (you+sg1a2b@domain) — check your provider supports them.\n" +
+        "Use an app password, not your main account password, whenever available.\n");
+    const host = await prompter.ask("IMAP host (e.g. imap.fastmail.com): ");
+    const portRaw = await prompter.ask("Port [993]: ");
+    const user = await prompter.ask("User / email: ");
+    const imapPass = await prompter.ask("Password (app password): ", { hidden: true });
+    const baseEmail = await prompter.ask(`Alias base address [${user}]: `);
+    prompter.close();
+    const config = {
+        host: host.trim(),
+        port: portRaw ? parseInt(portRaw, 10) : 993,
+        user: user.trim(),
+        pass: imapPass,
+        baseEmail: baseEmail.trim() || undefined,
+    };
+    process.stdout.write("Testing the connection… ");
+    try {
+        await testImapConnection(config);
+        console.log("ok.");
+    }
+    catch (err) {
+        console.error(`failed: ${err instanceof Error ? err.message : err}`);
+        process.exit(1);
+    }
+    data.imap = config;
+    saveVault(pass, data);
+    const note = data.sandmail
+        ? " Note: sandmail is also configured and takes precedence; remove it from the vault to use IMAP."
+        : "";
+    console.log(`IMAP connected (${config.user}@${config.host}).${note}`);
+}
+async function cmdStatus() {
+    if (!vaultExists()) {
+        console.log("No vault. Run `sandgate init` to get started.");
+        return;
+    }
+    const prompter = new Prompter();
+    const pass = await getPassphrase(prompter);
+    prompter.close();
+    const data = loadVault(pass);
+    const config = loadConfig();
+    const domains = Object.keys(data.totp);
+    const auditCount = existsSync(auditPath())
+        ? readFileSync(auditPath(), "utf8").trim().split("\n").filter(Boolean).length
+        : 0;
+    const approval = data.pwa
+        ? `PWA via ${data.pwa.relayUrl} (Telegram ${data.telegram ? "fallback" : "not set"})`
+        : data.telegram
+            ? "Telegram"
+            : "none — run `sandgate pair <relay-url>` or `sandgate connect-telegram <token>`";
+    const inboxLine = data.sandmail
+        ? "sandmail" + (data.imap ? " (imap configured but sandmail takes precedence)" : "")
+        : data.imap
+            ? `imap (${data.imap.user}@${data.imap.host})`
+            : "none — run `sandgate connect-sandmail <key>` or `sandgate connect-imap`";
+    console.log(`sandgate status — ${sandgateDir()}\n`);
+    console.log(`  approval channel   ${approval}`);
+    console.log(`  inbox backend      ${inboxLine}`);
+    console.log(`  2FA seeds          ${domains.length ? domains.join(", ") : "none — add with \`sandgate add-totp <domain> <secret>\`"}`);
+    console.log(`  2FA policy         default ${config.policies.totpDefault}` +
+        (Object.keys(config.policies.totp).length
+            ? "; " +
+                Object.entries(config.policies.totp)
+                    .map(([d, p]) => `${d}=${p}`)
+                    .join(", ")
+            : ""));
+    console.log(`  audit entries      ${auditCount}`);
+}
+async function cmdAudit(countArg) {
+    const count = Math.max(1, parseInt(countArg ?? "20", 10) || 20);
+    if (!existsSync(auditPath())) {
+        console.log("No audit entries yet.");
+        return;
+    }
+    const lines = readFileSync(auditPath(), "utf8").trim().split("\n").slice(-count);
+    const icons = {
+        auto: "·",
+        approved: "✓",
+        denied: "✗",
+        timeout: "…",
+        error: "!",
+    };
+    for (const line of lines) {
+        try {
+            const e = JSON.parse(line);
+            const when = e.ts.replace("T", " ").slice(0, 19);
+            const what = e.domain ?? e.action ?? e.detail ?? "";
+            console.log(`${when}  ${icons[e.decision] ?? "·"} ${String(e.decision).padEnd(8)} ${e.tool.padEnd(22)} ${what}`);
+        }
+        catch {
+            // skip malformed lines rather than crash the report
+        }
+    }
+}
+async function cmdRelay(portArg) {
+    const port = portArg ? parseInt(portArg, 10) : 8787;
+    const { startRelay } = await import("./relay/server.js");
+    const relay = await startRelay({
+        port,
+        stateDir: join(sandgateDir(), "relay"),
+    });
+    console.log(`sandgate relay listening on http://localhost:${relay.port}\n` +
+        `Behind TLS (required for phone push), pair with: sandgate pair https://your-relay-host`);
+}
+async function cmdPair(relayUrl) {
+    if (!relayUrl) {
+        console.error("Usage: sandgate pair <relay-url>\n" +
+            "Run `sandgate relay` first (behind TLS for a real phone; http://localhost:8787 works for a desktop browser test).");
+        process.exit(1);
+    }
+    const prompter = new Prompter();
+    const pass = await getPassphrase(prompter);
+    prompter.close();
+    const data = loadVault(pass);
+    const { newPairing } = await import("./pwacrypto.js");
+    const pairing = newPairing();
+    const base = relayUrl.replace(/\/$/, "");
+    const pairLink = `${base}/#p=${pairing.pairId}&s=${pairing.secret}`;
+    data.pwa = { relayUrl: base, pairId: pairing.pairId, secret: pairing.secret };
+    saveVault(pass, data);
+    const qrcode = (await import("qrcode-terminal")).default;
+    console.log("\nOpen this link on your phone (the secret is in the URL fragment — it never reaches the relay):\n");
+    console.log(`  ${pairLink}\n`);
+    qrcode.generate(pairLink, { small: true });
+    console.log("\nWaiting for the phone to subscribe (2 min)…");
+    const deadline = Date.now() + 120_000;
+    while (Date.now() < deadline) {
+        try {
+            const res = await fetch(`${base}/api/pair-status?pairId=${encodeURIComponent(pairing.pairId)}`);
+            const status = (await res.json());
+            if (status.subscribed) {
+                console.log("Paired! The PWA now takes over approvals (Telegram becomes the fallback). Try: sandgate test-approval");
+                return;
+            }
+        }
+        catch {
+            // relay not reachable yet; keep trying
+        }
+        await new Promise((r) => setTimeout(r, 3000));
+    }
+    console.log("No subscription yet — the pairing is saved anyway. Open the link on the phone, then check with: sandgate test-approval");
+}
+async function cmdTestApproval() {
+    const prompter = new Prompter();
+    const pass = await getPassphrase(prompter);
+    prompter.close();
+    const data = loadVault(pass);
+    let approver;
+    if (data.pwa) {
+        const { PwaApprover } = await import("./pwa-approver.js");
+        approver = new PwaApprover(data.pwa);
+        console.log("Sending test approval to the paired PWA (60s timeout)…");
+    }
+    else if (data.telegram) {
+        approver = new TelegramApprover(data.telegram.botToken, data.telegram.chatId);
+        console.log("Sending test approval to Telegram (60s timeout)…");
+    }
+    else {
+        console.error("No approval channel. Run `sandgate connect-telegram <bot-token>` or `sandgate pair <relay-url>`.");
+        process.exit(1);
+    }
+    const result = await approver.request({
+        title: "Test from sandgate",
+        body: "Tap Approve to confirm your approval channel works.",
+        timeoutSec: 60,
+    });
+    console.log(`Result: ${result.decision}`);
+}
+async function main() {
+    const [command, ...args] = process.argv.slice(2);
+    switch (command) {
+        case "init":
+            return cmdInit();
+        case "add-totp":
+            return cmdAddTotp(args[0], args[1]);
+        case "policy":
+            return cmdPolicy(args[0], args[1]);
+        case "connect-telegram":
+            return cmdConnectTelegram(args[0]);
+        case "connect-sandmail":
+            return cmdConnectSandmail(args[0]);
+        case "connect-imap":
+            return cmdConnectImap();
+        case "test-approval":
+            return cmdTestApproval();
+        case "relay":
+            return cmdRelay(args[0]);
+        case "pair":
+            return cmdPair(args[0]);
+        case "status":
+            return cmdStatus();
+        case "audit":
+            return cmdAudit(args[0]);
+        case undefined:
+        case "serve": {
+            const pass = process.env.SANDGATE_PASSPHRASE;
+            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": "..."}}');
+                process.exit(1);
+            }
+            return serve(pass);
+        }
+        case "help":
+        case "--help":
+        case "-h":
+            console.log(HELP);
+            return;
+        default:
+            console.error(`Unknown command: ${command}\n\n${HELP}`);
+            process.exit(1);
+    }
+}
+main().catch((err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+});