@certrev/cert-block 1.2.0-canary.7 → 1.2.0

package/dist/builder/ssr-seed.d.ts

@@ -0,0 +1,155 @@
+/**
+ * The server render's envelope seed (1.2.0): what lets a hydrated delivery card paint with NO browser read.
+ *
+ * Through 1.1.1 the browser re-read the Delivery API for every card it hydrated, because nothing handed the server's
+ * read to it. A storefront whose Content-Security-Policy `connect-src` does not name the CertREV origin (e.l.f.'s
+ * Hydrogen store is one) blocked that read, the read settled as a suppress, and the card the server had painted
+ * vanished. So the painted face now carries the envelope it was painted from, as one attribute on its wrapper:
+ * `data-certrev-envelope` = `{ v: 1, baseUrl, externalId, design?, payload, signature?, renderDef }`. `payload` is the
+ * signed envelope's payload as the Delivery API served it, less the fields the def hides (below); `renderDef` is the
+ * def the face was painted with; `design` is the design pin the read was made with (the canary replica's `?design=N`),
+ * present only on a pinned read. React escapes the attribute like any other, so no `<script>` and no CSP `script-src`
+ * are involved.
+ *
+ * HIDDEN FIELDS ARE ABSENT FROM THE PAGE, NOT JUST FROM THE FACE. A def's `hidden` set (`reviewerPhoto`, `memo`) is the
+ * brand's statement that the page does not show those fields; a seed that carried them would put the reviewer's photo
+ * URL or the memo text in the page source all the same. So `withoutHiddenContent` removes them from the payload
+ * BEFORE the card paints and before it serializes, and both the server's face and the browser's are painted from the
+ * stripped payload (so they are identical, and a hidden memo is not on the page in either place):
+ *  - `reviewerPhoto` hides `content.expert.photoUrl` and the author's `content.author.photoUrl` (the reader face paints
+ *    the author's photo under the same switch);
+ *  - `memo` hides `content.memo`.
+ * `display.showExpertPhoto: false` is the payload's own switch for the same photos and is stripped the same way (the
+ * portal never writes the URL for it either): both photo URLs go, as for `reviewerPhoto`, whatever the def hides.
+ * `content.expert.compensationCue` is NEVER touched: the cue is a locked disclosure no def can hide, and the face
+ * paints "Compensated expert" from it in the banner, the memo and the sidebar (the floating pill's own markup has
+ * no disclosure line, as in the portal's snippets; its modal paints the cue from the same field).
+ *
+ * THE SIGNATURE IS LEFT OUT WHENEVER ANYTHING WAS STRIPPED. The signature signs the full payload, so a payload with a
+ * field removed no longer verifies against it, and a seed that carried both would hand a verifier a pair that fails.
+ * Leaving it out costs nothing: the browser never re-checks a seed's signature (next paragraph), it re-runs only
+ * `renderVerdict` (lifecycle and subject) at its own clock, and neither reads a field the strip removes. A seed whose
+ * payload was not stripped keeps the signature, so a verifier can still check the page's HTML against the issuer key.
+ *
+ * The browser trusts a seed as far as it trusts the server HTML the seed sits in: whoever can write that HTML can
+ * already write any card they like, so the signature is NOT re-verified here (which would make hydration async, and
+ * Ed25519 in WebCrypto is not in every browser). The client still re-runs the lifecycle and subject policy
+ * (`renderVerdict`) at its own clock once hydration is done; `cert-review-card.tsx` does that.
+ *
+ * A PINNED CARD TAKES ONLY A SEED WITH THE SAME PIN (and an unpinned card only an unpinned one): the pin is part of
+ * the seed's key, as it is part of the read's, so the canary replica's `?design=7` card never paints the design the
+ * page carried for another version.
+ *
+ * WHEN THE SERVER HAD NO ENVELOPE TO PAINT (1.2.0) the same attribute carries a fallback record instead of a seed:
+ * `{ v: 1, baseUrl, externalId, design?, face }`, where `face` is `'options'` (CertREV could not be reached, so the
+ * server painted the block's own options face) or `'none'` (the server painted nothing: revoked, expired, unverifiable,
+ * for another entry). A browser that renders the card again (hydration, or React's client re-render after a hydration
+ * error elsewhere on the page) paints what the record says, so it neither reads the Delivery API nor shows a card the
+ * server withheld. A record holds no payload, so `parseSeed` never takes one for a seed. A `'none'` record sits on a
+ * `hidden` element with nothing in it.
+ *
+ * React-free and browser-only in effect: with no `document` (a server) `pageSeedFor` finds nothing, so a server never
+ * reads or keeps a seed and a multi-tenant render process holds nothing per page.
+ */
+import type { CertPayload, CertSignature } from '../contract/kernel.js';
+import { type DesignPin } from '../verify/get-verified-delivery.js';
+import type { CertChromeRenderDef } from './cert-chrome-data.js';
+export declare const SEED_ATTRIBUTE = "data-certrev-envelope";
+export interface DeliverySeed {
+    readonly baseUrl: string;
+    readonly externalId: string;
+    /** The design pin the read was made with; absent on an unpinned read (every production brand). */
+    readonly design?: DesignPin;
+    /** The payload as painted: with every field the def hides removed (`withoutHiddenContent`). */
+    readonly payload: CertPayload;
+    /**
+     * The envelope's signature as served; absent when the payload was stripped (it no longer verifies), and when a
+     * cache was filled by hand (a test, a custom cache).
+     */
+    readonly signature?: CertSignature;
+    readonly renderDef: CertChromeRenderDef | null;
+}
+/** A seed as read from the page: the parsed seed and the attribute's exact text (re-rendered verbatim on hydration). */
+export interface PageSeed {
+    readonly seed: DeliverySeed;
+    readonly raw: string;
+}
+/** What the server painted with no verified envelope: the block's options face, or nothing. */
+export type FallbackFace = 'options' | 'none';
+/** The record a server writes where it had no envelope to paint (the file header). */
+export interface DeliveryFallback {
+    readonly baseUrl: string;
+    readonly externalId: string;
+    readonly design?: DesignPin;
+    readonly face: FallbackFace;
+}
+/** A fallback record as read from the page, with the attribute's exact text. */
+export interface PageFallback {
+    readonly fallback: DeliveryFallback;
+    readonly raw: string;
+}
+/** Whatever the server wrote for one placement: a seed or a fallback record. */
+export type PageRecord = PageSeed | PageFallback;
+/**
+ * The payload with the named people's photo URLs removed (`null`); the same object when neither had one. The card uses
+ * it for a photo the browser could not load (a brand's CSP `img-src`, a 404), so the face repaints with the initials.
+ */
+export declare function withoutPhotos(payload: CertPayload, people: readonly ('expert' | 'author')[]): CertPayload;
+/**
+ * The payload with every content field the def's `hidden` set controls removed, and whether anything was; the two
+ * photo URLs go as well when the payload's own `display.showExpertPhoto` is `false` (exactly `false`, as the reader
+ * face reads it: absent or `null` shows the photo).
+ *
+ * Only the ids in `HIDEABLE_FIELDS` count (a def may list others; the faces ignore them, so they hide nothing). A
+ * removed text field becomes `null`, so the content keeps the shape the contract types give it and every face reads it
+ * as absent. Nothing but those fields changes: the subject and lifecycle (what `renderVerdict` reads), the cue, the
+ * dates, the links and the names are the payload's own. Never throws on a hostile shape: a payload whose `expert` or
+ * `author` is not an object has no photo to strip.
+ */
+export declare function withoutHiddenContent(payload: CertPayload, renderDef: CertChromeRenderDef | null): {
+    readonly payload: CertPayload;
+    readonly stripped: boolean;
+};
+/**
+ * The seed for a verified read: the payload stripped of what the def hides, and the signature only when nothing was
+ * stripped. The card paints from this seed's payload, on the server and in the browser alike.
+ */
+export declare function seedFor(read: {
+    readonly baseUrl: string;
+    readonly externalId: string;
+    readonly design?: DesignPin;
+    readonly payload: CertPayload;
+    readonly signature?: CertSignature;
+    readonly renderDef: CertChromeRenderDef | null;
+}): DeliverySeed;
+export declare function serializeSeed(seed: DeliverySeed): string;
+export declare function serializeFallback(fallback: DeliveryFallback): string;
+/** The seed in one attribute value, or null for anything that is not one (never throws). */
+export declare function parseSeed(raw: string): DeliverySeed | null;
+/** A fallback record in one attribute value, or null for anything that is not one (a seed included; never throws). */
+export declare function parseFallback(raw: string): DeliveryFallback | null;
+/**
+ * The record the server wrote for this placement and pin: its seed, or its fallback record. By default: from the map,
+ * else from one scan of the document (which also records every other one on the page). With `live`, the map is not
+ * consulted: the document is scanned and decides, so what a hydrating card learns is what the server HTML in front of
+ * it carries, not what an earlier page in this process left behind. `undefined` when the page carries none, and always
+ * on a server.
+ */
+export declare function pageRecordFor(baseUrl: string, externalId: string, design?: DesignPin, options?: {
+    readonly live?: boolean;
+}): PageRecord | undefined;
+/** `pageRecordFor`, seeds only: the seed the server painted for this placement and pin. */
+export declare function pageSeedFor(baseUrl: string, externalId: string, design?: DesignPin, options?: {
+    readonly live?: boolean;
+}): PageSeed | undefined;
+/**
+ * Whether the live document holds server-rendered React HTML: any Suspense boundary marker. The delivery card sits in
+ * a `<Suspense>` of its own, so a server render of one always leaves a marker, a card the server painted nothing for
+ * (revoked, expired, unreachable) included, and a client render never does. This is how a card that is hydrating tells
+ * a browser hydrating server HTML (the document holds it) from a server render that merely runs where a `document`
+ * exists (a test's jsdom, a shim): there the document does not hold the HTML being produced.
+ */
+export declare function pageHoldsServerHtml(): boolean;
+/** Test seam: forget every seed (a new page). */
+export declare function forgetPageSeedsForTests(): void;
+//# sourceMappingURL=ssr-seed.d.ts.map

