@certrev/cert-block 1.0.3 → 1.1.1

package/dist/verify/get-verified-delivery.js

@@ -0,0 +1,157 @@
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ * getVerifiedDelivery — the envelope PLUS the brand's render def, from the Delivery API
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * 1.1.0. The Delivery API answers a Builder placement with the signed artifact and, beside it,
+ * the brand's resolved render-def projection as a top-level `renderDef` sibling (the same shape a
+ * Shopify store carries in its `render_def` metafield). The envelope's signature covers `payload`
+ * only, so the sibling rides the response without touching the signed bytes, and a tombstone
+ * carries none. `getVerifiedEnvelope` keeps discarding it; this reads it.
+ *
+ * The same fetch, deadline, kernel and fail-closed rules as `getVerifiedEnvelope` (every sourcing
+ * failure reports the reason it actually is; nothing throws into the render path). Two things are
+ * different, and both are the point:
+ *
+ *  1. WHAT IS CACHED is the cryptographically verified PAYLOAD, not the verdict. The lifecycle
+ *     policy (revoked, expired) and the subject match are re-run by `renderVerdict` on EVERY call,
+ *     with the caller's clock. So a payload that was valid when fetched and expires while cached
+ *     stops rendering at its `expiresAt`, not at the next refetch; and a refetch after the TTL
+ *     picks up a tombstone (revocation) or a changed def with no write on the brand's side.
+ *  2. The CACHE KEY is the Delivery URL plus the rendering placement, so a staging and a
+ *     production origin never share an entry, and neither do two placements.
+ *
+ * `peekVerifiedDelivery` is the synchronous read of the same cache: a React component suspends on
+ * `getVerifiedDelivery` once, then reads the settled value without a second promise (which is what
+ * keeps a streaming SSR render from suspending forever on a fresh promise every retry).
+ */
+import { renderVerdict, verifyArtifact } from '../contract/kernel.js';
+import { TtlCache } from './cache.js';
+import { DEFAULT_FETCH_TIMEOUT_MS, fetchWithDeadline } from './fetch-with-deadline.js';
+/** Shared per-process cache: 60s for a verified read, 5s for a suppressed one. */
+const sharedDeliveryCache = new TtlCache({ ttlMs: 60_000, negativeTtlMs: 5_000 });
+function suppressed(reason) {
+    return { kind: 'suppressed', reason };
+}
+export function deliveryUrl(baseUrl, platform, externalId) {
+    const base = baseUrl.replace(/\/+$/, '');
+    return `${base}/api/cert/v1/delivery/${encodeURIComponent(platform)}/${encodeURIComponent(externalId)}`;
+}
+/** Cache key: the URL (origin included) × the placement rendering it. No clock: the TTL bounds time. */
+export function deliveryCacheKey(opts) {
+    return `delivery:${deliveryUrl(opts.baseUrl, opts.platform, opts.externalId)}|${encodeURIComponent(opts.context.platform)}:${encodeURIComponent(opts.context.externalId)}`;
+}
+const isString = (v) => typeof v === 'string';
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/**
+ * The def sibling, shape-checked. Anything that is not the metafield shape is null, which paints
+ * the preset default (the same thing an absent def paints): a def is presentation, never a claim,
+ * so a malformed one degrades the styling and nothing else. The TOKEN VALUES are not judged here;
+ * `resolveBlockTheme` re-validates each at paint time and drops what is not a safe value.
+ */
+export function parseRenderDef(value) {
+    if (!isRecord(value))
+        return null;
+    const { v, preset, rung, tokens, hidden, barInkFg, layout, customFace } = value;
+    if (typeof v !== 'number' || !Number.isFinite(v))
+        return null;
+    if (!isString(preset) || !isString(rung) || !isRecord(tokens))
+        return null;
+    if (!Array.isArray(hidden) || !hidden.every(isString))
+        return null;
+    if (layout !== undefined && !isString(layout))
+        return null;
+    let face;
+    if (customFace !== undefined) {
+        if (!isRecord(customFace) || !Array.isArray(customFace.placedFields) || !customFace.placedFields.every(isString)) {
+            return null;
+        }
+        face = { placedFields: [...customFace.placedFields] };
+    }
+    const tokenOut = {};
+    for (const key of ['accentColor', 'surface', 'cornerRadius', 'fontSlot', 'barInk', 'inkColor']) {
+        if (isString(tokens[key]))
+            tokenOut[key] = tokens[key];
+    }
+    return {
+        v,
+        preset,
+        rung,
+        tokens: tokenOut,
+        ...(barInkFg === '#141414' || barInkFg === '#ffffff' ? { barInkFg } : {}),
+        hidden: [...hidden],
+        ...(layout !== undefined ? { layout } : {}),
+        ...(face ? { customFace: face } : {}),
+    };
+}
+/** Fetch, parse and cryptographically verify one Delivery response. Never throws. */
+async function loadDelivery(opts) {
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    let res;
+    try {
+        res = await fetchWithDeadline(fetchImpl, deliveryUrl(opts.baseUrl, opts.platform, opts.externalId), { headers: { accept: 'application/json' } }, opts.timeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS);
+    }
+    catch {
+        // Unreachable, DNS/TLS, or the deadline. Same least-wrong member as getVerifiedEnvelope.
+        return suppressed('unsupported_contract_version');
+    }
+    // Nothing served for this placement: never certified, or withdrawn. A LIVE revocation is a 200
+    // tombstone, so a 4xx here genuinely means "no credential for this subject".
+    if (res.status === 404 || res.status === 410)
+        return suppressed('subject_mismatch');
+    if (!res.ok)
+        return suppressed('unsupported_contract_version');
+    let body;
+    try {
+        body = await res.json();
+    }
+    catch {
+        return suppressed('unsupported_contract_version');
+    }
+    if (!isRecord(body))
+        return suppressed('unsupported_contract_version');
+    let verdict;
+    try {
+        // `verifyArtifact`, so a tombstone verifies as itself and reports 'revoked'. The kernel reads
+        // `payload` + `signature` (or the tombstone's own fields); the `renderDef` sibling is not
+        // part of what is verified, and is never read unless the artifact verified.
+        verdict = await verifyArtifact(body, opts.resolveKid, { ...opts.context });
+    }
+    catch {
+        return suppressed('unknown_key');
+    }
+    if (verdict.decision !== 'render')
+        return suppressed(verdict.reason);
+    return { kind: 'verified', payload: verdict.payload, renderDef: parseRenderDef(body.renderDef) };
+}
+/** Apply the render-time policy to a cached read: lifecycle + subject at THIS render's clock. */
+export function settleDelivery(cached, context) {
+    if (cached.kind === 'suppressed')
+        return { verdict: { decision: 'suppress', reason: cached.reason }, renderDef: null };
+    const verdict = renderVerdict(cached.payload, context);
+    return { verdict, renderDef: verdict.decision === 'render' ? cached.renderDef : null };
+}
+/**
+ * Fetch (if needed), verify, cache, and settle one Delivery read for one placement. FAIL-CLOSED:
+ * the verdict is `render` only when the artifact verified against `resolveKid` AND, at
+ * `context.now`, the payload is unrevoked, unexpired and for this placement.
+ */
+export async function getVerifiedDelivery(opts) {
+    const cache = opts.cache ?? sharedDeliveryCache;
+    const cached = await cache.getOrLoad(deliveryCacheKey(opts), () => loadDelivery(opts), (v) => v.kind === 'suppressed', opts.ttlMs);
+    return settleDelivery(cached, opts.context);
+}
+/**
+ * The synchronous read: the settled answer when a fresh read is cached, else `undefined` (the
+ * caller then awaits `getVerifiedDelivery`). Never fetches.
+ */
+export function peekVerifiedDelivery(opts) {
+    const cached = (opts.cache ?? sharedDeliveryCache).peek(deliveryCacheKey(opts));
+    return cached === undefined ? undefined : settleDelivery(cached, opts.context);
+}
+/** Drop every cached read for one placement (e.g. from a revocation webhook). */
+export function invalidateDelivery(opts, cache = sharedDeliveryCache) {
+    cache.delete(deliveryCacheKey(opts));
+}
+export { sharedDeliveryCache };
+//# sourceMappingURL=get-verified-delivery.js.map

