@sandprivacy/sandgate 0.2.2 → 0.3.1

package/README.md

@@ -56,6 +56,24 @@ That's it. Your agent now has four new tools.
 
 **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.
 
+## Face ID / Touch ID on sensitive approvals (optional)
+
+A tap proves someone holds your unlocked phone. A biometric assertion
+proves it was *you*, on the *enrolled* device — and the gateway verifies
+it cryptographically instead of trusting the page:
+
+```bash
+sandgate enroll-biometric    # your phone asks; Face ID confirms
+sandgate biometric on        # now every approval must be signed
+```
+
+Each approval carries a WebAuthn assertion over a challenge derived from
+the request id, signed inside your phone's secure enclave. sandgate
+stores only the public key and checks the signature, the relying party,
+the challenge and the user-verification flag. Anything off — a replayed
+assertion, another device, a missing biometric — is a denial, never an
+approval. Off by default; `sandgate status` tells you where you stand.
+
 ## Policies
 
 ```bash
@@ -101,7 +119,8 @@ How the trust works: the pairing secret travels once, inside the URL **fragment*
 - [x] `sandgate audit` — pretty-print the audit trail
 - [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
+- [x] OS keychain for the vault passphrase (`SANDGATE_PASSPHRASE_CMD`, `sandgate protect`)
+- [x] Face ID / Touch ID on approvals, verified server-side (`sandgate enroll-biometric`)
 - [ ] 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)

package/dist/config.js

@@ -8,6 +8,7 @@ export const DEFAULT_CONFIG = {
         identityDefault: "auto",
     },
     approvalTimeoutSec: 120,
+    requireBiometric: false,
 };
 export function loadConfig() {
     if (!existsSync(configPath()))

package/dist/index.js

@@ -27,6 +27,8 @@ Usage:
   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 enroll-biometric              Enroll Face ID / Touch ID on the paired phone
+  sandgate biometric <on|off>            Require a verified biometric for every approval
   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)
@@ -254,6 +256,41 @@ async function cmdProtect() {
     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 cmdEnrollBiometric() {
+    const prompter = new Prompter();
+    const pass = await getPassphrase(prompter);
+    prompter.close();
+    const data = loadVault(pass);
+    if (!data.pwa) {
+        console.error("Biometrics need the PWA channel. Run `sandgate pair <relay-url>` first.");
+        process.exit(1);
+    }
+    const { PwaApprover } = await import("./pwa-approver.js");
+    const approver = new PwaApprover(data.pwa);
+    console.log("Sent to your phone — tap Enable and confirm with Face ID / Touch ID (2 min)…");
+    const credential = await approver.enroll(120);
+    if (!credential) {
+        console.error("Not enrolled (declined or timed out).");
+        process.exit(1);
+    }
+    data.biometric = credential;
+    saveVault(pass, data);
+    console.log(`Enrolled. sandgate stored only the public key (${credential.rpId}).
+` +
+        "Turn enforcement on with: sandgate biometric on");
+}
+async function cmdBiometric(mode) {
+    if (mode !== "on" && mode !== "off") {
+        console.error("Usage: sandgate biometric <on|off>");
+        process.exit(1);
+    }
+    const config = loadConfig();
+    config.requireBiometric = mode === "on";
+    saveConfig(config);
+    console.log(mode === "on"
+        ? "Biometric approvals required. Every approval must now be signed by the enrolled device."
+        : "Biometric requirement off. A tap is enough again.");
+}
 async function cmdStatus() {
     if (!vaultExists()) {
         console.log("No vault. Run `sandgate init` to get started.");
@@ -289,6 +326,13 @@ async function cmdStatus() {
                     .map(([d, p]) => `${d}=${p}`)
                     .join(", ")
             : ""));
+    console.log(`  biometric          ${config.requireBiometric
+        ? data.biometric
+            ? "required (enrolled)"
+            : "REQUIRED BUT NOT ENROLLED — run `sandgate enroll-biometric`"
+        : data.biometric
+            ? "enrolled, not enforced"
+            : "off"}`);
     console.log(`  audit entries      ${auditCount}`);
 }
 async function cmdAudit(countArg) {
@@ -379,9 +423,12 @@ async function cmdTestApproval() {
     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)…");
+        const { pwaApproverFrom } = await import("./pwa-approver.js");
+        const config = loadConfig();
+        approver = pwaApproverFrom(data, config);
+        console.log(config.requireBiometric
+            ? "Sending test approval to the paired PWA — Face ID required (60s timeout)…"
+            : "Sending test approval to the paired PWA (60s timeout)…");
     }
     else if (data.telegram) {
         approver = new TelegramApprover(data.telegram.botToken, data.telegram.chatId);
@@ -423,6 +470,10 @@ async function main() {
             return cmdRekey();
         case "protect":
             return cmdProtect();
+        case "enroll-biometric":
+            return cmdEnrollBiometric();
+        case "biometric":
+            return cmdBiometric(args[0]);
         case "status":
             return cmdStatus();
         case "audit":

package/dist/pwa-approver.js

@@ -1,5 +1,6 @@
 import { randomBytes } from "node:crypto";
 import { deriveKey, seal, open, aadForRequest, aadForDecision } from "./pwacrypto.js";
+import { verifyAssertion, verifyEnrollment, } from "./webauthn.js";
 export class PwaApprover {
     config;
     key;
@@ -13,7 +14,18 @@ export class PwaApprover {
     /** 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, { kind, title: req.title, body: req.body, timeoutSec: req.timeoutSec, ts: Date.now() }, aadForRequest(requestId));
+        // Biometric enforcement travels inside the sealed request: the relay
+        // cannot see it, and the phone cannot be told to skip it by anyone else.
+        const needsBiometric = kind !== "enroll" && !!this.config.requireBiometric;
+        const sealed = seal(this.key, {
+            kind,
+            title: req.title,
+            body: req.body,
+            timeoutSec: req.timeoutSec,
+            ts: Date.now(),
+            requireBiometric: needsBiometric,
+            credentialId: needsBiometric ? this.config.biometric?.credentialId : undefined,
+        }, aadForRequest(requestId));
         const post = await fetch(this.url("/api/request"), {
             method: "POST",
             headers: { "Content-Type": "application/json" },
@@ -34,26 +46,72 @@ export class PwaApprover {
             const decision = open(this.key, payload, aadForDecision(requestId));
             if (decision.requestId !== requestId)
                 continue; // belt and suspenders; AAD already binds it
-            return decision;
+            if (needsBiometric && decision.approved) {
+                // Fail closed: an approval without a verifiable assertion is not
+                // an approval. verifyAssertion throws on anything suspicious.
+                if (!this.config.biometric) {
+                    throw new Error("Biometric approval is required but no credential is enrolled. Run `sandgate enroll-biometric`.");
+                }
+                if (!decision.assertion) {
+                    throw new Error("Approval arrived without the required biometric assertion.");
+                }
+                verifyAssertion(decision.assertion, this.config.biometric, requestId);
+            }
+            return { requestId, decision };
         }
         return null;
     }
     async request(req) {
-        const decision = await this.roundTrip("approval", req);
-        if (!decision)
+        const result = await this.roundTrip("approval", req);
+        if (!result)
             return { approved: false, decision: "timeout" };
         return {
-            approved: decision.approved,
-            decision: decision.approved ? "approved" : "denied",
+            approved: result.decision.approved,
+            decision: result.decision.approved ? "approved" : "denied",
         };
     }
     async ask(req) {
-        const decision = await this.roundTrip("input", req);
-        if (!decision)
+        const result = await this.roundTrip("input", req);
+        if (!result)
             return { answer: null, decision: "timeout" };
+        const { decision } = result;
         if (!decision.approved || typeof decision.answer !== "string") {
             return { answer: null, decision: "denied" };
         }
         return { answer: decision.answer, decision: "answered" };
     }
+    /**
+     * Enroll the phone's platform authenticator. Returns the credential to
+     * store in the vault, or null if the human declined or let it expire.
+     */
+    async enroll(timeoutSec) {
+        const result = await this.roundTrip("enroll", {
+            title: "Enable Face ID / Touch ID approvals",
+            body: "Your device will sign approvals from now on. sandgate stores only the public key.",
+            timeoutSec,
+        });
+        if (!result)
+            return null;
+        const { requestId, decision } = result;
+        if (!decision.approved || !decision.enrollment)
+            return null;
+        return verifyEnrollment(decision.enrollment, {
+            requestId,
+            origin: new URL(this.config.relayUrl).origin,
+        });
+    }
+}
+/**
+ * Build the PWA approver from vault + config. Everything that talks to the
+ * phone goes through here: when `serve` and the CLI each assembled their
+ * own config, the CLI silently lost biometric enforcement.
+ */
+export function pwaApproverFrom(vault, config) {
+    if (!vault.pwa)
+        return null;
+    return new PwaApprover({
+        ...vault.pwa,
+        biometric: vault.biometric,
+        requireBiometric: config.requireBiometric,
+    });
 }

package/dist/relay/pwa-page.js

@@ -410,6 +410,69 @@ export const PWA_HTML = `<!doctype html>
     return { iv: bytesToB64u(iv), ct: bytesToB64u(ct) };
   }
 