package/dist/builder/ssr-seed.d.ts.map

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

package/dist/builder/ssr-seed.js

@@ -0,0 +1,278 @@
+/**
+ * The server render's envelope seed (1.2.0): what lets a hydrated delivery card paint with NO browser read.
+ *
+ * Through 1.1.1 the browser re-read the Delivery API for every card it hydrated, because nothing handed the server's
+ * read to it. A storefront whose Content-Security-Policy `connect-src` does not name the CertREV origin (e.l.f.'s
+ * Hydrogen store is one) blocked that read, the read settled as a suppress, and the card the server had painted
+ * vanished. So the painted face now carries the envelope it was painted from, as one attribute on its wrapper:
+ * `data-certrev-envelope` = `{ v: 1, baseUrl, externalId, design?, payload, signature?, renderDef }`. `payload` is the
+ * signed envelope's payload as the Delivery API served it, less the fields the def hides (below); `renderDef` is the
+ * def the face was painted with; `design` is the design pin the read was made with (the canary replica's `?design=N`),
+ * present only on a pinned read. React escapes the attribute like any other, so no `<script>` and no CSP `script-src`
+ * are involved.
+ *
+ * HIDDEN FIELDS ARE ABSENT FROM THE PAGE, NOT JUST FROM THE FACE. A def's `hidden` set (`reviewerPhoto`, `memo`) is the
+ * brand's statement that the page does not show those fields; a seed that carried them would put the reviewer's photo
+ * URL or the memo text in the page source all the same. So `withoutHiddenContent` removes them from the payload
+ * BEFORE the card paints and before it serializes, and both the server's face and the browser's are painted from the
+ * stripped payload (so they are identical, and a hidden memo is not on the page in either place):
+ *  - `reviewerPhoto` hides `content.expert.photoUrl` and the author's `content.author.photoUrl` (the reader face paints
+ *    the author's photo under the same switch);
+ *  - `memo` hides `content.memo`.
+ * `display.showExpertPhoto: false` is the payload's own switch for the same photos and is stripped the same way (the
+ * portal never writes the URL for it either): both photo URLs go, as for `reviewerPhoto`, whatever the def hides.
+ * `content.expert.compensationCue` is NEVER touched: the cue is a locked disclosure no def can hide, and the face
+ * paints "Compensated expert" from it in the banner, the memo and the sidebar (the floating pill's own markup has
+ * no disclosure line, as in the portal's snippets; its modal paints the cue from the same field).
+ *
+ * THE SIGNATURE IS LEFT OUT WHENEVER ANYTHING WAS STRIPPED. The signature signs the full payload, so a payload with a
+ * field removed no longer verifies against it, and a seed that carried both would hand a verifier a pair that fails.
+ * Leaving it out costs nothing: the browser never re-checks a seed's signature (next paragraph), it re-runs only
+ * `renderVerdict` (lifecycle and subject) at its own clock, and neither reads a field the strip removes. A seed whose
+ * payload was not stripped keeps the signature, so a verifier can still check the page's HTML against the issuer key.
+ *
+ * The browser trusts a seed as far as it trusts the server HTML the seed sits in: whoever can write that HTML can
+ * already write any card they like, so the signature is NOT re-verified here (which would make hydration async, and
+ * Ed25519 in WebCrypto is not in every browser). The client still re-runs the lifecycle and subject policy
+ * (`renderVerdict`) at its own clock once hydration is done; `cert-review-card.tsx` does that.
+ *
+ * A PINNED CARD TAKES ONLY A SEED WITH THE SAME PIN (and an unpinned card only an unpinned one): the pin is part of
+ * the seed's key, as it is part of the read's, so the canary replica's `?design=7` card never paints the design the
+ * page carried for another version.
+ *
+ * WHEN THE SERVER HAD NO ENVELOPE TO PAINT (1.2.0) the same attribute carries a fallback record instead of a seed:
+ * `{ v: 1, baseUrl, externalId, design?, face }`, where `face` is `'options'` (CertREV could not be reached, so the
+ * server painted the block's own options face) or `'none'` (the server painted nothing: revoked, expired, unverifiable,
+ * for another entry). A browser that renders the card again (hydration, or React's client re-render after a hydration
+ * error elsewhere on the page) paints what the record says, so it neither reads the Delivery API nor shows a card the
+ * server withheld. A record holds no payload, so `parseSeed` never takes one for a seed. A `'none'` record sits on a
+ * `hidden` element with nothing in it.
+ *
+ * React-free and browser-only in effect: with no `document` (a server) `pageSeedFor` finds nothing, so a server never
+ * reads or keeps a seed and a multi-tenant render process holds nothing per page.
+ */
+import { HIDEABLE_FIELDS } from '../components/render-def.js';
+import { parseDesignPin, parseRenderDef } from '../verify/get-verified-delivery.js';
+export const SEED_ATTRIBUTE = 'data-certrev-envelope';
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** A value worth hiding: anything but nothing (absent, null, the empty string). */
+const hasValue = (v) => v !== undefined && v !== null && v !== '';
+/**
+ * The payload with the named people's photo URLs removed (`null`); the same object when neither had one. The card uses
+ * it for a photo the browser could not load (a brand's CSP `img-src`, a 404), so the face repaints with the initials.
+ */
+export function withoutPhotos(payload, people) {
+    let content = { ...payload.content };
+    let stripped = false;
+    for (const person of people) {
+        const fields = content[person];
+        if (isRecord(fields) && hasValue(fields.photoUrl)) {
+            content = { ...content, [person]: { ...fields, photoUrl: null } };
+            stripped = true;
+        }
+    }
+    return stripped ? { ...payload, content: content } : payload;
+}
+/**
+ * The payload with every content field the def's `hidden` set controls removed, and whether anything was; the two
+ * photo URLs go as well when the payload's own `display.showExpertPhoto` is `false` (exactly `false`, as the reader
+ * face reads it: absent or `null` shows the photo).
+ *
+ * Only the ids in `HIDEABLE_FIELDS` count (a def may list others; the faces ignore them, so they hide nothing). A
+ * removed text field becomes `null`, so the content keeps the shape the contract types give it and every face reads it
+ * as absent. Nothing but those fields changes: the subject and lifecycle (what `renderVerdict` reads), the cue, the
+ * dates, the links and the names are the payload's own. Never throws on a hostile shape: a payload whose `expert` or
+ * `author` is not an object has no photo to strip.
+ */
+export function withoutHiddenContent(payload, renderDef) {
+    const hidden = (renderDef?.hidden ?? []).filter((id) => HIDEABLE_FIELDS.includes(id));
+    const display = payload.content?.display;
+    const photoOff = isRecord(display) && display.showExpertPhoto === false;
+    if (hidden.length === 0 && !photoOff)
+        return { payload, stripped: false };
+    let next = photoOff || hidden.includes('reviewerPhoto') ? withoutPhotos(payload, ['expert', 'author']) : payload;
+    if (hidden.includes('memo') && hasValue(next.content.memo)) {
+        next = { ...next, content: { ...next.content, memo: null } };
+    }
+    return { payload: next, stripped: next !== payload };
+}
+/**
+ * The seed for a verified read: the payload stripped of what the def hides, and the signature only when nothing was
+ * stripped. The card paints from this seed's payload, on the server and in the browser alike.
+ */
+export function seedFor(read) {
+    const { payload, stripped } = withoutHiddenContent(read.payload, read.renderDef);
+    return {
+        baseUrl: read.baseUrl,
+        externalId: read.externalId,
+        ...(read.design ? { design: read.design } : {}),
+        payload,
+        ...(read.signature && !stripped ? { signature: read.signature } : {}),
+        renderDef: read.renderDef,
+    };
+}
+const serializedPin = (design) => design ? { design: { version: design.version, ...(design.brand === undefined ? {} : { brand: design.brand }) } } : {};
+export function serializeSeed(seed) {
+    return JSON.stringify({
+        v: 1,
+        baseUrl: seed.baseUrl,
+        externalId: seed.externalId,
+        ...serializedPin(seed.design),
+        payload: seed.payload,
+        ...(seed.signature ? { signature: seed.signature } : {}),
+        renderDef: seed.renderDef,
+    });
+}
+export function serializeFallback(fallback) {
+    return JSON.stringify({
+        v: 1,
+        baseUrl: fallback.baseUrl,
+        externalId: fallback.externalId,
+        ...serializedPin(fallback.design),
+        face: fallback.face,
+    });
+}
+/** A pin a record names, judged by the same grammar the card's own pin is: undefined when absent, null when bad. */
+function parsedPin(design) {
+    if (design === undefined)
+        return undefined;
+    const judged = isRecord(design)
+        ? parseDesignPin({ design: design.version, ...(design.brand === undefined ? {} : { designBrand: design.brand }) })
+        : 'invalid';
+    return judged === 'invalid' || judged === undefined ? null : judged;
+}
+/** The seed in one attribute value, or null for anything that is not one (never throws). */
+export function parseSeed(raw) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(value) || value.v !== 1)
+        return null;
+    const { baseUrl, externalId, design, payload, signature, renderDef } = value;
+    if (typeof baseUrl !== 'string' || typeof externalId !== 'string')
+        return null;
+    if (!isRecord(payload) || !isRecord(payload.subject) || !isRecord(payload.lifecycle) || !isRecord(payload.content)) {
+        return null;
+    }
+    // A pin the seed names is judged by the same grammar the card's own pin is; one that fails it is not a seed.
+    const pin = parsedPin(design);
+    if (pin === null)
+        return null;
+    return {
+        baseUrl,
+        externalId,
+        ...(pin ? { design: pin } : {}),
+        payload: payload,
+        ...(isRecord(signature) ? { signature: signature } : {}),
+        renderDef: parseRenderDef(renderDef),
+    };
+}
+/** A fallback record in one attribute value, or null for anything that is not one (a seed included; never throws). */
+export function parseFallback(raw) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(value) || value.v !== 1 || 'payload' in value)
+        return null;
+    const { baseUrl, externalId, design, face } = value;
+    if (typeof baseUrl !== 'string' || typeof externalId !== 'string')
+        return null;
+    if (face !== 'options' && face !== 'none')
+        return null;
+    const pin = parsedPin(design);
+    if (pin === null)
+        return null;
+    return { baseUrl, externalId, ...(pin ? { design: pin } : {}), face };
+}
+/** One placement's key: the origin, the entry and the pin (the read's own key, so a pin never shares a seed). */
+function seedKey(baseUrl, externalId, design) {
+    return design ? `${baseUrl}|${externalId}|design=${design.version}|${design.brand ?? ''}` : `${baseUrl}|${externalId}`;
+}
+/**
+ * The seeds (and fallback records) this page's server HTML carried, by placement, for the page's lifetime: a card
+ * mounted later by a client-side render (an in-app navigation back to a server-rendered article, or React's client
+ * re-render after a hydration error) paints what the server painted, as the hydrated card it replaces would have.
+ */
+const pageSeeds = new Map();
+const recordKey = (record) => {
+    const r = 'seed' in record ? record.seed : record.fallback;
+    return seedKey(r.baseUrl, r.externalId, r.design);
+};
+/** Every seed and fallback record the live document carries, in document order. */
+function scanDocument() {
+    const found = [];
+    for (const el of Array.from(document.querySelectorAll(`[${SEED_ATTRIBUTE}]`))) {
+        const raw = el.getAttribute(SEED_ATTRIBUTE);
+        if (!raw)
+            continue;
+        const seed = parseSeed(raw);
+        const fallback = seed ? null : parseFallback(raw);
+        if (seed)
+            found.push({ seed, raw });
+        else if (fallback)
+            found.push({ fallback, raw });
+    }
+    return found;
+}
+/**
+ * The record the server wrote for this placement and pin: its seed, or its fallback record. By default: from the map,
+ * else from one scan of the document (which also records every other one on the page). With `live`, the map is not
+ * consulted: the document is scanned and decides, so what a hydrating card learns is what the server HTML in front of
+ * it carries, not what an earlier page in this process left behind. `undefined` when the page carries none, and always
+ * on a server.
+ */
+export function pageRecordFor(baseUrl, externalId, design, options = {}) {
+    const key = seedKey(baseUrl, externalId, design);
+    if (typeof document === 'undefined')
+        return undefined;
+    const known = options.live ? undefined : pageSeeds.get(key);
+    if (known)
+        return known;
+    let inDocument = false;
+    for (const found of scanDocument()) {
+        const k = recordKey(found);
+        if (k === key)
+            inDocument = true;
+        if (options.live || !pageSeeds.has(k))
+            pageSeeds.set(k, found);
+    }
+    // A live read answers for the document alone: a record an earlier page left in the map is not one this page carries.
+    return options.live && !inDocument ? undefined : pageSeeds.get(key);
+}
+/** `pageRecordFor`, seeds only: the seed the server painted for this placement and pin. */
+export function pageSeedFor(baseUrl, externalId, design, options = {}) {
+    const record = pageRecordFor(baseUrl, externalId, design, options);
+    return record && 'seed' in record ? record : undefined;
+}
+/** A Suspense boundary's comment marker as React's server render writes it: `$` (done), `$?` (pending), `$!`, `$~`. */
+const BOUNDARY_MARKER = /^\$[?!~]?$/;
+/**
+ * Whether the live document holds server-rendered React HTML: any Suspense boundary marker. The delivery card sits in
+ * a `<Suspense>` of its own, so a server render of one always leaves a marker, a card the server painted nothing for
+ * (revoked, expired, unreachable) included, and a client render never does. This is how a card that is hydrating tells
+ * a browser hydrating server HTML (the document holds it) from a server render that merely runs where a `document`
+ * exists (a test's jsdom, a shim): there the document does not hold the HTML being produced.
+ */
+export function pageHoldsServerHtml() {
+    if (typeof document === 'undefined' || !document.documentElement)
+        return false;
+    const walker = document.createTreeWalker(document.documentElement, 128 /* NodeFilter.SHOW_COMMENT */);
+    for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+        if (BOUNDARY_MARKER.test(node.data))
+            return true;
+    }
+    return false;
+}
+/** Test seam: forget every seed (a new page). */
+export function forgetPageSeedsForTests() {
+    pageSeeds.clear();
+}
+//# sourceMappingURL=ssr-seed.js.map

