@certrev/cert-block 0.5.4 → 1.0.0

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

@@ -1,7 +1,7 @@
 /**
  * `<certrev-cert-modal>` — the ONE Shadow-DOM element that renders both in-page cert
- * dialogs (certificate 3a + reviewer 4b) across Shopify / WordPress / Builder
- * (POR-10102). Replaces the three drifting per-platform modal implementations.
+ * dialogs (certificate + reviewer) across Shopify / WordPress / Builder.
+ * Replaces the three drifting per-platform modal implementations.
  *
  * Design:
  *  - One element, one OPEN shadow root, two `<dialog>`s (`#cert`, `#expert`). Public
@@ -53,7 +53,7 @@ function getSharedSheet(): CSSStyleSheet | null {
 
 /**
  * Inject the modal font families once, at document level, on first open — SELF-HOSTED from R2
- * (POR-10657). Declares the shared CERT_FONT_FACE_CSS @font-face block inline instead of loading a
+ * Declares the shared CERT_FONT_FACE_CSS @font-face block inline instead of loading a
  * render-blocking `fonts.googleapis.com` stylesheet (which also leaked the visitor's IP to Google).
  * @font-face at document level resolves across the shadow boundary, so the shadow-DOM modal picks
  * these up exactly as it did the old Google <link>. A crossorigin preconnect warms the R2 origin
@@ -164,16 +164,16 @@ export class CertRevCertModal extends HTMLElement {
 					if (!res.ok) return
 					const artifact = (await res.json()) as CertDeliveryArtifact
 					// A 200 may be a REVOCATION — either the SLIM `CertTombstone` the control plane now
-					// serves for a revoked placement (POR-10481, no payload) or a legacy envelope with
+					// serves for a revoked placement (no payload) or a legacy envelope with
 					// `revokedAt` set — plus an EXPIRED envelope. The Delivery API serves those signed so
-					// the edge SUPPRESSES rather than fail-opening on a 404 (POR-10101). Never render
+					// the edge SUPPRESSES rather than fail-opening on a 404. Never render
 					// "verified" content from a revoked/expired artifact.
 					if (isArtifactSuppressed(artifact)) {
 						this.markSuppressed()
 						return
 					}
 					// Not suppressed → a live envelope (a tombstone always suppresses above); `isTombstone`
-					// narrows the union so the payload read is type-safe (POR-10684).
+					// narrows the union so the payload read is type-safe.
 					const content = isTombstone(artifact)
 						? undefined
 						: (artifact.payload?.content as CertModalContent | undefined)
@@ -206,7 +206,7 @@ export class CertRevCertModal extends HTMLElement {
 	}
 
 	/**
-	 * The modal kill-switch (POR-10101): a fetched envelope is REVOKED/EXPIRED. Don't open;
+	 * 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.
 	 */
@@ -244,9 +244,9 @@ function safeParseContent(json: string): CertModalContent | null {
 }
 
 /**
- * The modal-side lifecycle gate (POR-10101 / POR-10684): a fetched Delivery-API artifact that is
+ * The modal-side lifecycle gate: a fetched Delivery-API artifact that is
  * REVOKED or EXPIRED must NOT render "verified" content. Two revocation shapes suppress:
- *   • the SLIM `CertTombstone` the control plane serves for a revoked placement (POR-10481) —
+ *   • the SLIM `CertTombstone` the control plane serves for a revoked placement —
  *     detected by the `kind: 'tombstone'` discriminator via `isTombstone`. It carries NO payload,
  *     so a `payload.lifecycle` read alone would MISS it (and `markSuppressed()` would never fire);
  *   • a legacy envelope with `lifecycle.revokedAt` set, or any envelope whose `expiresAt` passed.

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

@@ -1,14 +1,15 @@
 /**
- * Browser bundle ENTRY for the Shopify cert-badge Web Component (built by
- * scripts/build-shopify-cert-asset.mjs → shopify/extensions/certrev-schema/assets/certrev-cert.js,
- * loaded by the `certrev-cert` app block via its schema `javascript` key).
+ * Browser bundle ENTRY for the cert-badge Web Component. `pnpm build:modal-bundle`
+ * bundles this file into the IIFE at `dist/modal/certrev-cert.js` — the asset a
+ * storefront loads with a plain `<script>` tag, and the same asset the Shopify
+ * `certrev-cert` app block loads via its schema `javascript` key.
  *
  * Glue only: it resolves the published issuer key + the Delivery-API verifier (which runs the
  * canonical `verifyEnvelope` kernel) and kicks off the DOM revalidation pass. No crypto here.
  */
 
 import type { ResolvePublicKeyByKid } from '@certrev/cert-contract'
