@sezzlee/openapi 0.0.0-stage → 0.1.0

package/dist/lower/operations.js

@@ -0,0 +1,212 @@
+import { snakeCase } from "@sezzlee/core";
+import { OperationDropped } from "../diagnostics.js";
+import { childPointer, operationKey, rootPointer, } from "../ir/brand.js";
+import { arrayOf, entriesOf, objectOf, stringOf, } from "../ir/json.js";
+import { resolveComponent } from "../normalize/refs.js";
+import { lowerRequestBody } from "./body.js";
+import { lowerParameters } from "./parameters.js";
+import { lowerResponses } from "./responses.js";
+import { authOf, carriersOf, effectiveSecurity, } from "./security.js";
+import { serverOf } from "./servers.js";
+const methodKeys = {
+    get: "GET",
+    put: "PUT",
+    post: "POST",
+    delete: "DELETE",
+    options: "OPTIONS",
+    head: "HEAD",
+    patch: "PATCH",
+    trace: "TRACE",
+    query: "QUERY",
+};
+const describable = new Set([
+    "GET",
+    "HEAD",
+    "POST",
+    "PUT",
+    "PATCH",
+    "DELETE",
+    "OPTIONS",
+    "QUERY",
+]);
+const toolNamePattern = /^[a-z][a-z0-9_]{0,255}$/;
+function descriptionOf(operation) {
+    const summary = stringOf(operation["summary"])?.trim();
+    const description = stringOf(operation["description"])?.trim();
+    if (summary === undefined || summary === "") {
+        return description === "" ? undefined : description;
+    }
+    if (description === undefined ||
+        description === "" ||
+        description.startsWith(summary)) {
+        return description === undefined || description === ""
+            ? summary
+            : description;
+    }
+    return `${summary}\n\n${description}`;
+}
+function hoisted(path, prefix) {
+    if (prefix === undefined || prefix === "" || prefix === "/") {
+        return { route: path, prefix: "" };
+    }
+    const clean = prefix.replace(/\/+$/, "");
+    if (path === clean) {
+        return { route: "/", prefix: clean };
+    }
+    return path.startsWith(`${clean}/`)
+        ? { route: path.slice(clean.length), prefix: clean }
+        : { route: path, prefix: "" };
+}
+function sitesOf(document, diagnostics) {
+    const sites = [];
+    for (const [path, raw] of entriesOf(document["paths"])) {
+        const itemAt = childPointer(rootPointer, "paths", path);
+        let resolved;
+        try {
+            resolved = resolveComponent(document, raw, itemAt);
+        }
+        catch (error) {
+            if (!(error instanceof OperationDropped)) {
+                throw error;
+            }
+            diagnostics.report(error.code, error.at, error.message);
+            continue;
+        }
+        if (resolved === undefined) {
+            continue;
+        }
+        const item = resolved.node;
+        for (const [key, method] of Object.entries(methodKeys)) {
+            const operation = objectOf(item[key]);
+            if (operation !== undefined) {
+                sites.push({
+                    path,
+                    method,
+                    operation,
+                    at: childPointer(itemAt, key),
+                    item,
+                    itemAt,
+                });
+            }
+        }
+        for (const [name, raw2] of entriesOf(item["additionalOperations"])) {
+            const operation = objectOf(raw2);
+            if (operation !== undefined) {
+                sites.push({
+                    path,
+                    method: name.toUpperCase(),
+                    operation,
+                    at: childPointer(itemAt, "additionalOperations", name),
+                    item,
+                    itemAt,
+                });
+            }
+        }
+    }
+    return sites;
+}
+function searchTermsOf(context, operation, at) {
+    const declared = operation["x-sezzlee-search-terms"];
+    if (declared === undefined) {
+        return undefined;
+    }
+    if (!Array.isArray(declared) ||
+        !declared.every((term) => typeof term === "string")) {
+        context.diagnostics.report("search_terms_invalid", childPointer(at, "x-sezzlee-search-terms"), "x-sezzlee-search-terms must be an array of strings; the operation carries no search terms.");
+        return undefined;
+    }
+    const terms = declared.filter((term) => term.trim() !== "");
+    return terms.length === 0 ? undefined : terms;
+}
+function lowerOperation(context, site, schemes, options) {
+    const { operation, at, method } = site;
+    if (operation["x-sezzlee-dropped"] === true) {
+        return undefined;
+    }
+    if (!describable.has(method)) {
+        throw new OperationDropped("unsupported_method", at, `Method ${method} has no descriptor form.`);
+    }
+    if (objectOf(operation["callbacks"]) !== undefined) {
+        context.diagnostics.report("callbacks_ignored", childPointer(at, "callbacks"), "Callbacks are requests the backend makes, not operations the agent calls; they are not carried.");
+    }
+    const security = effectiveSecurity(operation, context.document);
+    const credentialSlots = carriersOf(security, schemes);
+    const identityCookies = new Set([...schemes.values()].flatMap((scheme) => scheme.type === "apiKey" && scheme.in === "cookie" ? [scheme.name] : []));
+    const lowered = lowerParameters({ ...context, cookieDenyList: options.cookieDenyList }, {
+        values: site.item["parameters"],
+        at: childPointer(site.itemAt, "parameters"),
+    }, { values: operation["parameters"], at: childPointer(at, "parameters") }, credentialSlots, identityCookies);
+    const requestBody = lowerRequestBody(context, operation["requestBody"], childPointer(at, "requestBody"), options.requestBodyRequired);
+    const responses = lowerResponses(context, operation["responses"], childPointer(at, "responses"), options.outputSchema === "document");
+    const operationId = stringOf(operation["operationId"])?.trim();
+    let usableId;
+    if (operationId !== undefined && operationId !== "") {
+        if (toolNamePattern.test(snakeCase(operationId))) {
+            usableId = operationId;
+        }
+        else {
+            context.diagnostics.report("operation_id_unusable", childPointer(at, "operationId"), `operationId '${operationId}' does not produce a valid tool name; the name is derived from the route instead.`);
+        }
+    }
+    const tags = arrayOf(operation["tags"])
+        .map(stringOf)
+        .filter((tag) => tag !== undefined && tag.trim() !== "");
+    const searchTerms = searchTermsOf(context, operation, at);
+    const { route, prefix } = hoisted(site.path, options.hoistPathPrefix);
+    const description = descriptionOf(operation);
+    const carriers = [...credentialSlots, ...lowered.carriers];
+    const descriptor = {
+        ...(usableId === undefined ? {} : { operationId: usableId }),
+        ...(tags[0] === undefined ? {} : { container: tags[0] }),
+        method: method,
+        route,
+        ...(description === undefined ? {} : { description }),
+        ...(operation["deprecated"] === true ? { deprecated: true } : {}),
+        ...(lowered.parameters.length === 0
+            ? {}
+            : { parameters: lowered.parameters }),
+        ...(requestBody === undefined ? {} : { requestBody }),
+        ...(responses === undefined ? {} : { responses }),
+        auth: authOf(security, carriers),
+        ...(tags.length === 0 ? {} : { tags }),
+        ...(searchTerms === undefined ? {} : { searchTerms }),
+    };
+    const server = serverOf([
+        { servers: operation["servers"], at: childPointer(at, "servers") },
+        {
+            servers: site.item["servers"],
+            at: childPointer(site.itemAt, "servers"),
+        },
+    ], {
+        servers: context.document["servers"],
+        at: childPointer(rootPointer, "servers"),
+    }, options, context.diagnostics);
+    return {
+        key: operationKey(method, site.path),
+        at,
+        descriptor,
+        baseUrl: server === undefined ? undefined : `${server}${prefix}`,
+        security,
+    };
+}
+export function lowerOperations(context, schemes, options) {
+    if (objectOf(context.document["webhooks"]) !== undefined) {
+        context.diagnostics.report("webhooks_ignored", childPointer(rootPointer, "webhooks"), "Webhooks are requests the backend makes, not operations the agent calls; they are not carried.");
+    }
+    const endpoints = [];
+    for (const site of sitesOf(context.document, context.diagnostics)) {
+        try {
+            const endpoint = lowerOperation(context, site, schemes, options);
+            if (endpoint !== undefined) {
+                endpoints.push(endpoint);
+            }
+        }
+        catch (error) {
+            if (!(error instanceof OperationDropped)) {
+                throw error;
+            }
+            context.diagnostics.report(error.code, error.at, error.message);
+        }
+    }
+    return endpoints;
+}

