@certrev/cert-block 0.1.0

package/src/contract/fixtures.ts

@@ -0,0 +1,107 @@
+/**
+ * Mock facts + a SIGNED envelope fixture for unit tests + local dev.
+ *
+ * `makeMockPayload` returns a complete, well-formed `CertPayload` (override any field).
+ * `makeSignedEnvelope` generates an ephemeral Ed25519 keypair, signs the payload's RFC-
+ * 8785 canonical bytes, and returns `{ envelope, resolveKid, publicKey }` so a test can
+ * run the FULL kernel pipeline (real signature verification) against the fixture — no
+ * mocking of the crypto.
+ *
+ * These helpers depend on Node's `crypto` (for keygen + signing on the ISSUER side, which
+ * tests stand in for). The SDK's RUNTIME never signs — it only verifies — so this stays
+ * test/dev-only and is not part of the public render API.
+ *
+ * The fixture signs over `canonicalPayloadBytes` from `@certrev/cert-contract` (RFC 8785),
+ * the SAME bytes the real kernel recomputes on verify — so a fixture envelope verifies
+ * end-to-end under the production `verifyEnvelope`, not a stand-in canonicalizer.
+ */
+
+import { generateKeyPairSync, type KeyObject, sign as nodeSign } from 'node:crypto'
+import {
+	canonicalPayloadBytes,
+	type CertDeliveryEnvelope,
+	type CertPayload,
+	type Ed25519PublicKeyInput,
+	type ResolvePublicKeyByKid,
+} from '@certrev/cert-contract'
+
+const FIXTURE_KID = 'certrev-fixture-key-1'
+
+/** Build a complete mock payload. Pass overrides to exercise specific render branches. */
+export function makeMockPayload(overrides: Partial<CertPayload> = {}): CertPayload {
+	const base: CertPayload = {
+		contractVersion: 1,
+		certId: 'cert_fixture_001',
+		subject: {
+			platform: 'shopify',
+			externalId: 'gid://shopify/Article/123456789',
+			logicalArticleId: 'art_logical_abc',
+			canonicalUrls: ['https://brand.example.com/blogs/skincare/retinol-guide'],
+			installationId: 'inst_shopify_42',
+			contentDigest: 'a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2',
+		},
+		content: {
+			expert: {
+				displayName: 'Dr. Jane Doe',
+				credentials: [
+					{ abbreviation: 'MD', fullName: 'Doctor of Medicine' },
+					{ abbreviation: 'FAAD', fullName: 'Fellow of the American Academy of Dermatology' },
+				],
+				profileUrl: 'https://certrev.com/experts/jane-doe',
+				photoUrl: 'https://cdn.certrev.com/experts/jane-doe.jpg',
+			},
+			author: { name: 'Sam Writer', title: 'Senior Content Editor' },
+			memo: 'I reviewed the retinol claims against current dermatology guidance; the concentrations and usage cadence cited are accurate and safely framed.',
+			certifiedAt: '2026-06-21T15:30:00.000Z',
+			contentModifiedAt: '2026-06-20T09:00:00.000Z',
+			verifyUrl: 'https://certrev.com/verify/cert_fixture_001',
+			display: {
+				accentColor: '#7c3aed',
+				showExpertPhoto: true,
+				showAuthor: true,
+				showMemo: true,
+				badgeStyle: 'full',
+			},
+		},
+		lifecycle: {
+			issuedAt: '2026-06-21T15:30:00.000Z',
+			expiresAt: '2099-01-01T00:00:00.000Z',
+			revokedAt: null,
+			revision: 1,
+		},
+		...overrides,
+	}
+	return base
+}
+
+export interface SignedEnvelopeFixture {
+	readonly envelope: CertDeliveryEnvelope
+	readonly resolveKid: ResolvePublicKeyByKid
+	readonly publicKey: KeyObject
+	readonly kid: string
+}
+
+/**
+ * Generate a fresh keypair, sign the payload, and return everything a test needs to run
+ * the kernel against a genuinely-valid envelope. The returned `resolveKid` resolves only
+ * the fixture kid (any other kid → null → 'unknown_key').
+ */
+export function makeSignedEnvelope(overrides: Partial<CertPayload> = {}, kid = FIXTURE_KID): SignedEnvelopeFixture {
+	const { publicKey, privateKey } = generateKeyPairSync('ed25519')
+	const payload = makeMockPayload(overrides)
+	const bytes = canonicalPayloadBytes(payload)
+	const sig = nodeSign(null, bytes, privateKey).toString('base64url')
+
+	const envelope: CertDeliveryEnvelope = {
+		payload,
+		signature: { alg: 'ed25519', kid, sig, signedAt: payload.lifecycle.issuedAt },
+	}
+
+	const spkiBase64 = publicKey.export({ format: 'der', type: 'spki' }).toString('base64')
+	const keyInput: Ed25519PublicKeyInput = { format: 'spki-base64', base64: spkiBase64 }
+	const resolveKid: ResolvePublicKeyByKid = (k) => (k === kid ? keyInput : null)
+
+	return { envelope, resolveKid, publicKey, kid }
+}
+
+export { FIXTURE_KID }

