@dwk/activitypub 0.1.0-beta.0

package/src/as2.ts

@@ -0,0 +1,257 @@
+/**
+ * ActivityStreams 2.0 vocabulary helpers for `@dwk/activitypub`.
+ *
+ * ActivityStreams 2.0 documents are JSON-LD, but the entire fediverse interops
+ * over the **compact** form with a fixed `@context`, so this module emits and
+ * parses that compact JSON shape directly rather than running a full JSON-LD
+ * processor. (Whether `@dwk/rdf`'s v1 JSON-LD subset covers the AS2 context is
+ * an open question — see `spec/open-questions.md` §4 — so v1 stays on the
+ * compact form Mastodon and friends actually speak.)
+ *
+ * Pure data: every function takes plain values and returns plain JSON objects,
+ * so the vocabulary is unit-testable without a Workers runtime or any binding.
+ */
+
+/** The ActivityStreams 2.0 namespace IRI. */
+export const AS2_NS = "https://www.w3.org/ns/activitystreams";
+
+/** The W3C security vocabulary namespace (carries `publicKey`). */
+export const SECURITY_NS = "https://w3id.org/security/v1";
+
+/** The special "public" collection that marks an activity world-readable. */
+export const PUBLIC_AUDIENCE = "https://www.w3.org/ns/activitystreams#Public";
+
+/**
+ * The `@context` an actor document advertises: the AS2 base plus the security
+ * vocabulary (so `publicKey` resolves) and the handful of property aliases
+ * (`manuallyApprovesFollowers`, `discoverable`) the fediverse expects.
+ */
+export const ACTOR_CONTEXT: readonly unknown[] = [
+  AS2_NS,
+  SECURITY_NS,
+  {
+    manuallyApprovesFollowers: "as:manuallyApprovesFollowers",
+    toot: "http://joinmastodon.org/ns#",
+    discoverable: "toot:discoverable",
+  },
+];
+
+/** Media type for an ActivityStreams 2.0 / ActivityPub document. */
+export const AS2_CONTENT_TYPE = "application/activity+json; charset=utf-8";
+
+/**
+ * The JSON-LD profile variant of AS2. A strict client may content-negotiate for
+ * `application/ld+json` carrying the ActivityStreams profile rather than the
+ * `application/activity+json` alias the fediverse speaks; both name the same
+ * document (§3.2).
+ */
+export const AS2_LD_CONTENT_TYPE =
+  'application/ld+json; profile="https://www.w3.org/ns/activitystreams"; charset=utf-8';
+
+/**
+ * The media types a federation peer uses to request AS2. A `GET` whose `Accept`
+ * names any of these (or the matching `profile`) wants the activity JSON rather
+ * than an HTML profile page.
+ */
+const AS2_ACCEPT_TOKENS = [
+  "application/activity+json",
+  "application/ld+json",
+  'profile="https://www.w3.org/ns/activitystreams"',
+];
+
+/** Whether an `Accept` header is asking for the ActivityStreams representation. */
+export function wantsActivityJson(accept: string | null): boolean {
+  if (!accept) return false;
+  const lower = accept.toLowerCase();
+  return AS2_ACCEPT_TOKENS.some((token) => lower.includes(token));
+}
+
+/**
+ * Pick the AS2 media type to serve for a given `Accept` (§3.2 content
+ * negotiation). A peer that asks specifically for the JSON-LD profile variant
+ * (`application/ld+json`, without also naming `application/activity+json`) gets
+ * {@link AS2_LD_CONTENT_TYPE}; everyone else — plain browsers, and the
+ * `application/activity+json` alias the fediverse speaks — gets
+ * {@link AS2_CONTENT_TYPE}.
+ */
+export function as2ContentType(accept: string | null): string {
+  if (accept && wantsActivityJson(accept)) {
+    const lower = accept.toLowerCase();
+    if (
+      lower.includes("application/ld+json") &&
+      !lower.includes("application/activity+json")
+    ) {
+      return AS2_LD_CONTENT_TYPE;
+    }
+  }
+  return AS2_CONTENT_TYPE;
+}
+
+/** A minimal JSON value type for AS2 documents. */
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | readonly JsonValue[]
+  | { readonly [key: string]: JsonValue };
+
+/** A parsed ActivityStreams object/activity (compact JSON). */
+export interface ActivityObject {
+  readonly id?: string;
+  readonly type?: string;
+  readonly actor?: JsonValue;
+  readonly object?: JsonValue;
+  readonly target?: JsonValue;
+  readonly to?: JsonValue;
+  readonly cc?: JsonValue;
+  readonly [key: string]: JsonValue | undefined;
+}
+
+/** The derived IRI set that identifies one actor and its collections. */
+export interface ActorIris {
+  readonly id: string;
+  readonly inbox: string;
+  readonly outbox: string;
+  readonly followers: string;
+  readonly following: string;
+  readonly keyId: string;
+}
+
+/** The human-facing profile fields of an actor. */
+export interface ActorProfile {
+  /** `preferredUsername` — the local part of the `acct:` handle. */
+  readonly username: string;
+  /** Display name; defaults to {@link username}. */
+  readonly name?: string;
+  /** Short bio rendered as `summary` (may contain HTML). */
+  readonly summary?: string;
+  /** Avatar image URL, surfaced as the actor `icon`. */
+  readonly icon?: string;
+  /** Whether follows require manual approval. Defaults to `false` (auto-accept). */
+  readonly manuallyApprovesFollowers?: boolean;
+  /** Whether the actor opts into discovery/search (Mastodon `toot:discoverable`). */
+  readonly discoverable?: boolean;
+}
+
+/** Optional extras woven into the actor document. */
+export interface ActorDocumentOptions {
+  /**
+   * The instance-level shared inbox IRI, advertised under `endpoints` (§4.1 /
+   * §7.1.3) so large peers can batch-deliver to this actor. Omitted entirely
+   * when the deployment does not serve one.
+   */
+  readonly sharedInbox?: string;
+}
+
+/**
+ * Build the `Person` actor document served at the actor IRI. The public key is
+ * embedded inline (PEM) under the security vocabulary so verifiers can resolve
+ * `keyId` without a second fetch, exactly as Mastodon publishes it.
+ */
+export function buildActorDocument(
+  iris: ActorIris,
+  profile: ActorProfile,
+  publicKeyPem: string,
+  options: ActorDocumentOptions = {},
+): Record<string, JsonValue> {
+  const doc: Record<string, JsonValue> = {
+    "@context": ACTOR_CONTEXT as JsonValue,
+    id: iris.id,
+    type: "Person",
+    preferredUsername: profile.username,
+    name: profile.name ?? profile.username,
+    inbox: iris.inbox,
+    outbox: iris.outbox,
+    followers: iris.followers,
+    following: iris.following,
+    manuallyApprovesFollowers: profile.manuallyApprovesFollowers ?? false,
+    discoverable: profile.discoverable ?? true,
+    publicKey: {
+      id: iris.keyId,
+      owner: iris.id,
+      publicKeyPem,
+    },
+  };
+  if (profile.summary !== undefined) doc.summary = profile.summary;
+  if (profile.icon !== undefined) {
+    doc.icon = { type: "Image", url: profile.icon };
+  }
+  if (options.sharedInbox !== undefined) {
+    doc.endpoints = { sharedInbox: options.sharedInbox };
+  }
+  return doc;
+}
+
+/**
+ * Build a paged `OrderedCollection` head document — the response to a bare
+ * collection `GET` (no `page` parameter). It advertises the total count and the
+ * `first`/`last` page links; the members live on the pages.
+ */
+export function buildCollection(
+  id: string,
+  totalItems: number,
+  pageSize: number,
+): Record<string, JsonValue> {
+  const doc: Record<string, JsonValue> = {
+    "@context": AS2_NS,
+    id,
+    type: "OrderedCollection",
+    totalItems,
+  };
+  if (totalItems > 0) {
+    doc.first = `${id}?page=1`;
+    doc.last = `${id}?page=${Math.max(1, Math.ceil(totalItems / pageSize))}`;
+  }
+  return doc;
+}
+
+/**
+ * Build one `OrderedCollectionPage` of members. `next` is present only when a
+ * further page exists, so a crawler walks `first → next → …` until it stops.
+ */
+export function buildCollectionPage(
+  collectionId: string,
+  page: number,
+  pageSize: number,
+  totalItems: number,
+  items: readonly JsonValue[],
+): Record<string, JsonValue> {
+  const doc: Record<string, JsonValue> = {
+    "@context": AS2_NS,
+    id: `${collectionId}?page=${page}`,
+    type: "OrderedCollectionPage",
+    partOf: collectionId,
+    totalItems,
+    orderedItems: items as JsonValue,
+  };
+  if (page * pageSize < totalItems) {
+    doc.next = `${collectionId}?page=${page + 1}`;
+  }
+  if (page > 1) doc.prev = `${collectionId}?page=${page - 1}`;
+  return doc;
+}
+
+/** Read the `id` of an activity's `object`, whether it is an IRI or nested object. */
+export function objectId(value: JsonValue | undefined): string | undefined {
+  if (typeof value === "string") return value;
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    const id = (value as Record<string, JsonValue>).id;
+    if (typeof id === "string") return id;
+  }
+  return undefined;
+}
+
+/** Read the `type` of an activity's `object` when it is a nested object. */
+export function objectType(value: JsonValue | undefined): string | undefined {
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    const type = (value as Record<string, JsonValue>).type;
+    if (typeof type === "string") return type;
+  }
+  return undefined;
+}
+
+/** Coerce an actor reference (IRI string or embedded object) to its IRI. */
+export function actorIri(value: JsonValue | undefined): string | undefined {
+  return objectId(value);
+}

