@bajustone/fortress 1.0.0-rc.1

package/src/plugins/webhook/queue/database.ts

@@ -0,0 +1,67 @@
+/**
+ * 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
+ */
+
+import type { WebhookDelivery } from '../types';
+import type { WebhookQueue } from './types';
+
+export function databaseQueue(opts: { pollMs?: number } = {}): WebhookQueue {
+  const pollMs = opts.pollMs ?? 10_000;
+
+  return {
+    async enqueue() {
+      // No-op: the webhook_delivery row IS the queue entry; the poller delivers it.
+    },
+
+    async start(handler, ctx) {
+      let stopped = false;
+      let timer: ReturnType<typeof setTimeout> | null = null;
+
+      const poll = async (): Promise<void> => {
+        if (stopped)
+          return;
+        try {
+          const due = await ctx.db.findMany<WebhookDelivery>({
+            model: 'webhook_delivery',
+            where: [
+              { field: 'status', operator: '=', value: 'pending' },
+              { field: 'nextRetryAt', operator: 'lte', value: new Date() },
+            ],
+            sortBy: { field: 'nextRetryAt', direction: 'asc' },
+          });
+          for (const delivery of due) {
+            if (stopped)
+              break;
+            // Sequential, so a slow delivery doesn't get double-picked next tick.
+            await handler({
+              deliveryId: delivery.id,
+              endpointId: delivery.endpointId,
+              eventType: delivery.eventType,
+              attempt: delivery.attempts + 1,
+              scheduledFor: delivery.nextRetryAt ?? undefined,
+            }).catch(() => {});
+          }
+        }
+        catch {
+          // Swallow poll errors (e.g. transient DB hiccup); retry next tick.
+        }
+        if (!stopped)
+          timer = setTimeout(() => void poll(), pollMs);
+      };
+
+      // First poll runs immediately and doubles as the startup recovery sweep.
+      timer = setTimeout(() => void poll(), 0);
+
+      return async () => {
+        stopped = true;
+        if (timer)
+          clearTimeout(timer);
+      };
+    },
+  } satisfies WebhookQueue;
+}

package/src/plugins/webhook/queue/in-memory.test.ts

@@ -0,0 +1,48 @@
+import type { DatabaseAdapter } from '../../../adapters/database';
+import type { WebhookQueueContext, WebhookQueueJob } from './types';
+import { describe, expect, it } from 'vitest';
+import { inMemoryQueue } from './in-memory';
+
+function ctxWithPending(pending: unknown[] = []): WebhookQueueContext {
+  return { db: { findMany: async () => pending } as unknown as DatabaseAdapter };
+}
+const tick = (): Promise<void> => new Promise(resolve => setTimeout(resolve, 5));
+
+describe('inMemoryQueue', () => {
+  it('delivers an enqueued job to the handler', async () => {
+    const jobs: WebhookQueueJob[] = [];
+    const queue = inMemoryQueue();
+    const stop = await queue.start!(async job => void jobs.push(job), ctxWithPending());
+
+    await queue.enqueue({ deliveryId: 'd1', endpointId: 'e1', eventType: 'order.paid', attempt: 1 });
+    await tick();
+
+    expect(jobs.map(j => j.deliveryId)).toEqual(['d1']);
+    await stop();
+  });
+
+  it('runs a startup recovery sweep over pending rows', async () => {
+    const jobs: WebhookQueueJob[] = [];
+    const queue = inMemoryQueue();
+    const stop = await queue.start!(
+      async job => void jobs.push(job),
+      ctxWithPending([{ id: 'd9', endpointId: 'e9', eventType: 'auth.login.success', attempts: 2, nextRetryAt: null }]),
+    );
+    await tick();
+
+    expect(jobs[0]).toMatchObject({ deliveryId: 'd9', attempt: 3 });
+    await stop();
+  });
+
+  it('stops delivering after teardown', async () => {
+    const jobs: WebhookQueueJob[] = [];
+    const queue = inMemoryQueue();
+    const stop = await queue.start!(async job => void jobs.push(job), ctxWithPending());
+    await stop();
+
+    await queue.enqueue({ deliveryId: 'd2', endpointId: 'e2', eventType: 'order.paid', attempt: 1 });
+    await tick();
+
+    expect(jobs).toHaveLength(0);
+  });
+});

package/src/plugins/webhook/queue/in-memory.ts

