the-campfire 0.1.0

package/server/routes/settings-routes.ts

@@ -0,0 +1,108 @@
+import type { Hono } from "hono";
+import type { RouteDeps } from "./route-deps.js";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { DEFAULT_OPENROUTER_MODEL, getSettings, updateSettings, type CampfireSettings } from "../settings-manager.js";
+
+function settingsResponse(s: CampfireSettings) {
+  return {
+    openrouterApiKeyConfigured: !!s.openrouterApiKey.trim(),
+    openrouterModel: s.openrouterModel || DEFAULT_OPENROUTER_MODEL,
+    moltbookApiKeyConfigured: !!s.moltbookApiKey?.trim(),
+    linearApiKeyConfigured: !!s.linearApiKey?.trim(),
+    claudeOAuthTokenConfigured: !!s.claudeOAuthToken?.trim(),
+    openaiApiKeyConfigured: !!s.openaiApiKey?.trim(),
+    anthropicApiKeyConfigured: !!s.anthropicApiKey?.trim(),
+    onboardingCompleted: s.onboardingCompleted,
+  };
+}
+
+function resolveClaudeMethod(
+  credentials: boolean, oauthEnv: boolean, apiKeyEnv: boolean,
+  anthropicStored: boolean, tokenStored: boolean,
+): string | null {
+  if (credentials) return "subscription";
+  if (oauthEnv) return "oauth-token";
+  if (apiKeyEnv || anthropicStored) return "api-key";
+  if (tokenStored) return "oauth-token";
+  return null;
+}
+
+function resolveCodexMethod(auth: boolean, apiKeyEnv: boolean, keyStored: boolean): string | null {
+  if (auth) return "subscription";
+  if (apiKeyEnv || keyStored) return "api-key";
+  return null;
+}
+
+export function registerSettingsRoutes(api: Hono, _deps: RouteDeps): void {
+  api.get("/settings", (c) => {
+    const settings = getSettings();
+    return c.json(settingsResponse(settings));
+  });
+
+  api.put("/settings", async (c) => {
+    const body = await c.req.json().catch(() => ({}));
+
+    // Validate string fields
+    const STRING_FIELDS = [
+      "openrouterApiKey", "openrouterModel", "moltbookApiKey", "linearApiKey",
+      "claudeOAuthToken", "openaiApiKey", "anthropicApiKey",
+    ] as const;
+
+    for (const field of STRING_FIELDS) {
+      if (body[field] !== undefined && typeof body[field] !== "string") {
+        return c.json({ error: `${field} must be a string` }, 400);
+      }
+    }
+
+    const hasOnboarding = typeof body.onboardingCompleted === "boolean";
+    const hasAnyField = STRING_FIELDS.some((f) => body[f] !== undefined) || hasOnboarding;
+    if (!hasAnyField) {
+      return c.json({ error: "At least one settings field is required" }, 400);
+    }
+
+    const patch: Record<string, string | boolean> = {};
+    if (hasOnboarding) patch.onboardingCompleted = body.onboardingCompleted;
+    for (const field of STRING_FIELDS) {
+      if (typeof body[field] === "string") {
+        patch[field] = field === "openrouterModel"
+          ? (body[field].trim() || DEFAULT_OPENROUTER_MODEL)
+          : body[field].trim();
+      }
+    }
+
+    const settings = updateSettings(patch);
+    return c.json(settingsResponse(settings));
+  });
+
+  // ─── Auth detection: check if Claude/Codex are already authenticated ─────
+  api.get("/settings/auth-status", (c) => {
+    const home = homedir();
+    // Claude: ~/.claude/.credentials.json or CLAUDE_CODE_OAUTH_TOKEN env var
+    const claudeCredentials = existsSync(join(home, ".claude", ".credentials.json"));
+    const claudeOAuthEnv = !!process.env.CLAUDE_CODE_OAUTH_TOKEN;
+    const claudeApiKeyEnv = !!process.env.ANTHROPIC_API_KEY;
+
+    // Codex: ~/.codex/auth.json or OPENAI_API_KEY env var
+    const codexAuth = existsSync(join(home, ".codex", "auth.json"));
+    const openaiApiKeyEnv = !!process.env.OPENAI_API_KEY;
+
+    // Also check global settings for stored tokens
+    const settings = getSettings();
+    const claudeTokenStored = !!settings.claudeOAuthToken?.trim();
+    const openaiKeyStored = !!settings.openaiApiKey?.trim();
+    const anthropicKeyStored = !!settings.anthropicApiKey?.trim();
+
+    return c.json({
+      claude: {
+        authenticated: claudeCredentials || claudeOAuthEnv || claudeApiKeyEnv || claudeTokenStored || anthropicKeyStored,
+        method: resolveClaudeMethod(claudeCredentials, claudeOAuthEnv, claudeApiKeyEnv, anthropicKeyStored, claudeTokenStored),
+      },
+      codex: {
+        authenticated: codexAuth || openaiApiKeyEnv || openaiKeyStored,
+        method: resolveCodexMethod(codexAuth, openaiApiKeyEnv, openaiKeyStored),
+      },
+    });
+  });
+}

