@knitli/openapi-mcp 0.0.0

package/dist/runtime/schema-keywords.d.ts

@@ -0,0 +1,2 @@
+export type SchemaChildKind = "single" | "map" | "array" | null;
+export declare function schemaChildKind(key: string): SchemaChildKind;

package/dist/runtime/schema-keywords.js

@@ -0,0 +1,30 @@
+const singular = new Set([
+    "additionalProperties",
+    "contains",
+    "contentSchema",
+    "else",
+    "if",
+    "items",
+    "not",
+    "propertyNames",
+    "then",
+    "unevaluatedItems",
+    "unevaluatedProperties",
+]);
+const maps = new Set([
+    "$defs",
+    "definitions",
+    "dependentSchemas",
+    "patternProperties",
+    "properties",
+]);
+const arrays = new Set(["allOf", "anyOf", "oneOf", "prefixItems"]);
+export function schemaChildKind(key) {
+    if (singular.has(key))
+        return "single";
+    if (maps.has(key))
+        return "map";
+    if (arrays.has(key))
+        return "array";
+    return null;
+}

package/dist/runtime/schema-resolver.d.ts

@@ -0,0 +1,10 @@
+import type { AdmittedManifest } from "./manifest.ts";
+import type { CatalogStore, JsonSchemaV4, SchemaRecordV4, TypedSchemaId } from "./types.ts";
+import { type RuntimeLimits } from "./versions.ts";
+/** Collect references only from positions that JSON Schema defines as schemas. */
+export declare function collectReferences(schema: JsonSchemaV4): readonly TypedSchemaId[];
+/**
+ * Load and verify a schema graph one breadth-first frontier at a time.
+ * No result escapes until the complete requested closure has passed all checks.
+ */
+export declare function resolveSchemaClosure(store: CatalogStore, admitted: AdmittedManifest, roots: TypedSchemaId | readonly TypedSchemaId[], limitOverrides?: RuntimeLimits): Promise<ReadonlyMap<TypedSchemaId, Readonly<SchemaRecordV4>>>;

package/dist/runtime/schema-resolver.js

