@tokenoftrust/storefront-runner 0.1.0

package/apps/storefront/src/lib/auth/totAccessClient.ts

@@ -0,0 +1,503 @@
+/**
+ * TotAccessClient — the storefront's seam to tot20's two access-code endpoints
+ * that back "Sign in with Token of Trust" for a gated preview host:
+ *
+ *   POST /api/internal/access-code/send   { email, resource }
+ *        → always 200 { ok: true }  (neutral; tot20 mails a code only if the
+ *          email holds a role on `resource` — enumeration-resistant)
+ *   POST /api/internal/access-code/verify { email, resource, code }
+ *        → { ok:true, email, resource, roles[], capability } on success
+ *        → { ok:false, reason } otherwise
+ *
+ * tot20 is the single authority: it owns the email→role map per appDomain (the
+ * grant check) AND the one-time code store. The storefront just relays and holds
+ * the resulting session. See /tmp/tot20-access-code-handoff.md for the contract.
+ *
+ * Built like `@/lib/forge` (interface + Http impl + Mock + env factory) so routes
+ * develop/test against `MockTotAccessClient` before the tot20 endpoints exist,
+ * then swap in the Http client with no call-site change.
+ *
+ * INTEGRATION NOTE (RESOLVED against live qa 2026-07-05): tot20's swagger
+ * `normalizeSecureUserRequest()` extracts machine creds from the request
+ * BODY/QUERY fields `totApiKey`/`totSecretKey` (or an `Authorization` bearer/
+ * license-key header) — NOT from custom `x-tot-*` headers. Verified empirically:
+ * creds in the body advance past auth (`problemFindingApiClient` for an unknown
+ * key) whereas header creds are rejected (`apiKeyRequired`). The wire is isolated
+ * to `credentialFields()` below — the ONLY spot to touch. Everything else (paths,
+ * bodies, response shapes) is contract-fixed.
+ */
+import { readEnv } from "@/lib/env";
+import { diagEmail } from "@/lib/diag/redact";
+
+/** `send` is deliberately opaque — it never reveals whether the email was eligible. */
+export interface AccessCodeSendResult {
+  ok: true;
+}
+
+/** `verify` echoes the roles/capability tot20 resolved for the email on `resource`. */
+export type AccessCodeVerifyResult =
+  | {
+      ok: true;
+      email: string;
+      resource: string;
+      roles: string[];
+      capability: string;
+      /**
+       * The signed ES256 identity assertion (compact JWS) tot emits at sign-in.
+       * Present-usually, NOT guaranteed: tot returns the flat result without it
+       * if signing hiccups (contract §6 graceful degradation). Phase 3 verifies
+       * this OFFLINE and derives the session from its claims rather than trusting
+       * the flat `roles`/`capability`. See `@/lib/auth/identityToken`.
+       */
+      id_token?: string;
+    }
+  | { ok: false; reason: VerifyFailureReason };
+
+export type VerifyFailureReason =
+  | "invalid"
+  | "expired"
+  | "too_many_attempts"
+  | "error";
+
+export interface TotAccessClient {
+  /** Ask tot20 to email a one-time code (only sent if the email is eligible). */
+  sendAccessCode(email: string, resource: string): Promise<AccessCodeSendResult>;
+  /** Verify the code; on success returns the viewer's roles + effective capability. */
+  verifyAccessCode(
+    email: string,
+    resource: string,
+    code: string,
+  ): Promise<AccessCodeVerifyResult>;
+  /**
+   * FEDERATED sign-in (multi-tenant): email a one-time code WITHOUT a resource —
+   * the caller (storefront, via its operator cred) is the audience; tot20 mails
+   * the code if the email holds a role on ANY tenant. Enumeration-resistant.
+   */
+  sendFederatedCode(email: string): Promise<AccessCodeSendResult>;
+  /**
+   * FEDERATED verify: on success the `id_token` carries ALL of the email's tenant
+   * memberships and `aud` = the calling app (storefront), not a tenant. `audience`
+   * echoes that aud so the caller can cross-check its configured app identity.
+   */
+  verifyFederatedCode(
+    email: string,
+    code: string,
+  ): Promise<FederatedVerifyResult>;
+  /**
+   * MAGIC-LINK exchange: exchange a single-use `signInToken` (minted by
+   * `developerInvites` with `issueSignInToken:true`) for a sign-in. POST-only by
+   * contract — never call this from a GET path (inbox link-scanners fire GET and would
+   * burn the token). Same result shape as {@link verifyFederatedCode}: the signed
+   * `id_token` is the SOLE authoritative output. `audience` is bound to the
+   * authenticated caller server-side, never passed in the body.
+   */
+  exchangeSignInToken(token: string): Promise<FederatedVerifyResult>;
+}
+
+/**
+ * Result of the FEDERATED verify. Success carries the signed `id_token` (whose
+ * claims — email + all `tenants[]` — are the sole authority) and the `audience`
+ * tot set (= the calling app). `id_token` is present-usually, not guaranteed
+ * (signer degradation, contract §6); the consumer fails closed when it's absent.
+ */
+export type FederatedVerifyResult =
+  | { ok: true; email: string; audience: string; id_token?: string }
+  | { ok: false; reason: VerifyFailureReason };
+
+// --- HTTP transport seam (injected by tests) --------------------------------
+
+export interface HttpResponseLike {
+  status: number;
+  json(): Promise<unknown>;
+}
+export interface HttpTransport {
+  post(url: string, headers: Record<string, string>, body: unknown): Promise<HttpResponseLike>;
+}
+
+/** Default transport: a JSON `fetch` POST. */
+export class FetchHttpTransport implements HttpTransport {
+  async post(url: string, headers: Record<string, string>, body: unknown) {
+    return fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json", accept: "application/json", ...headers },
+      body: JSON.stringify(body),
+    });
+  }
+}
+
+export interface HttpTotAccessClientConfig {
+  /** tot20 core API base (no trailing slash), e.g. https://qa.tokenoftrust.com */
+  baseUrl: string;
+  /** Storefront's own ToT credentials (machine auth to the private endpoints). */
+  apiKey: string;
+  secretKey?: string;
+  transport?: HttpTransport;
+}
+
+export class TotAccessClientError extends Error {}
+
+/** The real client. Neutral/typed on failure — a gate must fail closed, not throw. */
+export class HttpTotAccessClient implements TotAccessClient {
+  private readonly baseUrl: string;
+  private readonly apiKey: string;
+  private readonly secretKey?: string;
+  private readonly transport: HttpTransport;
+
+  constructor(config: HttpTotAccessClientConfig) {
+    if (!config.baseUrl) throw new TotAccessClientError("access: TOT_CORE_URL is not configured");
+    if (!config.apiKey) throw new TotAccessClientError("access: storefront ToT credentials are not configured");
+    this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+    this.apiKey = config.apiKey;
+    this.secretKey = config.secretKey;
+    this.transport = config.transport ?? new FetchHttpTransport();
+  }
+
+  /**
+   * The one integration-sensitive spot: how the storefront authenticates to the
+   * `requireSecretKey` endpoints. tot20 reads `totApiKey`/`totSecretKey` from the
+   * request body (`normalizeSecureUserRequest`), so we merge the storefront's own
+   * credentials into every POST body. Swap for a machine-JWT `Authorization:
+   * Bearer` here if tot20 ever requires it — this is the only place to change.
+   */
+  private credentialFields(): Record<string, string> {
+    const f: Record<string, string> = { totApiKey: this.apiKey };
+    if (this.secretKey) f.totSecretKey = this.secretKey;
+    return f;
+  }
+
+  async sendAccessCode(email: string, resource: string): Promise<AccessCodeSendResult> {
+    // Neutral by contract: even a transport error resolves to { ok: true } so the
+    // UI never leaks eligibility. (Real failures are logged server-side upstream.)
+    try {
+      await this.transport.post(
+        `${this.baseUrl}/api/internal/access-code/send`,
+        {},
+        { email: email.toLowerCase(), resource, ...this.credentialFields() },
+      );
+    } catch {
+      /* swallow — neutral response */
+    }
+    return { ok: true };
+  }
+
+  async verifyAccessCode(
+    email: string,
+    resource: string,
+    code: string,
+  ): Promise<AccessCodeVerifyResult> {
+    let res: HttpResponseLike;
+    try {
+      res = await this.transport.post(
+        `${this.baseUrl}/api/internal/access-code/verify`,
+        {},
+        { email: email.toLowerCase(), resource, code, ...this.credentialFields() },
+      );
+    } catch {
+      return { ok: false, reason: "error" };
+    }
+    let body: unknown;
+    try {
+      body = await res.json();
+    } catch {
+      return { ok: false, reason: "error" };
+    }
+    return normalizeVerify(body, email, resource);
+  }
+
+  async sendFederatedCode(email: string): Promise<AccessCodeSendResult> {
+    // Neutral by contract: a transport error still resolves to { ok: true } so the UI
+    // never leaks eligibility. But SERVER-SIDE we log tot20's real status/body — the
+    // client never sees it (enumeration-resistance preserved), and it's the only way
+    // to see why a code didn't send. Part of the cross-repo email-send trace.
+    try {
+      const res = await this.transport.post(
+        `${this.baseUrl}/api/internal/access-code/federated-send`,
+        {},
+        { email: email.toLowerCase(), ...this.credentialFields() },
+      );
+      let body: unknown = "(unread)";
+      try {
+        body = await res.json();
+      } catch {
+        body = "(non-JSON)";
+      }
+      try {
+        console.info(
+          "[diag:federated-send]",
+          JSON.stringify({ email: diagEmail(email.toLowerCase()), status: res.status, body }),
+        );
+      } catch {
+        /* never break */
+      }
+    } catch (e) {
+      try {
+        console.warn(
+          "[diag:federated-send] transport error",
+          e instanceof Error ? e.message : String(e),
+        );
+      } catch {
+        /* never break */
+      }
+    }
+    return { ok: true };
+  }
+
+  async verifyFederatedCode(
+    email: string,
+    code: string,
+  ): Promise<FederatedVerifyResult> {
+    let res: HttpResponseLike;
+    try {
+      res = await this.transport.post(
+        `${this.baseUrl}/api/internal/access-code/federated-verify`,
+        {},
+        { email: email.toLowerCase(), code, ...this.credentialFields() },
+      );
+    } catch {
+      return { ok: false, reason: "error" };
+    }
+    let body: unknown;
+    try {
+      body = await res.json();
+    } catch {
+      return { ok: false, reason: "error" };
+    }
+    return normalizeFederatedVerify(body, email);
+  }
+
+  async exchangeSignInToken(token: string): Promise<FederatedVerifyResult> {
+    let res: HttpResponseLike;
+    try {
+      res = await this.transport.post(
+        `${this.baseUrl}/api/internal/access-code/exchange`,
+        {},
+        { token, ...this.credentialFields() },
+      );
+    } catch {
+      return { ok: false, reason: "error" };
+    }
+    let body: unknown;
+    try {
+      body = await res.json();
+    } catch {
+      return { ok: false, reason: "error" };
+    }
+    // The token is bound to (email, audience) server-side; the response carries the
+    // authoritative email (no client-supplied fallback needed).
+    return normalizeFederatedVerify(body, "");
+  }
+}
+
+/** Parse tot20's FEDERATED verify response into a typed result (fail closed). */
+export function normalizeFederatedVerify(
+  body: unknown,
+  email: string,
+): FederatedVerifyResult {
+  // Unwrap the `{ content, metadata }` envelope when present (see normalizeVerify).
+  const raw = (body ?? {}) as Record<string, unknown>;
+  const b = (raw.content && typeof raw.content === "object" ? raw.content : raw) as Record<string, unknown>;
+  if (b.ok === true) {
+    const idToken =
+      typeof b.id_token === "string"
+        ? b.id_token
+        : typeof b.assertion === "string"
+          ? b.assertion
+          : undefined;
+    const result: FederatedVerifyResult = {
+      ok: true,
+      email: typeof b.email === "string" ? b.email.toLowerCase() : email.toLowerCase(),
+      audience: typeof b.audience === "string" ? b.audience : "",
+    };
+    if (idToken) result.id_token = idToken;
+    return result;
+  }
+  const reason = b.reason;
+  const known: VerifyFailureReason[] = ["invalid", "expired", "too_many_attempts", "error"];
+  return {
+    ok: false,
+    reason: known.includes(reason as VerifyFailureReason) ? (reason as VerifyFailureReason) : "invalid",
+  };
+}
+
+/** Parse + validate tot20's verify response into our typed result (fail closed). */
+export function normalizeVerify(
+  body: unknown,
+  email: string,
+  resource: string,
+): AccessCodeVerifyResult {
+  // tot20 wraps every API response in a `{ content, metadata }` envelope
+  // (swagger `sendJsonResponse`). Verified against live qa 2026-07-05: access-code
+  // /verify returns `{ content: { ok, email, resource, id_token }, metadata }`.
+  // Unwrap `content` when present; fall back to the raw body (the Mock + tests
+  // return the un-enveloped shape).
+  const raw = (body ?? {}) as Record<string, unknown>;
+  const b = (raw.content && typeof raw.content === "object" ? raw.content : raw) as Record<string, unknown>;
+  // Success is signalled by `ok === true` alone. tot20 DROPPED the unsigned
+  // `roles`/`capability` fields (contract §6, C2/R1) — the signed `id_token` is
+  // now the SOLE authority, and the storefront derives identity/membership from
+  // its verified claims (see auth/verify.ts), never from these echoes. So do NOT
+  // gate success on `roles` being present. `roles`/`capability` remain optional
+  // (populated only if a legacy/mock response still carries them).
+  if (b.ok === true) {
+    // TRANSITIONAL: accept `assertion` as well as `id_token` — some tot builds
+    // emitted the pre-rename field name. Contract §6 fixes it as `id_token`.
+    const idToken = typeof b.id_token === "string" ? b.id_token : typeof b.assertion === "string" ? b.assertion : undefined;
+    const result: AccessCodeVerifyResult = {
+      ok: true,
+      email: typeof b.email === "string" ? b.email.toLowerCase() : email.toLowerCase(),
+      resource: typeof b.resource === "string" ? b.resource : resource,
+      roles: Array.isArray(b.roles) ? b.roles.filter((r): r is string => typeof r === "string") : [],
+      capability: typeof b.capability === "string" ? b.capability : "none",
+    };
+    // Only attach when present so consumers can distinguish "signer degraded"
+    // from "no field", and so existing exact-shape tests stay green.
+    if (idToken) result.id_token = idToken;
+    return result;
+  }
+  const reason = b.reason;
+  const known: VerifyFailureReason[] = ["invalid", "expired", "too_many_attempts", "error"];
+  return {
+    ok: false,
+    reason: known.includes(reason as VerifyFailureReason) ? (reason as VerifyFailureReason) : "invalid",
+  };
+}
+
+// --- Mock (tests + local dev before tot20 lands) ----------------------------
+
+export interface MockRosterEntry {
+  roles: string[];
+  /** Single effective capability; derived if omitted. */
+  capability?: string;
+}
+
+/**
+ * In-memory TotAccessClient. Seeded with a per-(resource,email) roster and a
+ * fixed code, it drives route + gate tests deterministically and lets local dev
+ * exercise the flow before the tot20 endpoints exist.
+ */
+export class MockTotAccessClient implements TotAccessClient {
+  /** key = `${resource}${emailLower}` → roster entry. */
+  private roster = new Map<string, MockRosterEntry>();
+  sent: Array<{ email: string; resource: string }> = [];
+
+  constructor(
+    private readonly code = "123456",
+    seed: Array<{ email: string; resource: string; roles: string[]; capability?: string }> = [],
+    /**
+     * Optional signer: when set, `verifyAccessCode` also emits an `id_token` so
+     * the mock mirrors tot's Phase-3 signed assertion (contract §6). Left unset
+     * by default, keeping the flat-only shape existing tests assert on. Wire a
+     * real ES256 signer in dev/integration to exercise offline verify end-to-end.
+     */
+    private readonly signIdToken?: (input: {
+      email: string;
+      resource: string;
+      roles: string[];
+      capability: string;
+    }) => Promise<string>,
+  ) {
+    for (const s of seed) this.grant(s.email, s.resource, s.roles, s.capability);
+  }
+
+  grant(email: string, resource: string, roles: string[], capability?: string) {
+    this.roster.set(this.key(resource, email), { roles, capability });
+  }
+
+  private key(resource: string, email: string) {
+    return `${resource}${email.toLowerCase()}`;
+  }
+
+  async sendAccessCode(email: string, resource: string): Promise<AccessCodeSendResult> {
+    this.sent.push({ email: email.toLowerCase(), resource });
+    return { ok: true }; // neutral regardless of eligibility
+  }
+
+  async verifyAccessCode(
+    email: string,
+    resource: string,
+    code: string,
+  ): Promise<AccessCodeVerifyResult> {
+    if (code !== this.code) return { ok: false, reason: "invalid" };
+    const entry = this.roster.get(this.key(resource, email));
+    if (!entry) return { ok: false, reason: "invalid" }; // not eligible → indistinguishable
+    const capability = entry.capability ?? effectiveCapability(entry.roles);
+    const result: AccessCodeVerifyResult = {
+      ok: true,
+      email: email.toLowerCase(),
+      resource,
+      roles: entry.roles,
+      capability,
+    };
+    if (this.signIdToken) {
+      result.id_token = await this.signIdToken({
+        email: email.toLowerCase(),
+        resource,
+        roles: entry.roles,
+        capability,
+      });
+    }
+    return result;
+  }
+
+  async sendFederatedCode(email: string): Promise<AccessCodeSendResult> {
+    this.sent.push({ email: email.toLowerCase(), resource: "*" }); // federated: no single resource
+    return { ok: true };
+  }
+
+  async verifyFederatedCode(
+    email: string,
+    code: string,
+  ): Promise<FederatedVerifyResult> {
+    if (code !== this.code) return { ok: false, reason: "invalid" };
+    // Eligible if the email holds a role on ANY seeded resource. Roster keys are
+    // `${resource}<sep>${emailLower}`; match on the email suffix (an email's `@`
+    // never appears in an appDomain resource, so this can't false-match).
+    const lower = email.toLowerCase();
+    const hasAny = [...this.roster.keys()].some((k) => k.endsWith(lower));
+    if (!hasAny) return { ok: false, reason: "invalid" };
+    // The multi-tenant id_token is minted by tot in production; the mock returns
+    // the shape without a token unless a signer is wired (tests inject one).
+    return { ok: true, email: lower, audience: "storefront" };
+  }
+
+  async exchangeSignInToken(token: string): Promise<FederatedVerifyResult> {
+    // Accept the mock tokens minted by MockDeveloperInviteClient ("mock|<tenant>|<email>").
+    try {
+      const [tag, , email] = Buffer.from(token, "base64url").toString("utf8").split("|");
+      if (tag === "mock" && email) {
+        return { ok: true, email: email.toLowerCase(), audience: "storefront" };
+      }
+    } catch {
+      /* fall through to invalid */
+    }
+    return { ok: false, reason: "invalid" };
+  }
+}
+
+/** Collapse a role array to one effective capability (mirrors tot20's precedence). */
+export function effectiveCapability(roles: readonly string[]): string {
+  const has = (r: string) => roles.includes(r);
+  if (has("apikey:owner") || has("appOwner")) return "owner";
+  if (has("appAdmin")) return "admin";
+  if (has("developer")) return "developer";
+  if (has("inviter")) return "inviter";
+  if (has("administrator") || has("super-admin") || has("support")) return "staff";
+  return roles[0] ?? "none";
+}
+
+// --- Factory ----------------------------------------------------------------
+
+/**
+ * Build the env-configured client:
+ *   - `TOT_CORE_URL`   — tot20 core API base.
+ *   - `TOT_API_KEY` (+ optional `TOT_SECRET_KEY`) — storefront's own credentials.
+ * Throws {@link TotAccessClientError} when unconfigured (routes map that to 503).
+ */
+export async function createTotAccessClient(
+  overrides: Partial<HttpTotAccessClientConfig> = {},
+): Promise<HttpTotAccessClient> {
+  const baseUrl = overrides.baseUrl ?? (await readEnv("TOT_CORE_URL")) ?? "";
+  const apiKey = overrides.apiKey ?? (await readEnv("TOT_API_KEY")) ?? "";
+  const secretKey = overrides.secretKey ?? (await readEnv("TOT_SECRET_KEY"));
+  return new HttpTotAccessClient({ ...overrides, baseUrl, apiKey, secretKey });
+}

