@certrev/cert-block 0.1.0

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@certrev/cert-block",
+  "version": "0.1.0",
+  "description": "Headless / crypto_verify render edge for the CertREV CertDeliveryEnvelope. SSR-safe React components (<CertBadge>/<ExpertBio>/<CertRevBacklink>), a deterministic schema.org JSON-LD projector, a fail-closed verify layer over the shared VerdictKernel, and a framework-agnostic <certrev-badge> Web Component. Sign once (portal), render everywhere (Hydrogen / Next / Builder / universal embed).",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./webcomponent": {
+      "types": "./dist/webcomponent/certrev-badge.d.ts",
+      "default": "./dist/webcomponent/certrev-badge.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "publishTargets": [
+    "npmjs"
+  ],
+  "peerDependencies": {
+    "@certrev/cert-contract": ">=0.1.1",
+    "react": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.1.0",
+    "@types/node": "^20.0.0",
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "jsdom": "^25.0.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5",
+    "@certrev/cert-contract": "0.1.1"
+  },
+  "keywords": [
+    "certrev",
+    "certification",
+    "react",
+    "server-components",
+    "hydrogen",
+    "shopify",
+    "json-ld",
+    "schema-org",
+    "web-component",
+    "ed25519",
+    "ssr"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/__tests__/components.test.tsx

@@ -0,0 +1,191 @@
+/**
+ * SSR-render tests for the React components, exercised through `react-dom/server`'s
+ * `renderToStaticMarkup` — the SAME path Hydrogen / Next use to produce the crawlable
+ * HTML. Rendering server-side here proves three contract properties at once:
+ *   • SSR-safe: a component that touched `useState`/`useEffect`/`window` would throw under
+ *     `renderToStaticMarkup`; passing means the components are render-pure.
+ *   • Escaping: React escapes text + attributes, and our `safeHttpUrl` strips dangerous
+ *     schemes — both asserted against hostile mock facts.
+ *   • Fail-closed: a suppressed verdict / unsafe URL renders nothing.
+ *
+ * Facts are mocked via `makeMockPayload` (no crypto, no network — pure render under test).
+ */
+
+import { renderToStaticMarkup } from 'react-dom/server'
+import { describe, expect, it } from 'vitest'
+import { CertBadge } from '../components/CertBadge.js'
+import { CertJsonLd } from '../components/CertJsonLd.js'
+import { CertRevBacklink } from '../components/CertRevBacklink.js'
+import { CertReview } from '../components/CertReview.js'
+import { ExpertBio } from '../components/ExpertBio.js'
+import { makeMockPayload } from '../contract/fixtures.js'
+
+const payload = makeMockPayload()
+
+describe('<CertBadge>', () => {
+	it('renders the expert name, credentials, certified date, memo, and verify link (full style)', () => {
+		const html = renderToStaticMarkup(<CertBadge payload={payload} />)
+		expect(html).toContain('Dr. Jane Doe')
+		expect(html).toContain('MD, FAAD')
+		expect(html).toContain('Jun 21, 2026') // certifiedAt, deterministic UTC formatting
+		expect(html).toContain('retinol claims') // memo
+		expect(html).toContain('Verify on CertREV')
+		expect(html).toContain('href="https://certrev.com/verify/cert_fixture_001"')
+	})
+
+	it('carries an accessible name + the cert id data attribute', () => {
+		const html = renderToStaticMarkup(<CertBadge payload={payload} />)
+		expect(html).toContain('aria-label="Content reviewed by Dr. Jane Doe, MD, FAAD"')
+		expect(html).toContain('data-certrev-cert-id="cert_fixture_001"')
+		expect(html).toMatch(/^<section/)
+	})
+
+	it('applies the signed accent color as a CSS custom property + accent border', () => {
+		const html = renderToStaticMarkup(<CertBadge payload={payload} />)
+		expect(html).toContain('--certrev-accent:#7c3aed')
+		expect(html).toContain('border-inline-start-color:#7c3aed')
+	})
+
+	it('compact style collapses to one line — no memo, no dates, no photo', () => {
+		const html = renderToStaticMarkup(<CertBadge payload={payload} badgeStyle="compact" />)
+		expect(html).toContain('certrev-badge--compact')
+		expect(html).not.toContain('retinol claims')
+		expect(html).not.toContain('Certified')
+		expect(html).not.toContain('__photo')
+	})
+
+	it('honors display flags: showMemo=false hides the memo; showExpertPhoto=false hides the photo', () => {
+		const p = makeMockPayload({
+			content: { ...payload.content, display: { ...payload.content.display, showMemo: false, showExpertPhoto: false } },
+		})
+		const html = renderToStaticMarkup(<CertBadge payload={p} />)
+		expect(html).not.toContain('retinol claims')
+		expect(html).not.toContain('__photo')
+	})
+
+	it('ESCAPES a hostile display name (React text-escaping; no raw HTML injected)', () => {
+		const p = makeMockPayload({
+			content: {
+				...payload.content,
+				expert: { ...payload.content.expert, displayName: '<img src=x onerror=alert(1)>' },
+				memo: null,
+			},
+		})
+		const html = renderToStaticMarkup(<CertBadge payload={p} />)
+		expect(html).not.toContain('<img src=x onerror=alert(1)>')
+		expect(html).toContain('&lt;img src=x onerror=alert(1)&gt;')
+	})
+
+	it('DROPS a javascript: profile URL (safeHttpUrl) — the name renders unlinked, no href', () => {
+		const p = makeMockPayload({
+			content: {
+				...payload.content,
+				// biome-ignore lint/suspicious/noTemplateCurlyInString: literal javascript: scheme string for the XSS-drop assertion
+				expert: { ...payload.content.expert, profileUrl: 'javascript:alert(document.cookie)' },
+			},
+		})
+		const html = renderToStaticMarkup(<CertBadge payload={p} />)
+		expect(html).not.toContain('javascript:')
+		expect(html).not.toContain('__expert-link') // no anchor when the URL is unsafe
+		expect(html).toContain('Dr. Jane Doe') // name still rendered
+	})
+
+	it('renders the author byline only when the author is present + distinct from the expert', () => {
+		const distinct = renderToStaticMarkup(<CertBadge payload={payload} />)
+		expect(distinct).toContain('Written by Sam Writer, Senior Content Editor')
+
+		const same = makeMockPayload({
+			content: { ...payload.content, author: { name: 'Dr. Jane Doe', title: null } },
+		})
+		expect(renderToStaticMarkup(<CertBadge payload={same} />)).not.toContain('Written by')
+	})
+})
+
+describe('<ExpertBio>', () => {
+	it('renders the expert identity block with credentials expanded (abbr + full name)', () => {
+		const html = renderToStaticMarkup(<ExpertBio payload={payload} />)
+		expect(html).toMatch(/^<aside/)
+		expect(html).toContain('Dr. Jane Doe')
+		expect(html).toContain('<abbr title="Doctor of Medicine">MD</abbr>')
+		expect(html).toContain('Fellow of the American Academy of Dermatology')
+		expect(html).toContain('Verified expert reviewer')
+	})
+
+	it('respects the heading level prop for page-outline slotting', () => {
+		expect(renderToStaticMarkup(<ExpertBio payload={payload} headingLevel="h2" />)).toContain('<h2')
+		expect(renderToStaticMarkup(<ExpertBio payload={payload} />)).toContain('<h3') // default
+	})
+
+	it('omits the photo when showExpertPhoto is false', () => {
+		const p = makeMockPayload({
+			content: { ...payload.content, display: { ...payload.content.display, showExpertPhoto: false } },
+		})
+		expect(renderToStaticMarkup(<ExpertBio payload={p} />)).not.toContain('__photo')
+	})
+})
+
+describe('<CertRevBacklink>', () => {
+	it('renders the live verify link with an accessible label', () => {
+		const html = renderToStaticMarkup(<CertRevBacklink payload={payload} />)
+		expect(html).toMatch(/^<a/)
+		expect(html).toContain('href="https://certrev.com/verify/cert_fixture_001"')
+		expect(html).toContain('aria-label="Verify this certification on CertREV"')
+		expect(html).toContain('Verify on CertREV')
+	})
+
+	it('accepts a custom label', () => {
+		expect(renderToStaticMarkup(<CertRevBacklink payload={payload} label="Check the certificate" />)).toContain(
+			'Check the certificate',
+		)
+	})
+
+	it('FAIL-CLOSED: renders nothing when the verify URL is unsafe/absent', () => {
+		const p = makeMockPayload({ content: { ...payload.content, verifyUrl: 'javascript:alert(1)' } })
+		expect(renderToStaticMarkup(<CertRevBacklink payload={p} />)).toBe('')
+	})
+})
+
+describe('<CertJsonLd>', () => {
+	it('emits an application/ld+json <script> with the projected graph', () => {
+		const html = renderToStaticMarkup(<CertJsonLd payload={payload} />)
+		expect(html).toContain('<script type="application/ld+json">')
+		expect(html).toContain('"@type":"Article"')
+		expect(html).toContain('"@type":"Review"')
+		expect(html).toContain('"reviewedBy"')
+		expect(html).toContain('Dr. Jane Doe')
+	})
+
+	it('neutralizes < in the serialized body so a hostile memo cannot break out of the tag', () => {
+		const p = makeMockPayload({
+			content: { ...payload.content, memo: 'safe </script><script>alert(1)</script>' },
+		})
+		const html = renderToStaticMarkup(<CertJsonLd payload={p} />)
+		// The only literal </script> in the output is the script CLOSE tag, not from the memo.
+		expect(html.match(/<\/script>/g)?.length).toBe(1)
+		expect(html).toContain('\\u003c/script')
+	})
+
+	it('threads pageUrl into the Article @id for host-graph merge', () => {
+		const html = renderToStaticMarkup(<CertJsonLd payload={payload} pageUrl="https://shop.example.com/a/b" />)
+		expect(html).toContain('"@id":"https://shop.example.com/a/b#article"')
+	})
+})
+
+describe('<CertReview> (composite, fail-closed at the component boundary)', () => {
+	it('renders badge + JSON-LD on a render verdict', () => {
+		const html = renderToStaticMarkup(<CertReview verdict={{ decision: 'render', payload }} />)
+		expect(html).toContain('certrev-badge')
+		expect(html).toContain('application/ld+json')
+	})
+
+	it('renders NOTHING on a suppress verdict', () => {
+		const html = renderToStaticMarkup(<CertReview verdict={{ decision: 'suppress', reason: 'revoked' }} />)
+		expect(html).toBe('')
+	})
+
+	it('omitJsonLd drops the structured-data script but keeps the badge', () => {
+		const html = renderToStaticMarkup(<CertReview verdict={{ decision: 'render', payload }} omitJsonLd />)
+		expect(html).toContain('certrev-badge')
+		expect(html).not.toContain('application/ld+json')
+	})
+})

package/src/__tests__/project.test.ts

@@ -0,0 +1,128 @@
+import { describe, expect, it } from 'vitest'
+import { makeMockPayload } from '../contract/fixtures.js'
+import {
+	type JsonLdValue,
+	projectCertJsonLd,
+	projectCertJsonLdString,
+	serializeJsonLdForScript,
+} from '../jsonld/project.js'
+
+function graphOf(value: JsonLdValue | JsonLdValue[]): JsonLdValue[] {
+	if (Array.isArray(value)) return value
+	return value['@graph'] as JsonLdValue[]
+}
+function nodeOfType(value: JsonLdValue | JsonLdValue[], type: string): JsonLdValue {
+	const n = graphOf(value).find((x) => x['@type'] === type)
+	if (!n) throw new Error(`no ${type} node`)
+	return n
+}
+
+describe('projectCertJsonLd', () => {
+	it('emits a wrapped @graph with Article, Review, Person(expert), Organization', () => {
+		const g = projectCertJsonLd(makeMockPayload())
+		expect(Array.isArray(g)).toBe(false)
+		const graph = graphOf(g)
+		const types = graph.map((n) => n['@type']).sort()
+		expect(types).toEqual(['Article', 'Organization', 'Person', 'Review'])
+		expect((g as JsonLdValue)['@context']).toBe('https://schema.org')
+	})
+
+	it('Article @id aligns to the page URL (#article) so it MERGES into the host/Yoast node', () => {
+		const g = projectCertJsonLd(makeMockPayload(), {
+			pageUrl: 'https://brand.example.com/blogs/skincare/retinol-guide?utm=x',
+		})
+		const article = nodeOfType(g, 'Article')
+		// Fragment + query stripped, #article appended — the Yoast convention.
+		expect(article['@id']).toBe('https://brand.example.com/blogs/skincare/retinol-guide#article')
+	})
+
+	it('falls back to subject.canonicalUrls[0] for the Article @id when no pageUrl given', () => {
+		const article = nodeOfType(projectCertJsonLd(makeMockPayload()), 'Article')
+		expect(article['@id']).toBe('https://brand.example.com/blogs/skincare/retinol-guide#article')
+	})
+
+	it('attaches the EXPERT as reviewedBy (the E-E-A-T signal), not as author', () => {
+		const g = projectCertJsonLd(makeMockPayload())
+		const article = nodeOfType(g, 'Article')
+		const person = nodeOfType(g, 'Person')
+		expect(person.name).toBe('Dr. Jane Doe')
+		expect((article.reviewedBy as JsonLdValue)['@id']).toBe(person['@id'])
+		// Distinct author present + attached separately.
+		expect((article.author as JsonLdValue).name).toBe('Sam Writer')
+	})
+
+	it('projects credentials as hasCredential + honorificSuffix', () => {
+		const person = nodeOfType(projectCertJsonLd(makeMockPayload()), 'Person')
+		expect(person.honorificSuffix).toBe('MD, FAAD')
+		expect((person.hasCredential as JsonLdValue[]).map((c) => c.alternateName)).toEqual(['MD', 'FAAD'])
+	})
+
+	it('Review node binds itemReviewed→Article, author→expert, publisher→CertREV org', () => {
+		const g = projectCertJsonLd(makeMockPayload())
+		const review = nodeOfType(g, 'Review')
+		const article = nodeOfType(g, 'Article')
+		const person = nodeOfType(g, 'Person')
+		const org = nodeOfType(g, 'Organization')
+		expect((review.itemReviewed as JsonLdValue)['@id']).toBe(article['@id'])
+		expect((review.author as JsonLdValue)['@id']).toBe(person['@id'])
+		expect((review.publisher as JsonLdValue)['@id']).toBe(org['@id'])
+		expect(review.reviewBody).toContain('retinol claims')
+	})
+
+	it('CertREV node @ids are namespaced under certrev.com so they cannot collide with host nodes', () => {
+		const g = projectCertJsonLd(makeMockPayload())
+		const person = nodeOfType(g, 'Person')
+		const org = nodeOfType(g, 'Organization')
+		const review = nodeOfType(g, 'Review')
+		for (const id of [person['@id'], org['@id'], review['@id']]) {
+			expect(String(id).startsWith('https://certrev.com/')).toBe(true)
+		}
+	})
+
+	it('omits dateModified when contentModifiedAt is null', () => {
+		const article = nodeOfType(
+			projectCertJsonLd(makeMockPayload({ content: { ...makeMockPayload().content, contentModifiedAt: null } })),
+			'Article',
+		)
+		expect('dateModified' in article).toBe(false)
+	})
+
+	it('does not double-attribute when author === expert', () => {
+		const p = makeMockPayload()
+		const sameAuthor = makeMockPayload({
+			content: { ...p.content, author: { name: p.content.expert.displayName, title: null } },
+		})
+		const article = nodeOfType(projectCertJsonLd(sameAuthor), 'Article')
+		expect('author' in article).toBe(false)
+	})
+
+	it('is DETERMINISTIC — same facts → byte-identical serialization', () => {
+		const a = projectCertJsonLdString(makeMockPayload(), { pageUrl: 'https://x.com/p' })
+		const b = projectCertJsonLdString(makeMockPayload(), { pageUrl: 'https://x.com/p' })
+		expect(a).toBe(b)
+	})
+
+	it('wrapGraph:false returns a bare node array for merge-into-existing-graph callers', () => {
+		const arr = projectCertJsonLd(makeMockPayload(), { wrapGraph: false })
+		expect(Array.isArray(arr)).toBe(true)
+	})
+})
+
+describe('serializeJsonLdForScript', () => {
+	it('neutralizes </script> so the body cannot break out of the <script> tag', () => {
+		const evilPayload = makeMockPayload({
+			content: { ...makeMockPayload().content, memo: 'totally safe </script><script>alert(1)</script>' },
+		})
+		const out = projectCertJsonLdString(evilPayload)
+		expect(out).not.toContain('</script>')
+		expect(out).toContain('\\u003c/script')
+		// Still valid JSON that round-trips to the original string.
+		const parsed = JSON.parse(out.replace(/\\u003c/g, '<'))
+		const review = (parsed['@graph'] as JsonLdValue[]).find((n) => n['@type'] === 'Review')
+		expect(review?.reviewBody).toContain('</script>')
+	})
+
+	it('escapes every < (HTML-comment opener defense)', () => {
+		expect(serializeJsonLdForScript({ a: '<!-- x -->' })).toBe('{"a":"\\u003c!-- x --\\u003e"}')
+	})
+})

package/src/__tests__/verify.test.ts

@@ -0,0 +1,203 @@
+import { describe, expect, it, vi } from 'vitest'
+import { makeSignedEnvelope } from '../contract/fixtures.js'
+import type { CertDeliveryEnvelope } from '../contract/kernel.js'
+import { verifyEnvelope } from '../contract/kernel.js'
+import { TtlCache } from '../verify/cache.js'
+import { getVerifiedEnvelope } from '../verify/get-verified-envelope.js'
+import { staticKidResolver } from '../verify/resolve-kid.js'
+
+const RENDER_CTX = { platform: 'shopify', externalId: 'gid://shopify/Article/123456789' }
+
+describe('kernel via the SDK binding (real Ed25519 over JCS)', () => {
+	it('a freshly signed fixture envelope verifies + renders, carrying the payload', async () => {
+		const { envelope, resolveKid } = makeSignedEnvelope()
+		const verdict = await verifyEnvelope(envelope, resolveKid, { ...RENDER_CTX, now: new Date('2026-06-22T00:00:00Z') })
+		expect(verdict.decision).toBe('render')
+		if (verdict.decision === 'render') expect(verdict.payload.certId).toBe('cert_fixture_001')
+	})
+
+	it('a tampered payload fails the signature (fail-closed suppress)', async () => {
+		const { envelope, resolveKid } = makeSignedEnvelope()
+		const tampered: CertDeliveryEnvelope = { ...envelope, payload: { ...envelope.payload, certId: 'cert_FORGED' } }
+		expect(await verifyEnvelope(tampered, resolveKid, RENDER_CTX)).toEqual({
+			decision: 'suppress',
+			reason: 'invalid_signature',
+		})
+	})
+
+	it('an unknown kid suppresses unknown_key', async () => {
+		const { envelope } = makeSignedEnvelope()
+		const verdict = await verifyEnvelope(envelope, () => null, RENDER_CTX)
+		expect(verdict).toEqual({ decision: 'suppress', reason: 'unknown_key' })
+	})
+
+	it('platform mismatch suppresses', async () => {
+		const { envelope, resolveKid } = makeSignedEnvelope()
+		expect(await verifyEnvelope(envelope, resolveKid, { ...RENDER_CTX, platform: 'wordpress' })).toEqual({
+			decision: 'suppress',
+			reason: 'platform_mismatch',
+		})
+	})
+
+	it('revoked suppresses', async () => {
+		const { envelope, resolveKid } = makeSignedEnvelope({
+			lifecycle: {
+				issuedAt: '2026-06-21T00:00:00Z',
+				expiresAt: '2099-01-01T00:00:00Z',
+				revokedAt: '2026-06-21T12:00:00Z',
+				revision: 2,
+			},
+		})
+		expect((await verifyEnvelope(envelope, resolveKid, RENDER_CTX)).decision).toBe('suppress')
+	})
+
+	it('expired suppresses', async () => {
+		const { envelope, resolveKid } = makeSignedEnvelope({
+			lifecycle: { issuedAt: '2026-01-01T00:00:00Z', expiresAt: '2026-02-01T00:00:00Z', revokedAt: null, revision: 1 },
+		})
+		const verdict = await verifyEnvelope(envelope, resolveKid, { ...RENDER_CTX, now: new Date('2026-03-01T00:00:00Z') })
+		expect(verdict).toEqual({ decision: 'suppress', reason: 'expired' })
+	})
+
+	it('content drift (live hash != subject.contentDigest) suppresses', async () => {
+		const { envelope, resolveKid } = makeSignedEnvelope()
+		const verdict = await verifyEnvelope(envelope, resolveKid, { ...RENDER_CTX, liveContentHash: 'b'.repeat(64) })
+		expect(verdict).toEqual({ decision: 'suppress', reason: 'content_drift' })
+	})
+
+	it('matching live hash renders', async () => {
+		const digest = 'c'.repeat(64)
+		const { envelope, resolveKid } = makeSignedEnvelope({
+			subject: { ...makeSignedEnvelope().envelope.payload.subject, contentDigest: digest },
+		})
+		const verdict = await verifyEnvelope(envelope, resolveKid, { ...RENDER_CTX, liveContentHash: digest })
+		expect(verdict.decision).toBe('render')
+	})
+})
+
+describe('getVerifiedEnvelope — metafield source', () => {
+	it('verifies an envelope read from a metafield (object form)', async () => {
+		const { envelope, resolveKid } = makeSignedEnvelope()
+		const verdict = await getVerifiedEnvelope({
+			source: { kind: 'metafield', value: envelope },
+			resolveKid,
+			context: { ...RENDER_CTX, now: new Date('2026-06-22T00:00:00Z') },
+			cache: new TtlCache(),
+		})
+		expect(verdict.decision).toBe('render')
+	})
+
+	it('verifies an envelope read from a metafield (JSON-string form)', async () => {
+		const { envelope, resolveKid } = makeSignedEnvelope()
+		const verdict = await getVerifiedEnvelope({
+			source: { kind: 'metafield', value: JSON.stringify(envelope) },
+			resolveKid,
+			context: { ...RENDER_CTX, now: new Date('2026-06-22T00:00:00Z') },
+			cache: new TtlCache(),
+		})
+		expect(verdict.decision).toBe('render')
+	})
+
+	it('a missing metafield value fails closed to suppress', async () => {
+		const { resolveKid } = makeSignedEnvelope()
+		const verdict = await getVerifiedEnvelope({
+			source: { kind: 'metafield', value: null },
+			resolveKid,
+			context: RENDER_CTX,
+			cache: new TtlCache(),
+		})
+		expect(verdict.decision).toBe('suppress')
+	})
+
+	it('malformed JSON in a metafield fails closed (no throw)', async () => {
+		const { resolveKid } = makeSignedEnvelope()
+		const verdict = await getVerifiedEnvelope({
+			source: { kind: 'metafield', value: '{not json' },
+			resolveKid,
+			context: RENDER_CTX,
+			cache: new TtlCache(),
+		})
+		expect(verdict.decision).toBe('suppress')
+	})
+})
+
+describe('getVerifiedEnvelope — Delivery API source', () => {
+	it('fetches from GET /api/cert/v1/delivery/{platform}/{externalId} and verifies', async () => {
+		const { envelope, resolveKid } = makeSignedEnvelope()
+		const fetchImpl = vi.fn(async () => new Response(JSON.stringify(envelope), { status: 200 }))
+		const verdict = await getVerifiedEnvelope({
+			source: {
+				kind: 'delivery_api',
+				baseUrl: 'https://portal.certrev.com',
+				platform: 'shopify',
+				externalId: 'gid://shopify/Article/123456789',
+			},
+			resolveKid,
+			context: { ...RENDER_CTX, now: new Date('2026-06-22T00:00:00Z') },
+			fetchImpl: fetchImpl as unknown as typeof fetch,
+			cache: new TtlCache(),
+		})
+		expect(verdict.decision).toBe('render')
+		expect(fetchImpl).toHaveBeenCalledOnce()
+		const calledUrl = (fetchImpl.mock.calls[0] as unknown[])[0] as string
+		expect(calledUrl).toBe(
+			'https://portal.certrev.com/api/cert/v1/delivery/shopify/gid%3A%2F%2Fshopify%2FArticle%2F123456789',
+		)
+	})
+
+	it('a 404 / 410 from the Delivery API fails closed to suppress', async () => {
+		const { resolveKid } = makeSignedEnvelope()
+		const fetchImpl = vi.fn(async () => new Response('', { status: 410 }))
+		const verdict = await getVerifiedEnvelope({
+			source: { kind: 'delivery_api', baseUrl: 'https://portal.certrev.com', platform: 'shopify', externalId: 'x' },
+			resolveKid,
+			context: RENDER_CTX,
+			fetchImpl: fetchImpl as unknown as typeof fetch,
+			cache: new TtlCache(),
+		})
+		expect(verdict.decision).toBe('suppress')
+	})
+
+	it('SINGLE-FLIGHTS concurrent SSR renders — N renders → ONE fetch (thundering-herd guard)', async () => {
+		const { envelope, resolveKid } = makeSignedEnvelope()
+		let calls = 0
+		const fetchImpl = vi.fn(async () => {
+			calls++
+			await new Promise((r) => setTimeout(r, 10))
+			return new Response(JSON.stringify(envelope), { status: 200 })
+		})
+		const cache = new TtlCache<never>() as unknown as TtlCache<import('../contract/kernel.js').CertVerdict>
+		const opts = {
+			source: {
+				kind: 'delivery_api' as const,
+				baseUrl: 'https://portal.certrev.com',
+				platform: 'shopify',
+				externalId: 'gid://shopify/Article/123456789',
+			},
+			resolveKid,
+			context: { ...RENDER_CTX, now: new Date('2026-06-22T00:00:00Z') },
+			fetchImpl: fetchImpl as unknown as typeof fetch,
+			cache,
+		}
+		const verdicts = await Promise.all([
+			getVerifiedEnvelope(opts),
+			getVerifiedEnvelope(opts),
+			getVerifiedEnvelope(opts),
+			getVerifiedEnvelope(opts),
+			getVerifiedEnvelope(opts),
+		])
+		expect(verdicts.every((v) => v.decision === 'render')).toBe(true)
+		expect(calls).toBe(1)
+	})
+})
+
+describe('staticKidResolver', () => {
+	it('resolves a configured kid and returns null for an unknown one', async () => {
+		const { envelope, publicKey, kid } = makeSignedEnvelope()
+		const pem = publicKey.export({ format: 'pem', type: 'spki' }).toString()
+		const resolver = staticKidResolver({ [kid]: pem })
+		const verdict = await verifyEnvelope(envelope, resolver, { ...RENDER_CTX, now: new Date('2026-06-22T00:00:00Z') })
+		expect(verdict.decision).toBe('render')
+		expect(await resolver('nope')).toBeNull()
+	})
+})