commitrail 0.1.0-alpha.0

package/dist/cjs/postgres.js

@@ -0,0 +1,373 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventIdConflictError = exports.OUTBOX_SCHEMA_SQL = exports.OUTBOX_SCHEMA_VERSION = exports.OUTBOX_MIGRATIONS = void 0;
+exports.emit = emit;
+exports.transaction = transaction;
+exports.fromPrisma = fromPrisma;
+const node_crypto_1 = require("node:crypto");
+const subjects_js_1 = require("./subjects.js");
+/** Registered globally by description, so every copy of this package agrees on it. */
+const CONFLICTING_EVENT_BRAND = Symbol.for('commitrail.EventIdConflictError');
+/**
+ * The outbox schema, as an append-only list of migrations.
+ *
+ * A list rather than one script, because the alternative already caused a problem. A single
+ * converge-to-latest constant changes when the package changes, so a customer who pasted it
+ * into `001_add_commitrail.sql` finds that migration meaning something different a year later
+ * — which is the one thing migrations exist not to do. Pinning a version instead gives them an
+ * immutable statement of what they applied.
+ *
+ * **Every entry here is frozen once released.** A released migration has run against databases
+ * we do not own and cannot re-run; editing one changes what a version *means* while leaving
+ * every already-migrated database untouched. Fix a mistake by appending, never by amending.
+ *
+ * Each is written to be safely re-runnable — `IF NOT EXISTS`, `ADD COLUMN IF NOT EXISTS` — so
+ * applying the whole list to any database converges it, whatever it started from.
+ */
+exports.OUTBOX_MIGRATIONS = [
+    {
+        version: 1,
+        sql: `
+CREATE SCHEMA IF NOT EXISTS commitrail;
+
+CREATE TABLE IF NOT EXISTS commitrail.outbox_events (
+    event_id UUID PRIMARY KEY,
+    source_sequence BIGINT GENERATED ALWAYS AS IDENTITY,
+    transaction_id xid8 NOT NULL DEFAULT pg_current_xact_id(),
+    event_type TEXT NOT NULL,
+    event_version INTEGER NOT NULL DEFAULT 1,
+    payload JSONB NOT NULL,
+
+    occurred_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+
+    -- Which logical operation this event belongs to, and which event caused it.
+    --
+    -- Supplied by the application or left null; CommitRail never infers either. Chronological
+    -- proximity is not causation, and a timeline drawn from a guess is worse than no timeline.
+    -- A null correlation groups with nothing rather than with every other null.
+    --
+    -- Text rather than uuid: a correlation is the customer's own identifier for a business
+    -- operation — an order number, a checkout id — and forcing it into a uuid would make them
+    -- invent a second one and keep a mapping.
+    correlation_id TEXT,
+    causation_id TEXT
+);
+
+CREATE INDEX IF NOT EXISTS outbox_events_capture_idx
+    ON commitrail.outbox_events (transaction_id, source_sequence, event_id);
+`,
+    },
+    {
+        version: 2,
+        sql: `
+-- The business identities an event concerns — a JSON array of {"type","id"} pairs, or null
+-- when the event declares none. CommitRail normalises these into its own indexed table at
+-- acceptance; they are never queried in the outbox.
+--
+-- Appended rather than declared in the table above, so that a fresh install and an upgraded
+-- one have the same column order rather than merely the same columns.
+ALTER TABLE commitrail.outbox_events ADD COLUMN IF NOT EXISTS subjects JSONB;
+`,
+    },
+    {
+        version: 3,
+        sql: `
+-- Finding every event in one logical operation is the correlation timeline's whole query.
+CREATE INDEX IF NOT EXISTS outbox_events_correlation_idx
+    ON commitrail.outbox_events (correlation_id)
+    WHERE correlation_id IS NOT NULL;
+`,
+    },
+    {
+        version: 4,
+        sql: `
+-- Which migrations have been applied. Bookkeeping, and only bookkeeping.
+--
+-- CommitRail never decides what it can read from this number. Capture inspects the actual
+-- columns and preflight validates the actual structure, because a marker can be wrong — hand
+-- edited, restored from a backup taken mid-migration, or written by a migration that half
+-- applied — and a version that outranks reality is worse than no version at all. What this buys
+-- is the ability to say "you are on 3 of 4" rather than "something is missing", and to give a
+-- customer an immutable thing to pin in their own migration history.
+CREATE TABLE IF NOT EXISTS commitrail.outbox_schema (
+    -- One row, enforced rather than assumed.
+    singleton BOOLEAN PRIMARY KEY DEFAULT TRUE CHECK (singleton),
+    version INTEGER NOT NULL,
+    applied_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+`,
+    },
+];
+/** The newest schema this package knows how to write. */
+exports.OUTBOX_SCHEMA_VERSION = exports.OUTBOX_MIGRATIONS[exports.OUTBOX_MIGRATIONS.length - 1].version;
+/**
+ * Record which version has been applied.
+ *
+ * `GREATEST` so that re-running an older migration cannot walk the marker backwards — applying
+ * the whole list to a database that is already current is a supported thing to do, and it must
+ * be a no-op rather than a downgrade.
+ */
+const RECORD_VERSION = (version) => `
+INSERT INTO commitrail.outbox_schema (version) VALUES (${version})
+ON CONFLICT (singleton) DO UPDATE
+    SET version = GREATEST(commitrail.outbox_schema.version, EXCLUDED.version),
+        applied_at = now();
+`;
+/** The migration that introduced the marker table; nothing before it can record anything. */
+const FIRST_RECORDED_VERSION = 4;
+/**
+ * Every migration, in order, for a fresh install or to bring an old outbox up to date.
+ *
+ * Safe to run against any database at any version: every statement is conditional, and the
+ * marker only moves forward. This is the convenience; `OUTBOX_MIGRATIONS` is the contract.
+ *
+ * Versions before the marker table existed record nothing — there is nowhere to record it. The
+ * migration that creates the table sets the version to its own, which is sound because the list
+ * is ordered and everything before it has just run.
+ */
+exports.OUTBOX_SCHEMA_SQL = exports.OUTBOX_MIGRATIONS.map((m) => m.version < FIRST_RECORDED_VERSION ? m.sql : `${m.sql}${RECORD_VERSION(m.version)}`).join('\n');
+const INSERT = `
+INSERT INTO commitrail.outbox_events
+    (event_id, event_type, event_version, payload, occurred_at, correlation_id, causation_id, subjects)
+VALUES ($1::uuid, $2, $3, $4::jsonb, COALESCE($5::timestamptz, now()), $6, $7, $8::jsonb)
+ON CONFLICT (event_id) DO NOTHING
+`;
+/**
+ * What makes two emissions THE SAME EVENT.
+ *
+ * Every producer-controlled field participates, because every one of them changes what the event
+ * means, where it routes, or how it is ordered:
+ *
+ *     event_type, event_version, payload, correlation_id, causation_id, subjects
+ *     occurred_at — only when the caller supplied one; see below
+ *
+ * Database-assigned fields never participate: `source_sequence` and `transaction_id` are issued
+ * per attempt and can never match, and comparing them would make every retry a conflict.
+ *
+ * **A new producer-controlled column must be added to `CONFLICTS` in the same change that adds
+ * it to the schema.** An ordering key is already planned, and it is exactly the kind of field
+ * that changes an event's meaning while being easy to forget here — a forgotten field makes two
+ * genuinely different events compare equal, which turns this check back into the silent discard
+ * it exists to remove. `tests/integration/sdk/postgres.test.ts` fails if a column appears in the
+ * outbox that this comment has not accounted for, so the reminder is a test rather than a hope.
+ *
+ * Comparison happens in PostgreSQL rather than in JavaScript: `jsonb` equality is semantic, so
+ * key order and whitespace do not matter, and `IS DISTINCT FROM` gets NULL right without a
+ * special case. Inventing JSON equality rules in JS would mean inventing them twice.
+ */
+/**
+ * Does an event already exist under this id that is not the event being written?
+ *
+ * Runs only after the INSERT above did nothing, and only inside the caller's transaction.
+ * There is no race: the unique index on `event_id` serialises two transactions emitting the
+ * same id, so the second one blocks until the first commits or rolls back and then sees a
+ * settled answer.
+ *
+ * `occurred_at` is compared only when the caller supplied one. It defaults to `now()`, so a
+ * legitimate retry that omitted it writes a different timestamp every attempt — comparing it
+ * unconditionally would report every such retry as a conflict, which is precisely the case
+ * `ON CONFLICT DO NOTHING` exists to allow.
+ *
+ * `transaction_id` and `source_sequence` are excluded for the same reason and more strongly:
+ * they are assigned by the database per attempt and can never match.
+ *
+ * The comparison is on `jsonb`, so key order and whitespace do not matter — two payloads that
+ * differ only in serialisation are the same event, which is what a retrying producer produces.
+ */
+const CONFLICTS = `
+SELECT 1
+FROM commitrail.outbox_events e
+WHERE e.event_id = $1::uuid
+  AND (
+    (e.event_type, e.event_version, e.payload, e.correlation_id, e.causation_id, e.subjects)
+      IS DISTINCT FROM ($2, $3::integer, $4::jsonb, $6, $7, $8::jsonb)
+    OR ($5::timestamptz IS NOT NULL AND e.occurred_at IS DISTINCT FROM $5::timestamptz)
+  )
+`;
+/**
+ * A different event was already written under this `eventId`.
+ *
+ * Supplying an `eventId` is a claim that two calls describe the same event. When they do not,
+ * one of them is a mistake — a reused id, or a collision — and CommitRail has no way to know
+ * which. Discarding the second silently would leave the producer believing it was written.
+ *
+ * Thrown from inside the caller's transaction. **When the exception is allowed to propagate
+ * out of a `transaction()` callback, the transaction rolls back** and nothing half-happens.
+ * That is the intended handling and the reason this throws rather than returning a flag.
+ *
+ * Note what a throw does not do: it does not poison the PostgreSQL transaction by itself. A
+ * caller managing `BEGIN`/`COMMIT` themselves can catch this and commit anyway, and would then
+ * have committed business state describing an event that was never written. There is no way for
+ * an SDK to prevent that; enforcing it against every writer would mean putting the rule in the
+ * customer's database, which is a schema-versioning cost not worth paying yet. Catching this and
+ * continuing is almost certainly wrong.
+ */
+class EventIdConflictError extends Error {
+    eventId;
+    static brand = CONFLICTING_EVENT_BRAND;
+    [CONFLICTING_EVENT_BRAND] = true;
+    constructor(eventId) {
+        super(`CommitRail: an event already exists with eventId ${eventId} and different content. ` +
+            'An eventId identifies one event; reusing it for a different one is a producer bug.');
+        this.eventId = eventId;
+        this.name = 'EventIdConflictError';
+    }
+    static is(error) {
+        return (typeof error === 'object' &&
+            error !== null &&
+            error[CONFLICTING_EVENT_BRAND] === true);
+    }
+}
+exports.EventIdConflictError = EventIdConflictError;
+/**
+ * How many rows a driver says it affected.
+ *
+ * `OutboxWriter` is structural and write-only on purpose, so this is the one place that has to
+ * know what real drivers return: `pg` gives a result object with `rowCount`, Prisma's
+ * `$executeRawUnsafe` gives a bare number. Anything else returns undefined, and an unknown
+ * shape must not be read as "no conflict" — see the caller.
+ */
+function affectedRows(result) {
+    if (typeof result === 'number') {
+        return result;
+    }
+    if (typeof result === 'object' && result !== null && 'rowCount' in result) {
+        const count = result.rowCount;
+        return typeof count === 'number' ? count : undefined;
+    }
+    return undefined;
+}
+/**
+ * Write an event to the outbox **inside the caller's transaction**.
+ *
+ * That is the entire point, and the only thing that can go wrong here. Pass a transaction
+ * and the event commits with your business state or not at all. Pass a pool — which also
+ * has `.query` — and you have written the event on a separate connection, which is the
+ * dual write CommitRail exists to eliminate. Nothing at runtime can tell the two apart, so
+ * prefer `transaction()` below, which does not give you the chance.
+ *
+ * If you already manage transactions yourself, call `emit` on your transaction-scoped client.
+ * The example is deliberately not a `BEGIN`/`COMMIT` pair: written short it has no rollback
+ * path, and `emit` throwing would leave the connection inside a failed transaction.
+ *
+ * ```ts
+ * // `tx` is whatever your code already uses for the surrounding transaction.
+ * await emit(tx, { type: 'order.created', data: { orderId } });
+ * ```
+ */
+async function emit(writer, event) {
+    if (event.type.trim().length === 0) {
+        throw new Error('an event must have a type');
+    }
+    assertNotAPool(writer);
+    const supplied = event.eventId !== undefined;
+    const eventId = event.eventId ?? (0, node_crypto_1.randomUUID)();
+    const subjects = (0, subjects_js_1.normalizeSubjects)(event.subjects);
+    // Normalised before it is written AND before it is compared, so the two are the same value.
+    // Comparing raw caller input against a canonicalised row would report a producer that reordered
+    // its own subjects as a conflict.
+    const params = [
+        eventId,
+        event.type,
+        event.version ?? 1,
+        JSON.stringify(event.data),
+        event.occurredAt ?? null,
+        event.correlationId ?? null,
+        event.causationId ?? null,
+        subjects === null ? null : JSON.stringify(subjects),
+    ];
+    const inserted = affectedRows(await writer.query(INSERT, params));
+    // Only a caller-supplied id can collide. Without one this is a fresh UUID, so there is nothing
+    // to check and nothing to pay for — which also means an exotic writer whose results cannot be
+    // interpreted keeps working unless the caller opts into explicit ids.
+    if (!supplied || inserted === 1) {
+        return eventId;
+    }
+    const conflicting = affectedRows(await writer.query(CONFLICTS, params));
+    if (conflicting === undefined) {
+        // Loud, because the alternative is the defect this check exists to remove: an event
+        // silently discarded while the caller believes it was written.
+        throw new Error('CommitRail: this writer returns a query result the SDK cannot interpret, so the eventId ' +
+            'idempotency check cannot be enforced. Return the driver result unchanged — a `pg` result ' +
+            'object or an affected-row count — or omit `eventId` and let CommitRail generate one.');
+    }
+    if (conflicting > 0) {
+        throw new EventIdConflictError(eventId);
+    }
+    return eventId;
+}
+/**
+ * Refuse a connection pool, which is the one mistake this function makes available.
+ *
+ * `OutboxWriter` is structural so that any driver satisfies it, and a `pg` Pool has the same
+ * `.query` method a transaction client does. Passing one writes the event on a whatever
+ * connection the pool hands out — a different connection from the business write, outside the
+ * transaction. That is the dual write CommitRail exists to eliminate, produced by code that
+ * looks correct and behaves correctly until the day a transaction rolls back.
+ *
+ * The documentation used to say nothing at runtime could tell the two apart. That is true of the
+ * interface and false of the object: a `pg` Pool carries `totalCount`, `idleCount` and
+ * `waitingCount`, and a client carries none of them. Checking is cheap, catches the exact
+ * documented footgun, and cannot produce a false positive on a transaction client.
+ *
+ * A driver this does not recognise is passed through, so the guard only ever adds safety. It is
+ * not a substitute for `transaction()`, which removes the choice instead of policing it.
+ */
+function assertNotAPool(writer) {
+    const pool = writer;
+    if (typeof pool.totalCount === 'number' &&
+        typeof pool.idleCount === 'number' &&
+        typeof pool.waitingCount === 'number') {
+        throw new Error('CommitRail: emit() was given a connection pool, not a transaction. The event would be ' +
+            'written on a different connection from your business write and would survive a ' +
+            'rollback — the dual write CommitRail exists to eliminate. Use transaction(pool, tx => ' +
+            'tx.emit(...)), or pass the client your own transaction is running on.');
+    }
+}
+/**
+ * Run work in a transaction, with `emit` bound to it.
+ *
+ * The recommended shape, because it removes the one mistake available: the writer handed
+ * to the callback is the transaction, so an event cannot accidentally be written outside
+ * it.
+ *
+ * ```ts
+ * await transaction(pool, async (tx) => {
+ *   await tx.query('INSERT INTO orders (id, total) VALUES ($1, $2)', [id, total]);
+ *   await tx.emit({ type: 'order.created', data: { orderId: id } });
+ * });
+ * ```
+ */
+async function transaction(pool, work) {
+    const client = await pool.connect();
+    try {
+        await client.query('BEGIN', []);
+        const tx = {
+            query: (sql, params) => client.query(sql, params),
+            emit: (event) => emit(client, event),
+        };
+        const result = await work(tx);
+        await client.query('COMMIT', []);
+        return result;
+    }
+    catch (error) {
+        await client.query('ROLLBACK', []);
+        throw error;
+    }
+    finally {
+        client.release();
+    }
+}
+/**
+ * Adapt a Prisma transaction client.
+ *
+ * Typed structurally so this package does not depend on Prisma. Uses `$executeRawUnsafe`
+ * because the SQL is a constant defined above and the values are parameterised — the
+ * "unsafe" in the name refers to interpolating the statement, which never happens here.
+ */
+function fromPrisma(tx) {
+    return {
+        query: (sql, params) => tx.$executeRawUnsafe(sql, ...params),
+    };
+}
+//# sourceMappingURL=postgres.js.map