package/server/routes/skills-routes.ts

@@ -0,0 +1,52 @@
+import type { Hono } from "hono";
+import type { RouteDeps } from "./route-deps.js";
+import * as skillsManager from "../skills-manager.js";
+
+export function registerSkillsRoutes(api: Hono, _deps: RouteDeps): void {
+  // List all installed plugins with their skills and commands
+  api.get("/skills", (c) => {
+    const plugins = skillsManager.listPlugins();
+    const disabled = skillsManager.getDisabledPlugins();
+    const enriched = plugins.map((p) => ({
+      ...p,
+      disabledInCampfire: disabled.includes(p.id),
+    }));
+    return c.json(enriched);
+  });
+
+  // Get a single plugin by ID
+  api.get("/skills/:id", (c) => {
+    const id = decodeURIComponent(c.req.param("id"));
+    const plugin = skillsManager.getPlugin(id);
+    if (!plugin) return c.json({ error: "Plugin not found" }, 404);
+    const disabled = skillsManager.isPluginDisabled(id);
+    return c.json({ ...plugin, disabledInCampfire: disabled });
+  });
+
+  // Read a skill's SKILL.md content
+  api.get("/skills/:id/skill/:name", (c) => {
+    const id = decodeURIComponent(c.req.param("id"));
+    const name = decodeURIComponent(c.req.param("name"));
+    const content = skillsManager.readSkillContent(id, name);
+    if (content === null) return c.json({ error: "Skill not found" }, 404);
+    return c.json({ content });
+  });
+
+  // Read a command's content
+  api.get("/skills/:id/command/:name", (c) => {
+    const id = decodeURIComponent(c.req.param("id"));
+    const name = decodeURIComponent(c.req.param("name"));
+    const content = skillsManager.readCommandContent(id, name);
+    if (content === null) return c.json({ error: "Command not found" }, 404);
+    return c.json({ content });
+  });
+
+  // Toggle plugin enabled/disabled in Campfire
+  api.post("/skills/:id/toggle", async (c) => {
+    const id = decodeURIComponent(c.req.param("id"));
+    const body = await c.req.json().catch(() => ({}));
+    const disabled = body.disabled === true;
+    skillsManager.setPluginDisabled(id, disabled);
+    return c.json({ ok: true, disabled });
+  });
+}

package/server/routes/system-routes.ts

