@certrev/cert-block 0.1.0

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

@@ -0,0 +1,156 @@
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ * getVerifiedEnvelope — the server-side fetch + verify + cache entry point
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * The headless edge calls this ONCE per render in its server loader (Hydrogen loader,
+ * Next server component / route handler, Builder server fetch). It:
+ *   1. SOURCES the signed `CertDeliveryEnvelope` from EITHER a Shopify metafield (already
+ *      fetched via the Storefront API) OR the public Delivery API
+ *      (`GET /api/cert/v1/delivery/{platform}/{externalId}`).
+ *   2. Runs the shared VerdictKernel (signature + subject/lifecycle/drift), FAIL-CLOSED.
+ *   3. Caches the resulting verdict per-instance (TTL + single-flight) so concurrent SSR
+ *      renders don't stampede the origin.
+ *
+ * It returns a `CertVerdict`: `{ decision: 'render', payload }` → render the badge +
+ * JSON-LD; `{ decision: 'suppress', reason }` → render NOTHING. Any error (network,
+ * malformed JSON, throwing resolver) collapses to a `suppress` verdict — never throws
+ * into the render path, never renders an unverified credential.
+ */
+
+import type { CertDeliveryEnvelope, CertVerdict, RenderContext, ResolvePublicKeyByKid } from '../contract/kernel.js'
+import { verifyEnvelope } from '../contract/kernel.js'
+import { TtlCache } from './cache.js'
+
+/** Where the signed envelope comes from. Exactly one of the two source shapes. */
+export type EnvelopeSource =
+	/** PULL: the public, CDN-cacheable Delivery API. The helper fetches it. */
+	| {
+			readonly kind: 'delivery_api'
+			/** Base URL of the portal Delivery API, e.g. 'https://portal.certrev.com'. */
+			readonly baseUrl: string
+			readonly platform: string
+			readonly externalId: string
+	  }
+	/** PUSH/native: an envelope already read from a Shopify app-owned metafield (or any
+	 *  native store). The caller fetched it via the Storefront API; we just verify it. The
+	 *  value may be the parsed envelope or its JSON string (metafields store strings). */
+	| {
+			readonly kind: 'metafield'
+			readonly value: CertDeliveryEnvelope | string | null | undefined
+	  }
+
+export interface GetVerifiedEnvelopeOptions {
+	readonly source: EnvelopeSource
+	/** kid → public-key resolver (see ./resolve-kid). Required: no verify without keys. */
+	readonly resolveKid: ResolvePublicKeyByKid
+	/** Render context: the platform + externalId this edge IS, plus optional live hash. */
+	readonly context: Omit<RenderContext, 'now'> & { readonly now?: Date }
+	/** Injectable fetch for tests / non-global-fetch runtimes. */
+	readonly fetchImpl?: typeof fetch
+	/** Cache override (per-instance). Defaults to the module-level shared cache. */
+	readonly cache?: TtlCache<CertVerdict>
+	/** Positive verdict TTL ms (default 60_000). */
+	readonly ttlMs?: number
+}
+
+/** Module-level shared cache so all calls in a process coordinate by default. */
+const sharedVerdictCache = new TtlCache<CertVerdict>({ ttlMs: 60_000, negativeTtlMs: 5_000 })
+
+function suppress(
+	reason: CertVerdict extends { decision: 'suppress' }
+		? never
+		: Extract<CertVerdict, { decision: 'suppress' }>['reason'],
+): CertVerdict {
+	return { decision: 'suppress', reason }
+}
+
+function parseEnvelope(value: CertDeliveryEnvelope | string | null | undefined): CertDeliveryEnvelope | null {
+	if (value == null) return null
+	if (typeof value !== 'string') return value
+	try {
+		return JSON.parse(value) as CertDeliveryEnvelope
+	} catch {
+		return null
+	}
+}
+
+function deliveryApiUrl(s: Extract<EnvelopeSource, { kind: 'delivery_api' }>): string {
+	const base = s.baseUrl.replace(/\/+$/, '')
+	return `${base}/api/cert/v1/delivery/${encodeURIComponent(s.platform)}/${encodeURIComponent(s.externalId)}`
+}
+
+/** Stable cache key per (source identity × render externalId). */
+function cacheKey(source: EnvelopeSource, ctx: RenderContext): string {
+	if (source.kind === 'delivery_api') {
+		return `api:${source.platform}:${source.externalId}`
+	}
+	// Metafield: key on the rendering identity (the value is already in hand; the verdict
+	// still depends on context). Include a short hash of the value to bust on push update.
+	return `mf:${ctx.platform}:${ctx.externalId}`
+}
+
+async function fetchFromDeliveryApi(
+	s: Extract<EnvelopeSource, { kind: 'delivery_api' }>,
+	fetchImpl: typeof fetch,
+): Promise<CertDeliveryEnvelope | null> {
+	const res = await fetchImpl(deliveryApiUrl(s), { headers: { accept: 'application/json' } })
+	if (!res.ok) return null // 404 / 410 (revoked, no longer served) → no envelope → suppress
+	try {
+		return (await res.json()) as CertDeliveryEnvelope
+	} catch {
+		return null
+	}
+}
+
+/**
+ * Fetch (if needed), verify, and cache the certification verdict for one placement.
+ * FAIL-CLOSED on every error path. Safe to call on every SSR render — the cache +
+ * single-flight keep the origin load bounded.
+ */
+export async function getVerifiedEnvelope(opts: GetVerifiedEnvelopeOptions): Promise<CertVerdict> {
+	const fetchImpl = opts.fetchImpl ?? globalThis.fetch
+	const cache = opts.cache ?? sharedVerdictCache
+	const ctx: RenderContext = { ...opts.context }
+	const key = cacheKey(opts.source, ctx)
+
+	const isSuppress = (v: CertVerdict) => v.decision !== 'render'
+
+	return cache.getOrLoad(
+		key,
+		async () => {
+			let envelope: CertDeliveryEnvelope | null
+			try {
+				envelope =
+					opts.source.kind === 'delivery_api'
+						? await fetchFromDeliveryApi(opts.source, fetchImpl)
+						: parseEnvelope(opts.source.value)
+			} catch {
+				// Network/JSON failure → fail closed (do NOT render an unverified credential).
+				return suppress('unsupported_contract_version')
+			}
+			if (!envelope) {
+				// No envelope present (never certified / revoked + cleared / 404) → suppress.
+				return suppress('unsupported_contract_version')
+			}
+			// The kernel itself never throws (it fails closed), but guard the resolver too.
+			try {
+				return await verifyEnvelope(envelope, opts.resolveKid, ctx)
+			} catch {
+				return suppress('unknown_key')
+			}
+		},
+		isSuppress,
+	)
+}
+
+/** Expose the shared cache so a revocation webhook handler can invalidate proactively. */
+export function invalidateVerdict(
+	source: EnvelopeSource,
+	context: RenderContext,
+	cache: TtlCache<CertVerdict> = sharedVerdictCache,
+): void {
+	cache.delete(cacheKey(source, context))
+}
+
+export { sharedVerdictCache }

