blackriver-gateway 3.8.46

package/src/server/auth/loginGuard.ts

@@ -0,0 +1,130 @@
+/**
+ * Login brute-force guard.
+ *
+ * Tracks failed `/api/auth/login` attempts per client IP in process memory
+ * and returns lockout decisions. Single-process scope is intentional — this
+ * is a defense-in-depth check that pairs with Cloudflare/reverse-proxy rate
+ * limiting, not a substitute for it.
+ *
+ * Tunables:
+ *   - failure threshold: 5 within `WINDOW_MS`
+ *   - lockout duration: `LOCKOUT_MS`
+ *   - sliding window: `WINDOW_MS`
+ *
+ * The guard is a no-op when `enabled` is false; the caller decides based on
+ * the `bruteForceProtection` setting (default true).
+ */
+
+const WINDOW_MS = 15 * 60 * 1000;
+const LOCKOUT_MS = 15 * 60 * 1000;
+const FAILURE_THRESHOLD = 5;
+
+interface AttemptState {
+  count: number;
+  firstAttemptAt: number;
+  lockedUntil: number | null;
+}
+
+const attempts: Map<string, AttemptState> = new Map();
+
+// Above this many tracked IPs, opportunistically drop entries whose window has elapsed and
+// that are not currently locked. Without this the map only ever grew (entries were deleted
+// only on a *successful* login), so every distinct IP that ever failed a login leaked a
+// permanent entry — unbounded under distributed brute-force. Expired/unlocked entries are
+// already treated as "allowed", so removing them never changes a guard decision.
+const PRUNE_THRESHOLD = 256;
+
+function pruneExpiredAttempts(now: number): void {
+  for (const [key, state] of attempts) {
+    const windowElapsed = now - state.firstAttemptAt > WINDOW_MS;
+    const notLocked = !state.lockedUntil || state.lockedUntil <= now;
+    if (windowElapsed && notLocked) attempts.delete(key);
+  }
+}
+
+export interface GuardDecision {
+  allowed: boolean;
+  retryAfterSeconds?: number;
+}
+
+function nowMs(): number {
+  return Date.now();
+}
+
+function clientKey(rawIp: string | null | undefined): string {
+  const ip = (rawIp || "").trim();
+  return ip || "__unknown__";
+}
+
+export function checkLoginGuard(
+  rawIp: string | null | undefined,
+  options: { enabled: boolean }
+): GuardDecision {
+  if (!options.enabled) return { allowed: true };
+  const state = attempts.get(clientKey(rawIp));
+  if (!state) return { allowed: true };
+  const now = nowMs();
+  if (state.lockedUntil && state.lockedUntil > now) {
+    return {
+      allowed: false,
+      retryAfterSeconds: Math.ceil((state.lockedUntil - now) / 1000),
+    };
+  }
+  return { allowed: true };
+}
+
+export function recordLoginFailure(
+  rawIp: string | null | undefined,
+  options: { enabled: boolean }
+): GuardDecision {
+  if (!options.enabled) return { allowed: true };
+  const key = clientKey(rawIp);
+  const now = nowMs();
+
+  // Keep the map from growing without bound as distinct IPs fail logins over time.
+  if (attempts.size > PRUNE_THRESHOLD) pruneExpiredAttempts(now);
+
+  const existing = attempts.get(key);
+
+  if (!existing || now - existing.firstAttemptAt > WINDOW_MS) {
+    attempts.set(key, { count: 1, firstAttemptAt: now, lockedUntil: null });
+    return { allowed: true };
+  }
+
+  const nextCount = existing.count + 1;
+  if (nextCount >= FAILURE_THRESHOLD) {
+    const lockedUntil = now + LOCKOUT_MS;
+    attempts.set(key, {
+      count: nextCount,
+      firstAttemptAt: existing.firstAttemptAt,
+      lockedUntil,
+    });
+    return { allowed: false, retryAfterSeconds: Math.ceil(LOCKOUT_MS / 1000) };
+  }
+
+  attempts.set(key, {
+    count: nextCount,
+    firstAttemptAt: existing.firstAttemptAt,
+    lockedUntil: null,
+  });
+  return { allowed: true };
+}
+
+export function clearLoginAttempts(rawIp: string | null | undefined): void {
+  attempts.delete(clientKey(rawIp));
+}
+
+export function resetLoginGuardForTests(): void {
+  attempts.clear();
+}
+
+/** Test-only: current number of tracked IP entries. */
+export function getLoginGuardSizeForTests(): number {
+  return attempts.size;
+}
+
+export const LOGIN_GUARD_TUNABLES = Object.freeze({
+  WINDOW_MS,
+  LOCKOUT_MS,
+  FAILURE_THRESHOLD,
+});