@@ -0,0 +1,243 @@
+import type { Hono } from "hono";
+import type { RouteDeps } from "./route-deps.js";
+import { resolveBinary } from "../path-resolver.js";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { containerManager } from "../container-manager.js";
+import { getUsageLimits } from "../usage-limits.js";
+import {
+  getUpdateState,
+  checkForUpdate,
+  isUpdateAvailable,
+  setUpdateInProgress,
+} from "../update-checker.js";
+import { refreshServiceDefinition } from "../service.js";
+
+const UPDATE_CHECK_STALE_MS = 5 * 60 * 1000;
+
+export function registerSystemRoutes(api: Hono, deps: RouteDeps): void {
+  const { wsBridge, terminalManager } = deps;
+
+  // ─── Available backends ─────────────────────────────────────
+  api.get("/backends", (c) => {
+    const backends: Array<{ id: string; name: string; available: boolean }> = [];
+    backends.push({ id: "claude", name: "Claude Code", available: resolveBinary("claude") !== null });
+    backends.push({ id: "codex", name: "Codex", available: resolveBinary("codex") !== null });
+    backends.push({ id: "goose", name: "Goose", available: resolveBinary("goose") !== null });
+    backends.push({ id: "aider", name: "Aider", available: resolveBinary("aider") !== null });
+    backends.push({ id: "openhands", name: "OpenHands", available: resolveBinary("openhands") !== null });
+    backends.push({ id: "openclaw", name: "OpenClaw", available: resolveBinary("openclaw") !== null });
+    backends.push({ id: "opencode", name: "OpenCode", available: resolveBinary("opencode") !== null });
+    return c.json(backends);
+  });
+
+  api.get("/backends/:id/models", (c) => {
+    const backendId = c.req.param("id");
+    if (backendId === "codex") {
+      const cachePath = join(homedir(), ".codex", "models_cache.json");
+      if (!existsSync(cachePath)) {
+        return c.json({ error: "Codex models cache not found. Run codex once to populate it." }, 404);
+      }
+      try {
+        const raw = readFileSync(cachePath, "utf-8");
+        const cache = JSON.parse(raw) as {
+          models: Array<{
+            slug: string;
+            display_name?: string;
+            description?: string;
+            visibility?: string;
+            priority?: number;
+          }>;
+        };
+        const models = cache.models
+          .filter((m) => m.visibility === "list")
+          .sort((a, b) => (a.priority ?? 99) - (b.priority ?? 99))
+          .map((m) => ({
+            value: m.slug,
+            label: m.display_name || m.slug,
+            description: m.description || "",
+          }));
+        return c.json(models);
+      } catch (e) {
+        return c.json({ error: "Failed to parse Codex models cache" }, 500);
+      }
+    }
+    return c.json({ error: "Use frontend defaults for this backend" }, 404);
+  });
+
+  // ─── Containers ─────────────────────────────────────────────────
+  api.get("/containers/status", (c) => {
+    const available = containerManager.checkDocker();
+    const version = containerManager.getDockerVersion();
+    return c.json({ available, version });
+  });
+
+  api.get("/containers/images", (c) => {
+    const images = containerManager.listImages();
+    return c.json(images);
+  });
+
+  api.get("/containers/list", (c) => {
+    return c.json(containerManager.listContainers());
+  });
+
+  api.post("/containers/:sessionId/stop", async (c) => {
+    const sessionId = c.req.param("sessionId");
+    await containerManager.removeContainer(sessionId);
+    return c.json({ ok: true });
+  });
+
+  // ─── Usage Limits ─────────────────────────────────────────────────────
+  api.get("/usage-limits", async (c) => {
+    const limits = await getUsageLimits();
+    return c.json(limits);
+  });
+
+  api.get("/sessions/:id/usage-limits", async (c) => {
+    const sessionId = c.req.param("id");
+    const session = wsBridge.getSession(sessionId);
+    const empty = { five_hour: null, seven_day: null, extra_usage: null };
+
+    if (session?.backendType === "codex") {
+      const rl = wsBridge.getCodexRateLimits(sessionId);
+      if (!rl) return c.json(empty);
+      const mapLimit = (l: { usedPercent: number; windowDurationMins: number; resetsAt: number } | null) => {
+        if (!l) return null;
+        return {
+          utilization: l.usedPercent,
+          resets_at: l.resetsAt ? new Date(l.resetsAt * 1000).toISOString() : null,
+        };
+      };
+      return c.json({
+        five_hour: mapLimit(rl.primary),
+        seven_day: mapLimit(rl.secondary),
+        extra_usage: null,
+      });
+    }
+
+    const limits = await getUsageLimits();
+    return c.json(limits);
+  });
+
+  // ─── Update checking ─────────────────────────────────────────────────
+  api.get("/update-check", async (c) => {
+    const initialState = getUpdateState();
+    const needsRefresh =
+      initialState.lastChecked === 0
+      || Date.now() - initialState.lastChecked > UPDATE_CHECK_STALE_MS;
+    if (needsRefresh) {
+      await checkForUpdate();
+    }
+    const state = getUpdateState();
+    return c.json({
+      currentVersion: state.currentVersion,
+      latestVersion: state.latestVersion,
+      updateAvailable: isUpdateAvailable(),
+      isServiceMode: state.isServiceMode,
+      updateInProgress: state.updateInProgress,
+      lastChecked: state.lastChecked,
+    });
+  });
+
+  api.post("/update-check", async (c) => {
+    await checkForUpdate();
+    const state = getUpdateState();
+    return c.json({
+      currentVersion: state.currentVersion,
+      latestVersion: state.latestVersion,
+      updateAvailable: isUpdateAvailable(),
+      isServiceMode: state.isServiceMode,
+      updateInProgress: state.updateInProgress,
+      lastChecked: state.lastChecked,
+    });
+  });
+
+  api.post("/update", async (c) => {
+    const state = getUpdateState();
+    if (!state.isServiceMode) {
+      return c.json({ error: "Update & restart is only available in service mode" }, 400);
+    }
+    if (!isUpdateAvailable()) {
+      return c.json({ error: "No update available" }, 400);
+    }
+    if (state.updateInProgress) {
+      return c.json({ error: "Update already in progress" }, 409);
+    }
+
+    setUpdateInProgress(true);
+
+    setTimeout(async () => {
+      try {
+        console.log(`[update] Updating the-campfire to ${state.latestVersion}...`);
+        const proc = Bun.spawn(
+          ["bun", "install", "-g", `the-campfire@${state.latestVersion}`],
+          { stdout: "pipe", stderr: "pipe" },
+        );
+        const exitCode = await proc.exited;
+        if (exitCode !== 0) {
+          const stderr = await new Response(proc.stderr).text();
+          console.error(`[update] bun install failed (code ${exitCode}):`, stderr);
+          setUpdateInProgress(false);
+          return;
+        }
+        try {
+          refreshServiceDefinition();
+          console.log("[update] Service definition refreshed.");
+        } catch (err) {
+          console.warn("[update] Failed to refresh service definition:", err);
+        }
+        console.log("[update] Update successful, restarting service...");
+        const isLinux = process.platform === "linux";
+        const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
+        const restartCmd = isLinux
+          ? ["systemctl", "--user", "restart", "the-campfire.service"]
+          : uid !== undefined
+            ? ["launchctl", "kickstart", "-k", `gui/${uid}/sh.campfire.app`]
+            : ["launchctl", "kickstart", "-k", "sh.campfire.app"];
+
+        Bun.spawn(restartCmd, {
+          stdout: "ignore",
+          stderr: "ignore",
+          stdin: "ignore",
+          env: isLinux
+            ? {
+                ...process.env,
+                XDG_RUNTIME_DIR:
+                  process.env.XDG_RUNTIME_DIR ||
+                  `/run/user/${uid ?? 1000}`,
+              }
+            : undefined,
+        });
+        setTimeout(() => process.exit(0), 500);
+      } catch (err) {
+        console.error("[update] Update failed:", err);
+        setUpdateInProgress(false);
+      }
+    }, 100);
+
+    return c.json({
+      ok: true,
+      message: "Update started. Server will restart shortly.",
+    });
+  });
+
+  // ─── Terminal ──────────────────────────────────────────────────────
+  api.get("/terminal", (c) => {
+    const info = terminalManager.getInfo();
+    if (!info) return c.json({ active: false });
+    return c.json({ active: true, terminalId: info.id, cwd: info.cwd });
+  });
+
+  api.post("/terminal/spawn", async (c) => {
+    const body = await c.req.json<{ cwd: string; cols?: number; rows?: number }>();
+    if (!body.cwd) return c.json({ error: "cwd is required" }, 400);
+    const terminalId = terminalManager.spawn(body.cwd, body.cols, body.rows);
+    return c.json({ terminalId });
+  });
+
+  api.post("/terminal/kill", (c) => {
+    terminalManager.kill();
+    return c.json({ ok: true });
+  });
+}

