@openlup/platform 0.16.0 → 0.17.0

package/dist/communications/sql.d.ts

@@ -0,0 +1,26 @@
+/** Sparse projections of canonical units, never an install chain. */
+export declare const COMMUNICATIONS_MIGRATIONS: readonly [{
+    readonly id: "20260807190000_comms_outbox_rail";
+    readonly catalogPath: "db/platform/migrations/20260807190000_comms_outbox_rail.sql";
+    readonly position: 2;
+    readonly sha256: "dfb3e9808714846738222bb74a1bfdb38ceafdde2ca8a0c71ab835739fb333bd";
+    readonly url: URL;
+}, {
+    readonly id: "20260810120001_transactional_delivery_receipts";
+    readonly catalogPath: "db/platform/migrations/20260810120001_transactional_delivery_receipts.sql";
+    readonly position: 9;
+    readonly sha256: "a157f075f8684c29958c565239c19a55894bffaaff4fd80e04ee689c926e33f7";
+    readonly url: URL;
+}, {
+    readonly id: "20260813120000_communications_control_plane";
+    readonly catalogPath: "db/platform/migrations/20260813120000_communications_control_plane.sql";
+    readonly position: 20;
+    readonly sha256: "dea5fe631f1329272989e1598f6f48aeb6ce67fa070ddeb0200f69f62fcd972a";
+    readonly url: URL;
+}, {
+    readonly id: "20261019200000_communications_native_operations";
+    readonly catalogPath: "db/platform/migrations/20261019200000_communications_native_operations.sql";
+    readonly position: 70;
+    readonly sha256: "1d28380f12324c3bcccaa5a6d38c22e72332c7992bbb1f90651774dfc5e24982";
+    readonly url: URL;
+}];

package/dist/communications/sql.js

@@ -0,0 +1,7 @@
+/** Sparse projections of canonical units, never an install chain. */
+export const COMMUNICATIONS_MIGRATIONS = [
+    { id: "20260807190000_comms_outbox_rail", catalogPath: "db/platform/migrations/20260807190000_comms_outbox_rail.sql", position: 2, sha256: "dfb3e9808714846738222bb74a1bfdb38ceafdde2ca8a0c71ab835739fb333bd", url: new URL("../../sql/20260807190000_comms_outbox_rail.sql", import.meta.url) },
+    { id: "20260810120001_transactional_delivery_receipts", catalogPath: "db/platform/migrations/20260810120001_transactional_delivery_receipts.sql", position: 9, sha256: "a157f075f8684c29958c565239c19a55894bffaaff4fd80e04ee689c926e33f7", url: new URL("../../sql/20260810120001_transactional_delivery_receipts.sql", import.meta.url) },
+    { id: "20260813120000_communications_control_plane", catalogPath: "db/platform/migrations/20260813120000_communications_control_plane.sql", position: 20, sha256: "dea5fe631f1329272989e1598f6f48aeb6ce67fa070ddeb0200f69f62fcd972a", url: new URL("../../sql/20260813120000_communications_control_plane.sql", import.meta.url) },
+    { id: "20261019200000_communications_native_operations", catalogPath: "db/platform/migrations/20261019200000_communications_native_operations.sql", position: 70, sha256: "1d28380f12324c3bcccaa5a6d38c22e72332c7992bbb1f90651774dfc5e24982", url: new URL("../../sql/20261019200000_communications_native_operations.sql", import.meta.url) },
+];

package/dist/communications/standardWebhooks.d.ts

@@ -0,0 +1,14 @@
+export interface StandardWebhookHeaders {
+    id: string | null;
+    timestamp: string | null;
+    signature: string | null;
+}
+export declare function timingSafeEqual(a: string, b: string): boolean;
+export declare function standardWebhookKeyBytes(secret: string): Uint8Array;
+export declare function verifyStandardWebhookSignature(opts: {
+    headers: StandardWebhookHeaders;
+    rawBody: string;
+    secret: string;
+    toleranceSeconds?: number;
+    now?: () => number;
+}): Promise<boolean>;

package/dist/communications/standardWebhooks.js

