@knitli/openapi-mcp 0.0.0

package/dist/runtime/manifest.js

@@ -0,0 +1,489 @@
+import { sha256, verifyEd25519 } from "./digest.js";
+import { OpenApiMcpError } from "./errors.js";
+import { parseTypedRecordId } from "./references.js";
+import { canonicalJson, parseJsonStrict } from "./strict-json.js";
+import { resolveRuntimeLimits } from "./versions.js";
+function manifestSignatureDomain(format) {
+    return `knitli.openapi-mcp.release-manifest.v${format}\0`;
+}
+function manifestDigestDomain(format) {
+    return `knitli.openapi-mcp.release-manifest.v${format}`;
+}
+const rollbackSignatureDomain = "knitli.openapi-mcp.rollback-authorization.v1\0";
+const digestPattern = /^[0-9a-f]{64}$/;
+const identifierPattern = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const boundedAsciiPattern = /^[\x21-\x7e]+$/;
+const manifestKeys = [
+    "allowedOrigins",
+    "catalogId",
+    "compiledAt",
+    "compilerVersion",
+    "contract",
+    "format",
+    "generation",
+    "issuer",
+    "keyId",
+    "policyId",
+    "records",
+    "releaseId",
+    "source",
+];
+const sourceKeys = [
+    "contentSha256",
+    "referenceGraphDigest",
+    "revision",
+    "uri",
+];
+const signatureKeys = ["algorithm", "keyId", "signature"];
+const rollbackKeys = [
+    "algorithm",
+    "catalogId",
+    "currentHighestGeneration",
+    "expiresAt",
+    "id",
+    "issuer",
+    "keyId",
+    "reason",
+    "signature",
+    "targetGeneration",
+    "targetManifestDigest",
+];
+const envelopeRequiredKeys = ["manifestJson", "signature"];
+function manifestInvalid(message) {
+    return new OpenApiMcpError("MANIFEST_INVALID", message);
+}
+function rollbackRejected(message) {
+    return new OpenApiMcpError("MANIFEST_ROLLBACK_REJECTED", message);
+}
+function isObject(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === null || prototype === Object.prototype;
+}
+function ownData(value, key) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (descriptor === undefined ||
+        !("value" in descriptor) ||
+        !descriptor.enumerable) {
+        throw manifestInvalid(`${key} must be an own data property`);
+    }
+    return descriptor.value;
+}
+function requireExactShape(value, expected, label) {
+    if (!isObject(value))
+        throw manifestInvalid(`${label} must be an object`);
+    if (Reflect.ownKeys(value).some((key) => typeof key !== "string")) {
+        throw manifestInvalid(`${label} has a symbol property`);
+    }
+    const keys = Reflect.ownKeys(value).sort();
+    const sortedExpected = [...expected].sort();
+    if (keys.length !== sortedExpected.length ||
+        keys.some((key, index) => typeof key === "string" ? key !== sortedExpected[index] : true)) {
+        throw manifestInvalid(`${label} shape is invalid`);
+    }
+    for (const key of sortedExpected)
+        ownData(value, key);
+    return value;
+}
+function requireString(value, label, maximum, pattern) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.length > maximum ||
+        (pattern && !pattern.test(value))) {
+        throw manifestInvalid(`${label} is invalid`);
+    }
+    return value;
+}
+function requireIdentifier(value, label) {
+    const result = requireString(value, label, 128, identifierPattern);
+    if (result === "." || result === "..")
+        throw manifestInvalid(`${label} is invalid`);
+    return result;
+}
+function requireInteger(value, label) {
+    if (!Number.isSafeInteger(value) || value < 0)
+        throw manifestInvalid(`${label} is invalid`);
+    return value;
+}
+function requireDigest(value, label) {
+    if (typeof value !== "string" || !digestPattern.test(value))
+        throw manifestInvalid(`${label} is invalid`);
+    return value;
+}
+function requireTimestamp(value, label) {
+    const timestamp = requireString(value, label, 64, boundedAsciiPattern);
+    const parsed = new Date(timestamp);
+    if (!Number.isFinite(parsed.getTime()) ||
+        parsed.toISOString() !== timestamp) {
+        throw manifestInvalid(`${label} must be a canonical UTC timestamp`);
+    }
+    return timestamp;
+}
+function requireOrigin(value) {
+    const candidate = requireString(value, "allowed origin", 2048, boundedAsciiPattern);
+    let url;
+    try {
+        url = new URL(candidate);
+    }
+    catch {
+        throw manifestInvalid("allowed origin is invalid");
+    }
+    if (url.protocol !== "https:" ||
+        url.username !== "" ||
+        url.password !== "" ||
+        url.pathname !== "/" ||
+        url.search !== "" ||
+        url.hash !== "" ||
+        url.origin !== candidate) {
+        throw manifestInvalid("allowed origin must be an exact canonical HTTPS origin");
+    }
+    return candidate;
+}
+function parseManifest(text, limits) {
+    const parsed = parseJsonStrict(text, {
+        maxBytes: limits.maxManifestBytes,
+        maxDepth: limits.maxJsonDepth,
+        maxKeys: limits.maxManifestRecords + 32,
+    });
+    const value = requireExactShape(parsed, manifestKeys, "manifest");
+    const format = ownData(value, "format");
+    if ((format !== 4 && format !== 5) || ownData(value, "contract") !== 1) {
+        throw manifestInvalid("manifest versions are unsupported");
+    }
+    const catalogId = requireIdentifier(ownData(value, "catalogId"), "catalog ID");
+    const releaseId = requireIdentifier(ownData(value, "releaseId"), "release ID");
+    const generation = requireInteger(ownData(value, "generation"), "generation");
+    const issuer = requireString(ownData(value, "issuer"), "issuer", 256, boundedAsciiPattern);
+    const keyId = requireIdentifier(ownData(value, "keyId"), "key ID");
+    const policyId = requireIdentifier(ownData(value, "policyId"), "policy ID");
+    const compilerVersion = requireString(ownData(value, "compilerVersion"), "compiler version", 128, boundedAsciiPattern);
+    const compiledAt = requireTimestamp(ownData(value, "compiledAt"), "compiledAt");
+    const rawOrigins = ownData(value, "allowedOrigins");
+    if (!Array.isArray(rawOrigins) || rawOrigins.length === 0)
+        throw manifestInvalid("allowedOrigins is invalid");
+    const allowedOrigins = rawOrigins.map(requireOrigin);
+    if (new Set(allowedOrigins).size !== allowedOrigins.length)
+        throw manifestInvalid("allowedOrigins contains a duplicate");
+    const rawSource = requireExactShape(ownData(value, "source"), sourceKeys, "manifest source");
+    const source = {
+        uri: requireString(ownData(rawSource, "uri"), "source URI", 4096),
+        revision: requireString(ownData(rawSource, "revision"), "source revision", 512, boundedAsciiPattern),
+        contentSha256: requireDigest(ownData(rawSource, "contentSha256"), "source content digest"),
+        referenceGraphDigest: requireDigest(ownData(rawSource, "referenceGraphDigest"), "reference graph digest"),
+    };
+    const rawRecords = ownData(value, "records");
+    if (!isObject(rawRecords))
+        throw manifestInvalid("records must be an object");
+    const recordKeys = Reflect.ownKeys(rawRecords);
+    if (recordKeys.length > limits.maxManifestRecords)
+        throw manifestInvalid("manifest exceeds its record limit");
+    const records = Object.create(null);
+    for (const rawId of recordKeys) {
+        if (typeof rawId !== "string")
+            throw manifestInvalid("records has a symbol key");
+        let id;
+        try {
+            id = parseTypedRecordId(rawId);
+        }
+        catch {
+            throw manifestInvalid("manifest record ID is invalid");
+        }
+        records[id] = requireDigest(ownData(rawRecords, rawId), "record digest");
+    }
+    return {
+        format,
+        contract: 1,
+        catalogId,
+        releaseId,
+        generation,
+        issuer,
+        keyId,
+        policyId,
+        allowedOrigins,
+        compiledAt,
+        compilerVersion,
+        source,
+        records,
+    };
+}
+function parseSignature(value) {
+    const object = requireExactShape(value, signatureKeys, "manifest signature");
+    if (ownData(object, "algorithm") !== "Ed25519")
+        throw manifestInvalid("manifest signature algorithm is invalid");
+    return {
+        algorithm: "Ed25519",
+        keyId: requireIdentifier(ownData(object, "keyId"), "signature key ID"),
+        signature: requireString(ownData(object, "signature"), "manifest signature", 256, /^[A-Za-z0-9_-]+$/),
+    };
+}
+function findKey(keys, issuer, keyId) {
+    const matches = keys.filter((key) => key.issuer === issuer && key.keyId === keyId);
+    return matches.length === 1 ? matches[0] : null;
+}
+async function requireReleaseSignature(manifest, canonical, signatureValue, trust) {
+    let signature;
+    try {
+        signature = parseSignature(signatureValue);
+    }
+    catch {
+        throw new OpenApiMcpError("MANIFEST_SIGNATURE_INVALID", "Manifest signature envelope is invalid");
+    }
+    if (signature.keyId !== manifest.keyId) {
+        throw new OpenApiMcpError("MANIFEST_SIGNATURE_INVALID", "Manifest signature key does not match the manifest");
+    }
+    const key = findKey(trust.releaseKeys, manifest.issuer, signature.keyId);
+    if (key === null ||
+        !(await verifyEd25519(`${manifestSignatureDomain(manifest.format)}${canonical}`, signature.signature, key.publicKey))) {
+        throw new OpenApiMcpError("MANIFEST_SIGNATURE_INVALID", "Manifest signature is not trusted");
+    }
+}
+function rollbackUnsigned(value) {
+    return {
+        id: value.id,
+        catalogId: value.catalogId,
+        issuer: value.issuer,
+        currentHighestGeneration: value.currentHighestGeneration,
+        targetGeneration: value.targetGeneration,
+        targetManifestDigest: value.targetManifestDigest,
+        reason: value.reason,
+        expiresAt: value.expiresAt,
+        keyId: value.keyId,
+        algorithm: value.algorithm,
+    };
+}
+function parseRollback(value) {
+    const object = requireExactShape(value, rollbackKeys, "rollback authorization");
+    const rollback = {
+        id: requireIdentifier(ownData(object, "id"), "rollback authorization ID"),
+        catalogId: requireIdentifier(ownData(object, "catalogId"), "rollback catalog ID"),
+        issuer: requireString(ownData(object, "issuer"), "rollback issuer", 256, boundedAsciiPattern),
+        currentHighestGeneration: requireInteger(ownData(object, "currentHighestGeneration"), "rollback current generation"),
+        targetGeneration: requireInteger(ownData(object, "targetGeneration"), "rollback target generation"),
+        targetManifestDigest: requireDigest(ownData(object, "targetManifestDigest"), "rollback target digest"),
+        reason: requireString(ownData(object, "reason"), "rollback reason", 1024),
+        expiresAt: requireTimestamp(ownData(object, "expiresAt"), "rollback expiry"),
+        keyId: requireIdentifier(ownData(object, "keyId"), "rollback key ID"),
+        algorithm: ownData(object, "algorithm"),
+        signature: requireString(ownData(object, "signature"), "rollback signature", 256, /^[A-Za-z0-9_-]+$/),
+    };
+    if (rollback.algorithm !== "Ed25519")
+        throw manifestInvalid("rollback algorithm is invalid");
+    return rollback;
+}
+async function requireRollback(manifest, manifestDigest, state, candidate, trust) {
+    if (candidate === undefined)
+        throw rollbackRejected("A signed rollback authorization is required");
+    let value;
+    try {
+        value = parseRollback(candidate);
+    }
+    catch {
+        throw rollbackRejected("Rollback authorization is malformed");
+    }
+    if (value.catalogId !== manifest.catalogId ||
+        value.issuer !== manifest.issuer ||
+        value.currentHighestGeneration !== state.highestGeneration ||
+        value.targetGeneration !== manifest.generation ||
+        value.targetManifestDigest !== manifestDigest ||
+        state.consumedRollbackAuthorizationIds.includes(value.id)) {
+        throw rollbackRejected("Rollback authorization does not match current state and target");
+    }
+    const now = trust.now?.() ?? new Date();
+    if (new Date(value.expiresAt).getTime() <= now.getTime())
+        throw rollbackRejected("Rollback authorization has expired");
+    const key = findKey(trust.rollbackKeys, manifest.issuer, value.keyId);
+    if (key === null ||
+        trust.releaseKeys.some((releaseKey) => releaseKey.publicKey === key.publicKey)) {
+        throw rollbackRejected("Rollback key is not separately trusted");
+    }
+    const valid = await verifyEd25519(`${rollbackSignatureDomain}${canonicalJson(rollbackUnsigned(value))}`, value.signature, key.publicKey);
+    if (!valid)
+        throw rollbackRejected("Rollback signature is invalid");
+    return value.id;
+}
+function nextNormalState(state, manifest, digest) {
+    if (state === null) {
+        return {
+            revision: 0,
+            highestGeneration: manifest.generation,
+            highestManifestDigest: digest,
+            activeGeneration: manifest.generation,
+            activeManifestDigest: digest,
+            consumedRollbackAuthorizationIds: [],
+        };
+    }
+    if (manifest.generation > state.highestGeneration) {
+        return {
+            ...state,
+            revision: state.revision + 1,
+            highestGeneration: manifest.generation,
+            highestManifestDigest: digest,
+            activeGeneration: manifest.generation,
+            activeManifestDigest: digest,
+        };
+    }
+    if (manifest.generation === state.highestGeneration) {
+        if (digest !== state.highestManifestDigest) {
+            throw new OpenApiMcpError("MANIFEST_GENERATION_CONFLICT", "Equal manifest generation has a different digest");
+        }
+        if (state.activeGeneration === manifest.generation &&
+            state.activeManifestDigest === digest)
+            return null;
+        return {
+            ...state,
+            revision: state.revision + 1,
+            activeGeneration: manifest.generation,
+            activeManifestDigest: digest,
+        };
+    }
+    return null;
+}
+function deepFreeze(value) {
+    if (typeof value !== "object" || value === null || Object.isFrozen(value))
+        return value;
+    for (const key of Reflect.ownKeys(value))
+        deepFreeze(value[key]);
+    return Object.freeze(value);
+}
+function detachedManifest(manifest, limits) {
+    return parseManifest(canonicalJson(manifest), limits);
+}
+/** Authenticate a v4/v5 manifest without reading or mutating generation state. */
+export async function authenticateManifest(envelope, trust, limitOverrides) {
+    const limits = resolveRuntimeLimits(limitOverrides);
+    if (!isObject(envelope))
+        throw manifestInvalid("manifest envelope must be an object");
+    const envelopeKeys = Object.hasOwn(envelope, "rollback")
+        ? [...envelopeRequiredKeys, "rollback"]
+        : envelopeRequiredKeys;
+    const checkedEnvelope = requireExactShape(envelope, envelopeKeys, "manifest envelope");
+    const manifestJson = ownData(checkedEnvelope, "manifestJson");
+    if (typeof manifestJson !== "string")
+        throw manifestInvalid("manifestJson must be a string");
+    const signature = ownData(checkedEnvelope, "signature");
+    const rollbackCandidate = envelopeKeys.length === 3
+        ? ownData(checkedEnvelope, "rollback")
+        : undefined;
+    let manifest;
+    try {
+        manifest = parseManifest(manifestJson, limits);
+    }
+    catch (error) {
+        if (error instanceof OpenApiMcpError)
+            throw error;
+        throw manifestInvalid("Manifest parsing failed");
+    }
+    const canonical = canonicalJson(manifest);
+    await requireReleaseSignature(manifest, canonical, signature, trust);
+    const manifestDigest = await sha256(manifestDigestDomain(manifest.format), manifest);
+    let rollback;
+    let rollbackMalformed = false;
+    if (rollbackCandidate !== undefined) {
+        try {
+            rollback = parseRollback(rollbackCandidate);
+        }
+        catch {
+            rollback = undefined;
+            rollbackMalformed = true;
+        }
+    }
+    return deepFreeze({
+        manifest: detachedManifest(manifest, limits),
+        manifestDigest,
+        rollback,
+        rollbackMalformed,
+    });
+}
+/** Atomically commit the generation transition for an authenticated manifest. */
+/**
+ * Commit only the generation decision made against `state`.
+ * A null result is a CAS miss; callers must reread and re-plan rather than
+ * reinterpreting this manifest under a newer generation policy.
+ */
+export async function commitAuthenticatedManifestAtState(authenticated, trust, generations, state) {
+    const { manifest, manifestDigest, rollback, rollbackMalformed } = authenticated;
+    const admitted = { manifest, manifestDigest };
+    if (state !== null &&
+        manifest.generation === state.activeGeneration &&
+        manifestDigest === state.activeManifestDigest) {
+        return admitted;
+    }
+    let next = nextNormalState(state, manifest, manifestDigest);
+    if (state !== null &&
+        manifest.generation === state.highestGeneration &&
+        manifestDigest === state.highestManifestDigest &&
+        state.activeGeneration !== state.highestGeneration) {
+        throw rollbackRejected("Inactive high-water release cannot reactivate");
+    }
+    if (state !== null && manifest.generation < state.highestGeneration) {
+        if (rollbackMalformed)
+            throw rollbackRejected("Rollback authorization is malformed");
+        const rollbackId = await requireRollback(manifest, manifestDigest, state, rollback, trust);
+        next = {
+            ...state,
+            revision: state.revision + 1,
+            activeGeneration: manifest.generation,
+            activeManifestDigest: manifestDigest,
+            consumedRollbackAuthorizationIds: [
+                ...state.consumedRollbackAuthorizationIds,
+                rollbackId,
+            ],
+        };
+    }
+    if (next === null)
+        return admitted;
+    const accepted = await generations.accept(manifest.catalogId, manifest.issuer, {
+        expectedRevision: state?.revision ?? null,
+        next,
+    });
+    return accepted === null ? null : admitted;
+}
+export async function admitAuthenticatedManifest(authenticated, trust, generations) {
+    const { manifest, manifestDigest, rollback, rollbackMalformed } = authenticated;
+    const admitted = { manifest, manifestDigest };
+    for (let attempt = 0; attempt < 32; attempt += 1) {
+        const state = await generations.get(manifest.catalogId, manifest.issuer);
+        if (state !== null &&
+            manifest.generation === state.activeGeneration &&
+            manifestDigest === state.activeManifestDigest) {
+            return admitted;
+        }
+        let next = nextNormalState(state, manifest, manifestDigest);
+        if (state !== null &&
+            manifest.generation === state.highestGeneration &&
+            manifestDigest === state.highestManifestDigest &&
+            state.activeGeneration !== state.highestGeneration) {
+            throw rollbackRejected("Inactive high-water release cannot reactivate");
+        }
+        if (state !== null && manifest.generation < state.highestGeneration) {
+            if (rollbackMalformed)
+                throw rollbackRejected("Rollback authorization is malformed");
+            const rollbackId = await requireRollback(manifest, manifestDigest, state, rollback, trust);
+            next = {
+                ...state,
+                revision: state.revision + 1,
+                activeGeneration: manifest.generation,
+                activeManifestDigest: manifestDigest,
+                consumedRollbackAuthorizationIds: [
+                    ...state.consumedRollbackAuthorizationIds,
+                    rollbackId,
+                ],
+            };
+        }
+        if (next === null)
+            return admitted;
+        const accepted = await generations.accept(manifest.catalogId, manifest.issuer, {
+            expectedRevision: state?.revision ?? null,
+            next,
+        });
+        if (accepted !== null)
+            return admitted;
+    }
+    throw new OpenApiMcpError("MANIFEST_GENERATION_CONFLICT", "Generation state changed too many times; retry admission");
+}
+/** Verify a v4/v5 manifest and atomically admit its generation transition. */
+export async function admitManifest(envelope, trust, generations, limitOverrides) {
+    const authenticated = await authenticateManifest(envelope, trust, limitOverrides);
+    return admitAuthenticatedManifest(authenticated, trust, generations);
+}

