@knitli/openapi-mcp 0.0.0

package/dist/sqlite/catalog-store.d.ts

@@ -0,0 +1,20 @@
+import { type CatalogId, type CatalogStore, type ManifestEnvelope, type OperationRecordV4, type ReleaseId, type RuntimeLimits, type SchemaRecordV4, type SearchQuery, type StoredRecord, type TypedOperationId, type TypedSchemaId } from "../runtime/index.ts";
+export interface LegacyV3CatalogIdentity {
+    readonly catalogId: CatalogId;
+    readonly releaseId: ReleaseId;
+}
+export interface SqliteCatalogStoreOptions {
+    readonly limits?: Partial<RuntimeLimits>;
+    readonly legacyIdentity?: LegacyV3CatalogIdentity;
+}
+/** Read-only v4/v5 store with an explicit inventory-only v3 migration mode. */
+export declare class SqliteCatalogStore implements CatalogStore {
+    #private;
+    readonly legacyInventoryOnly: boolean;
+    constructor(path: string, options?: SqliteCatalogStoreOptions);
+    close(): void;
+    getManifest(catalog: CatalogId, release: ReleaseId): Promise<ManifestEnvelope>;
+    searchCandidates(query: SearchQuery): Promise<readonly import("../runtime/types.ts").CandidateRef[]>;
+    getOperation(catalog: CatalogId, release: ReleaseId, id: TypedOperationId): Promise<StoredRecord<OperationRecordV4> | null>;
+    getSchemas(catalog: CatalogId, release: ReleaseId, ids: readonly TypedSchemaId[]): Promise<readonly StoredRecord<SchemaRecordV4>[]>;
+}

package/dist/sqlite/catalog-store.js