package/src/verify/resolve-kid.ts

@@ -0,0 +1,103 @@
+/**
+ * Public-key resolution for the kernel's signature-verification step.
+ *
+ * The kernel needs a `kid → Ed25519 public key` resolver. CertREV publishes its public
+ * key set (a JWKS-like document) so any edge can verify without a shared secret; rotation
+ * is "publish N+1 keys, start signing with the new kid, retire the old once edges refresh".
+ *
+ * This module gives two resolvers:
+ *   • `staticKidResolver(keys)` — for a key set baked into the deploy (the headless edge
+ *     ships CertREV's current public keys as config; zero network at render time).
+ *   • `fetchingKidResolver({ jwksUrl })` — fetches + caches the published key set, so a
+ *     newly-rotated kid resolves without a redeploy. Cached with a long TTL (keys rotate
+ *     rarely) + single-flight (no thundering herd on the JWKS endpoint).
+ *
+ * Both return the `Ed25519PublicKeyInput` shape the kernel accepts. The fetching resolver
+ * understands the two encodings CertREV may publish: a PEM string, or a JWK with an
+ * Ed25519 `x` (base64url raw key).
+ */
+
+import type { Ed25519PublicKeyInput, ResolvePublicKeyByKid } from '../contract/kernel.js'
+import { TtlCache } from './cache.js'
+
+/** A static map of kid → public key (PEM string or an explicit input). */
+export type StaticKeySet = Readonly<Record<string, string | Ed25519PublicKeyInput>>
+
+function asInput(v: string | Ed25519PublicKeyInput): Ed25519PublicKeyInput {
+	// A bare string is treated as PEM (the common deploy-config form).
+	return typeof v === 'string' ? { format: 'pem', pem: v } : v
+}
+
+/** Resolver over a key set baked into the deploy. No network at render time. */
+export function staticKidResolver(keys: StaticKeySet): ResolvePublicKeyByKid {
+	return (kid) => {
+		const k = keys[kid]
+		return k ? asInput(k) : null
+	}
+}
+
+// ── JWKS-style published key set ──────────────────────────────────────────────────
+
+interface PublishedJwk {
+	readonly kid: string
+	readonly kty?: string
+	readonly crv?: string
+	/** base64url raw 32-byte Ed25519 public key (OKP/Ed25519). */
+	readonly x?: string
+	/** Alternatively, a PEM the publisher chose to ship. */
+	readonly pem?: string
+}
+
+interface PublishedKeySetDoc {
+	readonly keys: ReadonlyArray<PublishedJwk>
+}
+
+function base64urlToBytes(b64url: string): Uint8Array {
+	return new Uint8Array(Buffer.from(b64url, 'base64url'))
+}
+
+function jwkToInput(jwk: PublishedJwk): Ed25519PublicKeyInput | null {
+	if (jwk.pem) return { format: 'pem', pem: jwk.pem }
+	if (jwk.x) {
+		const bytes = base64urlToBytes(jwk.x)
+		if (bytes.length === 32) return { format: 'raw', bytes }
+	}
+	return null
+}
+
+export interface FetchingKidResolverOptions {
+	/** URL of CertREV's published key set (JWKS-like). */
+	readonly jwksUrl: string
+	/** Key-set cache TTL in ms (default 1h — keys rotate rarely). */
+	readonly ttlMs?: number
+	/** Injectable fetch for tests / non-global-fetch runtimes. */
+	readonly fetchImpl?: typeof fetch
+}
+
+/**
+ * Resolver that fetches + caches CertREV's published key set. A single fetch populates
+ * all kids; concurrent misses single-flight through the cache. A kid absent from the
+ * fetched set resolves to null (→ kernel suppresses 'unknown_key' — fail-closed).
+ */
+export function fetchingKidResolver(opts: FetchingKidResolverOptions): ResolvePublicKeyByKid {
+	const fetchImpl = opts.fetchImpl ?? globalThis.fetch
+	const cache = new TtlCache<Map<string, Ed25519PublicKeyInput>>({ ttlMs: opts.ttlMs ?? 3_600_000 })
+	const CACHE_KEY = opts.jwksUrl
+
+	async function loadKeySet(): Promise<Map<string, Ed25519PublicKeyInput>> {
+		const map = new Map<string, Ed25519PublicKeyInput>()
+		const res = await fetchImpl(opts.jwksUrl, { headers: { accept: 'application/json' } })
+		if (!res.ok) return map // empty → every kid resolves null → fail closed
+		const doc = (await res.json()) as PublishedKeySetDoc
+		for (const jwk of doc.keys ?? []) {
+			const input = jwkToInput(jwk)
+			if (input && jwk.kid) map.set(jwk.kid, input)
+		}
+		return map
+	}
+
+	return async (kid) => {
+		const keySet = await cache.getOrLoad(CACHE_KEY, loadKeySet, (m) => m.size === 0)
+		return keySet.get(kid) ?? null
+	}
+}

