@certrev/cert-block 1.2.1-canary.0 → 1.3.0

package/package.json

@@ -1,113 +1,113 @@
 {
-  "name": "@certrev/cert-block",
-  "version": "1.2.1-canary.0",
-  "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",
-    "url": "git+https://github.com/CertREV/cert-kit.git",
-    "directory": "packages/cert-block"
-  },
-  "homepage": "https://github.com/CertREV/cert-kit/tree/HEAD/packages/cert-block#readme",
-  "bugs": {
-    "url": "https://github.com/CertREV/cert-kit/issues"
-  },
-  "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
-    },
-    "./builder": {
-      "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"
-    },
-    "./reader": {
-      "types": "./dist/reader/index.d.ts",
-      "default": "./dist/reader/index.js"
-    },
-    "./reader.css": "./src/reader/reader.css",
-    "./webcomponent": {
-      "types": "./dist/webcomponent/certrev-badge.d.ts",
-      "default": "./dist/webcomponent/certrev-badge.js"
-    },
-    "./fixtures": {
-      "types": "./dist/contract/fixtures.d.ts",
-      "default": "./dist/contract/fixtures.js"
-    },
-    "./modal": {
-      "types": "./dist/modal/index.d.ts",
-      "default": "./dist/modal/index.js"
-    },
-    "./modal/placement": {
-      "types": "./dist/modal/placement.d.ts",
-      "default": "./dist/modal/placement.js"
-    },
-    "./modal/certrev-cert.js": "./dist/modal/certrev-cert.js"
-  },
-  "files": [
-    "dist",
-    "src",
-    "!src/**/__tests__",
-    "!src/**/*.test.ts",
-    "!src/**/*.test.tsx",
-    "README.md",
-    "CHANGELOG.md"
-  ],
-  "publishConfig": {
-    "registry": "https://registry.npmjs.org",
-    "access": "public"
-  },
-  "publishTargets": [
-    "npmjs",
-    "github-packages"
-  ],
-  "dependencies": {
-    "@certrev/cert-contract": "^0.5.0"
-  },
-  "peerDependencies": {
-    "react": ">=18.0.0"
-  },
-  "peerDependenciesMeta": {
-    "react": {
-      "optional": false
-    }
-  },
-  "devDependencies": {
-    "@testing-library/react": "^16.1.0",
-    "@types/node": "^20.0.0",
-    "@types/react": "^18.3.0",
-    "@types/react-dom": "^18.3.0",
-    "jsdom": "^25.0.0",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1",
-    "typescript": "^6.0.3",
-    "vitest": "^4.1.5"
-  },
-  "keywords": [
-    "certrev",
-    "certification",
-    "react",
-    "server-components",
-    "hydrogen",
-    "shopify",
-    "json-ld",
-    "schema-org",
-    "web-component",
-    "ed25519",
-    "ssr"
-  ],
-  "license": "MIT",
-  "scripts": {
-    "build": "tsc && pnpm build:modal-bundle",
-    "build:modal-bundle": "pnpm dlx esbuild@0.27.7 src/modal/certrev-cert.entry.ts --bundle --minify --target=es2020 --format=iife --legal-comments=none --tsconfig-raw='{\"compilerOptions\":{\"target\":\"ES2017\",\"module\":\"esnext\",\"strict\":true}}' --banner:js='/* biome-ignore-all format: generated cert-badge bundle, see @certrev/cert-block src/modal/ */ /* biome-ignore-all lint: generated cert-badge bundle, see @certrev/cert-block src/modal/ */' --outfile=dist/modal/certrev-cert.js",
-    "refresh:reader": "node scripts/refresh-reader.mjs",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run"
-  }
-}
+	"name": "@certrev/cert-block",
+	"version": "1.3.0",
+	"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",
+		"url": "git+https://github.com/CertREV/cert-kit.git",
+		"directory": "packages/cert-block"
+	},
+	"homepage": "https://github.com/CertREV/cert-kit/tree/HEAD/packages/cert-block#readme",
+	"bugs": {
+		"url": "https://github.com/CertREV/cert-kit/issues"
+	},
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		},
+		"./builder": {
+			"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"
+		},
+		"./reader": {
+			"types": "./dist/reader/index.d.ts",
+			"default": "./dist/reader/index.js"
+		},
+		"./reader.css": "./src/reader/reader.css",
+		"./webcomponent": {
+			"types": "./dist/webcomponent/certrev-badge.d.ts",
+			"default": "./dist/webcomponent/certrev-badge.js"
+		},
+		"./fixtures": {
+			"types": "./dist/contract/fixtures.d.ts",
+			"default": "./dist/contract/fixtures.js"
+		},
+		"./modal": {
+			"types": "./dist/modal/index.d.ts",
+			"default": "./dist/modal/index.js"
+		},
+		"./modal/placement": {
+			"types": "./dist/modal/placement.d.ts",
+			"default": "./dist/modal/placement.js"
+		},
+		"./modal/certrev-cert.js": "./dist/modal/certrev-cert.js"
+	},
+	"files": [
+		"dist",
+		"src",
+		"!src/**/__tests__",
+		"!src/**/*.test.ts",
+		"!src/**/*.test.tsx",
+		"README.md",
+		"CHANGELOG.md"
+	],
+	"publishConfig": {
+		"registry": "https://registry.npmjs.org",
+		"access": "public"
+	},
+	"publishTargets": [
+		"npmjs",
+		"github-packages"
+	],
+	"scripts": {
+		"build": "tsc && pnpm build:modal-bundle",
+		"build:modal-bundle": "pnpm dlx esbuild@0.27.7 src/modal/certrev-cert.entry.ts --bundle --minify --target=es2020 --format=iife --legal-comments=none --tsconfig-raw='{\"compilerOptions\":{\"target\":\"ES2017\",\"module\":\"esnext\",\"strict\":true}}' --banner:js='/* biome-ignore-all format: generated cert-badge bundle, see @certrev/cert-block src/modal/ */ /* biome-ignore-all lint: generated cert-badge bundle, see @certrev/cert-block src/modal/ */' --outfile=dist/modal/certrev-cert.js",
+		"refresh:reader": "node scripts/refresh-reader.mjs",
+		"typecheck": "tsc --noEmit",
+		"test": "vitest run"
+	},
+	"dependencies": {
+		"@certrev/cert-contract": "^0.6.0"
+	},
+	"peerDependencies": {
+		"react": ">=18.0.0"
+	},
+	"peerDependenciesMeta": {
+		"react": {
+			"optional": false
+		}
+	},
+	"devDependencies": {
+		"@testing-library/react": "^16.1.0",
+		"@types/node": "^20.0.0",
+		"@types/react": "^18.3.0",
+		"@types/react-dom": "^18.3.0",
+		"jsdom": "^25.0.0",
+		"react": "^18.3.1",
+		"react-dom": "^18.3.1",
+		"typescript": "^6.0.3",
+		"vitest": "^4.1.5"
+	},
+	"keywords": [
+		"certrev",
+		"certification",
+		"react",
+		"server-components",
+		"hydrogen",
+		"shopify",
+		"json-ld",
+		"schema-org",
+		"web-component",
+		"ed25519",
+		"ssr"
+	],
+	"license": "MIT"
+}

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