package/server/routes/webhook-routes.ts

@@ -0,0 +1,135 @@
+import type { Hono } from "hono";
+import type { RouteDeps } from "./route-deps.js";
+import * as webhookStore from "../webhook-store.js";
+import type { WebhookCreateInput } from "../webhook-types.js";
+
+export function registerWebhookRoutes(api: Hono, deps: RouteDeps): void {
+  const { launcher, wsBridge, webhookManager } = deps;
+
+  api.get("/webhooks", (c) => {
+    return c.json(webhookStore.listWebhooks());
+  });
+
+  api.get("/webhooks/:id", (c) => {
+    const id = c.req.param("id");
+    const webhook = webhookStore.getWebhook(id);
+    if (!webhook) return c.json({ error: "Webhook not found" }, 404);
+    return c.json(webhook);
+  });
+
+  api.post("/webhooks", async (c) => {
+    const data = await c.req.json() as WebhookCreateInput;
+    try {
+      const webhook = webhookStore.createWebhook(data);
+      return c.json(webhook, 201);
+    } catch (err) {
+      return c.json({ error: err instanceof Error ? err.message : String(err) }, 400);
+    }
+  });
+
+  api.put("/webhooks/:id", async (c) => {
+    const id = c.req.param("id");
+    const updates = await c.req.json();
+    try {
+      const webhook = webhookStore.updateWebhook(id, updates);
+      if (!webhook) return c.json({ error: "Webhook not found" }, 404);
+      return c.json(webhook);
+    } catch (err) {
+      return c.json({ error: err instanceof Error ? err.message : String(err) }, 400);
+    }
+  });
+
+  api.delete("/webhooks/:id", (c) => {
+    const id = c.req.param("id");
+    const deleted = webhookStore.deleteWebhook(id);
+    if (!deleted) return c.json({ error: "Webhook not found" }, 404);
+    return c.json({ ok: true });
+  });
+
+  api.post("/webhooks/:id/toggle", (c) => {
+    const id = c.req.param("id");
+    const webhook = webhookStore.getWebhook(id);
+    if (!webhook) return c.json({ error: "Webhook not found" }, 404);
+    const updated = webhookStore.updateWebhook(id, { enabled: !webhook.enabled });
+    return c.json(updated);
+  });
+
+  api.post("/webhooks/:id/test", async (c) => {
+    const id = c.req.param("id");
+    const webhook = webhookStore.getWebhook(id);
+    if (!webhook) return c.json({ error: "Webhook not found" }, 404);
+    if (webhookManager) {
+      webhookManager.emit("session.completed", "test-session", {
+        backendType: "claude",
+        model: "claude-sonnet-4-5-20250929",
+        totalCostUsd: 0.05,
+        numTurns: 3,
+        isError: false,
+        test: true,
+      });
+    }
+    return c.json({ ok: true });
+  });
+
+  // ─── OpenClaw Inbound Webhook ───────────────────────────────────
+  api.post("/webhooks/openclaw", async (c) => {
+    const expectedToken = process.env.CAMPFIRE_OPENCLAW_TOKEN;
+    if (expectedToken) {
+      const authHeader = c.req.header("Authorization") || "";
+      const token = authHeader.startsWith("Bearer ") ? authHeader.slice(7) : "";
+      if (token !== expectedToken) {
+        return c.json({ ok: false, error: "Unauthorized" }, 401);
+      }
+    }
+    try {
+      const body = await c.req.json() as {
+        message?: string;
+        name?: string;
+        model?: string;
+        cwd?: string;
+      };
+      if (!body.message || !body.message.trim()) {
+        return c.json({ ok: false, error: "message is required" }, 400);
+      }
+      const cwd = body.cwd || process.env.HOME || "/";
+      const session = launcher.launch({
+        model: body.model || "default",
+        permissionMode: "bypassPermissions",
+        cwd,
+        backendType: "openclaw",
+        env: {},
+      });
+      setTimeout(() => {
+        wsBridge.injectUserMessage(session.sessionId, body.message!.trim());
+      }, 2000);
+      console.log(`[routes] OpenClaw inbound webhook → created session ${session.sessionId} with prompt: "${body.message.trim().slice(0, 80)}..."`);
+      return c.json({
+        ok: true,
+        sessionId: session.sessionId,
+        name: body.name || "OpenClaw Hook",
+      }, 202);
+    } catch (err) {
+      console.error("[routes] OpenClaw inbound webhook error:", err);
+      return c.json({ ok: false, error: err instanceof Error ? err.message : String(err) }, 500);
+    }
+  });
+
+  // ─── OpenClaw Channel Inbound ────────────────────────────────────
+  api.post("/openclaw/inbound", async (c) => {
+    try {
+      const body = await c.req.json() as {
+        sessionId?: string;
+        senderId?: string;
+        text?: string;
+        metadata?: Record<string, unknown>;
+      };
+      if (!body.sessionId || !body.text) {
+        return c.json({ ok: false, error: "sessionId and text are required" }, 400);
+      }
+      wsBridge.injectAgentMessage(body.sessionId, body.text, body.metadata);
+      return c.json({ ok: true });
+    } catch (err) {
+      return c.json({ ok: false, error: err instanceof Error ? err.message : String(err) }, 500);
+    }
+  });
+}

