@dwk/webfinger 0.1.0-beta.0

package/dist/log.js

@@ -0,0 +1,34 @@
+/**
+ * `@dwk/webfinger` — structured observability event taxonomy.
+ *
+ * WebFinger is public discovery data, so the stakes are lower than an auth
+ * endpoint — but a server being scraped for `acct:` handles it does not control,
+ * or a misconfigured resource map that 404s every lookup, is exactly the kind of
+ * thing an operator wants a signal for. Logging and metrics are opt-in via an
+ * injected {@link Logger} and {@link Metrics} (see `@dwk/log`) and **share this
+ * one vocabulary**: the same dotted event name is passed to the logger and the
+ * metrics sink so a log line and its counter line up.
+ *
+ * Fields follow the redaction policy: a `resource` is reduced to its **host**
+ * (the domain of an `acct:`/`mailto:` handle or an `https:` URI) via the
+ * handler's `resourceHost` helper — the local part (the user identifier) is
+ * never logged, only the domain, a machine-readable `reason`, and the count of
+ * `rel` filters. See `spec/observability.md`.
+ *
+ * @packageDocumentation
+ */
+/** Stable event names emitted by `@dwk/webfinger`. */
+export const WebfingerLogEvent = {
+    /**
+     * A `resource` was matched and a JRD returned. Fields: `resourceHost`
+     * (sanitized), `relCount` (number of `rel` filters applied).
+     */
+    Resolved: "webfinger.resolved",
+    /**
+     * A request was rejected before a JRD could be returned. Field: `reason`
+     * (`missing_resource`, `malformed_resource`, `not_found`, or
+     * `method_not_allowed`), plus `resourceHost` when a `resource` was supplied.
+     */
+    Rejected: "webfinger.rejected",
+};
+//# sourceMappingURL=log.js.map

package/dist/log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.js","sourceRoot":"","sources":["../src/log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,sDAAsD;AACtD,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B;;;OAGG;IACH,QAAQ,EAAE,oBAAoB;IAC9B;;;;OAIG;IACH,QAAQ,EAAE,oBAAoB;CACtB,CAAC"}

package/dist/resource.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Resource-URI normalization for case-insensitive matching (RFC 7033 §4.1;
+ * RFC 3986 §3.1 and §6.2.2.1): a URI's **scheme** and **host** are
+ * case-insensitive, so a query for `acct:alice@EXAMPLE.COM` must match a
+ * configured `acct:alice@example.com`. The local part of an `acct:`/`mailto:`
+ * handle is the user identifier and stays **case-sensitive**.
+ *
+ * Normalization scopes the *lookup key* only: both the queried resource and the
+ * configured map keys are normalized before comparison (see `config.ts`). The
+ * echoed `subject` keeps the client's literal spelling — the package spec
+ * requires the subject to equal the queried resource URI, and fediverse software
+ * compares it case-insensitively.
+ */
+/**
+ * Normalize a resource URI for comparison: lowercase the scheme and host,
+ * preserving the case of an `acct:`/`mailto:` local part. For `http(s)` URIs the
+ * WHATWG `URL` parser performs the scheme/host lowercasing (and its standard
+ * path normalization); a URI that does not parse is returned with only its
+ * scheme lowercased, and a string with no scheme is returned unchanged.
+ */
+export declare function normalizeResource(resource: string): string;
+/**
+ * Decide whether a queried `resource` is a syntactically well-formed URI
+ * (RFC 7033 §4.2): it MUST carry a scheme (RFC 3986 §3.1), and an `http(s)`
+ * resource MUST additionally parse as an absolute URL. A value with no scheme,
+ * an ill-formed scheme, or an unparseable `http(s)` authority is *malformed*,
+ * and the handler answers `400` (not `404`) before any lookup — §4.2 requires a
+ * "bad request" indication when `resource` is absent **or malformed**.
+ *
+ * Validation is deliberately minimal: a syntactically valid scheme is enough for
+ * non-`http(s)` URIs (`acct:`, `mailto:`, `urn:`), since the resolver — not this
+ * gate — owns whether such a resource is controlled.
+ */
+export declare function isWellFormedResource(resource: string): boolean;
+//# sourceMappingURL=resource.d.ts.map

