commitrail 0.1.0-alpha.0

package/dist/esm/signing.js

@@ -0,0 +1,101 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+/**
+ * The canonical string a signature covers.
+ *
+ * Consumers reimplement this, so its exact shape matters far less than documenting it
+ * precisely — but it must include the delivery id, so that a captured body cannot be
+ * replayed as a different obligation.
+ */
+export function canonicalPayload(input) {
+    return `${input.timestamp}.${input.deliveryId}.${input.body}`;
+}
+/**
+ * The same thing, as bytes, for a caller who has the raw body and has not decoded it.
+ *
+ * A signature is over bytes. Decoding to a string and re-encoding round-trips exactly for the
+ * valid UTF-8 that JSON must be, so the two agree — but making the caller decode first asks them
+ * to do something the contract does not need, and `.toString()` with a forgotten or wrong
+ * encoding is a real way to break verification for reasons nobody can see.
+ *
+ * Returns `Uint8Array` rather than `Buffer` deliberately: a `Buffer` in a published `.d.ts` makes
+ * `@types/node` a requirement to compile against this package, which a library has no business
+ * imposing. The packaging gate caught that, which is what it is for.
+ */
+export function canonicalPayloadBytes(input) {
+    return Buffer.concat([
+        Buffer.from(`${input.timestamp}.${input.deliveryId}.`, 'utf8'),
+        Buffer.from(input.body.buffer, input.body.byteOffset, input.body.byteLength),
+    ]);
+}
+export function sign(secret, canonical) {
+    return createHmac('sha256', secret).update(canonical).digest('hex');
+}
+/**
+ * Build the `CommitRail-Signature` header.
+ *
+ * During a rotation this carries a signature under each secret, so a consumer's
+ * verification is "does one of these match mine". That code never has to know about
+ * versions and never changes shape when a secret rotates — which matters more than
+ * elegance for something that gets pasted into middleware once and left there.
+ */
+export function signatureHeader(input) {
+    const canonical = canonicalPayload(input);
+    const signatures = [input.material.current, input.material.previous]
+        .filter((s) => s !== undefined)
+        .map((s) => `v1=${sign(s.secret, canonical)}`);
+    return [`t=${input.timestamp}`, ...signatures].join(',');
+}
+/**
+ * Verify a header the way a consumer would. Exists so the contract we publish is the one
+ * we test against, rather than a description of it.
+ */
+export function verifySignatureHeader(input) {
+    const tolerance = input.toleranceSeconds ?? 300;
+    const now = input.now ?? Math.floor(Date.now() / 1000);
+    const parts = input.header.split(',').map((p) => p.trim());
+    const timestampPart = parts.find((p) => p.startsWith('t='));
+    if (timestampPart === undefined) {
+        return false;
+    }
+    const timestamp = parseTimestamp(timestampPart.slice(2));
+    // Bounds replay. A signature stays valid forever otherwise, and a captured request could
+    // be resent indefinitely. The bound is inclusive and symmetric: a delivery exactly `tolerance`
+    // seconds either side of now is accepted.
+    if (timestamp === undefined || Math.abs(now - timestamp) > tolerance) {
+        return false;
+    }
+    const expected = sign(input.secret, typeof input.body === 'string'
+        ? canonicalPayload({ timestamp, deliveryId: input.deliveryId, body: input.body })
+        : canonicalPayloadBytes({ timestamp, deliveryId: input.deliveryId, body: input.body }));
+    return parts
+        .filter((p) => p.startsWith('v1='))
+        .some((p) => equalsConstantTime(p.slice(3), expected));
+}
+function equalsConstantTime(a, b) {
+    const left = Buffer.from(a, 'utf8');
+    const right = Buffer.from(b, 'utf8');
+    // Length must be compared first — timingSafeEqual throws on a mismatch — and leaking the
+    // length of a hex digest tells an attacker nothing.
+    return left.length === right.length && timingSafeEqual(left, right);
+}
+/**
+ * The `t=` value, parsed strictly.
+ *
+ * `Number.parseInt` is lenient: it reads `1787000000.5` and `1787000000junk` as 1787000000, so
+ * three different header strings would verify against one signature. Harmless on its own — the
+ * signature is computed over the parsed integer, so nothing about the body or the window changes
+ * — but it is a divergence, and divergence is the thing this protocol cannot afford. A verifier
+ * written from PROTOCOL.md with a strict integer parse would reject what this one accepts, and
+ * the customer would meet the difference in production.
+ *
+ * Digits only. A negative timestamp is refused here rather than by the tolerance check, which
+ * makes the rule one sentence instead of two.
+ */
+function parseTimestamp(value) {
+    if (!/^\d+$/.test(value)) {
+        return undefined;
+    }
+    const parsed = Number.parseInt(value, 10);
+    return Number.isSafeInteger(parsed) ? parsed : undefined;
+}
+//# sourceMappingURL=signing.js.map

