webhook-delivery-engine 0.0.0-stage → 1.0.0

package/dist/src/security/auth.js

@@ -0,0 +1,39 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+const unauthorizedResult = Object.freeze({
+    authenticated: false,
+    statusCode: 401,
+});
+function digest(value) {
+    return createHash('sha256').update(value, 'utf8').digest();
+}
+function createAuthenticator(expectedDigest, clientId) {
+    return (candidateToken) => {
+        const token = typeof candidateToken === 'string' ? candidateToken : '';
+        const candidateDigest = digest(token);
+        const authenticated = timingSafeEqual(expectedDigest, candidateDigest);
+        return authenticated ? { authenticated: true, clientId } : unauthorizedResult;
+    };
+}
+/**
+ * Creates an authenticator for one configured API key and tenant identity.
+ *
+ * The configured key is reduced to a fixed-length SHA-256 digest before the
+ * returned function is exposed. Each candidate, including an absent token,
+ * is hashed and compared with `timingSafeEqual`; credentials are never
+ * returned or logged. The HTTP layer maps an unauthorized result to a 401
+ * response.
+ *
+ * @param config - API key and its configured tenant identity.
+ * @returns A function that returns the tenant identity only for a valid key.
+ * @throws {@link TypeError} when either configured value is not a non-empty string.
+ */
+export function createApiKeyAuthenticator(config) {
+    const { apiKey, clientId } = config;
+    if (typeof apiKey !== 'string' ||
+        apiKey.length === 0 ||
+        typeof clientId !== 'string' ||
+        clientId.length === 0) {
+        throw new TypeError('apiKey and clientId must be non-empty strings.');
+    }
+    return createAuthenticator(digest(apiKey), clientId);
+}

package/dist/src/security/ssrf.d.ts

@@ -0,0 +1,47 @@
+/**
+ * A destination URL validation result that never exposes DNS answers or
+ * resolver error details.
+ */
+export type DestinationUrlValidationResult = {
+    readonly valid: true;
+    readonly url: string;
+} | {
+    readonly valid: false;
+    readonly reason: 'invalid_url' | 'unsupported_protocol' | 'credentials_not_allowed' | 'unsafe_address' | 'dns_resolution_failed';
+};
+/**
+ * Internal delivery-only DNS result. Callers must not expose addresses in
+ * public API results, logs, or persisted records.
+ */
+export type DestinationDispatchResolutionResult = {
+    readonly valid: true;
+    readonly url: string;
+    readonly hostname: string;
+    readonly addresses: readonly string[];
+} | {
+    readonly valid: false;
+    readonly reason: Extract<DestinationUrlValidationResult, {
+        valid: false;
+    }>['reason'];
+};
+/**
+ * Resolves and validates a destination immediately before HTTP dispatch.
+ *
+ * Only absolute HTTPS URLs without embedded credentials are accepted. Literal
+ * addresses are classified without DNS; hostnames are rejected if any
+ * resolved IPv4 or IPv6 address is unsafe. Hostname lookup requests every
+ * address using Node DNS. Successful results include the vetted addresses for
+ * the delivery connector to pin. This internal result must never be exposed
+ * through the public API or logs.
+ *
+ * @param destinationUrl - Persisted destination URL for one dispatch attempt.
+ * @returns A canonical URL and vetted addresses or a generic safe failure.
+ */
+export declare function resolveDestinationForDispatch(destinationUrl: string): Promise<DestinationDispatchResolutionResult>;
+/**
+ * Validates a destination URL before it can be persisted.
+ *
+ * @param destinationUrl - Untrusted destination URL supplied by a caller or configuration.
+ * @returns A canonical URL on success or a generic safe failure reason.
+ */
+export declare function validateDestinationUrl(destinationUrl: string): Promise<DestinationUrlValidationResult>;

package/dist/src/security/ssrf.js