@@ -0,0 +1,71 @@
+/**
+ * `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
+ */
+
+import type { WebhookDelivery } from '../types';
+import type { WebhookQueue, WebhookQueueJob } from './types';
+
+export function inMemoryQueue(): WebhookQueue {
+  let handler: ((job: WebhookQueueJob) => Promise<void>) | null = null;
+  const timers = new Set<ReturnType<typeof setTimeout>>();
+  // Serialize handler execution: jobs run one at a time so two deliveries to the
+  // same endpoint never overlap (concurrent runs would race the circuit-breaker
+  // `consecutiveFailures` read-modify-write).
+  let chain: Promise<void> = Promise.resolve();
+
+  const enqueue = async (job: WebhookQueueJob): Promise<void> => {
+    const delay = job.scheduledFor ? Math.max(0, job.scheduledFor.getTime() - Date.now()) : 0;
+    const dispatch = (): void => {
+      const current = handler;
+      if (!current)
+        return;
+      chain = chain.then(() => current(job)).catch(() => {});
+    };
+    if (delay === 0) {
+      queueMicrotask(dispatch);
+    }
+    else {
+      const timer = setTimeout(() => {
+        timers.delete(timer);
+        dispatch();
+      }, delay);
+      timers.add(timer);
+    }
+  };
+
+  return {
+    enqueue,
+    async start(h, ctx) {
+      handler = h;
+      // Startup recovery sweep: re-enqueue rows a prior process left pending.
+      const pending = await ctx.db.findMany<WebhookDelivery>({
+        model: 'webhook_delivery',
+        where: [{ field: 'status', operator: '=', value: 'pending' }],
+      });
+      for (const delivery of pending) {
+        void enqueue({
+          deliveryId: delivery.id,
+          endpointId: delivery.endpointId,
+          eventType: delivery.eventType,
+          attempt: delivery.attempts + 1,
+          scheduledFor: delivery.nextRetryAt ?? undefined,
+        });
+      }
+      return async () => {
+        for (const timer of timers)
+          clearTimeout(timer);
+        timers.clear();
+        handler = null;
+      };
+    },
+  };
+}

package/src/plugins/webhook/queue/types.ts

@@ -0,0 +1,51 @@
+/**
+ * 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
+ */
+
+import type { DatabaseAdapter } from '../../../adapters/database';
+
+/** One unit of delivery work — a single attempt of a single delivery row. */
+export 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. */
+export interface WebhookQueueContext {
+  /** The fortress database adapter — used by the database queue to poll, and for the startup recovery sweep. */
+  db: DatabaseAdapter;
+}
+
+export 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>>;
+}

package/src/plugins/webhook/registry.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest';
+import { BUILTIN_EVENT_NAMES, builtinEvents } from './builtin-events';
+import { assertEventRegistry, createEventRegistry } from './registry';
+
+describe('webhook event registry', () => {
+  it('builtinEvents returns the five auth events in order', () => {
+    expect(builtinEvents().map(e => e.name)).toEqual([
+      'auth.login.success',
+      'auth.login.failure',
+      'auth.logout',
+      'auth.user.registered',
+      'auth.token.refreshed',
+    ]);
+    expect(BUILTIN_EVENT_NAMES.has('auth.login.success')).toBe(true);
+  });
+
+  it('builtinEvents({ exclude }) drops only the excluded events', () => {
+    const events = builtinEvents({ exclude: ['auth.logout'] });
+    expect(events).toHaveLength(4);
+    expect(events.find(e => e.name === 'auth.logout')).toBeUndefined();
+  });
+
+  it('assertEventRegistry rejects duplicate names', () => {
+    expect(() => assertEventRegistry([{ name: 'order.paid' }, { name: 'order.paid' }])).toThrow(/Duplicate/);
+  });
+
+  it('assertEventRegistry rejects an empty name', () => {
+    expect(() => assertEventRegistry([{ name: '' }])).toThrow();
+  });
+
+  it('assertEventRegistry rejects an unknown source', () => {
+    expect(() => assertEventRegistry([{ name: 'x', source: 'nope' as never }])).toThrow(/source/);
+  });
+
+  it('createEventRegistry exposes lookup + the source→name map', () => {
+    const reg = createEventRegistry([
+      ...builtinEvents({ exclude: ['auth.logout'] }),
+      { name: 'order.paid' },
+    ]);
+    expect(reg.has('order.paid')).toBe(true);
+    expect(reg.get('auth.login.success')?.source).toBe('afterLogin');
+    expect(reg.names()).toContain('order.paid');
+
+    const sources = reg.sources();
+    expect(sources.get('afterLogin')).toBe('auth.login.success');
+    expect(sources.has('beforeLogout')).toBe(false); // excluded above
+  });
+});

