@data-club/ai-hub-server 0.0.1

package/src/routes/metrics.ts

@@ -0,0 +1,111 @@
+/**
+ * `GET /metrics` — Prometheus-text endpoint with a bearer-token gate.
+ *
+ * Unlike every other protected endpoint, `/metrics` does **not** speak the JWT
+ * + role pipeline: Prometheus / Alloy scrapers don't speak our login flow.
+ * Instead, the request must carry `Authorization: Bearer <token>` whose value
+ * **constant-time-matches** `admin_setting.metrics_scrape_token` (§6.10).
+ *
+ * Series exposed (Step 4 — these start at 0 and become live in Steps 5/6):
+ *
+ * - `chat_requests_total` — counter, total `/chat` requests received.
+ * - `tpm_recovery_attempts_total` — counter, TPM recovery attempts started.
+ * - `tpm_exhausted_total` — counter, TPM recovery exhausted (turn → failed).
+ * - `chat_duration_ms` — histogram-like (rendered as a Gauge in v1; Step 6
+ *   may upgrade to a proper Prometheus histogram).
+ * - `letta_request_duration_ms` — same shape as above for Letta calls.
+ *
+ * Step 4 ships the auth gate + the series scaffolding with all counters at
+ * zero; Steps 5 + 6 wire them up as the chat path is implemented.
+ *
+ * @see SPECIFICATIONS.md §6.10 — observability / metrics token
+ * @see SPECIFICATIONS.md §6.3.5 — /metrics in the API surface
+ */
+
+import { timingSafeEqual } from "node:crypto";
+
+import { eq } from "drizzle-orm";
+
+import { adminSetting } from "../db/schema.js";
+import { unauthorized } from "../handlers/responses.js";
+import type { RouteHandler } from "../handlers/types.js";
+import { renderMetrics } from "../observability/metrics.js";
+
+/**
+ * Constant-time-compares the supplied bearer token against the stored
+ * scrape token. Returns `false` for any malformed input (no length leak).
+ *
+ * @param supplied - the bearer token from the request header.
+ * @param stored - the token from `admin_setting.metrics_scrape_token`.
+ * @returns `true` if the tokens match.
+ */
+function tokensEqual(supplied: string, stored: string): boolean {
+  // Buffers must be the same length for timingSafeEqual. Pad the shorter one
+  // and compare lengths separately so we still don't reveal "supplied was
+  // shorter" via timing.
+  const a = Buffer.from(supplied, "utf8");
+  const b = Buffer.from(stored, "utf8");
+  if (a.length !== b.length) {
+    // Burn an equal-length compare so the timing of the rejection doesn't
+    // distinguish "wrong length" from "wrong value."
+    const dummy = Buffer.alloc(b.length, 0);
+    try {
+      timingSafeEqual(dummy, b);
+    } catch {
+      /* ignored */
+    }
+    return false;
+  }
+  return timingSafeEqual(a, b);
+}
+
+/**
+ * Extracts the bearer token from the `Authorization` header value.
+ *
+ * @param value - the raw header value (or `null`).
+ * @returns the token or `null`.
+ */
+function extractBearer(value: string | null): string | null {
+  if (!value) return null;
+  const m = value.match(/^Bearer\s+(.+)$/i);
+  if (!m) return null;
+  const token = m[1]?.trim() ?? "";
+  return token.length > 0 ? token : null;
+}
+
+/**
+ * `GET /metrics` — bearer-token-gated Prometheus exposition.
+ *
+ * Not behind `protectedRoute` — the auth is the bearer token, not the JWT
+ * pipeline. Returns 401 on missing / wrong token (with the same generic
+ * `unauthorized` envelope as the JWT paths, no scope leakage).
+ *
+ * @see SPECIFICATIONS.md §6.10
+ */
+export const handleMetrics: RouteHandler = async (req, ctx) => {
+  const supplied = extractBearer(req.headers.get("authorization"));
+  if (!supplied) return unauthorized();
+
+  const settings = ctx.db
+    .select({ token: adminSetting.metricsScrapeToken })
+    .from(adminSetting)
+    .where(eq(adminSetting.id, 1))
+    .get();
+  const stored = settings?.token;
+  if (!stored || !tokensEqual(supplied, stored)) {
+    return unauthorized();
+  }
+
+  // Step 5 wires `chat_requests_total`, `chat_duration_ms`, and
+  // `letta_request_duration_ms` to live values. Step 6 fills in the
+  // TPM-recovery counters. The registry lives in
+  // `observability/metrics.ts`.
+  const body = renderMetrics();
+
+  return new Response(body, {
+    status: 200,
+    headers: {
+      "Content-Type": "text/plain; version=0.0.4; charset=utf-8",
+    },
+  });
+};