@certrev/cert-block 1.3.0 → 2.0.1

package/package.json

@@ -1,113 +1,116 @@
 {
-	"name": "@certrev/cert-block",
-	"version": "1.3.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",
-		"url": "git+https://github.com/CertREV/cert-kit.git",
-		"directory": "packages/cert-block"
-	},
-	"homepage": "https://github.com/CertREV/cert-kit/tree/HEAD/packages/cert-block#readme",
-	"bugs": {
-		"url": "https://github.com/CertREV/cert-kit/issues"
-	},
-	"type": "module",
-	"main": "./dist/index.js",
-	"types": "./dist/index.d.ts",
-	"exports": {
-		".": {
-			"types": "./dist/index.d.ts",
-			"default": "./dist/index.js"
-		},
-		"./builder": {
-			"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"
-		},
-		"./reader": {
-			"types": "./dist/reader/index.d.ts",
-			"default": "./dist/reader/index.js"
-		},
-		"./reader.css": "./src/reader/reader.css",
-		"./webcomponent": {
-			"types": "./dist/webcomponent/certrev-badge.d.ts",
-			"default": "./dist/webcomponent/certrev-badge.js"
-		},
-		"./fixtures": {
-			"types": "./dist/contract/fixtures.d.ts",
-			"default": "./dist/contract/fixtures.js"
-		},
-		"./modal": {
-			"types": "./dist/modal/index.d.ts",
-			"default": "./dist/modal/index.js"
-		},
-		"./modal/placement": {
-			"types": "./dist/modal/placement.d.ts",
-			"default": "./dist/modal/placement.js"
-		},
-		"./modal/certrev-cert.js": "./dist/modal/certrev-cert.js"
-	},
-	"files": [
-		"dist",
-		"src",
-		"!src/**/__tests__",
-		"!src/**/*.test.ts",
-		"!src/**/*.test.tsx",
-		"README.md",
-		"CHANGELOG.md"
-	],
-	"publishConfig": {
-		"registry": "https://registry.npmjs.org",
-		"access": "public"
-	},
-	"publishTargets": [
-		"npmjs",
-		"github-packages"
-	],
-	"scripts": {
-		"build": "tsc && pnpm build:modal-bundle",
-		"build:modal-bundle": "pnpm dlx esbuild@0.27.7 src/modal/certrev-cert.entry.ts --bundle --minify --target=es2020 --format=iife --legal-comments=none --tsconfig-raw='{\"compilerOptions\":{\"target\":\"ES2017\",\"module\":\"esnext\",\"strict\":true}}' --banner:js='/* biome-ignore-all format: generated cert-badge bundle, see @certrev/cert-block src/modal/ */ /* biome-ignore-all lint: generated cert-badge bundle, see @certrev/cert-block src/modal/ */' --outfile=dist/modal/certrev-cert.js",
-		"refresh:reader": "node scripts/refresh-reader.mjs",
-		"typecheck": "tsc --noEmit",
-		"test": "vitest run"
-	},
-	"dependencies": {
-		"@certrev/cert-contract": "^0.6.0"
-	},
-	"peerDependencies": {
-		"react": ">=18.0.0"
-	},
-	"peerDependenciesMeta": {
-		"react": {
-			"optional": false
-		}
-	},
-	"devDependencies": {
-		"@testing-library/react": "^16.1.0",
-		"@types/node": "^20.0.0",
-		"@types/react": "^18.3.0",
-		"@types/react-dom": "^18.3.0",
-		"jsdom": "^25.0.0",
-		"react": "^18.3.1",
-		"react-dom": "^18.3.1",
-		"typescript": "^6.0.3",
-		"vitest": "^4.1.5"
-	},
-	"keywords": [
-		"certrev",
-		"certification",
-		"react",
-		"server-components",
-		"hydrogen",
-		"shopify",
-		"json-ld",
-		"schema-org",
-		"web-component",
-		"ed25519",
-		"ssr"
-	],
-	"license": "MIT"
-}
+  "name": "@certrev/cert-block",
+  "version": "2.0.1",
+  "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",
+    "url": "git+https://github.com/CertREV/cert-kit.git",
+    "directory": "packages/cert-block"
+  },
+  "homepage": "https://github.com/CertREV/cert-kit/tree/HEAD/packages/cert-block#readme",
+  "bugs": {
+    "url": "https://github.com/CertREV/cert-kit/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./builder": {
+      "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"
+    },
+    "./reader": {
+      "types": "./dist/reader/index.d.ts",
+      "default": "./dist/reader/index.js"
+    },
+    "./reader.css": "./src/reader/reader.css",
+    "./webcomponent": {
+      "types": "./dist/webcomponent/certrev-badge.d.ts",
+      "default": "./dist/webcomponent/certrev-badge.js"
+    },
+    "./fixtures": {
+      "types": "./dist/contract/fixtures.d.ts",
+      "default": "./dist/contract/fixtures.js"
+    },
+    "./modal": {
+      "types": "./dist/modal/index.d.ts",
+      "default": "./dist/modal/index.js"
+    },
+    "./modal/placement": {
+      "types": "./dist/modal/placement.d.ts",
+      "default": "./dist/modal/placement.js"
+    },
+    "./modal/certrev-cert.js": "./dist/modal/certrev-cert.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/__tests__",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "publishTargets": [
+    "npmjs",
+    "github-packages"
+  ],
+  "dependencies": {
+    "@certrev/cert-contract": "^0.6.0"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.1.0",
+    "@types/node": "^20.0.0",
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "esbuild": "0.27.7",
+    "jsdom": "^25.0.0",
+    "playwright-core": "1.59.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
+  },
+  "keywords": [
+    "certrev",
+    "certification",
+    "react",
+    "server-components",
+    "hydrogen",
+    "shopify",
+    "json-ld",
+    "schema-org",
+    "web-component",
+    "ed25519",
+    "ssr"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc && pnpm build:modal-bundle",
+    "build:modal-bundle": "pnpm dlx esbuild@0.27.7 src/modal/certrev-cert.entry.ts --bundle --minify --target=es2020 --format=iife --legal-comments=none --tsconfig-raw='{\"compilerOptions\":{\"target\":\"ES2017\",\"module\":\"esnext\",\"strict\":true}}' --banner:js='/* biome-ignore-all format: generated cert-badge bundle, see @certrev/cert-block src/modal/ */ /* biome-ignore-all lint: generated cert-badge bundle, see @certrev/cert-block src/modal/ */' --outfile=dist/modal/certrev-cert.js",
+    "refresh:reader": "node scripts/refresh-reader.mjs",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.e2e.json",
+    "test": "vitest run",
+    "test:replica": "vitest run --config vitest.e2e.config.ts"
+  }
+}