package/src/server/authz/accessScopes.ts

@@ -0,0 +1,62 @@
+import { type AccessScope } from "@/lib/accessTokens/scopes";
+
+/**
+ * Required-scope inference for remote CLI access tokens.
+ *
+ * Policy (owner-confirmed 2026-06-19): infer from HTTP method —
+ *   - GET/HEAD/OPTIONS → read
+ *   - POST/PUT/PATCH/DELETE → write
+ * with two admin overrides:
+ *   - ADMIN_SCOPE_PREFIXES: admin for ANY method (inherently sensitive surfaces).
+ *   - ADMIN_MUTATION_PREFIXES: admin only when mutating; GET/HEAD stay read so a
+ *     `read` token can still inspect status under these prefixes.
+ *
+ * This covers every existing management route with zero per-route edits. A NEW
+ * mutating route nasce exigindo `write` por padrão (não `admin`) — quando uma
+ * rota nova for sensível, adicione seu prefixo a uma das listas abaixo.
+ *
+ * Note: this only governs the access-token credential path. Dashboard JWT, the
+ * loopback CLI machine-id token, and manage-scope API keys remain full-access.
+ * Loopback-only routes that spawn processes are blocked before auth regardless.
+ */
+
+/** Sensitive management surfaces — require `admin` for ALL methods. */
+export const ADMIN_SCOPE_PREFIXES: readonly string[] = [
+  "/api/cli/tokens", // access-token management (create/list/revoke)
+  "/api/oauth", // OAuth authorization flows
+  "/api/auth", // login / logout / session
+  "/api/policy", // policy engine
+  "/api/services", // embedded-service lifecycle (also loopback-blocked)
+  "/api/mcp", // MCP process surface (also loopback-blocked)
+];
+
+/** Require `admin` only for mutating methods; GET/HEAD under these stay `read`. */
+export const ADMIN_MUTATION_PREFIXES: readonly string[] = [
+  "/api/providers", // POST add provider / rotate key = admin; GET status = read
+  "/api/cli-tools/apply", // writes config onto the host filesystem
+];
+
+const READ_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+
+function matchesPrefix(path: string, prefixes: readonly string[]): boolean {
+  // Exact match or a true path-segment boundary (`pre/...`). A bare
+  // `startsWith(pre)` would over-match lookalikes (e.g. "/api/auth" vs
+  // "/api/authz-inventory"), so it is intentionally NOT used.
+  return prefixes.some((pre) => path === pre || path.startsWith(pre + "/"));
+}
+
+/**
+ * Determine the minimum access-token scope required to call `method path`.
+ * Pure + deterministic — safe to unit test exhaustively.
+ */
+export function inferRequiredScope(method: string, path: string): AccessScope {
+  const m = (method || "GET").toUpperCase();
+  const p = path || "/";
+
+  if (matchesPrefix(p, ADMIN_SCOPE_PREFIXES)) return "admin";
+
+  const isMutation = !READ_METHODS.has(m);
+  if (isMutation && matchesPrefix(p, ADMIN_MUTATION_PREFIXES)) return "admin";
+
+  return isMutation ? "write" : "read";
+}

package/src/server/authz/accessTokenAuth.ts

