@knitli/openapi-mcp 0.0.0

package/dist/release/publish.js

@@ -0,0 +1,346 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { link, lstat, mkdir, open, realpath, rmdir, unlink, } from "node:fs/promises";
+import { basename, dirname, join, relative, sep } from "node:path";
+const compiledStates = new WeakMap();
+/** Package-private construction gate; intentionally absent from the compiler barrel. */
+export function registerCompiledRelease(compiled, outDir, digests, sizes, ownership) {
+    compiledStates.set(compiled, {
+        outDir,
+        paths: { ...compiled.paths },
+        consumed: false,
+        digests: { ...digests },
+        sizes: { ...sizes },
+        ownership: {
+            directory: { ...ownership.directory },
+            sqlite: { ...ownership.sqlite },
+            signature: { ...ownership.signature },
+            manifest: { ...ownership.manifest },
+        },
+    });
+    return compiled;
+}
+function stateFor(compiled) {
+    const state = compiledStates.get(compiled);
+    if (!state || state.consumed)
+        throw new Error("compiled release is invalid or already consumed");
+    return state;
+}
+export function pathIdentityFromStats(stat) {
+    if (stat.birthtimeNs <= 0n)
+        throw new Error("path identity requires a nonzero birthtimeNs");
+    return {
+        dev: stat.dev,
+        ino: stat.ino,
+        birthtimeNs: stat.birthtimeNs,
+    };
+}
+export function samePathIdentity(left, right) {
+    return (left.dev === right.dev &&
+        left.ino === right.ino &&
+        left.birthtimeNs === right.birthtimeNs);
+}
+export async function capturePathIdentity(path, kind) {
+    const metadata = await lstat(path, { bigint: true });
+    const validKind = kind === "directory" ? metadata.isDirectory() : metadata.isFile();
+    if (!validKind || metadata.isSymbolicLink())
+        throw new Error(`compiler-created ${kind} is unsafe`);
+    if (kind === "file" && metadata.nlink !== 1n)
+        throw new Error("compiler-created file must have one link");
+    return pathIdentityFromStats(metadata);
+}
+async function ownedMetadata(path, identity) {
+    const metadata = await lstat(path, { bigint: true }).catch((error) => {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    });
+    return metadata && samePathIdentity(pathIdentityFromStats(metadata), identity)
+        ? metadata
+        : null;
+}
+async function requireOwnedFile(path, identity, label, requireSingleLink = true) {
+    const metadata = await ownedMetadata(path, identity);
+    if (!metadata?.isFile() ||
+        metadata.isSymbolicLink() ||
+        (requireSingleLink && metadata.nlink !== 1n))
+        throw new Error(`${label} identity or ownership was lost`);
+}
+async function requireOwnedDirectory(path, identity, label) {
+    const metadata = await ownedMetadata(path, identity);
+    if (!metadata?.isDirectory() || metadata.isSymbolicLink())
+        throw new Error(`${label} identity or ownership was lost`);
+}
+async function removeOwnedFile(path, identity) {
+    const metadata = await ownedMetadata(path, identity);
+    if (!metadata?.isFile() || metadata.isSymbolicLink())
+        return false;
+    await unlink(path);
+    return true;
+}
+export async function cleanupOwnedStage(paths, ownership) {
+    for (const kind of ["manifest", "signature", "sqlite"]) {
+        const identity = ownership[kind];
+        if (identity)
+            await removeOwnedFile(paths[kind], identity).catch(() => false);
+    }
+    if (!ownership.directory)
+        return;
+    const directory = await ownedMetadata(paths.directory, ownership.directory);
+    if (!directory?.isDirectory() || directory.isSymbolicLink())
+        return;
+    await rmdir(paths.directory).catch(() => { });
+}
+async function hashOwnedStageFile(path, identity, expectedSize, beforeOpen, beforeRead) {
+    if (!Number.isSafeInteger(expectedSize) || expectedSize < 0)
+        throw new Error("compiled release staged file size is invalid");
+    if (typeof constants.O_NOFOLLOW !== "number" || constants.O_NOFOLLOW === 0)
+        throw new Error("compiled release validation requires O_NOFOLLOW support");
+    await requireOwnedFile(path, identity, "compiled release staged file");
+    await beforeOpen();
+    let handle;
+    try {
+        handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    }
+    catch {
+        throw new Error("compiled release staged file could not be opened safely");
+    }
+    try {
+        const before = await handle.stat({ bigint: true });
+        if (!before.isFile() ||
+            before.nlink !== 1n ||
+            !samePathIdentity(pathIdentityFromStats(before), identity) ||
+            before.size !== BigInt(expectedSize))
+            throw new Error("compiled release staged content was modified or identity was lost");
+        await requireOwnedFile(path, identity, "compiled release staged file");
+        await beforeRead();
+        const digest = createHash("sha256");
+        const buffer = Buffer.allocUnsafe(Math.min(64 * 1024, expectedSize) || 1);
+        let total = 0;
+        while (total < expectedSize) {
+            const { bytesRead } = await handle.read(buffer, 0, Math.min(buffer.byteLength, expectedSize - total), null);
+            if (bytesRead === 0)
+                throw new Error("compiled release staged content was modified: early EOF");
+            digest.update(buffer.subarray(0, bytesRead));
+            total += bytesRead;
+        }
+        const growthProbe = new Uint8Array(1);
+        const { bytesRead: extraBytes } = await handle.read(growthProbe, 0, 1, null);
+        if (extraBytes !== 0)
+            throw new Error("compiled release staged content was modified: exceeds recorded size");
+        const after = await handle.stat({ bigint: true });
+        if (!after.isFile() ||
+            after.nlink !== 1n ||
+            !samePathIdentity(pathIdentityFromStats(after), identity) ||
+            after.size !== BigInt(expectedSize))
+            throw new Error("compiled release staged content was modified or identity was lost");
+        await requireOwnedFile(path, identity, "compiled release staged file");
+        return digest.digest("hex");
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function validateStage(compiled, state, checkpoint) {
+    const root = await realpath(state.outDir);
+    if (compiled.paths.directory !== state.paths.directory)
+        throw new Error("compiled release staged directory was substituted");
+    await requireOwnedDirectory(state.paths.directory, state.ownership.directory, "compiled release stage");
+    const directory = await realpath(state.paths.directory);
+    if (dirname(directory) !== root || relative(root, directory).includes(sep))
+        throw new Error("compiled release stage is outside its output directory");
+    for (const kind of ["sqlite", "signature", "manifest"]) {
+        const path = state.paths[kind];
+        if (compiled.paths[kind] !== path || dirname(path) !== directory)
+            throw new Error("compiled release staged path was substituted");
+        await requireOwnedFile(path, state.ownership[kind], "compiled release staged file");
+        const digest = await hashOwnedStageFile(path, state.ownership[kind], state.sizes[kind], () => checkpoint(`before-${kind}-validation-open`), () => checkpoint(`before-${kind}-validation-read`));
+        await requireOwnedFile(path, state.ownership[kind], "compiled release staged file");
+        if (digest !== state.digests[kind])
+            throw new Error("compiled release staged content was modified");
+    }
+    if (basename(state.paths.sqlite) !== `${compiled.manifest.releaseId}.sqlite` ||
+        basename(state.paths.signature) !==
+            `${compiled.manifest.releaseId}.manifest.sig` ||
+        basename(state.paths.manifest) !==
+            `${compiled.manifest.releaseId}.manifest.json`)
+        throw new Error("compiled release staged names disagree with its release ID");
+}
+async function syncFile(path, identity) {
+    const handle = await open(path, "r");
+    try {
+        const metadata = await handle.stat({ bigint: true });
+        if (!metadata.isFile() ||
+            !samePathIdentity(pathIdentityFromStats(metadata), identity))
+            throw new Error("compiled release staged file identity was lost");
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    await requireOwnedFile(path, identity, "compiled release staged file");
+}
+async function syncOwnedDirectory(path, identity) {
+    await requireOwnedDirectory(path, identity, "release target directory");
+    const handle = await open(path, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+    try {
+        const metadata = await handle.stat({ bigint: true });
+        if (!metadata.isDirectory() ||
+            !samePathIdentity(pathIdentityFromStats(metadata), identity))
+            throw new Error("release target directory identity or ownership was lost");
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    await requireOwnedDirectory(path, identity, "release target directory");
+}
+async function requirePromotedTargets(targets) {
+    for (const [path, identity] of targets)
+        await requireOwnedFile(path, identity, "published target");
+}
+async function exists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+async function requireLock(path, identity) {
+    const metadata = await ownedMetadata(path, identity);
+    if (!metadata?.isFile() ||
+        metadata.isSymbolicLink() ||
+        metadata.nlink !== 1n ||
+        (metadata.mode & 511n) !== 384n)
+        throw new Error("release publication lock identity or ownership was lost");
+}
+export async function publishReleaseWithCheckpoint(compiled, target, checkpoint = () => { }) {
+    const state = stateFor(compiled);
+    state.consumed = true;
+    const createdTargets = new Map();
+    let lockHandle;
+    let lockIdentity;
+    let lockPath;
+    let targetDirectory;
+    let targetDirectoryIdentity;
+    try {
+        await validateStage(compiled, state, checkpoint);
+        await mkdir(target.directory, { recursive: false }).catch((error) => {
+            if (error.code !== "EEXIST")
+                throw error;
+        });
+        targetDirectory = await realpath(target.directory);
+        targetDirectoryIdentity = await capturePathIdentity(targetDirectory, "directory");
+        await requireOwnedDirectory(targetDirectory, targetDirectoryIdentity, "release target directory");
+        lockPath = join(targetDirectory, `.${compiled.manifest.releaseId}.publish.lock`);
+        if (typeof constants.O_NOFOLLOW !== "number" || constants.O_NOFOLLOW === 0)
+            throw new Error("release publication requires O_NOFOLLOW support");
+        const flags = constants.O_CREAT |
+            constants.O_EXCL |
+            constants.O_WRONLY |
+            constants.O_NOFOLLOW;
+        lockHandle = await open(lockPath, flags, 0o600).catch((error) => {
+            if (error.code === "EEXIST")
+                throw new Error("release publication lock already exists; publication is in progress or requires operator cleanup");
+            throw error;
+        });
+        await requireOwnedDirectory(targetDirectory, targetDirectoryIdentity, "release target directory");
+        const lockStat = await lockHandle.stat({ bigint: true });
+        if (!lockStat.isFile() ||
+            lockStat.nlink !== 1n ||
+            (lockStat.mode & 511n) !== 384n)
+            throw new Error("release publication lock is unsafe");
+        lockIdentity = pathIdentityFromStats(lockStat);
+        await requireLock(lockPath, lockIdentity);
+        const targets = [
+            join(targetDirectory, `${compiled.manifest.releaseId}.sqlite`),
+            join(targetDirectory, `${compiled.manifest.releaseId}.manifest.sig`),
+            join(targetDirectory, `${compiled.manifest.releaseId}.manifest.json`),
+        ];
+        if ((await Promise.all(targets.map(exists))).some(Boolean))
+            throw new Error("release target already exists");
+        const sources = [
+            state.paths.sqlite,
+            state.paths.signature,
+            state.paths.manifest,
+        ];
+        const identities = [
+            state.ownership.sqlite,
+            state.ownership.signature,
+            state.ownership.manifest,
+        ];
+        const checkpoints = [
+            "payload-published",
+            "signature-published",
+            "manifest-published",
+        ];
+        for (let index = 0; index < sources.length; index += 1) {
+            const source = sources[index];
+            const destination = targets[index];
+            const identity = identities[index];
+            await requireLock(lockPath, lockIdentity);
+            await requireOwnedDirectory(targetDirectory, targetDirectoryIdentity, "release target directory");
+            await syncFile(source, identity);
+            await requirePromotedTargets(createdTargets);
+            try {
+                await link(source, destination);
+            }
+            catch (error) {
+                if (error.code === "EEXIST")
+                    throw new Error("release target already exists", { cause: error });
+                throw error;
+            }
+            const destinationMetadata = await lstat(destination, { bigint: true });
+            if (!destinationMetadata.isFile() ||
+                destinationMetadata.isSymbolicLink() ||
+                !samePathIdentity(pathIdentityFromStats(destinationMetadata), identity))
+                throw new Error("published target identity is unsafe");
+            createdTargets.set(destination, identity);
+            await requireOwnedDirectory(targetDirectory, targetDirectoryIdentity, "release target directory");
+            await requireLock(lockPath, lockIdentity);
+            if (!(await removeOwnedFile(source, identity)))
+                throw new Error("compiled release staged file identity was lost");
+            await syncOwnedDirectory(targetDirectory, targetDirectoryIdentity);
+            await checkpoint(checkpoints[index]);
+            await requireOwnedDirectory(targetDirectory, targetDirectoryIdentity, "release target directory");
+            await requirePromotedTargets(createdTargets);
+            await requireLock(lockPath, lockIdentity);
+        }
+    }
+    catch (error) {
+        const targetDirectoryOwned = targetDirectory && targetDirectoryIdentity
+            ? await ownedMetadata(targetDirectory, targetDirectoryIdentity).then((metadata) => metadata?.isDirectory() === true, () => false)
+            : false;
+        if (targetDirectoryOwned) {
+            for (const [path, identity] of [...createdTargets.entries()].reverse())
+                await removeOwnedFile(path, identity).catch(() => false);
+            if (createdTargets.size > 0)
+                await syncOwnedDirectory(targetDirectory, targetDirectoryIdentity).catch(() => { });
+        }
+        throw error;
+    }
+    finally {
+        await lockHandle?.close().catch(() => { });
+        if (lockPath &&
+            lockIdentity &&
+            targetDirectory &&
+            targetDirectoryIdentity &&
+            (await ownedMetadata(targetDirectory, targetDirectoryIdentity).then((metadata) => metadata?.isDirectory() === true, () => false))) {
+            await removeOwnedFile(lockPath, lockIdentity).catch(() => false);
+            await syncOwnedDirectory(targetDirectory, targetDirectoryIdentity).catch(() => { });
+        }
+        await cleanupOwnedStage(state.paths, state.ownership);
+    }
+}
+export async function publishRelease(compiled, target) {
+    await publishReleaseWithCheckpoint(compiled, target);
+}
+export async function discardCompiledRelease(compiled) {
+    const state = stateFor(compiled);
+    state.consumed = true;
+    await cleanupOwnedStage(state.paths, state.ownership);
+}

package/dist/release/reference-map.d.ts

@@ -0,0 +1,53 @@
+import type { Sha256 } from "../runtime/types.ts";
+import { type CompilerLimits } from "./load-v4.ts";
+export interface ReferenceMapEntryV1 {
+    readonly uri: string;
+    readonly file: string;
+    readonly sha256: Sha256;
+}
+export interface ReferenceMapV1 {
+    readonly version: 1;
+    readonly entries: readonly ReferenceMapEntryV1[];
+}
+export interface ResolvedReferenceV1 {
+    readonly bytes: Uint8Array;
+    readonly mediaType: "json" | "yaml";
+}
+export interface ReferenceResolver {
+    resolve(uri: string): Promise<ResolvedReferenceV1>;
+}
+export interface ResolvedDocumentV4 {
+    readonly uri: string;
+    readonly document: Record<string, unknown>;
+}
+export declare function normalizeHttpsUri(value: string): string;
+export declare function sourceUriFromLabel(label: string): string;
+export declare function normalizeGraphUri(value: string, baseUri: string): string;
+export declare function loadReferenceMap(mapPath: string, sourceUri: string, limits?: CompilerLimits): Promise<ReferenceMapV1>;
+export declare function referenceGraphDigest(map: ReferenceMapV1): Promise<Sha256>;
+interface ReferenceReadTestCheckpoint {
+    beforeOpen(): void | Promise<void>;
+    onRead(): void;
+}
+export declare class ReferenceGraphV4 {
+    #private;
+    readonly sourceUri: string;
+    readonly map: ReferenceMapV1;
+    /** @internal Test-only hook; this module is not exported by the package. */
+    static setReferenceReadCheckpointForTesting(checkpoint: ReferenceReadTestCheckpoint | undefined): void;
+    private constructor();
+    static create(options: {
+        sourceUri: string;
+        mapPath?: string;
+        referenceRoot?: string;
+        resolver?: ReferenceResolver;
+        limits: CompilerLimits;
+        rootBytes: number;
+    }): Promise<ReferenceGraphV4>;
+    resolve(rawRef: string, fromUri: string, depth: number): Promise<{
+        uri: string;
+        pointer: string;
+        document: Record<string, unknown>;
+    }>;
+}
+export {};