@opengeni/api-router 3.0.1 → 3.0.2-canary.38894290271001

package/src/http/deprecation.ts

@@ -0,0 +1,118 @@
+import type { Context, MiddlewareHandler } from "hono";
+import { registeredHandlerRoutePath } from "./registered-route-label";
+
+/**
+ * A public `/v1` route whose current behaviour is scheduled for removal.
+ *
+ * See docs/design/api-compatibility-policy.md: a breaking change to the public
+ * surface is announced, advertised on every affected response with the
+ * standard `Deprecation` (RFC 9745) and `Sunset` (RFC 8594) headers plus a
+ * `Link: rel="deprecation"` to the migration notes, and the old behaviour is
+ * kept for at least 90 days on the managed service or until the next major,
+ * whichever is later. Published SDKs surface these headers to the integrator.
+ */
+export type RouteDeprecation = {
+  /** Upper-case HTTP method. */
+  method: string;
+  /** The exact registered Hono template, e.g. `/v1/workspaces/:workspaceId/packs`. */
+  path: string;
+  /** When the deprecation was announced (ISO 8601). */
+  deprecatedAt: string;
+  /** Earliest removal on the managed service (ISO 8601). */
+  sunset: string;
+  /** Public migration notes (changelog/docs URL). */
+  link: string;
+  /** Optional successor route or document. */
+  successor?: string;
+};
+
+/**
+ * Every currently deprecated public route. Adding an entry here is the
+ * server-side half of a deprecation; the breaking change itself still needs an
+ * entry in scripts/public-api-breaking-changes.json and a new major.
+ */
+export const DEPRECATED_ROUTES: readonly RouteDeprecation[] = [];
+
+const MINIMUM_NOTICE_MS = 90 * 24 * 60 * 60 * 1000;
+
+function isoMillis(value: string, field: string, deprecation: RouteDeprecation): number {
+  const millis = Date.parse(value);
+  if (Number.isNaN(millis)) {
+    throw new Error(
+      `deprecation ${deprecation.method} ${deprecation.path}: ${field} is not an ISO date`,
+    );
+  }
+  return millis;
+}
+
+/** Validate one registry entry; the policy's 90-day minimum is enforced here. */
+export function assertValidRouteDeprecation(deprecation: RouteDeprecation): void {
+  if (!/^(GET|POST|PUT|PATCH|DELETE)$/.test(deprecation.method)) {
+    throw new Error(`deprecation method must be an upper-case HTTP verb: ${deprecation.method}`);
+  }
+  if (!deprecation.path.startsWith("/v1/")) {
+    throw new Error(`deprecation path must be a /v1 route template: ${deprecation.path}`);
+  }
+  const deprecatedAt = isoMillis(deprecation.deprecatedAt, "deprecatedAt", deprecation);
+  const sunset = isoMillis(deprecation.sunset, "sunset", deprecation);
+  if (sunset - deprecatedAt < MINIMUM_NOTICE_MS) {
+    throw new Error(
+      `deprecation ${deprecation.method} ${deprecation.path}: sunset must be at least 90 days after deprecatedAt`,
+    );
+  }
+  if (!/^https:\/\//.test(deprecation.link)) {
+    throw new Error(
+      `deprecation ${deprecation.method} ${deprecation.path}: link must be an https URL`,
+    );
+  }
+}
+
+/** The response headers that advertise one deprecation. */
+export function deprecationHeaders(deprecation: RouteDeprecation): Record<string, string> {
+  const deprecatedAt = Math.floor(Date.parse(deprecation.deprecatedAt) / 1000);
+  const links = [`<${deprecation.link}>; rel="deprecation"; type="text/html"`];
+  if (deprecation.successor) links.push(`<${deprecation.successor}>; rel="successor-version"`);
+  return {
+    // RFC 9745: a structured-field date, `@<unix seconds>`.
+    Deprecation: `@${deprecatedAt}`,
+    // RFC 8594: an HTTP-date.
+    Sunset: new Date(deprecation.sunset).toUTCString(),
+    Link: links.join(", "),
+  };
+}
+
+function appendHeader(context: Context, name: string, value: string): void {
+  const existing = context.res.headers.get(name);
+  context.res.headers.set(name, existing ? `${existing}, ${value}` : value);
+}
+
+/**
+ * Stamp deprecation headers on every response from a registered deprecated
+ * route, including error responses, so an integrator sees the notice whatever
+ * the call's outcome. Matching uses the registered route template, never
+ * request data.
+ */
+export function deprecationHeadersMiddleware(
+  registry: readonly RouteDeprecation[] = DEPRECATED_ROUTES,
+): MiddlewareHandler {
+  for (const deprecation of registry) assertValidRouteDeprecation(deprecation);
+  const byRoute = new Map(registry.map((entry) => [`${entry.method} ${entry.path}`, entry]));
+  return async (context, next) => {
+    await next();
+    if (byRoute.size === 0) return;
+    const path = registeredHandlerRoutePath(context);
+    if (!path) return;
+    const deprecation = byRoute.get(`${context.req.method} ${path}`);
+    if (!deprecation) return;
+    const headers = deprecationHeaders(deprecation);
+    try {
+      context.res.headers.set("Deprecation", headers.Deprecation!);
+    } catch {
+      // Immutable headers (a proxied or redirect response): copy once.
+      context.res = new Response(context.res.body, context.res);
+      context.res.headers.set("Deprecation", headers.Deprecation!);
+    }
+    context.res.headers.set("Sunset", headers.Sunset!);
+    appendHeader(context, "Link", headers.Link!);
+  };
+}