package/dist/resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../src/resource.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAwB1D;AAQD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAgB9D"}

package/dist/resource.js

@@ -0,0 +1,79 @@
+/**
+ * Resource-URI normalization for case-insensitive matching (RFC 7033 §4.1;
+ * RFC 3986 §3.1 and §6.2.2.1): a URI's **scheme** and **host** are
+ * case-insensitive, so a query for `acct:alice@EXAMPLE.COM` must match a
+ * configured `acct:alice@example.com`. The local part of an `acct:`/`mailto:`
+ * handle is the user identifier and stays **case-sensitive**.
+ *
+ * Normalization scopes the *lookup key* only: both the queried resource and the
+ * configured map keys are normalized before comparison (see `config.ts`). The
+ * echoed `subject` keeps the client's literal spelling — the package spec
+ * requires the subject to equal the queried resource URI, and fediverse software
+ * compares it case-insensitively.
+ */
+/**
+ * Normalize a resource URI for comparison: lowercase the scheme and host,
+ * preserving the case of an `acct:`/`mailto:` local part. For `http(s)` URIs the
+ * WHATWG `URL` parser performs the scheme/host lowercasing (and its standard
+ * path normalization); a URI that does not parse is returned with only its
+ * scheme lowercased, and a string with no scheme is returned unchanged.
+ */
+export function normalizeResource(resource) {
+    const colon = resource.indexOf(":");
+    if (colon <= 0)
+        return resource;
+    const scheme = resource.slice(0, colon).toLowerCase();
+    const rest = resource.slice(colon + 1);
+    if (scheme === "acct" || scheme === "mailto") {
+        const at = rest.lastIndexOf("@");
+        if (at === -1)
+            return `${scheme}:${rest}`;
+        const local = rest.slice(0, at);
+        const host = rest.slice(at + 1).toLowerCase();
+        return `${scheme}:${local}@${host}`;
+    }
+    if (scheme === "http" || scheme === "https") {
+        try {
+            return new URL(resource).href;
+        }
+        catch {
+            return `${scheme}:${rest}`;
+        }
+    }
+    return `${scheme}:${rest}`;
+}
+/**
+ * A valid URI scheme per RFC 3986 §3.1: an ALPHA followed by any number of
+ * ALPHA / DIGIT / "+" / "-" / ".".
+ */
+const SCHEME_PATTERN = /^[a-z][a-z0-9+.-]*$/i;
+/**
+ * Decide whether a queried `resource` is a syntactically well-formed URI
+ * (RFC 7033 §4.2): it MUST carry a scheme (RFC 3986 §3.1), and an `http(s)`
+ * resource MUST additionally parse as an absolute URL. A value with no scheme,
+ * an ill-formed scheme, or an unparseable `http(s)` authority is *malformed*,
+ * and the handler answers `400` (not `404`) before any lookup — §4.2 requires a
+ * "bad request" indication when `resource` is absent **or malformed**.
+ *
+ * Validation is deliberately minimal: a syntactically valid scheme is enough for
+ * non-`http(s)` URIs (`acct:`, `mailto:`, `urn:`), since the resolver — not this
+ * gate — owns whether such a resource is controlled.
+ */
+export function isWellFormedResource(resource) {
+    const colon = resource.indexOf(":");
+    if (colon <= 0)
+        return false;
+    const scheme = resource.slice(0, colon).toLowerCase();
+    if (!SCHEME_PATTERN.test(scheme))
+        return false;
+    if (scheme === "http" || scheme === "https") {
+        try {
+            new URL(resource);
+        }
+        catch {
+            return false;
+        }
+    }
+    return true;
+}
+//# sourceMappingURL=resource.js.map