package/server/routes.ts

@@ -0,0 +1,44 @@
+// Re-export shim — the actual route implementations live in routes/*.ts
+// This file preserves the original import path for backwards compatibility.
+import type { CliLauncher } from "./cli-launcher.js";
+import type { WsBridge } from "./ws-bridge.js";
+import type { SessionStore } from "./session-store.js";
+import type { WorktreeTracker } from "./worktree-tracker.js";
+import type { TerminalManager } from "./terminal-manager.js";
+import { createRoutes as _createRoutes } from "./routes/index.js";
+
+/**
+ * Legacy positional-args signature preserved for backwards compatibility.
+ * New code should import from `./routes/index.js` and pass a deps object.
+ */
+export function createRoutes(
+  launcher: CliLauncher,
+  wsBridge: WsBridge,
+  sessionStore: SessionStore,
+  worktreeTracker: WorktreeTracker,
+  terminalManager: TerminalManager,
+  prPoller?: import("./pr-poller.js").PRPoller,
+  recorder?: import("./recorder.js").RecorderManager,
+  cronScheduler?: import("./cron-scheduler.js").CronScheduler,
+  webhookManager?: import("./webhook-manager.js").WebhookManager,
+  adapterRegistry?: import("./adapter-registry.js").AdapterRegistry,
+  agentExecutor?: import("./agent-executor.js").AgentExecutor,
+  protocolMonitor?: import("./protocol-monitor.js").ProtocolMonitor,
+  agentMcpBridge?: import("./agent-mcp-bridge.js").AgentMcpBridge,
+) {
+  return _createRoutes({
+    launcher,
+    wsBridge,
+    sessionStore,
+    worktreeTracker,
+    terminalManager,
+    prPoller,
+    recorder,
+    cronScheduler,
+    webhookManager,
+    adapterRegistry,
+    agentExecutor,
+    protocolMonitor,
+    agentMcpBridge,
+  });
+}

