Skip to content

Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors

20.6 KB
Raw Blame
/**
 * API Authentication Guard — Shared utility for protecting API routes.
 *
 * Management APIs require a dashboard session, while client-facing APIs may still
 * accept Bearer API keys. Route scope is inferred from the request pathname.
 *
 * @module shared/utils/apiAuth
 */

import { getOrCreateBootstrapToken, peekBootstrapToken } from "@/lib/auth/bootstrapToken";
import { getSettings } from "@/lib/db/settings";
import {
  AUTHZ_HEADER_PEER_LOCALITY,
  BOOTSTRAP_TOKEN_HEADER,
  PEER_IP_HEADER,
  VIA_PROXY_HEADER,
} from "@/server/authz/headers";
import { classifyStampedPeerLocality } from "@/server/authz/peerStamp";
import { classifyHostLocality } from "@/server/authz/routeGuard";
import { isPublicApiRoute } from "@/shared/constants/publicApiRoutes";
import {
  verifyDashboardSessionToken,
  DASHBOARD_SESSION_COOKIE,
} from "@/shared/utils/dashboardSessionToken";
import { extractApiKey } from "@/sse/services/auth";

type RequestLike = {
  cookies?: {
    get?: (name: string) => { value?: string } | undefined;
  };
  headers?: Headers;
  method?: string;
  nextUrl?: { hostname?: string | null; pathname?: string | null } | null;
  url?: string;
  /** Real socket peer, present only for direct Node / test callers (never in the proxy runtime). */
  ip?: string;
  socket?: { remoteAddress?: string };
};

export interface AuthRequiredOptions {
  /**
   * Pre-resolved trusted peer verdict. The authz policy layer already resolves
   * locality from the token-stamped real TCP peer (`peerContext.isLoopbackRequest`)
   * and hands it down, so the bootstrap gate never re-derives it from headers on
   * the ORIGINAL (pre-strip) request — where a client-supplied copy of the
   * pipeline's own locality header could still be present.
   */
  loopback?: boolean;
  /**
   * Judge a public-classified path as if it were a management path. A public route
   * that does its own management check (`requireManagementAuth`) must not inherit the
   * "public, no auth needed" shortcut of the fresh-install window, or a remote caller
   * passes the check before a password exists.
   */
  ignorePublicRoute?: boolean;
}

export function hasConfiguredPassword(settings: Record<string, unknown>): boolean {
  return typeof settings.password === "string" && settings.password.length > 0;
}
export function hasConfiguredOidc(settings: Record<string, unknown>): boolean {
  return (
    settings.oidcEnabled === true &&
    typeof settings.oidcIssuer === "string" &&
    settings.oidcIssuer.trim().length > 0 &&
    typeof settings.oidcClientId === "string" &&
    settings.oidcClientId.trim().length > 0 &&
    typeof settings.oidcClientSecret === "string" &&
    settings.oidcClientSecret.trim().length > 0
  );
}

function getRequestPathname(request: RequestLike | Request | null | undefined): string | null {
  const nextPathname =
    request &&
    typeof request === "object" &&
    "nextUrl" in request &&
    request.nextUrl &&
    typeof request.nextUrl.pathname === "string"
      ? request.nextUrl.pathname
      : null;

  if (nextPathname) return nextPathname;

  const rawUrl =
    request && typeof request === "object" && "url" in request && typeof request.url === "string"
      ? request.url
      : "";

  if (!rawUrl) return null;

  try {
    return new URL(rawUrl, "http://localhost").pathname;
  } catch {
    return null;
  }
}

function isOnboardingBootstrapPath(pathname: string | null): boolean {
  return pathname === "/dashboard/onboarding";
}

function isRequireLoginBootstrapWritePath(pathname: string | null, method: string): boolean {
  return pathname === "/api/settings/require-login" && method.toUpperCase() === "POST";
}

/**
 * #14296: a non-loopback caller (typically a Docker/NAT-forwarded local
 * operator — see docs at the top of bootstrapToken.ts) may still complete
 * the fresh-install bootstrap window by presenting the one-shot token
 * printed to the process log. Never widens `isLoopbackRequest` itself —
 * this is an alternate proof checked only for the require-login bootstrap
 * write above, and only a non-mutating peek (the route handler consumes/
 * invalidates the token once the write actually succeeds).
 */
