@zudojs/openapi 0.1.0 → 1.2.0

package/dist/openApiUi/openApiUi.core.js

@@ -0,0 +1,157 @@
+/**
+ * @zudojs/openapi/openApiUi
+ *
+ * Renders a branded documentation page (Swagger UI or ReDoc) for a served
+ * OpenAPI document. The page carries the Zudo mark in its header and as its
+ * favicon, and reads the specification from `specUrl`.
+ *
+ * The returned string is a complete HTML document; serve it with
+ * `content-type: text/html`. {@link OpenAPIManager.toUIResponse} does that.
+ */
+import { ZUDO_FAVICON_DATA_URI, ZUDO_MARK_DATA_URI, ZUDO_SITE_URL, ZUDO_WORDMARK_DARK_DATA_URI, } from "./openApiUi.brand.js";
+const DEFAULT_TITLE = "API reference";
+const SWAGGER_ASSETS = "https://unpkg.com/swagger-ui-dist@5";
+const REDOC_ASSETS = "https://cdn.redoc.ly/redoc/latest/bundles";
+/** The default logo used by every branded page and by `info["x-logo"]`. */
+export function zudoLogo(overrides) {
+    return Object.freeze({
+        url: ZUDO_MARK_DATA_URI,
+        href: ZUDO_SITE_URL,
+        altText: "Zudo",
+        backgroundColor: "#FAFAF9",
+        ...overrides,
+    });
+}
+/** Escapes text for safe interpolation into HTML attribute or text nodes. */
+export function escapeHtml(value) {
+    return value
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
+}
+/** Serialises a value for an inline `<script>` without letting `</script>` through. */
+function jsLiteral(value) {
+    return JSON.stringify(value)
+        .replace(/</g, "\\u003c")
+        .replace(/\u2028/g, "\\u2028")
+        .replace(/\u2029/g, "\\u2029");
+}
+/**
+ * Rejects URLs that could execute script when placed in `src`/`href`.
+ *
+ * The scheme is read after stripping ASCII control characters, because the
+ * URL parser browsers apply does the same: `java\nscript:alert(1)` is a
+ * `javascript:` URL to every browser and nothing to a regex that only
+ * looks at the string as written. `data:` is accepted for images only —
+ * the assets base is interpolated into `<script src>`, where a
+ * `data:text/javascript,` base would run inline.
+ */
+function safeUrl(value) {
+    const trimmed = value.trim();
+    const normalized = trimmed.replace(/[\u0000-\u0020\u007f]/g, "");
+    const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(normalized)?.[1]?.toLowerCase();
+    if (scheme === "javascript" || scheme === "vbscript") {
+        throw new TypeError(`Refusing to render a "${scheme}:" URL`);
+    }
+    if (scheme === "data" && !/^data:image\//i.test(normalized)) {
+        throw new TypeError('Refusing to render a non-image "data:" URL; only data:image/* is allowed.');
+    }
+    // Attributes are always double-quoted here, so a single quote (common in
+    // data URIs) can stay as-is.
+    return trimmed
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+/**
+ * Guards the one place caller-supplied text reaches the page unescaped.
+ *
+ * A `<style>` element ends at the first `</style`, whatever the CSS around it
+ * says, so `customCss` containing that sequence closes the block early and
+ * everything after it is parsed as HTML — a script tag included. There is no
+ * escape that keeps the CSS valid, so this refuses rather than mangles.
+ */
+function safeCss(css) {
+    if (css === undefined)
+        return "";
+    if (/<\/\s*style/i.test(css)) {
+        throw new TypeError("customCss may not contain a closing </style> tag: it would end the " +
+            "style block and let the rest be parsed as HTML.");
+    }
+    return css;
+}
+const THEME_CSS = `
+:root{--zd-ink:#1A1A2E;--zd-red:#C0392B;--zd-bg:#FAFAF9;--zd-border:#E5E7EB}
+*{border-radius:0!important}
+html,body{margin:0;background:var(--zd-bg);font-family:Inter,system-ui,-apple-system,"Segoe UI",sans-serif}
+.zudo-bar{position:sticky;top:0;z-index:50;display:flex;align-items:center;gap:14px;height:56px;padding:0 20px;background:var(--zd-ink);color:var(--zd-bg);border-bottom:3px solid var(--zd-red)}
+.zudo-bar a{display:inline-flex;align-items:center;color:inherit;text-decoration:none}
+.zudo-bar img{height:22px;width:auto;display:block}
+.zudo-bar .zudo-sep{width:1px;height:22px;background:rgba(250,250,249,.25)}
+.zudo-bar .zudo-title{font-weight:800;font-size:14px;letter-spacing:.02em;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
+.zudo-bar .zudo-spec{margin-left:auto;font:700 11px/1 ui-monospace,SFMono-Regular,Menlo,monospace;letter-spacing:.06em;text-transform:uppercase;color:rgba(250,250,249,.75);border:2px solid rgba(250,250,249,.3);padding:6px 10px}
+.zudo-bar .zudo-spec:hover{border-color:var(--zd-bg);color:var(--zd-bg)}
+.zudo-foot{padding:16px 20px;border-top:1px solid var(--zd-border);color:#6B7280;font-size:12px;display:flex;gap:8px;align-items:center}
+.zudo-foot img{height:14px;width:auto}
+.swagger-ui .topbar{display:none}
+.swagger-ui .info .title{font-weight:900;letter-spacing:-.01em;color:var(--zd-ink)}
+.swagger-ui .opblock{border-width:2px;box-shadow:none}
+.swagger-ui .btn{border-width:2px;font-weight:700}
+.swagger-ui .btn.execute{background:var(--zd-red);border-color:var(--zd-red)}
+.swagger-ui .scheme-container{box-shadow:none;border-bottom:1px solid var(--zd-border);background:#fff}
+`;
+function header(options, title) {
+    const logo = options.logo === undefined ? zudoLogo({ url: ZUDO_WORDMARK_DARK_DATA_URI }) : options.logo;
+    const logoHtml = logo === false
+        ? ""
+        : `<a class="zudo-logo" href="${safeUrl(logo.href ?? ZUDO_SITE_URL)}" rel="noopener"><img src="${safeUrl(logo.url)}" alt="${escapeHtml(logo.altText ?? "Zudo")}"></a><span class="zudo-sep" aria-hidden="true"></span>`;
+    return (`<header class="zudo-bar">${logoHtml}<span class="zudo-title">${escapeHtml(title)}</span>` +
+        `<a class="zudo-spec" href="${safeUrl(options.specUrl)}">Open spec</a></header>`);
+}
+function footer() {
+    return `<footer class="zudo-foot"><span>Generated by</span><a href="${ZUDO_SITE_URL}" rel="noopener"><img src="${ZUDO_MARK_DATA_URI}" alt="Zudo"></a><span>@zudojs/openapi</span></footer>`;
+}
+function head(options, title, extra) {
+    const favicon = options.favicon === false
+        ? ""
+        : `<link rel="icon" href="${safeUrl(options.favicon ?? ZUDO_FAVICON_DATA_URI)}">`;
+    return (`<!doctype html><html lang="en"><head><meta charset="utf-8">` +
+        `<meta name="viewport" content="width=device-width,initial-scale=1">` +
+        `<meta name="theme-color" content="#1A1A2E">` +
+        `<title>${escapeHtml(title)}</title>${favicon}${extra}` +
+        `<style>${THEME_CSS}${safeCss(options.customCss)}</style></head>`);
+}
+/** Renders a complete, branded documentation page for `options.specUrl`. */
+export function renderOpenAPIUI(options) {
+    if (!options || typeof options.specUrl !== "string" || !options.specUrl.trim()) {
+        throw new TypeError("renderOpenAPIUI requires a specUrl");
+    }
+    const title = options.title ?? DEFAULT_TITLE;
+    const renderer = options.renderer ?? "swagger";
+    if (renderer === "redoc") {
+        const base = (options.assetsBaseUrl ?? REDOC_ASSETS).replace(/(?<!\/)\/+$/, "");
+        return (head(options, title, "") +
+            `<body>${header(options, title)}` +
+            `<redoc spec-url="${safeUrl(options.specUrl)}" hide-hostname></redoc>` +
+            `<script src="${safeUrl(base)}/redoc.standalone.js"></script>` +
+            `${footer()}</body></html>`);
+    }
+    const base = (options.assetsBaseUrl ?? SWAGGER_ASSETS).replace(/(?<!\/)\/+$/, "");
+    const config = {
+        url: options.specUrl,
+        dom_id: "#zudo-openapi",
+        deepLinking: true,
+        displayRequestDuration: true,
+        tryItOutEnabled: true,
+        ...options.swaggerOptions,
+    };
+    return (head(options, title, `<link rel="stylesheet" href="${safeUrl(base)}/swagger-ui.css">`) +
+        `<body>${header(options, title)}<div id="zudo-openapi"></div>` +
+        `<script src="${safeUrl(base)}/swagger-ui-bundle.js" crossorigin></script>` +
+        `<script>window.addEventListener("load",function(){window.ui=SwaggerUIBundle(${jsLiteral(config)});});</script>` +
+        `${footer()}</body></html>`);
+}
+//# sourceMappingURL=openApiUi.core.js.map

package/dist/openApiValidation/index.d.ts

@@ -3,6 +3,6 @@
  *
  * OpenAPI document validation.
  */
-export type { OpenAPIValidator } from "./openApiValidator.core.js";
-export { OpenAPIValidatorImpl } from "./openApiValidator.core.js";
+export type { OpenAPIValidator, OpenAPIValidationResult, } from "./openApiValidator.core.js";
+export { OpenAPIValidatorImpl, createOpenAPIValidator, } from "./openApiValidator.core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/openApiValidation/index.js

@@ -3,5 +3,5 @@
  *
  * OpenAPI document validation.
  */
-export { OpenAPIValidatorImpl } from "./openApiValidator.core.js";
+export { OpenAPIValidatorImpl, createOpenAPIValidator, } from "./openApiValidator.core.js";
 //# sourceMappingURL=index.js.map

package/dist/openApiValidation/openApiValidator.core.d.ts

@@ -1,22 +1,44 @@
 import type { OpenAPIDocument } from "../openApiTypes/openApiTypes.core.js";
-import type { OpenAPIValidationIssue } from "../openApiErrors/openApiError.core.js";
+import type { OpenAPIValidationIssue } from "../openApiErrors/openApiError.types.js";
+/** The result of validating a document. */
+export interface OpenAPIValidationResult {
+    readonly valid: boolean;
+    readonly errors: readonly OpenAPIValidationIssue[];
+    readonly warnings: readonly OpenAPIValidationIssue[];
+}
 export interface OpenAPIValidator {
-    validate(document: OpenAPIDocument): {
-        readonly valid: boolean;
-        readonly errors: readonly OpenAPIValidationIssue[];
-        readonly warnings: readonly OpenAPIValidationIssue[];
-    };
+    validate(document: OpenAPIDocument): OpenAPIValidationResult;
     assertValid(document: OpenAPIDocument): void;
 }
 export declare class OpenAPIValidatorImpl implements OpenAPIValidator {
-    validate(document: OpenAPIDocument): {
-        readonly valid: boolean;
-        readonly errors: readonly OpenAPIValidationIssue[];
-        readonly warnings: readonly OpenAPIValidationIssue[];
-    };
+    validate(document: OpenAPIDocument): OpenAPIValidationResult;
     assertValid(document: OpenAPIDocument): void;
     private validateDocumentStructure;
     private validatePaths;
+    private validateOperation;
     private validateOperationIds;
+    /**
+     * Checks that every security requirement names a declared scheme.
+     *
+     * A typo here produces a document that *looks* protected: tooling shows a
+     * lock icon, generated clients send nothing, and the mismatch is invisible
+     * without this check.
+     */
+    private validateSecurity;
+    /**
+     * Checks every `$ref`: that a local one resolves, and that a non-local one
+     * is at least not a scheme a resolver should never be pointed at.
+     *
+     * A `$ref` is an instruction to whatever dereferences the document. A
+     * `file:///etc/passwd` or `http://169.254.169.254/...` reference turns any
+     * downstream tool — a bundler, a mock server, a client generator — into an
+     * arbitrary-file-read or SSRF primitive on behalf of whoever supplied the
+     * spec. Accepting those silently, as a check that only looked at refs
+     * starting with `#` did, is the whole vulnerability.
+     */
+    private validateReferences;
+    private validateReference;
 }
+/** Creates a validator. */
+export declare function createOpenAPIValidator(): OpenAPIValidatorImpl;
 //# sourceMappingURL=openApiValidator.core.d.ts.map

package/dist/openApiValidation/openApiValidator.core.js

@@ -1,4 +1,7 @@
-import { OpenAPIValidationError } from "../openApiErrors/openApiError.core.js";
+import { OpenAPIValidationError } from "../openApiErrors/openApiError.types.js";
+import { MAX_OPERATION_ID_LENGTH, PATH_TEMPLATE_PARAMETER, RESPONSE_KEY_PATTERN, SUPPORTED_OPENAPI_VERSIONS, } from "../openApiConstants/openApiConstants.core.js";
+import { extractPathParameters } from "../openApiRouting/routeConverter.core.js";
+import { unescapeJsonPointerSegment } from "../openApiSchema/references.core.js";
 const OPERATIONS = [
     "get",
     "put",
@@ -9,106 +12,332 @@ const OPERATIONS = [
     "patch",
     "trace",
 ];
+/** A path segment that still uses `:name` rather than `{name}`. */
+const COLON_SEGMENT = /(^|\/):[^/]+/;
+/** Leading URI scheme of a non-local `$ref`, when it has one. */
+const URI_SCHEME = /^([A-Za-z][A-Za-z0-9+.-]*):/;
+/** Schemes a `$ref` resolver may reasonably be pointed at. */
+const FETCHABLE_SCHEMES = new Set(["http", "https"]);
+function error(collector, path, message) {
+    collector.errors.push({ path, message, severity: "error" });
+}
+function warn(collector, path, message) {
+    collector.warnings.push({ path, message, severity: "warning" });
+}
 export class OpenAPIValidatorImpl {
     validate(document) {
-        const errors = [];
-        const warnings = [];
-        this.validateDocumentStructure(document, errors, warnings);
-        this.validatePaths(document, errors, warnings);
-        this.validateOperationIds(document, errors, warnings);
+        const collector = { errors: [], warnings: [] };
+        this.validateDocumentStructure(document, collector);
+        this.validatePaths(document, collector);
+        this.validateOperationIds(document, collector);
+        this.validateSecurity(document, collector);
+        this.validateReferences(document, collector);
         return {
-            valid: errors.length === 0,
-            errors: Object.freeze([...errors]),
-            warnings: Object.freeze([...warnings]),
+            valid: collector.errors.length === 0,
+            errors: Object.freeze([...collector.errors]),
+            warnings: Object.freeze([...collector.warnings]),
         };
     }
     assertValid(document) {
         const result = this.validate(document);
-        if (!result.valid)
-            throw new OpenAPIValidationError("OpenAPI validation failed.", result.errors);
+        if (!result.valid) {
+            throw new OpenAPIValidationError(`OpenAPI validation failed with ${result.errors.length} error${result.errors.length === 1 ? "" : "s"}.`, result.errors);
+        }
     }
-    validateDocumentStructure(document, errors, warnings) {
-        if (!document.openapi)
-            errors.push({
-                path: ["openapi"],
-                message: "OpenAPI version is required.",
-                severity: "error",
-            });
+    validateDocumentStructure(document, collector) {
+        if (!document.openapi) {
+            error(collector, ["openapi"], "OpenAPI version is required.");
+        }
+        else if (!SUPPORTED_OPENAPI_VERSIONS.includes(document.openapi)) {
+            error(collector, ["openapi"], `Unsupported OpenAPI version "${document.openapi}". Supported: ${SUPPORTED_OPENAPI_VERSIONS.join(", ")}.`);
+        }
         if (!document.info) {
-            errors.push({
-                path: ["info"],
-                message: "Info object is required.",
-                severity: "error",
-            });
+            error(collector, ["info"], "Info object is required.");
         }
         else {
-            if (!document.info.title)
-                errors.push({
-                    path: ["info", "title"],
-                    message: "Info title is required.",
-                    severity: "error",
-                });
-            if (!document.info.version)
-                errors.push({
-                    path: ["info", "version"],
-                    message: "Info version is required.",
-                    severity: "error",
-                });
+            if (!document.info.title) {
+                error(collector, ["info", "title"], "Info title is required.");
+            }
+            if (!document.info.version) {
+                error(collector, ["info", "version"], "Info version is required.");
+            }
         }
         if (!document.paths || Object.keys(document.paths).length === 0) {
-            warnings.push({
-                path: ["paths"],
-                message: "Document has no paths defined.",
-                severity: "warning",
-            });
+            warn(collector, ["paths"], "Document has no paths defined.");
+        }
+        for (const [index, server] of (document.servers ?? []).entries()) {
+            if (!server.url) {
+                error(collector, ["servers", index, "url"], "Server url is required.");
+            }
+        }
+        for (const [index, tag] of (document.tags ?? []).entries()) {
+            if (!tag.name) {
+                error(collector, ["tags", index, "name"], "Tag name is required.");
+            }
         }
     }
-    validatePaths(document, errors, _warnings) {
-        for (const [path, pathItem] of Object.entries(document.paths)) {
+    validatePaths(document, collector) {
+        /** Paths seen so far, keyed by their template with parameter names erased. */
+        const shapes = new Map();
+        for (const [path, pathItem] of Object.entries(document.paths ?? {})) {
             if (!pathItem)
                 continue;
-            if (path.includes(":") && !path.includes("{")) {
-                errors.push({
-                    path: ["paths", path],
-                    message: `Path "${path}" contains un-converted path parameters. Use "/users/{id}" instead of "/users/:id".`,
-                    severity: "error",
-                });
+            // "/users/{id}" and "/users/{userId}" have the same hierarchy and
+            // differ only in template names; the specification forbids both
+            // existing, since a router cannot tell them apart.
+            const shape = path.replace(PATH_TEMPLATE_PARAMETER, "{}");
+            const twin = shapes.get(shape);
+            if (twin !== undefined && twin !== path) {
+                error(collector, ["paths", path], `Path "${path}" is identical to "${twin}" apart from its template parameter names; such paths must not both exist.`);
+            }
+            else {
+                shapes.set(shape, path);
+            }
+            if (!path.startsWith("/")) {
+                error(collector, ["paths", path], `Path "${path}" must start with "/".`);
+            }
+            // Catches "/users/:id" and "/a/:id/{b}" alike, which a bare
+            // `includes(":") && !includes("{")` test misses.
+            if (COLON_SEGMENT.test(path)) {
+                error(collector, ["paths", path], `Path "${path}" contains un-converted path parameters. Use "/users/{id}" instead of "/users/:id".`);
+            }
+            const templateParameters = extractPathParameters(path);
+            const duplicates = templateParameters.filter((name, index) => templateParameters.indexOf(name) !== index);
+            for (const duplicate of duplicates) {
+                error(collector, ["paths", path], `Path "${path}" declares the template parameter "{${duplicate}}" more than once.`);
             }
             for (const method of OPERATIONS) {
                 const operation = pathItem[method];
                 if (!operation)
                     continue;
-                for (const param of operation.parameters ?? []) {
-                    if (param.in === "path" && !param.required) {
-                        errors.push({
-                            path: ["paths", path, method, "parameters"],
-                            message: `Path parameter "${param.name}" must be required.`,
-                            severity: "error",
-                        });
-                    }
+                this.validateOperation(path, method, operation, pathItem, templateParameters, collector);
+            }
+        }
+    }
+    validateOperation(path, method, operation, pathItem, templateParameters, collector) {
+        const base = ["paths", path, method];
+        if (!operation.responses || Object.keys(operation.responses).length === 0) {
+            error(collector, [...base, "responses"], "Every operation must declare at least one response.");
+        }
+        else {
+            for (const key of Object.keys(operation.responses)) {
+                if (!RESPONSE_KEY_PATTERN.test(key)) {
+                    error(collector, [...base, "responses", key], `Response key "${key}" is not a status code, a range such as "4XX", or "default".`);
+                }
+                const response = operation.responses[key];
+                if (response && typeof response.description !== "string") {
+                    error(collector, [...base, "responses", key, "description"], "A response must have a description.");
+                }
+            }
+        }
+        if (operation.operationId &&
+            operation.operationId.length > MAX_OPERATION_ID_LENGTH) {
+            error(collector, [...base, "operationId"], `operationId "${operation.operationId}" exceeds the maximum length of ${MAX_OPERATION_ID_LENGTH}.`);
+        }
+        // Uniqueness is per list: the specification forbids duplicates within
+        // the path item's list and within the operation's list, while an
+        // operation-level parameter *overrides* a path-level one with the same
+        // name and location. Treating that override as a duplicate rejected
+        // legal documents.
+        const parameters = new Map();
+        for (const list of [pathItem.parameters, operation.parameters]) {
+            const seen = new Set();
+            for (const parameter of list ?? []) {
+                if (!parameter.name) {
+                    error(collector, [...base, "parameters"], "Every parameter must have a name.");
+                    continue;
+                }
+                const key = `${parameter.in}:${parameter.name}`;
+                if (seen.has(key)) {
+                    error(collector, [...base, "parameters"], `Duplicate parameter "${parameter.name}" in "${parameter.in}".`);
+                }
+                seen.add(key);
+                parameters.set(key, parameter);
+                if (parameter.in === "path" && parameter.required !== true) {
+                    error(collector, [...base, "parameters"], `Path parameter "${parameter.name}" must be required.`);
                 }
             }
         }
+        // The classic OpenAPI mistake: a templated path with no matching
+        // parameter, or a path parameter that no template slot refers to.
+        const declaredPathParameters = new Set([...parameters.values()]
+            .filter((parameter) => parameter.in === "path")
+            .map((parameter) => parameter.name));
+        for (const name of templateParameters) {
+            if (!declaredPathParameters.has(name)) {
+                error(collector, [...base, "parameters"], `Path template "{${name}}" has no matching parameter with in: "path".`);
+            }
+        }
+        for (const name of declaredPathParameters) {
+            if (!templateParameters.includes(name)) {
+                error(collector, [...base, "parameters"], `Path parameter "${name}" does not appear in the path template "${path}".`);
+            }
+        }
+        for (const tag of operation.tags ?? []) {
+            if (!tag) {
+                error(collector, [...base, "tags"], "Tags must be non-empty strings.");
+            }
+        }
     }
-    validateOperationIds(document, errors, _warnings) {
-        const operationIds = new Set();
-        for (const [path, pathItem] of Object.entries(document.paths)) {
+    validateOperationIds(document, collector) {
+        const operationIds = new Map();
+        for (const [path, pathItem] of Object.entries(document.paths ?? {})) {
             if (!pathItem)
                 continue;
             for (const method of OPERATIONS) {
                 const operation = pathItem[method];
                 if (!operation?.operationId)
                     continue;
-                if (operationIds.has(operation.operationId)) {
-                    errors.push({
-                        path: ["paths", path, method, "operationId"],
-                        message: `Duplicate operationId "${operation.operationId}".`,
-                        severity: "error",
-                    });
+                const previous = operationIds.get(operation.operationId);
+                if (previous) {
+                    error(collector, ["paths", path, method, "operationId"], `Duplicate operationId "${operation.operationId}" (also used by ${previous}).`);
+                }
+                else {
+                    operationIds.set(operation.operationId, `${method.toUpperCase()} ${path}`);
                 }
-                operationIds.add(operation.operationId);
             }
         }
     }
+    /**
+     * Checks that every security requirement names a declared scheme.
+     *
+     * A typo here produces a document that *looks* protected: tooling shows a
+     * lock icon, generated clients send nothing, and the mismatch is invisible
+     * without this check.
+     */
+    validateSecurity(document, collector) {
+        const schemes = new Set(Object.keys(document.components?.securitySchemes ?? {}));
+        /** Every scheme some requirement actually names. */
+        const required = new Set();
+        const check = (requirements, path) => {
+            for (const requirement of requirements) {
+                for (const name of Object.keys(requirement)) {
+                    required.add(name);
+                    if (!schemes.has(name)) {
+                        error(collector, path, `Security requirement "${name}" does not match any scheme in components.securitySchemes.`);
+                    }
+                }
+            }
+        };
+        check(document.security ?? [], ["security"]);
+        for (const [path, pathItem] of Object.entries(document.paths ?? {})) {
+            if (!pathItem)
+                continue;
+            for (const method of OPERATIONS) {
+                const operation = pathItem[method];
+                if (!operation?.security)
+                    continue;
+                check(operation.security, ["paths", path, method, "security"]);
+            }
+        }
+        // The mirror image, and the more dangerous direction: a declared scheme
+        // that nothing requires. Viewers render the lock, generated clients offer
+        // the credential field, and every operation is in fact unauthenticated.
+        for (const name of schemes) {
+            if (!required.has(name)) {
+                warn(collector, ["components", "securitySchemes", name], `Security scheme "${name}" is declared but no operation or ` +
+                    `document-level requirement uses it, so nothing it describes is ` +
+                    `actually required.`);
+            }
+        }
+    }
+    /**
+     * Checks every `$ref`: that a local one resolves, and that a non-local one
+     * is at least not a scheme a resolver should never be pointed at.
+     *
+     * A `$ref` is an instruction to whatever dereferences the document. A
+     * `file:///etc/passwd` or `http://169.254.169.254/...` reference turns any
+     * downstream tool — a bundler, a mock server, a client generator — into an
+     * arbitrary-file-read or SSRF primitive on behalf of whoever supplied the
+     * spec. Accepting those silently, as a check that only looked at refs
+     * starting with `#` did, is the whole vulnerability.
+     */
+    validateReferences(document, collector) {
+        const seen = new WeakSet();
+        const walk = (value, path) => {
+            if (typeof value !== "object" || value === null)
+                return;
+            if (seen.has(value))
+                return;
+            seen.add(value);
+            if (Array.isArray(value)) {
+                value.forEach((entry, index) => walk(entry, [...path, index]));
+                return;
+            }
+            const record = value;
+            const ref = record["$ref"];
+            if (typeof ref === "string") {
+                this.validateReference(document, ref, path, collector);
+                return;
+            }
+            for (const [key, entry] of Object.entries(record)) {
+                walk(entry, [...path, key]);
+            }
+        };
+        walk(document.paths ?? {}, ["paths"]);
+        walk(document.components ?? {}, ["components"]);
+    }
+    validateReference(document, ref, path, collector) {
+        if (ref.startsWith("#")) {
+            if (!resolvePointer(document, ref)) {
+                error(collector, path, `Reference "${ref}" does not resolve within the document.`);
+            }
+            return;
+        }
+        const scheme = URI_SCHEME.exec(ref)?.[1]?.toLowerCase();
+        if (scheme !== undefined && !FETCHABLE_SCHEMES.has(scheme)) {
+            error(collector, path, `Reference "${ref}" uses the "${scheme}:" scheme. Only local ` +
+                `references and http(s) URLs are allowed; a resolver following ` +
+                `this would read from outside the document.`);
+            return;
+        }
+        warn(collector, path, `Reference "${ref}" points outside the document. Whatever dereferences ` +
+            `this specification will fetch it — bundle the target into ` +
+            `components instead if the source is not fully trusted.`);
+    }
+}
+/** Resolves a local JSON Pointer, returning whether the target exists. */
+function resolvePointer(document, ref) {
+    const pointer = ref.slice(1);
+    if (pointer === "" || pointer === "/")
+        return true;
+    if (!pointer.startsWith("/"))
+        return false;
+    let current = document;
+    for (const rawSegment of pointer.slice(1).split("/")) {
+        // A stray or truncated percent-escape makes `decodeURIComponent` throw a
+        // `URIError`. Letting that escape turned `validate()` — whose entire job
+        // is to report problems rather than raise them — into a crash on a
+        // hand-crafted `$ref`.
+        let decoded;
+        try {
+            decoded = decodeURIComponent(rawSegment);
+        }
+        catch {
+            return false;
+        }
+        const segment = unescapeJsonPointerSegment(decoded);
+        if (typeof current !== "object" || current === null)
+            return false;
+        if (Array.isArray(current)) {
+            const index = Number(segment);
+            if (!Number.isInteger(index) || index < 0 || index >= current.length) {
+                return false;
+            }
+            current = current[index];
+            continue;
+        }
+        // Own properties only: `in` walks the prototype chain, so a reference
+        // to `#/components/schemas/constructor` resolved to
+        // `Object.prototype.constructor` and validated as present.
+        if (!Object.prototype.hasOwnProperty.call(current, segment))
+            return false;
+        current = current[segment];
+    }
+    return current !== undefined;
+}
+/** Creates a validator. */
+export function createOpenAPIValidator() {
+    return new OpenAPIValidatorImpl();
 }
 //# sourceMappingURL=openApiValidator.core.js.map