@openmobilehub/credentagent-storefront 0.2.0

package/dist/server.js

@@ -0,0 +1,506 @@
+// createStorefront() — a runnable storefront in one line.
+//
+// Stands up the real MCP storefront — the nine shopping tools (six UI-linked to the
+// React widget, three plain) + the single-file widget resource + a checkout page —
+// over HTTP at /mcp, around an injected catalog. The checkout tool is UNGATED by
+// default; call `store.gate(resolve)` to have it surface a `requires` manifest,
+// which is exactly where @openmobilehub/credentagent-gate mounts on:
+//
+//   const store = createStorefront();
+//   const credentagent = new CredentAgent();
+//   credentagent.mount(store.app);
+//   store.gate((order) => credentagent.requirements(order, [ required(age.over(21).when(hasAlcohol)) ]));
+//   const { url } = await store.listen(3005);   // → add http://localhost:3005/mcp to Claude / ChatGPT
+import { readFile } from "node:fs/promises";
+import { readFileSync } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { registerAppTool, registerAppResource, RESOURCE_MIME_TYPE } from "@modelcontextprotocol/ext-apps/server";
+import { randomBytes } from "node:crypto";
+import express from "express";
+import { z } from "zod";
+import { CART_META_KEY, CATALOG_META_KEY, createOrder, getProduct, getReviews, isCatalogSource, priceCart, SAMPLE_CATALOG, staticCatalog, } from "./index.js";
+import { appToolMeta } from "./tool-meta.js";
+import { MemoryCartStore, MemoryOrderStore } from "./state.js";
+// Composition with @openmobilehub/credentagent-gate (Context 2): the storefront pre-binds
+// the gate's shared `completeOrder` over ITS OWN stores + catalog and publishes the
+// ceremony seams on `app.locals.credentagent`, so `new CredentAgent().mount(store.app)` wires
+// the `/credentagent/*` rails with zero explicit args (the quickstart). The gate stays an
+// optional pairing — only this server module imports it; the pure pricing core
+// (`./index.js`) does not.
+import { completeOrder, issueCartMandate, verifyCartMandate, decodeCartMandateParam, renderRequirements, MemoryVerificationStore, } from "@openmobilehub/credentagent-gate";
+// ── widget bundle (single-file html, built by vite into dist/ui/) ───────────
+const SKYBRIDGE_MIME = "text/html+skybridge";
+// Product images are self-contained `data:` URIs (added to the CSP below); picsum
+// stays allowlisted in case a custom catalog uses remote images.
+const IMAGE_DOMAINS = ["https://picsum.photos", "https://fastly.picsum.photos"];
+function bundleCandidates() {
+    return [join(import.meta.dirname, "ui", "mcp-app.html"), join(process.cwd(), "dist", "ui", "mcp-app.html")];
+}
+// Stamp the resource URI with a short hash of the bundle so hosts re-fetch exactly
+// when the widget changes (they cache by URI). "dev" until the bundle is on disk.
+function bundleVersion() {
+    for (const c of bundleCandidates()) {
+        try {
+            return createHash("sha256").update(readFileSync(c)).digest("hex").slice(0, 8);
+        }
+        catch {
+            /* try next */
+        }
+    }
+    return "dev";
+}
+async function loadBundle() {
+    for (const c of bundleCandidates()) {
+        try {
+            return await readFile(c, "utf-8");
+        }
+        catch {
+            /* try next */
+        }
+    }
+    throw new Error(`credentagent-storefront: widget bundle not found (looked in: ${bundleCandidates().join(", ")})`);
+}
+// Derive this server's public origin from the incoming request. Proxies (Vercel,
+// tunnels) set x-forwarded-*; fall back to the Host header. Lets the storefront
+// build absolute checkout URLs at any origin when baseUrl wasn't configured.
+export function originFromRequest(req) {
+    const fwd = (name) => req.headers[name]?.split(",")[0]?.trim();
+    const proto = fwd("x-forwarded-proto") ?? req.protocol ?? "http";
+    const host = fwd("x-forwarded-host") ?? req.headers.host;
+    return host ? `${proto}://${host}`.replace(/\/+$/, "") : "";
+}
+// Re-home a mounted-ceremony approve link (`/credentagent/*`) onto THIS server's origin —
+// the same base the checkout link uses — so the gate links and the checkout link
+// share an origin (the rails are registered on this same app). Links to any other
+// path (e.g. a developer's external wallet origin) pass through untouched.
+function homeApproveUrl(approveUrl, base) {
+    try {
+        const u = new URL(approveUrl, "http://re-home.invalid");
+        if (u.pathname.startsWith("/credentagent/"))
+            return `${base}${u.pathname}${u.search}`;
+    }
+    catch {
+        /* not URL-shaped — leave as-is */
+    }
+    return approveUrl;
+}
+// Re-home every `/credentagent/*` approveUrl in a `requires` manifest onto `base`, and
+// (statelessOrders) append the `cart` param so each gate rail page can reconstruct the
+// order from the signed mandate rather than a store read.
+function homeRequires(requires, base, cart) {
+    return requires.map((e) => {
+        const entry = e;
+        if (typeof entry.approveUrl !== "string")
+            return e;
+        let approveUrl = homeApproveUrl(entry.approveUrl, base);
+        if (cart)
+            approveUrl += `${approveUrl.includes("?") ? "&" : "?"}cart=${cart}`;
+        return { ...entry, approveUrl };
+    });
+}
+export function createStorefront(opts = {}) {
+    // Normalize the catalog into a CatalogSource: a plain array (or the default) is wrapped
+    // in a static source; a dynamic source (e.g. `firestoreCatalog(...)`) is used as-is. Every
+    // catalog read below goes through `source.current()` — the last-known-good snapshot the
+    // prime middleware keeps warm — so the SYNCHRONOUS re-price paths (incl. the gate's
+    // ceremony `createOrder`) re-derive prices/ages server-side (invariant 2) with no gate change.
+    const source = isCatalogSource(opts.catalog)
+        ? opts.catalog
+        : staticCatalog(opts.catalog ?? SAMPLE_CATALOG);
+    const reviews = opts.reviews;
+    // Per-slot store resolution: an explicit store wins, else the `storage` provider's
+    // store for that slot (e.g. `redisStorage(...)`), else the in-memory default. Keeping
+    // the in-memory fallback last means zero-config stays unchanged (no `storage` → memory).
+    const cartStore = opts.cartStore ?? opts.storage?.cartStore ?? new MemoryCartStore();
+    // orderId → sessionId, recorded at checkout so the completion path (browser / place-order,
+    // which has no MCP session) can clear the RIGHT session's cart. In-memory, so on
+    // multi-instance serverless it shares the stateful-session limitation (needs sticky
+    // sessions); elsewhere it's best-effort and the cart simply isn't cleared.
+    const orderSessions = new Map();
+    const orderStore = opts.orderStore ?? opts.storage?.orderStore ?? new MemoryOrderStore();
+    // Created-but-not-completed orders, for the checkout page + place-order. A store
+    // (not a process Map) so it can be shared across serverless instances.
+    const createdOrderStore = opts.createdOrderStore ?? opts.storage?.createdOrderStore ?? new MemoryOrderStore();
+    // Per-order verification state shared with the mounted ceremony (the rails write
+    // it; the completion seam below reads it back to re-price + enforce the age gate).
+    const verificationStore = opts.verificationStore ?? opts.storage?.verificationStore ?? new MemoryVerificationStore();
+    let resolveGate;
+    let baseUrl = opts.baseUrl?.replace(/\/+$/, "") ?? "";
+    // statelessOrders (gate FR-007): the signed Cart Mandate is the created-order transport.
+    // The storefront must OWN a concrete signing key (not the gate's ephemeral one) so the
+    // mandate the checkout tool issues is the one the gate rails verify.
+    //
+    // That key MUST be STABLE across instances — statelessOrders exists to survive an
+    // instance split, and a per-process random key would make a mandate minted on instance A
+    // fail to verify on instance B (defeating the whole feature). So fail fast unless the host
+    // provides a `signingKey`, OR explicitly opts into an ephemeral per-process key
+    // (single-process dev / tests) — mirroring the gate's `allowEphemeralKey` escape hatch.
+    const statelessOrders = opts.statelessOrders ?? false;
+    if (statelessOrders && !opts.signingKey && !opts.allowEphemeralKey) {
+        throw new Error("[credentagent-storefront] statelessOrders requires a stable `signingKey` so a cart mandate minted on " +
+            "one instance verifies on another. Pass { signingKey } (e.g. process.env.GATE_SECRET), or " +
+            "{ allowEphemeralKey: true } for a single-process dev server / tests.");
+    }
+    const signingKey = opts.signingKey ?? (statelessOrders ? randomBytes(32).toString("hex") : undefined);
+    // Issue + base64url-encode a Cart Mandate for a priced order (the checkout link's `cart`).
+    const cartParamFor = (order) => {
+        const mandate = issueCartMandate({ orderId: order.id, lines: order.lines.map((l) => ({ id: l.id, quantity: l.quantity, unitPrice: l.unitPrice, lineTotal: l.lineTotal })), currency: order.currency, total: order.total }, signingKey);
+        return Buffer.from(JSON.stringify(mandate)).toString("base64url");
+    };
+    const withCart = (url, cart) => cart ? `${url}${url.includes("?") ? "&" : "?"}cart=${cart}` : url;
+    // Resolve a created order by id: from a VERIFIED cart mandate (statelessOrders, no store
+    // read) or the createdOrderStore. Fails closed — a forged/tampered/expired mandate → null.
+    const resolveCreated = async (orderId, cartRaw) => {
+        if (statelessOrders && cartRaw !== undefined) {
+            const verdict = verifyCartMandate(decodeCartMandateParam(cartRaw), orderId, signingKey);
+            if (!verdict.ok)
+                return null;
+            return createOrder(verdict.mandate.lines.map((l) => ({ productId: l.id, quantity: l.quantity })), orderId, source.current());
+        }
+        return (await createdOrderStore.read(orderId)) ?? null;
+    };
+    const BUNDLE_VERSION = bundleVersion();
+    const RESOURCE_URI = `ui://product-picker/mcp-app-${BUNDLE_VERSION}.html`;
+    const SKYBRIDGE_URI = `ui://product-picker/mcp-app-${BUNDLE_VERSION}.skybridge.html`;
+    // One canonical tool-meta for every UI-linked tool — both host surfaces, with
+    // openai/widgetAccessible always on (FR-014).
+    const UI_META = appToolMeta({ resourceUri: RESOURCE_URI, skybridgeUri: SKYBRIDGE_URI });
+    const app = createMcpExpressApp({ host: "0.0.0.0" });
+    // place-order accepts the order id from either a JSON fetch (the shared checkout
+    // page's instant-demo method) or an x-www-form-urlencoded form post; the SDK app
+    // only parses JSON, so add a urlencoded parser too or a form post's `req.body.order`
+    // is undefined and completion is never recorded.
+    app.use(express.urlencoded({ extended: false }));
+    // Prime the catalog before EVERY route runs — including the `/credentagent/*` ceremony
+    // rails a consumer mounts later (registered after this middleware, so this runs first).
+    // Awaiting the TTL-cached load means every synchronous `source.current()` below reads a
+    // warm, server-side re-derived snapshot. A cold/unreachable load FAILS CLOSED (503, no
+    // handler runs) rather than serving an empty catalog (Security invariant 2). The static
+    // default resolves instantly and never fails, so the zero-config path is unchanged.
+    app.use((_req, res, next) => {
+        source.load().then(() => next(), () => res.status(503).type("text").send("Catalog temporarily unavailable."));
+    });
+    // ── CredentAgent ceremony seams (Context 2) ──────────────────────────────────────
+    // Pre-bound so `new CredentAgent().mount(store.app)` wires the `/credentagent/*` rails with
+    // ZERO explicit args — it reads these off `app.locals.credentagent` (see the quickstart).
+    // The catalog re-prices server-side (the amount source of truth — invariant 2); the
+    // completion seam is the gate's shared `completeOrder` bound over THIS server's
+    // stores, so a finished ceremony records the order + clears the cart the SAME way
+    // get-order-status / the order-status poll read.
+    const ceremonyCatalog = {
+        createOrder: (items, orderId, repriceOpts) => createOrder(items, orderId, source.current(), { ageVerified: repriceOpts?.ageVerified, loyaltyApplied: repriceOpts?.loyaltyApplied }),
+    };
+    const ceremonyOrderStore = {
+        // A storefront Order is structurally a CeremonyOrder; resolveOrder re-prices it
+        // from the catalog regardless, recovering only the line items + id (CT3).
+        read: (orderId) => createdOrderStore.read(orderId),
+    };
+    const completion = (input) => completeOrder(input, {
+        catalog: ceremonyCatalog,
+        verificationStore,
+        records: {
+            read: async (orderId) => ((await orderStore.read(orderId)) ?? undefined),
+            write: async (record) => { await orderStore.write(record.orderId, record); },
+        },
+        cart: { clear: async () => { const sid = orderSessions.get(input.order.id); if (sid)
+                await cartStore.write(sid, new Map()); } },
+        ...(opts.settle ? { settle: opts.settle } : {}),
+    });
+    app.locals.credentagent = {
+        orderStore: ceremonyOrderStore,
+        verificationStore,
+        catalog: ceremonyCatalog,
+        completion,
+        // signingKey survives an instance split; default to an ephemeral per-process key
+        // for a single-process dev server / tests when none is configured (but statelessOrders
+        // forces a concrete, storefront-owned key so it can sign the mandate).
+        ...(signingKey ? { signingKey } : {}),
+        allowEphemeralKey: opts.allowEphemeralKey ?? !signingKey,
+        statelessOrders,
+    };
+    // ── cart logic (per-session over the catalog source + the cart store) ─────
+    // Each MCP session gets its own working cart: `sessionId` is the MCP session
+    // (extra.sessionId); a fallback key covers non-session transports (e.g. the in-memory
+    // transport used in tests) so single-connection flows work.
+    // `priceFrom` reads the warm catalog snapshot synchronously; every async entry below
+    // first `await source.load()` so the snapshot is fresh regardless of transport — the
+    // HTTP `/mcp` route is already primed by the middleware, but `mcpServer()` over a raw
+    // transport (e.g. stdio) is not, so the tool handlers warm the catalog themselves.
+    const DEFAULT_SESSION = "default";
+    const sessionOf = (extra) => extra.sessionId ?? DEFAULT_SESSION;
+    const priceFrom = (cart) => priceCart([...cart.entries()].map(([productId, quantity]) => ({ productId, quantity })), source.current());
+    const readPriced = async (sessionId) => {
+        await source.load();
+        return priceFrom(await cartStore.read(sessionId));
+    };
+    const addToCart = async (sessionId, items) => {
+        await source.load();
+        const cart = await cartStore.read(sessionId);
+        for (const { productId, quantity } of items) {
+            if (quantity <= 0)
+                continue;
+            cart.set(productId, (cart.get(productId) ?? 0) + quantity);
+        }
+        await cartStore.write(sessionId, cart);
+        return priceFrom(cart);
+    };
+    const setQuantity = async (sessionId, productId, quantity) => {
+        await source.load();
+        const cart = await cartStore.read(sessionId);
+        if (quantity <= 0)
+            cart.delete(productId);
+        else
+            cart.set(productId, quantity);
+        await cartStore.write(sessionId, cart);
+        return priceFrom(cart);
+    };
+    const removeFromCart = async (sessionId, productId) => {
+        await source.load();
+        const cart = await cartStore.read(sessionId);
+        cart.delete(productId);
+        await cartStore.write(sessionId, cart);
+        return priceFrom(cart);
+    };
+    // Cart-bearing result, emitted three ways so either host reads it: structuredContent
+    // (ChatGPT widget + model), a JSON text block, and _meta (Claude's out-of-band channel).
+    const cartResult = (priced) => ({
+        structuredContent: { products: source.current(), cart: priced },
+        content: [{ type: "text", text: JSON.stringify(priced) }],
+        _meta: { [CART_META_KEY]: priced },
+    });
+    function buildServer() {
+        const server = new McpServer({ name: "credentagent-storefront", version: "0.1.0" });
+        // ── UI-linked tools (6) — registerAppTool + the canonical UI_META ───────
+        registerAppTool(server, "browse-products", {
+            title: "Browse Products",
+            description: "Show the storefront catalog as an interactive visual product picker (a grid with images). " +
+                "Call this whenever the user asks what you sell, what's available, to see/show/browse products, or " +
+                "to shop — it renders the grid for them. Prefer it over describing the catalog in text.",
+            inputSchema: {},
+            annotations: { readOnlyHint: true },
+            _meta: UI_META,
+        }, async (_args, extra) => {
+            await source.load();
+            const catalog = source.current();
+            const priced = await readPriced(sessionOf(extra));
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `The product picker is now showing the catalog visually to the user (${catalog.length} products in a grid with images). ` +
+                            `Do NOT re-list the products as text — they can see them. Briefly invite them to pick items or tell you what to add. ` +
+                            `Adjust the cart by id with add-to-cart / set-quantity / remove-from-cart; check out with checkout.`,
+                    },
+                ],
+                structuredContent: { products: catalog, cart: priced },
+                _meta: { [CATALOG_META_KEY]: { products: catalog }, [CART_META_KEY]: priced },
+            };
+        });
+        registerAppTool(server, "add-to-cart", { title: "Add to Cart", description: "Add products to the cart by id (quantities add on top).", inputSchema: { items: z.array(z.object({ productId: z.string(), quantity: z.number().int().min(1) })) }, annotations: { readOnlyHint: false }, _meta: UI_META }, async ({ items }, extra) => cartResult(await addToCart(sessionOf(extra), items)));
+        registerAppTool(server, "set-quantity", { title: "Set Quantity", description: "Set the exact quantity of a product by id (0 removes).", inputSchema: { productId: z.string(), quantity: z.number().int().min(0) }, annotations: { readOnlyHint: false }, _meta: UI_META }, async ({ productId, quantity }, extra) => cartResult(await setQuantity(sessionOf(extra), productId, quantity)));
+        registerAppTool(server, "remove-from-cart", { title: "Remove from Cart", description: "Remove a product from the cart by id.", inputSchema: { productId: z.string() }, annotations: { readOnlyHint: false }, _meta: UI_META }, async ({ productId }, extra) => cartResult(await removeFromCart(sessionOf(extra), productId)));
+        registerAppTool(server, "get-cart", { title: "Get Cart", description: "Return the current cart: line items, quantities, total.", inputSchema: {}, annotations: { readOnlyHint: true }, _meta: UI_META }, async (_args, extra) => cartResult(await readPriced(sessionOf(extra))));
+        registerAppTool(server, "checkout", { title: "Checkout", description: "Snapshot the cart into an order and return a checkout link; if gated, also a `requires` manifest of what the buyer must prove on the page.", inputSchema: { items: z.array(z.object({ productId: z.string(), quantity: z.number().int().positive() })).optional() }, annotations: { readOnlyHint: false }, _meta: UI_META }, async ({ items }, extra) => {
+            await source.load();
+            const catalog = source.current();
+            const sessionId = sessionOf(extra);
+            const entries = items?.length ? items : [...(await cartStore.read(sessionId)).entries()].map(([productId, quantity]) => ({ productId, quantity }));
+            if (entries.length === 0)
+                return { content: [{ type: "text", text: "The cart is empty — add items before checking out." }], isError: true };
+            // Random id (not a per-instance counter): two serverless instances must
+            // not both mint "ORD-1" for different carts.
+            const order = createOrder(entries, `ORD-${Math.random().toString(36).slice(2, 8)}`, catalog);
+            // statelessOrders: carry the order in a signed Cart Mandate on the link instead of
+            // a store write — the checkout page + gate rails reconstruct + verify it (FR-007).
+            const cart = statelessOrders ? cartParamFor(order) : null;
+            if (!statelessOrders)
+                await createdOrderStore.write(order.id, order);
+            orderSessions.set(order.id, sessionId); // so completion clears THIS session's cart
+            const checkoutUrl = withCart(`${baseUrl}/checkout?order=${order.id}`, cart);
+            // ← where CredentAgent mounts on. Re-home any /credentagent/* approve link onto this
+            // server's origin (and propagate the cart param), so the gate links share the base.
+            const rawRequires = resolveGate?.(order);
+            const requires = rawRequires ? homeRequires(rawRequires, baseUrl, cart) : undefined;
+            const priced = priceFrom(new Map(entries.map((e) => [e.productId, e.quantity])));
+            // Cart-bearing structuredContent (FR-014): a fresh ChatGPT widget instance
+            // hydrates the real cart instead of an empty one.
+            const payload = { orderId: order.id, checkoutUrl, ...(requires?.length ? { requires } : {}), products: catalog, cart: priced };
+            return { structuredContent: payload, content: [{ type: "text", text: JSON.stringify({ orderId: order.id, checkoutUrl, requires: requires ?? [] }) }], _meta: { [CART_META_KEY]: priced } };
+        });
+        // ── plain tools (3) — registerTool, no widget ───────────────────────────
+        server.registerTool("get-product-details", { title: "Get Product Details", description: "Return full details for a single product by id.", inputSchema: { productId: z.string() }, annotations: { readOnlyHint: true } }, async ({ productId }) => {
+            await source.load();
+            const product = getProduct(source.current(), productId);
+            return product
+                ? { content: [{ type: "text", text: JSON.stringify(product) }], structuredContent: { product } }
+                : { content: [{ type: "text", text: `No product found with id "${productId}".` }], isError: true };
+        });
+        server.registerTool("get-product-reviews", { title: "Get Product Reviews", description: "Return customer reviews for a single product by id.", inputSchema: { productId: z.string() }, annotations: { readOnlyHint: true } }, async ({ productId }) => {
+            const r = getReviews(reviews, productId);
+            return { content: [{ type: "text", text: JSON.stringify(r) }], structuredContent: { reviews: r } };
+        });
+        server.registerTool("get-order-status", { title: "Get Order Status", description: "Read-only status of a completed purchase (the buyer completes checkout on the page; this only reports).", inputSchema: { orderId: z.string() }, annotations: { readOnlyHint: true } }, async ({ orderId }) => {
+            const order = await orderStore.read(orderId);
+            if (!order)
+                return { content: [{ type: "text", text: `Order ${orderId}: pending — the buyer hasn't finished on the checkout page yet.` }], structuredContent: { orderId, status: "pending" } };
+            return { content: [{ type: "text", text: JSON.stringify(order) }], structuredContent: { orderId, status: "completed", order } };
+        });
+        // ── widget resource — two registrations from one bundle ─────────────────
+        // Claude / MCP-Apps hosts read RESOURCE_URI; ChatGPT reads the skybridge URI.
+        // `data:` in the CSP so the widget's inline SVG image placeholder renders (FR-014).
+        registerAppResource(server, RESOURCE_URI, RESOURCE_URI, { mimeType: RESOURCE_MIME_TYPE }, async () => ({
+            contents: [{ uri: RESOURCE_URI, mimeType: RESOURCE_MIME_TYPE, text: await loadBundle(), _meta: { ui: { csp: { resourceDomains: [...IMAGE_DOMAINS, "data:"], connectDomains: baseUrl ? [baseUrl] : [] } } } }],
+        }));
+        server.registerResource("product-picker-skybridge", SKYBRIDGE_URI, { mimeType: SKYBRIDGE_MIME }, async () => ({
+            contents: [{ uri: SKYBRIDGE_URI, mimeType: SKYBRIDGE_MIME, text: await loadBundle(), _meta: { "openai/widgetCSP": { connect_domains: baseUrl ? [baseUrl] : [], resource_domains: [...IMAGE_DOMAINS, "data:"] } } }],
+        }));
+        return server;
+    }
+    // MCP over streamable HTTP, STATEFUL: the server issues an mcp-session-id on
+    // `initialize` and reuses that session's transport for its later requests, so each
+    // client gets a stable session id (→ its own cart, keyed by session in the tool
+    // handlers). NOTE: the transport map is per-instance memory — multi-instance serverless
+    // needs sticky sessions (session affinity) for per-session carts to hold.
+    const transports = new Map();
+    app.all("/mcp", async (req, res) => {
+        // Self-derive the public origin from the first request so checkout URLs are
+        // absolute behind any proxy (Vercel, a tunnel) with zero config — without it,
+        // `${baseUrl}/checkout` would be relative and the widget's `new URL()` throws.
+        if (!baseUrl)
+            baseUrl = originFromRequest(req);
+        const sid = req.headers["mcp-session-id"];
+        let transport = sid ? transports.get(sid) : undefined;
+        if (!transport) {
+            // A new session must arrive as an `initialize` with no session id; anything else
+            // (unknown id, or a non-init without a session) is rejected.
+            if (sid || !isInitializeRequest(req.body)) {
+                res.status(400).json({ jsonrpc: "2.0", error: { code: -32000, message: "No valid session" }, id: null });
+                return;
+            }
+            const created = new StreamableHTTPServerTransport({
+                sessionIdGenerator: () => randomUUID(),
+                onsessioninitialized: (id) => { transports.set(id, created); },
+            });
+            created.onclose = () => { if (created.sessionId)
+                transports.delete(created.sessionId); };
+            await buildServer().connect(created);
+            transport = created;
+        }
+        try {
+            await transport.handleRequest(req, res, req.body);
+        }
+        catch {
+            if (!res.headersSent)
+                res.status(500).json({ jsonrpc: "2.0", error: { code: -32603, message: "error" }, id: null });
+        }
+    });
+    // The checkout page: the ONE shared three-gate page (renderRequirements), so the
+    // storefront and the committed demo render the same polished checkout (T030). This
+    // page LINKS to the ceremony routes credentagent.mount() registered (re-homed onto this
+    // origin, in policy order, payment last); it does NOT run the ceremony — completion
+    // happens on the mounted /credentagent/* rails, which enforce the gates fail-closed.
+    app.get("/checkout", async (req, res) => {
+        // statelessOrders: reconstruct + VERIFY the order from the `cart` mandate (no store
+        // read); else read the createdOrderStore. `cart` is propagated onto the gate links below.
+        const cartRaw = typeof req.query.cart === "string" ? req.query.cart : undefined;
+        const created = await resolveCreated(String(req.query.order ?? ""), cartRaw);
+        if (!created)
+            return res.status(404).type("html").send("<h1>Unknown order</h1>");
+        // Read THIS order's verification (per order id — never global; Security
+        // invariant 4) so the page reflects what the buyer has proven so far, and
+        // re-price from the catalog with it (the discount opts in only once membership
+        // is presented — never trust the token's total; invariant 2/3).
+        const v = ((await verificationStore.read(created.id)) ?? {});
+        const ageVerified = v.ageVerified === true;
+        const loyaltyApplied = v.loyalty?.applied === true;
+        const order = ceremonyCatalog.createOrder(created.lines.map((l) => ({ productId: l.id, quantity: l.quantity })), created.id, { ageVerified, loyaltyApplied });
+        // A revisit of an already-completed order shows the paid state instead of the
+        // payment methods.
+        const done = (await orderStore.read(created.id)) ?? null;
+        // Resolve + re-home the manifest onto this server's mounted routes (each gate
+        // carries its OWN approveUrl — the renderer is route-agnostic). Resolve against
+        // the created order (the policy reads line ids + minimumAge — the re-priced
+        // `order` carries the same lines; the discounted total shows via `order` below).
+        const requires = homeRequires(resolveGate?.(created) ?? [], baseUrl, statelessOrders ? cartRaw : null);
+        const verification = { ageVerified, loyaltyApplied };
+        const paid = done ? { amount: done.amount, currency: done.currency, method: done.method } : null;
+        // An UNGATED storefront has no payment gate, so the manifest carries no
+        // `authorize` entry the renderer could derive a Pay CTA from — keep a simple
+        // instant-demo complete path (POST the order id to /checkout/place-order). A
+        // GATED order has NO such bypass: completion goes through the fail-closed payment
+        // gate (the manifest's `authorize` approveUrl → the renderer's single Pay CTA).
+        const ungated = requires.length === 0;
+        const orderQ = encodeURIComponent(order.id);
+        const payment = ungated
+            ? {
+                methods: [
+                    { value: "demo", name: `Complete purchase (demo) — ${order.total} ${order.currency}`, desc: "No real charge — records the order and clears the cart.", placeOrder: true },
+                ],
+                placeOrderPath: "/checkout/place-order",
+                orderToken: order.id,
+            }
+            : // A GATED order: offer the same payment methods the demo does — the headline
+                // passkey rail (authorize on-device; settles on-chain via x402 on Hedera) and
+                // the cross-device wallet rail — both mounted by credentagent.mount(), both completing
+                // through the fail-closed gate (no bypass). Without this the renderer falls back
+                // to a single Pay CTA from the manifest and the x402/Hedera passkey option never shows.
+                {
+                    methods: [
+                        { value: "passkey", name: "Pay with x402 Hedera · Passkey", desc: "Authorize with this device's passkey — payment settles on-chain via the x402 protocol (test network).", href: withCart(`/credentagent/passkey?order=${orderQ}`, statelessOrders ? cartRaw : null), checked: true },
+                        { value: "dc-payment", name: "Cross-device wallet", desc: "Scan a QR and approve with your phone's passkey or wallet — also x402 on Hedera.", href: withCart(`/credentagent/dc-payment?order=${orderQ}`, statelessOrders ? cartRaw : null) },
+                    ],
+                };
+        res.type("html").send(renderRequirements(order, requires, verification, { ...(payment ? { payment } : {}), paid }));
+    });
+    app.post("/checkout/place-order", async (req, res) => {
+        // statelessOrders: reconstruct + verify from the body's `cart` mandate; else the store.
+        const order = await resolveCreated(String(req.body?.order ?? ""), req.body?.cart);
+        if (order) {
+            // Security invariant 1 — enforce gates on EVERY completion path, not just the
+            // rendered page. This instant-demo path completes WITHOUT a device ceremony, so
+            // it is only ever valid for an UNGATED order. A gated order (age / payment
+            // requirements) MUST complete through the fail-closed payment gate; refuse it
+            // here server-side. The checkout page only offers this button for ungated
+            // orders, but a DIRECT POST of a gated order id would otherwise bypass the gate
+            // entirely — e.g. an age-restricted order completing with no age proof. Hiding
+            // the button is not enforcement.
+            if ((resolveGate?.(order) ?? []).length > 0) {
+                res.status(403).type("html").send(`<!doctype html><meta charset="utf-8"><body style="font-family:system-ui;max-width:32rem;margin:3rem auto"><h1>Verification required</h1><p>This order has age / payment requirements — complete it through checkout. It can't be placed from the instant-demo path.</p></body>`);
+                return;
+            }
+            await orderStore.write(order.id, { orderId: order.id, amount: order.total, currency: order.currency, method: "demo", completedAt: new Date().toISOString() });
+            const sid = orderSessions.get(order.id); // completion empties THIS session's cart
+            if (sid)
+                await cartStore.write(sid, new Map());
+        }
+        res.type("html").send(`<!doctype html><meta charset="utf-8"><body style="font-family:system-ui;max-width:32rem;margin:3rem auto"><h1>✓ Order placed (demo)</h1><p>You can close this tab — the storefront will update.</p></body>`);
+    });
+    // The widget polls this after checkout to learn when the buyer finished on the page
+    // (MCP has no server→client push). It then shows the confirmation + clears its cart.
+    app.get("/checkout/order-status", async (req, res) => {
+        // The widget iframe polls this cross-origin; allow it (simple GET → no preflight).
+        res.setHeader("Access-Control-Allow-Origin", "*");
+        const orderId = typeof req.query.orderId === "string" ? req.query.orderId : "";
+        const order = orderId ? await orderStore.read(orderId) : null;
+        res.json({ completed: !!order, order });
+    });
+    return {
+        app,
+        // Static source: the injected array. Dynamic source: the last-known-good snapshot
+        // (throws if read before the first successful load — the server primes it per request).
+        get catalog() { return source.current(); },
+        mcpServer: buildServer,
+        gate(resolve) { resolveGate = resolve; },
+        async listen(port = 3005) {
+            if (!baseUrl)
+                baseUrl = `http://localhost:${port}`;
+            await new Promise((resolve) => { app.listen(port, () => resolve()); });
+            return { url: `${baseUrl}/mcp`, port };
+        },
+    };
+}