@@ -25,6 +25,7 @@ import { type CertBlockMode, renderCertBlock } from '../components/render-cert-b
 import { CERT_STRINGS_VERSION, type ResolvedBlockTheme } from '../components/render-def.js'
 import { type CertPayload, renderVerdict } from '../contract/kernel.js'
 import {
+	type DeliveredFace,
 	type DesignPin,
 	getVerifiedDelivery,
 	parseDesignPin,
@@ -34,6 +35,14 @@ import {
 import { CARD_READER_CSS } from './card-reader-css.js'
 import type { BuilderCertChromeData, CertChromeRenderDef } from './cert-chrome-data.js'
 import { BUILDER_CERT_CHROME_KEYS } from './cert-chrome-data.js'
+import {
+	type DeliveredFaceHashes,
+	deliveredFaceDigest,
+	deliveredFaceHtml,
+	deliveredFaceMatches,
+	faceHashesFor,
+	showsWholeCard,
+} from './delivered-face.js'
 import { cardDeliveryRuntime } from './delivery-runtime.js'
 import { envelopeCardHtml, envelopeCardInput, isReaderFaceDef } from './envelope-face.js'
 import {
@@ -172,11 +181,25 @@ function suspendOn(key: string, start: () => Promise<VerifiedDelivery>): Verifie
 		pending = start().finally(() => inflightReads.delete(key))
 		inflightReads.set(key, pending)
 	}
-	const use = (React as unknown as { use?: <T>(p: Promise<T>) => T }).use
+	return suspendUntil(pending)
+}
+
+/** `use` where React has it (19), else the thrown promise (18). */
+function suspendUntil<T>(pending: Promise<T>): T {
+	const use = (React as unknown as { use?: <U>(p: Promise<U>) => U }).use
 	if (typeof use === 'function') return use(pending)
 	throw pending
 }
 
+/**
+ * 1.3.0: a delivered face's two digests, suspending once while WebCrypto computes them (`faceHashesFor` memoizes them
+ * by the face's content, so every later render of the same face, server or browser, reads them at once).
+ */
+function suspendOnFaceHashes(face: DeliveredFace): DeliveredFaceHashes | null {
+	const memo = faceHashesFor(face)
+	return memo.settled ? memo.settled.hashes : suspendUntil(memo.pending)
+}
+
 /**
  * 1.2.0-canary.6: the reader sidebar card is a right float that the article's copy flows around, as it does on a
  * WordPress or Shopify page. On a Builder page the card sits in its own block, a flex item of the flex column that holds
@@ -225,6 +248,8 @@ function EnvelopeFace(props: {
 	readonly html: string
 	readonly defVersion: number | undefined
 	readonly reader?: boolean
+	/** 1.3.0: the server-rendered face the signed digest binds (`DeliveredEnvelopeFace`); never with `reader`. */
+	readonly delivered?: boolean
 	/** The envelope seed (`ssr-seed.ts`): what a browser hydrating this face paints from, with no read of its own. */
 	readonly seed: string
 	/** 1.2.0, reader faces: told which person's photo the browser could not load (`ReaderEnvelopeFace`). */
@@ -270,8 +295,12 @@ function EnvelopeFace(props: {
 			data-certrev-strings-version={CERT_STRINGS_VERSION}
 			data-certrev-def-version={props.defVersion}
 			{...{ [SEED_ATTRIBUTE]: props.seed }}
-			{...(props.reader ? { 'data-certrev-face': 'reader', style: { display: 'flow-root' } } : {})}
-			// biome-ignore lint/security/noDangerouslySetInnerHtml: renderCertBlock is the escaping-safe SSR string renderer
+			{...(props.reader
+				? { 'data-certrev-face': 'reader', style: { display: 'flow-root' } }
+				: props.delivered
+					? { 'data-certrev-face': 'delivered' }
+					: {})}
+			// biome-ignore lint/security/noDangerouslySetInnerHtml: renderCertBlock is the escaping-safe SSR string renderer; a delivered face paints only when its bytes hash to the signed faceDigest
 			dangerouslySetInnerHTML={{ __html: props.html }}
 		/>,
 	)
@@ -340,6 +369,48 @@ function ReaderEnvelopeFace(props: {
 	)
 }
 
+/**
+ * 1.3.0: the delivered face this paint may use, or undefined (paint what 1.2.1 paints). Only for an unpinned card on a
+ * block that shows the whole card, a digest the verified content signs for the def's version, and a face whose UTF-8
+ * bytes hash to it (`delivered-face.ts`). Suspends once while WebCrypto hashes a face it has not seen.
+ */
+function deliveredFaceFor(
+	payload: CertPayload,
+	renderDef: CertChromeRenderDef | null,
+	face: DeliveredFace | undefined,
+	props: EnvelopeCardProps,
+): DeliveredFace | undefined {
+	if (!face || props.design || !showsWholeCard(props.part)) return undefined
+	const digest = deliveredFaceDigest(payload.content, renderDef, face)
+	if (!digest) return undefined
+	return deliveredFaceMatches(suspendOnFaceHashes(face), digest) ? face : undefined
+}
+
+/**
+ * 1.3.0: the delivered face, in the card's own wrapper (the same attributes as any envelope face, and
+ * `data-certrev-face="delivered"`): the server's stylesheet, then its markup. `seed` is the record that names it.
+ */
+function DeliveredEnvelopeFace(props: {
+	readonly face: DeliveredFace
+	readonly defVersion: number
+	readonly seed: string
+}) {
+	return <EnvelopeFace delivered html={deliveredFaceHtml(props.face)} defVersion={props.defVersion} seed={props.seed} />
+}
+
+/**
+ * 1.3.0: what a card hydrating a seed that names a delivered face renders when the browser's own check of that face
+ * fails (no WebCrypto: an insecure context; or bytes that do not hash to the seed's digest). The server painted the
+ * delivered face there, and the browser must not render that markup, so this adopts the server's element as it stands
+ * (no attribute or innerHTML compared: `suppressHydrationWarning`; no children hydrated: `dangerouslySetInnerHTML`)
+ * and paints nothing of its own. The render right after hydration (at the browser's clock) is another component, so
+ * React replaces this element with the face 1.2.1 paints for the seed.
+ */
+function ServerFaceUntilHydrated() {
+	// biome-ignore lint/security/noDangerouslySetInnerHtml: an empty string; it only stops React hydrating the server's children
+	return <div suppressHydrationWarning dangerouslySetInnerHTML={{ __html: '' }} />
+}
+
 /** Paint a verified payload with its def; null when the def and content give no face. */
 function paintEnvelope(
 	payload: CertPayload,
@@ -435,7 +506,16 @@ function paintRecord(
 				return null
 			}
 		}
-		return paintEnvelope(record.seed.payload, record.seed.renderDef, props, record.raw)
+		// 1.3.0: a seed that names a delivered face repaints it only after the browser hashes it against the seed
+		// payload's own digest; otherwise the seed paints what 1.2.1 paints for it.
+		const { seed } = record
+		const delivered = deliveredFaceFor(seed.payload, seed.renderDef, seed.face, props)
+		if (delivered && seed.renderDef) {
+			return <DeliveredEnvelopeFace face={delivered} defVersion={seed.renderDef.v} seed={record.raw} />
+		}
+		// Hydrating (not `judge`) over the delivered face the server painted, which the browser could not confirm.
+		if (seed.face && !judge) return <ServerFaceUntilHydrated />
+		return paintEnvelope(seed.payload, seed.renderDef, props, record.raw)
 	}
 	const html = record.fallback.face === 'options' ? fallbackFace(props) : null
 	return html === null ? (
@@ -587,6 +667,18 @@ function EnvelopeCertReviewCard(props: EnvelopeCardProps) {
 		signature: settled.signature,
 		renderDef: settled.renderDef,
 	})
+	// 1.3.0: the server-rendered face the Delivery API served beside the envelope, when its bytes hash to the digest the
+	// verified payload signs; the seed then carries it, so the browser can repaint (and re-check) the same face.
+	const delivered = deliveredFaceFor(seed.payload, seed.renderDef, settled.face, props)
+	if (delivered && seed.renderDef) {
+		return (
+			<DeliveredEnvelopeFace
+				face={delivered}
+				defVersion={seed.renderDef.v}
+				seed={serializeSeed({ ...seed, face: delivered })}
+			/>
+		)
+	}
 	return paintEnvelope(seed.payload, seed.renderDef, props, serializeSeed(seed))
 }
 

