@dwk/webmention 0.1.0-beta.0

package/dist/log.js

@@ -0,0 +1,40 @@
+/**
+ * `@dwk/webmention` — structured observability event taxonomy.
+ *
+ * The package's logging and metrics are opt-in via an injected {@link Logger}
+ * and {@link Metrics} (see `@dwk/log`), and **share this one vocabulary**: the
+ * same dotted event name is passed to `logger.warn(...)` and
+ * `metrics.count(...)` so a log line and its counter line up. Event names are
+ * stable, dotted, and queryable — operators filter on these rather than grepping
+ * free text. Security-relevant events (a blocked SSRF attempt, a receiver
+ * rejection, a poison-message retry) are first-class here so that being actively
+ * probed produces a distinct signal instead of looking like a dead link. See
+ * `spec/observability.md`.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Stable event names emitted by `@dwk/webmention`. Fields logged alongside each
+ * event use `hostFromUrl` for any URL so an attacker-supplied path/query is
+ * never recorded; tokens and bodies are never logged.
+ */
+export const WebmentionLogEvent = {
+    /**
+     * An outbound fetch was refused on SSRF grounds. Fields: `reason`
+     * (machine-readable cause), `host` (sanitized, when known).
+     */
+    SsrfBlocked: "webmention.ssrf.blocked",
+    /** A received mention passed validation and was enqueued. */
+    ReceiveAccepted: "webmention.receive.accepted",
+    /** A received mention was rejected at validation. Field: `reason`. */
+    ReceiveRejected: "webmention.receive.rejected",
+    /** Source verification finished. Fields: `links`, `status`. */
+    VerifyCompleted: "webmention.verify.completed",
+    /** The source fetch failed/was blocked during verification. Field: `error`. */
+    VerifyFetchFailed: "webmention.verify.fetch_failed",
+    /** A queue message threw and is being retried. Field: `error`. */
+    QueueRetry: "webmention.queue.retry",
+    /** A send attempt finished. Fields: `endpointHost`, `delivered`, `status`. */
+    SendCompleted: "webmention.send.completed",
+};
+//# sourceMappingURL=log.js.map

package/dist/log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.js","sourceRoot":"","sources":["../src/log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC;;;OAGG;IACH,WAAW,EAAE,yBAAyB;IACtC,6DAA6D;IAC7D,eAAe,EAAE,6BAA6B;IAC9C,sEAAsE;IACtE,eAAe,EAAE,6BAA6B;IAC9C,+DAA+D;IAC/D,eAAe,EAAE,6BAA6B;IAC9C,+EAA+E;IAC/E,iBAAiB,EAAE,gCAAgC;IACnD,kEAAkE;IAClE,UAAU,EAAE,wBAAwB;IACpC,8EAA8E;IAC9E,aAAa,EAAE,2BAA2B;CAClC,CAAC"}

package/dist/safe-fetch.d.ts

