reviewzy 0.1.0

package/README.md

@@ -0,0 +1,170 @@
+<div align="center">
+
+# reviewzy
+
+**human-in-the-loop mcp review for user-facing text: agents file, a human approves, later sessions apply**
+
+bulk-audit and rewrite user-facing copy across CLIs, TUIs, web UIs, and websites; prose authorship stays human
+
+[![license](https://shields.uwuclxdy.dev/badge/license-AGPL--3.0-blue)](#license)
+[![mcp](https://shields.uwuclxdy.dev/badge/mcp-2026--07--28-orange)](https://modelcontextprotocol.io)
+
+</div>
+
+---
+
+reviewzy is a self-hosted dashboard and mcp server for human-in-the-loop copy review. a coding agent files the exact strings it wants to write or rewrite. a human authors or approves each one on the dashboard. a later agent session fetches the approved words and applies them in place. no i18n keys, no content layer: each entry points at the string where it already lives.
+
+file an entry:
+
+```json
+{
+  "project": "my-app",
+  "entries": [
+    {
+      "repo": "https://github.com/me/my-app",
+      "file": "src/cli/main.ts",
+      "anchor_text": "error: something went wrong",
+      "agent_draft": "error: could not reach the reviewzy daemon",
+      "file_content": "#!/usr/bin/env bun\nconsole.error(\"error: something went wrong\")\n",
+      "constraints": { "max_len": 48, "tone": "plain, lowercase" }
+    }
+  ],
+  "filed_by": "help-text-audit"
+}
+```
+
+the call answers with the entry as `draft` and a dashboard link for the batch:
+
+```json
+{
+  "batch_id": "01M060XY9GNK6ANVENN4Y4MK7N",
+  "results": [
+    { "id": "01M060XY9GNK6ANVENN4Y4MK7P", "status": "draft", "deduped": false, "updated": false }
+  ],
+  "dashboard_url": "http://127.0.0.1:3123/?project=my-app"
+}
+```
+
+## Why
+
+- **file + snippet anchors, no i18n keys:** apply-back is a targeted replace in place
+- **humans author, agents apply:** the status machine is server-enforced; only the dashboard reaches `approved` or `rejected`
+- **per-project style guide as an mcp resource:** merged with the global guide, embedded in `fetch_approved`
+- **append-only revision history:** every save is undoable; history survives archiving
+- **ntfy and webhook notifications, archive retention:** one ping per filing batch; applied entries archive after `ARCHIVE_AFTER_DAYS`
+
+## How it works
+
+| stage | who | what happens |
+|---|---|---|
+| file | agent | `file_entries` through the stdio shim, which finds or spawns one shared daemon |
+| notify | daemon | pings ntfy and/or the webhook with a dashboard link |
+| author | human | edits, approves, or rejects on the dashboard; saving prose releases it as `approved` |
+| fetch | agent | `fetch_approved` (or a blocking `await_approved`) returns text, anchor, constraints, and the merged style guide |
+| apply | agent | replaces the anchor, reports through `mark_applied` |
+| archive | daemon | applied entries past `ARCHIVE_AFTER_DAYS` move to the archive with their revisions |
+
+## Install
+
+```sh
+bunx reviewzy@latest
+```
+
+requires bun >= 1.3 (the store is `bun:sqlite`, bun-only; no `npx` form). the shim spawns one shared daemon per machine on first use.
+
+from a checkout:
+
+```sh
+bun install
+bun run daemon
+```
+
+### as a Claude Code plugin
+
+the repo is a plugin: it registers the MCP server and adds a `/reviewzy` slash command plus the reviewzy skill.
+
+```
+/plugin marketplace add uwuclxdy/reviewzy
+/plugin install reviewzy@reviewzy
+```
+
+same bun requirement as the npm form.
+
+## Usage
+
+```sh
+curl http://127.0.0.1:3123/health
+```
+
+```json
+{"name":"reviewzy","version":"0.1.0","pid":4172598,"nonce":"881f0e93-8dde-4c75-b559-d2e3d3b223f0","startedAt":"2026-08-16T19:31:28.640Z"}
+```
+
+open http://127.0.0.1:3123/ for the dashboard.
+
+## Configuration
+
+copy `.env.example` to `.env` and edit. every key is optional; a bad value refuses startup.
+
+| key | default | what it does |
+|---|---|---|
+| `REVIEWZY_PORT` | `3123` | dashboard and mcp port; the bind is `127.0.0.1` always |
+| `REVIEWZY_DB` | `~/.local/share/reviewzy/reviewzy.db` | sqlite file (`$XDG_DATA_HOME` respected) |
+| `REVIEWZY_BASE_URL` | `http://127.0.0.1:$REVIEWZY_PORT` | dashboard url used in notification links |
+| `REVIEWZY_TOKEN` | unset | bearer token guarding mcp; set it and it is required |
+| `DASHBOARD_PASSWORD` | unset | dashboard login; set it and it is required |
+| `ARCHIVE_AFTER_DAYS` | `90` | days an applied entry waits before archiving |
+| `NTFY_URL` + `NTFY_TOPIC` | unset | ntfy server and topic; ntfy fires only when both are set |
+| `NTFY_PRIORITY` | `3` | ntfy priority, `1` to `5` |
+| `WEBHOOK_URL` | unset | generic webhook; posts project, batch id, count, and a dashboard link |
+
+a credential left unset keeps that surface loopback-only with a startup warning.
+
+## Integrations
+
+point an mcp client at reviewzy to start filing:
+
+```json
+{
+  "mcpServers": {
+    "reviewzy": {
+      "command": "bunx",
+      "args": ["reviewzy@latest"]
+    }
+  }
+}
+```
+
+the endpoint speaks the stateless `2026-07-28` mcp revision.
+
+## Comparison
+
+| | reviewzy | Contentrain | gotoHuman | Ditto |
+|---|---|---|---|---|
+| authorship | human authors, agent files and applies | agent authors, human approves | human edits form fields | team edits a live library |
+| code integration | anchors on live strings, no externalization | restructures the repo into a content layer | generic forms, no write-back | no code patch-back |
+| hosting | self-hosted | self-hosted | saas only | saas only |
+| queue | async queue plus blocking long-poll | queue, git/PR-first review | async queue | none |
+
+the blocking human-in-the-loop mcp family pops a dialog per call: no queue, no persistence, no dashboard.
+
+## FAQ
+
+**How do I approve AI-generated text before it lands in my code?** the agent files strings as drafts, you author or approve them on the dashboard, the agent applies.
+
+**Can an AI agent rewrite my CLI help text without i18n keys?** yes. entries anchor on the exact current strings; apply-back is a targeted replace.
+
+**How do I bulk-rewrite all user-facing copy in a codebase?** file batches per project, group by project or batch on the dashboard, approve in bulk with a before/after diff, then let a later agent session fetch and apply.
+
+**How do I update the style guide my agents read?** edit it on the dashboard at `/style-guide`. a saved edit reaches agents in up to 60 seconds.
+
+## Development
+
+```sh
+bun run check  # tsc --noEmit && bun test
+```
+
+## License
+
+[AGPL-3.0](LICENSE). self-hosted stays self-hosted; a saas wrapping it publishes its changes.

package/bin/reviewzy

@@ -0,0 +1,7 @@
+#!/usr/bin/env bun
+import { runShim } from "../src/shim/main.ts";
+
+runShim().catch((error: unknown) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "reviewzy",
+  "version": "0.1.0",
+  "description": "agents draft user-facing copy, humans sign off on a dashboard, agents apply the approved words back in place",
+  "license": "AGPL-3.0-only",
+  "type": "module",
+  "private": false,
+  "bin": {
+    "reviewzy": "bin/reviewzy"
+  },
+  "files": ["bin", "src", "tsconfig.json", ".env.example"],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "scripts": {
+    "check": "tsc --noEmit && bun test",
+    "daemon": "bun run src/daemon/main.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "^2.0.0",
+    "hono": "^4.13.2",
+    "ulid": "^3.0.2",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.0",
+    "typescript": "^5.9.0"
+  }
+}

package/src/config.ts

@@ -0,0 +1,76 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { z } from "zod";
+
+const defaultDbPath = () =>
+  join(process.env.XDG_DATA_HOME || join(homedir(), ".local", "share"), "reviewzy", "reviewzy.db");
+
+/** Every value the daemon reads from the environment. `.env.example` mirrors this list. */
+const ConfigSchema = z.object({
+  REVIEWZY_PORT: z.coerce.number().int().min(1).max(65535).default(3123),
+  REVIEWZY_DB: z.string().min(1).default(defaultDbPath),
+  REVIEWZY_BASE_URL: z.url().optional(),
+
+  REVIEWZY_TOKEN: z.string().min(1).optional(),
+  DASHBOARD_PASSWORD: z.string().min(1).optional(),
+
+  ARCHIVE_AFTER_DAYS: z.coerce.number().int().min(1).default(90),
+
+  NTFY_URL: z.url().optional(),
+  NTFY_TOPIC: z.string().min(1).optional(),
+  NTFY_PRIORITY: z.coerce.number().int().min(1).max(5).default(3),
+  WEBHOOK_URL: z.url().optional(),
+});
+
+export type Config = z.infer<typeof ConfigSchema> & { host: string; baseUrl: string };
+
+/** The daemon binds loopback unconditionally, so a missing credential can never expose a network surface. */
+export const HOST = "127.0.0.1";
+
+/** Refuses to start on a bad value rather than silently falling back to a default. */
+export function loadConfig(env: Record<string, string | undefined> = process.env): Config {
+  // An empty string in the environment is an unset variable, not a value that fails `min(1)`.
+  const present = Object.fromEntries(
+    Object.entries(env).filter(([, v]) => v !== undefined && v !== ""),
+  );
+
+  const parsed = ConfigSchema.safeParse(present);
+  if (!parsed.success) {
+    const detail = parsed.error.issues
+      .map((i) => `  ${i.path.join(".") || "(root)"}: ${i.message}`)
+      .join("\n");
+    throw new ConfigError(`reviewzy: bad environment configuration\n${detail}\nfix the named variable in .env, or unset it to take the default.`);
+  }
+
+  return {
+    ...parsed.data,
+    host: HOST,
+    baseUrl: parsed.data.REVIEWZY_BASE_URL ?? `http://${HOST}:${parsed.data.REVIEWZY_PORT}`,
+  };
+}
+
+/** Bad input from the operator, distinct from a bug in the daemon. */
+export class ConfigError extends Error {
+  override readonly name = "ConfigError";
+}
+
+/** Written to stderr at boot. Empty when both credentials are set. */
+export function startupWarnings(config: Config): string[] {
+  const warnings: string[] = [];
+  if (!config.REVIEWZY_TOKEN) {
+    warnings.push(
+      "REVIEWZY_TOKEN is unset: the mcp endpoint accepts any request from this machine. set it in .env to require a bearer token.",
+    );
+  }
+  if (!config.DASHBOARD_PASSWORD) {
+    warnings.push(
+      "DASHBOARD_PASSWORD is unset: the dashboard is open to any process on this machine. set it in .env to require a login.",
+    );
+  }
+  if (config.NTFY_URL !== undefined && config.NTFY_TOPIC === undefined) {
+    warnings.push(
+      "NTFY_TOPIC is unset: ntfy notifications stay off even though NTFY_URL is set. set NTFY_TOPIC in .env to arm them.",
+    );
+  }
+  return warnings;
+}

package/src/daemon/app.ts

@@ -0,0 +1,159 @@
+import {
+  bearerAuthChallengeResponse,
+  OAuthError,
+  OAuthErrorCode,
+} from "@modelcontextprotocol/server";
+import { Hono } from "hono";
+import { timingSafeEqual } from "hono/utils/buffer";
+import type { Config } from "../config.ts";
+import type { Store } from "../db/store.ts";
+import { mountDashboard } from "../dashboard/mount.ts";
+import { mountMcp } from "../mcp/route.ts";
+import { Notifier } from "../notify.ts";
+import { originGate } from "./origin.ts";
+import { NAME, VERSION } from "../version.ts";
+
+export type HealthBody = {
+  name: string;
+  version: string;
+  pid: number;
+  /** One random value per boot; the shim records it in the lockfile and adoption requires it to match, so a port spoofed by a process that cannot read the lockfile can never be adopted. */
+  nonce: string;
+  startedAt: string;
+};
+
+/** The drain response must reach the caller before the server stops serving; the shim that asked waits out this beat and then polls pid liveness, so the exact value is not load-bearing. */
+const DRAIN_FLUSH_MS = 25;
+
+/**
+ * A refusal made before the SDK sees the request, in the same shape `src/mcp/route.ts` uses: the
+ * daemon family answers with one JSON-RPC error style, so a client special-casing a refusal sees
+ * the shape it already handles.
+ */
+function refuse(status: number, message: string, headers: Record<string, string> = {}): Response {
+  return new Response(JSON.stringify({ jsonrpc: "2.0", error: { code: -32000, message }, id: null }), {
+    status,
+    headers: { "content-type": "application/json", ...headers },
+  });
+}
+
+/**
+ * The same credential rule `/mcp` applies (`docs/mcp-contract.md` auth row), duplicated here rather
+ * than exported from `src/mcp/route.ts` because that file owns the mcp surface alone. A malformed
+ * `Authorization` header is one 401, never a 400, so a missing token reads differently from a
+ * broken one.
+ */
+async function tokenAccepted(header: string | undefined, token: string): Promise<boolean> {
+  const presented = /^bearer +(.+)$/i.exec(header ?? "")?.[1];
+  if (presented === undefined) return false;
+  return timingSafeEqual(token, presented);
+}
+
+/**
+ * Serves the daemon's routes. `onDrain` is the shutdown the drain route hands off to (stop
+ * in-flight, close the store, exit); tests omit it to observe the route without ending their own
+ * process, which is also why the route never exits on its own.
+ */
+export function createApp(
+  config: Config,
+  store: Store,
+  startedAt: Date = new Date(),
+  onDrain?: () => void | Promise<void>,
+  notifier: Notifier = new Notifier({ config, baseUrl: config.baseUrl }),
+): Hono {
+  const app = new Hono();
+  let draining = false;
+  const nonce = crypto.randomUUID();
+
+  // App-wide because `docs/design.md` makes Origin validation unconditional rather than per-route:
+  // `/health` hands out a pid and a version, and the dashboard serves a browser. An absent `Origin`
+  // passes, so the shim's liveness probe is unaffected; only a browser sends one at all.
+  app.use(originGate(config));
+
+  // Mounted ahead of the mcp endpoint so a refusal here never reaches the SDK: once draining has
+  // begun, the daemon is going away, and the honest answer to a new request is "try again once a
+  // new daemon answers /health".
+  app.use(async (c, next) => {
+    if (draining && c.req.method === "POST" && c.req.path === "/mcp") {
+      // A notification has no id, and JSON-RPC 2.0 forbids answering one: it gets a bare empty 503,
+      // which the shim's empty-body rung turns into silence (a transport error is dropped for
+      // notifications). The clone keeps the body intact for the SDK rungs below (not reached here).
+      let bodyText = "";
+      try {
+        bodyText = await c.req.raw.clone().text();
+      } catch {
+        // Unreadable: treated as a request whose id could not be determined.
+      }
+      let parsed: unknown = null;
+      try {
+        parsed = JSON.parse(bodyText);
+      } catch {
+        // Not JSON: `null` is the right answer for a request whose id could not be determined.
+      }
+      if (parsed !== null && typeof parsed === "object" && !("id" in parsed)) {
+        return new Response(null, { status: 503, headers: { "retry-after": "1" } });
+      }
+
+      // Echo the request's own id rather than `null`: the frame this answers is well-formed and its
+      // id is in the body, so the client must be able to correlate the refusal.
+      const id = parsed !== null && typeof parsed === "object" ? (parsed as { id?: unknown }).id : null;
+      return new Response(
+        JSON.stringify({ jsonrpc: "2.0", error: { code: -32000, message: "daemon is draining; retry once a new daemon answers /health" }, id }),
+        {
+          status: 503,
+          headers: { "content-type": "application/json", "retry-after": "1" },
+        },
+      );
+    }
+    return next();
+  });
+
+  app.get("/health", (c) =>
+    c.json<HealthBody>({
+      name: NAME,
+      version: VERSION,
+      pid: process.pid,
+      nonce,
+      startedAt: startedAt.toISOString(),
+    }),
+  );
+
+  // POST /drain: loopback-only by construction (the daemon binds 127.0.0.1 unconditionally), and
+  // behind the same optional bearer token as `/mcp`. Idempotent: a second drain while draining gets
+  // the same answer rather than a second shutdown. The hook runs after a short beat so this
+  // response flushes before the server stops accepting.
+  app.all("/drain", async (c) => {
+    if (c.req.method !== "POST") {
+      return refuse(405, "Method not allowed.", { allow: "POST" });
+    }
+
+    const token = config.REVIEWZY_TOKEN;
+    if (token !== undefined && !(await tokenAccepted(c.req.header("Authorization"), token))) {
+      return bearerAuthChallengeResponse(
+        new OAuthError(OAuthErrorCode.InvalidToken, "REVIEWZY_TOKEN is set; a bearer token is required"),
+      );
+    }
+
+    if (!draining) {
+      draining = true;
+      // Long-poll responses must flush while the server still serves: an in-flight `await_approved`
+      // would otherwise hold this response open past `stop(false)`'s patience and get killed with
+      // nothing to show the caller, which then waits out its whole timeout against a dead daemon.
+      store.resolveInFlightWaiters();
+      if (onDrain !== undefined) {
+        setTimeout(() => {
+          void Promise.resolve(onDrain()).catch((error: unknown) => {
+            console.error(`reviewzy: drain failed: ${(error as Error).message}`);
+            process.exit(1);
+          });
+        }, DRAIN_FLUSH_MS);
+      }
+    }
+    return c.json({ status: "draining" });
+  });
+
+  mountMcp(app, config, store, notifier);
+  mountDashboard(app, config, store);
+
+  return app;
+}

package/src/daemon/main.ts

@@ -0,0 +1,103 @@
+#!/usr/bin/env bun
+import { ConfigError, HOST, loadConfig, startupWarnings } from "../config.ts";
+import { SWEEP_INTERVAL_MS, sweepArchive } from "../db/sweep.ts";
+import { openStore } from "../db/store.ts";
+import { Notifier } from "../notify.ts";
+import { VERSION } from "../version.ts";
+import { createApp } from "./app.ts";
+
+/**
+ * Boots the daemon: opens the store first so a bad db fails before a port is bound, then serves.
+ * Returns the server, store, notifier, and sweep timer so a caller (tests, the shim) can shut
+ * them down. `hooks.onDrain` is what the `/drain` route hands off to; omitting it leaves the
+ * route refusing new requests without ending the process, which is exactly what an in-process
+ * test wants.
+ */
+export function startDaemon(
+  config = loadConfig(),
+  hooks: { onDrain?: () => void | Promise<void> } = {},
+  sweepIntervalMs = SWEEP_INTERVAL_MS,
+) {
+  for (const warning of startupWarnings(config)) {
+    console.error(`reviewzy: warning: ${warning}`);
+  }
+
+  const store = openStore(config);
+  // Built here rather than inside `createApp` so the stop path below can dispose it: the debounce
+  // timers are unref'd and could never hold the daemon open, but a pending ping cancelled at
+  // shutdown is cleaner than one racing the store's close.
+  const notifier = new Notifier({ config, baseUrl: config.baseUrl });
+
+  // Unref'd like the notifier's timers, so a pending tick can never hold the daemon open. The
+  // stop path clears it before the store closes, so no tick fires on a closed database.
+  const sweepTimer = setInterval(
+    () => sweepArchive(store, Date.now(), config.ARCHIVE_AFTER_DAYS),
+    sweepIntervalMs,
+  );
+  sweepTimer.unref();
+
+  let server: ReturnType<typeof Bun.serve>;
+  try {
+    // One sweep before the port binds, so the dashboard never serves a queue the retention
+    // window has already retired. A failure lands in the same catch as a bind failure and
+    // closes the store either way, so neither leak.
+    sweepArchive(store, Date.now(), config.ARCHIVE_AFTER_DAYS);
+    server = Bun.serve({
+      hostname: HOST,
+      port: config.REVIEWZY_PORT,
+      fetch: createApp(config, store, new Date(), hooks.onDrain, notifier).fetch,
+    });
+  } catch (error) {
+    // A bind failure (e.g. a shim racing an already-running daemon on the same port) must not
+    // leak the store's open sqlite connection, and the armed sweep timer must not outlive it.
+    clearInterval(sweepTimer);
+    store.close();
+    throw error;
+  }
+
+  // The bound port, not `config.baseUrl`: a port-0 boot resolves to something the config never held.
+  console.error(`reviewzy ${VERSION} listening on http://${HOST}:${server.port} (pid ${process.pid})`);
+  return { server, store, notifier, sweepTimer };
+}
+
+if (import.meta.main) {
+  let daemon: ReturnType<typeof startDaemon>;
+  try {
+    // The drain hook closes over `stop`, which is declared below it: a function declaration is
+    // hoisted, and the hook only ever runs after `startDaemon` has returned, so the shutdown it
+    // names is always the daemon that just booted.
+    daemon = startDaemon(loadConfig(), { onDrain: () => stop() });
+  } catch (error) {
+    if (error instanceof ConfigError) {
+      console.error(error.message);
+      process.exit(1);
+    }
+    throw error;
+  }
+
+  // Graceful only (`false`): waits out in-flight requests before closing the store and exiting.
+  // SIGINT, SIGTERM, and the `/drain` route all land here, so a handoff drain and an operator's
+  // Ctrl-C shut down through one path.
+  let stopping = false;
+  function stop(): void {
+    if (stopping) return;
+    stopping = true;
+    void (async () => {
+      // An in-flight await_approved long-poll must flush before the graceful stop waits it out:
+      // the /drain route resolves waiters for the same reason, and an operator's Ctrl-C would
+      // otherwise hold the daemon up for the whole remaining wait.
+      daemon.store.resolveInFlightWaiters();
+      await daemon.server.stop(false);
+      // Cleared before the store closes: an armed tick firing on a closed database would crash.
+      clearInterval(daemon.sweepTimer);
+      // After the server stops, nothing can arm a new debounce, so this cancels exactly the set
+      // in-flight filings left behind; an in-flight ping already past its window still races the
+      // close, which is the accepted "dropped at exit" case.
+      daemon.notifier.dispose();
+      daemon.store.close();
+      process.exit(0);
+    })();
+  }
+  process.on("SIGINT", stop);
+  process.on("SIGTERM", stop);
+}

package/src/daemon/origin.ts

@@ -0,0 +1,60 @@
+import type { MiddlewareHandler } from "hono";
+import type { Config } from "../config.ts";
+
+/**
+ * A refusal made before the SDK sees the request, in the same shape `src/mcp/route.ts` uses: the
+ * daemon family answers with one JSON-RPC error style, so a client special-casing a refusal sees
+ * the shape it already handles.
+ */
+function refuse(status: 403 | 405, message: string, headers: Record<string, string> = {}) {
+  return new Response(JSON.stringify({ jsonrpc: "2.0", error: { code: -32000, message }, id: null }), {
+    status,
+    headers: { "content-type": "application/json", ...headers },
+  });
+}
+
+/**
+ * Answers "was this request issued by a page the daemon serves", the DNS-rebinding defence the
+ * design makes unconditional. An absent `Origin` passes: the shim, curl, and stdio clients send
+ * none, and only a browser sends one at all.
+ *
+ * The loopback set is matched against the port THIS request was addressed to. That equals
+ * `config.REVIEWZY_PORT` in every configuration `loadConfig` accepts, since the schema floors the
+ * port at 1 and the daemon binds it verbatim; reading it from the request keeps the gate off a
+ * config field rather than buying a safety property. A browser cannot forge that port either way,
+ * since reaching the daemon means addressing the port it bound.
+ */
+function originAllowed(origin: string, requestUrl: URL, configuredOrigin: string): boolean {
+  let parsed: URL;
+  try {
+    parsed = new URL(origin);
+  } catch {
+    return false; // Unparseable, the literal `null` of an opaque browser context included.
+  }
+  if (parsed.origin === configuredOrigin) return true;
+  // The scheme is compared too, or a default-port `https://127.0.0.1` matches a default-port http
+  // daemon: both sides normalise to an empty `port`.
+  return (
+    parsed.protocol === requestUrl.protocol &&
+    (parsed.hostname === "127.0.0.1" || parsed.hostname === "localhost" || parsed.hostname === "[::1]") &&
+    parsed.port === requestUrl.port
+  );
+}
+
+/**
+ * The DNS-rebinding gate, unconditional for every route the app serves: `/health` hands out a
+ * version and a pid, which is exactly the disclosure the check exists for, and the dashboard sits
+ * behind it too. The mcp rungs only re-check what is theirs to check.
+ */
+export function originGate(config: Config): MiddlewareHandler {
+  const configuredOrigin = new URL(config.baseUrl).origin;
+  return async (c, next) => {
+    const origin = c.req.header("Origin");
+    if (origin !== undefined && !originAllowed(origin, new URL(c.req.url), configuredOrigin)) {
+      // Echoed so a developer wiring a browser client sees what was refused, truncated because the
+      // value is attacker-controlled and unbounded by nature.
+      return refuse(403, `Invalid Origin: ${origin.slice(0, 100)}`);
+    }
+    return next();
+  };
+}