package/apps/storefront/src/lib/basePath.ts

@@ -0,0 +1,41 @@
+/**
+ * Tenant base-path helpers.
+ *
+ * When a request selects its tenant via a `/<domain>/` path prefix (see
+ * lib/tenantRouting.ts), every same-origin link must carry that prefix or the
+ * visitor falls out of the tenant. Host-routed requests have an empty base path
+ * and links are returned unchanged.
+ *
+ * `withBase` is the single source of truth for that rule and is used both
+ *   - server-side, from `Astro.locals.basePath`, in .astro components, and
+ *   - client-side, from `clientBasePath()` (the <html data-base-path> attr set
+ *     in Layout.astro), in hydrated islands.
+ *
+ * It is idempotent and conservative: only root-absolute single-slash paths are
+ * prefixed. Protocol-relative URLs ("//cdn…"), absolute URLs ("https://…"),
+ * fragments/queries ("#x", "?x"), and already-prefixed paths pass through. This
+ * mirrors the defense-in-depth client script in Layout.astro.
+ */
+export function withBase(basePath: string, href: string): string {
+  if (!basePath || !href) return href;
+  // Only same-origin root-absolute paths; skip protocol-relative "//".
+  if (href.charAt(0) !== "/" || href.charAt(1) === "/") return href;
+  // Already inside the prefix.
+  if (href === basePath || href.startsWith(`${basePath}/`)) return href;
+  return `${basePath}${href}`;
+}
+
+/**
+ * The active tenant base path as seen from the browser, read from the
+ * `<html data-base-path>` attribute Layout.astro emits. Returns "" on the
+ * server, for host-routed tenants, or before hydration.
+ */
+export function clientBasePath(): string {
+  if (typeof document === "undefined") return "";
+  return document.documentElement.dataset.basePath ?? "";
+}
+
+/** Convenience for hydrated islands: prefix `href` with the client base path. */
+export function withClientBase(href: string): string {
+  return withBase(clientBasePath(), href);
+}