package/dist/esm/signing.js.map

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

package/dist/esm/subjects.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Subjects: the business identities an event concerns.
+ *
+ * A subject is not what happened (the event type), not the operation it belongs to (the
+ * correlation id), and not what caused it (the causation id) — it is *who or what it was
+ * about*: an order, a payment, a customer, a document. Declaring them makes those
+ * identifiers first-class lookup keys in CommitRail, so an investigation can start from
+ * "what happened to order_1264" rather than from an event id nobody has.
+ *
+ * Subjects are an unordered set of `(type, id)` pairs. Plural on purpose: a
+ * `payment.captured` legitimately concerns the payment, the order and the customer, and
+ * CommitRail has no business deciding which of them is *the* subject.
+ */
+export interface EventSubject {
+    /** The kind of thing, in the application's own vocabulary: `order`, `payment`, `customer`. */
+    type: string;
+    /** The application's identifier for it: `order_1264`, `pay_991`. */
+    id: string;
+}
+/**
+ * Sized so normal business modelling never meets them; they exist to stop pathological
+ * usage, not to ration subjects. The evidence behind each number — measured throughput,
+ * storage and lookup curves, and what still needs re-measuring at production scale —
+ * is docs/benchmarks/event-subjects-limits.md; change them there first.
+ */
+export declare const SUBJECT_LIMITS: {
+    readonly maxPerEvent: 100;
+    readonly maxTypeLength: 200;
+    readonly maxIdLength: 500;
+};
+/** Registered globally by description, so every copy of this package agrees on it. */
+declare const BRAND: unique symbol;
+/** Branded like `InvalidDeliveryError`, and for the same dual-package reason. */
+export declare class InvalidSubjectsError extends Error {
+    static readonly brand: symbol;
+    readonly [BRAND] = true;
+    constructor(message: string);
+    static is(error: unknown): error is InvalidSubjectsError;
+}
+/**
+ * Validate and canonicalise a subjects value.
+ *
+ * Returns `null` for "no subjects" (undefined, null, or an empty array) so callers store
+ * nothing rather than an empty list. Exact duplicate `(type, id)` pairs are dropped —
+ * duplicates carry no meaning, and producers often assemble subjects from more than one
+ * code path — with first-occurrence order preserved. Anything malformed throws: a subject
+ * that cannot be represented is an error at the boundary, never a silent truncation.
+ *
+ * Takes `unknown` because the acceptance side re-validates whatever a producer actually
+ * wrote to the outbox, which no type annotation can vouch for.
+ */
+export declare function normalizeSubjects(subjects: unknown): EventSubject[] | null;
+export {};

package/dist/esm/subjects.js

