@certrev/cert-block 1.3.0 → 2.0.0

package/src/reader/render.ts

@@ -1,6 +1,7 @@
 /**
  * ─────────────────────────────────────────────────────────────────────────────
- * `renderReaderFace` — the certrev.com "reader" face, as the Builder card paints it (1.2.0)
+ * `renderReaderFace` — the certrev.com "reader" face, as the Builder card paints it (1.2.0; caught up to the portal's
+ * one face in 1.3.1)
  * ─────────────────────────────────────────────────────────────────────────────
  *
  * The same markup, byte for byte, as the Shopify `certrev-reader-{banner,memo,sidebar,pill}` snippets, which are the
@@ -12,6 +13,17 @@
  * It is a NEW face, selected only by a delivered render def that says `face: 'reader'` (see `envelopeCardHtml`).
  * Nothing in the legacy `renderCertBlock` is read or changed here.
  *
+ * Since 1.3.1 it also follows the portal's ONE FACE, as the Shopify snippets and the WordPress plugin paint it:
+ *  - the def's `rung` (credentialed and named: no memo, bio or photo, so the memo card is not printed and the banner
+ *    and sidebar are the memo-less card; named: no credential either; minimal: the band and the links only; any other
+ *    value is the memo rung);
+ *  - the sidebar's phone fold: the bio and the memo are printed twice, once as the card's own pair and once inside a
+ *    closed `<details class="certrev-r-more">` (the stylesheet shows one or the other: 640px and under, the fold);
+ *  - a TONED def (an ink, or a surface that is not white) adds `certrev-r-toned` to the root and `--cr-sf` / `--cr-ink`
+ *    to its style (`tokens.ts`); a def with no design paints the memo-rung defaults;
+ *  - the banner's author takes the same 42px face as the reviewer, and the credential date never breaks
+ *    (`<span class="certrev-r-nw">`).
+ *
  * The facts are read exactly as the snippets read the same envelope:
  *  - the card renders only with a reviewer name (the memo and sidebar too); the pill needs only a verify URL;
  *  - the credential is each credential's `cardLabel` (else `abbreviation`), joined; the "Credential verified by CertREV"
@@ -55,7 +67,7 @@ import {
 	textOr,
 } from './helpers.js'
 import { readerLogo } from './logo.js'
-import { readerTokens } from './tokens.js'
+import { isTonedStyle, readerTokens } from './tokens.js'
 
 export type ReaderLayout = 'banner' | 'sidebar' | 'floating'
 
@@ -85,6 +97,8 @@ export interface ReaderFaceInput {
  */
 
 /** What every section of one render shares: the facts read once from the envelope and the def. */