package/dist/state.d.ts

@@ -0,0 +1,25 @@
+/** The working cart, keyed per session (productId → quantity). Each MCP session gets its
+ *  own cart, so concurrent buyers never share one (Security invariant 4). */
+export interface CartStore {
+    read(sessionId: string): Promise<Map<string, number>>;
+    write(sessionId: string, cart: Map<string, number>): Promise<void>;
+}
+export declare class MemoryCartStore implements CartStore {
+    private carts;
+    read(sessionId: string): Promise<Map<string, number>>;
+    write(sessionId: string, cart: Map<string, number>): Promise<void>;
+}
+/** Completed-order records, keyed by order id (what `get-order-status` reads). The
+ *  payload is opaque to the storefront — the demo's ceremony writes its rich
+ *  completed-order shape (with settlement); a standalone storefront leaves it empty. */
+export interface OrderStore<T = unknown> {
+    read(orderId: string): Promise<T | null>;
+    write(orderId: string, order: T): Promise<void>;
+    clear(orderId: string): Promise<void>;
+}
+export declare class MemoryOrderStore<T = unknown> implements OrderStore<T> {
+    private orders;
+    read(orderId: string): Promise<T | null>;
+    write(orderId: string, order: T): Promise<void>;
+    clear(orderId: string): Promise<void>;
+}