package/src/webcomponent/certrev-badge.ts

@@ -0,0 +1,100 @@
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ * <certrev-badge> — the framework-agnostic universal-embed Web Component
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * The `universal_embed` surface class: a custom element any site can drop in, fed by the
+ * Delivery API, that renders the SAME badge as <CertBadge> (it shares
+ * `renderBadgeHtml`). Two usage modes, both crawler-friendly:
+ *
+ *   1. SSR + hydrate (PREFERRED, crawlable). A server-side include emits the badge HTML
+ *      (via `renderBadgeHtml`) INSIDE the element, plus the element tag. The component
+ *      sees existing light-DOM children and leaves them; it only re-renders if asked to
+ *      refresh. The crawler reads the server HTML; the component is progressive
+ *      enhancement.
+ *
+ *   2. Client fetch (fallback, NOT crawlable — for already-client-only contexts). Given a
+ *      `delivery-api` + `platform` + `external-id`, it fetches the envelope, runs the
+ *      verdict via the kernel (WebCrypto path lives in cert-contract; here we accept a
+ *      pre-supplied `resolveKid`), and renders on `render`. Documented as the weaker mode.
+ *
+ * The element NEVER renders an unverified credential: client-mode renders only on a
+ * `render` verdict; on any suppress/error it renders nothing (fail-closed).
+ *
+ * Registration is side-effect-free until you call `defineCertRevBadge()` (so importing
+ * the module in SSR doesn't touch `customElements`, which doesn't exist server-side).
+ */
+
+import type { CertVerdict, ResolvePublicKeyByKid } from '../contract/kernel.js'
+import { getVerifiedEnvelope } from '../verify/get-verified-envelope.js'
+import { renderBadgeHtml } from './render-badge-html.js'
+
+export const CERTREV_BADGE_TAG = 'certrev-badge'
+
+/**
+ * A resolver registry the page sets once (the published CertREV keys) so the element can
+ * verify in client-fetch mode without each tag carrying key config. SSR mode never needs
+ * this (verification happened server-side).
+ */
+let globalResolveKid: ResolvePublicKeyByKid | null = null
+export function setCertRevKidResolver(resolver: ResolvePublicKeyByKid): void {
+	globalResolveKid = resolver
+}
+
+export class CertRevBadgeElement extends HTMLElement {
+	static get observedAttributes(): string[] {
+		return ['delivery-api', 'platform', 'external-id', 'accent-color', 'badge-style', 'content-hash']
+	}
+
+	connectedCallback(): void {
+		// SSR/light-DOM-present mode: server already rendered the badge inside us. Leave it.
+		// Only client-fetch when there are no rendered children AND we have a source.
+		if (this.querySelector('.certrev-badge')) return
+		void this.clientFetchAndRender()
+	}
+
+	attributeChangedCallback(_name: string, oldValue: string | null, newValue: string | null): void {
+		if (oldValue === newValue) return
+		// Re-fetch only in client mode (no server-rendered child present).
+		if (this.isConnected && !this.querySelector('.certrev-badge')) {
+			void this.clientFetchAndRender()
+		}
+	}
+
+	private async clientFetchAndRender(): Promise<void> {
+		const baseUrl = this.getAttribute('delivery-api')
+		const platform = this.getAttribute('platform')
+		const externalId = this.getAttribute('external-id')
+		if (!baseUrl || !platform || !externalId) return // nothing to fetch → render nothing
+		if (!globalResolveKid) {
+			// No keys configured → cannot verify → fail closed (render nothing).
+			return
+		}
+		let verdict: CertVerdict
+		try {
+			verdict = await getVerifiedEnvelope({
+				source: { kind: 'delivery_api', baseUrl, platform, externalId },
+				resolveKid: globalResolveKid,
+				context: {
+					platform,
+					externalId,
+					liveContentHash: this.getAttribute('content-hash'),
+				},
+			})
+		} catch {
+			return // fail closed
+		}
+		if (verdict.decision !== 'render') return
+		const accentColor = this.getAttribute('accent-color') ?? undefined
+		const badgeStyle = (this.getAttribute('badge-style') as 'full' | 'compact' | null) ?? undefined
+		this.innerHTML = renderBadgeHtml(verdict.payload, { accentColor, badgeStyle })
+	}
+}
+
+/** Register the element. Idempotent + safe to call only in a browser/customElements env. */
+export function defineCertRevBadge(): void {
+	if (typeof customElements === 'undefined') return
+	if (!customElements.get(CERTREV_BADGE_TAG)) {
+		customElements.define(CERTREV_BADGE_TAG, CertRevBadgeElement)
+	}
+}

