@tokenoftrust/storefront-runner 1.3.4-rc.3 → 1.4.0

package/apps/storefront/src/lib/content/index.ts

@@ -0,0 +1,27 @@
+/**
+ * Structured content contracts (spec §F4) — ONE import surface for the
+ * data-driven framework widgets, so tenant content (JSON) and the .astro
+ * components share a single typed vocabulary and a tenant never copies HTML/CSS.
+ *
+ * New F4 contracts: rich text, callouts, needs-review, prose/policy sections,
+ * trust strip. Re-exported here alongside the tier/comparison contracts F10
+ * already owns (in lib/membership/model) so a membership page and a policy page
+ * import from the same place. (The <BrandGrid> `Brand` contract lives with its
+ * component in components/commerce/BrandGrid.astro.)
+ */
+export * from "./richtext.js";
+export * from "./callout.js";
+export * from "./needsReview.js";
+export * from "./prose.js";
+export * from "./trustStrip.js";
+
+// Reused tier contracts (F10) — surfaced here so all structured widgets share
+// one contract entry point.
+export type {
+  Tier,
+  TierFigure,
+  TierFeature,
+  TierCta,
+  ComparisonRow,
+} from "@/lib/membership/model";
+export { isIllustrative } from "@/lib/membership/model";

package/apps/storefront/src/lib/content/needsReview.ts

@@ -0,0 +1,58 @@
+/**
+ * Needs-review contract (spec §F4). The structured form of the f05 sheet's
+ * `.needs-review` flag: a first-class marker that a piece of migrated/authored
+ * content is a PLACEHOLDER pending human confirmation before go-live (a refund
+ * window not yet confirmed with the merchant, a claim we won't fabricate). It is
+ * the honest counterpart to f09's real-or-absent rule — where f09 forbids
+ * FABRICATING proof, this lets a tenant explicitly SAY "this needs confirming"
+ * instead of shipping a guess.
+ *
+ * Two roles:
+ *   1. A visible dev/preview affordance (<NeedsReviewCallout>) — a reviewer sees
+ *      exactly what still needs sign-off. It is NEVER shown to shoppers: the
+ *      renderer includes it only in preview (see <ProseSections includeNeedsReview>).
+ *   2. A go-live GUARD ({@link auditNeedsReview}) — a `blocker`-severity flag
+ *      fails the audit, mirroring f09's auditTrustProof, so unresolved
+ *      placeholders can't silently ship.
+ * Node-free + presentation-free.
+ */
+
+export type NeedsReviewSeverity = "blocker" | "note";
+
+export interface NeedsReview {
+  /** What must be confirmed, e.g. "Refund window not confirmed with merchant". */
+  reason: string;
+  /** blocker → must resolve before go-live; note → advisory. Default "note". */
+  severity?: NeedsReviewSeverity;
+  /** Optional owner/assignee (a name or handle) responsible for the sign-off. */
+  owner?: string;
+  /** Optional link to the source/ticket/context for the review. */
+  href?: string;
+}
+
+export const NEEDS_REVIEW_TITLE = "Needs review before go-live";
+
+/** True when a flag must block go-live (severity "blocker"). */
+export function isBlocking(n: Pick<NeedsReview, "severity">): boolean {
+  return n.severity === "blocker";
+}
+
+export interface NeedsReviewViolation {
+  reason: string;
+  owner?: string;
+}
+
+/**
+ * Go-live guard: given the needs-review flags a page/tenant carries, `ok` is
+ * false when ANY is a blocker. Parallels f09's auditTrustProof — a clean page
+ * (no flags, or only advisory notes) passes; an unresolved blocker fails and
+ * lists what's outstanding. The deploy path calls this before promoting.
+ */
+export function auditNeedsReview(
+  flags: ReadonlyArray<NeedsReview>,
+): { ok: boolean; blockers: NeedsReviewViolation[] } {
+  const blockers = flags
+    .filter(isBlocking)
+    .map((f) => ({ reason: f.reason, owner: f.owner }));
+  return { ok: blockers.length === 0, blockers };
+}

package/apps/storefront/src/lib/content/prose.ts

