@dwk/websub 0.1.0-beta.0

package/src/fetch.ts

@@ -0,0 +1,84 @@
+/**
+ * `@dwk/websub` — injectable `fetch` type and a body-size cap.
+ *
+ * Intent verification, topic fetching, and content distribution 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 body (4 MB). A challenge echo is tiny and a feed is
+ * modest; 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 = 4 * 1024 * 1024;
+
+/**
+ * Read a response body as a `Uint8Array`, 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 readBytesCapped(
+  response: Response,
+  maxBytes = MAX_BODY_BYTES,
+): Promise<Uint8Array | null> {
+  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 buffer = await response.arrayBuffer();
+      return buffer.byteLength > maxBytes ? null : new Uint8Array(buffer);
+    } catch {
+      return null;
+    }
+  }
+
+  const reader = body.getReader();
+  const chunks: Uint8Array[] = [];
+  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 merged;
+}

package/src/handler.ts

@@ -0,0 +1,163 @@
+/**
+ * `@dwk/websub` — the hub `fetch` handler and publish-notifier factory.
+ *
+ * `createWebSub` builds the WebSub hub endpoint: a single `POST`-only handler,
+ * mountable under any path prefix, that fields subscribe/unsubscribe requests and
+ * publish pings. Slow work (intent verification, content fan-out) is validated
+ * synchronously and pushed onto the queue, so the handler returns `202 Accepted`
+ * fast and the queue consumer (see {@link createWebSubQueueConsumer}) does the
+ * I/O with retries. `createPublishNotifier` is the in-process equivalent of a
+ * publish ping, for the Micropub write / Anglesite rebuild path. See
+ * `spec/packages/websub.md`.
+ *
+ * @packageDocumentation
+ */
+
+import { hostFromUrl, type LogFields } from "@dwk/log";
+import type { ExecutionContext } from "@cloudflare/workers-types";
+import {
+  resolveConfig,
+  type ResolvedConfig,
+  type WebSubConfig,
+  type WebSubEnv,
+} from "./config";
+import { WebSubLogEvent } from "./log";
+import { readHubParams, validatePublish, validateSubscribe } from "./validate";
+
+/** A `fetch`-compatible Worker handler. */
+export type WebSubHandler = (
+  request: Request,
+  env: WebSubEnv,
+  ctx: ExecutionContext,
+) => Promise<Response>;
+
+/**
+ * An in-process publish notifier: call it from the Micropub write path or an
+ * Anglesite rebuild hook to enqueue distribution of `topic` to its subscribers.
+ */
+export type PublishNotifier = (env: WebSubEnv, topic: string) => Promise<void>;
+
+function textResponse(status: number, body: string): Response {
+  return new Response(body, {
+    status,
+    headers: { "content-type": "text/plain; charset=utf-8" },
+  });
+}
+
+function requireQueue(env: WebSubEnv): void {
+  if (env.WEBSUB_QUEUE === undefined) {
+    throw new Error("@dwk/websub: missing required binding WEBSUB_QUEUE.");
+  }
+}
+
+function emit(
+  config: ResolvedConfig,
+  level: "info" | "warn",
+  event: string,
+  fields?: LogFields,
+): void {
+  config.logger[level](event, fields);
+  config.metrics.count(event, fields);
+}
+
+/**
+ * Build the WebSub hub handler from configuration.
+ *
+ * Accepts a form-encoded `POST`. `hub.mode=subscribe|unsubscribe` is validated
+ * and the verification-of-intent job enqueued (`202`); `hub.mode=publish`
+ * enqueues a distribution job (`202`). Invalid requests get `400` with a stable
+ * error code; other methods get `405`. Fails loudly if `WEBSUB_QUEUE` is missing.
+ */
+export function createWebSub(config: WebSubConfig): WebSubHandler {
+  const resolved = resolveConfig(config);
+  return async (request, env, _ctx) => {
+    if (request.method !== "POST") {
+      return new Response("Method Not Allowed", {
+        status: 405,
+        headers: { allow: "POST" },
+      });
+    }
+
+    requireQueue(env);
+
+    let form: FormData;
+    try {
+      form = await request.formData();
+    } catch {
+      return textResponse(400, "invalid_request");
+    }
+
+    // Lift the form into a string-only URLSearchParams; a `File`-valued field
+    // (multipart upload) is not a valid `hub.*` parameter and is dropped.
+    const search = new URLSearchParams();
+    for (const [key, value] of form.entries()) {
+      if (typeof value === "string") {
+        search.append(key, value);
+      }
+    }
+    const params = readHubParams(search);
+
+    if (params.mode === "publish") {
+      const result = validatePublish(params, resolved);
+      if (!result.ok) {
+        emit(resolved, "warn", WebSubLogEvent.PublishRejected, {
+          reason: result.error,
+        });
+        return textResponse(400, result.error);
+      }
+      await env.WEBSUB_QUEUE.send({ kind: "distribute", topic: result.topic });
+      emit(resolved, "info", WebSubLogEvent.PublishAccepted, {
+        topicHost: hostFromUrl(result.topic),
+      });
+      return new Response(null, { status: 202 });
+    }
+
+    const result = validateSubscribe(params, resolved);
+    if (!result.ok) {
+      emit(resolved, "warn", WebSubLogEvent.RequestRejected, {
+        reason: result.error,
+      });
+      return textResponse(400, result.error);
+    }
+
+    await env.WEBSUB_QUEUE.send({
+      kind: "verify",
+      mode: result.mode,
+      callback: result.callback,
+      topic: result.topic,
+      leaseSeconds: result.leaseSeconds,
+      ...(result.secret !== undefined ? { secret: result.secret } : {}),
+    });
+    emit(resolved, "info", WebSubLogEvent.RequestAccepted, {
+      mode: result.mode,
+      callbackHost: hostFromUrl(result.callback),
+      topicHost: hostFromUrl(result.topic),
+    });
+    return new Response(null, { status: 202 });
+  };
+}
+
+/**
+ * Build an in-process publish notifier. The returned function enqueues a
+ * distribution job for `topic` (after checking it is a topic this hub serves),
+ * so a Micropub write or static rebuild can fan out a push without going through
+ * the HTTP publish endpoint.
+ *
+ * @throws when `topic` is not one this hub serves — a caller wiring this into its
+ * own write path should only ever publish its own feeds.
+ */
+export function createPublishNotifier(config: WebSubConfig): PublishNotifier {
+  const resolved = resolveConfig(config);
+  return async (env, topic) => {
+    requireQueue(env);
+    if (!resolved.isAllowedTopic(topic)) {
+      throw new Error(
+        `@dwk/websub: refusing to publish unsupported topic ${hostFromUrl(topic) ?? "<invalid>"}.`,
+      );
+    }
+    await env.WEBSUB_QUEUE.send({ kind: "distribute", topic });
+    emit(resolved, "info", WebSubLogEvent.PublishAccepted, {
+      topicHost: hostFromUrl(topic),
+    });
+  };
+}

