@opengeni/api-router 0.30.3 → 1.0.0

package/src/http/metrics-listener.ts

@@ -0,0 +1,57 @@
+import type { Settings } from "@opengeni/config";
+import { Hono } from "hono";
+
+import { requireAccessKey } from "./auth";
+
+type PrometheusSource = { prometheusMetrics(): Promise<string> };
+
+/** Register the Prometheus exposition route on one Hono app. */
+export function registerPrometheusMetricsRoute(app: Hono, observability: PrometheusSource): void {
+  app.get("/metrics", async (c) =>
+    c.text(await observability.prometheusMetrics(), 200, {
+      "content-type": "text/plain; version=0.0.4; charset=utf-8",
+    }),
+  );
+}
+
+/**
+ * Whether the public API listener serves `GET /metrics`. A deployment that sets
+ * `OPENGENI_API_METRICS_PORT` moves the exposition to a dedicated internal
+ * listener, so an ingress that forwards every path to the API cannot publish it.
+ */
+export function publicListenerServesMetrics(settings: Pick<Settings, "apiMetricsPort">): boolean {
+  return settings.apiMetricsPort === undefined;
+}
+
+/**
+ * The dedicated metrics listener: only `GET /metrics`, behind the same
+ * deployment-key perimeter rules as the public listener. Nothing else is
+ * routed here, so exposing this port to a scraper exposes nothing else.
+ */
+export function createMetricsListenerApp(
+  settings: Settings,
+  observability: PrometheusSource,
+): Hono {
+  const app = new Hono();
+  app.use("*", requireAccessKey(settings));
+  registerPrometheusMetricsRoute(app, observability);
+  return app;
+}
+
+/** Start the dedicated listener when configured; returns undefined otherwise. */
+export function startApiMetricsListener(
+  settings: Settings,
+  observability: PrometheusSource,
+): ReturnType<typeof Bun.serve> | undefined {
+  const port = settings.apiMetricsPort;
+  if (port === undefined) return undefined;
+  if (port === settings.apiPort) {
+    throw new Error("OPENGENI_API_METRICS_PORT must differ from OPENGENI_API_PORT");
+  }
+  const app = createMetricsListenerApp(settings, observability);
+  return Bun.serve({
+    hostname: settings.apiHost,
+    port,
+    fetch: (request) => app.fetch(request),
+  });
+}

package/src/http/path-identifier.ts

@@ -0,0 +1,54 @@
+import { ApiHttpError } from "./api-error";
+
+const UUID_SYNTAX_MESSAGE = /invalid input syntax for type uuid: "([^"]*)"/u;
+
+/**
+ * A resource id taken verbatim from the URL path that is not a UUID cannot
+ * name any row. Routes pass such ids straight to PostgreSQL, which rejects the
+ * cast (SQLSTATE 22P02); that is a client addressing error, so answer 404
+ * instead of an unhandled 500.
+ *
+ * Deliberately narrow: only a uuid-syntax failure whose rejected text is
+ * exactly one of this request's own path segments qualifies. A malformed UUID
+ * produced by server code (a stored value, a derived subject, a body field)
+ * does not appear as a path segment and stays a genuine 500.
+ *
+ * Typical cause: a client built against a newer API calls a literal route
+ * (for example `.../scheduled-tasks/attention`) that an older server does not
+ * have, so the literal falls through to `.../scheduled-tasks/:taskId`.
+ */
+export function invalidPathIdentifierHttpError(
+  error: unknown,
+  pathname: string,
+): ApiHttpError | null {
+  const rejected = rejectedUuidText(error);
+  if (rejected === null || rejected.length === 0) return null;
+  const segments = pathname.split("/").map((segment) => {
+    try {
+      return decodeURIComponent(segment);
+    } catch {
+      return segment;
+    }
+  });
+  if (!segments.includes(rejected)) return null;
+  return new ApiHttpError(404, {
+    code: "not_found",
+    message: `Not found: "${rejected.slice(0, 64)}" is not a valid resource id for this route.`,
+    retryable: false,
+    details: { code: "invalid_path_identifier" },
+  });
+}
+
+/** The text PostgreSQL refused to cast to uuid, found through a bounded cause chain. */
+function rejectedUuidText(error: unknown): string | null {
+  let current: unknown = error;
+  for (let depth = 0; depth < 6 && current instanceof Error; depth += 1) {
+    const code = (current as { code?: unknown }).code;
+    if (code === "22P02") {
+      const match = UUID_SYNTAX_MESSAGE.exec(current.message);
+      if (match) return match[1] ?? null;
+    }
+    current = current.cause;
+  }
+  return null;
+}