@@ -0,0 +1,173 @@
+import { lookup } from 'node:dns/promises';
+import { isIP } from 'node:net';
+const blockedIpv4Cidrs = [
+    ['0.0.0.0', 8],
+    ['10.0.0.0', 8],
+    ['100.64.0.0', 10],
+    ['127.0.0.0', 8],
+    ['169.254.0.0', 16],
+    ['172.16.0.0', 12],
+    ['192.0.0.0', 24],
+    ['192.0.2.0', 24],
+    ['192.31.196.0', 24],
+    ['192.52.193.0', 24],
+    ['192.88.99.0', 24],
+    ['192.168.0.0', 16],
+    ['192.175.48.0', 24],
+    ['198.18.0.0', 15],
+    ['198.51.100.0', 24],
+    ['203.0.113.0', 24],
+    ['224.0.0.0', 4],
+    ['240.0.0.0', 4],
+];
+const blockedIpv6Cidrs = [
+    ['2001::', 23],
+    ['2001:db8::', 32],
+    ['2002::', 16],
+    ['3fff::', 20],
+];
+function ipv4ToBigInt(address) {
+    return address.split('.').reduce((value, octet) => (value << 8n) | BigInt(octet), 0n);
+}
+function ipv6ToBigInt(address) {
+    const halves = address.toLowerCase().split('::');
+    const left = halves[0] === '' ? [] : halves[0].split(':');
+    const right = halves.length === 2 && halves[1] !== '' ? halves[1].split(':') : [];
+    const zeroGroups = 8 - left.length - right.length;
+    const groups = [...left, ...Array.from({ length: zeroGroups }, () => '0'), ...right];
+    return groups.reduce((value, group) => (value << 16n) | BigInt(`0x${group}`), 0n);
+}
+function isIpv4InCidr(address, network, prefixLength) {
+    const shift = BigInt(32 - prefixLength);
+    return ipv4ToBigInt(address) >> shift === ipv4ToBigInt(network) >> shift;
+}
+function isIpv6InCidr(address, network, prefixLength) {
+    const networkAddress = ipv6ToBigInt(network);
+    const shift = BigInt(128 - prefixLength);
+    return address >> shift === networkAddress >> shift;
+}
+function isBlockedIpv4(address) {
+    return blockedIpv4Cidrs.some(([network, prefixLength]) => isIpv4InCidr(address, network, prefixLength));
+}
+function isBlockedIpv6(address) {
+    const addressValue = ipv6ToBigInt(address);
+    const mappedIpv4Prefix = addressValue >> 32n;
+    if (mappedIpv4Prefix === 0xffffn) {
+        const embeddedIpv4 = Number(addressValue & 0xffffffffn);
+        const ipv4Address = [
+            (embeddedIpv4 >>> 24) & 0xff,
+            (embeddedIpv4 >>> 16) & 0xff,
+            (embeddedIpv4 >>> 8) & 0xff,
+            embeddedIpv4 & 0xff,
+        ].join('.');
+        return isBlockedIpv4(ipv4Address);
+    }
+    // Only global-unicast IPv6 is eligible; this excludes unspecified, loopback,
+    // ULA, link-local, multicast, and other non-global allocation ranges.
+    if (!isIpv6InCidr(addressValue, '2000::', 3)) {
+        return true;
+    }
+    return blockedIpv6Cidrs.some(([network, prefixLength]) => isIpv6InCidr(addressValue, network, prefixLength));
+}
+function isBlockedAddress(address) {
+    const family = isIP(address);
+    if (family === 4) {
+        return isBlockedIpv4(address);
+    }
+    if (family === 6) {
+        return isBlockedIpv6(address);
+    }
+    return true;
+}
+function hostnameFromUrl(url) {
+    if (url.hostname.startsWith('[') && url.hostname.endsWith(']')) {
+        return url.hostname.slice(1, -1);
+    }
+    return url.hostname;
+}
+async function resolveAddresses(hostname) {
+    const resolved = await lookup(hostname, { all: true, verbatim: true });
+    return resolved.map(({ address }) => address);
+}
+function hasForbiddenUrlCharacters(value) {
+    return [...value].some((character) => {
+        const codePoint = character.codePointAt(0);
+        return (codePoint !== undefined && (codePoint <= 0x20 || codePoint === 0x7f || character === '\\'));
+    });
+}
+/**
+ * Resolves and validates a destination immediately before HTTP dispatch.
+ *
+ * Only absolute HTTPS URLs without embedded credentials are accepted. Literal
+ * addresses are classified without DNS; hostnames are rejected if any
+ * resolved IPv4 or IPv6 address is unsafe. Hostname lookup requests every
+ * address using Node DNS. Successful results include the vetted addresses for
+ * the delivery connector to pin. This internal result must never be exposed
+ * through the public API or logs.
+ *
+ * @param destinationUrl - Persisted destination URL for one dispatch attempt.
+ * @returns A canonical URL and vetted addresses or a generic safe failure.
+ */
+export async function resolveDestinationForDispatch(destinationUrl) {
+    if (typeof destinationUrl !== 'string' ||
+        destinationUrl.length === 0 ||
+        destinationUrl !== destinationUrl.trim() ||
+        hasForbiddenUrlCharacters(destinationUrl)) {
+        return { valid: false, reason: 'invalid_url' };
+    }
+    let parsedUrl;
+    try {
+        parsedUrl = new URL(destinationUrl);
+    }
+    catch {
+        return { valid: false, reason: 'invalid_url' };
+    }
+    if (parsedUrl.protocol !== 'https:') {
+        return { valid: false, reason: 'unsupported_protocol' };
+    }
+    const authority = /^https:\/\/([^/?#]*)/iu.exec(destinationUrl)?.[1];
+    if (authority === undefined || authority.length === 0 || parsedUrl.hostname.length === 0) {
+        return { valid: false, reason: 'invalid_url' };
+    }
+    if (authority.includes('@') || parsedUrl.username.length > 0 || parsedUrl.password.length > 0) {
+        return { valid: false, reason: 'credentials_not_allowed' };
+    }
+    const hostname = hostnameFromUrl(parsedUrl);
+    const normalizedHostname = hostname.toLowerCase().replace(/\.$/u, '');
+    if (normalizedHostname === 'localhost' || normalizedHostname.endsWith('.localhost')) {
+        return { valid: false, reason: 'unsafe_address' };
+    }
+    const addressFamily = isIP(hostname);
+    if (addressFamily !== 0) {
+        return isBlockedAddress(hostname)
+            ? { valid: false, reason: 'unsafe_address' }
+            : { valid: true, url: parsedUrl.toString(), hostname, addresses: [hostname] };
+    }
+    let addresses;
+    try {
+        addresses = await resolveAddresses(hostname);
+    }
+    catch {
+        return { valid: false, reason: 'dns_resolution_failed' };
+    }
+    if (addresses.length === 0) {
+        return { valid: false, reason: 'dns_resolution_failed' };
+    }
+    if (addresses.some(isBlockedAddress)) {
+        return { valid: false, reason: 'unsafe_address' };
+    }
+    return { valid: true, url: parsedUrl.toString(), hostname, addresses };
+}
+/**
+ * Validates a destination URL before it can be persisted.
+ *
+ * @param destinationUrl - Untrusted destination URL supplied by a caller or configuration.
+ * @returns A canonical URL on success or a generic safe failure reason.
+ */
+export async function validateDestinationUrl(destinationUrl) {
+    const result = await resolveDestinationForDispatch(destinationUrl);
+    if (!result.valid) {
+        return result;
+    }
+    return { valid: true, url: result.url };
+}

package/dist/src/shared/logger.d.ts

@@ -0,0 +1,11 @@
+import { type DestinationStream, type Logger } from 'pino';
+export declare const LOG_LEVELS: readonly ["fatal", "error", "warn", "info", "debug", "trace", "silent"];
+export type LogLevel = (typeof LOG_LEVELS)[number];
+export interface StructuredLoggerOptions {
+    readonly level: LogLevel;
+    readonly destination?: DestinationStream;
+}
+/** Resolves and validates a package option, environment setting, or default. */
+export declare function resolveLogLevel(explicit: string | undefined, environment: string | undefined): LogLevel;
+/** Creates the Pino-backed JSON logger with built-in sensitive-field redaction. */
+export declare function createStructuredLogger(options: StructuredLoggerOptions): Logger;

package/dist/src/shared/logger.js

@@ -0,0 +1,52 @@
+import pino, {} from 'pino';
+export const LOG_LEVELS = ['fatal', 'error', 'warn', 'info', 'debug', 'trace', 'silent'];
+const REDACT_PATHS = [
+    'Authorization',
+    'authorization',
+    'headers.Authorization',
+    'headers.authorization',
+    'headers["X-API-Key"]',
+    'headers["x-api-key"]',
+    'req.headers.Authorization',
+    'req.headers.authorization',
+    'req.headers["X-API-Key"]',
+    'req.headers["x-api-key"]',
+    'request.headers.Authorization',
+    'request.headers.authorization',
+    'request.headers["X-API-Key"]',
+    'request.headers["x-api-key"]',
+    '["x-api-key"]',
+    '["X-API-Key"]',
+    'apiKey',
+    'api_key',
+    'API_KEY',
+    'hmacSecret',
+    'hmac_secret',
+    'HMAC_SECRET',
+    'secret',
+    'payload',
+    'body',
+    'request.body',
+    'request.payload',
+    'event.payload',
+    'event.headers',
+    'eventData.payload',
+    'eventData.headers',
+];
+/** Resolves and validates a package option, environment setting, or default. */
+export function resolveLogLevel(explicit, environment) {
+    const candidate = explicit ?? environment ?? 'info';
+    if (LOG_LEVELS.includes(candidate))
+        return candidate;
+    throw new TypeError(`Unsupported log level "${candidate}".`);
+}
+/** Creates the Pino-backed JSON logger with built-in sensitive-field redaction. */
+export function createStructuredLogger(options) {
+    const pinoOptions = {
+        level: options.level,
+        redact: { paths: REDACT_PATHS, remove: true },
+    };
+    return options.destination === undefined
+        ? pino(pinoOptions)
+        : pino(pinoOptions, options.destination);
+}

package/dist/src/storage/migrations/runner.d.ts

@@ -0,0 +1,51 @@
+import type { SQLInputValue } from 'node:sqlite';
+/** A prepared SQLite statement surface shared by supported SQLite drivers. */
+export interface SqliteMigrationStatement {
+    /** Returns all rows produced by a query; row shape is validated by the runner. */
+    all(...parameters: SQLInputValue[]): unknown;
+    /** Returns one row produced by a query; row shape is validated by the runner. */
+    get(...parameters: SQLInputValue[]): unknown;
+    /** Executes a statement without returning rows. */
+    run(...parameters: SQLInputValue[]): unknown;
+}
+/** The minimal synchronous SQLite connection surface needed to apply migrations. */
+export interface SqliteMigrationConnection {
+    /** Executes one or more SQL statements on the current connection. */
+    exec(sql: string): void;
+    /** Prepares a SQL statement for parameterized execution. */
+    prepare(sql: string): SqliteMigrationStatement;
+}
+/** Options for applying migrations with a synchronous SQLite connection. */
+export interface SqliteMigrationOptions {
+    /** Selects the SQLite execution and transaction policy. */
+    readonly dialect: 'sqlite';
+    /** Connection whose transaction is exclusively controlled during migration. */
+    readonly connection: SqliteMigrationConnection;
+    /** Directory containing versioned SQLite SQL files; defaults to the bundled directory. */
+    readonly migrationDirectory?: string;
+}
+/** Options for applying the bundled SQLite migrations. */
+export type MigrationRunnerOptions = SqliteMigrationOptions;
+/** An explicit failure raised when migration discovery, validation, or execution fails. */
+export declare class MigrationError extends Error {
+    /**
+     * Creates a migration failure with an optional originating error.
+     *
+     * @param message - Actionable description of the migration failure.
+     * @param cause - Original filesystem or database error, when available.
+     */
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * Applies the forward-only SQL migrations for SQLite.
+ *
+ * Migration files are applied in lexical filename order, hashed with SHA-256,
+ * and recorded in `schema_migrations`. Existing records must match both the
+ * checked-in migration file and checksum. All pending SQLite migrations run
+ * in one transaction.
+ *
+ * @param options - Dialect, connection, and optional migration directory.
+ * @returns Versions newly applied by this invocation, in application order.
+ * @throws {@link MigrationError} when files are invalid, drift is detected, or execution fails.
+ */
+export declare function runMigrations(options: MigrationRunnerOptions): Promise<readonly string[]>;

package/dist/src/storage/migrations/runner.js

@@ -0,0 +1,155 @@
+import { createHash } from 'node:crypto';
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** An explicit failure raised when migration discovery, validation, or execution fails. */
+export class MigrationError extends Error {
+    /**
+     * Creates a migration failure with an optional originating error.
+     *
+     * @param message - Actionable description of the migration failure.
+     * @param cause - Original filesystem or database error, when available.
+     */
+    constructor(message, cause) {
+        super(message, { cause });
+        this.name = 'MigrationError';
+    }
+}
+/**
+ * Applies the forward-only SQL migrations for SQLite.
+ *
+ * Migration files are applied in lexical filename order, hashed with SHA-256,
+ * and recorded in `schema_migrations`. Existing records must match both the
+ * checked-in migration file and checksum. All pending SQLite migrations run
+ * in one transaction.
+ *
+ * @param options - Dialect, connection, and optional migration directory.
+ * @returns Versions newly applied by this invocation, in application order.
+ * @throws {@link MigrationError} when files are invalid, drift is detected, or execution fails.
+ */
+export async function runMigrations(options) {
+    const directory = options.migrationDirectory ?? fileURLToPath(new URL('./sql/sqlite/', import.meta.url));
+    const files = await loadMigrationFiles(directory);
+    return runSqliteMigrations(options.connection, files);
+}
+async function loadMigrationFiles(directory) {
+    let entries;
+    try {
+        entries = await readdir(directory, { withFileTypes: true });
+    }
+    catch (cause) {
+        throw new MigrationError(`Unable to read migration directory "${directory}".`, cause);
+    }
+    const names = entries
+        .filter((entry) => entry.isFile() && entry.name.endsWith('.sql'))
+        .map((entry) => entry.name)
+        .sort();
+    const versions = new Set();
+    const ordinals = new Set();
+    const files = [];
+    for (const name of names) {
+        const match = /^(\d+_[a-z0-9][a-z0-9_-]*)\.sql$/.exec(name);
+        if (match === null) {
+            throw new MigrationError(`Invalid migration filename "${name}".`);
+        }
+        const version = match[1];
+        if (version === undefined || versions.has(version)) {
+            throw new MigrationError(`Duplicate or invalid migration version in "${name}".`);
+        }
+        const ordinal = BigInt(version.slice(0, version.indexOf('_'))).toString();
+        if (ordinals.has(ordinal)) {
+            throw new MigrationError(`Duplicate migration sequence number in "${name}".`);
+        }
+        versions.add(version);
+        ordinals.add(ordinal);
+        let sql;
+        try {
+            sql = await readFile(join(directory, name), 'utf8');
+        }
+        catch (cause) {
+            throw new MigrationError(`Unable to read migration file "${name}".`, cause);
+        }
+        if (sql.trim().length === 0) {
+            throw new MigrationError(`Migration "${version}" is empty.`);
+        }
+        files.push({
+            version,
+            checksum: createHash('sha256').update(sql, 'utf8').digest('hex'),
+            sql,
+        });
+    }
+    return files.sort((left, right) => {
+        const leftOrdinal = BigInt(left.version.slice(0, left.version.indexOf('_')));
+        const rightOrdinal = BigInt(right.version.slice(0, right.version.indexOf('_')));
+        return leftOrdinal < rightOrdinal ? -1 : leftOrdinal > rightOrdinal ? 1 : 0;
+    });
+}
+function readAppliedMigrations(rows) {
+    if (!Array.isArray(rows)) {
+        throw new MigrationError('Migration ledger query returned an invalid result.');
+    }
+    return rows.map((row) => {
+        if (typeof row !== 'object' ||
+            row === null ||
+            !('version' in row) ||
+            !('checksum' in row) ||
+            typeof row.version !== 'string' ||
+            typeof row.checksum !== 'string') {
+            throw new MigrationError('Migration ledger contains an invalid record.');
+        }
+        return { version: row.version, checksum: row.checksum };
+    });
+}
+function getPendingMigrations(files, applied) {
+    const byVersion = new Map(files.map((file) => [file.version, file]));
+    const appliedVersions = new Set();
+    for (const record of applied) {
+        const file = byVersion.get(record.version);
+        if (file === undefined) {
+            throw new MigrationError(`Applied migration "${record.version}" is missing from the migration directory.`);
+        }
+        if (file.checksum !== record.checksum) {
+            throw new MigrationError(`Checksum mismatch for applied migration "${record.version}".`);
+        }
+        appliedVersions.add(record.version);
+    }
+    return files.filter((file) => !appliedVersions.has(file.version));
+}
+async function runSqliteMigrations(connection, files) {
+    let transactionStarted = false;
+    try {
+        connection.exec('BEGIN IMMEDIATE');
+        transactionStarted = true;
+        connection.exec(`CREATE TABLE IF NOT EXISTS schema_migrations (
+        version TEXT PRIMARY KEY,
+        checksum TEXT NOT NULL,
+        applied_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+      )`);
+        const applied = readAppliedMigrations(connection.prepare('SELECT version, checksum FROM schema_migrations').all());
+        const pending = getPendingMigrations(files, applied);
+        for (const migration of pending) {
+            connection.exec(migration.sql);
+            connection
+                .prepare('INSERT INTO schema_migrations (version, checksum) VALUES (?, ?)')
+                .run(migration.version, migration.checksum);
+        }
+        connection.exec('COMMIT');
+        return pending.map((migration) => migration.version);
+    }
+    catch (cause) {
+        if (transactionStarted) {
+            try {
+                connection.exec('ROLLBACK');
+            }
+            catch (rollbackCause) {
+                throw new MigrationError('Migration failed and SQLite rollback also failed.', new AggregateError([cause, rollbackCause]));
+            }
+        }
+        throw toMigrationError('SQLite migration failed.', cause);
+    }
+}
+function toMigrationError(message, cause) {
+    if (cause instanceof MigrationError)
+        return cause;
+    return new MigrationError(message, cause);
+}

package/dist/src/storage/migrations/sql/sqlite/001_initial_schema.sql

@@ -0,0 +1,52 @@
+CREATE TABLE IF NOT EXISTS webhook_events (
+  id TEXT NOT NULL PRIMARY KEY,
+  idempotency_key TEXT NOT NULL,
+  client_id TEXT NOT NULL,
+  destination_url TEXT NOT NULL,
+  payload TEXT NOT NULL CHECK (json_valid(payload)),
+  metadata TEXT NOT NULL CHECK (
+    json_valid(metadata) AND json_type(metadata) = 'object'
+  ),
+  headers TEXT NOT NULL CHECK (
+    json_valid(headers) AND json_type(headers) = 'object'
+  ),
+  status TEXT NOT NULL CHECK (
+    status IN ('pending', 'processing', 'delivered', 'retry', 'failed')
+  ),
+  attempt_count INTEGER NOT NULL DEFAULT 0 CHECK (attempt_count >= 0),
+  next_retry_at TEXT,
+  locked_at TEXT,
+  locked_by TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  CONSTRAINT uq_client_idempotency UNIQUE (client_id, idempotency_key),
+  CONSTRAINT chk_webhook_events_lease CHECK (
+    (status = 'processing' AND locked_at IS NOT NULL AND locked_by IS NOT NULL)
+    OR
+    (status <> 'processing' AND locked_at IS NULL AND locked_by IS NULL)
+  )
+) STRICT;
+
+CREATE INDEX IF NOT EXISTS idx_webhook_events_due
+  ON webhook_events (status, next_retry_at);
+
+CREATE TABLE IF NOT EXISTS webhook_event_attempts (
+  id TEXT NOT NULL PRIMARY KEY,
+  event_id TEXT NOT NULL,
+  attempt_number INTEGER NOT NULL CHECK (attempt_number > 0),
+  attempted_at TEXT NOT NULL,
+  status_code INTEGER CHECK (status_code IS NULL OR status_code BETWEEN 100 AND 599),
+  response_snippet TEXT CHECK (
+    response_snippet IS NULL OR length(CAST(response_snippet AS BLOB)) <= 1024
+  ),
+  error TEXT,
+  latency_ms INTEGER CHECK (latency_ms IS NULL OR latency_ms >= 0),
+  outcome TEXT NOT NULL CHECK (
+    outcome IN ('success', 'retry_scheduled', 'exhausted')
+  ),
+  CONSTRAINT fk_webhook_event_attempts_event
+    FOREIGN KEY (event_id) REFERENCES webhook_events (id) ON DELETE CASCADE
+) STRICT;
+
+CREATE UNIQUE INDEX IF NOT EXISTS uq_webhook_event_attempts_event_number
+  ON webhook_event_attempts (event_id, attempt_number);

package/dist/src/storage/sqlite.adapter.d.ts

@@ -0,0 +1,51 @@
+import type { AttemptRecord, WebhookEvent } from '../core/types.js';
+import type { ClaimDueEventsInput, DatabaseAdapter, EventPage, EventUpsertResult, ListEventsInput, RecordAttemptAndTransitionInput, RecoverStaleLeasesInput, ReleaseEventLeaseInput } from '../core/ports.js';
+/**
+ * SQLite implementation of the driver-neutral event persistence contract.
+ *
+ * Create instances with {@link SqliteDatabaseAdapter.open}; the returned
+ * adapter owns its database connection and must be closed by its owner.
+ */
+export declare class SqliteDatabaseAdapter implements DatabaseAdapter {
+    private readonly database;
+    private constructor();
+    /**
+     * Opens and initializes a SQLite database before exposing the adapter.
+     *
+     * Initialization enables WAL, a 5-second busy timeout, foreign-key checks,
+     * and applies the bundled forward-only migrations. The connection is closed
+     * and the original error is propagated if initialization fails.
+     *
+     * @param filename - SQLite database file path; use a file for WAL support.
+     * @returns An initialized adapter implementing {@link DatabaseAdapter}.
+     * @throws When the database cannot be opened, configured, or migrated.
+     */
+    static open(filename: string): Promise<SqliteDatabaseAdapter>;
+    /**
+     * Closes the SQLite connection owned by this adapter.
+     *
+     * @returns Nothing.
+     * @throws When the underlying database cannot be closed.
+     */
+    close(): void;
+    /** @inheritdoc */
+    upsertEvent(event: WebhookEvent): Promise<EventUpsertResult>;
+    /** @inheritdoc */
+    claimDueEvents(input: ClaimDueEventsInput): Promise<readonly WebhookEvent[]>;
+    /** @inheritdoc */
+    recoverStaleLeases(input: RecoverStaleLeasesInput): Promise<number>;
+    /** @inheritdoc */
+    releaseEventLease(input: ReleaseEventLeaseInput): Promise<boolean>;
+    /** @inheritdoc */
+    recordAttemptAndTransition(input: RecordAttemptAndTransitionInput): Promise<boolean>;
+    /** @inheritdoc */
+    findEventById(eventId: string, clientId: string): Promise<WebhookEvent | null>;
+    /** @inheritdoc */
+    findEventByIdempotencyKey(clientId: string, idempotencyKey: string): Promise<WebhookEvent | null>;
+    /** @inheritdoc */
+    listEvents(input: ListEventsInput): Promise<EventPage>;
+    /** @inheritdoc */
+    listAttempts(eventId: string, clientId: string): Promise<readonly AttemptRecord[]>;
+}
+/** Compares claimed events by creation time, then by their unique id. */
+export declare function compareClaimedEvents(left: WebhookEvent, right: WebhookEvent): number;