@hasna/events 0.1.16 → 0.1.18

package/dist/transports.js

@@ -33,9 +33,226 @@ function verifyWebhookSignature(secret, timestamp, body, signature, options = {}
   return verifyPayloadSignature(secret, timestamp, body, signature);
 }
 
+// src/ssrf.ts
+import { lookup as dnsLookup } from "dns/promises";
+import { isIP } from "net";
+var DEFAULT_MAX_REDIRECTS = 5;
+var IPV4_PRIVATE_RANGES = [
+  [0, 16777215],
+  [167772160, 184549375],
+  [1681915904, 1686110207],
+  [2130706432, 2147483647],
+  [2851995648, 2852061183],
+  [2886729728, 2887778303],
+  [3221225472, 3221225727],
+  [3221225984, 3221226239],
+  [3227017984, 3227018239],
+  [3232235520, 3232301055],
+  [3323068416, 3323199487],
+  [3325256704, 3325256959],
+  [3405803776, 3405804031],
+  [3758096384, 4294967295]
+];
+var IPV6_SPECIAL_PREFIXES = [
+  { groups: [0, 0, 0, 0, 0, 0, 0, 0], bits: 128 },
+  { groups: [0, 0, 0, 0, 0, 0, 0, 1], bits: 128 },
+  { groups: [0, 0, 0, 0, 0, 65535, 0, 0], bits: 96 },
+  { groups: [100, 65435, 0, 0, 0, 0, 0, 0], bits: 96 },
+  { groups: [256, 0, 0, 0, 0, 0, 0, 0], bits: 64 },
+  { groups: [8193, 0, 0, 0, 0, 0, 0, 0], bits: 32 },
+  { groups: [8193, 2, 0, 0, 0, 0, 0, 0], bits: 48 },
+  { groups: [8193, 16, 0, 0, 0, 0, 0, 0], bits: 28 },
+  { groups: [8193, 3512, 0, 0, 0, 0, 0, 0], bits: 32 },
+  { groups: [8194, 0, 0, 0, 0, 0, 0, 0], bits: 16 },
+  { groups: [16383, 0, 0, 0, 0, 0, 0, 0], bits: 20 },
+  { groups: [64512, 0, 0, 0, 0, 0, 0, 0], bits: 7 },
+  { groups: [65152, 0, 0, 0, 0, 0, 0, 0], bits: 10 },
+  { groups: [65216, 0, 0, 0, 0, 0, 0, 0], bits: 10 },
+  { groups: [65280, 0, 0, 0, 0, 0, 0, 0], bits: 8 }
+];
+function isPrivateAddress(address) {
+  const normalized = stripZoneId(address);
+  const version = isIP(normalized);
+  if (version === 4) {
+    const integer = ipv4ToInt(normalized);
+    if (integer === undefined)
+      return true;
+    return IPV4_PRIVATE_RANGES.some(([low, high]) => integer >= low && integer <= high);
+  }
+  if (version === 6) {
+    const groups = ipv6Groups(normalized);
+    if (!groups)
+      return true;
+    for (const prefix of IPV6_SPECIAL_PREFIXES) {
+      if (!ipv6MatchesPrefix(groups, prefix.groups, prefix.bits))
+        continue;
+      if (prefix.bits === 96 && groups[5] === 65535) {
+        return isPrivateAddress(ipv4IntToString(groups[6] << 16 | groups[7]));
+      }
+      if (prefix.bits === 16 && groups[0] === 8194) {
+        return isPrivateAddress(ipv4IntToString(groups[1] << 16 | groups[2]));
+      }
+      return true;
+    }
+    return false;
+  }
+  return true;
+}
+async function resolveWebhookTarget(url, policy = {}) {
+  const hostname = normalizeHostname(url.hostname);
+  const allowlist = (policy.allowPrivateHosts ?? []).map((entry) => normalizeHostname(entry.toLowerCase()));
+  if (allowlist.includes(hostname)) {
+    const version2 = isIP(hostname);
+    if (version2 === 4 || version2 === 6) {
+      return { hostname, addresses: [hostname] };
+    }
+    const lookup2 = policy.lookup ?? defaultTargetLookup;
+    let resolved2;
+    try {
+      resolved2 = await lookup2(hostname);
+    } catch {
+      throw new Error(`Webhook target ${hostname} could not be resolved`);
+    }
+    if (!Array.isArray(resolved2) || resolved2.length === 0) {
+      throw new Error(`Webhook target ${hostname} resolved to no addresses`);
+    }
+    const addresses = resolved2.map((entry) => normalizeHostname(entry.address));
+    return { hostname, addresses };
+  }
+  const version = isIP(hostname);
+  if (version === 4 || version === 6) {
+    if (isPrivateAddress(hostname)) {
+      throw new Error(`Webhook target ${hostname} is a private or special-use address`);
+    }
+    return { hostname, addresses: [hostname] };
+  }
+  const lookup = policy.lookup ?? defaultTargetLookup;
+  let resolved;
+  try {
+    resolved = await lookup(hostname);
+  } catch {
+    throw new Error(`Webhook target ${hostname} could not be resolved`);
+  }
+  if (!Array.isArray(resolved) || resolved.length === 0) {
+    throw new Error(`Webhook target ${hostname} resolved to no addresses`);
+  }
+  const allowed = [];
+  for (const entry of resolved) {
+    const address = normalizeHostname(entry.address);
+    if (isPrivateAddress(address)) {
+      if (allowlist.includes(address)) {
+        allowed.push(address);
+        continue;
+      }
+      throw new Error(`Webhook target ${hostname} resolves to private or special-use address ${address}`);
+    }
+    allowed.push(address);
+  }
+  if (allowed.length === 0) {
+    throw new Error(`Webhook target ${hostname} resolved to no public addresses`);
+  }
+  return { hostname, addresses: allowed };
+}
+async function assertWebhookTargetAllowed(url, policy = {}) {
+  await resolveWebhookTarget(url, policy);
+}
+function normalizeMaxRedirects(value) {
+  if (value === undefined)
+    return DEFAULT_MAX_REDIRECTS;
+  if (!Number.isInteger(value) || value < 0)
+    throw new Error("webhookTargetPolicy.maxRedirects must be a non-negative integer");
+  return value;
+}
+var defaultTargetLookup = async (hostname) => {
+  return dnsLookup(hostname, { all: true, verbatim: false });
+};
+function normalizeHostname(hostname) {
+  const lower = hostname.toLowerCase();
+  if (lower.startsWith("[") && lower.endsWith("]"))
+    return lower.slice(1, -1);
+  return lower;
+}
+function stripZoneId(address) {
+  const percent = address.indexOf("%");
+  return percent === -1 ? address : address.slice(0, percent);
+}
+function ipv4ToInt(address) {
+  const parts = address.split(".");
+  if (parts.length !== 4)
+    return;
+  let value = 0;
+  for (const part of parts) {
+    if (!/^\d{1,3}$/.test(part))
+      return;
+    const octet = Number(part);
+    if (octet > 255)
+      return;
+    value = value << 8 | octet;
+  }
+  return value >>> 0;
+}
+function ipv4IntToString(integer) {
+  return [
+    integer >>> 24 & 255,
+    integer >>> 16 & 255,
+    integer >>> 8 & 255,
+    integer & 255
+  ].join(".");
+}
+function ipv6Groups(address) {
+  const raw = stripZoneId(address);
+  const doubleColon = raw.indexOf("::");
+  const headText = doubleColon === -1 ? raw : raw.slice(0, doubleColon);
+  const tailText = doubleColon === -1 ? "" : raw.slice(doubleColon + 2);
+  const parseGroups = (text) => {
+    if (text === "")
+      return [];
+    const out = [];
+    for (const part of text.split(":")) {
+      if (part.includes(".")) {
+        const v4 = ipv4ToInt(part);
+        if (v4 === undefined)
+          return;
+        out.push(v4 >>> 16 & 65535, v4 & 65535);
+      } else {
+        if (!/^[0-9a-fA-F]{1,4}$/.test(part))
+          return;
+        out.push(parseInt(part, 16));
+      }
+    }
+    return out;
+  };
+  const head = parseGroups(headText);
+  if (!head)
+    return;
+  const tail = parseGroups(tailText);
+  if (!tail)
+    return;
+  const total = head.length + tail.length;
+  if (doubleColon === -1) {
+    return total === 8 ? head : undefined;
+  }
+  if (total >= 8)
+    return;
+  return [...head, ...new Array(8 - total).fill(0), ...tail];
+}
+function ipv6MatchesPrefix(groups, prefixGroups, prefixBits) {
+  let remaining = prefixBits;
+  for (let index = 0;index < prefixGroups.length && remaining > 0; index += 1) {
+    const take = Math.min(16, remaining);
+    const mask = 65535 << 16 - take & 65535;
+    if ((groups[index] & mask) !== (prefixGroups[index] & mask))
+      return false;
+    remaining -= take;
+  }
+  return true;
+}
+
 // src/transports.ts
 import { randomUUID } from "crypto";
 import { spawn } from "child_process";
