@sezzlee/openapi-mcp 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaan Akın
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,149 @@
-# Temporary Holding Version
+# @sezzlee/openapi-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+MCP server that exposes an OpenAPI (Swagger 2.0 / OpenAPI 3.0–3.2) document as sezzlee's
+search-first tool catalog — `search_tools`, `load_tool`, `invoke_tool` — over a **remote**
+backend, calling it with `fetch`.
+
+> Status: `0.2.0`, alpha. Install with `npm install -g @sezzlee/openapi-mcp` or run it with
+> `npx -y @sezzlee/openapi-mcp`; the binary is `sezzlee-openapi`.
+
+## How this differs from the embedded SDKs
+
+`Sezzlee.AspNetCore` and the NestJS SDK sit **inside** your backend process: they discover
+endpoints from your own controllers/routes and replay each MCP call through your existing
+pipeline, so your authentication and authorization run exactly as they do today.
+
+`openapi-mcp` is a separate service. It has no access to a backend's process or pipeline — it
+reads the backend's **OpenAPI document** to learn what operations exist ([the ingestion
+rules](../../http/spec/openapi-ingestion.md)), and calls the backend over the network for every
+invocation, attaching a credential it resolves itself ([how a credential is chosen and
+written](../../http/spec/credentials.md)). This is the only path for a backend that has no
+embedded SDK integrated into it.
+
+## Quick start
+
+The server reads its configuration from the file named by `SEZZLEE_OPENAPI_CONFIG`. Build the
+package first (this repository never runs `@sezzlee/core`'s consumers against a stale `dist`):
+
+```bash
+pnpm turbo run build --filter=@sezzlee/openapi-mcp
+```
+
+A minimal config — a local document, opt-in selection so at least one operation is exposed,
+default `stdio` transport:
+
+```json
+{
+  "source": "./openapi.json",
+  "selection": { "default": "include" }
+}
+```
+
+```bash
+SEZZLEE_OPENAPI_CONFIG=/absolute/path/to/config.json node packages/servers/openapi-mcp/dist/cli.js
+```
+
+`source` is either a path (resolved relative to the config file's own directory) or an
+`http(s)://` URL. On startup the server ingests the document, builds the catalog, prints a
+one-line-per-diagnostic-code summary to stderr, and then serves `stdio` or listens for
+`streamable HTTP`, depending on `transport.kind`.
+
+A config that fails validation, or that names an environment variable that is not set, stops the
+process with a message on stderr and exit code `2`. A document that ingests with a fatal
+diagnostic, or a catalog with a fatal diagnostic (`name_collision`, `invalid_name`,
+`ambiguous_selection`, …), stops it with exit code `1`.
+
+## Configuration
+
+All keys below are read from the `SEZZLEE_OPENAPI_CONFIG` JSON file and validated with a `zod`
+schema (`src/platform/config.ts`) that rejects unknown keys.
+
+| Key                              | Type                                       | Default        | Notes                                                                                                                                                                          |
+| -------------------------------- | ------------------------------------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `transport.kind`                 | `"stdio"` \| `"http"`                      | `"stdio"`      | —                                                                                                                                                                              |
+| `transport.host`                 | string (`http` only)                       | `"127.0.0.1"`  | Must stay loopback (`127.0.0.1`, `::1`, `localhost`) unless `tokenExchange` is configured — see below                                                                          |
+| `transport.port`                 | int, 0–65535 (`http` only)                 | `8787`         | —                                                                                                                                                                              |
+| `transport.path`                 | string starting with `/` (`http` only)     | `"/mcp"`       | —                                                                                                                                                                              |
+| `transport.resource`             | url (`http` only)                          | required       | The OAuth protected-resource identifier advertised at `/.well-known/oauth-protected-resource`                                                                                  |
+| `transport.authorizationServers` | array of url, min 1 (`http` only)          | required       | —                                                                                                                                                                              |
+| `transport.allowedHostnames`     | array of string (`http` only)              | `[]`           | Extra `Host` header values accepted, on top of the localhost defaults                                                                                                          |
+| `tokenExchange`                  | object                                     | not configured | RFC 8693 token exchange; required for an `http` transport to authenticate a caller (see [Rules](#rules))                                                                       |
+| `tokenExchange.tokenEndpoint`    | url                                        | required       | —                                                                                                                                                                              |
+| `tokenExchange.clientId`         | string                                     | required       | —                                                                                                                                                                              |
+| `tokenExchange.clientSecret`     | `{ fromEnv: string }`                      | required       | —                                                                                                                                                                              |
+| `tokenExchange.clientAuth`       | `"basic"` \| `"post"`                      | `"basic"`      | `client_secret_basic` or `client_secret_post`                                                                                                                                  |
+| `tokenExchange.audience`         | string                                     | not sent       | —                                                                                                                                                                              |
+| `tokenExchange.resource`         | url                                        | not sent       | —                                                                                                                                                                              |
+| `tokenExchange.scope`            | string                                     | not sent       | —                                                                                                                                                                              |
+| `tokenExchange.schemes`          | array of string, min 1                     | required       | The security scheme names the exchanged token satisfies                                                                                                                        |
+| `source`                         | string, non-empty                          | required       | A local file path (relative to the config file) or an `http(s)://` URL to the OpenAPI document                                                                                 |
+| `baseUrl`                        | url                                        | not set        | Replaces the document's root `servers`                                                                                                                                         |
+| `serverVariables`                | record\<string, string\>                   | not set        | Overrides for the document's server variable defaults                                                                                                                          |
+| `hoistPathPrefix`                | string starting with `/`                   | not set        | A leading path segment moved from every route into the base URL                                                                                                                |
+| `outputSchema`                   | `"document"` \| `"omit"`                   | `"document"`   | `omit` for a backend whose responses do not match its document                                                                                                                 |
+| `requestBodyRequired`            | `"document"` \| `"always"`                 | `"document"`   | `always` treats an undeclared `requestBody.required` as `true`                                                                                                                 |
+| `strict`                         | boolean                                    | `false`        | Raises `openapi_document_invalid` from a warning to a fatal diagnostic                                                                                                         |
+| `selection.default`              | `"include"` \| `"exclude"`                 | `"exclude"`    | Whether an operation is exposed when no rule matches it (opt-in by default)                                                                                                    |
+| `selection.rules`                | array of `{ route?, method?, decision }`   | `[]`           | `route`/`method` are matched the same way the embedded SDKs match a controller route                                                                                           |
+| `names`                          | record\<operation key, string\>            | `{}`           | Overrides a tool's name; the value must match `^[a-z][a-z0-9_]{0,255}$`                                                                                                        |
+| `credentials`                    | record\<security scheme name, credential\> | `{}`           | Either `{ "value": { "fromEnv": "..." } }` or `{ "username": { "fromEnv": "..." }, "password": { "fromEnv": "..." } }`; see [credentials.md](../../http/spec/credentials.md)   |
+| `allowHosts`                     | array of string                            | `[]`           | Hosts a backend operation may be served from, beyond the document's own root server                                                                                            |
+| `refHosts`                       | array of string                            | `[]`           | Hosts an external `$ref` may be fetched from, beyond the document's own host. Kept apart from `allowHosts`, so allowing a schema host never lets calls or credentials go there |
+| `identityCookies`                | array of string                            | `[]`           | Cookie names treated as identity carriers on top of the default deny-list (compared case-insensitively); they extend it and never replace it                                   |
+| `limits.timeoutMs`               | positive int                               | `30000`        | Per-invocation deadline                                                                                                                                                        |
+| `limits.maxResponseBytes`        | positive int                               | `262144`       | Response byte cap, applied while the body streams                                                                                                                              |
+| `limits.maxInlineFileBytes`      | positive int                               | `1048576`      | —                                                                                                                                                                              |
+
+A `credentials` entry is keyed by the security scheme name it satisfies; a `tokenExchange.schemes`
+entry marks that same scheme as satisfied by the exchanged token instead. `credentials` values are
+never inlined — only a reference to an environment variable — so a config file can be committed
+and shared.
+
+## Rules
+
+- **Only `src/net/fetch.ts` reaches the network.** It is the one place the host allowlist, the
+  manual redirect handling and the byte cap are applied; `src/transport/http.ts` may use
+  `node:http` only to _listen_, never to call out. Redirects are never followed — a followed
+  redirect could carry a request, and its credential, to a host the allowlist never approved.
+- **Only `src/platform/files.ts` touches the filesystem.** A file the document references through
+  an external `$ref`, or named by `source`, is checked against the directory the document was
+  read from on its _realpath_, so neither a `../` segment nor a symbolic link can escape it.
+- **The caller's MCP token is never forwarded to the backend.** Its audience is this server, not
+  the backend; forwarding it would bypass the backend's own audience check. On the `http`
+  transport with `tokenExchange` configured, the caller's token is exchanged (RFC 8693) for a
+  backend-scoped token at the transport's bearer gate, and only the exchanged token reaches
+  `invoke_tool`.
+- **An `http` transport without `tokenExchange` authenticates no caller**, so it may only bind a
+  loopback host (`127.0.0.1`, `::1`, `localhost`); otherwise the operator's static credentials
+  would be reachable from the network. Configuring `tokenExchange` on the `stdio` transport is
+  likewise refused (`token_exchange_requires_http`) — there is no caller token on `stdio` to
+  exchange.
+- Visibility is not enforcement: an operation's `security` says which credential a call needs, not
+  which caller may make it, so the catalog reports every operation's identity as `unknown` unless
+  its document says `security: []`.
+
+## Development
+
+```bash
+pnpm turbo run build --filter=@sezzlee/openapi-mcp
+pnpm turbo run lint --filter=@sezzlee/openapi-mcp
+pnpm turbo run check-types --filter=@sezzlee/openapi-mcp
+pnpm turbo run test --filter=@sezzlee/openapi-mcp
+```
+
+Run these through Turbo, not `pnpm --filter @sezzlee/openapi-mcp <task>` — the bare filter skips
+`dependsOn: ["build"]` and the test task would run against a stale `dist`.
+
+`test/` holds four suites:
+
+- `gateway.spec.ts`, `http.spec.ts` — unit tests, no environment variables needed.
+- `acceptance.spec.ts` — skipped unless `SEZZLEE_OPENAPI_ACCEPTANCE_DOC` names a path to a real
+  backend's OpenAPI document. The document itself never enters the repository; the suite ingests
+  it, builds a catalog, asserts there is no fatal diagnostic, and prints the diagnostic summary
+  instead of pinning a snapshot that would copy that backend's surface into the tree.
+- `parity.spec.ts` — skipped unless `SEZZLEE_PARITY_DIR` names a directory of fixtures written by
+  `sdks/dotnet/tests/Sezzlee.Tests/OpenApiParityDump.cs`, comparing this ingestion's output against
+  the .NET SDK's.
+
+Both `SEZZLEE_OPENAPI_ACCEPTANCE_DOC` and `SEZZLEE_PARITY_DIR` are declared in `turbo.json`'s `test`
+task so Turbo passes them through.

package/dist/catalog/build.d.ts

@@ -0,0 +1,25 @@
+import { type CatalogBuild, type CatalogDiagnostic } from "@sezzlee/core";
+import { type IngestionDiagnostic, type SecurityModel, type SourcedEndpoint } from "@sezzlee/openapi";
+import type { DocumentLoader } from "@sezzlee/openapi";
+import { type ChosenCredentials } from "../credentials/credentials.js";
+import type { GatewayConfig, ResolvedCredential } from "../platform/config.js";
+export interface GatewaySource {
+    readonly endpoint: SourcedEndpoint;
+    readonly baseUrl: string;
+    readonly credentials: ChosenCredentials;
+}
+export interface GatewayCatalog {
+    readonly catalog: CatalogBuild<GatewaySource>;
+    readonly allowedHosts: ReadonlySet<string>;
+    readonly security: SecurityModel;
+    readonly ingestion: readonly IngestionDiagnostic[];
+    readonly dropped: readonly CatalogDiagnostic[];
+}
+/**
+ * @param document the parsed document, or its text
+ * @param configuredHosts hosts the operator allows beyond the root server; an operation whose
+ * server is neither is dropped with `server_host_not_allowed`
+ */
+export declare function buildGatewayCatalog(document: string | Record<string, unknown>, config: GatewayConfig, credentials: ReadonlyMap<string, ResolvedCredential>, configuredHosts: readonly string[], documentUrl: string | undefined, loader: DocumentLoader | undefined): Promise<GatewayCatalog>;
+/** One line per diagnostic code, with its count and the first locations, so a large document stays readable. */
+export declare function summarize(ingestion: readonly IngestionDiagnostic[], catalog: readonly CatalogDiagnostic[]): string[];

package/dist/catalog/build.js

@@ -0,0 +1,109 @@
+import { asciiLower } from "../platform/ascii.js";
+import { buildCatalog, severityIn, } from "@sezzlee/core";
+import { ingest, } from "@sezzlee/openapi";
+import { chooseCredentials, } from "../credentials/credentials.js";
+/**
+ * @param document the parsed document, or its text
+ * @param configuredHosts hosts the operator allows beyond the root server; an operation whose
+ * server is neither is dropped with `server_host_not_allowed`
+ */
+export async function buildGatewayCatalog(document, config, credentials, configuredHosts, documentUrl, loader) {
+    const result = await ingest(document, {
+        ...(documentUrl === undefined ? {} : { documentUrl }),
+        ...(config.baseUrl === undefined ? {} : { baseUrl: config.baseUrl }),
+        ...(config.serverVariables === undefined
+            ? {}
+            : { serverVariables: config.serverVariables }),
+        ...(loader === undefined ? {} : { loader }),
+        strict: config.strict,
+        identityCookies: config.identityCookies,
+        outputSchema: config.outputSchema,
+        requestBodyRequired: config.requestBodyRequired,
+        ...(config.hoistPathPrefix === undefined
+            ? {}
+            : { hoistPathPrefix: config.hoistPathPrefix }),
+    });
+    const allowedHosts = new Set(configuredHosts.map((host) => asciiLower(host)));
+    if (result.rootBaseUrl !== undefined) {
+        allowedHosts.add(asciiLower(new URL(result.rootBaseUrl).host));
+    }
+    const dropped = [];
+    const candidates = result.endpoints.flatMap((endpoint) => {
+        if (endpoint.baseUrl === undefined) {
+            return [];
+        }
+        const host = asciiLower(new URL(endpoint.baseUrl).host);
+        if (!allowedHosts.has(host)) {
+            dropped.push({
+                code: "server_host_not_allowed",
+                message: `${endpoint.key} is served by '${host}', which is not on the allowlist.`,
+            });
+            return [];
+        }
+        const chosen = chooseCredentials(endpoint.security, result.security, credentials);
+        if (chosen === undefined) {
+            dropped.push({
+                code: "security_unsatisfiable",
+                message: `${endpoint.key} needs a credential none of the configured ones satisfies.`,
+            });
+            return [];
+        }
+        const name = config.names[endpoint.key];
+        const searchTerms = config.searchTerms[endpoint.key];
+        const descriptor = name === undefined
+            ? endpoint.descriptor
+            : { ...endpoint.descriptor, toolName: name };
+        return [
+            {
+                source: { endpoint, baseUrl: endpoint.baseUrl, credentials: chosen },
+                owner: endpoint.key,
+                descriptor,
+                ...(descriptor.tags === undefined ? {} : { tags: descriptor.tags }),
+                ...(searchTerms === undefined ? {} : { searchTerms }),
+                declare: (tags) => ({
+                    ...descriptor,
+                    ...(tags === undefined ? {} : { tags: [...tags] }),
+                }),
+            },
+        ];
+    });
+    const catalog = buildCatalog(candidates, {
+        selection: config.selection,
+        providers: new Set(),
+        severity: (code) => severityIn({
+            name_collision: "fatal",
+            invalid_name: "fatal",
+            ambiguous_selection: "fatal",
+        }, code),
+        failOn: "fatal",
+        prior: dropped,
+    });
+    return {
+        catalog,
+        allowedHosts,
+        security: result.security,
+        ingestion: result.diagnostics,
+        dropped,
+    };
+}
+/** One line per diagnostic code, with its count and the first locations, so a large document stays readable. */
+export function summarize(ingestion, catalog) {
+    const groups = new Map();
+    const add = (code, severity, sample) => {
+        const group = groups.get(code) ?? { severity, count: 0, samples: [] };
+        group.count += 1;
+        if (group.samples.length < 3) {
+            group.samples.push(sample);
+        }
+        groups.set(code, group);
+    };
+    for (const diagnostic of ingestion) {
+        add(diagnostic.code, diagnostic.severity, diagnostic.at === "" ? "(document)" : diagnostic.at);
+    }
+    for (const diagnostic of catalog) {
+        add(diagnostic.code, "catalog", diagnostic.message);
+    }
+    return [...groups.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([code, group]) => `${group.severity} ${code} ×${String(group.count)}: ${group.samples.join(" | ")}`);
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+import { fileURLToPath } from "node:url";
+import { resolve } from "node:path";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { buildGatewayCatalog, summarize } from "./catalog/build.js";
+import { createBoundedFetch, HostNotAllowed } from "./net/fetch.js";
+import { asciiLower } from "./platform/ascii.js";
+import { readConfig } from "./platform/config.js";
+import { directoryOf, readText, readWithin } from "./platform/files.js";
+import { createOpenApiMcpServer } from "./server.js";
+import { createTokenExchange } from "./credentials/token-exchange.js";
+import { serveHttp } from "./transport/http.js";
+function stop(message, code) {
+    process.stderr.write(`${message}\n`);
+    process.exit(code);
+}
+/**
+ * Guard: the config path is read by name so `turbo/no-undeclared-env-vars` forces it into
+ * `passThroughEnv`. The secrets a config names are read through the lookup below, the one place
+ * this package reads an arbitrary variable, because their names belong to the operator.
+ */
+const configPath = process.env["SEZZLEE_OPENAPI_CONFIG"];
+if (configPath === undefined || configPath === "") {
+    stop("sezzlee-openapi reads its config from the file SEZZLEE_OPENAPI_CONFIG names.", 2);
+}
+let raw;
+try {
+    raw = JSON.parse(await readText(configPath));
+}
+catch (error) {
+    stop(`sezzlee-openapi cannot read its config: ${error.message}`, 2);
+}
+const outcome = readConfig(raw, (name) => process.env[name]);
+if (outcome.kind === "invalid") {
+    stop(outcome.reason, 2);
+}
+const { config, credentials } = outcome;
+const isUrl = /^https?:\/\//i.test(config.source);
+const sourcePath = isUrl
+    ? undefined
+    : resolve(directoryOf(configPath), config.source);
+const documentUrl = isUrl
+    ? config.source
+    : new URL(`file://${sourcePath ?? ""}`).href;
+const documentHost = isUrl
+    ? asciiLower(new URL(config.source).host)
+    : undefined;
+const documentFetch = createBoundedFetch(new Set([
+    ...(documentHost === undefined ? [] : [documentHost]),
+    ...config.refHosts.map((host) => asciiLower(host)),
+]));
+const documentLimit = 64 * 1024 * 1024;
+async function readDocument(url) {
+    if (url.protocol === "file:") {
+        return readWithin(directoryOf(sourcePath ?? "."), fileURLToPath(url));
+    }
+    const response = await documentFetch({
+        method: "GET",
+        url,
+        headers: {
+            accept: "application/json, application/yaml;q=0.9, */*;q=0.1",
+        },
+    }, AbortSignal.timeout(config.limits.timeoutMs), documentLimit);
+    if (response.status !== 200 || response.body === undefined) {
+        throw new Error(`sezzlee-openapi: ${url.href} answered ${String(response.status)}.`);
+    }
+    return response.body;
+}
+const loader = readDocument;
+let text;
+try {
+    text = isUrl
+        ? await readDocument(new URL(config.source))
+        : await readText(sourcePath ?? "");
+}
+catch (error) {
+    stop(`sezzlee-openapi cannot read the document: ${error.message}`, 2);
+}
+const gateway = await buildGatewayCatalog(text, config, credentials, config.allowHosts, documentUrl, loader).catch((error) => stop(error instanceof HostNotAllowed
+    ? `sezzlee-openapi: the document references a schema on '${error.host}', which is not a reference host; add it to "refHosts" in the config to allow it.`
+    : `sezzlee-openapi cannot resolve the document: ${error.message}`, 2));
+for (const line of summarize(gateway.ingestion, gateway.catalog.diagnostics)) {
+    process.stderr.write(`${line}\n`);
+}
+process.stderr.write(`sezzlee-openapi: ${String(gateway.catalog.entries.length)} tool(s) from ${String(gateway.catalog.selected)} selected operation(s).\n`);
+if (gateway.catalog.fatal.length > 0 ||
+    gateway.ingestion.some((d) => d.severity === "fatal")) {
+    stop("sezzlee-openapi: the catalog has fatal diagnostics; see above.", 1);
+}
+const fetcher = createBoundedFetch(gateway.allowedHosts);
+const factory = () => createOpenApiMcpServer(gateway, fetcher, config.limits);
+if (config.transport.kind === "http") {
+    const exchangeConfig = config.tokenExchange;
+    const exchange = exchangeConfig === undefined
+        ? undefined
+        : createTokenExchange(exchangeConfig, outcome.clientSecret ?? "", createBoundedFetch(new Set([asciiLower(new URL(exchangeConfig.tokenEndpoint).host)])), config.limits.timeoutMs);
+    const listening = await serveHttp(factory, exchange, config.transport);
+    process.stderr.write(`sezzlee-openapi: listening on http://${config.transport.host}:${String(config.transport.port)}${config.transport.path}\n`);
+    const close = () => {
+        listening.close();
+    };
+    process.once("SIGINT", close);
+    process.once("SIGTERM", close);
+}
+else {
+    serveOverStdio();
+}
+function serveOverStdio() {
+    const handle = serveStdio(factory, {
+        onerror: (error) => {
+            process.stderr.write(`${error.message}\n`);
+        },
+    });
+    const shutdown = () => {
+        void handle.close();
+    };
+    process.once("SIGINT", shutdown);
+    process.once("SIGTERM", shutdown);
+}

package/dist/credentials/credentials.d.ts

@@ -0,0 +1,32 @@
+import type { SecurityModel, SecurityRequirement, SecurityScheme } from "@sezzlee/openapi";
+import type { ResolvedCredential } from "../platform/config.js";
+export interface Placement {
+    readonly scheme: SecurityScheme;
+    readonly credential: ResolvedCredential;
+}
+/** The credentials one invocation writes; empty for an anonymous alternative. */
+export type ChosenCredentials = readonly Placement[];
+/**
+ * Picks the first alternative whose every scheme a configured credential satisfies. Applying every
+ * configured scheme at once was rejected: it sends the backend credentials it did not ask for.
+ *
+ * @returns the placements to write, or `undefined` when no alternative can be satisfied
+ */
+export declare function chooseCredentials(requirements: readonly SecurityRequirement[] | undefined, schemes: SecurityModel, credentials: ReadonlyMap<string, ResolvedCredential>): ChosenCredentials | undefined;
+export interface OutboundSlots {
+    readonly headers: Record<string, string>;
+    readonly queryPairs: string[];
+    cookie: string | undefined;
+}
+/**
+ * Writes the chosen credentials into their slots. A credential cookie comes before a composed one,
+ * and a composed cookie with the same name is `cookie_carrier_collision` rather than an overwrite.
+ */
+export declare class ExchangedTokenMissing extends Error {
+    constructor();
+}
+/**
+ * @param exchanged the backend token the caller's own token was exchanged for; required when a
+ * placement is satisfied by token exchange
+ */
+export declare function applyCredentials(placements: ChosenCredentials, slots: OutboundSlots, exchanged?: string): void;

package/dist/credentials/credentials.js

@@ -0,0 +1,102 @@
+import { asciiLower, asciiUpper } from "../platform/ascii.js";
+import { mergeCookieHeader } from "@sezzlee/core";
+function fits(scheme, credential) {
+    if (credential === undefined) {
+        return false;
+    }
+    switch (scheme.type) {
+        case "apiKey":
+            return credential.kind === "value";
+        case "http":
+            return scheme.scheme === "basic"
+                ? credential.kind === "basic"
+                : credential.kind === "value" || credential.kind === "exchanged";
+        case "oauth2":
+        case "openIdConnect":
+            return credential.kind === "exchanged";
+        case "mutualTLS":
+            return false;
+    }
+}
+/**
+ * Picks the first alternative whose every scheme a configured credential satisfies. Applying every
+ * configured scheme at once was rejected: it sends the backend credentials it did not ask for.
+ *
+ * @returns the placements to write, or `undefined` when no alternative can be satisfied
+ */
+export function chooseCredentials(requirements, schemes, credentials) {
+    if (requirements === undefined || requirements.length === 0) {
+        return [];
+    }
+    for (const alternative of requirements) {
+        const placements = [];
+        let satisfied = true;
+        for (const ref of alternative.keys()) {
+            const scheme = schemes.get(ref);
+            const credential = credentials.get(ref);
+            if (scheme === undefined || !fits(scheme, credential)) {
+                satisfied = false;
+                break;
+            }
+            placements.push({ scheme, credential });
+        }
+        if (satisfied) {
+            return placements;
+        }
+    }
+    return undefined;
+}
+const encode = (value) => encodeURIComponent(value).replace(/[!'()*]/g, (c) => `%${asciiUpper(c.charCodeAt(0).toString(16))}`);
+/**
+ * Writes the chosen credentials into their slots. A credential cookie comes before a composed one,
+ * and a composed cookie with the same name is `cookie_carrier_collision` rather than an overwrite.
+ */
+export class ExchangedTokenMissing extends Error {
+    constructor() {
+        super("sezzlee-openapi: the operation needs an exchanged token, and the call carried none.");
+        this.name = "ExchangedTokenMissing";
+    }
+}
+/**
+ * @param exchanged the backend token the caller's own token was exchanged for; required when a
+ * placement is satisfied by token exchange
+ */
+export function applyCredentials(placements, slots, exchanged) {
+    const credentialCookies = [];
+    for (const { scheme, credential } of placements) {
+        if (credential.kind === "exchanged" && exchanged === undefined) {
+            throw new ExchangedTokenMissing();
+        }
+        const value = credential.kind === "value"
+            ? credential.value
+            : credential.kind === "exchanged"
+                ? (exchanged ?? "")
+                : "";
+        switch (scheme.type) {
+            case "apiKey":
+                if (scheme.in === "header") {
+                    slots.headers[asciiLower(scheme.name)] = value;
+                }
+                else if (scheme.in === "query") {
+                    slots.queryPairs.push(`${encode(scheme.name)}=${encode(value)}`);
+                }
+                else {
+                    credentialCookies.push(`${scheme.name}=${value}`);
+                }
+                break;
+            case "http":
+            case "oauth2":
+            case "openIdConnect":
+                slots.headers["authorization"] =
+                    credential.kind === "basic"
+                        ? `Basic ${Buffer.from(`${credential.username}:${credential.password}`, "utf8").toString("base64")}`
+                        : `Bearer ${value}`;
+                break;
+            case "mutualTLS":
+                break;
+        }
+    }
+    if (credentialCookies.length > 0) {
+        slots.cookie = mergeCookieHeader(credentialCookies.join("; "), slots.cookie);
+    }
+}

package/dist/credentials/token-exchange.d.ts

@@ -0,0 +1,24 @@
+import type { BoundedFetch } from "../net/fetch.js";
+import type { TokenExchangeConfig } from "../platform/config.js";
+export interface ExchangedToken {
+    readonly token: string;
+    /** Unix seconds. */
+    readonly expiresAt: number;
+}
+export declare class TokenExchangeFailed extends Error {
+    readonly rejected: boolean;
+    constructor(rejected: boolean, message: string);
+}
+export interface TokenExchange {
+    exchange(subjectToken: string): Promise<ExchangedToken>;
+}
+/**
+ * RFC 8693 token exchange against one authorization server.
+ *
+ * Guard: the cache key is a digest of the subject token, never the token, so a heap dump of the
+ * cache does not hold a usable credential; an exchanged token never outlives the subject token it
+ * was issued for; a failure is not cached, so a caller whose grant is restored is not locked out
+ * until an expiry; the token endpoint's body is never surfaced, for the reason a backend's 401 body
+ * is not — it describes the credential, not the call.
+ */
+export declare function createTokenExchange(config: TokenExchangeConfig, clientSecret: string, fetcher: BoundedFetch, timeoutMs: number, now?: () => number): TokenExchange;