@knitli/openapi-mcp 0.0.0

package/dist/release/load-v4.d.ts

@@ -0,0 +1,29 @@
+import { type FileHandle } from "node:fs/promises";
+import type { OpenApiDoc } from "../load.ts";
+import { type PathIdentity } from "./publish.ts";
+export interface CompilerLimits {
+    readonly maxSourceBytes: number;
+    readonly maxReferencedDocuments: number;
+    readonly maxPaths: number;
+    readonly maxOperations: number;
+    readonly maxSchemas: number;
+    readonly maxParametersPerOperation: number;
+    readonly maxPropertiesPerSchema: number;
+    readonly maxStringBytes: number;
+    readonly maxRefLength: number;
+    readonly maxJsonDepth: number;
+    readonly maxRecordBytes: number;
+    readonly maxYamlAliasExpansions: number;
+    readonly maxDocumentNodes: number;
+    readonly maxDocumentKeys: number;
+}
+export declare const DEFAULT_COMPILER_LIMITS: CompilerLimits;
+/** Package-internal descriptor reader for callers that already pinned a path identity. */
+export declare function requireOpenedFileV4(handle: FileHandle, expected: PathIdentity, label: string): Promise<bigint>;
+/** Package-internal bounded read that consumes only an already-verified descriptor. */
+export declare function readOpenedFileBoundedV4(handle: FileHandle, expected: PathIdentity, maxBytes: number, label: string): Promise<Uint8Array>;
+export declare function readFileBoundedV4(path: string, maxBytes: number, label: string): Promise<Uint8Array>;
+export declare function parseDocumentBytesV4(bytes: Uint8Array, mediaType: "json" | "yaml", limitOverrides?: Partial<CompilerLimits>): unknown;
+export declare function parseSpecBytesV4(bytes: Uint8Array, mediaType: "json" | "yaml", limitOverrides?: Partial<CompilerLimits>): OpenApiDoc;
+export declare function loadSpecV4(path: string, limitOverrides?: Partial<CompilerLimits>): Promise<OpenApiDoc>;
+export declare function redactSourcePath(_path: string, sourceLabel?: string): string;

package/dist/release/load-v4.js

