@certrev/cert-block 1.2.0-canary.7 → 1.2.0

package/src/builder/ssr-seed.ts

@@ -0,0 +1,343 @@
+/**
+ * The server render's envelope seed (1.2.0): what lets a hydrated delivery card paint with NO browser read.
+ *
+ * Through 1.1.1 the browser re-read the Delivery API for every card it hydrated, because nothing handed the server's
+ * read to it. A storefront whose Content-Security-Policy `connect-src` does not name the CertREV origin (e.l.f.'s
+ * Hydrogen store is one) blocked that read, the read settled as a suppress, and the card the server had painted
+ * vanished. So the painted face now carries the envelope it was painted from, as one attribute on its wrapper:
+ * `data-certrev-envelope` = `{ v: 1, baseUrl, externalId, design?, payload, signature?, renderDef }`. `payload` is the
+ * signed envelope's payload as the Delivery API served it, less the fields the def hides (below); `renderDef` is the
+ * def the face was painted with; `design` is the design pin the read was made with (the canary replica's `?design=N`),
+ * present only on a pinned read. React escapes the attribute like any other, so no `<script>` and no CSP `script-src`
+ * are involved.
+ *
+ * HIDDEN FIELDS ARE ABSENT FROM THE PAGE, NOT JUST FROM THE FACE. A def's `hidden` set (`reviewerPhoto`, `memo`) is the
+ * brand's statement that the page does not show those fields; a seed that carried them would put the reviewer's photo
+ * URL or the memo text in the page source all the same. So `withoutHiddenContent` removes them from the payload
+ * BEFORE the card paints and before it serializes, and both the server's face and the browser's are painted from the
+ * stripped payload (so they are identical, and a hidden memo is not on the page in either place):
+ *  - `reviewerPhoto` hides `content.expert.photoUrl` and the author's `content.author.photoUrl` (the reader face paints
+ *    the author's photo under the same switch);
+ *  - `memo` hides `content.memo`.
+ * `display.showExpertPhoto: false` is the payload's own switch for the same photos and is stripped the same way (the
+ * portal never writes the URL for it either): both photo URLs go, as for `reviewerPhoto`, whatever the def hides.
+ * `content.expert.compensationCue` is NEVER touched: the cue is a locked disclosure no def can hide, and the face
+ * paints "Compensated expert" from it in the banner, the memo and the sidebar (the floating pill's own markup has
+ * no disclosure line, as in the portal's snippets; its modal paints the cue from the same field).
+ *
+ * THE SIGNATURE IS LEFT OUT WHENEVER ANYTHING WAS STRIPPED. The signature signs the full payload, so a payload with a
+ * field removed no longer verifies against it, and a seed that carried both would hand a verifier a pair that fails.
+ * Leaving it out costs nothing: the browser never re-checks a seed's signature (next paragraph), it re-runs only
+ * `renderVerdict` (lifecycle and subject) at its own clock, and neither reads a field the strip removes. A seed whose
+ * payload was not stripped keeps the signature, so a verifier can still check the page's HTML against the issuer key.
+ *
+ * The browser trusts a seed as far as it trusts the server HTML the seed sits in: whoever can write that HTML can
+ * already write any card they like, so the signature is NOT re-verified here (which would make hydration async, and
+ * Ed25519 in WebCrypto is not in every browser). The client still re-runs the lifecycle and subject policy
+ * (`renderVerdict`) at its own clock once hydration is done; `cert-review-card.tsx` does that.
+ *
+ * A PINNED CARD TAKES ONLY A SEED WITH THE SAME PIN (and an unpinned card only an unpinned one): the pin is part of
+ * the seed's key, as it is part of the read's, so the canary replica's `?design=7` card never paints the design the
+ * page carried for another version.
+ *
+ * WHEN THE SERVER HAD NO ENVELOPE TO PAINT (1.2.0) the same attribute carries a fallback record instead of a seed:
+ * `{ v: 1, baseUrl, externalId, design?, face }`, where `face` is `'options'` (CertREV could not be reached, so the
+ * server painted the block's own options face) or `'none'` (the server painted nothing: revoked, expired, unverifiable,
+ * for another entry). A browser that renders the card again (hydration, or React's client re-render after a hydration
+ * error elsewhere on the page) paints what the record says, so it neither reads the Delivery API nor shows a card the
+ * server withheld. A record holds no payload, so `parseSeed` never takes one for a seed. A `'none'` record sits on a
+ * `hidden` element with nothing in it.
+ *
+ * React-free and browser-only in effect: with no `document` (a server) `pageSeedFor` finds nothing, so a server never
+ * reads or keeps a seed and a multi-tenant render process holds nothing per page.
+ */
+
+import { HIDEABLE_FIELDS } from '../components/render-def.js'
+import type { CertContent, CertPayload, CertSignature } from '../contract/kernel.js'
+import { type DesignPin, parseDesignPin, parseRenderDef } from '../verify/get-verified-delivery.js'
+import type { CertChromeRenderDef } from './cert-chrome-data.js'
+
+export const SEED_ATTRIBUTE = 'data-certrev-envelope'
+
+export interface DeliverySeed {
+	readonly baseUrl: string
+	readonly externalId: string
+	/** The design pin the read was made with; absent on an unpinned read (every production brand). */
+	readonly design?: DesignPin
+	/** The payload as painted: with every field the def hides removed (`withoutHiddenContent`). */
+	readonly payload: CertPayload
+	/**
+	 * The envelope's signature as served; absent when the payload was stripped (it no longer verifies), and when a
+	 * cache was filled by hand (a test, a custom cache).
+	 */
+	readonly signature?: CertSignature
+	readonly renderDef: CertChromeRenderDef | null
+}
+
+/** A seed as read from the page: the parsed seed and the attribute's exact text (re-rendered verbatim on hydration). */
+export interface PageSeed {
+	readonly seed: DeliverySeed
+	readonly raw: string
+}
+
+/** What the server painted with no verified envelope: the block's options face, or nothing. */
+export type FallbackFace = 'options' | 'none'
+
+/** The record a server writes where it had no envelope to paint (the file header). */
+export interface DeliveryFallback {
+	readonly baseUrl: string
+	readonly externalId: string
+	readonly design?: DesignPin
+	readonly face: FallbackFace
+}
+
+/** A fallback record as read from the page, with the attribute's exact text. */
+export interface PageFallback {
+	readonly fallback: DeliveryFallback
+	readonly raw: string
+}
+
+/** Whatever the server wrote for one placement: a seed or a fallback record. */
+export type PageRecord = PageSeed | PageFallback
+
+const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v)
+
+/** A value worth hiding: anything but nothing (absent, null, the empty string). */
+const hasValue = (v: unknown): boolean => v !== undefined && v !== null && v !== ''
+
+/**
+ * The payload with the named people's photo URLs removed (`null`); the same object when neither had one. The card uses
+ * it for a photo the browser could not load (a brand's CSP `img-src`, a 404), so the face repaints with the initials.
+ */
+export function withoutPhotos(payload: CertPayload, people: readonly ('expert' | 'author')[]): CertPayload {
+	let content: Record<string, unknown> = { ...payload.content }
+	let stripped = false
+	for (const person of people) {
+		const fields = content[person]
+		if (isRecord(fields) && hasValue(fields.photoUrl)) {
+			content = { ...content, [person]: { ...fields, photoUrl: null } }
+			stripped = true
+		}
+	}
+	return stripped ? { ...payload, content: content as unknown as CertContent } : payload
+}
+
+/**
+ * The payload with every content field the def's `hidden` set controls removed, and whether anything was; the two
+ * photo URLs go as well when the payload's own `display.showExpertPhoto` is `false` (exactly `false`, as the reader
+ * face reads it: absent or `null` shows the photo).
+ *
+ * Only the ids in `HIDEABLE_FIELDS` count (a def may list others; the faces ignore them, so they hide nothing). A
+ * removed text field becomes `null`, so the content keeps the shape the contract types give it and every face reads it
+ * as absent. Nothing but those fields changes: the subject and lifecycle (what `renderVerdict` reads), the cue, the
+ * dates, the links and the names are the payload's own. Never throws on a hostile shape: a payload whose `expert` or
+ * `author` is not an object has no photo to strip.
+ */
+export function withoutHiddenContent(
+	payload: CertPayload,
+	renderDef: CertChromeRenderDef | null,
+): { readonly payload: CertPayload; readonly stripped: boolean } {
+	const hidden = (renderDef?.hidden ?? []).filter((id) => (HIDEABLE_FIELDS as readonly string[]).includes(id))
+	const display: unknown = (payload.content as unknown as Record<string, unknown> | undefined)?.display
+	const photoOff = isRecord(display) && display.showExpertPhoto === false
+	if (hidden.length === 0 && !photoOff) return { payload, stripped: false }
+	let next = photoOff || hidden.includes('reviewerPhoto') ? withoutPhotos(payload, ['expert', 'author']) : payload
+	if (hidden.includes('memo') && hasValue(next.content.memo)) {
+		next = { ...next, content: { ...next.content, memo: null } as unknown as CertContent }
+	}
+	return { payload: next, stripped: next !== payload }
+}
+
+/**
+ * The seed for a verified read: the payload stripped of what the def hides, and the signature only when nothing was
+ * stripped. The card paints from this seed's payload, on the server and in the browser alike.
+ */
+export function seedFor(read: {
+	readonly baseUrl: string
+	readonly externalId: string
+	readonly design?: DesignPin
+	readonly payload: CertPayload
+	readonly signature?: CertSignature
+	readonly renderDef: CertChromeRenderDef | null
+}): DeliverySeed {
+	const { payload, stripped } = withoutHiddenContent(read.payload, read.renderDef)
+	return {
+		baseUrl: read.baseUrl,
+		externalId: read.externalId,
+		...(read.design ? { design: read.design } : {}),
+		payload,
+		...(read.signature && !stripped ? { signature: read.signature } : {}),
+		renderDef: read.renderDef,
+	}
+}
+
+const serializedPin = (design: DesignPin | undefined) =>
+	design ? { design: { version: design.version, ...(design.brand === undefined ? {} : { brand: design.brand }) } } : {}
+
+export function serializeSeed(seed: DeliverySeed): string {
+	return JSON.stringify({
+		v: 1,
+		baseUrl: seed.baseUrl,
+		externalId: seed.externalId,
+		...serializedPin(seed.design),
+		payload: seed.payload,
+		...(seed.signature ? { signature: seed.signature } : {}),
+		renderDef: seed.renderDef,
+	})
+}
+
+export function serializeFallback(fallback: DeliveryFallback): string {
+	return JSON.stringify({
+		v: 1,
+		baseUrl: fallback.baseUrl,
+		externalId: fallback.externalId,
+		...serializedPin(fallback.design),
+		face: fallback.face,
+	})
+}
+
+/** A pin a record names, judged by the same grammar the card's own pin is: undefined when absent, null when bad. */
+function parsedPin(design: unknown): DesignPin | undefined | null {
+	if (design === undefined) return undefined
+	const judged = isRecord(design)
+		? parseDesignPin({ design: design.version, ...(design.brand === undefined ? {} : { designBrand: design.brand }) })
+		: 'invalid'
+	return judged === 'invalid' || judged === undefined ? null : judged
+}
+
+/** The seed in one attribute value, or null for anything that is not one (never throws). */
+export function parseSeed(raw: string): DeliverySeed | null {
+	let value: unknown
+	try {
+		value = JSON.parse(raw)
+	} catch {
+		return null
+	}
+	if (!isRecord(value) || value.v !== 1) return null
+	const { baseUrl, externalId, design, payload, signature, renderDef } = value
+	if (typeof baseUrl !== 'string' || typeof externalId !== 'string') return null
+	if (!isRecord(payload) || !isRecord(payload.subject) || !isRecord(payload.lifecycle) || !isRecord(payload.content)) {
+		return null
+	}
+	// A pin the seed names is judged by the same grammar the card's own pin is; one that fails it is not a seed.
+	const pin = parsedPin(design)
+	if (pin === null) return null
+	return {
+		baseUrl,
+		externalId,
+		...(pin ? { design: pin } : {}),
+		payload: payload as unknown as CertPayload,
+		...(isRecord(signature) ? { signature: signature as unknown as CertSignature } : {}),
+		renderDef: parseRenderDef(renderDef),
+	}
+}
+
+/** A fallback record in one attribute value, or null for anything that is not one (a seed included; never throws). */
+export function parseFallback(raw: string): DeliveryFallback | null {
+	let value: unknown
+	try {
+		value = JSON.parse(raw)
+	} catch {
+		return null
+	}
+	if (!isRecord(value) || value.v !== 1 || 'payload' in value) return null
+	const { baseUrl, externalId, design, face } = value
+	if (typeof baseUrl !== 'string' || typeof externalId !== 'string') return null
+	if (face !== 'options' && face !== 'none') return null
+	const pin = parsedPin(design)
+	if (pin === null) return null
+	return { baseUrl, externalId, ...(pin ? { design: pin } : {}), face }
+}
+
+/** One placement's key: the origin, the entry and the pin (the read's own key, so a pin never shares a seed). */
+function seedKey(baseUrl: string, externalId: string, design: DesignPin | undefined): string {
+	return design ? `${baseUrl}|${externalId}|design=${design.version}|${design.brand ?? ''}` : `${baseUrl}|${externalId}`
+}
+
+/**
+ * The seeds (and fallback records) this page's server HTML carried, by placement, for the page's lifetime: a card
+ * mounted later by a client-side render (an in-app navigation back to a server-rendered article, or React's client
+ * re-render after a hydration error) paints what the server painted, as the hydrated card it replaces would have.
+ */
+const pageSeeds = new Map<string, PageRecord>()
+
+const recordKey = (record: PageRecord): string => {
+	const r = 'seed' in record ? record.seed : record.fallback
+	return seedKey(r.baseUrl, r.externalId, r.design)
+}
+
+/** Every seed and fallback record the live document carries, in document order. */
+function scanDocument(): PageRecord[] {
+	const found: PageRecord[] = []
+	for (const el of Array.from(document.querySelectorAll(`[${SEED_ATTRIBUTE}]`))) {
+		const raw = el.getAttribute(SEED_ATTRIBUTE)
+		if (!raw) continue
+		const seed = parseSeed(raw)
+		const fallback = seed ? null : parseFallback(raw)
+		if (seed) found.push({ seed, raw })
+		else if (fallback) found.push({ fallback, raw })
+	}
+	return found
+}
+
+/**
+ * The record the server wrote for this placement and pin: its seed, or its fallback record. By default: from the map,
+ * else from one scan of the document (which also records every other one on the page). With `live`, the map is not
+ * consulted: the document is scanned and decides, so what a hydrating card learns is what the server HTML in front of
+ * it carries, not what an earlier page in this process left behind. `undefined` when the page carries none, and always
+ * on a server.
+ */
+export function pageRecordFor(
+	baseUrl: string,
+	externalId: string,
+	design?: DesignPin,
+	options: { readonly live?: boolean } = {},
+): PageRecord | undefined {
+	const key = seedKey(baseUrl, externalId, design)
+	if (typeof document === 'undefined') return undefined
+	const known = options.live ? undefined : pageSeeds.get(key)
+	if (known) return known
+	let inDocument = false
+	for (const found of scanDocument()) {
+		const k = recordKey(found)
+		if (k === key) inDocument = true
+		if (options.live || !pageSeeds.has(k)) pageSeeds.set(k, found)
+	}
+	// A live read answers for the document alone: a record an earlier page left in the map is not one this page carries.
+	return options.live && !inDocument ? undefined : pageSeeds.get(key)
+}
+
+/** `pageRecordFor`, seeds only: the seed the server painted for this placement and pin. */
+export function pageSeedFor(
+	baseUrl: string,
+	externalId: string,
+	design?: DesignPin,
+	options: { readonly live?: boolean } = {},
+): PageSeed | undefined {
+	const record = pageRecordFor(baseUrl, externalId, design, options)
+	return record && 'seed' in record ? record : undefined
+}
+
+/** A Suspense boundary's comment marker as React's server render writes it: `$` (done), `$?` (pending), `$!`, `$~`. */
+const BOUNDARY_MARKER = /^\$[?!~]?$/
+
+/**
+ * Whether the live document holds server-rendered React HTML: any Suspense boundary marker. The delivery card sits in
+ * a `<Suspense>` of its own, so a server render of one always leaves a marker, a card the server painted nothing for
+ * (revoked, expired, unreachable) included, and a client render never does. This is how a card that is hydrating tells
+ * a browser hydrating server HTML (the document holds it) from a server render that merely runs where a `document`
+ * exists (a test's jsdom, a shim): there the document does not hold the HTML being produced.
+ */
+export function pageHoldsServerHtml(): boolean {
+	if (typeof document === 'undefined' || !document.documentElement) return false
+	const walker = document.createTreeWalker(document.documentElement, 128 /* NodeFilter.SHOW_COMMENT */)
+	for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+		if (BOUNDARY_MARKER.test((node as Comment).data)) return true
+	}
+	return false
+}
+
+/** Test seam: forget every seed (a new page). */
+export function forgetPageSeedsForTests(): void {
+	pageSeeds.clear()
+}