package/src/plugins/webhook/registry.ts

@@ -0,0 +1,64 @@
+/**
+ * Event registry — the single source of truth for which events may be emitted.
+ * Validates declarations at construction and provides name lookup.
+ *
+ * @module
+ */
+
+import type { BuiltinEventSource, WebhookEventDeclaration } from './types';
+
+export interface EventRegistry {
+  /** All declarations, in registration order. */
+  list: () => WebhookEventDeclaration[];
+  /** All event names, in registration order. */
+  names: () => string[];
+  get: (name: string) => WebhookEventDeclaration | undefined;
+  has: (name: string) => boolean;
+  /** Map of built-in hook source → event name, for hook binding. */
+  sources: () => Map<BuiltinEventSource, string>;
+}
+
+const VALID_SOURCES: ReadonlySet<string> = new Set<BuiltinEventSource>([
+  'afterLogin',
+  'onLoginFailure',
+  'beforeLogout',
+  'afterRegister',
+  'afterTokenRefresh',
+]);
+
+/**
+ * Validate an event registry: every declaration needs a non-empty string name,
+ * names must be unique, and any `source` must name a real hook. Throws on the
+ * first violation (a construction-time bug, not a runtime condition).
+ */
+export function assertEventRegistry(events: WebhookEventDeclaration[]): void {
+  const seen = new Set<string>();
+  for (const event of events) {
+    if (typeof event.name !== 'string' || event.name.length === 0)
+      throw new TypeError('Webhook event declaration requires a non-empty string `name`');
+    if (seen.has(event.name))
+      throw new Error(`Duplicate webhook event name: ${event.name}`);
+    seen.add(event.name);
+    if (event.source !== undefined && !VALID_SOURCES.has(event.source))
+      throw new Error(`Webhook event '${event.name}' has an unknown source: ${event.source}`);
+  }
+}
+
+/** Build a validated {@link EventRegistry} from a list of declarations. */
+export function createEventRegistry(events: WebhookEventDeclaration[]): EventRegistry {
+  assertEventRegistry(events);
+  const ordered = [...events];
+  const byName = new Map(ordered.map(e => [e.name, e]));
+  const sources = new Map<BuiltinEventSource, string>();
+  for (const event of ordered) {
+    if (event.source && !sources.has(event.source))
+      sources.set(event.source, event.name);
+  }
+  return {
+    list: () => ordered.map(e => ({ ...e })),
+    names: () => ordered.map(e => e.name),
+    get: name => byName.get(name),
+    has: name => byName.has(name),
+    sources: () => new Map(sources),
+  };
+}

package/src/plugins/webhook/signing.ts

@@ -0,0 +1,45 @@
+/**
+ * Standard Webhooks signing — HMAC-SHA256 over `{id}.{timestamp}.{body}`.
+ *
+ * @see https://www.standardwebhooks.com
+ * @module
+ */
+
+/**
+ * Sign a webhook payload per the Standard Webhooks spec: HMAC-SHA256 over
+ * `{webhookId}.{timestamp}.{body}`, base64-encoded. Uses Web Crypto so it runs
+ * on every fortress runtime.
+ */
+export async function signPayload(secret: string, webhookId: string, timestamp: number, body: string): Promise<string> {
+  const content = `${webhookId}.${timestamp}.${body}`;
+  const key = await crypto.subtle.importKey(
+    'raw',
+    new TextEncoder().encode(secret),
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    ['sign'],
+  );
+  const sig = await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(content));
+  return btoa(String.fromCharCode(...new Uint8Array(sig)));
+}
+
+/**
+ * Build the Standard Webhooks delivery headers for one attempt.
+ *
+ * `webhookId` must be **stable across retries of the same delivery** (receivers
+ * use it as their idempotency key); only `timestamp` changes per attempt. The
+ * caller is responsible for passing a stable id (e.g. `msg_<deliveryId>`).
+ */
+export async function signatureHeaders(
+  secret: string,
+  webhookId: string,
+  timestamp: number,
+  body: string,
+): Promise<Record<string, string>> {
+  const signature = await signPayload(secret, webhookId, timestamp, body);
+  return {
+    'webhook-id': webhookId,
+    'webhook-timestamp': String(timestamp),
+    'webhook-signature': `v1,${signature}`,
+  };
+}