package/dist/resource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.js","sourceRoot":"","sources":["../src/resource.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAgB;IAChD,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACpC,IAAI,KAAK,IAAI,CAAC;QAAE,OAAO,QAAQ,CAAC;IAEhC,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;IACtD,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;IAEvC,IAAI,MAAM,KAAK,MAAM,IAAI,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC7C,MAAM,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,EAAE,KAAK,CAAC,CAAC;YAAE,OAAO,GAAG,MAAM,IAAI,IAAI,EAAE,CAAC;QAC1C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAChC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;QAC9C,OAAO,GAAG,MAAM,IAAI,KAAK,IAAI,IAAI,EAAE,CAAC;IACtC,CAAC;IAED,IAAI,MAAM,KAAK,MAAM,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;QAC5C,IAAI,CAAC;YACH,OAAO,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC;QAChC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,GAAG,MAAM,IAAI,IAAI,EAAE,CAAC;QAC7B,CAAC;IACH,CAAC;IAED,OAAO,GAAG,MAAM,IAAI,IAAI,EAAE,CAAC;AAC7B,CAAC;AAED;;;GAGG;AACH,MAAM,cAAc,GAAG,sBAAsB,CAAC;AAE9C;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAAgB;IACnD,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACpC,IAAI,KAAK,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IAE7B,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;IACtD,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC;QAAE,OAAO,KAAK,CAAC;IAE/C,IAAI,MAAM,KAAK,MAAM,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;QAC5C,IAAI,CAAC;YACH,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC;QACpB,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@dwk/webfinger",
+  "version": "0.1.0-beta.0",
+  "description": "WebFinger (RFC 7033) account/resource discovery endpoint at /.well-known/webfinger.",
+  "keywords": [
+    "webfinger",
+    "rfc7033",
+    "well-known",
+    "discovery",
+    "cloudflare-workers"
+  ],
+  "type": "module",
+  "license": "ISC",
+  "author": "David W. Keith <me@dwk.io>",
+  "homepage": "https://github.com/davidwkeith/workers/tree/main/packages/webfinger#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/davidwkeith/workers.git",
+    "directory": "packages/webfinger"
+  },
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@dwk/log": "0.1.0-beta.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist"
+  }
+}

package/src/config.ts