@@ -0,0 +1,67 @@
+import { verifyAccessToken } from "@/lib/db/accessTokens";
+import { scopeSatisfies, type AccessScope } from "@/lib/accessTokens/scopes";
+import { inferRequiredScope } from "@/server/authz/accessScopes";
+
+/**
+ * Shared evaluation of a scoped CLI access token (`oma_...`) for remote mode.
+ *
+ * Used by BOTH the central authz pipeline (`managementPolicy` — the authoritative
+ * gate wired through `src/proxy.ts`) and the route-level `requireManagementAuth`
+ * (defense-in-depth + lets `/api/cli/whoami` learn its own scope). Keeping the
+ * logic here means the two gates can never drift.
+ *
+ * Returns a neutral verdict the caller maps to its own response shape
+ * (`allow()/reject()` in the policy, `null`/Response in requireManagementAuth).
+ */
+
+/** Prefix that distinguishes a CLI access token from an inference API key. */
+export const ACCESS_TOKEN_PREFIX = "oma_";
+
+export type AccessTokenVerdict =
+  | { kind: "absent" } // no oma_ bearer present → caller continues other auth paths
+  | { kind: "error" } // auth backend (DB) threw → 503, not an auth failure
+  | { kind: "invalid" } // oma_ present but unknown/expired/revoked → 401
+  | { kind: "insufficient"; have: AccessScope; need: AccessScope } // valid but scope too low → 403
+  | { kind: "ok"; scope: AccessScope; id: string; name: string }; // authorized → allow
+
+/** Read a Bearer token from the Authorization header (header-only; never URL). */
+export function extractBearer(request: Request): string | null {
+  const header = request.headers.get("authorization") || "";
+  const match = /^Bearer\s+(.+)$/i.exec(header.trim());
+  return match ? match[1].trim() : null;
+}
+
+function safePathname(url: string): string {
+  try {
+    return new URL(url).pathname;
+  } catch {
+    return "/";
+  }
+}
+
+/**
+ * Evaluate the request's access-token credential and required scope.
+ * Pure w.r.t. the request (only side effect is `verifyAccessToken` stamping
+ * `last_used_at`). Never throws — DB failures surface as `{ kind: "error" }`.
+ */
+export function evaluateAccessTokenAuth(request: Request): AccessTokenVerdict {
+  const bearer = extractBearer(request);
+  if (!bearer || !bearer.startsWith(ACCESS_TOKEN_PREFIX)) {
+    return { kind: "absent" };
+  }
+
+  let verified: ReturnType<typeof verifyAccessToken>;
+  try {
+    verified = verifyAccessToken(bearer);
+  } catch {
+    return { kind: "error" };
+  }
+  if (!verified) return { kind: "invalid" };
+
+  const need = inferRequiredScope(request.method, safePathname(request.url));
+  if (!scopeSatisfies(verified.scope, need)) {
+    return { kind: "insufficient", have: verified.scope, need };
+  }
+
+  return { kind: "ok", scope: verified.scope, id: verified.id, name: verified.name };
+}

package/src/server/authz/assertAuth.ts