+  // --- WebAuthn ceremonies (Face ID / Touch ID) ---------------------------
+  // The challenge is derived from the request id on both sides, so an
+  // assertion is worthless on any other request. sandgate only ever sees
+  // the public key: the private key never leaves the secure enclave.
+  async function webauthnChallenge(requestId) {
+    var digest = await crypto.subtle.digest(
+      "SHA-256",
+      enc.encode("sandgate-webauthn-v1:" + requestId)
+    );
+    return new Uint8Array(digest);
+  }
+
+  async function doEnroll(requestId) {
+    if (!window.PublicKeyCredential) throw new Error("this device has no passkey support");
+    var cred = await navigator.credentials.create({
+      publicKey: {
+        challenge: await webauthnChallenge(requestId),
+        rp: { id: location.hostname, name: "sandgate" },
+        user: {
+          id: crypto.getRandomValues(new Uint8Array(16)),
+          name: "sandgate",
+          displayName: "sandgate",
+        },
+        pubKeyCredParams: [{ type: "public-key", alg: -7 }],
+        authenticatorSelection: {
+          authenticatorAttachment: "platform",
+          userVerification: "required",
+          residentKey: "discouraged",
+        },
+        attestation: "none",
+        timeout: 60000,
+      },
+    });
+    var spki = cred.response.getPublicKey && cred.response.getPublicKey();
+    if (!spki) throw new Error("this device did not expose the public key");
+    return {
+      credentialId: bytesToB64u(cred.rawId),
+      publicKeySpki: bytesToB64u(spki),
+      clientDataJSON: bytesToB64u(cred.response.clientDataJSON),
+    };
+  }
+
+  async function doAssert(requestId, credentialId) {
+    if (!window.PublicKeyCredential) throw new Error("this device has no passkey support");
+    var assertion = await navigator.credentials.get({
+      publicKey: {
+        challenge: await webauthnChallenge(requestId),
+        rpId: location.hostname,
+        allowCredentials: credentialId
+          ? [{ type: "public-key", id: b64uToBytes(credentialId) }]
+          : undefined,
+        userVerification: "required",
+        timeout: 60000,
+      },
+    });
+    return {
+      credentialId: bytesToB64u(assertion.rawId),
+      authenticatorData: bytesToB64u(assertion.response.authenticatorData),
+      clientDataJSON: bytesToB64u(assertion.response.clientDataJSON),
+      signature: bytesToB64u(assertion.response.signature),
+    };
+  }
+
   // --- presence + push subscription ---------------------------------------
   // Announce this page to the relay immediately (push or not), so the
   // "sandgate pair" command can report "phone connected" without waiting
