@openmobilehub/credentagent-gate 0.2.0

package/dist/ceremony/mount.js

@@ -0,0 +1,118 @@
+// The injected-seam contract for the ceremony (Context 2). `mountCeremony(app)`
+// reads the seams the host provides (options + `app.locals.credentagent`), FAILS FAST
+// when a load-bearing one is missing (CT2 — never silently degrade), resolves a
+// CeremonyContext, and registers each rail's routes onto the host app. With no
+// rails extracted yet (Phase 2 — Foundational), it validates the seams + builds
+// the context only; the passkey / dc-payment / credential-gate rails push their
+// registrars here as they land (US1–US3).
+//
+// The package stays dependency-free: `CeremonyApp` is a minimal structural type
+// (no `express` import) carrying just `locals` + the route methods a rail needs.
+import { randomBytes } from "node:crypto";
+import { deriveOrigin } from "./origin.js";
+import { verifyCartMandate } from "./cartMandate.js";
+import { registerCredentialGate } from "./credential-gate/routes.js";
+import { registerPasskeyGate } from "./passkey/routes.js";
+import { registerDcPaymentGate } from "./dc-payment/routes.js";
+// Per-rail registration scaffold. Each rail (passkey / dc-payment /
+// credential-gate) pushes its registrar here once extracted (US1–US3). US1 lands
+// the credential gate (age + membership); passkey / dc-payment follow (US2/US3).
+// Each registrar no-ops on a route-less app shape, so mount()'s fail-fast tests
+// (which pass a `{ locals }`-only app) are unaffected.
+const RAILS = [registerCredentialGate, registerPasskeyGate, registerDcPaymentGate];
+/**
+ * Read + validate the injected seams, build the CeremonyContext, and register
+ * every rail's routes. Throws on a missing required seam (CT2). Seams may arrive
+ * via `options` OR `app.locals.credentagent` — options win.
+ */
+export function mountCeremony(app, options = {}) {
+    const locals = (app.locals.credentagent ?? {});
+    const verificationStore = options.verificationStore ?? locals.verificationStore ?? locals.store;
+    const orderStore = options.orderStore ?? locals.orderStore;
+    const catalog = options.catalog ?? locals.catalog;
+    const completion = options.completion ?? locals.completion;
+    const settlement = options.settlement ?? locals.settlement;
+    const origin = options.origin ?? locals.origin ?? deriveOrigin;
+    const allowEphemeralKey = options.allowEphemeralKey ?? locals.allowEphemeralKey ?? false;
+    const statelessOrders = options.statelessOrders ?? locals.statelessOrders ?? false;
+    let signingKey = options.signingKey ?? locals.signingKey;
+    // Fail fast (CT2) — a load-bearing seam must never silently default. (`origin`
+    // has a safe built-in default; `settlement` is genuinely optional.)
+    const missing = [];
+    if (!verificationStore)
+        missing.push("verificationStore");
+    if (!orderStore)
+        missing.push("orderStore");
+    if (!catalog)
+        missing.push("catalog");
+    if (!completion)
+        missing.push("completion");
+    if (missing.length > 0) {
+        throw new Error(`[credentagent] mount(): missing required ceremony seam(s): ${missing.join(", ")}. ` +
+            `Provide them via credentagent.mount(app, { ... }) or app.locals.credentagent.`);
+    }
+    // The challenge HMAC must survive an instance split (options→verify may hit
+    // different serverless instances — D6). We do NOT infer "serverless"; an
+    // ephemeral per-process key is allowed ONLY when the host opts in explicitly.
+    if (!signingKey) {
+        if (!allowEphemeralKey) {
+            throw new Error(`[credentagent] mount(): a stable 'signingKey' is required so the challenge HMAC survives an instance split. ` +
+                `Pass { signingKey } (e.g. process.env.GATE_SECRET), or { allowEphemeralKey: true } for a single-process dev server.`);
+        }
+        signingKey = randomBytes(32).toString("hex");
+    }
+    const ctx = {
+        verificationStore: verificationStore,
+        orderStore: orderStore,
+        catalog: catalog,
+        completion: completion,
+        signingKey,
+        origin,
+        statelessOrders,
+        ...(settlement ? { settlement } : {}),
+    };
+    // Re-expose the resolved seams on app.locals so the storefront's gate routes
+    // resolve verification THROUGH CredentAgent (and a re-mount is idempotent).
+    app.locals.credentagent = { ...app.locals.credentagent, store: ctx.verificationStore, ...ctx };
+    for (const register of RAILS)
+        register(app, ctx);
+    return ctx;
+}
+/**
+ * Shared order resolution + re-pricing (T003a). Resolve a created order by id,
+ * then RE-PRICE it from the catalog — the displayed and bound amounts come from
+ * the catalog, never the id/token (CT3, invariants 2/3). A tampered or unknown id
+ * resolves to `null` (the rail refuses).
+ *
+ * FR-007 (opt-in `statelessOrders`): when the host has no shared order store, a
+ * VERIFIED Cart Mandate carried on the request is the order transport — pass it as
+ * `opts.cartMandate` and the created order is reconstructed from it with NO store
+ * read, so a created order survives an instance split (US3). It stays fail-closed:
+ * a forged / tampered / replayed (wrong-order) / expired mandate does not resolve
+ * an order, and the catalog STILL reprices (the mandate carries the items, never
+ * the price — invariant 2). Off (default), the store is the source of truth and any
+ * mandate is an additive integrity envelope checked at completion, not a transport.
+ */
+export async function resolveOrder(ctx, orderId, opts) {
+    if (!orderId)
+        return null;
+    // Stateless transport (opt-in): reconstruct from the verified mandate, no store read.
+    if (ctx.statelessOrders && opts?.cartMandate !== undefined) {
+        const verdict = verifyCartMandate(opts.cartMandate, orderId, ctx.signingKey);
+        if (!verdict.ok)
+            return null;
+        const verification = await ctx.verificationStore.read(orderId);
+        const loyaltyApplied = !!verification?.loyalty?.applied;
+        return ctx.catalog.createOrder(verdict.mandate.lines.map((l) => ({ productId: l.id, quantity: l.quantity })), orderId, { loyaltyApplied });
+    }
+    // Default: the store is the source of truth.
+    const stored = await ctx.orderStore.read(orderId);
+    if (!stored || stored.id !== orderId || !Array.isArray(stored.lines))
+        return null;
+    // A loyalty discount is applied only when THIS order's verification opts in
+    // (invariant 3); the line items come from the store, every price from the
+    // catalog.
+    const verification = await ctx.verificationStore.read(orderId);
+    const loyaltyApplied = !!verification?.loyalty?.applied;
+    return ctx.catalog.createOrder(stored.lines.map((l) => ({ productId: l.id, quantity: l.quantity })), orderId, { loyaltyApplied });
+}