-import './certrev-cert-modal.js' // registers the unified <certrev-cert-modal> element (POR-10102)
+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'
@@ -18,9 +19,10 @@ import { createDeliveryVerifier } from './verify-client.js'
 /**
  * The published CertREV issuer signing key (SPKI PEM) for kid `cert-issuer-1` — the PUBLIC
  * verification key, safe to ship to every storefront browser. Kept BYTE-IDENTICAL to
- * `CERT_ENVELOPE_SIGNING_PUBLIC_KEY_PEM` in src/lib/cert-delivery/signer.ts; revalidate.test.ts
- * asserts the equality so a key rotation can't silently desync this copy. (signer.ts is
- * node-only, so it cannot be imported into a browser bundle — hence the asserted copy.)
+ * `CERT_ENVELOPE_SIGNING_PUBLIC_KEY_PEM` in the portal's cert-delivery signer. The equality is
+ * asserted PORTAL-side against this package's exported `CERT_ISSUER_*`, so a key rotation can't
+ * silently desync this copy; it cannot be asserted here, because the signer is node-only and
+ * cannot be imported into a browser bundle — hence the copy.
  */
 export const CERT_ISSUER_KID = 'cert-issuer-1'
 export const CERT_ISSUER_PUBLIC_KEY_PEM = `-----BEGIN PUBLIC KEY-----

package/src/modal/display-strings.ts

@@ -1,13 +1,17 @@
 /**
- * Cert-render display strings + date formatter for the MODAL — a BYTE-FAITHFUL relocation of
- * portal `src/lib/cert-delivery/display-strings.ts` (POR-10721 W2). Kept a SEPARATE module from
- * ftc-disclosure.ts (matching portal) so the bundle's `var` layout is byte-identical to the live asset.
+ * Cert-render display strings + date formatter for the MODAL — a BYTE-FAITHFUL relocation of the
+ * portal's own display-strings module. Kept a SEPARATE module from ftc-disclosure.ts (matching the
+ * portal's file split) so the bundle's `var` layout is byte-identical to the live deployed asset.
  *
  * ⚠ Deliberately SEPARATE from `../components/render-def.ts`/`format.ts`. `formatCertDisplayDate`
  * uses `toLocaleDateString` (NOT the components' fixed MONTHS array): the live modal formats dates
  * via `toLocaleDateString` at runtime in the browser, so a fixed-array formatter would VISIBLY
  * diverge on any browser whose ICU renders a month abbreviation differently (the "Sep"/"Sept"
  * CLDR-42 case). Byte-parity with the deployed asset requires preserving the exact source.
+ *
+ * Byte-frozen about OUTPUT, type-guarded about INPUT — the same split `escape.ts` makes here:
+ * every well-formed value renders the exact string portal renders, and a value the wire could
+ * never legitimately carry renders nothing (see `formatCertDisplayDate`).
  */
 
 import { FTC_DISCLOSURE_LINE } from "./ftc-disclosure.js";
@@ -20,13 +24,30 @@ export const CERT_SCOPE_LINE = FTC_DISCLOSURE_LINE;
 
 /**
  * Format a timestamp the way every cert byline renders dates ("Jun 14, 2026", en-US short month,
- * UTC-pinned). Byte-faithful to portal `formatCertDisplayDate`. Null for an unparseable input —
- * callers treat that as "no date, no byline".
+ * UTC-pinned). Null for an unparseable input — callers treat that as "no date, no byline".
+ * Byte-faithful to portal `formatCertDisplayDate` for every value the wire can legitimately carry.
+ *
+ * STRINGS AND `Date`s ONLY — any other type is null, the same rule `../components/format.ts`'s
+ * `formatDate` settled on. `certifiedAt` reaches here off a `JSON.parse(...) as` cast whose
+ * SIGNATURE was checked and whose SHAPE never was, and the `Date` constructor coerces whatever it
+ * is handed: `certifiedAt: 42` put "Jan 1, 1970" in the certificate's Issued row, and `[2026]`
+ * put "Jan 1, 2026" there. There is no reading to rescue — the wire types this field as an
+ * ISO-8601 string, so a number is always a malformed payload, and epoch seconds vs milliseconds
+ * is not decidable from the value anyway. A compliance-facing card that prints a confident wrong
+ * certification date is worse than one that prints none.
+ *
+ * The guard is on the TYPE, not the value: the string "42" still parses as the year 2042, exactly
+ * as `formatDate` does with it. Both helpers hand string parsing to the engine.
+ *
+ * One behaviour narrows: a `Date` from another realm fails `instanceof` and is now null instead of
+ * being coerced through `new Date(obj)`. Nothing passes a `Date` here at all — both call sites in
+ * `cert-modal-view.ts` pass `content.certifiedAt` straight off the parsed envelope.
  */
 export function formatCertDisplayDate(
 	iso: string | Date | null | undefined,
 ): string | null {
 	if (!iso) return null;
+	if (typeof iso !== "string" && !(iso instanceof Date)) return null;
 	const date = iso instanceof Date ? iso : new Date(iso);
 	if (Number.isNaN(date.getTime())) return null;
 	return date.toLocaleDateString("en-US", {

package/src/modal/escape.ts

@@ -1,17 +1,45 @@
 /**
  * HTML escaping for the cert MODAL string builder — a BYTE-FAITHFUL relocation of
- * portal `src/lib/utils/html.ts` `escapeHtml` (the exact `.replace` chain the deployed
- * `certrev-cert.js` was bundled from — POR-10721 W2).
+ * the portal's `escapeHtml` (the exact `.replace` chain the deployed `certrev-cert.js`
+ * was bundled from).
  *
  * ⚠ Deliberately SEPARATE from `../components/escape.ts`: that SSR helper encodes the
  * apostrophe as `'`, THIS one as `'`. They render identically in a browser, but
  * this module is a byte-frozen relocation of the live Shopify asset, so it must reproduce
  * portal's exact `'` bytes — the two escapes are NOT interchangeable here. (Unifying
  * them is a deliberate post-publish follow-up, tracked with the unification program.)