package/src/contract/kernel.ts

@@ -0,0 +1,20 @@
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ * Contract binding point — the SDK's single import of @certrev/cert-contract
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * Every other SDK module imports the contract TYPES and the KERNEL functions from HERE,
+ * never directly from `@certrev/cert-contract`, so the whole SDK's dependency on the
+ * contract is funnelled through one module. The published package owns the envelope types
+ * (`CertDeliveryEnvelope`, `CertPayload`, `CertCredential`, …), the RFC-8785
+ * canonicalization (`canonicalPayloadBytes`), and the fail-closed kernel (`verifyEnvelope`,
+ * `renderVerdict`, `verifySignatureOnly`, `toEd25519PublicKey`).
+ *
+ * `VerdictKernel` is the ONE name NOT re-exported from the package: the contract exposes
+ * the kernel as free functions, and different edges bundle them with different key-resolver
+ * shapes (cert-block uses `Ed25519PublicKeyInput`; the portal Delivery API uses raw
+ * `Uint8Array`), so the bundled interface stays edge-local — see ./verdict-kernel.
+ */
+
+export * from '@certrev/cert-contract'
+export type { VerdictKernel } from './verdict-kernel.js'

package/src/contract/verdict-kernel.ts

@@ -0,0 +1,47 @@
+/**
+ * VerdictKernel — cert-block's edge-local view of the kernel function set.
+ *
+ * The published `@certrev/cert-contract` exposes the kernel as FREE FUNCTIONS
+ * (`verifyEnvelope`, `renderVerdict`, `verifySignatureOnly`), NOT as a bundled interface,
+ * because different edges bundle them with different key-resolver shapes: cert-block
+ * resolves keys as `Ed25519PublicKeyInput`, while the portal Delivery API's kernel
+ * resolves raw `Uint8Array`. There is therefore no single canonical `VerdictKernel`
+ * interface to live in the contract — each edge declares the bundled shape it depends on.
+ * This is cert-block's.
+ */
+
+import type {
+	CertDeliveryEnvelope,
+	CertPayload,
+	CertSuppressReason,
+	CertVerdict,
+	RenderContext,
+	ResolvePublicKeyByKid,
+} from '@certrev/cert-contract'
+
+/** Full kernel: verify signature, then apply subject/lifecycle/drift policy. */
+export type VerifyEnvelope = (
+	envelope: CertDeliveryEnvelope,
+	resolveKid: ResolvePublicKeyByKid,
+	ctx: RenderContext,
+) => Promise<CertVerdict>
+
+/** Phase-2-only policy over an already-verified payload. */
+export type RenderVerdict = (payload: CertPayload, ctx: RenderContext) => CertVerdict
+
+/** Phase-1-only cryptographic verification. */
+export type VerifySignatureOnly = (
+	envelope: CertDeliveryEnvelope,
+	resolveKid: ResolvePublicKeyByKid,
+) => Promise<{ ok: true } | { ok: false; reason: CertSuppressReason }>
+
+/**
+ * The kernel function trio as a single named interface — the value-level surface for
+ * callers that want them as one object. `@certrev/cert-contract` exposes these as free
+ * functions; this is a convenience binding, deliberately kept out of the wire contract.
+ */
+export interface VerdictKernel {
+	readonly verifyEnvelope: VerifyEnvelope
+	readonly renderVerdict: RenderVerdict
+	readonly verifySignatureOnly: VerifySignatureOnly
+}