package/src/http/keyed-admission.ts

@@ -0,0 +1,29 @@
+/**
+ * One token bucket per closed key, for anonymous beacon routes. It bounds
+ * counter inflation and log volume from any caller without per-client state.
+ */
+export type KeyedAdmission<Key extends string> = { admit(key: Key): boolean };
+
+export function createKeyedAdmission<Key extends string>(
+  options: { capacity?: number; refillPerSecond?: number; now?: () => number } = {},
+): KeyedAdmission<Key> {
+  const capacity = options.capacity ?? 30;
+  const refillPerMs = (options.refillPerSecond ?? 0.5) / 1_000;
+  const now = options.now ?? Date.now;
+  const buckets = new Map<Key, { tokens: number; updatedAt: number }>();
+  return {
+    admit(key) {
+      const at = now();
+      const bucket = buckets.get(key) ?? { tokens: capacity, updatedAt: at };
+      bucket.tokens = Math.min(
+        capacity,
+        bucket.tokens + Math.max(0, at - bucket.updatedAt) * refillPerMs,
+      );
+      bucket.updatedAt = at;
+      buckets.set(key, bucket);
+      if (bucket.tokens < 1) return false;
+      bucket.tokens -= 1;
+      return true;
+    },
+  };
+}

package/src/http/local-browser-boundary.ts

