@certrev/cert-block 1.2.1 → 1.3.0

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 } : {}),
 	}
 }
 

package/src/index.ts

@@ -106,6 +106,7 @@ export {
 	type CertCredential,
 	type CertDeliveryEnvelope,
 	type CertDisplayConfig,
+	type CertFaceDigest,
 	type CertLifecycle,
 	type CertPayload,
 	type CertSignature,
@@ -135,6 +136,7 @@ export {
 export { TtlCache, type TtlCacheOptions } from './verify/cache.js'
 export {
 	type CachedDelivery,
+	type DeliveredFace,
 	type DesignPin,
 	deliveryCacheKey,
 	deliveryUrl,
@@ -142,6 +144,7 @@ export {
 	type GetVerifiedDeliveryOptions,
 	getVerifiedDelivery,
 	invalidateDelivery,
+	parseDeliveredFace,
 	parseDesignPin,
 	parseRenderDef,
 	peekVerifiedDelivery,

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

@@ -36,6 +36,12 @@
  * 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.
+ *
+ * 1.3.0: the response may also carry a server-rendered face as a second UNSIGNED sibling, `face: { html, css }`. It is
+ * read the way `renderDef` is (shape-checked, malformed is dropped, never read unless the artifact verified) and cached
+ * beside it, and `settleDelivery` hands it out only on a `render` verdict. NOTHING HERE VOUCHES FOR IT: the signature
+ * does not cover it. What binds it is the signed `payload.content.faceDigest` (cert-contract 0.6.0), and a caller
+ * paints it only after hashing it against that digest, as the Builder card does (`src/builder/delivered-face.ts`).
  */
 
 import type { CertChromeRenderDef } from '../builder/cert-chrome-data.js'
@@ -52,6 +58,16 @@ import { renderVerdict, verifyArtifact } from '../contract/kernel.js'
 import { TtlCache } from './cache.js'
 import { DEFAULT_FETCH_TIMEOUT_MS, fetchWithDeadline } from './fetch-with-deadline.js'
 
+/**
+ * 1.3.0: the server-rendered face the Delivery API may serve beside the artifact. UNSIGNED and UNVERIFIED as carried
+ * here: paint it only when sha256 of each half's UTF-8 bytes equals the signed `payload.content.faceDigest`, and the
+ * digest's `defVersion` is the def served with it.
+ */
+export interface DeliveredFace {
+	readonly html: string
+	readonly css: string
+}
+
 /**
  * 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.
@@ -63,6 +79,8 @@ export type CachedDelivery =
 			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
+			/** 1.3.0: the unsigned face sibling, when the response carried a well-formed one; else absent. */
+			readonly face?: DeliveredFace
 	  }
 	| {
 			readonly kind: 'suppressed'
@@ -80,6 +98,11 @@ export interface VerifiedDelivery {
 	readonly signature?: CertSignature
 	/** 1.2.0: on a suppress verdict, true when CertREV was not reached; else undefined. */
 	readonly unreachable?: true
+	/**
+	 * 1.3.0: on a `render` verdict, the server-rendered face served beside the artifact, when the response carried a
+	 * well-formed one; else undefined (never on a suppress verdict). UNVERIFIED: see `DeliveredFace`.
+	 */
+	readonly face?: DeliveredFace
 }
 
 export interface GetVerifiedDeliveryOptions {
@@ -230,6 +253,18 @@ export function parseRenderDef(value: unknown): CertChromeRenderDef | null {
 	}
 }
 
+/**
+ * 1.3.0: the face sibling, shape-checked: an object whose `html` and `css` are both strings, copied to exactly those
+ * two keys. Anything else is null, and the card paints exactly what it paints with no face. The markup is NOT judged
+ * here; the signed digest judges it at paint time.
+ */
+export function parseDeliveredFace(value: unknown): DeliveredFace | null {
+	if (!isRecord(value)) return null
+	const { html, css } = value
+	if (!isString(html) || !isString(css)) return null
+	return { html, css }
+}
+
 /** Fetch, parse and cryptographically verify one Delivery response. Never throws. */
 async function loadDelivery(opts: GetVerifiedDeliveryOptions): Promise<CachedDelivery> {
 	const fetchImpl = opts.fetchImpl ?? globalThis.fetch
@@ -259,8 +294,8 @@ async function loadDelivery(opts: GetVerifiedDeliveryOptions): Promise<CachedDel
 	let verdict: CertVerdict
 	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.
+		// `payload` + `signature` (or the tombstone's own fields); the `renderDef` and (1.3.0) `face`
+		// siblings are not part of what is verified, and are never read unless the artifact verified.
 		verdict = await verifyArtifact(body as unknown as CertDeliveryArtifact, opts.resolveKid, { ...opts.context })
 	} catch {
 		return suppressed('unknown_key')
@@ -268,11 +303,13 @@ async function loadDelivery(opts: GetVerifiedDeliveryOptions): Promise<CachedDel
 	if (verdict.decision !== 'render') return suppressed(verdict.reason)
 	// 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
+	const face = parseDeliveredFace(body.face)
 	return {
 		kind: 'verified',
 		payload: verdict.payload,
 		renderDef: parseRenderDef(body.renderDef),
 		...(signature ? { signature } : {}),
+		...(face ? { face } : {}),
 	}
 }
 
@@ -287,7 +324,12 @@ export function settleDelivery(cached: CachedDelivery, context: RenderContext):
 	}
 	const verdict = renderVerdict(cached.payload, context)
 	if (verdict.decision !== 'render') return { verdict, renderDef: null }
-	return { verdict, renderDef: cached.renderDef, ...(cached.signature ? { signature: cached.signature } : {}) }
+	return {
+		verdict,
+		renderDef: cached.renderDef,
+		...(cached.signature ? { signature: cached.signature } : {}),
+		...(cached.face ? { face: cached.face } : {}),
+	}
 }
 
 /**