@@ -0,0 +1,73 @@
+/**
+ * Node-native Standard Webhooks verifier for the inactive Auth email candidate.
+ * It intentionally mirrors the deployed Edge algorithm: `id.timestamp.rawBody`
+ * is signed with a decoded `whsec_` key and any space-separated v1 signature may
+ * match. Keep this independent of deployable Edge packaging.
+ */
+import { createHmac } from "node:crypto";
+const DEFAULT_TOLERANCE_SECONDS = 5 * 60;
+export function timingSafeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let index = 0; index < a.length; index += 1)
+        diff |= a.charCodeAt(index) ^ b.charCodeAt(index);
+    return diff === 0;
+}
+export function standardWebhookKeyBytes(secret) {
+    let value = secret.trim();
+    if (!value)
+        throw new Error("standard_webhook_secret_empty");
+    if (value.startsWith("v1,"))
+        value = value.slice("v1,".length);
+    if (value.startsWith("whsec_")) {
+        const decoded = decodeStandardWebhookKey(value.slice("whsec_".length));
+        // An empty `whsec_` would make a publicly reproducible empty-key HMAC. It
+        // is not a usable Standard Webhooks secret even though it is valid base64.
+        if (decoded.length === 0)
+            throw new Error("standard_webhook_secret_empty");
+        return Uint8Array.from(decoded, (character) => character.charCodeAt(0));
+    }
+    return new TextEncoder().encode(value);
+}
+function decodeStandardWebhookKey(base64) {
+    if (base64.length === 0)
+        return "";
+    if (!/^[A-Za-z0-9+/]+={0,2}$/.test(base64) || base64.length % 4 === 1) {
+        throw new Error("standard_webhook_secret_invalid_base64");
+    }
+    const decoded = atob(base64);
+    const canonicalPadded = Buffer.from(decoded, "latin1").toString("base64");
+    const canonicalUnpadded = canonicalPadded.replace(/=+$/, "");
+    if (base64 !== canonicalPadded && base64 !== canonicalUnpadded) {
+        throw new Error("standard_webhook_secret_invalid_base64");
+    }
+    return decoded;
+}
+async function hmacSha256Base64(keyBytes, message) {
+    return createHmac("sha256", Buffer.from(keyBytes)).update(message).digest("base64");
+}
+export async function verifyStandardWebhookSignature(opts) {
+    const { headers, rawBody, secret } = opts;
+    if (!secret || !headers.id || !headers.timestamp || !headers.signature)
+        return false;
+    const timestampSeconds = Number(headers.timestamp);
+    if (!Number.isFinite(timestampSeconds))
+        return false;
+    const nowSeconds = Math.floor((opts.now?.() ?? Date.now()) / 1000);
+    if (Math.abs(nowSeconds - timestampSeconds) > (opts.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS))
+        return false;
+    let expected;
+    try {
+        expected = await hmacSha256Base64(standardWebhookKeyBytes(secret), `${headers.id}.${headers.timestamp}.${rawBody}`);
+    }
+    catch {
+        // A malformed whsec_ value is an invalid verification key, never a reason
+        // to bypass signature verification or surface an unhandled request error.
+        return false;
+    }
+    return headers.signature
+        .split(" ")
+        .map((part) => (part.includes(",") ? part.slice(part.indexOf(",") + 1) : part))
+        .some((candidate) => timingSafeEqual(candidate, expected));
+}

package/dist/communications/status.d.ts

@@ -0,0 +1,11 @@
+import type { EmailSendDecision, EmailSendStatus } from "./contracts/types.js";
+export declare function isTerminalEmailSendStatus(status: string | null): status is EmailSendStatus;
+export declare function buildEmailSendDedupeKey(input: {
+    recipientId: string;
+    templateSlug: string;
+}): string;
+export declare function decideEmailSend(input: {
+    sequencePaused: boolean | null;
+    existingNonFailedMessageId: string | null;
+    templateAvailable: boolean;
+}): EmailSendDecision;

package/dist/communications/status.js

@@ -0,0 +1,36 @@
+const TERMINAL_EMAIL_STATUSES = new Set([
+    "bounced",
+    "complained",
+    "failed",
+    "skipped",
+]);
+export function isTerminalEmailSendStatus(status) {
+    return status !== null && TERMINAL_EMAIL_STATUSES.has(status);
+}
+export function buildEmailSendDedupeKey(input) {
+    return `email:${input.recipientId.trim()}:${input.templateSlug.trim()}`;
+}
+export function decideEmailSend(input) {
+    if (input.sequencePaused) {
+        return {
+            outcome: "skip",
+            reason: "sequence_paused",
+            existingMessageId: null,
+        };
+    }
+    if (input.existingNonFailedMessageId) {
+        return {
+            outcome: "skip",
+            reason: "already_sent",
+            existingMessageId: input.existingNonFailedMessageId,
+        };
+    }
+    if (!input.templateAvailable) {
+        return {
+            outcome: "skip",
+            reason: "template_unavailable",
+            existingMessageId: null,
+        };
+    }
+    return { outcome: "send" };
+}