@@ -593,13 +656,20 @@ export const PWA_HTML = `<!doctype html>
 
   function addCard(id, p, requestId, req) {
     var isInput = req.kind === "input";
+    var isEnroll = req.kind === "enroll";
     var card = document.createElement("div");
     card.className = "card";
 
     var who = document.createElement("div"); who.className = "who";
     who.textContent =
       (pairs.length > 1 ? p.name + " · " : "") +
-      (isInput ? "agent · question" : "agent · approval request");
+      (isEnroll
+        ? "sandgate · setup"
+        : isInput
+          ? "agent · question"
+          : req.requireBiometric
+            ? "agent · approval · Face ID"
+            : "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
@@ -607,7 +677,7 @@ export const PWA_HTML = `<!doctype html>
     if (req.body) { var bodyP = document.createElement("p"); bodyP.textContent = req.body; card.appendChild(bodyP); }
 
     var input = null;
-    if (isInput) {
+    if (isInput && !isEnroll) {
       input = document.createElement("input");
       input.className = "answer-input";
       input.placeholder = "Your answer";
@@ -623,7 +693,20 @@ export const PWA_HTML = `<!doctype html>
     card.appendChild(timer);
 
     var row = document.createElement("div"); row.className = "row";
-    if (isInput) {
+    if (isEnroll) {
+      row.appendChild(makeActionBtn("Enable", "ok", CHECK, function (btn) {
+        btn.disabled = true;
+        doEnroll(requestId).then(function (enrollment) {
+          submitDecision(id, { requestId: requestId, approved: true, ts: Date.now(), enrollment: enrollment }, "approved", btn);
+        }).catch(function (e) {
+          btn.disabled = false;
+          alert("Could not enable Face ID: " + (e && e.message ? e.message : e));
+        });
+      }));
+      row.appendChild(makeActionBtn("Not now", "no", CROSS, function (btn) {
+        submitDecision(id, { requestId: requestId, approved: false, ts: Date.now() }, "denied", btn);
+      }));
+    } else if (isInput) {
       var sendBtn = makeActionBtn("Send", "ok", CHECK, function (btn) {
         var value = input.value.trim();
         if (!value) { input.focus(); return; }
@@ -637,8 +720,18 @@ export const PWA_HTML = `<!doctype html>
         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(req.requireBiometric ? "Approve with Face ID" : "Approve", "ok", CHECK, function (btn) {
+        if (!req.requireBiometric) {
+          submitDecision(id, { requestId: requestId, approved: true, ts: Date.now() }, "approved", btn);
+          return;
+        }
+        btn.disabled = true;
+        doAssert(requestId, req.credentialId).then(function (assertion) {
+          submitDecision(id, { requestId: requestId, approved: true, ts: Date.now(), assertion: assertion }, "approved", btn);
+        }).catch(function (e) {
+          btn.disabled = false;
+          alert("Face ID check failed, approval not sent: " + (e && e.message ? e.message : e));
+        });
       }));
       row.appendChild(makeActionBtn("Deny", "no", CROSS, function (btn) {
         submitDecision(id, { requestId: requestId, approved: false, ts: Date.now() }, "denied", btn);

package/dist/server.js

@@ -5,7 +5,7 @@ import { loadVault } from "./vault.js";
 import { loadConfig, totpPolicy } from "./config.js";
 import { generateCode } from "./totp.js";
 import { TelegramApprover } from "./telegram.js";
-import { PwaApprover } from "./pwa-approver.js";
+import { pwaApproverFrom } from "./pwa-approver.js";
 import { backendFromVault } from "./inbox.js";
 import { audit } from "./audit.js";
 /**
@@ -23,9 +23,13 @@ function refusal(message) {
 export async function serve(passphrase) {
     const vault = loadVault(passphrase);
     const config = loadConfig();
+    if (config.requireBiometric && !vault.biometric) {
+        // Fail closed rather than silently downgrade to a plain tap.
+        throw new Error("requireBiometric is on but no credential is enrolled. Run `sandgate enroll-biometric`, or turn it off with `sandgate biometric off`.");
+    }
     // PWA (E2EE push) wins over Telegram when both are configured.
     const approver = vault.pwa
-        ? new PwaApprover(vault.pwa)
+        ? pwaApproverFrom(vault, config)
         : vault.telegram
             ? new TelegramApprover(vault.telegram.botToken, vault.telegram.chatId)
             : null;

package/dist/test/approver-wiring.test.js

@@ -0,0 +1,111 @@
+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 { pwaApproverFrom } from "../pwa-approver.js";
+import { DEFAULT_CONFIG } from "../config.js";
+/**
+ * Guards the wiring, not the crypto: enforcement must reach the phone
+ * from every entry point. `sandgate test-approval` once built its own
+ * approver config and quietly dropped requireBiometric, so an enforced
+ * vault still accepted a bare tap. One builder now serves serve() and the
+ * CLI, and this test fails if it ever stops enforcing.
+ */
+const CREDENTIAL = {
+    credentialId: "unused-for-this-test",
+    publicKeySpki: "unused-for-this-test",
+    rpId: "localhost",
+    origin: "http://localhost",
+    enrolledAt: new Date().toISOString(),
+};
+/** A phone that taps Approve without producing any assertion. */
+async function tapWithoutAssertion(relayUrl, pairId, secret) {
+    const key = deriveKey(secret);
+    for (let i = 0; i < 100; i++) {
+        const res = await fetch(`${relayUrl}/api/pending?pairId=${pairId}`);
+        const items = (await res.json());
+        if (items.length) {
+            const { requestId, payload } = items[0];
+            const request = open(key, payload, aadForRequest(requestId));
+            await fetch(`${relayUrl}/api/decision`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    pairId,
+                    requestId,
+                    payload: seal(key, { requestId, approved: true, ts: Date.now() }, aadForDecision(requestId)),
+                }),
+            });
+            return request;
+        }
+        await new Promise((r) => setTimeout(r, 50));
+    }
+    throw new Error("phone never saw a request");
+}
+/** Settle a promise without ever leaving a rejection unhandled. */
+function settled(p) {
+    return p.then((value) => ({ value }), (error) => ({ error }));
+}
+async function withRelay(fn) {
+    const relay = await startRelay({
+        port: 0,
+        stateDir: mkdtempSync(join(tmpdir(), "sandgate-relay-")),
+    });
+    try {
+        return await fn(`http://localhost:${relay.port}`);
+    }
+    finally {
+        relay.close();
+    }
+}
+test("an enforced vault rejects an approval that carries no assertion", async () => {
+    await withRelay(async (relayUrl) => {
+        const pairing = newPairing();
+        const vault = {
+            totp: {},
+            pwa: { relayUrl, pairId: pairing.pairId, secret: pairing.secret },
+            biometric: CREDENTIAL,
+        };
+        const approver = pwaApproverFrom(vault, { ...DEFAULT_CONFIG, requireBiometric: true });
+        const deciding = settled(approver.request({ title: "Pay 300 EUR", timeoutSec: 15 }));
+        const request = await tapWithoutAssertion(relayUrl, pairing.pairId, pairing.secret);
+        // The phone must be TOLD to ask for biometrics...
+        assert.equal(request.requireBiometric, true, "the request did not demand a biometric");
+        // ...and a bare tap must not pass for an approval.
+        const outcome = await deciding;
+        assert.equal(outcome.value, undefined, "a bare tap was accepted as an approval");
+        assert.match(String(outcome.error), /without the required biometric assertion/);
+    });
+});
+test("without enforcement, the same tap is a normal approval", async () => {
+    await withRelay(async (relayUrl) => {
+        const pairing = newPairing();
+        const vault = {
+            totp: {},
+            pwa: { relayUrl, pairId: pairing.pairId, secret: pairing.secret },
+        };
+        const approver = pwaApproverFrom(vault, { ...DEFAULT_CONFIG, requireBiometric: false });
+        const deciding = settled(approver.request({ title: "Harmless", timeoutSec: 15 }));
+        const request = await tapWithoutAssertion(relayUrl, pairing.pairId, pairing.secret);
+        assert.equal(request.requireBiometric, false);
+        assert.deepEqual((await deciding).value, { approved: true, decision: "approved" });
+    });
+});
+test("enforcement without an enrolled credential refuses instead of downgrading", async () => {
+    await withRelay(async (relayUrl) => {
+        const pairing = newPairing();
+        const vault = {
+            totp: {},
+            pwa: { relayUrl, pairId: pairing.pairId, secret: pairing.secret },
+        };
+        const approver = pwaApproverFrom(vault, { ...DEFAULT_CONFIG, requireBiometric: true });
+        const deciding = settled(approver.request({ title: "Pay 300 EUR", timeoutSec: 15 }));
+        await tapWithoutAssertion(relayUrl, pairing.pairId, pairing.secret);
+        const outcome = await deciding;
+        assert.equal(outcome.value, undefined, "an unenrolled vault approved anyway");
+        assert.match(String(outcome.error), /no credential is enrolled/);
+    });
+});

package/dist/test/helpers/page.js

@@ -0,0 +1,55 @@
+import { webcrypto } from "node:crypto";
+import { JSDOM } from "jsdom";
+import { PWA_HTML } from "../../relay/pwa-page.js";
+/**
+ * Loads the REAL page script into a DOM wired to a REAL relay: this is the
+ * layer that caught nothing while it didn't exist, and now gates releases.
+ */
+export async function loadPage(relayUrl, opts) {
+    const alerts = [];
+    const dom = new JSDOM(PWA_HTML, {
+        url: relayUrl + "/" + (opts.hash ?? ""),
+        runScripts: "outside-only",
+        pretendToBeVisual: true,
+    });
+    const w = dom.window;
+    // The pieces jsdom doesn't ship, wired to the real relay / real crypto.
+    w.fetch = (input, init) => fetch(new URL(input, relayUrl), init);
+    Object.defineProperty(w, "crypto", { value: webcrypto });
+    w.alert = (message) => alerts.push(String(message));
+    w.confirm = () => true;
+    if (opts.localStorage) {
+        for (const [key, value] of Object.entries(opts.localStorage)) {
+            w.localStorage.setItem(key, value);
+        }
+    }
+    // Execute the page's inline script exactly as a browser would. The
+    // decision alert is instrumented to carry the full stack: a one-line
+    // message told us nothing the day this layer was missing.
+    let script = dom.window.document.querySelector("script").textContent;
+    script = script.replace('alert("Could not send your decision: " + (err && err.message ? err.message : err));', 'alert("Could not send your decision: " + (err && err.stack ? err.stack : err));');
+    dom.window.eval(script);
+    // window.close() tears down the page's setIntervals so the test process
+    // can exit; without it the suite hangs forever.
+    return { window: w, alerts, close: () => dom.window.close() };
+}
+/**
+ * Without EventSource in jsdom the page falls back to its 8s poll, so give
+ * waits comfortable room past that boundary.
+ */
+export function waitFor(fn, ms = 15000) {
+    return new Promise((resolve, reject) => {
+        const started = Date.now();
+        const timer = setInterval(() => {
+            const value = fn();
+            if (value) {
+                clearInterval(timer);
+                resolve(value);
+            }
+            else if (Date.now() - started > ms) {
+                clearInterval(timer);
+                reject(new Error("waitFor timed out"));
+            }
+        }, 50);
+    });
+}

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

@@ -0,0 +1,170 @@
+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 { createHash, generateKeyPairSync, sign as cryptoSign } from "node:crypto";
+import { newPairing } from "../pwacrypto.js";
+import { startRelay } from "../relay/server.js";
+import { PwaApprover } from "../pwa-approver.js";
+import { loadPage, waitFor } from "./helpers/page.js";
+/**
+ * Browser-level biometric tests: the real page script runs the real
+ * WebAuthn ceremonies against a simulated platform authenticator (same
+ * key type, same signed payload as a Face ID enclave), and the real
+ * gateway verifies the result. Covers enrollment, a genuine approval,
+ * and — the one that matters — an authenticator that is not the enrolled
+ * one being rejected.
+ */
+function b64u(buf) {
+    return Buffer.from(buf).toString("base64url");
+}
+/** Install a fake platform authenticator into a jsdom window. */
+function installAuthenticator(window, opts) {
+    const origin = window.location.origin;
+    const rpIdHash = createHash("sha256").update(window.location.hostname).digest();
+    const clientData = (type, challenge) => Buffer.from(JSON.stringify({ type, challenge: b64u(challenge), origin }), "utf8");
+    window.PublicKeyCredential = function () { };
+    Object.defineProperty(window.navigator, "credentials", {
+        configurable: true,
+        value: {
+            async create(request) {
+                const cd = clientData("webauthn.create", request.publicKey.challenge);
+                return {
+                    rawId: opts.credentialId,
+                    response: {
+                        clientDataJSON: cd,
+                        getPublicKey: () => opts.publicKeySpki,
+                    },
+                };
+            },
+            async get(request) {
+                const cd = clientData("webauthn.get", request.publicKey.challenge);
+                const authData = Buffer.concat([rpIdHash, Buffer.from([0x05]), Buffer.alloc(4)]);
+                const signed = Buffer.concat([authData, createHash("sha256").update(cd).digest()]);
+                return {
+                    rawId: opts.credentialId,
+                    response: {
+                        authenticatorData: authData,
+                        clientDataJSON: cd,
+                        signature: cryptoSign("sha256", signed, opts.signingKey),
+                    },
+                };
+            },
+        },
+    });
+}
+function keypair() {
+    const { privateKey, publicKey } = generateKeyPairSync("ec", { namedCurve: "P-256" });
+    return {
+        signingKey: privateKey,
+        publicKeySpki: publicKey.export({ format: "der", type: "spki" }),
+    };
+}
+async function withRelay(fn) {
+    const relay = await startRelay({
+        port: 0,
+        stateDir: mkdtempSync(join(tmpdir(), "sandgate-relay-")),
+    });
+    try {
+        return await fn(`http://localhost:${relay.port}`);
+    }
+    finally {
+        relay.close();
+    }
+}
+test("enrollment through the page yields a credential the gateway trusts", async () => {
+    await withRelay(async (relayUrl) => {
+        const pairing = newPairing();
+        const { window, alerts, close } = await loadPage(relayUrl, {
+            hash: `#p=${pairing.pairId}&s=${pairing.secret}`,
+        });
+        try {
+            const device = keypair();
+            installAuthenticator(window, { ...device, credentialId: Buffer.from("cred-1") });
+            const approver = new PwaApprover({ relayUrl, pairId: pairing.pairId, secret: pairing.secret });
+            const enrolling = approver.enroll(20);
+            const enableBtn = await waitFor(() => window.document.querySelector(".card button.ok"));
+            assert.match(window.document.querySelector(".card .who").textContent, /setup/);
+            enableBtn.click();
+            const credential = await enrolling;
+            assert.ok(credential, "enrollment returned nothing");
+            assert.equal(credential.rpId, "localhost");
+            assert.equal(credential.publicKeySpki, b64u(device.publicKeySpki));
+            assert.deepEqual(alerts, [], `page alerted: ${alerts.join(" | ")}`);
+        }
+        finally {
+            close();
+        }
+    });
+});
+test("with biometrics required, an approval signed by the enrolled device is accepted", async () => {
+    await withRelay(async (relayUrl) => {
+        const pairing = newPairing();
+        const device = keypair();
+        const credentialId = Buffer.from("cred-1");
+        // 1. Enroll.
+        const enrollPage = await loadPage(relayUrl, { hash: `#p=${pairing.pairId}&s=${pairing.secret}` });
+        installAuthenticator(enrollPage.window, { ...device, credentialId });
+        const enroller = new PwaApprover({ relayUrl, pairId: pairing.pairId, secret: pairing.secret });
+        const enrolling = enroller.enroll(20);
+        (await waitFor(() => enrollPage.window.document.querySelector(".card button.ok"))).click();
+        const credential = await enrolling;
+        enrollPage.close();
+        assert.ok(credential);
+        // 2. Approve, biometrics enforced.
+        const page = await loadPage(relayUrl, { hash: `#p=${pairing.pairId}&s=${pairing.secret}` });
+        installAuthenticator(page.window, { ...device, credentialId });
+        try {
+            const approver = new PwaApprover({
+                relayUrl,
+                pairId: pairing.pairId,
+                secret: pairing.secret,
+                biometric: credential,
+                requireBiometric: true,
+            });
+            const deciding = approver.request({ title: "Pay 300 EUR", timeoutSec: 20 });
+            const approveBtn = await waitFor(() => page.window.document.querySelector(".card button.ok"));
+            assert.match(approveBtn.textContent, /Face ID/);
+            approveBtn.click();
+            assert.deepEqual(await deciding, { approved: true, decision: "approved" });
+            assert.deepEqual(page.alerts, [], `page alerted: ${page.alerts.join(" | ")}`);
+        }
+        finally {
+            page.close();
+        }
+    });
+});
+test("an approval signed by a different authenticator is refused, fail closed", async () => {
+    await withRelay(async (relayUrl) => {
+        const pairing = newPairing();
+        const enrolledDevice = keypair();
+        const credentialId = Buffer.from("cred-1");
+        const enrollPage = await loadPage(relayUrl, { hash: `#p=${pairing.pairId}&s=${pairing.secret}` });
+        installAuthenticator(enrollPage.window, { ...enrolledDevice, credentialId });
+        const enroller = new PwaApprover({ relayUrl, pairId: pairing.pairId, secret: pairing.secret });
+        const enrolling = enroller.enroll(20);
+        (await waitFor(() => enrollPage.window.document.querySelector(".card button.ok"))).click();
+        const credential = await enrolling;
+        enrollPage.close();
+        // The phone now signs with someone else's key — a stolen page, a
+        // tampered client. The gateway must not accept it as an approval.
+        const page = await loadPage(relayUrl, { hash: `#p=${pairing.pairId}&s=${pairing.secret}` });
+        installAuthenticator(page.window, { ...keypair(), credentialId });
+        try {
+            const approver = new PwaApprover({
+                relayUrl,
+                pairId: pairing.pairId,
+                secret: pairing.secret,
+                biometric: credential,
+                requireBiometric: true,
+            });
+            const deciding = approver.request({ title: "Pay 300 EUR", timeoutSec: 20 });
+            (await waitFor(() => page.window.document.querySelector(".card button.ok"))).click();
+            await assert.rejects(deciding, /does not verify/);
+        }
+        finally {
+            page.close();
+        }
+    });
+});

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

@@ -3,64 +3,16 @@ import assert from "node:assert/strict";
 import { mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { webcrypto } from "node:crypto";
-import { JSDOM } from "jsdom";
 import { newPairing } from "../pwacrypto.js";
 import { startRelay } from "../relay/server.js";
-import { PWA_HTML } from "../relay/pwa-page.js";
 import { PwaApprover } from "../pwa-approver.js";
+import { loadPage, waitFor } from "./helpers/page.js";
 /**
  * Browser-level tests: the REAL page script, executed in a DOM, against a
  * REAL relay — pairing via URL fragment, card rendering, a click on
  * Approve/Deny, and the legacy-storage migration. This is the layer that
  * caught nothing while it didn't exist; it exists now.
  */
-async function loadPage(relayUrl, opts) {
-    const alerts = [];
-    const dom = new JSDOM(PWA_HTML, {
-        url: relayUrl + "/" + (opts.hash ?? ""),
-        runScripts: "outside-only",
-        pretendToBeVisual: true,
-    });
-    const w = dom.window;
-    // The pieces jsdom doesn't ship, wired to the real relay / real crypto.
-    w.fetch = (input, init) => fetch(new URL(input, relayUrl), init);
-    Object.defineProperty(w, "crypto", { value: webcrypto });
-    w.alert = (message) => alerts.push(String(message));
-    w.confirm = () => true;
-    if (opts.localStorage) {
-        for (const [key, value] of Object.entries(opts.localStorage)) {
-            w.localStorage.setItem(key, value);
-        }
-    }
-    // Execute the page's inline script exactly as a browser would. The
-    // decision alert is instrumented to carry the full stack: a one-line
-    // message told us nothing the day this layer was missing.
-    let script = dom.window.document.querySelector("script").textContent;
-    script = script.replace('alert("Could not send your decision: " + (err && err.message ? err.message : err));', 'alert("Could not send your decision: " + (err && err.stack ? err.stack : err));');
-    dom.window.eval(script);
-    // window.close() tears down the page's setIntervals so the test process
-    // can exit; without it the suite hangs forever.
-    return { window: w, alerts, close: () => dom.window.close() };
-}
-// Without EventSource in jsdom the page falls back to its 8s poll, so give
-// waits comfortable room past that boundary.
-function waitFor(fn, ms = 15000) {
-    return new Promise((resolve, reject) => {
-        const started = Date.now();
-        const timer = setInterval(() => {
-            const value = fn();
-            if (value) {
-                clearInterval(timer);
-                resolve(value);
-            }
-            else if (Date.now() - started > ms) {
-                clearInterval(timer);
-                reject(new Error("waitFor timed out"));
-            }
-        }, 50);
-    });
-}
 for (const scenario of ["fragment", "legacy-storage"]) {
     test(`page pairs (${scenario}), renders the card, and Approve round-trips`, async () => {
         const relay = await startRelay({

package/dist/test/webauthn.test.js

@@ -0,0 +1,100 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { createHash, generateKeyPairSync, sign as cryptoSign } from "node:crypto";
+import { challengeFor, verifyEnrollment, verifyAssertion, } from "../webauthn.js";
+/**
+ * A synthetic platform authenticator: same key type (ES256), same signed
+ * payload layout (authenticatorData || SHA256(clientDataJSON)), same DER
+ * signatures as a real Face ID enclave. It lets us test the verification
+ * path — including every rejection — without a physical device.
+ */
+const ORIGIN = "https://relay.sandgate.dev";
+const RP_ID = "relay.sandgate.dev";
+function b64u(buf) {
+    return Buffer.from(buf).toString("base64url");
+}
+function makeAuthenticator() {
+    const { privateKey, publicKey } = generateKeyPairSync("ec", { namedCurve: "P-256" });
+    const spki = publicKey.export({ format: "der", type: "spki" });
+    const credentialId = b64u(Buffer.from("credential-id-bytes"));
+    const clientData = (type, challenge, origin = ORIGIN) => b64u(Buffer.from(JSON.stringify({ type, challenge, origin }), "utf8"));
+    const authData = (opts) => {
+        const data = Buffer.alloc(37);
+        createHash("sha256").update(opts?.rpId ?? RP_ID).digest().copy(data, 0);
+        data[32] = opts?.flags ?? 0x05; // UP | UV
+        return data;
+    };
+    return {
+        credentialId,
+        publicKeySpki: b64u(spki),
+        enroll: (requestId) => ({
+            credentialId,
+            publicKeySpki: b64u(spki),
+            clientDataJSON: clientData("webauthn.create", challengeFor(requestId)),
+        }),
+        assert: (requestId, opts) => {
+            const cd = clientData(opts?.type ?? "webauthn.get", challengeFor(requestId), opts?.origin);
+            const ad = authData(opts);
+            const signed = Buffer.concat([
+                ad,
+                createHash("sha256").update(Buffer.from(cd, "base64url")).digest(),
+            ]);
+            const signature = cryptoSign("sha256", signed, privateKey);
+            if (opts?.tamper)
+                signature[signature.length - 1] ^= 0xff;
+            return {
+                credentialId,
+                authenticatorData: b64u(ad),
+                clientDataJSON: cd,
+                signature: b64u(signature),
+            };
+        },
+    };
+}
+function enrolled(auth) {
+    return verifyEnrollment(auth.enroll("enroll-req"), {
+        requestId: "enroll-req",
+        origin: ORIGIN,
+    });
+}
+test("enrollment yields a usable credential bound to the relay", () => {
+    const cred = enrolled(makeAuthenticator());
+    assert.equal(cred.rpId, RP_ID);
+    assert.equal(cred.origin, ORIGIN);
+    assert.ok(cred.publicKeySpki.length > 0);
+});
+test("enrollment for another request or origin is rejected", () => {
+    const auth = makeAuthenticator();
+    assert.throws(() => verifyEnrollment(auth.enroll("req-a"), { requestId: "req-b", origin: ORIGIN }), /Challenge mismatch/);
+    assert.throws(() => verifyEnrollment(auth.enroll("req-a"), { requestId: "req-a", origin: "https://evil.example" }), /Unexpected origin/);
+});
+test("a genuine assertion for the right request verifies", () => {
+    const auth = makeAuthenticator();
+    const cred = enrolled(auth);
+    verifyAssertion(auth.assert("req-1"), cred, "req-1"); // must not throw
+});
+test("an assertion cannot be replayed on another request", () => {
+    const auth = makeAuthenticator();
+    const cred = enrolled(auth);
+    assert.throws(() => verifyAssertion(auth.assert("req-1"), cred, "req-2"), /Challenge mismatch/);
+});
+test("a tampered signature is rejected", () => {
+    const auth = makeAuthenticator();
+    const cred = enrolled(auth);
+    assert.throws(() => verifyAssertion(auth.assert("req-1", { tamper: true }), cred, "req-1"), /does not verify/);
+});
+test("an assertion without the user-verification flag is rejected", () => {
+    const auth = makeAuthenticator();
+    const cred = enrolled(auth);
+    assert.throws(() => verifyAssertion(auth.assert("req-1", { flags: 0x01 }), cred, "req-1"), /User verification flag missing/);
+});
+test("an assertion signed for another relying party is rejected", () => {
+    const auth = makeAuthenticator();
+    const cred = enrolled(auth);
+    assert.throws(() => verifyAssertion(auth.assert("req-1", { rpId: "phish.example" }), cred, "req-1"), /different relying party/);
+});
+test("another authenticator's assertion is rejected", () => {
+    const cred = enrolled(makeAuthenticator());
+    const attacker = makeAuthenticator();
+    assert.throws(() => verifyAssertion(attacker.assert("req-1"), cred, "req-1"), /does not verify/);
+});

package/dist/webauthn.js

@@ -0,0 +1,83 @@
+import { createHash, createPublicKey, verify as cryptoVerify } from "node:crypto";
+/** Deterministic per-request challenge: both sides derive it from the request id. */
+export function challengeFor(requestId) {
+    return createHash("sha256")
+        .update("sandgate-webauthn-v1:" + requestId)
+        .digest("base64url");
+}
+function parseClientData(b64url) {
+    const json = Buffer.from(b64url, "base64url").toString("utf8");
+    const data = JSON.parse(json);
+    if (typeof data.type !== "string" || typeof data.challenge !== "string") {
+        throw new Error("Malformed clientDataJSON.");
+    }
+    return data;
+}
+function checkClientData(evidence, expected) {
+    const data = parseClientData(evidence.clientDataJSON);
+    if (data.type !== expected.type) {
+        throw new Error(`Wrong ceremony type: ${data.type}.`);
+    }
+    if (data.challenge !== expected.challenge) {
+        throw new Error("Challenge mismatch (assertion is not for this request).");
+    }
+    if (data.origin !== expected.origin) {
+        throw new Error(`Unexpected origin: ${data.origin}.`);
+    }
+}
+/** Validate an enrollment and produce the record to store in the vault. */
+export function verifyEnrollment(evidence, expected) {
+    checkClientData(evidence, {
+        type: "webauthn.create",
+        challenge: challengeFor(expected.requestId),
+        origin: expected.origin,
+    });
+    const spki = Buffer.from(evidence.publicKeySpki, "base64url");
+    createPublicKey({ key: spki, format: "der", type: "spki" }); // throws if unusable
+    return {
+        credentialId: evidence.credentialId,
+        publicKeySpki: evidence.publicKeySpki,
+        rpId: new URL(expected.origin).hostname,
+        origin: expected.origin,
+        enrolledAt: new Date().toISOString(),
+    };
+}
+/**
+ * Verify an assertion for a given request. Throws on any failure — callers
+ * treat a throw as a denial, never as an approval.
+ */
+export function verifyAssertion(evidence, credential, requestId) {
+    if (evidence.credentialId !== credential.credentialId) {
+        throw new Error("Assertion from an unknown credential.");
+    }
+    checkClientData(evidence, {
+        type: "webauthn.get",
+        challenge: challengeFor(requestId),
+        origin: credential.origin,
+    });
+    const authData = Buffer.from(evidence.authenticatorData, "base64url");
+    if (authData.length < 37)
+        throw new Error("Malformed authenticatorData.");
+    const rpIdHash = createHash("sha256").update(credential.rpId).digest();
+    if (!authData.subarray(0, 32).equals(rpIdHash)) {
+        throw new Error("Assertion signed for a different relying party.");
+    }
+    const flags = authData[32];
+    if ((flags & 0x01) === 0)
+        throw new Error("User presence flag missing.");
+    if ((flags & 0x04) === 0) {
+        throw new Error("User verification flag missing (biometric/PIN not performed).");
+    }
+    const clientDataHash = createHash("sha256")
+        .update(Buffer.from(evidence.clientDataJSON, "base64url"))
+        .digest();
+    const signedData = Buffer.concat([authData, clientDataHash]);
+    const publicKey = createPublicKey({
+        key: Buffer.from(credential.publicKeySpki, "base64url"),
+        format: "der",
+        type: "spki",
+    });
+    const ok = cryptoVerify("sha256", signedData, publicKey, Buffer.from(evidence.signature, "base64url"));
+    if (!ok)
+        throw new Error("Assertion signature does not verify.");
+}

package/package.json

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