commitrail 0.1.0-alpha.0

package/dist/cjs/subjects.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvalidSubjectsError = exports.SUBJECT_LIMITS = void 0;
+exports.normalizeSubjects = normalizeSubjects;
+/**
+ * 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.
+ */
+exports.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. */
+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);
+    }
+}
+exports.InvalidSubjectsError = 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.
+ */
+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 > exports.SUBJECT_LIMITS.maxTypeLength) {
+            throw new InvalidSubjectsError(`a subject type may be at most ${exports.SUBJECT_LIMITS.maxTypeLength} characters`);
+        }
+        if (id.length > exports.SUBJECT_LIMITS.maxIdLength) {
+            throw new InvalidSubjectsError(`a subject id may be at most ${exports.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 > exports.SUBJECT_LIMITS.maxPerEvent) {
+        throw new InvalidSubjectsError(`an event may declare at most ${exports.SUBJECT_LIMITS.maxPerEvent} subjects`);
+    }
+    return normalized;
+}
+//# sourceMappingURL=subjects.js.map

package/dist/cjs/subjects.js.map

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

package/dist/cjs/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/cjs/webhooks.js

@@ -0,0 +1,214 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvalidDeliveryError = exports.DEFAULT_TOLERANCE_SECONDS = void 0;
+exports.verifyRequest = verifyRequest;
+const envelope_js_1 = require("./envelope.js");
+const signing_js_1 = require("./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.
+ */
+exports.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.
+ */
+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);
+    }
+}
+exports.InvalidDeliveryError = InvalidDeliveryError;
+/**
+ * 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.
+ */
+function verifyRequest(input) {
+    const signature = header(input.headers, envelope_js_1.HEADERS.signature);
+    const deliveryId = header(input.headers, envelope_js_1.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 ?? exports.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 = (0, signing_js_1.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 = [
+        [envelope_js_1.HEADERS.specVersion, event.specVersion],
+        [envelope_js_1.HEADERS.idempotencyKey, event.delivery?.id],
+        [envelope_js_1.HEADERS.eventId, event.id],
+        [envelope_js_1.HEADERS.eventType, event.type],
+        [envelope_js_1.HEADERS.attemptNumber, event.delivery?.attempt?.toString()],
+        [envelope_js_1.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/cjs/webhooks.js.map

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

package/dist/esm/envelope.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The wire contract.
+ *
+ * This package is the single definition of it. CommitRail signs and sends using exactly
+ * what customers import to receive and verify, so the two cannot drift — the same reason
+ * the control plane serialises through its route schemas rather than describing them
+ * separately.
+ */
+import type { EventSubject } from './subjects.js';
+export declare const SPEC_VERSION = "1";
+export interface CommitRailEvent<TData = unknown> {
+    specVersion: string;
+    /**
+     * The producer's own event identity, carried through untouched.
+     *
+     * Unique within its source, and not beyond it: a destination fed by two sources can see
+     * the same id from unrelated events. Deduplicate on `delivery.id`.
+     */
+    id: string;
+    type: string;
+    version: number;
+    /** When the event happened, as the producer recorded it. */
+    occurredAt: string;
+    /**
+     * The logical operation this event belongs to, and the event that caused it.
+     *
+     * Absent when the producer named neither — an absent member says "this event names no
+     * operation" more clearly than a null does. Put the same `correlationId` on whatever you
+     * emit in response and CommitRail joins the chain without being told anything else.
+     */
+    correlationId?: string;
+    causationId?: string;
+    /**
+     * The business identities the producer declared this event concerns.
+     *
+     * Absent when none were declared, for the same reason as the members above — and never
+     * inferred: these are exactly what the producer wrote, so a consumer can route or index
+     * on them with the same trust the producer's own code would get.
+     */
+    subjects?: EventSubject[];
+    delivery: {
+        /**
+         * The obligation this request is fulfilling, stable across every retry.
+         *
+         * **This is the idempotency key.** One event legitimately becomes two obligations when
+         * two routes point at the same destination, so deduplicating on `id` would silently
+         * drop the second.
+         */
+        id: string;
+        attempt: number;
+    };
+    data: TData;
+}
+/** Header names CommitRail sends. Lowercase, as Node normalises them. */
+export declare const HEADERS: {
+    readonly specVersion: "commitrail-spec-version";
+    readonly deliveryId: "commitrail-delivery-id";
+    readonly idempotencyKey: "commitrail-idempotency-key";
+    readonly attemptId: "commitrail-attempt-id";
+    readonly attemptNumber: "commitrail-attempt-number";
+    readonly eventId: "commitrail-event-id";
+    readonly eventType: "commitrail-event-type";
+    readonly timestamp: "commitrail-timestamp";
+    readonly signature: "commitrail-signature";
+};
+/**
+ * Serialise the wire envelope.
+ *
+ * Built by hand rather than with `JSON.stringify` on an object, for one reason: `data` is
+ * the customer's payload as PostgreSQL rendered it, and it must be spliced in as text.
+ * Parsing it to put it in an object would run it through `JSON.parse`, which is float64 and
+ * silently rewrites any integer past 2^53 — an order id of 12345678901234567890 came back
+ * as 12345678901234567000. See docs/defects.md.
+ *
+ * Every other member still goes through `JSON.stringify`, which is what escapes them. The
+ * field order is fixed and visible on purpose: these bytes are what gets signed, so the
+ * order is part of the contract rather than an implementation detail of an object literal.
+ */
+export declare function serialiseEnvelope(input: {
+    id: string;
+    type: string;
+    version: number;
+    occurredAt: string;
+    correlationId?: string | null;
+    causationId?: string | null;
+    subjects?: EventSubject[] | null;
+    deliveryId: string;
+    attempt: number;
+    /** JSON text. Never a parsed value — see the note above. */
+    data: string;
+}): string;

package/dist/esm/envelope.js

@@ -0,0 +1,50 @@
+export const SPEC_VERSION = '1';
+/** Header names CommitRail sends. Lowercase, as Node normalises them. */
+export const HEADERS = {
+    specVersion: 'commitrail-spec-version',
+    deliveryId: 'commitrail-delivery-id',
+    idempotencyKey: 'commitrail-idempotency-key',
+    attemptId: 'commitrail-attempt-id',
+    attemptNumber: 'commitrail-attempt-number',
+    eventId: 'commitrail-event-id',
+    eventType: 'commitrail-event-type',
+    timestamp: 'commitrail-timestamp',
+    signature: 'commitrail-signature',
+};
+/**
+ * Serialise the wire envelope.
+ *
+ * Built by hand rather than with `JSON.stringify` on an object, for one reason: `data` is
+ * the customer's payload as PostgreSQL rendered it, and it must be spliced in as text.
+ * Parsing it to put it in an object would run it through `JSON.parse`, which is float64 and
+ * silently rewrites any integer past 2^53 — an order id of 12345678901234567890 came back
+ * as 12345678901234567000. See docs/defects.md.
+ *
+ * Every other member still goes through `JSON.stringify`, which is what escapes them. The
+ * field order is fixed and visible on purpose: these bytes are what gets signed, so the
+ * order is part of the contract rather than an implementation detail of an object literal.
+ */
+export function serialiseEnvelope(input) {
+    // Omitted rather than sent as null, so the envelope keeps the shape it has always had for
+    // events that name no operation.
+    const optional = (name, value) => value === null || value === undefined ? '' : `"${name}":${JSON.stringify(value)},`;
+    return ('{' +
+        `"specVersion":${JSON.stringify(SPEC_VERSION)},` +
+        `"id":${JSON.stringify(input.id)},` +
+        `"type":${JSON.stringify(input.type)},` +
+        `"version":${JSON.stringify(input.version)},` +
+        `"occurredAt":${JSON.stringify(input.occurredAt)},` +
+        optional('correlationId', input.correlationId) +
+        optional('causationId', input.causationId) +
+        // A new member is added to the fixed order, never inserted into it: envelopes without
+        // subjects keep exactly the bytes they have always had, which is what lets deployed
+        // verifiers stay deployed. `JSON.stringify` of the array is safe — subjects are strings
+        // by contract, so there is no float64 hazard here, unlike `data`.
+        (input.subjects === null || input.subjects === undefined || input.subjects.length === 0
+            ? ''
+            : `"subjects":${JSON.stringify(input.subjects)},`) +
+        `"delivery":{"id":${JSON.stringify(input.deliveryId)},"attempt":${JSON.stringify(input.attempt)}},` +
+        `"data":${input.data}` +
+        '}');
+}
+//# sourceMappingURL=envelope.js.map

package/dist/esm/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../../src/envelope.ts"],"names":[],"mappings":"AAUA,MAAM,CAAC,MAAM,YAAY,GAAG,GAAG,CAAC;AAqDhC,yEAAyE;AACzE,MAAM,CAAC,MAAM,OAAO,GAAG;IACrB,WAAW,EAAE,yBAAyB;IACtC,UAAU,EAAE,wBAAwB;IACpC,cAAc,EAAE,4BAA4B;IAC5C,SAAS,EAAE,uBAAuB;IAClC,aAAa,EAAE,2BAA2B;IAC1C,OAAO,EAAE,qBAAqB;IAC9B,SAAS,EAAE,uBAAuB;IAClC,SAAS,EAAE,sBAAsB;IACjC,SAAS,EAAE,sBAAsB;CACzB,CAAC;AAEX;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAYjC;IACC,0FAA0F;IAC1F,iCAAiC;IACjC,MAAM,QAAQ,GAAG,CAAC,IAAY,EAAE,KAAgC,EAAE,EAAE,CAClE,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,KAAK,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC;IAErF,OAAO,CACL,GAAG;QACH,iBAAiB,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,GAAG;QAChD,QAAQ,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG;QACnC,UAAU,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG;QACvC,aAAa,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG;QAC7C,gBAAgB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG;QACnD,QAAQ,CAAC,eAAe,EAAE,KAAK,CAAC,aAAa,CAAC;QAC9C,QAAQ,CAAC,aAAa,EAAE,KAAK,CAAC,WAAW,CAAC;QAC1C,sFAAsF;QACtF,oFAAoF;QACpF,wFAAwF;QACxF,kEAAkE;QAClE,CAAC,KAAK,CAAC,QAAQ,KAAK,IAAI,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC;YACrF,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,cAAc,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC;QACpD,oBAAoB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,UAAU,CAAC,cAAc,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI;QACnG,UAAU,KAAK,CAAC,IAAI,EAAE;QACtB,GAAG,CACJ,CAAC;AACJ,CAAC"}

package/dist/esm/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The protocol, as a customer needs it.
+ *
+ * Everything here is something you use to integrate with CommitRail. Nothing is here because
+ * CommitRail's own server happens to need it: the server implements this same protocol from its
+ * own private code and imports nothing from this package, so the public surface is a decision
+ * about your integration rather than a projection of our internals.
+ *
+ * What that costs is the ability to say "we sign with exactly the function you verify with".
+ * What it buys is that every export here is one we intend to support, and the guarantee is kept
+ * where it can actually be kept for every language — by conformance vectors both implementations
+ * are tested against, and by end-to-end tests that verify what CommitRail sends using this
+ * verifier. A Go verifier could never have shared our functions either.
+ *
+ * Each side has a subpath of its own: `commitrail/postgres` produces, `commitrail/webhooks`
+ * receives, and neither is re-exported here.
+ */
+export { SPEC_VERSION, HEADERS, type CommitRailEvent } from './envelope.js';
+export { InvalidSubjectsError, SUBJECT_LIMITS, type EventSubject } from './subjects.js';
+export { verifySignatureHeader } from './signing.js';

package/dist/esm/index.js

@@ -0,0 +1,21 @@
+/**
+ * The protocol, as a customer needs it.
+ *
+ * Everything here is something you use to integrate with CommitRail. Nothing is here because
+ * CommitRail's own server happens to need it: the server implements this same protocol from its
+ * own private code and imports nothing from this package, so the public surface is a decision
+ * about your integration rather than a projection of our internals.
+ *
+ * What that costs is the ability to say "we sign with exactly the function you verify with".
+ * What it buys is that every export here is one we intend to support, and the guarantee is kept
+ * where it can actually be kept for every language — by conformance vectors both implementations
+ * are tested against, and by end-to-end tests that verify what CommitRail sends using this
+ * verifier. A Go verifier could never have shared our functions either.
+ *
+ * Each side has a subpath of its own: `commitrail/postgres` produces, `commitrail/webhooks`
+ * receives, and neither is re-exported here.
+ */
+export { SPEC_VERSION, HEADERS } from './envelope.js';
+export { InvalidSubjectsError, SUBJECT_LIMITS } from './subjects.js';
+export { verifySignatureHeader } from './signing.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,YAAY,EAAE,OAAO,EAAwB,MAAM,eAAe,CAAC;AAC5E,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAqB,MAAM,eAAe,CAAC;AACxF,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC"}

package/dist/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}