Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

7.6 KB
Raw Blame
import type { IncomingMessage } from 'node:http';
import type { ClientSurfaceReading, ServerRuntimeConfig } from '@inkeep/open-knowledge-core';
import { isAllowedApiOrigin, isOpaqueOrigin, isSafeMethod } from './api-origin.ts';
import type { PinoLogger } from './logger.ts';
import { isAllowedWorkspaceHostHeader, isLoopbackAddress } from './loopback.ts';

export function normalizeHostHeader(host: string): string {
  return host.replace(/:(443|80)$/, '').toLowerCase();
}

export function hostHeaderMatchesExternalHost(
  host: string | undefined,
  externalHost: string,
): boolean {
  return host !== undefined && normalizeHostHeader(host) === externalHost;
}

const FORWARDING_HEADERS = [
  'x-forwarded-for',
  'x-forwarded-proto',
  'x-forwarded-host',
  'forwarded',
  'x-real-ip',
  'x-client-ip',
  'x-cluster-client-ip',
  'cf-connecting-ip',
  'fastly-client-ip',
  'true-client-ip',
] as const;

export function hasForwardingHeaders(req: Pick<IncomingMessage, 'headers'>): boolean {
  return FORWARDING_HEADERS.some((h) => req.headers[h] !== undefined);
}

export const HOST_NOT_ADMITTED_REMEDIATION =
  'Add this host to server.bind or set server.externalUrl to it, then restart. Loopback (localhost/127.0.0.1/[::1]) is always admitted.';

export interface IngressPolicy {
  allowExternal: boolean;
  bindLiterals: readonly string[];
  externalOrigin: { host: string; protocol: string } | undefined;
  tolerateForwardedHeaders: boolean;
}

export class ExposureConsentError extends Error {}

export interface BuildIngressPolicyInput {
  serverRuntime?: ServerRuntimeConfig | undefined;
}

const NON_NAMEABLE_BINDS = new Set(['0.0.0.0', '::', 'localhost', '::1', '[::1]']);

function normalizeBindLiteral(address: string): string {
  const trimmed = address.trim().toLowerCase();
  return trimmed.startsWith('[') && trimmed.endsWith(']') ? trimmed.slice(1, -1) : trimmed;
}

export function buildIngressPolicy(input: BuildIngressPolicyInput): IngressPolicy {
  const runtime = input.serverRuntime;

  const bindLiterals =
    runtime === undefined
      ? []
      : runtime.bind
          .map(normalizeBindLiteral)
          .filter((addr) => !NON_NAMEABLE_BINDS.has(addr) && !addr.startsWith('127.'));

  let externalOrigin: IngressPolicy['externalOrigin'];
  if (runtime?.externalUrl !== undefined) {
    const parsed = new URL(runtime.externalUrl);
    externalOrigin = { host: normalizeHostHeader(parsed.host), protocol: parsed.protocol };
  }

  const allowExternal = runtime?.allowExternal === true;
  return {
    allowExternal,
    bindLiterals,
    externalOrigin,
    tolerateForwardedHeaders: allowExternal && externalOrigin !== undefined,
  };
}

export function isPeerAdmitted(remoteAddress: string | undefined, policy: IngressPolicy): boolean {
  if (isLoopbackAddress(remoteAddress)) return true;
  return policy.allowExternal && remoteAddress !== undefined;
}

function hostnameOfHostHeader(host: string): string | null {
  if (host.startsWith('[')) {
    const close = host.indexOf(']');
    if (close < 0) return null;
    return host.slice(1, close).toLowerCase();
  }
  const colon = host.lastIndexOf(':');
  return (colon >= 0 ? host.slice(0, colon) : host).toLowerCase();
}

export function isHostAdmitted(host: string | undefined, policy: IngressPolicy): boolean {
  if (isAllowedWorkspaceHostHeader(host)) return true;
  if (host === undefined) return false;
  if (policy.bindLiterals.length > 0) {
    const hostname = hostnameOfHostHeader(host);
    if (hostname !== null && policy.bindLiterals.includes(hostname)) return true;
  }
  return (
    policy.externalOrigin !== undefined &&
    hostHeaderMatchesExternalHost(host, policy.externalOrigin.host)
  );
}

