@weatherboard/cms 0.0.0-stage → 0.1.0

package/dist/portable/site-content.d.mts

@@ -0,0 +1,220 @@
+/**
+ * A-1713. The site content model, read: the home page, content pages and site
+ * settings, validated on read and returned in the shape a site's page
+ * composition consumes.
+ *
+ * ===========================================================================
+ * READ ONLY, BY CONSTRUCTION
+ * ===========================================================================
+ *
+ * A client site reads its content with a read-only token. All editing goes
+ * through the studio's dashboard, which writes to Sanity; nothing on a client
+ * site writes, and this module has no write path to call. It is handed a
+ * `ContentClient` (a `query` function) and nothing else.
+ *
+ * ===========================================================================
+ * VALIDATED ON READ, BECAUSE SANITY VALIDATION ONLY ADVISES
+ * ===========================================================================
+ *
+ * The schema's rules warn an editor; they do not refuse a publish, and
+ * anything writing over the API skips them entirely. So every document is
+ * checked here again, and a malformed one is refused BY NAME
+ * (`MalformedContentError`, code `malformed-content`) listing every problem
+ * with its path, rather than rendered half-empty. A page that renders with a
+ * missing headline and a page whose content is broken look identical to a
+ * visitor; a build that fails naming `hero.headline` does not.
+ *
+ * Absent is not malformed: `null` from `home()` means nobody has created the
+ * home page yet, and a site decides what to do about that.
+ *
+ * ===========================================================================
+ * THE SHAPE IT RETURNS
+ * ===========================================================================
+ *
+ * The INPUT shape of a site's composition schema (the reference build's
+ * frontmatter): a copy value is a plain string for the client's own words
+ * with no claim about their source, `{ text, copySource: "captured" }` for
+ * words claimed verbatim from the capture (the site checks every such claim
+ * against its capture evidence, so the claim must survive Sanity), and
+ * `{ text, copySource: "proposed" }` for studio-written words awaiting
+ * approval. All three round-trip exactly; a photo is its library slug; every key a block declares is
+ * present, `null` where there is nothing. So a site validates this with the
+ * same schema it validates its Markdown frontmatter with, and its components
+ * never know where the content came from.
+ *
+ * Mapping from the generic model to the composition's names:
+ *
+ *   hero.headline / subline / lead      hero.heading / subline / intro
+ *   hero.photos[0], [1]                 hero.image, hero.inset
+ *   hero.primaryAction / secondary...   hero.cta / secondaryCta
+ *   campaign (when shown)               the FIRST block, kind `campaign`, and
+ *                                       the page body (`# title` + its text)
+ *   featureStoriesBlock                 kind `feature_stories`
+ *   surfaceCardBlock                    kind `cta`
+ *   accentBandBlock                     kind `accent_band`
+ *   locationsBlock                      kind `locations` (jumpLink → anchor)
+ *
+ * Two places the composition cannot carry a proposed marker: a `cta` block's
+ * plain strings, and the campaign's title and body (which travel as Markdown).
+ * There the text is returned plain and the line is still listed in
+ * `proposedCopy`, which is the list a dashboard and a site both read for
+ * approval. Nothing is dropped silently.
+ */
+import { type CmsQuery } from "../contracts/query.mjs";
+export type CopyInput = string | {
+    readonly text: string;
+    readonly copySource: "captured" | "proposed";
+};
+export type ActionInput = {
+    readonly label: CopyInput;
+    readonly href: string;
+};
+export type HeroInput = {
+    readonly heading: CopyInput;
+    readonly subline: CopyInput | null;
+    readonly intro: CopyInput | null;
+    readonly image: string | null;
+    readonly inset: string | null;
+    readonly cta: ActionInput | null;
+    readonly secondaryCta: ActionInput | null;
+};
+export type StoryInput = {
+    readonly heading: CopyInput;
+    readonly body: CopyInput;
+    readonly action: ActionInput;
+    readonly image: string | null;
+    readonly shape: "wide" | "tall" | "round" | "free";
+    readonly card: boolean;
+};
+export type CompositionBlockInput = {
+    readonly kind: "campaign";
+    readonly action: ActionInput | null;
+    readonly images: readonly string[];
+} | {
+    readonly kind: "locations";
+    readonly anchor: string | null;
+    readonly heading: CopyInput;
+    readonly tail: CopyInput | null;
+    readonly image: string | null;
+} | {
+    readonly kind: "feature_stories";
+    readonly heading: CopyInput;
+    readonly tail: CopyInput | null;
+    readonly items: readonly StoryInput[];
+} | {
+    readonly kind: "accent_band";
+    readonly heading: CopyInput;
+    readonly body: CopyInput;
+    readonly action: ActionInput | null;
+    readonly image: string | null;
+} | {
+    readonly kind: "cta";
+    readonly heading: string;
+    readonly body: string | null;
+    readonly link: {
+        readonly label: string;
+        readonly href: string;
+    };
+};
+export type CompositionInput = {
+    readonly intro: string | null;
+    readonly photo: string | null;
+    readonly hero: HeroInput | null;
+    readonly blocks: readonly CompositionBlockInput[];
+};
+/** One line of studio-written copy awaiting approval, and where it is in the document. */
+export type ProposedCopy = {
+    readonly where: string;
+    readonly text: string;
+};
+export type CampaignState = "shown" | "off" | "not-started" | "ended" | "none";
+export type HomeContent = {
+    readonly composition: CompositionInput;
+    /** The page body as Markdown: the campaign's title and text when it is shown, otherwise empty. */
+    readonly body: string;
+    readonly campaign: CampaignState;
+    readonly proposedCopy: readonly ProposedCopy[];
+};
+export type PageContent = {
+    readonly slug: string;
+    readonly title: string;
+    readonly composition: CompositionInput;
+    readonly body: string;
+    readonly migrated: boolean;
+    readonly proposedCopy: readonly ProposedCopy[];
+};
+export type SiteSettingsContent = {
+    readonly name: string;
+    readonly description: string | null;
+    readonly contact: {
+        readonly email: string | null;
+        readonly phone: string | null;
+    };
+    readonly social: readonly {
+        readonly network: string;
+        readonly url: string;
+    }[];
+};
+export declare const MALFORMED_CONTENT = "malformed-content";
+export declare class MalformedContentError extends Error {
+    readonly code = "malformed-content";
+    readonly documentId: string;
+    readonly problems: readonly string[];
+    constructor(documentId: string, problems: readonly string[]);
+}
+export declare const READER_PHOTO_SLUG: RegExp;
+export declare const READER_ACTION_HREF: RegExp;
+export declare const READER_JUMP_LINK: RegExp;
+export declare const READER_STORY_LAYOUTS: readonly ["wide", "tall", "round", "free"];
+export declare const READER_HOME_PAGE_ID = "homePage";
+export declare const READER_SITE_SETTINGS_ID = "siteSettings";
+/**
+ * The narrow Portable Text `portableText` declares, back to Markdown: normal,
+ * h2, h3 and quote blocks, bullet and numbered lists, bold, italic, code and
+ * links. It is the inverse of the seed package's Markdown mapper, and the
+ * round-trip test holds the two to each other.
+ *
+ * An uploaded image inside rich text is REFUSED, not dropped: nothing can
+ * upload one yet (the dashboard slice decides how), so one arriving means
+ * something wrote the document by hand, and a page silently missing a picture
+ * is the failure this reader exists to prevent.
+ */
+export declare function portableTextToMarkdown(value: unknown): string;
+/** Whether a campaign is shown at `now`, and if not, why not. */
+export declare function campaignState(campaign: unknown, now: Date): CampaignState;
+/**
+ * A stored home page document, validated and mapped. Throws
+ * `MalformedContentError` naming every problem. `now` decides whether a
+ * scheduled campaign is shown, and is a parameter so a build, a preview and a
+ * test each say which moment they mean.
+ */
+export declare function parseHomePage(document: unknown, options: {
+    readonly now: Date;
+}): HomeContent;
+export declare function parseContentPage(document: unknown): PageContent;
+export declare function parseSiteSettings(document: unknown): SiteSettingsContent;
+/** By fixed id: a second home page at a random id is never read. */
+export declare const HOME_PAGE_DOCUMENT_QUERY = "*[_id == $id][0]";
+export declare const CONTENT_PAGES_QUERY = "*[_type == \"page\" && defined(slug.current)]|order(slug.current asc)";
+export declare const CONTENT_PAGE_BY_SLUG_QUERY = "*[_type == \"page\" && slug.current == $slug][0]";
+export interface SiteContentReader {
+    /** `null` when no home page document exists yet. */
+    home: (options: {
+        readonly now: Date;
+    }) => Promise<HomeContent | null>;
+    pages: () => Promise<PageContent[]>;
+    /** `null` when no page has that slug. */
+    pageBySlug: (slug: string) => Promise<PageContent | null>;
+    /** `null` before anyone has filled in the site's details. */
+    siteSettings: () => Promise<SiteSettingsContent | null>;
+}
+export declare function createSiteContentReader(client: {
+    query: <T>(groq: string, options?: {
+        params?: Record<string, unknown>;
+        tags?: readonly string[];
+    }) => Promise<T>;
+}): SiteContentReader;
+export declare function homeContentQuery(now: Date): CmsQuery<HomeContent | null>;
+export declare function contentPageQuery(slug: string): CmsQuery<PageContent | null>;
+export declare function contentPagesQuery(): CmsQuery<readonly PageContent[]>;
+export declare function siteSettingsQuery(): CmsQuery<SiteSettingsContent | null>;