function hasBootstrapToken(request: RequestLike | Request | null | undefined): boolean {
  const header = getHeaderValue(request, BOOTSTRAP_TOKEN_HEADER);
  return peekBootstrapToken(header);
}

/**
 * #14296: resolves whether the onboarding bootstrap write (require-login
 * POST) should stay open for this request.
 * Extracted out of isAuthRequired() to keep that function's branching flat —
 * this helper owns the loopback-or-token decision on its own.
 *
 * A loopback caller is always exempt. A non-loopback caller (e.g. a
 * Docker/NAT-forwarded local operator) is exempt ONLY with a valid one-shot
 * bootstrap token; otherwise a token is minted/announced to the process log
 * and auth stays required.
 */
function isBootstrapWriteExempt(
  request: RequestLike | Request | null | undefined,
  loopback: boolean
): boolean {
  if (loopback) return true;
  if (hasBootstrapToken(request)) return true;
  // No (or a stale/consumed) token — mint/announce one so an operator
  // watching the log can retrieve it, and keep requiring auth.
  getOrCreateBootstrapToken();
  return false;
}

function getRequestMethod(request: RequestLike | Request | null | undefined): string {
  if (
    request &&
    typeof request === "object" &&
    "method" in request &&
    typeof request.method === "string"
  ) {
    return request.method.toUpperCase();
  }
  return "GET";
}

function getHeaderValue(
  request: RequestLike | Request | null | undefined,
  name: string
): string | null {
  const requestHeaders =
    request && typeof request === "object" && "headers" in request ? request.headers : undefined;
  return requestHeaders?.get?.(name) ?? null;
}

function getSocketPeerAddress(request: RequestLike | Request | null | undefined): string | null {
  if (!request || typeof request !== "object") return null;
  const candidate = request as RequestLike;
  if (typeof candidate.ip === "string" && candidate.ip) return candidate.ip;
  const remoteAddress = candidate.socket?.remoteAddress;
  return typeof remoteAddress === "string" && remoteAddress ? remoteAddress : null;
}

/**
 * Trusted peer locality for the fresh-install bootstrap gate.
 *
 * NEVER derived from `Host` / `nextUrl.hostname` / the request URL — all three
 * are client-controlled, so a remote caller sending `Host: localhost` used to be
 * treated as the local operator (GHSA-7pq4-8pvv-rx7r). The verdict comes from
 * the same primitives the authz pipeline already trusts, in this order:
 *
 *   1. The token-stamped real TCP peer (`PEER_IP_HEADER` + `VIA_PROXY_HEADER`,
 *      written by the custom Node server from `req.socket.remoteAddress` after
 *      deleting any client-supplied value, validated against
 *      OMNIROUTE_PEER_STAMP_TOKEN). This is what the policy layer sees on the
 *      ORIGINAL request. A stamp present but failing validation → not loopback.
 *      A loopback socket flagged as a reverse-proxy hop → not loopback.
 *   2. The pipeline's own locality verdict (`AUTHZ_HEADER_PEER_LOCALITY`), which
 *      route handlers see after `runAuthzPipeline` stripped every client-supplied
 *      copy and re-stamped it from (1). Trusted only while the per-process stamp
 *      token exists — i.e. a stamping server is actually in front of Next, in
 *      which case every request that reached the policy carried (1) and this
 *      branch can only be the post-strip route-handler view.
 *   3. A real socket peer (`request.ip` / `request.socket.remoteAddress`) for
 *      direct Node / unit-test callers that never went through the pipeline.
 *      The proxy runtime exposes neither, so nothing here is client-reachable.
 *
 * Anything else → not loopback (fail closed), matching
 * `src/server/authz/peerContext.ts::isLoopbackRequest`.
 */
export function isLoopbackRequest(request: RequestLike | Request | null | undefined): boolean {
  return getRequestPeerLocality(request) === "loopback";
}