package/src/builder/delivered-face.ts

@@ -0,0 +1,142 @@
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ * The delivered face gate: when the Builder card may paint the server's markup (1.3.0)
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * The Delivery API may serve a server-rendered face (`face: { html, css }`) beside the signed artifact. That sibling
+ * is UNSIGNED. What binds it is the signed `payload.content.faceDigest` (cert-contract 0.6.0): the lowercase hex sha256
+ * of the markup's and the stylesheet's UTF-8 bytes, for one saved design version. The card paints the delivered face
+ * only when ALL of these hold:
+ *
+ *  - the verdict is `render` (the caller has already checked that);
+ *  - the card is not pinned (a design pin keeps 1.2.1's pinned face; the caller checks that);
+ *  - the block shows the whole card: `part` is not `'header'` or `'memo'`, so a split banner never paints the face
+ *    twice (`showsWholeCard`);
+ *  - the verified content carries a digest it understands (`v: 1`, two 64-char lowercase hex digests, a numeric
+ *    `defVersion`);
+ *  - a well-formed face was served;
+ *  - a def was served and its `v` IS the digest's `defVersion` (markup rendered for another design version is not
+ *    this design);
+ *  - sha256(html) and sha256(css) equal the signed values.
+ *
+ * In every other case the card paints exactly what 1.2.1 paints. Markup whose bytes do not hash to the signed digest
+ * is never painted, and a WebCrypto failure counts as a mismatch, never as a pass.
+ *
+ * Hashing uses WebCrypto (`crypto.subtle.digest`), the global the kernel verifies with, so it runs wherever the card
+ * already verifies (Node SSR, edge runtimes, a browser in a secure context). It is react-free; the card owns the
+ * suspension around the async digest.
+ */
+
+import type { CertContent, CertFaceDigest } from '../contract/kernel.js'
+import type { DeliveredFace } from '../verify/get-verified-delivery.js'
+import type { CertChromeRenderDef } from './cert-chrome-data.js'
+
+const SHA256_HEX = /^[0-9a-f]{64}$/
+
+/**
+ * Whether a block shows the whole card, by `renderCertBlock`'s own rule: only `'header'` and `'memo'` split the
+ * banner; absent, `'full'`, null or anything unrecognised is the full card. A split block keeps its own part even
+ * when a delivered face matches, because the delivered face is a whole design.
+ */
+export function showsWholeCard(part: unknown): boolean {
+	return part !== 'header' && part !== 'memo'
+}
+
+/** The signed digest, accepted only in the shape cert-contract 0.6.0 defines; anything else is null. */
+export function acceptedFaceDigest(content: CertContent | null | undefined): CertFaceDigest | null {
+	const digest: unknown = (content as { faceDigest?: unknown } | null | undefined)?.faceDigest
+	if (typeof digest !== 'object' || digest === null || Array.isArray(digest)) return null
+	const { v, defVersion, html, css } = digest as Record<string, unknown>
+	if (v !== 1 || typeof defVersion !== 'number' || !Number.isFinite(defVersion)) return null
+	if (typeof html !== 'string' || !SHA256_HEX.test(html)) return null
+	if (typeof css !== 'string' || !SHA256_HEX.test(css)) return null
+	return { v: 1, defVersion, html, css }
+}
+
+/**
+ * The synchronous half of the gate: the digest to hash the face against, or null when the delivered face cannot
+ * paint whatever its bytes are (no digest, no face, no def, or a def of another version). The card hashes only when
+ * this is non-null, so a delivery without a face never suspends a second time.
+ */
+export function deliveredFaceDigest(
+	content: CertContent | null | undefined,
+	renderDef: CertChromeRenderDef | null,
+	face: DeliveredFace | null | undefined,
+): CertFaceDigest | null {
+	if (!face) return null
+	const digest = acceptedFaceDigest(content)
+	if (!digest || !renderDef || renderDef.v !== digest.defVersion) return null
+	return digest
+}
+
+/** Lowercase hex sha256 of a string's UTF-8 bytes, via WebCrypto. */
+export async function sha256HexUtf8(text: string): Promise<string> {
+	const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text)))
+	let hex = ''
+	for (const byte of digest) hex += byte.toString(16).padStart(2, '0')
+	return hex
+}
+
+/** The two digests of a delivered face. */
+export interface DeliveredFaceHashes {
+	readonly html: string
+	readonly css: string
+}
+
+/** Hash both halves. Never rejects: a WebCrypto failure (none in an insecure context) is null, which never matches. */
+export async function hashDeliveredFace(face: DeliveredFace): Promise<DeliveredFaceHashes | null> {
+	try {
+		const [html, css] = await Promise.all([sha256HexUtf8(face.html), sha256HexUtf8(face.css)])
+		return { html, css }
+	} catch {
+		return null
+	}
+}
+
+/** The asynchronous half's verdict: both halves hash to the signed values. */
+export function deliveredFaceMatches(hashes: DeliveredFaceHashes | null, digest: CertFaceDigest): boolean {
+	return hashes !== null && hashes.html === digest.html && hashes.css === digest.css
+}
+
+/** The markup the card paints for a matching face: the stylesheet first, then the face. */
+export function deliveredFaceHtml(face: DeliveredFace): string {
+	return `<style>${face.css}</style>${face.html}`
+}
+
+/** One face's hashing: the pending digest, and its answer once settled. */
+export interface FaceHashMemo {
+	readonly pending: Promise<DeliveredFaceHashes | null>
+	settled?: { readonly hashes: DeliveredFaceHashes | null }
+}
+
+/** How many faces' hashes are kept (insertion order; the oldest goes first). A page or a brand has one or a few. */
+const FACE_HASH_MEMO_MAX = 64
+const faceHashMemo = new Map<string, FaceHashMemo>()
+
+/**
+ * The memoized hashing of one face, keyed by its CONTENT (both strings), not by the object: the browser parses a seed
+ * from the page afresh on each render, and a server's cached read and a seed of the same face share one entry. A
+ * failure settles to null and stays settled (a context with no WebCrypto does not gain one).
+ */
+export function faceHashesFor(face: DeliveredFace): FaceHashMemo {
+	const key = `${face.html.length}:${face.html}${face.css}`
+	const known = faceHashMemo.get(key)
+	if (known) return known
+	const fresh: FaceHashMemo = {
+		pending: hashDeliveredFace(face).then((hashes) => {
+			fresh.settled = { hashes }
+			return hashes
+		}),
+	}
+	if (faceHashMemo.size >= FACE_HASH_MEMO_MAX) {
+		const oldest = faceHashMemo.keys().next().value
+		if (oldest !== undefined) faceHashMemo.delete(oldest)
+	}
+	faceHashMemo.set(key, fresh)
+	return fresh
+}
+
+/** Test seam: forget every face's hashes (a new process). */
+export function forgetFaceHashesForTests(): void {
+	faceHashMemo.clear()
+}