package/apps/storefront/src/lib/cfImage.ts

@@ -0,0 +1,55 @@
+/**
+ * Cloudflare Image Resizing URL helpers (Epic Phase-2 D2).
+ *
+ * Rehosted product images live in the PRODUCT_IMAGES R2 bucket, which does NOT
+ * transform on a `?width=` query the way Shopify's CDN does. Cloudflare Image
+ * Resizing — the `/cdn-cgi/image/<options>/<source>` path, run at the zone edge —
+ * resizes AND reformats (`format=auto` → AVIF/WebP where supported) any same-zone
+ * or allowlisted source.
+ *
+ * We emit ROOT-RELATIVE `/cdn-cgi/image/...` URLs so they resolve against
+ * whichever zone is serving the page (and an extracted/self-hosted tenant's zone
+ * too — no hardcoded host). Referenced (non-rehosted) Shopify CDN URLs keep their
+ * native `?width=` scheme in Img.astro, since Shopify already resizes those — no
+ * need to route them back through our resizer.
+ */
+export interface CfImageOpts {
+  width: number;
+  height?: number;
+  fit?: "cover" | "contain" | "scale-down" | "crop" | "pad";
+  format?: "auto" | "avif" | "webp";
+  quality?: number;
+}
+
+/** The responsive widths we generate, in CSS px. */
+export const CF_IMAGE_WIDTHS = [320, 480, 640, 960, 1280, 1600] as const;
+
+/** Build a single `/cdn-cgi/image/...` URL for a source image. */
+export function cfImageUrl(src: string, opts: CfImageOpts): string {
+  const options = [
+    `width=${Math.round(opts.width)}`,
+    opts.height ? `height=${Math.round(opts.height)}` : null,
+    `fit=${opts.fit ?? "cover"}`,
+    `format=${opts.format ?? "auto"}`,
+    `quality=${opts.quality ?? 82}`,
+  ]
+    .filter(Boolean)
+    .join(",");
+  // Cloudflare accepts both absolute source URLs and same-zone paths verbatim
+  // after the options segment.
+  return `/cdn-cgi/image/${options}/${src}`;
+}
+
+/**
+ * Build a `srcset` of resized variants up to ~2x the display width, so the
+ * browser picks the right density. `displayWidth` is the intrinsic/layout width.
+ */
+export function cfImageSrcset(
+  src: string,
+  displayWidth: number,
+  opts: Omit<CfImageOpts, "width"> = {},
+): string {
+  const widths = CF_IMAGE_WIDTHS.filter((w) => w <= displayWidth * 2);
+  const list = widths.length ? widths : [displayWidth];
+  return list.map((w) => `${cfImageUrl(src, { ...opts, width: w })} ${w}w`).join(", ");
+}