package/dist/lower/parameters.d.ts

@@ -0,0 +1,30 @@
+import type { EndpointDescriptor, IdentityCarrier } from "@sezzlee/core";
+import { type DiagnosticSink } from "../diagnostics.js";
+import { type JsonPointer } from "../ir/brand.js";
+import { type JsonValue } from "../ir/json.js";
+import { type SchemaContext } from "../normalize/schema.js";
+type Parameter = NonNullable<EndpointDescriptor["parameters"]>[number];
+export declare const defaultCookieDenyList: RegExp;
+export interface ParameterContext extends SchemaContext {
+    readonly diagnostics: DiagnosticSink;
+    readonly cookieDenyList: RegExp;
+}
+export interface LoweredParameters {
+    readonly parameters: Parameter[];
+    readonly carriers: IdentityCarrier[];
+}
+/**
+ * Lowers the path item's and the operation's parameters. The operation's list wins over the path
+ * item's for the same `(name, in)` pair; merging by name alone would collapse a query `id` into a
+ * path `id`.
+ *
+ * @param credentialSlots the slots the operation's security schemes write a credential into
+ */
+export declare function lowerParameters(context: ParameterContext, pathItem: {
+    readonly values: JsonValue | undefined;
+    readonly at: JsonPointer;
+}, operation: {
+    readonly values: JsonValue | undefined;
+    readonly at: JsonPointer;
+}, credentialSlots: readonly IdentityCarrier[], identityCookies: ReadonlySet<string>): LoweredParameters;
+export {};

