@certrev/cert-block 0.5.5 → 1.0.0

package/src/verify/fetch-with-deadline.ts

@@ -0,0 +1,60 @@
+/**
+ * `fetchWithDeadline` — every network read on the render path gets a deadline.
+ *
+ * WHY: the verify layer runs INSIDE a server render (a Hydrogen loader, a Next server
+ * component, a Builder server fetch). A hung origin with no deadline holds that render open
+ * for as long as the runtime's socket timeout allows — one confirmed case was still pending
+ * at 45 SECONDS, i.e. a page that never answered because a decorative badge could not be
+ * verified. A badge is never worth a page: past the deadline the request is ABORTED (the
+ * connection goes back) and the caller fails closed, the same safe outcome as any other
+ * fetch failure.
+ *
+ * Two deliberate choices:
+ *   • The deadline is enforced by a RACE, not by the AbortSignal alone. A `fetchImpl` that
+ *     ignores its signal (a wrapper, a proxy, a non-conforming polyfill) must not be able to
+ *     hold a render open. The abort still fires, so a conforming implementation also releases
+ *     the socket rather than merely being abandoned.
+ *   • `setTimeout` + `AbortController`, not `AbortSignal.timeout()`. The one-liner reads
+ *     better but its timer is not the one a test's fake clock controls, and a deadline that
+ *     can only be tested by really waiting is a deadline nobody keeps tested.
+ */
+
+/**
+ * Default deadline for a render-path fetch. The Delivery API is CDN-cacheable and answers
+ * well under a second at p99; three seconds is generous for a cold origin and still bounded
+ * by what a page can afford to spend on a decoration whose failure mode is "render nothing".
+ * Callers on a tighter TTFB budget pass their own.
+ */
+export const DEFAULT_FETCH_TIMEOUT_MS = 3_000
+
+/**
+ * `fetchImpl(url, init)` with a hard deadline. Rejects when the deadline passes (after
+ * aborting the request); every caller on the verify path treats that rejection like any other
+ * fetch failure — fail closed. A non-finite or non-positive `timeoutMs` is an explicit opt-out
+ * (no deadline), for a caller that owns its own cancellation.
+ */
+export async function fetchWithDeadline(
+	fetchImpl: typeof fetch,
+	url: string,
+	init: RequestInit,
+	timeoutMs: number = DEFAULT_FETCH_TIMEOUT_MS,
+): Promise<Response> {
+	if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) return fetchImpl(url, init)
+
+	const controller = new AbortController()
+	let timer: ReturnType<typeof setTimeout> | undefined
+	const deadline = new Promise<never>((_, reject) => {
+		timer = setTimeout(() => {
+			controller.abort()
+			reject(new Error(`cert-block: fetch exceeded its ${timeoutMs}ms deadline — ${url}`))
+		}, timeoutMs)
+	})
+
+	try {
+		// Promise.race subscribes to both, so an abort-rejection that lands after the race has
+		// settled is still handled — it never surfaces as an unhandled rejection.
+		return await Promise.race([fetchImpl(url, { ...init, signal: controller.signal }), deadline])
+	} finally {
+		if (timer !== undefined) clearTimeout(timer)
+	}
+}

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

@@ -16,11 +16,23 @@
  * JSON-LD; `{ decision: 'suppress', reason }` → render NOTHING. Any error (network,
  * malformed JSON, throwing resolver) collapses to a `suppress` verdict — never throws
  * into the render path, never renders an unverified credential.
+ *
+ * `verdict.reason` is the ONLY signal a consumer gets when a badge does not appear (this
+ * package logs nothing), so every failure path here reports what ACTUALLY failed rather than
+ * a convenient catch-all. Every fetch also carries a deadline: a hung origin fails closed at
+ * `timeoutMs` instead of holding the render open (see ./fetch-with-deadline).
  */
 
