@dwk/webmention 0.1.0-beta.0

package/dist/validate.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `@dwk/webmention` — synchronous receiver validation.
+ *
+ * The Webmention receiver MUST validate `source` and `target` up front, before
+ * returning `202 Accepted` and before any network work, to reject malformed or
+ * foreign requests and prevent queue-exhaustion / spam. This module holds that
+ * pure check: plain strings in, a decision out. See `spec/packages/webmention.md`.
+ *
+ * @packageDocumentation
+ */
+/** Stable, locale-independent codes for an up-front validation failure. */
+export type WebmentionValidationError = "missing_source" | "missing_target" | "invalid_source" | "invalid_target" | "source_equals_target" | "target_not_supported";
+/** Inputs to {@link validateWebmentionParams}. */
+export interface ValidateParams {
+    /** The `source` form field (or `null` when absent). */
+    readonly source: string | null;
+    /** The `target` form field (or `null` when absent). */
+    readonly target: string | null;
+    /** Base URL of this receiver; `target` must live under its origin. */
+    readonly baseUrl: string;
+    /**
+     * Additional hostnames (besides `baseUrl`'s) that this receiver controls.
+     * Useful when one Worker fronts several domains.
+     */
+    readonly allowedHosts?: readonly string[];
+}
+/** Result of {@link validateWebmentionParams}. */
+export type ValidationResult = {
+    readonly ok: true;
+    readonly source: string;
+    readonly target: string;
+} | {
+    readonly ok: false;
+    readonly error: WebmentionValidationError;
+};
+/**
+ * Validate a received `source`/`target` pair synchronously.
+ *
+ * Checks, in order: both fields present, both syntactically valid `http(s)`
+ * URLs, `source` ≠ `target`, and `target` is a resource under this receiver's
+ * control (its host matches `baseUrl` or `allowedHosts`). Never performs I/O.
+ *
+ * @returns `{ ok: true, source, target }` with normalized URLs on success, or
+ * `{ ok: false, error }` with a stable {@link WebmentionValidationError}.
+ */
+export declare function validateWebmentionParams(params: ValidateParams): ValidationResult;
+//# sourceMappingURL=validate.d.ts.map

package/dist/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,2EAA2E;AAC3E,MAAM,MAAM,yBAAyB,GACjC,gBAAgB,GAChB,gBAAgB,GAChB,gBAAgB,GAChB,gBAAgB,GAChB,sBAAsB,GACtB,sBAAsB,CAAC;AAE3B,kDAAkD;AAClD,MAAM,WAAW,cAAc;IAC7B,uDAAuD;IACvD,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,uDAAuD;IACvD,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3C;AAED,kDAAkD;AAClD,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACvE;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,yBAAyB,CAAA;CAAE,CAAC;AAetE;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,cAAc,GACrB,gBAAgB,CAgClB"}

package/dist/validate.js