package/dist/verify/get-verified-delivery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-verified-delivery.js","sourceRoot":"","sources":["../../src/verify/get-verified-delivery.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@certrev/cert-block",
-	"version": "1.0.3",
+	"version": "1.1.1",
 	"description": "Headless render edge for the CertREV CertDeliveryEnvelope: SSR-safe React cert components, a framework-agnostic <certrev-badge> Web Component, a schema.org JSON-LD projector, and a fail-closed verify layer over the shared VerdictKernel.",
 	"repository": {
 		"type": "git",
@@ -23,6 +23,10 @@
 			"types": "./dist/builder/index.d.ts",
 			"default": "./dist/builder/index.js"
 		},
+		"./builder/face": {
+			"types": "./dist/builder/envelope-face.d.ts",
+			"default": "./dist/builder/envelope-face.js"
+		},
 		"./webcomponent": {
 			"types": "./dist/webcomponent/certrev-badge.d.ts",
 			"default": "./dist/webcomponent/certrev-badge.js"

package/src/builder/cert-chrome-data.ts

@@ -60,6 +60,25 @@ export interface CertChromeRenderDef {
 	readonly customFace?: { readonly placedFields: readonly string[] }
 }
 
+/**
+ * The DELIVERY MARKER (1.1.0): the exporter's statement that this block's cert is served,
+ * signed, by the CertREV Delivery API at `baseUrl`. When it is present the card no longer
+ * paints the other option keys: it takes its `externalId` from its own Builder entry id,
+ * fetches `GET {baseUrl}/api/cert/v1/delivery/builder/{externalId}`, verifies the envelope
+ * against the baked issuer key, and paints from the verified facts plus the brand's render
+ * def served beside them. A revoked, expired or unverifiable cert renders nothing.
+ *
+ * `baseUrl` is honoured ONLY when it is `https:` on `certrev.com` or a subdomain of it. The
+ * marker is an option like any other, so an editor can type into it; a foreign origin would
+ * let a page answer its own revocation check, and so renders nothing (never the options).
+ */
+export interface CertDeliveryMarker {
+	/** Marker shape version. Only `1` is understood; anything else renders nothing. */
+	readonly v: 1
+	/** The CertREV app origin that serves the Delivery API (e.g. `https://portal.certrev.com`). */
+	readonly baseUrl: string
+}
+
 /**
  * The OPTIONS a brand's native cert component receives. Delivered per certified
  * article; until the brand registers the component the block renders nothing.
@@ -131,6 +150,13 @@ export interface BuilderCertChromeData {
 	renderDef: CertChromeRenderDef | null
 	/** Version of the delivered string set (`data-certrev-strings-version` for the crawl monitor). */
 	stringsVersion: string
+	/**
+	 * 1.1.0: where the signed envelope for this block is served, or null for an options-only
+	 * block. Present ⇒ the card paints from the verified envelope + def and ignores the keys
+	 * above; they stay on the wire so installs older than 1.1.0 keep painting during the
+	 * transition. See `CertDeliveryMarker`.
+	 */
+	delivery: CertDeliveryMarker | null
 }
 
 /**
@@ -160,6 +186,7 @@ export const BUILDER_CERT_CHROME_KEYS = [
 	'display',
 	'renderDef',
 	'stringsVersion',
+	'delivery',
 ] as const
 
 export type BuilderCertChromeKey = (typeof BUILDER_CERT_CHROME_KEYS)[number]

package/src/builder/cert-review-card.tsx

@@ -18,10 +18,16 @@
  *  - honors `display.showCredentials`.
  */
 