package/dist/state.js

@@ -0,0 +1,25 @@
+// Storefront state — cart + completed orders. In-memory by default (zero deps);
+// inject a custom store for a persistent / multi-session backend (e.g. Redis on a
+// serverless deployment). Keys are per session / per order — never process-global
+// beyond this in-process default (Security invariant 4).
+export class MemoryCartStore {
+    carts = new Map();
+    async read(sessionId) {
+        return new Map(this.carts.get(sessionId) ?? []);
+    }
+    async write(sessionId, cart) {
+        this.carts.set(sessionId, new Map(cart));
+    }
+}
+export class MemoryOrderStore {
+    orders = new Map();
+    async read(orderId) {
+        return this.orders.get(orderId) ?? null;
+    }
+    async write(orderId, order) {
+        this.orders.set(orderId, order);
+    }
+    async clear(orderId) {
+        this.orders.delete(orderId);
+    }
+}

package/dist/tool-meta.d.ts

@@ -0,0 +1,27 @@
+export interface AppToolMeta {
+    [key: string]: unknown;
+    /** MCP-Apps (Claude) — the widget resource to render. */
+    ui: {
+        resourceUri: string;
+    };
+    /** ChatGPT — the skybridge template (the registered `text/html+skybridge` resource). */
+    "openai/outputTemplate": string;
+    /** ChatGPT — authorizes `window.openai.callTool` from inside the widget. */
+    "openai/widgetAccessible": true;
+    /** ChatGPT — the invoking/invoked status strings shown while a tool runs. */
+    "openai/toolInvocation": {
+        invoking: string;
+        invoked: string;
+    };
+}
+export interface AppToolMetaUris {
+    /** The MCP-Apps `ui://` resource (Claude). */
+    resourceUri: string;
+    /** The ChatGPT skybridge `ui://` resource; defaults to `resourceUri` if a single resource serves both. */
+    skybridgeUri?: string;
+}
+/** Build the canonical UI-linked tool `_meta` (both host surfaces, `widgetAccessible` always on). */
+export declare function appToolMeta(uris: AppToolMetaUris, status?: {
+    invoking?: string;
+    invoked?: string;
+}): AppToolMeta;

