@dwk/microsub 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,92 @@
+# `@dwk/microsub`
+
+> Microsub server: channel/feed subscriptions, server-side polling, and a normalised JF2 timeline. Consumes IndieAuth tokens.
+
+Part of the [`@dwk` IndieWeb + Solid cohort](../../README.md). See the
+[package specification](../../spec/packages/microsub.md) for the full requirements.
+
+A [Microsub](https://indieweb.org/Microsub-spec) server that runs as a
+Cloudflare Worker — the IndieWeb's **read side**, completing the loop alongside
+[`@dwk/micropub`](../micropub) (write), [`@dwk/webmention`](../webmention)
+(interaction), [`@dwk/indieauth`](../indieauth) (identity), and
+[`@dwk/websub`](../websub) (push).
+
+It manages feed subscriptions organised into channels, polls and parses sources
+server-side (Atom / RSS / JSON Feed / `h-feed`), and serves a normalised
+[JF2](https://jf2.spec.indieweb.org/) timeline to reader clients (Monocle,
+Together, Indigenous). The user's reading state lives on infrastructure they
+own, not in a hosted aggregator.
+
+## Usage
+
+```ts
+import {
+  createMicrosub,
+  createMicrosubPoller,
+  createMicrosubQueueConsumer,
+} from "@dwk/microsub";
+
+const config = {
+  baseUrl: "https://example.com",
+  // the owner's IndieAuth profile URL; tokens minted for any other `me` are
+  // rejected even if they carry the right scope
+  me: "https://example.com/",
+  // optional: defaults to `${origin}/microsub`
+  microsubEndpoint: "https://example.com/microsub",
+};
+
+const microsub = createMicrosub(config);
+const poll = createMicrosubPoller(config);
+const consume = createMicrosubQueueConsumer(config);
+
+export default {
+  fetch(request, env, ctx) {
+    return microsub(request, env, ctx);
+  },
+  // Cron Trigger: enqueue a poll job per followed feed.
+  scheduled(controller, env, ctx) {
+    return poll(controller, env, ctx);
+  },
+  // Queue consumer: fetch + parse + append to channel timelines.
+  queue(batch, env, ctx) {
+    return consume(batch, env, ctx);
+  },
+};
+```
+
+### Bindings (declared `Env` fragment)
+
+The handler fails loudly at startup if any of these are missing:
+
+- `MICROSUB_DB` — D1 database for channels, follows, timeline items, and the
+  per-feed poll cache.
+- `MICROSUB_QUEUE` — Queue for feed-poll fan-out and retries.
+- `AUTH_DB` — the [`@dwk/indieauth`](../indieauth) issued-token store, consulted
+  for revocation.
+- `TOKEN_SIGNING_KEY` — the secret the IndieAuth token endpoint signs tokens with.
+
+### What it implements
+
+The single endpoint dispatches on the `action` (and `method`) parameter:
+
+- **Channels** (`action=channels`): list, create, rename, delete
+  (`method=delete`), and reorder (`method=order`). A reserved `notifications`
+  channel always exists and cannot be deleted or renamed.
+- **Following** (`action=follow` / `action=unfollow`): subscribe with feed
+  discovery (Atom / RSS / JSON Feed / `h-feed`); a follow populates the timeline
+  immediately and primes the poll cache.
+- **Timeline** (`action=timeline`): JF2 entries with `before` / `after` opaque
+  cursors, `mark_read` / `mark_unread` (`entry`, `entry[]`, or
+  `last_read_entry`), `remove`, and per-channel unread counts.
+- **Search / preview** (`action=search` / `action=preview`): discover or preview
+  a feed's entries without subscribing.
+
+Every request is authorized by a DPoP-bound IndieAuth access token whose subject
+must match the configured `me`, with the proof-of-possession binding completed
+via [`@dwk/dpop`](../dpop) and revocation checked against the strongly-consistent
+token store. Polling runs off the read path on a Cron-triggered queue; the read
+path serves stored entries only. Every outbound fetch is SSRF-guarded.
+
+## License
+
+[ISC](../../LICENSE)

package/dist/auth.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 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 { type AccessTokenClaims, type IndieAuthStoreEnv } from "@dwk/indieauth";
+import type { ResolvedConfig } from "./config";
+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;
+/**
+ * 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 declare function tokenFromHeader(request: Request): string | null;
+/** Whether the granted scope string contains any of the acceptable scopes. */
+export declare function hasScope(scope: string, acceptable: readonly string[]): boolean;
+/**
+ * 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 declare function authorize(request: Request, env: AuthEnv, config: ResolvedConfig, token: string | null, requiredScopes: readonly string[], recordReplay: boolean): Promise<AuthResult>;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACvB,MAAM,gBAAgB,CAAC;AAExB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEhD,6CAA6C;AAC7C,MAAM,WAAW,OAAQ,SAAQ,iBAAiB,EAAE,gBAAgB;IAClE,uEAAuE;IACvE,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC;AAED,6EAA6E;AAC7E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,6DAA6D;AAC7D,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;CACpC;AAED,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG,WAAW,CAAC;AAUnD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAK/D;AAED,8EAA8E;AAC9E,wBAAgB,QAAQ,CACtB,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,SAAS,MAAM,EAAE,GAC5B,OAAO,CAGT;AAED;;;;;GAKG;AACH,wBAAsB,SAAS,CAC7B,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,cAAc,EACtB,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,cAAc,EAAE,SAAS,MAAM,EAAE,EACjC,YAAY,EAAE,OAAO,GACpB,OAAO,CAAC,UAAU,CAAC,CA0FrB"}

package/dist/auth.js

@@ -0,0 +1,102 @@
+/**
+ * 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, } from "@dwk/indieauth";
+import { createDpopReplayStore } from "./replay";
+function failure(error, description, status) {
+    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) {
+    const header = request.headers.get("Authorization");
+    if (!header)
+        return null;
+    const match = /^(DPoP|Bearer)\s+(.+)$/i.exec(header.trim());
+    return match ? match[2] : null;
+}
+/** Whether the granted scope string contains any of the acceptable scopes. */
+export function hasScope(scope, acceptable) {
+    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, env, config, token, requiredScopes, recordReplay) {
+    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 };
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

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

package/dist/config.d.ts

@@ -0,0 +1,102 @@
+/**
+ * `@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 { 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;
+}
+/**
+ * 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 declare function resolveConfig(config: MicrosubConfig): ResolvedConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAA2B,KAAK,MAAM,EAAE,KAAK,OAAO,EAAE,MAAM,UAAU,CAAC;AAC9E,OAAO,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,2BAA2B,CAAC;AAEnE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC1B,6EAA6E;IAC7E,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC;IACjC,+CAA+C;IAC/C,QAAQ,CAAC,cAAc,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;IAC5C,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,uEAAuE;IACvE,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC;AAED,8EAA8E;AAC9E,MAAM,WAAW,cAAc;IAC7B,iEAAiE;IACjE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,kDAAkD;IAClD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC;;;;OAIG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC;;;;OAIG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,wFAAwF;IACxF,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC;IAC3B,oDAAoD;IACpD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,8EAA8E;AAC9E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAaD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,CAqCpE"}

package/dist/config.js

@@ -0,0 +1,64 @@
+/**
+ * `@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 } from "@dwk/log";
+const DEFAULT_PAGE_SIZE = 20;
+const DEFAULT_MAX_ITEMS = 5000;
+function pathOf(absoluteUrl, label) {
+    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) {
+    let base;
+    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,
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,WAAW,EAA6B,MAAM,UAAU,CAAC;AAuF9E,MAAM,iBAAiB,GAAG,EAAE,CAAC;AAC7B,MAAM,iBAAiB,GAAG,IAAI,CAAC;AAE/B,SAAS,MAAM,CAAC,WAAmB,EAAE,KAAa;IAChD,IAAI,CAAC;QACH,OAAO,IAAI,GAAG,CAAC,WAAW,CAAC,CAAC,QAAQ,CAAC;IACvC,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,kBAAkB,KAAK,qBAAqB,CAAC,CAAC;IAChE,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,MAAsB;IAClD,IAAI,IAAS,CAAC;IACd,IAAI,CAAC;QACH,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACjC,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;IACjE,CAAC;IAED,MAAM,EAAE,GAAG,sBAAsB,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC7C,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;IACpE,CAAC;IAED,MAAM,gBAAgB,GAAG,MAAM,CAAC,gBAAgB,IAAI,GAAG,IAAI,CAAC,MAAM,WAAW,CAAC;IAE9E,MAAM,QAAQ,GACZ,MAAM,CAAC,QAAQ,KAAK,SAAS,IAAI,MAAM,CAAC,QAAQ,GAAG,CAAC;QAClD,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC;QAC7B,CAAC,CAAC,iBAAiB,CAAC;IACxB,MAAM,kBAAkB,GACtB,MAAM,CAAC,kBAAkB,KAAK,SAAS,IAAI,MAAM,CAAC,kBAAkB,GAAG,CAAC;QACtE,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,kBAAkB,CAAC;QACvC,CAAC,CAAC,iBAAiB,CAAC;IAExB,OAAO;QACL,EAAE;QACF,gBAAgB;QAChB,YAAY,EAAE,MAAM,CAAC,gBAAgB,EAAE,kBAAkB,CAAC;QAC1D,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,MAAM,CAAC,OAAO;QACjD,QAAQ;QACR,kBAAkB;QAClB,eAAe,EAAE,MAAM,CAAC,eAAe,IAAI,IAAI;QAC/C,eAAe,EAAE,MAAM,CAAC,eAAe,IAAI,IAAI;QAC/C,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,CAAC,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QAC5D,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,UAAU;QACnC,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,WAAW;KACvC,CAAC;AACJ,CAAC"}

package/dist/consumer.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `@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 type { ExecutionContext, MessageBatch } from "@cloudflare/workers-types";
+import { type MicrosubConfig, type MicrosubEnv } from "./config";
+import type { MicrosubJob } from "./queue";
+import { 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;
+}
+/**
+ * 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 declare function createMicrosubQueueConsumer(config: MicrosubConfig, options?: ConsumerOptions): MicrosubQueueConsumer;
+//# sourceMappingURL=consumer.d.ts.map

package/dist/consumer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consumer.d.ts","sourceRoot":"","sources":["../src/consumer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAEhF,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,WAAW,EAEjB,MAAM,UAAU,CAAC;AAIlB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,SAAS,CAAC;AAElE,+CAA+C;AAC/C,MAAM,MAAM,qBAAqB,GAAG,CAClC,KAAK,EAAE,YAAY,CAAC,WAAW,CAAC,EAChC,GAAG,EAAE,WAAW,EAChB,GAAG,EAAE,gBAAgB,KAClB,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnB,iFAAiF;AACjF,MAAM,WAAW,eAAe;IAC9B,qEAAqE;IACrE,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC;IAC/B,uEAAuE;IACvE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAWD;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,cAAc,EACtB,OAAO,CAAC,EAAE,eAAe,GACxB,qBAAqB,CAuEvB"}

package/dist/consumer.js

@@ -0,0 +1,87 @@
+/**
+ * `@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 { resolveConfig, } from "./config";
+import { fetchFeed } from "./discovery";
+import { orderEntriesForInsert } from "./jf2";
+import { MicrosubLogEvent } from "./log";
+import { createMicrosubStore } from "./store";
+function emit(config, event, fields) {
+    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, options) {
+    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();
+            }
+        }
+    };
+}
+//# sourceMappingURL=consumer.js.map

package/dist/consumer.js.map

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

package/dist/discovery.d.ts

@@ -0,0 +1,59 @@
+/**
+ * `@dwk/microsub` — feed discovery and fetching.
+ *
+ * `follow` and `preview` take a URL the user typed; the server must work out
+ * what to actually poll. {@link discoverFeed} fetches that URL (through the
+ * SSRF-safe wrapper), and:
+ *
+ * - if it is already a syndication feed (Atom / RSS / JSON Feed), parses it;
+ * - if it is HTML, looks for a `<link rel="alternate">` feed and follows the
+ *   first one; failing that, parses the page's own `h-feed` microformats.
+ *
+ * {@link fetchFeed} re-fetches an already-resolved feed URL on each poll,
+ * sending the cached `ETag` / `Last-Modified` so an unchanged feed returns `304`
+ * and is skipped. Every outbound request goes through {@link safeFetch}, and the
+ * body is read with a hard size cap.
+ *
+ * @packageDocumentation
+ */
+import { type Logger, type Metrics } from "@dwk/log";
+import { type FetchLike } from "./fetch";
+import { type Jf2Entry } from "./jf2";
+/** Shared options for the discovery/fetch helpers. */
+export interface DiscoveryOptions {
+    readonly fetch?: FetchLike;
+    readonly logger?: Logger;
+    readonly metrics?: Metrics;
+}
+/** A resolved feed: the URL to poll and the entries parsed from its first fetch. */
+export interface DiscoveredFeed {
+    /** The URL the poller should re-fetch (a feed, or an HTML `h-feed` page). */
+    readonly feedUrl: string;
+    /** The entries parsed from the discovery fetch. */
+    readonly entries: readonly Jf2Entry[];
+}
+/** A completed feed fetch. */
+export interface FetchedFeed {
+    /** The parsed entries (empty when not modified or unparseable). */
+    readonly entries: readonly Jf2Entry[];
+    /** `true` when the server answered `304 Not Modified`. */
+    readonly notModified: boolean;
+    readonly etag: string | null;
+    readonly lastModified: string | null;
+}
+/**
+ * Discover the feed at `target`. Returns the URL to poll plus the entries from
+ * this first fetch, or `null` when the target is unreachable, blocked, or has no
+ * feed and no `h-entry` content.
+ */
+export declare function discoverFeed(target: string, options?: DiscoveryOptions): Promise<DiscoveredFeed | null>;
+/**
+ * Fetch and parse an already-resolved feed URL, sending conditional-request
+ * validators when supplied. Returns `notModified` on a `304`, the parsed
+ * entries otherwise, or `null` when the fetch fails or is blocked.
+ */
+export declare function fetchFeed(feedUrl: string, options?: DiscoveryOptions, cache?: {
+    etag: string | null;
+    lastModified: string | null;
+}): Promise<FetchedFeed | null>;
+//# sourceMappingURL=discovery.d.ts.map