+import * as React from 'react'
+import { Suspense } from 'react'
+import { memoToggleFor, toggleMemo } from '../components/memo-toggle.js'
 import { type CertBlockMode, renderCertBlock } from '../components/render-cert-block.js'
-import type { ResolvedBlockTheme } from '../components/render-def.js'
+import { CERT_STRINGS_VERSION, type ResolvedBlockTheme } from '../components/render-def.js'
+import { getVerifiedDelivery, peekVerifiedDelivery, type VerifiedDelivery } from '../verify/get-verified-delivery.js'
 import type { BuilderCertChromeData } from './cert-chrome-data.js'
 import { BUILDER_CERT_CHROME_KEYS } from './cert-chrome-data.js'
+import { cardDeliveryRuntime } from './delivery-runtime.js'
+import { envelopeCardInput } from './envelope-face.js'
 
 /**
  * The canonical Builder block name. A brand's registration + the portal
@@ -49,6 +55,13 @@ export interface CertReviewCardProps extends Partial<BuilderCertChromeData> {
 	 * string-splitting shim is gone — `renderCertBlock` composes each part directly.
 	 */
 	part?: 'full' | 'header' | 'memo' | null
+	/**
+	 * 1.1.0: what `@builder.io/sdk-react` passes because the registration sets
+	 * `shouldReceiveBuilderProps: { builderContext: true }`. Only `content.id` is read: it is the
+	 * Builder entry this block renders inside, which IS the Delivery placement's `externalId`, so a
+	 * block copied onto another entry asks for that entry's cert and never shows this one's.
+	 */
+	builderContext?: { readonly content?: { readonly id?: unknown } | null } | null
 }
 
 /**
@@ -87,7 +100,121 @@ function fusedCredential(pair: BuilderCertChromeData['credentialVerification'] |
 	return credential && verifiedAt ? { credential, verifiedAt } : null
 }
 
+/**
+ * The delivery marker, accepted only as `{ v: 1, baseUrl }` with `baseUrl` an `https:` ORIGIN on
+ * `certrev.com` or one of its subdomains (no path, query, credentials or port). Anything else is
+ * null, and a block carrying a marker that is not accepted renders NOTHING: falling back to the
+ * options would let an edit to the marker switch revocation off.
+ */
+export function acceptedDeliveryMarker(value: unknown): { readonly baseUrl: string } | null {
+	if (typeof value !== 'object' || value === null || Array.isArray(value)) return null
+	const { v, baseUrl } = value as { v?: unknown; baseUrl?: unknown }
+	if (v !== 1 || typeof baseUrl !== 'string') return null
+	let url: URL
+	try {
+		url = new URL(baseUrl)
+	} catch {
+		return null
+	}
+	if (url.protocol !== 'https:' || url.username || url.password || url.port) return null
+	if (url.pathname !== '/' || url.search || url.hash) return null
+	const host = url.hostname.toLowerCase()
+	if (host !== 'certrev.com' && !host.endsWith('.certrev.com')) return null
+	return { baseUrl: url.origin }
+}
+
+/**
+ * Suspend on a Delivery read. React 19 gets `use` with ONE promise per placement while it is in
+ * flight; React 18 (no `use`) gets the promise thrown, the Suspense protocol it supports. Either
+ * way the retry finds the settled read in the cache through `peekVerifiedDelivery`, so it never
+ * suspends on a second promise.
+ */
+const inflightReads = new Map<string, Promise<VerifiedDelivery>>()
+function suspendOn(key: string, start: () => Promise<VerifiedDelivery>): VerifiedDelivery {
+	let pending = inflightReads.get(key)
+	if (!pending) {
+		pending = start().finally(() => inflightReads.delete(key))
+		inflightReads.set(key, pending)
+	}
+	const use = (React as unknown as { use?: <T>(p: Promise<T>) => T }).use
+	if (typeof use === 'function') return use(pending)
+	throw pending
+}
+
+/**
+ * The painted envelope face, with the phone memo toggle bound. One native click listener on the
+ * wrapper (delegated, so it survives a re-render of the HTML) flips the memo box the button sits
+ * in; the button is native, so Enter and Space reach it as clicks. Bound after hydration only: the
+ * server HTML is the collapsed face, which is also what a reader without JS keeps (the whole memo
+ * is still in the text for a screen reader, and the desktop never clamps it).
+ */
+function EnvelopeFace(props: { readonly html: string; readonly defVersion: number | undefined }) {
+	const ref = React.useRef<HTMLDivElement>(null)
+	React.useEffect(() => {
+		const el = ref.current
+		if (!el) return
+		const onClick = (e: MouseEvent) => {
+			const button = memoToggleFor(e.target)
+			if (button && el.contains(button)) toggleMemo(button)
+		}
+		el.addEventListener('click', onClick)
+		return () => el.removeEventListener('click', onClick)
+	}, [])
+	return (
+		<div
+			ref={ref}
+			data-certrev-cert-chrome=""
+			// Marks a face painted from the verified envelope (the migration dry-run and crawl monitor
+			// tell the two faces apart by it). The strings are the package's locked constants here.
+			data-certrev-delivery=""
+			data-certrev-strings-version={CERT_STRINGS_VERSION}
+			data-certrev-def-version={props.defVersion}
+			// biome-ignore lint/security/noDangerouslySetInnerHtml: renderCertBlock is the escaping-safe SSR string renderer
+			dangerouslySetInnerHTML={{ __html: props.html }}
+		/>
+	)
+}
+
+function EnvelopeCertReviewCard(props: {
+	readonly baseUrl: string
+	readonly externalId: string
+	readonly mode: unknown
+	readonly part: unknown
+}) {
+	const rt = cardDeliveryRuntime()
+	// The clock is read per render, so the lifecycle is judged NOW, not when the envelope was fetched.
+	const context = { platform: 'builder', externalId: props.externalId, now: new Date(rt.now()) }
+	const read = { baseUrl: props.baseUrl, platform: 'builder', externalId: props.externalId, context, cache: rt.cache }
+	const settled =
+		peekVerifiedDelivery(read) ??
+		suspendOn(`${props.baseUrl}|${props.externalId}`, () =>
+			getVerifiedDelivery({ ...read, resolveKid: rt.resolveKid, fetchImpl: rt.fetchImpl(), timeoutMs: rt.timeoutMs }),
+		)
+	// Revoked, expired, unverifiable, for another entry, or unreachable: nothing at all.
+	if (settled.verdict.decision !== 'render') return null
+	const input = envelopeCardInput(settled.verdict.payload.content, settled.renderDef, {
+		mode: props.mode,
+		part: props.part,
+	})
+	if (!input) return null
+	return <EnvelopeFace html={renderCertBlock(input)} defVersion={settled.renderDef ? settled.renderDef.v : undefined} />
+}
+
 export function CertReviewCard(props: CertReviewCardProps) {
+	// 1.1.0: a block that carries the delivery marker paints from the signed envelope and the
+	// brand's def, never from the options beside it. No marker (every entry exported before 1.1.0)
+	// takes the options path below, unchanged from 1.0.3.
+	if (props.delivery != null) {
+		const marker = acceptedDeliveryMarker(props.delivery)
+		const entryId = text(props.builderContext?.content?.id)
+		if (!marker || !entryId) return null
+		return (
+			<Suspense fallback={null}>
+				<EnvelopeCertReviewCard baseUrl={marker.baseUrl} externalId={entryId} mode={props.mode} part={props.part} />
+			</Suspense>
+		)
+	}
+
 	const reviewerName = text(props.reviewerName)
 	const verifyUrl = text(props.verifyUrl)
 	if (!reviewerName || !verifyUrl) return null // no chrome pre-cert (or an unreadable delivery)
@@ -119,7 +246,7 @@ export function CertReviewCard(props: CertReviewCardProps) {
 		// explicit `mode` and never reaches this line.
 		//
 		// The problem is the entries that already exist. `mode` is a PLACEMENT input, not one of
-		// the 19 wire keys (`BUILDER_CERT_CHROME_KEYS`), and the exporter emits only the wire
+		// the 20 wire keys (`BUILDER_CERT_CHROME_KEYS`), and the exporter emits only the wire
 		// projection (`options: { ...certData }`), so every entry exported to date has NO `mode`
 		// key at all. Through 0.5.5 this line read `?? 'banner'` and those entries rendered the
 		// banner face. Removing it in 1.0.0 did not give them the renderer's default in the
@@ -224,6 +351,7 @@ const WIRE_INPUT_TYPE: Record<(typeof BUILDER_CERT_CHROME_KEYS)[number], Builder
 	display: 'object',
 	renderDef: 'object',
 	stringsVersion: 'string',
+	delivery: 'object',
 }
 
 /**
@@ -241,10 +369,12 @@ const WIRE_INPUT_HELPER_TEXT: Partial<Record<(typeof BUILDER_CERT_CHROME_KEYS)[n
 		'System-populated by CertREV. Only its PRESENCE is read (absent = a pro-bono reviewer, so no cue renders); the cue itself is a locked constant, so editing this text changes nothing on the page, and clearing it does not remove the disclosure.',
 	scopeLine:
 		'System-populated by CertREV. The FTC scope line renders byte-verbatim from a locked constant: editing this text changes nothing on the page.',
+	delivery:
+		'System-populated by CertREV. When set, the card shows the certificate CertREV serves for this entry, verified, and ignores the other fields; if CertREV revokes it or it expires, the card shows nothing. Do not edit.',
 }
 
 /**
- * The wire-type inputs — DERIVED from `BUILDER_CERT_CHROME_KEYS`, so the 19-field
+ * The wire-type inputs — DERIVED from `BUILDER_CERT_CHROME_KEYS`, so the 20-field
  * option set can never drift from the type (the W3 lock asserts name-parity). This
  * kills the demo's hand-maintained 17-entry array.
  */
@@ -299,6 +429,8 @@ export interface CertBlockBuilderRegistration {
 	readonly name: string
 	readonly component: typeof CertReviewCard
 	readonly inputs: readonly BuilderInput[]
+	/** 1.1.0: asks the SDK for `builderContext`, whose `content.id` the delivery path reads. */
+	readonly shouldReceiveBuilderProps: { readonly builderContext: true }
 }
 
 /**
@@ -313,6 +445,7 @@ export const BUILDER_REGISTRATION: CertBlockBuilderRegistration = {
 	name: CERT_COMPONENT_NAME,
 	component: CertReviewCard,
 	inputs: [...PLACEMENT_INPUTS, ...WIRE_INPUTS],
+	shouldReceiveBuilderProps: { builderContext: true },
 }
 
 /**
@@ -326,6 +459,12 @@ export interface CertReviewCardRegisteredComponent {
 	name: string
 	description?: string
 	inputs: BuilderInput[]
+	/**
+	 * 1.1.0: `@builder.io/sdk-react`'s `RegisteredComponent.shouldReceiveBuilderProps`. The SDK then
+	 * passes the `builderContext` prop, and the delivery path takes its placement from
+	 * `builderContext.content.id`.
+	 */
+	shouldReceiveBuilderProps: { builderContext: boolean }
 }
 
 /**
@@ -340,4 +479,5 @@ export const certRevCertComponent: CertReviewCardRegisteredComponent = {
 	description:
 		'CertREV expert-review cert card. Options are populated by the CertREV exporter; editors choose placement (mode/part) only.',
 	inputs: [...PLACEMENT_INPUTS, ...WIRE_INPUTS],
+	shouldReceiveBuilderProps: { builderContext: true },
 }

package/src/builder/delivery-runtime.ts

@@ -0,0 +1,54 @@
+/**
+ * The Builder card's Delivery runtime (1.1.0): the trust root, fetch, cache and clock the
+ * envelope-backed `CertReviewCard` reads with.
+ *
+ * INTERNAL. This module is deliberately NOT on the package `exports` map, so a consumer cannot
+ * swap the trust root through the published API: the card verifies against the baked
+ * `cert-issuer-1` key, the same key the storefront badge bundle ships. The package's own tests
+ * reach the setter by relative import to run the real kernel against fixture-signed envelopes.
+ */
+
+import type { ResolvePublicKeyByKid } from '../contract/kernel.js'
+import { TtlCache } from '../verify/cache.js'
+import type { CachedDelivery } from '../verify/get-verified-delivery.js'
+import { CERT_ISSUER_KID, CERT_ISSUER_PUBLIC_KEY_PEM } from './issuer-key.js'
+
+export interface CardDeliveryRuntime {
+	readonly resolveKid: ResolvePublicKeyByKid
+	readonly fetchImpl: () => typeof fetch
+	readonly cache: TtlCache<CachedDelivery>
+	readonly now: () => number
+	readonly timeoutMs?: number
+}
+
+const bakedResolveKid: ResolvePublicKeyByKid = (kid) =>
+	kid === CERT_ISSUER_KID ? { format: 'pem', pem: CERT_ISSUER_PUBLIC_KEY_PEM } : null
+
+function defaultRuntime(): CardDeliveryRuntime {
+	return {
+		resolveKid: bakedResolveKid,
+		fetchImpl: () => globalThis.fetch,
+		cache: new TtlCache<CachedDelivery>({ ttlMs: 60_000, negativeTtlMs: 5_000 }),
+		now: Date.now,
+	}
+}
+
+let runtime: CardDeliveryRuntime = defaultRuntime()
+
+export function cardDeliveryRuntime(): CardDeliveryRuntime {
+	return runtime
+}
+
+/** Test seam: replace parts of the runtime (a fresh cache unless one is given). Returns a restore. */
+export function setCardDeliveryRuntimeForTests(overrides: Partial<CardDeliveryRuntime>): () => void {
+	const previous = runtime
+	const now = overrides.now ?? previous.now
+	runtime = {
+		...previous,
+		cache: new TtlCache<CachedDelivery>({ ttlMs: 60_000, negativeTtlMs: 5_000, now }),
+		...overrides,
+	}
+	return () => {
+		runtime = previous
+	}
+}