package/src/index.ts

@@ -0,0 +1,98 @@
+/**
+ * `@dwk/websub` — WebSub (W3C) hub.
+ *
+ * Endpoint package. The publish-side, real-time complement to `@dwk/webmention`:
+ * subscribers receive a push when the user's feed changes instead of polling. The
+ * hub fields `hub.mode=subscribe|unsubscribe` requests (validated synchronously,
+ * verified-of-intent and persisted asynchronously) and publish pings, keeps a
+ * strongly-consistent D1 subscription store with lease expiry, and on publish
+ * fans the topic's content out to every verified callback — signing the body with
+ * HMAC-SHA256 (`X-Hub-Signature`) when the subscriber registered a secret. The
+ * feeds themselves are static SSG artifacts (Anglesite's job, including the
+ * `Link rel="hub"`/`rel="self"` advertisement); this package is only the dynamic
+ * layer. Cloudflare specifics (D1, Queue) are confined here; validation, lease
+ * math, verification, and signing are pure and unit-test without a Workers
+ * runtime.
+ *
+ * @see spec/packages/websub.md
+ * @packageDocumentation
+ */
+
+export {
+  createWebSub,
+  createPublishNotifier,
+  type WebSubHandler,
+  type PublishNotifier,
+} from "./handler";
+export {
+  createWebSubQueueConsumer,
+  type WebSubQueueConsumer,
+  type ConsumerOptions,
+} from "./consumer";
+export {
+  resolveConfig,
+  normalizeTopic,
+  clampLease,
+  DEFAULT_MIN_LEASE_SECONDS,
+  DEFAULT_MAX_LEASE_SECONDS,
+  type WebSubConfig,
+  type WebSubEnv,
+  type ResolvedConfig,
+} from "./config";
+export {
+  createD1SubscriptionStore,
+  type SubscriptionStore,
+  type Subscription,
+  type SubscriptionUpsert,
+  type D1StoreOptions,
+} from "./store";
+export {
+  validateSubscribe,
+  validatePublish,
+  readHubParams,
+  MAX_SECRET_BYTES,
+  type SubscribeResult,
+  type SubscribeRequest,
+  type SubscribeError,
+  type PublishResult,
+  type PublishRequest,
+  type PublishError,
+  type RawHubParams,
+} from "./validate";
+export {
+  verifyIntent,
+  buildVerificationUrl,
+  generateChallenge,
+  notifyDenial,
+  buildDenialUrl,
+  type VerifyIntentOptions,
+  type VerifyIntentResult,
+  type NotifyDenialOptions,
+} from "./verify";
+export {
+  contentSignature,
+  buildLinkHeader,
+  fetchTopicContent,
+  deliverToSubscriber,
+  DEFAULT_SIGNATURE_ALGORITHM,
+  type SignatureAlgorithm,
+  type TopicContent,
+  type TopicFetchResult,
+  type DeliveryResult,
+  type DistributeOptions,
+} from "./distribute";
+export type { WebSubJob, VerifyJob, DistributeJob } from "./queue";
+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 { WebSubLogEvent } from "./log";
+export type { Logger, Metrics } from "@dwk/log";

package/src/log.ts

