@lukoweb/apitogo 0.2.2 → 0.2.12

package/src/config/v2/rules.ts

@@ -253,11 +253,64 @@ function isIpLiteral(hostname: string): boolean {
   return /^\d{1,3}(\.\d{1,3}){3}$/.test(hostname) || hostname.startsWith("[");
 }
 
+/** The credential the gateway sends to the origin: a header needs a name and a secret; mtls is not available yet. */
+function originAuthRules(
+  origin: NonNullable<ResolvedConfigV2["gateway"]>["origin"],
+  out: Collector,
+) {
+  const auth = origin.auth;
+  if (!auth) return;
+  const base = "gateway.origin.auth";
+  if (auth.type === "header") {
+    if (!auth.name)
+      out.error({
+        code: "GATEWAY_ORIGIN_INCOMPLETE",
+        path: `${base}.name`,
+        message: "origin.auth.type is header, so origin.auth.name is required.",
+        hint: 'For example: "X-Origin-Key".',
+      });
+    if (!auth.value)
+      out.error({
+        code: "GATEWAY_ORIGIN_INCOMPLETE",
+        path: `${base}.value`,
+        message:
+          "origin.auth.type is header, so origin.auth.value is required.",
+        hint: 'A secret reference, for example "secret:ORIGIN_KEY". Store it with `apitogo secrets set ORIGIN_KEY`.',
+      });
+  } else if (auth.type === "none" && (auth.name || auth.value)) {
+    out.error({
+      code: "GATEWAY_ORIGIN_INVALID",
+      path: base,
+      message: "origin.auth.type is none, but a name or value is set.",
+      hint: 'Remove them, or set the type to "header".',
+    });
+  } else if (auth.type === "mtls") {
+    out.error({
+      code: "GATEWAY_CAPABILITY_UNSUPPORTED",
+      path: `${base}.type`,
+      message:
+        "Client certificates (mtls) for the origin are not available yet.",
+      hint: 'Use type "header" with a secret.',
+    });
+  }
+}
+
 async function gatewayRules(resolved: ResolvedConfigV2, out: Collector) {
   const gateway = resolved.gateway;
   if (!gateway?.enabled) return;
   const origin = gateway.origin;
 
+  (gateway.policies.cors ?? []).forEach((site, index) => {
+    const { pathname, search, hash } = new URL(site);
+    if (pathname === "/" && !search && !hash && !site.endsWith("/")) return;
+    out.error({
+      code: "GATEWAY_CORS_ORIGIN_INVALID",
+      path: `gateway.policies.cors[${index}]`,
+      message: `"${site}" is not a browser origin: it has a path, a query or a trailing slash.`,
+      hint: `Use only scheme and host, for example "${new URL(site).origin}".`,
+    });
+  });
+
   if (origin.mode === "managed") {
     for (const field of ["source", "runtime", "runtimeVersion"] as const) {
       if (!origin[field]) {
@@ -340,6 +393,17 @@ async function gatewayRules(resolved: ResolvedConfigV2, out: Collector) {
     }
   }
 
+  originAuthRules(origin, out);
+  if (gateway.specs.length > 1) {
+    out.warn({
+      code: "GATEWAY_SPEC_INVALID",
+      path: "gateway.specs",
+      message:
+        "gateway.specs lists several files, but the platform takes one OpenAPI file per gateway, so deploy will refuse it.",
+      hint: "Merge them into one file.",
+    });
+  }
+
   for (const [index, spec] of gateway.specs.entries())
     await specRule(spec, index, resolved, out);
 

package/src/config/v2/schema.ts

@@ -60,6 +60,20 @@ const GatewayOriginSchema = z.strictObject({
   runtimeVersion: nonEmpty.optional(),
   exclude: pathList.optional(),
   url: httpsUrl.optional(),
+  /** Path the platform probes to check the origin, for example `/health`. */
+  healthPath: z
+    .string()
+    .regex(/^\/(?!\/)/, { error: 'must start with a single "/"' })
+    .optional(),
+  timeoutSeconds: z.int().min(1).max(120).optional(),
+  /** What the gateway sends to the origin as credential. The value is always a secret reference. */
+  auth: z
+    .strictObject({
+      type: z.enum(["none", "header", "mtls"]),
+      name: nonEmpty.optional(),
+      value: secretRef.optional(),
+    })
+    .optional(),
 });
 
 export const GatewaySchema = z.strictObject({
@@ -67,6 +81,10 @@ export const GatewaySchema = z.strictObject({
   provider: nonEmpty.optional(),
   origin: GatewayOriginSchema,
   specs: z.array(path).min(1, { error: "needs at least one OpenAPI file" }),
+  /** Who may read the OpenAPI file the platform publishes for this gateway. Default: public. */
+  export: z
+    .strictObject({ access: z.enum(["public", "authenticated"]).optional() })
+    .optional(),
   auth: z
     .strictObject({
       mode: z.enum(["identity", "oidc"]),
@@ -77,19 +95,35 @@ export const GatewaySchema = z.strictObject({
     .optional(),
   policies: z
     .strictObject({
+      access: z
+        .strictObject({
+          jwt: z.boolean().optional(),
+          apiKey: z.boolean().optional(),
+          apiKeyHeader: nonEmpty.optional(),
+          bindKeyToToken: z.boolean().optional(),
+        })
+        .optional(),
       rateLimit: z
         .strictObject({
           calls: z.int().positive(),
           periodSeconds: z.int().positive(),
+          scope: z.enum(["key", "entitlement"]).optional(),
         })
         .optional(),
       quota: z
         .strictObject({
           calls: z.int().positive(),
           periodDays: z.int().min(1),
+          scope: z.enum(["key", "entitlement"]).optional(),
         })
         .optional(),
       cors: z.array(z.url()).optional(),
+      operations: z
+        .strictObject({
+          public: z.array(nonEmpty).optional(),
+          deny: z.array(nonEmpty).optional(),
+        })
+        .optional(),
     })
     .optional(),
 });

package/src/config/v2/services.ts

@@ -642,3 +642,20 @@ export async function setProjectId(
   await writeConfig(resolved.configPath, next);
   return true;
 }
+
+/** Removes `project.id` when it is the given id: the project is gone, so the link would only point at nothing. */
+export async function clearProjectId(
+  dir: string,
+  projectId: string,
+): Promise<boolean> {
+  const { config, resolved } = loadConfigV2(dir);
+  if (config.project?.id !== projectId) return false;
+  const { id: _id, ...project } = config.project;
+  const { project: _old, ...rest } = config;
+  const next = reparse(resolved.configPath, {
+    ...rest,
+    ...(Object.keys(project).length > 0 ? { project } : {}),
+  });
+  await writeConfig(resolved.configPath, next);
+  return true;
+}

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