@dwk/microsub 0.1.0-beta.0

package/dist/xml.js.map

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

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@dwk/microsub",
+  "version": "0.1.0-beta.0",
+  "description": "Microsub server: channel/feed subscriptions, server-side polling, and a normalised JF2 timeline. Consumes IndieAuth tokens.",
+  "keywords": [
+    "microsub",
+    "indieweb",
+    "jf2",
+    "feed-reader",
+    "cloudflare-workers"
+  ],
+  "type": "module",
+  "license": "ISC",
+  "author": "David W. Keith <me@dwk.io>",
+  "homepage": "https://github.com/davidwkeith/workers/tree/main/packages/microsub#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/davidwkeith/workers.git",
+    "directory": "packages/microsub"
+  },
+  "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",
+    "!src/test-harness.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@dwk/dpop": "0.1.0-beta.0",
+    "@dwk/indieauth": "0.1.0-beta.0",
+    "@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/auth.ts

@@ -0,0 +1,184 @@
+/**
+ * Request authorization: validate the IndieAuth access token, complete its DPoP
+ * proof-of-possession binding, honour revocation, and gate the action on the
+ * token's scope.
+ *
+ * Mirrors `@dwk/micropub`'s authorization exactly — Microsub is the read side of
+ * the same identity layer, so it accepts the same DPoP-bound HS256 access tokens
+ * `@dwk/indieauth` mints and applies the same single-owner subject check: a
+ * token minted by this issuer for a *different* `me` cannot read here. The DPoP
+ * proof binds the token to this exact request (RFC 9449), so a stolen bearer
+ * token alone is useless; revocation is checked against the strongly-consistent
+ * issued-token store, never a cache. Replay detection (for state-changing
+ * `POST`s) is the caller's, recorded in the strongly-consistent `MICROSUB_DB`.
+ *
+ * @packageDocumentation
+ */
+
+import { DEFAULT_MAX_AGE_SECONDS, verifyDpopProof } from "@dwk/dpop";
+import {
+  createIndieAuthStore,
+  verifyAccessToken,
+  type AccessTokenClaims,
+  type IndieAuthStoreEnv,
+} from "@dwk/indieauth";
+
+import type { ResolvedConfig } from "./config";
+import { createDpopReplayStore } from "./replay";
+import type { MicrosubStoreEnv } from "./store";
+
+/** Bindings the authorization path needs. */
+export interface AuthEnv extends IndieAuthStoreEnv, MicrosubStoreEnv {
+  /** HMAC key the IndieAuth token endpoint signed access tokens with. */
+  readonly TOKEN_SIGNING_KEY: string;
+}
+
+/** A failed authorization: an OAuth-style error to surface to the client. */
+export interface AuthFailure {
+  readonly ok: false;
+  readonly error: string;
+  readonly description: string;
+  readonly status: number;
+}
+
+/** A successful authorization: the verified token claims. */
+export interface AuthSuccess {
+  readonly ok: true;
+  readonly claims: AccessTokenClaims;
+}
+
+export type AuthResult = AuthSuccess | AuthFailure;
+
+function failure(
+  error: string,
+  description: string,
+  status: number,
+): AuthFailure {
+  return { ok: false, error, description, status };
+}
+
+/**
+ * Extract the bearer token from the `Authorization` header. Both the RFC 9449
+ * `DPoP` scheme (which our tokens use) and the legacy `Bearer` scheme are
+ * accepted. Returns `null` when the header is absent or malformed.
+ */
+export function tokenFromHeader(request: Request): string | null {
+  const header = request.headers.get("Authorization");
+  if (!header) return null;
+  const match = /^(DPoP|Bearer)\s+(.+)$/i.exec(header.trim());
+  return match ? (match[2] as string) : null;
+}
+
+/** Whether the granted scope string contains any of the acceptable scopes. */
+export function hasScope(
+  scope: string,
+  acceptable: readonly string[],
+): boolean {
+  const granted = scope.split(/\s+/).filter(Boolean);
+  return acceptable.some((s) => granted.includes(s));
+}
+
+/**
+ * Authorize a request. Verifies the access token, completes the DPoP binding
+ * against this exact request (`htm`/`htu`/`ath`/`cnf.jkt`), checks revocation,
+ * records the proof for replay detection (when `recordReplay`), and — when
+ * `requiredScopes` is non-empty — enforces scope.
+ */
+export async function authorize(
+  request: Request,
+  env: AuthEnv,
+  config: ResolvedConfig,
+  token: string | null,
+  requiredScopes: readonly string[],
+  recordReplay: boolean,
+): Promise<AuthResult> {
+  if (!token) {
+    return failure("unauthorized", "a bearer access token is required", 401);
+  }
+
+  const verified = await verifyAccessToken(token, env.TOKEN_SIGNING_KEY, {
+    issuer: config.tokenIssuer,
+  });
+  if (!verified.valid) {
+    return failure(
+      "invalid_token",
+      `access token rejected: ${verified.reason}`,
+      401,
+    );
+  }
+  const claims = verified.claims;
+
+  // The token's subject (`sub`) is the canonical `me` it was minted for. A
+  // Microsub endpoint serves a single user, so reject any token whose subject is
+  // not this user — otherwise any token from the same issuer (for any `me`)
+  // could read this timeline. Both sides are canonicalized, so this is exact.
+  if (claims.sub !== config.me) {
+    return failure(
+      "invalid_token",
+      "access token subject is not the owner of this server",
+      403,
+    );
+  }
+
+  // Complete the DPoP proof-of-possession binding for this request.
+  const proof = request.headers.get("DPoP");
+  if (!proof) {
+    return failure(
+      "invalid_request",
+      "a DPoP proof is required for token-bound requests",
+      401,
+    );
+  }
+  const dpop = await verifyDpopProof({
+    proof,
+    htm: request.method,
+    htu: request.url,
+    accessToken: token,
+    expectedJkt: claims.cnf.jkt,
+  });
+  if (!dpop.valid) {
+    return failure(
+      "invalid_token",
+      `DPoP proof verification failed: ${dpop.reason}`,
+      401,
+    );
+  }
+
+  // Replay: only for state-changing requests. A captured GET proof is far less
+  // valuable, and recording every read's proof would write on the read path.
+  if (recordReplay && config.checkDpopReplay && dpop.jti) {
+    const now = Math.floor(Date.now() / 1000);
+    const fresh = await createDpopReplayStore(env).recordProof(
+      dpop.jti,
+      now + 2 * DEFAULT_MAX_AGE_SECONDS,
+      now,
+    );
+    if (!fresh) {
+      return failure(
+        "invalid_token",
+        "DPoP proof has already been used (replay detected)",
+        401,
+      );
+    }
+  }
+
+  // Revocation: staleness here is a security bug, so hit the strongly-consistent
+  // issued-token store rather than any cache.
+  if (config.checkRevocation) {
+    const store = createIndieAuthStore(env);
+    const now = Math.floor(Date.now() / 1000);
+    if (!(await store.isTokenActive(claims.jti, now))) {
+      return failure("invalid_token", "access token has been revoked", 401);
+    }
+  }
+
+  if (requiredScopes.length > 0 && !hasScope(claims.scope, requiredScopes)) {
+    return failure(
+      "insufficient_scope",
+      `this action requires one of the scopes: ${requiredScopes.join(", ")}`,
+      403,
+    );
+  }
+
+  return { ok: true, claims };
+}