@@ -0,0 +1,297 @@
+import { constants } from "node:fs";
+import { lstat, open } from "node:fs/promises";
+import { extname } from "node:path";
+import { isAlias, isMap, isScalar, isSeq, parseDocument } from "yaml";
+import { parseJsonStrict } from "../runtime/strict-json.js";
+import { pathIdentityFromStats, samePathIdentity, } from "./publish.js";
+export const DEFAULT_COMPILER_LIMITS = Object.freeze({
+    maxSourceBytes: 128 * 1024 * 1024,
+    maxReferencedDocuments: 1_024,
+    maxPaths: 100_000,
+    maxOperations: 100_000,
+    maxSchemas: 50_000,
+    maxParametersPerOperation: 256,
+    maxPropertiesPerSchema: 10_000,
+    maxStringBytes: 1 * 1024 * 1024,
+    maxRefLength: 2_048,
+    maxJsonDepth: 64,
+    maxRecordBytes: 1 * 1024 * 1024,
+    maxYamlAliasExpansions: 100,
+    maxDocumentNodes: 1_000_000,
+    maxDocumentKeys: 250_000,
+});
+const forbiddenKeys = new Set(["__proto__", "prototype", "constructor"]);
+/** Package-internal descriptor reader for callers that already pinned a path identity. */
+export async function requireOpenedFileV4(handle, expected, label) {
+    const metadata = await handle.stat({ bigint: true });
+    if (!metadata.isFile() ||
+        metadata.isSymbolicLink() ||
+        metadata.nlink !== 1n ||
+        !samePathIdentity(pathIdentityFromStats(metadata), expected))
+        throw new Error(`${label} descriptor identity is invalid`);
+    return metadata.size;
+}
+/** Package-internal bounded read that consumes only an already-verified descriptor. */
+export async function readOpenedFileBoundedV4(handle, expected, maxBytes, label) {
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 0)
+        throw new Error(`${label} byte limit invalid`);
+    const beforeSize = await requireOpenedFileV4(handle, expected, label);
+    if (beforeSize > BigInt(maxBytes))
+        throw new Error(`${label} exceeds byte limit`);
+    const expectedBytes = Number(beforeSize);
+    const bytes = new Uint8Array(expectedBytes);
+    let offset = 0;
+    while (offset < expectedBytes) {
+        const { bytesRead } = await handle.read(bytes, offset, Math.min(64 * 1024, expectedBytes - offset), null);
+        if (bytesRead === 0)
+            throw new Error(`${label} size changed while reading`);
+        offset += bytesRead;
+    }
+    const growthProbe = new Uint8Array(1);
+    if ((await handle.read(growthProbe, 0, 1, null)).bytesRead !== 0)
+        throw new Error(`${label} size changed while reading`);
+    const afterSize = await requireOpenedFileV4(handle, expected, label);
+    if (afterSize !== beforeSize)
+        throw new Error(`${label} size changed while reading`);
+    return bytes;
+}
+export async function readFileBoundedV4(path, maxBytes, label) {
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 0)
+        throw new Error(`${label} byte limit is invalid`);
+    if (typeof constants.O_NOFOLLOW !== "number" || constants.O_NOFOLLOW === 0)
+        throw new Error(`${label} requires O_NOFOLLOW support`);
+    const expected = await lstat(path, { bigint: true });
+    if (!expected.isFile() || expected.isSymbolicLink() || expected.nlink !== 1n)
+        throw new Error(`${label} is unsafe or not a single-link regular file`);
+    if (expected.size > BigInt(maxBytes))
+        throw new Error(`${label} exceeds byte limit`);
+    const expectedIdentity = pathIdentityFromStats(expected);
+    let handle;
+    try {
+        handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    }
+    catch (error) {
+        if (error.code === "ELOOP")
+            throw new Error(`${label} is unsafe or symbolic`);
+        throw error;
+    }
+    try {
+        const before = await handle.stat({ bigint: true });
+        if (!before.isFile() ||
+            before.nlink !== 1n ||
+            !samePathIdentity(pathIdentityFromStats(before), expectedIdentity))
+            throw new Error(`${label} is unsafe or not a single-link file`);
+        if (before.size > BigInt(maxBytes))
+            throw new Error(`${label} exceeds byte limit`);
+        const chunks = [];
+        let total = 0;
+        const buffer = Buffer.allocUnsafe(Math.min(64 * 1024, maxBytes + 1) || 1);
+        while (true) {
+            const { bytesRead } = await handle.read(buffer, 0, buffer.byteLength, null);
+            if (bytesRead === 0)
+                break;
+            total += bytesRead;
+            if (total > maxBytes)
+                throw new Error(`${label} exceeds byte limit`);
+            chunks.push(Uint8Array.from(buffer.subarray(0, bytesRead)));
+        }
+        const after = await handle.stat({ bigint: true });
+        if (!samePathIdentity(pathIdentityFromStats(after), pathIdentityFromStats(before)))
+            throw new Error(`${label} identity changed while reading`);
+        const current = await lstat(path, { bigint: true }).catch(() => null);
+        if (!current ||
+            current.isSymbolicLink() ||
+            !samePathIdentity(pathIdentityFromStats(current), pathIdentityFromStats(before)))
+            throw new Error(`${label} pathname identity changed while reading`);
+        const bytes = new Uint8Array(total);
+        let offset = 0;
+        for (const chunk of chunks) {
+            bytes.set(chunk, offset);
+            offset += chunk.byteLength;
+        }
+        return bytes;
+    }
+    finally {
+        await handle.close();
+    }
+}
+function requirePositiveLimits(limits) {
+    for (const [name, value] of Object.entries(limits)) {
+        if (!Number.isSafeInteger(value) || value < 0)
+            throw new Error(`${name} is invalid`);
+    }
+}
+function detachAndValidate(value, limits) {
+    const active = new WeakSet();
+    let nodes = 0;
+    let keys = 0;
+    const copy = (input, depth) => {
+        nodes += 1;
+        if (nodes > limits.maxDocumentNodes)
+            throw new Error("document exceeds node limit");
+        if (depth > limits.maxJsonDepth)
+            throw new Error("document exceeds JSON depth limit");
+        if (typeof input === "string") {
+            if (Buffer.byteLength(input) > limits.maxStringBytes)
+                throw new Error("document string exceeds byte limit");
+            return input;
+        }
+        if (input === null ||
+            typeof input === "boolean" ||
+            typeof input === "number")
+            return input;
+        if (Array.isArray(input)) {
+            if (active.has(input))
+                throw new Error("document contains an alias cycle");
+            active.add(input);
+            const result = input.map((entry) => copy(entry, depth + 1));
+            active.delete(input);
+            return result;
+        }
+        if (typeof input !== "object")
+            throw new Error("document contains a non-JSON value");
+        if (active.has(input))
+            throw new Error("document contains an alias cycle");
+        active.add(input);
+        const result = Object.create(null);
+        for (const key of Object.keys(input)) {
+            keys += 1;
+            if (keys > limits.maxDocumentKeys)
+                throw new Error("document exceeds key limit");
+            if (forbiddenKeys.has(key))
+                throw new Error(`document contains forbidden key ${key}`);
+            if (Buffer.byteLength(key) > limits.maxStringBytes)
+                throw new Error("document key exceeds string byte limit");
+            const descriptor = Object.getOwnPropertyDescriptor(input, key);
+            if (descriptor === undefined || !("value" in descriptor))
+                throw new Error("document contains an accessor");
+            result[key] = copy(descriptor.value, depth + 1);
+        }
+        active.delete(input);
+        return result;
+    };
+    return copy(value, 0);
+}
+function validateYamlAst(root, limits) {
+    const stack = [
+        { node: root, depth: 0 },
+    ];
+    let nodes = 0;
+    let keys = 0;
+    let aliases = 0;
+    while (stack.length > 0) {
+        const { node, depth } = stack.pop();
+        nodes += 1;
+        if (nodes > limits.maxDocumentNodes)
+            throw new Error("YAML document exceeds node limit");
+        if (depth > limits.maxJsonDepth)
+            throw new Error("YAML document exceeds depth limit");
+        if (isAlias(node)) {
+            aliases += 1;
+            if (aliases > limits.maxYamlAliasExpansions)
+                throw new Error("YAML alias expansion limit exceeded");
+            continue;
+        }
+        if (isMap(node)) {
+            for (const pair of node.items) {
+                keys += 1;
+                if (keys > limits.maxDocumentKeys)
+                    throw new Error("YAML document exceeds key limit");
+                if (!isScalar(pair.key) || typeof pair.key.value !== "string")
+                    throw new Error("YAML mapping keys must be strings");
+                if (forbiddenKeys.has(pair.key.value))
+                    throw new Error(`document contains forbidden key ${pair.key.value}`);
+                if (Buffer.byteLength(pair.key.value) > limits.maxStringBytes)
+                    throw new Error("YAML key exceeds string byte limit");
+                if (pair.value !== null)
+                    stack.push({ node: pair.value, depth: depth + 1 });
+            }
+            continue;
+        }
+        if (isSeq(node)) {
+            for (const child of node.items)
+                if (child !== null)
+                    stack.push({ node: child, depth: depth + 1 });
+            continue;
+        }
+        if (isScalar(node) &&
+            typeof node.value === "string" &&
+            Buffer.byteLength(node.value) > limits.maxStringBytes) {
+            throw new Error("YAML string exceeds byte limit");
+        }
+    }
+}
+export function parseDocumentBytesV4(bytes, mediaType, limitOverrides = {}) {
+    const limits = { ...DEFAULT_COMPILER_LIMITS, ...limitOverrides };
+    requirePositiveLimits(limits);
+    if (bytes.byteLength > limits.maxSourceBytes)
+        throw new Error("aggregate source bytes exceed limit");
+    const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    let parsed;
+    if (mediaType === "json") {
+        parsed = parseJsonStrict(text, {
+            maxBytes: limits.maxSourceBytes,
+            maxDepth: limits.maxJsonDepth,
+            maxKeys: limits.maxDocumentKeys,
+        });
+    }
+    else {
+        const document = parseDocument(text, {
+            version: "1.2",
+            schema: "core",
+            strict: true,
+            uniqueKeys: true,
+            stringKeys: true,
+            merge: false,
+        });
+        if (document.errors.length > 0 ||
+            document.warnings.length > 0 ||
+            document.contents === null) {
+            const issue = document.errors[0] ?? document.warnings[0];
+            throw new Error(`invalid YAML document: ${issue?.message ?? "empty document"}`);
+        }
+        validateYamlAst(document.contents, limits);
+        parsed = document.toJS({
+            maxAliasCount: limits.maxYamlAliasExpansions,
+        });
+    }
+    return detachAndValidate(parsed, limits);
+}
+export function parseSpecBytesV4(bytes, mediaType, limitOverrides = {}) {
+    const detached = parseDocumentBytesV4(bytes, mediaType, limitOverrides);
+    if (!detached ||
+        typeof detached !== "object" ||
+        typeof detached.openapi !== "string" ||
+        !/^3\.(?:0|1)\.[0-9]+$/.test(detached.openapi) ||
+        typeof detached.paths !== "object" ||
+        detached.paths === null ||
+        Array.isArray(detached.paths)) {
+        throw new Error("unsupported OpenAPI version or missing paths object");
+    }
+    return detached;
+}
+export async function loadSpecV4(path, limitOverrides = {}) {
+    const limits = { ...DEFAULT_COMPILER_LIMITS, ...limitOverrides };
+    requirePositiveLimits(limits);
+    const extension = extname(path).toLowerCase();
+    const mediaType = extension === ".json"
+        ? "json"
+        : extension === ".yaml" || extension === ".yml"
+            ? "yaml"
+            : null;
+    if (mediaType === null)
+        throw new Error("unsupported OpenAPI media type or file extension");
+    let bytes;
+    try {
+        bytes = await readFileBoundedV4(path, limits.maxSourceBytes, "source document");
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.includes("exceeds byte limit"))
+            throw new Error("source bytes exceed limit");
+        throw new Error("source document could not be read");
+    }
+    return parseSpecBytesV4(bytes, mediaType, limits);
+}
+export function redactSourcePath(_path, sourceLabel = "source document") {
+    return sourceLabel;
+}