package/src/verify/cache.ts

@@ -11,6 +11,13 @@
  *      ONE fetch, not N.
  *   3. Negative-caches failures briefly so a hard-down origin doesn't get hammered, while
  *      still recovering quickly (short negative TTL).
+ *   4. (1.2.0, opt-in through `staleMs`) STALE-WHILE-REVALIDATE and STALE-IF-ERROR: a positive
+ *      entry past its TTL but inside the stale window is served at once while ONE background
+ *      refresh replaces it; a refresh that only failed to reach the origin (`isTransient`)
+ *      keeps the stale entry instead of overwriting it. So an origin that is slow or briefly
+ *      down costs the page nothing it already had. A definitive answer (a revocation, say)
+ *      replaces the entry the moment the refresh lands. With the default `staleMs` of 0 an
+ *      expired entry is gone, exactly as before 1.2.0.
  *
  * It is deliberately tiny + dependency-free (a Map + timestamps) so it runs in any server
  * runtime (Node, edge, workerd). For multi-instance deployments this is per-instance L1 and
@@ -25,6 +32,18 @@ export interface TtlCacheOptions {
 	readonly negativeTtlMs?: number
 	/** Max entries before LRU-ish eviction of the oldest insert (default 1000). */
 	readonly maxEntries?: number
+	/**
+	 * 1.2.0: how long past its TTL a POSITIVE entry may still be served while a refresh runs (default 0: never). A
+	 * negative entry is never served stale.
+	 */
+	readonly staleMs?: number
+	/**
+	 * 1.2.0: how long an unsettled load may be joined by later callers (default: no limit). Past it, the next caller
+	 * starts a fresh load. WHY: a runtime may cancel the I/O of a request that has finished (Cloudflare workerd does),
+	 * which can leave a background refresh's promise pending forever; without a limit every later caller would join
+	 * it and none would ever refresh again.
+	 */
+	readonly inflightMaxMs?: number
 	/** Injectable clock for deterministic tests. */
 	readonly now?: () => number
 }
