@opengeni/api-router 3.0.1 → 3.1.2

package/src/http/unmatched-route.ts

@@ -0,0 +1,60 @@
+import type { Context, Hono } from "hono";
+import { matchedRoutes } from "hono/route";
+
+type RegisteredRoute = { method: string; path: string; handler: unknown };
+
+const PROBED_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"] as const;
+
+/**
+ * Whether a matched Hono route is a terminal handler rather than middleware.
+ *
+ * Method-specific registrations (`app.get`, `app.put`, `app.on([...])`) always
+ * belong to a real route. `app.use` and `app.all` both register the `ALL`
+ * method; Hono itself tells them apart by arity - middleware takes
+ * `(context, next)` - so the same rule is applied here.
+ */
+function isTerminalRoute(route: RegisteredRoute): boolean {
+  if (route.method.toUpperCase() !== "ALL") return true;
+  return typeof route.handler === "function" && route.handler.length < 2;
+}
+
+function routesFor(app: Hono, method: string, path: string): RegisteredRoute[] {
+  // Every Hono router returns `[[ [handler, route], params ][], stash?]`.
+  const result = app.router.match(method, path) as unknown as [
+    Array<[[unknown, RegisteredRoute], unknown]>,
+    ...unknown[],
+  ];
+  return result[0].map(([[, route]]) => route);
+}
+
+export type UnmatchedRoute = { status: 404 } | { status: 405; allow: string[] };
+
+/**
+ * Classify a request no registered handler can answer, BEFORE authentication
+ * or authorization middleware runs. Those layers otherwise turn a request for a
+ * route that does not exist into an authorization-shaped failure (for example
+ * the fail-closed session operation classifier answering a retryable 503), so
+ * a client probing an unknown method or path would be told to retry forever.
+ *
+ * Returns null when the request has a handler, or when classification itself
+ * fails (fail open: the request keeps its previous routing behavior).
+ */
+export function unmatchedRoute(app: Hono, c: Context): UnmatchedRoute | null {
+  const method = c.req.method.toUpperCase();
+  // CORS preflights are answered by middleware and have no route handlers.
+  if (method === "OPTIONS") return null;
+  try {
+    if (matchedRoutes(c).some((route) => isTerminalRoute(route as RegisteredRoute))) {
+      return null;
+    }
+    const effectiveMethod = method === "HEAD" ? "GET" : method;
+    const allow = PROBED_METHODS.filter(
+      (candidate) =>
+        candidate !== effectiveMethod &&
+        routesFor(app, candidate, c.req.path).some(isTerminalRoute),
+    );
+    return allow.length > 0 ? { status: 405, allow } : { status: 404 };
+  } catch {
+    return null;
+  }
+}

package/src/http/user-content.ts