package/src/index.ts

@@ -0,0 +1,85 @@
+/**
+ * @certrev/cert-block — the headless / crypto_verify render edge for CertREV.
+ *
+ * Public API:
+ *   • React components — <CertBadge>, <ExpertBio>, <CertRevBacklink>, <CertJsonLd>,
+ *     <CertReview> (composite). SSR-safe, theme-light, accessible, escaping every field.
+ *   • JSON-LD projector — deterministic facts → schema.org Article+reviewedBy(Person)
+ *     graph, mergeable by @id (won't collide with Yoast).
+ *   • Verify layer — `getVerifiedEnvelope` (fetch from metafield OR Delivery API + run
+ *     the fail-closed VerdictKernel + cache), kid resolvers, the TTL/single-flight cache.
+ *   • Contract types — re-exported from `@certrev/cert-contract` (stubbed locally until
+ *     that package publishes; see the contract binding point in ./contract/kernel).
+ *
+ * The Web Component (`<certrev-badge>`) ships from the './webcomponent' subpath export so
+ * importing the main entry doesn't touch `customElements` (which is undefined server-side).
+ */
+
+// ── React components ──────────────────────────────────────────────────────────────
+export { CertBadge, type CertBadgeProps } from './components/CertBadge.js'
+export { CertJsonLd, type CertJsonLdProps } from './components/CertJsonLd.js'
+export { CertRevBacklink, type CertRevBacklinkProps } from './components/CertRevBacklink.js'
+export { CertReview, type CertReviewProps } from './components/CertReview.js'
+export { ExpertBio, type ExpertBioProps } from './components/ExpertBio.js'
+export { escapeAttribute, escapeHtml, safeCssColor, safeHttpUrl, tidyText } from './components/escape.js'
+// ── Presentation helpers (shared with the Web Component) ────────────────────────────
+export {
+	credentialSuffix,
+	DEFAULT_ACCENT,
+	expertNameWithCredentials,
+	formatDate,
+	type ResolvedDisplay,
+	resolveDisplay,
+} from './components/format.js'
+// ── Test/dev fixtures (mock facts + signed-envelope generator) ─────────────────────
+export { FIXTURE_KID, makeMockPayload, makeSignedEnvelope, type SignedEnvelopeFixture } from './contract/fixtures.js'
+// ── Contract surface (types + kernel) — re-export the binding point ────────────────
+export {
+	CANONICALIZATION,
+	type CertContent,
+	type CertCredential,
+	type CertDeliveryEnvelope,
+	type CertDisplayConfig,
+	type CertLifecycle,
+	type CertPayload,
+	type CertSignature,
+	type CertSubject,
+	type CertSuppressReason,
+	type CertVerdict,
+	CONTRACT_VERSION,
+	type ContractVersion,
+	type Ed25519PublicKeyInput,
+	type RenderContext,
+	type ResolvePublicKeyByKid,
+	renderVerdict,
+	SIGNATURE_ALG,
+	type SignatureAlg,
+	type VerdictKernel,
+	verifyEnvelope,
+	verifySignatureOnly,
+} from './contract/kernel.js'
+// ── JSON-LD projector ───────────────────────────────────────────────────────────────
+export {
+	type JsonLdValue,
+	type ProjectJsonLdOptions,
+	projectCertJsonLd,
+	projectCertJsonLdString,
+	serializeJsonLdForScript,
+} from './jsonld/project.js'
+export { TtlCache, type TtlCacheOptions } from './verify/cache.js'
+// ── Verify layer ──────────────────────────────────────────────────────────────────
+export {
+	type EnvelopeSource,
+	type GetVerifiedEnvelopeOptions,
+	getVerifiedEnvelope,
+	invalidateVerdict,
+	sharedVerdictCache,
+} from './verify/get-verified-envelope.js'
+export {
+	type FetchingKidResolverOptions,
+	fetchingKidResolver,
+	type StaticKeySet,
+	staticKidResolver,
+} from './verify/resolve-kid.js'
+// ── Web Component string renderer (the markup shared by SSR + the custom element) ──
+export { type RenderBadgeOptions, renderBadgeHtml } from './webcomponent/render-badge-html.js'

