@bajustone/fortress 1.0.0-rc.1

package/dist/plugins/webhook.d.cts

@@ -0,0 +1,254 @@
+import { S as StandardSchemaV1, F as FortressPlugin } from '../config-GtlVt6ZD.cjs';
+import { FetchFn } from '@bajustone/fetcher';
+import { D as DatabaseAdapter } from '../index-CxEkfCA0.cjs';
+import '../jwt.cjs';
+import '../types-et0R8tsC.cjs';
+import '../auth-service-BcyQ2PuZ.cjs';
+
+/**
+ * Webhook delivery over `@bajustone/fetcher`.
+ *
+ * fetcher is 100% native `fetch` and does **no** IP pinning of its own, so the
+ * SSRF guard must live *inside* the transport: {@link ssrfSafeFetch} is a
+ * fetcher `FetchFn` that resolves + validates the target and issues the request
+ * through `node:https` with a custom `lookup` that pins the connection to the
+ * resolved IP — closing the DNS-rebinding window. A plain fetch (or a
+ * pre-flight check followed by a normal fetch) would re-resolve DNS and reopen
+ * that window, so the guard MUST be the transport.
+ *
+ * @module
+ */
+
+/** How retries are handled for a delivery client. See the webhook config docs. */
+type RetryMode = 'pluginScheduled' | 'inProcess' | 'queue';
+
+/**
+ * Bring-Your-Own-Queue interface. Delivery is always queued; consumers can
+ * back it with any system (in-memory, DB, BullMQ, SQS, Cloudflare Queues,
+ * Inngest, …) by implementing this small surface.
+ *
+ * @module
+ */
+
+/** One unit of delivery work — a single attempt of a single delivery row. */
+interface WebhookQueueJob {
+    deliveryId: string;
+    endpointId: string;
+    eventType: string;
+    /** 1-based attempt number. */
+    attempt: number;
+    /** When this attempt should run (retries); absent means "now". */
+    scheduledFor?: Date;
+}
+/** Context handed to {@link WebhookQueue.start} so fortress-aware queues can reach the DB. */
+interface WebhookQueueContext {
+    /** The fortress database adapter — used by the database queue to poll, and for the startup recovery sweep. */
+    db: DatabaseAdapter;
+}
+interface WebhookQueue {
+    /**
+     * If true, the plugin re-throws on failed delivery and the queue is expected
+     * to retry per its own policy (BullMQ/SQS/Inngest). If false/absent, the
+     * plugin schedules retries itself.
+     */
+    handlesRetries?: boolean;
+    /** Enqueue a delivery job. (A no-op for the database queue — the table IS the queue.) */
+    enqueue: (job: WebhookQueueJob) => Promise<void>;
+    /**
+     * Optional worker registration. Pull queues (in-memory, database) implement
+     * this; push/serverless queues (Cloudflare Queues with a separate consumer,
+     * Inngest, …) leave it undefined. Returns a teardown the consumer calls on
+     * shutdown. Implementations SHOULD run a startup recovery sweep here —
+     * re-enqueue rows left `pending` by a prior process — so at-least-once holds
+     * across restarts.
+     */
+    start?: (handler: (job: WebhookQueueJob) => Promise<void>, ctx: WebhookQueueContext) => Promise<() => Promise<void>>;
+}
+
+/**
+ * Public types for the webhook plugin v1 (custom events + Bring-Your-Own-Queue).
+ *
+ * @module
+ */
+
+/** A fortress lifecycle hook a built-in event auto-emits from. */
+type BuiltinEventSource = 'afterLogin' | 'onLoginFailure' | 'beforeLogout' | 'afterRegister' | 'afterTokenRefresh';
+/**
+ * Declares an event consumers (or the built-ins) can emit. Built-in auth events
+ * and user-defined events share this one shape and the same emit path.
+ */
+interface WebhookEventDeclaration<S extends StandardSchemaV1 = StandardSchemaV1> {
+    /** Dot-cased event name, e.g. `auth.login.success` or `order.paid`. */
+    name: string;
+    description?: string;
+    /** Standard Schema V1 validator (fortress builder, fetcher builder, Zod, …); the payload is validated at `emit()` time. */
+    schema?: S;
+    /** If set, the plugin auto-emits this event from the named fortress hook. */
+    source?: BuiltinEventSource;
+}
+/** Stable delivery failure taxonomy persisted in `webhook_delivery.error_kind`. */
+type WebhookErrorKind = 'http' | 'network';
+/** Stable endpoint deactivation reason taxonomy. */
+type WebhookDeactivatedReason = `permanent_${number}` | 'too_many_failures';
+/** A registered delivery endpoint. `secret` is redacted from `listEndpoints()`. */
+interface WebhookEndpoint {
+    id: string;
+    url: string;
+    events: string;
+    secret: string;
+    isActive: boolean;
+    deactivatedReason: WebhookDeactivatedReason | null;
+    consecutiveFailures: number;
+    createdAt: Date;
+}
+/** A persisted delivery attempt row — the transactional outbox record. */
+interface WebhookDelivery {
+    id: string;
+    endpointId: string;
+    eventType: string;
+    payload: string;
+    status: 'pending' | 'success' | 'failed';
+    attempts: number;
+    idempotencyKey: string | null;
+    lastAttemptAt: Date | null;
+    nextRetryAt: Date | null;
+    responseStatus: number | null;
+    responseBody: string | null;
+    errorKind: WebhookErrorKind | null;
+    createdAt: Date;
+}
+/** Delivery tuning + observability seams. */
+interface WebhookDeliveryConfig {
+    /** Per-attempt timeout (ms). Default 10_000. */
+    timeoutMs?: number;
+    /** Who owns retries. Default `'pluginScheduled'`. */
+    retry?: RetryMode;
+    /** Statuses that permanently deactivate an endpoint. Default `[404, 410, 421]`. */
+    permanentStatuses?: number[];
+    /** Consecutive failures before the circuit breaker deactivates an endpoint. Default 15. */
+    maxConsecutiveFailures?: number;
+    /** Called on a terminal `failed` delivery — the DLQ/alert seam. */
+    onDeliveryFailed?: (delivery: WebhookDelivery) => void | Promise<void>;
+    /** Called when an endpoint is auto-deactivated (permanent status or circuit breaker). */
+    onEndpointDeactivated?: (endpoint: WebhookEndpoint, reason: WebhookDeactivatedReason) => void | Promise<void>;
+    /**
+     * Override the delivery transport (a fetcher `FetchFn`). Defaults to the
+     * SSRF-guarded `ssrfSafeFetch()`. Use for custom transports or to intercept
+     * delivery in tests — **bypasses the SSRF guard**, so only override when you
+     * control the targets.
+     */
+    fetch?: FetchFn;
+}
+/** Options for `emit()`. */
+interface EmitOptions {
+    /** Dedup key — a second `emit` with the same `(endpoint, idempotencyKey)` is a no-op. */
+    idempotencyKey?: string;
+}
+/** Options for `registerEndpoint()`. */
+interface RegisterEndpointOptions {
+    /** Signing secret. If omitted, a CSPRNG secret is generated and returned once. */
+    secret?: string;
+}
+/** Patch accepted by `updateEndpoint()`. */
+interface UpdateEndpointPatch {
+    url?: string;
+    events?: string[];
+    isActive?: boolean;
+}
+/** An endpoint with `secret` removed — the shape returned by `listEndpoints()`/`updateEndpoint()`. */
+type RedactedWebhookEndpoint = Omit<WebhookEndpoint, 'secret'>;
+interface WebhookConfig {
+    /** Event registry. Defaults to {@link import('./builtin-events').builtinEvents}(). */
+    events?: WebhookEventDeclaration[];
+    /** Delivery queue (BYOQ). Defaults to the dev-only `inMemoryQueue()`. */
+    queue?: WebhookQueue;
+    /** Maximum delivery retries. Default 5. */
+    maxRetries?: number;
+    /** Reject `emit()` payloads larger than this many bytes. Default 262144 (256 KB). */
+    maxPayloadBytes?: number;
+    delivery?: WebhookDeliveryConfig;
+}
+/** Distinct, catchable failure codes thrown by `emit()`. */
+type WebhookEmitErrorCode = 'unknown_event' | 'invalid_payload' | 'payload_too_large';
+/** Thrown by `emit()` so callers can branch on `code` instead of string-matching. */
+declare class WebhookEmitError extends Error {
+    readonly code: WebhookEmitErrorCode;
+    constructor(code: WebhookEmitErrorCode, message: string);
+}
+
+/**
+ * Built-in auth events. These go through the same registry + emit path as
+ * user-defined events; the plugin merges them in by default and consumers can
+ * exclude individual ones via `builtinEvents({ exclude })`.
+ *
+ * @module
+ */
+
+/**
+ * The built-in auth event declarations. Pass `{ exclude: [...] }` to drop
+ * individual ones (their auto-emit hook then becomes a no-op).
+ */
+declare function builtinEvents(opts?: {
+    exclude?: string[];
+}): WebhookEventDeclaration[];
+
+/**
+ * Crash-safe bundled queue: polls `webhook_delivery` for due `pending` rows and
+ * drives delivery. The `webhook_delivery` table is the transactional outbox, so
+ * `enqueue` is a no-op — the row already exists and the poller picks it up.
+ * This is the only bundled queue that survives a process restart.
+ *
+ * @module
+ */
+
+declare function databaseQueue(opts?: {
+    pollMs?: number;
+}): WebhookQueue;
+
+/**
+ * `setTimeout`-driven, single-process queue. The **default** when no queue is
+ * configured.
+ *
+ * **Dev-only.** Scheduled retries live in in-process timers, so a restart
+ * **loses every pending retry** — the `webhook_delivery` row stays `pending`
+ * but nothing re-attempts it until the next process runs its startup recovery
+ * sweep (see {@link inMemoryQueue}'s `start`). Use {@link import('./database').databaseQueue}
+ * (or a real broker) in production.
+ *
+ * @module
+ */
+
+declare function inMemoryQueue(): WebhookQueue;
+
+/**
+ * Resolve `url` and throw when it points at a loopback, link-local, RFC1918,
+ * or otherwise non-public address. Exported for tests and for custom delivery
+ * transports that want to reuse fortress's SSRF guard. The built-in transport
+ * (`delivery.ts`) already calls {@link resolveSafeWebhookTarget} and pins the
+ * resolved IP, so callers using it do not need to invoke this themselves.
+ */
+declare function assertSafeWebhookUrl(url: string): Promise<void>;
+
+/**
+ * Webhook delivery plugin for fortress (v1).
+ *
+ * - **Custom events** — declare and `emit()` your own events through the same
+ *   path the built-in auth events use.
+ * - **Bring-Your-Own-Queue** — delivery is always queued; plug in any backend
+ *   via {@link import('./queue/types').WebhookQueue}. Defaults to the dev-only
+ *   {@link inMemoryQueue}; use {@link databaseQueue} (crash-safe) or a broker in prod.
+ * - **Standard Webhooks** signing (HMAC-SHA256), with a stable per-delivery
+ *   `webhook-id` for receiver-side idempotency.
+ * - **SSRF-safe delivery** over `@bajustone/fetcher` with connect-time IP pinning.
+ * - Failure classification, jittered backoff, circuit-breaker auto-deactivation,
+ *   and DLQ observability hooks.
+ *
+ * @module
+ */
+
+/**
+ * Webhook plugin factory. See the module docs for the full feature set.
+ */
+declare function webhook(config?: WebhookConfig): FortressPlugin;
+
+export { type EmitOptions, type RedactedWebhookEndpoint, type RegisterEndpointOptions, type UpdateEndpointPatch, type WebhookConfig, type WebhookDeactivatedReason, type WebhookDelivery, type WebhookDeliveryConfig, WebhookEmitError, type WebhookEmitErrorCode, type WebhookEndpoint, type WebhookErrorKind, type WebhookEventDeclaration, type WebhookQueue, type WebhookQueueContext, type WebhookQueueJob, assertSafeWebhookUrl, builtinEvents, databaseQueue, inMemoryQueue, webhook };