@@ -0,0 +1,76 @@
+/**
+ * `@dwk/webmention` — synchronous receiver validation.
+ *
+ * The Webmention receiver MUST validate `source` and `target` up front, before
+ * returning `202 Accepted` and before any network work, to reject malformed or
+ * foreign requests and prevent queue-exhaustion / spam. This module holds that
+ * pure check: plain strings in, a decision out. See `spec/packages/webmention.md`.
+ *
+ * @packageDocumentation
+ */
+function parseHttpUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        return null;
+    }
+    return url;
+}
+/**
+ * Validate a received `source`/`target` pair synchronously.
+ *
+ * Checks, in order: both fields present, both syntactically valid `http(s)`
+ * URLs, `source` ≠ `target`, and `target` is a resource under this receiver's
+ * control (its host matches `baseUrl` or `allowedHosts`). Never performs I/O.
+ *
+ * @returns `{ ok: true, source, target }` with normalized URLs on success, or
+ * `{ ok: false, error }` with a stable {@link WebmentionValidationError}.
+ */
+export function validateWebmentionParams(params) {
+    const { source, target, baseUrl, allowedHosts } = params;
+    if (source === null || source === "") {
+        return { ok: false, error: "missing_source" };
+    }
+    if (target === null || target === "") {
+        return { ok: false, error: "missing_target" };
+    }
+    const sourceUrl = parseHttpUrl(source);
+    if (sourceUrl === null) {
+        return { ok: false, error: "invalid_source" };
+    }
+    const targetUrl = parseHttpUrl(target);
+    if (targetUrl === null) {
+        return { ok: false, error: "invalid_target" };
+    }
+    if (sourceUrl.toString() === targetUrl.toString()) {
+        return { ok: false, error: "source_equals_target" };
+    }
+    if (!isControlledHost(targetUrl.host, baseUrl, allowedHosts)) {
+        return { ok: false, error: "target_not_supported" };
+    }
+    return {
+        ok: true,
+        source: sourceUrl.toString(),
+        target: targetUrl.toString(),
+    };
+}
+function isControlledHost(host, baseUrl, allowedHosts) {
+    const allowed = new Set();
+    try {
+        allowed.add(new URL(baseUrl).host.toLowerCase());
+    }
+    catch {
+        // A malformed baseUrl is a configuration error; fall through with no host
+        // allowed so every target is rejected rather than silently accepted.
+    }
+    for (const entry of allowedHosts ?? []) {
+        allowed.add(entry.toLowerCase());
+    }
+    return allowed.has(host.toLowerCase());
+}
+//# sourceMappingURL=validate.js.map

package/dist/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AA+BH,SAAS,YAAY,CAAC,KAAa;IACjC,IAAI,GAAQ,CAAC;IACb,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC1D,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,wBAAwB,CACtC,MAAsB;IAEtB,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,GAAG,MAAM,CAAC;IAEzD,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,KAAK,EAAE,EAAE,CAAC;QACrC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAChD,CAAC;IACD,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,KAAK,EAAE,EAAE,CAAC;QACrC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAChD,CAAC;IAED,MAAM,SAAS,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IACvC,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;QACvB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAChD,CAAC;IACD,MAAM,SAAS,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IACvC,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;QACvB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAChD,CAAC;IAED,IAAI,SAAS,CAAC,QAAQ,EAAE,KAAK,SAAS,CAAC,QAAQ,EAAE,EAAE,CAAC;QAClD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,sBAAsB,EAAE,CAAC;IACtD,CAAC;IAED,IAAI,CAAC,gBAAgB,CAAC,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,YAAY,CAAC,EAAE,CAAC;QAC7D,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,sBAAsB,EAAE,CAAC;IACtD,CAAC;IAED,OAAO;QACL,EAAE,EAAE,IAAI;QACR,MAAM,EAAE,SAAS,CAAC,QAAQ,EAAE;QAC5B,MAAM,EAAE,SAAS,CAAC,QAAQ,EAAE;KAC7B,CAAC;AACJ,CAAC;AAED,SAAS,gBAAgB,CACvB,IAAY,EACZ,OAAe,EACf,YAA2C;IAE3C,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,IAAI,CAAC;QACH,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;IACnD,CAAC;IAAC,MAAM,CAAC;QACP,0EAA0E;QAC1E,qEAAqE;IACvE,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,YAAY,IAAI,EAAE,EAAE,CAAC;QACvC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC;IACnC,CAAC;IACD,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;AACzC,CAAC"}

package/dist/verify.d.ts