@@ -0,0 +1,83 @@
+/**
+ * Sized so normal business modelling never meets them; they exist to stop pathological
+ * usage, not to ration subjects. The evidence behind each number — measured throughput,
+ * storage and lookup curves, and what still needs re-measuring at production scale —
+ * is docs/benchmarks/event-subjects-limits.md; change them there first.
+ */
+export const SUBJECT_LIMITS = {
+    maxPerEvent: 100,
+    maxTypeLength: 200,
+    maxIdLength: 500,
+};
+/** Registered globally by description, so every copy of this package agrees on it. */
+const BRAND = Symbol.for('commitrail.InvalidSubjectsError');
+/** Branded like `InvalidDeliveryError`, and for the same dual-package reason. */
+export class InvalidSubjectsError extends Error {
+    static brand = BRAND;
+    [BRAND] = true;
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidSubjectsError';
+    }
+    static is(error) {
+        return (typeof error === 'object' &&
+            error !== null &&
+            error[BRAND] === true);
+    }
+}
+/**
+ * Validate and canonicalise a subjects value.
+ *
+ * Returns `null` for "no subjects" (undefined, null, or an empty array) so callers store
+ * nothing rather than an empty list. Exact duplicate `(type, id)` pairs are dropped —
+ * duplicates carry no meaning, and producers often assemble subjects from more than one
+ * code path — with first-occurrence order preserved. Anything malformed throws: a subject
+ * that cannot be represented is an error at the boundary, never a silent truncation.
+ *
+ * Takes `unknown` because the acceptance side re-validates whatever a producer actually
+ * wrote to the outbox, which no type annotation can vouch for.
+ */
+export function normalizeSubjects(subjects) {
+    if (subjects === undefined || subjects === null) {
+        return null;
+    }
+    if (!Array.isArray(subjects)) {
+        throw new InvalidSubjectsError('subjects must be an array of { type, id } pairs');
+    }
+    const seen = new Set();
+    const normalized = [];
+    for (const subject of subjects) {
+        if (typeof subject !== 'object' || subject === null || Array.isArray(subject)) {
+            throw new InvalidSubjectsError('each subject must be an object with string type and id');
+        }
+        const { type, id } = subject;
+        if (typeof type !== 'string' || type.length === 0) {
+            throw new InvalidSubjectsError('a subject type must be a non-empty string');
+        }
+        if (typeof id !== 'string' || id.length === 0) {
+            throw new InvalidSubjectsError('a subject id must be a non-empty string');
+        }
+        if (type.length > SUBJECT_LIMITS.maxTypeLength) {
+            throw new InvalidSubjectsError(`a subject type may be at most ${SUBJECT_LIMITS.maxTypeLength} characters`);
+        }
+        if (id.length > SUBJECT_LIMITS.maxIdLength) {
+            throw new InvalidSubjectsError(`a subject id may be at most ${SUBJECT_LIMITS.maxIdLength} characters`);
+        }
+        // A joining delimiter cannot be trusted when it may appear in the values themselves;
+        // length-prefixing makes the key unambiguous whatever the strings contain.
+        const key = `${type.length}:${type}${id}`;
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        normalized.push({ type, id });
+    }
+    if (normalized.length === 0) {
+        return null;
+    }
+    if (normalized.length > SUBJECT_LIMITS.maxPerEvent) {
+        throw new InvalidSubjectsError(`an event may declare at most ${SUBJECT_LIMITS.maxPerEvent} subjects`);
+    }
+    return normalized;
+}
+//# sourceMappingURL=subjects.js.map

package/dist/esm/subjects.js.map

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

package/dist/esm/webhooks.d.ts