package/dist/lower/parameters.js

@@ -0,0 +1,143 @@
+import { OperationDropped } from "../diagnostics.js";
+import { childPointer } from "../ir/brand.js";
+import { arrayOf, booleanOf, entriesOf, objectOf, stringOf, } from "../ir/json.js";
+import { resolveComponent } from "../normalize/refs.js";
+import { normalizeSlot } from "../normalize/schema.js";
+export const defaultCookieDenyList = /^(session|sid|token|auth|jwt)$|sess/i;
+const reservedHeaders = new Set(["accept", "content-type", "authorization"]);
+const locations = new Set([
+    "path",
+    "query",
+    "header",
+    "cookie",
+    "querystring",
+]);
+const defaultStyle = {
+    path: "simple",
+    query: "form",
+    header: "simple",
+    cookie: "form",
+};
+const parameterContentTypes = new Set([
+    "application/json",
+    "text/plain",
+    "application/x-www-form-urlencoded",
+]);
+/**
+ * The media type a `content` parameter is serialized as, or `undefined` when the composer writes
+ * none; a JSON-family type is written as JSON.
+ */
+function contentTypeOf(declared) {
+    const bare = (declared.split(";")[0] ?? "").trim().toLowerCase();
+    if (parameterContentTypes.has(bare)) {
+        return bare;
+    }
+    return /\+json$/.test(bare) || bare === "text/json"
+        ? "application/json"
+        : undefined;
+}
+function collect(context, lists) {
+    const byKey = new Map();
+    for (const list of lists) {
+        arrayOf(list.values).forEach((value, index) => {
+            const resolved = resolveComponent(context.document, value, childPointer(list.at, index));
+            if (resolved === undefined) {
+                return;
+            }
+            const key = `${stringOf(resolved.node["in"])}|${stringOf(resolved.node["name"])}`;
+            byKey.set(key, resolved);
+        });
+    }
+    return [...byKey.values()];
+}
+/**
+ * Lowers the path item's and the operation's parameters. The operation's list wins over the path
+ * item's for the same `(name, in)` pair; merging by name alone would collapse a query `id` into a
+ * path `id`.
+ *
+ * @param credentialSlots the slots the operation's security schemes write a credential into
+ */
+export function lowerParameters(context, pathItem, operation, credentialSlots, identityCookies) {
+    const parameters = [];
+    const carriers = [];
+    for (const { node, at } of collect(context, [pathItem, operation])) {
+        const name = stringOf(node["name"]);
+        const location = stringOf(node["in"]);
+        if (name === undefined || location === undefined) {
+            context.diagnostics.report("openapi_document_invalid", at, "A parameter needs 'name' and 'in'.");
+            continue;
+        }
+        if (!locations.has(location)) {
+            context.diagnostics.report("openapi_document_invalid", childPointer(at, "in"), `Parameter location '${location}' is not defined by OpenAPI; the parameter is ignored.`);
+            continue;
+        }
+        const where = location;
+        if (where === "header" && reservedHeaders.has(name.toLowerCase())) {
+            context.diagnostics.report("reserved_header_parameter_ignored", at, `Header parameter '${name}' is ignored, as OpenAPI requires; ${name.toLowerCase() === "authorization" ? "the credential arrives through a security scheme" : "the composer writes it"}.`);
+            continue;
+        }
+        const occupies = credentialSlots.find((slot) => slot.in === where &&
+            (where === "header"
+                ? slot.name.toLowerCase() === name.toLowerCase()
+                : slot.name === name));
+        if (occupies !== undefined) {
+            context.diagnostics.report("credential_parameter_ignored", at, `${where} parameter '${name}' is the slot a security scheme writes its credential into; it is not an argument.`);
+            continue;
+        }
+        if (where === "cookie" &&
+            (identityCookies.has(name) || context.cookieDenyList.test(name))) {
+            carriers.push({ in: "cookie", name });
+            context.diagnostics.report("identity_cookie_parameter", at, `Cookie parameter '${name}' carries identity and is never an argument.`);
+            if (!identityCookies.has(name)) {
+                context.diagnostics.report("identity_cookie_uncovered", at, `Cookie '${name}' looks like a session cookie but no security scheme declares it; no credential is configured for it.`);
+            }
+            continue;
+        }
+        if (node["allowEmptyValue"] !== undefined) {
+            context.diagnostics.report("allow_empty_value_ignored", childPointer(at, "allowEmptyValue"), "allowEmptyValue is ignored; an empty string already writes 'key='.");
+        }
+        const description = stringOf(node["description"]);
+        const content = entriesOf(node["content"]);
+        if (content.length > 0 || where === "querystring") {
+            const [declared, media] = content[0] ?? ["", undefined];
+            const contentType = contentTypeOf(declared);
+            if (contentType === undefined || content.length !== 1) {
+                throw new OperationDropped("unsupported_parameter_content", childPointer(at, "content"), `Parameter '${name}' is serialized as ${declared === "" ? "no media type" : declared}, which the composer does not write; only JSON, text/plain and — for a querystring — urlencoded content are.`);
+            }
+            parameters.push({
+                name,
+                in: where,
+                required: where === "path" ? true : booleanOf(node["required"]) === true,
+                schema: normalizeSlot(context, objectOf(media)?.["schema"], childPointer(at, "content", declared, "schema"), { direction: "request", root: "preferred" }),
+                contentType,
+                ...(description === undefined ? {} : { description }),
+            });
+            continue;
+        }
+        const allowReserved = where === "query" && booleanOf(node["allowReserved"]) === true;
+        const schema = normalizeSlot(context, node["schema"], childPointer(at, "schema"), {
+            direction: "request",
+            root: "required",
+        });
+        const isArray = schema.type === "array" ||
+            (Array.isArray(schema.type) && schema.type.includes("array"));
+        const declaredStyle = stringOf(node["style"]);
+        const style = declaredStyle ?? defaultStyle[where];
+        const declaredExplode = booleanOf(node["explode"]);
+        parameters.push({
+            name,
+            in: where,
+            required: where === "path" ? true : booleanOf(node["required"]) === true,
+            schema,
+            ...(style === "deepObject" || isArray || declaredStyle !== undefined
+                ? { style }
+                : {}),
+            ...(isArray || declaredExplode !== undefined
+                ? { explode: declaredExplode ?? style === "form" }
+                : {}),
+            ...(allowReserved ? { allowReserved: true } : {}),
+            ...(description === undefined ? {} : { description }),
+        });
+    }
+    return { parameters, carriers };
+}