package/dist/portable/site-content.d.ts

@@ -0,0 +1,220 @@
+/**
+ * A-1713. The site content model, read: the home page, content pages and site
+ * settings, validated on read and returned in the shape a site's page
+ * composition consumes.
+ *
+ * ===========================================================================
+ * READ ONLY, BY CONSTRUCTION
+ * ===========================================================================
+ *
+ * A client site reads its content with a read-only token. All editing goes
+ * through the studio's dashboard, which writes to Sanity; nothing on a client
+ * site writes, and this module has no write path to call. It is handed a
+ * `ContentClient` (a `query` function) and nothing else.
+ *
+ * ===========================================================================
+ * VALIDATED ON READ, BECAUSE SANITY VALIDATION ONLY ADVISES
+ * ===========================================================================
+ *
+ * The schema's rules warn an editor; they do not refuse a publish, and
+ * anything writing over the API skips them entirely. So every document is
+ * checked here again, and a malformed one is refused BY NAME
+ * (`MalformedContentError`, code `malformed-content`) listing every problem
+ * with its path, rather than rendered half-empty. A page that renders with a
+ * missing headline and a page whose content is broken look identical to a
+ * visitor; a build that fails naming `hero.headline` does not.
+ *
+ * Absent is not malformed: `null` from `home()` means nobody has created the
+ * home page yet, and a site decides what to do about that.
+ *
+ * ===========================================================================
+ * THE SHAPE IT RETURNS
+ * ===========================================================================
+ *
+ * The INPUT shape of a site's composition schema (the reference build's
+ * frontmatter): a copy value is a plain string for the client's own words
+ * with no claim about their source, `{ text, copySource: "captured" }` for
+ * words claimed verbatim from the capture (the site checks every such claim
+ * against its capture evidence, so the claim must survive Sanity), and
+ * `{ text, copySource: "proposed" }` for studio-written words awaiting
+ * approval. All three round-trip exactly; a photo is its library slug; every key a block declares is
+ * present, `null` where there is nothing. So a site validates this with the
+ * same schema it validates its Markdown frontmatter with, and its components
+ * never know where the content came from.
+ *
+ * Mapping from the generic model to the composition's names:
+ *
+ *   hero.headline / subline / lead      hero.heading / subline / intro
+ *   hero.photos[0], [1]                 hero.image, hero.inset
+ *   hero.primaryAction / secondary...   hero.cta / secondaryCta
+ *   campaign (when shown)               the FIRST block, kind `campaign`, and
+ *                                       the page body (`# title` + its text)
+ *   featureStoriesBlock                 kind `feature_stories`
+ *   surfaceCardBlock                    kind `cta`
+ *   accentBandBlock                     kind `accent_band`
+ *   locationsBlock                      kind `locations` (jumpLink → anchor)
+ *
+ * Two places the composition cannot carry a proposed marker: a `cta` block's
+ * plain strings, and the campaign's title and body (which travel as Markdown).
+ * There the text is returned plain and the line is still listed in
+ * `proposedCopy`, which is the list a dashboard and a site both read for
+ * approval. Nothing is dropped silently.
+ */
+import { type CmsQuery } from "../contracts/query.js";
+export type CopyInput = string | {
+    readonly text: string;
+    readonly copySource: "captured" | "proposed";
+};
+export type ActionInput = {
+    readonly label: CopyInput;
+    readonly href: string;
+};
+export type HeroInput = {
+    readonly heading: CopyInput;
+    readonly subline: CopyInput | null;
+    readonly intro: CopyInput | null;
+    readonly image: string | null;
+    readonly inset: string | null;
+    readonly cta: ActionInput | null;
+    readonly secondaryCta: ActionInput | null;
+};
+export type StoryInput = {
+    readonly heading: CopyInput;
+    readonly body: CopyInput;
+    readonly action: ActionInput;
+    readonly image: string | null;
+    readonly shape: "wide" | "tall" | "round" | "free";
+    readonly card: boolean;
+};
+export type CompositionBlockInput = {
+    readonly kind: "campaign";
+    readonly action: ActionInput | null;
+    readonly images: readonly string[];
+} | {
+    readonly kind: "locations";
+    readonly anchor: string | null;
+    readonly heading: CopyInput;
+    readonly tail: CopyInput | null;
+    readonly image: string | null;
+} | {
+    readonly kind: "feature_stories";
+    readonly heading: CopyInput;
+    readonly tail: CopyInput | null;
+    readonly items: readonly StoryInput[];
+} | {
+    readonly kind: "accent_band";
+    readonly heading: CopyInput;
+    readonly body: CopyInput;
+    readonly action: ActionInput | null;
+    readonly image: string | null;
+} | {
+    readonly kind: "cta";
+    readonly heading: string;
+    readonly body: string | null;
+    readonly link: {
+        readonly label: string;
+        readonly href: string;
+    };
+};
+export type CompositionInput = {
+    readonly intro: string | null;
+    readonly photo: string | null;
+    readonly hero: HeroInput | null;
+    readonly blocks: readonly CompositionBlockInput[];
+};
+/** One line of studio-written copy awaiting approval, and where it is in the document. */
+export type ProposedCopy = {
+    readonly where: string;
+    readonly text: string;
+};
+export type CampaignState = "shown" | "off" | "not-started" | "ended" | "none";
+export type HomeContent = {
+    readonly composition: CompositionInput;
+    /** The page body as Markdown: the campaign's title and text when it is shown, otherwise empty. */
+    readonly body: string;
+    readonly campaign: CampaignState;
+    readonly proposedCopy: readonly ProposedCopy[];
+};
+export type PageContent = {
+    readonly slug: string;
+    readonly title: string;
+    readonly composition: CompositionInput;
+    readonly body: string;
+    readonly migrated: boolean;
+    readonly proposedCopy: readonly ProposedCopy[];
+};
+export type SiteSettingsContent = {
+    readonly name: string;
+    readonly description: string | null;
+    readonly contact: {
+        readonly email: string | null;
+        readonly phone: string | null;
+    };
+    readonly social: readonly {
+        readonly network: string;
+        readonly url: string;
+    }[];
+};
+export declare const MALFORMED_CONTENT = "malformed-content";
+export declare class MalformedContentError extends Error {
+    readonly code = "malformed-content";
+    readonly documentId: string;
+    readonly problems: readonly string[];
+    constructor(documentId: string, problems: readonly string[]);
+}
+export declare const READER_PHOTO_SLUG: RegExp;
+export declare const READER_ACTION_HREF: RegExp;
+export declare const READER_JUMP_LINK: RegExp;
+export declare const READER_STORY_LAYOUTS: readonly ["wide", "tall", "round", "free"];
+export declare const READER_HOME_PAGE_ID = "homePage";
+export declare const READER_SITE_SETTINGS_ID = "siteSettings";
+/**
+ * The narrow Portable Text `portableText` declares, back to Markdown: normal,
+ * h2, h3 and quote blocks, bullet and numbered lists, bold, italic, code and
+ * links. It is the inverse of the seed package's Markdown mapper, and the
+ * round-trip test holds the two to each other.
+ *
+ * An uploaded image inside rich text is REFUSED, not dropped: nothing can
+ * upload one yet (the dashboard slice decides how), so one arriving means
+ * something wrote the document by hand, and a page silently missing a picture
+ * is the failure this reader exists to prevent.
+ */
+export declare function portableTextToMarkdown(value: unknown): string;
+/** Whether a campaign is shown at `now`, and if not, why not. */
+export declare function campaignState(campaign: unknown, now: Date): CampaignState;
+/**
+ * A stored home page document, validated and mapped. Throws
+ * `MalformedContentError` naming every problem. `now` decides whether a
+ * scheduled campaign is shown, and is a parameter so a build, a preview and a
+ * test each say which moment they mean.
+ */
+export declare function parseHomePage(document: unknown, options: {
+    readonly now: Date;
+}): HomeContent;
+export declare function parseContentPage(document: unknown): PageContent;
+export declare function parseSiteSettings(document: unknown): SiteSettingsContent;
+/** By fixed id: a second home page at a random id is never read. */
+export declare const HOME_PAGE_DOCUMENT_QUERY = "*[_id == $id][0]";
+export declare const CONTENT_PAGES_QUERY = "*[_type == \"page\" && defined(slug.current)]|order(slug.current asc)";
+export declare const CONTENT_PAGE_BY_SLUG_QUERY = "*[_type == \"page\" && slug.current == $slug][0]";
+export interface SiteContentReader {
+    /** `null` when no home page document exists yet. */
+    home: (options: {
+        readonly now: Date;
+    }) => Promise<HomeContent | null>;
+    pages: () => Promise<PageContent[]>;
+    /** `null` when no page has that slug. */
+    pageBySlug: (slug: string) => Promise<PageContent | null>;
+    /** `null` before anyone has filled in the site's details. */
+    siteSettings: () => Promise<SiteSettingsContent | null>;
+}
+export declare function createSiteContentReader(client: {
+    query: <T>(groq: string, options?: {
+        params?: Record<string, unknown>;
+        tags?: readonly string[];
+    }) => Promise<T>;
+}): SiteContentReader;
+export declare function homeContentQuery(now: Date): CmsQuery<HomeContent | null>;
+export declare function contentPageQuery(slug: string): CmsQuery<PageContent | null>;
+export declare function contentPagesQuery(): CmsQuery<readonly PageContent[]>;
+export declare function siteSettingsQuery(): CmsQuery<SiteSettingsContent | null>;

