@certrev/cert-block 1.2.1 → 2.0.0

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

@@ -36,9 +36,24 @@
  * 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`).
+ *
+ * 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,
@@ -52,6 +67,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 +88,18 @@ 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
+			/** 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'
@@ -80,6 +117,21 @@ 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
+	/**
+	 * 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 {
@@ -230,6 +282,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
@@ -238,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 {
@@ -259,8 +323,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 +332,20 @@ 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)
+	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, faceHashes } : {}),
+		...(card ? { card, cardDigest } : {}),
 	}
 }
 
@@ -287,7 +360,15 @@ 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 } : {}),
+		...(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()
+}