package/src/config.ts

@@ -0,0 +1,291 @@
+/**
+ * Configuration, the declared Cloudflare `Env` fragment, and config resolution
+ * for `@dwk/activitypub`.
+ *
+ * Per the composition contract the package never reads the global environment
+ * directly: the actor profile, key material, and delivery policy are all passed
+ * into {@link createActivityPub}, so an actor can be instantiated multiple times
+ * and unit-tested in isolation. The only runtime coupling is the per-actor
+ * Durable Object namespace, and a missing binding fails loudly at startup.
+ */
+
+import { noopLogger, noopMetrics, type Logger, type Metrics } from "@dwk/log";
+
+import type { ActorIris, ActorProfile } from "./as2";
+import type {
+  KeyResolver,
+  ResolvedKey,
+  VerifyResult,
+  InboxRequest,
+} from "./signature";
+import type { SoftwareInfo } from "./nodeinfo";
+import type { ActivityPubObject } from "./object";
+
+/** Cloudflare bindings required by the ActivityPub handler and Durable Object. */
+export interface ActivityPubEnv {
+  /**
+   * Durable Object namespace for the per-actor class
+   * ({@link ActivityPubObject}). The single authoritative store for the inbox,
+   * outbox, follower/following collections, activity-`id` dedup, and the
+   * delivery queue.
+   */
+  readonly ACTOR: DurableObjectNamespace<ActivityPubObject>;
+}
+
+/** An override for inbound signature verification (see `@dwk/http-signatures`, #59). */
+export type InboxVerifier = (
+  request: InboxRequest,
+) => Promise<VerifyResult> | VerifyResult;
+
+/** Configuration passed to {@link createActivityPub}. */
+export interface ActivityPubConfig {
+  /**
+   * The actor's identity root / base URL, e.g. `https://example.com`. The actor
+   * IRI and every collection IRI are derived from it. No trailing slash. Mount
+   * the package under a path prefix by including it here (e.g.
+   * `https://example.com/ap`).
+   */
+  readonly baseUrl: string;
+
+  /** The single actor this deployment serves (v1 is one actor per `baseUrl`). */
+  readonly actor: ActorProfile;
+
+  /**
+   * PEM-encoded SPKI **public** key, published inline in the actor document so
+   * peers can verify this actor's outbound signatures.
+   */
+  readonly publicKeyPem: string;
+
+  /**
+   * PEM-encoded PKCS#8 **private** key (a secret binding's value) used to sign
+   * outbound deliveries. Required to federate outbound (e.g. `Accept` a follow);
+   * omit it for a read-only actor that never delivers.
+   */
+  readonly privateKeyPem?: string;
+
+  /**
+   * Bearer token authorizing the owner-only publish endpoint
+   * (`POST <actor>/outbox`). When unset, that endpoint is disabled. This is the
+   * `@dwk/micropub` publish → `Create` fan-out seam; full C2S is out of scope
+   * for v1.
+   */
+  readonly publishToken?: string;
+
+  /**
+   * Whether to serve and advertise an instance-level **shared inbox** at
+   * `${baseUrl}/inbox` (ActivityPub §4.1 / §7.1.3), letting large peers
+   * batch-deliver to this actor. Defaults to `true`; set `false` to publish no
+   * `endpoints.sharedInbox` and serve no shared-inbox route.
+   */
+  readonly sharedInbox?: boolean;
+
+  /** Members served per `OrderedCollection` page. Defaults to 50. */
+  readonly pageSize?: number;
+
+  /** Max delivery attempts before a queued activity is dropped. Defaults to 8. */
+  readonly deliveryMaxAttempts?: number;
+
+  /** Base backoff (ms) for delivery retries (doubled per attempt). Defaults to 60_000. */
+  readonly deliveryBaseDelayMs?: number;
+
+  /** Accepted clock skew (seconds) on inbound signed `Date` headers. Defaults to 300. */
+  readonly clockSkewSeconds?: number;
+
+  /** Software identity for the NodeInfo document. Defaults to this package. */
+  readonly software?: SoftwareInfo;
+
+  /**
+   * Resolve a `keyId` to its owner + PEM key for inbound verification. Defaults
+   * to fetching the `keyId` (an actor or key IRI) as AS2 and reading
+   * `publicKey`. Supply your own to add caching or a key store.
+   */
+  readonly keyResolver?: KeyResolver;
+
+  /**
+   * Override inbound signature verification entirely (e.g. to plug in
+   * `@dwk/http-signatures`). When set, the built-in draft-cavage verifier and
+   * {@link keyResolver} are bypassed.
+   */
+  readonly verifyInboxSignature?: InboxVerifier;
+
+  /** `fetch` used for key resolution and outbound delivery. Defaults to global `fetch`. */
+  readonly fetch?: typeof fetch;
+
+  /** Injectable clock (epoch ms) for deterministic tests. Defaults to `Date.now`. */
+  readonly now?: () => number;
+
+  /** Structured-logging seam; defaults to a no-op. */
+  readonly logger?: Logger;
+  /** Metrics seam; defaults to a no-op. */
+  readonly metrics?: Metrics;
+}
+
+/** Fully-resolved configuration with defaults applied and IRIs derived. */
+export interface ResolvedConfig {
+  readonly baseUrl: string;
+  readonly actor: ActorProfile;
+  readonly iris: ActorIris;
+  /** Instance-level shared inbox IRI, or `undefined` when not served. */
+  readonly sharedInbox?: string;
+  readonly publicKeyPem: string;
+  readonly privateKeyPem?: string;
+  readonly publishToken?: string;
+  readonly pageSize: number;
+  readonly deliveryMaxAttempts: number;
+  readonly deliveryBaseDelayMs: number;
+  readonly clockSkewSeconds: number;
+  readonly software: SoftwareInfo;
+  readonly keyResolver: KeyResolver;
+  readonly verifyInboxSignature?: InboxVerifier;
+  readonly fetch: typeof fetch;
+  readonly now: () => number;
+  readonly logger: Logger;
+  readonly metrics: Metrics;
+}
+
+/**
+ * Internal headers the trusted front door uses to hand verified facts and the
+ * config subset the DO needs (including signing key material, which never leaves
+ * Cloudflare's network) to the Durable Object.
+ */
+export const INTERNAL_HEADERS = {
+  /** The verified actor IRI that signed an inbound `POST /inbox` (absent ⇒ unverified). */
+  signedActor: "x-ap-signed-actor",
+  /** JSON config subset the DO needs (IRIs, delivery policy, signing key). */
+  config: "x-ap-config",
+  /** Marks an owner-authorized publish request (`POST <actor>/outbox`). */
+  publish: "x-ap-publish",
+} as const;
+
+/** The config subset the front door forwards to the DO via {@link INTERNAL_HEADERS.config}. */
+export interface ForwardedConfig {
+  readonly iris: ActorIris;
+  readonly actorName: string;
+  /** Shared inbox IRI the DO should also accept inbound `POST`s on, if served. */
+  readonly sharedInbox?: string;
+  readonly manuallyApprovesFollowers: boolean;
+  readonly pageSize: number;
+  readonly deliveryMaxAttempts: number;
+  readonly deliveryBaseDelayMs: number;
+  readonly keyId: string;
+  /** Private key (PKCS#8 PEM) so the DO can sign deliveries from its alarm. */
+  readonly privateKeyPem?: string;
+}
+
+const DEFAULT_PAGE_SIZE = 50;
+const DEFAULT_MAX_ATTEMPTS = 8;
+const DEFAULT_BASE_DELAY_MS = 60_000;
+const DEFAULT_CLOCK_SKEW_SECONDS = 300;
+
+const DEFAULT_SOFTWARE: SoftwareInfo = {
+  name: "dwk-activitypub",
+  version: "0.0.0",
+};
+
+/** Strip a trailing slash so path joins are unambiguous. */
+function normalizeBaseUrl(baseUrl: string): string {
+  return baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+}
+
+/** Derive the actor + collection IRIs from a base URL and username. */
+export function deriveIris(baseUrl: string, username: string): ActorIris {
+  const id = `${baseUrl}/users/${encodeURIComponent(username)}`;
+  return {
+    id,
+    inbox: `${id}/inbox`,
+    outbox: `${id}/outbox`,
+    followers: `${id}/followers`,
+    following: `${id}/following`,
+    keyId: `${id}#main-key`,
+  };
+}
+
+/**
+ * The default key resolver: fetch the `keyId` (an actor or fragment IRI) as AS2
+ * and read its embedded `publicKey`. Returns `null` when the document cannot be
+ * fetched or carries no usable key, which the verifier maps to a rejection.
+ */
+function defaultKeyResolver(fetchImpl: typeof fetch): KeyResolver {
+  return async (keyId: string): Promise<ResolvedKey | null> => {
+    // The key IRI is the actor (or key) document URL with its fragment
+    // stripped. Parse it as a URL so the fragment is removed per the URL spec
+    // (rather than by string surgery) and an unparseable `keyId` is rejected
+    // before it reaches `fetch`.
+    let actorUrl: string;
+    try {
+      const url = new URL(keyId);
+      // Only ever dereference a remote actor/key document over HTTP(S); reject
+      // other schemes (`file:`, `data:`, …) outright so a crafted `keyId`
+      // cannot redirect the fetch at a non-network resource.
+      if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+      url.hash = "";
+      actorUrl = url.href;
+    } catch {
+      return null;
+    }
+    let response: Response;
+    try {
+      response = await fetchImpl(actorUrl, {
+        headers: { accept: "application/activity+json" },
+        // Bound key resolution so a slow remote cannot stall inbox verification.
+        signal: AbortSignal.timeout(10_000),
+      });
+    } catch {
+      return null;
+    }
+    if (!response.ok) return null;
+    let doc: unknown;
+    try {
+      doc = await response.json();
+    } catch {
+      return null;
+    }
+    if (!doc || typeof doc !== "object") return null;
+    const publicKey = (doc as Record<string, unknown>).publicKey;
+    if (!publicKey || typeof publicKey !== "object") return null;
+    const pem = (publicKey as Record<string, unknown>).publicKeyPem;
+    const owner =
+      (publicKey as Record<string, unknown>).owner ??
+      (doc as Record<string, unknown>).id;
+    if (typeof pem !== "string" || typeof owner !== "string") return null;
+    return { owner, publicKeyPem: pem };
+  };
+}
+
+/** Apply defaults and derive IRIs from raw {@link ActivityPubConfig}. */
+export function resolveConfig(config: ActivityPubConfig): ResolvedConfig {
+  if (!config.baseUrl) {
+    throw new Error("@dwk/activitypub: `baseUrl` is required");
+  }
+  if (!config.actor || !config.actor.username) {
+    throw new Error("@dwk/activitypub: `actor.username` is required");
+  }
+  if (!config.publicKeyPem) {
+    throw new Error("@dwk/activitypub: `publicKeyPem` is required");
+  }
+  const baseUrl = normalizeBaseUrl(config.baseUrl);
+  const fetchImpl = config.fetch ?? fetch;
+  const sharedInbox =
+    (config.sharedInbox ?? true) ? `${baseUrl}/inbox` : undefined;
+
+  return {
+    baseUrl,
+    actor: config.actor,
+    iris: deriveIris(baseUrl, config.actor.username),
+    sharedInbox,
+    publicKeyPem: config.publicKeyPem,
+    privateKeyPem: config.privateKeyPem,
+    publishToken: config.publishToken,
+    pageSize: config.pageSize ?? DEFAULT_PAGE_SIZE,
+    deliveryMaxAttempts: config.deliveryMaxAttempts ?? DEFAULT_MAX_ATTEMPTS,
+    deliveryBaseDelayMs: config.deliveryBaseDelayMs ?? DEFAULT_BASE_DELAY_MS,
+    clockSkewSeconds: config.clockSkewSeconds ?? DEFAULT_CLOCK_SKEW_SECONDS,
+    software: config.software ?? DEFAULT_SOFTWARE,
+    keyResolver: config.keyResolver ?? defaultKeyResolver(fetchImpl),
+    verifyInboxSignature: config.verifyInboxSignature,
+    fetch: fetchImpl,
+    now: config.now ?? (() => Date.now()),
+    logger: config.logger ?? noopLogger,
+    metrics: config.metrics ?? noopMetrics,
+  };
+}