package/src/http/registered-route-label.ts

@@ -0,0 +1,34 @@
+import type { Context } from "hono";
+import { matchedRoutes } from "hono/route";
+
+/**
+ * The registered Hono path template of the handler that answers this request.
+ *
+ * Hono resolves every route matching a request before the first middleware
+ * runs, so the metrics middleware can read the exact code-owned template (for
+ * example `/v1/workspaces/:workspaceId/rigs/:rigId`) without re-implementing
+ * routing. Templates come only from route registrations, never from request
+ * data, so they are a closed and bounded metric/log label set.
+ *
+ * Middleware (arity two: `(context, next)`) and global catch-alls never name a
+ * route; the first matched terminal handler is the one Hono dispatches to.
+ */
+export function registeredHandlerRoutePath(context: Context): string | null {
+  try {
+    for (const route of matchedRoutes(context)) {
+      if (typeof route.handler !== "function" || route.handler.length >= 2) continue;
+      const label = boundedRegisteredRouteLabel(route.path);
+      if (label) return label;
+    }
+  } catch {
+    // Route labels are observational and must never affect request handling.
+  }
+  return null;
+}
+
+/** Normalize a registered template; drop catch-alls that would name nothing. */
+export function boundedRegisteredRouteLabel(path: string | null | undefined): string | null {
+  if (!path || !path.startsWith("/") || path === "/*") return null;
+  // `:param{regex}` constraints are routing detail, not part of the label.
+  return path.replace(/(:[A-Za-z0-9_]+)\{[^/]*\}/g, "$1");
+}

package/src/http/request-body.ts

