@thorprovider/storefront 0.3.1 → 0.4.0-mvp.0

package/assets/templates/app/lib/__STOREFRONT__/schema.ts

@@ -0,0 +1,121 @@
+// Generated by Thor Commerce storefront (template: assets/templates/app/lib/__STOREFRONT__/schema.ts)
+// Zod contracts for the shell-level base components. Single source shared by
+// the server-side catalog (catalog.ts) and the client-side registry
+// (registry.tsx) — json-render does not validate props against the catalog at
+// render time, so the registry parses here.
+
+import { z } from 'zod'
+
+export const ctaSchema = z.object({
+  label: z.string(),
+  href: z.string().optional(),
+})
+
+export const navLinkSchema = z.object({
+  label: z.string(),
+  href: z.string().optional(),
+})
+
+const footerLinkSchema = z.object({
+  label: z.string(),
+  href: z.string().optional(),
+})
+
+const footerLinkColumnSchema = z.object({
+  title: z.string(),
+  links: z.array(footerLinkSchema),
+})
+
+// Declared locally so the scaffold's zod version is the only one in play.
+// Cross-major schema assignment (@thorprovider/blocks ships zod v3) breaks the
+// defineCatalog contract, so the block contract is mirrored here instead.
+export const shellProductSchema = z.object({
+  id: z.union([z.string(), z.number()]),
+  title: z.string(),
+  price: z.number(),
+  originalPrice: z.number().optional(),
+  // Required: the ProductCard1 block contract demands `image: string`, and the
+  // runtime's card projection always fills it (PRODUCT_IMAGE_FALLBACK).
+  image: z.string(),
+  badge: z.string().optional(),
+})
+
+export const navbarPropsSchema = z.object({
+  navLinks: z.array(navLinkSchema),
+  logoText: z.string(),
+  logoHref: z.string().optional(),
+  currentPath: z.string().optional(),
+  signIn: ctaSchema.optional(),
+  cta: ctaSchema.optional(),
+  cartCount: z.number().optional(),
+})
+
+// Mirrors the StorefrontNavbar block contract in this scaffold. `storeCategories`
+// is bound to /navCategories and `items` is derived from /cart in the registry,
+// so only the static chrome is declared here.
+export const navCategorySchema = z.object({
+  label: z.string(),
+  href: z.string(),
+  children: z.array(z.object({ label: z.string(), href: z.string() })).optional(),
+  emphasis: z.boolean().optional(),
+})
+
+// Optional brand seam mirroring the Navbar4 / FooterSection1 accent props and
+// the StorefrontHero1 editorial image. Declared locally (see shellProductSchema)
+// so the scaffold's zod version is the only one in play.
+export const shellAccentSchema = z.object({
+  text: z.string(),
+  className: z.string().optional(),
+})
+
+export const storefrontNavbarPropsSchema = z.object({
+  storeCategories: z.array(navCategorySchema),
+  shippingNote: z.string(),
+  utilityLinks: z.array(z.object({ label: z.string(), href: z.string() })),
+  logoText: z.string(),
+  logoHref: z.string().optional(),
+  logoAccent: shellAccentSchema.optional(),
+  className: z.string().optional(),
+  accountHref: z.string().optional(),
+  // Held global search (E2 task 5.4): the generated shell opts out of the
+  // navbar search control while no verified global search contract exists.
+  showSearch: z.boolean().optional(),
+})
+
+// Mirrors ShoppingCart4 (block) minus the runtime-bound `items`; the registry
+// fills items from /cart. promotions carry icon NAMES resolved via icon-map.
+export const cartPromotionSchema = z.object({
+  threshold: z.number(),
+  reward: z.string(),
+  icon: z.string(),
+})
+
+export const cartDrawerPropsSchema = z.object({
+  promotions: z.array(cartPromotionSchema),
+  taxRate: z.number().optional(),
+})
+
+export const bannerPropsSchema = z.object({
+  badge: z.string().optional(),
+  message: z.string(),
+  href: z.string(),
+  linkLabel: z.string(),
+  avatars: z.array(z.string()).optional(),
+})
+
+export const productCardPropsSchema = z.object({
+  products: z.array(shellProductSchema),
+  heading: z.string().optional(),
+  maxItems: z.number().optional(),
+})
+
+export const footerPropsSchema = z.object({
+  brandName: z.string(),
+  brandAccent: shellAccentSchema.optional(),
+  brandDescription: z.string().optional(),
+  linkColumns: z.array(footerLinkColumnSchema),
+  className: z.string().optional(),
+  newsletter: z
+    .object({ placeholder: z.string().optional(), buttonLabel: z.string().optional() })
+    .optional(),
+})

