@openmobilehub/credentagent-storefront 0.2.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,186 @@
+# @openmobilehub/credentagent-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/credentagent-gate`](../credentagent-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/credentagent-storefront`)
+> and the runnable MCP server (`@openmobilehub/credentagent-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/credentagent-storefront @openmobilehub/credentagent-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.credentagent`, so
+`new CredentAgent().mount(store.app)` wires the real `/credentagent/*` 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/credentagent-storefront/server";
+import { CredentAgent, age, membership, payment, required, optional } from "@openmobilehub/credentagent-gate";
+
+const store = createStorefront();                  // the whole storefront — one line
+const credentagent = new CredentAgent();
+credentagent.mount(store.app);                          // wires the real /credentagent/* ceremony rails
+
+store.gate((order) =>                              // resolved on every checkout (payment settles LAST)
+  credentagent.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 `credentagent.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).
+
+## Production persistence — one option, no adapters
+
+`createStorefront()` defaults to **in-memory** stores — perfect for local dev and the quickstart
+above. A real deployment runs on **multiple instances** (serverless / Vercel), where a cart added on
+one instance is invisible to the checkout that lands on another, so production needs **shared
+persistence**. Pass a `storage` provider and all four stores (cart, created-order, completed-order,
+verification) are backed by it — no hand-written adapters:
+
+```ts
+import { createStorefront } from "@openmobilehub/credentagent-storefront/server";
+import { redisStorage } from "@openmobilehub/credentagent-storefront/redis";
+
+const store = createStorefront({
+  storage: redisStorage({
+    url: process.env.KV_REST_API_URL!,
+    token: process.env.KV_REST_API_TOKEN!,
+    namespace: "my-shop",            // isolates keys if multiple shops share one Redis
+  }),
+});
+```
+
+- **In-memory stays the zero-config default** — omit `storage` and nothing changes.
+- **Escape hatch:** an explicit `cartStore` / `orderStore` / `createdOrderStore` / `verificationStore`
+  still wins over the provider for that slot (bring any custom backend).
+- **Lean by default:** `@upstash/redis` is an **optional peer dependency**, loaded lazily only on the
+  `{ url, token }` path — in-memory users never install it.
+- Order and verification state is **keyed per order id**, and the **cart is keyed per MCP session**
+  (`${namespace}:cart:${sessionId}`) — never process-global (Security invariant 4); the store persists
+  state only and is **not** a trust anchor.
+- **Per-user carts need session affinity on serverless.** Each MCP session gets its own cart, but the
+  session/transport lives in per-instance memory — so a **multi-instance serverless** deployment needs
+  **sticky sessions** for a shopper's cart to follow them. (Orders & verification are keyed by order id
+  and are unaffected.)
+
+## Live catalog — one option, no loader
+
+`createStorefront({ catalog })` takes a static `Product[]` by default — perfect for the quickstart.
+A real merchant wants to edit products **without a redeploy**, i.e. a **dynamic catalog source**.
+Pass `firestoreCatalog(...)` and the module owns the loader, the cache, and fail-closed loading — no
+hand-written glue:
+
+```ts
+import { createStorefront } from "@openmobilehub/credentagent-storefront/server";
+import { firestoreCatalog } from "@openmobilehub/credentagent-storefront/firestore";
+
+const store = createStorefront({
+  catalog: firestoreCatalog({
+    collection: "products",   // Firestore collection of product docs
+    ttlMs: 300_000,           // cache for 5 min, then refresh
+    // credential: { projectId, clientEmail, privateKey }  // or rely on Application Default Credentials
+  }),
+});
+```
+
+- **Static array stays the zero-config default** — pass a `Product[]` (or omit `catalog`) and nothing
+  changes; no Firebase required.
+- **Fails closed:** an empty/unreachable **cold** load **refuses** (the server returns 503) rather than
+  serving an empty catalog; a **refresh** blip serves the last-known-good catalog; a malformed /
+  negative-price doc **fails the load** (never silently drops a product).
+- **Prices and age thresholds re-derive server-side** from the loaded catalog on every completion path
+  (Security invariant 2 — never trust the order token).
+- **Lean by default:** `firebase-admin` is an **optional peer dependency**, loaded lazily only on the
+  credentials path — static-catalog users never install it.
+
+## 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 `/credentagent/*` ceremony routes
+   `credentagent.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/credentagent-storefront";
+
+const cart = priceCart([{ productId: "oak-whiskey", quantity: 1 }], SAMPLE_CATALOG);
+cart.hasAgeRestricted;                            // true → wire @openmobilehub/credentagent-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.
+- Catalog is static by default or a **dynamic source** (`firestoreCatalog(...)` from `./firestore`) —
+  edit products with no redeploy; loaded + cached server-side, fail-closed.
+
+`createStorefront()` accepts `{ catalog, reviews, baseUrl, cartStore, orderStore, createdOrderStore,
+verificationStore, storage, signingKey, allowEphemeralKey, settle }`. `catalog` is a `Product[]` (static)
+or a `CatalogSource` (dynamic, e.g. `firestoreCatalog(...)`). 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/credentagent-gate`](../credentagent-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,110 @@
+/** 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/credentagent-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 source of products for `createStorefront({ catalog })`. The static-array default is
+ * wrapped in `staticCatalog(...)`; a DYNAMIC source (e.g. `firestoreCatalog(...)` from
+ * `@openmobilehub/credentagent-storefront/firestore`) loads products server-side with a TTL
+ * cache so a merchant edits the catalog without a redeploy.
+ *
+ * Two methods so an async source can feed the gate's SYNCHRONOUS ceremony re-price:
+ * `load()` refreshes (fail-closed on a cold/empty load); `current()` returns the
+ * last-known-good snapshot the synchronous re-price paths read. The storefront awaits
+ * `load()` before every request, so `current()` is always warm inside a handler. Prices
+ * and age thresholds are always re-derived from this source server-side (Security
+ * invariant 2 — never trust the order token).
+ */
+export interface CatalogSource {
+    /** Load the current catalog, TTL-cached. Rejects (fail-closed) on a cold/empty load. */
+    load(): Promise<Product[]>;
+    /** Last-known-good snapshot for the synchronous re-price paths. Throws if never loaded. */
+    current(): Product[];
+}
+/** Wrap a static product array as a {@link CatalogSource} — the zero-config default (never fails). */
+export declare function staticCatalog(products: Product[]): CatalogSource;
+/** True when `x` is a {@link CatalogSource} (has a `load` method) rather than a plain `Product[]`. */
+export declare function isCatalogSource(x: Product[] | CatalogSource | undefined): x is CatalogSource;
+/** A tiny runnable catalog (incl. one age-restricted item) so the package demos itself. */
+export declare const SAMPLE_CATALOG: Product[];