/**
 * Trusted three-way locality of the caller — the same signals and order as
 * `isLoopbackRequest()` above, but keeping the LAN verdict so route handlers can apply
 * the LOCAL_ONLY semantics (loopback OR private LAN, never via a reverse proxy) to a
 * single capability inside a route that stays reachable remotely. Fails closed to
 * "remote".
 */
export function getRequestPeerLocality(
  request: RequestLike | Request | null | undefined
): "loopback" | "lan" | "remote" {
  if (!request || typeof request !== "object") return "remote";

  const stampToken = process.env.OMNIROUTE_PEER_STAMP_TOKEN;

  const stampedPeer = getHeaderValue(request, PEER_IP_HEADER);
  if (stampedPeer !== null) {
    return classifyStampedPeerLocality(
      stampedPeer,
      getHeaderValue(request, VIA_PROXY_HEADER),
      stampToken
    );
  }

  const pipelineVerdict = getHeaderValue(request, AUTHZ_HEADER_PEER_LOCALITY);
  if (pipelineVerdict !== null && stampToken) {
    return pipelineVerdict === "loopback" || pipelineVerdict === "lan" ? pipelineVerdict : "remote";
  }

  const socketPeer = getSocketPeerAddress(request);
  if (socketPeer) return classifyHostLocality(socketPeer);

  // A stamping server is in front (every supported runtime — run-next dev/start and
  // standalone-server-ws for Docker, the npm CLI and Electron — calls
  // ensurePeerStampToken() at boot) but neither trusted signal is on this request:
  // fail closed. The Host header is never consulted in that process.
  if (stampToken) return "remote";

  // No stamping server in this process at all: route handlers invoked directly (the
  // unit-test harness) or a raw `next` launch that also bypasses every LOCAL_ONLY
  // gate in peerContext. There is no real peer to read, so keep the historical
  // URL/Host verdict rather than turning every direct handler call into a remote one.
  return isLegacyHostLoopback(request) ? "loopback" : "remote";
}

function isLegacyHostLoopback(request: RequestLike | Request): boolean {
  let hostname: string | null = null;
  const candidate = request as RequestLike;
  if (candidate.nextUrl && typeof candidate.nextUrl.hostname === "string") {
    hostname = candidate.nextUrl.hostname;
  } else if (typeof candidate.url === "string" && candidate.url) {
    try {
      hostname = new URL(candidate.url, "http://localhost").hostname;
    } catch {
      hostname = null;
    }
  }
  if (!hostname) {
    const host = getHeaderValue(request, "host");
    if (!host) return false;
    try {
      hostname = new URL(`http://${host}`).hostname;
    } catch {
      hostname = host.split(":")[0] || null;
    }
  }
  if (!hostname) return false;
  const normalized = hostname
    .trim()
    .toLowerCase()
    .replace(/^\[(.*)\]$/, "$1");
  return (
    normalized === "localhost" || normalized === "::1" || /^127(?:\.\d{1,3}){3}$/.test(normalized)
  );
}

function getCookieValueFromHeader(headers: Headers | undefined, name: string): string | null {
  const cookieHeader = headers?.get("cookie") || 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) continue;
    return rawValue.join("=").trim();
  }

  return null;
}

function getRequestApiKey(
  request: RequestLike | Request | null | undefined,
  opts?: { allowUrl?: boolean }
): string | null {
  if (!request || typeof request !== "object") return null;

  const headers = "headers" in request ? request.headers : undefined;
  const rawUrl = "url" in request && typeof request.url === "string" ? request.url : null;
  const pathname = getRequestPathname(request);
  const syntheticUrl = rawUrl || (pathname ? `http://localhost${pathname}` : null);

  // Management auth never honours a URL-borne credential (defence-in-depth: the
  // path-scoped token is a client-API affordance only — a credential in the URL
  // must not authenticate a management route). See the #3300 security follow-up.
  const allowUrl = opts?.allowUrl !== false;

  return extractApiKey({ headers, url: allowUrl ? syntheticUrl : null }, { allowUrl });
}

async function validateBearerApiKey(apiKey: string | null): Promise<boolean> {
  if (!apiKey) return false;

  try {
    const { validateApiKey } = await import("@/lib/db/apiKeys");
    return await validateApiKey(apiKey);
  } catch {
    return false;
  }
}

