@knitli/openapi-mcp 0.0.0

package/dist/runtime/verify-record.js

@@ -0,0 +1,492 @@
+import { sha256 } from "./digest.js";
+import { OpenApiMcpError } from "./errors.js";
+import { parseTypedRecordId } from "./references.js";
+import { schemaChildKind } from "./schema-keywords.js";
+import { canonicalJsonBounded, parseJsonStrict } from "./strict-json.js";
+import { MAX_OPERATION_TAG_BYTES, MAX_OPERATION_TAG_BYTES_TOTAL, MAX_OPERATION_TAGS, resolveRuntimeLimits, } from "./versions.js";
+const operationKeys = [
+    "advisory",
+    "api",
+    "deprecated",
+    "id",
+    "method",
+    "operationId",
+    "origin",
+    "parameters",
+    "path",
+    "requestBody",
+    "schemaIds",
+    "summary",
+    "tags",
+];
+const legacyOperationKeys = operationKeys.filter((key) => key !== "tags");
+const schemaKeys = ["id", "schema"];
+const wrapperKeys = ["id", "logicalDigest", "record"];
+const parameterKeys = [
+    "allowReserved",
+    "deprecated",
+    "explode",
+    "in",
+    "name",
+    "required",
+    "style",
+    "value",
+];
+const schemaUseSchemaKeys = ["kind", "schemaId"];
+const schemaUseContentKeys = ["kind", "mediaType", "schemaId"];
+const requestBodyKeys = ["content", "required"];
+const requestBodyMediaKeys = ["encoding", "mediaType", "schemaId"];
+const encodingKeys = [
+    "allowReserved",
+    "contentType",
+    "explode",
+    "headers",
+    "property",
+    "style",
+];
+const encodingHeaderKeys = ["name", "required", "value"];
+const digestPattern = /^[0-9a-f]{64}$/;
+const mediaTypePattern = /^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/;
+const headerPattern = /^[a-z0-9!#$%&'*+.^_`|~-]+$/;
+const locations = ["path", "query", "header", "cookie"];
+const styles = [
+    "matrix",
+    "label",
+    "form",
+    "simple",
+    "spaceDelimited",
+    "pipeDelimited",
+    "deepObject",
+];
+function mismatch(message) {
+    return new OpenApiMcpError("RECORD_DIGEST_MISMATCH", message);
+}
+function exactObject(value, keys, label) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw mismatch(`${label} is not an object`);
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== null && prototype !== Object.prototype)
+        throw mismatch(`${label} prototype is invalid`);
+    const actual = Reflect.ownKeys(value);
+    if (actual.some((key) => typeof key !== "string"))
+        throw mismatch(`${label} has a symbol property`);
+    const sorted = actual.sort();
+    const expected = [...keys].sort();
+    if (sorted.length !== expected.length ||
+        sorted.some((key, index) => key !== expected[index]))
+        throw mismatch(`${label} shape is invalid`);
+    for (const key of sorted) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (descriptor === undefined ||
+            !("value" in descriptor) ||
+            !descriptor.enumerable)
+            throw mismatch(`${label} properties must be own data`);
+    }
+    return value;
+}
+function extractStoredRecord(value) {
+    try {
+        const object = exactObject(value, wrapperKeys, "stored row");
+        const id = Object.getOwnPropertyDescriptor(object, "id");
+        const logicalDigest = Object.getOwnPropertyDescriptor(object, "logicalDigest");
+        const record = Object.getOwnPropertyDescriptor(object, "record");
+        if (id === undefined ||
+            !("value" in id) ||
+            logicalDigest === undefined ||
+            !("value" in logicalDigest) ||
+            record === undefined ||
+            !("value" in record))
+            throw mismatch("Stored row properties must be own data");
+        return {
+            id: id.value,
+            logicalDigest: logicalDigest.value,
+            record: record.value,
+        };
+    }
+    catch (error) {
+        if (error instanceof OpenApiMcpError &&
+            error.code === "RECORD_DIGEST_MISMATCH")
+            throw error;
+        throw mismatch("Stored row wrapper cannot be inspected");
+    }
+}
+function schemaId(value, label) {
+    try {
+        if (typeof value !== "string" ||
+            !parseTypedRecordId(value).startsWith("schema:"))
+            throw new Error();
+        return value;
+    }
+    catch {
+        throw mismatch(`${label} is not a typed schema ID`);
+    }
+}
+function validateOperationTags(value) {
+    if (!Array.isArray(value) || value.length > MAX_OPERATION_TAGS)
+        throw mismatch("Operation record tags are invalid");
+    const seen = new Set();
+    let totalBytes = 0;
+    for (const tag of value) {
+        if (typeof tag !== "string" ||
+            tag.length === 0 ||
+            tag.length > MAX_OPERATION_TAG_BYTES)
+            throw mismatch("Operation record tags are invalid");
+        const tagBytes = new TextEncoder().encode(tag).byteLength;
+        if (tagBytes > MAX_OPERATION_TAG_BYTES ||
+            totalBytes + tagBytes > MAX_OPERATION_TAG_BYTES_TOTAL ||
+            seen.has(tag))
+            throw mismatch("Operation record tags are invalid");
+        seen.add(tag);
+        totalBytes += tagBytes;
+    }
+}
+function sortedUnique(values, label) {
+    for (let index = 1; index < values.length; index += 1) {
+        if (values[index - 1] >= values[index])
+            throw mismatch(`${label} must be sorted and unique`);
+    }
+}
+function validateSchemaUse(value, label) {
+    const candidate = exactObject(value, value?.kind === "content"
+        ? schemaUseContentKeys
+        : schemaUseSchemaKeys, label);
+    if (candidate.kind !== "schema" && candidate.kind !== "content")
+        throw mismatch(`${label} discriminant is invalid`);
+    if (candidate.kind === "content" &&
+        (typeof candidate.mediaType !== "string" ||
+            !mediaTypePattern.test(candidate.mediaType))) {
+        throw mismatch(`${label} media type is invalid`);
+    }
+    return schemaId(candidate.schemaId, `${label} schema ID`);
+}
+function validateParameters(value) {
+    if (!Array.isArray(value))
+        throw mismatch("Operation parameters are invalid");
+    const schemaIds = [];
+    const pathNames = [];
+    let previousLocation = -1;
+    let previousName = "";
+    for (const [index, raw] of value.entries()) {
+        const parameter = exactObject(raw, parameterKeys, `parameter ${index}`);
+        if (typeof parameter.name !== "string" ||
+            parameter.name.length === 0 ||
+            typeof parameter.in !== "string" ||
+            !locations.includes(parameter.in) ||
+            typeof parameter.required !== "boolean" ||
+            typeof parameter.deprecated !== "boolean" ||
+            typeof parameter.style !== "string" ||
+            !styles.includes(parameter.style) ||
+            typeof parameter.explode !== "boolean" ||
+            typeof parameter.allowReserved !== "boolean")
+            throw mismatch(`parameter ${index} fields are invalid`);
+        if (parameter.in === "path" && parameter.required !== true)
+            throw mismatch("Path parameters must be required");
+        if (parameter.in === "path")
+            pathNames.push(parameter.name);
+        const location = locations.indexOf(parameter.in);
+        if (location < previousLocation ||
+            (location === previousLocation && parameter.name <= previousName))
+            throw mismatch("Operation parameters must be sorted and unique");
+        previousLocation = location;
+        previousName = parameter.name;
+        schemaIds.push(validateSchemaUse(parameter.value, `parameter ${index} value`));
+    }
+    return { schemaIds, pathNames };
+}
+export function parseOperationPathTemplateV4(path) {
+    if (!path.startsWith("/") ||
+        path.startsWith("//") ||
+        !/^[\x21-\x7e]+$/.test(path) ||
+        path.includes("\\") ||
+        path.includes("?") ||
+        path.includes("#"))
+        throw new Error("operation path must be a root-relative request target");
+    const matches = [...path.matchAll(/\{([^{}]+)\}/g)];
+    const withoutValidTemplates = path.replace(/\{([^{}]+)\}/g, "");
+    if (withoutValidTemplates.includes("{") ||
+        withoutValidTemplates.includes("}")) {
+        throw new Error("operation path template is malformed");
+    }
+    const variables = matches.map((match) => match[1]);
+    if (new Set(variables).size !== variables.length) {
+        throw new Error("operation path template variables must be unique");
+    }
+    const comparablePath = path.replace(/\{([^{}]+)\}/g, "openapi-template");
+    const normalized = new URL(comparablePath, "https://openapi.invalid");
+    if (normalized.origin !== "https://openapi.invalid" ||
+        normalized.pathname !== comparablePath ||
+        normalized.search !== "" ||
+        normalized.hash !== "")
+        throw new Error("operation path must be normalized");
+    return variables;
+}
+function validatePathTemplate(path, pathNames) {
+    let variables;
+    try {
+        variables = parseOperationPathTemplateV4(path);
+    }
+    catch {
+        throw mismatch("Operation path template is invalid");
+    }
+    const sortedVariables = [...variables].sort();
+    const sortedPathNames = [...pathNames].sort();
+    if (sortedVariables.length !== sortedPathNames.length ||
+        sortedVariables.some((name, index) => name !== sortedPathNames[index])) {
+        throw mismatch("Operation path parameters must exactly match path-template variables");
+    }
+}
+function validateRequestBody(value) {
+    if (value === null)
+        return [];
+    const body = exactObject(value, requestBodyKeys, "request body");
+    if (typeof body.required !== "boolean" ||
+        !Array.isArray(body.content) ||
+        body.content.length === 0)
+        throw mismatch("Request body fields are invalid");
+    const schemaIds = [];
+    let previousMedia = "";
+    for (const [mediaIndex, rawMedia] of body.content.entries()) {
+        const media = exactObject(rawMedia, requestBodyMediaKeys, `request body media ${mediaIndex}`);
+        if (typeof media.mediaType !== "string" ||
+            !mediaTypePattern.test(media.mediaType) ||
+            media.mediaType <= previousMedia ||
+            !Array.isArray(media.encoding)) {
+            throw mismatch("Request body media entries are invalid or unsorted");
+        }
+        previousMedia = media.mediaType;
+        schemaIds.push(schemaId(media.schemaId, "request body schema ID"));
+        let previousProperty = "";
+        for (const [encodingIndex, rawEncoding] of media.encoding.entries()) {
+            const encoding = exactObject(rawEncoding, encodingKeys, `encoding ${encodingIndex}`);
+            if (typeof encoding.property !== "string" ||
+                encoding.property.length === 0 ||
+                encoding.property <= previousProperty ||
+                !(encoding.contentType === null ||
+                    (typeof encoding.contentType === "string" &&
+                        mediaTypePattern.test(encoding.contentType))) ||
+                !(encoding.style === null ||
+                    (typeof encoding.style === "string" &&
+                        styles.includes(encoding.style))) ||
+                !(encoding.explode === null || typeof encoding.explode === "boolean") ||
+                typeof encoding.allowReserved !== "boolean" ||
+                !Array.isArray(encoding.headers))
+                throw mismatch("Request body encoding fields are invalid or unsorted");
+            previousProperty = encoding.property;
+            let previousHeader = "";
+            for (const [headerIndex, rawHeader] of encoding.headers.entries()) {
+                const header = exactObject(rawHeader, encodingHeaderKeys, `encoding header ${headerIndex}`);
+                if (typeof header.name !== "string" ||
+                    !headerPattern.test(header.name) ||
+                    header.name <= previousHeader ||
+                    typeof header.required !== "boolean") {
+                    throw mismatch("Encoding headers are invalid or unsorted");
+                }
+                previousHeader = header.name;
+                schemaIds.push(validateSchemaUse(header.value, `encoding header ${headerIndex} value`));
+            }
+        }
+    }
+    return schemaIds;
+}
+function validateSchemaReferences(value) {
+    if (typeof value === "boolean")
+        return;
+    const stack = [
+        { label: "schema", value },
+    ];
+    const pushSubschema = (child, label) => {
+        if (typeof child === "boolean")
+            return;
+        if (typeof child !== "object" || child === null || Array.isArray(child))
+            throw mismatch(`${label} must be a boolean or object schema`);
+        stack.push({ label, value: child });
+    };
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (!current)
+            continue;
+        if (typeof current.value !== "object" ||
+            current.value === null ||
+            Array.isArray(current.value))
+            throw mismatch(`${current.label} must be an object schema`);
+        for (const [key, child] of Object.entries(current.value)) {
+            if (["$dynamicRef", "$recursiveRef", "$anchor", "$dynamicAnchor"].includes(key))
+                throw mismatch(`${key} is unsupported in a schema record`);
+            if (key === "$ref")
+                schemaId(child, "schema $ref");
+            else if (schemaChildKind(key) === "single")
+                pushSubschema(child, `schema ${key}`);
+            else if (schemaChildKind(key) === "array") {
+                if (!Array.isArray(child))
+                    throw mismatch(`schema ${key} must be an array`);
+                child.forEach((entry, index) => {
+                    pushSubschema(entry, `schema ${key}[${index}]`);
+                });
+            }
+            else if (schemaChildKind(key) === "map") {
+                if (typeof child !== "object" || child === null || Array.isArray(child))
+                    throw mismatch(`schema ${key} must be an object`);
+                for (const [name, entry] of Object.entries(child))
+                    pushSubschema(entry, `schema ${key}.${name}`);
+            }
+        }
+    }
+}
+function validateRecord(record, wrapperId, format) {
+    let id;
+    try {
+        if (typeof wrapperId !== "string")
+            throw new Error();
+        id = parseTypedRecordId(wrapperId);
+    }
+    catch {
+        throw mismatch("Stored row ID is malformed");
+    }
+    const isOperation = id.startsWith("operation:");
+    const object = exactObject(record, isOperation
+        ? format === 5
+            ? operationKeys
+            : legacyOperationKeys
+        : schemaKeys, "logical record");
+    if (object.id !== id)
+        throw mismatch("Stored row and logical record IDs disagree");
+    if (isOperation) {
+        if (typeof object.api !== "string" ||
+            typeof object.operationId !== "string" ||
+            ![
+                "GET",
+                "HEAD",
+                "POST",
+                "PUT",
+                "PATCH",
+                "DELETE",
+                "OPTIONS",
+                "TRACE",
+            ].includes(object.method) ||
+            typeof object.path !== "string" ||
+            typeof object.origin !== "string" ||
+            !(object.summary === null || typeof object.summary === "string") ||
+            typeof object.deprecated !== "boolean" ||
+            !Array.isArray(object.schemaIds) ||
+            !(typeof object.advisory === "object" &&
+                object.advisory !== null &&
+                !Array.isArray(object.advisory)))
+            throw mismatch("Operation record fields are invalid");
+        const tags = format === 5 ? object.tags : [];
+        validateOperationTags(tags);
+        if (`operation:${object.api}:${object.operationId}` !== id) {
+            throw mismatch("Operation record ID does not match its API and operation ID");
+        }
+        const parameters = validateParameters(object.parameters);
+        validatePathTemplate(object.path, parameters.pathNames);
+        const directSchemaIds = [
+            ...parameters.schemaIds,
+            ...validateRequestBody(object.requestBody),
+        ].sort();
+        const declaredSchemaIds = object.schemaIds.map((value) => schemaId(value, "Operation schema ID"));
+        sortedUnique(declaredSchemaIds, "Operation schema IDs");
+        const expectedSchemaIds = [...new Set(directSchemaIds)].sort();
+        if (declaredSchemaIds.length !== expectedSchemaIds.length ||
+            declaredSchemaIds.some((value, index) => value !== expectedSchemaIds[index])) {
+            throw mismatch("Operation schema IDs do not equal direct schema uses");
+        }
+        return (format === 5
+            ? object
+            : { ...object, tags });
+    }
+    else if (typeof object.schema !== "boolean" &&
+        (typeof object.schema !== "object" ||
+            object.schema === null ||
+            Array.isArray(object.schema))) {
+        throw mismatch("Schema record is invalid");
+    }
+    else {
+        validateSchemaReferences(object.schema);
+    }
+    return object;
+}
+function detached(record, limits) {
+    let json;
+    try {
+        json = canonicalJsonBounded(record, {
+            maxBytes: limits.maxRecordBytes,
+            maxDepth: limits.maxJsonDepth,
+            maxNodes: Math.max(1, limits.maxRecordBytes),
+        });
+    }
+    catch {
+        throw mismatch("Logical record cannot be bounded and canonicalized");
+    }
+    return parseJsonStrict(json, {
+        maxBytes: limits.maxRecordBytes,
+        maxDepth: limits.maxJsonDepth,
+        maxKeys: limits.maxManifestRecords,
+    });
+}
+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);
+}
+/** Reconstruct, hash, admit, detach, and freeze one untrusted store row. */
+export async function verifyStoredRecord(admitted, rowValue, limitOverrides) {
+    const limits = resolveRuntimeLimits(limitOverrides);
+    const row = extractStoredRecord(rowValue);
+    let wrapperId;
+    try {
+        if (typeof row.id !== "string")
+            throw new Error();
+        wrapperId = parseTypedRecordId(row.id);
+    }
+    catch {
+        throw mismatch("Stored row ID is malformed");
+    }
+    if (!Object.hasOwn(admitted.manifest.records, wrapperId)) {
+        throw new OpenApiMcpError("RECORD_NOT_ADMITTED", "Logical record is absent from the admitted manifest");
+    }
+    if (typeof row.logicalDigest !== "string" ||
+        !digestPattern.test(row.logicalDigest))
+        throw mismatch("Stored row digest is invalid");
+    let digestInput;
+    let copy;
+    try {
+        digestInput = detached(row.record, limits);
+        copy = validateRecord(digestInput, wrapperId, admitted.manifest.format);
+    }
+    catch (error) {
+        if (error instanceof OpenApiMcpError &&
+            error.code === "RECORD_DIGEST_MISMATCH")
+            throw error;
+        throw mismatch("Logical record cannot be canonicalized");
+    }
+    const recordKind = copy.id.startsWith("operation:") ? "operation" : "schema";
+    const domain = `knitli.openapi-mcp.${recordKind}-record.v${admitted.manifest.format}`;
+    const digest = await sha256(domain, digestInput);
+    if (digest !== row.logicalDigest)
+        throw mismatch("Stored logical digest does not match the row");
+    if (admitted.manifest.records[copy.id] !== digest) {
+        throw mismatch("Logical record digest does not match the admitted manifest");
+    }
+    if (copy.id.startsWith("operation:")) {
+        const operation = copy;
+        let origin;
+        try {
+            origin = new URL(operation.origin);
+        }
+        catch {
+            throw mismatch("Operation origin is invalid");
+        }
+        if (origin.protocol !== "https:" ||
+            origin.username !== "" ||
+            origin.password !== "" ||
+            origin.pathname !== "/" ||
+            origin.search !== "" ||
+            origin.hash !== "" ||
+            origin.origin !== operation.origin ||
+            !admitted.manifest.allowedOrigins.includes(operation.origin))
+            throw mismatch("Operation origin is not admitted by the manifest");
+    }
+    return deepFreeze(copy);
+}