@@ -0,0 +1,88 @@
+import {
+  AUTHZ_HEADER_AUTH_ID,
+  AUTHZ_HEADER_AUTH_KIND,
+  AUTHZ_HEADER_AUTH_LABEL,
+  AUTHZ_HEADER_AUTH_SCOPES,
+  AUTHZ_HEADER_ROUTE_CLASS,
+} from "./headers";
+import type { AuthSubject, RouteClass } from "./types";
+
+export class AuthzAssertionError extends Error {
+  readonly status: number;
+  readonly code: string;
+
+  constructor(code: string, message: string, status = 500) {
+    super(message);
+    this.name = "AuthzAssertionError";
+    this.code = code;
+    this.status = status;
+  }
+}
+
+type HeaderSource = Headers | { get(name: string): string | null };
+
+function readHeader(source: HeaderSource, name: string): string | null {
+  return source.get(name) ?? null;
+}
+
+function isHeaderSource(value: unknown): value is HeaderSource {
+  if (value instanceof Headers) return true;
+  if (typeof value !== "object" || value === null) return false;
+  return typeof (value as { get?: unknown }).get === "function";
+}
+
+export function readSubjectFromHeaders(headers: HeaderSource): AuthSubject {
+  const kind = (readHeader(headers, AUTHZ_HEADER_AUTH_KIND) ?? "anonymous") as AuthSubject["kind"];
+  const id = readHeader(headers, AUTHZ_HEADER_AUTH_ID) ?? "anonymous";
+  const label = readHeader(headers, AUTHZ_HEADER_AUTH_LABEL) ?? undefined;
+  const rawScopes = readHeader(headers, AUTHZ_HEADER_AUTH_SCOPES);
+  const scopes = rawScopes
+    ? rawScopes
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean)
+    : [];
+  return { kind, id, label, scopes };
+}
+
+export function readRouteClassFromHeaders(headers: HeaderSource): RouteClass | null {
+  const raw = readHeader(headers, AUTHZ_HEADER_ROUTE_CLASS);
+  if (raw === "PUBLIC" || raw === "CLIENT_API" || raw === "MANAGEMENT") return raw;
+  return null;
+}
+
+export function assertAuth(
+  request: Request | { headers: HeaderSource },
+  expected: RouteClass
+): AuthSubject {
+  const headers = request.headers;
+
+  if (!isHeaderSource(headers)) {
+    throw new AuthzAssertionError("AUTHZ_INVALID_REQUEST", "Request headers are unavailable", 500);
+  }
+
+  const actualClass = readRouteClassFromHeaders(headers);
+  if (!actualClass) {
+    throw new AuthzAssertionError(
+      "AUTHZ_NOT_INITIALIZED",
+      "Request did not pass through the authz middleware",
+      500
+    );
+  }
+
+  if (actualClass !== expected) {
+    throw new AuthzAssertionError(
+      "AUTHZ_ROUTE_CLASS_MISMATCH",
+      `Expected ${expected} but got ${actualClass}`,
+      500
+    );
+  }
+
+  const subject = readSubjectFromHeaders(headers);
+
+  if (expected !== "PUBLIC" && subject.kind === "anonymous") {
+    throw new AuthzAssertionError("AUTHZ_UNAUTHENTICATED", "Authentication required", 401);
+  }
+
+  return subject;
+}

package/src/server/authz/classify.ts