@@ -0,0 +1,370 @@
+import { DatabaseSync } from "node:sqlite";
+import { createD1CatalogStore, OpenApiMcpError, parseTypedRecordId, resolveRuntimeLimits, } from "../runtime/index.js";
+import { parseJsonStrict } from "../runtime/strict-json.js";
+import { MAX_SEARCH_QUERY_BYTES } from "../runtime/versions.js";
+import { releaseFileIdentity, verifyReleaseCompletion, } from "./release-completion.js";
+const SCHEMA_PROBE = `SELECT CASE
+  WHEN typeof(name) = 'text' AND name IN ('meta', 'release_metadata') THEN name
+  ELSE NULL
+END AS name,
+CASE
+  WHEN typeof(type) = 'text' AND type = 'table' THEN type
+  ELSE NULL
+END AS type
+FROM sqlite_schema
+WHERE name IN ('meta', 'release_metadata')
+ORDER BY name COLLATE BINARY
+LIMIT 3;`;
+const V3_VERSION_PROBE = `SELECT CASE
+  WHEN typeof(value) = 'text' AND length(CAST(value AS BLOB)) <= 1 THEN value
+  ELSE NULL
+END AS value
+FROM meta
+WHERE key = ?
+LIMIT 2;`;
+const V4_VERSION_PROBE = `SELECT DISTINCT
+CASE
+  WHEN typeof(format) = 'integer' AND length(CAST(format AS BLOB)) <= 1 THEN format
+  ELSE NULL
+END AS format,
+CASE
+  WHEN typeof(contract) = 'integer' AND length(CAST(contract AS BLOB)) <= 1 THEN contract
+  ELSE NULL
+END AS contract
+FROM release_metadata
+ORDER BY format, contract
+LIMIT 3;`;
+const V3_SEARCH_SQL = `SELECT CASE
+  WHEN typeof(o.qualified_id) = 'text'
+    AND length(CAST(o.qualified_id AS BLOB)) <= ?
+  THEN o.qualified_id
+  ELSE NULL
+END AS qualified_id
+FROM operations_fts
+JOIN operations AS o ON o.rowid = operations_fts.rowid
+WHERE operations_fts MATCH ?
+  AND (? IS NULL OR o.api = ?)
+ORDER BY bm25(operations_fts), o.qualified_id COLLATE BINARY
+LIMIT ?;`;
+const legacyQualifiedIdBytes = 641;
+function unsupported(message) {
+    return new OpenApiMcpError("ARTIFACT_FORMAT_UNSUPPORTED", message);
+}
+function segment(value) {
+    try {
+        if (typeof value !== "string")
+            throw new Error();
+        parseTypedRecordId(`operation:${value}:x`);
+        return value;
+    }
+    catch {
+        throw unsupported("Catalog identity is invalid");
+    }
+}
+function snapshotLegacyIdentity(options) {
+    try {
+        const legacyIdentity = Object.getOwnPropertyDescriptor(options, "legacyIdentity");
+        if (legacyIdentity === undefined)
+            return undefined;
+        if (!legacyIdentity.enumerable || !("value" in legacyIdentity))
+            throw new Error();
+        if (legacyIdentity.value === undefined)
+            return undefined;
+        const value = legacyIdentity.value;
+        if (typeof value !== "object" || value === null || Array.isArray(value))
+            throw new Error();
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== null && prototype !== Object.prototype)
+            throw new Error();
+        if (Object.getOwnPropertySymbols(value).length !== 0)
+            throw new Error();
+        const keys = Object.getOwnPropertyNames(value).sort();
+        if (keys.length !== 2 || keys[0] !== "catalogId" || keys[1] !== "releaseId")
+            throw new Error();
+        const catalogId = Object.getOwnPropertyDescriptor(value, "catalogId");
+        const releaseId = Object.getOwnPropertyDescriptor(value, "releaseId");
+        if (!catalogId?.enumerable ||
+            !("value" in catalogId) ||
+            !releaseId?.enumerable ||
+            !("value" in releaseId))
+            throw new Error();
+        return Object.freeze({
+            catalogId: segment(catalogId.value),
+            releaseId: segment(releaseId.value),
+        });
+    }
+    catch (error) {
+        if (error instanceof OpenApiMcpError)
+            throw error;
+        throw unsupported("Catalog identity is invalid");
+    }
+}
+function snapshotLegacySearchQuery(value, limits) {
+    try {
+        if (typeof value !== "object" || value === null || Array.isArray(value))
+            throw new Error();
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== null && prototype !== Object.prototype)
+            throw new Error();
+        if (Object.getOwnPropertySymbols(value).length !== 0)
+            throw new Error();
+        const api = Object.getOwnPropertyDescriptor(value, "api");
+        const expected = api === undefined ? ["limit", "query"] : ["api", "limit", "query"];
+        const keys = Object.getOwnPropertyNames(value).sort();
+        if (keys.length !== expected.length ||
+            keys.some((key, index) => key !== expected[index]))
+            throw new Error();
+        const query = Object.getOwnPropertyDescriptor(value, "query");
+        const limit = Object.getOwnPropertyDescriptor(value, "limit");
+        if (!query?.enumerable ||
+            !("value" in query) ||
+            !limit?.enumerable ||
+            !("value" in limit) ||
+            (api !== undefined && (!api.enumerable || !("value" in api))))
+            throw new Error();
+        const queryValue = query.value;
+        if (typeof queryValue !== "string" ||
+            queryValue.length > MAX_SEARCH_QUERY_BYTES ||
+            new TextEncoder().encode(queryValue).byteLength >
+                MAX_SEARCH_QUERY_BYTES ||
+            queryValue.length === 0 ||
+            !Number.isSafeInteger(limit.value) ||
+            limit.value < 1 ||
+            limit.value > limits.maxSearchResults)
+            throw new OpenApiMcpError("INPUT_INVALID", "Search input is invalid");
+        let apiValue = null;
+        if (api !== undefined && api.value !== undefined) {
+            searchApi(api.value);
+            apiValue = api.value;
+        }
+        return {
+            query: queryValue,
+            api: apiValue,
+            limit: limit.value,
+        };
+    }
+    catch (error) {
+        if (error instanceof OpenApiMcpError)
+            throw error;
+        throw new OpenApiMcpError("INPUT_INVALID", "Search input is invalid");
+    }
+}
+function searchApi(value) {
+    try {
+        if (typeof value !== "string")
+            throw new Error();
+        parseTypedRecordId(`operation:${value}:x`);
+    }
+    catch {
+        throw new OpenApiMcpError("INPUT_INVALID", "Search API is invalid");
+    }
+}
+function snapshotSqliteRuntimeLimits(options) {
+    let overrides;
+    try {
+        if (typeof options !== "object" ||
+            options === null ||
+            Array.isArray(options))
+            throw new Error();
+        const limits = Object.getOwnPropertyDescriptor(options, "limits");
+        if (limits !== undefined) {
+            if (!limits.enumerable || !("value" in limits))
+                throw new Error();
+            overrides = limits.value;
+        }
+    }
+    catch {
+        throw new RangeError("Runtime limits overrides must be an exact plain data object");
+    }
+    return resolveRuntimeLimits(overrides);
+}
+function exactly(rows, name) {
+    return (rows.length === 1 &&
+        typeof rows[0] === "object" &&
+        rows[0] !== null &&
+        rows[0].name === name &&
+        rows[0].type === "table");
+}
+function isExecutableArtifact(rows) {
+    return (rows.length > 0 &&
+        rows.length <= 2 &&
+        rows.every((row) => typeof row === "object" &&
+            row !== null &&
+            (row.format === 4 ||
+                row.format === 5) &&
+            row.contract === 1));
+}
+function bunSqlite() {
+    return process.getBuiltinModule?.("bun:sqlite");
+}
+function openReadOnlyDatabase(path) {
+    const module = bunSqlite();
+    if (module !== undefined)
+        return new module.Database(path, { readonly: true });
+    return new DatabaseSync(path, { readOnly: true });
+}
+function all(database, sql, values = []) {
+    const statement = database.prepare(sql);
+    try {
+        return statement.all(...values);
+    }
+    finally {
+        statement.finalize?.();
+    }
+}
+function first(database, sql, values) {
+    const statement = database.prepare(sql);
+    try {
+        return statement.get(...values);
+    }
+    finally {
+        statement.finalize?.();
+    }
+}
+function closeDatabase(database) {
+    database.close(true);
+}
+function bridge(database) {
+    return {
+        prepare(sql) {
+            let values = [];
+            return {
+                bind(...next) {
+                    values = next;
+                    return this;
+                },
+                async all() {
+                    return {
+                        success: true,
+                        results: all(database, sql, values),
+                    };
+                },
+                async first() {
+                    return first(database, sql, values) ?? null;
+                },
+            };
+        },
+    };
+}
+/** Read-only v4/v5 store with an explicit inventory-only v3 migration mode. */
+export class SqliteCatalogStore {
+    legacyInventoryOnly;
+    #database;
+    #v4;
+    #legacyIdentity;
+    #limits;
+    #path;
+    #payloadIdentity;
+    constructor(path, options = {}) {
+        this.#path = path;
+        this.#limits = snapshotSqliteRuntimeLimits(options);
+        let database;
+        try {
+            database = openReadOnlyDatabase(path);
+            const tables = all(database, SCHEMA_PROBE);
+            if (exactly(tables, "release_metadata")) {
+                const versions = all(database, V4_VERSION_PROBE);
+                if (!isExecutableArtifact(versions))
+                    throw unsupported("Artifact format unsupported");
+                this.legacyInventoryOnly = false;
+                this.#v4 = createD1CatalogStore(bridge(database), this.#limits);
+            }
+            else if (exactly(tables, "meta")) {
+                const versions = all(database, V3_VERSION_PROBE, ["format_version"]);
+                if (versions.length !== 1 ||
+                    typeof versions[0] !== "object" ||
+                    versions[0] === null ||
+                    versions[0].value !== "3")
+                    throw unsupported("Artifact format is unsupported");
+                this.#legacyIdentity = snapshotLegacyIdentity(options);
+                this.legacyInventoryOnly = true;
+            }
+            else
+                throw unsupported("Artifact format is unsupported");
+            this.#database = database;
+        }
+        catch (error) {
+            if (database !== undefined)
+                closeDatabase(database);
+            if (error instanceof OpenApiMcpError)
+                throw error;
+            throw unsupported("Artifact format is unsupported");
+        }
+    }
+    close() {
+        if (this.#database !== undefined)
+            closeDatabase(this.#database);
+        this.#database = undefined;
+    }
+    #v4Store() {
+        if (!this.#database)
+            throw unsupported("Catalog store is closed");
+        if (!this.#v4)
+            throw unsupported("v3 artifacts are inventory-only");
+        return this.#v4;
+    }
+    async getManifest(catalog, release) {
+        const envelope = await this.#v4Store().getManifest(catalog, release);
+        // The signed envelope's format controls completion, never unsigned SQL metadata.
+        if (parseJsonStrict(envelope.manifestJson, {
+            maxBytes: this.#limits.maxManifestBytes,
+            maxDepth: this.#limits.maxJsonDepth,
+            maxKeys: this.#limits.maxManifestRecords + 100,
+        }).format === 5) {
+            this.#payloadIdentity ??= releaseFileIdentity(this.#path);
+            verifyReleaseCompletion(this.#path, this.#payloadIdentity, envelope, this.#limits);
+        }
+        return envelope;
+    }
+    async searchCandidates(query) {
+        if (!this.legacyInventoryOnly)
+            return this.#v4Store().searchCandidates(query);
+        if (!this.#database)
+            throw unsupported("Catalog store is closed");
+        const legacyIdentity = this.#legacyIdentity;
+        if (!legacyIdentity)
+            throw unsupported("v3 inventory requires an explicit catalog identity");
+        const snapshot = snapshotLegacySearchQuery(query, this.#limits);
+        try {
+            const rows = all(this.#database, V3_SEARCH_SQL, [
+                legacyQualifiedIdBytes,
+                snapshot.query,
+                snapshot.api,
+                snapshot.api,
+                snapshot.limit,
+            ]);
+            if (rows.length > snapshot.limit)
+                throw new Error();
+            const seen = new Set();
+            return rows.map((row) => {
+                const qualified = typeof row === "object" && row !== null
+                    ? row.qualified_id
+                    : undefined;
+                if (typeof qualified !== "string")
+                    throw new Error();
+                if (snapshot.api !== null && !qualified.startsWith(`${snapshot.api}:`))
+                    throw new Error();
+                const parsed = parseTypedRecordId(`operation:${qualified}`);
+                if (!parsed.startsWith("operation:") || seen.has(parsed))
+                    throw new Error();
+                seen.add(parsed);
+                return {
+                    catalogId: legacyIdentity.catalogId,
+                    releaseId: legacyIdentity.releaseId,
+                    operationId: parsed,
+                };
+            });
+        }
+        catch (error) {
+            if (error instanceof OpenApiMcpError)
+                throw error;
+            throw new OpenApiMcpError("INPUT_INVALID", "Search expression is invalid");
+        }
+    }
+    async getOperation(catalog, release, id) {
+        return await this.#v4Store().getOperation(catalog, release, id);
+    }
+    async getSchemas(catalog, release, ids) {
+        return await this.#v4Store().getSchemas(catalog, release, ids);
+    }
+}

package/dist/sqlite/destination-guard.d.ts

@@ -0,0 +1,24 @@
+import type { LookupFunction } from "node:net";
+export interface DestinationGuardOptions {
+    readonly allowedOrigins: readonly string[];
+    /** Trusted resolver only; every returned address still passes public policy. */
+    readonly lookup?: (hostname: string, options: {
+        all: true;
+        verbatim: true;
+    }) => Promise<readonly {
+        address: string;
+        family: number;
+    }[]>;
+    readonly now?: () => number;
+    readonly ttlMs?: number;
+}
+export interface ApprovedDestination {
+    readonly origin: string;
+    readonly expiresAt: number;
+    readonly lookup: LookupFunction;
+}
+export declare class NodeDestinationGuard {
+    #private;
+    constructor(options: DestinationGuardOptions);
+    authorize(value: URL, signal?: AbortSignal): Promise<ApprovedDestination>;
+}

package/dist/sqlite/destination-guard.js

@@ -0,0 +1,140 @@
+import { lookup as systemLookup } from "node:dns/promises";
+import { BlockList, isIP } from "node:net";
+import { OpenApiMcpError } from "../runtime/errors.js";
+const deniedV4 = new BlockList();
+for (const [network, prefix] of [
+    ["0.0.0.0", 8],
+    ["10.0.0.0", 8],
+    ["100.64.0.0", 10],
+    ["127.0.0.0", 8],
+    ["169.254.0.0", 16],
+    ["172.16.0.0", 12],
+    ["192.0.0.0", 24],
+    ["192.0.2.0", 24],
+    ["192.88.99.0", 24],
+    ["192.168.0.0", 16],
+    ["198.18.0.0", 15],
+    ["198.51.100.0", 24],
+    ["203.0.113.0", 24],
+    ["224.0.0.0", 4],
+    ["240.0.0.0", 4],
+])
+    deniedV4.addSubnet(network, prefix, "ipv4");
+const publicV6 = new BlockList();
+publicV6.addSubnet("2000::", 3, "ipv6");
+const deniedV6 = new BlockList();
+for (const [network, prefix] of [
+    ["2001::", 23],
+    ["2001:db8::", 32],
+    ["2002::", 16],
+    ["3fff::", 20],
+])
+    deniedV6.addSubnet(network, prefix, "ipv6");
+function denied() {
+    return new OpenApiMcpError("DESTINATION_DENIED", "Destination is not permitted");
+}
+/** Conservative IANA special-purpose policy, including all mapped/translation IPv6. */
+function isPublic(address, family) {
+    if (isIP(address) !== family || address.includes("%"))
+        return false;
+    if (family === 4)
+        return !deniedV4.check(address, "ipv4");
+    return (family === 6 &&
+        publicV6.check(address, "ipv6") &&
+        !deniedV6.check(address, "ipv6"));
+}
+export class NodeDestinationGuard {
+    #origins;
+    #resolve;
+    #now;
+    #ttl;
+    constructor(options) {
+        this.#origins = new Set(options.allowedOrigins.map((value) => {
+            const url = new URL(value);
+            if (url.protocol !== "https:" ||
+                url.username ||
+                url.password ||
+                url.search ||
+                url.hash ||
+                url.pathname !== "/")
+                throw denied();
+            return url.origin;
+        }));
+        this.#resolve = options.lookup ?? systemLookup;
+        this.#now = options.now ?? Date.now;
+        this.#ttl = options.ttlMs ?? 30_000;
+        if (!Number.isSafeInteger(this.#ttl) || this.#ttl < 1 || this.#ttl > 30_000)
+            throw new RangeError("Destination TTL must only lower 30000ms");
+    }
+    async authorize(value, signal) {
+        const url = new URL(value.href);
+        if (url.protocol !== "https:" ||
+            url.username ||
+            url.password ||
+            !this.#origins.has(url.origin))
+            throw denied();
+        const hostname = url.hostname.replace(/^\[|\]$/g, "");
+        const issuedAt = this.#now();
+        if (!Number.isFinite(issuedAt))
+            throw denied();
+        const expiresAt = issuedAt + this.#ttl;
+        let answers;
+        let timeout;
+        let abort;
+        try {
+            if (signal?.aborted)
+                throw denied();
+            const family = isIP(hostname);
+            answers = family
+                ? [{ address: hostname, family }]
+                : await Promise.race([
+                    this.#resolve(hostname, { all: true, verbatim: true }),
+                    new Promise((_, reject) => {
+                        timeout = setTimeout(() => reject(denied()), this.#ttl);
+                    }),
+                    new Promise((_, reject) => {
+                        abort = () => reject(denied());
+                        signal?.addEventListener("abort", abort, { once: true });
+                    }),
+                ]);
+        }
+        catch {
+            throw denied();
+        }
+        finally {
+            clearTimeout(timeout);
+            if (abort)
+                signal?.removeEventListener("abort", abort);
+        }
+        if (!Array.isArray(answers) ||
+            answers.length === 0 ||
+            answers.length > 64 ||
+            this.#now() >= expiresAt)
+            throw denied();
+        const pinned = answers.map(({ address, family }) => {
+            if (!isPublic(address, family))
+                throw denied();
+            return Object.freeze({ address, family });
+        });
+        const lookup = (requested, options, callback) => {
+            const time = this.#now();
+            if (requested !== hostname ||
+                !Number.isFinite(time) ||
+                time >= expiresAt) {
+                callback(denied(), "", 0);
+                return;
+            }
+            const eligible = pinned.filter((answer) => !options.family || answer.family === Number(options.family));
+            const first = eligible[0];
+            if (!first) {
+                callback(denied(), "", 0);
+                return;
+            }
+            if (options.all)
+                callback(null, eligible.map((answer) => ({ ...answer })));
+            else
+                callback(null, first.address, first.family);
+        };
+        return Object.freeze({ origin: url.origin, expiresAt, lookup });
+    }
+}

package/dist/sqlite/generation-store.d.ts

@@ -0,0 +1,12 @@
+import type { CatalogId, GenerationState, GenerationStore, GenerationTransition } from "../runtime/types.ts";
+/** Stable bounded failure when another process retains the generation mutex. */
+export declare class GenerationStoreContentionError extends Error {
+    constructor();
+}
+/** Node-only durable, user-private compare-and-swap generation storage. */
+export declare class FileGenerationStore implements GenerationStore {
+    #private;
+    constructor(path: string);
+    get(catalogId: CatalogId, issuer: string): Promise<GenerationState | null>;
+    accept(catalogId: CatalogId, issuer: string, transition: GenerationTransition): Promise<GenerationState | null>;
+}