@dwk/webfinger 0.1.0-beta.0

package/src/log.ts

@@ -0,0 +1,38 @@
+/**
+ * `@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",
+} as const;
+
+/** Union of the event-name string literals in {@link WebfingerLogEvent}. */
+export type WebfingerLogEvent =
+  (typeof WebfingerLogEvent)[keyof typeof WebfingerLogEvent];

package/src/resource.ts

@@ -0,0 +1,82 @@
+/**
+ * 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: string): string {
+  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: string): boolean {
+  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;
+}