-import type { CertDeliveryEnvelope, CertVerdict, RenderContext, ResolvePublicKeyByKid } from '../contract/kernel.js'
-import { verifyEnvelope } from '../contract/kernel.js'
+import type {
+	CertDeliveryArtifact,
+	CertSuppressReason,
+	CertVerdict,
+	RenderContext,
+	ResolvePublicKeyByKid,
+} from '../contract/kernel.js'
+import { verifyArtifact } from '../contract/kernel.js'
 import { TtlCache } from './cache.js'
+import { DEFAULT_FETCH_TIMEOUT_MS, fetchWithDeadline } from './fetch-with-deadline.js'
 
 /** Where the signed envelope comes from. Exactly one of the two source shapes. */
 export type EnvelopeSource =
@@ -32,12 +44,13 @@ export type EnvelopeSource =
 			readonly platform: string
 			readonly externalId: string
 	  }
-	/** PUSH/native: an envelope already read from a Shopify app-owned metafield (or any
+	/** PUSH/native: an artifact already read from a Shopify app-owned metafield (or any
 	 *  native store). The caller fetched it via the Storefront API; we just verify it. The
-	 *  value may be the parsed envelope or its JSON string (metafields store strings). */
+	 *  value may be the parsed artifact — a full envelope OR the slim revocation tombstone —
+	 *  or its JSON string (metafields store strings). */
 	| {
 			readonly kind: 'metafield'
-			readonly value: CertDeliveryEnvelope | string | null | undefined
+			readonly value: CertDeliveryArtifact | string | null | undefined
 	  }
 
 export interface GetVerifiedEnvelopeOptions {
@@ -45,33 +58,58 @@ export interface GetVerifiedEnvelopeOptions {
 	/** kid → public-key resolver (see ./resolve-kid). Required: no verify without keys. */
 	readonly resolveKid: ResolvePublicKeyByKid
 	/** Render context: the platform + externalId this edge IS, plus optional live hash. */
-	readonly context: Omit<RenderContext, 'now'> & { readonly now?: Date }
+	readonly context: RenderContext
 	/** Injectable fetch for tests / non-global-fetch runtimes. */
 	readonly fetchImpl?: typeof fetch
 	/** Cache override (per-instance). Defaults to the module-level shared cache. */
 	readonly cache?: TtlCache<CertVerdict>
-	/** Positive verdict TTL ms (default 60_000). */
+	/** TTL in ms for a RENDER verdict written by this call (default: the cache's own positive
+	 *  TTL — 60_000 on the shared cache). A suppress verdict keeps the cache's short negative
+	 *  TTL regardless, so a longer `ttlMs` can never make a transient failure sticky. */
 	readonly ttlMs?: number
+	/** Deadline in ms for the Delivery API fetch (default `DEFAULT_FETCH_TIMEOUT_MS`, 3s).
+	 *  Ignored by the metafield source, which does no I/O. */
+	readonly timeoutMs?: number
 }
 
 /** Module-level shared cache so all calls in a process coordinate by default. */
 const sharedVerdictCache = new TtlCache<CertVerdict>({ ttlMs: 60_000, negativeTtlMs: 5_000 })
 
-function suppress(
-	reason: CertVerdict extends { decision: 'suppress' }
-		? never
-		: Extract<CertVerdict, { decision: 'suppress' }>['reason'],
-): CertVerdict {
+function suppress(reason: CertSuppressReason): CertVerdict {
 	return { decision: 'suppress', reason }
 }
 
-function parseEnvelope(value: CertDeliveryEnvelope | string | null | undefined): CertDeliveryEnvelope | null {
-	if (value == null) return null
-	if (typeof value !== 'string') return value
+/**
+ * What sourcing produced: an artifact to verify, or the TRUTHFUL reason it produced none.
+ *
+ * WHY a reason per failure, and why these reasons: the verdict's `reason` is the only thing a
+ * consumer sees when a badge silently doesn't render. Every sourcing failure used to collapse
+ * to 'unsupported_contract_version', which is FALSE for a 404 and for an unreachable origin —
+ * it sends whoever is debugging to inspect a contractVersion that was never in play.
+ *
+ * `CertSuppressReason` (owned by @certrev/cert-contract) has no member for a TRANSPORT
+ * failure, and inventing one here would be a cross-package contract change. So the mapping
+ * is: nothing is published for this subject → 'subject_mismatch'; a body arrived that could
+ * not be parsed → 'unsupported_contract_version' (true as written); the origin could not be
+ * read at all → 'unsupported_contract_version' as the least-wrong member — it asserts nothing
+ * about the credential itself, which every other member would.
+ */
+type SourceOutcome =
+	| { readonly ok: true; readonly artifact: CertDeliveryArtifact }
+	| { readonly ok: false; readonly reason: CertSuppressReason }
+
+/** Read the artifact out of a metafield value. Never throws. */
+function parseMetafieldValue(value: CertDeliveryArtifact | string | null | undefined): SourceOutcome {
+	// Absent — never certified, or the app cleared the metafield (Shopify writes an empty
+	// string rather than deleting it). Nothing is published for this subject.
+	if (value == null || (typeof value === 'string' && value.trim() === '')) {
+		return { ok: false, reason: 'subject_mismatch' }
+	}
+	if (typeof value !== 'string') return { ok: true, artifact: value }
 	try {
-		return JSON.parse(value) as CertDeliveryEnvelope
+		return { ok: true, artifact: JSON.parse(value) as CertDeliveryArtifact }
 	} catch {
-		return null
+		return { ok: false, reason: 'unsupported_contract_version' }
 	}
 }
 
@@ -98,33 +136,76 @@ function fnv1a(s: string): string {
 }
 
 /** A stable string form of the metafield value for hashing (parsed → canonical-ish JSON). */
-function metafieldValueKey(value: CertDeliveryEnvelope | string | null | undefined): string {
+function metafieldValueKey(value: CertDeliveryArtifact | string | null | undefined): string {
 	if (value == null) return 'null'
 	const s = typeof value === 'string' ? value : JSON.stringify(value)
 	return fnv1a(s)
 }
 
-/** Stable cache key per (source identity × render externalId × envelope value). */
+/** WHICH artifact is being verified. For the delivery source that is the full URL — the base
+ *  URL is part of the identity (a staging portal and production serve DIFFERENT envelopes for
+ *  the same platform/externalId); for a metafield it's a hash of the value the caller passed. */
+function sourceKey(source: EnvelopeSource): string {
+	return source.kind === 'delivery_api' ? `api:${deliveryApiUrl(source)}` : `mf:${metafieldValueKey(source.value)}`
+}
+
+/** WHERE it is being rendered. `now` is deliberately NOT part of the key: elapsed time is what
+ *  the TTL already bounds, and keying on an injected clock would turn the cache into a
+ *  permanent miss for every caller that passes one. */
+function placementKey(ctx: RenderContext): string {
+	return `${encodeURIComponent(ctx.platform)}:${encodeURIComponent(ctx.externalId)}`
+}
+
+/** Everything in the key ABOVE the live content hash — one placement, all of its hashes. */
+function placementPrefix(source: EnvelopeSource, ctx: RenderContext): string {
+	return `${sourceKey(source)}|${placementKey(ctx)}|`
+}
+
+/**
+ * Stable cache key per (artifact identity × placement × live content hash) — i.e. every input
+ * the verdict actually depends on. Both source branches now key on the same three things: the
+ * old delivery key (`api:<platform>:<externalId>`) named neither the base URL nor the render
+ * context, so one entry was shared by a staging and a production portal, and — the dangerous
+ * one — a verdict computed while the article matched its `contentDigest` was served for a
+ * later render whose body had DRIFTED, rendering a credential the drift check would have
+ * suppressed. The live hash goes LAST so `invalidateVerdict` can drop a placement by prefix.
+ */
 function cacheKey(source: EnvelopeSource, ctx: RenderContext): string {
-	if (source.kind === 'delivery_api') {
-		return `api:${source.platform}:${source.externalId}`
-	}
-	// Metafield: key on the rendering identity AND a short hash of the envelope value, so a
-	// push update (new envelope at the same placement) busts the entry, and verifying
-	// different envelopes against one render context never collides on a stale verdict.
-	return `mf:${ctx.platform}:${ctx.externalId}:${metafieldValueKey(source.value)}`
+	return `${placementPrefix(source, ctx)}${ctx.liveContentHash ?? '-'}`
 }
 
+/** Fetch the artifact from the Delivery API. Never throws: every failure comes back as the
+ *  truthful suppress reason (see `SourceOutcome`). */
 async function fetchFromDeliveryApi(
 	s: Extract<EnvelopeSource, { kind: 'delivery_api' }>,
 	fetchImpl: typeof fetch,
-): Promise<CertDeliveryEnvelope | null> {
-	const res = await fetchImpl(deliveryApiUrl(s), { headers: { accept: 'application/json' } })
-	if (!res.ok) return null // 404 / 410 (revoked, no longer served) → no envelope → suppress
+	timeoutMs: number,
+): Promise<SourceOutcome> {
+	let res: Response
+	try {
+		res = await fetchWithDeadline(fetchImpl, deliveryApiUrl(s), { headers: { accept: 'application/json' } }, timeoutMs)
+	} catch {
+		// Unreachable origin, DNS/TLS failure, or the deadline above. No transport member
+		// exists in the contract enum; this is the least-wrong one.
+		return { ok: false, reason: 'unsupported_contract_version' }
+	}
+	if (res.status === 404 || res.status === 410) {
+		// The API serves nothing for this (platform, externalId): never certified, or the
+		// placement was withdrawn. Revocation of a LIVE cert comes back 200 with a tombstone
+		// so a 4xx here is genuinely "no credential for this subject" — which is
+		// also the question the consumer needs to ask (is this the externalId I think it is?).
+		return { ok: false, reason: 'subject_mismatch' }
+	}
+	if (!res.ok) {
+		// 5xx / 429 / anything else: the origin is failing, not the credential. Transport gap
+		// again — same least-wrong member, and the short negative TTL keeps it recoverable.
+		return { ok: false, reason: 'unsupported_contract_version' }
+	}
 	try {
-		return (await res.json()) as CertDeliveryEnvelope
+		return { ok: true, artifact: (await res.json()) as CertDeliveryArtifact }
 	} catch {
-		return null
+		// A body arrived and could not be parsed — here the reason is literally true.
+		return { ok: false, reason: 'unsupported_contract_version' }
 	}
 }
 
@@ -144,38 +225,40 @@ export async function getVerifiedEnvelope(opts: GetVerifiedEnvelopeOptions): Pro
 	return cache.getOrLoad(
 		key,
 		async () => {
-			let envelope: CertDeliveryEnvelope | null
-			try {
-				envelope =
-					opts.source.kind === 'delivery_api'
-						? await fetchFromDeliveryApi(opts.source, fetchImpl)
-						: parseEnvelope(opts.source.value)
-			} catch {
-				// Network/JSON failure → fail closed (do NOT render an unverified credential).
-				return suppress('unsupported_contract_version')
-			}
-			if (!envelope) {
-				// No envelope present (never certified / revoked + cleared / 404) → suppress.
-				return suppress('unsupported_contract_version')
-			}
+			const sourced =
+				opts.source.kind === 'delivery_api'
+					? await fetchFromDeliveryApi(opts.source, fetchImpl, opts.timeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS)
+					: parseMetafieldValue(opts.source.value)
+			if (!sourced.ok) return suppress(sourced.reason)
+			// `verifyArtifact` — not `verifyEnvelope` — because the Delivery API answers a
+			// revoked cert with the slim signed TOMBSTONE. The envelope-only kernel
+			// still fails closed on one, but it reports it as an unparseable envelope; the
+			// artifact kernel verifies the tombstone's own signature + subject and says
+			// 'revoked', which is both true and the thing a consumer needs to hear.
 			// The kernel itself never throws (it fails closed), but guard the resolver too.
 			try {
-				return await verifyEnvelope(envelope, opts.resolveKid, ctx)
+				return await verifyArtifact(sourced.artifact, opts.resolveKid, ctx)
 			} catch {
 				return suppress('unknown_key')
 			}
 		},
 		isSuppress,
+		opts.ttlMs,
 	)
 }
 
-/** Expose the shared cache so a revocation webhook handler can invalidate proactively. */
+/**
+ * Expose the shared cache so a revocation webhook handler can invalidate proactively. Drops
+ * EVERY entry for this source at this placement, whatever live content hash each was cached
+ * under — the webhook knows the article, never the body hash a given render observed, and an
+ * invalidation that misses because of a hash mismatch is a revoked cert that keeps rendering.
+ */
 export function invalidateVerdict(
 	source: EnvelopeSource,
 	context: RenderContext,
 	cache: TtlCache<CertVerdict> = sharedVerdictCache,
 ): void {
-	cache.delete(cacheKey(source, context))
+	cache.deletePrefix(placementPrefix(source, context))
 }
 
 export { sharedVerdictCache }

package/src/verify/resolve-kid.ts

@@ -20,6 +20,7 @@
 import { base64urlDecode } from '@certrev/cert-contract'
 import type { Ed25519PublicKeyInput, ResolvePublicKeyByKid } from '../contract/kernel.js'
 import { TtlCache } from './cache.js'
+import { DEFAULT_FETCH_TIMEOUT_MS, fetchWithDeadline } from './fetch-with-deadline.js'
 
 /** A static map of kid → public key (PEM string or an explicit input). */
 export type StaticKeySet = Readonly<Record<string, string | Ed25519PublicKeyInput>>
@@ -72,6 +73,9 @@ export interface FetchingKidResolverOptions {
 	readonly jwksUrl: string
 	/** Key-set cache TTL in ms (default 1h — keys rotate rarely). */
 	readonly ttlMs?: number
+	/** Deadline in ms for the JWKS fetch (default `DEFAULT_FETCH_TIMEOUT_MS`, 3s). This fetch
+	 *  is on the render path too — a hung key endpoint must not hold a page open. */
+	readonly timeoutMs?: number
 	/** Injectable fetch for tests / non-global-fetch runtimes. */
 	readonly fetchImpl?: typeof fetch
 }
@@ -88,12 +92,24 @@ export function fetchingKidResolver(opts: FetchingKidResolverOptions): ResolvePu
 
 	async function loadKeySet(): Promise<Map<string, Ed25519PublicKeyInput>> {
 		const map = new Map<string, Ed25519PublicKeyInput>()
-		const res = await fetchImpl(opts.jwksUrl, { headers: { accept: 'application/json' } })
-		if (!res.ok) return map // empty → every kid resolves null → fail closed
-		const doc = (await res.json()) as PublishedKeySetDoc
-		for (const jwk of doc.keys ?? []) {
-			const input = jwkToInput(jwk)
-			if (input && jwk.kid) map.set(jwk.kid, input)
+		try {
+			const res = await fetchWithDeadline(
+				fetchImpl,
+				opts.jwksUrl,
+				{ headers: { accept: 'application/json' } },
+				opts.timeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS,
+			)
+			if (!res.ok) return map // empty → every kid resolves null → fail closed
+			const doc = (await res.json()) as PublishedKeySetDoc
+			for (const jwk of doc.keys ?? []) {
+				const input = jwkToInput(jwk)
+				if (input && jwk.kid) map.set(jwk.kid, input)
+			}
+		} catch {
+			// Unreachable / deadline / unreadable body → the EMPTY key set below, negative-cached
+			// briefly. The resolver itself never throws: a kid that cannot be resolved must come
+			// back as null ('unknown_key' — true) rather than as an exception the caller has to
+			// remember to catch.
 		}
 		return map
 	}

package/src/webcomponent/certrev-badge.ts

@@ -41,6 +41,17 @@ export function setCertRevKidResolver(resolver: ResolvePublicKeyByKid): void {
 	globalResolveKid = resolver
 }
 
+/**
+ * `badge-style` is AUTHOR-typed markup, not signed data — a hand-written attribute on a page
+ * we don't control. Only the two real faces are honored; anything else (`"Full"`, a stray
+ * value, an empty attribute) reads as ABSENT, so the signed display config decides. The
+ * attribute was previously CAST (`as 'full' | 'compact' | null`), which let a typo travel
+ * into the renderer as if it were a face.
+ */
+function badgeStyleAttribute(value: string | null): 'full' | 'compact' | undefined {
+	return value === 'full' || value === 'compact' ? value : undefined
+}
+
 export class CertRevBadgeElement extends HTMLElement {
 	static get observedAttributes(): string[] {
 		return ['delivery-api', 'platform', 'external-id', 'accent-color', 'badge-style', 'content-hash']
@@ -86,8 +97,19 @@ export class CertRevBadgeElement extends HTMLElement {
 		}
 		if (verdict.decision !== 'render') return
 		const accentColor = this.getAttribute('accent-color') ?? undefined
-		const badgeStyle = (this.getAttribute('badge-style') as 'full' | 'compact' | null) ?? undefined
-		this.innerHTML = renderBadgeHtml(verdict.payload, { accentColor, badgeStyle })
+		const badgeStyle = badgeStyleAttribute(this.getAttribute('badge-style'))
+		// The render is INSIDE the fail-closed boundary too. `connectedCallback` `void`s this
+		// promise, so a throw from the renderer (a payload shape nothing runtime-validates —
+		// the kernel checks the signature, never `content`) would escape as an unhandled
+		// rejection instead of rendering nothing, which is the one behaviour this element
+		// documents. Compute first, assign after, so a failure leaves the element untouched.
+		let html: string
+		try {
+			html = renderBadgeHtml(verdict.payload, { accentColor, badgeStyle })
+		} catch {
+			return // fail closed
+		}
+		this.innerHTML = html
 	}
 }
 

package/src/webcomponent/render-badge-html.ts

@@ -13,7 +13,14 @@
  */
 
 import { escapeAttribute, escapeHtml, safeCssColor, safeHttpUrl } from '../components/escape.js'
-import { credentialSuffix, formatDate, resolveDisplay } from '../components/format.js'
+import {
+	credentialSuffix,
+	dedupeCredential,
+	expertNameWithCredentials,
+	formatDate,
+	resolveDisplay,
+} from '../components/format.js'
+import { CERTREV_LINK_REL } from '../components/rel.js'
 import {
 	CERT_SCOPE_LINE,
 	CERT_STRINGS_VERSION,
@@ -21,13 +28,13 @@ import {
 	resolveRenderTheme,
 	themeCssVarDeclarations,
 } from '../components/render-def.js'
-import type { CertPayload } from '../contract/kernel.js'
+import type { CertContent, CertPayload } from '../contract/kernel.js'
 
 export interface RenderBadgeOptions {
 	readonly accentColor?: string
 	readonly badgeStyle?: 'full' | 'compact'
 	/**
-	 * The brand render-def (WS6). ABSENT → the badge renders the CertREV preset
+	 * The brand render-def. ABSENT → the badge renders the CertREV preset
 	 * default (theme output byte-identical to un-themed). PRESENT → validated
 	 * themeable tokens are emitted as `--certrev-*` CSS vars + subtractive
 	 * visibility applies. Mirrors `<CertBadge>`'s `renderDef` prop exactly.
@@ -37,6 +44,37 @@ export interface RenderBadgeOptions {
 
 const C = 'certrev-badge'
 
+/**
+ * The payload as it ACTUALLY arrives, not as the contract types promise it.
+ *
+ * `getVerifiedEnvelope` casts raw JSON (`JSON.parse(value) as CertDeliveryEnvelope`) and
+ * `verifyEnvelope` checks the signature, subject, lifecycle and drift — it never asserts the
+ * SHAPE of `content`. `renderBadgeHtml` is public API on top of that (the README shows a
+ * consumer calling it with a payload of their own), so every field is read as absent-able.
+ * The escape/format helpers already coerce a non-string VALUE (`asText`); what no helper can
+ * absorb is a missing PARENT object, which is what this view exists for. `cert-modal-view.ts`
+ * has read the same data this way since the unified modal landed — two renderers in one package
+ * disagreeing
+ * about whether the same payload is trusted is itself the defect.
+ *
+ * The `format.ts` helpers still take the CONTRACT type (`payload?.content`): they are
+ * shape-guarded on their own side, so widening them here would only hide that.
+ */
+type Loose<T> = { readonly [K in keyof T]?: T[K] | null }
+type LooseContent = Omit<Loose<CertContent>, 'expert' | 'author'> & {
+	readonly expert?: Loose<CertContent['expert']> | null
+	readonly author?: Loose<CertContent['author']> | null
+}
+
+/**
+ * The badge has exactly two faces, and this is the ONE place that decides which. Anything
+ * that is not the compact face renders the full face — so an unvalidated `badgeStyle` (a
+ * malformed envelope's number, an untyped caller's typo) can never reach the class name.
+ */
+function badgeFace(style: unknown): 'full' | 'compact' {
+	return style === 'compact' ? 'compact' : 'full'
+}
+
 function attr(name: string, value: string | null | undefined): string {
 	if (value == null || value === '') return ''
 	return ` ${name}="${escapeAttribute(value)}"`
@@ -48,23 +86,26 @@ function attr(name: string, value: string | null | undefined): string {
  * already decided to render by the time this is called).
  */
 export function renderBadgeHtml(payload: CertPayload, opts: RenderBadgeOptions = {}): string {
-	const content = payload.content
-	const display = resolveDisplay(content.display, opts.accentColor, opts.renderDef)
+	const content: LooseContent = payload?.content ?? {}
+	const expert = content.expert ?? null
+	const display = resolveDisplay(content.display ?? undefined, opts.accentColor, opts.renderDef)
 	const theme = resolveRenderTheme(opts.renderDef)
-	const style = opts.badgeStyle ?? display.badgeStyle
+	const style = badgeFace(opts.badgeStyle ?? display.badgeStyle)
 	const accent = safeCssColor(display.accentColor) ?? '#0f766e'
 	const verifyUrl = safeHttpUrl(content.verifyUrl)
-	const profileUrl = safeHttpUrl(content.expert.profileUrl)
-	const photoUrl = style === 'full' && display.showExpertPhoto ? safeHttpUrl(content.expert.photoUrl) : null
-	const suffix = credentialSuffix(content)
+	const profileUrl = safeHttpUrl(expert?.profileUrl)
+	const photoUrl = style === 'full' && display.showExpertPhoto ? safeHttpUrl(expert?.photoUrl) : null
+	// Same composition rule as <CertBadge>: the suffix drops a credential the display name
+	// already carries, so the two renderers never disagree about one payload.
+	const suffix = dedupeCredential(expert?.displayName, credentialSuffix(payload?.content))
 	const certified = formatDate(content.certifiedAt)
 	const updated = formatDate(content.contentModifiedAt)
 
-	const name = `${escapeHtml(content.expert.displayName)}${
+	const name = `${escapeHtml(expert?.displayName)}${
 		suffix ? `<span class="${C}__credentials">, ${escapeHtml(suffix)}</span>` : ''
 	}`
 	const nameNode = profileUrl
-		? `<a class="${C}__expert-link" href="${escapeAttribute(profileUrl)}" rel="noopener">${name}</a>`
+		? `<a class="${C}__expert-link" href="${escapeAttribute(profileUrl)}" rel="${CERTREV_LINK_REL}">${name}</a>`
 		: name
 
 	const mark =
@@ -72,8 +113,10 @@ export function renderBadgeHtml(payload: CertPayload, opts: RenderBadgeOptions =
 		`<circle cx="12" cy="12" r="11" fill="${escapeAttribute(accent)}"></circle>` +
 		`<path d="M7 12.5l3.2 3.2L17 9" stroke="#ffffff" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"></path></svg>`
 
+	// alt="" is deliberate: the byline below renders the same name as text, so alt text would make a
+	// screen reader announce it twice. Kept in lockstep with <CertBadge> and the modal avatar.
 	const photo = photoUrl
-		? `<img class="${C}__photo" src="${escapeAttribute(photoUrl)}" alt="Photo of ${escapeAttribute(content.expert.displayName)}" width="40" height="40" loading="lazy" decoding="async" />`
+		? `<img class="${C}__photo" src="${escapeAttribute(photoUrl)}" alt="" width="40" height="40" loading="lazy" decoding="async" />`
 		: ''
 
 	const header =
@@ -88,7 +131,7 @@ export function renderBadgeHtml(payload: CertPayload, opts: RenderBadgeOptions =
 		if (display.showMemo && content.memo) {
 			body += `<p class="${C}__memo">${escapeHtml(content.memo)}</p>`
 		}
-		if (display.showAuthor && content.author.name && content.author.name !== content.expert.displayName) {
+		if (display.showAuthor && content.author?.name && content.author.name !== expert?.displayName) {
 			const title = content.author.title ? `, ${escapeHtml(content.author.title)}` : ''
 			body += `<p class="${C}__author">Written by ${escapeHtml(content.author.name)}${title}</p>`
 		}
@@ -114,7 +157,7 @@ export function renderBadgeHtml(payload: CertPayload, opts: RenderBadgeOptions =
 	// byte-verbatim COMPENSATED_EXPERT_CUE. The scope line is byte-verbatim
 	// CERT_SCOPE_LINE (its curly apostrophe U+2019 survives escapeHtml untouched).
 	const cueInner = profileUrl
-		? `Compensated <a class="${C}__cue-link" href="${escapeAttribute(profileUrl)}" rel="noopener">expert</a>`
+		? `Compensated <a class="${C}__cue-link" href="${escapeAttribute(profileUrl)}" rel="${CERTREV_LINK_REL}">expert</a>`
 		: 'Compensated expert'
 	const disclosure =
 		`<div class="${C}__disclosure">` +
@@ -123,11 +166,13 @@ export function renderBadgeHtml(payload: CertPayload, opts: RenderBadgeOptions =
 		`</div>`
 
 	const verify = verifyUrl
-		? `<a class="${C}__verify" href="${escapeAttribute(verifyUrl)}" rel="noopener" aria-label="Verify this certification on CertREV">Verify on CertREV</a>`
+		? `<a class="${C}__verify" href="${escapeAttribute(verifyUrl)}" rel="${CERTREV_LINK_REL}" aria-label="Verify this certification on CertREV">Verify on CertREV</a>`
 		: ''
 
-	const ariaLabel = `Content reviewed by ${content.expert.displayName}${suffix ? `, ${suffix}` : ''}`
-	// Accent LEADS so the un-themed output is byte-identical to the pre-WS6 single-var
+	// Same derivation <CertBadge> labels with, so the two renderers cannot drift on the one
+	// string a screen reader actually announces.
+	const ariaLabel = `Content reviewed by ${expertNameWithCredentials(payload?.content)}`
+	// Accent LEADS so the un-themed output is byte-identical to the older single-var
 	// form. A THEMED brand appends surface/radius/font: the data-bearing tokens ride
 	// escaped (a no-op for validated hex/length — defense in depth), the font is a
 	// controlled literal stack emitted raw. The whole string is NOT re-escaped
@@ -139,8 +184,10 @@ export function renderBadgeHtml(payload: CertPayload, opts: RenderBadgeOptions =
 	}
 
 	return (
-		`<section class="${C} ${C}--${escapeAttribute(style)}" style="${rootStyle}"` +
-		attr('data-certrev-cert-id', payload.certId) +
+		// `style` is one of two literals by construction (`badgeFace`), so the class name needs
+		// no escaping — there is no path by which caller data reaches it.
+		`<section class="${C} ${C}--${style}" style="${rootStyle}"` +
+		attr('data-certrev-cert-id', payload?.certId) +
 		` data-certrev-strings-version="${CERT_STRINGS_VERSION}"` +
 		attr('data-certrev-def-version', theme.version != null ? String(theme.version) : null) +
 		` aria-label="${escapeAttribute(ariaLabel)}">${header}${body}${disclosure}${verify}</section>`