@@ -0,0 +1,135 @@
+import {
+  PUBLIC_READONLY_API_ROUTE_PREFIXES,
+  PUBLIC_READONLY_METHODS,
+  isPublicApiRoute,
+} from "../../shared/constants/publicApiRoutes";
+import type { ClassificationReason, RouteClassification } from "./types";
+
+const CLIENT_API_ALIAS_PREFIXES: ReadonlyArray<{ alias: string; canonical: string }> = [
+  { alias: "/chat/completions", canonical: "/api/v1/chat/completions" },
+  { alias: "/responses", canonical: "/api/v1/responses" },
+  { alias: "/models", canonical: "/api/v1/models" },
+];
+
+function normalizePathname(rawPath: string): { path: string; reason?: ClassificationReason } {
+  let path = rawPath || "/";
+  if (!path.startsWith("/")) path = "/" + path;
+  if (path.length > 1 && path.endsWith("/")) path = path.slice(0, -1);
+
+  if (path === "/codex" || path.startsWith("/codex/")) {
+    return { path: "/api/v1/responses", reason: "client_api_codex_alias" };
+  }
+
+  if (path === "/v1/v1" || path.startsWith("/v1/v1/")) {
+    const tail = path.slice("/v1/v1".length) || "";
+    return { path: "/api/v1" + tail, reason: "client_api_double_prefix" };
+  }
+
+  if (path === "/v1beta" || path.startsWith("/v1beta/")) {
+    const tail = path.slice("/v1beta".length) || "";
+    return { path: "/api/v1beta" + tail, reason: "client_api_alias" };
+  }
+
+  if (path === "/v1" || path.startsWith("/v1/")) {
+    const tail = path.slice("/v1".length) || "";
+    return { path: "/api/v1" + tail, reason: "client_api_alias" };
+  }
+
+  for (const { alias, canonical } of CLIENT_API_ALIAS_PREFIXES) {
+    if (path === alias) {
+      return { path: canonical, reason: "client_api_alias" };
+    }
+    if (path.startsWith(alias + "/")) {
+      return { path: canonical + path.slice(alias.length), reason: "client_api_alias" };
+    }
+  }
+
+  return { path };
+}
+
+export function classifyRoute(rawPath: string, method: string = "GET"): RouteClassification {
+  const { path: normalizedPath, reason: aliasReason } = normalizePathname(rawPath);
+
+  if (normalizedPath === "/" || normalizedPath === "") {
+    return {
+      routeClass: "MANAGEMENT",
+      reason: "root_redirect",
+      normalizedPath: "/",
+    };
+  }
+
+  if (normalizedPath === "/dashboard/onboarding") {
+    return {
+      routeClass: "PUBLIC",
+      reason: "setup_wizard",
+      normalizedPath,
+    };
+  }
+
+  // Public, ticket-gated device-flow connect pages (e.g. /connect/codex/{token}).
+  // Anyone with the shared link completes the provider login in their own browser.
+  if (normalizedPath === "/connect" || normalizedPath.startsWith("/connect/")) {
+    return {
+      routeClass: "PUBLIC",
+      reason: "public_connect_page",
+      normalizedPath,
+    };
+  }
+
+  if (normalizedPath.startsWith("/dashboard")) {
+    return {
+      routeClass: "MANAGEMENT",
+      reason: "dashboard_prefix",
+      normalizedPath,
+    };
+  }
+
+  if (normalizedPath === "/api/v1" || normalizedPath.startsWith("/api/v1/")) {
+    return {
+      routeClass: "CLIENT_API",
+      reason: aliasReason ?? "client_api_v1",
+      normalizedPath,
+    };
+  }
+
+  if (normalizedPath === "/api/v1beta" || normalizedPath.startsWith("/api/v1beta/")) {
+    return {
+      routeClass: "CLIENT_API",
+      reason: aliasReason ?? "client_api_v1",
+      normalizedPath,
+    };
+  }
+
+  if (normalizedPath.startsWith("/api/")) {
+    if (isClassifiedAsPublic(normalizedPath, method)) {
+      return {
+        routeClass: "PUBLIC",
+        reason: matchesReadonlyPublic(normalizedPath, method)
+          ? "public_readonly_prefix"
+          : "public_prefix",
+        normalizedPath,
+      };
+    }
+
+    return {
+      routeClass: "MANAGEMENT",
+      reason: "management_api",
+      normalizedPath,
+    };
+  }
+
+  return {
+    routeClass: "MANAGEMENT",
+    reason: "fallback_management",
+    normalizedPath,
+  };
+}
+
+function matchesReadonlyPublic(path: string, method: string): boolean {
+  if (!PUBLIC_READONLY_METHODS.has(String(method).toUpperCase())) return false;
+  return PUBLIC_READONLY_API_ROUTE_PREFIXES.some((p) => path.startsWith(p));
+}
+
+function isClassifiedAsPublic(path: string, method: string): boolean {
+  return isPublicApiRoute(path, method);
+}

package/src/server/authz/context.ts

@@ -0,0 +1,44 @@
+import type { AuthSubject, RouteClass, RouteClassification } from "./types";
+
+export interface AuthDecision {
+  allow: true;
+  subject: AuthSubject;
+}
+
+export interface AuthRejection {
+  allow: false;
+  status: number;
+  code: string;
+  message: string;
+}
+
+export type AuthOutcome = AuthDecision | AuthRejection;
+
+export interface RequestLike {
+  method: string;
+  headers: Headers;
+  cookies?: { get?: (name: string) => { value?: string } | undefined };
+  nextUrl?: { pathname?: string | null } | null;
+  url?: string;
+  ip?: string;
+  socket?: { remoteAddress?: string };
+}
+
+export interface PolicyContext {
+  request: RequestLike;
+  classification: RouteClassification;
+  requestId: string;
+}
+
+export interface RoutePolicy {
+  readonly routeClass: RouteClass;
+  evaluate(ctx: PolicyContext): Promise<AuthOutcome>;
+}
+
+export function allow(subject: AuthSubject): AuthDecision {
+  return { allow: true, subject };
+}
+
+export function reject(status: number, code: string, message: string): AuthRejection {
+  return { allow: false, status, code, message };
+}