package/src/config.ts

@@ -0,0 +1,156 @@
+/**
+ * `@dwk/microsub` — injected configuration and the Cloudflare `Env` fragment.
+ *
+ * Per the composition contract a package never reads the global environment
+ * directly: all config (base URL, owner `me`, endpoint URL, page size, poll
+ * cadence) is passed into {@link createMicrosub}, so the server can be
+ * instantiated multiple times and unit-tested in isolation. The Cloudflare
+ * bindings it 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/microsub.md`.
+ *
+ * @packageDocumentation
+ */
+
+import { canonicalizeProfileUrl } from "@dwk/indieauth";
+import { noopLogger, noopMetrics, type Logger, type Metrics } from "@dwk/log";
+import type { D1Database, Queue } from "@cloudflare/workers-types";
+
+import type { FetchLike } from "./fetch";
+import type { MicrosubJob } from "./queue";
+
+/**
+ * Cloudflare bindings required by the Microsub handler, poller, and queue
+ * consumer.
+ *
+ * The subscription + timeline store **MUST** be strongly consistent — D1
+ * (session consistency), never KV: a lost subscription or a dropped read-state
+ * flag is a correctness bug, not a safe-to-be-stale cache
+ * (`spec/non-functional-requirements.md`).
+ */
+export interface MicrosubEnv {
+  /** D1 database for channels, follows, timeline items, and the poll cache. */
+  readonly MICROSUB_DB: D1Database;
+  /** Queue for feed-poll fan-out and retries. */
+  readonly MICROSUB_QUEUE: Queue<MicrosubJob>;
+  /** The `@dwk/indieauth` issued-token store (D1), consulted for revocation. */
+  readonly AUTH_DB: D1Database;
+  /** HMAC key the IndieAuth token endpoint signed access tokens with. */
+  readonly TOKEN_SIGNING_KEY: string;
+}
+
+/** Configuration passed to {@link createMicrosub} and its poller/consumer. */
+export interface MicrosubConfig {
+  /** The identity root / base URL (e.g. `https://example.com`). */
+  readonly baseUrl: string;
+  /**
+   * The site owner's IndieAuth profile URL (`me`). A token only authorizes a
+   * request when its subject (`sub`) equals this, after canonicalization — so a
+   * token minted by the same issuer for a *different* `me` cannot read here.
+   * Required: a Microsub endpoint serves exactly one user.
+   */
+  readonly me: string;
+  /** Absolute Microsub endpoint URL. Defaults to `${origin}/microsub`. */
+  readonly microsubEndpoint?: string;
+  /**
+   * Expected access-token issuer (`iss`). Defaults to `baseUrl`, matching the
+   * `@dwk/indieauth` issuer default.
+   */
+  readonly tokenIssuer?: string;
+  /** Default timeline page size. Defaults to 20. */
+  readonly pageSize?: number;
+  /**
+   * Per-channel retention ceiling: when a poll pushes a channel above this, the
+   * oldest items are reaped. Defaults to 5000. Keeps a runaway feed from filling
+   * the D1 store unbounded.
+   */
+  readonly maxItemsPerChannel?: number;
+  /**
+   * Whether to check each token against the issued-token store (revocation).
+   * Defaults to `true` — staleness here is a security bug, so the check hits the
+   * strongly-consistent `AUTH_DB` rather than any cache.
+   */
+  readonly checkRevocation?: boolean;
+  /**
+   * Whether to reject replayed DPoP proofs on state-changing (`POST`) requests
+   * by tracking each accepted proof's `jti` in the strongly-consistent
+   * `MICROSUB_DB`. Defaults to `true`.
+   */
+  readonly checkDpopReplay?: boolean;
+  /** `fetch` implementation for discovery/polling/preview; 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;
+}
+
+/** Fully resolved configuration with defaults applied and the path parsed. */
+export interface ResolvedConfig {
+  readonly me: string;
+  readonly microsubEndpoint: string;
+  readonly microsubPath: string;
+  readonly tokenIssuer: string;
+  readonly pageSize: number;
+  readonly maxItemsPerChannel: number;
+  readonly checkRevocation: boolean;
+  readonly checkDpopReplay: boolean;
+  readonly fetch: FetchLike;
+  readonly logger: Logger;
+  readonly metrics: Metrics;
+}
+
+const DEFAULT_PAGE_SIZE = 20;
+const DEFAULT_MAX_ITEMS = 5000;
+
+function pathOf(absoluteUrl: string, label: string): string {
+  try {
+    return new URL(absoluteUrl).pathname;
+  } catch {
+    throw new Error(`@dwk/microsub: ${label} is not a valid URL`);
+  }
+}
+
+/**
+ * Resolve user config into a {@link ResolvedConfig}, applying defaults and
+ * pre-computing the endpoint pathname for request routing. Throws if `baseUrl`
+ * or `me` (or an explicitly supplied endpoint URL) is invalid.
+ */
+export function resolveConfig(config: MicrosubConfig): ResolvedConfig {
+  let base: URL;
+  try {
+    base = new URL(config.baseUrl);
+  } catch {
+    throw new Error("@dwk/microsub: `baseUrl` is not a valid URL");
+  }
+
+  const me = canonicalizeProfileUrl(config.me);
+  if (me === null) {
+    throw new Error("@dwk/microsub: `me` is not a valid profile URL");
+  }
+
+  const microsubEndpoint = config.microsubEndpoint ?? `${base.origin}/microsub`;
+
+  const pageSize =
+    config.pageSize !== undefined && config.pageSize > 0
+      ? Math.floor(config.pageSize)
+      : DEFAULT_PAGE_SIZE;
+  const maxItemsPerChannel =
+    config.maxItemsPerChannel !== undefined && config.maxItemsPerChannel > 0
+      ? Math.floor(config.maxItemsPerChannel)
+      : DEFAULT_MAX_ITEMS;
+
+  return {
+    me,
+    microsubEndpoint,
+    microsubPath: pathOf(microsubEndpoint, "microsubEndpoint"),
+    tokenIssuer: config.tokenIssuer ?? config.baseUrl,
+    pageSize,
+    maxItemsPerChannel,
+    checkRevocation: config.checkRevocation ?? true,
+    checkDpopReplay: config.checkDpopReplay ?? true,
+    fetch: config.fetch ?? ((input, init) => fetch(input, init)),
+    logger: config.logger ?? noopLogger,
+    metrics: config.metrics ?? noopMetrics,
+  };
+}

package/src/consumer.ts

@@ -0,0 +1,140 @@
+/**
+ * `@dwk/microsub` — the poll-queue consumer.
+ *
+ * The slow work the scheduled poller deferred runs here, off the request path,
+ * with the queue providing retries and backoff. For each `poll` job it:
+ *
+ * 1. fetches the feed conditionally (sending the cached `ETag` /
+ *    `Last-Modified`); a `304` is acked with nothing to do;
+ * 2. parses the body to JF2 (Atom / RSS / JSON Feed / `h-feed`);
+ * 3. appends new entries — deduped by entry id — to every channel following
+ *    that feed, reaping past the per-channel retention ceiling; and
+ * 4. records the returned validators for the next poll.
+ *
+ * A job whose fetch fails (unreachable / blocked / non-2xx) or whose store work
+ * throws is retried; everything else is acked. Feeds are assumed newest-first,
+ * so entries are inserted oldest-first and the newest gets the highest paging
+ * `seq`. See `spec/packages/microsub.md`.
+ *
+ * @packageDocumentation
+ */
+
+import { hostFromUrl } from "@dwk/log";
+import type { ExecutionContext, MessageBatch } from "@cloudflare/workers-types";
+
+import {
+  resolveConfig,
+  type MicrosubConfig,
+  type MicrosubEnv,
+  type ResolvedConfig,
+} from "./config";
+import { fetchFeed } from "./discovery";
+import { orderEntriesForInsert } from "./jf2";
+import { MicrosubLogEvent } from "./log";
+import type { MicrosubJob } from "./queue";
+import { createMicrosubStore, type MicrosubStore } from "./store";
+
+/** A Queue consumer for Microsub poll jobs. */
+export type MicrosubQueueConsumer = (
+  batch: MessageBatch<MicrosubJob>,
+  env: MicrosubEnv,
+  ctx: ExecutionContext,
+) => Promise<void>;
+
+/** Extra wiring for the consumer, primarily to inject a store/clock in tests. */
+export interface ConsumerOptions {
+  /** Override the store; defaults to a D1 store over `MICROSUB_DB`. */
+  readonly store?: MicrosubStore;
+  /** Clock injection for deterministic tests; defaults to `Date.now`. */
+  readonly now?: () => number;
+}
+
+function emit(
+  config: ResolvedConfig,
+  event: string,
+  fields?: Record<string, unknown>,
+): void {
+  config.logger.info(event, fields);
+  config.metrics.count(event, fields);
+}
+
+/**
+ * Build the Queue consumer that polls feeds and appends to channel timelines.
+ * Fails loudly if no store is configured (neither `options.store` nor the
+ * `MICROSUB_DB` binding).
+ */
+export function createMicrosubQueueConsumer(
+  config: MicrosubConfig,
+  options?: ConsumerOptions,
+): MicrosubQueueConsumer {
+  const resolved = resolveConfig(config);
+  const clock = options?.now ?? (() => Math.floor(Date.now() / 1000));
+
+  return async (batch, env, _ctx) => {
+    const store =
+      options?.store ??
+      (env.MICROSUB_DB
+        ? createMicrosubStore(env)
+        : (() => {
+            throw new Error(
+              "@dwk/microsub: missing required D1 binding `MICROSUB_DB`",
+            );
+          })());
+
+    for (const message of batch.messages) {
+      const job = message.body;
+      try {
+        const cache = await store.getFeedCache(job.feedUrl);
+        const fetched = await fetchFeed(
+          job.feedUrl,
+          {
+            fetch: resolved.fetch,
+            logger: resolved.logger,
+            metrics: resolved.metrics,
+          },
+          cache ?? undefined,
+        );
+        if (fetched === null) {
+          // Unreachable / blocked / non-2xx — retry the whole job later.
+          message.retry();
+          continue;
+        }
+
+        const now = clock();
+        await store.setFeedCache(
+          job.feedUrl,
+          fetched.etag,
+          fetched.lastModified,
+          now,
+        );
+
+        let added = 0;
+        if (!fetched.notModified && fetched.entries.length > 0) {
+          // Order oldest-first so the newest entry gets the highest paging `seq`.
+          const ordered = orderEntriesForInsert(fetched.entries);
+          const channels = await store.channelsForFeed(job.feedUrl);
+          for (const channel of channels) {
+            added += await store.insertItems(
+              channel,
+              job.feedUrl,
+              ordered,
+              now,
+              resolved.maxItemsPerChannel,
+            );
+          }
+        }
+        emit(resolved, MicrosubLogEvent.FeedPolled, {
+          added,
+          host: hostFromUrl(job.feedUrl),
+        });
+        message.ack();
+      } catch (err) {
+        emit(resolved, MicrosubLogEvent.PollRetry, {
+          error: err instanceof Error ? err.name : "unknown",
+          host: hostFromUrl(job.feedUrl),
+        });
+        message.retry();
+      }
+    }
+  };
+}