@@ -0,0 +1,237 @@
+import { OpenApiMcpError } from "./errors.js";
+import { parseTypedRecordId } from "./references.js";
+import { schemaChildKind } from "./schema-keywords.js";
+import { canonicalJson } from "./strict-json.js";
+import { verifyStoredRecord } from "./verify-record.js";
+import { DEFAULT_RUNTIME_LIMITS, resolveRuntimeLimits, } from "./versions.js";
+function resolutionLimit(message) {
+    return new OpenApiMcpError("SCHEMA_RESOLUTION_LIMIT", message);
+}
+function schemaLookupUnavailable() {
+    return new OpenApiMcpError("UPSTREAM_ERROR", "Schema lookup is unavailable", {
+        retryable: true,
+    });
+}
+function schemaReference(value) {
+    try {
+        if (typeof value !== "string")
+            throw new Error();
+        const parsed = parseTypedRecordId(value);
+        if (!parsed.startsWith("schema:"))
+            throw new Error();
+        return parsed;
+    }
+    catch {
+        throw new OpenApiMcpError("RECORD_DIGEST_MISMATCH", "Verified schema contains an invalid local reference");
+    }
+}
+/** Collect references only from positions that JSON Schema defines as schemas. */
+export function collectReferences(schema) {
+    if (typeof schema === "boolean")
+        return [];
+    const found = new Set();
+    const stack = [schema];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (typeof current === "boolean" || current === undefined)
+            continue;
+        if (Object.hasOwn(current, "$ref")) {
+            found.add(schemaReference(current.$ref));
+        }
+        for (const [key, child] of Object.entries(current)) {
+            const kind = schemaChildKind(key);
+            if (kind === "single") {
+                stack.push(child);
+            }
+            else if (kind === "array") {
+                for (const entry of child)
+                    stack.push(entry);
+            }
+            else if (kind === "map") {
+                for (const entry of Object.values(child)) {
+                    stack.push(entry);
+                }
+            }
+        }
+    }
+    return [...found].sort();
+}
+function snapshotRows(value, maximum) {
+    try {
+        if (!Array.isArray(value))
+            throw new Error();
+        const lengthDescriptor = Object.getOwnPropertyDescriptor(value, "length");
+        if (lengthDescriptor === undefined ||
+            !("value" in lengthDescriptor) ||
+            !Number.isSafeInteger(lengthDescriptor.value) ||
+            lengthDescriptor.value < 0 ||
+            lengthDescriptor.value > maximum)
+            throw new Error();
+        const length = lengthDescriptor.value;
+        const keys = Reflect.ownKeys(value);
+        if (keys.length !== length + 1 ||
+            keys.some((key) => typeof key !== "string" ||
+                (key !== "length" && !/^(0|[1-9][0-9]*)$/.test(key))))
+            throw new Error();
+        const snapshot = [];
+        for (let index = 0; index < length; index += 1) {
+            const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+            if (descriptor === undefined ||
+                !("value" in descriptor) ||
+                !descriptor.enumerable)
+                throw new Error();
+            snapshot.push(descriptor.value);
+        }
+        return snapshot;
+    }
+    catch {
+        throw new OpenApiMcpError("RECORD_NOT_ADMITTED", "Schema lookup result is invalid");
+    }
+}
+class ImmutableSchemaMap {
+    #records;
+    constructor(records) {
+        this.#records = new Map(records);
+        Object.freeze(this);
+    }
+    get size() {
+        return this.#records.size;
+    }
+    get(key) {
+        return this.#records.get(key);
+    }
+    has(key) {
+        return this.#records.has(key);
+    }
+    entries() {
+        return this.#records.entries();
+    }
+    keys() {
+        return this.#records.keys();
+    }
+    values() {
+        return this.#records.values();
+    }
+    forEach(callbackfn, thisArg) {
+        for (const [key, value] of this.#records) {
+            callbackfn.call(thisArg, value, key, this);
+        }
+    }
+    [Symbol.iterator]() {
+        return this.entries();
+    }
+    get [Symbol.toStringTag]() {
+        return "ImmutableSchemaMap";
+    }
+}
+function snapshotRoots(value, maximum) {
+    try {
+        if (typeof value === "string")
+            return [value];
+        if (!Array.isArray(value) ||
+            Object.getPrototypeOf(value) !== Array.prototype)
+            throw new Error();
+        const lengthDescriptor = Object.getOwnPropertyDescriptor(value, "length");
+        if (lengthDescriptor === undefined ||
+            !("value" in lengthDescriptor) ||
+            !Number.isSafeInteger(lengthDescriptor.value) ||
+            lengthDescriptor.value < 0 ||
+            lengthDescriptor.value > maximum)
+            throw new Error();
+        const length = lengthDescriptor.value;
+        const ownKeys = Reflect.ownKeys(value);
+        if (ownKeys.length !== length + 1 ||
+            ownKeys.some((key) => typeof key !== "string" ||
+                (key !== "length" && !/^(0|[1-9][0-9]*)$/.test(key))))
+            throw new Error();
+        const snapshot = [];
+        for (let index = 0; index < length; index += 1) {
+            const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+            if (descriptor === undefined ||
+                !("value" in descriptor) ||
+                typeof descriptor.value !== "string")
+                throw new Error();
+            snapshot.push(descriptor.value);
+        }
+        return snapshot;
+    }
+    catch {
+        throw resolutionLimit("Schema root list is invalid or exceeds its limit");
+    }
+}
+/**
+ * Load and verify a schema graph one breadth-first frontier at a time.
+ * No result escapes until the complete requested closure has passed all checks.
+ */
+export async function resolveSchemaClosure(store, admitted, roots, limitOverrides = DEFAULT_RUNTIME_LIMITS) {
+    const limits = resolveRuntimeLimits(limitOverrides);
+    const rootLimit = Math.min(limits.maxManifestRecords, limits.maxSchemaClosureBytes);
+    let frontier = [...new Set(snapshotRoots(roots, rootLimit))].sort();
+    const visited = new Set();
+    const resolved = new Map();
+    let aggregateBytes = 0;
+    let hop = 0;
+    while (frontier.length > 0) {
+        if (hop > limits.maxSchemaRefHops) {
+            throw resolutionLimit("Schema reference hop limit exceeded");
+        }
+        for (const id of frontier) {
+            let parsed;
+            try {
+                parsed = parseTypedRecordId(id);
+            }
+            catch {
+                throw new OpenApiMcpError("RECORD_NOT_ADMITTED", "Schema reference is not admitted");
+            }
+            if (!parsed.startsWith("schema:") ||
+                !Object.hasOwn(admitted.manifest.records, id)) {
+                throw new OpenApiMcpError("RECORD_NOT_ADMITTED", "Schema reference is not admitted");
+            }
+        }
+        const next = new Set();
+        let offset = 0;
+        while (offset < frontier.length) {
+            const remainingBytes = limits.maxSchemaClosureBytes - aggregateBytes;
+            if (remainingBytes <= 0) {
+                throw resolutionLimit("Schema closure byte limit exceeded");
+            }
+            const chunkSize = Math.max(1, Math.min(frontier.length - offset, Math.floor(remainingBytes / limits.maxRecordBytes)));
+            const chunk = frontier.slice(offset, offset + chunkSize);
+            let rowResult;
+            try {
+                rowResult = await store.getSchemas(admitted.manifest.catalogId, admitted.manifest.releaseId, chunk);
+            }
+            catch {
+                throw schemaLookupUnavailable();
+            }
+            const rows = snapshotRows(rowResult, chunk.length);
+            const verifiedRows = await Promise.all(rows.map((row) => verifyStoredRecord(admitted, row, limits)));
+            const byId = new Map(verifiedRows.map((record) => [record.id, record]));
+            if (byId.size !== chunk.length ||
+                verifiedRows.length !== chunk.length ||
+                chunk.some((id) => !byId.has(id))) {
+                throw new OpenApiMcpError("RECORD_NOT_ADMITTED", "A required schema record is missing or ambiguous");
+            }
+            for (const id of chunk) {
+                const verified = byId.get(id);
+                if (!verified.id.startsWith("schema:")) {
+                    throw new OpenApiMcpError("RECORD_DIGEST_MISMATCH", "Schema lookup returned a non-schema record");
+                }
+                aggregateBytes += new TextEncoder().encode(canonicalJson(verified)).length;
+                if (aggregateBytes > limits.maxSchemaClosureBytes) {
+                    throw resolutionLimit("Schema closure byte limit exceeded");
+                }
+                resolved.set(id, verified);
+                visited.add(id);
+                for (const reference of collectReferences(verified.schema)) {
+                    if (!visited.has(reference))
+                        next.add(reference);
+                }
+            }
+            offset += chunk.length;
+        }
+        frontier = [...next].filter((id) => !visited.has(id)).sort();
+        hop += 1;
+    }
+    return new ImmutableSchemaMap(resolved);
+}

package/dist/runtime/serialize.d.ts

@@ -0,0 +1,12 @@
+import type { JsonObject, OperationRecordV4, SchemaRecordV4, SerializeArgumentsOptions, TypedSchemaId } from "./types.ts";
+export interface SerializedArguments {
+    readonly normalizedArguments: JsonObject;
+    readonly relativeUrl: string;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body: Uint8Array | null;
+}
+/**
+ * Detach, validate, and serialize one exact public argument envelope.
+ * The result is authority-free and contains no caller-selected credentials.
+ */
+export declare function serializeArguments(operation: Readonly<OperationRecordV4>, schemas: ReadonlyMap<TypedSchemaId, Readonly<SchemaRecordV4>>, arguments_: unknown, optionsValue?: SerializeArgumentsOptions): SerializedArguments;