@@ -0,0 +1,100 @@
+import { type CommitRailEvent } from './envelope.js';
+/** Registered globally by description, so every copy of this package agrees on it. */
+declare const BRAND: unique symbol;
+/**
+ * How much clock skew is tolerated by default, in seconds.
+ *
+ * Five minutes. It bounds replay: without it a captured request stays valid forever. Too tight
+ * and ordinary clock drift between two correct machines starts rejecting real deliveries.
+ */
+export declare const DEFAULT_TOLERANCE_SECONDS = 300;
+/** Why a delivery was rejected. Stable values — new ones may be added. */
+export type InvalidDeliveryCode = 'missing_signature' | 'missing_delivery_id'
+/** The signature header could not be parsed at all. */
+ | 'malformed_signature'
+/** The signature was well formed but the timestamp is outside your tolerance. */
+ | 'timestamp_out_of_range'
+/** The signature did not match: the wrong secret, or a body altered after signing. */
+ | 'signature_mismatch' | 'malformed_body'
+/** A header CommitRail sent disagrees with the signed envelope. */
+ | 'header_mismatch';
+/**
+ * A delivery that could not be trusted.
+ *
+ * `error instanceof InvalidDeliveryError` is the ordinary way to catch this and works in
+ * every normal application. It can fail in one specific case, and the case is created by
+ * this package being dual-published: an application that both `import`s and `require()`s
+ * `commitrail` loads two copies, with two distinct classes, and an error thrown by one
+ * is not an `instanceof` the other. `InvalidDeliveryError.is(error)` checks a shared
+ * symbol instead and is true across copies.
+ */
+export declare class InvalidDeliveryError extends Error {
+    static readonly brand: symbol;
+    readonly [BRAND] = true;
+    /**
+     * Which check failed, for your logs.
+     *
+     * The message stays deliberately vague about *why* a signature did not verify, because the
+     * most common mistake is echoing it to the caller — and a wrong secret, a stale timestamp and
+     * a tampered body are three very different hints to hand an attacker. The code exists so your
+     * own logs do not have to be as careful as your responses.
+     *
+     * The distinction that matters in practice: `signature_invalid` after a deploy is almost
+     * always the wrong secret, and `malformed_body` is almost always a framework that parsed and
+     * re-serialised the body instead of giving you the bytes that were signed.
+     *
+     * Return a bare 400 or 401 to the caller. Log the code.
+     */
+    readonly code: InvalidDeliveryCode;
+    constructor(code: InvalidDeliveryCode, reason: string);
+    static is(error: unknown): error is InvalidDeliveryError;
+}
+export interface VerifyRequestInput {
+    /** Request headers, however your framework exposes them. Case-insensitive. */
+    headers: Record<string, string | string[] | undefined>;
+    /**
+     * The RAW request body, exactly as received.
+     *
+     * Not a parsed object re-serialised: `JSON.stringify` of a parsed body can differ from
+     * the bytes that were signed — key order, number formatting, whitespace — and the
+     * signature would fail for no reason a reader could see. Most frameworks need to be told
+     * to keep the raw body.
+     *
+     * Bytes are preferred, because a signature is over bytes: hand Express its `Buffer` or a
+     * `Uint8Array` straight through rather than calling `.toString()`, which is one more place to
+     * pick the wrong encoding. A string is accepted and equivalent — JSON is UTF-8, which
+     * round-trips exactly.
+     */
+    body: string | Uint8Array;
+    secret: string;
+    /** How much clock skew to tolerate, in seconds. Defaults to five minutes. */
+    toleranceSeconds?: number;
+}
+/**
+ * Verify a delivery and return its event.
+ *
+ * Throws rather than returning false, so a handler that forgets to check the result still
+ * fails closed.
+ *
+ * ```ts
+ * app.post('/webhooks/commitrail', async (request, reply) => {
+ *   const event = verifyRequest({
+ *     headers: request.headers,
+ *     body: request.rawBody,
+ *     secret: process.env.COMMITRAIL_SIGNING_SECRET!,
+ *   });
+ *
+ *   if (await alreadyProcessed(event.delivery.id)) return reply.code(200).send();
+ *
+ *   await handle(event);
+ *   await recordProcessed(event.delivery.id);
+ *   return reply.code(200).send();
+ * });
+ * ```
+ *
+ * The deduplication is not decoration. Delivery is at-least-once: a timeout or a dropped
+ * connection means CommitRail never learned whether you processed the event, and it will
+ * try again.
+ */
+export declare function verifyRequest<TData = unknown>(input: VerifyRequestInput): CommitRailEvent<TData>;
+export {};

package/dist/esm/webhooks.js