@@ -0,0 +1,61 @@
+/**
+ * `@dwk/webmention` — asynchronous source verification (receiver side).
+ *
+ * After the receiver has returned `202 Accepted`, a queued worker fetches the
+ * `source` and confirms it actually links to `target` (Webmention §3.2.1).
+ * Verification is link-level: the source document must contain a link
+ * (`href`/`src`) that resolves to the target. Full Microformats2 extraction is
+ * intentionally out of scope here — it would pull a parser into the Worker
+ * bundle the runtime budget rules out. See `spec/packages/webmention.md`.
+ *
+ * @packageDocumentation
+ */
+import { type Logger, type Metrics } from "@dwk/log";
+import { type FetchLike } from "./fetch";
+/**
+ * Extract every absolute link URL (`href` and `src`) from an HTML document,
+ * resolved against `baseUrl`. `href` links are listed before `src` links.
+ *
+ * Async because HTML scanning runs through the runtime's `HTMLRewriter`, which
+ * also means links inside comments are ignored without a separate stripping
+ * pass.
+ */
+export declare function extractLinks(html: string, baseUrl: string): Promise<string[]>;
+/**
+ * Decide whether `body` (a fetched source document) links to `target`.
+ *
+ * HTML bodies are scanned for an `href`/`src` resolving to the target. Other
+ * content types require an **exact** match of the target URL (Webmention
+ * §3.2.2), not a loose substring: a JSON body must carry a string value equal to
+ * the target, and any other (e.g. plain text) body must contain the target as a
+ * standalone URL token.
+ */
+export declare function sourceLinksTo(body: string, target: string, baseUrl: string, contentType: string): Promise<boolean>;
+/** Options for {@link verifySource}. */
+export interface VerifyOptions {
+    /** `fetch` implementation to use; defaults to the global `fetch`. */
+    readonly fetch?: FetchLike;
+    /** Logger for verification outcomes/failures; defaults to a no-op. */
+    readonly logger?: Logger;
+    /** Metrics sink for verification-outcome counters; defaults to a no-op. */
+    readonly metrics?: Metrics;
+}
+/** Outcome of fetching and checking a source document. */
+export interface VerifyResult {
+    /** Whether the source links to the target. */
+    readonly links: boolean;
+    /** The source's HTTP status (`0` when the fetch threw). */
+    readonly status: number;
+}
+/**
+ * Fetch `source` and verify that it links to `target`.
+ *
+ * Fetches through the SSRF-safe wrapper ({@link safeFetch}): the source host —
+ * and every redirect hop — is validated against private/loopback/link-local
+ * ranges, redirects are capped, and the request is bounded by a timeout.
+ * Relative links resolve against the final URL. A failed, blocked, or non-2xx
+ * fetch yields `{ links: false }` — a removed/unreachable source no longer
+ * endorses the mention.
+ */
+export declare function verifySource(source: string, target: string, options?: VerifyOptions): Promise<VerifyResult>;
+//# sourceMappingURL=verify.d.ts.map

package/dist/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAIL,KAAK,MAAM,EACX,KAAK,OAAO,EACb,MAAM,UAAU,CAAC;AAOlB,OAAO,EAAkB,KAAK,SAAS,EAAE,MAAM,SAAS,CAAC;AAWzD;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,EAAE,CAAC,CA6BnB;AAqED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,OAAO,CAAC,CA4BlB;AAED,wCAAwC;AACxC,MAAM,WAAW,aAAa;IAC5B,qEAAqE;IACrE,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC;IAC3B,sEAAsE;IACtE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAyBD,0DAA0D;AAC1D,MAAM,WAAW,YAAY;IAC3B,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,2DAA2D;IAC3D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,YAAY,CAAC,CAgDvB"}

package/dist/verify.js