@@ -0,0 +1,343 @@
+import {
+  localAllowedOriginEntries,
+  localSandboxApiRouteAllowed,
+  type Settings,
+} from "@opengeni/config";
+
+/**
+ * Browser boundary for the unauthenticated local product mode.
+ *
+ * In `local` access mode every request without credentials acts as the local
+ * `dev` user, and the default local sandbox runs agent commands on the host.
+ * Binding the API to loopback keeps other devices out, but a web page open in
+ * the developer's browser can still reach `http://127.0.0.1:<port>`:
+ *
+ * - any site can send cross-origin requests to it (CORS only hides the
+ *   response; a simple POST still runs), and
+ * - a DNS-rebinding site can make its own hostname resolve to 127.0.0.1 and
+ *   read responses as a same-origin page.
+ *
+ * The boundary therefore sorts the `Host` a request is addressed to into two
+ * classes:
+ *
+ * - Browser hosts: loopback, the hosts of the configured web, public, and
+ *   extra origins, the GitHub App callback tunnel, and a specific API bind
+ *   address. A present `Origin` must be this stack's web app, an explicitly
+ *   configured origin, or the API's own address on one of these hosts.
+ * - Sandbox hosts: names only sandboxes and the worker use to reach the API
+ *   (`host.docker.internal` with the Docker sandbox, and the hosts of
+ *   `OPENGENI_MCP_URL` and `OPENGENI_MCP_INTERNAL_URL`). They serve only the
+ *   sandbox routes (Codemode, first-party MCP, and the Git broker) and refuse
+ *   any request that carries browser metadata. A browser cannot tell a
+ *   sandbox name from an attacker's, so a rebinding page on one of these
+ *   names can neither send an accepted `Origin` nor reach the rest of the API.
+ *
+ * Every other `Host` is refused. Non-browser clients (the SDK, curl, sandbox
+ * callbacks, host-app servers) send no `Origin` and are unaffected. The `Host`
+ * port is not compared: a rebinding page controls only the hostname, while
+ * local proxies and forwarders legitimately present their own port.
+ *
+ * It applies only to `local` access mode in the `local` environment (the
+ * `bun run dev` stack and manual local runs). Managed and configured access
+ * modes, and deployments that set another `OPENGENI_ENVIRONMENT`, keep their
+ * existing CORS policy.
+ */
+export type LocalBrowserBoundarySettings = Pick<
+  Settings,
+  | "productAccessMode"
+  | "environment"
+  | "apiHost"
+  | "webBaseUrl"
+  | "publicBaseUrl"
+  | "opengeniMcpUrl"
+  | "opengeniMcpInternalUrl"
+  | "githubAppManifestBaseUrl"
+  | "localAllowedOrigins"
+  | "sandboxBackend"
+>;
+
+export type LocalBrowserBoundaryRejectionCode =
+  | "LOCAL_HOST_NOT_ALLOWED"
+  | "LOCAL_ORIGIN_NOT_ALLOWED"
+  | "LOCAL_SANDBOX_ROUTE_ONLY";
+
+export type LocalBrowserBoundaryRejection = {
+  status: 403;
+  code: LocalBrowserBoundaryRejectionCode;
+  message: string;
+  /** The refused `Host` or `Origin`, for the API log only; never sent back. */
+  refused: string;
+};
+
+/** Called once per distinct refused value, so an operator can see why. */
+export type LocalBrowserBoundaryWarn = (
+  message: string,
+  attributes: Record<string, string>,
+) => void;
+
+export type LocalBrowserBoundary = {
+  readonly allowedOrigins: ReadonlySet<string>;
+  /** Hostnames a browser may address. */
+  readonly browserHostnames: ReadonlySet<string>;
+  /** Hostnames only sandboxes and the worker use; sandbox routes only, no browsers. */
+  readonly sandboxHostnames: ReadonlySet<string>;
+  /** Whether a present `Origin` may call the API for a request with this `Host`. */
+  originAllowed(origin: string, host: string | null): boolean;
+  /** The rejection for this request, or null when the boundary admits it. */
+  rejection(request: Request): LocalBrowserBoundaryRejection | null;
+};
+
+const LOOPBACK_HOSTNAMES = ["127.0.0.1", "localhost", "[::1]"] as const;
+/** Docker Desktop's name for the host; Linux sandboxes use the configured bridge route. */
+const DOCKER_HOST_ALIAS = "host.docker.internal";
+/** `apps/web` dev server default when no web base URL is configured. */
+const DEFAULT_LOCAL_WEB_ORIGIN = "http://127.0.0.1:3000";
+const WILDCARD_BIND_HOSTS = new Set(["", "0.0.0.0", "::", "[::]"]);
+/**
+ * Only browsers send these. (Node's fetch sends `Sec-Fetch-Mode: cors`, so that
+ * header does not identify a browser.)
+ */
+const BROWSER_REQUEST_HEADERS = ["origin", "sec-fetch-site"];
+/** Distinct refused values logged per boundary, so a rebinding page cannot flood the log. */
+const MAX_REPORTED_REJECTIONS = 32;
+const MAX_REPORTED_VALUE_LENGTH = 200;
+
+const HOST_NOT_ALLOWED_MESSAGE =
+  "The local Opengeni API only answers requests addressed to this computer. " +
+  "To use another address, set it in OPENGENI_WEB_BASE_URL, OPENGENI_PUBLIC_BASE_URL, " +
+  "or OPENGENI_LOCAL_ALLOWED_ORIGINS.";
+const ORIGIN_NOT_ALLOWED_MESSAGE =
+  "The local Opengeni API has no authentication, so browser requests are accepted only " +
+  "from this stack's web app. Add other trusted origins to OPENGENI_LOCAL_ALLOWED_ORIGINS.";
+const SANDBOX_ROUTE_ONLY_MESSAGE =
+  "This address is the local Opengeni API's sandbox route. It serves only sandbox calls " +
+  "(Codemode, first-party MCP, and the Git broker), never browsers. Open the web app at " +
+  "its own address, or list this address in OPENGENI_LOCAL_ALLOWED_ORIGINS.";
+
+const WARNINGS: Record<LocalBrowserBoundaryRejectionCode, { message: string; setting: string }> = {
+  LOCAL_HOST_NOT_ALLOWED: {
+    message: "Local API refused a request addressed to a name that is not this computer's",
+    setting: "OPENGENI_WEB_BASE_URL, OPENGENI_PUBLIC_BASE_URL, or OPENGENI_LOCAL_ALLOWED_ORIGINS",
+  },
+  LOCAL_ORIGIN_NOT_ALLOWED: {
+    message: "Local API refused a browser request from an origin that is not this stack's web app",
+    setting: "OPENGENI_WEB_BASE_URL or OPENGENI_LOCAL_ALLOWED_ORIGINS",
+  },
+  LOCAL_SANDBOX_ROUTE_ONLY: {
+    message: "Local API refused a browser or non-sandbox request on an address only sandboxes use",
+    setting: "OPENGENI_WEB_BASE_URL or OPENGENI_LOCAL_ALLOWED_ORIGINS",
+  },
+};
+
+/**
+ * Requests the API builds and dispatches to itself, such as the Codemode SDK
+ * proxy's re-dispatch. They never come from the network, and the request they
+ * were built from already passed the boundary.
+ */
+const internalDispatches = new WeakSet<Request>();
+
+/** Mark a request the API dispatches to itself so the boundary admits it. */
+export function markLocalInternalDispatch(request: Request): Request {
+  internalDispatches.add(request);
+  return request;
+}
+
+export function localBrowserBoundaryApplies(
+  settings: Pick<Settings, "productAccessMode" | "environment">,
+): boolean {
+  return settings.productAccessMode === "local" && settings.environment === "local";
+}
+
+/** Build the boundary, or null when the deployment is not the local dev product. */
+export function createLocalBrowserBoundary(
+  settings: LocalBrowserBoundarySettings,
+  options: { warn?: LocalBrowserBoundaryWarn } = {},
+): LocalBrowserBoundary | null {
+  if (!localBrowserBoundaryApplies(settings)) return null;
+
+  const webOrigins = [settings.webBaseUrl ?? DEFAULT_LOCAL_WEB_ORIGIN, settings.publicBaseUrl]
+    .map((value) => parseHttpUrl(value))
+    .filter((url): url is URL => url !== null);
+  const extraOrigins = localAllowedOriginEntries(settings.localAllowedOrigins).map(
+    (origin) => new URL(origin),
+  );
+
+  const allowedOrigins = new Set<string>();
+  for (const url of [...webOrigins, ...extraOrigins]) {
+    allowedOrigins.add(url.origin);
+    // 127.0.0.1, localhost, and [::1] are the same machine and port; the
+    // developer may open the printed URL under any of those names.
+    if (isLoopbackHostname(url.hostname)) {
+      for (const hostname of LOOPBACK_HOSTNAMES) {
+        const alias = new URL(url.origin);
+        alias.hostname = hostname;
+        allowedOrigins.add(alias.origin);
+      }
+    }
+  }
+
+  const browserHostnames = new Set<string>(LOOPBACK_HOSTNAMES);
+  for (const url of [...webOrigins, ...extraOrigins]) browserHostnames.add(url.hostname);
+  // A tunnel configured for GitHub App callbacks: GitHub redirects the browser there.
+  const githubAppTunnel = parseHttpUrl(settings.githubAppManifestBaseUrl);
+  if (githubAppTunnel) browserHostnames.add(githubAppTunnel.hostname);
+  const apiHost = settings.apiHost.trim().toLowerCase();
+  if (!WILDCARD_BIND_HOSTS.has(apiHost)) {
+    const url = parseHostHeader(
+      apiHost.includes(":") && !apiHost.startsWith("[") ? `[${apiHost}]` : apiHost,
+    );
+    if (url) browserHostnames.add(url.hostname);
+  }
+
+  // The sandbox-visible API route (Docker Desktop's host alias, the Linux
+  // Docker bridge address, or a tunnel for a remote sandbox) and the worker's
+  // internal route arrive with their own Host.
+  const sandboxHostnames = new Set<string>();
+  if (settings.sandboxBackend === "docker") sandboxHostnames.add(DOCKER_HOST_ALIAS);
+  for (const value of [settings.opengeniMcpUrl, settings.opengeniMcpInternalUrl]) {
+    const url = parseHttpUrl(value?.replaceAll("{workspaceId}", "workspace"));
+    if (url) sandboxHostnames.add(url.hostname);
+  }
+  // A name the developer also uses in the browser stays a browser host.
+  for (const hostname of browserHostnames) sandboxHostnames.delete(hostname);
+
+  const browserHost = (host: string | null): URL | null => {
+    const url = host === null ? null : parseHostHeader(host);
+    return url !== null && browserHostnames.has(url.hostname) ? url : null;
+  };
+
+  const originAllowed = (origin: string, host: string | null): boolean => {
+    const url = parseHttpUrl(origin);
+    if (!url || url.origin !== origin.toLowerCase().replace(/\/$/u, "")) return false;
+    if (allowedOrigins.has(url.origin)) return true;
+    // Pages served by the API itself (for example the MCP OAuth consent form)
+    // and same-origin dev proxies present the API's own address. Only a
+    // browser host qualifies: sandbox names and unknown names never do.
+    const requestHost = browserHost(host);
+    return requestHost !== null && requestHost.host === url.host;
+  };
+
+  const reported = new Set<string>();
+  const report = (rejection: LocalBrowserBoundaryRejection, host: string | null) => {
+    if (!options.warn) return;
+    const key = `${rejection.code}\u0000${rejection.refused}`;
+    if (reported.has(key) || reported.size >= MAX_REPORTED_REJECTIONS) return;
+    reported.add(key);
+    const warning = WARNINGS[rejection.code];
+    options.warn(warning.message, {
+      code: rejection.code,
+      refused: rejection.refused.slice(0, MAX_REPORTED_VALUE_LENGTH),
+      host: (host ?? "").slice(0, MAX_REPORTED_VALUE_LENGTH),
+      setting: warning.setting,
+    });
+  };
+
+  const refuse = (
+    code: LocalBrowserBoundaryRejectionCode,
+    refused: string,
+    host: string | null,
+  ): LocalBrowserBoundaryRejection => {
+    const message =
+      code === "LOCAL_HOST_NOT_ALLOWED"
+        ? HOST_NOT_ALLOWED_MESSAGE
+        : code === "LOCAL_ORIGIN_NOT_ALLOWED"
+          ? ORIGIN_NOT_ALLOWED_MESSAGE
+          : SANDBOX_ROUTE_ONLY_MESSAGE;
+    const rejection: LocalBrowserBoundaryRejection = { status: 403, code, message, refused };
+    report(rejection, host);
+    return rejection;
+  };
+
+  return {
+    allowedOrigins,
+    browserHostnames,
+    sandboxHostnames,
+    originAllowed,
+    rejection(request) {
+      if (internalDispatches.has(request)) return null;
+      const host = localBrowserRequestHost(request);
+      const origin = request.headers.get("origin");
+      if (browserHost(host)) {
+        if (origin !== null && !originAllowed(origin, host)) {
+          return refuse("LOCAL_ORIGIN_NOT_ALLOWED", origin, host);
+        }
+        return null;
+      }
+      const parsedHost = host === null ? null : parseHostHeader(host);
+      if (parsedHost === null || !sandboxHostnames.has(parsedHost.hostname)) {
+        return refuse("LOCAL_HOST_NOT_ALLOWED", host ?? "", host);
+      }
+      if (
+        BROWSER_REQUEST_HEADERS.some((name) => request.headers.has(name)) ||
+        !localSandboxApiRouteAllowed(requestPathname(request))
+      ) {
+        return refuse("LOCAL_SANDBOX_ROUTE_ONLY", host ?? "", host);
+      }
+      return null;
+    },
+  };
+}
+
+/** The standard API error envelope for a boundary rejection outside Hono. */
+export function localBrowserBoundaryResponse(rejection: LocalBrowserBoundaryRejection): Response {
+  return Response.json(
+    {
+      error: {
+        status: rejection.status,
+        code: "forbidden",
+        message: rejection.message,
+        retryable: false,
+        details: { code: rejection.code },
+      },
+    },
+    { status: rejection.status },
+  );
+}
+
+/** The `Host` the boundary checks: the header, else the request URL's authority. */
+export function localBrowserRequestHost(request: Request): string | null {
+  const header = request.headers.get("host");
+  if (header !== null) return header;
+  try {
+    return new URL(request.url).host || null;
+  } catch {
+    return null;
+  }
+}
+
+/** The normalized path the router sees (URL parsing resolves dot segments). */
+function requestPathname(request: Request): string {
+  try {
+    return new URL(request.url).pathname;
+  } catch {
+    return "";
+  }
+}
+
+function parseHostHeader(value: string): URL | null {
+  const host = value.trim();
+  // A Host is exactly `hostname[:port]`; anything else is not an address.
+  if (!host || /[\s/?#@\\,]/u.test(host)) return null;
+  try {
+    const url = new URL(`http://${host}`);
+    return url.host === host.toLowerCase() || url.host === host.toLowerCase().replace(/:80$/u, "")
+      ? url
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+function parseHttpUrl(value: string | undefined): URL | null {
+  if (!value) return null;
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" || url.protocol === "https:" ? url : null;
+  } catch {
+    return null;
+  }
+}
+
+function isLoopbackHostname(hostname: string): boolean {
+  return (LOOPBACK_HOSTNAMES as readonly string[]).includes(hostname);
+}

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");
+}