[Epic] Pluggable createStorefront sources — fold demo-hand-rolled infra into attestomcp-storefront

[dzuluaga]

Why

attestomcp-from-scratch is 28 lines because the storefront module hides the whole ceremony. But every real deployment re-implements the same infrastructure our shopping demo hand-rolls — persistence and a live catalog loader — because createStorefront doesn't own them. That makes "using AttestoMCP" look far heavier than the quickstart.

Goal: make createStorefront accept pluggable stores / sources so consumers never hand-write adapters, and the demo collapses back toward the 28-line quickstart.

Children

• createStorefront: first-class persistence (redis option) so consumers don't hand-write store adapters #27 — persistence: createStorefront({ storage: redisStorage(…) }) builds cart/order/verification stores internally
• createStorefront: first-class dynamic/Firestore catalog source so consumers don't hand-write the loader #28 — dynamic catalog: createStorefront({ catalog: firestoreCatalog(…) }) owns the loader + TTL cache + fail-closed
• scope A (credentagent#29): flip to published @openmobilehub/credentagent-* and delete the hand-rolled Redis + Firestore adapters mcp-apps-shopping-demo#27 — scope A: slim mcp-apps-shopping-demo to consume both (flip to published @openmobilehub/credentagent-* ^0.2.x, delete its 3 Redis adapter classes + catalog-store.ts / firebase-admin.ts / catalog-source.ts)

Design

One combined spec (via spec-kit) covering the shared seam — pluggable stores + catalog sources — with these invariants held:

• In-memory stores and the static catalog array remain the zero-config defaults (quickstart unchanged).
• Explicit store/catalog injection still supported and precedence-clear (custom-backend escape hatch).
• Security: per-order verification scoping (invariant 4), server-side price/age re-derivation (invariant 2), catalog fail-closed on empty/unreachable load.
• @upstash/redis / Firebase Admin stay peer/optional so in-memory/static users keep a lean install.

API contract (maintainer-owned — anchor for the spec)

The public signatures below are the contract; the spec fleshes out behavior, edge cases, and tests within them. Any change to these signatures needs maintainer (@dzuluaga) sign-off — this is a separate, explicit line in the review gate, because a published API shape is not reversible the way an implementation is.

interface CreateStorefrontOptions {
  // …existing: catalog, reviews, baseUrl, signingKey, cartStore, orderStore, … …

  // #27 persistence — where cart/order/verification state lives; in-memory is the default
  storage?: StorageAdapter;

  // #28 catalog — a SOURCE, not only a static array; the array stays the default
  catalog?: Product[] | CatalogSource;
}

// symmetric factories — the backend name lives in the helper, never the option

// #27 helper — builds cart + created/completed-order + verification stores from one handle
function redisStorage(opts: {
  url: string;
  token: string;                             // @upstash/redis-compatible (HTTP/REST)
  namespace?: string;                        // key prefix; isolates deployments on a shared instance
}): StorageAdapter;

// #28 helper — the module owns loader + TTL cache + fail-closed
function firestoreCatalog(opts: {
  credentials?: FirebaseAdminCreds;          // else GOOGLE_APPLICATION_CREDENTIALS
  collection?: string;
  ttlMs?: number;                            // default 300_000
}): CatalogSource;

interface StorageAdapter {
  // provides the four stores createStorefront needs, each scoped per order id (Security invariant 4)
}
interface CatalogSource {
  load(): Promise<Product[]>;                // fail-closed: throws on empty/unreachable cold load
}

Precedence / defaults (also maintainer-owned):

• Explicit store injection (cartStore / createdOrderStore / orderStore / verificationStore) wins over storage — the custom-backend escape hatch.
• No storage and no explicit stores → in-memory (zero-config default; quickstart unchanged).
• catalog as Product[] → static (default); as CatalogSource → dynamic.
• @upstash/redis and firebase-admin stay peer/optional deps.
• Naming rule: options name the concept (storage, catalog); the backend appears only in the factory (redisStorage, firestoreCatalog) — so a future postgresStorage() / sqlCatalog() needs no interface change.

Related

• Rename Rename public API identifier AttestoMcp → AttestoMCP (all-caps MCP brand token) #26 (AttestoMcp → AttestoMCP)
• Demo Firestore PR DX: "bring your own host" recipe + a typed seam contract (defineHost) for non-storefront integration #24 (mcp-apps-shopping-demo) — the reference implementation being folded in

[dzuluaga]

@TheBlackBit — assigning you this epic and its two children. Here's the brief.

What: one combined spec (via spec-kit) for the shared seam behind #27 + #28 — making createStorefront accept pluggable stores / catalog sources so consumers never hand-write infra.

Why it matters: attestomcp-from-scratch is 28 lines because the module hides the ceremony. The moment someone deploys for real, they re-implement persistence and a live catalog loader by hand — exactly what the shopping demo does today. This epic folds that back into the module.

Reference implementations to generalize (already written, just not in the package):

• createStorefront: first-class persistence (redis option) so consumers don't hand-write store adapters #27 persistence → the demo's api/compose-storefront.ts — the three adapter classes RedisCartStore / RedisJsonStore / RedisVerificationStore.
• createStorefront: first-class dynamic/Firestore catalog source so consumers don't hand-write the loader #28 catalog → your PR DX: "bring your own host" recipe + a typed seam contract (defineHost) for non-storefront integration #24 in mcp-apps-shopping-demo: catalog-store.ts (loader + 5-min TTL + fail-closed), firebase-admin.ts (lazy Admin SDK), catalog-source.ts (CATALOG_SOURCE selection).

Guardrails:

• The API contract is anchored in the epic body (signatures + precedence/defaults). Design freely within it; any change to the signatures themselves needs @dzuluaga sign-off.
• Preserve the security invariants: per-order verification scoping (invariant 4), server-side price/age re-derivation (invariant 2), catalog fail-closed. Keep @upstash/redis + firebase-admin peer/optional.
• In-memory stores and the static catalog array stay the zero-config defaults — the 28-line quickstart must not change.

Process: spec-kit — specify → clarify → plan → tasks. Review gate: @dzuluaga approves the spec before any implementation, with the API shape as a separate explicit approval line.

Heads-up (prereq): the repo isn't spec-kit-initialized yet (only .specify/memory/ on main, no scripts/templates). Setup is being coordinated with @dzuluaga — sync with him before running speckit-specify so you start on a ready repo.

[dzuluaga]

API contract refined (maintainer): persistence is now storage?: StorageAdapter + a redisStorage({ url, token, namespace }) factory — symmetric with catalog / firestoreCatalog(), replacing the earlier redis: { url, token } + top-level namespace. Rationale: options name the concept (storage, catalog); the backend lives only in the factory, so a future postgresStorage() needs no interface change. @TheBlackBit — spec to the updated signatures in the epic body. #27 body updated to match.