package/dist/ceremony/origin.d.ts

@@ -0,0 +1,10 @@
+export interface RequestLike {
+    headers: Record<string, string | string[] | undefined>;
+    host: string;
+    protocol: string;
+}
+export interface Origin {
+    rpID: string;
+    origin: string;
+}
+export declare function deriveOrigin(req: RequestLike): Origin;

package/dist/ceremony/origin.js

@@ -0,0 +1,9 @@
+function first(value) {
+    return Array.isArray(value) ? value[0] : value;
+}
+export function deriveOrigin(req) {
+    const host = first(req.headers["x-forwarded-host"]) ?? req.host;
+    const proto = first(req.headers["x-forwarded-proto"]) ?? req.protocol;
+    const rpID = host.split(":")[0];
+    return { rpID, origin: `${proto}://${host}` };
+}

package/dist/ceremony/passkey/page.d.ts

@@ -0,0 +1,7 @@
+import type { CeremonyOrder } from "../types.js";
+export declare function renderPasskeyPage(args: {
+    order: CeremonyOrder;
+    crossDevice?: boolean;
+    returnUrl?: string;
+    cart?: string;
+}): string;

package/dist/ceremony/passkey/page.js

@@ -0,0 +1,143 @@
+import { pageHead, brandHeader, progressRail, orderSummaryCard, trustFooter, settlingBar, completionHandoffBanner } from "../theme.js";
+function money(amount, currency) {
+    return new Intl.NumberFormat("en-US", { style: "currency", currency }).format(amount);
+}
+export function renderPasskeyPage(args) {
+    const { order, crossDevice = false } = args;
+    // Where the completed receipt links back to — the checkout hub, which then renders
+    // the paid state (a forward, fresh GET — so the buyer never browser-backs onto a
+    // stale, re-payable checkout). Defaults to this server's `/checkout?order=<id>`.
+    // statelessOrders: carry the cart mandate back so the store-less hub can re-resolve.
+    const returnUrl = args.returnUrl ?? `/checkout?order=${encodeURIComponent(order.id)}${args.cart ? `&cart=${args.cart}` : ""}`;
+    const total = money(order.total, order.currency);
+    // The shared order summary card (line items + bold Total) — same chrome as the hub.
+    const summary = orderSummaryCard({
+        lines: order.lines.map((l) => ({ name: l.name ?? l.id, quantity: l.quantity, lineTotal: l.lineTotal, currency: l.currency ?? order.currency })),
+        total: order.total,
+        currency: order.currency,
+        caption: `Order ${order.id}`,
+    });
+    // Pay is the current (final) step; the upstream gates are done by the time payment runs.
+    const rail = progressRail([{ label: "Age", done: true }, { label: "Membership", done: true }, { label: "Pay" }], 2);
+    const tagline = crossDevice ? "Approve on your phone (scan a QR)" : "Authorize with this device";
+    // crossDevice pins the registration to a roaming authenticator, so the browser
+    // skips local Touch ID and shows the QR for a phone (caBLE). The toggle link flips
+    // the mode by adding/removing the xdev param on the same gate URL.
+    const optionsUrl = crossDevice ? "/credentagent/passkey/options?xdev=1" : "/credentagent/passkey/options";
+    // statelessOrders: keep the cart mandate on the same-device ⇄ cross-device toggle so the
+    // store-less server can still resolve THIS order after switching.
+    const cartQ = args.cart ? `&cart=${args.cart}` : "";
+    const toggleHref = crossDevice ? `/credentagent/passkey?order=${encodeURIComponent(order.id)}${cartQ}` : `/credentagent/passkey?order=${encodeURIComponent(order.id)}&xdev=1${cartQ}`;
+    const toggleText = crossDevice ? "← Use this device instead" : "Use my phone instead (scan a QR) →";
+    // Page-local chrome over the shared design system: the verify-progress rows reuse
+    // `.step`; the receipt gate rows + the QR toggle link are page-specific.
+    const extraCss = `
+  #receipt { display: none; margin-top: 16px; }
+  .gate { font-size: .82rem; padding: 3px 0; }
+  .gate.pass { color: var(--success); } .gate.fail { color: var(--danger); }
+  .toggle { display: block; text-align: center; margin-top: 12px; font-size: .85rem; color: var(--accent); text-decoration: none; }
+  .toggle:hover { text-decoration: underline; }`;
+    return `<!doctype html>
+<html lang="en">
+${pageHead(`Authorize payment · ${order.id}`, extraCss)}
+<body>
+  <div class="wrap">
+  ${brandHeader({ h1: "Authorize payment", tagline })}
+  ${rail}
+  ${summary}
+  <div class="card">
+    <p class="lede">An agent prepared this order — confirm the exact amount with your device's secure element (Touch ID, Windows Hello, or a phone via cross-device sign-in). Once authorized, payment settles on-chain via the <strong>x402</strong> protocol — on a <strong>test network</strong>, no real money, a tiny token amount (a fixed demo rate, not the dollar total).</p>
+    <button id="go" class="btn btn-primary">Authorize ${total}</button>
+    <a class="toggle" href="${toggleHref}">${toggleText}</a>
+    <div id="log"></div>
+    ${settlingBar()}
+    <div id="receipt"></div>
+  </div>
+  ${trustFooter()}
+  <script type="module">
+    import { startRegistration } from "/credentagent/lib/sw/index.js";
+    const ORDER_ID = ${JSON.stringify(order.id)};
+    // statelessOrders: forward the signed cart mandate (?cart=… in this page's URL) so a
+    // store-less server can reconstruct THIS order on verify.
+    const CART = new URLSearchParams(location.search).get("cart");
+    const OPTIONS_URL = ${JSON.stringify(optionsUrl)};
+    const RETURN_URL = ${JSON.stringify(returnUrl)};
+    const DONE_BANNER = ${JSON.stringify(completionHandoffBanner(returnUrl))};
+    const log = document.getElementById("log");
+    const btn = document.getElementById("go");
+    const settling = document.getElementById("settling");
+    const step = (t, c = "") => { const d = document.createElement("div"); d.className = "step " + c; d.textContent = t; log.appendChild(d); };
+    const esc = (s) => String(s).replace(/[&<>"']/g, (c) => "&#" + c.charCodeAt(0) + ";");
+    btn.addEventListener("click", async () => {
+      btn.disabled = true;
+      try {
+        step("→ GET options");
+        const { options, challengeToken } = await fetch(OPTIONS_URL).then((r) => r.json());
+        step("→ Touch ID / passkey prompt");
+        const response = await startRegistration({ optionsJSON: options });
+        step("→ verify · Settling via x402 on Hedera testnet (if configured)… can take ~10s");
+        settling.classList.add("on");
+        const out = await fetch("/credentagent/passkey/verify", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ response, challengeToken, order: ORDER_ID, cart: CART }),
+        }).then((r) => r.json()).finally(() => settling.classList.remove("on"));
+        if (!out.mandate) throw new Error(out.error || "authorization failed");
+        step("✓ authorized · mandate built (" + out.trust_level + ")", "ok");
+        renderReceipt(out);
+        if (out.settlementError) { step("✗ settlement failed — authorized, not settled (retry below)", "err"); btn.disabled = false; }
+        else if (!out.completed) btn.disabled = false;
+      } catch (err) {
+        step("✗ " + (err?.message ?? String(err)), "err");
+        btn.disabled = false;
+      }
+    });
+
+    function renderReceipt(out) {
+      const el = document.getElementById("receipt");
+      const passCount = out.gates.filter((g) => g.pass).length;
+      const allPass = passCount === out.gates.length;
+      const gateLines = out.gates.map((g) => '<div class="gate ' + (g.pass ? "pass" : "fail") + '">' + (g.pass ? "✓" : "✗") + " " + esc(g.gate) + " — " + esc(g.detail) + "</div>").join("");
+      // The x402 on-chain settlement receipt — same .settle card the dc-payment rail
+      // renders: the tinybar amount, payer/merchant, speed, tx, and a PROMINENT
+      // tappable HashScan link (the buyer is on their phone; one tap to the live
+      // explorer is the third-party proof). A configured-but-failed settle is the
+      // calm "authorized, not settled" line (FR-013) — never an alarming wall.
+      const s = out.settlement;
+      const settlement = s
+        ? '<div class="settle"><div class="settle-head">✓ Settled via x402 on Hedera testnet</div>' +
+          '<dl class="kv">' +
+          "<dt>Amount</dt><dd>" + (s.amountTinybar / 1e8) + ' ℏ <span class="dim">(' + esc(s.fxRate) + ")</span></dd>" +
+          "<dt>From</dt><dd>" + esc(s.payer.accountId) + ' <span class="dim">' +
+          (s.payer.kind === "session-wallet"
+            ? "wallet created for this order, " + (s.walletAgeMs / 1000).toFixed(1) + "s old when it paid"
+            : "demo customer") + "</span></dd>" +
+          "<dt>To</dt><dd>" + esc(s.payTo) + ' <span class="dim">merchant</span></dd>' +
+          "<dt>Speed</dt><dd>settled in " + (s.settledInMs / 1000).toFixed(1) + "s</dd>" +
+          '<dt>Tx</dt><dd><span class="mono">' + esc(s.txId) + "</span></dd>" +
+          "</dl>" +
+          '<a class="hashscan" href="' + esc(s.hashscanUrl) + '" target="_blank" rel="noopener">View on HashScan ›</a>' +
+          "</div>"
+        : out.settlementError
+          ? '<div class="settle-failed">✗ Settlement failed — authorized, not settled: ' + esc(out.settlementError) + "</div>"
+          : "";
+      // Every gate + payment is done ⇒ the order is COMPLETE. Lead with the prominent
+      // handoff: close this window and continue in the agent (the MCP host polls
+      // order-status and resumes). No auto-redirect — we don't yank the buyer off the
+      // "you're done" message; the on-chain proof + a secondary return link stay below.
+      const done = out.completed ? DONE_BANNER : "";
+      const gates = '<div class="gate ' + (allPass ? "pass" : "fail") + '">' +
+        (allPass ? "✓ All " + out.gates.length + " authorization gates passed" : "✗ " + (out.gates.length - passCount) + " of " + out.gates.length + " failed") + "</div>" + gateLines;
+      el.innerHTML = done + '<div class="row-ok">✓ Payment Mandate authorized (amount-bound)</div>' +
+        '<div class="small" style="margin:4px 0 8px;">' + esc(out.mandate.id) + "</div>" + gates + settlement;
+      el.style.display = "block";
+      if (out.completed) {
+        btn.disabled = true;
+        btn.textContent = "Authorized ✓";
+      }
+    }
+  </script>
+  </div>
+</body>
+</html>`;
+}