package/dist/portable/webhook.d.cts

@@ -0,0 +1,133 @@
+/**
+ * Verifying a Sanity webhook (A-590 step 1, A-592's `SANITY_WEBHOOK_SECRET`).
+ *
+ * -------------------------------------------------------------------------
+ * WHY THIS ENDPOINT NEEDS A SIGNATURE AT ALL
+ * -------------------------------------------------------------------------
+ *
+ * `/revalidate` throws away cache entries. A-590: "An unauthenticated
+ * revalidation endpoint is a free cache-purge and rebuild trigger for anyone
+ * who finds the URL." On a plan whose API request allowance is a HARD cap that
+ * returns 402 rather than a bill, an attacker who can empty the cache at will
+ * can take a client's site content-offline for the rest of the month. So the
+ * signature is not hygiene here; it is the availability control.
+ *
+ * -------------------------------------------------------------------------
+ * THE WIRE FORMAT IS MEASURED, NOT REMEMBERED
+ * -------------------------------------------------------------------------
+ *
+ * Read on 2026-09-16 from Sanity's own toolkit,
+ * `https://raw.githubusercontent.com/sanity-io/webhook-toolkit/main/src/signature.ts`:
+ *
+ *   header            `sanity-webhook-signature`
+ *   value             `t=<millis>,v1=<signature>`  (regex `/^t=(\d+)[, ]+v1=([^, ]+)$/`)
+ *   signed payload    `` `${timestamp}.${body}` ``
+ *   algorithm         HMAC-SHA256
+ *   digest encoding   base64url — standard base64 with `+`→`-`, `/`→`_`, padding stripped
+ *   MINIMUM_TIMESTAMP 1609459200000 (2021-01-01Z), below which a value is nonsense
+ *
+ * `signature.test.ts` does not take that paragraph's word for it either: it
+ * signs a payload with `@sanity/webhook`'s own `encodeSignatureHeader` and
+ * asserts this verifier accepts it. If Sanity changes the format, that test
+ * goes red rather than production quietly rejecting every webhook.
+ *
+ * -------------------------------------------------------------------------
+ * WHAT THIS ADDS TO THE TOOLKIT, AND WHY IT IS NOT JUST IMPORTED
+ * -------------------------------------------------------------------------
+ *
+ * Two things, both of which are `CLAUDE.md`'s "take the safer construction".
+ *
+ * First, a REPLAY WINDOW. The toolkit enforces only that the timestamp is after
+ * 2021; a captured webhook is otherwise replayable forever. A replayed purge is
+ * the attack in the first paragraph, executed with a request somebody was
+ * legitimately sent. `verifySanityWebhook` takes a symmetric tolerance — the
+ * window is symmetric for A-44's reason, since a far-future timestamp is
+ * precisely how you mint a request that stays replayable for a year.
+ *
+ * Second, a MISSING SECRET IS A REJECTION, never a bypass. A-590 says it in as
+ * many words: "reject on absence rather than skipping the check when the secret
+ * is unset." The degraded mode of "no secret configured, so allow it" is
+ * produced by a deploy that forgot `wrangler secret put`, announces itself
+ * nowhere, and grants strangers the purge endpoint.
+ *
+ * The comparison is `crypto.subtle.verify`, which compares raw digests in
+ * constant time. A `===` on the base64 strings short-circuits at the first
+ * differing character, which turns one 2^256 search into a few dozen sequential
+ * 64-way ones against an endpoint that answers in milliseconds.
+ *
+ * -------------------------------------------------------------------------
+ * `encodeSignatureHeader` IS ASYNC. AWAIT IT. (A-651)
+ * -------------------------------------------------------------------------
+ *
+ * `@sanity/webhook@4.0.4` declares
+ *
+ *   encodeSignatureHeader(payload: string, timestamp: number, secret: string):
+ *     Promise<string>
+ *
+ * and nothing forces you to await it. Drop the `await` and the Promise is
+ * stringified into the header as the literal `[object Promise]`, which arrives
+ * here, fails `SIGNATURE_VALUE`, and is rejected as `malformed-signature`. The
+ * rejection is correct and the message is about the wire format, so it sends
+ * you to read Sanity's header spec — the one place the bug is not. TypeScript
+ * does not save you either: the value usually lands in a `Record<string,
+ * string>` built by a helper, or inside a template literal, both of which take
+ * a Promise without complaint.
+ *
+ * The rule: every call to `encodeSignatureHeader` is awaited, and the helper
+ * that wraps it is `async` rather than returning the Promise for someone else
+ * to forget. The content-client compatibility tests and CMS signer tests await every
+ * encoder call; this note exists so the next one
+ * is too, because the symptom will not tell you.
+ */
+/** Sanity's header. Lower-cased; `Headers.get` is case-insensitive either way. */
+export declare const SANITY_SIGNATURE_HEADER = "sanity-webhook-signature";
+/** 2021-01-01T00:00:00.000Z. Sanity's `MINIMUM_TIMESTAMP`; anything earlier is not a timestamp. */
+export declare const MINIMUM_TIMESTAMP = 1609459200000;
+/**
+ * How far from `now` a webhook timestamp may be, in milliseconds.
+ *
+ * Five minutes rather than A-44's sixty seconds: this one crosses Sanity's
+ * delivery queue rather than two NTP-synced clouds, and a retried delivery is a
+ * normal event. It is still a window rather than "forever", which is the whole
+ * difference from the toolkit.
+ */
+export declare const DEFAULT_TOLERANCE_MS = 300000;
+export type WebhookRejection = 
+/** `SANITY_WEBHOOK_SECRET` is unset or empty. Fail closed. */
+"no-secret"
+/** No `sanity-webhook-signature` header. */
+ | "no-signature"
+/** Header present but not `t=…,v1=…`, or `v1` is not decodable base64url. */
+ | "malformed-signature"
+/** Before 2021, or outside the tolerance in either direction. */
+ | "stale-timestamp"
+/** Well-formed, in window, wrong. */
+ | "bad-signature";
+export type WebhookVerification = {
+    ok: true;
+} | {
+    ok: false;
+    reason: WebhookRejection;
+};
+/**
+ * Verify a Sanity webhook delivery.
+ *
+ * `rawBody` must be the bytes as received — `await request.text()`, never
+ * `JSON.stringify(await request.json())`. A parse-and-restringify is not a
+ * byte-for-byte round trip (key order, number formatting, whitespace) and one
+ * byte changes the whole digest, so the symptom is every webhook failing after
+ * a refactor that looked like tidying.
+ *
+ * The `reason` is for our logs and our tests. It is never returned to the
+ * caller: "your signature was fine but your clock is stale" is the next step in
+ * an attack, handed over free.
+ */
+export declare function verifySanityWebhook(options: {
+    secret: string | undefined;
+    rawBody: string;
+    headers: {
+        get(name: string): string | null;
+    };
+    now?: number;
+    toleranceMs?: number;
+}): Promise<WebhookVerification>;