@dwk/webmention 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 David W. Keith
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,140 @@
+# `@dwk/webmention`
+
+> Webmention (W3C) receiver + sender. Endpoint package.
+
+Part of the [`@dwk` IndieWeb + Solid cohort](../../README.md). See the
+[package specification](../../spec/packages/webmention.md) for the full
+requirements.
+
+The receiver validates `source`/`target` **synchronously**, returns
+`202 Accepted`, and enqueues the pair for **asynchronous** link verification.
+The queue consumer fetches the source, confirms it links to the target, and
+persists (or removes) the mention in an inbox. The sender discovers a target's
+Webmention endpoint and notifies it on publish. Cloudflare specifics (Queue,
+D1) are confined to this package; the parsing and verification logic is pure and
+unit-tests without a Workers runtime.
+
+## Receiver
+
+```ts
+import { createWebmention } from "@dwk/webmention";
+
+const webmention = createWebmention({ baseUrl: "https://example.com" });
+
+// In your Worker's fetch handler, mount under any path prefix:
+//   POST /webmention   (application/x-www-form-urlencoded: source, target)
+return webmention(request, env, ctx);
+```
+
+`createWebmention` validates up front — both fields are syntactically valid
+`http(s)` URLs, `source` ≠ `target`, and `target` is a resource under this
+receiver's control (`baseUrl`'s host, plus any `allowedHosts`). Invalid requests
+get `400` with a stable error code in the body; valid ones are enqueued and get
+`202`. Other methods get `405`. The handler **fails loudly** if the required
+`WEBMENTION_QUEUE` binding is missing.
+
+### Async verification (queue consumer)
+
+```ts
+import { createWebmentionQueueConsumer } from "@dwk/webmention";
+
+const verify = createWebmentionQueueConsumer({ baseUrl: "https://example.com" });
+
+export default {
+  fetch: webmention,
+  queue: verify, // bound to WEBMENTION_QUEUE
+};
+```
+
+The consumer fetches each `source`, checks for a link to `target`, and **upserts**
+the verified mention into the inbox — or **removes** it when the source no longer
+links. Jobs that throw are retried.
+
+## Sender
+
+```ts
+import { sendWebmentions } from "@dwk/webmention";
+
+// On publish, notify each outbound link's target:
+const results = await sendWebmentions(myPostUrl, outboundLinks);
+```
+
+Endpoint discovery follows the spec: 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 — honoring a
+`<base href>` and ignoring endpoints inside HTML comments. The legacy
+`http://webmention.org/` rel is also accepted. The sender refuses to POST a
+discovered endpoint that is not `http(s)`.
+
+## Bindings (`Env` fragment)
+
+| Binding            | Type         | Required | Purpose                                  |
+| ------------------ | ------------ | -------- | ---------------------------------------- |
+| `WEBMENTION_QUEUE` | `Queue`      | yes      | Async verification of received mentions. |
+| `WEBMENTION_INBOX` | `D1Database` | yes\*    | Default inbox for verified mentions.     |
+
+\* `WEBMENTION_INBOX` is optional when you pass a custom `inbox` in config — for
+example, to store mentions in the `@dwk/solid-pod` Durable Object when composed
+into a pod.
+
+## Config
+
+| Field          | Type         | Default        | Purpose                                       |
+| -------------- | ------------ | -------------- | --------------------------------------------- |
+| `baseUrl`      | `string`     | —              | Receiver origin; `target` must live under it. |
+| `allowedHosts` | `string[]`   | `[]`           | Extra controlled hostnames.                   |
+| `inbox`        | `InboxStore` | D1 from `env`  | Override the default inbox store.             |
+| `fetch`        | `FetchLike`  | global `fetch` | Override `fetch` (verification/discovery).     |
+| `logger`       | `Logger`     | `noopLogger`   | Structured logs (see `@dwk/log`).             |
+| `metrics`      | `Metrics`    | `noopMetrics`  | Queryable counters (see `@dwk/log`).          |
+
+## Observability
+
+Logging and metrics are **opt-in and injected** (see [`@dwk/log`](../log)),
+defaulting to no-ops. Both seams share one event vocabulary
+(`WebmentionLogEvent`), so a log line and its counter line up — SSRF blocks (by
+reason), receive accepted/rejected, verification outcomes (by links/status),
+queue retries (by reason), and send outcomes (by delivered/status):
+
+```ts
+import { consoleLogger, analyticsEngineMetrics } from "@dwk/log";
+import { createWebmention } from "@dwk/webmention";
+
+const webmention = createWebmention({
+  baseUrl: "https://example.com",
+  logger: consoleLogger({ minLevel: "info" }),
+  // env.WEBMENTION_METRICS is an AnalyticsEngineDataset binding.
+  metrics: analyticsEngineMetrics(env.WEBMENTION_METRICS),
+});
+```
+
+Both honor the redaction policy: only sanitized hosts, status, reason codes,
+booleans, and counts — never tokens, bodies, or full URLs.
+
+## Federation handoff (documented config, not core code)
+
+To bridge to the fediverse, emit `h-card` / `h-entry` markup on your published
+pages and include [Bridgy Fed](https://fed.brid.gy/) (`https://fed.brid.gy/`) as
+one of the outbound targets you pass to `sendWebmentions`. Bridgy Fed discovers
+your page's Webmention endpoint and handles the ActivityPub translation; no
+special code in this package is required.
+
+## Conformance
+
+The discovery and verification logic is unit-tested against the
+[webmention.rocks](https://webmention.rocks/) discovery cases — including exact
+`rel` matching (not naïve substring), endpoints hidden in HTML comments, escaped
+HTML, empty vs. missing `href`, `<base href>` resolution, query-string
+endpoints, and multiple/ordered endpoint advertisements.
+
+## Scope
+
+- Verification is **link-level**: the source document must contain an
+  `href`/`src` resolving to the target. Full **Microformats2** extraction (author,
+  content, mention type) is intentionally out of scope to keep the Worker bundle
+  within the runtime budget; the inbox records `source`, `target`, and the
+  verification time.
+
+## License
+
+[ISC](../../LICENSE)

package/dist/discovery.d.ts

@@ -0,0 +1,43 @@
+/**
+ * `@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 { type Logger, type Metrics } from "@dwk/log";
+import { type FetchLike } from "./fetch";
+/**
+ * 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 declare function findWebmentionEndpoint(linkHeader: string | null, html: string, documentUrl: string): Promise<string | 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 declare function discoverEndpoint(target: string, options?: DiscoverOptions): Promise<string | null>;
+//# sourceMappingURL=discovery.d.ts.map

package/dist/discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../src/discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAA2B,KAAK,MAAM,EAAE,KAAK,OAAO,EAAE,MAAM,UAAU,CAAC;AAQ9E,OAAO,EAAkB,KAAK,SAAS,EAAE,MAAM,SAAS,CAAC;AA4BzD;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAC1C,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAyCxB;AAED,4CAA4C;AAC5C,MAAM,WAAW,eAAe;IAC9B,qEAAqE;IACrE,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC;IAC3B,yEAAyE;IACzE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAwCxB"}

package/dist/discovery.js

@@ -0,0 +1,128 @@
+/**
+ * `@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 } from "@dwk/log";
+import { isHtmlContentType, parseLinkHeader, resolveUrl, scanElements, splitTokens, } from "./html";
+import { readBodyCapped } 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) {
+    if (rel.toLowerCase() === "webmention") {
+        return true;
+    }
+    let href;
+    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, html, documentUrl) {
+    // 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;
+}
+/**
+ * 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, 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, 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);
+}
+//# sourceMappingURL=discovery.js.map

package/dist/discovery.js.map

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

package/dist/fetch.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `@dwk/webmention` — injectable `fetch` type.
+ *
+ * Endpoint discovery, source verification, and sending all perform HTTP I/O.
+ * They accept a {@link FetchLike} so callers can inject a stub in tests (no
+ * network) and so the package never reaches for a global it didn't receive.
+ *
+ * @packageDocumentation
+ */
+/** A minimal, injectable `fetch` signature. */
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+/**
+ * Default cap on a fetched document body (2 MB). Discovery and verification
+ * only need to scan markup for links; a larger body is almost certainly hostile
+ * or irrelevant, and buffering it would risk an OOM (the Worker memory limit is
+ * 128 MB). See `spec/non-functional-requirements.md`.
+ */
+export declare const MAX_BODY_BYTES: number;
+/**
+ * Read a response body as text, refusing bodies larger than `maxBytes`.
+ *
+ * A declared `Content-Length` over the cap is rejected up front; the stream is
+ * then read incrementally and aborted the moment the cap is exceeded, so a
+ * missing or lying `Content-Length` cannot force the whole body into memory.
+ * Returns `null` when the body is too large or cannot be read.
+ */
+export declare function readBodyCapped(response: Response, maxBytes?: number): Promise<string | null>;
+//# sourceMappingURL=fetch.d.ts.map

package/dist/fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../src/fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,+CAA+C;AAC/C,MAAM,MAAM,SAAS,GAAG,CACtB,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,WAAW,KACf,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEvB;;;;;GAKG;AACH,eAAO,MAAM,cAAc,QAAkB,CAAC;AAE9C;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,QAAQ,EAAE,QAAQ,EAClB,QAAQ,SAAiB,GACxB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAgDxB"}

package/dist/fetch.js

@@ -0,0 +1,73 @@
+/**
+ * `@dwk/webmention` — injectable `fetch` type.
+ *
+ * Endpoint discovery, source verification, and sending all perform HTTP I/O.
+ * They accept a {@link FetchLike} so callers can inject a stub in tests (no
+ * network) and so the package never reaches for a global it didn't receive.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Default cap on a fetched document body (2 MB). Discovery and verification
+ * only need to scan markup for links; a larger body is almost certainly hostile
+ * or irrelevant, and buffering it would risk an OOM (the Worker memory limit is
+ * 128 MB). See `spec/non-functional-requirements.md`.
+ */
+export const MAX_BODY_BYTES = 2 * 1024 * 1024;
+/**
+ * Read a response body as text, refusing bodies larger than `maxBytes`.
+ *
+ * A declared `Content-Length` over the cap is rejected up front; the stream is
+ * then read incrementally and aborted the moment the cap is exceeded, so a
+ * missing or lying `Content-Length` cannot force the whole body into memory.
+ * Returns `null` when the body is too large or cannot be read.
+ */
+export async function readBodyCapped(response, maxBytes = MAX_BODY_BYTES) {
+    const declared = response.headers.get("content-length");
+    if (declared !== null) {
+        const length = Number.parseInt(declared, 10);
+        if (Number.isFinite(length) && length > maxBytes) {
+            return null;
+        }
+    }
+    const body = response.body;
+    if (body === null) {
+        try {
+            const text = await response.text();
+            return text.length > maxBytes ? null : text;
+        }
+        catch {
+            return null;
+        }
+    }
+    const reader = body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done) {
+                break;
+            }
+            if (value !== undefined) {
+                total += value.byteLength;
+                if (total > maxBytes) {
+                    await reader.cancel();
+                    return null;
+                }
+                chunks.push(value);
+            }
+        }
+    }
+    catch {
+        return null;
+    }
+    const merged = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        merged.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return new TextDecoder().decode(merged);
+}
+//# sourceMappingURL=fetch.js.map