package/src/server/authz/csrf.ts

@@ -0,0 +1,85 @@
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+
+import { DASHBOARD_CSRF_HEADER } from "@/shared/constants/dashboardCsrf";
+
+const TOKEN_VERSION = "v1";
+const TOKEN_TTL_SECONDS = 10 * 60;
+const TOKEN_CONTEXT = "omniroute-dashboard-csrf-v1";
+
+export interface DashboardCsrfToken {
+  token: string;
+  expiresAt: string;
+}
+
+function getJwtSecret(): Buffer | null {
+  const secret = process.env.JWT_SECRET?.trim();
+  return secret ? Buffer.from(secret, "utf8") : null;
+}
+
+function getCookieValue(request: Request, name: string): string | null {
+  const cookieHeader = request.headers.get("cookie") || request.headers.get("Cookie");
+  if (!cookieHeader) return null;
+
+  for (const segment of cookieHeader.split(";")) {
+    const [rawKey, ...rawValue] = segment.split("=");
+    if (!rawKey || rawValue.length === 0) continue;
+    if (rawKey.trim() === name) return rawValue.join("=").trim() || null;
+  }
+
+  return null;
+}
+
+function sessionHash(authToken: string): string {
+  return createHash("sha256").update(authToken).digest("base64url");
+}
+
+function csrfMac(secret: Buffer, expiresAtSeconds: number, authToken: string): Buffer {
+  return createHmac("sha256", secret)
+    .update(TOKEN_CONTEXT)
+    .update("\n")
+    .update(String(expiresAtSeconds))
+    .update("\n")
+    .update(sessionHash(authToken))
+    .digest();
+}
+
+export function issueDashboardCsrfToken(
+  request: Request,
+  nowMs: number = Date.now()
+): DashboardCsrfToken | null {
+  const secret = getJwtSecret();
+  const authToken = getCookieValue(request, "auth_token");
+  if (!secret || !authToken) return null;
+
+  const expiresAtSeconds = Math.floor(nowMs / 1000) + TOKEN_TTL_SECONDS;
+  const mac = csrfMac(secret, expiresAtSeconds, authToken).toString("base64url");
+
+  return {
+    token: `${TOKEN_VERSION}.${expiresAtSeconds}.${mac}`,
+    expiresAt: new Date(expiresAtSeconds * 1000).toISOString(),
+  };
+}
+
+export function validateDashboardCsrfToken(request: Request, nowMs: number = Date.now()): boolean {
+  const secret = getJwtSecret();
+  const authToken = getCookieValue(request, "auth_token");
+  const rawToken = request.headers.get(DASHBOARD_CSRF_HEADER);
+  if (!secret || !authToken || !rawToken) return false;
+
+  const [version, rawExpiresAt, rawMac, ...extra] = rawToken.split(".");
+  if (extra.length > 0 || version !== TOKEN_VERSION || !rawExpiresAt || !rawMac) return false;
+
+  const expiresAtSeconds = Number(rawExpiresAt);
+  const nowSeconds = Math.floor(nowMs / 1000);
+  if (!Number.isSafeInteger(expiresAtSeconds) || expiresAtSeconds < nowSeconds) return false;
+
+  let providedMac: Buffer;
+  try {
+    providedMac = Buffer.from(rawMac, "base64url");
+  } catch {
+    return false;
+  }
+
+  const expectedMac = csrfMac(secret, expiresAtSeconds, authToken);
+  return providedMac.length === expectedMac.length && timingSafeEqual(providedMac, expectedMac);
+}

package/src/server/authz/headers.ts