package/apps/storefront/src/lib/chrome/model.ts

@@ -0,0 +1,65 @@
+/**
+ * Chrome model — typed props for the reusable, tenant-agnostic site-chrome
+ * components (AnnouncementBar, UtilityNav, SiteHeader, NavDropdown/MegaMenu,
+ * SiteFooter). Chrome is a STANDARD component set skinned by theme tokens, never
+ * hand-built per tenant page. A tenant's chrome is data (`chrome.json`) that
+ * populates these shapes; the wrapping mechanism (see lib/rawChrome.ts) surrounds
+ * body-only page fragments with the rendered chrome.
+ */
+
+/** A navigation/footer link. `external` opens off-site; `badge` shows e.g. "NEW". */
+export interface ChromeLink {
+  label: string;
+  href: string;
+  external?: boolean;
+  badge?: string;
+}
+
+/** One column of a mega-menu panel. */
+export interface MegaColumn {
+  title?: string;
+  links: ChromeLink[];
+}
+
+/**
+ * A primary-nav item. A plain link (no children/columns), a single-column
+ * dropdown (`children`), or a multi-column mega-menu (`columns`). `badge` marks
+ * it (e.g. "NEW"); `flag` gives it the emphasized/highlighted treatment.
+ */
+export interface ChromeNavItem {
+  label: string;
+  href: string;
+  badge?: string;
+  flag?: boolean;
+  children?: ChromeLink[];
+  columns?: MegaColumn[];
+}
+
+export interface SocialLink {
+  label: string;
+  href: string;
+  /** Optional inline-SVG path data (single <path d="…">) — no external images. */
+  iconPath?: string;
+}
+
+export interface ChromeLogo {
+  src: string;
+  alt: string;
+  width?: number;
+  height?: number;
+}
+
+export interface FooterColumn {
+  title: string;
+  links: ChromeLink[];
+}
+
+export interface FooterNewsletter {
+  title?: string;
+  body?: string;
+  /** Form action (defaults to /api/newsletter). */
+  action?: string;
+  placeholder?: string;
+  /** Hidden `source` field value (e.g. "footer"). */
+  source?: string;
+}