@@ -0,0 +1,120 @@
+/**
+ * Configuration for {@link createWebfinger}: the set of resources this server
+ * controls (a static map, a resolver function, or both) plus the optional
+ * logging/metrics seams. Per the composition contract the package never reads
+ * the global environment — every resource mapping arrives here, so a handler can
+ * be instantiated multiple times and tested in isolation.
+ */
+
+import { noopLogger, noopMetrics, type Logger, type Metrics } from "@dwk/log";
+
+import type { ResourceRecord } from "./jrd";
+import { normalizeResource } from "./resource";
+
+/**
+ * A dynamic resolver from a queried `resource` URI to its {@link ResourceRecord},
+ * or `undefined` when this server does not control the resource (→ `404`). The
+ * `resource` is passed **normalized** (lowercased scheme/host per RFC 7033 §4.1),
+ * so a resolver can compare it directly without re-normalizing. The matched
+ * `rel` filters are passed through so a resolver backed by stored data (e.g. a
+ * profile document via `@dwk/rdf`) can avoid materialising links it is about to
+ * discard, but applying the filter is optional — the handler always re-applies
+ * {@link filterLinksByRel} to whatever is returned.
+ */
+export type ResourceResolver = (
+  resource: string,
+  rels: readonly string[],
+) => ResourceRecord | undefined | Promise<ResourceRecord | undefined>;
+
+/** Configuration passed to {@link createWebfinger}. */
+export interface WebfingerConfig {
+  /**
+   * Static map of controlled `resource` URI → its descriptor. Keys are the
+   * exact `resource` values clients query (`acct:user@example.com`,
+   * `https://example.com/`, `mailto:user@example.com`). Consulted before
+   * {@link resolve}.
+   */
+  readonly resources?: Readonly<Record<string, ResourceRecord>>;
+  /**
+   * Dynamic fallback consulted when {@link resources} has no entry for the
+   * queried URI. At least one of {@link resources} or `resolve` MUST be
+   * supplied, or {@link createWebfinger} throws at construction time.
+   */
+  readonly resolve?: ResourceResolver;
+  /**
+   * Logger for discovery events; defaults to a no-op. Wire a real logger (see
+   * `@dwk/log`) to surface unknown-resource probes and method rejections instead
+   * of swallowing them.
+   */
+  readonly logger?: Logger;
+  /**
+   * Metrics sink for discovery counters; defaults to a no-op. Wire an adapter
+   * (e.g. `analyticsEngineMetrics` from `@dwk/log`) to chart the same events the
+   * logger names — "lookups/min", "404 rate", "rel-filtered lookups".
+   */
+  readonly metrics?: Metrics;
+}
+
+/** Configuration after defaults are filled and a unified resolver is built. */
+export interface ResolvedConfig {
+  /** Look up a resource: static map first, then the dynamic resolver. */
+  readonly resolve: (
+    resource: string,
+    rels: readonly string[],
+  ) => Promise<ResourceRecord | undefined>;
+  readonly logger: Logger;
+  readonly metrics: Metrics;
+}
+
+/**
+ * Validate and normalise a {@link WebfingerConfig}. Fails loudly when neither a
+ * resource map nor a resolver is configured — a WebFinger endpoint that controls
+ * no resources is always a misconfiguration, not a silent "everything is a 404".
+ * Returns a single `resolve` that consults the static map first (an O(1) exact
+ * match) and then the dynamic resolver.
+ */
+export function resolveConfig(config: WebfingerConfig): ResolvedConfig {
+  if (config.resources === undefined && config.resolve === undefined) {
+    throw new Error(
+      "@dwk/webfinger: configure `resources` and/or `resolve` — a WebFinger " +
+        "endpoint must control at least one resource source.",
+    );
+  }
+
+  // Key the static map by the normalized resource URI so matching is
+  // case-insensitive on scheme/host (RFC 7033 §4.1). When two configured keys
+  // normalize to the same value, the later entry wins.
+  const normalizedMap =
+    config.resources === undefined
+      ? undefined
+      : new Map(
+          Object.entries(config.resources).map(([key, record]) => [
+            normalizeResource(key),
+            record,
+          ]),
+        );
+  const dynamicResolve = config.resolve;
+
+  const resolve = async (
+    resource: string,
+    rels: readonly string[],
+  ): Promise<ResourceRecord | undefined> => {
+    const key = normalizeResource(resource);
+    if (normalizedMap !== undefined) {
+      const record = normalizedMap.get(key);
+      if (record !== undefined) {
+        return record;
+      }
+    }
+    if (dynamicResolve !== undefined) {
+      return await dynamicResolve(key, rels);
+    }
+    return undefined;
+  };
+
+  return {
+    resolve,
+    logger: config.logger ?? noopLogger,
+    metrics: config.metrics ?? noopMetrics,
+  };
+}

package/src/handler.ts

