@cookiecrumbs-eu/mcp 0.7.0

package/dist/config/src/schema.js

@@ -0,0 +1,323 @@
+import { z } from 'zod';
+// ------------------------------------------------------------------
+// BannerConfig v1 — see docs/platform/contracts.md ("Phase 4 contracts"
+// → "BannerConfig v1 additions"). This is the one schema every writer
+// (dashboard, CLI, REST, MCP) validates against; the same shape is
+// enforced in Postgres through schema_registry('banner_config', 1).
+// Phase 4 only ADDS optional fields, so every stored draft stays valid.
+// ------------------------------------------------------------------
+export const HEX_COLOUR = /^#[0-9a-fA-F]{6}$/;
+export const CATEGORY_KEY = /^[a-z][a-z0-9_]{1,31}$/;
+export const LANG_TAG = /^[a-z]{2,3}(-[a-z0-9]{2,8})*$/;
+export const COUNTRY_CODE = /^[A-Z]{2}$/;
+/** Footer links point at real pages on the operator's own site, so nothing but http(s) is accepted. */
+export const URL_HTTP = /^https?:\/\/\S+$/i;
+export const GCM_SIGNALS = [
+    'ad_storage',
+    'analytics_storage',
+    'ad_user_data',
+    'ad_personalization',
+    'functionality_storage',
+    'personalization_storage',
+    'security_storage',
+];
+/**
+ * `ribbon`, `sheet` and `inline` are additive (2026-08-23). An older runtime that meets one of them
+ * falls back to its nearest shipped shape, so a published config never renders nothing:
+ * ribbon → bar, sheet → modal, inline → corner (see LAYOUT_FALLBACK).
+ */
+export const LAYOUTS = ['bar', 'modal', 'corner', 'headless', 'ribbon', 'sheet', 'inline'];
+export const LAYOUT_FALLBACK = {
+    bar: 'bar',
+    modal: 'modal',
+    corner: 'corner',
+    headless: 'headless',
+    ribbon: 'bar',
+    sheet: 'modal',
+    inline: 'corner',
+};
+/**
+ * Local faces only. The banner is a blocking first script on someone else's page and may make no
+ * third-party request, so a webfont is not available to it at any price — the character has to come
+ * from scale, weight and tracking instead. `inherit` adopts the host page's own family.
+ */
+export const TYPE_STACKS = ['system', 'inherit', 'grotesk', 'serif', 'mono', 'rounded'];
+/** The six regimes of region_rule_sets v3 (`ca_qc` added in phase 5). */
+export const REGIMES = ['eu_optin', 'uk_pecr', 'us_optout', 'ch_fadp', 'br_lgpd', 'ca_qc'];
+/** Required in every enabled language (lint `missing_text`). */
+export const TEXT_KEYS = [
+    'title',
+    'body',
+    'accept_all',
+    'reject_all',
+    'settings',
+    'save',
+    'declaration_link',
+    'reopen_label',
+    'consent_id_label',
+];
+/** Optional per language; some become required by lint depending on regions/behaviour. */
+export const OPTIONAL_TEXT_KEYS = [
+    'do_not_sell',
+    'gpc_honoured',
+    'object',
+    'close_refuses',
+    'saved',
+    'confidentiality_settings',
+    /** Footer of every banner, when the matching URL is set in `links`. */
+    'imprint_label',
+    'privacy_label',
+    /** Accessible label for the language switcher. */
+    'language_label',
+];
+export const ALL_TEXT_KEYS = [...TEXT_KEYS, ...OPTIONAL_TEXT_KEYS];
+const colour = z.string().regex(HEX_COLOUR, 'expected #rrggbb');
+export const ThemeSchema = z.object({
+    // ---- v1 core. Required, and in `two_ink` these carry the DERIVED values so an older runtime
+    // (or an export, or a screenshot service) still renders the same banner without knowing the system.
+    background: colour,
+    text: colour,
+    muted: colour,
+    button: colour,
+    button_text: colour,
+    border: colour,
+    radius: z.number().int().min(0).max(32),
+    font: z.enum(['system', 'inherit']),
+    dark: z.enum(['light', 'dark', 'system']),
+    // ---- Two Inks (2026-08-23). All optional; absent = `classic` = today's rendering exactly.
+    /** Which rendering system draws the banner. */
+    system: z.enum(['classic', 'two_ink']).optional(),
+    /** The decisive plate: body text, buttons, rules, the switch. */
+    ink: colour.optional(),
+    /**
+     * Optional button plate, when the buttons should not be the same colour as the body text — the
+     * ordinary "dark text, coloured buttons" look. The runtime picks the button label from stock or ink,
+     * whichever is legible on it, so an accent can never produce an unreadable button.
+     */
+    accent: colour.optional(),
+    /** The second plate. Where it overprints `ink` the system derives a third colour for free. */
+    ink2: colour.optional(),
+    /** The ground the two inks are printed on. */
+    stock: colour.optional(),
+    /** Surface tooth, 0-3. Uncoated stock, not a texture image — it is two CSS gradients. */
+    tooth: z.number().int().min(0).max(3).optional(),
+    /** Off-registration in px, 0-4: how far the second plate sits from the first. 0 = perfect register. */
+    registration: z.number().int().min(0).max(4).optional(),
+    /** The one spacing division. Every measurement on the banner is a multiple of it. */
+    unit: z.number().int().min(4).max(12).optional(),
+    /** Local face for the banner. Never a webfont — see TYPE_STACKS. */
+    type_stack: z.enum(TYPE_STACKS).optional(),
+    /** Type scale. `loud` is display-scale; `compact` suits a ribbon. */
+    type_scale: z.enum(['compact', 'regular', 'loud']).optional(),
+    /**
+     * Button language. Accept and Reject ALWAYS share it — equal prominence is a legal requirement
+     * under eu_optin / uk_pecr / br_lgpd / ca_qc, so the shape is a property of the theme, never of a
+     * single control, and there is deliberately no way to style one decision differently from the other.
+     */
+    button_shape: z.enum(['sharp', 'soft', 'pill', 'plate']).optional(),
+    button_fill: z.enum(['solid', 'outline', 'plate']).optional(),
+    /** How the banner meets the page, and what that meeting-line says. */
+    edge: z.enum(['none', 'hairline', 'rule', 'plate']).optional(),
+    /** The backdrop behind a dialog layout. */
+    backdrop: z.enum(['none', 'dim', 'deep', 'ink']).optional(),
+    /** Elevation off the page. */
+    lift: z.enum(['none', 'soft', 'hard']).optional(),
+    /** The perforated receipt strip along the bottom edge — the consent record, on the banner. */
+    receipt: z.boolean().optional(),
+    /**
+     * What sits inside the floating reopen roundel. Absent/`brand` = the CookieCrumbs mark (the Free
+     * plan's attribution, like the footer line); `cookie` = the plain cookie badge; `custom` = the
+     * operator's own image (`reopen_image`). Anything but `brand` needs the remove_branding feature —
+     * the publish gate enforces it.
+     */
+    reopen_icon: z.enum(['brand', 'cookie', 'custom']).optional(),
+    /** The custom icon: an SVG/PNG/WebP data URL (kept small) or an https address on the operator's own site. */
+    reopen_image: z
+        .string()
+        .max(24000)
+        .regex(/^(data:image\/(svg\+xml|png|jpeg|webp);base64,[A-Za-z0-9+/=]+|https:\/\/\S+)$/, 'an image data URL or an https address')
+        .optional(),
+    /** Custom colours for the reopen roundel; absent = derived from the theme (dark-mode aware). */
+    reopen_bg: colour.optional(),
+    reopen_fg: colour.optional(),
+    /** Cap for a modal/sheet's height on small screens, in viewport-height percent. */
+    max_height_mobile: z.number().int().min(40).max(95).optional(),
+    /** Where a bar / ribbon / corner / inline banner sits. Ignored by modal and sheet. */
+    placement: z.enum(['bottom', 'top', 'bottom_left', 'bottom_right', 'top_right']).optional(),
+    /** The one authored moment. `tear` tears the notice along its perforation into layer 2. */
+    motion: z.enum(['none', 'fade', 'rise', 'tear']).optional(),
+    /**
+     * A small cookie after the title ("We use cookies and other technologies. 🍪"), drawn as inline SVG,
+     * never an emoji and never an image request. `cookie` is a glyph in the title's own colour;
+     * `cookie_colour` is a baked, golden-brown cookie with chocolate chips. Absent = none.
+     */
+    title_icon: z.enum(['none', 'cookie', 'cookie_colour']).optional(),
+    /**
+     * The operator's own CSS, appended to the banner's stylesheet inside the shadow root. `@import` and
+     * external `url()` are removed by `sanitiseCss` before it is served: a consent banner that fetches
+     * something from another origin before the visitor has chosen is the exact thing this product exists
+     * to prevent. 8 kB is a generous ceiling for overriding a banner and a hard cap on what rides on the
+     * critical path of someone else's page.
+     */
+    custom_css: z.string().max(8000).optional(),
+});
+export const TextsSchema = z
+    .object({
+    ...Object.fromEntries(TEXT_KEYS.map((k) => [k, z.string().min(1).max(2000)])),
+    ...Object.fromEntries(OPTIONAL_TEXT_KEYS.map((k) => [k, z.string().max(2000).optional()])),
+})
+    .strict();
+export const CategorySchema = z.object({
+    key: z.string().regex(CATEGORY_KEY, 'lowercase key, 2-32 chars'),
+    locked: z.boolean(),
+    default: z.boolean(),
+    gcm: z.array(z.enum(GCM_SIGNALS)).max(7),
+    /** On by default with an "Object" control under uk_pecr statistical mode. */
+    uk_statistical: z.boolean().optional(),
+});
+export const CategoryTextSchema = z.object({
+    name: z.string().min(1).max(80),
+    description: z.string().min(1).max(1000),
+});
+export const RegimeSettingSchema = z
+    .object({
+    enabled: z.boolean(),
+    expiry_months: z.number().int().min(1).max(13),
+})
+    .strict();
+export const UkPecrSettingSchema = RegimeSettingSchema.extend({ statistical_mode: z.boolean().optional() }).strict();
+export const UsOptoutSettingSchema = RegimeSettingSchema.extend({
+    expiry_months: z.number().int().min(1).max(12),
+    /** Honour Global Privacy Control; default true. */
+    gpc: z.boolean().optional(),
+}).strict();
+export const ChFadpSettingSchema = RegimeSettingSchema.extend({
+    /** strict = opt-in like the EU; fmg = functional + measurement granted by default, marketing opt-in. */
+    mode: z.enum(['strict', 'fmg']).optional(),
+}).strict();
+/**
+ * Quebec Law 25: opt-in for every non-necessary category, a refuse-all control of equal prominence
+ * (the runtime renders Accept all / Reject all with the same style) and the "confidentiality settings"
+ * wording on the settings control (`texts.<lang>.confidentiality_settings`). `settings_label: 'default'`
+ * deliberately keeps the ordinary "Settings" label and silences the lint warning.
+ */
+export const CaQcSettingSchema = RegimeSettingSchema.extend({
+    settings_label: z.enum(['confidentiality', 'default']).optional(),
+}).strict();
+export const RegimesSchema = z
+    .object({
+    eu_optin: RegimeSettingSchema.optional(),
+    uk_pecr: UkPecrSettingSchema.optional(),
+    us_optout: UsOptoutSettingSchema.optional(),
+    ch_fadp: ChFadpSettingSchema.optional(),
+    br_lgpd: RegimeSettingSchema.optional(),
+    ca_qc: CaQcSettingSchema.optional(),
+})
+    .strict();
+export const RegionsSchema = z
+    .object({
+    rules_version: z.number().int().min(1),
+    regimes: RegimesSchema,
+    fallback: z.enum(REGIMES),
+    force_regime: z.enum(REGIMES).nullable().optional(),
+    overrides: z.record(z.string().regex(COUNTRY_CODE, 'ISO 3166-1 alpha-2, upper case'), z.enum(REGIMES)).optional(),
+})
+    .strict();
+export const BannerConfigSchema = z
+    .object({
+    schema_version: z.literal(1),
+    layout: z.enum(LAYOUTS),
+    theme: ThemeSchema,
+    default_lang: z.string().regex(LANG_TAG),
+    languages: z.array(z.string().regex(LANG_TAG)).min(1).max(40),
+    texts: z.record(z.string().regex(LANG_TAG), TextsSchema),
+    categories: z.array(CategorySchema).min(1).max(12),
+    category_texts: z.record(z.string().regex(LANG_TAG), z.record(z.string().regex(CATEGORY_KEY), CategoryTextSchema)),
+    block: z.record(z.string().min(1).max(253), z.string().regex(CATEGORY_KEY)),
+    regions: RegionsSchema,
+    consent_mode: z
+        .object({
+        enabled: z.boolean(),
+        mode: z.enum(['basic', 'advanced']),
+        wait_for_update: z.number().int().min(0).max(5000),
+        /** gtag('set','ads_data_redaction', true) before the defaults; default true. */
+        ads_data_redaction: z.boolean().optional(),
+        /** gtag('set','url_passthrough', true); default false. */
+        url_passthrough: z.boolean().optional(),
+        /**
+         * What happens to the Google Tag Manager container script (`googletagmanager.com/gtm.js`) before
+         * a choice. `block` (the default): it waits for its category like any other script, so Tag
+         * Assistant sees nothing until a visitor decides. `load`: the container loads at once (it sets
+         * no cookies of its own) and the tags inside it are gated by the Consent Mode signals cc.js sets
+         * before it; the "Consent Initialization" trigger and the CookieCrumbs GTM template then work.
+         */
+        gtm_container: z.enum(['block', 'load']).optional(),
+    })
+        .strict(),
+    /**
+     * Links to the site's OWN pages, shown in the banner's footer. Optional, because not every site has
+     * both; each is rendered only when it is set. Labels come from `texts.<lang>.imprint_label` /
+     * `privacy_label` so they translate with everything else.
+     */
+    links: z
+        .object({
+        imprint: z.string().regex(URL_HTTP, 'expected a full http(s) address').max(2000).optional(),
+        privacy: z.string().regex(URL_HTTP, 'expected a full http(s) address').max(2000).optional(),
+    })
+        .strict()
+        .optional(),
+    /**
+     * The "Made & Hosted in Europe by CookieCrumbs" line in the banner footer. Omitted = shown.
+     * Turning it off is a paid entitlement: the publish gate requires the `remove_branding` plan
+     * feature, and `publish_version` forces `show: true` back in for plans without it.
+     */
+    branding: z.object({ show: z.boolean() }).strict().optional(),
+    /**
+     * Embed code injected when its category is granted, compiled at publish from managed services
+     * with an active `embed_code` (the CCM-style "source code of the embed"). Site-owner-authored
+     * markup, executed on the site owner's own page at their instruction; never edited by hand here.
+     */
+    inject: z
+        .array(z.object({ category: z.string().regex(CATEGORY_KEY), code: z.string().min(1).max(20000) }).strict())
+        .max(24)
+        .optional(),
+    behaviour: z
+        .object({
+        reask_on_material: z.boolean(),
+        refusal_months: z.number().int().min(1).max(13),
+        show_consent_id: z.boolean(),
+        reopen_control: z.enum(['floating', 'link']),
+        /** Closing layer 1 records `implied_dismiss` (all non-locked off); default false = no decision. */
+        implied_dismiss: z.boolean().optional(),
+        /** auto: data-cc-lang → <html lang> → navigator.languages → default_lang; default: default_lang only. */
+        lang_detect: z.enum(['auto', 'default']).optional(),
+        /**
+         * Show a language picker in the banner. `auto` (the default) shows it only when more than one
+         * language is configured, which is the only time it would do anything.
+         */
+        language_switcher: z.enum(['auto', 'always', 'never']).optional(),
+        /** What the reopen control (and [data-cc-open]) opens: the settings layer (default) or the first layer. */
+        reopen_opens: z.enum(['settings', 'banner']).optional(),
+        /**
+         * Render the category switches on the FIRST layer for quick selection. A Save button joins
+         * Accept all / Reject all, and Settings becomes a plain text link beneath the buttons.
+         */
+        categories_on_first: z.boolean().optional(),
+    })
+        .strict(),
+})
+    .strict();
+/** The JSON the runtime fetches: the draft plus publication metadata. */
+export const PublishedConfigSchema = BannerConfigSchema.extend({
+    version_id: z.string().uuid(),
+    number: z.number().int().min(1),
+    site_key: z.string(),
+    environment: z.enum(['production', 'preview']),
+    runtime_min: z.string(),
+    published_at: z.string(),
+    hashes: z.object({
+        config: z.string().length(64),
+        purposes: z.string().length(64),
+        texts: z.record(z.string(), z.string().length(64)),
+    }),
+});

