@certrev/cert-block 2.0.0 → 2.0.1

package/src/builder/delivery-runtime.ts

@@ -24,6 +24,7 @@ import type { ResolvePublicKeyByKid } from '../contract/kernel.js'
 import { TtlCache } from '../verify/cache.js'
 import type { CachedDelivery } from '../verify/get-verified-delivery.js'
 import { forgetKeySetsForTests, keySetResolver } from '../verify/key-set.js'
+import { setCardBeaconForTests } from './card-beacon.js'
 import { forgetCardDigestsForTests } from './card-contract.js'
 import { forgetCardReportsForTests } from './card-report.js'
 import { forgetFaceHashesForTests } from './delivered-face.js'
@@ -32,8 +33,17 @@ import { forgetPageSeedsForTests } from './ssr-seed.js'
 
 /** The card's server read deadline. A brand's server waits this long once per cold placement. */
 export const CARD_DELIVERY_TIMEOUT_MS = 8_000
-/** How long past its 60s TTL a certificate may still paint while it is refreshed or CertREV is down. */
-export const CARD_DELIVERY_STALE_MS = 300_000
+/**
+ * 2.0.1: how long a verified answer is fresh. With the stale window below, a card adds at most one minute to the Delivery
+ * API's own cache (`max-age=60, stale-while-revalidate=240`), so a revoked card is gone within ADR 0001 §7's five to
+ * six minutes (2.0.0's 60 s + 300 s here stacked to about twelve).
+ */
+export const CARD_DELIVERY_TTL_MS = 30_000
+/**
+ * How long past its TTL a certificate may still paint while it is refreshed or CertREV is down (2.0.1: 30 s; 2.0.0:
+ * 300 s). Never longer: past it, a read that cannot reach CertREV prints nothing.
+ */
+export const CARD_DELIVERY_STALE_MS = 30_000
 
 export interface CardDeliveryRuntime {
 	/** The baked kids: the package's own trust root (and the only keys that may sign a published key set). */
@@ -54,7 +64,7 @@ const bakedResolveKid: ResolvePublicKeyByKid = (kid) =>
 
 function newCardCache(now?: () => number): TtlCache<CachedDelivery> {
 	return new TtlCache<CachedDelivery>({
-		ttlMs: 60_000,
+		ttlMs: CARD_DELIVERY_TTL_MS,
 		negativeTtlMs: 5_000,
 		staleMs: CARD_DELIVERY_STALE_MS,
 		// A refresh the host runtime abandoned (workerd cancels a finished request's I/O) never
@@ -94,7 +104,8 @@ export function cardResolveKidFor(rt: CardDeliveryRuntime, baseUrl: string): Res
 /**
  * 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), (1.3.0) every delivered face's memoized hashes and (2.0.0) every card
- * document's digest and every published key set. Returns a restore.
+ * document's digest and every published key set. 2.0.1: beacons go nowhere (a test that wants them sets its own
+ * transport with `setCardBeaconForTests` after this). Returns a restore.
  */
 export function setCardDeliveryRuntimeForTests(overrides: Partial<CardDeliveryRuntime>): () => void {
 	forgetPageSeedsForTests()
@@ -102,6 +113,7 @@ export function setCardDeliveryRuntimeForTests(overrides: Partial<CardDeliveryRu
 	forgetCardDigestsForTests()
 	forgetKeySetsForTests()
 	forgetCardReportsForTests()
+	const restoreBeacon = setCardBeaconForTests()
 	const previous = runtime
 	const now = overrides.now ?? previous.now
 	runtime = {
@@ -111,5 +123,6 @@ export function setCardDeliveryRuntimeForTests(overrides: Partial<CardDeliveryRu
 	}
 	return () => {
 		runtime = previous
+		restoreBeacon()
 	}
 }

package/src/builder/index.tsx

@@ -31,10 +31,10 @@
  * (`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,
- * which is the 1.0.3 trust boundary, not a new one.
+ * is not exactly that shape, or a missing entry id renders nothing. 2.0.1: a block WITHOUT the marker
+ * (every entry exported before 1.1.0) renders nothing too, and reports `no_marker`: through 2.0.0 it
+ * painted its options as 1.0.3 did, unsigned export-time claims an editor could change. So deleting the
+ * marker no longer brings any face back.
  *
  * Three things the card DOES enforce, and they are the limit of it: no chrome at all without a
  * `reviewerName` and a `verifyUrl`; a credential renders only welded to its dated verification

package/src/builder/ssr-seed.ts

@@ -41,9 +41,10 @@
  * page carried for another version.
  *
  * WHEN THE SERVER HAD NO ENVELOPE TO PAINT (1.2.0) the same attribute carries a fallback record instead of a seed:
- * `{ v: 1, baseUrl, externalId, design?, face }`, where `face` is `'options'` (CertREV could not be reached, so the
- * server painted the block's own options face) or `'none'` (the server painted nothing: revoked, expired, unverifiable,
- * for another entry). A browser that renders the card again (hydration, or React's client re-render after a hydration
+ * `{ v: 1, baseUrl, externalId, design?, face, reason? }`, where `face` is `'none'` (the server painted nothing:
+ * revoked, expired, unverifiable, for another entry, or, 2.0.1, CertREV not reached, with `reason` naming why) or, on a
+ * page a 2.0.0 server rendered, `'options'` (CertREV could not be reached and that server painted the block's options
+ * face; 2.0.1 prints nothing for it). A browser that renders the card again (hydration, or React's client re-render after a hydration
  * error elsewhere on the page) paints what the record says, so it neither reads the Delivery API nor shows a card the
  * 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.
@@ -114,7 +115,7 @@ export interface PageSeed {
 	readonly raw: string
 }
 
-/** What the server painted with no verified envelope: the block's options face, or nothing. */
+/** What the server painted with no verified envelope: nothing (2.0.1 never writes `'options'`; a 2.0.0 page may hold one). */
 export type FallbackFace = 'options' | 'none'
 
 /** The record a server writes where it had no envelope to paint (the file header). */

package/src/builder/version.ts

@@ -0,0 +1,2 @@
+/** This package's version, as its beacon reports it (held to `package.json` by `version.test.ts`). */
+export const CERT_BLOCK_VERSION = '2.0.1'

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

@@ -106,6 +106,8 @@ export type CachedDelivery =
 			readonly reason: CertSuppressReason
 			/** 1.2.0: true when CertREV was not reached (no answer about the credential); see the module header. */
 			readonly unreachable?: true
+			/** 2.0.1: the HTTP status, when CertREV answered with a non-OK status other than 404/410. */
+			readonly status?: number
 	  }
 
 /** The answer for one render: the verdict AT THIS RENDER'S CLOCK, and the def to paint it with. */
@@ -117,6 +119,8 @@ export interface VerifiedDelivery {
 	readonly signature?: CertSignature
 	/** 1.2.0: on a suppress verdict, true when CertREV was not reached; else undefined. */
 	readonly unreachable?: true
+	/** 2.0.1: with `unreachable`, the HTTP status when CertREV answered with one (a 5xx, a 429, ...); else undefined. */
+	readonly status?: number
 	/**
 	 * 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`.
@@ -175,8 +179,13 @@ function suppressed(reason: CertSuppressReason): CachedDelivery {
 }
 
 /** A read that did not reach CertREV: the same least-wrong reason as before 1.2.0, marked `unreachable`. */
-function unreachable(): CachedDelivery {
-	return { kind: 'suppressed', reason: 'unsupported_contract_version', unreachable: true }
+function unreachable(status?: number): CachedDelivery {
+	return {
+		kind: 'suppressed',
+		reason: 'unsupported_contract_version',
+		unreachable: true,
+		...(status === undefined ? {} : { status }),
+	}
 }
 
 const isUnreachable = (v: CachedDelivery): boolean => v.kind === 'suppressed' && v.unreachable === true
@@ -312,7 +321,7 @@ async function loadDelivery(opts: GetVerifiedDeliveryOptions): Promise<CachedDel
 	// Nothing served for this placement: never certified, or withdrawn. A LIVE revocation is a 200
 	// tombstone, so a 4xx here genuinely means "no credential for this subject".
 	if (res.status === 404 || res.status === 410) return suppressed('subject_mismatch')
-	if (!res.ok) return unreachable()
+	if (!res.ok) return unreachable(res.status)
 	let body: unknown
 	try {
 		body = await res.json()
@@ -356,6 +365,7 @@ export function settleDelivery(cached: CachedDelivery, context: RenderContext):
 			verdict: { decision: 'suppress', reason: cached.reason },
 			renderDef: null,
 			...(cached.unreachable ? { unreachable: true as const } : {}),
+			...(cached.unreachable && cached.status !== undefined ? { status: cached.status } : {}),
 		}
 	}
 	const verdict = renderVerdict(cached.payload, context)