@certrev/cert-block 1.0.2 → 1.1.0

package/dist/verify/get-verified-delivery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-verified-delivery.js","sourceRoot":"","sources":["../../src/verify/get-verified-delivery.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@certrev/cert-block",
-	"version": "1.0.2",
+	"version": "1.1.0",
 	"description": "Headless render edge for the CertREV CertDeliveryEnvelope: SSR-safe React cert components, a framework-agnostic <certrev-badge> Web Component, a schema.org JSON-LD projector, and a fail-closed verify layer over the shared VerdictKernel.",
 	"repository": {
 		"type": "git",
@@ -23,6 +23,10 @@
 			"types": "./dist/builder/index.d.ts",
 			"default": "./dist/builder/index.js"
 		},
+		"./builder/face": {
+			"types": "./dist/builder/envelope-face.d.ts",
+			"default": "./dist/builder/envelope-face.js"
+		},
 		"./webcomponent": {
 			"types": "./dist/webcomponent/certrev-badge.d.ts",
 			"default": "./dist/webcomponent/certrev-badge.js"

package/src/builder/cert-chrome-data.ts

@@ -60,6 +60,25 @@ export interface CertChromeRenderDef {
 	readonly customFace?: { readonly placedFields: readonly string[] }
 }
 
+/**
+ * The DELIVERY MARKER (1.1.0): the exporter's statement that this block's cert is served,
+ * signed, by the CertREV Delivery API at `baseUrl`. When it is present the card no longer
+ * paints the other option keys: it takes its `externalId` from its own Builder entry id,
+ * fetches `GET {baseUrl}/api/cert/v1/delivery/builder/{externalId}`, verifies the envelope
+ * against the baked issuer key, and paints from the verified facts plus the brand's render
+ * def served beside them. A revoked, expired or unverifiable cert renders nothing.
+ *
+ * `baseUrl` is honoured ONLY when it is `https:` on `certrev.com` or a subdomain of it. The
+ * marker is an option like any other, so an editor can type into it; a foreign origin would
+ * let a page answer its own revocation check, and so renders nothing (never the options).
+ */
+export interface CertDeliveryMarker {
+	/** Marker shape version. Only `1` is understood; anything else renders nothing. */
+	readonly v: 1
+	/** The CertREV app origin that serves the Delivery API (e.g. `https://portal.certrev.com`). */
+	readonly baseUrl: string
+}
+
 /**
  * The OPTIONS a brand's native cert component receives. Delivered per certified
  * article; until the brand registers the component the block renders nothing.
@@ -131,6 +150,13 @@ export interface BuilderCertChromeData {
 	renderDef: CertChromeRenderDef | null
 	/** Version of the delivered string set (`data-certrev-strings-version` for the crawl monitor). */
 	stringsVersion: string
+	/**
+	 * 1.1.0: where the signed envelope for this block is served, or null for an options-only
+	 * block. Present ⇒ the card paints from the verified envelope + def and ignores the keys
+	 * above; they stay on the wire so installs older than 1.1.0 keep painting during the
+	 * transition. See `CertDeliveryMarker`.
+	 */
+	delivery: CertDeliveryMarker | null
 }
 
 /**
@@ -160,6 +186,7 @@ export const BUILDER_CERT_CHROME_KEYS = [
 	'display',
 	'renderDef',
 	'stringsVersion',
+	'delivery',
 ] as const
 
 export type BuilderCertChromeKey = (typeof BUILDER_CERT_CHROME_KEYS)[number]

package/src/builder/cert-review-card.tsx

@@ -18,10 +18,16 @@
  *  - honors `display.showCredentials`.
  */
 
+import * as React from 'react'
+import { Suspense } from 'react'
+import { memoToggleFor, toggleMemo } from '../components/memo-toggle.js'
 import { type CertBlockMode, renderCertBlock } from '../components/render-cert-block.js'
