@certrev/cert-block 1.0.3 → 1.1.1

package/src/modal/certrev-cert-modal.ts

@@ -23,6 +23,9 @@
  *    so the document-level delegate can't see the close controls.
  *  - Fonts inject at document level on first open (font faces don't scope into a
  *    shadow root); deferring to first open avoids loading them on every article view.
+ *  - A page can carry several faces, each with its own element (a WordPress Query Loop, a
+ *    related-posts block). A trigger opens its OWN face's element (`ownCertModal`), never the
+ *    document's first one, and a suppressed element hides only its own face's triggers.
  */
 
 import { type CertDeliveryArtifact, isTombstone } from '@certrev/cert-contract'
@@ -33,6 +36,44 @@ import { CERT_MODAL_CSS } from './certrev-cert-modal.styles.js'
 export const CERT_MODAL_TAG = 'certrev-cert-modal'
 type ModalKind = 'cert' | 'expert'
 
+/**
+ * One rendered face on a surface that can print several per page: the WordPress plugin wraps each
+ * face's card, memo and rail wraps in `<div data-certrev-cert="1">`. A trigger never reaches a
+ * `<certrev-cert-modal>` in another face root, and one outside every face root never reaches a
+ * modal inside one.
+ */
+export const FACE_ROOT_SELECTOR = '[data-certrev-cert]'
+
+/** The element a trigger opens, or why it has none. */
+export type OwnCertModal =
+	| { readonly modal: Element; readonly reason: null }
+	| { readonly modal: null; readonly reason: 'none' | 'ambiguous'; readonly count: number }
+
+/**
+ * The `<certrev-cert-modal>` that belongs to `trigger`'s face: the one in the SMALLEST subtree that
+ * holds both. Walk up from the trigger; the first ancestor holding a modal decides:
+ *  - exactly one → that is the face's modal. On Shopify the card wrap (badge + modal) and the memo
+ *    wrap (triggers only) are placed apart in the article, and their nearest common container holds
+ *    the page's one modal; a Builder page puts one modal beside the CMS content; a WordPress face root
+ *    holds its own.
+ *  - more than one → `ambiguous`: the trigger's face has no modal of its own and sits between other
+ *    faces'. Picking one would open another cert's certificate, so there is no answer.
+ * The walk never leaves the trigger's face root, and only counts modals in that same face root (or,
+ * for a trigger in none, modals in none), so a WordPress face without a modal resolves to `none`.
+ */
+export function ownCertModal(trigger: Element): OwnCertModal {
+	const face = trigger.closest(FACE_ROOT_SELECTOR)
+	for (let node: Element | null = trigger; node; node = node.parentElement) {
+		const found = Array.from(node.querySelectorAll(CERT_MODAL_TAG)).filter(
+			(m) => m.closest(FACE_ROOT_SELECTOR) === face,
+		)
+		if (found.length === 1) return { modal: found[0] as Element, reason: null }
+		if (found.length > 1) return { modal: null, reason: 'ambiguous', count: found.length }
+		if (node === face) break
+	}
+	return { modal: null, reason: 'none', count: 0 }
+}
+
 /** Shared constructable stylesheet (one per document lifetime). */
 let sharedSheet: CSSStyleSheet | null = null
 function supportsConstructableSheets(): boolean {
@@ -208,11 +249,13 @@ export class CertRevCertModal extends HTMLElement {
 	/**
 	 * The modal kill-switch: a fetched envelope is REVOKED/EXPIRED. Don't open;
 	 * mark the host suppressed (mirrors the badge revalidation's `data-certrev-suppressed`) and
-	 * hide the light-DOM triggers so a stale click can't re-open a pulled cert. Best-effort DOM.
+	 * hide THIS face's light-DOM triggers (those whose `ownCertModal` is this element) so a stale
+	 * click can't re-open a pulled cert. Another face's triggers on the page are not touched.
 	 */
 	private markSuppressed(): void {
 		this.setAttribute('data-certrev-suppressed', '')
-		for (const t of Array.from(document.querySelectorAll('[data-certrev-modal-open]'))) {
+		for (const t of Array.from(this.ownerDocument.querySelectorAll('[data-certrev-modal-open]'))) {
+			if (ownCertModal(t).modal !== this) continue
 			t.setAttribute('hidden', '')
 			t.setAttribute('aria-hidden', 'true')
 		}

package/src/modal/certrev-cert.entry.ts

@@ -10,7 +10,6 @@
 
 import type { ResolvePublicKeyByKid } from '@certrev/cert-contract'
 import './certrev-cert-modal.js' // registers the unified <certrev-cert-modal> element
-import { installFtcGuard } from './ftc-guard.js'
 import { initCertInteractionsOnReady } from './interactions.js'
 import { initCertPlacement } from './placement.js'
 import { initBadgeRevalidation } from './revalidate.js'
@@ -37,10 +36,9 @@ if (typeof document !== 'undefined') {
 	// in-article position — so the badge re-verify pass below finds `<certrev-badge>` already in
 	// place and never re-runs against a detached/re-attached node.
 	initCertPlacement(document)
+	// No disclosure guard since 1.1.1: nothing here hides, replaces or re-checks a face at load or on
+	// mutation, so a face that loads inside a closed <details>, tab or accordion renders when opened.
 	// Tap-to-expand contributor bios + the in-page certificate modal (progressive enhancement).
 	initCertInteractionsOnReady(document)
-	// FTC §3 anti-stripping: neutralize a memo whose verbatim disclosure was stripped/hidden/altered
-	// (restores the iframe kill switch in the native, in-DOM render). No-op when there's no memo.
-	installFtcGuard(document)
 	initBadgeRevalidation(document, { verify: createDeliveryVerifier(resolveKid) })
 }

package/src/modal/deprecated.ts

@@ -0,0 +1,25 @@
+/**
+ * Public names kept only so a patch release never breaks a compiling integration (the semver
+ * contract at the head of CHANGELOG.md). Each one does nothing it used to do; removal is for 2.0.
+ */
+
+/** Dispatched on the document, once per document, on the first call of a removed API, so a caller
+ *  that still relies on it can see that it does nothing. `detail: { api, removedIn }`. */
+export const DEPRECATED_API_EVENT = 'certrev:deprecated-api'
+
+/** Documents that have already been told, so repeated calls dispatch once. */
+const announcedDocs = new WeakSet<Document>()
+
+/**
+ * @deprecated Removed in 1.1.1: the runtime FTC disclosure guard is gone. This installs nothing,
+ * checks nothing and never hides or replaces a face; whether a face shows its disclosure is settled
+ * where the face is configured. The first call per document dispatches {@link DEPRECATED_API_EVENT}.
+ * Will be deleted in 2.0.
+ */
+export function installFtcGuard(doc: Document): void {
+	if (announcedDocs.has(doc)) return
+	announcedDocs.add(doc)
+	doc.dispatchEvent(
+		new CustomEvent(DEPRECATED_API_EVENT, { detail: { api: 'installFtcGuard', removedIn: '1.1.1' } }),
+	)
+}

package/src/modal/ftc-disclosure.ts

@@ -4,9 +4,13 @@
  * module. Legally load-bearing: the curly apostrophe (U+2019) in "article’s"
  * is byte-exact; a reword is a contract divergence.
  *
- * Kept as its OWN module (imported by both ftc-guard + display-strings, exactly as in portal) so
- * the browser bundle emits the same `var` structure as the deployed certrev-cert.js — do not merge
- * it into display-strings.ts (that consolidation drops one `var` and breaks byte-parity).
+ * Kept as its OWN module (imported by display-strings, exactly as in portal) so the browser bundle
+ * emits the same `var` structure as the deployed certrev-cert.js — do not merge it into
+ * display-strings.ts (that consolidation drops one `var` and breaks byte-parity).
+ *
+ * It is the text the faces RENDER, nothing more. Since 1.1.1 nothing in this package checks at
+ * runtime that it is present or visible (the `ftc-guard` kill switch is gone): whether a face shows
+ * its disclosure is settled where the face is configured, not by hiding or replacing it in the page.
  */
 
 export const FTC_DISCLOSURE_LINE =

package/src/modal/index.ts

@@ -6,8 +6,8 @@
  * storefront (`<script src=".../dist/modal/certrev-cert.js">`) instead of vendoring a copy.
  *
  * Importing this module as ESM has the SAME side effect as loading the IIFE: it registers the
- * `<certrev-cert-modal>` element and (in a browser) runs placement + interactions + FTC guard +
- * badge revalidation. Bundler users: `import '@certrev/cert-block/modal'`.
+ * `<certrev-cert-modal>` element and (in a browser) runs placement + interactions + badge
+ * revalidation (no FTC guard since 1.1.1). Bundler users: `import '@certrev/cert-block/modal'`.
  */
 
 // Side-effect: register the element + (in a browser) kick off the DOM passes.
@@ -23,7 +23,8 @@ export {
 
 // Composable entry points for advanced consumers (the IIFE wires these itself).
 export { CERT_MODAL_TAG } from "./certrev-cert-modal.js";
-export { installFtcGuard } from "./ftc-guard.js";
+/** @deprecated Since 1.1.1 a no-op (the runtime FTC guard was removed); deleted in 2.0. */
+export { installFtcGuard } from "./deprecated.js";
 export { initCertInteractionsOnReady } from "./interactions.js";
 export { initCertPlacement } from "./placement.js";
 export {

package/src/modal/interactions.ts

@@ -8,8 +8,8 @@
  *     (revealing the row's `.acc-bio` in place; the name caret rotates via CSS) and mirrors the
  *     state on `aria-expanded`. A click on a link inside the row (e.g. the "Compensated expert"
  *     cue) is NOT a toggle. Keyboard: Enter/Space on the role=button row.
- *   • In-page modals: a `[data-certrev-modal-open]` control opens the unified
- *     `<certrev-cert-modal>` element via its `.open('cert'|'expert')` method. Bare /
+ *   • In-page modals: a `[data-certrev-modal-open]` control opens its OWN face's
+ *     `<certrev-cert-modal>` element (`ownCertModal`) via its `.open('cert'|'expert')` method. Bare /
  *     `"cert"` opens the certificate dialog; `"expert"` opens the reviewer dialog. With no JS / no
  *     element / no envelope a link control falls back to its href (the certificate or the CertREV
  *     profile page). The element owns its OWN close plumbing (× / Close / backdrop / Esc) inside its
@@ -18,12 +18,18 @@
  * No crypto, no network — pure DOM. Idempotent install (guarded so a double-load can't double-bind).
  */
 
-import { CERT_MODAL_TAG } from './certrev-cert-modal.js'
+import { CERT_MODAL_TAG, ownCertModal } from './certrev-cert-modal.js'
 
 export const ACC_ATTR = 'data-certrev-acc'
 export const MODAL_OPEN_ATTR = 'data-certrev-modal-open'
 export const INITIALS_ATTR = 'data-certrev-initials'
 export const CARD_SELECTOR = '.certrev-card'
+/** Stamped on a control that could not tell which modal is its own (value: the reason), beside the
+ *  bubbling {@link MODAL_UNRESOLVED_EVENT}, so the miss is inspectable rather than a silent link. */
+export const MODAL_UNRESOLVED_ATTR = 'data-certrev-modal-unresolved'
+/** Dispatched on a control whose face has no modal of its own but sits between other faces'
+ *  (`ownCertModal` → `ambiguous`). `detail: { reason: 'ambiguous', modals }`. */
+export const MODAL_UNRESOLVED_EVENT = 'certrev:modal-unresolved'
 
 /** The dialog a `data-certrev-modal-open` control targets. */
 export type ModalKind = 'cert' | 'expert'
@@ -53,8 +59,10 @@ export function modalTargetKind(value: string | null): ModalKind {
 	return value === 'expert' ? 'expert' : 'cert'
 }
 
-/** Open a cert dialog via the `<certrev-cert-modal>` element. Returns false (so the caller lets an
- *  href fall back) when the element is absent or declines (no envelope + no fetch source). */
+/** Open a cert dialog via the document's FIRST `<certrev-cert-modal>` element: a page-level helper
+ *  for a page with one face. Controls go through `openOwnModal`, which finds their own face's element.
+ *  Returns false (so the caller lets an href fall back) when the element is absent or declines (no
+ *  envelope + no fetch source). */
 export function openModal(doc: Document, kind: ModalKind): boolean {
 	const el = doc.querySelector(CERT_MODAL_TAG) as CertModalElement | null
 	if (el && typeof el.open === 'function') return el.open(kind)
@@ -66,6 +74,28 @@ export function openCertModal(doc: Document): boolean {
 	return openModal(doc, 'cert')
 }
 
+/**
+ * Open a dialog of `control`'s OWN face's `<certrev-cert-modal>` (see `ownCertModal`), which is what
+ * the delegated click / key handlers do. Returns false (so a link control follows its own href) when
+ * the face has no modal, the element declines, or the control cannot tell which modal is its own; in
+ * that last case it is stamped `data-certrev-modal-unresolved="ambiguous"` and receives
+ * `certrev:modal-unresolved`, and another face's certificate is never opened in its place.
+ */
+export function openOwnModal(control: Element, kind: ModalKind): boolean {
+	const own = ownCertModal(control)
+	if (own.modal) {
+		const el = own.modal as CertModalElement
+		return typeof el.open === 'function' ? el.open(kind) : false
+	}
+	if (own.reason === 'ambiguous') {
+		control.setAttribute(MODAL_UNRESOLVED_ATTR, own.reason)
+		control.dispatchEvent(
+			new CustomEvent(MODAL_UNRESOLVED_EVENT, { bubbles: true, detail: { reason: own.reason, modals: own.count } }),
+		)
+	}
+	return false
+}
+
 function asElement(target: EventTarget | null): Element | null {
 	return target && (target as Element).closest ? (target as Element) : null
 }
@@ -111,7 +141,7 @@ export function initCertInteractions(doc: Document): void {
 		// (Close is owned by the <certrev-cert-modal> element inside its shadow root.)
 		const opener = el.closest(`[${MODAL_OPEN_ATTR}]`)
 		if (opener) {
-			if (openModal(doc, modalTargetKind(opener.getAttribute(MODAL_OPEN_ATTR)))) e.preventDefault()
+			if (openOwnModal(opener, modalTargetKind(opener.getAttribute(MODAL_OPEN_ATTR)))) e.preventDefault()
 			return
 		}
 
@@ -144,7 +174,7 @@ export function initCertInteractions(doc: Document): void {
 
 		const opener = el.closest(`[${MODAL_OPEN_ATTR}]`)
 		if (opener) {
-			if (openModal(doc, modalTargetKind(opener.getAttribute(MODAL_OPEN_ATTR)))) {
+			if (openOwnModal(opener, modalTargetKind(opener.getAttribute(MODAL_OPEN_ATTR)))) {
 				e.preventDefault()
 				return
 			}

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

@@ -0,0 +1,211 @@
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ * getVerifiedDelivery — the envelope PLUS the brand's render def, from the Delivery API
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * 1.1.0. The Delivery API answers a Builder placement with the signed artifact and, beside it,
+ * the brand's resolved render-def projection as a top-level `renderDef` sibling (the same shape a
+ * Shopify store carries in its `render_def` metafield). The envelope's signature covers `payload`
+ * only, so the sibling rides the response without touching the signed bytes, and a tombstone
+ * carries none. `getVerifiedEnvelope` keeps discarding it; this reads it.
+ *
+ * The same fetch, deadline, kernel and fail-closed rules as `getVerifiedEnvelope` (every sourcing
+ * failure reports the reason it actually is; nothing throws into the render path). Two things are
+ * different, and both are the point:
+ *
+ *  1. WHAT IS CACHED is the cryptographically verified PAYLOAD, not the verdict. The lifecycle
+ *     policy (revoked, expired) and the subject match are re-run by `renderVerdict` on EVERY call,
+ *     with the caller's clock. So a payload that was valid when fetched and expires while cached
+ *     stops rendering at its `expiresAt`, not at the next refetch; and a refetch after the TTL
+ *     picks up a tombstone (revocation) or a changed def with no write on the brand's side.
+ *  2. The CACHE KEY is the Delivery URL plus the rendering placement, so a staging and a
+ *     production origin never share an entry, and neither do two placements.
+ *
+ * `peekVerifiedDelivery` is the synchronous read of the same cache: a React component suspends on
+ * `getVerifiedDelivery` once, then reads the settled value without a second promise (which is what
+ * keeps a streaming SSR render from suspending forever on a fresh promise every retry).
+ */
+
+import type { CertChromeRenderDef } from '../builder/cert-chrome-data.js'
+import type {
+	CertDeliveryArtifact,
+	CertPayload,
+	CertSuppressReason,
+	CertVerdict,
+	RenderContext,
+	ResolvePublicKeyByKid,
+} from '../contract/kernel.js'
+import { renderVerdict, verifyArtifact } from '../contract/kernel.js'
+import { TtlCache } from './cache.js'
+import { DEFAULT_FETCH_TIMEOUT_MS, fetchWithDeadline } from './fetch-with-deadline.js'
+
+/** What one Delivery read settles to, as cached: a verified payload + its def, or the reason not. */
+export type CachedDelivery =
+	| { readonly kind: 'verified'; readonly payload: CertPayload; readonly renderDef: CertChromeRenderDef | null }
+	| { readonly kind: 'suppressed'; readonly reason: CertSuppressReason }
+
+/** The answer for one render: the verdict AT THIS RENDER'S CLOCK, and the def to paint it with. */
+export interface VerifiedDelivery {
+	readonly verdict: CertVerdict
+	/** The brand's render def, or null (no def resolved, a malformed one, or a suppress verdict). */
+	readonly renderDef: CertChromeRenderDef | null
+}
+
+export interface GetVerifiedDeliveryOptions {
+	/** Base URL of the CertREV app that serves the Delivery API, e.g. 'https://portal.certrev.com'. */
+	readonly baseUrl: string
+	readonly platform: string
+	readonly externalId: string
+	/** kid → public-key resolver. Required: no verify without keys. */
+	readonly resolveKid: ResolvePublicKeyByKid
+	/** Render context: the platform + externalId this edge IS, and the render's clock (`now`). */
+	readonly context: RenderContext
+	readonly fetchImpl?: typeof fetch
+	/** Cache override. Defaults to the module-level shared delivery cache. */
+	readonly cache?: TtlCache<CachedDelivery>
+	/** TTL in ms for a VERIFIED read (default: the cache's positive TTL, 60_000 on the shared one). */
+	readonly ttlMs?: number
+	/** Deadline in ms for the fetch (default `DEFAULT_FETCH_TIMEOUT_MS`, 3s). */
+	readonly timeoutMs?: number
+}
+
+/** Shared per-process cache: 60s for a verified read, 5s for a suppressed one. */
+const sharedDeliveryCache = new TtlCache<CachedDelivery>({ ttlMs: 60_000, negativeTtlMs: 5_000 })
+
+function suppressed(reason: CertSuppressReason): CachedDelivery {
+	return { kind: 'suppressed', reason }
+}
+
+export function deliveryUrl(baseUrl: string, platform: string, externalId: string): string {
+	const base = baseUrl.replace(/\/+$/, '')
+	return `${base}/api/cert/v1/delivery/${encodeURIComponent(platform)}/${encodeURIComponent(externalId)}`
+}
+
+/** Cache key: the URL (origin included) × the placement rendering it. No clock: the TTL bounds time. */
+export function deliveryCacheKey(
+	opts: Pick<GetVerifiedDeliveryOptions, 'baseUrl' | 'platform' | 'externalId' | 'context'>,
+): string {
+	return `delivery:${deliveryUrl(opts.baseUrl, opts.platform, opts.externalId)}|${encodeURIComponent(opts.context.platform)}:${encodeURIComponent(opts.context.externalId)}`
+}
+
+const isString = (v: unknown): v is string => typeof v === 'string'
+const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v)
+
+/**
+ * The def sibling, shape-checked. Anything that is not the metafield shape is null, which paints
+ * the preset default (the same thing an absent def paints): a def is presentation, never a claim,
+ * so a malformed one degrades the styling and nothing else. The TOKEN VALUES are not judged here;
+ * `resolveBlockTheme` re-validates each at paint time and drops what is not a safe value.
+ */
+export function parseRenderDef(value: unknown): CertChromeRenderDef | null {
+	if (!isRecord(value)) return null
+	const { v, preset, rung, tokens, hidden, barInkFg, layout, customFace } = value
+	if (typeof v !== 'number' || !Number.isFinite(v)) return null
+	if (!isString(preset) || !isString(rung) || !isRecord(tokens)) return null
+	if (!Array.isArray(hidden) || !hidden.every(isString)) return null
+	if (layout !== undefined && !isString(layout)) return null
+	let face: CertChromeRenderDef['customFace']
+	if (customFace !== undefined) {
+		if (!isRecord(customFace) || !Array.isArray(customFace.placedFields) || !customFace.placedFields.every(isString)) {
+			return null
+		}
+		face = { placedFields: [...customFace.placedFields] }
+	}
+	const tokenOut: Record<string, string> = {}
+	for (const key of ['accentColor', 'surface', 'cornerRadius', 'fontSlot', 'barInk', 'inkColor'] as const) {
+		if (isString(tokens[key])) tokenOut[key] = tokens[key]
+	}
+	return {
+		v,
+		preset,
+		rung,
+		tokens: tokenOut,
+		...(barInkFg === '#141414' || barInkFg === '#ffffff' ? { barInkFg } : {}),
+		hidden: [...hidden],
+		...(layout !== undefined ? { layout } : {}),
+		...(face ? { customFace: face } : {}),
+	}
+}
+
+/** Fetch, parse and cryptographically verify one Delivery response. Never throws. */
+async function loadDelivery(opts: GetVerifiedDeliveryOptions): Promise<CachedDelivery> {
+	const fetchImpl = opts.fetchImpl ?? globalThis.fetch
+	let res: Response
+	try {
+		res = await fetchWithDeadline(
+			fetchImpl,
+			deliveryUrl(opts.baseUrl, opts.platform, opts.externalId),
+			{ headers: { accept: 'application/json' } },
+			opts.timeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS,
+		)
+	} catch {
+		// Unreachable, DNS/TLS, or the deadline. Same least-wrong member as getVerifiedEnvelope.
+		return suppressed('unsupported_contract_version')
+	}
+	// Nothing served for this placement: never certified, or withdrawn. A LIVE revocation is a 200
+	// tombstone, so a 4xx here genuinely means "no credential for this subject".
+	if (res.status === 404 || res.status === 410) return suppressed('subject_mismatch')
+	if (!res.ok) return suppressed('unsupported_contract_version')
+	let body: unknown
+	try {
+		body = await res.json()
+	} catch {
+		return suppressed('unsupported_contract_version')
+	}
+	if (!isRecord(body)) return suppressed('unsupported_contract_version')
+	let verdict: CertVerdict
+	try {
+		// `verifyArtifact`, so a tombstone verifies as itself and reports 'revoked'. The kernel reads
+		// `payload` + `signature` (or the tombstone's own fields); the `renderDef` sibling is not
+		// part of what is verified, and is never read unless the artifact verified.
+		verdict = await verifyArtifact(body as unknown as CertDeliveryArtifact, opts.resolveKid, { ...opts.context })
+	} catch {
+		return suppressed('unknown_key')
+	}
+	if (verdict.decision !== 'render') return suppressed(verdict.reason)
+	return { kind: 'verified', payload: verdict.payload, renderDef: parseRenderDef(body.renderDef) }
+}
+
+/** Apply the render-time policy to a cached read: lifecycle + subject at THIS render's clock. */
+export function settleDelivery(cached: CachedDelivery, context: RenderContext): VerifiedDelivery {
+	if (cached.kind === 'suppressed') return { verdict: { decision: 'suppress', reason: cached.reason }, renderDef: null }
+	const verdict = renderVerdict(cached.payload, context)
+	return { verdict, renderDef: verdict.decision === 'render' ? cached.renderDef : null }
+}
+
+/**
+ * Fetch (if needed), verify, cache, and settle one Delivery read for one placement. FAIL-CLOSED:
+ * the verdict is `render` only when the artifact verified against `resolveKid` AND, at
+ * `context.now`, the payload is unrevoked, unexpired and for this placement.
+ */
+export async function getVerifiedDelivery(opts: GetVerifiedDeliveryOptions): Promise<VerifiedDelivery> {
+	const cache = opts.cache ?? sharedDeliveryCache
+	const cached = await cache.getOrLoad(
+		deliveryCacheKey(opts),
+		() => loadDelivery(opts),
+		(v) => v.kind === 'suppressed',
+		opts.ttlMs,
+	)
+	return settleDelivery(cached, opts.context)
+}
+
+/**
+ * The synchronous read: the settled answer when a fresh read is cached, else `undefined` (the
+ * caller then awaits `getVerifiedDelivery`). Never fetches.
+ */
+export function peekVerifiedDelivery(
+	opts: Pick<GetVerifiedDeliveryOptions, 'baseUrl' | 'platform' | 'externalId' | 'context' | 'cache'>,
+): VerifiedDelivery | undefined {
+	const cached = (opts.cache ?? sharedDeliveryCache).peek(deliveryCacheKey(opts))
+	return cached === undefined ? undefined : settleDelivery(cached, opts.context)
+}
+
+/** Drop every cached read for one placement (e.g. from a revocation webhook). */
+export function invalidateDelivery(
+	opts: Pick<GetVerifiedDeliveryOptions, 'baseUrl' | 'platform' | 'externalId' | 'context'>,
+	cache: TtlCache<CachedDelivery> = sharedDeliveryCache,
+): void {
+	cache.delete(deliveryCacheKey(opts))
+}
+
+export { sharedDeliveryCache }

package/dist/modal/ftc-guard.d.ts

@@ -1,85 +0,0 @@
-/**
- * FTC disclosure tamper guard for the NATIVE Shopify cert render (iframe→native parity).
- *
- * In the cross-origin iframe model the expert-memo embed inlined the portal's
- * `ftcTamperGuardScript()`: a kill switch that blanks the memo if the verbatim FTC
- * material-connection disclosure is stripped, hidden, or altered — making the MSA §3
- * anti-stripping covenant TECHNICALLY enforced, not just contractual. The native memo renders
- * in the host theme's DOM (no sandbox), so without this it would lose that runtime enforcement.
- * This module restores it: on load + on later DOM mutation it verifies the in-DOM
- * `[data-ftc-line]` is present, carries the EXACT verbatim text, and is actually visible; if not,
- * it neutralizes the memo with a neutral notice so the memo NEVER renders without its disclosure.
- *
- * Native-specific semantics (differ from the iframe, which only existed when a memo did):
- *   - Enforcement is keyed on the MEMO element (`.certrev-memo`). A certified article with NO
- *     memo legitimately has no `.certrev-memo` and no disclosure — the guard does NOT fire
- *     (no false positive on the no-memo path).
- *   - On tamper it neutralizes ONLY the memo (never `document.body` — we're in the host page).
- *   - The contributors card is governed by the badge re-verify (`revalidate.ts`), not this guard;
- *     the card carries only the one-word "Compensated" cue, never the guarded disclosure.
- *   - COVERAGE, and it is narrower than it reads: `.certrev-memo` / `.certrev-memo-wrap` are portal
- *     LIQUID markup — NOTHING in this package emits either. So the kill switch covers the Liquid
- *     memo surface and nothing else. `<CertBadge>` and `render-badge-html.ts` emit the same
- *     `[data-ftc-line]` hook inside a `.certrev-badge` (no memo), and `renderCertBlock` emits no
- *     hook at all; on those surfaces a pass verifies nothing and says so (`'unguarded'`) rather
- *     than reporting success, and no observer is installed at all. Widening enforcement to the
- *     badge is a live design decision, not an omission — see `FtcEnforcementResult`.
- *
- * Pure DOM, no crypto, no network. The expected text is the single source of truth
- * `FTC_DISCLOSURE_LINE` (imported, not copied — so a reword can never desync this guard).
- */
-export declare const FTC_LINE_SELECTOR = "[data-ftc-line]";
-export declare const MEMO_SELECTOR = ".certrev-memo";
-export declare const MEMO_WRAP_SELECTOR = ".certrev-memo-wrap";
-/** Marker on the neutral notice node that replaces a tampered memo (testable / idempotent). */
-export declare const FTC_NEUTRALIZED_ATTR = "data-certrev-ftc-neutralized";
-/** True when a memo's disclosure line is present, exactly verbatim, and visible. */
-export declare function isDisclosureIntact(memo: Element): boolean;
-/**
- * Replace a tampered memo with a neutral, self-contained notice — no reviewer attribution, no
- * seal — so the surface can never read as an endorsement without its required disclosure.
- */
-export declare function neutralizeMemo(memo: Element): void;
-/**
- * What ONE enforcement pass actually established:
- *   - `'intact'`    — at least one memo was checked, and every one carried its verbatim, visible line.
- *   - `'tampered'`  — at least one memo failed the check and was neutralized.
- *   - `'unguarded'` — the document holds no `.certrev-memo`, so the pass checked nothing.
- *
- * `'unguarded'` used to be reported as `true`, indistinguishable from `'intact'`, and that
- * conflation was a correctness bug, not a cosmetic one: `.certrev-memo` is portal Liquid markup
- * this package never emits, so on every React / Web Component / `renderCertBlock` surface the pass
- * finds nothing and answered "all intact" about a disclosure it had never looked at — the kill
- * switch silently reporting success on exactly the surfaces it does not protect.
- *
- * The legitimate no-memo certified article (card only, no memo, no disclosure owed) lands here too,
- * and the guard genuinely cannot tell the two apart from the DOM alone. That is the point of a
- * third state rather than a second boolean: "nothing was verified" is the honest answer to both,
- * and it is the caller — which knows which surface it rendered — that can tell whether that is
- * expected or a coverage gap.
- */
-export type FtcEnforcementResult = 'intact' | 'tampered' | 'unguarded';
-/**
- * Enforce the disclosure across every memo in the doc: neutralize any whose disclosure isn't
- * intact. A doc with no `.certrev-memo` is a no-op — see `FtcEnforcementResult` for why that is
- * `'unguarded'` and not success.
- */
-export declare function enforceFtcDisclosure(doc: Document): FtcEnforcementResult;
-/**
- * Install the guard once per document: enforce now (on DOM ready) and re-enforce on later DOM
- * mutations within the guarded subtree(s) — so a host script that strips / hides / edits the
- * disclosure after load still trips the kill switch. Idempotent.
- *
- * The observer scope is the memo wrap(s) — placement.ts relocates a wrap as a node, so the observer
- * tracks it wherever it moves — plus any memo sitting outside a wrap. When the document has
- * NEITHER, NO observer is installed at all. That bail-out is the whole storefront case, not an edge
- * one: this package emits neither selector (both are portal Liquid), so the old `<body>` fallback
- * was the only branch a React / Web Component / `renderCertBlock` page could take, and it pinned a
- * subtree + attributes + characterData observer — no `attributeFilter`, no coalescing — on the
- * host's entire page for the life of the tab, re-running an enforce pass on EVERY mutation a busy
- * storefront makes, to query a selector that could never match. A guard watching a page it cannot
- * act on is pure cost; `enforceFtcDisclosure`'s `'unguarded'` result is the correctness half of the
- * same gap.
- */
-export declare function installFtcGuard(doc: Document): void;
-//# sourceMappingURL=ftc-guard.d.ts.map

package/dist/modal/ftc-guard.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"ftc-guard.d.ts","sourceRoot":"","sources":["../../src/modal/ftc-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAIH,eAAO,MAAM,iBAAiB,oBAAoB,CAAA;AAClD,eAAO,MAAM,aAAa,kBAAkB,CAAA;AAC5C,eAAO,MAAM,kBAAkB,uBAAuB,CAAA;AACtD,+FAA+F;AAC/F,eAAO,MAAM,oBAAoB,iCAAiC,CAAA;AAgClE,oFAAoF;AACpF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAKzD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAUlD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,UAAU,GAAG,WAAW,CAAA;AAEtE;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,QAAQ,GAAG,oBAAoB,CAWxE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CA0BnD"}