package/dist/release/manifest-builder.d.ts

@@ -0,0 +1,19 @@
+import type { CatalogId, ManifestEnvelope, ReleaseId, ReleaseManifestV4, Sha256, TypedRecordId } from "../runtime/types.ts";
+export interface ManifestBuilderInput {
+    catalogId: CatalogId;
+    releaseId: ReleaseId;
+    generation: number;
+    issuer: string;
+    keyId: string;
+    policyId: string;
+    allowedOrigins: readonly string[];
+    compiledAt: string;
+    compilerVersion: string;
+    sourceUri: string;
+    sourceRevision: string;
+    sourceContentSha256: Sha256;
+    referenceGraphDigest: Sha256;
+    records: Readonly<Record<TypedRecordId, Sha256>>;
+}
+export declare function buildReleaseManifestV4(input: ManifestBuilderInput): ReleaseManifestV4;
+export declare function buildManifestEnvelopeV4(manifest: ReleaseManifestV4, privateKeyPem: string): ManifestEnvelope;

package/dist/release/manifest-builder.js

@@ -0,0 +1,28 @@
+import { ARTIFACT_FORMAT_VERSION, RUNTIME_CONTRACT_VERSION, } from "../runtime/versions.js";
+import { signReleaseManifestV4 } from "../sign.js";
+export function buildReleaseManifestV4(input) {
+    return {
+        format: ARTIFACT_FORMAT_VERSION,
+        contract: RUNTIME_CONTRACT_VERSION,
+        catalogId: input.catalogId,
+        releaseId: input.releaseId,
+        generation: input.generation,
+        issuer: input.issuer,
+        keyId: input.keyId,
+        policyId: input.policyId,
+        allowedOrigins: [...input.allowedOrigins].sort(),
+        compiledAt: input.compiledAt,
+        compilerVersion: input.compilerVersion,
+        source: {
+            uri: input.sourceUri,
+            revision: input.sourceRevision,
+            contentSha256: input.sourceContentSha256,
+            referenceGraphDigest: input.referenceGraphDigest,
+        },
+        records: Object.fromEntries(Object.entries(input.records).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)),
+    };
+}
+export function buildManifestEnvelopeV4(manifest, privateKeyPem) {
+    const signed = signReleaseManifestV4(manifest, manifest.keyId, privateKeyPem);
+    return { manifestJson: signed.manifestJson, signature: signed.signature };
+}