-import type { ResolvedBlockTheme } from '../components/render-def.js'
+import { CERT_STRINGS_VERSION, type ResolvedBlockTheme } from '../components/render-def.js'
+import { getVerifiedDelivery, peekVerifiedDelivery, type VerifiedDelivery } from '../verify/get-verified-delivery.js'
 import type { BuilderCertChromeData } from './cert-chrome-data.js'
 import { BUILDER_CERT_CHROME_KEYS } from './cert-chrome-data.js'
+import { cardDeliveryRuntime } from './delivery-runtime.js'
+import { envelopeCardInput } from './envelope-face.js'
 
 /**
  * The canonical Builder block name. A brand's registration + the portal
@@ -33,8 +39,12 @@ export const CERT_COMPONENT_NAME = 'CertREV Cert'
 export interface CertReviewCardProps extends Partial<BuilderCertChromeData> {
 	/**
 	 * Placement face — the ENTRY/editor chooses this, NOT the exporter (not a wire-type field).
-	 * Absent ⇒ whatever `renderCertBlock` defaults to (`sidebar`); this component names no
-	 * fallback of its own, so there is exactly ONE place the default is written down.
+	 *
+	 * Absent ⇒ `banner`, via the compatibility bridge in the render body below. That is NOT the
+	 * package default: a direct `renderCertBlock` caller omitting `mode` gets `sidebar`, and
+	 * `sidebar` is the registered input's `defaultValue`, so blocks created in the editor carry
+	 * an explicit `mode`. The bridge covers only entries exported before the exporter emitted
+	 * `mode` at all, and is deleted once those are backfilled. See the render body for why.
 	 */
 	mode?: CertBlockMode | null
 	/**
@@ -45,6 +55,13 @@ export interface CertReviewCardProps extends Partial<BuilderCertChromeData> {
 	 * string-splitting shim is gone — `renderCertBlock` composes each part directly.
 	 */
 	part?: 'full' | 'header' | 'memo' | null