package/dist/runtime/versions.d.ts

@@ -0,0 +1,63 @@
+/** Version of the portable runtime API and its persisted contract. */
+export declare const RUNTIME_CONTRACT_VERSION: 1;
+/** Version of immutable, signed logical release artifacts. */
+export declare const ARTIFACT_FORMAT_VERSION: 5;
+/** Version of the credential-free prepared-call representation. */
+export declare const PREPARED_CALL_VERSION: 2;
+/** Fixed UTF-8 envelope for a single catalog search query. */
+export declare const MAX_SEARCH_QUERY_BYTES: number;
+/** Fixed bounds for authenticated OpenAPI operation tags. */
+export declare const MAX_OPERATION_TAGS = 32;
+export declare const MAX_OPERATION_TAG_BYTES = 128;
+export declare const MAX_OPERATION_TAG_BYTES_TOTAL: number;
+/** Application security and availability limits for every runtime adapter. */
+export interface RuntimeLimits {
+    /**
+     * Combined canonical operation/schema bytes admitted per release and search.
+     * Optional so complete RuntimeLimits objects written before this limit was
+     * introduced remain source-compatible.
+     */
+    readonly maxReleaseInventoryBytes?: number;
+    readonly maxManifestBytes: number;
+    readonly maxManifestRecords: number;
+    readonly maxRecordBytes: number;
+    readonly maxJsonDepth: number;
+    readonly maxSchemaClosureBytes: number;
+    readonly maxSchemaRefHops: number;
+    readonly maxSearchResults: number;
+    readonly defaultSearchResults: number;
+    readonly maxArgumentsBytes: number;
+    readonly maxResponseBytes: number;
+    readonly maxPages: number;
+    readonly maxPaginationBytes: number;
+    readonly maxRedirects: number;
+    readonly requestDeadlineMs: number;
+}
+/** Fully defaulted limits used by runtime internals. */
+interface ResolvedRuntimeLimits extends RuntimeLimits {
+    readonly maxReleaseInventoryBytes: number;
+}
+export declare const DEFAULT_RUNTIME_LIMITS: Readonly<{
+    readonly maxManifestBytes: number;
+    readonly maxManifestRecords: 100000;
+    readonly maxRecordBytes: number;
+    readonly maxReleaseInventoryBytes: number;
+    readonly maxJsonDepth: 64;
+    readonly maxSchemaClosureBytes: number;
+    readonly maxSchemaRefHops: 16;
+    readonly maxSearchResults: 50;
+    readonly defaultSearchResults: 10;
+    readonly maxArgumentsBytes: number;
+    readonly maxResponseBytes: number;
+    readonly maxPages: 10;
+    readonly maxPaginationBytes: number;
+    readonly maxRedirects: 3;
+    readonly requestDeadlineMs: 30000;
+}>;
+/**
+ * Apply operator limits without allowing a caller to relax the signed-runtime
+ * availability envelope. Every supplied value must be a positive safe integer
+ * no greater than the portable default.
+ */
+export declare function resolveRuntimeLimits(overrides?: Partial<RuntimeLimits>): ResolvedRuntimeLimits;
+export {};