package/src/delivery.ts

@@ -0,0 +1,155 @@
+/**
+ * Outbound delivery for `@dwk/activitypub`: sign an activity and `POST` it to a
+ * remote inbox.
+ *
+ * Delivery targets are attacker-influenced URLs (a follower's advertised inbox),
+ * so every target passes a syntactic SSRF guard before any request leaves —
+ * rejecting non-HTTPS schemes and private / loopback / link-local hosts so a
+ * malicious actor cannot point a delivery at the Worker's own network. (DNS
+ * rebinding is out of scope: the Workers runtime does not expose name
+ * resolution to user code; see `@dwk/webmention`'s safe-fetch for the same
+ * limitation.) The forthcoming `@dwk/http-signatures` package owns the signing
+ * primitive; this module wires it to the network.
+ */
+
+import { signRequest, type SignerKey } from "./signature";
+
+/** Machine-readable cause of a blocked delivery target. */
+export type BlockedReason =
+  | "invalid_url"
+  | "disallowed_scheme"
+  | "blocked_host";
+
+/** Raised when a delivery target is refused on SSRF grounds. */
+export class DeliveryBlockedError extends Error {
+  readonly reason: BlockedReason;
+  constructor(reason: BlockedReason) {
+    super(`delivery target blocked: ${reason}`);
+    this.name = "DeliveryBlockedError";
+    this.reason = reason;
+  }
+}
+
+/** Parse a canonical dotted-decimal IPv4 host into its four octets. */
+function parseIPv4(host: string): [number, number, number, number] | null {
+  const match = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+  if (!match) return null;
+  const octets: number[] = [];
+  for (let i = 1; i <= 4; i++) {
+    const value = Number(match[i]);
+    if (value > 255) return null;
+    octets.push(value);
+  }
+  return octets as [number, number, number, number];
+}
+
+/** Whether an IPv4 address falls in a private, loopback, or link-local range. */
+function isPrivateIPv4(octets: [number, number, number, number]): boolean {
+  const [a, b] = octets;
+  if (a === 10) return true; // 10.0.0.0/8
+  if (a === 127) return true; // loopback
+  if (a === 0) return true; // "this network"
+  if (a === 169 && b === 254) return true; // link-local (incl. cloud metadata)
+  if (a === 172 && b >= 16 && b <= 31) return true; // 172.16.0.0/12
+  if (a === 192 && b === 168) return true; // 192.168.0.0/16
+  if (a >= 224) return true; // multicast / reserved
+  return false;
+}
+
+/** A host name that names the local host or an internal/reserved suffix. */
+function isBlockedHostName(host: string): boolean {
+  const lower = host.toLowerCase();
+  if (lower === "localhost") return true;
+  return (
+    lower.endsWith(".localhost") ||
+    lower.endsWith(".internal") ||
+    lower.endsWith(".local")
+  );
+}
+
+/**
+ * Validate a delivery target URL: HTTPS only, and a public host. Throws a
+ * {@link DeliveryBlockedError} on any failure so the caller logs it and drops
+ * the row rather than retrying a target that can never be reached.
+ */
+export function assertPublicHttpsTarget(url: string): URL {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new DeliveryBlockedError("invalid_url");
+  }
+  if (parsed.protocol !== "https:") {
+    throw new DeliveryBlockedError("disallowed_scheme");
+  }
+  const host = parsed.hostname;
+  const ipv4 = parseIPv4(host);
+  if (ipv4 && isPrivateIPv4(ipv4)) {
+    throw new DeliveryBlockedError("blocked_host");
+  }
+  // IPv6 loopback / unique-local / link-local, and bracketed forms.
+  const v6 = host.replace(/^\[|\]$/g, "").toLowerCase();
+  if (
+    v6 === "::1" ||
+    v6.startsWith("fe80:") ||
+    v6.startsWith("fc") ||
+    v6.startsWith("fd")
+  ) {
+    throw new DeliveryBlockedError("blocked_host");
+  }
+  if (isBlockedHostName(host)) {
+    throw new DeliveryBlockedError("blocked_host");
+  }
+  return parsed;
+}
+
+/** The outcome of a single delivery attempt. */
+export type DeliveryResult =
+  | { readonly ok: true; readonly status: number }
+  | {
+      readonly ok: false;
+      readonly status: number;
+      readonly retryable: boolean;
+    };
+
+/**
+ * Sign and `POST` one activity to a remote inbox. A `2xx` is success; `4xx`
+ * (except `408`/`429`) is a permanent failure (drop) since the peer rejected the
+ * request; `5xx`, `408`, `429`, and network errors are retryable.
+ */
+export async function deliverActivity(
+  inboxUrl: string,
+  activityJson: string,
+  signer: SignerKey,
+  fetchImpl: typeof fetch,
+  now: () => number = () => Date.now(),
+  timeoutMs = 10_000,
+): Promise<DeliveryResult> {
+  // Throws DeliveryBlockedError for an unsafe target — the caller drops the row.
+  assertPublicHttpsTarget(inboxUrl);
+
+  const body = new TextEncoder().encode(activityJson);
+  const signed = await signRequest(inboxUrl, body, signer, { now });
+
+  let response: Response;
+  try {
+    response = await fetchImpl(inboxUrl, {
+      method: "POST",
+      headers: signed.headers,
+      body: signed.body as BufferSource,
+      // A hung peer must not pin the delivery worker; a timeout is retryable.
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch {
+    return { ok: false, status: 0, retryable: true };
+  }
+
+  if (response.status >= 200 && response.status < 300) {
+    return { ok: true, status: response.status };
+  }
+  const retryable =
+    response.status >= 500 ||
+    response.status === 408 ||
+    response.status === 429;
+  return { ok: false, status: response.status, retryable };
+}