@@ -0,0 +1,183 @@
+/**
+ * The WebFinger fetch handler (RFC 7033): a stateless `GET` endpoint, mountable
+ * at `/.well-known/webfinger`, that dispatches on the `resource` query parameter,
+ * returns the matching JRD (`rel`-filtered), and otherwise distinguishes a
+ * missing or malformed parameter (`400`) from an uncontrolled resource (`404`).
+ * Discovery data is public, so every response carries permissive CORS (§10.2).
+ */
+
+import { hostFromUrl, type LogFields } from "@dwk/log";
+
+import {
+  resolveConfig,
+  type ResolvedConfig,
+  type WebfingerConfig,
+} from "./config";
+import { buildJrd } from "./jrd";
+import { WebfingerLogEvent } from "./log";
+import { isWellFormedResource } from "./resource";
+
+/**
+ * Cloudflare bindings required by the WebFinger handler: **none**. The resource
+ * mapping is config-supplied (composition contract), so this fragment is empty
+ * and contributes nothing to the composed Worker's `Env`.
+ */
+export type WebfingerEnv = Record<never, never>;
+
+/** A `fetch`-compatible Worker handler. */
+export type WebfingerHandler = (
+  request: Request,
+  env: WebfingerEnv,
+  ctx: ExecutionContext,
+) => Promise<Response>;
+
+/** Media type for a JSON Resource Descriptor (RFC 7033 §10.2). */
+const JRD_CONTENT_TYPE = "application/jrd+json; charset=utf-8";
+const TEXT_CONTENT_TYPE = "text/plain; charset=utf-8";
+
+/**
+ * WebFinger serves public discovery data to any origin, so every response —
+ * success or error — advertises permissive CORS per RFC 7033 §10.2.
+ */
+const CORS_HEADERS: Readonly<Record<string, string>> = {
+  "access-control-allow-origin": "*",
+};
+
+/**
+ * Reduce a queried `resource` to its host for logging: the domain of an
+ * `acct:`/`mailto:` handle, or the host of an `https:`/`http:` URI. The local
+ * part (the user identifier) is deliberately dropped — only the domain is
+ * recorded (see `log.ts`).
+ */
+function resourceHost(resource: string): string | undefined {
+  if (/^(acct|mailto):/i.test(resource)) {
+    const at = resource.lastIndexOf("@");
+    if (at !== -1) {
+      const host = resource.slice(at + 1).toLowerCase();
+      return host.length > 0 ? host : undefined;
+    }
+    return undefined;
+  }
+  return hostFromUrl(resource);
+}
+
+/**
+ * Emit a structured event on both the logger and the metrics seam, which share
+ * one event vocabulary (see `@dwk/log`): `warn` for rejections, `info` for a
+ * resolved lookup. Callers pass only sanitized hosts, reason codes, and counts.
+ */
+function emit(
+  config: ResolvedConfig,
+  level: "info" | "warn",
+  event: string,
+  fields?: LogFields,
+): void {
+  config.logger[level](event, fields);
+  config.metrics.count(event, fields);
+}
+
+function jrdResponse(body: string, method: string): Response {
+  return new Response(method === "HEAD" ? null : body, {
+    status: 200,
+    headers: { "content-type": JRD_CONTENT_TYPE, ...CORS_HEADERS },
+  });
+}
+
+function errorResponse(
+  status: number,
+  message: string,
+  extraHeaders?: Readonly<Record<string, string>>,
+): Response {
+  return new Response(message, {
+    status,
+    headers: {
+      "content-type": TEXT_CONTENT_TYPE,
+      ...CORS_HEADERS,
+      ...extraHeaders,
+    },
+  });
+}
+
+/**
+ * Build the WebFinger handler from configuration.
+ *
+ * The returned handler is mountable at `/.well-known/webfinger`. It accepts
+ * `GET` (and `HEAD`): a request with no `resource` parameter — or a malformed
+ * one (no scheme / unparseable URI, RFC 7033 §4.2) — gets `400`; a `resource`
+ * this server does not control gets `404`; a match gets `200` with an
+ * `application/jrd+json` body whose `subject` echoes the queried URI, filtered by
+ * any `rel` parameters. `OPTIONS` returns a CORS preflight; other methods get
+ * `405`. Fails loudly at construction if no resource source is configured.
+ */
+export function createWebfinger(config: WebfingerConfig): WebfingerHandler {
+  const resolved = resolveConfig(config);
+
+  return async (request, _env, _ctx) => {
+    const method = request.method;
+
+    if (method === "OPTIONS") {
+      return new Response(null, {
+        status: 204,
+        headers: {
+          ...CORS_HEADERS,
+          "access-control-allow-methods": "GET, HEAD, OPTIONS",
+          "access-control-allow-headers": "*",
+        },
+      });
+    }
+
+    if (method !== "GET" && method !== "HEAD") {
+      emit(resolved, "warn", WebfingerLogEvent.Rejected, {
+        reason: "method_not_allowed",
+      });
+      return errorResponse(405, "method_not_allowed: use GET", {
+        allow: "GET, HEAD, OPTIONS",
+      });
+    }
+
+    const url = new URL(request.url);
+    const resource = url.searchParams.get("resource");
+
+    if (resource === null || resource.length === 0) {
+      emit(resolved, "warn", WebfingerLogEvent.Rejected, {
+        reason: "missing_resource",
+      });
+      return errorResponse(
+        400,
+        "missing_resource: the `resource` query parameter is required",
+      );
+    }
+
+    if (!isWellFormedResource(resource)) {
+      emit(resolved, "warn", WebfingerLogEvent.Rejected, {
+        reason: "malformed_resource",
+        resourceHost: resourceHost(resource),
+      });
+      return errorResponse(
+        400,
+        "malformed_resource: the `resource` query parameter is not a valid URI",
+      );
+    }
+
+    const rels = url.searchParams.getAll("rel").filter((rel) => rel.length > 0);
+
+    const record = await resolved.resolve(resource, rels);
+    if (record === undefined) {
+      emit(resolved, "warn", WebfingerLogEvent.Rejected, {
+        reason: "not_found",
+        resourceHost: resourceHost(resource),
+      });
+      return errorResponse(
+        404,
+        "not_found: no descriptor for the requested resource",
+      );
+    }
+
+    const jrd = buildJrd(resource, record, rels);
+    emit(resolved, "info", WebfingerLogEvent.Resolved, {
+      resourceHost: resourceHost(resource),
+      relCount: rels.length,
+    });
+    return jrdResponse(JSON.stringify(jrd), method);
+  };
+}