package/dist/tool-meta.js

@@ -0,0 +1,24 @@
+// The canonical `_meta` for a UI-linked storefront tool — emitting BOTH host
+// surfaces from ONE place so neither can be forgotten.
+//
+//   • MCP-Apps hosts (Claude native app / claude.ai) read `ui.resourceUri`.
+//   • ChatGPT (skybridge) reads the `openai/*` keys.
+//
+// `openai/widgetAccessible: true` is what authorizes `window.openai.callTool`.
+// The reference demo set `openai/outputTemplate` but NOT `widgetAccessible`
+// (an inline `_meta` that forgot a key), which is exactly why its widget rendered
+// in ChatGPT but was interactively dead — the steppers and Checkout button
+// silently no-op'd. Routing every UI-linked tool through this builder makes that
+// omission impossible (FR-014).
+/** Build the canonical UI-linked tool `_meta` (both host surfaces, `widgetAccessible` always on). */
+export function appToolMeta(uris, status) {
+    return {
+        ui: { resourceUri: uris.resourceUri },
+        "openai/outputTemplate": uris.skybridgeUri ?? uris.resourceUri,
+        "openai/widgetAccessible": true,
+        "openai/toolInvocation": {
+            invoking: status?.invoking ?? "Working…",
+            invoked: status?.invoked ?? "Done",
+        },
+    };
+}