package/server/security-middleware.ts

@@ -0,0 +1,100 @@
+/**
+ * Security middleware — headers + rate limiting for the Hono server.
+ *
+ * Security headers: X-Frame-Options, X-Content-Type-Options, Referrer-Policy,
+ * X-XSS-Protection, Strict-Transport-Security, Permissions-Policy.
+ *
+ * Rate limiting: per-IP sliding window, configurable via env vars.
+ */
+
+import type { Context, Next } from "hono";
+
+// ─── Security Headers ──────────────────────────────────────────────────────
+
+export async function securityHeaders(c: Context, next: Next): Promise<void> {
+  await next();
+
+  c.header("X-Content-Type-Options", "nosniff");
+  c.header("X-Frame-Options", "SAMEORIGIN");
+  c.header("Referrer-Policy", "strict-origin-when-cross-origin");
+  c.header("X-XSS-Protection", "1; mode=block");
+  c.header("Permissions-Policy", "camera=(), microphone=(), geolocation=()");
+
+  // HSTS only if behind HTTPS (don't break HTTP dev setups)
+  if (c.req.header("x-forwarded-proto") === "https") {
+    c.header("Strict-Transport-Security", "max-age=31536000; includeSubDomains");
+  }
+}
+
+// ─── Rate Limiting ──────────────────────────────────────────────────────────
+
+const WINDOW_MS = Number(process.env.CAMPFIRE_RATE_LIMIT_WINDOW_MS) || 60_000;
+const MAX_REQUESTS = Number(process.env.CAMPFIRE_RATE_LIMIT_MAX) || 120;
+
+interface RateEntry {
+  count: number;
+  resetAt: number;
+}
+
+const ipBuckets = new Map<string, RateEntry>();
+
+// Clean up stale entries every 5 minutes. unref() so the interval never
+// keeps the process (or a test runner) alive on its own.
+setInterval(() => {
+  const now = Date.now();
+  for (const [ip, entry] of ipBuckets) {
+    if (entry.resetAt <= now) ipBuckets.delete(ip);
+  }
+}, 5 * 60_000).unref?.();
+
+/** Socket-level remote IPs, tagged by the Bun.serve fetch handler before the
+ *  request reaches Hono. A WeakMap keyed by the raw Request cannot be spoofed
+ *  by client-supplied headers. */
+const requestIps = new WeakMap<Request, string>();
+
+/** Record the actual socket remote address for a request (called from index.ts). */
+export function tagRequestIp(req: Request, ip: string | undefined | null): void {
+  if (ip) requestIps.set(req, ip);
+}
+
+function isLoopback(ip: string): boolean {
+  return ip === "127.0.0.1" || ip === "::1" || ip === "::ffff:127.0.0.1";
+}
+
+function getClientIp(c: Context): string {
+  const socketIp = requestIps.get(c.req.raw) ?? "";
+  // Forwarded headers are only trustworthy when the direct peer is a local
+  // reverse proxy — otherwise a client could spoof them to dodge the limiter.
+  if (!socketIp || isLoopback(socketIp)) {
+    const forwarded = c.req.header("x-forwarded-for")?.split(",")[0]?.trim()
+      || c.req.header("x-real-ip");
+    if (forwarded) return forwarded;
+  }
+  return socketIp || "unknown";
+}
+
+export async function rateLimiter(c: Context, next: Next): Promise<void> {
+  const ip = getClientIp(c);
+  const now = Date.now();
+
+  let entry = ipBuckets.get(ip);
+  if (!entry || entry.resetAt <= now) {
+    entry = { count: 0, resetAt: now + WINDOW_MS };
+    ipBuckets.set(ip, entry);
+  }
+
+  entry.count++;
+
+  // Set rate limit headers
+  const remaining = Math.max(0, MAX_REQUESTS - entry.count);
+  c.header("X-RateLimit-Limit", String(MAX_REQUESTS));
+  c.header("X-RateLimit-Remaining", String(remaining));
+  c.header("X-RateLimit-Reset", String(Math.ceil(entry.resetAt / 1000)));
+
+  if (entry.count > MAX_REQUESTS) {
+    c.header("Retry-After", String(Math.ceil((entry.resetAt - now) / 1000)));
+    return c.json({ error: "Too many requests. Please retry later." }, 429) as unknown as void;
+  }
+
+  await next();
+}