@sandprivacy/sandgate 0.1.0

package/dist/test/pwa.test.js

@@ -0,0 +1,113 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { newPairing, deriveKey, seal, open, aadForRequest, aadForDecision, } from "../pwacrypto.js";
+import { startRelay } from "../relay/server.js";
+import { PwaApprover } from "../pwa-approver.js";
+test("seal/open round-trips; tampering and wrong AAD are rejected", () => {
+    const { secret } = newPairing();
+    const key = deriveKey(secret);
+    const sealed = seal(key, { hello: "world" }, aadForRequest("r1"));
+    assert.deepEqual(open(key, sealed, aadForRequest("r1")), { hello: "world" });
+    assert.throws(() => open(key, sealed, aadForRequest("r2")), /authentication/);
+    const tampered = { ...sealed, ct: sealed.ct.slice(0, -4) + "AAAA" };
+    assert.throws(() => open(key, tampered, aadForRequest("r1")), /authentication/);
+    const otherKey = deriveKey(newPairing().secret);
+    assert.throws(() => open(otherKey, sealed, aadForRequest("r1")), /authentication/);
+});
+/** Plays the phone: polls pending, decrypts, answers. Same crypto as the PWA. */
+async function phoneAnswers(relayUrl, pairId, secret, approved) {
+    const key = deriveKey(secret);
+    for (let i = 0; i < 50; i++) {
+        const res = await fetch(`${relayUrl}/api/pending?pairId=${pairId}`);
+        const items = (await res.json());
+        if (items.length) {
+            const item = items[0];
+            const req = open(key, item.payload, aadForRequest(item.requestId));
+            const decision = seal(key, { requestId: item.requestId, approved, ts: Date.now() }, aadForDecision(item.requestId));
+            await fetch(`${relayUrl}/api/decision`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ pairId, requestId: item.requestId, payload: decision }),
+            });
+            return req;
+        }
+        await new Promise((r) => setTimeout(r, 50));
+    }
+    throw new Error("phone never saw a pending request");
+}
+test("full approval round-trip through the relay (approve, deny, timeout)", async () => {
+    const relay = await startRelay({
+        port: 0,
+        stateDir: mkdtempSync(join(tmpdir(), "sandgate-relay-")),
+    });
+    const relayUrl = `http://localhost:${relay.port}`;
+    try {
+        const pairing = newPairing();
+        const approver = new PwaApprover({
+            relayUrl,
+            pairId: pairing.pairId,
+            secret: pairing.secret,
+        });
+        // Approve
+        const phone1 = phoneAnswers(relayUrl, pairing.pairId, pairing.secret, true);
+        const r1 = await approver.request({ title: "Pay 300 EUR", timeoutSec: 10 });
+        assert.deepEqual(r1, { approved: true, decision: "approved" });
+        assert.equal((await phone1).title, "Pay 300 EUR"); // phone could read the sealed request
+        // Deny
+        const phone2 = phoneAnswers(relayUrl, pairing.pairId, pairing.secret, false);
+        const r2 = await approver.request({ title: "Delete account", timeoutSec: 10 });
+        assert.deepEqual(r2, { approved: false, decision: "denied" });
+        await phone2;
+        // Timeout (nobody answers)
+        const r3 = await approver.request({ title: "Silence", timeoutSec: 1 });
+        assert.deepEqual(r3, { approved: false, decision: "timeout" });
+    }
+    finally {
+        relay.close();
+    }
+});
+test("a relay cannot forge an approval (bad blob is rejected, request times out)", async () => {
+    const relay = await startRelay({
+        port: 0,
+        stateDir: mkdtempSync(join(tmpdir(), "sandgate-relay-")),
+    });
+    const relayUrl = `http://localhost:${relay.port}`;
+    try {
+        const pairing = newPairing();
+        const approver = new PwaApprover({
+            relayUrl,
+            pairId: pairing.pairId,
+            secret: pairing.secret,
+        });
+        // "Evil relay": answers with a forged decision sealed under the WRONG key.
+        const evil = (async () => {
+            const wrongKey = deriveKey(newPairing().secret);
+            for (let i = 0; i < 50; i++) {
+                const res = await fetch(`${relayUrl}/api/pending?pairId=${pairing.pairId}`);
+                const items = (await res.json());
+                if (items.length) {
+                    const forged = seal(wrongKey, { requestId: items[0].requestId, approved: true, ts: Date.now() }, aadForDecision(items[0].requestId));
+                    await fetch(`${relayUrl}/api/decision`, {
+                        method: "POST",
+                        headers: { "Content-Type": "application/json" },
+                        body: JSON.stringify({
+                            pairId: pairing.pairId,
+                            requestId: items[0].requestId,
+                            payload: forged,
+                        }),
+                    });
+                    return;
+                }
+                await new Promise((r) => setTimeout(r, 50));
+            }
+        })();
+        await assert.rejects(approver.request({ title: "Forgery target", timeoutSec: 3 }), /authentication/);
+        await evil;
+    }
+    finally {
+        relay.close();
+    }
+});

