OmniRoute/scripts/check/check-openapi-security-tiers.mjs

#!/usr/bin/env node
/**
 * Cross-references openapi.yaml x-loopback-only / x-always-protected annotations
 * against the compile-time constants in src/server/authz/routeGuard.ts.
 *
 * Fails if any YAML annotation disagrees with the routeGuard.ts constants.
 */

import fs from "node:fs";
import path from "node:path";
import * as yaml from "js-yaml";
import { isLocalOnlyDocPath, readRegexArray, readStringArray } from "./routeGuardConstants.mjs";

const ROOT = process.cwd();
const OPENAPI_PATH = path.join(ROOT, "docs", "openapi.yaml");
const ROUTE_GUARD_PATH = path.join(ROOT, "src", "server", "authz", "routeGuard.ts");

const guardSrc = fs.readFileSync(ROUTE_GUARD_PATH, "utf-8");

// Both halves of isLocalOnlyPath(): the flat prefixes AND the regex patterns.
// Reading only the prefixes reported regex-gated and imported-constant routes
// as unprotected (see routeGuardConstants.mjs).
let LOCAL_ONLY_PREFIXES;
let LOCAL_ONLY_PATTERNS;
let ALWAYS_PROTECTED_PATHS;
try {
  LOCAL_ONLY_PREFIXES = readStringArray(guardSrc, "LOCAL_ONLY_API_PREFIXES", { root: ROOT });
  LOCAL_ONLY_PATTERNS = readRegexArray(guardSrc, "LOCAL_ONLY_API_PATTERNS");
  ALWAYS_PROTECTED_PATHS = readStringArray(guardSrc, "ALWAYS_PROTECTED_API_PATHS", { root: ROOT });
} catch (err) {
  console.error(`[openapi-security-tiers] FAIL — ${err.message}`);
  process.exit(1);
}

if (LOCAL_ONLY_PREFIXES.length === 0 || ALWAYS_PROTECTED_PATHS.length === 0) {
  console.error("[openapi-security-tiers] FAIL — could not parse routeGuard.ts constants");
  process.exit(1);
}

const localOnlyGuards = { prefixes: LOCAL_ONLY_PREFIXES, patterns: LOCAL_ONLY_PATTERNS };

const raw = yaml.load(fs.readFileSync(OPENAPI_PATH, "utf-8"));
const paths = raw.paths || {};

const errors = [];

for (const [pathStr, methods] of Object.entries(paths)) {
  if (!methods || typeof methods !== "object") continue;
  for (const [method, spec] of Object.entries(methods)) {
    if (!["get", "post", "put", "patch", "delete"].includes(method) || !spec) continue;

    if (spec["x-loopback-only"] === true) {
      if (!isLocalOnlyDocPath(pathStr, localOnlyGuards)) {
        errors.push(
          `${method.toUpperCase()} ${pathStr}: has x-loopback-only but is NOT covered by ` +
            `LOCAL_ONLY_API_PREFIXES [${LOCAL_ONLY_PREFIXES.join(", ")}] ` +
            `nor by LOCAL_ONLY_API_PATTERNS [${LOCAL_ONLY_PATTERNS.join(", ")}]`
        );
      }
    }

    if (spec["x-always-protected"] === true) {
      const matchesPath = ALWAYS_PROTECTED_PATHS.some(
        (p) => pathStr === p || pathStr.startsWith(`${p}/`)
      );
      if (!matchesPath) {
        errors.push(
          `${method.toUpperCase()} ${pathStr}: has x-always-protected but is NOT in ` +
            `ALWAYS_PROTECTED_API_PATHS [${ALWAYS_PROTECTED_PATHS.join(", ")}]`
        );
      }
    }
  }
}

// Reverse pass: every YAML path that falls under a LOCAL_ONLY prefix should
// carry `x-loopback-only: true` on every method, otherwise external API
// consumers have no signal that the route is loopback-restricted. Closes the
// "new spawn-capable route added without annotation" regression class.
//
// Currently reported as warnings (non-fatal) because the v3.8.4 release ships
// with a known annotation gap on /api/services/* and /api/cli-tools/runtime/*
// that will be patched in a follow-up doc-only PR. Promote to errors once the
// backlog is cleared.
const reverseWarnings = [];
for (const [pathStr, methods] of Object.entries(paths)) {
  if (!methods || typeof methods !== "object") continue;
  if (!isLocalOnlyDocPath(pathStr, localOnlyGuards)) continue;
  for (const [method, spec] of Object.entries(methods)) {
    if (!["get", "post", "put", "patch", "delete"].includes(method) || !spec) continue;
    if (spec["x-loopback-only"] !== true) {
      reverseWarnings.push(
        `${method.toUpperCase()} ${pathStr}: is LOCAL_ONLY per routeGuard ` +
          `but is missing x-loopback-only: true annotation`
      );
    }
  }
}

if (reverseWarnings.length > 0) {
  console.warn(
    `[openapi-security-tiers] WARN — ${reverseWarnings.length} LOCAL_ONLY paths missing x-loopback-only annotation (non-fatal, follow-up doc PR):`
  );
  reverseWarnings.forEach((w) => console.warn(`  - ${w}`));
}

if (errors.length === 0) {
  console.log("[openapi-security-tiers] PASS — all security tier annotations match routeGuard.ts");
  process.exit(0);
} else {
  console.error(`[openapi-security-tiers] FAIL — ${errors.length} annotation mismatches:`);
  errors.forEach((e) => console.error(`  - ${e}`));
  process.exit(1);
}