@@ -0,0 +1,186 @@
+/**
+ * Prose / policy page contract (spec §F4). The marquee promotion: a policy /
+ * about / compliance page is authored as STRUCTURED sections — headings,
+ * paragraphs, lists, definition glossaries, callouts, a contact block, and
+ * needs-review flags — instead of the `body_html` blob that `[...slug].astro`
+ * used to `set:html`. <ProseSections> renders these with real headings, `<dl>`
+ * semantics, list landmarks, and safe links (no `set:html`), so a tenant drives
+ * a full policy page from JSON with no HTML/CSS to copy (the F4 acceptance).
+ *
+ * The section shapes mirror the repeated patterns the f05 sheet styled for the
+ * raw-HTML path (`.prose`, `.toc`, `.contact-card`, `.disclaimer`/`.warn-band`,
+ * `.needs-review`) — one content vocabulary, two delivery paths (raw fragment
+ * vs. structured widget), the same look from f06 tokens.
+ *
+ * Node-free + presentation-free.
+ */
+import type { RichText } from "./richtext.js";
+import { plainText } from "./richtext.js";
+import type { CalloutTone } from "./callout.js";
+import type { NeedsReview } from "./needsReview.js";
+
+/** A section heading (renders <h2> or <h3>; carries/derives an anchor id). */
+export interface ProseHeadingSection {
+  kind: "heading";
+  text: string;
+  /** 2 → <h2> (default), 3 → <h3>. Keeps a real document outline. */
+  level?: 2 | 3;
+  /** Anchor id for TOC links; derived from `text` when omitted. */
+  id?: string;
+}
+
+export interface ProseParagraphSection {
+  kind: "paragraph";
+  text: RichText;
+}
+
+/** A bullet (default) or numbered list. */
+export interface ProseListSection {
+  kind: "list";
+  items: RichText[];
+  ordered?: boolean;
+}
+
+/** A definition glossary — renders a semantic <dl>/<dt>/<dd>. */
+export interface ProseDefinitionsSection {
+  kind: "definitions";
+  items: { term: string; description: RichText }[];
+}
+
+/** A tone-styled callout embedded in the flow (see callout.ts). */
+export interface ProseCalloutSection {
+  kind: "callout";
+  tone: CalloutTone;
+  title?: string;
+  body: RichText;
+}
+
+/** A contact block — renders a semantic <address> with real mailto/tel links. */
+export interface ProseContactSection {
+  kind: "contact";
+  heading?: string;
+  email?: string;
+  phone?: string;
+  /** Postal address lines, rendered in order. */
+  address?: string[];
+}
+
+/** A needs-review flag embedded in the flow (see needsReview.ts). */
+export type ProseNeedsReviewSection = { kind: "needs_review" } & NeedsReview;
+
+export type ProseSection =
+  | ProseHeadingSection
+  | ProseParagraphSection
+  | ProseListSection
+  | ProseDefinitionsSection
+  | ProseCalloutSection
+  | ProseContactSection
+  | ProseNeedsReviewSection;
+
+/** A full structured page (policy / about / compliance). */
+export interface ProsePage {
+  title: string;
+  eyebrow?: string;
+  intro?: string;
+  /** ISO date (YYYY-MM-DD) rendered as a "Last updated" line. */
+  updated?: string;
+  sections: ProseSection[];
+}
+
+/** Slugify heading text into a stable, URL-safe anchor id. */
+export function slugifyHeading(text: string): string {
+  return text
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+/**
+ * Drop structurally-empty sections (a blank heading, an empty paragraph/list,
+ * an empty definitions/contact block) so a partially-authored page never
+ * renders a stray empty node.
+ */
+export function normalizeProse(
+  sections: ReadonlyArray<ProseSection>,
+): ProseSection[] {
+  const out: ProseSection[] = [];
+  for (const s of sections) {
+    switch (s.kind) {
+      case "heading":
+        if (s.text.trim()) out.push(s);
+        break;
+      case "paragraph":
+        if (plainText(s.text)) out.push(s);
+        break;
+      case "list": {
+        const items = s.items.filter((i) => plainText(i));
+        if (items.length) out.push({ ...s, items });
+        break;
+      }
+      case "definitions": {
+        const items = s.items.filter((d) => d.term.trim() && plainText(d.description));
+        if (items.length) out.push({ ...s, items });
+        break;
+      }
+      case "callout":
+        if (plainText(s.body)) out.push(s);
+        break;
+      case "contact":
+        if (s.email || s.phone || (s.address && s.address.length)) out.push(s);
+        break;
+      case "needs_review":
+        if (s.reason.trim()) out.push(s);
+        break;
+    }
+  }
+  return out;
+}
+
+/** Fill in a derived `id` for every heading that lacks one (for TOC anchoring). */
+export function withHeadingIds(
+  sections: ReadonlyArray<ProseSection>,
+): ProseSection[] {
+  const seen = new Map<string, number>();
+  return sections.map((s) => {
+    if (s.kind !== "heading") return s;
+    const base = s.id?.trim() || slugifyHeading(s.text);
+    // De-dupe collisions so anchors stay unique on a long policy page.
+    const n = seen.get(base) ?? 0;
+    seen.set(base, n + 1);
+    const id = n === 0 ? base : `${base}-${n + 1}`;
+    return { ...s, id };
+  });
+}
+
+export interface TocEntry {
+  id: string;
+  text: string;
+  level: 2 | 3;
+}
+
+/**
+ * The table-of-contents entries for a page — one per level-2 heading (the
+ * top-level policy sections). Assumes {@link withHeadingIds} has run so every
+ * heading has an id. Level-3 headings are excluded to keep the chip row short.
+ */
+export function tableOfContents(
+  sections: ReadonlyArray<ProseSection>,
+): TocEntry[] {
+  const out: TocEntry[] = [];
+  for (const s of sections) {
+    if (s.kind === "heading" && (s.level ?? 2) === 2 && s.id) {
+      out.push({ id: s.id, text: s.text, level: 2 });
+    }
+  }
+  return out;
+}
+
+/** Every needs-review flag on a page (for the go-live audit). */
+export function collectNeedsReview(
+  sections: ReadonlyArray<ProseSection>,
+): NeedsReview[] {
+  return sections
+    .filter((s): s is ProseNeedsReviewSection => s.kind === "needs_review")
+    .map(({ kind: _kind, ...flag }) => flag);
+}

package/apps/storefront/src/lib/content/richtext.ts

@@ -0,0 +1,76 @@
+/**
+ * Inline rich-text model (spec §F4 structured framework widgets).
+ *
+ * The structured content widgets replace hand-authored HTML fragments with
+ * DATA. Prose still needs a LITTLE inline formatting — a link, a bold run —
+ * without reopening the raw-HTML door (which f09's real-or-absent rule and the
+ * CSP both push us to close). So instead of a `body_html` blob a paragraph
+ * carries a {@link RichText}: either a plain string (the common case) or an
+ * array of typed {@link InlineRun}s. Components render runs as real DOM
+ * (anchors, <strong>, <em>) with NO `set:html`, so there is no injection seam
+ * and no per-tenant markup to copy.
+ *
+ * Node-free + presentation-free: this is the shared shape the .astro widgets
+ * and the contract tests both import.
+ */
+
+/** A run of inline content inside a {@link RichText}. */
+export type InlineRun =
+  /** Plain (optionally emphasized) text. */
+  | { kind: "text"; text: string; strong?: boolean; em?: boolean }
+  /** A hyperlink. `external` is derived by {@link isExternalHref} when omitted. */
+  | { kind: "link"; text: string; href: string; external?: boolean };
+
+/**
+ * Inline content for a paragraph / list item / callout body / definition. A
+ * bare string is the ergonomic common case (one text run); an array carries
+ * mixed links + emphasis. Authors never write HTML here.
+ */
+export type RichText = string | InlineRun[];
+
+/**
+ * True when a href points off-site (so the link component adds
+ * rel="noopener noreferrer" + a new-tab affordance). Protocol-relative (`//…`)
+ * and absolute http(s) URLs are external; site-root (`/…`), anchors (`#…`),
+ * and `mailto:` / `tel:` are treated as in-context (same tab, no rel).
+ */
+export function isExternalHref(href: string): boolean {
+  const h = href.trim();
+  if (h.startsWith("//")) return true;
+  return /^https?:\/\//i.test(h);
+}
+
+/**
+ * Normalize any {@link RichText} to an array of runs. A plain string becomes a
+ * single text run; an existing array is returned filtered of empty text runs
+ * (an empty link text keeps its href-less nothing dropped too). Every returned
+ * link run has an explicit `external` flag so the component needn't recompute.
+ */
+export function toRuns(rich: RichText | null | undefined): InlineRun[] {
+  if (rich == null) return [];
+  if (typeof rich === "string") {
+    return rich.length > 0 ? [{ kind: "text", text: rich }] : [];
+  }
+  const out: InlineRun[] = [];
+  for (const run of rich) {
+    if (run.kind === "text") {
+      if (run.text.length > 0) out.push(run);
+    } else if (run.kind === "link") {
+      if (run.text.length > 0 && run.href.length > 0) {
+        out.push({ ...run, external: run.external ?? isExternalHref(run.href) });
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Flatten a {@link RichText} to plain text — for aria-labels, SEO descriptions,
+ * and heading-id slugs. Never emits markup.
+ */
+export function plainText(rich: RichText | null | undefined): string {
+  return toRuns(rich)
+    .map((r) => r.text)
+    .join("")
+    .trim();
+}

package/apps/storefront/src/lib/content/trustStrip.ts

@@ -0,0 +1,74 @@
+/**
+ * Trust-strip contract (spec §F4, governed by f09's real-or-absent rule).
+ *
+ * A trust strip is the quiet row of proof tokens a store repeats across pages
+ * ("Ships from USA", "Lab-tested", a rating). Because a rating/review token is
+ * exactly the kind of social proof f09 forbids FABRICATING, this contract is
+ * real-or-absent BY CONSTRUCTION: {@link sanitizeTrustStrip} reuses f09's
+ * `isFabricatedTrustProof` detector to drop any claim that is actually scraped
+ * review-widget markup, and drops any rating token whose average/count aren't
+ * real positive finite numbers (the same test `readReviewAggregate` applies). A
+ * strip with nothing real left renders NOTHING — never a fabricated badge.
+ *
+ * Node-free + presentation-free; the .astro widget renders the sanitized items.
+ */
+import { isFabricatedTrustProof } from "@tot/public-runtime";
+
+export type TrustStripItem =
+  /** A plain proof claim, e.g. "Ships from USA", "Lab-tested". */
+  | { kind: "claim"; label: string }
+  /**
+   * A REAL aggregate rating. Surfaced only when `average` (1–5) and `count`
+   * are real positive finite numbers — a half-populated aggregate is dropped.
+   */
+  | { kind: "rating"; average: number; count: number; label?: string };
+
+/** True when a rating token is backed by real, positive, finite numbers. */
+export function isRealRating(
+  item: Extract<TrustStripItem, { kind: "rating" }>,
+): boolean {
+  const { average, count } = item;
+  return (
+    Number.isFinite(average) &&
+    average > 0 &&
+    average <= 5 &&
+    Number.isFinite(count) &&
+    count > 0
+  );
+}
+
+/**
+ * Drop everything that isn't real proof:
+ *   - a `claim` whose label carries scraped review-widget markup / a baked-in
+ *     aggregate (f09's `isFabricatedTrustProof`), or is blank;
+ *   - a `rating` that isn't a real positive finite aggregate ({@link isRealRating}).
+ * The result is safe to render verbatim; an empty result means "render nothing".
+ */
+export function sanitizeTrustStrip(
+  items: ReadonlyArray<TrustStripItem>,
+): TrustStripItem[] {
+  const out: TrustStripItem[] = [];
+  for (const item of items) {
+    if (item.kind === "claim") {
+      const label = item.label.trim();
+      if (label.length > 0 && !isFabricatedTrustProof(label)) {
+        out.push({ kind: "claim", label });
+      }
+    } else if (item.kind === "rating") {
+      if (isRealRating(item)) out.push(item);
+    }
+  }
+  return out;
+}
+
+/**
+ * A screen-reader label for a real rating token, e.g.
+ * "Rated 4.9 out of 5 from 369 reviews". Callers pass only sanitized ratings.
+ */
+export function ratingAriaLabel(
+  item: Extract<TrustStripItem, { kind: "rating" }>,
+): string {
+  const avg = Math.round(item.average * 10) / 10;
+  const noun = item.count === 1 ? "review" : "reviews";
+  return `Rated ${avg} out of 5 from ${item.count} ${noun}`;
+}

package/apps/storefront/src/lib/content-edit/client.ts

@@ -5,14 +5,20 @@
  * same tool-result unwrap, same typed errors) — reusing the forge seam's
  * exported transport + error types so there is ONE wire contract, not two.
  *
- * AUTH SHAPE (G4 design note, `pending beta/WS2 confirmation`): the storefront
- * backend calls `content_edit` as the TENANT OPERATOR (`credential_validate`
- * with storefront's own TOT_API_KEY/TOT_SECRET_KEY — the SAME credential
- * change/accept already uses), not as the individual signed-in developer.
- * Developer-level authorization is the caller's job (`/dev`'s own
- * `readViewerSession()` + capability check, BEFORE this client is ever
- * constructed) — this client only proves "a legitimate storefront backend is
- * asking", the same trust boundary `/api/changes/accept` already relies on.
+ * AUTH SHAPE (Option A, `content-edit-machine-identity` — mirrors change/B3):
+ * the storefront backend calls `content_edit` with the SAME machine-identity
+ * APP token the change/forge clients use — a `client_credentials` +
+ * `private_key_jwt` token minted against the MCP's OAuth token endpoint via
+ * {@link AppTokenProvider}, attached as Bearer at `initialize` and on every
+ * request by {@link FetchTransport} — NOT the retired `credential_validate`
+ * handshake and NOT a human `TOT_ACCESS_TOKEN`. Developer-level authorization
+ * is, and remains, the caller's job: `/dev`'s own `readViewerSession()` +
+ * capability check (BEFORE this client is ever constructed) derives the
+ * tenant from the signed-in developer's OWN session, never from a
+ * caller-supplied value — tenant isolation is enforced there, unaffected by
+ * this change. This client only proves "a legitimate storefront backend
+ * (machine identity) is asking", the same trust boundary
+ * `/api/changes/accept` already relies on post-B3.
  */
 import {
   FetchTransport,
@@ -20,16 +26,25 @@ import {
   ForgeConfigError,
   ForgeTransportError,
   SESSION_HEADER,
+  AppTokenProvider,
+  deriveMcpOauthEndpoints,
   type McpTransport,
   type JsonRpcRequest,
   type TotCredentials,
   type TransportResponse,
+  type BearerProvider,
 } from "@/lib/forge";
 import { mapForgeError } from "@/lib/forge/errors.js";
 import { readEnv } from "@/lib/env";
 import type { ContentEditFile, ContentEditResult } from "./types.js";
 
 export const CONTENT_EDIT_TOOL = {
+  /**
+   * Session-validation tool for the NON-OAuth (api-key/secret) construction —
+   * kept ONLY for backward-compatible test-transport injection (no
+   * bearerProvider). The deployed path never calls this — see the module
+   * header.
+   */
   validate: "credential_validate",
   edit: "content_edit",
 } as const;
@@ -77,10 +92,21 @@ function unwrapToolResult<T>(result: unknown): T {
 export interface JsonRpcContentEditClientConfig {
   /** MCP base URL (the `POST /mcp` endpoint). */
   baseUrl: string;
-  /** Storefront's ToT operator credentials for `credential_validate`. */
+  /** Storefront's ToT credentials for the legacy `credential_validate` path. */
   credentials: TotCredentials;
   /** Transport override (defaults to fetch). Injected by tests. */
   transport?: McpTransport;
+  /**
+   * Machine-identity app-token source (mirrors forge's B2 / change's B3,
+   * binding `c0-forge-auth-supersede`). When present, the client
+   * authenticates PURELY via a `client_credentials` + `private_key_jwt` app
+   * token — attached as Bearer at `initialize` and on every request by
+   * {@link FetchTransport}, re-minted on expiry/401 — and NEVER calls the
+   * retired `credential_validate` handshake. Built by
+   * {@link createContentEditClient} from `MCP_BASE_URL`; tests may inject
+   * their own {@link BearerProvider}.
+   */
+  bearerProvider?: BearerProvider;
 }
 
 // --- The client -----------------------------------------------------------
@@ -92,6 +118,8 @@ export class JsonRpcContentEditClient {
   private nextId = 1;
   /** Cached session validation — validate once, reuse (lazily). */
   private sessionPromise?: Promise<string | undefined>;
+  /** True when a machine-identity app token authenticates the session (mirrors forge B2 / change B3). */
+  private readonly usesServiceAuth: boolean;
 
   constructor(config: JsonRpcContentEditClientConfig) {
     if (!config.baseUrl) {
@@ -104,7 +132,9 @@ export class JsonRpcContentEditClient {
     }
     this.baseUrl = config.baseUrl;
     this.credentials = config.credentials;
-    this.transport = config.transport ?? new FetchTransport(config.baseUrl);
+    this.usesServiceAuth = config.bearerProvider != null;
+    this.transport =
+      config.transport ?? new FetchTransport(config.baseUrl, config.bearerProvider);
   }
 
   async editContent(
@@ -123,7 +153,17 @@ export class JsonRpcContentEditClient {
   // --- internals (mirror JsonRpcChangeClient) --------------------------------
 
   private ensureSession(): Promise<string | undefined> {
-    this.sessionPromise ??= this.validateSession();
+    // Service-auth (mirrors forge B2 / change B3 / binding
+    // `c0-forge-auth-supersede`): the app token is attached as Bearer at the
+    // transport layer (initialize + every request), so the legacy
+    // `credential_validate` round-trip is skipped entirely — it was retired
+    // MCP-side and would now be rejected. FetchTransport still threads the
+    // real `Mcp-Session-Id` the Bearer-authed handshake minted, so a session
+    // id is never needed from here. Without a bearerProvider (e.g. an
+    // injected mock transport in unit tests) the legacy validate path is kept.
+    this.sessionPromise ??= this.usesServiceAuth
+      ? Promise.resolve(undefined)
+      : this.validateSession();
     return this.sessionPromise;
   }
 
@@ -211,7 +251,21 @@ export class JsonRpcContentEditClient {
 
 /**
  * Build a {@link JsonRpcContentEditClient} from the runtime env — the SAME env
- * the change client reads (`MCP_BASE_URL` + storefront's own ToT credentials).
+ * the change client reads:
+ *   - `MCP_BASE_URL`  — the `POST /mcp` endpoint (its ORIGIN also hosts the OAuth
+ *     token endpoint + resource the app token binds to; already `…/storefront`
+ *     per B4, so the app token's resource + this RPC endpoint match).
+ *   - `TOT_API_KEY` (+ optional `TOT_SECRET_KEY`) — storefront's OWN ToT
+ *     credentials (retained for legacy/local paths; the deployed content-edit
+ *     session no longer uses them for auth).
+ *
+ * Machine identity (mirrors forge B2 / change B3 / binding
+ * `c0-forge-auth-supersede`): the content-edit session authenticates with a
+ * `client_credentials` + `private_key_jwt` APP token minted against the MCP's
+ * OAuth token endpoint via {@link AppTokenProvider} — NOT a human
+ * `TOT_ACCESS_TOKEN` and NOT a shared secret. `TOT_ACCESS_TOKEN` is
+ * deliberately NOT read here.
+ *
  * Throws {@link ForgeConfigError} when the base URL or api key is missing.
  * Secrets are read via {@link readEnv} and never logged.
  */
@@ -224,7 +278,9 @@ export async function createContentEditClient(
     ({
       apiKey: (await readEnv("TOT_API_KEY")) ?? "",
       secretKey: await readEnv("TOT_SECRET_KEY"),
-      accessToken: await readEnv("TOT_ACCESS_TOKEN"),
     } satisfies TotCredentials);
-  return new JsonRpcContentEditClient({ ...overrides, baseUrl, credentials });
+  const bearerProvider =
+    overrides.bearerProvider ??
+    (baseUrl ? new AppTokenProvider(deriveMcpOauthEndpoints(baseUrl)) : undefined);
+  return new JsonRpcContentEditClient({ ...overrides, baseUrl, credentials, bearerProvider });
 }

package/apps/storefront/src/lib/d1/catalog.ts

@@ -153,6 +153,18 @@ export async function getProductByHandle(
   return row ? (JSON.parse(row.data) as CatalogProduct) : null;
 }
 
+/**
+ * All active-status products, full data. No pagination — the D3 inventory
+ * projection (`api/apps/v1/inventory.ts`) reads the whole active catalog to
+ * build its per-SKU list, mirroring `searchProducts`'s active-only scoping.
+ */
+export async function listAllActiveProducts(db: Queryable): Promise<CatalogProduct[]> {
+  const rows = await db.all<{ data: string }>(
+    `SELECT data FROM products WHERE status = 'active' ORDER BY position ASC`,
+  );
+  return rows.map((r) => JSON.parse(r.data) as CatalogProduct);
+}
+
 function sortClause(sort?: ListProductsQuery["sort"]): string {
   switch (sort) {
     case "price-asc":