+	/**
+	 * 1.1.0: what `@builder.io/sdk-react` passes because the registration sets
+	 * `shouldReceiveBuilderProps: { builderContext: true }`. Only `content.id` is read: it is the
+	 * Builder entry this block renders inside, which IS the Delivery placement's `externalId`, so a
+	 * block copied onto another entry asks for that entry's cert and never shows this one's.
+	 */
+	builderContext?: { readonly content?: { readonly id?: unknown } | null } | null
 }
 
 /**
@@ -83,7 +100,121 @@ function fusedCredential(pair: BuilderCertChromeData['credentialVerification'] |
 	return credential && verifiedAt ? { credential, verifiedAt } : null
 }
 
+/**
+ * The delivery marker, accepted only as `{ v: 1, baseUrl }` with `baseUrl` an `https:` ORIGIN on
+ * `certrev.com` or one of its subdomains (no path, query, credentials or port). Anything else is
+ * null, and a block carrying a marker that is not accepted renders NOTHING: falling back to the
+ * options would let an edit to the marker switch revocation off.
+ */
+export function acceptedDeliveryMarker(value: unknown): { readonly baseUrl: string } | null {
+	if (typeof value !== 'object' || value === null || Array.isArray(value)) return null
+	const { v, baseUrl } = value as { v?: unknown; baseUrl?: unknown }
+	if (v !== 1 || typeof baseUrl !== 'string') return null
+	let url: URL
+	try {
+		url = new URL(baseUrl)
+	} catch {
+		return null
+	}
+	if (url.protocol !== 'https:' || url.username || url.password || url.port) return null
+	if (url.pathname !== '/' || url.search || url.hash) return null
+	const host = url.hostname.toLowerCase()
+	if (host !== 'certrev.com' && !host.endsWith('.certrev.com')) return null
+	return { baseUrl: url.origin }
+}
+
+/**
+ * Suspend on a Delivery read. React 19 gets `use` with ONE promise per placement while it is in
+ * flight; React 18 (no `use`) gets the promise thrown, the Suspense protocol it supports. Either
+ * way the retry finds the settled read in the cache through `peekVerifiedDelivery`, so it never
+ * suspends on a second promise.
+ */
+const inflightReads = new Map<string, Promise<VerifiedDelivery>>()
+function suspendOn(key: string, start: () => Promise<VerifiedDelivery>): VerifiedDelivery {
+	let pending = inflightReads.get(key)
+	if (!pending) {
+		pending = start().finally(() => inflightReads.delete(key))
+		inflightReads.set(key, pending)
+	}
+	const use = (React as unknown as { use?: <T>(p: Promise<T>) => T }).use
+	if (typeof use === 'function') return use(pending)
+	throw pending
+}
+
+/**
+ * The painted envelope face, with the phone memo toggle bound. One native click listener on the
+ * wrapper (delegated, so it survives a re-render of the HTML) flips the memo box the button sits
+ * in; the button is native, so Enter and Space reach it as clicks. Bound after hydration only: the
+ * server HTML is the collapsed face, which is also what a reader without JS keeps (the whole memo
+ * is still in the text for a screen reader, and the desktop never clamps it).
+ */
+function EnvelopeFace(props: { readonly html: string; readonly defVersion: number | undefined }) {
+	const ref = React.useRef<HTMLDivElement>(null)
+	React.useEffect(() => {
+		const el = ref.current
+		if (!el) return
+		const onClick = (e: MouseEvent) => {
+			const button = memoToggleFor(e.target)
+			if (button && el.contains(button)) toggleMemo(button)
+		}
+		el.addEventListener('click', onClick)
+		return () => el.removeEventListener('click', onClick)
+	}, [])
+	return (
+		<div
+			ref={ref}
+			data-certrev-cert-chrome=""
+			// Marks a face painted from the verified envelope (the migration dry-run and crawl monitor
+			// tell the two faces apart by it). The strings are the package's locked constants here.
+			data-certrev-delivery=""
+			data-certrev-strings-version={CERT_STRINGS_VERSION}
+			data-certrev-def-version={props.defVersion}
+			// biome-ignore lint/security/noDangerouslySetInnerHtml: renderCertBlock is the escaping-safe SSR string renderer
+			dangerouslySetInnerHTML={{ __html: props.html }}
+		/>
+	)
+}
+
+function EnvelopeCertReviewCard(props: {
+	readonly baseUrl: string
+	readonly externalId: string
+	readonly mode: unknown
+	readonly part: unknown
+}) {
+	const rt = cardDeliveryRuntime()
+	// The clock is read per render, so the lifecycle is judged NOW, not when the envelope was fetched.
+	const context = { platform: 'builder', externalId: props.externalId, now: new Date(rt.now()) }
+	const read = { baseUrl: props.baseUrl, platform: 'builder', externalId: props.externalId, context, cache: rt.cache }
+	const settled =
+		peekVerifiedDelivery(read) ??
+		suspendOn(`${props.baseUrl}|${props.externalId}`, () =>
+			getVerifiedDelivery({ ...read, resolveKid: rt.resolveKid, fetchImpl: rt.fetchImpl(), timeoutMs: rt.timeoutMs }),
+		)
+	// Revoked, expired, unverifiable, for another entry, or unreachable: nothing at all.
+	if (settled.verdict.decision !== 'render') return null
+	const input = envelopeCardInput(settled.verdict.payload.content, settled.renderDef, {
+		mode: props.mode,
+		part: props.part,
+	})
+	if (!input) return null
+	return <EnvelopeFace html={renderCertBlock(input)} defVersion={settled.renderDef ? settled.renderDef.v : undefined} />
+}
+
 export function CertReviewCard(props: CertReviewCardProps) {
+	// 1.1.0: a block that carries the delivery marker paints from the signed envelope and the
+	// brand's def, never from the options beside it. No marker (every entry exported before 1.1.0)
+	// takes the options path below, unchanged from 1.0.3.
+	if (props.delivery != null) {
+		const marker = acceptedDeliveryMarker(props.delivery)
+		const entryId = text(props.builderContext?.content?.id)
+		if (!marker || !entryId) return null
+		return (
+			<Suspense fallback={null}>
+				<EnvelopeCertReviewCard baseUrl={marker.baseUrl} externalId={entryId} mode={props.mode} part={props.part} />
+			</Suspense>
+		)
+	}
+
 	const reviewerName = text(props.reviewerName)
 	const verifyUrl = text(props.verifyUrl)
 	if (!reviewerName || !verifyUrl) return null // no chrome pre-cert (or an unreadable delivery)
@@ -106,12 +237,28 @@ export function CertReviewCard(props: CertReviewCardProps) {
 		: undefined
 
 	const html = renderCertBlock({
-		// NO fallback here, deliberately: `renderCertBlock` owns the ONE placement default
-		// (absent or unrecognised ⇒ sidebar). This line used to say `?? 'banner'`, and it was
-		// one of THREE layers each naming a default — here, the registered input's helper text,
-		// and the wire type's own doc comment — while the renderer, the only place that actually
-		// paints a face, named none. Three copies of a default is three chances to disagree.
-		mode: props.mode ?? undefined,
+		// COMPATIBILITY BRIDGE, NOT THE DESIGN. Delete this fallback once the exporter emits an
+		// explicit `mode` and existing entries have been backfilled; until then it must stay.
+		//
+		// `renderCertBlock` owns the ONE placement default (absent or unrecognised ⇒ sidebar) and
+		// that decision STANDS: it is what a direct caller gets, and `sidebar` is the registered
+		// input's `defaultValue`, so every block created in the editor from now on carries an
+		// explicit `mode` and never reaches this line.
+		//
+		// The problem is the entries that already exist. `mode` is a PLACEMENT input, not one of
+		// the 20 wire keys (`BUILDER_CERT_CHROME_KEYS`), and the exporter emits only the wire
+		// projection (`options: { ...certData }`), so every entry exported to date has NO `mode`
+		// key at all. Through 0.5.5 this line read `?? 'banner'` and those entries rendered the
+		// banner face. Removing it in 1.0.0 did not give them the renderer's default in the
+		// abstract; it silently repainted live pages from banner to sidebar, with no entry edit
+		// and no version pin to protect them, because their install line is unpinned.
+		//
+		// So this is a bridge for pre-existing entries, NOT a reversal of the sidebar default.
+		// The three-copies-of-a-default problem that motivated removing it is still real and is
+		// still fixed: the helper text and the wire type's doc comment no longer name a default,
+		// and this line names one only for input the renderer can no longer distinguish from a
+		// deliberate choice. The exporter writing `mode` is what retires it.
+		mode: props.mode ?? 'banner',
 		theme,
 		// First-class banner memo split — renderCertBlock composes the requested
 		// part directly; no string-splitting. Ignored outside banner mode, and an unrecognised
@@ -204,6 +351,7 @@ const WIRE_INPUT_TYPE: Record<(typeof BUILDER_CERT_CHROME_KEYS)[number], Builder
 	display: 'object',
 	renderDef: 'object',
 	stringsVersion: 'string',
+	delivery: 'object',
 }
 
 /**
@@ -221,10 +369,12 @@ const WIRE_INPUT_HELPER_TEXT: Partial<Record<(typeof BUILDER_CERT_CHROME_KEYS)[n
 		'System-populated by CertREV. Only its PRESENCE is read (absent = a pro-bono reviewer, so no cue renders); the cue itself is a locked constant, so editing this text changes nothing on the page, and clearing it does not remove the disclosure.',
 	scopeLine:
 		'System-populated by CertREV. The FTC scope line renders byte-verbatim from a locked constant: editing this text changes nothing on the page.',
+	delivery:
+		'System-populated by CertREV. When set, the card shows the certificate CertREV serves for this entry, verified, and ignores the other fields; if CertREV revokes it or it expires, the card shows nothing. Do not edit.',
 }
 
 /**
- * The wire-type inputs — DERIVED from `BUILDER_CERT_CHROME_KEYS`, so the 19-field
+ * The wire-type inputs — DERIVED from `BUILDER_CERT_CHROME_KEYS`, so the 20-field
  * option set can never drift from the type (the W3 lock asserts name-parity). This
  * kills the demo's hand-maintained 17-entry array.
  */
@@ -279,6 +429,8 @@ export interface CertBlockBuilderRegistration {
 	readonly name: string
 	readonly component: typeof CertReviewCard
 	readonly inputs: readonly BuilderInput[]
+	/** 1.1.0: asks the SDK for `builderContext`, whose `content.id` the delivery path reads. */
+	readonly shouldReceiveBuilderProps: { readonly builderContext: true }
 }
 
 /**
@@ -293,6 +445,7 @@ export const BUILDER_REGISTRATION: CertBlockBuilderRegistration = {
 	name: CERT_COMPONENT_NAME,
 	component: CertReviewCard,
 	inputs: [...PLACEMENT_INPUTS, ...WIRE_INPUTS],
+	shouldReceiveBuilderProps: { builderContext: true },
 }
 
 /**
@@ -306,6 +459,12 @@ export interface CertReviewCardRegisteredComponent {
 	name: string
 	description?: string
 	inputs: BuilderInput[]
+	/**
+	 * 1.1.0: `@builder.io/sdk-react`'s `RegisteredComponent.shouldReceiveBuilderProps`. The SDK then
+	 * passes the `builderContext` prop, and the delivery path takes its placement from
+	 * `builderContext.content.id`.
+	 */
+	shouldReceiveBuilderProps: { builderContext: boolean }
 }
 
 /**
@@ -320,4 +479,5 @@ export const certRevCertComponent: CertReviewCardRegisteredComponent = {
 	description:
 		'CertREV expert-review cert card. Options are populated by the CertREV exporter; editors choose placement (mode/part) only.',
 	inputs: [...PLACEMENT_INPUTS, ...WIRE_INPUTS],
+	shouldReceiveBuilderProps: { builderContext: true },
 }

package/src/builder/delivery-runtime.ts

@@ -0,0 +1,54 @@
+/**
+ * The Builder card's Delivery runtime (1.1.0): the trust root, fetch, cache and clock the
+ * envelope-backed `CertReviewCard` reads with.
+ *
+ * INTERNAL. This module is deliberately NOT on the package `exports` map, so a consumer cannot
+ * swap the trust root through the published API: the card verifies against the baked
+ * `cert-issuer-1` key, the same key the storefront badge bundle ships. The package's own tests
+ * reach the setter by relative import to run the real kernel against fixture-signed envelopes.
+ */
+
+import type { ResolvePublicKeyByKid } from '../contract/kernel.js'
+import { TtlCache } from '../verify/cache.js'
+import type { CachedDelivery } from '../verify/get-verified-delivery.js'
+import { CERT_ISSUER_KID, CERT_ISSUER_PUBLIC_KEY_PEM } from './issuer-key.js'
+
+export interface CardDeliveryRuntime {
+	readonly resolveKid: ResolvePublicKeyByKid
+	readonly fetchImpl: () => typeof fetch
+	readonly cache: TtlCache<CachedDelivery>
+	readonly now: () => number
+	readonly timeoutMs?: number
+}
+
+const bakedResolveKid: ResolvePublicKeyByKid = (kid) =>
+	kid === CERT_ISSUER_KID ? { format: 'pem', pem: CERT_ISSUER_PUBLIC_KEY_PEM } : null
+
+function defaultRuntime(): CardDeliveryRuntime {
+	return {
+		resolveKid: bakedResolveKid,
+		fetchImpl: () => globalThis.fetch,
+		cache: new TtlCache<CachedDelivery>({ ttlMs: 60_000, negativeTtlMs: 5_000 }),
+		now: Date.now,
+	}
+}
+
+let runtime: CardDeliveryRuntime = defaultRuntime()
+
+export function cardDeliveryRuntime(): CardDeliveryRuntime {
+	return runtime
+}
+
+/** Test seam: replace parts of the runtime (a fresh cache unless one is given). Returns a restore. */
+export function setCardDeliveryRuntimeForTests(overrides: Partial<CardDeliveryRuntime>): () => void {
+	const previous = runtime
+	const now = overrides.now ?? previous.now
+	runtime = {
+		...previous,
+		cache: new TtlCache<CachedDelivery>({ ttlMs: 60_000, negativeTtlMs: 5_000, now }),
+		...overrides,
+	}
+	return () => {
+		runtime = previous
+	}
+}

package/src/builder/envelope-face.ts

@@ -0,0 +1,173 @@
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ * `envelopeCardInput` — the Builder card's face, from VERIFIED facts + the brand's def (1.1.0)
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * The one mapping from a verified payload's `content` and the Delivery API's `renderDef` sibling
+ * to the `renderCertBlock` input the registered `CertReviewCard` paints. It is its own module,
+ * react-free, and exported on the `./builder/face` subpath so the portal's server bundle (which
+ * cannot load `./builder`: that entry creates a React context at import) renders its preview
+ * through THIS function instead of a copy of it. A preview and the live card that share the
+ * mapping cannot disagree about it.
+ *
+ * The facts are read exactly as the Shopify app embed reads the same envelope:
+ *  - the credential is each verified credential's `cardLabel` (else `abbreviation`), joined, and
+ *    only with the dated verification beside it; no date, no credential (the name-only face);
+ *  - the compensation cue's PRESENCE is the only thing read; the words are the locked constant,
+ *    and an absent or null cue is the pro-bono face with no cue;
+ *  - the def's `hidden` set removes only what is hideable (`HIDEABLE_FIELDS`); a def cannot hide
+ *    the scope line, the credential verification or the certificate link.
+ *
+ * The face is the PHONE-aware one (`responsive`): on a narrow viewport the banner header stacks and
+ * a long memo collapses behind a toggle the card binds (`memo-toggle.ts`); a wider viewport paints
+ * exactly what it would without it.
+ *
+ * The caller has already run the kernel. This function never decides WHETHER to render a cert;
+ * it only returns null when the verified content cannot make a face (no reviewer, no verify URL).
+ */
+
+import type {
+	CertBlockFace,
+	CertBlockLayout,
+	CertBlockMode,
+	RenderCertBlockInput,
+} from '../components/render-cert-block.js'
+import { accentFg, HIDEABLE_FIELDS, isOpaqueHexColor, type ResolvedBlockTheme } from '../components/render-def.js'
+import type { CertContent } from '../contract/kernel.js'
+import type { CertChromeRenderDef } from './cert-chrome-data.js'
+
+/**
+ * Every field id `renderCertBlock` places, in its canonical order. A def-driven face places all of
+ * them except what the def hides; `renderCertBlock` still gates each on its fact being present.
+ */
+export const CERT_FACE_FIELDS = [
+	'label',
+	'authorName',
+	'authorTitle',
+	'reviewerPhoto',
+	'bylineCredentialed',
+	'bylinePlain',
+	'bio',
+	'memo',
+	'profileLink',
+	'certificateLink',
+	'scopeLine',
+	'compensationCue',
+] as const
+
+const MODES: readonly CertBlockMode[] = ['banner', 'sidebar', 'floating']
+
+function isMode(v: unknown): v is CertBlockMode {
+	return typeof v === 'string' && (MODES as readonly string[]).includes(v)
+}
+
+function text(v: unknown): string {
+	return typeof v === 'string' ? v : ''
+}
+
+function optionalText(v: unknown): string | undefined {
+	return text(v).trim() !== '' ? (v as string) : undefined
+}
+
+export interface EnvelopeCardOptions {
+	/** The placement the entry/editor chose. A recognised mode wins over the def's layout. */
+	readonly mode?: unknown
+	/** Banner memo placement, passed through as on the options path. */
+	readonly part?: unknown
+}
+
+/** The def's theme tokens as `renderCertBlock` theme input, with the accent ink derived. */
+export function themeFromDef(def: CertChromeRenderDef | null): Partial<ResolvedBlockTheme> | undefined {
+	const tokens = def?.tokens
+	if (!tokens) return undefined
+	const accentColor = optionalText(tokens.accentColor)
+	return {
+		accentColor,
+		surface: optionalText(tokens.surface),
+		cornerRadius: optionalText(tokens.cornerRadius),
+		fontSlot: optionalText(tokens.fontSlot) as ResolvedBlockTheme['fontSlot'] | undefined,
+		// The ink painted over the accent fill, derived the way the portal derives it, so a black
+		// accent carries white ink. Omitted for an accent `resolveBlockTheme` would reject anyway.
+		...(accentColor && isOpaqueHexColor(accentColor) ? { accentFg: accentFg(accentColor) } : {}),
+		barInk: optionalText(tokens.barInk),
+		inkColor: optionalText(tokens.inkColor),
+	}
+}
+
+/** The face a def asks for: its custom composition, or every field minus the hideable ones it hides. */
+export function faceFromDef(def: CertChromeRenderDef | null, layout: CertBlockLayout): CertBlockFace | undefined {
+	if (!def) return undefined
+	if (layout === 'custom') return { rung: def.rung, placedFields: [...(def.customFace?.placedFields ?? [])] }
+	const hidden = new Set(def.hidden.filter((id) => (HIDEABLE_FIELDS as readonly string[]).includes(id)))
+	return { rung: def.rung, placedFields: CERT_FACE_FIELDS.filter((id) => !hidden.has(id)) }
+}
+
+/**
+ * The layout: an editor-chosen mode, else the def's own layout (a custom face only when the def
+ * carries one), else banner, which is what the Shopify embed paints for a def with no layout and
+ * what every exported Builder entry has painted since 0.5.
+ */
+export function layoutFor(def: CertChromeRenderDef | null, mode: unknown): CertBlockLayout {
+	if (isMode(mode)) return mode
+	if (def?.layout === 'custom' && def.customFace) return 'custom'
+	if (isMode(def?.layout)) return def.layout
+	return 'banner'
+}
+
+/** The fused credential label the envelope's verified credentials stand for, or '' (name-only). */
+export function credentialLabel(expert: Record<string, unknown>): { credential: string; verifiedAt: string } | null {
+	const verifiedAt = optionalText(expert.credentialVerifiedAt)
+	if (!verifiedAt) return null
+	const creds = Array.isArray(expert.credentials) ? expert.credentials : []
+	const credential = creds
+		.map((c) => {
+			const rec = (typeof c === 'object' && c !== null ? c : {}) as Record<string, unknown>
+			return optionalText(rec.cardLabel) ?? optionalText(rec.abbreviation)
+		})
+		.filter((l): l is string => l !== undefined)
+		.join(', ')
+	return credential ? { credential, verifiedAt } : null
+}
+
+/**
+ * The exact `renderCertBlock` input for a verified envelope's content and the brand's def, or
+ * null when the content cannot make a face.
+ */
+export function envelopeCardInput(
+	content: CertContent,
+	renderDef: CertChromeRenderDef | null,
+	options: EnvelopeCardOptions = {},
+): RenderCertBlockInput | null {
+	const expert = (content?.expert ?? {}) as unknown as Record<string, unknown>
+	const author = (content?.author ?? {}) as unknown as Record<string, unknown>
+	const reviewerName = text(expert.displayName)
+	const verifyUrl = text(content?.verifyUrl)
+	if (!reviewerName || !verifyUrl) return null
+	const cred = credentialLabel(expert)
+	const layout = layoutFor(renderDef, options.mode)
+	const face = faceFromDef(renderDef, layout)
+	const theme = themeFromDef(renderDef)
+	const part =
+		options.part === 'full' || options.part === 'header' || options.part === 'memo' ? options.part : undefined
+	return {
+		mode: layout,
+		...(theme ? { theme } : {}),
+		...(face ? { face } : {}),
+		...(part ? { part } : {}),
+		responsive: true,
+		facts: {
+			authorName: optionalText(author.name) ?? 'Editorial',
+			authorTitle: optionalText(author.title),
+			reviewerName,
+			credential: cred?.credential ?? '',
+			credentialVerifiedAt: cred?.verifiedAt ?? '',
+			certifiedAt: text(content.certifiedAt),
+			memo: text(content.memo),
+			bio: optionalText(expert.bio),
+			profileUrl: text(expert.profileUrl),
+			certificateUrl: verifyUrl,
+			// Presence only: a cue string renders the locked constant; absent or null is pro-bono.
+			compensationCue: optionalText(expert.compensationCue) ? undefined : null,
+		},
+	}
+}

package/src/builder/index.tsx

@@ -12,7 +12,7 @@
  * another article, and there is no `placementId` input to forge or mis-select.
  *
  * THE PUSH KIT DOES NOT INHERIT THAT PROPERTY, and this module exports it too. `CertReviewCard` /
- * `certRevCertComponent` register the 19 wire-type fields — `reviewerName`,
+ * `certRevCertComponent` register the 20 wire-type fields — `reviewerName`,
  * `credentialVerification`, `verifyUrl`, `memo` — as Builder INPUTS, and the card renders what
  * those inputs hold; it runs no signature check and consults no verdict. `advanced: true` folds
  * them out of the editor's default view, which is a UI reveal and not a lock, and `safeHttpUrl`
@@ -22,6 +22,17 @@
  * narrows it. See "PUSH trust model" in the package README for the full statement — including
  * what a revocation upstream does and does not reach.
  *
+ * 1.1.0 NARROWS THAT FOR A BLOCK CARRYING THE `delivery` MARKER (`{ v: 1, baseUrl }`, which the
+ * CertREV exporter writes). Such a block ignores every other option: it reads the signed envelope
+ * for the entry it renders inside (`builderContext.content.id`) from the CertREV Delivery API on
+ * `baseUrl` (an https certrev.com origin, nothing else), verifies it against the baked
+ * `cert-issuer-1` key, re-judges revocation and expiry at every render, and paints the brand's
+ * render def served beside it. 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.
+ *
  * 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
  * (the fused pair); and the FTC disclosures render from locked constants, so rewriting the
@@ -95,7 +106,7 @@ export function CertRevEditorPlaceholder() {
 				background: '#fff5fa',
 			}}
 		>