package/dist/lower/responses.d.ts

@@ -0,0 +1,6 @@
+import { type EndpointDescriptor } from "@sezzlee/core";
+import { type JsonPointer } from "../ir/brand.js";
+import { type SchemaContext } from "../normalize/schema.js";
+type Responses = NonNullable<EndpointDescriptor["responses"]>;
+export declare function lowerResponses(context: SchemaContext, value: unknown, at: JsonPointer, withSchemas: boolean): Responses | undefined;
+export {};

package/dist/lower/responses.js

@@ -0,0 +1,63 @@
+import { isJsonMediaType } from "@sezzlee/core";
+import { OperationDropped } from "../diagnostics.js";
+import { childPointer } from "../ir/brand.js";
+import { entriesOf, isObject, objectOf, stringOf, } from "../ir/json.js";
+import { resolveComponent } from "../normalize/refs.js";
+import { normalizeSlot } from "../normalize/schema.js";
+const streamingMediaTypes = new Set([
+    "text/event-stream",
+    "application/jsonl",
+    "application/x-ndjson",
+    "application/json-seq",
+    "multipart/mixed",
+]);
+const bare = (declared) => (declared.split(";")[0] ?? "").trim().toLowerCase();
+function jsonMedia(content) {
+    for (const [declared, media] of entriesOf(content)) {
+        const mediaType = bare(declared);
+        if (isObject(media) &&
+            media["itemSchema"] === undefined &&
+            (isJsonMediaType(mediaType) || mediaType === "*/*")) {
+            return { declared, media };
+        }
+    }
+    return undefined;
+}
+function isStreamingOnly(content) {
+    const entries = entriesOf(content);
+    return (entries.length > 0 &&
+        entries.every(([declared, media]) => streamingMediaTypes.has(bare(declared)) ||
+            (isObject(media) && media["itemSchema"] !== undefined)));
+}
+export function lowerResponses(context, value, at, withSchemas) {
+    const out = {};
+    for (const [code, raw] of entriesOf(value)) {
+        if (!/^([1-5][0-9]{2}|[1-5]XX|default)$/.test(code)) {
+            continue;
+        }
+        const codeAt = childPointer(at, code);
+        const resolved = resolveComponent(context.document, isObject(raw) ? raw : {}, codeAt);
+        if (resolved === undefined) {
+            continue;
+        }
+        const { node, at: responseAt } = resolved;
+        if (objectOf(node["links"]) !== undefined) {
+            context.diagnostics.report("links_ignored", childPointer(responseAt, "links"), "Response links describe follow-up calls the agent finds by search; they are not carried.");
+        }
+        if (code.startsWith("2") && isStreamingOnly(node["content"])) {
+            throw new OperationDropped("streaming_response_unsupported", childPointer(responseAt, "content"), `The ${code} response is only a streaming sequence, which an invocation cannot return as one result.`);
+        }
+        const description = stringOf(node["description"]);
+        const json = withSchemas ? jsonMedia(node["content"]) : undefined;
+        const schema = json?.media["schema"] === undefined
+            ? undefined
+            : normalizeSlot(context, json.media["schema"], childPointer(responseAt, "content", json.declared, "schema"), { direction: "response", root: "preferred" });
+        out[code] = {
+            ...(schema === undefined ? {} : { schema }),
+            ...(description === undefined || description === ""
+                ? {}
+                : { description }),
+        };
+    }
+    return Object.keys(out).length === 0 ? undefined : out;
+}

