@obsunified/collector 2.0.1 → 2.2.0

package/src/auth/dashboard-auth.ts

@@ -1,7 +1,13 @@
-import type { MiddlewareHandler } from "hono";
+import type { Context, MiddlewareHandler } from "hono";
 import type { CollectorEnv } from "../framework/env";
 import { ProjectsStore } from "../lib/projects-store";
 import { type SqlDb, sqlDbFor } from "../lib/sql-db";
+import {
+	LoginRateLimiter,
+	type LoginRateLimitOptions,
+	loginClientKey,
+	UNKEYED_LOGIN_CLIENT_WARNING,
+} from "./login-rate-limit";
 
 const SESSION_COOKIE = "obs_session";
 const SESSION_MAX_AGE = 7 * 24 * 60 * 60; // 7 days in seconds
@@ -104,17 +110,47 @@ function getCookie(
 	return match ? decodeURIComponent(match[1]) : undefined;
 }
 
+export interface DashboardAuthConfig {
+	password?: string;
+	token?: string;
+	/**
+	 * Failed-login limiter for POST /auth/login (see login-rate-limit.ts).
+	 * Pass `false` to disable; defaults to 10 failures per 15 minutes.
+	 * `clientAddress` lets the host supply the connection's peer address;
+	 * `trustProxyHeaders` honours forwarding headers from a trusted proxy.
+	 * Without either, Workers use the edge-set client IP and every other
+	 * runtime has no trustworthy identity: limiting is then skipped (never a
+	 * shared bucket, which would let one client lock everyone out) and a
+	 * warning is logged once via `warn` (default `console.warn`).
+	 */
+	loginRateLimit?:
+		| (LoginRateLimitOptions & {
+				clientAddress?: (
+					c: Context<{ Bindings: CollectorEnv }>,
+				) => string | undefined;
+				trustProxyHeaders?: boolean;
+				/** Sink for the one-time "limiter inactive" warning. */
+				warn?: (message: string) => void;
+		  })
+		| false;
+}
+
 /**
- * Creates auth routes and middleware for dashboard password login.
+ * Creates auth routes and middleware for dashboard password login and
+ * programmatic read/admin bearer token authentication.
  *
  * Routes added:
  *   POST /auth/login  — accepts { password }, sets session cookie
- *   GET  /auth/check  — returns { authenticated: true/false }
+ *   GET  /auth/check  — returns { authenticated: true/false } (supports cookie and Bearer token)
  *   POST /auth/logout — clears session cookie
  *
- * The returned middleware validates the session cookie on protected routes.
+ * The returned middleware validates either:
+ *   1. Authorization: Bearer <token> (programmatic read/admin token for MCP/API)
+ *   2. obs_session cookie (human dashboard user session)
+ *
+ * Ingest keys are rejected on dashboard/internal routes — they are write-only.
  */