package/assets/templates/app/lib/__STOREFRONT__/session.core.ts

@@ -0,0 +1,470 @@
+// Generated by Thor Commerce storefront (composition core: session).
+//
+// Host session core — pure signing and validation for the storefront session
+// cookie. No Next.js, no React, no I/O: this module turns a validated session
+// payload into a signed, tamper-evident cookie value and back, so it is unit
+// testable in isolation. The Next host (`./session`) owns the actual cookie.
+//
+// Shapes are owned once by `@thorprovider/types`; their validation is owned by
+// `@thorprovider/runtime/contracts`. This file adds no commerce logic and calls
+// no backend and no external SDK.
+//
+// Early guest receipt gate (change B, task 2.1) — recorded here because change
+// B edits no backend source:
+//   - The host issues this signed, httpOnly, store-scoped capability cookie. The
+//     signing secret is host-only (`THOR_SESSION_SECRET`), independent of the
+//     backend, and is never embedded, generated as a constant, or printed.
+//   - Receipt recovery reads `receiptCartId` from THIS verified cookie only. A
+//     bare client-supplied order id or cart id never authorizes a receipt.
+//   - Recovery (integration, not part of this foundation) MUST GET the backend
+//     cart and require `cart.completed_at`, then issue a single-shot native
+//     complete to reconcile and return the SAME persisted order.
+//   - Owned backend follow-up (debt, not fixed by change B): the native public
+//     order/cart lookup that reconcile needs is not yet verified; the runtime
+//     commerce provider (adapters/runtime only, no direct SDK call) must expose
+//     it before the UI promises recovery.
+
+import { createHash, createHmac, randomUUID, timingSafeEqual } from 'node:crypto'
+import type { StoreContext } from '@thorprovider/types'
+import { storeContextSchema } from '@thorprovider/runtime/contracts'
+
+/** Cookie value format version; bump on any incompatible payload change. */
+export const SESSION_PAYLOAD_VERSION = 1
+
+/** Default session lifetime: 30 days, mirrored by the cookie `maxAge`. */
+export const SESSION_TTL_SECONDS = 60 * 60 * 24 * 30
+
+/** Cookie-name prefix; the full name is store-scoped via `sessionCookieName`. */
+export const SESSION_COOKIE_PREFIX = 'thor_session_'
+
+/** Domain separator so a session HMAC can never be replayed as another token. */
+const SIGNING_DOMAIN = 'thor-session.v1'
+
+/** A short secret is a weak HMAC key; fail loud instead of silently weakening. */
+const MIN_SECRET_LENGTH = 16
+
+export type SessionStatus = 'active' | 'completed'
+
+/**
+ * The signed capability carried by the session cookie.
+ *
+ * `cartId` is the active backend guest cart; `receiptCartId` is the completed
+ * cart kept for receipt recovery after the active cart is cleared. Both are
+ * backend ids the host persists — the client never supplies either one to
+ * authorize a receipt.
+ */
+export interface HostSessionPayload {
+  version: typeof SESSION_PAYLOAD_VERSION
+  /** Validated single-store context; binds the cookie to store/channel/region. */
+  context: StoreContext
+  /** Opaque guest shopper identity (a UUID issued by the host). */
+  shopperId: string
+  /** Active backend cart id, or null when no cart is active. */
+  cartId: string | null
+  /** Completed backend cart id kept for recovery, or null. */
+  receiptCartId: string | null
+  /** `active` while shopping; `completed` after a confirmed order. */
+  status: SessionStatus
+  /** Issued-at epoch seconds. */
+  issuedAt: number
+  /** Expiry epoch seconds; enforced in addition to the cookie `maxAge`. */
+  expiresAt: number
+}
+
+export interface CreateSessionOptions {
+  /** Injectable clock (epoch seconds) for deterministic tests. */
+  now?: number
+  /** Override the default lifetime. */
+  ttlSeconds?: number
+  /** Reuse an identity instead of issuing a fresh UUID. */
+  shopperId?: string
+}
+
+export interface DecodeSessionOptions {
+  /** Injectable clock (epoch seconds) for deterministic tests. */
+  now?: number
+  /** Reject a cookie whose store/channel/region/currency does not match. */
+  expectedContext?: StoreContext
+}
+
+function assertSecret(secret: string): void {
+  if (typeof secret !== 'string' || secret.length < MIN_SECRET_LENGTH) {
+    throw new Error(
+      `session signing secret must be a string of at least ${MIN_SECRET_LENGTH} characters`,
+    )
+  }
+}
+
+function sign(body: string, secret: string): string {
+  return createHmac('sha256', secret)
+    .update(`${SIGNING_DOMAIN}.${body}`)
+    .digest('base64url')
+}
+
+function nowSeconds(): number {
+  return Math.floor(Date.now() / 1000)
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0
+}
+
+function isNullableString(value: unknown): value is string | null {
+  return value === null || isNonEmptyString(value)
+}
+
+function isFiniteInteger(value: unknown): value is number {
+  return typeof value === 'number' && Number.isInteger(value) && Number.isFinite(value)
+}
+
+/**
+ * Store-scoped, cookie-name-safe session cookie name.
+ *
+ * Two stores on the same host therefore get distinct cookie names, and an
+ * unexpected store id cannot collide with another store's cookie.
+ *
+ * Sanitization can make distinct ids collide (`a.b` and `a_b` both map to
+ * `a_b`); because the cookie is one per app, a collision would let one store
+ * overwrite another's session. When sanitization changed the id, a short digest
+ * of the original id is appended so distinct stores always get distinct names.
+ */
+export function sessionCookieName(storeId: string): string {
+  const safe = storeId.replace(/[^A-Za-z0-9_-]/g, '_')
+  if (safe.length === 0) {
+    throw new Error('sessionCookieName: storeId must contain a cookie-safe character')
+  }
+  if (safe === storeId) return `${SESSION_COOKIE_PREFIX}${safe}`
+  const digest = createHash('sha256').update(storeId).digest('base64url').slice(0, 10)
+  return `${SESSION_COOKIE_PREFIX}${safe}_${digest}`
+}
+
+/** Issue a fresh opaque guest identity. Two calls never collide. */
+export function newShopperId(): string {
+  return randomUUID()
+}
+
+/**
+ * Build a new active session for a store context.
+ *
+ * The context is validated before the cookie is ever issued, so a cookie is
+ * only created for a valid store/channel/region/currency.
+ */
+export function createHostSession(
+  context: StoreContext,
+  options: CreateSessionOptions = {},
+): HostSessionPayload {
+  const validated = storeContextSchema.parse(context)
+  const issuedAt = options.now ?? nowSeconds()
+  const ttlSeconds = options.ttlSeconds ?? SESSION_TTL_SECONDS
+  return {
+    version: SESSION_PAYLOAD_VERSION,
+    context: validated,
+    shopperId: options.shopperId ?? newShopperId(),
+    cartId: null,
+    receiptCartId: null,
+    status: 'active',
+    issuedAt,
+    expiresAt: issuedAt + ttlSeconds,
+  }
+}
+
+/** Sign a session payload into a `<body>.<signature>` cookie value. */
+export function encodeHostSession(payload: HostSessionPayload, secret: string): string {
+  assertSecret(secret)
+  const body = Buffer.from(JSON.stringify(payload), 'utf8').toString('base64url')
+  return `${body}.${sign(body, secret)}`
+}
+
+/**
+ * Verify and decode a session cookie value.
+ *
+ * Returns null for a missing, malformed, tampered, expired, or wrong-store
+ * cookie — the caller then clears/regenerates rather than trusting client ids.
+ * The signature is compared in constant time.
+ */
+export function decodeHostSession(
+  raw: string | undefined | null,
+  secret: string,
+  options: DecodeSessionOptions = {},
+): HostSessionPayload | null {
+  assertSecret(secret)
+  if (typeof raw !== 'string' || raw.length === 0) return null
+
+  const parts = raw.split('.')
+  if (parts.length !== 2) return null
+  const [body, provided] = parts
+  if (body.length === 0 || provided.length === 0) return null
+
+  const expected = sign(body, secret)
+  const providedBuf = Buffer.from(provided, 'base64url')
+  const expectedBuf = Buffer.from(expected, 'base64url')
+  if (providedBuf.length !== expectedBuf.length) return null
+  if (!timingSafeEqual(providedBuf, expectedBuf)) return null
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(Buffer.from(body, 'base64url').toString('utf8'))
+  } catch {
+    return null
+  }
+
+  const payload = parseSessionPayload(parsed)
+  if (!payload) return null
+
+  const now = options.now ?? nowSeconds()
+  if (payload.expiresAt <= now) return null
+  if (options.expectedContext && !sessionMatchesContext(payload, options.expectedContext)) {
+    return null
+  }
+  return payload
+}
+
+/**
+ * Validate a decoded payload against the contract.
+ *
+ * The store context is re-validated with the shared runtime schema; a completed
+ * session must carry a receipt cart so recovery has an authorized handle.
+ */
+function parseSessionPayload(input: unknown): HostSessionPayload | null {
+  if (typeof input !== 'object' || input === null) return null
+  const candidate = input as Record<string, unknown>
+  if (candidate.version !== SESSION_PAYLOAD_VERSION) return null
+
+  const context = storeContextSchema.safeParse(candidate.context)
+  if (!context.success) return null
+
+  if (!isNonEmptyString(candidate.shopperId)) return null
+  if (!isNullableString(candidate.cartId)) return null
+  if (!isNullableString(candidate.receiptCartId)) return null
+  if (candidate.status !== 'active' && candidate.status !== 'completed') return null
+  if (candidate.status === 'completed' && !isNonEmptyString(candidate.receiptCartId)) return null
+  if (!isFiniteInteger(candidate.issuedAt) || !isFiniteInteger(candidate.expiresAt)) return null
+
+  return {
+    version: SESSION_PAYLOAD_VERSION,
+    context: context.data,
+    shopperId: candidate.shopperId,
+    cartId: candidate.cartId,
+    receiptCartId: candidate.receiptCartId,
+    status: candidate.status,
+    issuedAt: candidate.issuedAt,
+    expiresAt: candidate.expiresAt,
+  }
+}
+
+/** True when the payload is bound to exactly this store/channel/region/currency. */
+export function sessionMatchesContext(
+  payload: HostSessionPayload,
+  context: StoreContext,
+): boolean {
+  return (
+    payload.context.storeId === context.storeId &&
+    payload.context.salesChannelId === context.salesChannelId &&
+    payload.context.regionId === context.regionId &&
+    payload.context.currencyCode === context.currencyCode
+  )
+}
+
+/** Attach the active backend cart id to the session. */
+export function bindSessionCart(
+  payload: HostSessionPayload,
+  cartId: string,
+): HostSessionPayload {
+  if (!isNonEmptyString(cartId)) throw new Error('bindSessionCart: cartId is required')
+  return { ...payload, cartId, status: 'active' }
+}
+
+/**
+ * Record a confirmed order for `receiptCartId`.
+ *
+ * The active cart is cleared ONLY when it is the cart that was completed. If
+ * the session has a DIFFERENT active cart (a new purchase started after an
+ * earlier order), that cart is preserved and the session stays `active` while
+ * the completed receipt is retained for recovery. When there is no active cart,
+ * the session becomes `completed`.
+ *
+ * Call this ONLY on a confirmed order — on any error the active cart must be
+ * retained and no receipt recorded, so never call it in an error path.
+ */
+export function completeSessionCart(
+  payload: HostSessionPayload,
+  receiptCartId: string,
+): HostSessionPayload {
+  if (!isNonEmptyString(receiptCartId)) {
+    throw new Error('completeSessionCart: receiptCartId is required')
+  }
+  const hasActiveCart = isNonEmptyString(payload.cartId)
+  const isSameCart = hasActiveCart && payload.cartId === receiptCartId
+  return {
+    ...payload,
+    cartId: isSameCart ? null : payload.cartId,
+    receiptCartId,
+    status: isSameCart || !hasActiveCart ? 'completed' : 'active',
+  }
+}
+
+/**
+ * True when the verified session carries a completed cart safe to recover.
+ *
+ * Recovery is keyed on the presence of `receiptCartId`, not on the `status`
+ * field: a shopper who starts a NEW cart after a completed order keeps the
+ * prior receipt cart id on the same cookie (status returns to `active`), so the
+ * proof cookie is never lost while the new cart is active.
+ */
+export function canRecoverReceipt(
+  payload: HostSessionPayload | null,
+): payload is HostSessionPayload & { receiptCartId: string } {
+  return payload !== null && isNonEmptyString(payload.receiptCartId)
+}
+
+// ---------------------------------------------------------------------------
+// Customer auth codec (change: storefront-customer-auth, task 2.1)
+// ---------------------------------------------------------------------------
+//
+// The auth cookie is a DEDICATED, store-scoped, httpOnly, HMAC-signed cookie
+// that carries the customer JWT for the duration of a request. It is separate
+// from the guest session cookie so the accepted guest payload/version is never
+// touched (see design D1). This module stays pure: no Next.js, no React, no I/O,
+// and no commerce logic. The Next host (`./session`) owns the actual cookie.
+
+/** Cookie value format version; bump on any incompatible auth payload change. */
+export const AUTH_PAYLOAD_VERSION = 1
+
+/** Default auth token lifetime: 30 days, mirrored by the cookie `maxAge`. */
+export const AUTH_TOKEN_TTL_SECONDS = 60 * 60 * 24 * 30
+
+/** Cookie-name prefix; the full name is store-scoped via `authCookieName`. */
+export const AUTH_COOKIE_PREFIX = 'thor_auth_'
+
+/** Domain separator so an auth HMAC can never be replayed as another token. */
+export const AUTH_SIGNING_DOMAIN = 'thor-auth.v1'
+
+/**
+ * The signed capability carried by the auth cookie.
+ *
+ * `token` is the customer JWT the backend issued; it lives only in this
+ * httpOnly cookie and in server-side request scope and is never sent to the
+ * client. The cookie is bound to `storeId` so a session issued for one store
+ * cannot authenticate another.
+ */
+export interface HostAuthPayload {
+  version: number
+  storeId: string
+  token: string
+  /** Issued-at epoch seconds. */
+  issuedAt: number
+  /** Expiry epoch seconds; enforced in addition to the cookie `maxAge`. */
+  expiresAt: number
+}
+
+export interface CreateHostAuthOptions {
+  /** Injectable clock (epoch seconds) for deterministic tests. */
+  now?: number
+  /** Override the default lifetime. */
+  ttlSeconds?: number
+}
+
+export interface DecodeHostAuthOptions {
+  /** Injectable clock (epoch seconds) for deterministic tests. */
+  now?: number
+  /** Reject a cookie issued for a different store. */
+  expectedStoreId?: string
+}
+
+/** Store-scoped auth cookie name. Distinct from the guest session cookie. */
+export function authCookieName(storeId: string): string {
+  return `${AUTH_COOKIE_PREFIX}${storeId}`
+}
+
+function signAuth(body: string, secret: string): string {
+  return createHmac('sha256', secret)
+    .update(`${AUTH_SIGNING_DOMAIN}.${body}`)
+    .digest('base64url')
+}
+
+/** Build a new auth payload for a store and customer token. */
+export function createHostAuth(
+  storeId: string,
+  token: string,
+  options: CreateHostAuthOptions = {},
+): HostAuthPayload {
+  if (!isNonEmptyString(storeId)) throw new Error('createHostAuth: storeId is required')
+  if (!isNonEmptyString(token)) throw new Error('createHostAuth: token is required')
+  const issuedAt = options.now ?? nowSeconds()
+  const ttlSeconds = options.ttlSeconds ?? AUTH_TOKEN_TTL_SECONDS
+  return {
+    version: AUTH_PAYLOAD_VERSION,
+    storeId,
+    token,
+    issuedAt,
+    expiresAt: issuedAt + ttlSeconds,
+  }
+}
+
+/** Sign an auth payload into a `<body>.<signature>` cookie value. */
+export function encodeHostAuth(payload: HostAuthPayload, secret: string): string {
+  assertSecret(secret)
+  const body = Buffer.from(JSON.stringify(payload), 'utf8').toString('base64url')
+  return `${body}.${signAuth(body, secret)}`
+}
+
+/**
+ * Verify and decode an auth cookie value.
+ *
+ * Returns null for a missing, malformed, tampered, expired, or wrong-store
+ * cookie. The signature is compared in constant time.
+ */
+export function decodeHostAuth(
+  raw: string | undefined | null,
+  secret: string,
+  options: DecodeHostAuthOptions = {},
+): HostAuthPayload | null {
+  assertSecret(secret)
+  if (typeof raw !== 'string' || raw.length === 0) return null
+
+  const parts = raw.split('.')
+  if (parts.length !== 2) return null
+  const [body, provided] = parts
+  if (body.length === 0 || provided.length === 0) return null
+
+  const expected = signAuth(body, secret)
+  const providedBuf = Buffer.from(provided, 'base64url')
+  const expectedBuf = Buffer.from(expected, 'base64url')
+  if (providedBuf.length !== expectedBuf.length) return null
+  if (!timingSafeEqual(providedBuf, expectedBuf)) return null
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(Buffer.from(body, 'base64url').toString('utf8'))
+  } catch {
+    return null
+  }
+
+  const payload = parseAuthPayload(parsed)
+  if (!payload) return null
+
+  const now = options.now ?? nowSeconds()
+  if (payload.expiresAt <= now) return null
+  if (options.expectedStoreId !== undefined && payload.storeId !== options.expectedStoreId) {
+    return null
+  }
+  return payload
+}
+
+/** Validate a decoded auth payload against the contract. */
+function parseAuthPayload(input: unknown): HostAuthPayload | null {
+  if (typeof input !== 'object' || input === null) return null
+  const candidate = input as Record<string, unknown>
+  if (candidate.version !== AUTH_PAYLOAD_VERSION) return null
+  if (!isNonEmptyString(candidate.storeId)) return null
+  if (!isNonEmptyString(candidate.token)) return null
+  if (!isFiniteInteger(candidate.issuedAt) || !isFiniteInteger(candidate.expiresAt)) return null
+
+  return {
+    version: AUTH_PAYLOAD_VERSION,
+    storeId: candidate.storeId,
+    token: candidate.token,
+    issuedAt: candidate.issuedAt,
+    expiresAt: candidate.expiresAt,
+  }
+}