@@ -0,0 +1,56 @@
+/**
+ * `@dwk/websub` — structured observability event taxonomy.
+ *
+ * Like the rest of the cohort, this package's logging and metrics are opt-in via
+ * an injected {@link Logger} and {@link Metrics} (see `@dwk/log`) and **share one
+ * vocabulary**: the same dotted event name is passed to `logger.*(...)` and
+ * `metrics.count(...)` so a log line and its counter line up. Event names are
+ * stable, dotted, and queryable. Security-relevant events (a blocked SSRF
+ * attempt, a verification rejection) are first-class so being actively probed
+ * produces a distinct signal rather than silence. See `spec/observability.md`.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Stable event names emitted by `@dwk/websub`. Fields logged alongside each
+ * event use `hostFromUrl` for any URL so an attacker-supplied path/query is
+ * never recorded; secrets and bodies are never logged.
+ */
+export const WebSubLogEvent = {
+  /**
+   * An outbound fetch was refused on SSRF grounds. Fields: `reason`
+   * (machine-readable cause), `host` (sanitized, when known).
+   */
+  SsrfBlocked: "websub.ssrf.blocked",
+  /** A subscribe/unsubscribe request passed validation and was enqueued. Fields: `mode`, `callbackHost`, `topicHost`. */
+  RequestAccepted: "websub.request.accepted",
+  /** A subscribe/unsubscribe request was rejected at validation. Field: `reason`. */
+  RequestRejected: "websub.request.rejected",
+  /** A publish ping passed validation and distribution was enqueued. Field: `topicHost`. */
+  PublishAccepted: "websub.publish.accepted",
+  /** A publish ping was rejected at validation. Field: `reason`. */
+  PublishRejected: "websub.publish.rejected",
+  /** Intent verification of a callback completed. Fields: `mode`, `callbackHost`, `confirmed`, `status`. */
+  VerifyCompleted: "websub.verify.completed",
+  /** The verification GET to the callback failed/was blocked. Field: `error`. */
+  VerifyFetchFailed: "websub.verify.fetch_failed",
+  /** A subscription was activated (verified subscribe). Fields: `callbackHost`, `topicHost`, `leaseSeconds`. */
+  SubscriptionActivated: "websub.subscription.activated",
+  /** A subscription was removed (verified unsubscribe or pruned). Fields: `callbackHost`, `topicHost`, `reason`. */
+  SubscriptionRemoved: "websub.subscription.removed",
+  /** A subscription was denied (`hub.mode=denied`). Emitted whether or not the callback was reachable; `notified` records whether it accepted the GET. Fields: `callbackHost`, `topicHost`, `notified`, `reason`. */
+  SubscriptionDenied: "websub.subscription.denied",
+  /** A content-distribution delivery to one subscriber finished. Fields: `callbackHost`, `delivered`, `status`. */
+  DeliveryCompleted: "websub.delivery.completed",
+  /** A distribution job could not fetch the topic content. Fields: `topicHost`, `status`. */
+  TopicFetchFailed: "websub.topic.fetch_failed",
+  /** The topic declared no `Content-Type` and no fallback was configured, so distribution was refused rather than mislabeled (WebSub §7). Fields: `topicHost`, `status`. */
+  TopicContentTypeMissing: "websub.topic.content_type_missing",
+  /** A queue message threw and is being retried. Fields: `kind`, `error`. */
+  QueueRetry: "websub.queue.retry",
+} as const;
+
+/** Union of the event-name string literals in {@link WebSubLogEvent}. */
+export type WebSubLogEvent =
+  (typeof WebSubLogEvent)[keyof typeof WebSubLogEvent];

package/src/queue.ts

@@ -0,0 +1,40 @@
+/**
+ * `@dwk/websub` — queued job shapes.
+ *
+ * The hub does its slow, failure-prone work — the verification-of-intent GET and
+ * content-distribution fan-out — off the request path, on a queue with retries
+ * and backoff (`spec/packages/websub.md`). Two job kinds flow through the one
+ * queue, discriminated by `kind`.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Verify a subscriber's intent: GET the callback with `hub.challenge` and,
+ * on a confirming 2xx echo, activate (subscribe) or remove (unsubscribe) the
+ * subscription. Carries everything needed to persist the subscription so the
+ * store write happens only after verification succeeds.
+ */
+export interface VerifyJob {
+  readonly kind: "verify";
+  readonly mode: "subscribe" | "unsubscribe";
+  readonly callback: string;
+  readonly topic: string;
+  /** Lease to grant on a confirmed subscribe (seconds); ignored for unsubscribe. */
+  readonly leaseSeconds: number;
+  /** Optional HMAC secret registered by the subscriber, stored on activation. */
+  readonly secret?: string;
+}
+
+/**
+ * Distribute a topic's current content to every active subscriber: fetch the
+ * topic, then POST the body (signed per-subscriber when a secret is set) to each
+ * verified callback.
+ */
+export interface DistributeJob {
+  readonly kind: "distribute";
+  readonly topic: string;
+}
+
+/** A job on the WebSub queue: either intent verification or content distribution. */
+export type WebSubJob = VerifyJob | DistributeJob;