+import { request as nodeHttpRequest } from "http";
+import { request as nodeHttpsRequest } from "https";
 function now() {
   return new Date().toISOString();
 }
@@ -66,9 +283,18 @@ function buildWebhookRequest(event, channel, options = {}) {
   }
   return { body, headers };
 }
+function normalizeWebhookUrl(raw) {
+  const url = new URL(raw);
+  if (url.username !== "" || url.password !== "") {
+    url.username = "";
+    url.password = "";
+  }
+  return url.toString();
+}
 async function dispatchWebhook(event, channel, options = {}) {
   if (!channel.webhook)
     throw new Error(`Channel ${channel.id} has no webhook config`);
+  const webhookUrl = normalizeWebhookUrl(channel.webhook.url);
   const startedAt = now();
   let secret = channel.webhook.secret;
   if (channel.webhook.secretRef) {
@@ -85,10 +311,14 @@ async function dispatchWebhook(event, channel, options = {}) {
   }
   const timestamp = (options.now?.() ?? new Date).toISOString();
   const { body, headers } = buildWebhookRequest(event, channel, { secret, timestamp });
+  const validateTargets = options.webhookTargetPolicy !== undefined || options.fetchImpl === undefined;
+  if (validateTargets) {
+    return dispatchValidatedWebhook(event, channel, { body, headers, startedAt, options });
+  }
   const controller = new AbortController;
   const timeout = setTimeout(() => controller.abort(), channel.webhook.timeoutMs ?? 15000);
   try {
-    const response = await (options.fetchImpl ?? fetch)(channel.webhook.url, {
+    const response = await (options.fetchImpl ?? fetch)(webhookUrl, {
       method: "POST",
       headers,
       body,
@@ -116,6 +346,130 @@ async function dispatchWebhook(event, channel, options = {}) {
     clearTimeout(timeout);
   }
 }
+function isRedirectStatus(status) {
+  return status === 301 || status === 302 || status === 303 || status === 307 || status === 308;
+}
+function redirectKeepsBody(status) {
+  return status === 307 || status === 308;
+}
+async function pinnedNativeRequest(target, addresses, method, headers, body, signal, tls) {
+  const isHttps = target.protocol === "https:";
+  if (!isHttps && target.protocol !== "http:") {
+    throw new Error(`Webhook target uses unsupported protocol ${target.protocol}`);
+  }
+  const defaultPort = isHttps ? 443 : 80;
+  const port = target.port ? Number(target.port) : defaultPort;
+  const requestOptions = {
+    hostname: target.hostname,
+    port,
+    path: `${target.pathname}${target.search}`,
+    method,
+    headers,
+    ...tls?.ca ? { ca: tls.ca } : {},
+    lookup: (hostname, _options, callback) => {
+      const entries = addresses.map((address) => ({
+        address,
+        family: address.includes(":") ? 6 : 4
+      }));
+      callback(null, entries);
+    }
+  };
+  return new Promise((resolve, reject) => {
+    const request = isHttps ? nodeHttpsRequest(requestOptions, onResponse) : nodeHttpRequest(requestOptions, onResponse);
+    const onAbort = () => {
+      const error = new Error("The operation was aborted.");
+      error.name = "AbortError";
+      request.destroy(error);
+    };
+    if (signal.aborted)
+      onAbort();
+    else
+      signal.addEventListener("abort", onAbort, { once: true });
+    request.on("error", reject);
+    if (body !== undefined)
+      request.write(body);
+    request.end();
+    function onResponse(response) {
+      const chunks = [];
+      response.on("data", (chunk) => chunks.push(Buffer.from(chunk)));
+      response.on("error", reject);
+      response.on("end", () => {
+        const headersRecord = {};
+        for (const [name, value] of Object.entries(response.headers)) {
+          if (typeof value === "string")
+            headersRecord[name] = value;
+          else if (Array.isArray(value))
+            headersRecord[name] = value.join(", ");
+        }
+        resolve(new Response(Buffer.concat(chunks), { status: response.statusCode ?? 200, headers: headersRecord }));
+      });
+    }
+  });
+}
+async function dispatchValidatedWebhook(event, channel, input) {
+  const { body, headers, startedAt, options } = input;
+  const webhook = channel.webhook;
+  if (!webhook)
+    throw new Error(`Channel ${channel.id} has no webhook config`);
+  const policy = options.webhookTargetPolicy ?? {};
+  const maxRedirects = normalizeMaxRedirects(policy.maxRedirects);
+  const controller = new AbortController;
+  const timeout = setTimeout(() => controller.abort(), webhook.timeoutMs ?? 15000);
+  try {
+    let target = new URL(normalizeWebhookUrl(webhook.url));
+    let requestHeaders = headers;
+    let method = "POST";
+    let requestBody = body;
+    let redirectsFollowed = 0;
+    for (;; ) {
+      const resolved = await resolveWebhookTarget(target, policy).catch((error) => {
+        throw new Error(`Webhook target rejected by SSRF guard: ${error.message}`);
+      });
+      const response = options.fetchImpl ? await options.fetchImpl(target, {
+        method,
+        headers: requestHeaders,
+        body: requestBody,
+        signal: controller.signal,
+        redirect: "manual"
+      }) : await pinnedNativeRequest(target, resolved.addresses, method, requestHeaders, requestBody, controller.signal, options.tls);
+      const location = response.headers.get("location");
+      if (isRedirectStatus(response.status) && location) {
+        if (redirectsFollowed >= maxRedirects) {
+          return failedAttempt(startedAt, `Webhook target exceeded ${maxRedirects} redirects`);
+        }
+        redirectsFollowed += 1;
+        const next = new URL(location, target);
+        target = next;
+        if (!redirectKeepsBody(response.status)) {
+          method = "GET";
+          requestBody = undefined;
+          requestHeaders = Object.fromEntries(Object.entries(requestHeaders).filter(([name]) => name.toLowerCase() !== "content-type" && name.toLowerCase() !== "content-length"));
+        }
+        continue;
+      }
+      const responseBody = truncate(await response.text());
+      return {
+        attempt: 1,
+        status: response.ok ? "success" : "failed",
+        startedAt,
+        completedAt: now(),
+        responseStatus: response.status,
+        responseBody,
+        error: response.ok ? undefined : `Webhook returned HTTP ${response.status}`
+      };
+    }
+  } catch (error) {
+    return {
+      attempt: 1,
+      status: "failed",
+      startedAt,
+      completedAt: now(),
+      error: error instanceof Error ? error.message : String(error)
+    };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
 function failedAttempt(startedAt, error) {
   return {
     attempt: 1,
@@ -214,9 +568,9 @@ function createDeliveryResult(event, channel, attempts) {
   };
 }
 export {
-  buildWebhookRequest,
-  createDeliveryResult,
-  dispatchChannel,
+  dispatchWebhook,
   dispatchCommand,
-  dispatchWebhook
+  dispatchChannel,
+  createDeliveryResult,
+  buildWebhookRequest
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/events",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "description": "Shared event envelopes, local channels, replay, and delivery transports for Hasna open-source apps",
   "type": "module",
   "main": "./dist/index.js",
@@ -14,6 +14,10 @@
       "types": "./types/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./sdk": {
+      "types": "./types/index.d.ts",
+      "import": "./dist/index.js"
+    },
     "./storage": {
       "types": "./types/storage.d.ts",
       "import": "./dist/storage.js"
@@ -72,7 +76,7 @@
   ],
   "scripts": {
     "build": "bun run build:runtime && bun run build:types",
-    "build:runtime": "rm -rf dist && bun build src/cli/index.ts --outdir dist/cli --target bun && bun build src/index.ts src/storage.ts src/signing.ts src/filter.ts src/transports.ts src/types.ts src/commander.ts src/catalog.ts src/app-event.ts src/durable.ts src/durable-worker.ts --root src --outdir dist --target bun && bun build src/durable-spool.ts --root src --outdir dist --target node",
+    "build:runtime": "rm -rf dist && bun build src/cli/index.ts --outdir dist/cli --target bun && bun build src/index.ts src/storage.ts src/signing.ts src/filter.ts src/transports.ts src/ssrf.ts src/types.ts src/commander.ts src/catalog.ts src/app-event.ts src/durable.ts src/durable-worker.ts --root src --outdir dist --target bun && bun build src/durable-spool.ts --root src --outdir dist --target node",
     "build:types": "rm -rf types && tsc -p tsconfig.build.json --emitDeclarationOnly --outDir types",
     "generated-artifacts:check": "bun run build && test -z \"$(git status --porcelain --untracked-files=all -- dist types)\"",
     "contract:check": "contracts repo-conformance .",
@@ -113,7 +117,7 @@
   },
   "devDependencies": {
     "@hasna/contracts": "0.8.5",
-    "@types/bun": "latest",
+    "@types/bun": "1.3.14",
     "typescript": "^5.7.3"
   }
 }

package/types/app-home.d.ts

@@ -0,0 +1,42 @@
+export type PathKind = "config" | "data" | "state" | "cache";
+export interface PathsResolverOptions {
+    app: string;
+    internal?: boolean;
+    platform?: string;
+    home?: string;
+    env?: Record<string, string | undefined>;
+}
+export declare function dataDir(options: PathsResolverOptions): string;
+/** Env var names for the exact-app data-home overrides (preserved, highest precedence). */
+export declare const HASNA_EVENTS_DIR_ENV = "HASNA_EVENTS_DIR";
+export declare const HASNA_EVENTS_HOME_ENV = "HASNA_EVENTS_HOME";
+/** The primary store file — its existence at a home marks the store as physically located there. */
+export declare const EVENTS_STORE_SENTINEL_FILE = "events.json";
+/** The effective user home, mirroring the pre-existing events resolution (`HOME` || `USERPROFILE` || `os.homedir()`). */
+export declare function effectiveHome(): string;
+/** Pre-XDG default home: ~/.hasna/events. */
+export declare function legacyHomeDir(): string;
+/**
+ * The @hasna/paths-resolved data home for events (XDG / macOS home layout).
+ * The `home` is injected so the resolver follows the same home the legacy path
+ * does (`$HOME`-first, matching the pre-existing resolution).
+ */
+export declare function resolverHome(): string;
+/**
+ * Whether the resolver (XDG) home should be adopted as the store home. The
+ * resolver home is adopted only when the operator has set `HASNA_DATA_HOME`
+ * (the data-kind override — a deliberate opt-in to the XDG layout) or the
+ * store has already been physically migrated there (`events.json` exists). A
+ * machine that only redirects another kind must NOT have its data home moved,
+ * and a live store at the legacy home must never become invisible on upgrade.
+ */
+export declare function adoptResolverHome(resolved: string, env?: NodeJS.ProcessEnv): boolean;
+/** The exact-app override root (`HASNA_EVENTS_DIR` wins over `HASNA_EVENTS_HOME`), when set. Empty values are treated as unset. */
+export declare function exactEventsHome(): string | undefined;
+/**
+ * Effective events data home: an exact-app override (`HASNA_EVENTS_DIR`, then
+ * the legacy `HASNA_EVENTS_HOME` fallback) wins unconditionally; otherwise the
+ * resolver (XDG) data home once adopted; otherwise the legacy `~/.hasna/events`
+ * default.
+ */
+export declare function getEventsHome(): string;

package/types/cli-webhook-policy.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Shared CLI-only administrator opt-in for intentional private webhook ingress.
+ * The transport still requires an exact hostname/IP allowlist match and pins
+ * the validated address. SDK clients do not read this setting automatically.
+ */
+export declare function webhookTargetPolicyFromEnv(): {
+    allowPrivateHosts: string[];
+} | undefined;

package/types/durable.d.ts

@@ -35,6 +35,8 @@ export interface DurableSpoolImportResult {
     imported: number;
     deduped: number;
     queued: number;
+    /** Records quarantined because they were malformed or identity-mismatched. */
+    quarantined: number;
 }
 export interface DurableRetryDeadOptions {
     eventId?: string;

package/types/index.d.ts

@@ -7,6 +7,7 @@ export * from "./storage.js";
 export * from "./filter.js";
 export * from "./signing.js";
 export * from "./transports.js";
+export * from "./ssrf.js";
 export * from "./catalog.js";
 export * from "./app-event.js";
 export { redactPaths, redactSensitiveKeys } from "./redaction.js";

package/types/ssrf.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Webhook-target SSRF guard for the durable delivery transport.
+ *
+ * The durable webhook transport must default-deny private and special-use
+ * targets (IPv4/IPv6), refuse redirects that would reach a private target,
+ * and prevent a DNS-rebinding window between validation and connection. The
+ * connection is pinned to the validated address at the transport level (the
+ * original URL hostname is preserved for TLS SNI and hostname verification,
+ * so a certificate issued for the hostname verifies normally).
+ *
+ * A narrow, admin-controlled allowlist (`allowPrivateHosts`) permits
+ * intentional private ingress such as a loopback receiver on the same machine.
+ * Allowlisted hostnames are still resolved and pinned, so the rebinding window
+ * stays closed for them as well.
+ */
+export interface LookupAddress {
+    address: string;
+    family: number;
+}
+export type TargetLookup = (hostname: string) => Promise<LookupAddress[]>;
+export interface WebhookTargetPolicy {
+    /**
+     * Admin-controlled allowlist of private hostnames or IP addresses that
+     * intentional private webhook ingress may target (for example a loopback
+     * receiver on the same machine). Exact match only, case-insensitive for
+     * hostnames. Defaults to none.
+     */
+    allowPrivateHosts?: string[];
+    /**
+     * Maximum redirect hops followed. Every hop is revalidated against the same
+     * policy. Defaults to 5.
+     */
+    maxRedirects?: number;
+    /** Injectable hostname resolver, used by tests. Defaults to dns.promises.lookup. */
+    lookup?: TargetLookup;
+}
+export declare const DEFAULT_MAX_REDIRECTS = 5;
+export interface ResolvedWebhookTarget {
+    hostname: string;
+    /** Validated public addresses the connection may be pinned to. */
+    addresses: string[];
+}
+/**
+ * True when the address is a private, loopback, link-local, multicast, or
+ * otherwise special-use address that a webhook must not reach by default.
+ * Unparsable or non-IP input fails closed (treated as private).
+ */
+export declare function isPrivateAddress(address: string): boolean;
+/**
+ * Resolves and validates a webhook target. Returns the validated public
+ * addresses (which the caller pins the connection to), or throws with a
+ * bounded reason when the target is private, unresolvable, empty, or mixed
+ * with a private answer. The narrow admin allowlist admits exact private
+ * hostnames and addresses.
+ */
+export declare function resolveWebhookTarget(url: URL, policy?: WebhookTargetPolicy): Promise<ResolvedWebhookTarget>;
+/** Validates a webhook target URL against the SSRF policy, throwing on rejection. */
+export declare function assertWebhookTargetAllowed(url: URL, policy?: WebhookTargetPolicy): Promise<void>;
+export declare function normalizeMaxRedirects(value: number | undefined): number;

package/types/storage.d.ts

@@ -1,6 +1,6 @@
+import { HASNA_EVENTS_DIR_ENV, HASNA_EVENTS_HOME_ENV } from "./app-home.js";
 import type { ChannelConfig, DeliveryResult, EventAppendOptions, EventAppendResult, EventEnvelope, EventPage, EventPageOptions, EventsStatus, EventsStoreRuntime, StoredEventsData } from "./types.js";
-export declare const HASNA_EVENTS_DIR_ENV = "HASNA_EVENTS_DIR";
-export declare const HASNA_EVENTS_HOME_ENV = "HASNA_EVENTS_HOME";
+export { HASNA_EVENTS_DIR_ENV, HASNA_EVENTS_HOME_ENV };
 export declare const LOCAL_JSON_EVENT_CURSOR_PREFIX = "local-json-v1:";
 export declare const DEFAULT_EVENT_PAGE_LIMIT = 100;
 export declare const MAX_EVENT_PAGE_LIMIT = 1000;

package/types/transports.d.ts

@@ -1,8 +1,31 @@
 import type { ChannelConfig, DeliveryAttempt, DeliveryResult, EventEnvelope } from "./types.js";
+import { type WebhookTargetPolicy } from "./ssrf.js";
+export interface TransportTlsOptions {
+    /**
+     * Override the certificate authorities used by the pinned native transport
+     * (for example a private PKI or a self-signed test certificate). Ignored on
+     * an injected `fetchImpl` path, where the operator owns TLS. Defaults to the
+     * runtime's standard CA store.
+     */
+    ca?: string | Buffer | Array<string | Buffer>;
+}
 export interface TransportDispatchOptions {
     fetchImpl?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
     secretResolver?: WebhookSecretResolver;
     now?: () => Date;
+    /**
+     * TLS options for the pinned native transport (the default, non-injected
+     * fetch path). `ca` overrides the trusted certificate authorities.
+     */
+    tls?: TransportTlsOptions;
+    /**
+     * Webhook-target SSRF policy. When provided, the durable webhook transport
+     * validates every target (and every redirect hop) against it. When omitted,
+     * the guard still applies on the default `fetch` path and is deferred to an
+     * injected `fetchImpl` (the operator who injects a fetch implementation owns
+     * the network boundary).
+     */
+    webhookTargetPolicy?: WebhookTargetPolicy;
 }
 export type WebhookSecretResolver = (reference: string) => string | undefined | Promise<string | undefined>;
 export interface BuildWebhookRequestOptions {