@@ -0,0 +1,158 @@
+/**
+ * Response headers for user-controlled bytes served from the API origin.
+ *
+ * Retained files, screenshots, exports, and live frames carry bytes and, for
+ * uploads, a content type chosen by a user or agent. The API shares its origin
+ * with the web console in the default deployment, so a stored `text/html` file
+ * opened by top-level navigation would otherwise run as that origin.
+ *
+ * Every such response therefore:
+ * - is a sandboxed document with no script, form, popup, plugin, or network
+ *   capability (`sandbox` plus `default-src 'none'`). Raster images and text
+ *   still render when a URL is opened directly;
+ * - cannot be embedded by another site as a no-cors subresource (CORP);
+ * - is never re-sniffed into a different type (`nosniff`).
+ *
+ * Audio and video keep their real origin (`sandbox allow-same-origin`, still
+ * without `allow-scripts`): the browser's synthesized media document re-fetches
+ * its own URL, and from an opaque origin that same-origin-only request would be
+ * refused. With scripts disabled and `nosniff`, such a response can only ever
+ * be a media player, never attacker markup.
+ *
+ * Markup types that a browser would render as an active document (HTML, XML,
+ * SVG, multipart) are additionally served as attachments, so a direct
+ * navigation downloads the bytes instead of showing attacker-authored markup on
+ * the app origin. The console never navigates to these routes: it reads bytes
+ * through the SDK and renders them in app-owned elements, so neither header
+ * changes an in-app preview. Signed object-storage GET URLs for active markup
+ * carry the same attachment as a signed response override
+ * (`userContentSignedGetUrlOptions`), because the storage endpoint is not
+ * always a separate site.
+ */
+const USER_CONTENT_FETCH_DIRECTIVES =
+  "default-src 'none'; img-src 'self' data: blob:; media-src 'self' data: blob:; style-src 'unsafe-inline'";
+
+export const USER_CONTENT_SECURITY_POLICY = `${USER_CONTENT_FETCH_DIRECTIVES}; sandbox`;
+
+/** Media players only; scripts stay disabled (see the module comment). */
+export const USER_MEDIA_CONTENT_SECURITY_POLICY = `${USER_CONTENT_FETCH_DIRECTIVES}; sandbox allow-same-origin`;
+
+export const USER_CONTENT_SECURITY_HEADERS = Object.freeze({
+  "Content-Security-Policy": USER_CONTENT_SECURITY_POLICY,
+  "Cross-Origin-Resource-Policy": "same-origin",
+  "X-Content-Type-Options": "nosniff",
+} as const);
+
+const ACTIVE_DOCUMENT_TYPES = new Set(["text/html", "text/xml", "text/xsl", "application/xml"]);
+
+/** Media type essence (no parameters), lowercased. */
+function mediaTypeEssence(contentType: string): string {
+  return (contentType.split(";", 1)[0] ?? "").trim().toLowerCase();
+}
+
+/**
+ * True when a browser would render this type as an active document (HTML,
+ * XHTML, SVG, any XML dialect, or multipart replacement streams). Anything that
+ * is not a clean `type/subtype` token is treated as active too.
+ */
+export function isActiveUserContentType(contentType: string): boolean {
+  const essence = mediaTypeEssence(contentType);
+  if (!/^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/.test(essence)) return true;
+  return (
+    ACTIVE_DOCUMENT_TYPES.has(essence) ||
+    essence.endsWith("+xml") ||
+    essence.startsWith("multipart/")
+  );
+}
+
+const DISPOSITION_FILENAME_MAX_CHARS = 200;
+
+/** RFC 8187 `attr-char` percent-encoding (stricter than `encodeURIComponent`). */
+function encodeExtendedParameterValue(value: string): string {
+  return encodeURIComponent(value).replace(
+    /['()*]/g,
+    (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`,
+  );
+}
+
+/**
+ * RFC 6266 filename parameters: an ASCII-only quoted `filename` that cannot
+ * break out of the header, plus an RFC 8187 `filename*` carrying the original
+ * name (for example non-Latin names) whenever the ASCII form had to change it.
+ */
+function dispositionFilenameParameters(filename: string): string {
+  const cleaned = Array.from(
+    filename
+      .replace(/[\u0000-\u001f\u007f/\\]+/g, "_")
+      // Lone surrogates cannot be percent-encoded as UTF-8.
+      .replace(/[\ud800-\udbff](?![\udc00-\udfff])|(?<![\ud800-\udbff])[\udc00-\udfff]/g, "_")
+      .trim(),
+  )
+    .slice(0, DISPOSITION_FILENAME_MAX_CHARS)
+    .join("");
+  const ascii =
+    cleaned
+      .replace(/[^A-Za-z0-9._ -]+/g, "_")
+      .replace(/\s+/g, " ")
+      .trim()
+      .slice(0, DISPOSITION_FILENAME_MAX_CHARS) || "download";
+  if (!cleaned || ascii === cleaned) return `filename="${ascii}"`;
+  return `filename="${ascii}"; filename*=UTF-8''${encodeExtendedParameterValue(cleaned)}`;
+}
+
+/** `Content-Disposition: attachment` for active markup; inline types are unchanged. */
+export function userContentDispositionHeaders(
+  contentType: string,
+  filename?: string | null,
+): { "Content-Disposition": string } | Record<string, never> {
+  if (!isActiveUserContentType(contentType)) return {};
+  return {
+    "Content-Disposition": filename
+      ? `attachment; ${dispositionFilenameParameters(filename)}`
+      : "attachment",
+  };
+}
+
+/**
+ * Signed object-storage GET options for one stored object: active markup gets
+ * a signed `attachment` response override, so a browser that opens the URL
+ * downloads the bytes instead of rendering them with their stored type. The
+ * storage endpoint is not always a separate site (local development serves it
+ * from loopback, and a preview may route the bucket path on the app origin),
+ * so a signed URL follows the same rule as the API routes. Spread into
+ * `createGetUrl`; inline types add nothing.
+ */
+export function userContentSignedGetUrlOptions(
+  contentType: string,
+  filename?: string | null,
+): { responseContentDisposition: string } | Record<string, never> {
+  const headers = userContentDispositionHeaders(contentType, filename);
+  return "Content-Disposition" in headers
+    ? { responseContentDisposition: headers["Content-Disposition"] }
+    : {};
+}
+
+/** True for audio and video types the browser plays in a synthesized media document. */
+export function isPlayableMediaUserContentType(contentType: string): boolean {
+  const essence = mediaTypeEssence(contentType);
+  return !isActiveUserContentType(essence) && /^(audio|video)\//.test(essence);
+}
+
+/** Sandbox policy for one response; only playable media keeps its origin. */
+export function userContentSecurityPolicy(contentType: string): string {
+  return isPlayableMediaUserContentType(contentType)
+    ? USER_MEDIA_CONTENT_SECURITY_POLICY
+    : USER_CONTENT_SECURITY_POLICY;
+}
+
+/** Full header set for one user-content response with the given content type. */
+export function userContentResponseHeaders(
+  contentType: string,
+  filename?: string | null,
+): Record<string, string> {
+  return {
+    ...USER_CONTENT_SECURITY_HEADERS,
+    "Content-Security-Policy": userContentSecurityPolicy(contentType),
+    ...userContentDispositionHeaders(contentType, filename),
+  };
+}

package/src/http/variable-sets-removed.ts

@@ -0,0 +1,122 @@
+import type { VaultApiError } from "@opengeni/contracts";
+import type { Context } from "hono";
+import { HTTPException } from "hono/http-exception";
+
+const VARIABLE_SETS_REMOVED_MESSAGE =
+  "Variable Sets were replaced by vaults. Save secrets with /v1/workspaces/{workspaceId}/vaults and choose a session's vaults with PUT /sessions/{sessionId}/vault-policy.";
+
+/** The RM-1 answer for legacy Variable Set routes (410) and fields (422). */
+export function variableSetsRemovedResponse(
+  c: Context,
+  status: 410 | 422,
+  fields?: readonly string[],
+): Response {
+  const body: VaultApiError = {
+    error: "variable_sets_removed",
+    message: VARIABLE_SETS_REMOVED_MESSAGE,
+    details: { vaultsPath: "/vaults", ...(fields?.length ? { fields: [...fields] } : {}) },
+  };
+  return c.json(body, status);
+}
+
+/** Thrown where a route cannot return directly; `app.onError` renders it. */
+export class VariableSetsRemovedError extends Error {
+  override readonly name = "VariableSetsRemovedError";
+  constructor(readonly fields: readonly string[]) {
+    super(`variable_sets_removed: ${fields.join(", ")}`);
+  }
+}
+
+const CORE_VARIABLE_SETS_REMOVED = /^variable_sets_removed: (\S+) /;
+
+/**
+ * The RM-1 body for a removed-field error from a route or from core's
+ * `variableSetsRemovedError`, or null for any other error.
+ */
+export function variableSetsRemovedErrorResponse(c: Context, error: unknown): Response | null {
+  if (error instanceof VariableSetsRemovedError) {
+    return variableSetsRemovedResponse(c, 422, error.fields);
+  }
+  if (error instanceof HTTPException && error.status === 422) {
+    const field = CORE_VARIABLE_SETS_REMOVED.exec(error.message)?.[1];
+    if (field) return variableSetsRemovedResponse(c, 422, [field]);
+  }
+  return null;
+}
+
+/**
+ * Legacy selection fields that still carry a choice. Empty arrays and null
+ * mean "no Variable Sets" and stay accepted so old clients keep working.
+ */
+export function legacyVariableSetFields(payload: unknown): string[] {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return [];
+  const record = payload as Record<string, unknown>;
+  const fields: string[] = [];
+  for (const field of ["variableSetIds", "defaultVariableSetIds"] as const) {
+    const ids = record[field];
+    if (ids !== undefined && ids !== null && !(Array.isArray(ids) && ids.length === 0)) {
+      fields.push(field);
+    }
+  }
+  for (const field of ["variableSetId", "environmentId"] as const) {
+    if (record[field] !== undefined && record[field] !== null) fields.push(field);
+  }
+  return fields;
+}
+
+/** True when the body explicitly clears a legacy selection (`null` or `[]`). */
+export function clearsLegacyVariableSet(payload: unknown): boolean {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return false;
+  const record = payload as Record<string, unknown>;
+  return (
+    (Object.hasOwn(record, "variableSetId") && record.variableSetId === null) ||
+    (Object.hasOwn(record, "environmentId") && record.environmentId === null) ||
+    (Array.isArray(record.variableSetIds) && record.variableSetIds.length === 0)
+  );
+}
+
+const LEGACY_VARIABLE_SET_FIELDS = [
+  "variableSetIds",
+  "variableSetId",
+  "environmentId",
+  "defaultVariableSetIds",
+] as const;
+
+/**
+ * Drops every (empty) legacy Variable Set field so nothing downstream can act
+ * on one. Call after {@link legacyVariableSetFields} found none set.
+ */
+export function withoutLegacyVariableSetFields(payload: unknown): unknown {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return payload;
+  const rest: Record<string, unknown> = { ...(payload as Record<string, unknown>) };
+  for (const field of LEGACY_VARIABLE_SET_FIELDS) delete rest[field];
+  return rest;
+}
+
+/**
+ * The RM-1 boundary for one JSON body: a 422 `variable_sets_removed` response
+ * when a legacy field still carries a choice, otherwise the body without them.
+ */
+export function rejectLegacyVariableSetFields(
+  c: Context,
+  payload: unknown,
+): { response: Response } | { payload: unknown } {
+  const fields = legacyVariableSetFields(payload);
+  if (fields.length > 0) return { response: variableSetsRemovedResponse(c, 422, fields) };
+  return { payload: withoutLegacyVariableSetFields(payload) };
+}
+
+/**
+ * Old clients send `variableSetId: null` / `environmentId: null` to mean "no
+ * Variable Sets". The create schema only takes the array form, so translate the
+ * accepted empty legacy fields to it. Call after {@link legacyVariableSetFields}.
+ */
+export function withoutEmptyLegacyVariableSetFields(payload: unknown): unknown {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return payload;
+  const record = payload as Record<string, unknown>;
+  if (!Object.hasOwn(record, "variableSetId") && !Object.hasOwn(record, "environmentId")) {
+    return payload;
+  }
+  const { variableSetId: _variableSetId, environmentId: _environmentId, ...rest } = record;
+  return { ...rest, variableSetIds: rest.variableSetIds ?? [] };
+}

package/src/http/websocket-upgrade-dispatch.ts

@@ -0,0 +1,29 @@
+import { localBrowserBoundaryResponse, type LocalBrowserBoundary } from "./local-browser-boundary";
+
+export type ApiWebSocketUpgradeRoute<Server> = {
+  handles(request: Request): boolean;
+  upgrade(request: Request, server: Server): Response | undefined;
+};
+
+export type ApiWebSocketUpgradeDispatch =
+  | { handled: false }
+  | { handled: true; response: Response | undefined };
+
+/**
+ * WebSocket upgrades bypass the Hono app, so the local-mode browser boundary
+ * (./local-browser-boundary.ts) is applied here before a transport upgrades.
+ * Returns `{ handled: false }` when no transport claims the request, so the
+ * caller dispatches it to the app, where the boundary runs as middleware.
+ */
+export function dispatchApiWebSocketUpgrade<Server>(
+  request: Request,
+  server: Server,
+  routes: ReadonlyArray<ApiWebSocketUpgradeRoute<Server>>,
+  localBrowserBoundary: LocalBrowserBoundary | null,
+): ApiWebSocketUpgradeDispatch {
+  const route = routes.find((candidate) => candidate.handles(request));
+  if (!route) return { handled: false };
+  const rejection = localBrowserBoundary?.rejection(request);
+  if (rejection) return { handled: true, response: localBrowserBoundaryResponse(rejection) };
+  return { handled: true, response: route.upgrade(request, server) };
+}