/**
 * Check whether a Bearer API key is valid AND carries a scope that authorizes
 * it on management API routes (`/api/*` excluding `/api/v1/*` and the public
 * allowlist). Returns `false` for unscoped keys so that the existing
 * default-deny posture on management routes is preserved.
 *
 * Scope set is sourced from `@/shared/constants/managementScopes` so this
 * helper stays in lockstep with `requireManagementAuth.hasManageScope`.
 */
async function validateBearerApiKeyForManagement(apiKey: string | null): Promise<boolean> {
  if (!apiKey) return false;

  try {
    const [{ validateApiKey, getApiKeyMetadata }, { hasManageScope }] = await Promise.all([
      import("@/lib/db/apiKeys"),
      import("@/shared/constants/managementScopes"),
    ]);
    const valid = await validateApiKey(apiKey);
    if (!valid) return false;

    const metadata = await getApiKeyMetadata(apiKey);
    if (!metadata) return false;

    return hasManageScope(metadata.scopes);
  } catch {
    return false;
  }
}

/**
 * Whether the bearer key on this request holds `scope`, or a full management
 * scope. Used by the cache routes so a machine client with `read:cache` or
 * `write:cache` can reach them without a dashboard session (#14304). A key
 * with only one of those scopes does not pass `isAuthenticated`, which is
 * what keeps it out of every other management route.
 */
export async function isCacheScopedKey(request: Request, scope: string): Promise<boolean> {
  const apiKey = extractApiKey(request, { allowUrl: false });
  if (!apiKey) return false;
  try {
    const [{ validateApiKey, getApiKeyMetadata }, { hasCacheScope }] = await Promise.all([
      import("@/lib/db/apiKeys"),
      import("@/shared/constants/managementScopes"),
    ]);
    if (!(await validateApiKey(apiKey))) return false;
    const metadata = await getApiKeyMetadata(apiKey);
    if (!metadata) return false;
    return hasCacheScope(metadata.scopes, scope);
  } catch {
    return false;
  }
}

export function isManagementApiRequest(request: RequestLike | Request): boolean {
  const pathname = getRequestPathname(request);
  if (!pathname?.startsWith("/api/")) return false;
  if (pathname.startsWith("/api/v1/")) return false;
  return !isPublicApiRoute(pathname, getRequestMethod(request));
}

export async function isDashboardSessionAuthenticated(
  request?: RequestLike | Request | null
): Promise<boolean> {
  if (!process.env.JWT_SECRET) return false;

  let token =
    request &&
    typeof request === "object" &&
    "cookies" in request &&
    request.cookies?.get?.(DASHBOARD_SESSION_COOKIE)?.value
      ? request.cookies.get(DASHBOARD_SESSION_COOKIE)?.value || null
      : null;

  const requestHeaders =
    request && typeof request === "object" && "headers" in request ? request.headers : undefined;

  if (!token) {
    token = getCookieValueFromHeader(requestHeaders, DASHBOARD_SESSION_COOKIE);
  }

  if (!token) {
    try {
      // Lazy: `next/headers` only resolves inside the Next.js runtime. The MCP server
      // bundle now reaches this module through keyConnectionScope → comboTargetKeyPolicy
      // → apiKeyPolicy (#16499) and must stay importable on plain Node.
      const { cookies } = await import("next/headers");
      const cookieStore = await cookies();
      token = cookieStore.get(DASHBOARD_SESSION_COOKIE)?.value || null;
    } catch {
      token = null;
    }
  }

  if (!token) return false;

  return (await verifyDashboardSessionToken(token)) !== null;
}

// ──────────────── Auth Verification ────────────────

/**
 * Check if a request is authenticated.
 *
 * @returns null if authenticated, error message string if not
 */
export async function verifyAuth(request: any): Promise<string | null> {
  if (await isDashboardSessionAuthenticated(request)) {
    return null;
  }

  const isManagement = isManagementApiRequest(request);
  const apiKey = getRequestApiKey(request, { allowUrl: !isManagement });
  if (isManagement) {
    if (await validateBearerApiKeyForManagement(apiKey)) {
      return null;
    }
    return apiKey ? "Invalid management token" : "Authentication required";
  }

  if (await validateBearerApiKey(apiKey)) {
    return null;
  }

  return "Authentication required";
}

