Split mod.tsx into log-store, auth, and routes modules

The ~700-line mod.tsx was doing too many things: log storage, auth
helpers, route definitions, and the public createFederationDebugger API.
Extract cohesive units into their own modules:

 -  log-store.ts: LogStore class, SerializedLogRecord, createLogSink
 -  auth.ts: FederationDebuggerAuth type, session/HMAC helpers, checkAuth
 -  routes.tsx: createDebugApp (Hono route tree with auth middleware)

mod.tsx is now the public entry point that wires the pieces together and
re-exports the public types.

Addresses: #564 (comment)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: dahlia

packages/debugger/src/auth.ts

@@ -0,0 +1,142 @@
+/**
+ * Authentication types and helpers for the debug dashboard.
+ *
+ * @module
+ */
+import { timingSafeEqual } from "node:crypto";
+
+/**
+ * Authentication configuration for the debug dashboard.
+ *
+ * The debug dashboard can be protected using one of three authentication modes:
+ *
+ * - `"password"` — Shows a password-only login form.
+ * - `"usernamePassword"` — Shows a username + password login form.
+ * - `"request"` — Authenticates based on the incoming request (e.g., IP
+ *   address).  No login form is shown; unauthenticated requests receive a
+ *   403 response.
+ *
+ * Each mode supports either a static credential check or a callback function.
+ */
+export type FederationDebuggerAuth =
+  | {
+    readonly type: "password";
+    authenticate(password: string): boolean | Promise<boolean>;
+  }
+  | {
+    readonly type: "password";
+    readonly password: string;
+  }
+  | {
+    readonly type: "usernamePassword";
+    authenticate(
+      username: string,
+      password: string,
+    ): boolean | Promise<boolean>;
+  }
+  | {
+    readonly type: "usernamePassword";
+    readonly username: string;
+    readonly password: string;
+  }
+  | {
+    readonly type: "request";
+    authenticate(request: Request): boolean | Promise<boolean>;
+  };
+
+export const SESSION_COOKIE_NAME = "__fedify_debug_session";
+const SESSION_TOKEN = "authenticated";
+
+export async function generateHmacKey(): Promise<CryptoKey> {
+  return await crypto.subtle.generateKey(
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign", "verify"],
+  );
+}
+
+function toHex(buffer: ArrayBuffer): string {
+  return [...new Uint8Array(buffer)]
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+function fromHex(hex: string): ArrayBuffer {
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < hex.length; i += 2) {
+    bytes[i / 2] = parseInt(hex.substring(i, i + 2), 16);
+  }
+  return bytes.buffer as ArrayBuffer;
+}
+
+export async function signSession(key: CryptoKey): Promise<string> {
+  const encoder = new TextEncoder();
+  const signature = await crypto.subtle.sign(
+    "HMAC",
+    key,
+    encoder.encode(SESSION_TOKEN),
+  );
+  return toHex(signature);
+}
+
+export async function verifySession(
+  key: CryptoKey,
+  signature: string,
+): Promise<boolean> {
+  try {
+    const encoder = new TextEncoder();
+    return await crypto.subtle.verify(
+      "HMAC",
+      key,
+      fromHex(signature),
+      encoder.encode(SESSION_TOKEN),
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Constant-time string comparison to prevent timing attacks on credential
+ * checks.  Uses {@link timingSafeEqual} from `node:crypto` under the hood.
+ */
+function constantTimeEqual(a: string, b: string): boolean {
+  const encoder = new TextEncoder();
+  const bufA = encoder.encode(a);
+  const bufB = encoder.encode(b);
+  if (bufA.byteLength !== bufB.byteLength) {
+    // Still compare to burn the same amount of time regardless, but
+    // the result is always false when lengths differ.
+    timingSafeEqual(bufA, new Uint8Array(bufA.byteLength));
+    return false;
+  }
+  return timingSafeEqual(bufA, bufB);
+}
+
+export async function checkAuth(
+  auth: FederationDebuggerAuth,
+  formData: { username?: string; password: string },
+): Promise<boolean> {
+  if (auth.type === "password") {
+    if ("authenticate" in auth) {
+      return await auth.authenticate(formData.password);
+    }
+    return constantTimeEqual(formData.password, auth.password);
+  }
+  if (auth.type === "usernamePassword") {
+    if ("authenticate" in auth) {
+      return await auth.authenticate(
+        formData.username ?? "",
+        formData.password,
+      );
+    }
+    // Check both fields in constant time (don't short-circuit)
+    const usernameMatch = constantTimeEqual(
+      formData.username ?? "",
+      auth.username,
+    );
+    const passwordMatch = constantTimeEqual(formData.password, auth.password);
+    return usernameMatch && passwordMatch;
+  }
+  return false;
+}

packages/debugger/src/log-store.ts

@@ -0,0 +1,127 @@
+/**
+ * Log record storage for the debug dashboard, backed by a {@link KvStore}.
+ *
+ * @module
+ */
+import type { KvKey, KvStore } from "@fedify/fedify/federation";
+import type { LogRecord, Sink } from "@logtape/logtape";
+
+/**
+ * A serialized log record for the debug dashboard.
+ */
+export interface SerializedLogRecord {
+  /**
+   * The logger category.
+   */
+  readonly category: readonly string[];
+
+  /**
+   * The log level.
+   */
+  readonly level: string;
+
+  /**
+   * The rendered log message.
+   */
+  readonly message: string;
+
+  /**
+   * The timestamp in milliseconds since the Unix epoch.
+   */
+  readonly timestamp: number;
+
+  /**
+   * The extra properties of the log record (excluding traceId and spanId).
+   */
+  readonly properties: Record<string, unknown>;
+}
+
+/**
+ * Persistent storage for log records grouped by trace ID, backed by a
+ * {@link KvStore}.  When the same `KvStore` is shared across web and worker
+ * processes the dashboard can display logs produced by background tasks.
+ */
+export class LogStore {
+  readonly #kv: KvStore;
+  readonly #keyPrefix: KvKey;
+  /** Chain of pending write promises for flush(). */
+  #pending: Promise<void> = Promise.resolve();
+
+  constructor(kv: KvStore, keyPrefix: KvKey = ["fedify", "debugger", "logs"]) {
+    this.#kv = kv;
+    this.#keyPrefix = keyPrefix;
+  }
+
+  /**
+   * Enqueue a log record for writing.  The write happens asynchronously;
+   * call {@link flush} to wait for all pending writes to complete.
+   *
+   * Keys use a timestamp + random suffix so that entries sort
+   * chronologically and never collide, even across multiple processes
+   * sharing the same {@link KvStore}.
+   */
+  add(traceId: string, record: SerializedLogRecord): void {
+    const key: KvKey = [
+      ...this.#keyPrefix,
+      traceId,
+      `${Date.now().toString(36).padStart(10, "0")}-${
+        Math.random().toString(36).slice(2)
+      }`,
+    ] as unknown as KvKey;
+    // Errors are swallowed so a single failed write cannot poison the
+    // chain or cause an unhandled rejection — logging is best-effort.
+    this.#pending = this.#pending.then(
+      () => this.#kv.set(key, record),
+    ).catch(() => {});
+  }
+
+  /** Wait for all pending writes to complete. */
+  flush(): Promise<void> {
+    return this.#pending;
+  }
+
+  async get(traceId: string): Promise<readonly SerializedLogRecord[]> {
+    const prefix: KvKey = [...this.#keyPrefix, traceId] as unknown as KvKey;
+    const logs: SerializedLogRecord[] = [];
+    for await (const entry of this.#kv.list(prefix)) {
+      logs.push(entry.value as SerializedLogRecord);
+    }
+    return logs;
+  }
+}
+
+/**
+ * Converts a {@link LogRecord} into a plain serializable object suitable
+ * for storage in a {@link KvStore}.
+ */
+export function serializeLogRecord(record: LogRecord): SerializedLogRecord {
+  // Render message to string
+  const messageParts: string[] = [];
+  for (const part of record.message) {
+    if (typeof part === "string") messageParts.push(part);
+    else if (part == null) messageParts.push("");
+    else messageParts.push(String(part));
+  }
+  // Exclude traceId and spanId from properties
+  const { traceId: _t, spanId: _s, ...properties } = record.properties;
+  return {
+    category: record.category,
+    level: record.level,
+    message: messageParts.join(""),
+    timestamp: record.timestamp,
+    properties,
+  };
+}
+
+/**
+ * Creates a LogTape {@link Sink} that writes log records into the given
+ * {@link LogStore}, grouped by their `traceId` property.  Records without
+ * a `traceId` are silently discarded.
+ */
+export function createLogSink(store: LogStore): Sink {
+  return (record: LogRecord): void => {
+    const traceId = record.properties.traceId;
+    if (typeof traceId !== "string" || traceId.length === 0) return;
+    store.add(traceId, serializeLogRecord(record));
+  };
+}