package/dist/lower/security.d.ts

@@ -0,0 +1,41 @@
+import type { EndpointDescriptor, IdentityCarrier } from "@sezzlee/core";
+import type { DiagnosticSink } from "../diagnostics.js";
+import { type Brand } from "../ir/brand.js";
+import { type JsonObject } from "../ir/json.js";
+export type CredentialRef = Brand<string, "CredentialRef">;
+export type SecurityScheme = {
+    readonly type: "apiKey";
+    readonly in: "header" | "query" | "cookie";
+    readonly name: string;
+} | {
+    readonly type: "http";
+    readonly scheme: "basic";
+} | {
+    readonly type: "http";
+    readonly scheme: "bearer";
+    readonly bearerFormat?: string;
+} | {
+    readonly type: "oauth2";
+    readonly flows: JsonObject;
+} | {
+    readonly type: "openIdConnect";
+    readonly url: string;
+} | {
+    readonly type: "mutualTLS";
+};
+/** One alternative of a `security` list: every scheme in it applies together. */
+export type SecurityRequirement = ReadonlyMap<CredentialRef, readonly string[]>;
+export type SecurityModel = ReadonlyMap<CredentialRef, SecurityScheme>;
+export declare function securitySchemesOf(document: JsonObject, diagnostics: DiagnosticSink): SecurityModel;
+/**
+ * The operation's own `security`, else the document's. `undefined` means no list was declared
+ * anywhere, which is not the same as an explicit empty list.
+ */
+export declare function effectiveSecurity(operation: JsonObject, document: JsonObject): readonly SecurityRequirement[] | undefined;
+export declare function isAnonymousAllowed(requirements: readonly SecurityRequirement[] | undefined): boolean;
+export declare function carriersOf(requirements: readonly SecurityRequirement[] | undefined, schemes: SecurityModel): IdentityCarrier[];
+/**
+ * A document says which credential a call needs, never which caller may make it, so nothing but an
+ * explicit anonymous alternative is turned into a visibility fact.
+ */
+export declare function authOf(requirements: readonly SecurityRequirement[] | undefined, carriers: readonly IdentityCarrier[]): EndpointDescriptor["auth"];