package/dist/release/publish.d.ts

@@ -0,0 +1,45 @@
+import type { ManifestEnvelope, ReleaseManifestV4 } from "../runtime/types.ts";
+export interface CompiledReleasePaths {
+    readonly directory: string;
+    readonly sqlite: string;
+    readonly signature: string;
+    readonly manifest: string;
+}
+export interface CompiledRelease {
+    readonly manifest: ReleaseManifestV4;
+    readonly envelope: ManifestEnvelope;
+    readonly paths: CompiledReleasePaths;
+}
+type StageFileKind = "sqlite" | "signature" | "manifest";
+type StageFileRecord<T> = Readonly<Record<StageFileKind, T>>;
+export interface PathIdentity {
+    readonly dev: bigint;
+    readonly ino: bigint;
+    readonly birthtimeNs: bigint;
+}
+export interface CompiledReleaseOwnership {
+    readonly directory: PathIdentity;
+    readonly sqlite: PathIdentity;
+    readonly signature: PathIdentity;
+    readonly manifest: PathIdentity;
+}
+/** Package-private construction gate; intentionally absent from the compiler barrel. */
+export declare function registerCompiledRelease(compiled: CompiledRelease, outDir: string, digests: StageFileRecord<string>, sizes: StageFileRecord<number>, ownership: CompiledReleaseOwnership): CompiledRelease;
+export declare function pathIdentityFromStats(stat: {
+    readonly dev: bigint;
+    readonly ino: bigint;
+    readonly birthtimeNs: bigint;
+}): PathIdentity;
+export declare function samePathIdentity(left: PathIdentity, right: PathIdentity): boolean;
+export declare function capturePathIdentity(path: string, kind: "directory" | "file"): Promise<PathIdentity>;
+export declare function cleanupOwnedStage(paths: CompiledReleasePaths, ownership: Partial<CompiledReleaseOwnership>): Promise<void>;
+export type PublishCheckpoint = "before-sqlite-validation-open" | "before-signature-validation-open" | "before-manifest-validation-open" | "before-sqlite-validation-read" | "before-signature-validation-read" | "before-manifest-validation-read" | "payload-published" | "signature-published" | "manifest-published";
+type Checkpoint = (checkpoint: PublishCheckpoint) => void | Promise<void>;
+export declare function publishReleaseWithCheckpoint(compiled: CompiledRelease, target: {
+    readonly directory: string;
+}, checkpoint?: Checkpoint): Promise<void>;
+export declare function publishRelease(compiled: CompiledRelease, target: {
+    readonly directory: string;
+}): Promise<void>;
+export declare function discardCompiledRelease(compiled: CompiledRelease): Promise<void>;
+export {};