@lukoweb/apitogo 0.2.22 → 0.2.24

package/src/config/v2/gateway-reference.ts

@@ -1,220 +1,220 @@
-import { readFile } from "node:fs/promises";
-import { parse } from "yaml";
-import type { ResolvedGateway } from "./resolve.js";
-
-/** What the gateway checks, in the terms the exported OpenAPI file uses. */
-export type ReferenceOptions = {
-  /** The address callers use. Replaces every server of the spec. */
-  gatewayBaseUrl: string;
-  /** The customer's own API address. It must never appear in the result. */
-  originUrl?: string;
-  jwtRequired: boolean;
-  oidcMetadataUrl?: string;
-  apiKeyRequired: boolean;
-  apiKeyHeader: string;
-  /** Action keys such as `get:/orders`. */
-  publicOperations: ReadonlySet<string>;
-  deniedOperations: ReadonlySet<string>;
-};
-
-/** Header of the API key when the gateway does not say otherwise (same as the platform's OpenAPI export). */
-export const DEFAULT_KEY_HEADER = "Ocp-Apim-Subscription-Key";
-
-const METHODS = [
-  "get",
-  "put",
-  "post",
-  "delete",
-  "options",
-  "head",
-  "patch",
-  "trace",
-] as const;
-
-type Json = Record<string, unknown>;
-
-const isObject = (value: unknown): value is Json =>
-  typeof value === "object" && value !== null && !Array.isArray(value);
-
-/** `GET /orders/` becomes `get:/orders`, the key the platform uses for an operation. */
-export function actionKey(method: string, path: string): string {
-  const trimmed = path.trim();
-  const withSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
-  const normalized =
-    withSlash.length > 1 ? withSlash.replace(/\/+$/, "") || "/" : withSlash;
-  return `${method.trim().toLowerCase()}:${normalized}`;
-}
-
-/** A config entry like `GET /orders` as an action key, or undefined when it has no method and path. */
-export function configActionKey(entry: string): string | undefined {
-  const match = /^\s*([A-Za-z]+)\s+(\S+)\s*$/.exec(entry);
-  return match?.[1] && match[2] ? actionKey(match[1], match[2]) : undefined;
-}
-
-/**
- * What the platform's OpenAPI export is made with, from the config: a token is checked when `access.jwt` is on (the
- * default when `auth` is set), a key unless `access.apiKey` is off.
- */
-export function referenceOptions(
-  gateway: ResolvedGateway,
-  gatewayBaseUrl: string,
-  keyHeaderName?: string,
-): ReferenceOptions {
-  const access = gateway.policies.access;
-  const jwt = access?.jwt ?? gateway.auth !== undefined;
-  const keys = (list?: string[]) =>
-    new Set(
-      (list ?? []).flatMap((entry) => {
-        const key = configActionKey(entry);
-        return key ? [key] : [];
-      }),
-    );
-  return {
-    gatewayBaseUrl,
-    originUrl: gateway.origin.url,
-    jwtRequired: jwt && gateway.auth !== undefined,
-    oidcMetadataUrl: jwt ? gateway.auth?.metadataUrl : undefined,
-    apiKeyRequired: access?.apiKey ?? true,
-    apiKeyHeader: keyHeaderName ?? access?.apiKeyHeader ?? DEFAULT_KEY_HEADER,
-    publicOperations: keys(gateway.policies.operations?.public),
-    deniedOperations: keys(gateway.policies.operations?.deny),
-  };
-}
-
-export class ReferenceSpecError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = "ReferenceSpecError";
-  }
-}
-
-function operationsOf(paths: Json): [string, Json, (typeof METHODS)[number]][] {
-  return Object.entries(paths).flatMap(([path, item]) =>
-    isObject(item)
-      ? METHODS.filter((method) => isObject(item[method])).map(
-          (method) =>
-            [path, item, method] as [string, Json, (typeof METHODS)[number]],
-        )
-      : [],
-  );
-}
-
-/**
- * The document the portal's API page shows. It follows what the platform exports for outside docs tools: servers
- * point at the gateway, the security schemes say what the gateway really checks, denied operations are gone, public
- * operations carry no security, and the origin address never shows (it is replaced by the gateway address).
- */
-export function buildReferenceSpec(
-  specText: string,
-  options: ReferenceOptions,
-): Json {
-  let root: unknown;
-  try {
-    root = parse(specText);
-  } catch {
-    throw new ReferenceSpecError("The OpenAPI file could not be read.");
-  }
-  if (!isObject(root) || typeof root.openapi !== "string")
-    throw new ReferenceSpecError("The OpenAPI file could not be read.");
-
-  const doc = structuredClone(root);
-  const paths = isObject(doc.paths) ? doc.paths : {};
-
-  // Denied operations are removed; a path with nothing left goes too.
-  for (const [path, item, method] of operationsOf(paths))
-    if (options.deniedOperations.has(actionKey(method, path)))
-      delete item[method];
-  for (const [path, item] of Object.entries(paths))
-    if (!isObject(item) || !METHODS.some((method) => method in item))
-      delete paths[path];
-
-  // Public operations need neither token nor key.
-  for (const [path, item, method] of operationsOf(paths))
-    if (options.publicOperations.has(actionKey(method, path)))
-      (item[method] as Json).security = [];
-
-  // Servers on paths and operations would point somewhere else, often at the origin.
-  doc.servers = [{ url: options.gatewayBaseUrl.replace(/\/+$/, "") }];
-  for (const item of Object.values(paths)) {
-    if (!isObject(item)) continue;
-    delete item.servers;
-    for (const method of METHODS) {
-      const operation = item[method];
-      if (isObject(operation)) delete operation.servers;
-    }
-  }
-
-  // The document describes the gateway, not the origin: the origin's own schemes are replaced.
-  const schemes: Json = {};
-  const requirement: Json = {};
-  if (options.jwtRequired) {
-    schemes.bearerAuth = {
-      type: "http",
-      scheme: "bearer",
-      bearerFormat: "JWT",
-    };
-    requirement.bearerAuth = [];
-  }
-  if (options.oidcMetadataUrl)
-    schemes.openIdAuth = {
-      type: "openIdConnect",
-      openIdConnectUrl: options.oidcMetadataUrl,
-    };
-  if (options.apiKeyRequired) {
-    schemes.apiKeyAuth = {
-      type: "apiKey",
-      in: "header",
-      name: options.apiKeyHeader,
-    };
-    requirement.apiKeyAuth = [];
-  }
-  const components = isObject(doc.components) ? doc.components : {};
-  if (Object.keys(schemes).length > 0) components.securitySchemes = schemes;
-  else delete components.securitySchemes;
-  if (Object.keys(components).length > 0) doc.components = components;
-  else delete doc.components;
-  // One requirement with both schemes means both are needed together.
-  doc.security = Object.keys(requirement).length > 0 ? [requirement] : [];
-  for (const [, item, method] of operationsOf(paths)) {
-    const operation = item[method] as Json;
-    if (Array.isArray(operation.security) && operation.security.length > 0)
-      delete operation.security;
-  }
-
-  return JSON.parse(hideOrigin(JSON.stringify(doc), options)) as Json;
-}
-
-/** The origin address must not show anywhere, not even in a description. */
-function hideOrigin(text: string, options: ReferenceOptions): string {
-  const origin = options.originUrl?.trim().replace(/\/+$/, "");
-  if (!origin) return text;
-  const gateway = options.gatewayBaseUrl.trim().replace(/\/+$/, "");
-  // JSON.stringify leaves slashes as they are, so the plain address is what to look for.
-  const pattern = new RegExp(
-    origin.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&"),
-    "gi",
-  );
-  return text.replace(pattern, () => gateway);
-}
-
-/** Reads the gateway's OpenAPI file and builds the reference document. Returns JSON text, one key order per input. */
-export async function renderReferenceSpec(
-  gateway: ResolvedGateway,
-  gatewayBaseUrl: string,
-  keyHeaderName?: string,
-): Promise<string> {
-  const file = gateway.specs[0];
-  if (!file)
-    throw new ReferenceSpecError("gateway.specs lists no OpenAPI file.");
-  let text: string;
-  try {
-    text = await readFile(file, "utf8");
-  } catch {
-    throw new ReferenceSpecError(`Cannot read the OpenAPI file ${file}.`);
-  }
-  const spec = buildReferenceSpec(
-    text,
-    referenceOptions(gateway, gatewayBaseUrl, keyHeaderName),
-  );
-  return `${JSON.stringify(spec, null, 2)}\n`;
-}
+import { readFile } from "node:fs/promises";
+import { parse } from "yaml";
+import type { ResolvedGateway } from "./resolve.js";
+
+/** What the gateway checks, in the terms the exported OpenAPI file uses. */
+export type ReferenceOptions = {
+  /** The address callers use. Replaces every server of the spec. */
+  gatewayBaseUrl: string;
+  /** The customer's own API address. It must never appear in the result. */
+  originUrl?: string;
+  jwtRequired: boolean;
+  oidcMetadataUrl?: string;
+  apiKeyRequired: boolean;
+  apiKeyHeader: string;
+  /** Action keys such as `get:/orders`. */
+  publicOperations: ReadonlySet<string>;
+  deniedOperations: ReadonlySet<string>;
+};
+
+/** Header of the API key when the gateway does not say otherwise (same as the platform's OpenAPI export). */
+export const DEFAULT_KEY_HEADER = "Ocp-Apim-Subscription-Key";
+
+const METHODS = [
+  "get",
+  "put",
+  "post",
+  "delete",
+  "options",
+  "head",
+  "patch",
+  "trace",
+] as const;
+
+type Json = Record<string, unknown>;
+
+const isObject = (value: unknown): value is Json =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/** `GET /orders/` becomes `get:/orders`, the key the platform uses for an operation. */
+export function actionKey(method: string, path: string): string {
+  const trimmed = path.trim();
+  const withSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+  const normalized =
+    withSlash.length > 1 ? withSlash.replace(/\/+$/, "") || "/" : withSlash;
+  return `${method.trim().toLowerCase()}:${normalized}`;
+}
+
+/** A config entry like `GET /orders` as an action key, or undefined when it has no method and path. */
+export function configActionKey(entry: string): string | undefined {
+  const match = /^\s*([A-Za-z]+)\s+(\S+)\s*$/.exec(entry);
+  return match?.[1] && match[2] ? actionKey(match[1], match[2]) : undefined;
+}
+
+/**
+ * What the platform's OpenAPI export is made with, from the config: a token is checked when `access.jwt` is on (the
+ * default when `auth` is set), a key unless `access.apiKey` is off.
+ */
+export function referenceOptions(
+  gateway: ResolvedGateway,
+  gatewayBaseUrl: string,
+  keyHeaderName?: string,
+): ReferenceOptions {
+  const access = gateway.policies.access;
+  const jwt = access?.jwt ?? gateway.auth !== undefined;
+  const keys = (list?: string[]) =>
+    new Set(
+      (list ?? []).flatMap((entry) => {
+        const key = configActionKey(entry);
+        return key ? [key] : [];
+      }),
+    );
+  return {
+    gatewayBaseUrl,
+    originUrl: gateway.origin.url,
+    jwtRequired: jwt && gateway.auth !== undefined,
+    oidcMetadataUrl: jwt ? gateway.auth?.metadataUrl : undefined,
+    apiKeyRequired: access?.apiKey ?? true,
+    apiKeyHeader: keyHeaderName ?? access?.apiKeyHeader ?? DEFAULT_KEY_HEADER,
+    publicOperations: keys(gateway.policies.operations?.public),
+    deniedOperations: keys(gateway.policies.operations?.deny),
+  };
+}
+
+export class ReferenceSpecError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ReferenceSpecError";
+  }
+}
+
+function operationsOf(paths: Json): [string, Json, (typeof METHODS)[number]][] {
+  return Object.entries(paths).flatMap(([path, item]) =>
+    isObject(item)
+      ? METHODS.filter((method) => isObject(item[method])).map(
+          (method) =>
+            [path, item, method] as [string, Json, (typeof METHODS)[number]],
+        )
+      : [],
+  );
+}
+
+/**
+ * The document the portal's API page shows. It follows what the platform exports for outside docs tools: servers
+ * point at the gateway, the security schemes say what the gateway really checks, denied operations are gone, public
+ * operations carry no security, and the origin address never shows (it is replaced by the gateway address).
+ */
+export function buildReferenceSpec(
+  specText: string,
+  options: ReferenceOptions,
+): Json {
+  let root: unknown;
+  try {
+    root = parse(specText);
+  } catch {
+    throw new ReferenceSpecError("The OpenAPI file could not be read.");
+  }
+  if (!isObject(root) || typeof root.openapi !== "string")
+    throw new ReferenceSpecError("The OpenAPI file could not be read.");
+
+  const doc = structuredClone(root);
+  const paths = isObject(doc.paths) ? doc.paths : {};
+
+  // Denied operations are removed; a path with nothing left goes too.
+  for (const [path, item, method] of operationsOf(paths))
+    if (options.deniedOperations.has(actionKey(method, path)))
+      delete item[method];
+  for (const [path, item] of Object.entries(paths))
+    if (!isObject(item) || !METHODS.some((method) => method in item))
+      delete paths[path];
+
+  // Public operations need neither token nor key.
+  for (const [path, item, method] of operationsOf(paths))
+    if (options.publicOperations.has(actionKey(method, path)))
+      (item[method] as Json).security = [];
+
+  // Servers on paths and operations would point somewhere else, often at the origin.
+  doc.servers = [{ url: options.gatewayBaseUrl.replace(/\/+$/, "") }];
+  for (const item of Object.values(paths)) {
+    if (!isObject(item)) continue;
+    delete item.servers;
+    for (const method of METHODS) {
+      const operation = item[method];
+      if (isObject(operation)) delete operation.servers;
+    }
+  }
+
+  // The document describes the gateway, not the origin: the origin's own schemes are replaced.
+  const schemes: Json = {};
+  const requirement: Json = {};
+  if (options.jwtRequired) {
+    schemes.bearerAuth = {
+      type: "http",
+      scheme: "bearer",
+      bearerFormat: "JWT",
+    };
+    requirement.bearerAuth = [];
+  }
+  if (options.oidcMetadataUrl)
+    schemes.openIdAuth = {
+      type: "openIdConnect",
+      openIdConnectUrl: options.oidcMetadataUrl,
+    };
+  if (options.apiKeyRequired) {
+    schemes.apiKeyAuth = {
+      type: "apiKey",
+      in: "header",
+      name: options.apiKeyHeader,
+    };
+    requirement.apiKeyAuth = [];
+  }
+  const components = isObject(doc.components) ? doc.components : {};
+  if (Object.keys(schemes).length > 0) components.securitySchemes = schemes;
+  else delete components.securitySchemes;
+  if (Object.keys(components).length > 0) doc.components = components;
+  else delete doc.components;
+  // One requirement with both schemes means both are needed together.
+  doc.security = Object.keys(requirement).length > 0 ? [requirement] : [];
+  for (const [, item, method] of operationsOf(paths)) {
+    const operation = item[method] as Json;
+    if (Array.isArray(operation.security) && operation.security.length > 0)
+      delete operation.security;
+  }
+
+  return JSON.parse(hideOrigin(JSON.stringify(doc), options)) as Json;
+}
+
+/** The origin address must not show anywhere, not even in a description. */
+function hideOrigin(text: string, options: ReferenceOptions): string {
+  const origin = options.originUrl?.trim().replace(/\/+$/, "");
+  if (!origin) return text;
+  const gateway = options.gatewayBaseUrl.trim().replace(/\/+$/, "");
+  // JSON.stringify leaves slashes as they are, so the plain address is what to look for.
+  const pattern = new RegExp(
+    origin.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&"),
+    "gi",
+  );
+  return text.replace(pattern, () => gateway);
+}
+
+/** Reads the gateway's OpenAPI file and builds the reference document. Returns JSON text, one key order per input. */
+export async function renderReferenceSpec(
+  gateway: ResolvedGateway,
+  gatewayBaseUrl: string,
+  keyHeaderName?: string,
+): Promise<string> {
+  const file = gateway.specs[0];
+  if (!file)
+    throw new ReferenceSpecError("gateway.specs lists no OpenAPI file.");
+  let text: string;
+  try {
+    text = await readFile(file, "utf8");
+  } catch {
+    throw new ReferenceSpecError(`Cannot read the OpenAPI file ${file}.`);
+  }
+  const spec = buildReferenceSpec(
+    text,
+    referenceOptions(gateway, gatewayBaseUrl, keyHeaderName),
+  );
+  return `${JSON.stringify(spec, null, 2)}\n`;
+}