@@ -0,0 +1,127 @@
+import type { Context } from "hono";
+import type { z } from "zod";
+import { ZodError } from "zod";
+
+import { ApiHttpError } from "./api-error";
+
+/**
+ * Validation failures produced by parsing a client-supplied request body.
+ *
+ * The same `ZodError` instance is rethrown so route-local handlers that
+ * already map `instanceof ZodError` keep their exact behavior; only the
+ * central `app.onError` consults this set to answer a client error instead of
+ * a 500. A ZodError that is NOT registered here (for example, a server-side
+ * response projection that no longer matches its contract) remains a genuine
+ * server fault.
+ */
+const requestBodyValidationErrors = new WeakSet<ZodError>();
+/** Malformed-JSON failures raised by reading a client request body. */
+const requestBodyJsonErrors = new WeakSet<SyntaxError>();
+
+const MAX_REPORTED_ISSUES = 10;
+
+/** Parse an already-read request body against its public request schema. */
+export function parseRequestBody<Schema extends z.ZodType>(
+  schema: Schema,
+  body: unknown,
+): z.output<Schema> {
+  const parsed = schema.safeParse(body);
+  if (parsed.success) return parsed.data;
+  requestBodyValidationErrors.add(parsed.error);
+  throw parsed.error;
+}
+
+/**
+ * Read the request body as JSON. Malformed JSON is a client error (400), never
+ * an unhandled `SyntaxError` 500. Other failures (body limit, aborted stream)
+ * keep their own mapping.
+ */
+export async function readRequestJson(c: Context): Promise<unknown> {
+  try {
+    return await c.req.json();
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new ApiHttpError(400, {
+        code: "validation_failed",
+        message: "Request body must be valid JSON.",
+        retryable: false,
+        details: { code: "invalid_json" },
+      });
+    }
+    throw error;
+  }
+}
+
+/** Read and validate a JSON request body in one step. */
+export async function parseRequestJson<Schema extends z.ZodType>(
+  c: Context,
+  schema: Schema,
+): Promise<z.output<Schema>> {
+  return parseRequestBody(schema, await readRequestJson(c));
+}
+
+/**
+ * Tag malformed-JSON failures of `c.req.json()` for this request. The same
+ * `SyntaxError` instance is rethrown so routes that already catch it keep
+ * their own mapping; an uncaught one becomes a 400 in `app.onError` instead of
+ * a 500. A `SyntaxError` from parsing stored or upstream data is never tagged.
+ */
+export function tagRequestJsonParseErrors(c: Context): void {
+  const original = c.req.json.bind(c.req);
+  const tagged = async () => {
+    try {
+      return await original();
+    } catch (error) {
+      if (error instanceof SyntaxError) requestBodyJsonErrors.add(error);
+      throw error;
+    }
+  };
+  (c.req as { json: typeof tagged }).json = tagged;
+}
+
+export function isRequestBodyValidationError(error: unknown): error is ZodError | SyntaxError {
+  return requestBodyInputError(error) !== null;
+}
+
+/** Walk a bounded cause chain for a tagged client-input failure. */
+function requestBodyInputError(error: unknown): ZodError | SyntaxError | null {
+  let current: unknown = error;
+  for (let depth = 0; depth < 5 && current instanceof Error; depth += 1) {
+    if (current instanceof ZodError && requestBodyValidationErrors.has(current)) return current;
+    if (current instanceof SyntaxError && requestBodyJsonErrors.has(current)) return current;
+    current = current.cause;
+  }
+  return null;
+}
+
+/**
+ * Public 400 for a registered request-body validation failure, naming every
+ * offending field (bounded) so API callers can correct the request.
+ */
+export function requestBodyValidationHttpError(error: unknown): ApiHttpError | null {
+  const inputError = requestBodyInputError(error);
+  if (!inputError) return null;
+  if (inputError instanceof SyntaxError) {
+    return new ApiHttpError(400, {
+      code: "validation_failed",
+      message: "Request body must be valid JSON.",
+      retryable: false,
+      details: { code: "invalid_json" },
+    });
+  }
+  const zodError = inputError;
+  const issues = zodError.issues.slice(0, MAX_REPORTED_ISSUES).map((issue) => ({
+    path: issue.path.map(String).join("."),
+    message: issue.message,
+  }));
+  const summary = issues.map((issue) => `${issue.path || "request"}: ${issue.message}`).join("; ");
+  const omittedIssueCount = Math.max(0, zodError.issues.length - issues.length);
+  return new ApiHttpError(400, {
+    code: "validation_failed",
+    message: `Invalid request body: ${summary}${
+      omittedIssueCount > 0 ? `; and ${omittedIssueCount} more` : ""
+    }`,
+    retryable: false,
+    details: { code: "invalid_request_body", issues, omittedIssueCount },
+  });
+}

package/src/http/request-source.ts