package/dist/cjs/postgres.js.map

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

package/dist/cjs/signing.d.ts

@@ -0,0 +1,66 @@
+export interface SigningSecret {
+    version: number;
+    secret: string;
+}
+export interface SigningMaterial {
+    current: SigningSecret;
+    /** Present only while a rotation is in progress. */
+    previous?: SigningSecret;
+}
+/**
+ * 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 declare function canonicalPayload(input: {
+    timestamp: number;
+    deliveryId: string;
+    body: string;
+}): string;
+/**
+ * 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 declare function canonicalPayloadBytes(input: {
+    timestamp: number;
+    deliveryId: string;
+    body: Uint8Array;
+}): Uint8Array;
+export declare function sign(secret: string, canonical: string | Uint8Array): string;
+/**
+ * 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 declare function signatureHeader(input: {
+    timestamp: number;
+    deliveryId: string;
+    body: string;
+    material: SigningMaterial;
+}): string;
+/**
+ * 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 declare function verifySignatureHeader(input: {
+    header: string;
+    secret: string;
+    deliveryId: string;
+    /** The raw body. Bytes are preferred; a string is decoded UTF-8 and equivalent for JSON. */
+    body: string | Uint8Array;
+    toleranceSeconds?: number;
+    now?: number;
+}): boolean;

package/dist/cjs/signing.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canonicalPayload = canonicalPayload;
+exports.canonicalPayloadBytes = canonicalPayloadBytes;
+exports.sign = sign;
+exports.signatureHeader = signatureHeader;
+exports.verifySignatureHeader = verifySignatureHeader;
+const node_crypto_1 = require("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.
+ */
+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.
+ */
+function canonicalPayloadBytes(input) {
+    return Buffer.concat([
+        Buffer.from(`${input.timestamp}.${input.deliveryId}.`, 'utf8'),
+        Buffer.from(input.body.buffer, input.body.byteOffset, input.body.byteLength),
+    ]);
+}
+function sign(secret, canonical) {
+    return (0, node_crypto_1.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.
+ */
+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.
+ */
+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 && (0, node_crypto_1.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/cjs/signing.js.map

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

package/dist/cjs/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 {};