package/dist/config/src/theme.js

@@ -0,0 +1,147 @@
+/**
+ * The Two Inks derivation — ONE implementation, shared by the runtime (which paints the banner) and the
+ * dashboard (which has to show the customer what their two choices produce before they publish).
+ *
+ * Duplicating this maths would guarantee drift between the preview and the real thing, which on a
+ * consent banner means a preview that passes contrast while the live banner fails it.
+ *
+ * See DESIGN.md → "The model". The rule that falls out of it: `ink` is the body-text colour, so it must
+ * pass 4.5:1 against `stock`; a bright colour can only ever be `ink2`.
+ */
+/** Relative luminance, WCAG 2.1. Inlined so this module imports nothing. */
+function luminance(hex) {
+    const n = parseInt(hex.slice(1), 16);
+    const c = [(n >> 16) & 255, (n >> 8) & 255, n & 255].map((v) => {
+        const s = v / 255;
+        return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+    });
+    return 0.2126 * c[0] + 0.7152 * c[1] + 0.0722 * c[2];
+}
+/** Contrast ratio between two #rrggbb colours. */
+export function contrast(a, b) {
+    const la = luminance(a);
+    const lb = luminance(b);
+    const [hi, lo] = la > lb ? [la, lb] : [lb, la];
+    return (hi + 0.05) / (lo + 0.05);
+}
+const rgb = (hex) => {
+    const n = parseInt(hex.slice(1), 16);
+    return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+};
+const toHex = (c) => '#' + c.map((v) => Math.round(Math.min(255, Math.max(0, v))).toString(16).padStart(2, '0')).join('');
+/** `t` = 0 returns a, 1 returns b. */
+export const mix = (a, b, t) => {
+    const [r1, g1, b1] = rgb(a);
+    const [r2, g2, b2] = rgb(b);
+    return toHex([r1 + (r2 - r1) * t, g1 + (g2 - g1) * t, b1 + (b2 - b1) * t]);
+};
+/** What two plates actually do where they cross: multiply. This is where the third colour comes from. */
+export const overprint = (a, b) => {
+    const [r1, g1, b1] = rgb(a);
+    const [r2, g2, b2] = rgb(b);
+    return toHex([(r1 * r2) / 255, (g1 * g2) / 255, (b1 * b2) / 255]);
+};
+/**
+ * Secondary text, in the ink's own hue rather than grey — but never lighter than AA allows.
+ *
+ * A fixed blend fails: mixing a mid-tone ink like #25408F a third of the way toward its stock lands at
+ * 3.77:1. So the blend walks back toward the ink until it clears 4.6:1, which means secondary text is as
+ * light as this particular pair can afford and no lighter.
+ *
+ * Muted text is also printed on the wash (the receipt strip, a hovered category row), which sits a few
+ * percent closer to the ink than the stock does — so the walk checks the wash too, or a pair like
+ * Press's federal blue passes on the stock and quietly lands at 4.1:1 on its own receipt.
+ */
+export function mutedOf(ink, stock) {
+    const wash = mix(ink, stock, 0.93);
+    for (let t = 0.34; t > 0.02; t -= 0.04) {
+        const c = mix(ink, stock, t);
+        if (contrast(c, stock) >= 4.6 && contrast(c, wash) >= 4.5)
+            return c;
+    }
+    return ink;
+}
+/** Two chosen values in, a whole palette out. The customer never sets the derived ones. */
+export function plates(t) {
+    const stock = t.stock || t.background;
+    const ink = t.ink || t.text;
+    const ink2 = t.ink2 || ink;
+    return {
+        stock,
+        ink,
+        ink2,
+        over: ink2 === ink ? mix(ink, '#000000', 0.18) : overprint(ink, ink2),
+        muted: mutedOf(ink, stock),
+        line: mix(ink, stock, 0.82),
+        wash: mix(ink, stock, 0.93),
+        onInk: stock,
+    };
+}
+/**
+ * The v1 six, computed from the pair. A `two_ink` config must always carry these so an older runtime,
+ * a config export, or a screenshot service renders the same banner without knowing the system exists.
+ */
+export function derivedCore(t) {
+    const p = plates(t);
+    return { background: p.stock, text: p.ink, muted: p.muted, button: p.ink, button_text: p.stock, border: p.line };
+}
+/** What the builder shows beside the two pickers, so the derivation is visible rather than magic. */
+export const DERIVED_ROLES = [
+    { key: 'muted', label: 'Secondary text', note: 'kept above 4.5:1 automatically' },
+    { key: 'over', label: 'Overprint', note: 'hover, focus ring, selection' },
+    { key: 'line', label: 'Hairlines', note: 'rules and dividers' },
+    { key: 'wash', label: 'Wash', note: 'row tint and the receipt strip' },
+];
+/**
+ * Strip everything from operator CSS that would reach off-origin.
+ *
+ * The banner runs before consent exists, so it may make no third-party request at any price — that rules
+ * out `@import` and any `url()` pointing at a scheme or a protocol-relative host. `data:` is kept: it is
+ * inline by definition and issues no request. Returns the cleaned CSS and what was removed, because a
+ * silent strip is how someone spends an afternoon wondering why their background never loads.
+ */
+export function sanitiseCss(css) {
+    const removed = [];
+    let out = css;
+    out = out.replace(/@import[^;]*;?/gi, (m) => {
+        removed.push(m.trim().slice(0, 80));
+        return '';
+    });
+    out = out.replace(/url\(\s*(['"]?)([^)'"]*)\1\s*\)/gi, (m, _q, ref) => {
+        const v = ref.trim();
+        if (/^data:/i.test(v) || v === '' || v.startsWith('#'))
+            return m;
+        removed.push(m.trim().slice(0, 80));
+        return 'none';
+    });
+    // </style> would end the banner's own stylesheet element early.
+    out = out.replace(/<\/style/gi, () => {
+        removed.push('</style');
+        return '';
+    });
+    return { css: out, removed };
+}
+/** The class names a banner is built from, so overriding it is not reverse engineering. */
+export const CSS_HOOKS = [
+    { sel: '.cc-p', what: 'the notice itself (both layers)' },
+    { sel: '.cc-t', what: 'the title' },
+    { sel: '.cc-b', what: 'the body text' },
+    { sel: '.cc-l', what: 'the declaration link' },
+    { sel: '.cc-a', what: 'the row of decisions' },
+    { sel: '.cc-btn', what: 'every button; .cc-s is the subordinate Settings one' },
+    { sel: '.cc-ft', what: 'the footer with your imprint and privacy links' },
+    { sel: '.cc-rc', what: 'the consent receipt strip' },
+    { sel: '.cc-rows', what: 'the category list on layer 2' },
+    { sel: '.cc-row', what: 'one category row' },
+    { sel: '.cc-sw', what: 'a category switch' },
+    { sel: '.cc-bd', what: 'the backdrop behind a modal or sheet' },
+    { sel: '.cc-r', what: 'the floating reopen button' },
+];
+/**
+ * Is this pair usable? `ink` carries the body text, so it must clear AA against `stock`. Returned rather
+ * than thrown: the builder shows it live while the customer is still dragging a colour picker.
+ */
+export function inkCheck(ink, stock) {
+    const r = contrast(ink, stock);
+    return { ratio: r, ok: r >= 4.5 };
+}

package/dist/config/src/verify.js

@@ -0,0 +1,51 @@
+import { canonJson, sha256Hex } from "./canon.js";
+const US = '';
+export function canonicalEvent(r) {
+    const ms = Date.parse(r.occurred_at);
+    return [
+        r.site_id,
+        r.environment,
+        r.id,
+        r.subject_id,
+        r.event_type,
+        String(ms),
+        r.version_id,
+        r.texts_hash,
+        r.language ?? '',
+        r.country ?? '',
+        r.regime ?? '',
+        canonJson(r.categories),
+        canonJson(r.services ?? {}),
+        r.tc_string ?? '',
+        canonJson(r.gcm_state ?? {}),
+        canonJson(r.collection ?? {}),
+        r.client_nonce,
+    ].join(US);
+}
+export async function recordHash(r) {
+    return sha256Hex((r.prev_hash ?? '') + canonicalEvent(r));
+}
+/**
+ * The hash the *next* record links to. A redacted (tombstoned) record keeps its original hash in
+ * `redaction_prev_hash` while `record_hash` was recomputed over the redacted values; this mirrors
+ * public.verify_chain and is the only special case in the chain.
+ */
+export function linkHash(r) {
+    return r.redacted ? (r.redaction_prev_hash ?? null) : r.record_hash;
+}
+/** Verifies an ordered list of records (oldest first) for one site + environment. */
+export async function verifyChain(records) {
+    let prev = records.length ? records[0].prev_hash : null;
+    for (let i = 0; i < records.length; i++) {
+        const r = records[i];
+        if ((r.prev_hash ?? null) !== (prev ?? null))
+            return { ok: false, checked: i, firstBadId: r.id };
+        if (r.redacted && !r.redaction_prev_hash)
+            return { ok: false, checked: i, firstBadId: r.id };
+        const h = await recordHash(r);
+        if (h !== r.record_hash)
+            return { ok: false, checked: i, firstBadId: r.id };
+        prev = linkHash(r);
+    }
+    return { ok: true, checked: records.length, firstBadId: null };
+}