@@ -0,0 +1,178 @@
+import { BlockList, isIP } from "node:net";
+import { trustedProxyCidrEntries, type Settings } from "@opengeni/config";
+import type { Context } from "hono";
+
+const TRANSPORT_PEER_ADDRESS_BINDING = "opengeniTransportPeerAddress";
+
+/** Returned when the runtime supplied no transport peer (for example an
+ * in-process test request). Callers treat it as one shared bucket. */
+export const UNKNOWN_REQUEST_SOURCE_ADDRESS = "unknown";
+
+/**
+ * App-owned request header carrying the server-resolved client address into
+ * Better Auth, which reads client addresses only from request headers. It is
+ * removed from every inbound request and re-stamped on managed-auth routes, so
+ * a caller-supplied value never reaches the auth rate limiter or session IP.
+ */
+export const TRUSTED_CLIENT_ADDRESS_HEADER = "x-opengeni-trusted-client-address";
+
+type ApiRequestBindings = {
+  [TRANSPORT_PEER_ADDRESS_BINDING]?: string | null;
+};
+
+/** The deployment's declared proxy chain (`OPENGENI_API_TRUSTED_PROXY_*`). */
+export type RequestSourceTrust = Pick<Settings, "apiTrustedProxyHops" | "apiTrustedProxyCidrs">;
+
+export function apiRequestBindingsForTransportPeer(
+  address: string | null | undefined,
+): ApiRequestBindings {
+  return { [TRANSPORT_PEER_ADDRESS_BINDING]: address ?? null };
+}
+
+/**
+ * Resolve a quota/audit source from the server-owned transport peer. Forwarded
+ * values are considered only when the operator declares an exact trusted proxy
+ * hop count (`OPENGENI_API_TRUSTED_PROXY_HOPS`) and, when
+ * `OPENGENI_API_TRUSTED_PROXY_CIDRS` is set, only for a transport peer inside
+ * those ranges. Each trusted proxy must append the address of the peer that
+ * connected to it, or overwrite the header with the original client address;
+ * the chain is then walked from the server side so caller-prepended values
+ * cannot replace the address observed by the trusted edge. A missing, short,
+ * or malformed chain falls back to the transport peer.
+ */
+export function trustedRequestSourceAddress(c: Context, trust: RequestSourceTrust): string {
+  const bindings = c.env as ApiRequestBindings | undefined;
+  const peer =
+    normalizedAddress(bindings?.[TRANSPORT_PEER_ADDRESS_BINDING]) ?? UNKNOWN_REQUEST_SOURCE_ADDRESS;
+  const trustedProxyHops = trust.apiTrustedProxyHops;
+  if (
+    !Number.isInteger(trustedProxyHops) ||
+    trustedProxyHops <= 0 ||
+    peer === UNKNOWN_REQUEST_SOURCE_ADDRESS ||
+    !peerIsTrustedProxy(peer, trust.apiTrustedProxyCidrs)
+  ) {
+    return peer;
+  }
+  const header = c.req.header("x-forwarded-for");
+  if (!header) return peer;
+  // Entries are never filtered: dropping a malformed value would shift the
+  // server-side position and could promote a caller-prepended value.
+  const forwarded = header.split(",");
+  const sourceIndex = forwarded.length - trustedProxyHops;
+  if (sourceIndex < 0) return peer;
+  return normalizedAddress(forwarded[sourceIndex]) ?? peer;
+}
+
+/**
+ * Rate-limit key for a trusted source address. An IPv6 address keys on its
+ * /64, the block one subscriber normally holds and the granularity Better
+ * Auth applies to the same stamped address, so rotating addresses inside one
+ * /64 cannot mint fresh buckets. An IPv4-mapped IPv6 address (how a
+ * dual-stack listener reports an IPv4 peer) keys on the embedded IPv4 address
+ * instead of collapsing every IPv4 client into one /64. Anything else,
+ * including {@link UNKNOWN_REQUEST_SOURCE_ADDRESS}, is returned unchanged.
+ */
+export function requestSourceRateLimitKey(address: string): string {
+  if (isIP(address) !== 6) return address;
+  const groups = ipv6Groups(address);
+  if (!groups) return address;
+  if (groups.slice(0, 5).every((group) => group === 0) && groups[5] === 0xffff) {
+    const high = groups[6]!;
+    const low = groups[7]!;
+    return `${high >> 8}.${high & 0xff}.${low >> 8}.${low & 0xff}`;
+  }
+  return `${groups
+    .slice(0, 4)
+    .map((group) => group.toString(16))
+    .join(":")}::/64`;
+}
+
+/** {@link trustedRequestSourceAddress} as an application rate-limit key. */
+export function trustedRequestSourceRateLimitKey(c: Context, trust: RequestSourceTrust): string {
+  return requestSourceRateLimitKey(trustedRequestSourceAddress(c, trust));
+}
+
+/**
+ * Replace any caller-supplied {@link TRUSTED_CLIENT_ADDRESS_HEADER}. When
+ * `stamp` is true the header is set to the trusted source address, so every
+ * Better Auth request derived from this request (direct handler calls,
+ * isolated provider requests, and `auth.api.*` calls built from its headers)
+ * keys rate limits and session records on the real client.
+ */
+export function replaceTrustedClientAddressHeader(
+  c: Context,
+  trust: RequestSourceTrust,
+  stamp: boolean,
+): void {
+  const headers = c.req.raw.headers;
+  headers.delete(TRUSTED_CLIENT_ADDRESS_HEADER);
+  if (!stamp) return;
+  const address = trustedRequestSourceAddress(c, trust);
+  if (address !== UNKNOWN_REQUEST_SOURCE_ADDRESS) {
+    headers.set(TRUSTED_CLIENT_ADDRESS_HEADER, address);
+  }
+}
+
+const trustedProxyRanges = new Map<string, BlockList | null>();
+
+function peerIsTrustedProxy(peer: string, cidrs: string): boolean {
+  let ranges = trustedProxyRanges.get(cidrs);
+  if (ranges === undefined) {
+    // Settings validation already rejected malformed entries at boot.
+    const entries = trustedProxyCidrEntries(cidrs);
+    ranges = entries.length === 0 ? null : new BlockList();
+    for (const entry of entries) ranges?.addSubnet(entry.address, entry.prefix, entry.family);
+    trustedProxyRanges.set(cidrs, ranges);
+  }
+  if (!ranges) return true;
+  return ranges.check(peer, isIP(peer) === 6 ? "ipv6" : "ipv4");
+}
+
+/**
+ * Canonical IP text, or null. Accepts the `ipv4:port` and `[ipv6]:port` forms
+ * some load balancers write into X-Forwarded-For, and drops IPv6 zone ids.
+ */
+function normalizedAddress(value: string | null | undefined): string | null {
+  let candidate = value?.trim();
+  if (!candidate || candidate.length > 64) return null;
+  const bracketed = /^\[([^\]]+)\](?::\d{1,5})?$/u.exec(candidate);
+  if (bracketed) {
+    candidate = bracketed[1]!;
+  } else {
+    const ipv4WithPort = /^(\d{1,3}(?:\.\d{1,3}){3}):\d{1,5}$/u.exec(candidate);
+    if (ipv4WithPort) candidate = ipv4WithPort[1]!;
+  }
+  const zone = candidate.indexOf("%");
+  if (zone >= 0) candidate = candidate.slice(0, zone);
+  const family = isIP(candidate);
+  if (family === 4) return candidate;
+  if (family === 6) return candidate.toLowerCase();
+  return null;
+}
+
+/** The eight 16-bit groups of a valid IPv6 address, or null. */
+function ipv6Groups(address: string): number[] | null {
+  let text = address;
+  const tail: number[] = [];
+  const lastColon = text.lastIndexOf(":");
+  const last = text.slice(lastColon + 1);
+  if (last.includes(".")) {
+    const octets = last.split(".").map(Number);
+    if (octets.length !== 4 || octets.some((octet) => !Number.isInteger(octet))) return null;
+    tail.push((octets[0]! << 8) | octets[1]!, (octets[2]! << 8) | octets[3]!);
+    text = text.slice(0, lastColon + 1);
+    if (!text.endsWith("::")) text = text.slice(0, -1);
+  }
+  const halves = text.split("::");
+  if (halves.length > 2) return null;
+  const parse = (part: string): number[] =>
+    part ? part.split(":").map((group) => Number.parseInt(group, 16)) : [];
+  const head = parse(halves[0]!);
+  const rest = halves.length === 2 ? parse(halves[1]!) : [];
+  const fill = halves.length === 2 ? 8 - head.length - rest.length - tail.length : 0;
+  if (fill < 0) return null;
+  const groups = [...head, ...Array.from({ length: fill }, () => 0), ...rest, ...tail];
+  if (groups.length !== 8) return null;
+  if (groups.some((group) => !Number.isInteger(group) || group < 0 || group > 0xffff)) return null;
+  return groups;
+}