@dwk/websub 0.1.0-beta.0

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@dwk/websub",
+  "version": "0.1.0-beta.0",
+  "description": "WebSub (W3C) hub: subscription store, intent verification, and signed content distribution.",
+  "keywords": [
+    "websub",
+    "pubsubhubbub",
+    "indieweb",
+    "feeds",
+    "cloudflare-workers"
+  ],
+  "type": "module",
+  "license": "ISC",
+  "author": "David W. Keith <me@dwk.io>",
+  "homepage": "https://github.com/davidwkeith/workers/tree/main/packages/websub#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/davidwkeith/workers.git",
+    "directory": "packages/websub"
+  },
+  "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/config.ts

@@ -0,0 +1,199 @@
+/**
+ * `@dwk/websub` — injected configuration and the Cloudflare `Env` fragment.
+ *
+ * Per the composition contract, a package never reads the global environment
+ * directly: all config (base URL, the topics this hub serves, lease bounds) is
+ * passed into {@link createWebSub}, so the hub can be instantiated multiple times
+ * and unit-tested in isolation. The Cloudflare bindings the hub needs are
+ * declared as a TypeScript `Env` fragment that the composed Worker's `Env` is a
+ * superset of. See `spec/composition-contract.md` and `spec/packages/websub.md`.
+ *
+ * @packageDocumentation
+ */
+
+import { noopLogger, noopMetrics, type Logger, type Metrics } from "@dwk/log";
+import type { D1Database, Queue } from "@cloudflare/workers-types";
+import {
+  DEFAULT_SIGNATURE_ALGORITHM,
+  type SignatureAlgorithm,
+} from "./distribute";
+import type { FetchLike } from "./fetch";
+import type { WebSubJob } from "./queue";
+
+/**
+ * Cloudflare bindings required by the hub handler and its queue consumer.
+ *
+ * The subscription store **MUST** be strongly consistent — D1 (session
+ * consistency), never KV: a stale or lost subscription is a correctness bug, not
+ * a safe-to-be-stale cache (`spec/non-functional-requirements.md`).
+ */
+export interface WebSubEnv {
+  /** D1 database backing the subscription table. */
+  readonly WEBSUB_DB: D1Database;
+  /** Queue for intent verification and content-distribution fan-out + retries. */
+  readonly WEBSUB_QUEUE: Queue<WebSubJob>;
+}
+
+/** Configuration passed to {@link createWebSub}. */
+export interface WebSubConfig {
+  /** Base URL of this hub; informational and used for self-advertisement. */
+  readonly baseUrl: string;
+  /**
+   * Absolute URL of the hub endpoint itself, advertised to subscribers in the
+   * `rel="hub"` `Link` header on each delivery. Defaults to {@link baseUrl};
+   * set it when the hub is mounted under a path prefix.
+   */
+  readonly hubUrl?: string;
+  /**
+   * The topic URLs this hub will serve (the user's own feeds). A subscribe or
+   * publish request for any other topic is rejected. Compared by normalized URL
+   * (default ports and a trailing-slash-only path are folded). Provide either
+   * this or {@link isAllowedTopic}.
+   */
+  readonly allowedTopics?: readonly string[];
+  /**
+   * Predicate deciding whether a topic URL is one this hub serves, for callers
+   * whose feed set is dynamic. Takes precedence over {@link allowedTopics}.
+   */
+  readonly isAllowedTopic?: (topic: string) => boolean;
+  /** Minimum lease (seconds) the hub will grant. Default 300 (5 minutes). */
+  readonly minLeaseSeconds?: number;
+  /** Maximum lease (seconds) the hub will grant. Default 864000 (10 days). */
+  readonly maxLeaseSeconds?: number;
+  /**
+   * Lease granted when a subscriber omits `hub.lease_seconds`. Default 864000
+   * (10 days). Clamped into `[minLeaseSeconds, maxLeaseSeconds]`.
+   */
+  readonly defaultLeaseSeconds?: number;
+  /**
+   * HMAC digest method for the `X-Hub-Signature` on signed deliveries (WebSub
+   * §8 permits `sha1`/`sha256`/`sha384`/`sha512`). WebSub has no per-request
+   * method parameter, so this is a hub-level choice; it defaults to the secure
+   * `sha256`. Set it to `sha1` **only** when a subscriber requires the legacy
+   * method for interop — SHA-1 is weaker and not the default for that reason.
+   */
+  readonly signatureAlgorithm?: SignatureAlgorithm;
+  /**
+   * Media type to forward on distribution when the topic response declares no
+   * `Content-Type`. WebSub §7 requires the distribution `Content-Type` to
+   * correspond to the topic's, so the hub never fabricates a generic
+   * `application/octet-stream`. Set this to the type the hub's feeds are served
+   * as (e.g. `application/atom+xml`) so a topic that omits the header is still
+   * distributable; left unset, such a topic is refused rather than mislabeled.
+   */
+  readonly defaultContentType?: string;
+  /** `fetch` implementation for verification/distribution; defaults to global `fetch`. */
+  readonly fetch?: FetchLike;
+  /** Logger; defaults to a no-op (see `@dwk/log`). */
+  readonly logger?: Logger;
+  /** Metrics sink; defaults to a no-op (see `@dwk/log`). */
+  readonly metrics?: Metrics;
+}
+
+/** Default lower bound on a granted lease (5 minutes). */
+export const DEFAULT_MIN_LEASE_SECONDS = 300;
+/** Default upper bound on a granted lease (10 days). */
+export const DEFAULT_MAX_LEASE_SECONDS = 864_000;
+
+/** Config with defaults resolved and the topic check normalized to a predicate. */
+export interface ResolvedConfig {
+  readonly baseUrl: string;
+  readonly hubUrl: string;
+  readonly isAllowedTopic: (topic: string) => boolean;
+  readonly minLeaseSeconds: number;
+  readonly maxLeaseSeconds: number;
+  readonly defaultLeaseSeconds: number;
+  readonly signatureAlgorithm: SignatureAlgorithm;
+  /** Fallback distribution `Content-Type`; `undefined` refuses to mislabel. */
+  readonly defaultContentType?: string;
+  readonly fetch: FetchLike;
+  readonly logger: Logger;
+  readonly metrics: Metrics;
+}
+
+/**
+ * Normalize a topic URL for comparison: lowercase host, default port dropped,
+ * a bare `/` path elided, and fragment removed. Query strings are preserved
+ * (a feed may legitimately carry one). Returns `null` when `raw` is unparseable
+ * or not `http(s)`.
+ */
+export function normalizeTopic(raw: string): string | null {
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    return null;
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    return null;
+  }
+  url.hash = "";
+  const path = url.pathname === "/" ? "" : url.pathname;
+  return `${url.protocol}//${url.host}${path}${url.search}`;
+}
+
+/**
+ * Resolve {@link WebSubConfig} into {@link ResolvedConfig}, filling defaults and
+ * turning the topic allowlist into a single predicate.
+ *
+ * @throws when neither `allowedTopics` nor `isAllowedTopic` is supplied — a hub
+ * with no topics would accept subscriptions it can never serve.
+ */
+export function resolveConfig(config: WebSubConfig): ResolvedConfig {
+  const min = config.minLeaseSeconds ?? DEFAULT_MIN_LEASE_SECONDS;
+  const max = config.maxLeaseSeconds ?? DEFAULT_MAX_LEASE_SECONDS;
+  if (min > max) {
+    throw new Error(
+      `@dwk/websub: minLeaseSeconds (${min}) exceeds maxLeaseSeconds (${max}).`,
+    );
+  }
+  const fallback = config.defaultLeaseSeconds ?? DEFAULT_MAX_LEASE_SECONDS;
+  const defaultLeaseSeconds = Math.min(Math.max(fallback, min), max);
+
+  let isAllowedTopic: (topic: string) => boolean;
+  if (config.isAllowedTopic !== undefined) {
+    isAllowedTopic = config.isAllowedTopic;
+  } else if (config.allowedTopics !== undefined) {
+    const allowed = new Set<string>();
+    for (const topic of config.allowedTopics) {
+      const normalized = normalizeTopic(topic);
+      if (normalized !== null) {
+        allowed.add(normalized);
+      }
+    }
+    isAllowedTopic = (topic) => {
+      const normalized = normalizeTopic(topic);
+      return normalized !== null && allowed.has(normalized);
+    };
+  } else {
+    throw new Error(
+      "@dwk/websub: configure allowedTopics or isAllowedTopic — a hub must " +
+        "know which topics it serves.",
+    );
+  }
+
+  return {
+    baseUrl: config.baseUrl,
+    hubUrl: config.hubUrl ?? config.baseUrl,
+    isAllowedTopic,
+    minLeaseSeconds: min,
+    maxLeaseSeconds: max,
+    defaultLeaseSeconds,
+    signatureAlgorithm:
+      config.signatureAlgorithm ?? DEFAULT_SIGNATURE_ALGORITHM,
+    ...(config.defaultContentType !== undefined
+      ? { defaultContentType: config.defaultContentType }
+      : {}),
+    fetch: config.fetch ?? ((input, init) => fetch(input, init)),
+    logger: config.logger ?? noopLogger,
+    metrics: config.metrics ?? noopMetrics,
+  };
+}
+
+/** Clamp a requested lease into the hub's `[min, max]` bounds. */
+export function clampLease(requested: number, config: ResolvedConfig): number {
+  return Math.min(
+    Math.max(requested, config.minLeaseSeconds),
+    config.maxLeaseSeconds,
+  );
+}