+ *
+ * The two files are separate about BYTES and identical about TYPES: `asText` below mirrors
+ * `../components/escape.ts`'s guard of the same name, for the same reason. This escape runs
+ * downstream of a `JSON.parse(...) as CertDeliveryEnvelope` cast, and `verifyEnvelope` checks
+ * the SIGNATURE, never the SHAPE — so a number / object / array arrives where the contract
+ * promised a string, and `text.replace` on one is a `TypeError`. In the browser that throw
+ * takes down the dialog the reader clicked, so the family's contract is NEVER THROW.
  */
 
-export function escapeHtml(text: string): string {
-	return text
+/**
+ * Coerce an untyped value to renderable text — byte-for-byte the same rule the components
+ * copy applies: a string passes through UNTOUCHED (the escape chain below is the only XSS
+ * boundary the modal has, and any change to its string output is a security regression);
+ * a finite number renders as its digits; everything else — null, undefined, booleans,
+ * objects, arrays, NaN/Infinity — renders as empty.
+ *
+ * Deliberately not `String(input)`: blind coercion splices `[object Object]` (or a hostile
+ * `toString`'s payload) into the dialog, and on a null-prototype object it throws the very
+ * TypeError this exists to prevent. A value that is not text is not copy.
+ *
+ * Exported for `cert-modal-view.ts`, whose pre-escape `.trim()` reads need the same guard —
+ * a coercion applied only inside `escapeHtml` would still leave the dereference above it
+ * throwing. Modal-internal (the `/modal` entry does not re-export it).
+ */
+export function asText(input: unknown): string {
+	if (typeof input === "string") return input;
+	if (typeof input === "number") return Number.isFinite(input) ? String(input) : "";
+	return "";
+}
+
+export function escapeHtml(text: string | null | undefined): string {
+	return asText(text)
 		.replace(/&/g, "&")
 		.replace(/</g, "&lt;")
 		.replace(/>/g, "&gt;")

package/src/modal/font-face.ts

@@ -1,16 +1,13 @@
-// ⚠ VENDORED, BYTE-FAITHFUL copy of portal `src/lib/cert-delivery/fonts/font-face.generated.ts`
-// (POR-10721 W2) — the exact @font-face block the deployed `certrev-cert.js` was bundled from.
-// Regenerated upstream in portal; do not hand-edit the CSS here (a drift would break byte-parity).
-//
-// GENERATED by scripts/build-cert-fonts.mjs — DO NOT EDIT BY HAND.
+// ⚠ VENDORED, BYTE-FAITHFUL copy of the portal's GENERATED cert @font-face module — the exact
+// @font-face block the deployed `certrev-cert.js` was bundled from. It is generated (and
+// regenerated) upstream in portal, never in this repo: do not hand-edit the CSS here, because a
+// drift would break byte-parity with the deployed asset.
 //
 // The CertREV self-hosted cert @font-face block (absolute R2 URLs on assets.certrev.com),
-// mirrored from the block spliced into
-// shopify/extensions/certrev-schema/assets/certrev-cert.css so the surfaces that CAN'T @import a
-// .css asset share ONE canonical declaration: the standalone /embed renderers and the
-// <certrev-cert-modal> web component (POR-10657). Regenerate with
-// `node scripts/build-cert-fonts.mjs` (or `--emit-ts-only` to re-derive from the CSS without
-// re-downloading). Inline this inside a <style> to load the fonts non-blocking from R2.
+// mirrored from the block spliced into the Shopify extension's `certrev-cert.css` so the surfaces
+// that CAN'T @import a .css asset share ONE canonical declaration: the standalone /embed renderers
+// and the <certrev-cert-modal> web component. Inline this inside a <style> to load the fonts
+// non-blocking from R2.
 
 export const CERT_FONT_FACE_CSS = `
 @font-face {

package/src/modal/ftc-disclosure.ts

@@ -1,7 +1,7 @@
 /**
  * The verbatim FTC material-connection + scope disclosure line — a BYTE-FAITHFUL relocation of
- * the (tree-shaken) `FTC_DISCLOSURE_LINE` from portal `src/lib/embed/ftc-disclosure.ts`
- * (POR-9317 / POR-10721 W2). Legally load-bearing: the curly apostrophe (U+2019) in "article’s"
+ * the (tree-shaken) `FTC_DISCLOSURE_LINE` from the portal's embed disclosure
+ * 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

package/src/modal/ftc-guard.ts

@@ -1,8 +1,8 @@
 /**
  * FTC disclosure tamper guard for the NATIVE Shopify cert render (iframe→native parity).
  *
- * In the cross-origin iframe model the expert-memo embed inlined `ftcTamperGuardScript()`
- * (src/lib/embed/ftc-disclosure.ts): a kill switch that blanks the memo if the verbatim FTC
+ * 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.
@@ -17,6 +17,13 @@
  *   - 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).
@@ -30,6 +37,21 @@ export const MEMO_WRAP_SELECTOR = '.certrev-memo-wrap'
 /** Marker on the neutral notice node that replaces a tampered memo (testable / idempotent). */
 export const FTC_NEUTRALIZED_ATTR = 'data-certrev-ftc-neutralized'
 
+/**
+ * Link qualification for the notice's CertREV anchor — a CertREV link on a brand's page that the
+ * brand did not author, so it carries the same qualification as every other anchor this package
+ * emits. Deliberately a LOCAL literal rather than an import of `CERTREV_LINK_REL`
+ * (`../components/rel.ts`): `src/modal/` imports NOTHING from `src/components/` by design — every
+ * shared string here (`ftc-disclosure.ts`, `logo-paths.ts`, `display-strings.ts`) is a modal-local
+ * copy so the browser IIFE never drags the SSR renderer in. `ftc-guard.test.ts` imports the
+ * components constant and asserts this value stays a superset of it, so the copies cannot drift.
+ *
+ * `noreferrer` rides ON TOP of the shared tokens (which omit it): this is the only anchor the
+ * package opens with `target="_blank"`, and it fires from a page whose operator has just stripped
+ * the disclosure — withholding the referrer there is worth the token.
+ */
+const NOTICE_LINK_REL = 'nofollow sponsored noopener noreferrer'
+
 /** Documents already guarded, so a double script-load can't double-bind. */
 const guardedDocs = new WeakSet<Document>()
 
@@ -65,32 +87,63 @@ export function neutralizeMemo(memo: Element): void {
 		'font-family:system-ui,-apple-system,sans-serif;font-size:12px;color:#555;padding:12px;line-height:1.4'
 	notice.innerHTML =
 		'This CertREV verification cannot be displayed because its required disclosure was not shown. ' +
-		'<a href="https://certrev.com" style="color:#555" target="_blank" rel="noopener noreferrer">Learn more</a>.'
+		`<a href="https://certrev.com" style="color:#555" target="_blank" rel="${NOTICE_LINK_REL}">Learn more</a>.`
 	memo.replaceWith(notice)
 }
 
+/**
+ * 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` (no-memo article) is a no-op. Returns true if all memos
- * present were intact (or none existed).
+ * intact. A doc with no `.certrev-memo` is a no-op — see `FtcEnforcementResult` for why that is
+ * `'unguarded'` and not success.
  */
-export function enforceFtcDisclosure(doc: Document): boolean {
-	let allIntact = true
-	for (const memo of Array.from(doc.querySelectorAll(MEMO_SELECTOR))) {
+export function enforceFtcDisclosure(doc: Document): FtcEnforcementResult {
+	const memos = Array.from(doc.querySelectorAll(MEMO_SELECTOR))
+	if (!memos.length) return 'unguarded'
+	let result: FtcEnforcementResult = 'intact'
+	for (const memo of memos) {
 		if (!isDisclosureIntact(memo)) {
-			allIntact = false
+			result = 'tampered'
 			neutralizeMemo(memo)
 		}
 	}
-	return allIntact
+	return result
 }
 
 /**
  * Install the guard once per document: enforce now (on DOM ready) and re-enforce on later DOM
- * mutations within the memo wrap(s) — so a host script that strips / hides / edits the disclosure
- * after load still trips the kill switch. Scoping the observer to the small `.certrev-memo-wrap`
- * subtree(s) keeps it cheap on a busy storefront page (cf. the iframe, which observed its whole
- * — tiny — body). Idempotent.
+ * 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 function installFtcGuard(doc: Document): void {
 	if (guardedDocs.has(doc)) return
@@ -104,11 +157,13 @@ export function installFtcGuard(doc: Document): void {
 		run()
 		const MO = doc.defaultView?.MutationObserver
 		if (!MO) return
-		// Observe the stable memo wrap(s) — placement.js relocates the wrap as a node, so the
-		// observer tracks it wherever it moves. Fall back to <body> only if no wrap exists.
+		// The guarded roots: the stable wrap(s), plus any memo not inside one (in the Liquid shape a
+		// wrap always contains its memo, so this is normally just the wraps). No root ⇒ no observer.
 		const wraps = Array.from(doc.querySelectorAll(MEMO_WRAP_SELECTOR))
-		const scope = wraps.length ? wraps : doc.body ? [doc.body] : []
-		for (const node of scope) {
+		const looseMemos = Array.from(doc.querySelectorAll(MEMO_SELECTOR)).filter(
+			(memo) => !memo.closest(MEMO_WRAP_SELECTOR),
+		)
+		for (const node of [...wraps, ...looseMemos]) {
 			const mo = new MO(run)
 			mo.observe(node, { childList: true, subtree: true, characterData: true, attributes: true })
 		}

package/src/modal/index.ts

@@ -1,6 +1,6 @@
 /**
  * `@certrev/cert-block/modal` — the browser cert MODAL + badge-revalidation Web Component
- * (POR-10721 W2). A BYTE-FAITHFUL relocation of portal `src/lib/cert-delivery/wc/`; the IIFE
+ * — a BYTE-FAITHFUL relocation of the portal's cert-delivery web-component sources. The IIFE
  * built from `certrev-cert.entry.ts` (`build:modal-bundle`) is structurally byte-identical to the
  * Shopify-deployed `certrev-cert.js`, so a headless brand can drop the SAME verified modal onto its
  * storefront (`<script src=".../dist/modal/certrev-cert.js">`) instead of vendoring a copy.

package/src/modal/interactions.ts

@@ -2,14 +2,14 @@
  * Cert-card INTERACTIONS for the native Shopify cert experience.
  *
  * Progressive enhancement, delegated from the document (one listener, survives the placement
- * reposition). Two behaviours (POR-9827 chevron model):
+ * reposition). Two behaviours (the chevron model):
  *
  *   • Accordion bios — a contributor row carrying `[data-certrev-acc]` toggles its `.open` class
  *     (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 (POR-10102) via its `.open('cert'|'expert')` method. Bare /
+ *     `<certrev-cert-modal>` element 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

package/src/modal/logo-paths.ts

@@ -1,5 +1,5 @@
-// ⚠ VENDORED, BYTE-FAITHFUL copy of portal `src/lib/design-guide/logo.ts` `LOGO_PATHS`
-// (POR-10721 W2). Byte-identical to `../components/render-cert-block.ts`'s private copy;
+// ⚠ VENDORED, BYTE-FAITHFUL copy of the portal design-guide's `LOGO_PATHS`.
+// Byte-identical to `../components/render-cert-block.ts`'s private copy;
 // kept modal-local so the browser bundle never pulls in the SSR renderer. Unifying the
 // package's two copies onto one shared leaf module is a post-publish follow-up.
 /**

package/src/modal/placement.ts

@@ -18,7 +18,7 @@
  *       When no references exist, each falls back to a chrome-aware semantic-landmark / theme-class
  *       scan, with a STYLED end-of-article fallback when nothing matches.
  *   (c) Records the matched tier on each wrap as `data-certrev-placement` — the observability the
- *       pre-launch theme-matrix sweep + the POR-9578 liveness check read, so a silent misplacement
+ *       pre-launch theme-matrix sweep + the liveness check read, so a silent misplacement
  *       becomes an inspectable signal rather than a surprise on a real brand's store.
  *
  * It runs BEFORE the badge re-verify pass and never moves a wrap twice, so the `<certrev-badge>`
@@ -62,8 +62,9 @@ export const TOP_CONTENT_SELECTOR = TOP_ANCHORS.map((a) => a.selector).join(', '
  *  footer, nav, or cart drawer often carries its own `.rte` that precedes the article in document
  *  order — IntelliPure's announcement bar is literally `<div class="announcement__content … rte">`.
  *  `isRenderable` can't reject those (they're visible), so `querySelector('.rte')` returned the
- *  announcement bar and the contributors card was injected there instead of the article (POR-9809 —
- *  "contributors not showing"). Placement scopes anchors out of chrome STRUCTURALLY via this set. */
+ *  announcement bar and the contributors card was injected there instead of the article (the
+ *  "contributors not showing" regression). Placement scopes anchors out of chrome STRUCTURALLY
+ *  via this set. */
 export const SITE_CHROME_SELECTOR =
 	'header, [role="banner"], [class*="announcement"], footer, [role="contentinfo"], nav, [role="navigation"], cart-drawer, .cart-drawer, .drawer, .mini-cart, .modal, [role="dialog"]'
 
@@ -127,7 +128,7 @@ function isRenderable(el: Element): boolean {
  * Whether `el` sits inside SITE CHROME (announcement bar / header / footer / nav / cart drawer /
  * modal). Complements `isRenderable`: chrome anchors are usually VISIBLE, so the visibility guard
  * can't reject them — but a cert wrap must never anchor there. This is the guard that keeps the
- * contributors card out of IntelliPure's `.rte`-classed announcement bar (POR-9809).
+ * contributors card out of IntelliPure's `.rte`-classed announcement bar.
  */
 function isInSiteChrome(el: Element): boolean {
 	return el.closest(SITE_CHROME_SELECTOR) !== null
@@ -143,7 +144,7 @@ function anchorTier(el: Element, anchors: ReadonlyArray<{ readonly selector: str
 
 /**
  * First anchor that exists, is RENDERABLE (not in a hidden drawer/popup), is NOT site chrome (a
- * visible announcement bar / header / nav — POR-9809), and is safely positionable relative to
+ * visible announcement bar / header / nav), and is safely positionable relative to
  * `wrap`. Iterates ALL matches per selector (not just the first in document order) so an unusable
  * early match (a closed drawer's `.rte`, or the announcement bar's) is skipped for the article copy.
  */
@@ -210,7 +211,7 @@ export function placeWrap(doc: Document, wrap: HTMLElement): PlaceResult {
 		// on a certified article) lives INSIDE the body-content container, so `closest(TOP_CONTENT_SELECTOR)`
 		// resolves the exact article `.rte` / `article` / `main` — never a same-classed site-chrome element
 		// that merely precedes the article in document order (IntelliPure's `.rte` announcement bar, which
-		// is visible so isRenderable can't reject it — POR-9809 "contributors not showing"). This also ties
+		// is visible so isRenderable can't reject it — the "contributors not showing" regression). This ties
 		// the card + memo to the SAME article region by construction.
 		const refs = doc.querySelector(REFERENCES_SELECTOR)
 		const owner = refs?.closest(TOP_CONTENT_SELECTOR) ?? null

package/src/modal/revalidate.ts

@@ -11,10 +11,9 @@
  *   • verdict `render`  → leave the SSR badge (verified live);
  *   • verdict `suppress` (invalid-sig / subject-mismatch / revoked / expired) → HIDE it
  *     (fail-closed), stamping `data-certrev-suppressed` with the verdict's reason. A revoked
- *     placement now serves the SLIM `CertTombstone` (POR-10481), which `verifyArtifact`
+ *     placement now serves the SLIM `CertTombstone`, which `verifyArtifact`
  *     resolves to `suppress:'revoked'` — so the badge hides AND the suppressed-reason telemetry
- *     is right (`verifyEnvelope` used to mis-report it as `unsupported_contract_version`;
- *     POR-10684);
+ *     is right (`verifyEnvelope` used to mis-report it as `unsupported_contract_version`);
  *   • the Delivery API 404s (no servable artifact) or the network errors → LEAVE the SSR badge.
  *     The SSR copy already passed the Liquid lifecycle gate against the app-owned metafield
  *     (the authoritative revoke/expire surface — the binding retracts it on revoke), so the WC

package/src/modal/verify-client.ts

@@ -5,9 +5,9 @@
  * `@certrev/cert-contract` (WebCrypto Ed25519 over RFC-8785 JCS — the same kernel the server +
  * every other edge run). No crypto is reimplemented here.
  *
- * `verifyArtifact` (POR-10684, cert-contract 0.3.0) dispatches on the `kind: 'tombstone'`
+ * `verifyArtifact` (cert-contract 0.3.0) dispatches on the `kind: 'tombstone'`
  * discriminator: a full `CertDeliveryEnvelope` runs the whole crypto + lifecycle pipeline, while
- * the SLIM `CertTombstone` the control plane now serves for a revoked placement (POR-10481) —
+ * the SLIM `CertTombstone` the control plane now serves for a revoked placement —
  * which carries NO payload — verifies its own signature + subject and resolves to
  * `suppress:'revoked'`. The old `verifyEnvelope` fails a tombstone's shape-check and returns
  * `suppress:'unsupported_contract_version'` (still a blank badge, but the wrong suppressed-reason

package/src/verify/cache.ts

@@ -13,9 +13,9 @@
  *      still recovering quickly (short negative TTL).
  *
  * It is deliberately tiny + dependency-free (a Map + timestamps) so it runs in any server
- * runtime (Node, edge, workerd). For multi-instance deployments this is per-instance L1;
- * pair with a shared CDN/KV cache (the Delivery API is CDN-cacheable on
- * `lifecycle.revision`) for L2 — see README.
+ * runtime (Node, edge, workerd). For multi-instance deployments this is per-instance L1 and
+ * nothing more: each instance keeps its own copy, so an L2 (the CDN in front of the Delivery
+ * API, which is cacheable on `lifecycle.revision`, or a shared KV) is the caller's to add.
  */
 
 export interface TtlCacheOptions {
@@ -68,8 +68,19 @@ export class TtlCache<V> {
 	 * TTL; if `isNegative(value)` returns true (e.g. a 'suppress' verdict) it's cached
 	 * with the shorter negative TTL so a transient failure recovers fast. A thrown loader
 	 * is NOT cached (it rejects all current waiters and the next call retries).
+	 *
+	 * `positiveTtlMs` overrides the cache's positive TTL FOR THIS WRITE only, so one caller
+	 * can hold a verdict longer/shorter than the cache's default without owning the cache.
+	 * It deliberately does NOT apply to a negative result: a caller asking for a 10-minute
+	 * positive TTL is asking for fewer origin reads, not for a transient failure to be
+	 * remembered for ten minutes (see the negative-TTL rationale in the module header).
 	 */
-	async getOrLoad(key: string, loader: () => Promise<V>, isNegative?: (v: V) => boolean): Promise<V> {
+	async getOrLoad(
+		key: string,
+		loader: () => Promise<V>,
+		isNegative?: (v: V) => boolean,
+		positiveTtlMs?: number,
+	): Promise<V> {
 		const cached = this.peek(key)
 		if (cached !== undefined) return cached
 
@@ -79,7 +90,7 @@ export class TtlCache<V> {
 		const promise = (async () => {
 			const value = await loader()
 			const negative = isNegative ? isNegative(value) : false
-			this.set(key, value, negative)
+			this.set(key, value, negative, negative ? undefined : positiveTtlMs)
 			return value
 		})().finally(() => {
 			this.inflight.delete(key)
@@ -89,14 +100,16 @@ export class TtlCache<V> {
 		return promise
 	}
 
-	/** Insert/overwrite an entry with the appropriate TTL. */
-	set(key: string, value: V, negative = false): void {
+	/** Insert/overwrite an entry. `ttlMsOverride` replaces the TTL this write would otherwise
+	 *  get (positive or negative); omit it for the cache's configured TTLs. */
+	set(key: string, value: V, negative = false, ttlMsOverride?: number): void {
 		if (this.store.size >= this.maxEntries && !this.store.has(key)) {
 			// Evict the oldest inserted key (Map preserves insertion order).
 			const oldest = this.store.keys().next().value
 			if (oldest !== undefined) this.store.delete(oldest)
 		}
-		const ttl = negative ? this.negativeTtlMs : this.ttlMs
+		const configured = negative ? this.negativeTtlMs : this.ttlMs
+		const ttl = ttlMsOverride !== undefined && Number.isFinite(ttlMsOverride) ? ttlMsOverride : configured
 		this.store.set(key, { value, expiresAt: this.now() + ttl, negative })
 	}
 
@@ -105,6 +118,19 @@ export class TtlCache<V> {
 		this.store.delete(key)
 	}
 
+	/**
+	 * Drop every key under a prefix. WHY it exists: a cache key identifies everything the
+	 * cached value depends on, which for a verdict includes the live content hash the render
+	 * observed — a fact a revocation webhook does not know. Invalidating by prefix lets the
+	 * webhook drop a placement without having to reconstruct every render context that ever
+	 * cached it.
+	 */
+	deletePrefix(prefix: string): void {
+		for (const key of this.store.keys()) {
+			if (key.startsWith(prefix)) this.store.delete(key)
+		}
+	}
+
 	clear(): void {
 		this.store.clear()
 		this.inflight.clear()