package/dist/communications/transactionalDelivery.d.ts

@@ -0,0 +1,19 @@
+import type { CapturedTransactionalDeliveryPort, TransactionalDeliveryCommand, TransactionalDeliveryReceipt, TransactionalDeliveryReceiptStore } from "./contracts/transactionalDelivery.js";
+export declare class TransactionalDeliveryValidationError extends Error {
+    constructor();
+}
+export declare class TransactionalDeliveryConflictError extends Error {
+    constructor();
+}
+export declare class TransactionalDeliveryUnavailableError extends Error {
+    constructor();
+}
+/** One direct command, one captured delivery attempt, and one durable receipt transition. */
+export declare function createTransactionalDelivery(deps: {
+    store: TransactionalDeliveryReceiptStore;
+    delivery: CapturedTransactionalDeliveryPort;
+}, options?: {
+    fingerprint?: (command: TransactionalDeliveryCommand) => string;
+}): {
+    send(command: TransactionalDeliveryCommand): Promise<TransactionalDeliveryReceipt>;
+};

package/dist/communications/transactionalDelivery.js

@@ -0,0 +1,96 @@
+import { isTransactionalDeliveryIdentifier } from "./transactionalDeliveryIdentifier.js";
+import { createHash } from "node:crypto";
+const FINGERPRINT = /^[a-f0-9]{64}$/;
+const FAILURE_CODE = /^[a-z][a-z0-9_.-]{0,127}$/;
+export class TransactionalDeliveryValidationError extends Error {
+    constructor() {
+        super("transactional_delivery_command_invalid");
+    }
+}
+export class TransactionalDeliveryConflictError extends Error {
+    constructor() {
+        super("transactional_delivery_command_conflict");
+    }
+}
+export class TransactionalDeliveryUnavailableError extends Error {
+    constructor() {
+        super("transactional_delivery_unavailable");
+    }
+}
+function fingerprint(command) {
+    return createHash("sha256")
+        .update(JSON.stringify({
+        recipientReference: command.recipientReference,
+        templateReference: command.templateReference,
+        accessGrantReference: command.accessGrantReference ?? null,
+    }))
+        .digest("hex");
+}
+function validate(command) {
+    if (!isTransactionalDeliveryIdentifier(command.idempotencyKey)
+        || !isTransactionalDeliveryIdentifier(command.recipientReference)
+        || !isTransactionalDeliveryIdentifier(command.templateReference)
+        || (command.accessGrantReference !== undefined
+            && !isTransactionalDeliveryIdentifier(command.accessGrantReference))) {
+        throw new TransactionalDeliveryValidationError();
+    }
+}
+function accepted(receipt, idempotencyKey, commandFingerprint) {
+    if (receipt.idempotencyKey !== idempotencyKey || receipt.commandFingerprint !== commandFingerprint
+        || receipt.state !== "accepted" || !isTransactionalDeliveryIdentifier(receipt.deliveryReference)
+        || !Number.isInteger(receipt.attemptCount) || receipt.attemptCount < 1) {
+        throw new Error("transactional_delivery_receipt_invalid");
+    }
+    return receipt;
+}
+/** One direct command, one captured delivery attempt, and one durable receipt transition. */
+export function createTransactionalDelivery(deps, options = {}) {
+    const commandFingerprint = options.fingerprint ?? fingerprint;
+    return {
+        async send(command) {
+            validate(command);
+            const digest = commandFingerprint(command);
+            if (!FINGERPRINT.test(digest))
+                throw new Error("transactional_delivery_fingerprint_invalid");
+            const prior = await deps.store.readReceipt(command.idempotencyKey);
+            if (prior) {
+                if (prior.commandFingerprint !== digest)
+                    throw new TransactionalDeliveryConflictError();
+                if (prior.state === "accepted")
+                    return accepted(prior, command.idempotencyKey, digest);
+            }
+            try {
+                const { deliveryReference } = await deps.delivery.deliver(command);
+                if (!isTransactionalDeliveryIdentifier(deliveryReference))
+                    throw new Error("captured_delivery_reference_invalid");
+                try {
+                    return accepted(await deps.store.recordAccepted({
+                        idempotencyKey: command.idempotencyKey,
+                        commandFingerprint: digest,
+                        deliveryReference,
+                    }), command.idempotencyKey, digest);
+                }
+                catch {
+                    // Delivery may already have happened. Never turn an accepted-write
+                    // failure into a durable failed receipt for the same command.
+                    throw new TransactionalDeliveryUnavailableError();
+                }
+            }
+            catch (error) {
+                if (error instanceof TransactionalDeliveryUnavailableError)
+                    throw error;
+                try {
+                    await deps.store.recordFailed({
+                        idempotencyKey: command.idempotencyKey,
+                        commandFingerprint: digest,
+                        errorCode: "captured_delivery_failed",
+                    });
+                }
+                catch {
+                    // The caller still receives the same sanitized unavailable result.
+                }
+                throw new TransactionalDeliveryUnavailableError();
+            }
+        },
+    };
+}