-			CertREV Review — <b>resolves at publish</b> from issuer verification. The expert badge appears here once this
+			CertREV Review: <b>resolves at publish</b> from issuer verification. The expert badge appears here once this
 			page’s article is certified, and only while the credential is valid.
 		</div>
 	)
@@ -144,8 +155,10 @@ export {
 	type BuilderCertChromeData,
 	type BuilderCertChromeKey,
 	type CertChromeRenderDef,
+	type CertDeliveryMarker,
 } from './cert-chrome-data.js'
 export {
+	acceptedDeliveryMarker,
 	BUILDER_REGISTRATION,
 	type BuilderInput,
 	CERT_COMPONENT_NAME,
@@ -157,3 +170,12 @@ export {
 	PLACEMENT_INPUTS,
 	WIRE_INPUTS,
 } from './cert-review-card.js'
+export {
+	CERT_FACE_FIELDS,
+	credentialLabel,
+	type EnvelopeCardOptions,
+	envelopeCardInput,
+	faceFromDef,
+	layoutFor,
+	themeFromDef,
+} from './envelope-face.js'

package/src/builder/issuer-key.ts

@@ -0,0 +1,13 @@
+/**
+ * The CertREV issuer PUBLIC key the envelope-backed Builder card verifies against (1.1.0).
+ *
+ * A copy of `CERT_ISSUER_KID` / `CERT_ISSUER_PUBLIC_KEY_PEM` in `modal/certrev-cert.entry.ts`, not
+ * an import of it: that entry registers a custom element and starts the storefront DOM passes at
+ * import, which a React server render must not do, and moving the constant out of it would change
+ * the storefront bundle the Shopify extension ships byte-for-byte. The two copies are pinned equal by
+ * `builder/__tests__/issuer-key.test.ts`, so a rotation that updates one and not the other fails.
+ */
+export const CERT_ISSUER_KID = 'cert-issuer-1'
+export const CERT_ISSUER_PUBLIC_KEY_PEM = `-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEAMWN956IOPjpAq900dL428VzA28TO/pVXnq3brwqUmwM=
+-----END PUBLIC KEY-----`