@openmobilehub/attestomcp-gate 0.1.0

package/dist/ceremony/theme.js

@@ -0,0 +1,285 @@
+// theme.ts — the SHARED AttestoMcp design system for the browser ceremony flow.
+//
+// The checkout hub (checkout-page.ts) and the two gate pages (credential-gate/page.ts,
+// dc-payment/page.ts) all render through THIS module so they read as ONE branded flow:
+// the same wordmark, the same card surfaces, the same teal accent, the same discreet
+// honesty footer. Each page composes the pieces below around its OWN logic — the chrome
+// is presentation-only and never touches a completion path.
+//
+// Design language (opinionated, build to this):
+//   • ONE accent — teal #0d9488 (hover #0f766e). Used sparingly: primary CTA, active
+//     step, the discount row, a verified ✓.
+//   • ink #0f172a · muted #64748b · hairline #e2e8f0 · surface #fff on app bg #f8fafc.
+//   • success #047857 · danger #b91c1c.
+//   • System type stack. Money is tabular-nums. Single column, max-width 460px, 14px
+//     card radius, a soft two-layer shadow, mobile-first (great at 390px).
+//
+// Honesty (FR-011 / Principle VII): the trust footer is the single presence-only surface.
+// It MUST keep the literal token "presence-only-demo" so the honesty tests and the FR
+// stay satisfied — the wire crypto is real; the issuer trust anchor is not.
+function escapeHtml(s) {
+    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function money(amount, currency) {
+    return new Intl.NumberFormat("en-US", { style: "currency", currency }).format(amount);
+}
+// ── The design-system stylesheet ────────────────────────────────────────────
+// One <style> block shared by all three pages so they are visually identical chrome.
+// Pages add only the few component styles unique to them (e.g. the QR notice).
+const DESIGN_CSS = `
+  :root {
+    --accent: #0d9488; --accent-hover: #0f766e;
+    --ink: #0f172a; --muted: #64748b; --hairline: #e2e8f0;
+    --surface: #ffffff; --app-bg: #f8fafc;
+    --success: #047857; --danger: #b91c1c;
+    --shadow: 0 1px 3px rgba(15,23,42,.08), 0 1px 2px rgba(15,23,42,.04);
+  }
+  * { box-sizing: border-box; }
+  body {
+    font-family: -apple-system, "Segoe UI", Roboto, system-ui, sans-serif;
+    background: var(--app-bg); color: var(--ink);
+    margin: 0; padding: 20px 16px 40px;
+    line-height: 1.55; -webkit-font-smoothing: antialiased;
+  }
+  .wrap { max-width: 460px; margin: 0 auto; }
+  h1 { font-size: 1.5rem; font-weight: 700; line-height: 1.2; margin: 0 0 6px; color: var(--ink); }
+  p.lede { font-size: .95rem; color: var(--muted); margin: 0 0 4px; }
+  small, .small { font-size: .8rem; color: var(--muted); }
+  .num { text-align: right; font-variant-numeric: tabular-nums; }
+
+  /* Brand header */
+  .brand { display: flex; align-items: center; justify-content: space-between; margin-bottom: 18px; }
+  .wordmark { font-size: .78rem; letter-spacing: .22em; font-weight: 700; color: var(--muted); }
+  .demo-pill {
+    font-size: .62rem; letter-spacing: .14em; font-weight: 700; color: var(--muted);
+    border: 1px solid var(--hairline); border-radius: 999px; padding: 3px 9px; background: var(--surface);
+  }
+  .head { margin-bottom: 18px; }
+  .head .tagline { font-size: .95rem; color: var(--muted); margin: 0; }
+
+  /* Card surface */
+  .card {
+    background: var(--surface); border: 1px solid var(--hairline);
+    border-radius: 14px; box-shadow: var(--shadow);
+    padding: 18px; margin-bottom: 16px;
+  }
+  .card-title { font-size: .8rem; letter-spacing: .04em; text-transform: uppercase; color: var(--muted); font-weight: 700; margin: 0 0 12px; }
+
+  /* Order summary */
+  .summary table { width: 100%; border-collapse: collapse; }
+  .summary td { padding: 8px 0; font-size: .95rem; }
+  .summary .line td { border-bottom: 1px solid var(--hairline); }
+  .summary .qty { color: var(--muted); font-variant-numeric: tabular-nums; }
+  .summary .disc td { color: var(--accent); font-weight: 600; }
+  .summary .total td { padding-top: 12px; border-top: 1px solid var(--hairline); font-weight: 700; font-size: 1.05rem; }
+
+  /* Progress rail (Age · Membership · Pay) */
+  .rail { display: flex; align-items: flex-start; justify-content: space-between; position: relative; margin: 4px 2px 18px; }
+  .rail::before { content: ""; position: absolute; top: 11px; left: 11%; right: 11%; height: 2px; background: var(--hairline); z-index: 0; }
+  .rail-step { position: relative; z-index: 1; display: flex; flex-direction: column; align-items: center; gap: 6px; flex: 1; }
+  .rail-dot {
+    width: 22px; height: 22px; border-radius: 999px; background: var(--surface);
+    border: 2px solid var(--hairline); display: flex; align-items: center; justify-content: center;
+    font-size: .7rem; font-weight: 700; color: var(--muted);
+  }
+  .rail-step.done .rail-dot { background: var(--accent); border-color: var(--accent); color: #fff; }
+  .rail-step.current .rail-dot { border-color: var(--accent); color: var(--accent); box-shadow: 0 0 0 3px rgba(13,148,136,.14); }
+  .rail-label { font-size: .68rem; letter-spacing: .02em; color: var(--muted); text-align: center; }
+  .rail-step.done .rail-label, .rail-step.current .rail-label { color: var(--ink); font-weight: 600; }
+
+  /* Buttons */
+  .btn {
+    display: block; width: 100%; height: 48px; line-height: 1; border-radius: 10px;
+    font-size: .95rem; font-weight: 600; text-align: center; text-decoration: none;
+    border: 1px solid transparent; cursor: pointer; transition: background .12s, transform .04s;
+    display: flex; align-items: center; justify-content: center;
+  }
+  .btn-primary { background: var(--accent); color: #fff; border-color: var(--accent); }
+  .btn-primary:hover { background: var(--accent-hover); border-color: var(--accent-hover); }
+  .btn-primary:active { transform: translateY(1px); }
+  .btn-secondary { background: transparent; color: var(--accent); border-color: var(--hairline); }
+  .btn-secondary:hover { border-color: var(--accent); }
+  .btn-danger { background: var(--accent); color: #fff; border-color: var(--accent); }
+  .btn + .btn { margin-top: 10px; }
+  .btn:disabled { opacity: .55; cursor: default; }
+
+  /* Status rows + verify log */
+  .row-ok { color: var(--success); font-weight: 600; font-size: .95rem; display: flex; align-items: center; gap: 8px; }
+  .row-pending { color: var(--ink); font-size: .95rem; }
+  .step { padding: 5px 0; font-size: .85rem; display: flex; gap: 8px; align-items: baseline; }
+  .step.ok { color: var(--success); }
+  .step.err { color: var(--danger); white-space: pre-wrap; }
+  .notice {
+    margin-top: 14px; padding: 12px 14px; background: #f1f5f9; border: 1px solid var(--hairline);
+    border-radius: 10px; font-size: .88rem; color: var(--ink);
+  }
+
+  /* Payment-method group (Shopify-style radio group + one Pay CTA) */
+  .pm-head { font-size: .8rem; letter-spacing: .04em; text-transform: uppercase; color: var(--muted); font-weight: 700; margin: 0 0 12px; }
+  .pm-group { border: 1px solid var(--hairline); border-radius: 10px; overflow: hidden; }
+  .pm-row { display: flex; gap: 10px; align-items: flex-start; padding: 12px 14px; cursor: pointer; border-bottom: 1px solid var(--hairline); }
+  .pm-row:last-child { border-bottom: none; }
+  .pm-row:has(input:checked) { background: #f0fdfa; box-shadow: inset 3px 0 0 var(--accent); }
+  .pm-row input { margin-top: 3px; accent-color: var(--accent); }
+  .pm-name { display: block; font-size: .9rem; font-weight: 600; color: var(--ink); }
+  .pm-desc { display: block; font-size: .8rem; color: var(--muted); margin-top: 2px; }
+  .step-no { display: inline-block; min-width: 1.4em; color: var(--muted); font-variant-numeric: tabular-nums; }
+
+  /* Calm payment-lock state (never alarming) */
+  .lock {
+    display: flex; align-items: center; gap: 8px; justify-content: center;
+    color: var(--muted); font-size: .9rem; padding: 14px;
+    background: #f1f5f9; border: 1px solid var(--hairline); border-radius: 10px;
+  }
+
+  /* Discreet trust footer */
+  .trust { margin-top: 22px; text-align: center; }
+  .trust .trust-line { font-size: .78rem; color: var(--muted); }
+
+  /* Tidy success / receipt card */
+  .receipt-banner {
+    background: var(--accent); color: #fff; border-radius: 12px; padding: 16px;
+    text-align: center; font-weight: 700; font-size: 1.05rem; margin-bottom: 12px;
+  }
+  .receipt-banner .sub { font-weight: 500; font-size: .85rem; opacity: .95; margin-top: 4px; }
+  .receipt-banner a { color: #fff; text-decoration: underline; }
+
+  /* Prominent end-of-ceremony handoff — shown when the WHOLE ceremony is done
+     (payment is the last gate). Bigger than the inline receipt banner: the order is
+     complete and the buyer can close the window; the agent (MCP host) polls
+     order-status and continues the conversation. */
+  .complete-banner {
+    background: var(--accent); color: #fff; border-radius: 14px; padding: 22px 18px 20px;
+    text-align: center; margin-bottom: 14px; box-shadow: var(--shadow);
+  }
+  .complete-banner .big { font-size: 1.35rem; font-weight: 800; line-height: 1.2; }
+  .complete-banner .sub { font-weight: 500; font-size: .92rem; opacity: .97; margin-top: 8px; line-height: 1.5; }
+  .complete-banner .sub strong { font-weight: 800; }
+  .complete-banner .ret { display: inline-block; margin-top: 12px; font-size: .82rem; opacity: .92; }
+  .complete-banner a { color: #fff; text-decoration: underline; }
+
+  /* Indeterminate settling bar — shown while x402 settles on-chain (~10s). A teal
+     sliver slides across a hairline track so the buyer sees the wait is live work,
+     not a hang. Hidden until a page adds .on; both payment rails use it. */
+  .settling-bar { display: none; margin: 14px 0 2px; height: 6px; background: var(--hairline); border-radius: 999px; overflow: hidden; }
+  .settling-bar.on { display: block; }
+  .settling-bar > i { display: block; width: 35%; height: 100%; background: var(--accent); border-radius: 999px; animation: settle-slide 1.15s ease-in-out infinite; }
+  @keyframes settle-slide { from { margin-left: -35%; } to { margin-left: 100%; } }
+
+  /* x402 settlement receipt — on-chain proof, design-system styled. The settle card
+     reuses the surface chrome; the teal left rail marks it as the success path. */
+  .settle {
+    margin-top: 14px; padding: 14px 16px; background: #f0fdfa;
+    border: 1px solid var(--hairline); border-left: 3px solid var(--accent);
+    border-radius: 10px;
+  }
+  .settle .settle-head { font-weight: 700; font-size: .95rem; color: var(--success); margin: 0 0 8px; }
+  .settle dl.kv { display: grid; grid-template-columns: 64px 1fr; gap: 4px 12px; margin: 0; font-size: .9rem; }
+  .settle dl.kv dt { color: var(--muted); font-size: .8rem; padding-top: 1px; }
+  .settle dl.kv dd { margin: 0; word-break: break-word; }
+  .settle .dim { color: var(--muted); font-weight: 400; font-size: .78rem; }
+  .settle .mono { font-family: ui-monospace, Menlo, monospace; font-size: .78rem; word-break: break-all; }
+  /* Prominent, tappable HashScan link — the buyer is on their phone; one tap to the
+     live explorer is the third-party proof (no QR; the package has no qr route). */
+  .settle .hashscan {
+    display: flex; align-items: center; justify-content: center; gap: 8px;
+    margin-top: 12px; height: 44px; border-radius: 10px;
+    background: var(--accent); color: #fff; font-weight: 600; font-size: .92rem;
+    text-decoration: none;
+  }
+  .settle .hashscan:hover { background: var(--accent-hover); }
+  /* Calm "authorized, not settled" line — never alarming red wall; a muted danger row. */
+  .settle-failed {
+    margin-top: 14px; padding: 12px 14px; background: #fef2f2;
+    border: 1px solid var(--hairline); border-left: 3px solid var(--danger);
+    border-radius: 10px; font-size: .88rem; color: var(--danger);
+  }
+`;
+/** <head> with the shared design-system CSS. `extraCss` lets a page add the few
+ *  component styles unique to it without forking the design language. */
+export function pageHead(title, extraCss = "") {
+    return `<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>${escapeHtml(title)}</title>
+<style>${DESIGN_CSS}${extraCss}</style>
+</head>`;
+}
+/** The ATTESTOMCP wordmark + a discreet DEMO pill, with an optional confident h1 +
+ *  identity-first tagline underneath. Pass `h1`/`tagline` to render the heading block;
+ *  omit them to render just the brand row (a page can lay out its own heading). */
+export function brandHeader(opts = {}) {
+    const heading = opts.h1 != null
+        ? `<div class="head"><h1>${escapeHtml(opts.h1)}</h1>${opts.tagline != null ? `<p class="tagline">${escapeHtml(opts.tagline)}</p>` : ""}</div>`
+        : "";
+    return `<div class="brand"><span class="wordmark">ATTESTOMCP</span><span class="demo-pill">DEMO</span></div>${heading}`;
+}
+/** An indeterminate "settling…" progress bar (hidden until JS adds `.on`). Shown on
+ *  the payment rails while x402 settlement runs on-chain (~10s) so the wait reads as
+ *  live work. `id` defaults to "settling" for the page script to toggle. */
+export function settlingBar(id = "settling") {
+    return `<div class="settling-bar" id="${id}"><i></i></div>`;
+}
+/**
+ * The prominent end-of-ceremony handoff banner: every attestation + payment is done,
+ * so the order is COMPLETE. It tells the buyer they can close the window and continue
+ * in their agent — the MCP host polls order-status and resumes the conversation
+ * automatically (Mode A: the agent never runs the ceremony, it only orchestrates +
+ * polls). An optional secondary link returns to the checkout hub for a pure-browser
+ * flow. Built server-side and embedded into the gate page's receipt script.
+ */
+export function completionHandoffBanner(returnUrl) {
+    const ret = returnUrl
+        ? `<a class="ret" href="${escapeHtml(returnUrl)}">Staying in the browser? Return to checkout ›</a>`
+        : "";
+    return `<div class="complete-banner"><div class="big">✓ Order complete</div><div class="sub">You can <strong>close this window</strong> and continue in your agent — it has your order and will pick up from here.</div>${ret}</div>`;
+}
+/** The order summary card: line items, an accent discount row, a bold Total with a
+ *  top hairline. Money is tabular. Shared by all three pages so the cart reads the
+ *  same everywhere. */
+export function orderSummaryCard(args) {
+    const cur = args.currency;
+    const rows = args.lines
+        .map((l) => `<tr class="line"><td>${escapeHtml(l.name)} <span class="qty">×${l.quantity}</span></td><td class="num">${money(l.lineTotal, l.currency ?? cur)}</td></tr>`)
+        .join("\n");
+    const discount = args.discount ?? 0;
+    const discRow = discount > 0
+        ? `<tr class="disc"><td>${escapeHtml(args.discountLabel ?? "Discount")}</td><td class="num">-${money(discount, cur)}</td></tr>`
+        : "";
+    const caption = args.caption ? `<p class="card-title">${escapeHtml(args.caption)}</p>` : "";
+    return `<div class="card summary">
+  ${caption}<table>
+    ${rows}
+    ${discRow}
+    <tr class="total"><td>Total</td><td class="num">${money(args.total, cur)}</td></tr>
+  </table>
+</div>`;
+}
+/**
+ * The Age · Membership · Pay stepper. DONE = filled accent with ✓; CURRENT (the step
+ * at `currentIndex`, when not already done) = accent ring; everything else = muted.
+ * The hub passes real status; each gate page marks its OWN step current.
+ */
+export function progressRail(steps, currentIndex) {
+    if (steps.length === 0)
+        return "";
+    const dots = steps
+        .map((s, i) => {
+        const isDone = !!s.done;
+        const isCurrent = i === currentIndex && !isDone;
+        const cls = isDone ? "done" : isCurrent ? "current" : "";
+        const mark = isDone ? "✓" : String(i + 1);
+        return `<div class="rail-step ${cls}"><div class="rail-dot">${mark}</div><div class="rail-label">${escapeHtml(s.label)}</div></div>`;
+    })
+        .join("");
+    return `<div class="rail" role="list" aria-label="Progress">${dots}</div>`;
+}
+// ── Trust footer ────────────────────────────────────────────────────────────
+/**
+ * The single, DISCREET presence-only honesty line (replaces the old yellow warning
+ * box). It MUST keep the literal "presence-only-demo" token (FR-011 + the honesty
+ * tests) — the wire crypto is real; the issuer trust anchor is not.
+ */
+export function trustFooter() {
+    return `<div class="trust"><div class="trust-line">🔒 presence-only-demo · secured by AttestoMcp · the wire crypto is real; issuer trust anchor is not</div></div>`;
+}

package/dist/ceremony/types.d.ts

@@ -0,0 +1,95 @@
+import type { CartMandate } from "./cartMandate.js";
+import type { SettlementRecordLike } from "./completion.js";
+export type MaybePromise<T> = T | Promise<T>;
+export interface CeremonyOrderLine {
+    /** Product id. */
+    id: string;
+    /** Display name (optional; the catalog is the source of truth). */
+    name?: string;
+    /** Unit price (catalog-authoritative). */
+    unitPrice: number;
+    /** Quantity. */
+    quantity: number;
+    /** unitPrice × quantity. */
+    lineTotal: number;
+    /** ISO 4217 (optional; order-level currency is authoritative). */
+    currency?: string;
+    /** Per-product age threshold (e.g. 21), re-derived from the catalog. */
+    minimumAge?: number;
+    /** Product category — available to custom `.when()` predicates. */
+    category?: string;
+}
+export interface CeremonyOrder {
+    /** Stable per checkout. */
+    id: string;
+    lines: CeremonyOrderLine[];
+    itemCount?: number;
+    subtotal: number;
+    /** Re-derived from the catalog + this order's verified loyalty state. */
+    discount: number;
+    /** subtotal − discount; re-derived, never trusted from the token. */
+    total: number;
+    currency: string;
+    createdAt?: string;
+}
+export interface CartItemRef {
+    productId: string;
+    quantity: number;
+}
+export interface RepriceOpts {
+    ageVerified?: boolean;
+    loyaltyApplied?: boolean;
+}
+export interface CeremonyCatalog {
+    /**
+     * Re-price an order's lines from the catalog — the SERVER-SIDE source of truth
+     * (Security invariant 2: never trust the token's totals). The id is preserved;
+     * the loyalty discount is applied only when THIS order's verification opts in.
+     * Mirrors the demo's `createOrder(items, id, opts)` so it injects with no glue.
+     */
+    createOrder(items: CartItemRef[], orderId: string, opts?: RepriceOpts): CeremonyOrder;
+}
+export interface CeremonyOrderStore {
+    /**
+     * Resolve a created order by id. Totals are re-derived from the catalog
+     * regardless (CT3) — this only recovers the line items + id, never the price.
+     */
+    read(orderId: string): MaybePromise<CeremonyOrder | null | undefined>;
+}
+export interface GateOutcome {
+    gate: string;
+    pass: boolean;
+    detail: string;
+}
+export interface CompletionInput {
+    order: CeremonyOrder;
+    mandateId: string;
+    amount: number;
+    currency: string;
+    method: string;
+    instrument?: unknown;
+    gates: GateOutcome[];
+    /** Optional signed Cart Mandate (ap2.CartMandate). When present AND the context has a
+     *  `signingKey`, completion verifies it (signature + order-id binding + expiry) BEFORE
+     *  re-pricing and refuses a tampered/replayed/expired cart — additive, fail-closed
+     *  defense-in-depth; the catalog stays the price authority either way. */
+    cartMandate?: CartMandate;
+}
+export interface CompletionResult {
+    completed: boolean;
+    settlement?: SettlementRecordLike;
+    settlementError?: string;
+    /** Why a non-completion happened — a failed ceremony ("gates"), a tampered/replayed/
+     *  expired Cart Mandate ("cart-mandate"), a tampered token re-priced against the
+     *  catalog ("reprice"), a signed Cart Mandate and signed Payment Mandate that
+     *  disagree on order/amount/currency ("reconcile"), or an age-restricted order with
+     *  no proven per-order age claim ("age"). */
+    reason?: "gates" | "cart-mandate" | "reprice" | "reconcile" | "age";
+}
+/**
+ * The host-bound completion seam mount() hands to each rail. The host pre-binds
+ * it to its completed-order + cart stores; the package ships `completeOrder`
+ * (completion.ts) as one ready implementation over the injected ceremony context.
+ */
+export type CompletionSeam = (input: CompletionInput) => MaybePromise<CompletionResult>;
+export type SettlementSeam = (order: CeremonyOrder) => Promise<SettlementRecordLike>;

package/dist/ceremony/types.js

@@ -0,0 +1 @@
+export {};

package/dist/client.d.ts

@@ -0,0 +1,39 @@
+import type { AttestoMcpOptions, GateOrder, Step, VerificationManifestEntry, VerificationStore } from "./types.js";
+import { type CeremonySeams } from "./ceremony/mount.js";
+/** The ceremony seams the host supplies to `mount()`; the per-order
+ *  verification store is AttestoMcp's own, so the host never passes it here. */
+export type MountCeremony = Omit<Partial<CeremonySeams>, "verificationStore">;
+/**
+ * Minimal structural type for an Express app — the package stays dependency-free
+ * (no `express` import). `mount()` only needs `app.locals` for the store seam.
+ */
+export interface ExpressApp {
+    locals: Record<string, unknown>;
+}
+export declare class AttestoMcp {
+    readonly walletOrigin: string;
+    readonly store: VerificationStore;
+    private mountedRoutes;
+    constructor(opts?: AttestoMcpOptions);
+    /**
+     * Context 1 — resolve a policy against a server-priced order into the flat,
+     * JSON-safe `requires` manifest. Runs `.when()`/`appliesTo` predicates,
+     * payment-last; no functions cross the wire.
+     */
+    requirements(order: GateOrder, policy: Step[]): VerificationManifestEntry[];
+    /**
+     * Context 2 — wire the verification ceremony onto your Express app.
+     *
+     * Pass the ceremony seams (`{ orderStore, catalog, completion, signingKey, … }`)
+     * to register the gate's routes through `mountCeremony`: it validates the seams,
+     * FAILS FAST on a missing required one (CT2), and attaches each rail. AttestoMcp's
+     * own per-order store is injected as the `verificationStore` (keyed by order id,
+     * never process-global — Security invariant 4), so the host never passes it.
+     *
+     * Called WITHOUT seams it keeps the v0.1 behavior: expose the per-order store
+     * via `app.locals.attestomcp` so a host's existing fail-closed `/credential-gate/*`
+     * routes resolve verification state THROUGH AttestoMcp. The rails register only
+     * when seams are supplied; with none extracted yet, that path attaches no routes.
+     */
+    mount(app: ExpressApp, ceremony?: MountCeremony): void;
+}

package/dist/client.js

@@ -0,0 +1,84 @@
+// The configure-once client (Principle I): construct with your wallet origin,
+// then declarative calls. `requirements(order, policy)` resolves a policy to the
+// serializable manifest (Context 1); `mount(app)` is the Context-2 seam.
+import { resolveRequirements } from "./manifest.js";
+import { MemoryVerificationStore } from "./store.js";
+import { mountCeremony } from "./ceremony/mount.js";
+/** Zero-config default so `new AttestoMcp()` works for local dev. */
+const DEFAULT_WALLET_ORIGIN = `http://localhost:${process.env.PORT ?? 3000}`;
+export class AttestoMcp {
+    walletOrigin;
+    store;
+    // True once the ceremony rails are wired onto a host app (so `/attestomcp/*` routes
+    // exist on this server). `requirements()` then emits approve links that resolve
+    // to those mounted routes rather than the legacy `/credential-gate/*` shape.
+    mountedRoutes = false;
+    constructor(opts = {}) {
+        let origin = opts.walletOrigin?.trim();
+        if (!origin) {
+            // Zero-config: default to localhost so the getting-started example just runs.
+            origin = DEFAULT_WALLET_ORIGIN;
+        }
+        else if (!/^https?:\/\//.test(origin)) {
+            // Wallet ceremonies are origin-bound, so a scheme-less value can't work.
+            // Warn and fall back rather than hard-failing (DX over a thrown error).
+            console.warn(`[attestomcp] walletOrigin "${origin}" is not an absolute http(s) origin; using ${DEFAULT_WALLET_ORIGIN}. ` +
+                `Pass an absolute origin (e.g. https://shop.example) for any deployed environment.`);
+            origin = DEFAULT_WALLET_ORIGIN;
+        }
+        // OpenID4VP / WebAuthn are origin-bound, so a localhost origin in production
+        // mints approve links a buyer's phone can't reach. Warn loudly — not fatal.
+        if (process.env.NODE_ENV === "production" && /^https?:\/\/(localhost|127\.0\.0\.1)/.test(origin)) {
+            console.warn(`[attestomcp] walletOrigin is ${origin} in production — buyers can't open localhost approve links. ` +
+                `Set { walletOrigin } to your public origin.`);
+        }
+        this.walletOrigin = origin.replace(/\/$/, "");
+        this.store = opts.store ?? new MemoryVerificationStore();
+    }
+    /**
+     * Context 1 — resolve a policy against a server-priced order into the flat,
+     * JSON-safe `requires` manifest. Runs `.when()`/`appliesTo` predicates,
+     * payment-last; no functions cross the wire.
+     */
+    requirements(order, policy) {
+        return resolveRequirements(order, policy, { walletOrigin: this.walletOrigin, mountedRoutes: this.mountedRoutes });
+    }
+    /**
+     * Context 2 — wire the verification ceremony onto your Express app.
+     *
+     * Pass the ceremony seams (`{ orderStore, catalog, completion, signingKey, … }`)
+     * to register the gate's routes through `mountCeremony`: it validates the seams,
+     * FAILS FAST on a missing required one (CT2), and attaches each rail. AttestoMcp's
+     * own per-order store is injected as the `verificationStore` (keyed by order id,
+     * never process-global — Security invariant 4), so the host never passes it.
+     *
+     * Called WITHOUT seams it keeps the v0.1 behavior: expose the per-order store
+     * via `app.locals.attestomcp` so a host's existing fail-closed `/credential-gate/*`
+     * routes resolve verification state THROUGH AttestoMcp. The rails register only
+     * when seams are supplied; with none extracted yet, that path attaches no routes.
+     */
+    mount(app, ceremony) {
+        if (ceremony) {
+            mountCeremony(app, { ...ceremony, verificationStore: this.store });
+            this.mountedRoutes = true;
+            return;
+        }
+        // Zero-arg compose (the quickstart): a host (e.g. attestomcp-storefront) has
+        // already populated the ceremony seams on `app.locals.attestomcp`. Wire the rails
+        // straight from those seams — including the host's OWN verificationStore when it
+        // supplied one, so its `completion` seam shares the exact per-order state the
+        // rails write (invariant 4). Falls back to AttestoMcp's own store otherwise.
+        const locals = (app.locals.attestomcp ?? {});
+        if (locals.orderStore && locals.catalog && locals.completion) {
+            mountCeremony(app, locals.verificationStore ? {} : { verificationStore: this.store });
+            this.mountedRoutes = true;
+            return;
+        }
+        // Legacy (no seams): expose the per-order store so a host's existing
+        // fail-closed routes resolve verification THROUGH AttestoMcp.
+        const existing = app.locals.attestomcp;
+        if (existing?.store === this.store)
+            return; // idempotent
+        app.locals.attestomcp = { store: this.store, walletOrigin: this.walletOrigin };
+    }
+}

package/dist/credentials.d.ts

@@ -0,0 +1,48 @@
+import type { Credential, DcqlQuery, Effect, GateOrder, Step } from "./types.js";
+export declare function gate(): Effect;
+export declare function discount(opts: {
+    percent?: number;
+    amount?: number;
+}): Effect;
+export declare function authorize(): Effect;
+/**
+ * Concise DCQL for a single mdoc credential: name the doctype and the claim
+ * leaves, get back the full verifier-shaped `DcqlQuery`. Selective disclosure
+ * (never retain) is the default.
+ */
+export declare function dcql(spec: {
+    docType: string;
+    claims: string[];
+}): DcqlQuery;
+/** Age verification. `age.over(21)` proves the `age_over_21` claim (explicit positive). */
+export declare const age: {
+    over(minAge: number): Credential;
+};
+/** Loyalty / membership — optional; presenting it applies a discount. */
+export declare const membership: {
+    discount(percent: number): Credential;
+};
+/**
+ * Payment authorization. Settles LAST (the resolver sorts authorize-effect
+ * entries to the end). The amount is derived from the order server-side, never
+ * passed as a field (Principle IV / Security invariant 2).
+ */
+export declare const payment: {
+    in(currency: string): Credential;
+};
+/** Define a custom credential — gate ANY consequential action with ANY credential. */
+export declare function defineCredential(c: {
+    id: string;
+    request: DcqlQuery;
+    verify: (claims: Record<string, unknown>) => boolean;
+    effect: Effect;
+    appliesTo?: (order: GateOrder) => boolean;
+    ui: {
+        label: string;
+        action: string;
+    };
+}): Credential;
+/** A required gate — present in the manifest whenever it applies. */
+export declare function required(c: Credential): Step;
+/** An optional gate — surfaced but never blocking. */
+export declare function optional(c: Credential): Step;