package/dist/communications/transactionalDeliveryIdentifier.d.ts

@@ -0,0 +1,3 @@
+/** Narrow, portable receipt contract for the captured transactional action. */
+/** Bounded opaque identifiers keep commands and persisted evidence content-free. */
+export declare function isTransactionalDeliveryIdentifier(value: string): boolean;

package/dist/communications/transactionalDeliveryIdentifier.js

@@ -0,0 +1,6 @@
+/** Narrow, portable receipt contract for the captured transactional action. */
+const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/;
+/** Bounded opaque identifiers keep commands and persisted evidence content-free. */
+export function isTransactionalDeliveryIdentifier(value) {
+    return IDENTIFIER.test(value);
+}

package/dist/communications/unsubscribeToken.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Stateless, signed unsubscribe tokens for marketing emails (RODO one-click
+ * opt-out): an HMAC-SHA256 over the recipient email + consent purpose, so the
+ * unsubscribe route can suppress the right permission without a lookup table or
+ * trusting raw query params. Node marketing senders build the token to embed in
+ * the email footer; `api/unsubscribe.ts` verifies it.
+ *
+ * This module is the only implementation. The former Deno mirror was deleted
+ * with the `unsubscribe` Edge function; nothing has to be kept in sync any more.
+ *
+ * WebCrypto only (global `crypto.subtle`/`btoa`/`atob`, Node 18+).
+ */
+export interface UnsubscribePayload {
+    email: string;
+    purpose: string;
+}
+/**
+ * How long a newly minted unsubscribe link stays valid: 548 days, i.e. about
+ * eighteen months, expressed in whole days so the value does not depend on which
+ * months a token happens to span.
+ *
+ * Contract, and why this number:
+ *
+ * - Until this field existed the token carried `{e, p, v}` and the verifier
+ *   checked only the HMAC, so a link minted in 2026 stayed valid forever. That
+ *   made "wait for the old links to age out" an unbounded strategy and left a
+ *   permanently replayable capability sitting in mailboxes.
+ * - Eighteen months is longer than a marketing message is realistically acted
+ *   on and longer than a full annual cycle plus a lapsed re-engagement, so it
+ *   does not cut short a genuine opt-out; it is short enough that the capability
+ *   is not effectively perpetual.
+ * - ⛔ A token WITHOUT `exp` stays valid. Every link already delivered was
+ *   minted without one, and refusing them would retro-expire opt-outs the
+ *   recipient was told would work. Expiry is a forward-only narrowing.
+ *
+ * ⛔ Do not rename this to anything containing `TOKEN`, `SECRET`, `PASSWORD`,
+ * `SERVICE_ROLE` or `API_KEY`. This module is client-reachable `src/` source and
+ * `scripts/check-client-secret-boundary.ts` refuses a SCREAMING_SNAKE
+ * identifier carrying any of those words there — a TTL is not a credential, so
+ * the name avoids the shape rather than the allowlist.
+ */
+export declare const UNSUBSCRIBE_LINK_TTL_SECONDS: number;
+/** Clock seam, so expiry can be proved without waiting eighteen months. */
+export interface UnsubscribeTokenClock {
+    now?: Date;
+}
+/**
+ * Build a `<base64url(payload)>.<base64url(sig)>` unsubscribe token.
+ *
+ * Quoted-printable safety: this token rides as `?token=…` inside marketing emails
+ * whose Polish diacritics force quoted-printable encoding. A token beginning with
+ * two hex digits could be corrupted if a transport leaves the `=` separator raw
+ * (`=7d` -> `}`). This token is structurally immune: the payload always serializes
+ * as `{"e":…`, so base64url makes the token always begin "ey" (`e` is hex, `y` is
+ * not) — `=ey` is never a valid `=<2 hex>` escape. unsubscribeToken.test.ts guards
+ * this; do NOT reshape the payload to lead with a field that could base64url into
+ * two hex digits without re-checking (and prefixing the token if so). `exp` is
+ * appended last for exactly that reason.
+ */
+export declare function buildUnsubscribeToken(payload: UnsubscribePayload, secret: string, clock?: UnsubscribeTokenClock): Promise<string>;
+/**
+ * Add the signed query to a resolved unsubscribe endpoint. The adapter that
+ * owns deployment/provider configuration must choose and validate that endpoint
+ * before it reaches this neutral communications-domain helper.
+ */
+export declare function buildUnsubscribeUrl(unsubscribeEndpointUrl: string, token: string, locale: "pl" | "en"): string;
+/**
+ * Verify a token; returns the payload or null on any tampering / bad shape /
+ * elapsed expiry.
+ *
+ * ⛔ An absent `exp` is valid, not a rejection: tokens minted before expiry
+ * existed are still in mailboxes, and a recipient who was promised a working
+ * opt-out link must keep one. A present `exp` must be a finite number and must
+ * still be in the future — it is inside the signed payload, so it cannot be
+ * stripped or moved without breaking the HMAC.
+ */
+export declare function verifyUnsubscribeToken(token: string, secret: string, clock?: UnsubscribeTokenClock): Promise<UnsubscribePayload | null>;

