@openmobilehub/attestomcp-storefront 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Open Mobile Hub, a series of LF Projects, LLC
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,119 @@
+# @openmobilehub/attestomcp-storefront
+
+**The agentic storefront core.** A runnable MCP shopping server — the cart → priced-cart →
+order model + the nine shopping tools + the widget bundle — **catalog-injected** (bring your
+own products, own-the-code). Pairs with
+[`@openmobilehub/attestomcp-gate`](../attestomcp-gate) so you can **gate any consequential MCP tool
+with any credential**: age, membership, a prescription, payment. **Payments is one application
+of the same gate, not the point** — `minimumAge` on a product is all it takes to lock checkout.
+
+> **Design preview / v0.1.** The pure pricing/order model (`@openmobilehub/attestomcp-storefront`)
+> and the runnable MCP server (`@openmobilehub/attestomcp-storefront/server`) are real and tested.
+> Some of the demo's widget polish is still being extracted from the reference server
+> ([mcp-apps-shopping-demo](https://github.com/openmobilehub/mcp-apps-shopping-demo)).
+> See the repo's `ROADMAP.md`.
+
+## Install
+
+```bash
+npm install @openmobilehub/attestomcp-storefront @openmobilehub/attestomcp-gate
+```
+
+Apache-2.0, ESM. Two entry points: `.` (the pure pricing model, dependency-light) and
+`./server` (the runnable MCP server, brings in `@modelcontextprotocol/sdk` + `express`).
+
+## Quickstart — a credential-gated storefront in ≤ 10 lines
+
+`createStorefront()` stands up the real MCP server (nine tools, a widget resource, a checkout
+page) over HTTP at `/mcp`. It publishes the ceremony seams on `store.app.locals.attestomcp`, so
+`new AttestoMcp().mount(store.app)` wires the real `/attestomcp/*` ceremony rails with zero glue, and
+`store.gate()` resolves your policy on every `checkout` call (copied from
+[`examples/storefront.mjs`](https://github.com/openmobilehub/mcp-apps-shopping-demo/blob/main/examples/storefront.mjs) /
+[`storefront-gate.test.ts`](https://github.com/openmobilehub/mcp-apps-shopping-demo/blob/main/storefront-gate.test.ts)):
+
+```ts
+import { createStorefront } from "@openmobilehub/attestomcp-storefront/server";
+import { AttestoMcp, age, membership, payment, required, optional } from "@openmobilehub/attestomcp-gate";
+
+const store = createStorefront();                  // the whole storefront — one line
+const attestomcp = new AttestoMcp();
+attestomcp.mount(store.app);                          // wires the real /attestomcp/* ceremony rails
+
+store.gate((order) =>                              // resolved on every checkout (payment settles LAST)
+  attestomcp.requirements(order, [
+    required(age.over(21).when((order) => order.lines.some((l) => l.minimumAge != null))),
+    optional(membership.discount(10)),              // 10% off if a loyalty credential is presented
+    required(payment.in("usd")),                    // amount derived from the order; settles last
+  ]),
+);
+
+const { url } = await store.listen(3005);          // → add http://localhost:3005/mcp to Claude / ChatGPT / Goose
+```
+
+Browse → add the whiskey (21+) → checkout. The `checkout` tool returns the link **plus** a
+`requires` manifest; the buyer proves age + (optionally) membership, then authorizes payment on
+the `mount()`-served page; the widget polls and shows the discounted confirmation. Add the
+headphones instead and the age gate drops — the `.when()` predicate receives the **order** and is
+false. Without `store.gate(...)` the storefront is ungated: a plain checkout link, no `requires`.
+
+> The product's `minimumAge` is the single field that ties the two packages together: `priceCart`
+> re-derives it onto each priced line, so a storefront `Order` feeds `attestomcp.requirements()`
+> directly — no mapping. The gate's amount is **re-derived server-side from this catalog**, never
+> trusted from the order token (Security invariant 2).
+
+## The three execution contexts
+
+`createStorefront()` is built around the split the gate enforces — conflating these is forbidden
+([spec §0](https://github.com/openmobilehub/mcp-apps-shopping-demo/blob/main/specs/001-attesto-sdk/spec.md)):
+
+1. **Tool — mints the link + reports requirements.** The `checkout` tool snapshots the cart into an
+   order, returns `{ orderId, checkoutUrl, requires }`, and runs **no ceremony** (no phone in the loop).
+2. **Page — runs the gates.** `GET /checkout?order=<id>` links to the `/attestomcp/*` ceremony routes
+   `attestomcp.mount(store.app)` serves; the buyer completes every gate there in one session.
+3. **Poll — reports completion.** The widget polls `GET /checkout/order-status?orderId=<id>`; once the
+   ceremony's shared `completeOrder` records the order (re-priced, age re-enforced, cart cleared), it
+   reflects the completed — discounted — total.
+
+## Pure pricing model (no server)
+
+The `.` entry point is the pure, catalog-injected pricing core — useful standalone or to fork:
+
+```ts
+import { priceCart, createOrder, requiredAgeForLines, SAMPLE_CATALOG } from "@openmobilehub/attestomcp-storefront";
+
+const cart = priceCart([{ productId: "oak-whiskey", quantity: 1 }], SAMPLE_CATALOG);
+cart.hasAgeRestricted;                            // true → wire @openmobilehub/attestomcp-gate on checkout
+requiredAgeForLines(cart.lines, SAMPLE_CATALOG);  // 21
+
+const order = createOrder([{ productId: "oak-whiskey", quantity: 1 }], "ORD-1", SAMPLE_CATALOG);
+order.total;                                      // 124
+```
+
+Pure functions — no globals — so the same code serves any storefront. Pass your own `Product[]` as
+the catalog; unknown ids are collected (`unknownIds`), not thrown.
+
+## What's real in v0.1
+
+- `createStorefront(opts)` → `{ app, catalog, gate, listen, mcpServer }` — the runnable MCP server
+  (nine tools, widget resource, checkout page) over HTTP, catalog-injected, gate-ready.
+- `priceCart()` / `createOrder()` / `requiredAgeForLines()` / `getProduct()` / `getReviews()` — pure,
+  catalog-injected pricing & lookups.
+- The `Product` / `Order` / `PricedCart` / `PricedCartLine` model + a runnable `SAMPLE_CATALOG`
+  (includes one 21+ item) so the package demos itself.
+- Loyalty discount with a per-call percent override (`LOYALTY_DISCOUNT_PCT`, `PriceOpts`).
+- Pluggable stores (cart / created-order / completed-order / verification) — default in-memory;
+  inject a shared store (e.g. Redis) for a multi-instance serverless deployment.
+
+`createStorefront()` accepts `{ catalog, reviews, baseUrl, cartStore, orderStore, createdOrderStore,
+verificationStore, signingKey, allowEphemeralKey, settle }`. The optional `settle` seam (e.g.
+on-chain) **gates** completion: a configured-but-failed settle records nothing and leaves the cart
+intact.
+
+## Honest status
+
+The composed gate is **presence-only** in v0.1 (`trust_level: "presence-only-demo"`): the passkey rail
+is real WebAuthn cryptography, but the age/membership and Digital-Credentials payment rails enforce
+disclosure + binding, **not** mdoc issuer/device-signature trust — a flow demo, not a real safety
+control. See [`@openmobilehub/attestomcp-gate`](../attestomcp-gate#honest-status) for the full breakdown.
+
+Apache-2.0 · part of [Open Mobile Hub](https://openmobilehub.org) (Linux Foundation).

package/dist/generated-images.d.ts

@@ -0,0 +1,2 @@
+/** Product id → a generated, self-contained image (data URI). */
+export declare const PRODUCT_IMAGES: Record<string, string>;

package/dist/generated-images.js

@@ -0,0 +1,23 @@
+// Self-contained product images — generated here, no external image service.
+// Each is a clean SVG tile: a category-tinted gradient + the product's emoji
+// (instantly recognizable, renders crisply at any size), embedded as a data URI.
+// The widget shows the product name beneath, so the tile is just the visual.
+function tile(emoji, bg) {
+    const svg = `<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 400 300'>` +
+        `<defs><linearGradient id='g' x1='0' y1='0' x2='1' y2='1'>` +
+        `<stop offset='0' stop-color='${bg[0]}'/><stop offset='1' stop-color='${bg[1]}'/>` +
+        `</linearGradient></defs>` +
+        `<rect width='400' height='300' fill='url(#g)'/>` +
+        `<text x='200' y='150' font-size='150' text-anchor='middle' dominant-baseline='central'>${emoji}</text>` +
+        `</svg>`;
+    return "data:image/svg+xml," + encodeURIComponent(svg);
+}
+/** Product id → a generated, self-contained image (data URI). */
+export const PRODUCT_IMAGES = {
+    "aurora-headphones": tile("🎧", ["#7c3aed", "#a78bfa"]),
+    "oak-whiskey": tile("🥃", ["#b45309", "#f59e0b"]),
+    "drift-mouse": tile("🖱️", ["#0f766e", "#2dd4bf"]),
+    "celebration-champagne": tile("🍾", ["#be185d", "#f9a8d4"]),
+    "summit-backpack": tile("🎒", ["#1d4ed8", "#60a5fa"]),
+    "lumen-desk-lamp": tile("💡", ["#a16207", "#fde047"]),
+};

package/dist/index.d.ts

@@ -0,0 +1,87 @@
+/** Default loyalty discount, in percent. Override per-call via PriceOpts. */
+export declare const LOYALTY_DISCOUNT_PCT = 10;
+/** `_meta` keys the storefront tools use to embed the catalog / cart for the widget to read. */
+export declare const CATALOG_META_KEY = "product-picker/catalog";
+export declare const CART_META_KEY = "product-picker/cart";
+/** A product review, surfaced by `get-product-reviews`. */
+export interface Review {
+    author: string;
+    rating: number;
+    text: string;
+}
+export interface Product {
+    id: string;
+    name: string;
+    price: number;
+    currency: string;
+    image: string;
+    category: string;
+    description: string;
+    /** Minimum age to purchase (e.g. 21). Absent = no age restriction. */
+    minimumAge?: number;
+}
+export interface CartItemInput {
+    productId: string;
+    quantity: number;
+}
+export interface PricedCartLine {
+    id: string;
+    name: string;
+    unitPrice: number;
+    currency: string;
+    quantity: number;
+    lineTotal: number;
+    /**
+     * Per-product age threshold (e.g. 21), re-derived from the catalog onto the
+     * line. Lets a priced `Order` feed `@openmobilehub/attestomcp-gate`'s
+     * `requirements()` directly — no `toGateOrder` mapping needed.
+     */
+    minimumAge?: number;
+    /** Product category, carried through for custom `.when()` / `appliesTo` predicates. */
+    category?: string;
+}
+export interface PricedCart {
+    lines: PricedCartLine[];
+    itemCount: number;
+    subtotal: number;
+    discount: number;
+    total: number;
+    currency: string;
+    unknownIds: string[];
+    hasAgeRestricted: boolean;
+    ageVerified: boolean;
+    loyaltyApplied: boolean;
+}
+export interface Order {
+    id: string;
+    lines: PricedCartLine[];
+    itemCount: number;
+    subtotal: number;
+    discount: number;
+    total: number;
+    currency: string;
+    createdAt: string;
+}
+export interface PriceOpts {
+    ageVerified?: boolean;
+    loyaltyApplied?: boolean;
+    /** Loyalty discount percent (defaults to LOYALTY_DISCOUNT_PCT). */
+    loyaltyDiscountPct?: number;
+}
+/**
+ * Price a cart against an injected catalog. Unknown ids are collected, not
+ * thrown. Pure — no globals, so the same function serves any storefront.
+ */
+export declare function priceCart(items: CartItemInput[], catalog: Product[], opts?: PriceOpts): PricedCart;
+/** The strictest minimum age across the cart's products, or null if none. */
+export declare function requiredAgeForLines(lines: {
+    id: string;
+}[], catalog: Product[]): number | null;
+/** Snapshot a priced cart into an immutable order. */
+export declare function createOrder(items: CartItemInput[], id: string, catalog: Product[], opts?: PriceOpts): Order;
+/** Look up a product by id in the injected catalog. */
+export declare function getProduct(catalog: Product[], productId: string): Product | undefined;
+/** Reviews for a product, from the injected reviews map (empty if none). */
+export declare function getReviews(reviews: Record<string, Review[]> | undefined, productId: string): Review[];
+/** A tiny runnable catalog (incl. one age-restricted item) so the package demos itself. */
+export declare const SAMPLE_CATALOG: Product[];

package/dist/index.js

@@ -0,0 +1,151 @@
+// @openmobilehub/attestomcp-storefront — the agentic storefront core (v0.1 slice).
+//
+// The cart → priced-cart → order model an MCP shopping app needs, **catalog-injected**
+// (bring your own products). Own-the-code: fork it and edit your catalog. This slice
+// is the pure pricing/order model; the MCP tools + widget bundle that render it are
+// tracked in the roadmap.
+import { PRODUCT_IMAGES } from "./generated-images.js";
+/** Default loyalty discount, in percent. Override per-call via PriceOpts. */
+export const LOYALTY_DISCOUNT_PCT = 10;
+/** `_meta` keys the storefront tools use to embed the catalog / cart for the widget to read. */
+export const CATALOG_META_KEY = "product-picker/catalog";
+export const CART_META_KEY = "product-picker/cart";
+function round2(n) {
+    return Math.round(n * 100) / 100;
+}
+/**
+ * Price a cart against an injected catalog. Unknown ids are collected, not
+ * thrown. Pure — no globals, so the same function serves any storefront.
+ */
+export function priceCart(items, catalog, opts = {}) {
+    const byId = new Map(catalog.map((p) => [p.id, p]));
+    const lines = [];
+    const unknownIds = [];
+    let hasAgeRestricted = false;
+    for (const { productId, quantity } of items) {
+        const product = byId.get(productId);
+        if (!product) {
+            unknownIds.push(productId);
+            continue;
+        }
+        if (quantity <= 0)
+            continue;
+        if (product.minimumAge != null)
+            hasAgeRestricted = true;
+        lines.push({
+            id: product.id,
+            name: product.name,
+            unitPrice: product.price,
+            currency: product.currency,
+            quantity,
+            lineTotal: round2(product.price * quantity),
+            // Re-derived onto the line so a priced Order is gate-ready (inv #2).
+            ...(product.minimumAge != null ? { minimumAge: product.minimumAge } : {}),
+            category: product.category,
+        });
+    }
+    const itemCount = lines.reduce((sum, l) => sum + l.quantity, 0);
+    const subtotal = round2(lines.reduce((sum, l) => sum + l.lineTotal, 0));
+    const loyaltyApplied = !!opts.loyaltyApplied;
+    const pct = opts.loyaltyDiscountPct ?? LOYALTY_DISCOUNT_PCT;
+    const discount = loyaltyApplied ? round2(subtotal * (pct / 100)) : 0;
+    const total = round2(subtotal - discount);
+    const currency = lines[0]?.currency ?? "USD";
+    return {
+        lines,
+        itemCount,
+        subtotal,
+        discount,
+        total,
+        currency,
+        unknownIds,
+        hasAgeRestricted,
+        ageVerified: !!opts.ageVerified,
+        loyaltyApplied,
+    };
+}
+/** The strictest minimum age across the cart's products, or null if none. */
+export function requiredAgeForLines(lines, catalog) {
+    const byId = new Map(catalog.map((p) => [p.id, p]));
+    let max = null;
+    for (const { id } of lines) {
+        const m = byId.get(id)?.minimumAge;
+        if (m != null && (max === null || m > max))
+            max = m;
+    }
+    return max;
+}
+/** Snapshot a priced cart into an immutable order. */
+export function createOrder(items, id, catalog, opts = {}) {
+    const { lines, itemCount, subtotal, discount, total, currency } = priceCart(items, catalog, opts);
+    return { id, lines, itemCount, subtotal, discount, total, currency, createdAt: new Date().toISOString() };
+}
+/** Look up a product by id in the injected catalog. */
+export function getProduct(catalog, productId) {
+    return catalog.find((p) => p.id === productId);
+}
+/** Reviews for a product, from the injected reviews map (empty if none). */
+export function getReviews(reviews, productId) {
+    return reviews?.[productId] ?? [];
+}
+/** A tiny runnable catalog (incl. one age-restricted item) so the package demos itself. */
+// Generated, self-contained product images (see generated-images.ts) — emoji tiles
+// embedded as data URIs, so the catalog needs no external image service.
+export const SAMPLE_CATALOG = [
+    {
+        id: "aurora-headphones",
+        name: "Aurora Wireless Headphones",
+        price: 199.0,
+        currency: "USD",
+        image: PRODUCT_IMAGES["aurora-headphones"],
+        category: "Audio",
+        description: "Over-ear ANC headphones with 40h battery life.",
+    },
+    {
+        id: "oak-whiskey",
+        name: "Oak Reserve Whiskey Collection",
+        price: 124.0,
+        currency: "USD",
+        image: PRODUCT_IMAGES["oak-whiskey"],
+        category: "Beverages",
+        description: "Trio of small-batch aged whiskeys. 21+ only.",
+        minimumAge: 21,
+    },
+    {
+        id: "drift-mouse",
+        name: "Drift Wireless Mouse",
+        price: 49.0,
+        currency: "USD",
+        image: PRODUCT_IMAGES["drift-mouse"],
+        category: "Electronics",
+        description: "Ergonomic silent-click wireless mouse, 6-month battery.",
+    },
+    {
+        id: "celebration-champagne",
+        name: "Celebration Champagne Duo",
+        price: 89.0,
+        currency: "USD",
+        image: PRODUCT_IMAGES["celebration-champagne"],
+        category: "Beverages",
+        description: "Brut champagne duo with two crystal flutes. 21+ only.",
+        minimumAge: 21,
+    },
+    {
+        id: "summit-backpack",
+        name: "Summit Trail Backpack",
+        price: 129.0,
+        currency: "USD",
+        image: PRODUCT_IMAGES["summit-backpack"],
+        category: "Outdoors",
+        description: "35L weatherproof hiking backpack with a stowaway rain cover.",
+    },
+    {
+        id: "lumen-desk-lamp",
+        name: "Lumen LED Desk Lamp",
+        price: 59.0,
+        currency: "USD",
+        image: PRODUCT_IMAGES["lumen-desk-lamp"],
+        category: "Home",
+        description: "Dimmable LED desk lamp with a USB-C charging base.",
+    },
+];

package/dist/server.d.ts

@@ -0,0 +1,86 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { Express, Request } from "express";
+import type { Order, Product, Review } from "./index.js";
+import type { CartStore, OrderStore } from "./state.js";
+import { type CeremonyOrder, type VerificationStore } from "@openmobilehub/attestomcp-gate";
+/** Given a priced order, return the `requires` manifest (or `undefined` = ungated). */
+export type GateResolver = (order: Order) => unknown[] | undefined;
+export interface StorefrontOptions {
+    /** Products to sell. Defaults to the package's `SAMPLE_CATALOG`. */
+    catalog?: Product[];
+    /** Reviews per product id, backing `get-product-reviews`. */
+    reviews?: Record<string, Review[]>;
+    /** Origin the checkout links resolve from. Default `http://localhost:<port>`. */
+    baseUrl?: string;
+    /** Cart store; default in-memory. */
+    cartStore?: CartStore;
+    /** Completed-order store (read by `get-order-status`); default in-memory. */
+    orderStore?: OrderStore<CompletedOrderRecord>;
+    /**
+     * Created-but-not-yet-completed orders (read by the checkout page + place-order),
+     * keyed by order id. Default in-memory. Inject a shared store (e.g. Redis) on a
+     * multi-instance serverless deployment, or the checkout page lands on a cold
+     * instance that never saw the order.
+     */
+    createdOrderStore?: OrderStore<Order>;
+    /**
+     * Per-order verification state the mounted ceremony writes (age proven / loyalty
+     * applied) and this server's `completion` seam reads back to re-price + enforce
+     * the age gate. Default in-memory; inject a shared store on a serverless
+     * deployment. Published on `app.locals.attestomcp` so `attestomcp.mount(store.app)`
+     * wires the rails against the SAME state (Security invariant 4).
+     */
+    verificationStore?: VerificationStore;
+    /**
+     * Stable HMAC key for the ceremony's challenge nonce (e.g. `process.env.GATE_SECRET`).
+     * Required so an options→verify hop survives an instance split on serverless. When
+     * absent, `allowEphemeralKey` defaults true so a single-process dev server / tests
+     * just run with a per-process key.
+     */
+    signingKey?: string;
+    /** Allow a per-process ephemeral signing key (default: true unless `signingKey` is set). */
+    allowEphemeralKey?: boolean;
+    /**
+     * Optional demo-mode settlement seam (e.g. on-chain). Throwing GATES completion:
+     * a configured-but-failed settle records nothing and leaves the cart intact.
+     */
+    settle?: (order: CeremonyOrder) => Promise<Record<string, unknown> & {
+        network: string;
+        txId: string;
+        status: string;
+    }>;
+}
+/**
+ * A completed-order record the widget poll + `get-order-status` read. The standalone
+ * demo `place-order` writes the lean shape (orderId/amount/currency/method/completedAt);
+ * the mounted ceremony's shared `completeOrder` writes the richer one (mandate id,
+ * gate outcomes, instrument, settlement) — both satisfy this superset so the poll
+ * reads either.
+ */
+export interface CompletedOrderRecord {
+    orderId: string;
+    amount: number;
+    currency: string;
+    method: string;
+    completedAt: string;
+    mandateId?: string;
+    instrument?: unknown;
+    gates?: {
+        gate: string;
+        pass: boolean;
+        detail: string;
+    }[];
+    settlement?: unknown;
+}
+export interface Storefront {
+    app: Express;
+    catalog: Product[];
+    gate(resolve: GateResolver): void;
+    listen(port?: number): Promise<{
+        url: string;
+        port: number;
+    }>;
+    mcpServer(): McpServer;
+}
+export declare function originFromRequest(req: Request): string;
+export declare function createStorefront(opts?: StorefrontOptions): Storefront;