export function isOriginAdmitted(origin: string, policy: IngressPolicy): boolean {
  if (isAllowedApiOrigin(origin)) return true;
  let parsed: URL;
  try {
    parsed = new URL(origin);
  } catch {
    return false;
  }
  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return false;
  if (
    policy.externalOrigin !== undefined &&
    parsed.protocol === policy.externalOrigin.protocol &&
    normalizeHostHeader(parsed.host) === policy.externalOrigin.host
  ) {
    return true;
  }
  if (policy.bindLiterals.length > 0) {
    const hostname = normalizeBindLiteral(parsed.hostname);
    if (policy.bindLiterals.includes(hostname)) return true;
  }
  return false;
}

export const OPAQUE_ORIGIN_REFUSAL_DETAIL =
  'Requests from a null origin, and writes from a file: origin, are refused. Send the request from a loopback page, the OpenKnowledge app, or a client that sends no Origin header.';

export type OriginAdmission =
  | { readonly admitted: true; readonly corsGrant: boolean }
  | { readonly admitted: false; readonly detail: string | undefined };

export function admitRequestOrigin(
  origin: string | undefined,
  method: string | undefined,
  policy: IngressPolicy,
): OriginAdmission {
  if (origin === undefined) return { admitted: true, corsGrant: true };
  const opaque = isOpaqueOrigin(origin);
  if (!isOriginAdmitted(origin, policy) || (opaque && !isSafeMethod(method))) {
    return { admitted: false, detail: opaque ? OPAQUE_ORIGIN_REFUSAL_DETAIL : undefined };
  }
  return { admitted: true, corsGrant: !opaque };
}

export function tripsForwardedHeaderTripwire(
  req: Pick<IncomingMessage, 'headers'>,
  policy: IngressPolicy,
): boolean {
  return !policy.tolerateForwardedHeaders && hasForwardingHeaders(req);
}

export type ForwardedRefusalCaller =
  | 'mcp-mount'
  | 'native-api-surface'
  | 'native-mcp-surface'
  | 'collab-upgrade'
  | 'ws-upgrade';

let warnedForwardedHeaderRefusal = false;

export function __resetWarnedForwardedHeaderRefusalForTests(): void {
  warnedForwardedHeaderRefusal = false;
}

export function warnForwardedHeaderRefusalOnce(
  log: PinoLogger,
  handler: ForwardedRefusalCaller,
): void {
  if (warnedForwardedHeaderRefusal) return;
  warnedForwardedHeaderRefusal = true;
  log.warn(
    { handler },
    '[ingress] refused a request carrying a forwarding header (X-Forwarded-For etc.) — without external-exposure consent, every surface except the /healthz + /readyz probes refuses proxied requests (APIs 403, /collab upgrades dropped). To front this server with a proxy, set server.externalUrl to the public origin in .ok/config.yml (or OK_EXTERNAL_URL) AND consent with server.allowExternal: true in .ok/local/config.yml (or OK_ALLOW_EXTERNAL=1) — the keys live in different files because consent is per-machine and never travels. allowExternal consents to exposure on a server with NO authentication — restrict access at the edge. Removing server.externalUrl does not lift this refusal (it fires on the header, not the URL) and would un-admit that Host/Origin everywhere else. Warned once per process; every refusal is still logged at warn level (HTTP refusals additionally as api.error, counted in ok.api.error.count).',
  );
}

export interface IngressRequestContext {
  requestId: string | undefined;
  peerClass: 'loopback' | 'external' | 'unknown';
  clientSurface: ClientSurfaceReading;
  actor: undefined;
}

const ingressContexts = new WeakMap<IncomingMessage, IngressRequestContext>();

export function stampIngressContext(
  req: IncomingMessage,
  input: { requestId?: string | undefined; clientSurface?: ClientSurfaceReading },
): IngressRequestContext {
  const peer = req.socket?.remoteAddress;
  const context: IngressRequestContext = {
    requestId: input.requestId,
    peerClass: peer === undefined ? 'unknown' : isLoopbackAddress(peer) ? 'loopback' : 'external',
    clientSurface: input.clientSurface,
    actor: undefined,
  };
  ingressContexts.set(req, context);
  return context;
}

export function getIngressContext(req: IncomingMessage): IngressRequestContext | undefined {
  return ingressContexts.get(req);
}