+type Rung = 'memo' | 'credentialed' | 'named' | 'minimal'
+
 interface Facts {
 	readonly content: Rec
 	readonly expert: Rec
@@ -92,13 +106,20 @@ interface Facts {
 	readonly def: unknown
 	readonly certId: string
 	readonly ename: string
-	/** Whether a photo may be painted: neither `reviewerPhoto` hidden nor `showExpertPhoto: false`. */
+	/** The def's rung: `memo` unless it says `minimal`, `named` or `credentialed` (any other value is the memo rung). */
+	readonly rung: Rung
+	/** The minimal rung: the band and the links, nothing else. */
+	readonly minimal: boolean
+	/** Whether a photo may be painted: neither `reviewerPhoto` hidden nor `showExpertPhoto: false`, and the memo rung. */
 	readonly showPhoto: boolean
-	/** The joined credential labels, '' when there are none. */
+	/** The joined credential labels, '' when there are none or the rung shows none (named, minimal). */
 	readonly creds: string
 	readonly hasCue: boolean
 	readonly illus: boolean
-	readonly noMemo: boolean
+	/** Whether the memo is printed: there is one, and the rung is the memo rung. */
+	readonly hasMemo: boolean
+	/** Whether the root carries `certrev-r-toned` (the token style says so). */
+	readonly toned: boolean
 	readonly purl: string
 	readonly vurl: string
 	readonly style: string
@@ -112,7 +133,9 @@ function readFacts(input: ReaderFaceInput): Facts {
 	const def = input.def
 	const rd = rec(def)
 
-	const showPhoto = disp.showExpertPhoto !== false && !contains(rd.hidden, 'reviewerPhoto')
+	const rung: Rung = rd.rung === 'minimal' || rd.rung === 'named' || rd.rung === 'credentialed' ? rd.rung : 'memo'
+	const minimal = rung === 'minimal'
+	const showPhoto = disp.showExpertPhoto !== false && !contains(rd.hidden, 'reviewerPhoto') && rung === 'memo'
 
 	// POR-9738: each credential's cardLabel over its bare abbreviation, joined with ', ' (labels are not trimmed).
 	const labels: string[] = []
@@ -133,11 +156,14 @@ function readFacts(input: ReaderFaceInput): Facts {
 		def,
 		certId: asText(input.certId),
 		ename: textOr(expert.displayName),
+		rung,
+		minimal,
 		showPhoto,
-		creds: labels.join(', '),
+		creds: rung === 'named' || minimal ? '' : labels.join(', '),
 		hasCue,
 		illus: input.illustrative === true && !hasCue,
-		noMemo: isBlank(content.memo),
+		hasMemo: !isBlank(content.memo) && rung === 'memo',
+		toned: isTonedStyle(style),
 		purl: cleaned(safeUrl(expert.profileUrl)),
 		vurl: cleaned(safeUrl(content.verifyUrl)),
 		style,
@@ -147,7 +173,7 @@ function readFacts(input: ReaderFaceInput): Facts {
 
 /** The `<section>` open tag every reader section shares. `badge` is the `.certrev-badge` hook the revalidation reads. */
 function sectionOpen(f: Facts, badge: boolean, aria: string): string {
-	const cls = badge ? 'certrev-reader certrev-badge' : 'certrev-reader'
+	const cls = `certrev-reader${badge ? ' certrev-badge' : ''}${f.toned ? ' certrev-r-toned' : ''}`
 	// `{% if rd %}`: any def that is not nil/false stamps its version.
 	const version = isTruthy(f.def) ? ` data-certrev-def-version="${esc(rec(f.def).v)}"` : ''
 	return (
@@ -165,7 +191,7 @@ const anchor = (href: string, modal: string, label: string): string =>
  * name the wording stays one leaf.
  */
 function profileLabel(f: Facts): string {
-	const first = cleaned(firstName(f.ename))
+	const first = f.minimal ? '' : cleaned(firstName(f.ename))
 	return first !== '' ? `View <!-- -->${esc(first)}<!-- -->&rsquo;s profile` : 'View profile'
 }
 
@@ -194,15 +220,15 @@ const SCOPE = CERT_SCOPE_LINE
  * The muted credential line, empty when the reviewer has no displayed credential (so no "verified" claim prints).
  *
  * The banner's is the demo's three leaves in one `<em>`: the credential, " · ", and the attribution, which reads
- * "Credential verified by CertREV on {date}" or, with no date, just "Credential verified by CertREV". The spans carry
- * no style of their own. The sidebar names the credential in its bold line already, so its `<em>` is the attribution
- * alone.
+ * "Credential verified by CertREV on {date}" or, with no date, just "Credential verified by CertREV". The banner's date
+ * sits in its own `<span class="certrev-r-nw">`, which the stylesheet never lets break. The sidebar names the credential
+ * in its bold line already, so its `<em>` is the attribution alone, and its date is plain text.
  */
 function verifiedLine(f: Facts, withCredentials: boolean): string {
 	if (f.creds === '') return ''
 	const date = cleaned(isBlank(f.expert.credentialVerifiedAt) ? '' : longDate(f.expert.credentialVerifiedAt))
-	const on = date !== '' ? ` on ${esc(date)}` : ''
-	if (!withCredentials) return `<em>Credential verified by CertREV${on}</em>`
+	if (!withCredentials) return `<em>Credential verified by CertREV${date !== '' ? ` on ${esc(date)}` : ''}</em>`
+	const on = date !== '' ? ` on <span class="certrev-r-nw">${esc(date)}</span>` : ''
 	return `<em><span>${esc(f.creds)}</span> · <span>Credential verified by CertREV${on}</span></em>`
 }
 
@@ -215,24 +241,34 @@ function bannerCard(f: Facts): string {
 	const author = rec(f.content.author)
 	const authorName = textOr(author.name)
 	const authorTitle = textOr(author.title)
-	const hasAuthor = f.disp.showAuthor !== false && authorName !== '' && authorName !== f.ename
-	const avatar = (photo: unknown, name: string, size: 'sm' | ''): string =>
-		readerFace({ photo, show: f.showPhoto, name, size, width: 84 })
+	const hasAuthor = f.disp.showAuthor !== false && authorName !== '' && authorName !== f.ename && !f.minimal
+	// Both bylines take the same 42px face, photo or initials, at every width.
+	const avatar = (photo: unknown, name: string): string =>
+		readerFace({ photo, show: f.showPhoto, name, size: '', width: 84 })
 
 	const authorBy = hasAuthor
-		? `<div class="certrev-r-by">${avatar(author.photoUrl, authorName, 'sm')}<div>\n              <b>${esc(authorName)}</b>` +
+		? `<div class="certrev-r-by">${avatar(author.photoUrl, authorName)}<div>\n              <b>${esc(authorName)}</b>` +
 			`${authorTitle !== '' ? `<em>${esc(authorTitle)}</em>` : ''}<span class="certrev-r-role">Written by</span>\n            </div>\n          </div>`
 		: ''
 	const expertBy =
-		`<div class="certrev-r-by">${avatar(f.expert.photoUrl, f.ename, '')}<div>\n            <b>${esc(f.ename)}</b>` +
+		`<div class="certrev-r-by">${avatar(f.expert.photoUrl, f.ename)}<div>\n            <b>${esc(f.ename)}</b>` +
 		`${verifiedLine(f, true)}<span class="certrev-r-role on">Reviewed by</span>\n          </div>\n        </div>`
+	// The minimal rung is the band and the links: no bylines, no date, no cue, no scope line.
+	const bys = f.minimal
+		? ''
+		: `<div class="certrev-r-bys${hasAuthor ? '' : ' solo'}">${authorBy}${expertBy}\n      </div>`
 
 	const certifiedAt = f.content.certifiedAt
-	const certified = isBlank(certifiedAt) ? '' : cleaned(longDate(certifiedAt))
+	const certified = f.minimal || isBlank(certifiedAt) ? '' : cleaned(longDate(certifiedAt))
+	const hasCue = f.hasCue && !f.minimal
+	const illus = f.illus && !f.minimal
+	// Without a printed memo (none, or a rung that prints none) this card is the sole claim face and carries the scope line.
+	const noMemo = !f.hasMemo
+	const scopeOn = noMemo && !f.minimal
 
 	// A memo-less article gets the profile and certificate row, so the certificate stays reachable.
 	let links = ''
-	if (f.noMemo && (f.purl !== '' || f.vurl !== '')) {
+	if (noMemo && (f.purl !== '' || f.vurl !== '')) {
 		links =
 			'<div class="certrev-r-links">' +
 			(f.purl !== '' ? anchor(f.purl, '="expert"', profileLabel(f)) : '') +
@@ -240,8 +276,8 @@ function bannerCard(f: Facts): string {
 			'</div>'
 	}
 
-	const hasFoot = certified !== '' || f.hasCue || f.illus
-	const rule = hasFoot || f.noMemo ? '<div class="certrev-r-rule"></div>' : ''
+	const hasFoot = certified !== '' || hasCue || illus
+	const rule = hasFoot || scopeOn ? '<div class="certrev-r-rule"></div>' : ''
 
 	let foot = ''
 	if (hasFoot) {
@@ -249,29 +285,29 @@ function bannerCard(f: Facts): string {
 		// span paints the mono cue and the date's own face.
 		const when = certified !== '' ? `<span><em>Certified</em>${esc(certified)}</span>` : '<span></span>'
 		let cue = ''
-		if (f.hasCue) {
+		if (hasCue) {
 			// The locked cue in plain words, as the demo's foot (judge round 6, E1): no link, so nothing underlines
 			// "expert"; the reviewer's profile is the card's or the memo's "View … profile" link.
 			cue = `<span>${COMPENSATED_EXPERT_CUE}</span>`
-		} else if (f.illus) {
+		} else if (illus) {
 			cue = '<span>Illustrative example</span>'
 		}
 		foot = `<div class="certrev-r-foot">${when}${cue}</div>`
 	}
 
 	// POR-9317: the memo card carries the scope line when there is a memo; with none this card is the sole claim face.
-	const scope = f.noMemo ? `<div class="certrev-r-scope" data-ftc-disclosure data-ftc-line>${SCOPE}</div>` : ''
+	const scope = scopeOn ? `<div class="certrev-r-scope" data-ftc-disclosure data-ftc-line>${SCOPE}</div>` : ''
 
 	return (
-		`${sectionOpen(f, true, credentialAria(f))}\n  <div class="certrev-r-card">\n` +
-		`    <div class="certrev-r-cap">${readerLogo(f.fg === '#ffffff' ? 'white' : 'mono', 18, 'CertREV')}Expert reviewed &amp; certified</div>\n` +
-		`    <div class="certrev-r-cap-body">\n      <div class="certrev-r-bys${hasAuthor ? '' : ' solo'}">${authorBy}${expertBy}\n      </div>` +
+		`${sectionOpen(f, true, f.minimal ? 'Expert reviewed' : credentialAria(f))}\n  <div class="certrev-r-card">\n` +
+		`    <div class="certrev-r-cap">${readerLogo(f.fg === '#ffffff' ? 'white' : 'mono', 18, 'CertREV')}Expert reviewed${f.minimal ? '' : ' &amp; certified'}</div>\n` +
+		`    <div class="certrev-r-cap-body">\n      ${bys}` +
 		`${links}${rule}${foot}${scope}</div>\n  </div>\n</section>`
 	)
 }
 
 function bannerMemo(f: Facts): string {
-	if (f.ename === '' || isBlank(f.content.memo)) return ''
+	if (f.ename === '' || !f.hasMemo) return ''
 	const links =
 		f.purl !== '' || f.vurl !== ''
 			? '<div class="certrev-r-links">' +
@@ -298,8 +334,6 @@ function bannerMemo(f: Facts): string {
 
 function sidebar(f: Facts): string {
 	if (f.ename === '') return ''
-	const bio = f.disp.showBio !== false && !isBlank(f.expert.bio) ? asText(f.expert.bio) : ''
-	const avatar = readerFace({ photo: f.expert.photoUrl, show: f.showPhoto, name: f.ename, size: 'lg', width: 112 })
 	const both = f.purl !== '' && f.vurl !== ''
 	const links =
 		f.purl !== '' || f.vurl !== ''
@@ -308,13 +342,28 @@ function sidebar(f: Facts): string {
 				(f.vurl !== '' ? anchor(f.vurl, '', 'View Certificate') : '') +
 				'</div>'
 			: ''
+	const open =
+		`${sectionOpen(f, true, f.minimal ? 'Expert reviewed' : credentialAria(f))}\n  <div class="certrev-r-side">\n` +
+		`    <div class="certrev-r-cap center">${readerLogo(f.fg === '#ffffff' ? 'white' : 'mono', 18, 'CertREV')}Expert reviewed</div>\n    `
+	// The minimal rung is the band and the links: no body at all.
+	if (f.minimal) return `${open}${links}</div>\n</section>`
+
+	const bio = f.disp.showBio !== false && !isBlank(f.expert.bio) && f.rung === 'memo' ? asText(f.expert.bio) : ''
+	const avatar = readerFace({ photo: f.expert.photoUrl, show: f.showPhoto, name: f.ename, size: 'lg', width: 112 })
+	// The bio and the memo are printed twice: as the card's own pair, and again inside a closed <details> the stylesheet
+	// shows instead on a phone (640px and under; owner decision 3d0838a4, plugin 1.8.3). The disclosure and both links
+	// stay outside the fold. With no memo the toggle says "About the expert"; with neither bio nor memo there is no fold.
+	const fold =
+		`${bio !== '' ? `<p>${esc(bio)}</p>` : ''}` +
+		`${f.hasMemo ? `<blockquote>${esc(f.content.memo)}</blockquote>` : ''}`
+	const more =
+		fold !== ''
+			? `<details class="certrev-r-more"><summary>${f.hasMemo ? 'Read the expert memo' : 'About the expert'}</summary>${fold}</details>`
+			: ''
 	return (
-		`${sectionOpen(f, true, credentialAria(f))}\n  <div class="certrev-r-side">\n` +
-		`    <div class="certrev-r-cap center">${readerLogo(f.fg === '#ffffff' ? 'white' : 'mono', 18, 'CertREV')}Expert reviewed</div>\n` +
-		`    <div class="certrev-r-side-body">\n      <div class="certrev-r-by">${avatar}<div>\n` +
+		`${open}<div class="certrev-r-side-body">\n      <div class="certrev-r-by">${avatar}<div>\n` +
 		`          <b>${esc(f.ename)}${f.creds !== '' ? `<!-- -->, <!-- -->${esc(f.creds)}` : ''}</b>${verifiedLine(f, false)}</div>\n      </div>` +
-		`${bio !== '' ? `<p>${esc(bio)}</p>` : ''}` +
-		`${isBlank(f.content.memo) ? '' : `<blockquote>${esc(f.content.memo)}</blockquote>`}` +
+		`${fold}${more}` +
 		`<div class="certrev-r-scope" data-ftc-disclosure data-ftc-line>${scopeLead(f)}${SCOPE}</div>\n    </div>` +
 		`${links}</div>\n</section>`
 	)

package/src/reader/tokens.ts

@@ -1,24 +1,32 @@
 /**
- * `certrev-reader-tokens`: the four CSS custom properties a reader section carries on its root, from the render def.
+ * `certrev-reader-tokens`: the CSS custom properties a reader section carries on its root, from the render def.
  *
  *   --cr-ba     the accent the card cap and pill paint: the def's `barInk`, else its `accentColor`, else navy
  *   --cr-ba-fg  the ink on that accent: white, or `#141414` when the def baked it for the colour that painted
  *   --cr-br     the corner radius
  *   --cr-bf     the font stack for the brand's `fontSlot`
+ *   --cr-sf     (toned face only) the card surface, the def's `surface`
+ *   --cr-ink    (toned face only) the card ink, the def's `inkColor`
  *
  * The values land inside a double-quoted `style` attribute, and they are held to the allow-list the Liquid snippet and
  * the PHP twin's def parser hold them to: a colour is `#RGB` or `#RRGGBB`, a radius one non-negative px / rem / em / %
- * length or a bare `0`, and anything else paints the default (navy, 14px). A denylist of characters is not enough: a
+ * length or a bare `0`, and anything else paints the default (navy `#0a1b3f`, 12px: the design guide's memo-rung
+ * defaults, as the plugin and the hosted embed paint a face with no design). A denylist of characters is not enough: a
  * quote, a backslash, a comment opener or a bracket left in a value hides the `;` that ends it and swallows the
  * declarations after it. The variable names are the reader stylesheet's (`reader.css`), which `.certrev-reader`
  * declares defaults for.
+ *
+ * A face is TONED when the def sets an ink, or a surface that is not white (`#fff` / `#ffffff`, either case): only
+ * then are `--cr-sf` / `--cr-ink` written (each only when valid), and the section root gains `certrev-r-toned`
+ * (`isTonedStyle`, which reads the style string as the snippets do).
  */
 import { asText } from '../components/escape.js'
 import { esc, rec, textOr } from './helpers.js'
 
-/** The accent when the def has none: CertREV navy. */
-const DEFAULT_ACCENT = '#0A1B3F'
-const DEFAULT_RADIUS = '14px'
+/** The accent when the def has none: the design guide's memo-rung default (CertREV navy). */
+const DEFAULT_ACCENT = '#0a1b3f'
+/** The corner when the def has none: the design guide's memo-rung default. */
+const DEFAULT_RADIUS = '12px'
 /** The foreground the def bakes for a light accent; anything else is the white default. */
 const DARK_INK = '#141414'
 
@@ -71,6 +79,9 @@ export interface ReaderTokens {
 	readonly fg: string
 }
 
+/** Whether a root `style` is a toned face's: the snippets' `cr_style contains ';--cr-sf:' or ';--cr-ink:'`. */
+export const isTonedStyle = (style: string): boolean => style.includes(';--cr-sf:') || style.includes(';--cr-ink:')
+
 export function readerTokens(def: unknown): ReaderTokens {
 	const rd = rec(def)
 	const tokens = rec(rd.tokens)
@@ -90,5 +101,17 @@ export function readerTokens(def: unknown): ReaderTokens {
 
 	const br = radius(tokens.cornerRadius) || DEFAULT_RADIUS
 	const bf = fontStack(asText(tokens.fontSlot))
-	return { style: `--cr-ba:${esc(ba)};--cr-ba-fg:${fg};--cr-br:${esc(br)};--cr-bf:${bf}`, fg }
+
+	// A toned face: an ink, or a surface that is not white. `downcase` in the snippet; the digits are ASCII.
+	const surface = hexColour(tokens.surface)
+	const ink = hexColour(tokens.inkColor)
+	const surfaceLc = surface.toLowerCase()
+	const toned = ink !== '' || (surface !== '' && surfaceLc !== '#fff' && surfaceLc !== '#ffffff')
+
+	let style = `--cr-ba:${esc(ba)};--cr-ba-fg:${fg};--cr-br:${esc(br)};--cr-bf:${bf}`
+	if (toned) {
+		if (surface !== '') style += `;--cr-sf:${esc(surface)}`
+		if (ink !== '') style += `;--cr-ink:${esc(ink)}`
+	}
+	return { style, fg }
 }

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

@@ -42,9 +42,18 @@
  * 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`).
+ *
+ * 2.0.0: the response may also carry the contract-1 CARD DOCUMENT as a third UNSIGNED sibling, `card` (CertREV's portal
+ * serves it only for a brand on contract 1). It is kept exactly as served when it is a JSON object (any other value,
+ * `null` included, is no card), cached beside the payload, and handed out only on a `render` verdict. Like `face`,
+ * NOTHING HERE VOUCHES FOR IT: the signed `payload.content.faceDigest` binds it (`contract: 1`, `doc`), and the Builder
+ * card prints it only after its shape check and digest check pass (`src/builder/card-contract.ts`). A read with no
+ * card is the 1.3.1 object exactly. The read is made with `credentials: 'omit'`: it never sends a cookie.
  */
 
+import { cardDocumentDigest } from '../builder/card-contract.js'
 import type { CertChromeRenderDef } from '../builder/cert-chrome-data.js'
+import { type DeliveredFaceHashes, hashDeliveredFace } from '../builder/delivered-face.js'
 import type {
 	CertDeliveryArtifact,
 	CertPayload,
@@ -81,6 +90,16 @@ export type CachedDelivery =
 			readonly signature?: CertSignature
 			/** 1.3.0: the unsigned face sibling, when the response carried a well-formed one; else absent. */
 			readonly face?: DeliveredFace
+			/** 2.0.0: the unsigned card-document sibling as served, when it was a JSON object; else absent. */
+			readonly card?: Readonly<Record<string, unknown>>
+			/**
+			 * 2.0.0: the digest of `card` (lowercase hex sha256 of its RFC 8785 bytes; null when it cannot be computed),
+			 * computed once by the read that cached it; present whenever `card` is. UNVERIFIED like the card: the caller
+			 * compares it with the signed binding.
+			 */
+			readonly cardDigest?: string | null
+			/** 2.0.0: the two hashes of `face`, computed once by the read; present whenever `face` is (null: no WebCrypto). */
+			readonly faceHashes?: DeliveredFaceHashes | null
 	  }
 	| {
 			readonly kind: 'suppressed'
@@ -103,6 +122,16 @@ export interface VerifiedDelivery {
 	 * well-formed one; else undefined (never on a suppress verdict). UNVERIFIED: see `DeliveredFace`.
 	 */
 	readonly face?: DeliveredFace
+	/**
+	 * 2.0.0: on a `render` verdict, the card document served beside the artifact (a JSON object, exactly as served);
+	 * else undefined. UNVERIFIED: print it only after `parseCardDocument` and the digest check of
+	 * `src/builder/card-contract.ts`, against the verified payload's `faceDigest`.
+	 */
+	readonly card?: Readonly<Record<string, unknown>>
+	/** 2.0.0: `card`'s digest as the read computed it, beside `card`; see `CachedDelivery`. */
+	readonly cardDigest?: string | null
+	/** 2.0.0: `face`'s hashes as the read computed them, beside `face`; see `CachedDelivery`. */
+	readonly faceHashes?: DeliveredFaceHashes | null
 }
 
 export interface GetVerifiedDeliveryOptions {
@@ -273,7 +302,7 @@ async function loadDelivery(opts: GetVerifiedDeliveryOptions): Promise<CachedDel
 		res = await fetchWithDeadline(
 			fetchImpl,
 			deliveryUrl(opts.baseUrl, opts.platform, opts.externalId, opts.design),
-			{ headers: { accept: 'application/json' } },
+			{ headers: { accept: 'application/json' }, credentials: 'omit' },
 			opts.timeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS,
 		)
 	} catch {
@@ -304,12 +333,19 @@ async function loadDelivery(opts: GetVerifiedDeliveryOptions): Promise<CachedDel
 	// 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)
+	const card = isRecord(body.card) ? body.card : undefined
+	// 2.0.0: the digests a render compares with the signed binding, computed here, once per read, so a render that waited
+	// for this read never waits a second time. Under React 19, `use` matches promises by their order in a render: a
+	// second suspension (on a digest) after the first (on this read) was handed this read's result, and the card failed.
+	const cardDigest = card ? await cardDocumentDigest(card) : undefined
+	const faceHashes = face ? await hashDeliveredFace(face) : undefined
 	return {
 		kind: 'verified',
 		payload: verdict.payload,
 		renderDef: parseRenderDef(body.renderDef),
 		...(signature ? { signature } : {}),
-		...(face ? { face } : {}),
+		...(face ? { face, faceHashes } : {}),
+		...(card ? { card, cardDigest } : {}),
 	}
 }
 
@@ -329,6 +365,9 @@ export function settleDelivery(cached: CachedDelivery, context: RenderContext):
 		renderDef: cached.renderDef,
 		...(cached.signature ? { signature: cached.signature } : {}),
 		...(cached.face ? { face: cached.face } : {}),
+		...(cached.faceHashes !== undefined ? { faceHashes: cached.faceHashes } : {}),
+		...(cached.card ? { card: cached.card } : {}),
+		...(cached.cardDigest !== undefined ? { cardDigest: cached.cardDigest } : {}),
 	}
 }
 

package/src/verify/key-set.ts

@@ -0,0 +1,225 @@
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ * The issuer key SET a card trusts (2.0.0): baked keys first, then CertREV's signed published set
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * Through 1.3.x the Builder card trusted exactly one baked key (`cert-issuer-1`), so a key rotation would have needed
+ * every brand to install a new package. 2.0 trusts a SET without adding a trust root:
+ *
+ *  1. A kid the package bakes resolves to the baked key, always (a published set never overrides a baked key).
+ *  2. Any other kid makes ONE read of the delivery origin's published key set, `GET <origin>/api/cert/v1/keys`
+ *     (`credentials: 'omit'`, the card's deadline): a browser reads it at most once per page and origin, a server at
+ *     most once per origin per hour (single-flight, a failure remembered for ten minutes).
+ *  3. The set is accepted only when it is signed by a BAKED kid, over the RFC 8785 bytes of exactly this object:
+ *
+ *       { kind: 'certrev.keyset', v: 1, issuedAt, keys: [{ kid, crv: 'Ed25519', x }] }     (x: base64url, 32 bytes)
+ *
+ *     answered as `{ keyset, signature: { alg: 'ed25519', kid, sig, signedAt? } }`. Refused: another `kind` or `v`
+ *     (an envelope, a tombstone or a release record can never verify as a key set: their signed bytes are other
+ *     objects), a set whose `issuedAt` is older than the one already accepted from that origin (no rollback), a set
+ *     whose keys do not hold its signer's kid with the same key (it may not drop or replace the key that vouches for
+ *     it), a malformed key, a signature that does not verify.
+ *  4. Anything else (no route, a network error, a refused set) leaves the kid unknown: the kernel suppresses the
+ *     envelope with `unknown_key`, so the card renders nothing and reports, exactly as for an unknown kid in 1.3.x.
+ *
+ * The route is the portal's (ADR 0001 section 3 addendum). Today every envelope is signed by the baked
+ * `cert-issuer-1`, so step 2 never runs and nothing is fetched.
+ */
+
+import {
+	base64urlDecode,
+	canonicalBytes,
+	type Ed25519PublicKeyInput,
+	importEd25519PublicKey,
+	type ResolvePublicKeyByKid,
+} from '../contract/kernel.js'
+import { TtlCache } from './cache.js'
+import { DEFAULT_FETCH_TIMEOUT_MS, fetchWithDeadline } from './fetch-with-deadline.js'
+
+/** Where an origin publishes its key set. */
+export const KEY_SET_PATH = '/api/cert/v1/keys'
+
+/** The signed object, exactly as the portal canonicalizes and signs it. */
+export interface PublishedKeySet {
+	readonly kind: 'certrev.keyset'
+	readonly v: 1
+	readonly issuedAt: string
+	readonly keys: ReadonlyArray<{ readonly kid: string; readonly crv: 'Ed25519'; readonly x: string }>
+}
+
+/** An accepted set: the keys it publishes, and when it was issued (for the no-rollback rule). */
+export interface AcceptedKeySet {
+	readonly issuedAt: number
+	readonly keys: ReadonlyMap<string, Ed25519PublicKeyInput>
+}
+
+const ED25519 = { name: 'Ed25519' } as const
+
+const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v)
+const isString = (v: unknown): v is string => typeof v === 'string'
+
+function rawKey(x: unknown): Uint8Array | null {
+	if (!isString(x) || !/^[A-Za-z0-9_-]+$/.test(x)) return null
+	try {
+		const bytes = base64urlDecode(x)
+		return bytes.length === 32 ? bytes : null
+	} catch {
+		return null
+	}
+}
+
+/** Ed25519 verify under a declared key or an imported one; any failure (a bad key, no WebCrypto Ed25519) is false. */
+async function verifies(key: Ed25519PublicKeyInput | CryptoKey, sig: Uint8Array, bytes: Uint8Array): Promise<boolean> {
+	try {
+		const imported = 'format' in (key as object) ? await importEd25519PublicKey(key as Ed25519PublicKeyInput) : key
+		// Fresh ArrayBuffer-backed copies: WebCrypto's BufferSource excludes a SharedArrayBuffer view.
+		return await crypto.subtle.verify(ED25519, imported as CryptoKey, new Uint8Array(sig), new Uint8Array(bytes))
+	} catch {
+		return false
+	}
+}
+
+/**
+ * Judge one key-set response body against the baked keys (and the set already accepted from the same origin, for
+ * the no-rollback rule). Returns the accepted set, or null. Never throws.
+ */
+export async function verifyKeySet(
+	body: unknown,
+	bakedResolveKid: ResolvePublicKeyByKid,
+	previous?: AcceptedKeySet,
+): Promise<AcceptedKeySet | null> {
+	if (!isRecord(body) || !isRecord(body.keyset) || !isRecord(body.signature)) return null
+	const { keyset, signature } = body
+	if (keyset.kind !== 'certrev.keyset' || keyset.v !== 1) return null
+	if (!isString(keyset.issuedAt)) return null
+	const issuedAt = Date.parse(keyset.issuedAt)
+	if (!Number.isFinite(issuedAt)) return null
+	if (previous && issuedAt < previous.issuedAt) return null
+	if (!Array.isArray(keyset.keys) || keyset.keys.length === 0) return null
+	if (signature.alg !== 'ed25519' || !isString(signature.kid) || !isString(signature.sig)) return null
+
+	// The signer must be a kid this package bakes.
+	let baked: Ed25519PublicKeyInput | CryptoKey | null | undefined
+	try {
+		baked = await bakedResolveKid(signature.kid)
+	} catch {
+		return null
+	}
+	if (!baked) return null
+
+	const keys = new Map<string, Ed25519PublicKeyInput>()
+	for (const entry of keyset.keys) {
+		if (!isRecord(entry) || !isString(entry.kid) || entry.kid === '' || entry.crv !== 'Ed25519') return null
+		const bytes = rawKey(entry.x)
+		if (!bytes || keys.has(entry.kid)) return null
+		keys.set(entry.kid, { format: 'raw', bytes })
+	}
+	// The set must keep the key that signed it.
+	const signerEntry = keys.get(signature.kid)
+	if (!signerEntry) return null
+
+	let sig: Uint8Array
+	let bytes: Uint8Array
+	try {
+		sig = base64urlDecode(signature.sig)
+		bytes = canonicalBytes(keyset)
+	} catch {
+		return null
+	}
+	if (!(await verifies(baked, sig, bytes))) return null
+	// ... and publish it as the same key: the signature must verify under the published entry too.
+	if (!(await verifies(signerEntry, sig, bytes))) return null
+	return { issuedAt, keys }
+}
+
+export interface KeySetResolverOptions {
+	/** The delivery origin the card reads (the marker's `baseUrl`). */
+	readonly baseUrl: string
+	/** The baked kids (the package's own trust root). */
+	readonly bakedResolveKid: ResolvePublicKeyByKid
+	readonly fetchImpl: typeof fetch
+	readonly timeoutMs?: number
+}
+
+/** What one origin's published set settled to: accepted, or nothing (unknown kid). */
+type Loaded = AcceptedKeySet | null
+
+/** Server: one read per origin per hour, a failure remembered for ten minutes (single-flight across renders). */
+const serverSets = new TtlCache<Loaded>({ ttlMs: 3_600_000, negativeTtlMs: 600_000, maxEntries: 50 })
+/** Browser: one read per origin for the page's lifetime, whatever it settled to. */
+const pageSets = new Map<string, Promise<Loaded>>()
+/** The newest set accepted per origin (both runtimes), for the no-rollback rule. */
+const acceptedSets = new Map<string, AcceptedKeySet>()
+
+function originOf(baseUrl: string): string | null {
+	try {
+		return new URL(baseUrl).origin
+	} catch {
+		return null
+	}
+}
+
+async function loadKeySet(origin: string, opts: KeySetResolverOptions): Promise<Loaded> {
+	let res: Response
+	try {
+		res = await fetchWithDeadline(
+			opts.fetchImpl,
+			`${origin}${KEY_SET_PATH}`,
+			{ headers: { accept: 'application/json' }, credentials: 'omit' },
+			opts.timeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS,
+		)
+	} catch {
+		return acceptedSets.get(origin) ?? null
+	}
+	if (!res.ok) return acceptedSets.get(origin) ?? null
+	let body: unknown
+	try {
+		body = await res.json()
+	} catch {
+		return acceptedSets.get(origin) ?? null
+	}
+	const previous = acceptedSets.get(origin)
+	const accepted = await verifyKeySet(body, opts.bakedResolveKid, previous)
+	// A refused set (older, unsigned, malformed) never replaces one this origin already proved.
+	if (!accepted) return previous ?? null
+	acceptedSets.set(origin, accepted)
+	return accepted
+}
+
+function publishedSet(origin: string, opts: KeySetResolverOptions): Promise<Loaded> {
+	if (typeof document !== 'undefined') {
+		let pending = pageSets.get(origin)
+		if (!pending) {
+			pending = loadKeySet(origin, opts)
+			pageSets.set(origin, pending)
+		}
+		return pending
+	}
+	return serverSets.getOrLoad(
+		origin,
+		() => loadKeySet(origin, opts),
+		(v) => v === null,
+	)
+}
+
+/**
+ * The resolver a card verifies with: the baked kids, then (for any other kid) the origin's published, signed set.
+ * Never throws; an unresolved kid is null (`unknown_key`).
+ */
+export function keySetResolver(opts: KeySetResolverOptions): ResolvePublicKeyByKid {
+	return async (kid) => {
+		const baked = await opts.bakedResolveKid(kid)
+		if (baked) return baked
+		const origin = originOf(opts.baseUrl)
+		if (!origin) return null
+		const set = await publishedSet(origin, opts)
+		return set?.keys.get(kid) ?? null
+	}
+}
+
+/** Test seam: forget every published set (a new page and process). */
+export function forgetKeySetsForTests(): void {
+	serverSets.clear()
+	pageSets.clear()
+	acceptedSets.clear()
+}