package/dist/runtime/versions.js

@@ -0,0 +1,86 @@
+/** Version of the portable runtime API and its persisted contract. */
+export const RUNTIME_CONTRACT_VERSION = 1;
+/** Version of immutable, signed logical release artifacts. */
+export const ARTIFACT_FORMAT_VERSION = 5;
+/** Version of the credential-free prepared-call representation. */
+export const PREPARED_CALL_VERSION = 2;
+/** Fixed UTF-8 envelope for a single catalog search query. */
+export const MAX_SEARCH_QUERY_BYTES = 4 * 1024;
+/** Fixed bounds for authenticated OpenAPI operation tags. */
+export const MAX_OPERATION_TAGS = 32;
+export const MAX_OPERATION_TAG_BYTES = 128;
+export const MAX_OPERATION_TAG_BYTES_TOTAL = 2 * 1024;
+export const DEFAULT_RUNTIME_LIMITS = Object.freeze({
+    maxManifestBytes: 8 * 1024 * 1024,
+    maxManifestRecords: 100_000,
+    maxRecordBytes: 1 * 1024 * 1024,
+    maxReleaseInventoryBytes: 128 * 1024 * 1024,
+    maxJsonDepth: 64,
+    maxSchemaClosureBytes: 4 * 1024 * 1024,
+    maxSchemaRefHops: 16,
+    maxSearchResults: 50,
+    defaultSearchResults: 10,
+    maxArgumentsBytes: 256 * 1024,
+    maxResponseBytes: 8 * 1024 * 1024,
+    maxPages: 10,
+    maxPaginationBytes: 16 * 1024 * 1024,
+    maxRedirects: 3,
+    requestDeadlineMs: 30_000,
+});
+const malformedOverridesMessage = "Runtime limits overrides must be an exact plain data object";
+function malformedOverrides() {
+    return new RangeError(malformedOverridesMessage);
+}
+/**
+ * Apply operator limits without allowing a caller to relax the signed-runtime
+ * availability envelope. Every supplied value must be a positive safe integer
+ * no greater than the portable default.
+ */
+export function resolveRuntimeLimits(overrides = {}) {
+    const resolved = {
+        ...DEFAULT_RUNTIME_LIMITS,
+    };
+    let supplied;
+    try {
+        if (overrides === null ||
+            typeof overrides !== "object" ||
+            Array.isArray(overrides)) {
+            throw malformedOverrides();
+        }
+        const prototype = Object.getPrototypeOf(overrides);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw malformedOverrides();
+        }
+        supplied = Reflect.ownKeys(overrides).map((candidate) => {
+            if (typeof candidate !== "string" ||
+                !Object.hasOwn(DEFAULT_RUNTIME_LIMITS, candidate)) {
+                throw malformedOverrides();
+            }
+            const descriptor = Object.getOwnPropertyDescriptor(overrides, candidate);
+            if (descriptor === undefined ||
+                !descriptor.enumerable ||
+                !("value" in descriptor)) {
+                throw malformedOverrides();
+            }
+            return [
+                candidate,
+                descriptor.value,
+            ];
+        });
+    }
+    catch {
+        throw malformedOverrides();
+    }
+    for (const [key, value] of supplied) {
+        const maximum = DEFAULT_RUNTIME_LIMITS[key];
+        if (value === undefined ||
+            typeof value !== "number" ||
+            !Number.isSafeInteger(value) ||
+            value < 1 ||
+            value > maximum) {
+            throw new RangeError(`Runtime limit ${key} must only lower its default`);
+        }
+        resolved[key] = value;
+    }
+    return Object.freeze(resolved);
+}