@@ -0,0 +1,216 @@
+/**
+ * `@dwk/webmention` — asynchronous source verification (receiver side).
+ *
+ * After the receiver has returned `202 Accepted`, a queued worker fetches the
+ * `source` and confirms it actually links to `target` (Webmention §3.2.1).
+ * Verification is link-level: the source document must contain a link
+ * (`href`/`src`) that resolves to the target. Full Microformats2 extraction is
+ * intentionally out of scope here — it would pull a parser into the Worker
+ * bundle the runtime budget rules out. See `spec/packages/webmention.md`.
+ *
+ * @packageDocumentation
+ */
+import { hostFromUrl, noopLogger, noopMetrics, } from "@dwk/log";
+import { isHtmlContentType, isJsonContentType, resolveUrl, scanElements, } from "./html";
+import { readBodyCapped } from "./fetch";
+import { WebmentionLogEvent } from "./log";
+import { safeFetch } from "./safe-fetch";
+/** Elements whose `href` may constitute a link to the target. */
+const HREF_TAGS = new Set(["a", "link", "area"]);
+/** Elements whose `src` may constitute a link to the target. */
+const SRC_TAGS = new Set(["img", "video", "audio", "source", "track"]);
+const LINK_SELECTOR = "base, a, link, area, img, video, audio, source, track";
+/**
+ * Extract every absolute link URL (`href` and `src`) from an HTML document,
+ * resolved against `baseUrl`. `href` links are listed before `src` links.
+ *
+ * Async because HTML scanning runs through the runtime's `HTMLRewriter`, which
+ * also means links inside comments are ignored without a separate stripping
+ * pass.
+ */
+export async function extractLinks(html, baseUrl) {
+    const elements = await scanElements(html, LINK_SELECTOR, ["href", "src"]);
+    // The first <base href> anywhere in the document governs relative resolution.
+    let documentBase = baseUrl;
+    for (const el of elements) {
+        if (el.name === "base" && el.attrs.href) {
+            documentBase = resolveUrl(el.attrs.href, baseUrl) ?? baseUrl;
+            break;
+        }
+    }
+    const links = [];
+    const collect = (tags, attr) => {
+        for (const el of elements) {
+            if (!tags.has(el.name)) {
+                continue;
+            }
+            const value = el.attrs[attr];
+            if (value === null || value === undefined || value === "") {
+                continue;
+            }
+            const resolved = resolveUrl(value, documentBase);
+            if (resolved !== null) {
+                links.push(resolved);
+            }
+        }
+    };
+    collect(HREF_TAGS, "href");
+    collect(SRC_TAGS, "src");
+    return links;
+}
+/**
+ * Characters that unambiguously continue a URL token: an alphanumeric, or a
+ * structural delimiter (path / query / fragment / userinfo). One of these
+ * abutting the target means the target is part of a longer URL.
+ */
+const URL_CORE_CHAR = /[A-Za-z0-9_/\-~%+=&?#@]/;
+/**
+ * The full RFC 3986 URL character set (unreserved + reserved + `%`). Punctuation
+ * such as `.` `,` `;` `)` `]` is valid inside a URL but also routinely trails or
+ * wraps one in prose, so on its own it does not prove continuation — only when
+ * it is itself followed by a {@link URL_CORE_CHAR} (e.g. the `.` in `…/post.html`).
+ */
+const URL_CHAR = /[A-Za-z0-9\-._~:/?#[\]@!$&'()*+,;=%]/;
+/**
+ * Whether `body` contains `target` as a standalone URL token — present, with
+ * neither neighbour continuing a URL. This rejects the over-matches a bare
+ * substring admits (`…/post` inside `…/posting`, `…/target` inside
+ * `…/target/extra`, or the target as a suffix of a longer URL) while still
+ * accepting a target trailed by sentence punctuation or wrapped in brackets.
+ */
+function textHasUrlToken(body, target) {
+    for (let from = body.indexOf(target); from !== -1; from = body.indexOf(target, from + 1)) {
+        const before = from === 0 ? "" : (body[from - 1] ?? "");
+        const after = body[from + target.length] ?? "";
+        const afterNext = body[from + target.length + 1] ?? "";
+        // A preceding core URL char makes the target a suffix of a longer URL.
+        const beforeContinues = URL_CORE_CHAR.test(before);
+        // A following core URL char continues the URL; a punctuation URL char only
+        // continues it when itself followed by a core char (so `.html` continues,
+        // but a sentence-ending `.` or a wrapping `)` is a boundary).
+        const afterContinues = URL_CORE_CHAR.test(after) ||
+            (URL_CHAR.test(after) && URL_CORE_CHAR.test(afterNext));
+        if (!beforeContinues && !afterContinues) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Whether any string value within a parsed JSON value equals `target` exactly.
+ * Webmention §3.2.2 requires an exact match of the target URL in a non-HTML
+ * source, so a JSON body is walked for a string property value identical to the
+ * target rather than substring-scanned.
+ */
+function jsonHasTargetValue(value, target) {
+    if (typeof value === "string") {
+        return value === target;
+    }
+    if (Array.isArray(value)) {
+        return value.some((item) => jsonHasTargetValue(item, target));
+    }
+    if (value !== null && typeof value === "object") {
+        return Object.values(value).some((item) => jsonHasTargetValue(item, target));
+    }
+    return false;
+}
+/**
+ * Decide whether `body` (a fetched source document) links to `target`.
+ *
+ * HTML bodies are scanned for an `href`/`src` resolving to the target. Other
+ * content types require an **exact** match of the target URL (Webmention
+ * §3.2.2), not a loose substring: a JSON body must carry a string value equal to
+ * the target, and any other (e.g. plain text) body must contain the target as a
+ * standalone URL token.
+ */
+export async function sourceLinksTo(body, target, baseUrl, contentType) {
+    const normalizedTarget = resolveUrl(target, target);
+    if (normalizedTarget === null) {
+        return false;
+    }
+    if (isHtmlContentType(contentType)) {
+        return (await extractLinks(body, baseUrl)).some((link) => link === normalizedTarget);
+    }
+    if (isJsonContentType(contentType)) {
+        let parsed;
+        try {
+            parsed = JSON.parse(body);
+        }
+        catch {
+            // A body that claims to be JSON but does not parse cannot exact-match.
+            return false;
+        }
+        return (jsonHasTargetValue(parsed, target) ||
+            (normalizedTarget !== target &&
+                jsonHasTargetValue(parsed, normalizedTarget)));
+    }
+    return (textHasUrlToken(body, target) ||
+        (normalizedTarget !== target && textHasUrlToken(body, normalizedTarget)));
+}
+/**
+ * Record a verification outcome on both seams (sanitized hosts only) and return
+ * the result. The counter mirrors the log so "verification success rate" is
+ * chartable from the `links`/`status` fields.
+ */
+function recordVerifyOutcome(logger, metrics, source, target, result) {
+    const fields = {
+        sourceHost: hostFromUrl(source),
+        targetHost: hostFromUrl(target),
+        links: result.links,
+        status: result.status,
+    };
+    logger.info(WebmentionLogEvent.VerifyCompleted, fields);
+    metrics.count(WebmentionLogEvent.VerifyCompleted, fields);
+    return result;
+}
+/**
+ * Fetch `source` and verify that it links to `target`.
+ *
+ * Fetches through the SSRF-safe wrapper ({@link safeFetch}): the source host —
+ * and every redirect hop — is validated against private/loopback/link-local
+ * ranges, redirects are capped, and the request is bounded by a timeout.
+ * Relative links resolve against the final URL. A failed, blocked, or non-2xx
+ * fetch yields `{ links: false }` — a removed/unreachable source no longer
+ * endorses the mention.
+ */
+export async function verifySource(source, target, options) {
+    const doFetch = options?.fetch ?? ((input, init) => fetch(input, init));
+    const logger = options?.logger ?? noopLogger;
+    const metrics = options?.metrics ?? noopMetrics;
+    let response;
+    let base;
+    try {
+        const result = await safeFetch(doFetch, source, { method: "GET", headers: { accept: "text/html, */*" } }, { logger, metrics });
+        response = result.response;
+        base = result.url;
+    }
+    catch (err) {
+        // A blocked attempt is already logged as `ssrf.blocked` inside safeFetch;
+        // record the verification-level failure too so the outcome isn't silent.
+        logger.debug(WebmentionLogEvent.VerifyFetchFailed, {
+            sourceHost: hostFromUrl(source),
+            error: err instanceof Error ? err.name : "unknown",
+        });
+        return { links: false, status: 0 };
+    }
+    if (!response.ok) {
+        return recordVerifyOutcome(logger, metrics, source, target, {
+            links: false,
+            status: response.status,
+        });
+    }
+    const contentType = response.headers.get("content-type") ?? "";
+    const body = await readBodyCapped(response);
+    if (body === null) {
+        // Unreadable or oversized body: treat as no longer endorsing the mention.
+        return recordVerifyOutcome(logger, metrics, source, target, {
+            links: false,
+            status: response.status,
+        });
+    }
+    return recordVerifyOutcome(logger, metrics, source, target, {
+        links: await sourceLinksTo(body, target, base, contentType),
+        status: response.status,
+    });
+}
+//# sourceMappingURL=verify.js.map

package/dist/verify.js.map

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

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@dwk/webmention",
+  "version": "0.1.0-beta.0",
+  "description": "Webmention receiver (async verification queue) and sender.",
+  "keywords": [
+    "webmention",
+    "indieweb",
+    "w3c",
+    "cloudflare-workers"
+  ],
+  "type": "module",
+  "license": "ISC",
+  "author": "David W. Keith <me@dwk.io>",
+  "homepage": "https://github.com/davidwkeith/workers/tree/main/packages/webmention#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/davidwkeith/workers.git",
+    "directory": "packages/webmention"
+  },
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@dwk/log": "0.1.0-beta.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist"
+  }
+}

package/src/discovery.ts

@@ -0,0 +1,167 @@
+/**
+ * `@dwk/webmention` — Webmention endpoint discovery (sender side).
+ *
+ * Given a target URL, find its declared Webmention endpoint following the W3C
+ * discovery algorithm: the HTTP `Link` header (`rel=webmention`) wins, then the
+ * first `<link>`/`<a rel="webmention">` in document order, with relative URLs
+ * resolved against the (post-redirect) document URL. The legacy
+ * `http://webmention.org/` rel value is also accepted. See
+ * `spec/packages/webmention.md`.
+ *
+ * @packageDocumentation
+ */
+
+import { noopLogger, noopMetrics, type Logger, type Metrics } from "@dwk/log";
+import {
+  isHtmlContentType,
+  parseLinkHeader,
+  resolveUrl,
+  scanElements,
+  splitTokens,
+} from "./html";
+import { readBodyCapped, type FetchLike } from "./fetch";
+import { safeFetch } from "./safe-fetch";
+
+// The legacy rel values predating the standardized `webmention` token. They are
+// absolute URLs, so a candidate rel is normalized through `URL` before being
+// compared: `http://webmention.org` and `http://webmention.org/` then coincide
+// (tolerating the trailing slash developers commonly omit), while a look-alike
+// host like `http://webmention.org.evil.example/` parses to a different href and
+// is rejected — which a bare `startsWith` prefix test would not catch.
+const LEGACY_REL_HREFS = new Set([
+  "http://webmention.org/",
+  "http://webmention.org/webmention",
+]);
+
+function isWebmentionRel(rel: string): boolean {
+  if (rel.toLowerCase() === "webmention") {
+    return true;
+  }
+  let href: string;
+  try {
+    href = new URL(rel).href;
+  } catch {
+    // Not the standard token and not an absolute URL — not a webmention rel.
+    return false;
+  }
+  return LEGACY_REL_HREFS.has(href);
+}
+
+/**
+ * Find the Webmention endpoint declared by a fetched document.
+ *
+ * Pass the `Link` header value, the response body, and the document URL (used
+ * as the base for relative resolution). Returns the absolute endpoint URL or
+ * `null` when none is advertised. Async because HTML scanning runs through the
+ * runtime's `HTMLRewriter`.
+ */
+export async function findWebmentionEndpoint(
+  linkHeader: string | null,
+  html: string,
+  documentUrl: string,
+): Promise<string | null> {
+  // 1. HTTP Link header wins, in header order.
+  for (const entry of parseLinkHeader(linkHeader)) {
+    if (entry.rels.some(isWebmentionRel)) {
+      return resolveUrl(entry.uri, documentUrl);
+    }
+  }
+  // 2. Fall back to the first <link>/<a rel="webmention"> in document order,
+  //    resolving relative hrefs against the document's <base href> if present.
+  //    HTMLRewriter does not report elements inside comments, so a commented-out
+  //    endpoint is ignored without a separate stripping pass.
+  if (html === "") {
+    return null;
+  }
+  const elements = await scanElements(html, "base, link, a", ["rel", "href"]);
+  // The first <base href> anywhere in the document governs relative resolution.
+  let documentBase = documentUrl;
+  for (const el of elements) {
+    if (el.name === "base" && el.attrs.href) {
+      documentBase = resolveUrl(el.attrs.href, documentUrl) ?? documentUrl;
+      break;
+    }
+  }
+  for (const el of elements) {
+    if (el.name === "base") {
+      continue;
+    }
+    const rels = splitTokens(el.attrs.rel ?? null);
+    if (!rels.some(isWebmentionRel)) {
+      continue;
+    }
+    const href = el.attrs.href;
+    // A tag with no `href` attribute at all is malformed — skip it and keep
+    // looking (test 20). An empty `href=""` is valid and advertises the
+    // document itself as the endpoint (test 15).
+    if (href === null || href === undefined) {
+      continue;
+    }
+    return resolveUrl(href, documentBase);
+  }
+  return null;
+}
+
+/** Options for {@link discoverEndpoint}. */
+export interface DiscoverOptions {
+  /** `fetch` implementation to use; defaults to the global `fetch`. */
+  readonly fetch?: FetchLike;
+  /** Logger passed through to the SSRF-safe fetch; defaults to a no-op. */
+  readonly logger?: Logger;
+  /** Metrics sink passed through to the SSRF-safe fetch; defaults to a no-op. */
+  readonly metrics?: Metrics;
+}
+
+/**
+ * Fetch `target` and discover its Webmention endpoint.
+ *
+ * Fetches through the SSRF-safe wrapper ({@link safeFetch}): the target host —
+ * and every redirect hop — is validated against private/loopback/link-local
+ * ranges, redirects are capped, and the request is bounded by a timeout. The
+ * endpoint resolves against the final URL. Returns the absolute endpoint URL,
+ * or `null` when discovery finds none or the fetch fails or is blocked.
+ */
+export async function discoverEndpoint(
+  target: string,
+  options?: DiscoverOptions,
+): Promise<string | null> {
+  const doFetch: FetchLike =
+    options?.fetch ?? ((input, init) => fetch(input, init));
+  const logger = options?.logger ?? noopLogger;
+  const metrics = options?.metrics ?? noopMetrics;
+
+  let response: Response;
+  let base: string;
+  try {
+    const result = await safeFetch(
+      doFetch,
+      target,
+      { method: "GET", headers: { accept: "text/html, */*" } },
+      { logger, metrics },
+    );
+    response = result.response;
+    base = result.url;
+  } catch {
+    return null;
+  }
+
+  const fromHeader = await findWebmentionEndpoint(
+    response.headers.get("link"),
+    "",
+    base,
+  );
+  if (fromHeader !== null) {
+    return fromHeader;
+  }
+
+  const contentType = response.headers.get("content-type") ?? "";
+  if (!isHtmlContentType(contentType)) {
+    return null;
+  }
+
+  const html = await readBodyCapped(response);
+  if (html === null) {
+    return null;
+  }
+  return findWebmentionEndpoint(null, html, base);
+}