@dwk/webmention 0.1.0-beta.0

package/dist/html.js

@@ -0,0 +1,183 @@
+/**
+ * `@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
+ */
+/**
+ * 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 function parseLinkHeader(value) {
+    if (value === null || value.trim() === "") {
+        return [];
+    }
+    const entries = [];
+    for (const part of splitLinks(value)) {
+        const match = /^\s*<([^>]*)>\s*(.*)$/.exec(part);
+        if (match === null) {
+            continue;
+        }
+        const uri = match[1] ?? "";
+        const rels = splitTokens(extractRel(match[2] ?? ""));
+        if (rels.length > 0) {
+            entries.push({ uri, rels });
+        }
+    }
+    return entries;
+}
+/**
+ * Split a `Link` header on top-level commas, respecting both the angle-bracket
+ * URI reference and double-quoted parameter values — so a comma inside
+ * `title="A, B"` or inside `<…>` does not split the entry.
+ */
+function splitLinks(value) {
+    const result = [];
+    let depth = 0;
+    let inQuotes = false;
+    let current = "";
+    for (let i = 0; i < value.length; i++) {
+        const char = value[i];
+        if (char === '"' && value[i - 1] !== "\\") {
+            inQuotes = !inQuotes;
+        }
+        else if (!inQuotes && char === "<") {
+            depth++;
+        }
+        else if (!inQuotes && char === ">") {
+            depth--;
+        }
+        if (char === "," && depth === 0 && !inQuotes) {
+            result.push(current);
+            current = "";
+        }
+        else {
+            current += char;
+        }
+    }
+    if (current.trim() !== "") {
+        result.push(current);
+    }
+    return result;
+}
+/**
+ * Split a `Link` entry's parameter string on top-level semicolons, respecting
+ * double-quoted values so a `;` inside a quoted value does not split a param.
+ */
+function splitParams(paramString) {
+    const result = [];
+    let inQuotes = false;
+    let current = "";
+    for (let i = 0; i < paramString.length; i++) {
+        const char = paramString[i];
+        if (char === '"' && paramString[i - 1] !== "\\") {
+            inQuotes = !inQuotes;
+        }
+        if (char === ";" && !inQuotes) {
+            result.push(current);
+            current = "";
+        }
+        else {
+            current += char;
+        }
+    }
+    if (current.trim() !== "") {
+        result.push(current);
+    }
+    return result;
+}
+/**
+ * Extract the `rel` parameter from a `Link` entry's parameter string. Matches
+ * the `rel` parameter exactly (per-parameter), so a `rel=` substring inside
+ * another parameter's quoted value (e.g. `title="my rel=x"`) is not mistaken
+ * for it.
+ */
+function extractRel(paramString) {
+    for (const param of splitParams(paramString)) {
+        const match = /^\s*rel\s*=\s*("([^"]*)"|'([^']*)'|[^;\s]+)\s*$/i.exec(param);
+        if (match !== null) {
+            return match[2] ?? match[3] ?? match[1] ?? null;
+        }
+    }
+    return null;
+}
+/**
+ * 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 function isHtmlContentType(contentType) {
+    const essence = contentType.split(";")[0]?.trim().toLowerCase() ?? "";
+    return essence === "text/html" || essence === "application/xhtml+xml";
+}
+/**
+ * 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 function isJsonContentType(contentType) {
+    const essence = contentType.split(";")[0]?.trim().toLowerCase() ?? "";
+    return essence === "application/json" || essence.endsWith("+json");
+}
+/** Split a whitespace-separated token list (e.g. a `rel` value) into tokens. */
+export function splitTokens(value) {
+    if (value === null) {
+        return [];
+    }
+    return value
+        .trim()
+        .split(/\s+/)
+        .filter((token) => token !== "");
+}
+/** Resolve `uri` against `base`, returning a normalized absolute URL or `null`. */
+export function resolveUrl(uri, base) {
+    try {
+        return new URL(uri, base).toString();
+    }
+    catch {
+        return 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 async function scanElements(html, selector, attrNames) {
+    const elements = [];
+    const rewriter = new HTMLRewriter().on(selector, {
+        element(el) {
+            const attrs = {};
+            for (const name of attrNames) {
+                attrs[name] = el.getAttribute(name);
+            }
+            elements.push({ name: el.tagName, attrs });
+        },
+    });
+    // Drive the parser to completion by consuming the transformed body.
+    await rewriter.transform(new Response(html)).text();
+    return elements;
+}
+//# sourceMappingURL=html.js.map

package/dist/html.js.map

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

package/dist/inbox.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `@dwk/webmention` — inbox store.
+ *
+ * Verified mentions are persisted to an inbox so they can be surfaced on the
+ * target resource. The default is a D1-backed store (strongly consistent —
+ * never KV, per `spec/non-functional-requirements.md`); when composed into a
+ * Solid Pod, a caller can supply an {@link InboxStore} backed by the
+ * `@dwk/solid-pod` Durable Object instead. The store keys on the
+ * `(source, target)` pair so re-verifying a mention updates it in place and a
+ * source that drops the link can be removed. See `spec/packages/webmention.md`.
+ *
+ * @packageDocumentation
+ */
+import type { D1Database } from "@cloudflare/workers-types";
+/** A verified Webmention: `source` links to `target`, confirmed at `verifiedAt`. */
+export interface VerifiedMention {
+    readonly source: string;
+    readonly target: string;
+    /** Verification time, epoch milliseconds. */
+    readonly verifiedAt: number;
+}
+/** Persistence surface for verified mentions. */
+export interface InboxStore {
+    /** Upsert a verified mention, keyed on `(source, target)`. */
+    store(mention: VerifiedMention): Promise<void>;
+    /** Remove a mention (e.g. the source dropped the link); no-op when absent. */
+    remove(source: string, target: string): Promise<void>;
+    /** List mentions, newest first; scoped to `target` when given. */
+    list(target?: string): Promise<VerifiedMention[]>;
+}
+/** Options for {@link createD1Inbox}. */
+export interface D1InboxOptions {
+    /** Table name to use; created if absent. Defaults to `webmentions`. */
+    readonly table?: string;
+}
+/**
+ * Build a D1-backed {@link InboxStore}. The backing table is created on first
+ * use if it does not already exist.
+ */
+export declare function createD1Inbox(db: D1Database, options?: D1InboxOptions): InboxStore;
+//# sourceMappingURL=inbox.d.ts.map

package/dist/inbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbox.d.ts","sourceRoot":"","sources":["../src/inbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAE5D,oFAAoF;AACpF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,6CAA6C;IAC7C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,iDAAiD;AACjD,MAAM,WAAW,UAAU;IACzB,8DAA8D;IAC9D,KAAK,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,8EAA8E;IAC9E,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,kEAAkE;IAClE,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;CACnD;AAED,yCAAyC;AACzC,MAAM,WAAW,cAAc;IAC7B,uEAAuE;IACvE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAQD;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,EAAE,EAAE,UAAU,EACd,OAAO,CAAC,EAAE,cAAc,GACvB,UAAU,CAmEZ"}

package/dist/inbox.js

@@ -0,0 +1,73 @@
+/**
+ * `@dwk/webmention` — inbox store.
+ *
+ * Verified mentions are persisted to an inbox so they can be surfaced on the
+ * target resource. The default is a D1-backed store (strongly consistent —
+ * never KV, per `spec/non-functional-requirements.md`); when composed into a
+ * Solid Pod, a caller can supply an {@link InboxStore} backed by the
+ * `@dwk/solid-pod` Durable Object instead. The store keys on the
+ * `(source, target)` pair so re-verifying a mention updates it in place and a
+ * source that drops the link can be removed. See `spec/packages/webmention.md`.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Build a D1-backed {@link InboxStore}. The backing table is created on first
+ * use if it does not already exist.
+ */
+export function createD1Inbox(db, options) {
+    const table = options?.table ?? "webmentions";
+    // Guard the identifier: it is interpolated into DDL, so only allow a safe
+    // set of characters rather than trusting the caller blindly.
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(table)) {
+        throw new Error(`@dwk/webmention: invalid inbox table name "${table}".`);
+    }
+    let ready = null;
+    const ensureSchema = () => {
+        ready ??= db
+            .prepare(`CREATE TABLE IF NOT EXISTS ${table} (` +
+            `source TEXT NOT NULL, ` +
+            `target TEXT NOT NULL, ` +
+            `verified_at INTEGER NOT NULL, ` +
+            `PRIMARY KEY (source, target))`)
+            .run()
+            .then(() => undefined);
+        return ready;
+    };
+    return {
+        async store(mention) {
+            await ensureSchema();
+            await db
+                .prepare(`INSERT INTO ${table} (source, target, verified_at) ` +
+                `VALUES (?1, ?2, ?3) ` +
+                `ON CONFLICT (source, target) ` +
+                `DO UPDATE SET verified_at = excluded.verified_at`)
+                .bind(mention.source, mention.target, mention.verifiedAt)
+                .run();
+        },
+        async remove(source, target) {
+            await ensureSchema();
+            await db
+                .prepare(`DELETE FROM ${table} WHERE source = ?1 AND target = ?2`)
+                .bind(source, target)
+                .run();
+        },
+        async list(target) {
+            await ensureSchema();
+            const statement = target === undefined
+                ? db.prepare(`SELECT source, target, verified_at FROM ${table} ` +
+                    `ORDER BY verified_at DESC`)
+                : db
+                    .prepare(`SELECT source, target, verified_at FROM ${table} ` +
+                    `WHERE target = ?1 ORDER BY verified_at DESC`)
+                    .bind(target);
+            const { results } = await statement.all();
+            return results.map((row) => ({
+                source: row.source,
+                target: row.target,
+                verifiedAt: row.verified_at,
+            }));
+        },
+    };
+}
+//# sourceMappingURL=inbox.js.map

package/dist/inbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbox.js","sourceRoot":"","sources":["../src/inbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAkCH;;;GAGG;AACH,MAAM,UAAU,aAAa,CAC3B,EAAc,EACd,OAAwB;IAExB,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,IAAI,aAAa,CAAC;IAC9C,0EAA0E;IAC1E,6DAA6D;IAC7D,IAAI,CAAC,0BAA0B,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CAAC,8CAA8C,KAAK,IAAI,CAAC,CAAC;IAC3E,CAAC;IAED,IAAI,KAAK,GAAyB,IAAI,CAAC;IACvC,MAAM,YAAY,GAAG,GAAkB,EAAE;QACvC,KAAK,KAAK,EAAE;aACT,OAAO,CACN,8BAA8B,KAAK,IAAI;YACrC,wBAAwB;YACxB,wBAAwB;YACxB,gCAAgC;YAChC,+BAA+B,CAClC;aACA,GAAG,EAAE;aACL,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QACzB,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;IAEF,OAAO;QACL,KAAK,CAAC,KAAK,CAAC,OAAO;YACjB,MAAM,YAAY,EAAE,CAAC;YACrB,MAAM,EAAE;iBACL,OAAO,CACN,eAAe,KAAK,iCAAiC;gBACnD,sBAAsB;gBACtB,+BAA+B;gBAC/B,kDAAkD,CACrD;iBACA,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC;iBACxD,GAAG,EAAE,CAAC;QACX,CAAC;QAED,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM;YACzB,MAAM,YAAY,EAAE,CAAC;YACrB,MAAM,EAAE;iBACL,OAAO,CAAC,eAAe,KAAK,oCAAoC,CAAC;iBACjE,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC;iBACpB,GAAG,EAAE,CAAC;QACX,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,MAAM;YACf,MAAM,YAAY,EAAE,CAAC;YACrB,MAAM,SAAS,GACb,MAAM,KAAK,SAAS;gBAClB,CAAC,CAAC,EAAE,CAAC,OAAO,CACR,2CAA2C,KAAK,GAAG;oBACjD,2BAA2B,CAC9B;gBACH,CAAC,CAAC,EAAE;qBACC,OAAO,CACN,2CAA2C,KAAK,GAAG;oBACjD,6CAA6C,CAChD;qBACA,IAAI,CAAC,MAAM,CAAC,CAAC;YACtB,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,SAAS,CAAC,GAAG,EAAc,CAAC;YACtD,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;gBAC3B,MAAM,EAAE,GAAG,CAAC,MAAM;gBAClB,MAAM,EAAE,GAAG,CAAC,MAAM;gBAClB,UAAU,EAAE,GAAG,CAAC,WAAW;aAC5B,CAAC,CAAC,CAAC;QACN,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,96 @@
+/**
+ * `@dwk/webmention` — Webmention (W3C) receiver + sender.
+ *
+ * Endpoint package. 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. Cloud
+ * specifics (Queue, D1) are confined here; HTML scanning uses the runtime's
+ * streaming `HTMLRewriter`, so the parsing/verification helpers are async and
+ * exercised under the Workers test pool.
+ *
+ * @see spec/packages/webmention.md
+ * @packageDocumentation
+ */
+import type { D1Database, ExecutionContext, MessageBatch, Queue } from "@cloudflare/workers-types";
+import { type Logger, type Metrics } from "@dwk/log";
+import { type InboxStore } from "./inbox";
+import type { FetchLike } from "./fetch";
+export { validateWebmentionParams, type ValidateParams, type ValidationResult, type WebmentionValidationError, } from "./validate";
+export { discoverEndpoint, findWebmentionEndpoint, type DiscoverOptions, } from "./discovery";
+export { sendWebmention, sendWebmentions, type SendOptions, type SendResult, } from "./sender";
+export { verifySource, sourceLinksTo, extractLinks, type VerifyOptions, type VerifyResult, } from "./verify";
+export { createD1Inbox, type InboxStore, type VerifiedMention, type D1InboxOptions, } from "./inbox";
+export type { FetchLike } from "./fetch";
+export { safeFetch, assertPublicUrl, isPrivateOrReservedHost, SsrfError, DEFAULT_MAX_REDIRECTS, DEFAULT_TIMEOUT_MS, type SafeFetchOptions, type SafeFetchResult, type SsrfReason, } from "./safe-fetch";
+export { WebmentionLogEvent } from "./log";
+export type { Logger, Metrics } from "@dwk/log";
+/** A queued verification job: confirm that `source` links to `target`. */
+export interface WebmentionJob {
+    readonly source: string;
+    readonly target: string;
+}
+/** Cloudflare bindings required by the Webmention handler and queue consumer. */
+export interface WebmentionEnv {
+    /** Queue producer for async verification of received mentions. */
+    readonly WEBMENTION_QUEUE: Queue<WebmentionJob>;
+    /**
+     * D1 database backing the default inbox. Optional only when an
+     * {@link InboxStore} is supplied via {@link WebmentionConfig.inbox} (e.g. a
+     * Solid Pod DO-backed inbox).
+     */
+    readonly WEBMENTION_INBOX?: D1Database;
+}
+/** Configuration passed to {@link createWebmention}. */
+export interface WebmentionConfig {
+    /** Base URL of this receiver; a `target` must live under its origin. */
+    readonly baseUrl: string;
+    /** Additional controlled hostnames besides `baseUrl`'s. */
+    readonly allowedHosts?: readonly string[];
+    /**
+     * Inbox store for verified mentions. Defaults to a D1 store built from
+     * {@link WebmentionEnv.WEBMENTION_INBOX}; supply one to back the inbox with
+     * the `@dwk/solid-pod` Durable Object instead.
+     */
+    readonly inbox?: InboxStore;
+    /** `fetch` implementation for verification; defaults to the global `fetch`. */
+    readonly fetch?: FetchLike;
+    /**
+     * Logger for receiver/queue events; defaults to a no-op. Wire a real logger
+     * (see `@dwk/log`) to surface SSRF blocks, validation rejections, and
+     * poison-message retries instead of swallowing them.
+     */
+    readonly logger?: Logger;
+    /**
+     * Metrics sink for receiver/queue counters; defaults to a no-op. Wire an
+     * adapter (e.g. `analyticsEngineMetrics` from `@dwk/log`, bound to an
+     * `AnalyticsEngineDataset`) to chart the same events the logger names —
+     * "SSRF blocks/min", "verification success rate", "queue retries by reason".
+     */
+    readonly metrics?: Metrics;
+}
+/** A `fetch`-compatible Worker handler. */
+export type WebmentionHandler = (request: Request, env: WebmentionEnv, ctx: ExecutionContext) => Promise<Response>;
+/** A Queue consumer for asynchronous Webmention verification. */
+export type WebmentionQueueConsumer = (batch: MessageBatch<WebmentionJob>, env: WebmentionEnv, ctx: ExecutionContext) => Promise<void>;
+/**
+ * Build the Webmention receiver handler from configuration.
+ *
+ * The returned handler is mountable under any path prefix. It accepts a
+ * form-encoded `POST` (`source` + `target`), validates synchronously, enqueues
+ * the pair for verification, and returns `202 Accepted`. Invalid requests get
+ * `400`; other methods get `405`. Fails loudly if the required `WEBMENTION_QUEUE`
+ * binding is missing.
+ */
+export declare function createWebmention(config: WebmentionConfig): WebmentionHandler;
+/**
+ * Build the Queue consumer that verifies received mentions.
+ *
+ * For each job it fetches the source and checks for a link to the target: a
+ * verified mention is upserted into the inbox, while a source that no longer
+ * links is removed. A job that throws is retried; otherwise it is acked. Fails
+ * loudly if no inbox is configured.
+ */
+export declare function createWebmentionQueueConsumer(config: WebmentionConfig): WebmentionQueueConsumer;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,161 @@
+/**
+ * `@dwk/webmention` — Webmention (W3C) receiver + sender.
+ *
+ * Endpoint package. 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. Cloud
+ * specifics (Queue, D1) are confined here; HTML scanning uses the runtime's
+ * streaming `HTMLRewriter`, so the parsing/verification helpers are async and
+ * exercised under the Workers test pool.
+ *
+ * @see spec/packages/webmention.md
+ * @packageDocumentation
+ */
+import { hostFromUrl, noopLogger, noopMetrics, } from "@dwk/log";
+import { createD1Inbox } from "./inbox";
+import { WebmentionLogEvent } from "./log";
+import { validateWebmentionParams } from "./validate";
+import { verifySource } from "./verify";
+export { validateWebmentionParams, } from "./validate";
+export { discoverEndpoint, findWebmentionEndpoint, } from "./discovery";
+export { sendWebmention, sendWebmentions, } from "./sender";
+export { verifySource, sourceLinksTo, extractLinks, } from "./verify";
+export { createD1Inbox, } from "./inbox";
+export { safeFetch, assertPublicUrl, isPrivateOrReservedHost, SsrfError, DEFAULT_MAX_REDIRECTS, DEFAULT_TIMEOUT_MS, } from "./safe-fetch";
+export { WebmentionLogEvent } from "./log";
+function textResponse(status, body) {
+    return new Response(body, {
+        status,
+        headers: { "content-type": "text/plain; charset=utf-8" },
+    });
+}
+function resolveInbox(config, env) {
+    if (config.inbox !== undefined) {
+        return config.inbox;
+    }
+    if (env.WEBMENTION_INBOX !== undefined) {
+        return createD1Inbox(env.WEBMENTION_INBOX);
+    }
+    throw new Error("@dwk/webmention: no inbox configured — provide config.inbox or bind " +
+        "WEBMENTION_INBOX (D1).");
+}
+function formValue(value) {
+    return typeof value === "string" ? value : null;
+}
+/**
+ * Whether the request body is `application/x-www-form-urlencoded` — the encoding
+ * Webmention §3.1.3 requires. `Request.formData()` would also accept
+ * `multipart/form-data`, so the essence is checked up front rather than relying
+ * on it.
+ */
+function isFormUrlEncoded(contentType) {
+    const essence = contentType?.split(";")[0]?.trim().toLowerCase() ?? "";
+    return essence === "application/x-www-form-urlencoded";
+}
+/**
+ * Build the Webmention receiver handler from configuration.
+ *
+ * The returned handler is mountable under any path prefix. It accepts a
+ * form-encoded `POST` (`source` + `target`), validates synchronously, enqueues
+ * the pair for verification, and returns `202 Accepted`. Invalid requests get
+ * `400`; other methods get `405`. Fails loudly if the required `WEBMENTION_QUEUE`
+ * binding is missing.
+ */
+export function createWebmention(config) {
+    const logger = config.logger ?? noopLogger;
+    const metrics = config.metrics ?? noopMetrics;
+    return async (request, env, _ctx) => {
+        if (request.method !== "POST") {
+            return new Response("Method Not Allowed", {
+                status: 405,
+                headers: { allow: "POST" },
+            });
+        }
+        if (env.WEBMENTION_QUEUE === undefined) {
+            throw new Error("@dwk/webmention: missing required binding WEBMENTION_QUEUE.");
+        }
+        if (!isFormUrlEncoded(request.headers.get("content-type"))) {
+            const fields = { reason: "invalid_content_type" };
+            logger.warn(WebmentionLogEvent.ReceiveRejected, fields);
+            metrics.count(WebmentionLogEvent.ReceiveRejected, fields);
+            return textResponse(400, "invalid_request: Content-Type must be application/x-www-form-urlencoded");
+        }
+        let form;
+        try {
+            form = await request.formData();
+        }
+        catch {
+            return textResponse(400, "invalid_request: expected a form-encoded body with source and target");
+        }
+        const result = validateWebmentionParams({
+            source: formValue(form.get("source")),
+            target: formValue(form.get("target")),
+            baseUrl: config.baseUrl,
+            allowedHosts: config.allowedHosts,
+        });
+        if (!result.ok) {
+            const fields = { reason: result.error };
+            logger.warn(WebmentionLogEvent.ReceiveRejected, fields);
+            metrics.count(WebmentionLogEvent.ReceiveRejected, fields);
+            return textResponse(400, result.error);
+        }
+        await env.WEBMENTION_QUEUE.send({
+            source: result.source,
+            target: result.target,
+        });
+        const fields = {
+            sourceHost: hostFromUrl(result.source),
+            targetHost: hostFromUrl(result.target),
+        };
+        logger.info(WebmentionLogEvent.ReceiveAccepted, fields);
+        metrics.count(WebmentionLogEvent.ReceiveAccepted, fields);
+        return new Response(null, { status: 202 });
+    };
+}
+/**
+ * Build the Queue consumer that verifies received mentions.
+ *
+ * For each job it fetches the source and checks for a link to the target: a
+ * verified mention is upserted into the inbox, while a source that no longer
+ * links is removed. A job that throws is retried; otherwise it is acked. Fails
+ * loudly if no inbox is configured.
+ */
+export function createWebmentionQueueConsumer(config) {
+    const logger = config.logger ?? noopLogger;
+    const metrics = config.metrics ?? noopMetrics;
+    return async (batch, env, _ctx) => {
+        const inbox = resolveInbox(config, env);
+        for (const message of batch.messages) {
+            const { source, target } = message.body;
+            try {
+                const result = await verifySource(source, target, {
+                    fetch: config.fetch,
+                    logger,
+                    metrics,
+                });
+                if (result.links) {
+                    await inbox.store({ source, target, verifiedAt: Date.now() });
+                }
+                else {
+                    await inbox.remove(source, target);
+                }
+                message.ack();
+            }
+            catch (err) {
+                // A poison message must not retry silently — record why so an operator
+                // can tell a transient failure from a wedged one.
+                const fields = {
+                    sourceHost: hostFromUrl(source),
+                    targetHost: hostFromUrl(target),
+                    error: err instanceof Error ? err.name : "unknown",
+                };
+                logger.warn(WebmentionLogEvent.QueueRetry, fields);
+                metrics.count(WebmentionLogEvent.QueueRetry, fields);
+                message.retry();
+            }
+        }
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/log.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `@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 declare const WebmentionLogEvent: {
+    /**
+     * An outbound fetch was refused on SSRF grounds. Fields: `reason`
+     * (machine-readable cause), `host` (sanitized, when known).
+     */
+    readonly SsrfBlocked: "webmention.ssrf.blocked";
+    /** A received mention passed validation and was enqueued. */
+    readonly ReceiveAccepted: "webmention.receive.accepted";
+    /** A received mention was rejected at validation. Field: `reason`. */
+    readonly ReceiveRejected: "webmention.receive.rejected";
+    /** Source verification finished. Fields: `links`, `status`. */
+    readonly VerifyCompleted: "webmention.verify.completed";
+    /** The source fetch failed/was blocked during verification. Field: `error`. */
+    readonly VerifyFetchFailed: "webmention.verify.fetch_failed";
+    /** A queue message threw and is being retried. Field: `error`. */
+    readonly QueueRetry: "webmention.queue.retry";
+    /** A send attempt finished. Fields: `endpointHost`, `delivered`, `status`. */
+    readonly SendCompleted: "webmention.send.completed";
+};
+/** Union of the event-name string literals in {@link WebmentionLogEvent}. */
+export type WebmentionLogEvent = (typeof WebmentionLogEvent)[keyof typeof WebmentionLogEvent];
+//# sourceMappingURL=log.d.ts.map

package/dist/log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.d.ts","sourceRoot":"","sources":["../src/log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;GAIG;AACH,eAAO,MAAM,kBAAkB;IAC7B;;;OAGG;;IAEH,6DAA6D;;IAE7D,sEAAsE;;IAEtE,+DAA+D;;IAE/D,+EAA+E;;IAE/E,kEAAkE;;IAElE,8EAA8E;;CAEtE,CAAC;AAEX,6EAA6E;AAC7E,MAAM,MAAM,kBAAkB,GAC5B,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,OAAO,kBAAkB,CAAC,CAAC"}