package/dist/builder/ssr-seed.js.map

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

package/dist/verify/cache.d.ts

@@ -11,6 +11,13 @@
  *      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).
+ *   4. (1.2.0, opt-in through `staleMs`) STALE-WHILE-REVALIDATE and STALE-IF-ERROR: a positive
+ *      entry past its TTL but inside the stale window is served at once while ONE background
+ *      refresh replaces it; a refresh that only failed to reach the origin (`isTransient`)
+ *      keeps the stale entry instead of overwriting it. So an origin that is slow or briefly
+ *      down costs the page nothing it already had. A definitive answer (a revocation, say)
+ *      replaces the entry the moment the refresh lands. With the default `staleMs` of 0 an
+ *      expired entry is gone, exactly as before 1.2.0.
  *
  * 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 and
@@ -24,6 +31,18 @@ export interface TtlCacheOptions {
     readonly negativeTtlMs?: number;
     /** Max entries before LRU-ish eviction of the oldest insert (default 1000). */
     readonly maxEntries?: number;
+    /**
+     * 1.2.0: how long past its TTL a POSITIVE entry may still be served while a refresh runs (default 0: never). A
+     * negative entry is never served stale.
+     */
+    readonly staleMs?: number;
+    /**
+     * 1.2.0: how long an unsettled load may be joined by later callers (default: no limit). Past it, the next caller
+     * starts a fresh load. WHY: a runtime may cancel the I/O of a request that has finished (Cloudflare workerd does),
+     * which can leave a background refresh's promise pending forever; without a limit every later caller would join
+     * it and none would ever refresh again.
+     */
+    readonly inflightMaxMs?: number;
     /** Injectable clock for deterministic tests. */
     readonly now?: () => number;
 }