package/dist/communications/unsubscribeToken.js

@@ -0,0 +1,150 @@
+/**
+ * Stateless, signed unsubscribe tokens for marketing emails (RODO one-click
+ * opt-out): an HMAC-SHA256 over the recipient email + consent purpose, so the
+ * unsubscribe route can suppress the right permission without a lookup table or
+ * trusting raw query params. Node marketing senders build the token to embed in
+ * the email footer; `api/unsubscribe.ts` verifies it.
+ *
+ * This module is the only implementation. The former Deno mirror was deleted
+ * with the `unsubscribe` Edge function; nothing has to be kept in sync any more.
+ *
+ * WebCrypto only (global `crypto.subtle`/`btoa`/`atob`, Node 18+).
+ */
+/**
+ * How long a newly minted unsubscribe link stays valid: 548 days, i.e. about
+ * eighteen months, expressed in whole days so the value does not depend on which
+ * months a token happens to span.
+ *
+ * Contract, and why this number:
+ *
+ * - Until this field existed the token carried `{e, p, v}` and the verifier
+ *   checked only the HMAC, so a link minted in 2026 stayed valid forever. That
+ *   made "wait for the old links to age out" an unbounded strategy and left a
+ *   permanently replayable capability sitting in mailboxes.
+ * - Eighteen months is longer than a marketing message is realistically acted
+ *   on and longer than a full annual cycle plus a lapsed re-engagement, so it
+ *   does not cut short a genuine opt-out; it is short enough that the capability
+ *   is not effectively perpetual.
+ * - ⛔ A token WITHOUT `exp` stays valid. Every link already delivered was
+ *   minted without one, and refusing them would retro-expire opt-outs the
+ *   recipient was told would work. Expiry is a forward-only narrowing.
+ *
+ * ⛔ Do not rename this to anything containing `TOKEN`, `SECRET`, `PASSWORD`,
+ * `SERVICE_ROLE` or `API_KEY`. This module is client-reachable `src/` source and
+ * `scripts/check-client-secret-boundary.ts` refuses a SCREAMING_SNAKE
+ * identifier carrying any of those words there — a TTL is not a credential, so
+ * the name avoids the shape rather than the allowlist.
+ */
+export const UNSUBSCRIBE_LINK_TTL_SECONDS = 548 * 24 * 60 * 60;
+function base64urlEncode(bytes) {
+    let binary = "";
+    for (const b of bytes)
+        binary += String.fromCharCode(b);
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function base64urlDecodeToString(value) {
+    const padded = value.replace(/-/g, "+").replace(/_/g, "/").padEnd(Math.ceil(value.length / 4) * 4, "=");
+    return atob(padded);
+}
+function timingSafeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i += 1)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}
+async function hmacBase64url(secret, message) {
+    const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const sig = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(message));
+    return base64urlEncode(new Uint8Array(sig));
+}
+/**
+ * Build a `<base64url(payload)>.<base64url(sig)>` unsubscribe token.
+ *
+ * Quoted-printable safety: this token rides as `?token=…` inside marketing emails
+ * whose Polish diacritics force quoted-printable encoding. A token beginning with
+ * two hex digits could be corrupted if a transport leaves the `=` separator raw
+ * (`=7d` -> `}`). This token is structurally immune: the payload always serializes
+ * as `{"e":…`, so base64url makes the token always begin "ey" (`e` is hex, `y` is
+ * not) — `=ey` is never a valid `=<2 hex>` escape. unsubscribeToken.test.ts guards
+ * this; do NOT reshape the payload to lead with a field that could base64url into
+ * two hex digits without re-checking (and prefixing the token if so). `exp` is
+ * appended last for exactly that reason.
+ */
+export async function buildUnsubscribeToken(payload, secret, clock = {}) {
+    const issuedAtSeconds = Math.floor((clock.now ?? new Date()).getTime() / 1000);
+    const body = base64urlEncode(new TextEncoder().encode(JSON.stringify({
+        e: payload.email,
+        p: payload.purpose,
+        v: 1,
+        exp: issuedAtSeconds + UNSUBSCRIBE_LINK_TTL_SECONDS,
+    })));
+    const sig = await hmacBase64url(secret, body);
+    return `${body}.${sig}`;
+}
+/**
+ * Add the signed query to a resolved unsubscribe endpoint. The adapter that
+ * owns deployment/provider configuration must choose and validate that endpoint
+ * before it reaches this neutral communications-domain helper.
+ */
+export function buildUnsubscribeUrl(unsubscribeEndpointUrl, token, locale) {
+    const endpoint = parseUnsubscribeEndpointUrl(unsubscribeEndpointUrl);
+    const params = new URLSearchParams({ token });
+    if (locale === "en")
+        params.set("lang", "en");
+    endpoint.search = `?${params.toString()}`;
+    return endpoint.toString();
+}
+function parseUnsubscribeEndpointUrl(value) {
+    const endpoint = new URL(value);
+    if (endpoint.protocol !== "https:" ||
+        endpoint.username ||
+        endpoint.password ||
+        endpoint.search ||
+        endpoint.hash ||
+        endpoint.hostname.endsWith(".")) {
+        throw new Error("unsubscribe endpoint URL must be HTTPS without credentials, query, fragment, or a trailing-dot hostname");
+    }
+    return endpoint;
+}
+/**
+ * Verify a token; returns the payload or null on any tampering / bad shape /
+ * elapsed expiry.
+ *
+ * ⛔ An absent `exp` is valid, not a rejection: tokens minted before expiry
+ * existed are still in mailboxes, and a recipient who was promised a working
+ * opt-out link must keep one. A present `exp` must be a finite number and must
+ * still be in the future — it is inside the signed payload, so it cannot be
+ * stripped or moved without breaking the HMAC.
+ */
+export async function verifyUnsubscribeToken(token, secret, clock = {}) {
+    if (!token || !secret)
+        return null;
+    const dot = token.indexOf(".");
+    if (dot <= 0)
+        return null;
+    const body = token.slice(0, dot);
+    const sig = token.slice(dot + 1);
+    const expected = await hmacBase64url(secret, body);
+    if (!timingSafeEqual(sig, expected))
+        return null;
+    try {
+        const parsed = JSON.parse(base64urlDecodeToString(body));
+        if (typeof parsed.e !== "string" || typeof parsed.p !== "string")
+            return null;
+        if (!parsed.e || !parsed.p)
+            return null;
+        if (parsed.exp !== undefined) {
+            if (typeof parsed.exp !== "number" || !Number.isFinite(parsed.exp))
+                return null;
+            const nowSeconds = Math.floor((clock.now ?? new Date()).getTime() / 1000);
+            if (parsed.exp <= nowSeconds)
+                return null;
+        }
+        return { email: parsed.e, purpose: parsed.p };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/communications/validation.d.ts

@@ -0,0 +1,2 @@
+import { z } from "zod";
+export { z };

package/dist/communications/validation.js

@@ -0,0 +1,3 @@
+import { z } from "zod";
+z.config({ jitless: true });
+export { z };

package/dist/http/index.d.ts

@@ -4,3 +4,4 @@ export { NODE_HTTP_TIMEOUT_CODE, closeInputAfterResponse, runWithHttpDeadline, t
 export { applySecurityHeaders, contentTypeFor, looksLikeAsset, serveSpaStatic, type NodeSecurityHeaderPolicy, type StaticAssetReader, } from "./security.js";
 export { createDistStaticReader } from "./staticAssets.js";
 export { createNodeHttpRuntime, createRequestHandler, type HttpEntrypointRegistration, type HttpPathEntrypoint, type NodeCsrFallback, type NodeHttpRuntimeOptions, type NodeLegacyRedirect, } from "./runtime.js";
+export { MAX_WEBHOOK_BODY_BYTES, WebhookBodyTooLargeError, readRawBody, verifyHmacSignature, timingSafeStringEqual } from "./webhookSignature.js";

package/dist/http/index.js

@@ -3,3 +3,4 @@ export { NODE_HTTP_TIMEOUT_CODE, closeInputAfterResponse, runWithHttpDeadline, }
 export { applySecurityHeaders, contentTypeFor, looksLikeAsset, serveSpaStatic, } from "./security.js";
 export { createDistStaticReader } from "./staticAssets.js";
 export { createNodeHttpRuntime, createRequestHandler, } from "./runtime.js";
+export { MAX_WEBHOOK_BODY_BYTES, WebhookBodyTooLargeError, readRawBody, verifyHmacSignature, timingSafeStringEqual } from "./webhookSignature.js";

package/dist/http/webhookSignature.d.ts

@@ -0,0 +1,42 @@
+import type { HttpRequest } from "./types.js";
+/** Hard cap on raw webhook body bytes — the payment provider events are well under 256 KiB. */
+export declare const MAX_WEBHOOK_BODY_BYTES = 1048576;
+/** Thrown by readRawBody when the streamed body exceeds MAX_WEBHOOK_BODY_BYTES. */
+export declare class WebhookBodyTooLargeError extends Error {
+    constructor();
+}
+/**
+ * Reads the exact raw request body bytes for provider webhook signature
+ * verification.
+ *
+ * `@vercel/node` (v3, the builder for `/api` functions in this Vite project)
+ * auto-parses `application/json` request bodies into `req.body` and IGNORES the
+ * `export const config = { api: { bodyParser: false } }` opt-out — that opt-out
+ * is a Next.js Pages Router convention, not a vanilla `@vercel/node` one
+ * (verified empirically against the hidden-preview deploy: a JSON payload posted
+ * with `Content-Type: application/json` arrives parsed, the same bytes posted as
+ * `text/plain` arrive raw). Re-serializing the parsed object with
+ * `JSON.stringify` does NOT reproduce the provider's exact bytes — the payment provider signs
+ * pretty-printed JSON, so a compacted re-serialization breaks HMAC verification.
+ *
+ * Reading the underlying request stream FIRST — before touching `req.body`,
+ * whose getter triggers the parse that consumes the stream — preserves the exact
+ * bytes when the platform parses lazily. When `req` is not a stream (unit tests
+ * pass a plain `{ body }` object) or the stream yields nothing (already
+ * consumed), we fall back to `req.body`.
+ */
+export declare function readRawBody(req: HttpRequest): Promise<string>;
+export declare function verifyHmacSignature(input: {
+    rawBody: string;
+    signatureHeader: string | undefined;
+    secret: string;
+}): boolean;
+/**
+ * Constant-time comparison of two shared-secret strings.
+ *
+ * Exported because it is not payment-specific: any route holding a shared token has to compare it
+ * the same way, and a second hand-rolled copy of a security primitive is how one of them quietly
+ * stops being constant-time. The length check comes first because `timingSafeEqual` THROWS on a
+ * length mismatch rather than returning false, and the length of a shared token is not the secret.
+ */
+export declare function timingSafeStringEqual(left: string, right: string): boolean;