@bajustone/fortress 1.0.0-rc.1

package/dist/plugins/webhook.js

@@ -0,0 +1,789 @@
+// src/plugins/webhook/index.ts
+import { Buffer as Buffer2 } from "buffer";
+
+// src/plugins/webhook/builtin-events.ts
+var BUILTIN = [
+  { name: "auth.login.success", source: "afterLogin", description: "A user authenticated successfully." },
+  { name: "auth.login.failure", source: "onLoginFailure", description: "A login attempt failed." },
+  { name: "auth.logout", source: "beforeLogout", description: "A user logged out." },
+  { name: "auth.user.registered", source: "afterRegister", description: "A new user was registered." },
+  { name: "auth.token.refreshed", source: "afterTokenRefresh", description: "An access token was refreshed." }
+];
+var BUILTIN_EVENT_NAMES = new Set(BUILTIN.map((e) => e.name));
+function builtinEvents(opts = {}) {
+  const all = BUILTIN.map((e) => ({ ...e }));
+  return opts.exclude ? all.filter((e) => !opts.exclude.includes(e.name)) : all;
+}
+
+// src/plugins/webhook/delivery.ts
+import { Buffer } from "buffer";
+import { request as httpsRequest } from "https";
+import { createFetch } from "@bajustone/fetcher";
+
+// src/plugins/webhook/ssrf.ts
+import { lookup } from "dns/promises";
+import { isIP } from "net";
+function stripIpv6Brackets(host) {
+  return host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
+}
+function parseIpv4(address) {
+  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) {
+  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 > 65535 || lo < 0 || lo > 65535)
+    return null;
+  return `${hi >> 8}.${hi & 255}.${lo >> 8}.${lo & 255}`;
+}
+function isPrivateIpv4(address) {
+  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;
+}
+function ipv6Groups(address) {
+  let host = stripIpv6Brackets(address).toLowerCase();
+  const zone = host.indexOf("%");
+  if (zone !== -1)
+    host = host.slice(0, zone);
+  if (!host.includes(":"))
+    return null;
+  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;
+  if (tail === null) {
+    parts = head;
+  } else {
+    const missing = 8 - head.length - tail.length;
+    if (missing < 1)
+      return null;
+    parts = [...head, ...Array.from({ 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 > 65535))
+    return null;
+  return groups;
+}
+function extractNat64Ipv4(address) {
+  const groups = ipv6Groups(address);
+  if (!groups)
+    return null;
+  if (groups[0] === 100 && groups[1] === 65435 && groups[2] === 0 && groups[3] === 0 && groups[4] === 0 && groups[5] === 0) {
+    const g6 = groups[6];
+    const g7 = groups[7];
+    return `${g6 >> 8 & 255}.${g6 & 255}.${g7 >> 8 & 255}.${g7 & 255}`;
+  }
+  return null;
+}
+function isPrivateIp(address) {
+  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");
+}
+async function resolveSafeWebhookTarget(url) {
+  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 };
+}
+async function assertSafeWebhookUrl(url) {
+  await resolveSafeWebhookTarget(url);
+}
+
+// src/plugins/webhook/delivery.ts
+function ssrfSafeFetch() {
+  return async (req) => {
+    const target = await resolveSafeWebhookTarget(req.url);
+    const body = req.method === "GET" || req.method === "HEAD" ? void 0 : await req.text();
+    const headers = {};
+    req.headers.forEach((value, key) => {
+      headers[key] = value;
+    });
+    return new Promise((resolve, reject) => {
+      const clientReq = httpsRequest(
+        {
+          protocol: target.url.protocol,
+          hostname: target.url.hostname,
+          port: target.url.port || 443,
+          path: `${target.url.pathname}${target.url.search}`,
+          method: req.method,
+          headers,
+          // Pin the connection to the exact validated IP (DNS-rebind defense).
+          lookup: (_hostname, _options, cb) => cb(null, target.address, target.family)
+        },
+        (res) => {
+          const chunks = [];
+          res.on("data", (chunk) => chunks.push(chunk));
+          res.on("end", () => {
+            const resHeaders = new Headers();
+            for (const [key, value] of Object.entries(res.headers)) {
+              if (typeof value === "string")
+                resHeaders.set(key, value);
+              else if (Array.isArray(value))
+                resHeaders.set(key, value.join(", "));
+            }
+            const status = res.statusCode && res.statusCode >= 200 ? res.statusCode : 502;
+            resolve(new Response(Buffer.concat(chunks), { status, headers: resHeaders }));
+          });
+        }
+      );
+      if (req.signal) {
+        if (req.signal.aborted)
+          clientReq.destroy(new Error("aborted"));
+        else
+          req.signal.addEventListener("abort", () => clientReq.destroy(new Error("aborted")), { once: true });
+      }
+      clientReq.on("error", reject);
+      clientReq.end(body);
+    });
+  };
+}
+function createDeliveryClient(opts) {
+  return createFetch({
+    baseUrl: "",
+    fetch: opts.fetch ?? ssrfSafeFetch(),
+    timeout: opts.timeoutMs ?? 1e4,
+    ...opts.retryMode === "inProcess" ? {
+      retry: {
+        attempts: 5,
+        methods: ["POST"],
+        backoff: 5e3,
+        factor: 2,
+        maxBackoff: 5 * 6e4
+      }
+    } : {}
+  });
+}
+async function safeReadBody(response) {
+  try {
+    const text = await response.text();
+    return text.slice(0, 2048);
+  } catch {
+    return null;
+  }
+}
+async function deliver(client, url, body, headers) {
+  const response = await client.post(url, {
+    body,
+    headers: { "Content-Type": "application/json", ...headers }
+  });
+  if (response.ok)
+    return { ok: true, status: response.status };
+  const transport = response.status === 0;
+  return {
+    ok: false,
+    kind: transport ? "network" : "http",
+    status: transport ? null : response.status,
+    responseBody: transport ? null : await safeReadBody(response),
+    message: transport ? "Transport error (network, timeout, or blocked target)" : `HTTP ${response.status}`
+  };
+}
+
+// src/plugins/webhook/hooks.ts
+function bindBuiltinHooks(registry, emit) {
+  const sources = registry.sources();
+  const hooks = {};
+  const loginName = sources.get("afterLogin");
+  if (loginName) {
+    hooks.afterLogin = async (ctx, result) => {
+      void emit(ctx.db, loginName, {
+        event: loginName,
+        userId: result.user.id,
+        email: result.user.email,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        ip: ctx.meta?.ipAddress ?? null
+      }).catch(() => {
+      });
+      return result;
+    };
+  }
+  const failureName = sources.get("onLoginFailure");
+  if (failureName) {
+    hooks.onLoginFailure = async (ctx) => {
+      void emit(ctx.db, failureName, {
+        event: failureName,
+        identifier: ctx.identifier,
+        error: ctx.error.message,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      }).catch(() => {
+      });
+    };
+  }
+  const logoutName = sources.get("beforeLogout");
+  if (logoutName) {
+    hooks.beforeLogout = async (ctx) => {
+      void emit(ctx.db, logoutName, {
+        event: logoutName,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        ip: ctx.meta?.ipAddress ?? null
+      }).catch(() => {
+      });
+    };
+  }
+  const registerName = sources.get("afterRegister");
+  if (registerName) {
+    hooks.afterRegister = async (ctx, user) => {
+      void emit(ctx.db, registerName, {
+        event: registerName,
+        userId: user.id,
+        email: user.email,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        ip: ctx.meta?.ipAddress ?? null
+      }).catch(() => {
+      });
+    };
+  }
+  const refreshName = sources.get("afterTokenRefresh");
+  if (refreshName) {
+    hooks.afterTokenRefresh = async (ctx, result) => {
+      void emit(ctx.db, refreshName, {
+        event: refreshName,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        ip: ctx.meta?.ipAddress ?? null
+      }).catch(() => {
+      });
+      return result;
+    };
+  }
+  return hooks;
+}
+
+// src/plugins/webhook/queue/in-memory.ts
+function inMemoryQueue() {
+  let handler = null;
+  const timers = /* @__PURE__ */ new Set();
+  let chain = Promise.resolve();
+  const enqueue = async (job) => {
+    const delay = job.scheduledFor ? Math.max(0, job.scheduledFor.getTime() - Date.now()) : 0;
+    const dispatch = () => {
+      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;
+      const pending = await ctx.db.findMany({
+        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 ?? void 0
+        });
+      }
+      return async () => {
+        for (const timer of timers)
+          clearTimeout(timer);
+        timers.clear();
+        handler = null;
+      };
+    }
+  };
+}
+
+// src/plugins/webhook/registry.ts
+var VALID_SOURCES = /* @__PURE__ */ new Set([
+  "afterLogin",
+  "onLoginFailure",
+  "beforeLogout",
+  "afterRegister",
+  "afterTokenRefresh"
+]);
+function assertEventRegistry(events) {
+  const seen = /* @__PURE__ */ new Set();
+  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 !== void 0 && !VALID_SOURCES.has(event.source))
+      throw new Error(`Webhook event '${event.name}' has an unknown source: ${event.source}`);
+  }
+}
+function createEventRegistry(events) {
+  assertEventRegistry(events);
+  const ordered = [...events];
+  const byName = new Map(ordered.map((e) => [e.name, e]));
+  const sources = /* @__PURE__ */ new Map();
+  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)
+  };
+}
+
+// src/plugins/webhook/signing.ts
+async function signPayload(secret, webhookId, timestamp, body) {
+  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)));
+}
+async function signatureHeaders(secret, webhookId, timestamp, body) {
+  const signature = await signPayload(secret, webhookId, timestamp, body);
+  return {
+    "webhook-id": webhookId,
+    "webhook-timestamp": String(timestamp),
+    "webhook-signature": `v1,${signature}`
+  };
+}
+
+// src/plugins/webhook/types.ts
+var WebhookEmitError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "WebhookEmitError";
+    this.code = code;
+  }
+};
+
+// src/plugins/webhook/queue/database.ts
+function databaseQueue(opts = {}) {
+  const pollMs = opts.pollMs ?? 1e4;
+  return {
+    async enqueue() {
+    },
+    async start(handler, ctx) {
+      let stopped = false;
+      let timer = null;
+      const poll = async () => {
+        if (stopped)
+          return;
+        try {
+          const due = await ctx.db.findMany({
+            model: "webhook_delivery",
+            where: [
+              { field: "status", operator: "=", value: "pending" },
+              { field: "nextRetryAt", operator: "lte", value: /* @__PURE__ */ new Date() }
+            ],
+            sortBy: { field: "nextRetryAt", direction: "asc" }
+          });
+          for (const delivery of due) {
+            if (stopped)
+              break;
+            await handler({
+              deliveryId: delivery.id,
+              endpointId: delivery.endpointId,
+              eventType: delivery.eventType,
+              attempt: delivery.attempts + 1,
+              scheduledFor: delivery.nextRetryAt ?? void 0
+            }).catch(() => {
+            });
+          }
+        } catch {
+        }
+        if (!stopped)
+          timer = setTimeout(() => void poll(), pollMs);
+      };
+      timer = setTimeout(() => void poll(), 0);
+      return async () => {
+        stopped = true;
+        if (timer)
+          clearTimeout(timer);
+      };
+    }
+  };
+}
+
+// src/plugins/webhook/index.ts
+var RETRY_INTERVALS_MS = [5e3, 5 * 6e4, 30 * 6e4, 2 * 60 * 6e4, 5 * 60 * 6e4];
+var TRANSIENT_4XX = /* @__PURE__ */ new Set([408, 425, 429]);
+function withJitter(ms) {
+  return Math.max(0, Math.round(ms * (1 + (Math.random() - 0.5) * 0.5)));
+}
+function generateSecret() {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+  return `whsec_${hex}`;
+}
+function idWhere(id) {
+  return [{ field: "id", operator: "=", value: id }];
+}
+function redact(endpoint) {
+  const { secret: _secret, ...rest } = endpoint;
+  return rest;
+}
+function webhook(config = {}) {
+  const registry = createEventRegistry(config.events ?? builtinEvents());
+  const queue = config.queue ?? inMemoryQueue();
+  const retryMode = config.delivery?.retry ?? "pluginScheduled";
+  const maxRetries = config.maxRetries ?? 5;
+  const maxPayloadBytes = config.maxPayloadBytes ?? 256 * 1024;
+  const timeoutMs = config.delivery?.timeoutMs ?? 1e4;
+  const permanentStatuses = new Set(config.delivery?.permanentStatuses ?? [404, 410, 421]);
+  const maxConsecutiveFailures = config.delivery?.maxConsecutiveFailures ?? 15;
+  const onDeliveryFailed = config.delivery?.onDeliveryFailed;
+  const onEndpointDeactivated = config.delivery?.onEndpointDeactivated;
+  if (retryMode === "queue" && !queue.handlesRetries) {
+    throw new Error('delivery.retry: "queue" requires a queue with handlesRetries: true');
+  }
+  const client = createDeliveryClient({ timeoutMs, retryMode, fetch: config.delivery?.fetch });
+  const deliverFn = (url, body, headers) => deliver(client, url, body, headers);
+  function classify(result) {
+    if (!result.ok && result.kind === "http" && result.status !== null) {
+      if (permanentStatuses.has(result.status))
+        return "deactivate";
+      if (TRANSIENT_4XX.has(result.status))
+        return "retry";
+      if (result.status >= 400 && result.status < 500)
+        return "permanent_fail";
+      return "retry";
+    }
+    return "retry";
+  }
+  async function deactivateEndpoint(db, endpoint, reason) {
+    if (!endpoint.isActive)
+      return;
+    await db.update({ model: "webhook_endpoint", where: idWhere(endpoint.id), data: { isActive: false, deactivatedReason: reason } });
+    if (onEndpointDeactivated)
+      await onEndpointDeactivated({ ...endpoint, isActive: false, deactivatedReason: reason }, reason);
+  }
+  async function processJob(db, job) {
+    const delivery = await db.findOne({ model: "webhook_delivery", where: idWhere(job.deliveryId) });
+    if (!delivery || delivery.status !== "pending")
+      return;
+    const endpoint = await db.findOne({ model: "webhook_endpoint", where: idWhere(delivery.endpointId) });
+    if (!endpoint || !endpoint.isActive)
+      return;
+    const webhookId = `msg_${delivery.id}`;
+    const timestamp = Math.floor(Date.now() / 1e3);
+    const headers = await signatureHeaders(endpoint.secret, webhookId, timestamp, delivery.payload);
+    const result = await deliverFn(endpoint.url, delivery.payload, headers);
+    const now = /* @__PURE__ */ new Date();
+    const attempts = delivery.attempts + 1;
+    if (result.ok) {
+      await db.update({
+        model: "webhook_delivery",
+        where: idWhere(delivery.id),
+        data: { status: "success", attempts, lastAttemptAt: now, nextRetryAt: null, responseStatus: result.status, errorKind: null }
+      });
+      if (endpoint.consecutiveFailures > 0)
+        await db.update({ model: "webhook_endpoint", where: idWhere(endpoint.id), data: { consecutiveFailures: 0 } });
+      return;
+    }
+    const consecutiveFailures = endpoint.consecutiveFailures + 1;
+    await db.update({ model: "webhook_endpoint", where: idWhere(endpoint.id), data: { consecutiveFailures } });
+    const responseStatus = result.status;
+    const responseBody = result.responseBody;
+    const errorKind = result.kind;
+    const action = classify(result);
+    const exhausted = attempts >= maxRetries;
+    const breakerTripped = consecutiveFailures >= maxConsecutiveFailures;
+    const willRetry = action === "retry" && !exhausted && retryMode !== "inProcess";
+    const markFailed = async () => {
+      await db.update({
+        model: "webhook_delivery",
+        where: idWhere(delivery.id),
+        data: { status: "failed", attempts, lastAttemptAt: now, nextRetryAt: null, responseStatus, responseBody, errorKind }
+      });
+      if (onDeliveryFailed) {
+        const row = await db.findOne({ model: "webhook_delivery", where: idWhere(delivery.id) });
+        if (row)
+          await onDeliveryFailed(row);
+      }
+    };
+    if (action === "deactivate") {
+      await markFailed();
+      await deactivateEndpoint(db, endpoint, `permanent_${responseStatus}`);
+      return;
+    }
+    if (!willRetry || breakerTripped) {
+      await markFailed();
+      if (breakerTripped)
+        await deactivateEndpoint(db, endpoint, "too_many_failures");
+      return;
+    }
+    if (retryMode === "queue") {
+      await db.update({
+        model: "webhook_delivery",
+        where: idWhere(delivery.id),
+        data: { status: "pending", attempts, lastAttemptAt: now, responseStatus, responseBody, errorKind }
+      });
+      throw new Error(`Webhook delivery failed (${errorKind}${responseStatus !== null ? ` ${responseStatus}` : ""}); queue will retry`);
+    }
+    const retryMs = withJitter(RETRY_INTERVALS_MS[Math.min(attempts - 1, RETRY_INTERVALS_MS.length - 1)]);
+    const nextRetryAt = new Date(Date.now() + retryMs);
+    await db.update({
+      model: "webhook_delivery",
+      where: idWhere(delivery.id),
+      data: { status: "pending", attempts, lastAttemptAt: now, nextRetryAt, responseStatus, responseBody, errorKind }
+    });
+    await queue.enqueue({
+      deliveryId: delivery.id,
+      endpointId: endpoint.id,
+      eventType: delivery.eventType,
+      attempt: attempts + 1,
+      scheduledFor: nextRetryAt
+    });
+  }
+  async function emitEvent(db, eventName, payload, opts) {
+    const declaration = registry.get(eventName);
+    if (!declaration)
+      throw new WebhookEmitError("unknown_event", `Unknown webhook event: ${eventName}`);
+    if (declaration.schema) {
+      const result = await declaration.schema["~standard"].validate(payload);
+      if (result.issues)
+        throw new WebhookEmitError("invalid_payload", `Invalid payload for webhook event '${eventName}'`);
+    }
+    const payloadJson = JSON.stringify(payload);
+    if (Buffer2.byteLength(payloadJson, "utf8") > maxPayloadBytes)
+      throw new WebhookEmitError("payload_too_large", `Webhook payload for '${eventName}' exceeds ${maxPayloadBytes} bytes`);
+    const endpoints = await db.findMany({ model: "webhook_endpoint", where: [{ field: "isActive", operator: "=", value: true }] });
+    const now = /* @__PURE__ */ new Date();
+    for (const endpoint of endpoints) {
+      let names;
+      try {
+        names = JSON.parse(endpoint.events);
+      } catch {
+        continue;
+      }
+      if (!names.includes(eventName))
+        continue;
+      if (opts?.idempotencyKey) {
+        const existing = await db.findOne({
+          model: "webhook_delivery",
+          where: [
+            { field: "endpointId", operator: "=", value: endpoint.id },
+            { field: "idempotencyKey", operator: "=", value: opts.idempotencyKey }
+          ]
+        });
+        if (existing)
+          continue;
+      }
+      let delivery;
+      try {
+        delivery = await db.create({
+          model: "webhook_delivery",
+          data: {
+            endpointId: endpoint.id,
+            eventType: eventName,
+            payload: payloadJson,
+            status: "pending",
+            attempts: 0,
+            idempotencyKey: opts?.idempotencyKey ?? null,
+            nextRetryAt: now
+            // due immediately (the database queue selects on this)
+          }
+        });
+      } catch (err) {
+        if (opts?.idempotencyKey) {
+          const winner = await db.findOne({
+            model: "webhook_delivery",
+            where: [
+              { field: "endpointId", operator: "=", value: endpoint.id },
+              { field: "idempotencyKey", operator: "=", value: opts.idempotencyKey }
+            ]
+          });
+          if (winner)
+            continue;
+        }
+        throw err;
+      }
+      await queue.enqueue({ deliveryId: delivery.id, endpointId: endpoint.id, eventType: eventName, attempt: 1, scheduledFor: now });
+    }
+  }
+  let queueStarted = false;
+  let queueTeardown = null;
+  function ensureQueueStarted(db) {
+    if (queueStarted || !queue.start)
+      return;
+    queueStarted = true;
+    void queue.start((job) => processJob(db, job), { db }).then((teardown) => {
+      queueTeardown = teardown;
+    }).catch(() => {
+      queueStarted = false;
+    });
+  }
+  return {
+    name: "webhook",
+    models: [
+      {
+        name: "webhook_endpoint",
+        fields: {
+          id: { type: "string", required: true },
+          url: { type: "string", required: true },
+          events: { type: "string", required: true },
+          secret: { type: "string", required: true },
+          isActive: { type: "boolean", required: true },
+          deactivatedReason: { type: "string" },
+          consecutiveFailures: { type: "number", required: true },
+          createdAt: { type: "date", required: true }
+        }
+      },
+      {
+        name: "webhook_delivery",
+        fields: {
+          id: { type: "string", required: true },
+          endpointId: { type: "string", required: true, references: { model: "webhook_endpoint", field: "id" } },
+          eventType: { type: "string", required: true },
+          payload: { type: "string", required: true },
+          status: { type: "string", required: true },
+          attempts: { type: "number", required: true },
+          idempotencyKey: { type: "string" },
+          lastAttemptAt: { type: "date" },
+          nextRetryAt: { type: "date" },
+          responseStatus: { type: "number" },
+          responseBody: { type: "string" },
+          errorKind: { type: "string" },
+          createdAt: { type: "date", required: true }
+        }
+      }
+    ],
+    hooks: bindBuiltinHooks(registry, emitEvent),
+    methods: (ctx) => {
+      ensureQueueStarted(ctx.db);
+      return {
+        /** Emit an event — validates against the declared schema and the payload cap, then queues delivery to every subscribed endpoint. */
+        emit(eventName, payload, opts) {
+          return emitEvent(ctx.db, eventName, payload, opts);
+        },
+        /** Register a delivery endpoint. A CSPRNG `secret` is generated when omitted and returned once on the result. */
+        async registerEndpoint(url, events, opts) {
+          const secret = opts?.secret ?? generateSecret();
+          return ctx.db.create({
+            model: "webhook_endpoint",
+            data: { url, events: JSON.stringify(events), secret, isActive: true, consecutiveFailures: 0 }
+          });
+        },
+        /** Patch an endpoint's url / events / active flag. Re-activating clears the deactivation reason and resets the failure counter. Secret is redacted. */
+        async updateEndpoint(id, patch) {
+          const data = {};
+          if (patch.url !== void 0)
+            data.url = patch.url;
+          if (patch.events !== void 0)
+            data.events = JSON.stringify(patch.events);
+          if (patch.isActive !== void 0) {
+            data.isActive = patch.isActive;
+            if (patch.isActive) {
+              data.deactivatedReason = null;
+              data.consecutiveFailures = 0;
+            }
+          }
+          const updated = await ctx.db.update({ model: "webhook_endpoint", where: idWhere(id), data });
+          return updated ? redact(updated) : null;
+        },
+        /** Rotate an endpoint's signing secret. Returns the new secret once. */
+        async rotateSecret(id) {
+          const secret = generateSecret();
+          const updated = await ctx.db.update({ model: "webhook_endpoint", where: idWhere(id), data: { secret } });
+          if (!updated)
+            throw new Error(`Webhook endpoint not found: ${id}`);
+          return { id, secret };
+        },
+        /** List all endpoints with `secret` redacted. */
+        async listEndpoints() {
+          const rows = await ctx.db.findMany({ model: "webhook_endpoint" });
+          return rows.map(redact);
+        },
+        /** Delete an endpoint and its delivery rows. */
+        async removeEndpoint(id) {
+          await ctx.db.delete({ model: "webhook_delivery", where: [{ field: "endpointId", operator: "=", value: id }] });
+          await ctx.db.delete({ model: "webhook_endpoint", where: idWhere(id) });
+        },
+        /** The registered event types (name + description). */
+        listEventTypes() {
+          return registry.list().map((e) => ({ name: e.name, description: e.description }));
+        },
+        /** Stop the queue worker (timers/poller) — call on shutdown. */
+        async stop() {
+          if (queueTeardown) {
+            await queueTeardown();
+            queueTeardown = null;
+          }
+          queueStarted = false;
+        }
+      };
+    }
+  };
+}
+export {
+  WebhookEmitError,
+  assertSafeWebhookUrl,
+  builtinEvents,
+  databaseQueue,
+  inMemoryQueue,
+  webhook
+};