/**
 * Check if a request is authenticated — boolean convenience wrapper for route handlers.
 *
 * Uses `cookies()` from next/headers (App Router compatible) and Bearer API key.
 * Returns true if authenticated, false otherwise.
 *
 * Unlike `verifyAuth`, this does NOT check `isAuthRequired()` — callers that
 * need to conditionally skip auth should check that separately.
 */
export async function isAuthenticated(request: Request): Promise<boolean> {
  // If settings say login/auth is disabled, treat all requests as authenticated
  if (!(await isAuthRequired(request))) {
    return true;
  }

  if (await isDashboardSessionAuthenticated(request)) {
    return true;
  }

  const isManagement = isManagementApiRequest(request);
  const apiKey = getRequestApiKey(request, { allowUrl: !isManagement });
  if (isManagement) {
    return validateBearerApiKeyForManagement(apiKey);
  }

  return validateBearerApiKey(apiKey);
}

/**
 * Check if a route is in the public (no-auth) allowlist.
 */
export function isPublicRoute(pathname: string, method = "GET"): boolean {
  return isPublicApiRoute(pathname, method);
}

/**
 * Check if authentication is required based on settings.
 * If requireLogin is explicitly false, auth is skipped. Fresh installs without
 * a password keep their unauthenticated bootstrap path only on loopback
 * requests; exposed network requests must configure INITIAL_PASSWORD or log in.
 *
 * "Loopback" is the trusted peer verdict (`isLoopbackRequest` above, or the
 * policy-supplied `options.loopback`), never the Host header.
 */
export async function isAuthRequired(
  request?: RequestLike | Request | null | undefined,
  options?: AuthRequiredOptions
): Promise<boolean> {
  try {
    const settings = await getSettings();
    if (settings.requireLogin === false) return false;

    if (
      !hasConfiguredPassword(settings) &&
      !hasConfiguredOidc(settings) &&
      !process.env.INITIAL_PASSWORD
    ) {
      if (!request) return false;

      const pathname = getRequestPathname(request);
      const method = getRequestMethod(request);
      if (isOnboardingBootstrapPath(pathname)) {
        return false;
      }

      if (!options?.ignorePublicRoute && pathname && isPublicApiRoute(pathname, method)) {
        return false;
      }

      const loopback = options?.loopback ?? isLoopbackRequest(request);

      // The first-password write is the switch that disarms every other guard
      // (requireLogin=false makes isAuthenticated() true everywhere), so it is
      // the one bootstrap path that MUST honour the loopback constraint — it
      // used to be an unconditional `return false`, open to any network peer
      // during the window (GHSA-7pq4-8pvv-rx7r). It stays open for the local
      // operator even after onboarding completed without a password.
      //
      // #14296: a non-loopback caller here is NOT automatically the remote
      // attacker GHSA-7pq4-8pvv-rx7r closed — it may be a Docker/NAT-forwarded
      // local operator whose peer is the docker0 bridge gateway, never
      // 127.0.0.1. Owner decision: never reclassify that peer as loopback
      // (it is indistinguishable from any other client of the published
      // port); instead accept the one-shot bootstrap token printed to the
      // process log as an alternate proof for this write only. The general
      // `PATCH /api/settings` is deliberately NOT token-reachable: it accepts
      // any settings key, and the wizard never needs it — the skip-password
      // path writes requireLogin=false first (auth then off install-wide by
      // design, #574) and the password path logs in and carries a session.
      if (isRequireLoginBootstrapWritePath(pathname, method)) {
        return !isBootstrapWriteExempt(request, loopback);
      }

      return settings.setupComplete === true || !loopback;
    }

    return true;
  } catch (error: any) {
    // On error, require auth (secure by default)
    // Log the error so failures (e.g., SQLITE_BUSY) aren't silent 401s
    console.error(
      "[API_AUTH_GUARD] isAuthRequired failed, defaulting to true:",
      error?.message || error
    );
    return true;
  }
}