@@ -0,0 +1,101 @@
+/**
+ * `@dwk/webmention` — SSRF-safe outbound fetch.
+ *
+ * A Webmention implementation's whole job is fetching attacker-supplied URLs:
+ * the receiver fetches `source`, and the sender fetches `target` plus the
+ * endpoint it discovers there. Without guardrails an attacker can point any of
+ * these at the Worker's own network — loopback, the link-local cloud metadata
+ * IP (`169.254.169.254`), or RFC 1918 ranges — to exfiltrate credentials or
+ * probe internal services. This module is the single choke point every
+ * outbound fetch in the package goes through. It:
+ *
+ * 1. rejects URLs whose host is a private, loopback, link-local, or otherwise
+ *    non-public address (or a name like `localhost` / `*.internal`),
+ * 2. follows redirects manually, re-validating the host on every `Location`
+ *    hop so a public-looking host cannot 302 to an internal one, and capping
+ *    the hop count, and
+ * 3. bounds the whole operation with a single timeout, so a slow-loris target
+ *    cannot pin a queue-consumer invocation.
+ *
+ * Host validation is purely syntactic on the URL host — DNS rebinding (a name
+ * that resolves to a private IP) is out of scope here, as the Workers runtime
+ * does not expose name resolution to user code. See `spec/packages/webmention.md`
+ * and `spec/non-functional-requirements.md`.
+ *
+ * @packageDocumentation
+ */
+import { type Logger, type Metrics } from "@dwk/log";
+import type { FetchLike } from "./fetch";
+/** Default cap on redirect hops before a fetch is abandoned. */
+export declare const DEFAULT_MAX_REDIRECTS = 5;
+/** Default overall timeout (ms) bounding a fetch, redirects included. */
+export declare const DEFAULT_TIMEOUT_MS = 10000;
+/**
+ * Machine-readable cause of an {@link SsrfError}, suitable for logging as a
+ * structured field (no free-text parsing required).
+ */
+export type SsrfReason = "invalid_url" | "disallowed_scheme" | "blocked_host" | "too_many_redirects";
+/**
+ * Raised when a request is refused on SSRF grounds (blocked host, disallowed
+ * scheme, or too many redirects). Callers catch this exactly like a network
+ * failure — a blocked attempt looks the same as an unreachable host — but
+ * {@link safeFetch} logs it first (event `webmention.ssrf.blocked`) so the
+ * single most security-relevant event in the package still produces a signal.
+ *
+ * Carries the structured {@link reason} and, when known, the sanitized
+ * {@link host} so a logger can record them as queryable fields.
+ */
+export declare class SsrfError extends Error {
+    /** Machine-readable cause. */
+    readonly reason: SsrfReason;
+    /** The offending host (name plus any port), when one is known. */
+    readonly host?: string;
+    constructor(message: string, reason: SsrfReason, host?: string);
+}
+/**
+ * Decide whether a URL host is private, loopback, link-local, or otherwise
+ * not safe to fetch from inside the Worker's network. Accepts the raw
+ * `URL.hostname` form (IPv6 hosts may arrive wrapped in `[...]`).
+ */
+export declare function isPrivateOrReservedHost(hostname: string): boolean;
+/**
+ * Validate that `rawUrl` is a fetchable public `http(s)` URL, returning the
+ * parsed {@link URL}. Throws {@link SsrfError} for an unparseable URL, a
+ * non-`http(s)` scheme (e.g. `file:`, `javascript:`), or a private/reserved
+ * host.
+ */
+export declare function assertPublicUrl(rawUrl: string): URL;
+/** Tunables for {@link safeFetch}. */
+export interface SafeFetchOptions {
+    /** Maximum redirect hops to follow (default {@link DEFAULT_MAX_REDIRECTS}). */
+    readonly maxRedirects?: number;
+    /** Overall timeout in ms, redirects included (default {@link DEFAULT_TIMEOUT_MS}). */
+    readonly timeoutMs?: number;
+    /** Logger for SSRF blocks; defaults to a no-op (see `@dwk/log`). */
+    readonly logger?: Logger;
+    /** Metrics sink for SSRF-block counters; defaults to a no-op (see `@dwk/log`). */
+    readonly metrics?: Metrics;
+}
+/** A completed {@link safeFetch}: the final response and the URL it came from. */
+export interface SafeFetchResult {
+    /** The final, non-redirect response. */
+    readonly response: Response;
+    /** The fully-resolved URL the response came from (the base for relative links). */
+    readonly url: string;
+}
+/**
+ * Fetch `rawUrl` through `doFetch` with SSRF guardrails.
+ *
+ * The initial host and every redirect target are validated with
+ * {@link assertPublicUrl}; redirects are followed manually (`redirect:
+ * "manual"`) up to `maxRedirects` hops; and a single {@link AbortSignal.timeout}
+ * bounds the whole chain. The request method, headers, and body from `init` are
+ * preserved across hops — a redirected `POST` notification re-POSTs to the
+ * (re-validated) new location rather than silently degrading to `GET`.
+ *
+ * @throws {SsrfError} when a host is blocked, a scheme is disallowed, or the
+ * redirect cap is exceeded. Other failures (network, timeout) propagate as the
+ * underlying fetch rejection. Callers treat any throw as "fetch failed".
+ */
+export declare function safeFetch(doFetch: FetchLike, rawUrl: string, init: RequestInit, options?: SafeFetchOptions): Promise<SafeFetchResult>;
+//# sourceMappingURL=safe-fetch.d.ts.map