package/src/index.ts

@@ -0,0 +1,44 @@
+/**
+ * `@dwk/webfinger` — WebFinger (RFC 7033) account/resource discovery endpoint.
+ *
+ * Endpoint package: exports a factory returning a `fetch`-compatible handler,
+ * mountable at `/.well-known/webfinger` so it composes with other `@dwk`
+ * packages in one Worker. It maps a queried `resource` URI (`acct:`, `mailto:`,
+ * `https:`) to a JSON Resource Descriptor (JRD) of links — avatar, profile page,
+ * OIDC issuer, the `self` ActivityPub actor — and is the foundational discovery
+ * step for federation.
+ *
+ * It exists because WebFinger is **borderline static**: a static host can emit a
+ * single JRD, but only request logic can dispatch on `resource` (404 for a URI
+ * this server does not control), echo the matched `subject`, and filter `links`
+ * by `rel`. The package is pure and stateless — the `resource → JRD` mapping is
+ * supplied by config (a static map and/or a resolver), never read from the
+ * global environment — so it ships no Durable Object and needs no bindings, and
+ * the discovery logic unit-tests under Node without a Workers runtime.
+ *
+ * @see spec/packages/webfinger.md
+ * @packageDocumentation
+ */
+
+export { createWebfinger } from "./handler";
+export type { WebfingerEnv, WebfingerHandler } from "./handler";
+
+export {
+  resolveConfig,
+  type WebfingerConfig,
+  type ResourceResolver,
+  type ResolvedConfig,
+} from "./config";
+
+export {
+  filterLinksByRel,
+  buildJrd,
+  type Jrd,
+  type Link,
+  type ResourceRecord,
+} from "./jrd";
+
+export { normalizeResource, isWellFormedResource } from "./resource";
+
+export { WebfingerLogEvent } from "./log";
+export type { Logger, Metrics } from "@dwk/log";

package/src/jrd.ts