package/dist/plugins/webhook.d.ts

@@ -0,0 +1,254 @@
+import { S as StandardSchemaV1, F as FortressPlugin } from '../config-B2366s_G.js';
+import { FetchFn } from '@bajustone/fetcher';
+import { D as DatabaseAdapter } from '../index-CxEkfCA0.js';
+import '../jwt.js';
+import '../types-et0R8tsC.js';
+import '../auth-service-BkzZkWfH.js';
+
+/**
+ * Webhook delivery over `@bajustone/fetcher`.
+ *
+ * fetcher is 100% native `fetch` and does **no** IP pinning of its own, so the
+ * SSRF guard must live *inside* the transport: {@link ssrfSafeFetch} is a
+ * fetcher `FetchFn` that resolves + validates the target and issues the request
+ * through `node:https` with a custom `lookup` that pins the connection to the
+ * resolved IP — closing the DNS-rebinding window. A plain fetch (or a
+ * pre-flight check followed by a normal fetch) would re-resolve DNS and reopen
+ * that window, so the guard MUST be the transport.
+ *
+ * @module
+ */
+
+/** How retries are handled for a delivery client. See the webhook config docs. */
+type RetryMode = 'pluginScheduled' | 'inProcess' | 'queue';
+
+/**
+ * Bring-Your-Own-Queue interface. Delivery is always queued; consumers can
+ * back it with any system (in-memory, DB, BullMQ, SQS, Cloudflare Queues,
+ * Inngest, …) by implementing this small surface.
+ *
+ * @module
+ */
+
+/** One unit of delivery work — a single attempt of a single delivery row. */
+interface WebhookQueueJob {
+    deliveryId: string;
+    endpointId: string;
+    eventType: string;
+    /** 1-based attempt number. */
+    attempt: number;
+    /** When this attempt should run (retries); absent means "now". */
+    scheduledFor?: Date;
+}
+/** Context handed to {@link WebhookQueue.start} so fortress-aware queues can reach the DB. */
+interface WebhookQueueContext {
+    /** The fortress database adapter — used by the database queue to poll, and for the startup recovery sweep. */
+    db: DatabaseAdapter;
+}
+interface WebhookQueue {
+    /**
+     * If true, the plugin re-throws on failed delivery and the queue is expected
+     * to retry per its own policy (BullMQ/SQS/Inngest). If false/absent, the
+     * plugin schedules retries itself.
+     */
+    handlesRetries?: boolean;
+    /** Enqueue a delivery job. (A no-op for the database queue — the table IS the queue.) */
+    enqueue: (job: WebhookQueueJob) => Promise<void>;
+    /**
+     * Optional worker registration. Pull queues (in-memory, database) implement
+     * this; push/serverless queues (Cloudflare Queues with a separate consumer,
+     * Inngest, …) leave it undefined. Returns a teardown the consumer calls on
+     * shutdown. Implementations SHOULD run a startup recovery sweep here —
+     * re-enqueue rows left `pending` by a prior process — so at-least-once holds
+     * across restarts.
+     */
+    start?: (handler: (job: WebhookQueueJob) => Promise<void>, ctx: WebhookQueueContext) => Promise<() => Promise<void>>;
+}
+
+/**
+ * Public types for the webhook plugin v1 (custom events + Bring-Your-Own-Queue).
+ *
+ * @module
+ */
+
+/** A fortress lifecycle hook a built-in event auto-emits from. */
+type BuiltinEventSource = 'afterLogin' | 'onLoginFailure' | 'beforeLogout' | 'afterRegister' | 'afterTokenRefresh';
+/**
+ * Declares an event consumers (or the built-ins) can emit. Built-in auth events
+ * and user-defined events share this one shape and the same emit path.
+ */
+interface WebhookEventDeclaration<S extends StandardSchemaV1 = StandardSchemaV1> {
+    /** Dot-cased event name, e.g. `auth.login.success` or `order.paid`. */
+    name: string;
+    description?: string;
+    /** Standard Schema V1 validator (fortress builder, fetcher builder, Zod, …); the payload is validated at `emit()` time. */
+    schema?: S;
+    /** If set, the plugin auto-emits this event from the named fortress hook. */
+    source?: BuiltinEventSource;
+}
+/** Stable delivery failure taxonomy persisted in `webhook_delivery.error_kind`. */
+type WebhookErrorKind = 'http' | 'network';
+/** Stable endpoint deactivation reason taxonomy. */
+type WebhookDeactivatedReason = `permanent_${number}` | 'too_many_failures';
+/** A registered delivery endpoint. `secret` is redacted from `listEndpoints()`. */
+interface WebhookEndpoint {
+    id: string;
+    url: string;
+    events: string;
+    secret: string;
+    isActive: boolean;
+    deactivatedReason: WebhookDeactivatedReason | null;
+    consecutiveFailures: number;
+    createdAt: Date;
+}
+/** A persisted delivery attempt row — the transactional outbox record. */
+interface WebhookDelivery {
+    id: string;
+    endpointId: string;
+    eventType: string;
+    payload: string;
+    status: 'pending' | 'success' | 'failed';
+    attempts: number;
+    idempotencyKey: string | null;
+    lastAttemptAt: Date | null;
+    nextRetryAt: Date | null;
+    responseStatus: number | null;
+    responseBody: string | null;
+    errorKind: WebhookErrorKind | null;
+    createdAt: Date;
+}
+/** Delivery tuning + observability seams. */
+interface WebhookDeliveryConfig {
+    /** Per-attempt timeout (ms). Default 10_000. */
+    timeoutMs?: number;
+    /** Who owns retries. Default `'pluginScheduled'`. */
+    retry?: RetryMode;
+    /** Statuses that permanently deactivate an endpoint. Default `[404, 410, 421]`. */
+    permanentStatuses?: number[];
+    /** Consecutive failures before the circuit breaker deactivates an endpoint. Default 15. */
+    maxConsecutiveFailures?: number;
+    /** Called on a terminal `failed` delivery — the DLQ/alert seam. */
+    onDeliveryFailed?: (delivery: WebhookDelivery) => void | Promise<void>;
+    /** Called when an endpoint is auto-deactivated (permanent status or circuit breaker). */
+    onEndpointDeactivated?: (endpoint: WebhookEndpoint, reason: WebhookDeactivatedReason) => void | Promise<void>;
+    /**
+     * Override the delivery transport (a fetcher `FetchFn`). Defaults to the
+     * SSRF-guarded `ssrfSafeFetch()`. Use for custom transports or to intercept
+     * delivery in tests — **bypasses the SSRF guard**, so only override when you
+     * control the targets.
+     */
+    fetch?: FetchFn;
+}
+/** Options for `emit()`. */
+interface EmitOptions {
+    /** Dedup key — a second `emit` with the same `(endpoint, idempotencyKey)` is a no-op. */
+    idempotencyKey?: string;
+}
+/** Options for `registerEndpoint()`. */
+interface RegisterEndpointOptions {
+    /** Signing secret. If omitted, a CSPRNG secret is generated and returned once. */
+    secret?: string;
+}
+/** Patch accepted by `updateEndpoint()`. */
+interface UpdateEndpointPatch {
+    url?: string;
+    events?: string[];
+    isActive?: boolean;
+}
+/** An endpoint with `secret` removed — the shape returned by `listEndpoints()`/`updateEndpoint()`. */
+type RedactedWebhookEndpoint = Omit<WebhookEndpoint, 'secret'>;
+interface WebhookConfig {
+    /** Event registry. Defaults to {@link import('./builtin-events').builtinEvents}(). */
+    events?: WebhookEventDeclaration[];
+    /** Delivery queue (BYOQ). Defaults to the dev-only `inMemoryQueue()`. */
+    queue?: WebhookQueue;
+    /** Maximum delivery retries. Default 5. */
+    maxRetries?: number;
+    /** Reject `emit()` payloads larger than this many bytes. Default 262144 (256 KB). */
+    maxPayloadBytes?: number;
+    delivery?: WebhookDeliveryConfig;
+}
+/** Distinct, catchable failure codes thrown by `emit()`. */
+type WebhookEmitErrorCode = 'unknown_event' | 'invalid_payload' | 'payload_too_large';
+/** Thrown by `emit()` so callers can branch on `code` instead of string-matching. */
+declare class WebhookEmitError extends Error {
+    readonly code: WebhookEmitErrorCode;
+    constructor(code: WebhookEmitErrorCode, message: string);
+}
+
+/**
+ * Built-in auth events. These go through the same registry + emit path as
+ * user-defined events; the plugin merges them in by default and consumers can
+ * exclude individual ones via `builtinEvents({ exclude })`.
+ *
+ * @module
+ */
+
+/**
+ * The built-in auth event declarations. Pass `{ exclude: [...] }` to drop
+ * individual ones (their auto-emit hook then becomes a no-op).
+ */
+declare function builtinEvents(opts?: {
+    exclude?: string[];
+}): WebhookEventDeclaration[];
+
+/**
+ * Crash-safe bundled queue: polls `webhook_delivery` for due `pending` rows and
+ * drives delivery. The `webhook_delivery` table is the transactional outbox, so
+ * `enqueue` is a no-op — the row already exists and the poller picks it up.
+ * This is the only bundled queue that survives a process restart.
+ *
+ * @module
+ */
+
+declare function databaseQueue(opts?: {
+    pollMs?: number;
+}): WebhookQueue;
+
+/**
+ * `setTimeout`-driven, single-process queue. The **default** when no queue is
+ * configured.
+ *
+ * **Dev-only.** Scheduled retries live in in-process timers, so a restart
+ * **loses every pending retry** — the `webhook_delivery` row stays `pending`
+ * but nothing re-attempts it until the next process runs its startup recovery
+ * sweep (see {@link inMemoryQueue}'s `start`). Use {@link import('./database').databaseQueue}
+ * (or a real broker) in production.
+ *
+ * @module
+ */
+
+declare function inMemoryQueue(): WebhookQueue;
+
+/**
+ * Resolve `url` and throw when it points at a loopback, link-local, RFC1918,
+ * or otherwise non-public address. Exported for tests and for custom delivery
+ * transports that want to reuse fortress's SSRF guard. The built-in transport
+ * (`delivery.ts`) already calls {@link resolveSafeWebhookTarget} and pins the
+ * resolved IP, so callers using it do not need to invoke this themselves.
+ */
+declare function assertSafeWebhookUrl(url: string): Promise<void>;
+
+/**
+ * Webhook delivery plugin for fortress (v1).
+ *
+ * - **Custom events** — declare and `emit()` your own events through the same
+ *   path the built-in auth events use.
+ * - **Bring-Your-Own-Queue** — delivery is always queued; plug in any backend
+ *   via {@link import('./queue/types').WebhookQueue}. Defaults to the dev-only
+ *   {@link inMemoryQueue}; use {@link databaseQueue} (crash-safe) or a broker in prod.
+ * - **Standard Webhooks** signing (HMAC-SHA256), with a stable per-delivery
+ *   `webhook-id` for receiver-side idempotency.
+ * - **SSRF-safe delivery** over `@bajustone/fetcher` with connect-time IP pinning.
+ * - Failure classification, jittered backoff, circuit-breaker auto-deactivation,
+ *   and DLQ observability hooks.
+ *
+ * @module
+ */
+
+/**
+ * Webhook plugin factory. See the module docs for the full feature set.
+ */
+declare function webhook(config?: WebhookConfig): FortressPlugin;
+
+export { type EmitOptions, type RedactedWebhookEndpoint, type RegisterEndpointOptions, type UpdateEndpointPatch, type WebhookConfig, type WebhookDeactivatedReason, type WebhookDelivery, type WebhookDeliveryConfig, WebhookEmitError, type WebhookEmitErrorCode, type WebhookEndpoint, type WebhookErrorKind, type WebhookEventDeclaration, type WebhookQueue, type WebhookQueueContext, type WebhookQueueJob, assertSafeWebhookUrl, builtinEvents, databaseQueue, inMemoryQueue, webhook };