package/dist/ceremony/passkey/routes.d.ts

@@ -0,0 +1,2 @@
+import { type RailRegistrar } from "../mount.js";
+export declare const registerPasskeyGate: RailRegistrar;

package/dist/ceremony/passkey/routes.js

@@ -0,0 +1,173 @@
+// The passkey payment rail (US2) — same-device (Touch ID / Windows Hello) and
+// cross-device (FIDO caBLE). Registers its routes onto the host app through the
+// Foundational mount() seam:
+//   GET  /credentagent/passkey?order=<id>[&xdev=1]   → the authorize page (xdev toggle)
+//   GET  /credentagent/passkey/options[?xdev=1]      → WebAuthn options + signed challenge token
+//   POST /credentagent/passkey/verify                → verify assertion → four gates → completeOrder
+//   GET  /credentagent/lib/sw/*                       → @simplewebauthn/browser ESM, same-origin
+//
+// Dependency-free (no `express` import — invariant from mount.ts): handlers are
+// registered against the structural CeremonyApp.get/post/use, the verify body is
+// read either from a host-installed parser (`req.body`) or off the request stream,
+// and the browser ESM is served from disk (no `express.static`).
+//
+// EVERY route resolves the order by id THROUGH `resolveOrder` (catalog re-pricing;
+// a tampered/unknown id is refused — CT3, invariant 2). Completion runs through the
+// SHARED `completeOrder` seam (ctx.completion) — the same path dc-payment uses — so
+// re-pricing, the age gate, settlement, and state-clearing behave identically
+// across rails (FR-008). WebAuthn stays bound to this server's origin/RP-ID with a
+// sealed, time-limited, single-use challenge (FR-007, invariant 6).
+//
+// Trust is PRESENCE-ONLY (Principle VII / FR-011): the WebAuthn flow is real, but
+// the mandate is dev-signed — a flow demo, not a real safety control.
+import { createRequire } from "node:module";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { resolveOrder } from "../mount.js";
+import { decodeCartMandateParam } from "../cartMandate.js";
+import { buildPasskeyMandate, buildBindingFields, runGates } from "../mandate.js";
+import { buildRegistrationOptions, verifyPasskeyAssertion } from "./verify.js";
+import { renderPasskeyPage } from "./page.js";
+function firstHeader(value) {
+    return Array.isArray(value) ? value[0] : value;
+}
+function originOf(ctx, req) {
+    const reqLike = { headers: req.headers, host: firstHeader(req.headers.host) ?? "localhost", protocol: req.protocol };
+    return ctx.origin(reqLike);
+}
+function isCrossDevice(raw) {
+    return (Array.isArray(raw) ? raw[0] : raw) === "1";
+}
+// Read the JSON body from a host-installed parser, or straight off the stream when
+// no parser ran (so the rail is self-contained — it doesn't require express.json()).
+async function readJsonBody(req) {
+    if (req.body && typeof req.body === "object")
+        return req.body;
+    try {
+        const chunks = [];
+        for await (const chunk of req) {
+            chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+        }
+        if (chunks.length === 0)
+            return {};
+        return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+const CONTENT_TYPES = {
+    ".js": "text/javascript",
+    ".mjs": "text/javascript",
+    ".map": "application/json",
+    ".json": "application/json",
+    ".ts": "text/plain",
+};
+// Resolve @simplewebauthn/browser's ESM dir (its `main` is script/index.js; walk
+// up two levels to the package root, then into /esm). Fail LOUDLY at wire-up if the
+// layout changed, rather than silently 404-ing the browser module at runtime.
+function resolveBrowserEsmDir() {
+    const requireFrom = createRequire(import.meta.url);
+    const scriptIndexPath = requireFrom.resolve("@simplewebauthn/browser");
+    const dir = path.join(path.dirname(path.dirname(scriptIndexPath)), "esm");
+    if (!existsSync(path.join(dir, "index.js"))) {
+        throw new Error(`[credentagent] @simplewebauthn/browser ESM not found at ${dir}`);
+    }
+    return dir;
+}
+export const registerPasskeyGate = (app, ctx) => {
+    // The Foundational fail-fast tests mount() with a route-less app shape; only
+    // attach when the host app can actually route.
+    const get = app.get?.bind(app);
+    const post = app.post?.bind(app);
+    const use = app.use?.bind(app);
+    if (!get || !post || !use)
+        return;
+    // Serve @simplewebauthn/browser ESM same-origin (no CDN) — dependency-free file
+    // serving with path-traversal containment.
+    const browserEsmDir = resolveBrowserEsmDir();
+    use("/credentagent/lib/sw", (req, res) => {
+        const rel = (req.path ?? req.url ?? "/").split("?")[0];
+        const filePath = path.resolve(browserEsmDir, "." + rel);
+        // Containment: a resolved path must stay inside the served ESM directory.
+        if (filePath !== browserEsmDir && !filePath.startsWith(browserEsmDir + path.sep)) {
+            res.status(403).type("text/plain").send("forbidden");
+            return;
+        }
+        if (!existsSync(filePath) || !statSync(filePath).isFile()) {
+            res.status(404).type("text/plain").send("not found");
+            return;
+        }
+        const mime = CONTENT_TYPES[path.extname(filePath)] ?? "application/octet-stream";
+        res.status(200).type(mime).send(readFileSync(filePath, "utf8"));
+    });
+    // GET the authorize page — re-priced order, presence-only honesty banner.
+    get("/credentagent/passkey", async (req, res) => {
+        const order = await resolveOrder(ctx, typeof req.query.order === "string" ? req.query.order : undefined, { cartMandate: decodeCartMandateParam(req.query.cart) });
+        if (!order) {
+            res.status(404).type("html").send("<!doctype html><h1>Order not found</h1>");
+            return;
+        }
+        try {
+            res.status(200).type("html").send(renderPasskeyPage({ order, crossDevice: isCrossDevice(req.query.xdev), cart: typeof req.query.cart === "string" ? req.query.cart : undefined }));
+        }
+        catch {
+            // A hand-edited order can carry a bad currency that throws in Intl; never 500.
+            res.status(404).type("html").send("<!doctype html><h1>Order not found</h1>");
+        }
+    });
+    // GET WebAuthn options + a signed challenge token (order-independent — the
+    // challenge binds to this origin/RP-ID, the order is bound at verify).
+    get("/credentagent/passkey/options", async (req, res) => {
+        const { options, challengeToken } = await buildRegistrationOptions(originOf(ctx, req), ctx.signingKey, {
+            crossDevice: isCrossDevice(req.query.xdev),
+        });
+        res.json({ options, challengeToken });
+    });
+    // POST verify — recover the nonce, verify the assertion against this origin/RP-ID,
+    // build the AP2 mandate, run the four deterministic gates, and complete through
+    // the SHARED completeOrder seam (re-price + age gate + idempotent record).
+    post("/credentagent/passkey/verify", async (req, res) => {
+        const body = await readJsonBody(req);
+        const cartMandate = body.cartMandate ?? decodeCartMandateParam(body.cart);
+        const order = await resolveOrder(ctx, typeof body.order === "string" ? body.order : undefined, { cartMandate });
+        if (!order) {
+            res.status(400).json({ completed: false, error: "missing or invalid order" });
+            return;
+        }
+        try {
+            const origin = originOf(ctx, req);
+            const authenticator = await verifyPasskeyAssertion({
+                response: body.response,
+                challengeToken: String(body.challengeToken ?? ""),
+                origin,
+                secret: ctx.signingKey,
+            });
+            const mandate = buildPasskeyMandate({ order, authenticator, origin });
+            const gates = runGates(mandate);
+            const completion = await ctx.completion({
+                order,
+                mandateId: mandate.id,
+                amount: mandate.payment.amount,
+                currency: mandate.payment.currency,
+                method: "passkey",
+                instrument: { issuer: mandate.payment.instrument, maskedAccount: mandate.payment.instrumentReference, holder: null },
+                gates: gates.map((g) => ({ gate: g.gate, pass: g.pass, detail: g.detail })),
+                ...(cartMandate !== undefined ? { cartMandate: cartMandate } : {}),
+            });
+            res.json({
+                mandate,
+                gates,
+                completed: completion.completed,
+                settlement: completion.settlement ?? null,
+                settlementError: completion.settlementError ?? null,
+                reason: completion.reason ?? null,
+                binding: buildBindingFields(order, origin),
+                trust_level: "presence-only-demo",
+            });
+        }
+        catch (err) {
+            res.status(400).json({ completed: false, error: err.message });
+        }
+    });
+};

package/dist/ceremony/passkey/verify.d.ts

@@ -0,0 +1,15 @@
+import { type RegistrationResponseJSON } from "@simplewebauthn/server";
+import type { Origin } from "../origin.js";
+import type { VerifiedAuthenticator } from "../mandate.js";
+export declare function buildRegistrationOptions(origin: Origin, secret: string, opts?: {
+    crossDevice?: boolean;
+}): Promise<{
+    options: import("@simplewebauthn/server").PublicKeyCredentialCreationOptionsJSON;
+    challengeToken: string;
+}>;
+export declare function verifyPasskeyAssertion(args: {
+    response: RegistrationResponseJSON;
+    challengeToken: string;
+    origin: Origin;
+    secret: string;
+}): Promise<VerifiedAuthenticator>;

package/dist/ceremony/passkey/verify.js

@@ -0,0 +1,56 @@
+// The passkey rail's WebAuthn step (US2) — extracted from the demo's
+// payment-gate/passkey/verify.ts. A single registration ceremony is the
+// authorization gesture: the challenge is recovered from the signed token
+// (stateless — survives an options→verify instance split), and the assertion is
+// verified against THIS server's origin/RP-ID with user verification required
+// (invariant 6). The signing secret is the injected `signingKey` seam (mount()
+// requires a stable one — D6), never a process global.
+//
+// Trust is PRESENCE-ONLY (Principle VII / FR-011): the attestation flow is real,
+// but the mandate it feeds (mandate.ts) is dev-signed, not key-bound — a flow
+// demo, not a real safety control.
+import { generateRegistrationOptions, verifyRegistrationResponse, } from "@simplewebauthn/server";
+import { issueChallenge, verifyChallenge } from "../challengeToken.js";
+const RP_NAME = "CredentAgent Gate";
+// Build registration options + a signed challenge token. userID is ephemeral —
+// we never persist the credential, so a fresh random user each time is fine.
+// crossDevice pins authenticatorAttachment to "cross-platform", which removes the
+// local Touch ID option so the browser goes straight to the phone/QR (caBLE) path.
+export async function buildRegistrationOptions(origin, secret, opts = {}) {
+    const { challenge, token } = issueChallenge(secret);
+    const options = await generateRegistrationOptions({
+        rpName: RP_NAME,
+        rpID: origin.rpID,
+        userName: "credentagent-gate-user",
+        challenge: Buffer.from(challenge, "base64url"),
+        attestationType: "none",
+        authenticatorSelection: {
+            residentKey: "preferred",
+            userVerification: "required",
+            ...(opts.crossDevice ? { authenticatorAttachment: "cross-platform" } : {}),
+        },
+    });
+    return { options, challengeToken: token };
+}
+export async function verifyPasskeyAssertion(args) {
+    // Recover + validate the sealed, time-limited nonce FIRST — a forged or expired
+    // token is rejected before any attestation parsing (invariant 6).
+    const expectedChallenge = verifyChallenge(args.challengeToken, args.secret);
+    const verification = await verifyRegistrationResponse({
+        response: args.response,
+        expectedChallenge,
+        expectedOrigin: args.origin.origin,
+        expectedRPID: args.origin.rpID,
+        requireUserVerification: true,
+    });
+    if (!verification.verified || !verification.registrationInfo) {
+        throw new Error("registration not verified");
+    }
+    const info = verification.registrationInfo;
+    return {
+        credentialID: info.credential.id,
+        userVerified: true,
+        credentialDeviceType: info.credentialDeviceType,
+        credentialBackedUp: info.credentialBackedUp,
+    };
+}

package/dist/ceremony/reconciliation.d.ts

@@ -0,0 +1,34 @@
+import type { CartMandate } from "./cartMandate.js";
+/** The Payment Mandate's bound fields as they reach the completion seam — each rail
+ *  projects them from its verified `mandate.payment` (+ the id of the order the
+ *  payment authorizes). Scalars, not the mandate object, so the seam stays
+ *  decoupled from the passkey/dc-payment mandate shapes. */
+export interface PaymentBinding {
+    /** The Payment Mandate's bound amount (`mandate.payment.amount`). */
+    amount: number;
+    /** The Payment Mandate's bound currency (`mandate.payment.currency`). */
+    currency: string;
+    /** The order id the payment authorizes (the mandate's cart/subject). */
+    orderId: string;
+}
+/** Why a Cart ↔ Payment reconciliation refused. */
+export type ReconcileRefusal = "order-id" | "currency" | "amount";
+export type ReconcileVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    reason: ReconcileRefusal;
+};
+/**
+ * Reconcile a (signature-verified) Cart Mandate with the Payment Mandate's binding,
+ * given the catalog-RE-DERIVED total (server-side truth, never the token — invariant
+ * 2). The verdict is `ok` only when all three agree:
+ *   1. order id / subject — the cart and the payment authorize the SAME order
+ *      (a Cart Mandate swapped onto another order's payment is refused);
+ *   2. currency — the cart and the payment settle in the same currency;
+ *   3. amount — `cart.total === rederivedTotal === payment.amount`, a single bound
+ *      figure (a cart sealed for X against a payment for Y≠X is refused; a discount
+ *      reconciles only when the re-derived total already reflects it — invariant 3).
+ * Returns a typed verdict; it never throws.
+ */
+export declare function reconcileCartPayment(cart: CartMandate, payment: PaymentBinding, rederivedTotal: number): ReconcileVerdict;

package/dist/ceremony/reconciliation.js

@@ -0,0 +1,21 @@
+/**
+ * Reconcile a (signature-verified) Cart Mandate with the Payment Mandate's binding,
+ * given the catalog-RE-DERIVED total (server-side truth, never the token — invariant
+ * 2). The verdict is `ok` only when all three agree:
+ *   1. order id / subject — the cart and the payment authorize the SAME order
+ *      (a Cart Mandate swapped onto another order's payment is refused);
+ *   2. currency — the cart and the payment settle in the same currency;
+ *   3. amount — `cart.total === rederivedTotal === payment.amount`, a single bound
+ *      figure (a cart sealed for X against a payment for Y≠X is refused; a discount
+ *      reconciles only when the re-derived total already reflects it — invariant 3).
+ * Returns a typed verdict; it never throws.
+ */
+export function reconcileCartPayment(cart, payment, rederivedTotal) {
+    if (cart.orderId !== payment.orderId)
+        return { ok: false, reason: "order-id" };
+    if (cart.currency !== payment.currency)
+        return { ok: false, reason: "currency" };
+    if (cart.total !== rederivedTotal || cart.total !== payment.amount)
+        return { ok: false, reason: "amount" };
+    return { ok: true };
+}