package/src/plugins/webhook/ssrf.ts

@@ -0,0 +1,198 @@
+/**
+ * SSRF protection for webhook delivery.
+ *
+ * Webhook URLs are consumer-supplied, so delivery is a live SSRF surface
+ * (cloud metadata endpoints, internal services). This module resolves the
+ * target host, refuses private/loopback/link-local/CGNAT addresses (IPv4,
+ * IPv6, `::ffff:`-mapped, and `64:ff9b::/96` NAT64 forms), and returns the *resolved IP* so the
+ * caller can pin the connection to it — closing the DNS-rebinding window
+ * between validation and connect.
+ *
+ * Lifted verbatim from the original `index.ts` (logic unchanged); the delivery
+ * transport (`delivery.ts`) pins {@link SafeWebhookTarget.address} via a custom
+ * `lookup`, and {@link assertSafeWebhookUrl} is exported for custom transports.
+ *
+ * @module
+ */
+
+import { lookup } from 'node:dns/promises';
+import { isIP } from 'node:net';
+
+/** A validated webhook target plus the exact resolved IP to pin the connection to. */
+export interface SafeWebhookTarget {
+  url: URL;
+  address: string;
+  family: 4 | 6;
+}
+
+function stripIpv6Brackets(host: string): string {
+  return host.startsWith('[') && host.endsWith(']') ? host.slice(1, -1) : host;
+}
+
+function parseIpv4(address: string): number[] | null {
+  const parts = address.split('.');
+  if (parts.length !== 4)
+    return null;
+  const octets = parts.map(part => Number(part));
+  if (octets.some(octet => !Number.isInteger(octet) || octet < 0 || octet > 255))
+    return null;
+  return octets;
+}
+
+function extractMappedIpv4(address: string): string | null {
+  const lower = stripIpv6Brackets(address).toLowerCase();
+  if (!lower.startsWith('::ffff:'))
+    return null;
+  const tail = lower.slice('::ffff:'.length);
+  if (parseIpv4(tail))
+    return tail;
+  const words = tail.split(':');
+  if (words.length !== 2)
+    return null;
+  const hi = Number.parseInt(words[0], 16);
+  const lo = Number.parseInt(words[1], 16);
+  if (!Number.isInteger(hi) || !Number.isInteger(lo) || hi < 0 || hi > 0xFFFF || lo < 0 || lo > 0xFFFF)
+    return null;
+  return `${hi >> 8}.${hi & 0xFF}.${lo >> 8}.${lo & 0xFF}`;
+}
+
+function isPrivateIpv4(address: string): boolean {
+  const octets = parseIpv4(address);
+  if (!octets)
+    return false;
+  const [a, b] = octets;
+  return a === 0
+    || a === 10
+    || a === 127
+    || (a === 100 && b >= 64 && b <= 127)
+    || (a === 169 && b === 254)
+    || (a === 172 && b >= 16 && b <= 31)
+    || (a === 192 && b === 168)
+    || (a === 198 && (b === 18 || b === 19))
+    || a >= 224;
+}
+
+/**
+ * Expand an IPv6 literal to its 8 16-bit groups, handling `::` compression and
+ * a trailing embedded dotted-quad. Returns null for anything not well-formed.
+ */
+function ipv6Groups(address: string): number[] | null {
+  let host = stripIpv6Brackets(address).toLowerCase();
+  const zone = host.indexOf('%');
+  if (zone !== -1)
+    host = host.slice(0, zone);
+  if (!host.includes(':'))
+    return null;
+
+  // Fold a trailing dotted-quad (e.g. `64:ff9b::1.2.3.4`) into two hex groups.
+  if (host.includes('.')) {
+    const lastColon = host.lastIndexOf(':');
+    const v4 = parseIpv4(host.slice(lastColon + 1));
+    if (!v4)
+      return null;
+    const hi = ((v4[0] << 8) | v4[1]).toString(16);
+    const lo = ((v4[2] << 8) | v4[3]).toString(16);
+    host = `${host.slice(0, lastColon + 1)}${hi}:${lo}`;
+  }
+
+  const halves = host.split('::');
+  if (halves.length > 2)
+    return null;
+  const head = halves[0] === '' ? [] : halves[0].split(':');
+  const tail = halves.length === 2 ? (halves[1] === '' ? [] : halves[1].split(':')) : null;
+
+  let parts: string[];
+  if (tail === null) {
+    parts = head; // no `::` — must already be 8 groups
+  }
+  else {
+    const missing = 8 - head.length - tail.length;
+    if (missing < 1)
+      return null;
+    parts = [...head, ...Array.from<string>({ length: missing }).fill('0'), ...tail];
+  }
+  if (parts.length !== 8)
+    return null;
+
+  const groups = parts.map(part => Number.parseInt(part, 16));
+  if (groups.some(g => !Number.isInteger(g) || g < 0 || g > 0xFFFF))
+    return null;
+  return groups;
+}
+
+/**
+ * Decode the IPv4 embedded in an RFC 6052 NAT64 well-known-prefix (`64:ff9b::/96`)
+ * address, or null if `address` isn't in that prefix. On a NAT64/DNS64 network
+ * the gateway connects to this translated IPv4, so it must face the same
+ * private-range checks — `64:ff9b::a9fe:a9fe` is the cloud metadata IP.
+ */
+function extractNat64Ipv4(address: string): string | null {
+  const groups = ipv6Groups(address);
+  if (!groups)
+    return null;
+  if (groups[0] === 0x0064 && groups[1] === 0xFF9B
+    && groups[2] === 0 && groups[3] === 0 && groups[4] === 0 && groups[5] === 0) {
+    const g6 = groups[6];
+    const g7 = groups[7];
+    return `${(g6 >> 8) & 0xFF}.${g6 & 0xFF}.${(g7 >> 8) & 0xFF}.${g7 & 0xFF}`;
+  }
+  return null;
+}
+
+/** `true` if `address` is a loopback/private/link-local/CGNAT/multicast IP (v4, v6, `::ffff:` mapped, or `64:ff9b::/96` NAT64). */
+export function isPrivateIp(address: string): boolean {
+  const host = stripIpv6Brackets(address).toLowerCase();
+  const mapped = extractMappedIpv4(host);
+  if (mapped)
+    return isPrivateIpv4(mapped);
+  const nat64 = extractNat64Ipv4(host);
+  if (nat64)
+    return isPrivateIpv4(nat64);
+  if (isPrivateIpv4(host))
+    return true;
+  if (host === '::' || host === '::1')
+    return true;
+  return host.startsWith('fc')
+    || host.startsWith('fd')
+    || host.startsWith('fe80:')
+    || host.startsWith('ff');
+}
+
+/**
+ * Resolve `url` to a {@link SafeWebhookTarget}, throwing when it is not https
+ * or resolves to a loopback/private/link-local/CGNAT address (including
+ * IPv4-mapped IPv6 forms like `::ffff:169.254.169.254`) or a `localhost`/
+ * `.local`/`.localhost` host. The returned `address`/`family` is the exact IP
+ * the caller must pin the connection to.
+ */
+export async function resolveSafeWebhookTarget(url: string): Promise<SafeWebhookTarget> {
+  const parsed = new URL(url);
+  if (parsed.protocol !== 'https:')
+    throw new Error('Webhook URL must use https');
+  const host = stripIpv6Brackets(parsed.hostname.toLowerCase());
+  if (host === 'localhost' || host.endsWith('.localhost') || host.endsWith('.local'))
+    throw new Error('Webhook URL host is not allowed');
+
+  const literalFamily = isIP(host);
+  const records = literalFamily === 0
+    ? await lookup(host, { all: true, verbatim: true })
+    : [{ address: host, family: literalFamily }];
+  if (records.length === 0)
+    throw new Error('Webhook URL host did not resolve');
+  if (records.some(record => isPrivateIp(record.address)))
+    throw new Error('Webhook URL resolves to a private address');
+
+  const selected = records[0];
+  return { url: parsed, address: selected.address, family: selected.family as 4 | 6 };
+}
+
+/**
+ * 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.
+ */
+export async function assertSafeWebhookUrl(url: string): Promise<void> {
+  await resolveSafeWebhookTarget(url);
+}