package/src/jsonld/project.ts

@@ -0,0 +1,206 @@
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ * Deterministic JSON-LD projector — facts → schema.org graph (mergeable by @id)
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * INVARIANT #1 of the contract: the JSON-LD is PROJECTED from `payload.content` facts
+ * at render time, never stored in (or signed into) the envelope. This is that projector.
+ * It is DETERMINISTIC — same facts in → byte-identical graph out — so two edges (and a
+ * server pre-render) produce the same structured data, and a snapshot diff is meaningful.
+ *
+ * DESIGN GOAL: MERGE, don't collide.
+ *   A brand page usually already emits an `Article` (or `BlogPosting`) graph — Yoast on
+ *   WordPress, the theme on Shopify, the framework on headless. If we emit a SECOND
+ *   top-level `Article`, crawlers see two competing primary entities. Instead we emit a
+ *   `@graph` whose Article node carries the SAME `@id` the page's primary article uses
+ *   (the page URL + `#article`, the Yoast convention) so a consumer MERGES our
+ *   `reviewedBy` / `dateModified` into the existing node by `@id` rather than duplicating
+ *   it. Our own nodes (the review, the expert Person, the CertREV org) use CertREV-scoped
+ *   `@id`s that cannot clash with the host page's nodes.
+ *
+ * The Person we attach is the reviewing EXPERT (schema.org `reviewedBy`), which is the
+ * E-E-A-T signal CertREV exists to add — not the author. The author (content byline) is
+ * attached as `author` only when present + distinct.
+ */
+
+import type { CertContent, CertPayload } from '../contract/kernel.js'
+
+/** A JSON-LD node/graph value. Loose by design — this is wire JSON, not a TS model. */
+export type JsonLdValue = Record<string, unknown>
+
+export interface ProjectJsonLdOptions {
+	/**
+	 * The canonical page URL the article renders on. Used to derive the primary
+	 * Article node `@id` (`${pageUrl}#article`) so we merge into the host page's graph
+	 * instead of colliding. When omitted, the first `subject.canonicalUrls` entry is
+	 * used; when there is none either, a CertREV-scoped article `@id` is derived from
+	 * `verifyUrl` (still mergeable, just not aligned to a host node).
+	 */
+	readonly pageUrl?: string
+	/**
+	 * When true (default), emit the wrapping `{ "@context": "...", "@graph": [...] }`.
+	 * When false, return just the array of nodes — for a caller that merges them into an
+	 * existing `@graph` it already owns.
+	 */
+	readonly wrapGraph?: boolean
+}
+
+const SCHEMA_CONTEXT = 'https://schema.org'
+
+/**
+ * Strip the query AND fragment from a URL for a stable, mergeable @id. The Yoast / host
+ * convention keys the primary Article node on `{path}#article` with no query — so a page
+ * reached with a `?utm=…` tracking param must derive the SAME `@id` as the canonical URL,
+ * else our `reviewedBy` lands on a sibling node instead of merging into the host's Article.
+ */
+function baseUrl(url: string): string {
+	const cut = Math.min(...[url.indexOf('#'), url.indexOf('?')].filter((i) => i !== -1), url.length)
+	return url.slice(0, cut)
+}
+
+/** Derive the primary Article `@id`, aligned to the Yoast/host convention when we can. */
+function articleId(payload: CertPayload, opts: ProjectJsonLdOptions): string {
+	const page = opts.pageUrl ?? payload.subject.canonicalUrls[0]
+	if (page) return `${baseUrl(page)}#article`
+	// No page URL known — derive a stable, mergeable id from the verify URL.
+	return `${baseUrl(payload.content.verifyUrl)}#article`
+}
+
+/** CertREV-scoped node ids — namespaced under the verify URL so they never clash. */
+function reviewId(content: CertContent): string {
+	return `${content.verifyUrl}#certrev-review`
+}
+function expertId(content: CertContent): string {
+	return content.expert.profileUrl ? `${content.expert.profileUrl}#person` : `${content.verifyUrl}#expert`
+}
+function orgId(content: CertContent): string {
+	// One stable CertREV organization node across all pages: derive from the verify
+	// URL origin so it dedupes cleanly when a page hosts multiple certified articles.
+	try {
+		return `${new URL(content.verifyUrl).origin}/#certrev-organization`
+	} catch {
+		return 'https://certrev.com/#certrev-organization'
+	}
+}
+
+/** Build the reviewing-expert Person node (the E-E-A-T signal). */
+function expertPersonNode(payload: CertPayload): JsonLdValue {
+	const { expert } = payload.content
+	const node: JsonLdValue = {
+		'@type': 'Person',
+		'@id': expertId(payload.content),
+		name: expert.displayName,
+	}
+	if (expert.profileUrl) node.url = expert.profileUrl
+	if (expert.photoUrl) node.image = expert.photoUrl
+	if (expert.credentials.length > 0) {
+		// hasCredential → EducationalOccupationalCredential per credential; also a flat
+		// honorificSuffix list for consumers that don't read hasCredential.
+		node.hasCredential = expert.credentials.map((c) => ({
+			'@type': 'EducationalOccupationalCredential',
+			name: c.fullName,
+			alternateName: c.abbreviation,
+		}))
+		node.honorificSuffix = expert.credentials.map((c) => c.abbreviation).join(', ')
+	}
+	return node
+}
+
+/** Build the CertREV organization node (publisher of the review credential). */
+function certRevOrgNode(payload: CertPayload): JsonLdValue {
+	let url = 'https://certrev.com'
+	try {
+		url = new URL(payload.content.verifyUrl).origin
+	} catch {
+		/* keep default */
+	}
+	return {
+		'@type': 'Organization',
+		'@id': orgId(payload.content),
+		name: 'CertREV',
+		url,
+	}
+}
+
+/** Build the Review node binding the article to its expert review. */
+function reviewNode(payload: CertPayload): JsonLdValue {
+	const node: JsonLdValue = {
+		'@type': 'Review',
+		'@id': reviewId(payload.content),
+		itemReviewed: { '@id': articleId(payload, {}) },
+		author: { '@id': expertId(payload.content) },
+		publisher: { '@id': orgId(payload.content) },
+		datePublished: payload.content.certifiedAt,
+		url: payload.content.verifyUrl,
+	}
+	if (payload.content.memo) node.reviewBody = payload.content.memo
+	return node
+}
+
+/**
+ * The primary Article node — carries the SAME `@id` the host page's article uses so a
+ * consumer merges our `reviewedBy` / `dateModified` into the existing node rather than
+ * duplicating the primary entity. We deliberately emit ONLY the certification-relevant
+ * properties (reviewedBy, dateModified, plus author when distinct) — not headline, body,
+ * image, etc. — so we never overwrite the host's richer Article fields on merge.
+ */
+function articleNode(payload: CertPayload, opts: ProjectJsonLdOptions): JsonLdValue {
+	const { content } = payload
+	const node: JsonLdValue = {
+		'@type': 'Article',
+		'@id': articleId(payload, opts),
+		reviewedBy: { '@id': expertId(content) },
+		review: { '@id': reviewId(content) },
+	}
+	if (content.contentModifiedAt) node.dateModified = content.contentModifiedAt
+	// Author only when present + distinct from the expert (don't double-attribute).
+	if (content.author.name && content.author.name !== content.expert.displayName) {
+		const author: JsonLdValue = { '@type': 'Person', name: content.author.name }
+		if (content.author.title) author.jobTitle = content.author.title
+		node.author = author
+	}
+	return node
+}
+
+/**
+ * Project the verified certification facts into a schema.org `@graph`.
+ *
+ * @param payload  The cryptographically-verified payload (the same facts the badge renders).
+ * @param opts     Page URL for @id alignment + graph-wrapping control.
+ * @returns        A `{ "@context", "@graph" }` object (wrapGraph !== false) OR a bare
+ *                 array of nodes (wrapGraph === false) for merge-into-existing-graph callers.
+ */
+export function projectCertJsonLd(payload: CertPayload, opts: ProjectJsonLdOptions = {}): JsonLdValue | JsonLdValue[] {
+	const nodes: JsonLdValue[] = [
+		articleNode(payload, opts),
+		reviewNode(payload),
+		expertPersonNode(payload),
+		certRevOrgNode(payload),
+	]
+	if (opts.wrapGraph === false) return nodes
+	return { '@context': SCHEMA_CONTEXT, '@graph': nodes }
+}
+
+/**
+ * Serialize the projected graph to the exact JSON string that goes inside a
+ * `<script type="application/ld+json">`. We use `JSON.stringify` with no extra
+ * whitespace for a compact, deterministic body. The string is then made safe to embed
+ * by `serializeJsonLdForScript` (which neutralizes `</script>`).
+ */
+export function projectCertJsonLdString(payload: CertPayload, opts: ProjectJsonLdOptions = {}): string {
+	return serializeJsonLdForScript(projectCertJsonLd(payload, opts))
+}
+
+/**
+ * Serialize an arbitrary JSON-LD value for safe inclusion inside a `<script>` element.
+ * Inside `application/ld+json`, two HTML sequences can break out of the tag: `</script>`
+ * (closes the element early) and HTML-comment markers `<!--` / `-->` (some parsers treat
+ * a comment opened inside a script as suspending script-data parsing). A memo or name
+ * containing either is attacker-influenced text, so we neutralize BOTH angle brackets to
+ * their `\uXXXX` form. This is valid JSON that parses back to the identical string — the
+ * structured data is unchanged, but no `<…>`/`-->` sequence can terminate the script.
+ * Standard Next.js / Yoast hardening.
+ */
+export function serializeJsonLdForScript(value: unknown): string {
+	return JSON.stringify(value).replace(/</g, '\\u003c').replace(/>/g, '\\u003e')
+}