package/src/builder/card-beacon.ts

@@ -0,0 +1,201 @@
+/**
+ * The Builder card's beacon (2.0.1): what the card tells CertREV about itself, so a card that does not print on a brand's
+ * page is seen by CertREV and not only by the brand's console.
+ *
+ * One `POST <delivery origin>/api/cert/v1/beacon` per event, a `text/plain` JSON body (a CORS simple request, so no
+ * preflight; the origin is the delivery origin the page's `connect-src` already allows, so no new CSP source):
+ *
+ *     { v: 1, client: 'cert-block', clientVersion, contract, platform: 'builder', externalId, family,
+ *       events: [{ kind: 'fallback' | 'health', reason, outcome, status? }] }
+ *
+ * What it never carries: cookies (`credentials: 'omit'`), the page's address (`referrerPolicy: 'no-referrer'`) or text, the reader's user agent (only a
+ * coarse family: chromium, webkit, gecko, other, or server), or anything the reader typed. `externalId` is the Builder
+ * entry the block renders in, which the brand's page already sends to CertREV when it reads the card.
+ *
+ * How much: in a browser, every fallback (each placement and reason once per page, `card-report.ts`) and one health
+ * event per page in a hundred, at most three beacons per page (a page is a document address: an in-app navigation to
+ * another article starts a new budget); on a server, each placement, reason and origin at most
+ * once an hour per process, with a short deadline, never awaited. A beacon that fails is dropped: it never retries,
+ * never stores anything and never changes what the card prints.
+ */
+
+import { CARD_CONTRACT_VERSION } from './card-contract.js'
+import { CERT_BLOCK_VERSION } from './version.js'
+
+export const BEACON_PATH = '/api/cert/v1/beacon'
+/** Where a block with no accepted delivery marker reports: CertREV's production delivery origin. */
+export const DEFAULT_BEACON_ORIGIN = 'https://portal.certrev.com'
+/** The most beacons one page sends. */
+export const BEACON_MAX_PER_PAGE = 3
+/** The share of page views that send one health event. */
+export const BEACON_HEALTH_SAMPLE = 0.01
+/** A server sends one beacon per placement, reason and origin at most this often. */
+export const BEACON_SERVER_INTERVAL_MS = 3_600_000
+const SERVER_MAX_KEYS = 500
+const SERVER_TIMEOUT_MS = 1_500
+
+export type BeaconOutcome = 'ok' | 'unreachable' | 'http_4xx' | 'http_5xx' | 'verify_failed' | 'unsupported' | 'other'
+export type BeaconFamily = 'chromium' | 'webkit' | 'gecko' | 'server' | 'other'
+
+export interface BeaconEvent {
+	readonly kind: 'fallback' | 'health'
+	readonly reason: string
+	readonly outcome: BeaconOutcome
+	/** The HTTP status CertREV answered with, when a read failed on one (outcome `http_4xx` or `http_5xx`). */
+	readonly status?: number
+}
+
+export interface CardBeacon {
+	readonly v: 1
+	readonly client: 'cert-block'
+	readonly clientVersion: string
+	readonly contract: number
+	readonly platform: 'builder'
+	readonly externalId?: string
+	readonly family: BeaconFamily
+	readonly events: readonly BeaconEvent[]
+}
+
+/** How a beacon leaves: `url`, the JSON body, and where it is sent from. */
+export type BeaconTransport = (url: string, body: string, where: 'browser' | 'server') => void
+
+/** The transport the card ships with: `fetch`, never awaited, never throwing (exported for CertREV's replica harness). */
+export const fetchBeaconTransport: BeaconTransport = (url, body, where) => {
+	try {
+		const send = globalThis.fetch
+		if (typeof send !== 'function') return
+		const init: RequestInit = {
+			method: 'POST',
+			body,
+			headers: { 'content-type': 'text/plain;charset=UTF-8' },
+			credentials: 'omit',
+			// Never the reader's page address, whatever the storefront's Referrer-Policy.
+			referrerPolicy: 'no-referrer',
+			...(where === 'browser'
+				? // Opaque and kept alive: no CORS read of the answer, and it outlives a navigation away.
+					{ mode: 'no-cors' as const, keepalive: true }
+				: typeof AbortSignal !== 'undefined' && typeof AbortSignal.timeout === 'function'
+					? { signal: AbortSignal.timeout(SERVER_TIMEOUT_MS) }
+					: {}),
+		}
+		void send(url, init).catch(() => {})
+	} catch {
+		// A beacon never throws into a render.
+	}
+}
+
+let transport: BeaconTransport = fetchBeaconTransport
+let sentOnPage = 0
+let healthDrawn: boolean | null = null
+/** The document address the page budget belongs to. */
+let budgetPage: string | null = null
+
+/** Start a new page budget when the document's address changed (an in-app navigation). */
+function samePageBudget(): void {
+	const page = typeof location !== 'undefined' ? `${location.pathname}${location.search}` : ''
+	if (page === budgetPage) return
+	budgetPage = page
+	sentOnPage = 0
+	healthDrawn = null
+}
+const sentOnServer = new Map<string, number>()
+let random: () => number = Math.random
+let clock: () => number = Date.now
+
+/** The coarse browser family, from the user agent; nothing else of it is kept. */
+export function browserFamily(userAgent: string): BeaconFamily {
+	if (/Firefox\//.test(userAgent)) return 'gecko'
+	if (/(Chrome|Chromium|CriOS|Edg)\//.test(userAgent)) return 'chromium'
+	if (/AppleWebKit\//.test(userAgent)) return 'webkit'
+	return 'other'
+}
+
+/** The delivery origin a beacon goes to: an `https:` origin on certrev.com, else CertREV's production origin. */
+function beaconOrigin(baseUrl: string | undefined): string {
+	if (!baseUrl) return DEFAULT_BEACON_ORIGIN
+	try {
+		const url = new URL(baseUrl)
+		const host = url.hostname
+		if (url.protocol === 'https:' && (host === 'certrev.com' || host.endsWith('.certrev.com'))) return url.origin
+	} catch {
+		// Fall through.
+	}
+	return DEFAULT_BEACON_ORIGIN
+}
+
+export function beaconBody(externalId: string, events: readonly BeaconEvent[], family: BeaconFamily): CardBeacon {
+	return {
+		v: 1,
+		client: 'cert-block',
+		clientVersion: CERT_BLOCK_VERSION,
+		contract: CARD_CONTRACT_VERSION,
+		platform: 'builder',
+		...(externalId ? { externalId } : {}),
+		family,
+		events,
+	}
+}
+
+/** Send one event from the browser, within the page's budget. */
+export function sendBrowserBeacon(baseUrl: string | undefined, externalId: string, event: BeaconEvent): void {
+	if (typeof document === 'undefined') return
+	samePageBudget()
+	if (sentOnPage >= BEACON_MAX_PER_PAGE) return
+	sentOnPage++
+	const userAgent = typeof navigator !== 'undefined' ? String(navigator.userAgent ?? '') : ''
+	const body = beaconBody(externalId, [event], browserFamily(userAgent))
+	transport(`${beaconOrigin(baseUrl)}${BEACON_PATH}`, JSON.stringify(body), 'browser')
+}
+
+/** Send one health event from the browser on one page view in a hundred (drawn once per page). */
+export function maybeSendBrowserHealth(baseUrl: string | undefined, externalId: string): void {
+	if (typeof document === 'undefined') return
+	samePageBudget()
+	if (healthDrawn === null) healthDrawn = random() < BEACON_HEALTH_SAMPLE
+	if (!healthDrawn) return
+	healthDrawn = false
+	sendBrowserBeacon(baseUrl, externalId, { kind: 'health', reason: 'card_printed', outcome: 'ok' })
+}
+
+/** Send one event from a server: each placement, reason and origin at most once an hour per process. */
+export function sendServerBeacon(baseUrl: string | undefined, externalId: string, event: BeaconEvent): void {
+	const origin = beaconOrigin(baseUrl)
+	const key = `${origin}|${externalId}|${event.kind}|${event.reason}`
+	const now = clock()
+	const last = sentOnServer.get(key)
+	if (last !== undefined && now - last < BEACON_SERVER_INTERVAL_MS) return
+	sentOnServer.delete(key)
+	if (sentOnServer.size >= SERVER_MAX_KEYS) {
+		const oldest = sentOnServer.keys().next().value
+		if (oldest !== undefined) sentOnServer.delete(oldest)
+	}
+	sentOnServer.set(key, now)
+	transport(`${origin}${BEACON_PATH}`, JSON.stringify(beaconBody(externalId, [event], 'server')), 'server')
+}
+
+/**
+ * Test seam: replace the transport (and the sampling draw and clock) and forget the page's and the process's budget.
+ * Returns a restore.
+ */
+export function setCardBeaconForTests(
+	overrides: { transport?: BeaconTransport; random?: () => number; now?: () => number } = {},
+): () => void {
+	const previous = { transport, random, clock }
+	transport = overrides.transport ?? (() => {})
+	random = overrides.random ?? (() => 1)
+	clock = overrides.now ?? Date.now
+	forgetCardBeaconsForTests()
+	return () => {
+		transport = previous.transport
+		random = previous.random
+		clock = previous.clock
+	}
+}
+
+/** Test seam: a new page and a new process. */
+export function forgetCardBeaconsForTests(): void {
+	sentOnPage = 0
+	healthDrawn = null
+	budgetPage = null
+	sentOnServer.clear()
+}