package/dist/safety.d.ts

@@ -0,0 +1,28 @@
+import type { Risk, Safety } from "./types.ts";
+/**
+ * Operation-id suffixes that are POSTs by protocol but reads by semantics,
+ * keyed by the API they were derived from. Scoping is load-bearing, not
+ * tidiness: `preview` and `query` are generic enough that another mounted API
+ * will have a genuinely mutating `POST .../query`, and a global list would
+ * classify it `read` — reachable through the no-approval read tool. An API
+ * with no entry here gets no overrides, so mutating methods stay `write`.
+ *
+ * This table is engine code, not artifact data: the server recomputes safety
+ * at load and honours a stored `read` on a mutating method only if the same
+ * `(api, suffix)` pair appears here.
+ */
+export declare const READ_OVERRIDES: Record<string, readonly string[]>;
+/** A batch endpoint bundles arbitrary sub-request methods, so it is never a read. */
+export declare function isBatch(path: string): boolean;
+/**
+ * Classifies an operation as read or write. Method is the default; the
+ * API's own override list corrects semantically-read POSTs. `$batch` always
+ * wins, and an unrecognised API never gets an override.
+ */
+export declare function classifySafety(method: string, path: string, operationId: string, api: string): Safety;
+/**
+ * Risk tier drives which write tool an operation is reachable through.
+ * Unknown privilege is treated as high: 22% of Graph has no permission
+ * mapping, and unmapped must not silently mean "safe".
+ */
+export declare function riskFor(safety: Safety, privilegeLevel: number | null, path: string): Risk;