package/dist/lower/security.js

@@ -0,0 +1,113 @@
+import { childPointer, rootPointer } from "../ir/brand.js";
+import { arrayOf, entriesOf, objectOf, stringOf, } from "../ir/json.js";
+const apiKeyLocations = new Set(["header", "query", "cookie"]);
+export function securitySchemesOf(document, diagnostics) {
+    const schemes = new Map();
+    const components = objectOf(document["components"]);
+    for (const [name, raw] of entriesOf(components?.["securitySchemes"])) {
+        const at = childPointer(rootPointer, "components", "securitySchemes", name);
+        const scheme = objectOf(raw);
+        const type = stringOf(scheme?.["type"]);
+        const ref = name;
+        switch (type) {
+            case "apiKey": {
+                const location = stringOf(scheme?.["in"]) ?? "";
+                const key = stringOf(scheme?.["name"]);
+                if (!apiKeyLocations.has(location) || key === undefined) {
+                    diagnostics.report("openapi_document_invalid", at, "An apiKey scheme needs 'in' (header, query or cookie) and 'name'.");
+                    continue;
+                }
+                schemes.set(ref, {
+                    type: "apiKey",
+                    in: location,
+                    name: key,
+                });
+                continue;
+            }
+            case "http": {
+                const httpScheme = stringOf(scheme?.["scheme"])?.toLowerCase();
+                if (httpScheme === "basic") {
+                    schemes.set(ref, { type: "http", scheme: "basic" });
+                }
+                else if (httpScheme === "bearer") {
+                    const bearerFormat = stringOf(scheme?.["bearerFormat"]);
+                    schemes.set(ref, {
+                        type: "http",
+                        scheme: "bearer",
+                        ...(bearerFormat === undefined ? {} : { bearerFormat }),
+                    });
+                }
+                else {
+                    diagnostics.report("security_scheme_unsupported", at, `The http scheme '${httpScheme ?? ""}' has no credential placement; only basic and bearer do.`);
+                }
+                continue;
+            }
+            case "oauth2":
+                schemes.set(ref, {
+                    type: "oauth2",
+                    flows: objectOf(scheme?.["flows"]) ?? {},
+                });
+                continue;
+            case "openIdConnect":
+                schemes.set(ref, {
+                    type: "openIdConnect",
+                    url: stringOf(scheme?.["openIdConnectUrl"]) ?? "",
+                });
+                continue;
+            case "mutualTLS":
+                schemes.set(ref, { type: "mutualTLS" });
+                continue;
+            default:
+                diagnostics.report("openapi_document_invalid", at, `Security scheme type '${type ?? "absent"}' is not defined by OpenAPI.`);
+        }
+    }
+    return schemes;
+}
+/**
+ * The operation's own `security`, else the document's. `undefined` means no list was declared
+ * anywhere, which is not the same as an explicit empty list.
+ */
+export function effectiveSecurity(operation, document) {
+    const declared = operation["security"] ?? document["security"];
+    if (declared === undefined) {
+        return undefined;
+    }
+    return arrayOf(declared).map((alternative) => new Map(entriesOf(alternative).map(([name, scopes]) => [
+        name,
+        arrayOf(scopes)
+            .map(stringOf)
+            .filter((scope) => scope !== undefined),
+    ])));
+}
+export function isAnonymousAllowed(requirements) {
+    return (requirements !== undefined &&
+        (requirements.length === 0 ||
+            requirements.some((alternative) => alternative.size === 0)));
+}
+export function carriersOf(requirements, schemes) {
+    const carriers = new Map();
+    for (const alternative of requirements ?? []) {
+        for (const ref of alternative.keys()) {
+            const scheme = schemes.get(ref);
+            if (scheme?.type === "apiKey") {
+                carriers.set(`${scheme.in}|${scheme.name}`, {
+                    in: scheme.in,
+                    name: scheme.name,
+                });
+            }
+        }
+    }
+    return [...carriers.values()];
+}
+/**
+ * A document says which credential a call needs, never which caller may make it, so nothing but an
+ * explicit anonymous alternative is turned into a visibility fact.
+ */
+export function authOf(requirements, carriers) {
+    return {
+        anonymous: isAnonymousAllowed(requirements) ? "yes" : "unknown",
+        policies: [],
+        imperative: false,
+        ...(carriers.length === 0 ? {} : { carriers: [...carriers] }),
+    };
+}

package/dist/lower/servers.d.ts

@@ -0,0 +1,22 @@
+import type { DiagnosticSink } from "../diagnostics.js";
+import { type JsonPointer } from "../ir/brand.js";
+import { type JsonValue } from "../ir/json.js";
+export interface ServerOptions {
+    readonly documentUrl?: string;
+    readonly baseUrl?: string;
+    readonly variables?: Readonly<Record<string, string>>;
+}
+/**
+ * Resolves the first server of the nearest non-empty list among operation and path item, else the
+ * root's. A configured `baseUrl` replaces the root list; it does not override a server an
+ * operation or path item declares for itself.
+ *
+ * @param lists the operation's and the path item's lists, nearest first
+ */
+export declare function serverOf(lists: ReadonlyArray<{
+    readonly servers: JsonValue | undefined;
+    readonly at: JsonPointer;
+}>, root: {
+    readonly servers: JsonValue | undefined;
+    readonly at: JsonPointer;
+}, options: ServerOptions, diagnostics: DiagnosticSink): string | undefined;