package/src/consumer.ts

@@ -0,0 +1,187 @@
+/**
+ * `@dwk/websub` — the queue consumer.
+ *
+ * The hub's slow work runs here, off the request path, with the queue providing
+ * retries and backoff. Two job kinds flow through:
+ *
+ * - **verify** — issue the verification-of-intent GET; on a confirmed subscribe,
+ *   write the subscription to the D1 store with its lease expiry, and on a
+ *   confirmed unsubscribe, remove it. A subscription row is created only after
+ *   verification succeeds, so an unverified callback never lands in the store.
+ * - **distribute** — prune expired leases, fetch the topic's current content, and
+ *   fan it out (signed per-subscriber when a secret is set) to every active
+ *   subscriber.
+ *
+ * A job whose store/fetch work throws — or a distribution that cannot fetch the
+ * topic — is retried; everything else is acked. See `spec/packages/websub.md`.
+ *
+ * @packageDocumentation
+ */
+
+import { hostFromUrl, type LogFields } from "@dwk/log";
+import type { ExecutionContext, MessageBatch } from "@cloudflare/workers-types";
+import {
+  resolveConfig,
+  type ResolvedConfig,
+  type WebSubConfig,
+  type WebSubEnv,
+} from "./config";
+import { deliverToSubscriber, fetchTopicContent } from "./distribute";
+import { WebSubLogEvent } from "./log";
+import type { WebSubJob } from "./queue";
+import { createD1SubscriptionStore, type SubscriptionStore } from "./store";
+import { notifyDenial, verifyIntent } from "./verify";
+
+/** A Queue consumer for WebSub verification and distribution jobs. */
+export type WebSubQueueConsumer = (
+  batch: MessageBatch<WebSubJob>,
+  env: WebSubEnv,
+  ctx: ExecutionContext,
+) => Promise<void>;
+
+/** Extra wiring for the consumer, primarily to inject a store in tests. */
+export interface ConsumerOptions {
+  /** Override the subscription store; defaults to a D1 store over `WEBSUB_DB`. */
+  readonly store?: SubscriptionStore;
+  /** Clock injection for deterministic tests; defaults to `Date.now`. */
+  readonly now?: () => number;
+}
+
+function emit(
+  config: ResolvedConfig,
+  level: "info" | "warn",
+  event: string,
+  fields?: LogFields,
+): void {
+  config.logger[level](event, fields);
+  config.metrics.count(event, fields);
+}
+
+function resolveStore(
+  options: ConsumerOptions | undefined,
+  env: WebSubEnv,
+): SubscriptionStore {
+  if (options?.store !== undefined) {
+    return options.store;
+  }
+  if (env.WEBSUB_DB === undefined) {
+    throw new Error("@dwk/websub: missing required binding WEBSUB_DB.");
+  }
+  return createD1SubscriptionStore(env.WEBSUB_DB);
+}
+
+/**
+ * Build the Queue consumer that performs intent verification and content
+ * distribution. Fails loudly if no store is configured (neither
+ * `options.store` nor the `WEBSUB_DB` binding).
+ */
+export function createWebSubQueueConsumer(
+  config: WebSubConfig,
+  options?: ConsumerOptions,
+): WebSubQueueConsumer {
+  const resolved = resolveConfig(config);
+  const clock = options?.now ?? (() => Date.now());
+
+  return async (batch, env, _ctx) => {
+    const store = resolveStore(options, env);
+
+    for (const message of batch.messages) {
+      const job = message.body;
+      try {
+        if (job.kind === "verify") {
+          const result = await verifyIntent(job.callback, job.topic, {
+            mode: job.mode,
+            leaseSeconds:
+              job.mode === "subscribe" ? job.leaseSeconds : undefined,
+            fetch: resolved.fetch,
+            logger: resolved.logger,
+            metrics: resolved.metrics,
+          });
+          if (result.confirmed) {
+            if (job.mode === "subscribe") {
+              await store.upsert({
+                callback: job.callback,
+                topic: job.topic,
+                secret: job.secret,
+                leaseSeconds: job.leaseSeconds,
+                now: clock(),
+              });
+              emit(resolved, "info", WebSubLogEvent.SubscriptionActivated, {
+                callbackHost: hostFromUrl(job.callback),
+                topicHost: hostFromUrl(job.topic),
+                leaseSeconds: job.leaseSeconds,
+              });
+            } else {
+              await store.remove(job.callback, job.topic);
+              emit(resolved, "info", WebSubLogEvent.SubscriptionRemoved, {
+                callbackHost: hostFromUrl(job.callback),
+                topicHost: hostFromUrl(job.topic),
+                reason: "unsubscribed",
+              });
+            }
+          } else if (job.mode === "subscribe") {
+            // Intent unconfirmed: signal denial to the subscriber (WebSub §5.2)
+            // instead of silently dropping the request. (An unconfirmed
+            // unsubscribe simply leaves the existing subscription in place.)
+            await notifyDenial(job.callback, job.topic, {
+              reason: "verification_failed",
+              fetch: resolved.fetch,
+              logger: resolved.logger,
+              metrics: resolved.metrics,
+            });
+          }
+          message.ack();
+          continue;
+        }
+
+        // kind === "distribute"
+        const now = clock();
+        await store.pruneExpired(now);
+        const fetched = await fetchTopicContent(job.topic, {
+          fetch: resolved.fetch,
+          logger: resolved.logger,
+          metrics: resolved.metrics,
+          defaultContentType: resolved.defaultContentType,
+        });
+        if (fetched.kind === "retry") {
+          // The topic was unreachable / non-2xx — retry the whole job later
+          // rather than dropping the push.
+          message.retry();
+          continue;
+        }
+        if (fetched.kind === "drop") {
+          // A permanent, deterministic refusal (e.g. an unlabelable topic):
+          // retrying can't fix it, so ack and move on rather than clog the
+          // queue and re-hammer the topic. fetchTopicContent already logged why.
+          message.ack();
+          continue;
+        }
+        const content = fetched.content;
+        const subscribers = await store.listActive(job.topic, now);
+        // Fan out in parallel: deliverToSubscriber never throws (it reports a
+        // failed/blocked POST as delivered:false), so one slow or dead callback
+        // must not head-of-line block the rest and risk timing out the whole
+        // consumer invocation.
+        await Promise.all(
+          subscribers.map((subscriber) =>
+            deliverToSubscriber(subscriber, content, resolved.hubUrl, {
+              fetch: resolved.fetch,
+              logger: resolved.logger,
+              metrics: resolved.metrics,
+              signatureAlgorithm: resolved.signatureAlgorithm,
+            }),
+          ),
+        );
+        message.ack();
+      } catch (err) {
+        // A store/queue failure must not retry silently — name the kind and
+        // error so an operator can tell a transient blip from a wedged job.
+        emit(resolved, "warn", WebSubLogEvent.QueueRetry, {
+          kind: job.kind,
+          error: err instanceof Error ? err.name : "unknown",
+        });
+        message.retry();
+      }
+    }
+  };
+}

