@certrev/cert-block 0.1.0

package/dist/contract/kernel.js

@@ -0,0 +1,19 @@
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ * Contract binding point — the SDK's single import of @certrev/cert-contract
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * Every other SDK module imports the contract TYPES and the KERNEL functions from HERE,
+ * never directly from `@certrev/cert-contract`, so the whole SDK's dependency on the
+ * contract is funnelled through one module. The published package owns the envelope types
+ * (`CertDeliveryEnvelope`, `CertPayload`, `CertCredential`, …), the RFC-8785
+ * canonicalization (`canonicalPayloadBytes`), and the fail-closed kernel (`verifyEnvelope`,
+ * `renderVerdict`, `verifySignatureOnly`, `toEd25519PublicKey`).
+ *
+ * `VerdictKernel` is the ONE name NOT re-exported from the package: the contract exposes
+ * the kernel as free functions, and different edges bundle them with different key-resolver
+ * shapes (cert-block uses `Ed25519PublicKeyInput`; the portal Delivery API uses raw
+ * `Uint8Array`), so the bundled interface stays edge-local — see ./verdict-kernel.
+ */
+export * from '@certrev/cert-contract';
+//# sourceMappingURL=kernel.js.map

package/dist/contract/kernel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kernel.js","sourceRoot":"","sources":["../../src/contract/kernel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,cAAc,wBAAwB,CAAA"}

package/dist/contract/verdict-kernel.d.ts

@@ -0,0 +1,34 @@
+/**
+ * VerdictKernel — cert-block's edge-local view of the kernel function set.
+ *
+ * The published `@certrev/cert-contract` exposes the kernel as FREE FUNCTIONS
+ * (`verifyEnvelope`, `renderVerdict`, `verifySignatureOnly`), NOT as a bundled interface,
+ * because different edges bundle them with different key-resolver shapes: cert-block
+ * resolves keys as `Ed25519PublicKeyInput`, while the portal Delivery API's kernel
+ * resolves raw `Uint8Array`. There is therefore no single canonical `VerdictKernel`
+ * interface to live in the contract — each edge declares the bundled shape it depends on.
+ * This is cert-block's.
+ */
+import type { CertDeliveryEnvelope, CertPayload, CertSuppressReason, CertVerdict, RenderContext, ResolvePublicKeyByKid } from '@certrev/cert-contract';
+/** Full kernel: verify signature, then apply subject/lifecycle/drift policy. */
+export type VerifyEnvelope = (envelope: CertDeliveryEnvelope, resolveKid: ResolvePublicKeyByKid, ctx: RenderContext) => Promise<CertVerdict>;
+/** Phase-2-only policy over an already-verified payload. */
+export type RenderVerdict = (payload: CertPayload, ctx: RenderContext) => CertVerdict;
+/** Phase-1-only cryptographic verification. */
+export type VerifySignatureOnly = (envelope: CertDeliveryEnvelope, resolveKid: ResolvePublicKeyByKid) => Promise<{
+    ok: true;
+} | {
+    ok: false;
+    reason: CertSuppressReason;
+}>;
+/**
+ * The kernel function trio as a single named interface — the value-level surface for
+ * callers that want them as one object. `@certrev/cert-contract` exposes these as free
+ * functions; this is a convenience binding, deliberately kept out of the wire contract.
+ */
+export interface VerdictKernel {
+    readonly verifyEnvelope: VerifyEnvelope;
+    readonly renderVerdict: RenderVerdict;
+    readonly verifySignatureOnly: VerifySignatureOnly;
+}
+//# sourceMappingURL=verdict-kernel.d.ts.map

package/dist/contract/verdict-kernel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verdict-kernel.d.ts","sourceRoot":"","sources":["../../src/contract/verdict-kernel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACX,oBAAoB,EACpB,WAAW,EACX,kBAAkB,EAClB,WAAW,EACX,aAAa,EACb,qBAAqB,EACrB,MAAM,wBAAwB,CAAA;AAE/B,gFAAgF;AAChF,MAAM,MAAM,cAAc,GAAG,CAC5B,QAAQ,EAAE,oBAAoB,EAC9B,UAAU,EAAE,qBAAqB,EACjC,GAAG,EAAE,aAAa,KACd,OAAO,CAAC,WAAW,CAAC,CAAA;AAEzB,4DAA4D;AAC5D,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,EAAE,aAAa,KAAK,WAAW,CAAA;AAErF,+CAA+C;AAC/C,MAAM,MAAM,mBAAmB,GAAG,CACjC,QAAQ,EAAE,oBAAoB,EAC9B,UAAU,EAAE,qBAAqB,KAC7B,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,kBAAkB,CAAA;CAAE,CAAC,CAAA;AAEtE;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAA;IACvC,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAA;IACrC,QAAQ,CAAC,mBAAmB,EAAE,mBAAmB,CAAA;CACjD"}

