@lukoweb/apitogo 0.2.10 → 0.2.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lukoweb/apitogo",
-  "version": "0.2.10",
+  "version": "0.2.13",
   "type": "module",
   "sideEffects": [
     "**/*.css",

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

@@ -0,0 +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`;
+}

package/src/config/v2/index.ts

@@ -65,6 +65,14 @@ export {
   writeManifest,
 } from "./manifest.js";
 export { MANIFEST_FILE, manifestPathFor } from "./paths.js";
+export {
+  buildReferenceSpec,
+  DEFAULT_KEY_HEADER,
+  type ReferenceOptions,
+  ReferenceSpecError,
+  referenceOptions,
+  renderReferenceSpec,
+} from "./gateway-reference.js";
 export {
   type DerivedCorsSite,
   derivedCorsSites,

package/src/config/v2/wrapper.ts

@@ -1,6 +1,10 @@
 import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { ConfigError, type ConfigIssue } from "./errors.js";
+import {
+  ReferenceSpecError,
+  renderReferenceSpec,
+} from "./gateway-reference.js";
 import {
   hasCapability,
   missingManifestServices,
@@ -43,8 +47,10 @@ const PLANS_CONSOLE_CAPABILITIES = [
 export type PortalPlan = {
   /** Docs pages, navigation and search APItoGo builds. */
   docs: boolean;
-  /** OpenAPI reference pages and playground. */
+  /** OpenAPI reference pages and playground, built from the gateway's OpenAPI file. */
   apiReference: boolean;
+  /** Where the reference points its calls, and the header of the API key; set when `apiReference` is true. */
+  gatewayReference?: { baseUrl: string; keyHeaderName?: string };
   /** OpenID sign-in against the identity issuer. */
   auth?: {
     issuer: string;
@@ -144,11 +150,11 @@ export function planPortal(
   const skipped: PortalPlan["skipped"] = [];
   const skip = (piece: string, reason: string) =>
     void skipped.push({ piece, reason });
-  const { identity, plans } = manifest.services;
+  const { identity, plans, gateway } = manifest.services;
 
   const plan: PortalPlan = {
     docs: profile.modules.docs,
-    apiReference: profile.pipelines.openapi,
+    apiReference: false,
     userPanel: false,
     signup: false,
     skipped,
@@ -157,6 +163,22 @@ export function planPortal(
 
   if (!profile.enabled) return plan;
 
+  // The API page is built from the gateway's OpenAPI file and calls the gateway, so it needs the gateway's address.
+  if (profile.pipelines.openapi) {
+    if (!gateway) skip("api reference", "services.json has no gateway entry");
+    else if (!serviceReady(gateway))
+      skip("api reference", `gateway is ${gateway.status}, not ready`);
+    else if (!gateway.baseUrl)
+      skip("api reference", "the gateway entry has no base URL yet");
+    else {
+      plan.apiReference = true;
+      plan.gatewayReference = {
+        baseUrl: gateway.baseUrl,
+        keyHeaderName: gateway.keyHeaderName,
+      };
+    }
+  }
+
   if (!profile.console.enabled) {
     skip("console", "portal.console.enabled is false");
     return plan;
@@ -207,6 +229,12 @@ const json = (value: unknown) => JSON.stringify(value, null, 2);
 /** Name of the site config the wrapper imports, next to it in `generated/`. */
 export const SITE_CONFIG_FILE = "apitogo.config.json";
 
+/** The gateway's OpenAPI document as the portal shows it, inside `generated/`. */
+export const REFERENCE_SPEC_FILE = "openapi/gateway.json";
+
+/** Route of the API reference page. */
+export const API_REFERENCE_PATH = "api";
+
 /**
  * The site settings (title, modules, docs globs, theme, sign-in) in the shape the existing build reads from
  * `apitogo.config.json`. It is generated, never edited, and lives in `generated/`.
@@ -237,6 +265,24 @@ export function buildSiteConfig(
           },
         }
       : {}),
+    ...(plan.apiReference
+      ? {
+          apis: [
+            {
+              type: "file",
+              input: `./${REFERENCE_SPEC_FILE}`,
+              path: API_REFERENCE_PATH,
+            },
+          ],
+          navigation: [
+            {
+              type: "link",
+              to: `/${API_REFERENCE_PATH}`,
+              label: "API Reference",
+            },
+          ],
+        }
+      : {}),
     ...(theme !== undefined ? { theme } : {}),
     ...(plan.auth ? { authentication: { type: "openid", ...plan.auth } } : {}),
     ...(plan.preview ? { preview: true } : {}),
@@ -298,6 +344,8 @@ export type PreparedPortal = {
   wrapper: string;
   /** Contents of the generated site config the wrapper imports. */
   siteConfig: Record<string, unknown>;
+  /** The gateway's OpenAPI document for the API page (JSON text), when the plan builds one. */
+  referenceSpec?: string;
   /** The manifest to ship at the site root, when there is a deployed one. */
   publishedManifest?: ServiceManifest;
   /** Absolute path the wrapper was written to, under the state directory's `generated/`. */
@@ -363,6 +411,25 @@ export async function preparePortal(
   }
 
   const plan = planPortal(profile, effective);
+  let referenceSpec: string | undefined;
+  if (plan.apiReference && plan.gatewayReference && resolved.gateway) {
+    try {
+      referenceSpec = await renderReferenceSpec(
+        resolved.gateway,
+        plan.gatewayReference.baseUrl,
+        plan.gatewayReference.keyHeaderName,
+      );
+    } catch (error) {
+      if (!(error instanceof ReferenceSpecError)) throw error;
+      // `check` reports a bad OpenAPI file as an error. The build goes on without the page.
+      plan.apiReference = false;
+      plan.gatewayReference = undefined;
+      plan.skipped.push({
+        piece: "api reference",
+        reason: `${error.message} The API page is left out.`,
+      });
+    }
+  }
   const siteConfig = buildSiteConfig(resolved, plan, await readTheme(resolved));
   const wrapper = renderWrapper(plan);
   const wrapperPath = path.join(resolved.state.generatedDir, WRAPPER_FILE);
@@ -372,6 +439,16 @@ export async function preparePortal(
       path.join(path.dirname(wrapperPath), SITE_CONFIG_FILE),
       `${JSON.stringify(siteConfig, null, 2)}\n`,
     );
+    const referenceFile = path.join(
+      path.dirname(wrapperPath),
+      REFERENCE_SPEC_FILE,
+    );
+    if (referenceSpec !== undefined) {
+      await mkdir(path.dirname(referenceFile), { recursive: true });
+      await writeFile(referenceFile, referenceSpec);
+    } else {
+      await rm(referenceFile, { force: true });
+    }
     const temporary = `${wrapperPath}.${process.pid}.tmp`;
     try {
       await writeFile(temporary, wrapper, "utf8");
@@ -386,6 +463,7 @@ export async function preparePortal(
     plan,
     wrapper,
     siteConfig,
+    referenceSpec,
     // Without a console there are no console links to offer, so a docs-only portal ships no manifest.
     publishedManifest:
       manifestSource === "file" && profile.console.enabled