package/src/verify/cache.ts

@@ -0,0 +1,116 @@
+/**
+ * In-process TTL cache with single-flight de-duplication.
+ *
+ * WHY: under SSR, a popular product/blog page can render N times concurrently across a
+ * server's request workers. Without coordination, each render fires its own fetch to the
+ * Shopify metafield / Delivery API → a thundering herd against the issuer on cold cache
+ * or cache expiry. This cache:
+ *   1. Serves a fresh value from memory within its TTL (no fetch).
+ *   2. SINGLE-FLIGHTS concurrent misses for the same key — the first caller's in-flight
+ *      promise is shared by every other caller for that key, so N concurrent renders do
+ *      ONE fetch, not N.
+ *   3. Negative-caches failures briefly so a hard-down origin doesn't get hammered, while
+ *      still recovering quickly (short negative TTL).
+ *
+ * It is deliberately tiny + dependency-free (a Map + timestamps) so it runs in any server
+ * runtime (Node, edge, workerd). For multi-instance deployments this is per-instance L1;
+ * pair with a shared CDN/KV cache (the Delivery API is CDN-cacheable on
+ * `lifecycle.revision`) for L2 — see README.
+ */
+
+export interface TtlCacheOptions {
+	/** Positive-result TTL in ms (default 60_000). */
+	readonly ttlMs?: number
+	/** Negative-result (miss/error) TTL in ms (default 5_000). */
+	readonly negativeTtlMs?: number
+	/** Max entries before LRU-ish eviction of the oldest insert (default 1000). */
+	readonly maxEntries?: number
+	/** Injectable clock for deterministic tests. */
+	readonly now?: () => number
+}
+
+interface Entry<V> {
+	readonly value: V
+	readonly expiresAt: number
+	readonly negative: boolean
+}
+
+export class TtlCache<V> {
+	private readonly store = new Map<string, Entry<V>>()
+	private readonly inflight = new Map<string, Promise<V>>()
+	private readonly ttlMs: number
+	private readonly negativeTtlMs: number
+	private readonly maxEntries: number
+	private readonly now: () => number
+
+	constructor(opts: TtlCacheOptions = {}) {
+		this.ttlMs = opts.ttlMs ?? 60_000
+		this.negativeTtlMs = opts.negativeTtlMs ?? 5_000
+		this.maxEntries = opts.maxEntries ?? 1000
+		this.now = opts.now ?? Date.now
+	}
+
+	/** Read a live (non-expired) entry, or undefined. Prunes the entry if expired. */
+	peek(key: string): V | undefined {
+		const e = this.store.get(key)
+		if (!e) return undefined
+		if (e.expiresAt <= this.now()) {
+			this.store.delete(key)
+			return undefined
+		}
+		return e.value
+	}
+
+	/**
+	 * Get-or-load with single-flight. If a fresh value is cached, returns it. Otherwise
+	 * de-duplicates concurrent loads for `key`: the first caller runs `loader`, every
+	 * concurrent caller awaits the same promise. The result is cached with the positive
+	 * TTL; if `isNegative(value)` returns true (e.g. a 'suppress' verdict) it's cached
+	 * with the shorter negative TTL so a transient failure recovers fast. A thrown loader
+	 * is NOT cached (it rejects all current waiters and the next call retries).
+	 */
+	async getOrLoad(key: string, loader: () => Promise<V>, isNegative?: (v: V) => boolean): Promise<V> {
+		const cached = this.peek(key)
+		if (cached !== undefined) return cached
+
+		const existing = this.inflight.get(key)
+		if (existing) return existing
+
+		const promise = (async () => {
+			const value = await loader()
+			const negative = isNegative ? isNegative(value) : false
+			this.set(key, value, negative)
+			return value
+		})().finally(() => {
+			this.inflight.delete(key)
+		})
+
+		this.inflight.set(key, promise)
+		return promise
+	}
+
+	/** Insert/overwrite an entry with the appropriate TTL. */
+	set(key: string, value: V, negative = false): void {
+		if (this.store.size >= this.maxEntries && !this.store.has(key)) {
+			// Evict the oldest inserted key (Map preserves insertion order).
+			const oldest = this.store.keys().next().value
+			if (oldest !== undefined) this.store.delete(oldest)
+		}
+		const ttl = negative ? this.negativeTtlMs : this.ttlMs
+		this.store.set(key, { value, expiresAt: this.now() + ttl, negative })
+	}
+
+	/** Drop a key (e.g. on a known revocation push). */
+	delete(key: string): void {
+		this.store.delete(key)
+	}
+
+	clear(): void {
+		this.store.clear()
+		this.inflight.clear()
+	}
+
+	get size(): number {
+		return this.store.size
+	}
+}