package/dist/contract/verdict-kernel.js

@@ -0,0 +1,13 @@
+/**
+ * VerdictKernel — cert-block's edge-local view of the kernel function set.
+ *
+ * The published `@certrev/cert-contract` exposes the kernel as FREE FUNCTIONS
+ * (`verifyEnvelope`, `renderVerdict`, `verifySignatureOnly`), NOT as a bundled interface,
+ * because different edges bundle them with different key-resolver shapes: cert-block
+ * resolves keys as `Ed25519PublicKeyInput`, while the portal Delivery API's kernel
+ * resolves raw `Uint8Array`. There is therefore no single canonical `VerdictKernel`
+ * interface to live in the contract — each edge declares the bundled shape it depends on.
+ * This is cert-block's.
+ */
+export {};
+//# sourceMappingURL=verdict-kernel.js.map

package/dist/contract/verdict-kernel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verdict-kernel.js","sourceRoot":"","sources":["../../src/contract/verdict-kernel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @certrev/cert-block — the headless / crypto_verify render edge for CertREV.
+ *
+ * Public API:
+ *   • React components — <CertBadge>, <ExpertBio>, <CertRevBacklink>, <CertJsonLd>,
+ *     <CertReview> (composite). SSR-safe, theme-light, accessible, escaping every field.
+ *   • JSON-LD projector — deterministic facts → schema.org Article+reviewedBy(Person)
+ *     graph, mergeable by @id (won't collide with Yoast).
+ *   • Verify layer — `getVerifiedEnvelope` (fetch from metafield OR Delivery API + run
+ *     the fail-closed VerdictKernel + cache), kid resolvers, the TTL/single-flight cache.
+ *   • Contract types — re-exported from `@certrev/cert-contract` (stubbed locally until
+ *     that package publishes; see the contract binding point in ./contract/kernel).
+ *
+ * The Web Component (`<certrev-badge>`) ships from the './webcomponent' subpath export so
+ * importing the main entry doesn't touch `customElements` (which is undefined server-side).
+ */
+export { CertBadge, type CertBadgeProps } from './components/CertBadge.js';
+export { CertJsonLd, type CertJsonLdProps } from './components/CertJsonLd.js';
+export { CertRevBacklink, type CertRevBacklinkProps } from './components/CertRevBacklink.js';
+export { CertReview, type CertReviewProps } from './components/CertReview.js';
+export { ExpertBio, type ExpertBioProps } from './components/ExpertBio.js';
+export { escapeAttribute, escapeHtml, safeCssColor, safeHttpUrl, tidyText } from './components/escape.js';
+export { credentialSuffix, DEFAULT_ACCENT, expertNameWithCredentials, formatDate, type ResolvedDisplay, resolveDisplay, } from './components/format.js';
+export { FIXTURE_KID, makeMockPayload, makeSignedEnvelope, type SignedEnvelopeFixture } from './contract/fixtures.js';
+export { CANONICALIZATION, type CertContent, type CertCredential, type CertDeliveryEnvelope, type CertDisplayConfig, type CertLifecycle, type CertPayload, type CertSignature, type CertSubject, type CertSuppressReason, type CertVerdict, CONTRACT_VERSION, type ContractVersion, type Ed25519PublicKeyInput, type RenderContext, type ResolvePublicKeyByKid, renderVerdict, SIGNATURE_ALG, type SignatureAlg, type VerdictKernel, verifyEnvelope, verifySignatureOnly, } from './contract/kernel.js';
+export { type JsonLdValue, type ProjectJsonLdOptions, projectCertJsonLd, projectCertJsonLdString, serializeJsonLdForScript, } from './jsonld/project.js';
+export { TtlCache, type TtlCacheOptions } from './verify/cache.js';
+export { type EnvelopeSource, type GetVerifiedEnvelopeOptions, getVerifiedEnvelope, invalidateVerdict, sharedVerdictCache, } from './verify/get-verified-envelope.js';
+export { type FetchingKidResolverOptions, fetchingKidResolver, type StaticKeySet, staticKidResolver, } from './verify/resolve-kid.js';
+export { type RenderBadgeOptions, renderBadgeHtml } from './webcomponent/render-badge-html.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAAE,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAA;AAC1E,OAAO,EAAE,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,4BAA4B,CAAA;AAC7E,OAAO,EAAE,eAAe,EAAE,KAAK,oBAAoB,EAAE,MAAM,iCAAiC,CAAA;AAC5F,OAAO,EAAE,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,4BAA4B,CAAA;AAC7E,OAAO,EAAE,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAA;AAC1E,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AAEzG,OAAO,EACN,gBAAgB,EAChB,cAAc,EACd,yBAAyB,EACzB,UAAU,EACV,KAAK,eAAe,EACpB,cAAc,GACd,MAAM,wBAAwB,CAAA;AAE/B,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,kBAAkB,EAAE,KAAK,qBAAqB,EAAE,MAAM,wBAAwB,CAAA;AAErH,OAAO,EACN,gBAAgB,EAChB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAChB,gBAAgB,EAChB,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,aAAa,EAClB,KAAK,qBAAqB,EAC1B,aAAa,EACb,aAAa,EACb,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,cAAc,EACd,mBAAmB,GACnB,MAAM,sBAAsB,CAAA;AAE7B,OAAO,EACN,KAAK,WAAW,EAChB,KAAK,oBAAoB,EACzB,iBAAiB,EACjB,uBAAuB,EACvB,wBAAwB,GACxB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAElE,OAAO,EACN,KAAK,cAAc,EACnB,KAAK,0BAA0B,EAC/B,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,GAClB,MAAM,mCAAmC,CAAA;AAC1C,OAAO,EACN,KAAK,0BAA0B,EAC/B,mBAAmB,EACnB,KAAK,YAAY,EACjB,iBAAiB,GACjB,MAAM,yBAAyB,CAAA;AAEhC,OAAO,EAAE,KAAK,kBAAkB,EAAE,eAAe,EAAE,MAAM,qCAAqC,CAAA"}

package/dist/index.js

@@ -0,0 +1,38 @@
+/**
+ * @certrev/cert-block — the headless / crypto_verify render edge for CertREV.
+ *
+ * Public API:
+ *   • React components — <CertBadge>, <ExpertBio>, <CertRevBacklink>, <CertJsonLd>,
+ *     <CertReview> (composite). SSR-safe, theme-light, accessible, escaping every field.
+ *   • JSON-LD projector — deterministic facts → schema.org Article+reviewedBy(Person)
+ *     graph, mergeable by @id (won't collide with Yoast).
+ *   • Verify layer — `getVerifiedEnvelope` (fetch from metafield OR Delivery API + run
+ *     the fail-closed VerdictKernel + cache), kid resolvers, the TTL/single-flight cache.
+ *   • Contract types — re-exported from `@certrev/cert-contract` (stubbed locally until
+ *     that package publishes; see the contract binding point in ./contract/kernel).
+ *
+ * The Web Component (`<certrev-badge>`) ships from the './webcomponent' subpath export so
+ * importing the main entry doesn't touch `customElements` (which is undefined server-side).
+ */
+// ── React components ──────────────────────────────────────────────────────────────
+export { CertBadge } from './components/CertBadge.js';
+export { CertJsonLd } from './components/CertJsonLd.js';
+export { CertRevBacklink } from './components/CertRevBacklink.js';
+export { CertReview } from './components/CertReview.js';
+export { ExpertBio } from './components/ExpertBio.js';
+export { escapeAttribute, escapeHtml, safeCssColor, safeHttpUrl, tidyText } from './components/escape.js';
+// ── Presentation helpers (shared with the Web Component) ────────────────────────────
+export { credentialSuffix, DEFAULT_ACCENT, expertNameWithCredentials, formatDate, resolveDisplay, } from './components/format.js';
+// ── Test/dev fixtures (mock facts + signed-envelope generator) ─────────────────────
+export { FIXTURE_KID, makeMockPayload, makeSignedEnvelope } from './contract/fixtures.js';
+// ── Contract surface (types + kernel) — re-export the binding point ────────────────
+export { CANONICALIZATION, CONTRACT_VERSION, renderVerdict, SIGNATURE_ALG, verifyEnvelope, verifySignatureOnly, } from './contract/kernel.js';
+// ── JSON-LD projector ───────────────────────────────────────────────────────────────
+export { projectCertJsonLd, projectCertJsonLdString, serializeJsonLdForScript, } from './jsonld/project.js';
+export { TtlCache } from './verify/cache.js';
+// ── Verify layer ──────────────────────────────────────────────────────────────────
+export { getVerifiedEnvelope, invalidateVerdict, sharedVerdictCache, } from './verify/get-verified-envelope.js';
+export { fetchingKidResolver, staticKidResolver, } from './verify/resolve-kid.js';
+// ── Web Component string renderer (the markup shared by SSR + the custom element) ──
+export { renderBadgeHtml } from './webcomponent/render-badge-html.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,qFAAqF;AACrF,OAAO,EAAE,SAAS,EAAuB,MAAM,2BAA2B,CAAA;AAC1E,OAAO,EAAE,UAAU,EAAwB,MAAM,4BAA4B,CAAA;AAC7E,OAAO,EAAE,eAAe,EAA6B,MAAM,iCAAiC,CAAA;AAC5F,OAAO,EAAE,UAAU,EAAwB,MAAM,4BAA4B,CAAA;AAC7E,OAAO,EAAE,SAAS,EAAuB,MAAM,2BAA2B,CAAA;AAC1E,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AACzG,uFAAuF;AACvF,OAAO,EACN,gBAAgB,EAChB,cAAc,EACd,yBAAyB,EACzB,UAAU,EAEV,cAAc,GACd,MAAM,wBAAwB,CAAA;AAC/B,sFAAsF;AACtF,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,kBAAkB,EAA8B,MAAM,wBAAwB,CAAA;AACrH,sFAAsF;AACtF,OAAO,EACN,gBAAgB,EAWhB,gBAAgB,EAKhB,aAAa,EACb,aAAa,EAGb,cAAc,EACd,mBAAmB,GACnB,MAAM,sBAAsB,CAAA;AAC7B,uFAAuF;AACvF,OAAO,EAGN,iBAAiB,EACjB,uBAAuB,EACvB,wBAAwB,GACxB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,QAAQ,EAAwB,MAAM,mBAAmB,CAAA;AAClE,qFAAqF;AACrF,OAAO,EAGN,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,GAClB,MAAM,mCAAmC,CAAA;AAC1C,OAAO,EAEN,mBAAmB,EAEnB,iBAAiB,GACjB,MAAM,yBAAyB,CAAA;AAChC,sFAAsF;AACtF,OAAO,EAA2B,eAAe,EAAE,MAAM,qCAAqC,CAAA"}

package/dist/jsonld/project.d.ts

@@ -0,0 +1,71 @@
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ * Deterministic JSON-LD projector — facts → schema.org graph (mergeable by @id)
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * INVARIANT #1 of the contract: the JSON-LD is PROJECTED from `payload.content` facts
+ * at render time, never stored in (or signed into) the envelope. This is that projector.
+ * It is DETERMINISTIC — same facts in → byte-identical graph out — so two edges (and a
+ * server pre-render) produce the same structured data, and a snapshot diff is meaningful.
+ *
+ * DESIGN GOAL: MERGE, don't collide.
+ *   A brand page usually already emits an `Article` (or `BlogPosting`) graph — Yoast on
+ *   WordPress, the theme on Shopify, the framework on headless. If we emit a SECOND
+ *   top-level `Article`, crawlers see two competing primary entities. Instead we emit a
+ *   `@graph` whose Article node carries the SAME `@id` the page's primary article uses
+ *   (the page URL + `#article`, the Yoast convention) so a consumer MERGES our
+ *   `reviewedBy` / `dateModified` into the existing node by `@id` rather than duplicating
+ *   it. Our own nodes (the review, the expert Person, the CertREV org) use CertREV-scoped
+ *   `@id`s that cannot clash with the host page's nodes.
+ *
+ * The Person we attach is the reviewing EXPERT (schema.org `reviewedBy`), which is the
+ * E-E-A-T signal CertREV exists to add — not the author. The author (content byline) is
+ * attached as `author` only when present + distinct.
+ */
+import type { CertPayload } from '../contract/kernel.js';
+/** A JSON-LD node/graph value. Loose by design — this is wire JSON, not a TS model. */
+export type JsonLdValue = Record<string, unknown>;
+export interface ProjectJsonLdOptions {
+    /**
+     * The canonical page URL the article renders on. Used to derive the primary
+     * Article node `@id` (`${pageUrl}#article`) so we merge into the host page's graph
+     * instead of colliding. When omitted, the first `subject.canonicalUrls` entry is
+     * used; when there is none either, a CertREV-scoped article `@id` is derived from
+     * `verifyUrl` (still mergeable, just not aligned to a host node).
+     */
+    readonly pageUrl?: string;
+    /**
+     * When true (default), emit the wrapping `{ "@context": "...", "@graph": [...] }`.
+     * When false, return just the array of nodes — for a caller that merges them into an
+     * existing `@graph` it already owns.
+     */
+    readonly wrapGraph?: boolean;
+}
+/**
+ * Project the verified certification facts into a schema.org `@graph`.
+ *
+ * @param payload  The cryptographically-verified payload (the same facts the badge renders).
+ * @param opts     Page URL for @id alignment + graph-wrapping control.
+ * @returns        A `{ "@context", "@graph" }` object (wrapGraph !== false) OR a bare
+ *                 array of nodes (wrapGraph === false) for merge-into-existing-graph callers.
+ */
+export declare function projectCertJsonLd(payload: CertPayload, opts?: ProjectJsonLdOptions): JsonLdValue | JsonLdValue[];
+/**
+ * Serialize the projected graph to the exact JSON string that goes inside a
+ * `<script type="application/ld+json">`. We use `JSON.stringify` with no extra
+ * whitespace for a compact, deterministic body. The string is then made safe to embed
+ * by `serializeJsonLdForScript` (which neutralizes `</script>`).
+ */
+export declare function projectCertJsonLdString(payload: CertPayload, opts?: ProjectJsonLdOptions): string;
+/**
+ * Serialize an arbitrary JSON-LD value for safe inclusion inside a `<script>` element.
+ * Inside `application/ld+json`, two HTML sequences can break out of the tag: `</script>`
+ * (closes the element early) and HTML-comment markers `<!--` / `-->` (some parsers treat
+ * a comment opened inside a script as suspending script-data parsing). A memo or name
+ * containing either is attacker-influenced text, so we neutralize BOTH angle brackets to
+ * their `\uXXXX` form. This is valid JSON that parses back to the identical string — the
+ * structured data is unchanged, but no `<…>`/`-->` sequence can terminate the script.
+ * Standard Next.js / Yoast hardening.
+ */
+export declare function serializeJsonLdForScript(value: unknown): string;
+//# sourceMappingURL=project.d.ts.map

package/dist/jsonld/project.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../../src/jsonld/project.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAe,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAErE,uFAAuF;AACvF,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAEjD,MAAM,WAAW,oBAAoB;IACpC;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAC5B;AAuHD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,WAAW,EAAE,IAAI,GAAE,oBAAyB,GAAG,WAAW,GAAG,WAAW,EAAE,CASpH;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,WAAW,EAAE,IAAI,GAAE,oBAAyB,GAAG,MAAM,CAErG;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAE/D"}

package/dist/jsonld/project.js

@@ -0,0 +1,183 @@
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ * Deterministic JSON-LD projector — facts → schema.org graph (mergeable by @id)
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * INVARIANT #1 of the contract: the JSON-LD is PROJECTED from `payload.content` facts
+ * at render time, never stored in (or signed into) the envelope. This is that projector.
+ * It is DETERMINISTIC — same facts in → byte-identical graph out — so two edges (and a
+ * server pre-render) produce the same structured data, and a snapshot diff is meaningful.
+ *
+ * DESIGN GOAL: MERGE, don't collide.
+ *   A brand page usually already emits an `Article` (or `BlogPosting`) graph — Yoast on
+ *   WordPress, the theme on Shopify, the framework on headless. If we emit a SECOND
+ *   top-level `Article`, crawlers see two competing primary entities. Instead we emit a
+ *   `@graph` whose Article node carries the SAME `@id` the page's primary article uses
+ *   (the page URL + `#article`, the Yoast convention) so a consumer MERGES our
+ *   `reviewedBy` / `dateModified` into the existing node by `@id` rather than duplicating
+ *   it. Our own nodes (the review, the expert Person, the CertREV org) use CertREV-scoped
+ *   `@id`s that cannot clash with the host page's nodes.
+ *
+ * The Person we attach is the reviewing EXPERT (schema.org `reviewedBy`), which is the
+ * E-E-A-T signal CertREV exists to add — not the author. The author (content byline) is
+ * attached as `author` only when present + distinct.
+ */
+const SCHEMA_CONTEXT = 'https://schema.org';
+/**
+ * Strip the query AND fragment from a URL for a stable, mergeable @id. The Yoast / host
+ * convention keys the primary Article node on `{path}#article` with no query — so a page
+ * reached with a `?utm=…` tracking param must derive the SAME `@id` as the canonical URL,
+ * else our `reviewedBy` lands on a sibling node instead of merging into the host's Article.
+ */
+function baseUrl(url) {
+    const cut = Math.min(...[url.indexOf('#'), url.indexOf('?')].filter((i) => i !== -1), url.length);
+    return url.slice(0, cut);
+}
+/** Derive the primary Article `@id`, aligned to the Yoast/host convention when we can. */
+function articleId(payload, opts) {
+    const page = opts.pageUrl ?? payload.subject.canonicalUrls[0];
+    if (page)
+        return `${baseUrl(page)}#article`;
+    // No page URL known — derive a stable, mergeable id from the verify URL.
+    return `${baseUrl(payload.content.verifyUrl)}#article`;
+}
+/** CertREV-scoped node ids — namespaced under the verify URL so they never clash. */
+function reviewId(content) {
+    return `${content.verifyUrl}#certrev-review`;
+}
+function expertId(content) {
+    return content.expert.profileUrl ? `${content.expert.profileUrl}#person` : `${content.verifyUrl}#expert`;
+}
+function orgId(content) {
+    // One stable CertREV organization node across all pages: derive from the verify
+    // URL origin so it dedupes cleanly when a page hosts multiple certified articles.
+    try {
+        return `${new URL(content.verifyUrl).origin}/#certrev-organization`;
+    }
+    catch {
+        return 'https://certrev.com/#certrev-organization';
+    }
+}
+/** Build the reviewing-expert Person node (the E-E-A-T signal). */
+function expertPersonNode(payload) {
+    const { expert } = payload.content;
+    const node = {
+        '@type': 'Person',
+        '@id': expertId(payload.content),
+        name: expert.displayName,
+    };
+    if (expert.profileUrl)
+        node.url = expert.profileUrl;
+    if (expert.photoUrl)
+        node.image = expert.photoUrl;
+    if (expert.credentials.length > 0) {
+        // hasCredential → EducationalOccupationalCredential per credential; also a flat
+        // honorificSuffix list for consumers that don't read hasCredential.
+        node.hasCredential = expert.credentials.map((c) => ({
+            '@type': 'EducationalOccupationalCredential',
+            name: c.fullName,
+            alternateName: c.abbreviation,
+        }));
+        node.honorificSuffix = expert.credentials.map((c) => c.abbreviation).join(', ');
+    }
+    return node;
+}
+/** Build the CertREV organization node (publisher of the review credential). */
+function certRevOrgNode(payload) {
+    let url = 'https://certrev.com';
+    try {
+        url = new URL(payload.content.verifyUrl).origin;
+    }
+    catch {
+        /* keep default */
+    }
+    return {
+        '@type': 'Organization',
+        '@id': orgId(payload.content),
+        name: 'CertREV',
+        url,
+    };
+}
+/** Build the Review node binding the article to its expert review. */
+function reviewNode(payload) {
+    const node = {
+        '@type': 'Review',
+        '@id': reviewId(payload.content),
+        itemReviewed: { '@id': articleId(payload, {}) },
+        author: { '@id': expertId(payload.content) },
+        publisher: { '@id': orgId(payload.content) },
+        datePublished: payload.content.certifiedAt,
+        url: payload.content.verifyUrl,
+    };
+    if (payload.content.memo)
+        node.reviewBody = payload.content.memo;
+    return node;
+}
+/**
+ * The primary Article node — carries the SAME `@id` the host page's article uses so a
+ * consumer merges our `reviewedBy` / `dateModified` into the existing node rather than
+ * duplicating the primary entity. We deliberately emit ONLY the certification-relevant
+ * properties (reviewedBy, dateModified, plus author when distinct) — not headline, body,
+ * image, etc. — so we never overwrite the host's richer Article fields on merge.
+ */
+function articleNode(payload, opts) {
+    const { content } = payload;
+    const node = {
+        '@type': 'Article',
+        '@id': articleId(payload, opts),
+        reviewedBy: { '@id': expertId(content) },
+        review: { '@id': reviewId(content) },
+    };
+    if (content.contentModifiedAt)
+        node.dateModified = content.contentModifiedAt;
+    // Author only when present + distinct from the expert (don't double-attribute).
+    if (content.author.name && content.author.name !== content.expert.displayName) {
+        const author = { '@type': 'Person', name: content.author.name };
+        if (content.author.title)
+            author.jobTitle = content.author.title;
+        node.author = author;
+    }
+    return node;
+}
+/**
+ * Project the verified certification facts into a schema.org `@graph`.
+ *
+ * @param payload  The cryptographically-verified payload (the same facts the badge renders).
+ * @param opts     Page URL for @id alignment + graph-wrapping control.
+ * @returns        A `{ "@context", "@graph" }` object (wrapGraph !== false) OR a bare
+ *                 array of nodes (wrapGraph === false) for merge-into-existing-graph callers.
+ */
+export function projectCertJsonLd(payload, opts = {}) {
+    const nodes = [
+        articleNode(payload, opts),
+        reviewNode(payload),
+        expertPersonNode(payload),
+        certRevOrgNode(payload),
+    ];
+    if (opts.wrapGraph === false)
+        return nodes;
+    return { '@context': SCHEMA_CONTEXT, '@graph': nodes };
+}
+/**
+ * Serialize the projected graph to the exact JSON string that goes inside a
+ * `<script type="application/ld+json">`. We use `JSON.stringify` with no extra
+ * whitespace for a compact, deterministic body. The string is then made safe to embed
+ * by `serializeJsonLdForScript` (which neutralizes `</script>`).
+ */
+export function projectCertJsonLdString(payload, opts = {}) {
+    return serializeJsonLdForScript(projectCertJsonLd(payload, opts));
+}
+/**
+ * Serialize an arbitrary JSON-LD value for safe inclusion inside a `<script>` element.
+ * Inside `application/ld+json`, two HTML sequences can break out of the tag: `</script>`
+ * (closes the element early) and HTML-comment markers `<!--` / `-->` (some parsers treat
+ * a comment opened inside a script as suspending script-data parsing). A memo or name
+ * containing either is attacker-influenced text, so we neutralize BOTH angle brackets to
+ * their `\uXXXX` form. This is valid JSON that parses back to the identical string — the
+ * structured data is unchanged, but no `<…>`/`-->` sequence can terminate the script.
+ * Standard Next.js / Yoast hardening.
+ */
+export function serializeJsonLdForScript(value) {
+    return JSON.stringify(value).replace(/</g, '\\u003c').replace(/>/g, '\\u003e');
+}
+//# sourceMappingURL=project.js.map

package/dist/jsonld/project.js.map

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

package/dist/verify/cache.d.ts

@@ -0,0 +1,56 @@
+/**
+ * In-process TTL cache with single-flight de-duplication.
+ *
+ * WHY: under SSR, a popular product/blog page can render N times concurrently across a
+ * server's request workers. Without coordination, each render fires its own fetch to the
+ * Shopify metafield / Delivery API → a thundering herd against the issuer on cold cache
+ * or cache expiry. This cache:
+ *   1. Serves a fresh value from memory within its TTL (no fetch).
+ *   2. SINGLE-FLIGHTS concurrent misses for the same key — the first caller's in-flight
+ *      promise is shared by every other caller for that key, so N concurrent renders do
+ *      ONE fetch, not N.
+ *   3. Negative-caches failures briefly so a hard-down origin doesn't get hammered, while
+ *      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.
+ */
+export interface TtlCacheOptions {
+    /** Positive-result TTL in ms (default 60_000). */
+    readonly ttlMs?: number;
+    /** Negative-result (miss/error) TTL in ms (default 5_000). */
+    readonly negativeTtlMs?: number;
+    /** Max entries before LRU-ish eviction of the oldest insert (default 1000). */
+    readonly maxEntries?: number;
+    /** Injectable clock for deterministic tests. */
+    readonly now?: () => number;
+}
+export declare class TtlCache<V> {
+    private readonly store;
+    private readonly inflight;
+    private readonly ttlMs;
+    private readonly negativeTtlMs;
+    private readonly maxEntries;
+    private readonly now;
+    constructor(opts?: TtlCacheOptions);
+    /** Read a live (non-expired) entry, or undefined. Prunes the entry if expired. */
+    peek(key: string): V | undefined;
+    /**
+     * Get-or-load with single-flight. If a fresh value is cached, returns it. Otherwise
+     * de-duplicates concurrent loads for `key`: the first caller runs `loader`, every
+     * concurrent caller awaits the same promise. The result is cached with the positive
+     * 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).
+     */
+    getOrLoad(key: string, loader: () => Promise<V>, isNegative?: (v: V) => boolean): Promise<V>;
+    /** Insert/overwrite an entry with the appropriate TTL. */
+    set(key: string, value: V, negative?: boolean): void;
+    /** Drop a key (e.g. on a known revocation push). */
+    delete(key: string): void;
+    clear(): void;
+    get size(): number;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/verify/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/verify/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,WAAW,eAAe;IAC/B,kDAAkD;IAClD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,8DAA8D;IAC9D,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC/B,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,gDAAgD;IAChD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CAC3B;AAQD,qBAAa,QAAQ,CAAC,CAAC;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA8B;IACpD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgC;IACzD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAQ;IACtC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAQ;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAc;gBAEtB,IAAI,GAAE,eAAoB;IAOtC,kFAAkF;IAClF,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAUhC;;;;;;;OAOG;IACG,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAoBlG,0DAA0D;IAC1D,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,UAAQ,GAAG,IAAI;IAUlD,oDAAoD;IACpD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIzB,KAAK,IAAI,IAAI;IAKb,IAAI,IAAI,IAAI,MAAM,CAEjB;CACD"}

package/dist/verify/cache.js

@@ -0,0 +1,93 @@
+/**
+ * In-process TTL cache with single-flight de-duplication.
+ *
+ * WHY: under SSR, a popular product/blog page can render N times concurrently across a
+ * server's request workers. Without coordination, each render fires its own fetch to the
+ * Shopify metafield / Delivery API → a thundering herd against the issuer on cold cache
+ * or cache expiry. This cache:
+ *   1. Serves a fresh value from memory within its TTL (no fetch).
+ *   2. SINGLE-FLIGHTS concurrent misses for the same key — the first caller's in-flight
+ *      promise is shared by every other caller for that key, so N concurrent renders do
+ *      ONE fetch, not N.
+ *   3. Negative-caches failures briefly so a hard-down origin doesn't get hammered, while
+ *      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.
+ */
+export class TtlCache {
+    store = new Map();
+    inflight = new Map();
+    ttlMs;
+    negativeTtlMs;
+    maxEntries;
+    now;
+    constructor(opts = {}) {
+        this.ttlMs = opts.ttlMs ?? 60_000;
+        this.negativeTtlMs = opts.negativeTtlMs ?? 5_000;
+        this.maxEntries = opts.maxEntries ?? 1000;
+        this.now = opts.now ?? Date.now;
+    }
+    /** Read a live (non-expired) entry, or undefined. Prunes the entry if expired. */
+    peek(key) {
+        const e = this.store.get(key);
+        if (!e)
+            return undefined;
+        if (e.expiresAt <= this.now()) {
+            this.store.delete(key);
+            return undefined;
+        }
+        return e.value;
+    }
+    /**
+     * Get-or-load with single-flight. If a fresh value is cached, returns it. Otherwise
+     * de-duplicates concurrent loads for `key`: the first caller runs `loader`, every
+     * concurrent caller awaits the same promise. The result is cached with the positive
+     * 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).
+     */
+    async getOrLoad(key, loader, isNegative) {
+        const cached = this.peek(key);
+        if (cached !== undefined)
+            return cached;
+        const existing = this.inflight.get(key);
+        if (existing)
+            return existing;
+        const promise = (async () => {
+            const value = await loader();
+            const negative = isNegative ? isNegative(value) : false;
+            this.set(key, value, negative);
+            return value;
+        })().finally(() => {
+            this.inflight.delete(key);
+        });
+        this.inflight.set(key, promise);
+        return promise;
+    }
+    /** Insert/overwrite an entry with the appropriate TTL. */
+    set(key, value, negative = false) {
+        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;
+        this.store.set(key, { value, expiresAt: this.now() + ttl, negative });
+    }
+    /** Drop a key (e.g. on a known revocation push). */
+    delete(key) {
+        this.store.delete(key);
+    }
+    clear() {
+        this.store.clear();
+        this.inflight.clear();
+    }
+    get size() {
+        return this.store.size;
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/verify/cache.js.map

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