package/dist/safe-fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-fetch.d.ts","sourceRoot":"","sources":["../src/safe-fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAA2B,KAAK,MAAM,EAAE,KAAK,OAAO,EAAE,MAAM,UAAU,CAAC;AAC9E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAGzC,gEAAgE;AAChE,eAAO,MAAM,qBAAqB,IAAI,CAAC;AACvC,yEAAyE;AACzE,eAAO,MAAM,kBAAkB,QAAS,CAAC;AAKzC;;;GAGG;AACH,MAAM,MAAM,UAAU,GAClB,aAAa,GACb,mBAAmB,GACnB,cAAc,GACd,oBAAoB,CAAC;AAEzB;;;;;;;;;GASG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,8BAA8B;IAC9B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,kEAAkE;IAClE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;gBACX,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,MAAM;CAM/D;AAuKD;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAsBjE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,GAAG,CAsBnD;AAED,sCAAsC;AACtC,MAAM,WAAW,gBAAgB;IAC/B,+EAA+E;IAC/E,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,sFAAsF;IACtF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,oEAAoE;IACpE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,kFAAkF;IAClF,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,kFAAkF;AAClF,MAAM,WAAW,eAAe;IAC9B,wCAAwC;IACxC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,mFAAmF;IACnF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,SAAS,CAC7B,OAAO,EAAE,SAAS,EAClB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,eAAe,CAAC,CAqE1B"}

package/dist/safe-fetch.js

