@certrev/cert-block 1.2.0-canary.7 → 1.2.1-canary.0

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

@@ -29,12 +29,20 @@
  * `peekVerifiedDelivery` is the synchronous read of the same cache: a React component suspends on
  * `getVerifiedDelivery` once, then reads the settled value without a second promise (which is what
  * keeps a streaming SSR render from suspending forever on a fresh promise every retry).
+ *
+ * 1.2.0: a suppressed read that only failed to REACH CertREV (the fetch threw or hit its deadline, a 5xx or other
+ * non-OK status but 404/410, a body that is not JSON or not an object) is marked `unreachable`. It says nothing
+ * about the credential, so a cache with a stale window keeps a verified entry over it (stale-if-error), and the
+ * 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.
  */
 
 import type { CertChromeRenderDef } from '../builder/cert-chrome-data.js'
 import type {
 	CertDeliveryArtifact,
 	CertPayload,
+	CertSignature,
 	CertSuppressReason,
 	CertVerdict,
 	RenderContext,
@@ -44,16 +52,34 @@ import { renderVerdict, verifyArtifact } from '../contract/kernel.js'
 import { TtlCache } from './cache.js'
 import { DEFAULT_FETCH_TIMEOUT_MS, fetchWithDeadline } from './fetch-with-deadline.js'
 
-/** What one Delivery read settles to, as cached: a verified payload + its def, or the reason not. */
+/**
+ * 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.
+ */
 export type CachedDelivery =
-	| { readonly kind: 'verified'; readonly payload: CertPayload; readonly renderDef: CertChromeRenderDef | null }
-	| { readonly kind: 'suppressed'; readonly reason: CertSuppressReason }
+	| {
+			readonly kind: 'verified'
+			readonly payload: CertPayload
+			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
+	  }
+	| {
+			readonly kind: 'suppressed'
+			readonly reason: CertSuppressReason
+			/** 1.2.0: true when CertREV was not reached (no answer about the credential); see the module header. */
+			readonly unreachable?: true
+	  }
 
 /** The answer for one render: the verdict AT THIS RENDER'S CLOCK, and the def to paint it with. */
 export interface VerifiedDelivery {
 	readonly verdict: CertVerdict
 	/** The brand's render def, or null (no def resolved, a malformed one, or a suppress verdict). */
 	readonly renderDef: CertChromeRenderDef | null
+	/** The verified envelope's signature, on a `render` verdict whose read kept it; else undefined. */
+	readonly signature?: CertSignature
+	/** 1.2.0: on a suppress verdict, true when CertREV was not reached; else undefined. */
+	readonly unreachable?: true
 }
 
 export interface GetVerifiedDeliveryOptions {
@@ -70,7 +96,7 @@ export interface GetVerifiedDeliveryOptions {
 	readonly cache?: TtlCache<CachedDelivery>
 	/** TTL in ms for a VERIFIED read (default: the cache's positive TTL, 60_000 on the shared one). */
 	readonly ttlMs?: number
-	/** Deadline in ms for the fetch (default `DEFAULT_FETCH_TIMEOUT_MS`, 3s). */
+	/** Deadline in ms for the fetch (default `DEFAULT_FETCH_TIMEOUT_MS`, 3s; the Builder card's runtime passes 8s). */
 	readonly timeoutMs?: number
 	/**
 	 * 1.2.0-canary.5: read one saved design version instead of the brand's live def. CertREV's own canary
@@ -96,6 +122,13 @@ function suppressed(reason: CertSuppressReason): CachedDelivery {
 	return { kind: 'suppressed', reason }
 }
 
+/** 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 }
+}
+
+const isUnreachable = (v: CachedDelivery): boolean => v.kind === 'suppressed' && v.unreachable === true
+
 /** The Delivery route; a design pin adds `?design=<v>` and, with a brand, `&designBrand=<brand>`. */
 export function deliveryUrl(baseUrl: string, platform: string, externalId: string, design?: DesignPin): string {
 	const base = baseUrl.replace(/\/+$/, '')
@@ -210,19 +243,19 @@ async function loadDelivery(opts: GetVerifiedDeliveryOptions): Promise<CachedDel
 		)
 	} catch {
 		// Unreachable, DNS/TLS, or the deadline. Same least-wrong member as getVerifiedEnvelope.
-		return suppressed('unsupported_contract_version')
+		return unreachable()
 	}
 	// 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 suppressed('unsupported_contract_version')
+	if (!res.ok) return unreachable()
 	let body: unknown
 	try {
 		body = await res.json()
 	} catch {
-		return suppressed('unsupported_contract_version')
+		return unreachable()
 	}
-	if (!isRecord(body)) return suppressed('unsupported_contract_version')
+	if (!isRecord(body)) return unreachable()
 	let verdict: CertVerdict
 	try {
 		// `verifyArtifact`, so a tombstone verifies as itself and reports 'revoked'. The kernel reads
@@ -233,14 +266,28 @@ async function loadDelivery(opts: GetVerifiedDeliveryOptions): Promise<CachedDel
 		return suppressed('unknown_key')
 	}
 	if (verdict.decision !== 'render') return suppressed(verdict.reason)
-	return { kind: 'verified', payload: verdict.payload, renderDef: parseRenderDef(body.renderDef) }
+	// 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
+	return {
+		kind: 'verified',
+		payload: verdict.payload,
+		renderDef: parseRenderDef(body.renderDef),
+		...(signature ? { signature } : {}),
+	}
 }
 
 /** Apply the render-time policy to a cached read: lifecycle + subject at THIS render's clock. */
 export function settleDelivery(cached: CachedDelivery, context: RenderContext): VerifiedDelivery {
-	if (cached.kind === 'suppressed') return { verdict: { decision: 'suppress', reason: cached.reason }, renderDef: null }
+	if (cached.kind === 'suppressed') {
+		return {
+			verdict: { decision: 'suppress', reason: cached.reason },
+			renderDef: null,
+			...(cached.unreachable ? { unreachable: true as const } : {}),
+		}
+	}
 	const verdict = renderVerdict(cached.payload, context)
-	return { verdict, renderDef: verdict.decision === 'render' ? cached.renderDef : null }
+	if (verdict.decision !== 'render') return { verdict, renderDef: null }
+	return { verdict, renderDef: cached.renderDef, ...(cached.signature ? { signature: cached.signature } : {}) }
 }
 
 /**
@@ -255,10 +302,29 @@ export async function getVerifiedDelivery(opts: GetVerifiedDeliveryOptions): Pro
 		() => loadDelivery(opts),
 		(v) => v.kind === 'suppressed',
 		opts.ttlMs,
+		isUnreachable,
 	)
 	return settleDelivery(cached, opts.context)
 }
 
+/**
+ * 1.2.0, the synchronous read a render uses: the settled answer for a fresh cached read; or, inside the cache's
+ * stale window, the stale read's answer at once while ONE background refresh (the same fetch `getVerifiedDelivery`
+ * makes) replaces it; else `undefined`, and the caller awaits `getVerifiedDelivery`. The verdict is still settled
+ * at `context.now`, so a stale payload that has expired or been revoked in its own fields still suppresses.
+ */
+export function readVerifiedDelivery(opts: GetVerifiedDeliveryOptions): VerifiedDelivery | undefined {
+	const cache = opts.cache ?? sharedDeliveryCache
+	const cached = cache.peekOrRefresh(
+		deliveryCacheKey(opts),
+		() => loadDelivery(opts),
+		(v) => v.kind === 'suppressed',
+		opts.ttlMs,
+		isUnreachable,
+	)
+	return cached === undefined ? undefined : settleDelivery(cached, opts.context)
+}
+
 /**
  * The synchronous read: the settled answer when a fresh read is cached, else `undefined` (the
  * caller then awaits `getVerifiedDelivery`). Never fetches.