@@ -33,10 +52,21 @@ export declare class TtlCache<V> {
     private readonly ttlMs;
     private readonly negativeTtlMs;
     private readonly maxEntries;
+    private readonly staleMs;
+    private readonly inflightMaxMs;
     private readonly now;
     constructor(opts?: TtlCacheOptions);
-    /** Read a live (non-expired) entry, or undefined. Prunes the entry if expired. */
+    /** The entry while it may still be served (fresh, or positive and inside the stale window); prunes it past that. */
+    private servable;
+    /** Read a live (non-expired) entry, or undefined. Never serves a stale one; prunes an entry past its stale window. */
     peek(key: string): V | undefined;
+    /**
+     * The synchronous stale-while-revalidate read: a fresh value; or a positive entry past its TTL but inside the stale
+     * window, returned at once while this starts (or joins) ONE background refresh through `loader`; else undefined,
+     * and the caller loads (`getOrLoad`). The refresh caches as `getOrLoad` does, with the same arguments; its failure
+     * is swallowed (the stale value was already served, and a thrown loader is never cached).
+     */
+    peekOrRefresh(key: string, loader: () => Promise<V>, isNegative?: (v: V) => boolean, positiveTtlMs?: number, isTransient?: (v: V) => boolean): 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
@@ -50,8 +80,15 @@ export declare class TtlCache<V> {
      * 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).
+     *
+     * 1.2.0: inside the stale window (`staleMs`) an expired positive entry is returned at once and refreshed in the
+     * background (`peekOrRefresh`). `isTransient(value)` marks a result that says only "the origin was not reached"
+     * (a timeout, a 5xx): when a servable positive entry exists, such a result is NOT cached over it and the caller
+     * gets that entry's value instead (stale-if-error). With no entry to keep, it is cached as `isNegative` says.
      */
-    getOrLoad(key: string, loader: () => Promise<V>, isNegative?: (v: V) => boolean, positiveTtlMs?: number): Promise<V>;
+    getOrLoad(key: string, loader: () => Promise<V>, isNegative?: (v: V) => boolean, positiveTtlMs?: number, isTransient?: (v: V) => boolean): Promise<V>;
+    /** Single-flight load and cache (joins an unsettled load younger than `inflightMaxMs`). */
+    private load;
     /** 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?: boolean, ttlMsOverride?: number): void;

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

@@ -1 +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;;;;;;;;;;;;;OAaG;IACG,SAAS,CACd,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACxB,UAAU,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,OAAO,EAC9B,aAAa,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,CAAC,CAAC;IAoBb;+EAC2E;IAC3E,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,UAAQ,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI;IAW1E,oDAAoD;IACpD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIzB;;;;;;OAMG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAMlC,KAAK,IAAI,IAAI;IAKb,IAAI,IAAI,IAAI,MAAM,CAEjB;CACD"}
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/verify/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;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;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC/B,gDAAgD;IAChD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CAC3B;AAaD,qBAAa,QAAQ,CAAC,CAAC;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA8B;IACpD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiC;IAC1D,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,OAAO,CAAQ;IAChC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAQ;IACtC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAc;gBAEtB,IAAI,GAAE,eAAoB;IAStC,oHAAoH;IACpH,OAAO,CAAC,QAAQ;IAUhB,sHAAsH;IACtH,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAKhC;;;;;OAKG;IACH,aAAa,CACZ,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACxB,UAAU,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,OAAO,EAC9B,aAAa,CAAC,EAAE,MAAM,EACtB,WAAW,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,OAAO,GAC7B,CAAC,GAAG,SAAS;IAShB;;;;;;;;;;;;;;;;;;OAkBG;IACG,SAAS,CACd,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACxB,UAAU,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,OAAO,EAC9B,aAAa,CAAC,EAAE,MAAM,EACtB,WAAW,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,OAAO,GAC7B,OAAO,CAAC,CAAC,CAAC;IAMb,2FAA2F;IAC3F,OAAO,CAAC,IAAI;IA4BZ;+EAC2E;IAC3E,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,UAAQ,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI;IAW1E,oDAAoD;IACpD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIzB;;;;;;OAMG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAMlC,KAAK,IAAI,IAAI;IAKb,IAAI,IAAI,IAAI,MAAM,CAEjB;CACD"}