-export function createDashboardAuth(config: { password: string }): {
+export function createDashboardAuth(config?: DashboardAuthConfig): {
 	middleware: MiddlewareHandler<{
 		Bindings: CollectorEnv;
 		Variables: { projectId: string };
@@ -127,45 +163,99 @@ export function createDashboardAuth(config: { password: string }): {
 		Bindings: CollectorEnv;
 		Variables: { projectId: string };
 	}> = async (c, next) => {
-		if (!config.password) {
+		const configuredPassword = config?.password ?? c.env.DASHBOARD_PASSWORD;
+		const configuredToken =
+			config?.token ??
+			c.env.DASHBOARD_TOKEN ??
+			(c.env as unknown as Record<string, string | undefined>)
+				.OBS_DASHBOARD_TOKEN;
+
+		if (!configuredPassword && !configuredToken) {
 			return c.json(
 				{
 					error:
-						"DASHBOARD_PASSWORD is not configured. Set the DASHBOARD_PASSWORD environment variable.",
+						"Neither DASHBOARD_PASSWORD nor DASHBOARD_TOKEN is configured. Set at least one environment variable.",
 				},
 				500,
 			);
 		}
 
-		const cookieHeader = c.req.header("Cookie");
-		const sessionValue = getCookie(cookieHeader, SESSION_COOKIE);
+		let authenticated = false;
 
-		if (!sessionValue) {
-			// For API requests, return 401. For page requests, redirect to login.
-			const accept = c.req.header("Accept") || "";
-			if (accept.includes("text/html")) {
-				return c.redirect("/dashboard/login");
+		const authHeader = c.req.header("Authorization");
+		if (authHeader) {
+			const match = authHeader.match(/^Bearer\s+(.+)$/i);
+			if (!match) {
+				return c.json({ error: "Unauthorized" }, 401);
+			}
+			const bearerToken = match[1].trim();
+			if (!bearerToken) {
+				return c.json({ error: "Unauthorized" }, 401);
 			}
-			return c.json({ error: "Unauthorized" }, 401);
-		}
 
-		// Session cookie format: payload.signature
-		const dotIndex = sessionValue.lastIndexOf(".");
-		if (dotIndex === -1) {
-			return c.json({ error: "Invalid session" }, 401);
-		}
+			// Ingest keys must never grant read/admin access to dashboard/internal endpoints.
+			const ingestKey = c.env.INGEST_KEY;
+			if (ingestKey && (await timingSafeEqualStr(bearerToken, ingestKey))) {
+				return c.json(
+					{
+						error:
+							"Unauthorized: ingest keys cannot be used for dashboard/internal access",
+					},
+					401,
+				);
+			}
+
+			// Fail closed if no programmatic read/admin token is configured.
+			if (!configuredToken) {
+				return c.json({ error: "Unauthorized" }, 401);
+			}
+
+			// Verify bearer token in constant time.
+			const valid = await timingSafeEqualStr(bearerToken, configuredToken);
+			if (!valid) {
+				return c.json({ error: "Unauthorized" }, 401);
+			}
+
+			authenticated = true;
+		} else {
+			// Check session cookie for browser dashboard users.
+			const cookieHeader = c.req.header("Cookie");
+			const sessionValue = getCookie(cookieHeader, SESSION_COOKIE);
 
-		const payload = sessionValue.substring(0, dotIndex);
-		const sig = sessionValue.substring(dotIndex + 1);
+			if (sessionValue) {
+				if (!configuredPassword) {
+					return c.json({ error: "Unauthorized" }, 401);
+				}
 
-		const valid = await verify(payload, sig, config.password);
-		if (!valid) {
-			return c.json({ error: "Invalid session" }, 401);
+				const dotIndex = sessionValue.lastIndexOf(".");
+				if (dotIndex === -1) {
+					return c.json({ error: "Invalid session" }, 401);
+				}
+
+				const payload = sessionValue.substring(0, dotIndex);
+				const sig = sessionValue.substring(dotIndex + 1);
+
+				const valid = await verify(payload, sig, configuredPassword);
+				if (!valid) {
+					return c.json({ error: "Invalid session" }, 401);
+				}
+
+				const token = parseSessionToken(payload);
+				if (!token || token.exp < Math.floor(Date.now() / 1000)) {
+					return c.json({ error: "Session expired" }, 401);
+				}
+
+				authenticated = true;
+			}
 		}
 
-		const token = parseSessionToken(payload);
-		if (!token || token.exp < Math.floor(Date.now() / 1000)) {
-			return c.json({ error: "Session expired" }, 401);
+		if (!authenticated) {
+			// For API requests, return 401. For page requests, redirect to login.
+			const accept = c.req.header("Accept") || "";
+			if (accept.includes("text/html")) {
+				return c.redirect("/dashboard/login");
+			}
+			return c.json({ error: "Unauthorized" }, 401);
 		}
 
 		// Resolve project for data-scoped routes. /internal/projects/* is exempt
@@ -197,24 +287,59 @@ export function createDashboardAuth(config: { password: string }): {
 	const registerRoutes = (
 		app: import("hono").Hono<{ Bindings: CollectorEnv }>,
 	) => {
+		const limiter =
+			config?.loginRateLimit === false
+				? null
+				: new LoginRateLimiter(config?.loginRateLimit ?? {});
+		let warnedUnkeyedClient = false;
+
 		app.post("/auth/login", async (c) => {
-			if (!config.password) {
+			const configuredPassword = config?.password ?? c.env.DASHBOARD_PASSWORD;
+			if (!configuredPassword) {
 				return c.json({ error: "Dashboard password not configured" }, 500);
 			}
 
-			const body = await c.req
-				.json<{ password?: string }>()
-				.catch(() => ({ password: undefined }));
+			const limitConfig = config?.loginRateLimit || undefined;
+			const clientKey = limiter
+				? loginClientKey(c.req.raw.headers, {
+						clientAddress: limitConfig?.clientAddress?.(c),
+						trustProxyHeaders: limitConfig?.trustProxyHeaders,
+					})
+				: null;
+			if (limiter && clientKey === null && !warnedUnkeyedClient) {
+				warnedUnkeyedClient = true;
+				(limitConfig?.warn ?? console.warn)(UNKEYED_LOGIN_CLIENT_WARNING);
+			}
+			const verdict = clientKey === null ? null : limiter?.check(clientKey);
+			if (verdict && !verdict.allowed) {
+				c.header("Retry-After", String(verdict.retryAfterSeconds));
+				return c.json({ error: "Too many failed login attempts" }, 429);
+			}
+
+			let body: { password?: string } | null = null;
+			try {
+				body = await c.req.json<{ password?: string }>();
+			} catch (err) {
+				// The framework's body cap (hono/body-limit) surfaces an oversized
+				// streamed body as an error from the read; let it propagate so the
+				// middleware answers 413 instead of this handler calling it a bad
+				// password. Anything else is malformed JSON → 401 below.
+				if (err instanceof Error && err.name === "BodyLimitError") throw err;
+				body = null;
+			}
 			if (
-				!body.password ||
-				!(await timingSafeEqualStr(body.password, config.password))
+				!body?.password ||
+				typeof body.password !== "string" ||
+				!(await timingSafeEqualStr(body.password, configuredPassword))
 			) {
+				if (clientKey !== null) limiter?.recordFailure(clientKey);
 				return c.json({ error: "Invalid password" }, 401);
 			}
+			if (clientKey !== null) limiter?.reset(clientKey);
 
 			const expiresAt = Math.floor(Date.now() / 1000) + SESSION_MAX_AGE;
 			const payload = createSessionToken(expiresAt);
-			const sig = await sign(payload, config.password);
+			const sig = await sign(payload, configuredPassword);
 			const cookieValue = `${payload}.${sig}`;
 
 			const isSecure = c.req.url.startsWith("https:");
@@ -227,10 +352,34 @@ export function createDashboardAuth(config: { password: string }): {
 		});
 
 		app.get("/auth/check", async (c) => {
+			const configuredPassword = config?.password ?? c.env.DASHBOARD_PASSWORD;
+			const configuredToken =
+				config?.token ??
+				c.env.DASHBOARD_TOKEN ??
+				(c.env as unknown as Record<string, string | undefined>)
+					.OBS_DASHBOARD_TOKEN;
+
+			const authHeader = c.req.header("Authorization");
+			if (authHeader) {
+				const match = authHeader.match(/^Bearer\s+(.+)$/i);
+				if (match && configuredToken) {
+					const bearerToken = match[1].trim();
+					const ingestKey = c.env.INGEST_KEY;
+					if (ingestKey && (await timingSafeEqualStr(bearerToken, ingestKey))) {
+						return c.json({ authenticated: false });
+					}
+					const valid = await timingSafeEqualStr(bearerToken, configuredToken);
+					if (valid) {
+						return c.json({ authenticated: true });
+					}
+				}
+				return c.json({ authenticated: false });
+			}
+
 			const cookieHeader = c.req.header("Cookie");
 			const sessionValue = getCookie(cookieHeader, SESSION_COOKIE);
 
-			if (!sessionValue) {
+			if (!sessionValue || !configuredPassword) {
 				return c.json({ authenticated: false });
 			}
 
@@ -242,7 +391,7 @@ export function createDashboardAuth(config: { password: string }): {
 			const payload = sessionValue.substring(0, dotIndex);
 			const sig = sessionValue.substring(dotIndex + 1);
 
-			const valid = await verify(payload, sig, config.password);
+			const valid = await verify(payload, sig, configuredPassword);
 			if (!valid) {
 				return c.json({ authenticated: false });
 			}

package/src/auth/login-rate-limit.test.ts

@@ -0,0 +1,129 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { LoginRateLimiter, loginClientKey } from "./login-rate-limit";
+
+describe("LoginRateLimiter", () => {
+	it("blocks after the failure budget and recovers when the window ends", () => {
+		let now = 1_000_000;
+		const limiter = new LoginRateLimiter({
+			maxFailures: 3,
+			windowMs: 60_000,
+			now: () => now,
+		});
+		for (let i = 0; i < 3; i += 1) {
+			expect(limiter.check("1.2.3.4").allowed).toBe(true);
+			limiter.recordFailure("1.2.3.4");
+		}
+		const blocked = limiter.check("1.2.3.4");
+		expect(blocked.allowed).toBe(false);
+		expect(blocked.retryAfterSeconds).toBe(60);
+		// Other clients are unaffected.
+		expect(limiter.check("5.6.7.8").allowed).toBe(true);
+		now += 60_000;
+		expect(limiter.check("1.2.3.4").allowed).toBe(true);
+	});
+
+	it("a successful login clears the client's failures", () => {
+		const limiter = new LoginRateLimiter({ maxFailures: 2 });
+		limiter.recordFailure("k");
+		limiter.reset("k");
+		limiter.recordFailure("k");
+		expect(limiter.check("k").allowed).toBe(true);
+	});
+
+	it("evicts the oldest client past the tracking cap", () => {
+		const limiter = new LoginRateLimiter({ maxFailures: 1, maxClients: 2 });
+		limiter.recordFailure("a");
+		limiter.recordFailure("b");
+		limiter.recordFailure("c");
+		expect(limiter.check("a").allowed).toBe(true);
+		expect(limiter.check("c").allowed).toBe(false);
+	});
+
+	describe("loginClientKey", () => {
+		const headers = (init: Record<string, string>) => new Headers(init);
+		const spoofed = headers({
+			"cf-connecting-ip": "9.9.9.9",
+			"x-forwarded-for": "8.8.8.8, 10.0.0.1",
+		});
+
+		afterEach(() => {
+			vi.unstubAllGlobals();
+		});
+
+		it("keys on the connection peer and ignores spoofed headers by default", () => {
+			expect(loginClientKey(spoofed, { clientAddress: "203.0.113.7" })).toBe(
+				"203.0.113.7",
+			);
+			expect(
+				loginClientKey(spoofed, {
+					clientAddress: "203.0.113.7",
+					trustProxyHeaders: false,
+				}),
+			).toBe("203.0.113.7");
+		});
+
+		it("prefers the trusted forwarded client over the proxy peer", () => {
+			// Behind a trusted proxy the peer is the proxy itself; the
+			// forwarded address is the real client.
+			expect(
+				loginClientKey(spoofed, {
+					clientAddress: "10.0.0.1",
+					trustProxyHeaders: true,
+				}),
+			).toBe("9.9.9.9");
+			expect(
+				loginClientKey(headers({ "x-forwarded-for": "8.8.8.8, 10.0.0.1" }), {
+					clientAddress: "10.0.0.1",
+					trustProxyHeaders: true,
+				}),
+			).toBe("8.8.8.8");
+			// Whitespace-only / empty header values do not count as forwarded.
+			expect(
+				loginClientKey(headers({ "x-forwarded-for": "  " }), {
+					clientAddress: "10.0.0.1",
+					trustProxyHeaders: true,
+				}),
+			).toBe("10.0.0.1");
+		});
+
+		it("falls back to the peer when a trusted proxy sent no headers", () => {
+			expect(
+				loginClientKey(headers({}), {
+					clientAddress: "10.0.0.1",
+					trustProxyHeaders: true,
+				}),
+			).toBe("10.0.0.1");
+			expect(
+				loginClientKey(headers({}), { trustProxyHeaders: true }),
+			).toBeNull();
+		});
+
+		it("ignores forwarding headers unless a trusted proxy is declared", () => {
+			// Direct client on Node: headers are attacker-chosen and there is no
+			// peer address → no key (never a shared bucket).
+			expect(loginClientKey(spoofed)).toBeNull();
+			expect(loginClientKey(headers({}))).toBeNull();
+			expect(loginClientKey(spoofed, { trustProxyHeaders: true })).toBe(
+				"9.9.9.9",
+			);
+			expect(
+				loginClientKey(headers({ "x-forwarded-for": "8.8.8.8, 10.0.0.1" }), {
+					trustProxyHeaders: true,
+				}),
+			).toBe("8.8.8.8");
+		});
+
+		it("trusts CF-Connecting-IP only on the Cloudflare Workers runtime", () => {
+			vi.stubGlobal("navigator", { userAgent: "Cloudflare-Workers" });
+			expect(loginClientKey(spoofed)).toBe("9.9.9.9");
+			expect(
+				loginClientKey(headers({ "x-forwarded-for": "8.8.8.8" })),
+			).toBeNull();
+			// A host-resolved peer still wins over the edge header on Workers
+			// unless the embedder opts into trusting proxy headers.
+			expect(loginClientKey(spoofed, { clientAddress: "203.0.113.7" })).toBe(
+				"203.0.113.7",
+			);
+		});
+	});
+});

package/src/auth/login-rate-limit.ts

@@ -0,0 +1,143 @@
+/**
+ * Fixed-window failure limiter for `POST /auth/login`. Only failed attempts
+ * count; a successful login clears the client's bucket. State is in-memory,
+ * so on Cloudflare Workers it is per isolate and on Node per process — it
+ * slows a single-origin brute force without any shared storage, and it can
+ * never lock an operator out for longer than one window.
+ */
+
+export interface LoginRateLimitOptions {
+	/** Failed attempts allowed per window before 429. Default 10. */
+	maxFailures?: number;
+	/** Window length in milliseconds. Default 15 minutes. */
+	windowMs?: number;
+	/** Upper bound on tracked clients; the oldest bucket is evicted past it. */
+	maxClients?: number;
+	/** Clock override for tests. */
+	now?: () => number;
+}
+
+export interface LoginRateLimitVerdict {
+	allowed: boolean;
+	retryAfterSeconds: number;
+}
+
+interface Bucket {
+	failures: number;
+	windowStartedAt: number;
+}
+
+export class LoginRateLimiter {
+	private readonly buckets = new Map<string, Bucket>();
+	private readonly maxFailures: number;
+	private readonly windowMs: number;
+	private readonly maxClients: number;
+	private readonly now: () => number;
+
+	constructor(options: LoginRateLimitOptions = {}) {
+		this.maxFailures = Math.max(1, options.maxFailures ?? 10);
+		this.windowMs = Math.max(1_000, options.windowMs ?? 15 * 60_000);
+		this.maxClients = Math.max(1, options.maxClients ?? 10_000);
+		this.now = options.now ?? Date.now;
+	}
+
+	check(key: string): LoginRateLimitVerdict {
+		const bucket = this.live(key);
+		if (!bucket || bucket.failures < this.maxFailures) {
+			return { allowed: true, retryAfterSeconds: 0 };
+		}
+		const remaining = bucket.windowStartedAt + this.windowMs - this.now();
+		return {
+			allowed: false,
+			retryAfterSeconds: Math.max(1, Math.ceil(remaining / 1000)),
+		};
+	}
+
+	recordFailure(key: string): void {
+		const bucket = this.live(key);
+		if (bucket) {
+			bucket.failures += 1;
+			return;
+		}
+		if (this.buckets.size >= this.maxClients) {
+			const oldest = this.buckets.keys().next().value;
+			if (oldest !== undefined) this.buckets.delete(oldest);
+		}
+		this.buckets.set(key, { failures: 1, windowStartedAt: this.now() });
+	}
+
+	reset(key: string): void {
+		this.buckets.delete(key);
+	}
+
+	/** Bucket for `key` if its window is still open; expired buckets are dropped. */
+	private live(key: string): Bucket | undefined {
+		const bucket = this.buckets.get(key);
+		if (!bucket) return undefined;
+		if (bucket.windowStartedAt + this.windowMs <= this.now()) {
+			this.buckets.delete(key);
+			return undefined;
+		}
+		return bucket;
+	}
+}
+
+export interface LoginClientKeyOptions {
+	/** Transport-level peer address (e.g. the TCP remote address on Node). */
+	clientAddress?: string;
+	/**
+	 * Honour `CF-Connecting-IP` / `X-Forwarded-For` ahead of `clientAddress`.
+	 * Only set this when a trusted reverse proxy terminates every connection
+	 * and rewrites those headers: behind such a proxy the transport peer is
+	 * the proxy itself, so the forwarded address is the real client. Left
+	 * off, those headers are ignored entirely and a direct client cannot pick
+	 * its own bucket.
+	 */
+	trustProxyHeaders?: boolean;
+}
+
+/** True under workerd, where `CF-Connecting-IP` is set by the Cloudflare edge. */
+export const isCloudflareWorkersRuntime = (): boolean =>
+	typeof navigator !== "undefined" &&
+	typeof navigator.userAgent === "string" &&
+	navigator.userAgent.startsWith("Cloudflare-Workers");
+
+/**
+ * Client identity for limiting, most specific trustworthy source first:
+ *   1. proxy headers, only when the host says a trusted proxy sets them
+ *      (`CF-Connecting-IP`, then the first `X-Forwarded-For` hop);
+ *   2. the peer address the host resolved from the connection — the default
+ *      on Node, and the fallback when a trusted proxy sent no header;
+ *   3. `CF-Connecting-IP` when running on Cloudflare Workers (edge-set).
+ *
+ * With `trustProxyHeaders` unset, forwarding headers never influence the key,
+ * so a direct client cannot escape its bucket by forging them.
+ *
+ * Returns `null` when none of these apply. There is deliberately no shared
+ * fallback bucket: one bucket for every client would let an anonymous
+ * attacker lock every operator out of the dashboard with a handful of wrong
+ * passwords, which is a worse failure than an unthrottled login endpoint
+ * guarded by a strong password. Callers skip limiting on `null` and must
+ * warn so the embedder supplies `clientAddress` or `trustProxyHeaders`.
+ */
+export const loginClientKey = (
+	headers: { get(name: string): string | null },
+	options: LoginClientKeyOptions = {},
+): string | null => {
+	const cf = headers.get("cf-connecting-ip")?.trim();
+	if (options.trustProxyHeaders) {
+		if (cf) return cf;
+		const forwarded = headers.get("x-forwarded-for")?.split(",")[0]?.trim();
+		if (forwarded) return forwarded;
+	}
+	const peer = options.clientAddress?.trim();
+	if (peer) return peer;
+	if (cf && isCloudflareWorkersRuntime()) return cf;
+	return null;
+};
+
+export const UNKEYED_LOGIN_CLIENT_WARNING =
+	"[dashboard-auth] login rate limiting is inactive: no trustworthy client address. " +
+	"On Node, pass `loginRateLimit.clientAddress` (e.g. the TCP peer from @hono/node-server's getConnInfo); " +
+	"behind a trusted reverse proxy set `loginRateLimit.trustProxyHeaders`. " +
+	"Cloudflare Workers key on CF-Connecting-IP automatically.";