@@ -0,0 +1,104 @@
+/**
+ * JSON Resource Descriptor (JRD) data model and the pure `rel`-filtering rule
+ * from RFC 7033 §4.3. These types are plain data — no Workers runtime, no
+ * Cloudflare bindings — so the discovery logic unit-tests in isolation. The
+ * handler in `handler.ts` turns an HTTP request into a `resource` lookup and
+ * renders the resulting {@link Jrd} as `application/jrd+json`.
+ */
+
+/**
+ * A single link relation in a JRD (RFC 7033 §4.4.4). `rel` is required; the
+ * remaining members are optional and emitted only when present. Either `href`
+ * (a concrete target) or `template` (a URI template) typically carries the
+ * link's value.
+ */
+export interface Link {
+  /** The link relation type — a registered name or an absolute URI. */
+  readonly rel: string;
+  /** Media type of the target resource, when known. */
+  readonly type?: string;
+  /** The target URI. */
+  readonly href?: string;
+  /** Human-readable titles keyed by language tag (or `"und"`). */
+  readonly titles?: Readonly<Record<string, string>>;
+  /** Additional, scheme-defined properties; a `null` value means "absent". */
+  readonly properties?: Readonly<Record<string, string | null>>;
+  /** A URI template, used in place of `href` for parameterised links. */
+  readonly template?: string;
+}
+
+/**
+ * What the configured resource map (or {@link ResourceResolver}) yields for a
+ * controlled resource. `subject` is optional here: the handler defaults it to
+ * the queried `resource` URI (which is what Mastodon/fediverse clients require),
+ * so a record normally lists only its `aliases`, `properties`, and `links`.
+ */
+export interface ResourceRecord {
+  /** Overrides the echoed subject; defaults to the queried `resource` URI. */
+  readonly subject?: string;
+  /** Other URIs that identify the same entity (RFC 7033 §4.4.2). */
+  readonly aliases?: readonly string[];
+  /** Subject-level properties; a `null` value means "absent". */
+  readonly properties?: Readonly<Record<string, string | null>>;
+  /** The link relations advertised for this resource. */
+  readonly links?: readonly Link[];
+}
+
+/**
+ * A fully-rendered JRD as serialised in a `200` response. `subject` and `links`
+ * are always present (`links` may be an empty array after `rel` filtering);
+ * `aliases` and `properties` appear only when the record supplied them.
+ */
+export interface Jrd {
+  /** The subject URI — equals the queried `resource` unless the record overrode it. */
+  readonly subject: string;
+  /** Other URIs identifying the subject. */
+  readonly aliases?: readonly string[];
+  /** Subject-level properties. */
+  readonly properties?: Readonly<Record<string, string | null>>;
+  /** The (possibly `rel`-filtered) link set. */
+  readonly links: readonly Link[];
+}
+
+/**
+ * Apply the RFC 7033 §4.3 `rel` filter: with no `rel` parameters the full link
+ * set is returned; otherwise only links whose `rel` exactly matches one of the
+ * requested relations survive. `rel` filtering never touches `aliases` or
+ * subject `properties` — it scopes the `links` array only.
+ */
+export function filterLinksByRel(
+  links: readonly Link[],
+  rels: readonly string[],
+): readonly Link[] {
+  if (rels.length === 0) return links;
+  return links.filter((link) => rels.includes(link.rel));
+}
+
+/**
+ * Render the final {@link Jrd} for a matched resource: echo the queried
+ * `resource` as the subject (unless the record overrides it), apply the `rel`
+ * filter to the links, and carry through `aliases`/`properties` only when the
+ * record actually supplied them (so the JSON stays minimal).
+ */
+export function buildJrd(
+  resource: string,
+  record: ResourceRecord,
+  rels: readonly string[],
+): Jrd {
+  const jrd: {
+    subject: string;
+    aliases?: readonly string[];
+    properties?: Readonly<Record<string, string | null>>;
+    links: readonly Link[];
+  } = {
+    subject: record.subject ?? resource,
+    links: filterLinksByRel(record.links ?? [], rels),
+  };
+  if (record.aliases && record.aliases.length > 0) {
+    jrd.aliases = record.aliases;
+  }
+  if (record.properties && Object.keys(record.properties).length > 0) {
+    jrd.properties = record.properties;
+  }
+  return jrd;
+}