package/dist/fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.js","sourceRoot":"","sources":["../src/fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AAE9C;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,QAAkB,EAClB,QAAQ,GAAG,cAAc;IAEzB,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IACxD,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACtB,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;QAC7C,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,QAAQ,EAAE,CAAC;YACjD,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC;IAC3B,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAClB,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;YACnC,OAAO,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;QAC9C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;IAChC,MAAM,MAAM,GAAiB,EAAE,CAAC;IAChC,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,CAAC;QACH,SAAS,CAAC;YACR,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;YAC5C,IAAI,IAAI,EAAE,CAAC;gBACT,MAAM;YACR,CAAC;YACD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACxB,KAAK,IAAI,KAAK,CAAC,UAAU,CAAC;gBAC1B,IAAI,KAAK,GAAG,QAAQ,EAAE,CAAC;oBACrB,MAAM,MAAM,CAAC,MAAM,EAAE,CAAC;oBACtB,OAAO,IAAI,CAAC;gBACd,CAAC;gBACD,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACrB,CAAC;QACH,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC;IACrC,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,UAAU,CAAC;IAC7B,CAAC;IACD,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AAC1C,CAAC"}

package/dist/html.d.ts

@@ -0,0 +1,68 @@
+/**
+ * `@dwk/webmention` — HTML / `Link`-header parsing helpers.
+ *
+ * Shared by endpoint discovery (sender) and source verification (receiver).
+ * `Link`-header parsing is plain string scanning; HTML scanning uses the
+ * Workers runtime's streaming `HTMLRewriter` rather than regex tag matching, so
+ * it handles comments, attribute quoting, and malformed markup correctly
+ * without pulling a parser into the bundle (`HTMLRewriter` is built into the
+ * runtime — zero script-size cost; see `spec/non-functional-requirements.md`).
+ *
+ * Because `HTMLRewriter` is a `workerd` global, the HTML scanners are async and
+ * exercised under the Workers test pool, not bare Node.
+ *
+ * @packageDocumentation
+ */
+/** A parsed `Link` header entry: its target URI and `rel` tokens. */
+export interface LinkHeaderEntry {
+    readonly uri: string;
+    readonly rels: readonly string[];
+}
+/**
+ * Parse an HTTP `Link` header into entries. Handles multiple comma-separated
+ * links and semicolon-separated parameters, e.g.
+ * `<https://a.example/webmention>; rel="webmention"`.
+ *
+ * Entries with no `rel` parameter are dropped; an empty URI (`<>`) is kept so
+ * the caller can resolve it against the document URL (a Webmention endpoint
+ * advertised at the page itself).
+ */
+export declare function parseLinkHeader(value: string | null): LinkHeaderEntry[];
+/**
+ * Whether a `Content-Type` value names an HTML document (`text/html` or
+ * `application/xhtml+xml`). Compares the media type's essence — the part before
+ * any `;` parameters — case-insensitively, so `text/html; charset=utf-8`
+ * matches but an unrelated type carrying `text/html` inside a parameter does
+ * not.
+ */
+export declare function isHtmlContentType(contentType: string): boolean;
+/**
+ * Whether a `Content-Type` value names a JSON document (`application/json` or a
+ * `+json`-suffixed type such as `application/activity+json`). Compares the media
+ * type's essence — the part before any `;` parameters — case-insensitively.
+ */
+export declare function isJsonContentType(contentType: string): boolean;
+/** Split a whitespace-separated token list (e.g. a `rel` value) into tokens. */
+export declare function splitTokens(value: string | null): string[];
+/** Resolve `uri` against `base`, returning a normalized absolute URL or `null`. */
+export declare function resolveUrl(uri: string, base: string): string | null;
+/** An element seen by {@link scanElements}: its (lowercased) tag name and the requested attributes. */
+export interface ScannedElement {
+    /** Lowercased tag name, e.g. `"a"`, `"link"`, `"base"`. */
+    readonly name: string;
+    /** Requested attribute values; `null` when the attribute is absent, `""` when present but empty. */
+    readonly attrs: Readonly<Record<string, string | null>>;
+}
+/**
+ * Scan `html` with the runtime's streaming `HTMLRewriter`, returning — in
+ * document order — every element matching `selector` together with the
+ * requested attribute values.
+ *
+ * Using a real tokenizer (rather than regex) means elements inside comments are
+ * never reported (the parser treats comment contents as text, satisfying
+ * webmention.rocks discovery test 13), attribute quoting is handled correctly,
+ * and a `data-href` attribute is never mistaken for `href`. An absent attribute
+ * is reported as `null`; a present-but-empty one (`href=""`) as `""`.
+ */
+export declare function scanElements(html: string, selector: string, attrNames: readonly string[]): Promise<ScannedElement[]>;
+//# sourceMappingURL=html.d.ts.map

package/dist/html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"html.d.ts","sourceRoot":"","sources":["../src/html.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,qEAAqE;AACrE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,eAAe,EAAE,CAiBvE;AA8ED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAG9D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAG9D;AAED,gFAAgF;AAChF,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,EAAE,CAQ1D;AAED,mFAAmF;AACnF,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMnE;AAED,uGAAuG;AACvG,MAAM,WAAW,cAAc;IAC7B,2DAA2D;IAC3D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oGAAoG;IACpG,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC;CACzD;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,OAAO,CAAC,cAAc,EAAE,CAAC,CAc3B"}