package/dist/test/telegram.test.js

@@ -0,0 +1,81 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { TelegramApprover } from "../telegram.js";
+/**
+ * Fake transport: captures sent messages, then feeds callback taps to the
+ * dispatcher. Lets us prove several concurrent approvals resolve correctly
+ * through the single getUpdates loop.
+ */
+class FakeTelegram extends TelegramApprover {
+    sent = [];
+    taps = [];
+    nextMessageId = 1;
+    nextUpdateId = 1;
+    constructor() {
+        super("fake-token", "12345");
+    }
+    async api(method, params) {
+        if (method === "sendMessage") {
+            const nonce = params.reply_markup.inline_keyboard[0][0].callback_data.split(":")[1];
+            const messageId = this.nextMessageId++;
+            this.sent.push({ messageId, nonce });
+            return { message_id: messageId };
+        }
+        if (method === "getUpdates") {
+            await new Promise((r) => setTimeout(r, 10));
+            const updates = this.taps.map((tap) => ({
+                update_id: this.nextUpdateId++,
+                callback_query: {
+                    id: "cb" + this.nextUpdateId,
+                    data: `${tap.verdict}:${tap.nonce}`,
+                    message: { chat: { id: 12345 } },
+                },
+            }));
+            this.taps = [];
+            return updates;
+        }
+        return {}; // answerCallbackQuery, editMessageText
+    }
+}
+test("two concurrent approvals resolve independently through one dispatcher", async () => {
+    const fake = new FakeTelegram();
+    const a = fake.request({ title: "Payment A", timeoutSec: 5 });
+    const b = fake.request({ title: "Payment B", timeoutSec: 5 });
+    // Wait until both messages are sent, then tap: deny A, approve B.
+    while (fake.sent.length < 2)
+        await new Promise((r) => setTimeout(r, 5));
+    fake.taps.push({ verdict: "no", nonce: fake.sent[0].nonce });
+    fake.taps.push({ verdict: "ok", nonce: fake.sent[1].nonce });
+    const [ra, rb] = await Promise.all([a, b]);
+    assert.deepEqual(ra, { approved: false, decision: "denied" });
+    assert.deepEqual(rb, { approved: true, decision: "approved" });
+});
+test("a tap from a foreign chat is ignored, and the request times out", async () => {
+    class ForeignChat extends FakeTelegram {
+        async api(method, params) {
+            if (method === "getUpdates" && this.sent.length) {
+                await new Promise((r) => setTimeout(r, 10));
+                return [
+                    {
+                        update_id: 999,
+                        callback_query: {
+                            id: "cb999",
+                            data: `ok:${this.sent[0].nonce}`,
+                            message: { chat: { id: 666 } }, // wrong chat
+                        },
+                    },
+                ];
+            }
+            return super.api(method, params);
+        }
+    }
+    const fake = new ForeignChat();
+    const result = await fake.request({ title: "Sensitive", timeoutSec: 1 });
+    assert.equal(result.decision, "timeout");
+    assert.equal(result.approved, false);
+});
+test("unanswered requests time out as denied", async () => {
+    const fake = new FakeTelegram();
+    const result = await fake.request({ title: "Silence", timeoutSec: 1 });
+    assert.deepEqual(result, { approved: false, decision: "timeout" });
+});

package/dist/totp.js