package/src/distribute.ts

@@ -0,0 +1,257 @@
+/**
+ * `@dwk/websub` — signed content distribution.
+ *
+ * On publish, the hub fetches the topic's current content and `POST`s it to every
+ * active subscriber's callback (WebSub §7). When a subscriber registered a
+ * `hub.secret`, the body is authenticated with an HMAC signature in the
+ * `X-Hub-Signature: <method>=<hex>` header so the subscriber can verify the
+ * delivery came from this hub (§8). The digest method is a hub-level config
+ * option (`sha256` by default; `sha1`/`sha384`/`sha512` are also permitted by
+ * §8 and selected via `signatureAlgorithm`). Deliveries carry `Link` headers
+ * advertising
+ * the hub (`rel="hub"`) and the topic (`rel="self"`). Every POST goes through
+ * {@link safeFetch}. See `spec/packages/websub.md`.
+ *
+ * @packageDocumentation
+ */
+
+import {
+  hostFromUrl,
+  noopLogger,
+  noopMetrics,
+  type Logger,
+  type Metrics,
+} from "@dwk/log";
+import type { FetchLike } from "./fetch";
+import { readBytesCapped } from "./fetch";
+import { WebSubLogEvent } from "./log";
+import { safeFetch } from "./safe-fetch";
+import type { Subscription } from "./store";
+
+/** A topic's current content, as fetched from the topic URL. */
+export interface TopicContent {
+  /** The raw body bytes to forward to subscribers. */
+  readonly body: Uint8Array;
+  /** The topic's `Content-Type`, forwarded verbatim to subscribers. */
+  readonly contentType: string;
+}
+
+/**
+ * The HMAC digest methods WebSub §8 permits for `X-Hub-Signature`. The method
+ * name is emitted verbatim as the header's `<method>=` prefix, so it must match
+ * the WebSub spelling (`sha1`, not `sha-1`).
+ */
+export type SignatureAlgorithm = "sha1" | "sha256" | "sha384" | "sha512";
+
+/** Map a WebSub signature method name to its WebCrypto SHA hash name. */
+const HASH_FOR_METHOD: Record<SignatureAlgorithm, string> = {
+  sha1: "SHA-1",
+  sha256: "SHA-256",
+  sha384: "SHA-384",
+  sha512: "SHA-512",
+};
+
+/** WebSub's secure default signature method; SHA-1 interop is opt-in only. */
+export const DEFAULT_SIGNATURE_ALGORITHM: SignatureAlgorithm = "sha256";
+
+/** Outcome of delivering content to one subscriber. */
+export interface DeliveryResult {
+  readonly callback: string;
+  /** Whether the callback accepted the delivery (2xx). */
+  readonly delivered: boolean;
+  /** The delivery's HTTP status (`0` when the POST threw or was blocked). */
+  readonly status: number;
+}
+
+/**
+ * Compute the `X-Hub-Signature` value for `body` under `secret`:
+ * `<method>=<lowercase hex HMAC>` (WebSub §8). `method` defaults to the secure
+ * `sha256`; WebSub also permits `sha1`/`sha384`/`sha512`. The header prefix is
+ * the WebSub method name verbatim (e.g. `sha1=`, not `sha-1=`).
+ */
+export async function contentSignature(
+  secret: string,
+  body: Uint8Array,
+  method: SignatureAlgorithm = DEFAULT_SIGNATURE_ALGORITHM,
+): Promise<string> {
+  const key = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secret),
+    { name: "HMAC", hash: HASH_FOR_METHOD[method] },
+    false,
+    ["sign"],
+  );
+  const mac = await crypto.subtle.sign("HMAC", key, body as BufferSource);
+  const hex = [...new Uint8Array(mac)]
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+  return `${method}=${hex}`;
+}
+
+/** Build the `Link` header advertising this hub and the topic (WebSub §5.1). */
+export function buildLinkHeader(hubUrl: string, topic: string): string {
+  return `<${hubUrl}>; rel="hub", <${topic}>; rel="self"`;
+}
+
+/** Inputs shared by distribution helpers. */
+export interface DistributeOptions {
+  readonly fetch?: FetchLike;
+  readonly logger?: Logger;
+  readonly metrics?: Metrics;
+  /**
+   * HMAC method used for the `X-Hub-Signature` header. WebSub §8 has no
+   * per-request method parameter, so this is a hub-level choice; it defaults to
+   * the secure {@link DEFAULT_SIGNATURE_ALGORITHM} (`sha256`). Set it to `sha1`
+   * only for interop with subscribers that require the legacy method.
+   */
+  readonly signatureAlgorithm?: SignatureAlgorithm;
+  /**
+   * Media type to forward when the topic response declares no `Content-Type`.
+   * WebSub §7 requires the distribution `Content-Type` to correspond to the
+   * topic's, so the hub never fabricates a generic `application/octet-stream`:
+   * when the topic omits the header and no fallback is configured here, the
+   * content is refused rather than mislabeled.
+   */
+  readonly defaultContentType?: string;
+}
+
+/**
+ * Outcome of {@link fetchTopicContent}, telling the caller what to do with the
+ * queue message:
+ *
+ * - **`ok`** — the topic's current content, ready to fan out.
+ * - **`retry`** — a transient failure (topic unreachable, non-2xx, or an
+ *   over-cap body that may be a truncated response): re-enqueue and try later.
+ * - **`drop`** — a deterministic refusal that re-fetching cannot fix, so the
+ *   caller acks rather than burning retries and re-hammering the topic. Today
+ *   this is a topic that declares no `Content-Type` and for which no
+ *   {@link DistributeOptions.defaultContentType} fallback is configured, since
+ *   forwarding it would mislabel the feed (WebSub §7).
+ */
+export type TopicFetchResult =
+  | { readonly kind: "ok"; readonly content: TopicContent }
+  | { readonly kind: "retry" }
+  | { readonly kind: "drop" };
+
+/**
+ * Fetch the topic's current content through {@link safeFetch}, classifying the
+ * outcome as `ok` / `retry` / `drop` (see {@link TopicFetchResult}). A missing,
+ * unlabelable `Content-Type` is a `drop` — a permanent format/config error that
+ * retrying would only turn into a self-inflicted hammering of the topic — while
+ * unreachable/non-2xx/over-cap responses are transient `retry`s.
+ */
+export async function fetchTopicContent(
+  topic: string,
+  options?: DistributeOptions,
+): Promise<TopicFetchResult> {
+  const doFetch: FetchLike =
+    options?.fetch ?? ((input, init) => fetch(input, init));
+  const logger = options?.logger ?? noopLogger;
+  const metrics = options?.metrics ?? noopMetrics;
+
+  let response: Response;
+  try {
+    const result = await safeFetch(
+      doFetch,
+      topic,
+      { method: "GET" },
+      { logger, metrics },
+    );
+    response = result.response;
+  } catch {
+    const fields = { topicHost: hostFromUrl(topic), status: 0 };
+    logger.warn(WebSubLogEvent.TopicFetchFailed, fields);
+    metrics.count(WebSubLogEvent.TopicFetchFailed, fields);
+    return { kind: "retry" };
+  }
+
+  if (!response.ok) {
+    await response.body?.cancel().catch(() => undefined);
+    const fields = { topicHost: hostFromUrl(topic), status: response.status };
+    logger.warn(WebSubLogEvent.TopicFetchFailed, fields);
+    metrics.count(WebSubLogEvent.TopicFetchFailed, fields);
+    return { kind: "retry" };
+  }
+
+  const contentType =
+    response.headers.get("content-type") ?? options?.defaultContentType;
+  if (contentType === undefined || contentType === "") {
+    // WebSub §7: the distribution Content-Type MUST correspond to the topic's.
+    // With neither a topic header nor a configured fallback, forwarding would
+    // mislabel the feed. Re-fetching can't conjure a Content-Type, so drop the
+    // job (the caller acks) rather than retry — retrying would only clog the
+    // queue and re-hammer the topic for a permanent configuration error.
+    await response.body?.cancel().catch(() => undefined);
+    const fields = { topicHost: hostFromUrl(topic), status: response.status };
+    logger.warn(WebSubLogEvent.TopicContentTypeMissing, fields);
+    metrics.count(WebSubLogEvent.TopicContentTypeMissing, fields);
+    return { kind: "drop" };
+  }
+  const body = await readBytesCapped(response);
+  if (body === null) {
+    const fields = { topicHost: hostFromUrl(topic), status: response.status };
+    logger.warn(WebSubLogEvent.TopicFetchFailed, fields);
+    metrics.count(WebSubLogEvent.TopicFetchFailed, fields);
+    return { kind: "retry" };
+  }
+  return { kind: "ok", content: { body, contentType } };
+}
+
+/**
+ * Deliver `content` to one subscriber. POSTs the body with the topic's
+ * `Content-Type`, the hub/self `Link` header, and — when the subscription
+ * carries a secret — the `X-Hub-Signature`. Never throws: a failed or blocked
+ * POST is reported as `delivered: false`.
+ */
+export async function deliverToSubscriber(
+  subscription: Subscription,
+  content: TopicContent,
+  hubUrl: string,
+  options?: DistributeOptions,
+): Promise<DeliveryResult> {
+  const doFetch: FetchLike =
+    options?.fetch ?? ((input, init) => fetch(input, init));
+  const logger = options?.logger ?? noopLogger;
+  const metrics = options?.metrics ?? noopMetrics;
+
+  const headers: Record<string, string> = {
+    "content-type": content.contentType,
+    link: buildLinkHeader(hubUrl, subscription.topic),
+  };
+  if (subscription.secret !== null) {
+    headers["x-hub-signature"] = await contentSignature(
+      subscription.secret,
+      content.body,
+      options?.signatureAlgorithm ?? DEFAULT_SIGNATURE_ALGORITHM,
+    );
+  }
+
+  const finish = (delivered: boolean, status: number): DeliveryResult => {
+    const fields = {
+      callbackHost: hostFromUrl(subscription.callback),
+      delivered,
+      status,
+    };
+    logger.info(WebSubLogEvent.DeliveryCompleted, fields);
+    metrics.count(WebSubLogEvent.DeliveryCompleted, fields);
+    return { callback: subscription.callback, delivered, status };
+  };
+
+  try {
+    const result = await safeFetch(
+      doFetch,
+      subscription.callback,
+      {
+        method: "POST",
+        headers,
+        // `content.body` is a Uint8Array; pass its backing buffer as the body.
+        body: content.body as BodyInit,
+      },
+      { logger, metrics },
+    );
+    await result.response.body?.cancel().catch(() => undefined);
+    return finish(result.response.ok, result.response.status);
+  } catch {
+    return finish(false, 0);
+  }
+}