package/src/webcomponent/render-badge-html.ts

@@ -0,0 +1,106 @@
+/**
+ * Framework-agnostic badge HTML renderer.
+ *
+ * The single source of badge markup for BOTH the Web Component (client upgrade) and any
+ * server-side include that wants to emit the badge as a string without React. It mirrors
+ * the <CertBadge> JSX one-for-one — same classes, same structure, same accessibility —
+ * but builds an HTML string, so EVERY interpolated field is escaped by hand
+ * (`escapeHtml` for content, `escapeAttribute` for attributes, `safeHttpUrl` for hrefs).
+ *
+ * It is pure + DOM-free, so it runs server-side (the SSR string the crawler sees) and is
+ * reused client-side by the Web Component. Crawlability requirement from the contract:
+ * the badge must be in the server HTML, never client-only.
+ */
+
+import { escapeAttribute, escapeHtml, safeCssColor, safeHttpUrl } from '../components/escape.js'
+import { credentialSuffix, formatDate, resolveDisplay } from '../components/format.js'
+import type { CertPayload } from '../contract/kernel.js'
+
+export interface RenderBadgeOptions {
+	readonly accentColor?: string
+	readonly badgeStyle?: 'full' | 'compact'
+}
+
+const C = 'certrev-badge'
+
+function attr(name: string, value: string | null | undefined): string {
+	if (value == null || value === '') return ''
+	return ` ${name}="${escapeAttribute(value)}"`
+}
+
+/**
+ * Render the certified-badge markup for a verified payload as an HTML string. Returns ''
+ * when there is nothing safe to link to AND nothing to show (defensive; the kernel has
+ * already decided to render by the time this is called).
+ */
+export function renderBadgeHtml(payload: CertPayload, opts: RenderBadgeOptions = {}): string {
+	const content = payload.content
+	const display = resolveDisplay(content.display, opts.accentColor)
+	const style = opts.badgeStyle ?? display.badgeStyle
+	const accent = safeCssColor(display.accentColor) ?? '#0f766e'
+	const verifyUrl = safeHttpUrl(content.verifyUrl)
+	const profileUrl = safeHttpUrl(content.expert.profileUrl)
+	const photoUrl = style === 'full' && display.showExpertPhoto ? safeHttpUrl(content.expert.photoUrl) : null
+	const suffix = credentialSuffix(content)
+	const certified = formatDate(content.certifiedAt)
+	const updated = formatDate(content.contentModifiedAt)
+
+	const name = `${escapeHtml(content.expert.displayName)}${
+		suffix ? `<span class="${C}__credentials">, ${escapeHtml(suffix)}</span>` : ''
+	}`
+	const nameNode = profileUrl
+		? `<a class="${C}__expert-link" href="${escapeAttribute(profileUrl)}" rel="noopener">${name}</a>`
+		: name
+
+	const mark =
+		`<svg class="${C}__mark" width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true" focusable="false">` +
+		`<circle cx="12" cy="12" r="11" fill="${escapeAttribute(accent)}"></circle>` +
+		`<path d="M7 12.5l3.2 3.2L17 9" stroke="#ffffff" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"></path></svg>`
+
+	const photo = photoUrl
+		? `<img class="${C}__photo" src="${escapeAttribute(photoUrl)}" alt="Photo of ${escapeAttribute(content.expert.displayName)}" width="40" height="40" loading="lazy" decoding="async" />`
+		: ''
+
+	const header =
+		`<div class="${C}__header">${mark}${photo}` +
+		`<div class="${C}__heading">` +
+		`<span class="${C}__eyebrow">Expert reviewed</span>` +
+		`<span class="${C}__byline">Reviewed by ${nameNode}</span>` +
+		`</div></div>`
+
+	let body = ''
+	if (style === 'full') {
+		if (display.showMemo && content.memo) {
+			body += `<p class="${C}__memo">${escapeHtml(content.memo)}</p>`
+		}
+		if (display.showAuthor && content.author.name && content.author.name !== content.expert.displayName) {
+			const title = content.author.title ? `, ${escapeHtml(content.author.title)}` : ''
+			body += `<p class="${C}__author">Written by ${escapeHtml(content.author.name)}${title}</p>`
+		}
+		const dates: string[] = []
+		if (certified) {
+			dates.push(
+				`<div class="${C}__date"><dt>Certified</dt><dd><time datetime="${escapeAttribute(content.certifiedAt)}">${escapeHtml(certified)}</time></dd></div>`,
+			)
+		}
+		if (updated && content.contentModifiedAt) {
+			dates.push(
+				`<div class="${C}__date"><dt>Last updated</dt><dd><time datetime="${escapeAttribute(content.contentModifiedAt)}">${escapeHtml(updated)}</time></dd></div>`,
+			)
+		}
+		if (dates.length) body += `<dl class="${C}__dates">${dates.join('')}</dl>`
+	}
+
+	const verify = verifyUrl
+		? `<a class="${C}__verify" href="${escapeAttribute(verifyUrl)}" rel="noopener" aria-label="Verify this certification on CertREV">Verify on CertREV</a>`
+		: ''
+
+	const ariaLabel = `Content reviewed by ${content.expert.displayName}${suffix ? `, ${suffix}` : ''}`
+	const rootStyle = `--certrev-accent:${accent};border-inline-start-color:${accent}`
+
+	return (
+		`<section class="${C} ${C}--${escapeAttribute(style)}" style="${escapeAttribute(rootStyle)}"` +
+		attr('data-certrev-cert-id', payload.certId) +
+		` aria-label="${escapeAttribute(ariaLabel)}">${header}${body}${verify}</section>`
+	)
+}