package/dist/runtime/prepared-call.d.ts

@@ -0,0 +1,39 @@
+import type { ActionCardinality, ActionKind, CatalogId, HttpMethod, JsonObject, PaginationTokenState, PreparedCall, ReleaseId, Sha256, TypedOperationId } from "./types.ts";
+import { type RuntimeLimits } from "./versions.ts";
+export type PreparedCallInput = Omit<PreparedCall, "inputDigest" | "preparedCallDigest">;
+interface ParsedPreparedCall {
+    readonly version: 2;
+    readonly catalogId: CatalogId;
+    readonly releaseId: ReleaseId;
+    readonly operationId: TypedOperationId;
+    readonly operationDigest: Sha256;
+    readonly manifestDigest: Sha256;
+    readonly credentialProfileId: string;
+    readonly credentialProfileDigest: Sha256;
+    readonly reservedSlotsDigest: Sha256;
+    readonly method: HttpMethod;
+    readonly origin: string;
+    readonly relativeUrl: string;
+    readonly pageToken: string | null;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body: Uint8Array | null;
+    readonly normalizedArguments: JsonObject;
+    readonly safety: "read" | "action";
+    readonly actionKind: ActionKind | null;
+    readonly cardinality: ActionCardinality | null;
+    readonly inputDigest: Sha256;
+    readonly preparedCallDigest: Sha256;
+}
+/** Package-private defensive snapshot shared by the runtime and local codec. */
+export declare function snapshotPaginationTokenState(value: unknown, limits: RuntimeLimits, now?: number): Readonly<PaginationTokenState>;
+/** SHA-256 of raw request bytes, independent of JSON canonicalization. */
+export declare function digestBytes(value: Uint8Array): Promise<Sha256>;
+/** Compute the domain-separated call digest, deliberately omitting its own key. */
+export declare function digestPreparedCall(call: PreparedCall): Promise<Sha256>;
+/** Verify a prepared call locally; storage admission is rechecked separately. */
+export declare function verifyAndSnapshotPreparedCall(call: PreparedCall): Promise<Readonly<ParsedPreparedCall>>;
+/** Verify a prepared call locally; storage admission is rechecked separately. */
+export declare function verifyPreparedCall(call: PreparedCall): Promise<void>;
+/** Build an owned, detached prepared call and bind all fields to its digests. */
+export declare function createPreparedCall(input: PreparedCallInput): Promise<PreparedCall>;
+export {};