@@ -0,0 +1,209 @@
+import { HEADERS } from './envelope.js';
+import { verifySignatureHeader } from './signing.js';
+/** Registered globally by description, so every copy of this package agrees on it. */
+const BRAND = Symbol.for('commitrail.InvalidDeliveryError');
+/**
+ * How much clock skew is tolerated by default, in seconds.
+ *
+ * Five minutes. It bounds replay: without it a captured request stays valid forever. Too tight
+ * and ordinary clock drift between two correct machines starts rejecting real deliveries.
+ */
+export const DEFAULT_TOLERANCE_SECONDS = 300;
+/**
+ * A delivery that could not be trusted.
+ *
+ * `error instanceof InvalidDeliveryError` is the ordinary way to catch this and works in
+ * every normal application. It can fail in one specific case, and the case is created by
+ * this package being dual-published: an application that both `import`s and `require()`s
+ * `commitrail` loads two copies, with two distinct classes, and an error thrown by one
+ * is not an `instanceof` the other. `InvalidDeliveryError.is(error)` checks a shared
+ * symbol instead and is true across copies.
+ */
+export class InvalidDeliveryError extends Error {
+    static brand = BRAND;
+    [BRAND] = true;
+    /**
+     * Which check failed, for your logs.
+     *
+     * The message stays deliberately vague about *why* a signature did not verify, because the
+     * most common mistake is echoing it to the caller — and a wrong secret, a stale timestamp and
+     * a tampered body are three very different hints to hand an attacker. The code exists so your
+     * own logs do not have to be as careful as your responses.
+     *
+     * The distinction that matters in practice: `signature_invalid` after a deploy is almost
+     * always the wrong secret, and `malformed_body` is almost always a framework that parsed and
+     * re-serialised the body instead of giving you the bytes that were signed.
+     *
+     * Return a bare 400 or 401 to the caller. Log the code.
+     */
+    code;
+    constructor(code, reason) {
+        super(`CommitRail delivery rejected: ${reason}`);
+        this.name = 'InvalidDeliveryError';
+        this.code = code;
+    }
+    static is(error) {
+        return (typeof error === 'object' &&
+            error !== null &&
+            error[BRAND] === true);
+    }
+}
+/**
+ * Verify a delivery and return its event.
+ *
+ * Throws rather than returning false, so a handler that forgets to check the result still
+ * fails closed.
+ *
+ * ```ts
+ * app.post('/webhooks/commitrail', async (request, reply) => {
+ *   const event = verifyRequest({
+ *     headers: request.headers,
+ *     body: request.rawBody,
+ *     secret: process.env.COMMITRAIL_SIGNING_SECRET!,
+ *   });
+ *
+ *   if (await alreadyProcessed(event.delivery.id)) return reply.code(200).send();
+ *
+ *   await handle(event);
+ *   await recordProcessed(event.delivery.id);
+ *   return reply.code(200).send();
+ * });
+ * ```
+ *
+ * The deduplication is not decoration. Delivery is at-least-once: a timeout or a dropped
+ * connection means CommitRail never learned whether you processed the event, and it will
+ * try again.
+ */
+export function verifyRequest(input) {
+    const signature = header(input.headers, HEADERS.signature);
+    const deliveryId = header(input.headers, HEADERS.deliveryId);
+    if (signature === undefined) {
+        throw new InvalidDeliveryError('missing_signature', 'no signature header');
+    }
+    if (deliveryId === undefined) {
+        throw new InvalidDeliveryError('missing_delivery_id', 'no delivery id header');
+    }
+    /**
+     * The timestamp first, and separately, so the code can say which it was.
+     *
+     * One *message* for every cryptographic failure is right: the common mistake is echoing it to
+     * the caller, and "your clock is wrong" versus "your secret is wrong" are different hints to
+     * hand an attacker. That argument does not extend to a field you have to read deliberately —
+     * and these are the two an integrator most needs to tell apart, because a stale timestamp
+     * during setup is a clock problem and a mismatch is a secret or a raw-body problem, and they
+     * are fixed in completely different places.
+     */
+    const tolerance = input.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS;
+    const timestamp = signedTimestamp(signature);
+    if (timestamp === undefined) {
+        throw new InvalidDeliveryError('malformed_signature', 'signature did not verify');
+    }
+    if (Math.abs(Math.floor(Date.now() / 1000) - timestamp) > tolerance) {
+        throw new InvalidDeliveryError('timestamp_out_of_range', 'signature did not verify');
+    }
+    const valid = verifySignatureHeader({
+        header: signature,
+        secret: input.secret,
+        deliveryId,
+        body: input.body,
+        toleranceSeconds: tolerance,
+    });
+    if (!valid) {
+        throw new InvalidDeliveryError('signature_mismatch', 'signature did not verify');
+    }
+    let event;
+    try {
+        event = JSON.parse(typeof input.body === 'string' ? input.body : Buffer.from(input.body).toString('utf8'));
+    }
+    catch {
+        throw new InvalidDeliveryError('malformed_body', 'body was not valid JSON');
+    }
+    // Before touching a member of it. `JSON.parse('null')` is null and `null.delivery` is a
+    // TypeError, not an InvalidDeliveryError — so a handler doing `if (InvalidDeliveryError.is(e))`
+    // would miss it and rethrow, turning a rejected delivery into a 500. A verifier must never
+    // throw a type its caller has not been told about.
+    if (typeof event !== 'object' || event === null || Array.isArray(event)) {
+        throw new InvalidDeliveryError('malformed_body', 'the body is not a CommitRail envelope');
+    }
+    if (event.delivery?.id !== deliveryId) {
+        throw new InvalidDeliveryError('header_mismatch', 'delivery id in the body does not match the header');
+    }
+    assertHeadersAgree(input.headers, event, signature);
+    return event;
+}
+function header(headers, name) {
+    const direct = headers[name] ?? headers[name.toLowerCase()];
+    const value = Array.isArray(direct) ? direct[0] : direct;
+    if (value !== undefined) {
+        return value;
+    }
+    // Fall back to a case-insensitive scan for frameworks that preserve the original casing.
+    const match = Object.entries(headers).find(([key]) => key.toLowerCase() === name);
+    const found = match?.[1];
+    return Array.isArray(found) ? found[0] : found;
+}
+/**
+ * The envelope is signed. Most of the headers are not.
+ *
+ * `canonicalPayload` covers the timestamp, the delivery id and the body — so the body cannot be
+ * altered and the delivery id cannot be swapped. Everything else CommitRail sends is a
+ * convenience copy of something already inside the envelope, carried in a header so a consumer
+ * can route or log without parsing. Those copies are **not** covered by the signature.
+ *
+ * That matters because the obvious thing to do with `commitrail-idempotency-key` is deduplicate
+ * on it, and a value an attacker can edit is a poor thing to deduplicate on: replay a captured
+ * delivery with a fresh key and a consumer trusting the header processes it twice; send two
+ * genuine deliveries with one key and it drops one. Neither needs the signing secret.
+ *
+ * So every header that duplicates a signed field is checked against the envelope here, and the
+ * advice becomes true rather than merely stated: after `verifyRequest` returns, the headers
+ * agree with the envelope, and the envelope is what was signed.
+ *
+ * **Only a header that is present and disagrees is rejected.** An absent one is fine, and that is
+ * deliberate: CommitRail must stay free to stop sending a convenience header without every
+ * deployed verifier refusing the delivery. This is the same reasoning as `verifyRequest` never
+ * reading `specVersion` to decide anything — comparing two things CommitRail sent is not the same
+ * as requiring a particular version, and it must not quietly become that.
+ *
+ * `commitrail-attempt-id` is the one header with nothing in the envelope to check it against. It
+ * stays unauthenticated; do not make a decision on it.
+ */
+function assertHeadersAgree(headers, event, signature) {
+    const timestamp = signedTimestamp(signature);
+    const expected = [
+        [HEADERS.specVersion, event.specVersion],
+        [HEADERS.idempotencyKey, event.delivery?.id],
+        [HEADERS.eventId, event.id],
+        [HEADERS.eventType, event.type],
+        [HEADERS.attemptNumber, event.delivery?.attempt?.toString()],
+        [HEADERS.timestamp, timestamp?.toString()],
+    ];
+    for (const [name, value] of expected) {
+        const sent = header(headers, name);
+        if (sent !== undefined && sent !== value) {
+            // Named, because unlike a signature failure this one tells an attacker nothing they did
+            // not already choose — and it is the sort of thing a proxy causes by rewriting headers.
+            throw new InvalidDeliveryError('header_mismatch', `${name} does not match the signed envelope`);
+        }
+    }
+}
+/** The `t=` a signature header carries, which is authenticated: it is inside the signed string. */
+function signedTimestamp(header) {
+    const part = header
+        .split(',')
+        .map((p) => p.trim())
+        .find((p) => p.startsWith('t='));
+    if (part === undefined) {
+        return undefined;
+    }
+    const value = part.slice(2);
+    // Digits only, matching `verifySignatureHeader`. See the note on `parseTimestamp` there: a
+    // lenient parse means several header strings verify against one signature, and a verifier
+    // written from the specification would not agree with us about which.
+    if (!/^\d+$/.test(value)) {
+        return undefined;
+    }
+    const parsed = Number.parseInt(value, 10);
+    return Number.isSafeInteger(parsed) ? parsed : undefined;
+}
+//# sourceMappingURL=webhooks.js.map

package/dist/esm/webhooks.js.map

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