@@ -0,0 +1,76 @@
+/**
+ * Header constants used by the authz pipeline.
+ *
+ * Middleware adds these headers to the upstream request after a successful
+ * auth decision. Route handlers and downstream services read them through
+ * the assertAuth() helper instead of re-running auth logic.
+ *
+ * All header names are lowercase to match Next.js / fetch semantics.
+ *
+ * IMPORTANT: these headers are stripped from incoming client requests
+ * before classification (see pipeline.ts) so a remote caller cannot
+ * pre-populate them and impersonate a privileged subject.
+ */
+
+export const AUTHZ_HEADER_REQUEST_ID = "x-request-id";
+
+export const AUTHZ_HEADER_ROUTE_CLASS = "x-omniroute-route-class";
+
+export const AUTHZ_HEADER_AUTH_KIND = "x-omniroute-auth-kind";
+export const AUTHZ_HEADER_AUTH_ID = "x-omniroute-auth-id";
+export const AUTHZ_HEADER_AUTH_LABEL = "x-omniroute-auth-label";
+export const AUTHZ_HEADER_AUTH_SCOPES = "x-omniroute-auth-scopes";
+
+/** CLI sends this header so the local process can call management APIs without login. */
+export const CLI_TOKEN_HEADER = "x-omniroute-cli-token";
+
+/**
+ * The real TCP peer IP, stamped by the custom Node server BEFORE Next runs
+ * (scripts/dev/peer-stamp.mjs), formatted as `<token>|<ip>`. The middleware has
+ * no socket, so this is the only trustworthy locality signal — but ONLY when the
+ * token matches this process's OMNIROUTE_PEER_STAMP_TOKEN (see
+ * policies/management.ts → resolveStampedPeer). Any client-supplied value is
+ * deleted by the server before stamping, and this header is stripped from the
+ * forwarded request in pipeline.ts so it never reaches route handlers/upstream.
+ * NEVER decide locality from the Host header — it is fully client-controlled.
+ * Keep in sync with PEER_IP_HEADER in scripts/dev/peer-stamp.mjs.
+ */
+export const PEER_IP_HEADER = "x-omniroute-peer-ip";
+
+/**
+ * Trusted "request arrived via a reverse proxy" marker stamped by the custom
+ * Node server alongside PEER_IP_HEADER, formatted as `<token>|1` when the
+ * inbound TCP request carried forwarding headers (`x-forwarded-for` /
+ * `x-real-ip`) and `<token>|0` otherwise. The middleware combines this with
+ * the stamped peer IP so a loopback / private-LAN socket that is actually the
+ * proxy hop (e.g. OmniRoute behind nginx / Caddy / Cloudflare Tunnel) is NOT
+ * trusted as local — closing the upstream da667836 vulnerability that would
+ * otherwise let a leaked JWT over a public tunnel reach LOCAL_ONLY routes
+ * that spawn child processes. Token-validated like PEER_IP_HEADER, so a
+ * remote caller cannot forge it. Stripped from forwarded headers before
+ * route handlers see it.
+ * Keep in sync with VIA_PROXY_HEADER in scripts/dev/peer-stamp.mjs.
+ */
+export const VIA_PROXY_HEADER = "x-omniroute-via-proxy";
+
+/**
+ * Trusted locality verdict ("loopback" | "lan" | "remote") that the pipeline
+ * computes from the stamped real peer IP and forwards to route handlers. Route
+ * code (e.g. cliTokenAuth) reads THIS instead of re-deriving locality from the
+ * spoofable Host header. Like the other trusted headers it is stripped from
+ * client input and re-set by the pipeline, so a remote caller cannot forge it.
+ */
+export const AUTHZ_HEADER_PEER_LOCALITY = "x-omniroute-peer-locality";
+
+/**
+ * Headers the pipeline must NEVER trust on incoming requests. They are
+ * stripped before route classification to prevent header-spoofing attacks.
+ */
+export const AUTHZ_TRUSTED_HEADERS: ReadonlyArray<string> = [
+  AUTHZ_HEADER_ROUTE_CLASS,
+  AUTHZ_HEADER_AUTH_KIND,
+  AUTHZ_HEADER_AUTH_ID,
+  AUTHZ_HEADER_AUTH_LABEL,
+  AUTHZ_HEADER_AUTH_SCOPES,
+  AUTHZ_HEADER_PEER_LOCALITY,
+];