package/src/builder/delivery-runtime.ts

@@ -18,6 +18,7 @@
 import type { ResolvePublicKeyByKid } from '../contract/kernel.js'
 import { TtlCache } from '../verify/cache.js'
 import type { CachedDelivery } from '../verify/get-verified-delivery.js'
+import { forgetFaceHashesForTests } from './delivered-face.js'
 import { CERT_ISSUER_KID, CERT_ISSUER_PUBLIC_KEY_PEM } from './issuer-key.js'
 import { forgetPageSeedsForTests } from './ssr-seed.js'
 
@@ -67,10 +68,11 @@ export function cardDeliveryRuntime(): CardDeliveryRuntime {
 
 /**
  * Test seam: replace parts of the runtime (a fresh cache unless one is given) and forget the page's envelope seeds
- * (a fresh runtime is a fresh page). Returns a restore.
+ * (a fresh runtime is a fresh page) and (1.3.0) every delivered face's memoized hashes. Returns a restore.
  */
 export function setCardDeliveryRuntimeForTests(overrides: Partial<CardDeliveryRuntime>): () => void {
 	forgetPageSeedsForTests()
+	forgetFaceHashesForTests()
 	const previous = runtime
 	const now = overrides.now ?? previous.now
 	runtime = {

package/src/builder/index.tsx

@@ -27,7 +27,10 @@
  * for the entry it renders inside (`builderContext.content.id`) from the CertREV Delivery API on
  * `baseUrl` (an https certrev.com origin, nothing else), verifies it against the baked
  * `cert-issuer-1` key, re-judges revocation and expiry at every render, and paints the brand's
- * render def served beside it. A revoked, expired, unverifiable or unreachable cert, a marker that
+ * render def served beside it. 1.3.0: when the Delivery API also serves a server-rendered face
+ * (`face: { html, css }`, unsigned) and the verified envelope signs that face's sha256 digests for the
+ * def version served (`content.faceDigest`), an unpinned whole-card block paints that face instead;
+ * markup that does not hash to the signed digest is never painted. A revoked, expired, unverifiable or unreachable cert, a marker that
  * is not exactly that shape, or a missing entry id renders nothing. A block WITHOUT the marker
  * (every entry exported before 1.1.0) renders from its options exactly as 1.0.3 did, so the
  * paragraph above still describes it: an editor who deletes the marker gets the options face back,

package/src/builder/ssr-seed.ts

@@ -48,13 +48,26 @@
  * 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.
  *
+ * A DELIVERED FACE RIDES THE SEED (1.3.0), and only when the server painted it: the seed then ends with
+ * `face: { html, css }`, the server-rendered markup and stylesheet the Delivery API served beside the envelope, whose
+ * hashes the signed `payload.content.faceDigest` binds. A browser repaints that face from the seed only after hashing
+ * it against the seed payload's digest itself (`cert-review-card.tsx`); a seed with no `face`, a malformed one, or one
+ * whose hashes fail paints what 1.2.1 paints for it. A seed with no face is byte for byte the 1.2.1 seed. The face is
+ * on the page twice (painted, and in the seed), which is its page-weight cost.
+ *
  * 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 DeliveredFace,
+	type DesignPin,
+	parseDeliveredFace,
+	parseDesignPin,
+	parseRenderDef,
+} from '../verify/get-verified-delivery.js'
 import type { CertChromeRenderDef } from './cert-chrome-data.js'
 
 export const SEED_ATTRIBUTE = 'data-certrev-envelope'
@@ -72,6 +85,11 @@ export interface DeliverySeed {
 	 */
 	readonly signature?: CertSignature
 	readonly renderDef: CertChromeRenderDef | null
+	/**
+	 * 1.3.0: the delivered face the server painted (the file header); absent whenever it painted anything else. On a
+	 * seed read from the page it is UNVERIFIED until hashed against `payload.content.faceDigest`.
+	 */
+	readonly face?: DeliveredFace
 }
 
 /** A seed as read from the page: the parsed seed and the attribute's exact text (re-rendered verbatim on hydration). */
@@ -183,6 +201,8 @@ export function serializeSeed(seed: DeliverySeed): string {
 		payload: seed.payload,
 		...(seed.signature ? { signature: seed.signature } : {}),
 		renderDef: seed.renderDef,
+		// 1.3.0: last, and only with a delivered face, so a seed without one is the 1.2.1 bytes.
+		...(seed.face ? { face: { html: seed.face.html, css: seed.face.css } } : {}),
 	})
 }
 
@@ -214,7 +234,7 @@ export function parseSeed(raw: string): DeliverySeed | null {
 		return null
 	}
 	if (!isRecord(value) || value.v !== 1) return null
-	const { baseUrl, externalId, design, payload, signature, renderDef } = value
+	const { baseUrl, externalId, design, payload, signature, renderDef, face } = value
 	if (typeof baseUrl !== 'string' || typeof externalId !== 'string') return null
 	if (!isRecord(payload) || !isRecord(payload.subject) || !isRecord(payload.lifecycle) || !isRecord(payload.content)) {
 		return null
@@ -222,6 +242,8 @@ export function parseSeed(raw: string): DeliverySeed | 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
+	// 1.3.0: a face that is not two strings is no face; the seed is still a seed (and paints as 1.2.1 paints it).
+	const delivered = parseDeliveredFace(face)
 	return {
 		baseUrl,
 		externalId,
@@ -229,6 +251,7 @@ export function parseSeed(raw: string): DeliverySeed | null {
 		payload: payload as unknown as CertPayload,
 		...(isRecord(signature) ? { signature: signature as unknown as CertSignature } : {}),
 		renderDef: parseRenderDef(renderDef),
+		...(delivered ? { face: delivered } : {}),
 	}
 }