@@ -0,0 +1,348 @@
+/**
+ * `@dwk/webmention` — SSRF-safe outbound fetch.
+ *
+ * A Webmention implementation's whole job is fetching attacker-supplied URLs:
+ * the receiver fetches `source`, and the sender fetches `target` plus the
+ * endpoint it discovers there. Without guardrails an attacker can point any of
+ * these at the Worker's own network — loopback, the link-local cloud metadata
+ * IP (`169.254.169.254`), or RFC 1918 ranges — to exfiltrate credentials or
+ * probe internal services. This module is the single choke point every
+ * outbound fetch in the package goes through. It:
+ *
+ * 1. rejects URLs whose host is a private, loopback, link-local, or otherwise
+ *    non-public address (or a name like `localhost` / `*.internal`),
+ * 2. follows redirects manually, re-validating the host on every `Location`
+ *    hop so a public-looking host cannot 302 to an internal one, and capping
+ *    the hop count, and
+ * 3. bounds the whole operation with a single timeout, so a slow-loris target
+ *    cannot pin a queue-consumer invocation.
+ *
+ * Host validation is purely syntactic on the URL host — DNS rebinding (a name
+ * that resolves to a private IP) is out of scope here, as the Workers runtime
+ * does not expose name resolution to user code. See `spec/packages/webmention.md`
+ * and `spec/non-functional-requirements.md`.
+ *
+ * @packageDocumentation
+ */
+import { noopLogger, noopMetrics } from "@dwk/log";
+import { WebmentionLogEvent } from "./log";
+/** Default cap on redirect hops before a fetch is abandoned. */
+export const DEFAULT_MAX_REDIRECTS = 5;
+/** Default overall timeout (ms) bounding a fetch, redirects included. */
+export const DEFAULT_TIMEOUT_MS = 10_000;
+/** HTTP status codes that carry a `Location` we may follow. */
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+/**
+ * Raised when a request is refused on SSRF grounds (blocked host, disallowed
+ * scheme, or too many redirects). Callers catch this exactly like a network
+ * failure — a blocked attempt looks the same as an unreachable host — but
+ * {@link safeFetch} logs it first (event `webmention.ssrf.blocked`) so the
+ * single most security-relevant event in the package still produces a signal.
+ *
+ * Carries the structured {@link reason} and, when known, the sanitized
+ * {@link host} so a logger can record them as queryable fields.
+ */
+export class SsrfError extends Error {
+    /** Machine-readable cause. */
+    reason;
+    /** The offending host (name plus any port), when one is known. */
+    host;
+    constructor(message, reason, host) {
+        super(message);
+        this.name = "SsrfError";
+        this.reason = reason;
+        this.host = host;
+    }
+}
+/** Parse a canonical dotted-decimal IPv4 host into its four octets. */
+function parseIPv4(host) {
+    const match = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+    if (match === null) {
+        return null;
+    }
+    const octets = [];
+    for (let group = 1; group <= 4; group++) {
+        const part = match[group];
+        if (part === undefined) {
+            return null;
+        }
+        const octet = Number.parseInt(part, 10);
+        if (octet > 255) {
+            return null;
+        }
+        octets.push(octet);
+    }
+    return octets;
+}
+/**
+ * True when `octets` falls in a range that must never be fetched from inside
+ * the Worker's network: this-network, loopback, link-local (incl. the cloud
+ * metadata IP), the RFC 1918 private blocks, CGNAT, IETF protocol/benchmark
+ * assignments, and the multicast/reserved/broadcast space.
+ */
+function isPrivateIPv4(octets) {
+    const [a, b, c] = octets;
+    if (a === 0)
+        return true; // 0.0.0.0/8 ("this network", incl. 0.0.0.0)
+    if (a === 10)
+        return true; // 10.0.0.0/8 private
+    if (a === 127)
+        return true; // 127.0.0.0/8 loopback
+    if (a === 100 && b >= 64 && b <= 127)
+        return true; // 100.64.0.0/10 CGNAT
+    if (a === 169 && b === 254)
+        return true; // 169.254.0.0/16 link-local (metadata)
+    if (a === 172 && b >= 16 && b <= 31)
+        return true; // 172.16.0.0/12 private
+    if (a === 192 && b === 0 && c === 0)
+        return true; // 192.0.0.0/24 IETF protocol
+    if (a === 192 && b === 0 && c === 2)
+        return true; // 192.0.2.0/24 TEST-NET-1
+    if (a === 192 && b === 168)
+        return true; // 192.168.0.0/16 private
+    if (a === 198 && b === 51 && c === 100)
+        return true; // 198.51.100.0/24 TEST-NET-2
+    if (a === 198 && (b === 18 || b === 19))
+        return true; // 198.18.0.0/15 benchmark
+    if (a === 203 && b === 0 && c === 113)
+        return true; // 203.0.113.0/24 TEST-NET-3
+    if (a >= 224)
+        return true; // 224.0.0.0/4 multicast + 240.0.0.0/4 reserved + broadcast
+    return false;
+}
+/**
+ * Parse an IPv6 host (brackets already stripped) into its eight 16-bit groups,
+ * expanding `::` compression and any trailing embedded IPv4 literal. Returns
+ * `null` when `host` is not a valid IPv6 address.
+ */
+function parseIPv6(host) {
+    if (!host.includes(":")) {
+        return null;
+    }
+    let str = host;
+    // Fold a trailing embedded IPv4 literal (e.g. ::ffff:127.0.0.1) into two
+    // hex groups so the rest can be parsed uniformly.
+    const v4Match = /(?:^|:)((?:\d{1,3}\.){3}\d{1,3})$/.exec(str);
+    const v4Str = v4Match?.[1];
+    if (v4Str !== undefined) {
+        const v4 = parseIPv4(v4Str);
+        if (v4 === null) {
+            return null;
+        }
+        const hi = ((v4[0] << 8) | v4[1]).toString(16);
+        const lo = ((v4[2] << 8) | v4[3]).toString(16);
+        str = `${str.slice(0, str.length - v4Str.length)}${hi}:${lo}`;
+    }
+    // At most one "::" compression marker is allowed.
+    if (str.indexOf("::") !== str.lastIndexOf("::")) {
+        return null;
+    }
+    const toGroups = (part) => {
+        if (part === "") {
+            return [];
+        }
+        const groups = [];
+        for (const token of part.split(":")) {
+            if (!/^[0-9a-fA-F]{1,4}$/.test(token)) {
+                return null;
+            }
+            groups.push(Number.parseInt(token, 16));
+        }
+        return groups;
+    };
+    if (str.includes("::")) {
+        const parts = str.split("::");
+        const left = toGroups(parts[0] ?? "");
+        const right = toGroups(parts[1] ?? "");
+        if (left === null || right === null) {
+            return null;
+        }
+        const missing = 8 - left.length - right.length;
+        if (missing < 1) {
+            return null;
+        }
+        return [...left, ...new Array(missing).fill(0), ...right];
+    }
+    const all = toGroups(str);
+    if (all === null || all.length !== 8) {
+        return null;
+    }
+    return all;
+}
+/**
+ * True when `groups` (eight 16-bit values) is an IPv6 address that must never
+ * be fetched: unspecified, loopback, link-local, site-local, unique-local,
+ * multicast, the documentation prefix, or an address that embeds an IPv4
+ * (IPv4-mapped `::ffff:0:0/96`, deprecated IPv4-compatible `::/96`, or NAT64
+ * `64:ff9b::/96`) whose embedded IPv4 is itself private.
+ */
+function isPrivateIPv6(groups) {
+    const first = groups[0] ?? 0;
+    const g6 = groups[6] ?? 0;
+    const g7 = groups[7] ?? 0;
+    if (groups.every((group) => group === 0))
+        return true; // :: unspecified
+    if (groups.slice(0, 7).every((group) => group === 0) && g7 === 1)
+        return true; // ::1 loopback
+    if ((first & 0xffc0) === 0xfe80)
+        return true; // fe80::/10 link-local
+    if ((first & 0xffc0) === 0xfec0)
+        return true; // fec0::/10 site-local (deprecated)
+    if ((first & 0xfe00) === 0xfc00)
+        return true; // fc00::/7 unique local
+    if ((first & 0xff00) === 0xff00)
+        return true; // ff00::/8 multicast
+    if (first === 0x2001 && groups[1] === 0x0db8)
+        return true; // 2001:db8::/32 documentation
+    // Extract the IPv4 embedded in the low 32 bits.
+    const embeddedV4 = [
+        g6 >> 8,
+        g6 & 0xff,
+        g7 >> 8,
+        g7 & 0xff,
+    ];
+    // ::ffff:0:0/96 IPv4-mapped and ::/96 deprecated IPv4-compatible.
+    if (groups.slice(0, 5).every((group) => group === 0) &&
+        (groups[5] === 0xffff || groups[5] === 0x0000)) {
+        return isPrivateIPv4(embeddedV4);
+    }
+    // 64:ff9b::/96 NAT64 well-known prefix.
+    if (first === 0x0064 &&
+        groups[1] === 0xff9b &&
+        groups.slice(2, 6).every((group) => group === 0)) {
+        return isPrivateIPv4(embeddedV4);
+    }
+    return false;
+}
+/** Hostnames (non-IP) that are never public and must never be fetched. */
+function isBlockedHostname(host) {
+    const lower = host.toLowerCase();
+    return (lower === "localhost" ||
+        lower.endsWith(".localhost") ||
+        lower.endsWith(".local") ||
+        lower.endsWith(".internal"));
+}
+/**
+ * Decide whether a URL host is private, loopback, link-local, or otherwise
+ * not safe to fetch from inside the Worker's network. Accepts the raw
+ * `URL.hostname` form (IPv6 hosts may arrive wrapped in `[...]`).
+ */
+export function isPrivateOrReservedHost(hostname) {
+    if (hostname === "") {
+        return true;
+    }
+    // Strip IPv6 brackets and a trailing dot. A trailing dot makes a name an
+    // FQDN that still resolves (e.g. `localhost.` → 127.0.0.1) but would slip
+    // past the string checks below if left in place.
+    const host = (hostname.startsWith("[") && hostname.endsWith("]")
+        ? hostname.slice(1, -1)
+        : hostname).replace(/\.$/, "");
+    const v4 = parseIPv4(host);
+    if (v4 !== null) {
+        return isPrivateIPv4(v4);
+    }
+    const v6 = parseIPv6(host);
+    if (v6 !== null) {
+        return isPrivateIPv6(v6);
+    }
+    return isBlockedHostname(host);
+}
+/**
+ * Validate that `rawUrl` is a fetchable public `http(s)` URL, returning the
+ * parsed {@link URL}. Throws {@link SsrfError} for an unparseable URL, a
+ * non-`http(s)` scheme (e.g. `file:`, `javascript:`), or a private/reserved
+ * host.
+ */
+export function assertPublicUrl(rawUrl) {
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        throw new SsrfError(`invalid URL: ${rawUrl}`, "invalid_url");
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new SsrfError(`disallowed scheme: ${url.protocol}`, "disallowed_scheme", url.hostname);
+    }
+    if (isPrivateOrReservedHost(url.hostname)) {
+        throw new SsrfError(`blocked host: ${url.hostname}`, "blocked_host", url.hostname);
+    }
+    return url;
+}
+/**
+ * Fetch `rawUrl` through `doFetch` with SSRF guardrails.
+ *
+ * The initial host and every redirect target are validated with
+ * {@link assertPublicUrl}; redirects are followed manually (`redirect:
+ * "manual"`) up to `maxRedirects` hops; and a single {@link AbortSignal.timeout}
+ * bounds the whole chain. The request method, headers, and body from `init` are
+ * preserved across hops — a redirected `POST` notification re-POSTs to the
+ * (re-validated) new location rather than silently degrading to `GET`.
+ *
+ * @throws {SsrfError} when a host is blocked, a scheme is disallowed, or the
+ * redirect cap is exceeded. Other failures (network, timeout) propagate as the
+ * underlying fetch rejection. Callers treat any throw as "fetch failed".
+ */
+export async function safeFetch(doFetch, rawUrl, init, options) {
+    const maxRedirects = options?.maxRedirects ?? DEFAULT_MAX_REDIRECTS;
+    const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const logger = options?.logger ?? noopLogger;
+    const metrics = options?.metrics ?? noopMetrics;
+    const signal = AbortSignal.timeout(timeoutMs);
+    // A blocked request is the single most security-relevant event here, so log
+    // it (with its structured reason + sanitized host) before re-throwing — an
+    // operator being actively probed sees a distinct signal instead of silence.
+    try {
+        let currentUrl = assertPublicUrl(rawUrl).toString();
+        let currentInit = { ...init };
+        for (let hop = 0;; hop++) {
+            const response = await doFetch(currentUrl, {
+                ...currentInit,
+                redirect: "manual",
+                signal,
+            });
+            if (!REDIRECT_STATUSES.has(response.status)) {
+                return { response, url: currentUrl };
+            }
+            const location = response.headers.get("location");
+            if (location === null || location === "") {
+                // A redirect with nothing to follow — hand back as the final response.
+                return { response, url: currentUrl };
+            }
+            if (hop >= maxRedirects) {
+                throw new SsrfError(`too many redirects (> ${maxRedirects})`, "too_many_redirects", new URL(currentUrl).host);
+            }
+            // Resolve the next hop against the current URL and re-validate its host
+            // before following — a public host must not be able to bounce us inward.
+            const next = assertPublicUrl(new URL(location, currentUrl).toString());
+            // Drain the redirect body so the connection can be reused/closed.
+            await response.body?.cancel().catch(() => undefined);
+            // Strip credential-bearing headers on a cross-origin hop, matching what a
+            // browser's `fetch` does, so a redirect cannot leak them to a new origin.
+            if (currentInit.headers && new URL(currentUrl).origin !== next.origin) {
+                const headers = new Headers(currentInit.headers);
+                for (const name of [
+                    "authorization",
+                    "cookie",
+                    "cookie2",
+                    "proxy-authorization",
+                    "set-cookie",
+                ]) {
+                    headers.delete(name);
+                }
+                currentInit = { ...currentInit, headers };
+            }
+            currentUrl = next.toString();
+        }
+    }
+    catch (err) {
+        if (err instanceof SsrfError) {
+            const fields = { reason: err.reason, host: err.host };
+            logger.warn(WebmentionLogEvent.SsrfBlocked, fields);
+            // Mirror the log as a counter so "SSRF blocks/min by reason" is chartable.
+            metrics.count(WebmentionLogEvent.SsrfBlocked, fields);
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=safe-fetch.js.map

package/dist/safe-fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-fetch.js","sourceRoot":"","sources":["../src/safe-fetch.ts"],"names":[],"mappings":"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"}

package/dist/sender.d.ts

@@ -0,0 +1,43 @@
+/**
+ * `@dwk/webmention` — sender.
+ *
+ * On publish, notify each outbound target: discover its Webmention endpoint
+ * (see {@link discoverEndpoint}) and POST a `source`/`target` notification as
+ * `application/x-www-form-urlencoded`. See `spec/packages/webmention.md`.
+ *
+ * @packageDocumentation
+ */
+import { type Logger, type Metrics } from "@dwk/log";
+import type { FetchLike } from "./fetch";
+/** Options for {@link sendWebmention} / {@link sendWebmentions}. */
+export interface SendOptions {
+    /** `fetch` implementation to use; defaults to the global `fetch`. */
+    readonly fetch?: FetchLike;
+    /** Logger for send outcomes; defaults to a no-op (see `@dwk/log`). */
+    readonly logger?: Logger;
+    /** Metrics sink for send-outcome counters; defaults to a no-op (see `@dwk/log`). */
+    readonly metrics?: Metrics;
+}
+/** Outcome of attempting to notify a single target. */
+export interface SendResult {
+    /** The target URL that was notified. */
+    readonly target: string;
+    /** The discovered endpoint, or `null` when the target declares none. */
+    readonly endpoint: string | null;
+    /** Whether the endpoint accepted the notification (2xx response). */
+    readonly delivered: boolean;
+    /** The notification's HTTP status (`0` when not sent or the POST threw). */
+    readonly status: number;
+}
+/**
+ * Discover `target`'s Webmention endpoint and notify it that `source` links to
+ * it. Targets that declare no endpoint are skipped (`delivered: false`).
+ */
+export declare function sendWebmention(source: string, target: string, options?: SendOptions): Promise<SendResult>;
+/**
+ * Notify many targets, one {@link SendResult} per target (input order
+ * preserved). Failures are reported, never thrown, so one dead target does not
+ * sink the rest.
+ */
+export declare function sendWebmentions(source: string, targets: readonly string[], options?: SendOptions): Promise<SendResult[]>;
+//# sourceMappingURL=sender.d.ts.map

package/dist/sender.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sender.d.ts","sourceRoot":"","sources":["../src/sender.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAIL,KAAK,MAAM,EACX,KAAK,OAAO,EACb,MAAM,UAAU,CAAC;AAElB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAIzC,oEAAoE;AACpE,MAAM,WAAW,WAAW;IAC1B,qEAAqE;IACrE,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC;IAC3B,sEAAsE;IACtE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,oFAAoF;IACpF,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,uDAAuD;AACvD,MAAM,WAAW,UAAU;IACzB,wCAAwC;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,qEAAqE;IACrE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,UAAU,CAAC,CA+DrB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,UAAU,EAAE,CAAC,CAIvB"}

package/dist/sender.js

@@ -0,0 +1,80 @@
+/**
+ * `@dwk/webmention` — sender.
+ *
+ * On publish, notify each outbound target: discover its Webmention endpoint
+ * (see {@link discoverEndpoint}) and POST a `source`/`target` notification as
+ * `application/x-www-form-urlencoded`. See `spec/packages/webmention.md`.
+ *
+ * @packageDocumentation
+ */
+import { hostFromUrl, noopLogger, noopMetrics, } from "@dwk/log";
+import { discoverEndpoint } from "./discovery";
+import { WebmentionLogEvent } from "./log";
+import { safeFetch } from "./safe-fetch";
+/**
+ * Discover `target`'s Webmention endpoint and notify it that `source` links to
+ * it. Targets that declare no endpoint are skipped (`delivered: false`).
+ */
+export async function sendWebmention(source, target, options) {
+    const doFetch = options?.fetch ?? ((input, init) => fetch(input, init));
+    const logger = options?.logger ?? noopLogger;
+    const metrics = options?.metrics ?? noopMetrics;
+    const logOutcome = (result) => {
+        const fields = {
+            targetHost: hostFromUrl(target),
+            endpointHost: result.endpoint === null ? undefined : hostFromUrl(result.endpoint),
+            delivered: result.delivered,
+            status: result.status,
+        };
+        logger.info(WebmentionLogEvent.SendCompleted, fields);
+        // Mirror the log as a counter so "deliveries (by delivered/status)" charts.
+        metrics.count(WebmentionLogEvent.SendCompleted, fields);
+        return result;
+    };
+    const endpoint = await discoverEndpoint(target, {
+        fetch: doFetch,
+        logger,
+        metrics,
+    });
+    // Only notify http(s) endpoints: a page could advertise a `javascript:`,
+    // `file:`, or `mailto:` endpoint, which we must never fetch. `URL.protocol`
+    // is already lowercased and includes the trailing colon.
+    if (endpoint === null) {
+        return logOutcome({ target, endpoint: null, delivered: false, status: 0 });
+    }
+    const protocol = new URL(endpoint).protocol;
+    if (protocol !== "http:" && protocol !== "https:") {
+        return logOutcome({ target, endpoint: null, delivered: false, status: 0 });
+    }
+    const body = new URLSearchParams({ source, target }).toString();
+    let response;
+    try {
+        // Notify through the SSRF-safe wrapper: the discovered endpoint host (and
+        // any redirect hop) is validated against private/loopback ranges and the
+        // POST is bounded by a timeout.
+        const result = await safeFetch(doFetch, endpoint, {
+            method: "POST",
+            headers: { "content-type": "application/x-www-form-urlencoded" },
+            body,
+        }, { logger });
+        response = result.response;
+    }
+    catch {
+        return logOutcome({ target, endpoint, delivered: false, status: 0 });
+    }
+    return logOutcome({
+        target,
+        endpoint,
+        delivered: response.ok,
+        status: response.status,
+    });
+}
+/**
+ * Notify many targets, one {@link SendResult} per target (input order
+ * preserved). Failures are reported, never thrown, so one dead target does not
+ * sink the rest.
+ */
+export function sendWebmentions(source, targets, options) {
+    return Promise.all(targets.map((target) => sendWebmention(source, target, options)));
+}
+//# sourceMappingURL=sender.js.map

package/dist/sender.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sender.js","sourceRoot":"","sources":["../src/sender.ts"],"names":[],"mappings":"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"}