@@ -0,0 +1,28 @@
+import * as OTPAuth from "otpauth";
+/** Generate the current code for a stored seed. The seed never leaves this module's callers' memory. */
+export function generateCode(secret, opts) {
+    const totp = new OTPAuth.TOTP({
+        secret: OTPAuth.Secret.fromBase32(normalizeSecret(secret)),
+        digits: opts?.digits ?? 6,
+        period: opts?.period ?? 30,
+        algorithm: "SHA1",
+    });
+    const period = opts?.period ?? 30;
+    const now = Math.floor(Date.now() / 1000);
+    return {
+        code: totp.generate(),
+        secondsRemaining: period - (now % period),
+    };
+}
+/** Accept secrets pasted with spaces/dashes/lowercase, and full otpauth:// URIs. */
+export function normalizeSecret(input) {
+    const trimmed = input.trim();
+    if (trimmed.startsWith("otpauth://")) {
+        const url = new URL(trimmed);
+        const secret = url.searchParams.get("secret");
+        if (!secret)
+            throw new Error("otpauth:// URI has no secret parameter.");
+        return secret.toUpperCase();
+    }
+    return trimmed.replace(/[\s-]/g, "").toUpperCase();
+}

package/dist/vault.js

@@ -0,0 +1,46 @@
+import { scryptSync, randomBytes, createCipheriv, createDecipheriv, } from "node:crypto";
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { vaultPath } from "./paths.js";
+const SCRYPT_OPTS = { N: 2 ** 15, r: 8, p: 1, maxmem: 64 * 1024 * 1024 };
+function deriveKey(passphrase, salt) {
+    return scryptSync(passphrase, salt, 32, SCRYPT_OPTS);
+}
+export function vaultExists() {
+    return existsSync(vaultPath());
+}
+export function saveVault(passphrase, data) {
+    const salt = randomBytes(16);
+    const iv = randomBytes(12);
+    const key = deriveKey(passphrase, salt);
+    const cipher = createCipheriv("aes-256-gcm", key, iv);
+    const plaintext = Buffer.from(JSON.stringify(data), "utf8");
+    const encrypted = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    const file = {
+        version: 1,
+        kdf: "scrypt",
+        salt: salt.toString("base64"),
+        iv: iv.toString("base64"),
+        tag: cipher.getAuthTag().toString("base64"),
+        data: encrypted.toString("base64"),
+    };
+    writeFileSync(vaultPath(), JSON.stringify(file), { mode: 0o600 });
+}
+export function loadVault(passphrase) {
+    if (!vaultExists()) {
+        throw new Error(`No vault found at ${vaultPath()}. Run \`sandgate init\` first.`);
+    }
+    const file = JSON.parse(readFileSync(vaultPath(), "utf8"));
+    const key = deriveKey(passphrase, Buffer.from(file.salt, "base64"));
+    const decipher = createDecipheriv("aes-256-gcm", key, Buffer.from(file.iv, "base64"));
+    decipher.setAuthTag(Buffer.from(file.tag, "base64"));
+    try {
+        const plaintext = Buffer.concat([
+            decipher.update(Buffer.from(file.data, "base64")),
+            decipher.final(),
+        ]);
+        return JSON.parse(plaintext.toString("utf8"));
+    }
+    catch {
+        throw new Error("Could not unlock the vault: wrong passphrase.");
+    }
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@sandprivacy/sandgate",
+  "version": "0.1.0",
+  "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",
+  "bin": {
+    "sandgate": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "test": "npm run build && node scripts/test.mjs"
+  },
+  "homepage": "https://sandgate.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sandprivacy/sandgate.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sandprivacy/sandgate/issues"
+  },
+  "keywords": [
+    "mcp",
+    "ai-agents",
+    "human-in-the-loop",
+    "2fa",
+    "totp",
+    "approval",
+    "email-verification",
+    "browser-use",
+    "claude"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "imapflow": "^1.7.8",
+    "mailparser": "^3.9.20",
+    "otpauth": "^9.5.1",
+    "qrcode-terminal": "^0.12.0",
+    "read": "^5.0.1",
+    "web-push": "^3.6.7",
+    "zod": "^4.5.4"
+  },
+  "devDependencies": {
+    "@types/mailparser": "^3.4.6",
+    "@types/node": "^26.4.1",
+    "@types/qrcode-terminal": "^0.12.2",
+    "@types/web-push": "^3.6.4",
+    "tsx": "^4.23.13",
+    "typescript": "^7.0.2"
+  }
+}