@@ -35,28 +54,64 @@ interface Entry<V> {
 	readonly negative: boolean
 }
 
+interface Inflight<V> {
+	readonly promise: Promise<V>
+	readonly startedAt: number
+}
+
 export class TtlCache<V> {
 	private readonly store = new Map<string, Entry<V>>()
-	private readonly inflight = new Map<string, Promise<V>>()
+	private readonly inflight = new Map<string, Inflight<V>>()
 	private readonly ttlMs: number
 	private readonly negativeTtlMs: number
 	private readonly maxEntries: number
+	private readonly staleMs: number
+	private readonly inflightMaxMs: number
 	private readonly now: () => number
 
 	constructor(opts: TtlCacheOptions = {}) {
 		this.ttlMs = opts.ttlMs ?? 60_000
 		this.negativeTtlMs = opts.negativeTtlMs ?? 5_000
 		this.maxEntries = opts.maxEntries ?? 1000
+		this.staleMs = opts.staleMs !== undefined && opts.staleMs > 0 ? opts.staleMs : 0
+		this.inflightMaxMs = opts.inflightMaxMs ?? Number.POSITIVE_INFINITY
 		this.now = opts.now ?? Date.now
 	}
 
-	/** Read a live (non-expired) entry, or undefined. Prunes the entry if expired. */
-	peek(key: string): V | undefined {
+	/** The entry while it may still be served (fresh, or positive and inside the stale window); prunes it past that. */
+	private servable(key: string): Entry<V> | undefined {
 		const e = this.store.get(key)
 		if (!e) return undefined
+		const now = this.now()
+		if (e.expiresAt > now) return e
+		if (!e.negative && now < e.expiresAt + this.staleMs) return e
+		this.store.delete(key)
+		return undefined
+	}
+
+	/** Read a live (non-expired) entry, or undefined. Never serves a stale one; prunes an entry past its stale window. */
+	peek(key: string): V | undefined {
+		const e = this.servable(key)
+		return e && e.expiresAt > this.now() ? e.value : undefined
+	}
+
+	/**
+	 * The synchronous stale-while-revalidate read: a fresh value; or a positive entry past its TTL but inside the stale
+	 * window, returned at once while this starts (or joins) ONE background refresh through `loader`; else undefined,
+	 * and the caller loads (`getOrLoad`). The refresh caches as `getOrLoad` does, with the same arguments; its failure
+	 * is swallowed (the stale value was already served, and a thrown loader is never cached).
+	 */
+	peekOrRefresh(
+		key: string,
+		loader: () => Promise<V>,
+		isNegative?: (v: V) => boolean,
+		positiveTtlMs?: number,
+		isTransient?: (v: V) => boolean,
+	): V | undefined {
+		const e = this.servable(key)
+		if (!e) return undefined
 		if (e.expiresAt <= this.now()) {
-			this.store.delete(key)
-			return undefined
+			this.load(key, loader, isNegative, positiveTtlMs, isTransient).catch(() => undefined)
 		}
 		return e.value
 	}
@@ -74,29 +129,50 @@ export class TtlCache<V> {
 	 * It deliberately does NOT apply to a negative result: a caller asking for a 10-minute
 	 * positive TTL is asking for fewer origin reads, not for a transient failure to be
 	 * remembered for ten minutes (see the negative-TTL rationale in the module header).
+	 *
+	 * 1.2.0: inside the stale window (`staleMs`) an expired positive entry is returned at once and refreshed in the
+	 * background (`peekOrRefresh`). `isTransient(value)` marks a result that says only "the origin was not reached"
+	 * (a timeout, a 5xx): when a servable positive entry exists, such a result is NOT cached over it and the caller
+	 * gets that entry's value instead (stale-if-error). With no entry to keep, it is cached as `isNegative` says.
 	 */
 	async getOrLoad(
 		key: string,
 		loader: () => Promise<V>,
 		isNegative?: (v: V) => boolean,
 		positiveTtlMs?: number,
+		isTransient?: (v: V) => boolean,
 	): Promise<V> {
-		const cached = this.peek(key)
-		if (cached !== undefined) return cached
+		const served = this.peekOrRefresh(key, loader, isNegative, positiveTtlMs, isTransient)
+		if (served !== undefined) return served
+		return this.load(key, loader, isNegative, positiveTtlMs, isTransient)
+	}
 
+	/** Single-flight load and cache (joins an unsettled load younger than `inflightMaxMs`). */
+	private load(
+		key: string,
+		loader: () => Promise<V>,
+		isNegative: ((v: V) => boolean) | undefined,
+		positiveTtlMs: number | undefined,
+		isTransient: ((v: V) => boolean) | undefined,
+	): Promise<V> {
 		const existing = this.inflight.get(key)
-		if (existing) return existing
+		if (existing && this.now() - existing.startedAt < this.inflightMaxMs) return existing.promise
 
-		const promise = (async () => {
+		const promise: Promise<V> = (async () => {
 			const value = await loader()
+			if (isTransient?.(value)) {
+				const kept = this.servable(key)
+				if (kept && !kept.negative) return kept.value
+			}
 			const negative = isNegative ? isNegative(value) : false
 			this.set(key, value, negative, negative ? undefined : positiveTtlMs)
 			return value
 		})().finally(() => {
-			this.inflight.delete(key)
+			// Only this load's own slot: a newer load that replaced an abandoned one keeps its place.
+			if (this.inflight.get(key)?.promise === promise) this.inflight.delete(key)
 		})
 
-		this.inflight.set(key, promise)
+		this.inflight.set(key, { promise, startedAt: this.now() })
 		return promise
 	}
 

package/src/verify/get-verified-delivery.ts

@@ -29,12 +29,20 @@
  * `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).
+ *
+ * 1.2.0: a suppressed read that only failed to REACH CertREV (the fetch threw or hit its deadline, a 5xx or other
+ * non-OK status but 404/410, a body that is not JSON or not an object) is marked `unreachable`. It says nothing
+ * about the credential, so a cache with a stale window keeps a verified entry over it (stale-if-error), and the
+ * card paints its options face instead of nothing. A definitive answer (404/410, a key or signature that does not
+ * verify, a revoked, expired or mismatched artifact) is never `unreachable`. `readVerifiedDelivery` is the
+ * synchronous read that also serves a stale entry while refreshing it.
  */
 
 import type { CertChromeRenderDef } from '../builder/cert-chrome-data.js'
 import type {
 	CertDeliveryArtifact,
 	CertPayload,
+	CertSignature,
 	CertSuppressReason,
 	CertVerdict,
 	RenderContext,
@@ -44,16 +52,34 @@ import { renderVerdict, verifyArtifact } from '../contract/kernel.js'
 import { TtlCache } from './cache.js'
 import { DEFAULT_FETCH_TIMEOUT_MS, fetchWithDeadline } from './fetch-with-deadline.js'
 
-/** What one Delivery read settles to, as cached: a verified payload + its def, or the reason not. */
+/**
+ * What one Delivery read settles to, as cached: a verified payload + its def (and, from 1.2.0, the signature it
+ * verified with, so a server render can hand the signed envelope to the browser), or the reason not.
+ */
 export type CachedDelivery =
-	| { readonly kind: 'verified'; readonly payload: CertPayload; readonly renderDef: CertChromeRenderDef | null }
-	| { readonly kind: 'suppressed'; readonly reason: CertSuppressReason }
+	| {
+			readonly kind: 'verified'
+			readonly payload: CertPayload
+			readonly renderDef: CertChromeRenderDef | null
+			/** Absent only in a cache filled by hand (a test, a custom cache); a read always keeps it. */
+			readonly signature?: CertSignature
+	  }
+	| {
+			readonly kind: 'suppressed'
+			readonly reason: CertSuppressReason
+			/** 1.2.0: true when CertREV was not reached (no answer about the credential); see the module header. */
+			readonly unreachable?: true
+	  }
 
 /** The answer for one render: the verdict AT THIS RENDER'S CLOCK, and the def to paint it with. */
 export interface VerifiedDelivery {
 	readonly verdict: CertVerdict
 	/** The brand's render def, or null (no def resolved, a malformed one, or a suppress verdict). */
 	readonly renderDef: CertChromeRenderDef | null
+	/** The verified envelope's signature, on a `render` verdict whose read kept it; else undefined. */
+	readonly signature?: CertSignature
+	/** 1.2.0: on a suppress verdict, true when CertREV was not reached; else undefined. */
+	readonly unreachable?: true
 }
 
 export interface GetVerifiedDeliveryOptions {
@@ -70,7 +96,7 @@ export interface GetVerifiedDeliveryOptions {
 	readonly cache?: TtlCache<CachedDelivery>
 	/** TTL in ms for a VERIFIED read (default: the cache's positive TTL, 60_000 on the shared one). */
 	readonly ttlMs?: number
-	/** Deadline in ms for the fetch (default `DEFAULT_FETCH_TIMEOUT_MS`, 3s). */
+	/** Deadline in ms for the fetch (default `DEFAULT_FETCH_TIMEOUT_MS`, 3s; the Builder card's runtime passes 8s). */
 	readonly timeoutMs?: number
 	/**
 	 * 1.2.0-canary.5: read one saved design version instead of the brand's live def. CertREV's own canary
@@ -96,6 +122,13 @@ function suppressed(reason: CertSuppressReason): CachedDelivery {
 	return { kind: 'suppressed', reason }
 }
 
+/** A read that did not reach CertREV: the same least-wrong reason as before 1.2.0, marked `unreachable`. */
+function unreachable(): CachedDelivery {
+	return { kind: 'suppressed', reason: 'unsupported_contract_version', unreachable: true }
+}
+
+const isUnreachable = (v: CachedDelivery): boolean => v.kind === 'suppressed' && v.unreachable === true
+
 /** The Delivery route; a design pin adds `?design=<v>` and, with a brand, `&designBrand=<brand>`. */
 export function deliveryUrl(baseUrl: string, platform: string, externalId: string, design?: DesignPin): string {
 	const base = baseUrl.replace(/\/+$/, '')
@@ -210,19 +243,19 @@ async function loadDelivery(opts: GetVerifiedDeliveryOptions): Promise<CachedDel
 		)
 	} catch {
 		// Unreachable, DNS/TLS, or the deadline. Same least-wrong member as getVerifiedEnvelope.
-		return suppressed('unsupported_contract_version')
+		return unreachable()
 	}
 	// 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')
+	if (!res.ok) return unreachable()
 	let body: unknown
 	try {
 		body = await res.json()
 	} catch {
-		return suppressed('unsupported_contract_version')
+		return unreachable()
 	}
-	if (!isRecord(body)) return suppressed('unsupported_contract_version')
+	if (!isRecord(body)) return unreachable()
 	let verdict: CertVerdict
 	try {
 		// `verifyArtifact`, so a tombstone verifies as itself and reports 'revoked'. The kernel reads
@@ -233,14 +266,28 @@ async function loadDelivery(opts: GetVerifiedDeliveryOptions): Promise<CachedDel
 		return suppressed('unknown_key')
 	}
 	if (verdict.decision !== 'render') return suppressed(verdict.reason)
-	return { kind: 'verified', payload: verdict.payload, renderDef: parseRenderDef(body.renderDef) }
+	// A `render` verdict came from an envelope (a tombstone never renders), so `signature` is the one just verified.
+	const signature = isRecord(body.signature) ? (body.signature as unknown as CertSignature) : undefined
+	return {
+		kind: 'verified',
+		payload: verdict.payload,
+		renderDef: parseRenderDef(body.renderDef),
+		...(signature ? { signature } : {}),
+	}
 }
 
 /** Apply the render-time policy to a cached read: lifecycle + subject at THIS render's clock. */
 export function settleDelivery(cached: CachedDelivery, context: RenderContext): VerifiedDelivery {
-	if (cached.kind === 'suppressed') return { verdict: { decision: 'suppress', reason: cached.reason }, renderDef: null }
+	if (cached.kind === 'suppressed') {
+		return {
+			verdict: { decision: 'suppress', reason: cached.reason },
+			renderDef: null,
+			...(cached.unreachable ? { unreachable: true as const } : {}),
+		}
+	}
 	const verdict = renderVerdict(cached.payload, context)
-	return { verdict, renderDef: verdict.decision === 'render' ? cached.renderDef : null }
+	if (verdict.decision !== 'render') return { verdict, renderDef: null }
+	return { verdict, renderDef: cached.renderDef, ...(cached.signature ? { signature: cached.signature } : {}) }
 }
 
 /**
@@ -255,10 +302,29 @@ export async function getVerifiedDelivery(opts: GetVerifiedDeliveryOptions): Pro
 		() => loadDelivery(opts),
 		(v) => v.kind === 'suppressed',
 		opts.ttlMs,
+		isUnreachable,
 	)
 	return settleDelivery(cached, opts.context)
 }
 
+/**
+ * 1.2.0, the synchronous read a render uses: the settled answer for a fresh cached read; or, inside the cache's
+ * stale window, the stale read's answer at once while ONE background refresh (the same fetch `getVerifiedDelivery`
+ * makes) replaces it; else `undefined`, and the caller awaits `getVerifiedDelivery`. The verdict is still settled
+ * at `context.now`, so a stale payload that has expired or been revoked in its own fields still suppresses.
+ */
+export function readVerifiedDelivery(opts: GetVerifiedDeliveryOptions): VerifiedDelivery | undefined {
+	const cache = opts.cache ?? sharedDeliveryCache
+	const cached = cache.peekOrRefresh(
+		deliveryCacheKey(opts),
+		() => loadDelivery(opts),
+		(v) => v.kind === 'suppressed',
+		opts.ttlMs,
+		isUnreachable,
+	)
+	return cached === undefined ? undefined : 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.