@openmobilehub/attestomcp-storefront 0.1.0

package/dist/server.js

@@ -0,0 +1,386 @@
+// 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/attestomcp-gate mounts on:
+//
+//   const store = createStorefront();
+//   const attestomcp = new AttestoMcp();
+//   attestomcp.mount(store.app);
+//   store.gate((order) => attestomcp.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 } 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 { registerAppTool, registerAppResource, RESOURCE_MIME_TYPE } from "@modelcontextprotocol/ext-apps/server";
+import express from "express";
+import { z } from "zod";
+import { CART_META_KEY, CATALOG_META_KEY, createOrder, getProduct, getReviews, priceCart, SAMPLE_CATALOG, } from "./index.js";
+import { appToolMeta } from "./tool-meta.js";
+import { MemoryCartStore, MemoryOrderStore } from "./state.js";
+// Composition with @openmobilehub/attestomcp-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.attestomcp`, so `new AttestoMcp().mount(store.app)` wires
+// the `/attestomcp/*` 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, renderRequirements, MemoryVerificationStore, } from "@openmobilehub/attestomcp-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(`attestomcp-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 (`/attestomcp/*`) 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("/attestomcp/"))
+            return `${base}${u.pathname}${u.search}`;
+    }
+    catch {
+        /* not URL-shaped — leave as-is */
+    }
+    return approveUrl;
+}
+// Re-home every `/attestomcp/*` approveUrl in a `requires` manifest onto `base`.
+function homeRequires(requires, base) {
+    return requires.map((e) => {
+        const entry = e;
+        return typeof entry.approveUrl === "string"
+            ? { ...entry, approveUrl: homeApproveUrl(entry.approveUrl, base) }
+            : e;
+    });
+}
+export function createStorefront(opts = {}) {
+    const catalog = opts.catalog ?? SAMPLE_CATALOG;
+    const reviews = opts.reviews;
+    const cartStore = opts.cartStore ?? new MemoryCartStore();
+    const orderStore = opts.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 ?? 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 ?? new MemoryVerificationStore();
+    let resolveGate;
+    let baseUrl = opts.baseUrl?.replace(/\/+$/, "") ?? "";
+    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 }));
+    // ── AttestoMcp ceremony seams (Context 2) ──────────────────────────────────────
+    // Pre-bound so `new AttestoMcp().mount(store.app)` wires the `/attestomcp/*` rails with
+    // ZERO explicit args — it reads these off `app.locals.attestomcp` (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, catalog, { 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 () => { await cartStore.write(new Map()); } },
+        ...(opts.settle ? { settle: opts.settle } : {}),
+    });
+    app.locals.attestomcp = {
+        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.
+        ...(opts.signingKey ? { signingKey: opts.signingKey } : {}),
+        allowEphemeralKey: opts.allowEphemeralKey ?? !opts.signingKey,
+    };
+    // ── cart logic (closure over the injected catalog + the cart store) ───────
+    const priceFrom = (cart) => priceCart([...cart.entries()].map(([productId, quantity]) => ({ productId, quantity })), catalog);
+    const readPriced = async () => priceFrom(await cartStore.read());
+    const addToCart = async (items) => {
+        const cart = await cartStore.read();
+        for (const { productId, quantity } of items) {
+            if (quantity <= 0)
+                continue;
+            cart.set(productId, (cart.get(productId) ?? 0) + quantity);
+        }
+        await cartStore.write(cart);
+        return priceFrom(cart);
+    };
+    const setQuantity = async (productId, quantity) => {
+        const cart = await cartStore.read();
+        if (quantity <= 0)
+            cart.delete(productId);
+        else
+            cart.set(productId, quantity);
+        await cartStore.write(cart);
+        return priceFrom(cart);
+    };
+    const removeFromCart = async (productId) => {
+        const cart = await cartStore.read();
+        cart.delete(productId);
+        await cartStore.write(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: catalog, cart: priced },
+        content: [{ type: "text", text: JSON.stringify(priced) }],
+        _meta: { [CART_META_KEY]: priced },
+    });
+    function buildServer() {
+        const server = new McpServer({ name: "attestomcp-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 () => {
+            const priced = await readPriced();
+            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 }) => cartResult(await addToCart(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 }) => cartResult(await setQuantity(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 }) => cartResult(await removeFromCart(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 () => cartResult(await readPriced()));
+        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 }) => {
+            const entries = items?.length ? items : [...(await cartStore.read()).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);
+            await createdOrderStore.write(order.id, order);
+            const checkoutUrl = `${baseUrl}/checkout?order=${order.id}`;
+            // ← where AttestoMcp mounts on. Re-home any /attestomcp/* approve link onto this
+            // server's origin, so the gate links share the checkout link's base.
+            const rawRequires = resolveGate?.(order);
+            const requires = rawRequires ? homeRequires(rawRequires, baseUrl) : 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 }) => {
+            const product = getProduct(catalog, 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 (stateless per request), mirroring the reference server.
+    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 server = buildServer();
+        const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+        res.on("close", () => { transport.close().catch(() => { }); server.close().catch(() => { }); });
+        try {
+            await server.connect(transport);
+            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 attestomcp.mount() registered (re-homed onto this
+    // origin, in policy order, payment last); it does NOT run the ceremony — completion
+    // happens on the mounted /attestomcp/* rails, which enforce the gates fail-closed.
+    app.get("/checkout", async (req, res) => {
+        const created = await createdOrderStore.read(String(req.query.order ?? ""));
+        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);
+        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 attestomcp.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: `/attestomcp/passkey?order=${orderQ}`, 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: `/attestomcp/dc-payment?order=${orderQ}` },
+                    ],
+                };
+        res.type("html").send(renderRequirements(order, requires, verification, { ...(payment ? { payment } : {}), paid }));
+    });
+    app.post("/checkout/place-order", async (req, res) => {
+        const order = await createdOrderStore.read(String(req.body?.order ?? ""));
+        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() });
+            await cartStore.write(new Map()); // completion empties the cart
+        }
+        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,
+        catalog,
+        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,24 @@
+/** The working cart: productId → quantity. */
+export interface CartStore {
+    read(): Promise<Map<string, number>>;
+    write(cart: Map<string, number>): Promise<void>;
+}
+export declare class MemoryCartStore implements CartStore {
+    private cart;
+    read(): Promise<Map<string, number>>;
+    write(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 {
+    cart = new Map();
+    async read() {
+        return new Map(this.cart);
+    }
+    async write(cart) {
+        this.cart = 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",
+        },
+    };
+}