@knitli/openapi-mcp 1.4.1 → 2.0.0

package/README.md

@@ -8,6 +8,9 @@ The executable artifact format is **5**, runtime contract **1**, and prepared-ca
 format **2**. This package is compiled TypeScript, separate from the Toolshed
 prompt plugins.
 
+The standalone `serve` CLI denies actions because it has no independent operator
+approval provider. Embedded hosts can supply one through `serveOpenApiStdio(config, approve)`.
+
 ## Install and check the runtime
 
 Local serving requires Node `>=24.16.0 <25`. Packed consumers exercise Node 24
@@ -186,7 +189,7 @@ These endpoints and client
 registration must be configured by the operator. The server uses authorization
 code PKCE with S256 and a temporary `127.0.0.1` callback listener on an ephemeral
 port at `/oauth/callback`; the identity provider must support that redirect.
-The client needs URL elicitation for OAuth and form elicitation for confirmation.
+The client needs URL elicitation for OAuth.
 Open the offered authorization URL, finish login, then follow the client's resume
 flow. Unsupported elicitation fails closed.
 
@@ -234,10 +237,33 @@ If an action reports `UPSTREAM_OUTCOME_UNKNOWN`, its error includes the exact
 the uncertain outcome; the server has consumed the authorization and does not
 automatically retry the action.
 
-Actions require server-controlled authorization bound to the prepared request,
-credential profile, release, and argument digest. Review the elicited destination,
-operation, effect, and arguments, then explicitly confirm. Rejection, cancellation,
-expiry, a changed request, or a changed credential binding prevents dispatch.
+The built-in CLI denies actions with `ACTION_DENIED`: MCP client confirmation
+does not prove independent operator approval. Configured `exactPolicies` cannot
+activate through client responses alone. Search and reads remain available.
+
+An embedding can pass the same approval callback as the second argument to
+`serveOpenApiStdio(config, approve)`, provide a host-owned `StatefulActionAuthorizer` through
+`createOpenApiMcpServer`, or use `createStdioActionAuthorizer(templates, approve)`
+from `@knitli/openapi-mcp/stdio`. The built-in elicitation authorizers require an
+`approve(presentation, details)` callback that authenticates operator approval outside
+the MCP requester. Without it they deny. The callback receives the frozen
+presentation bound to the exact prepared-call and credential-binding digests,
+including policy digest and expiry when activating standing authority. It must
+return literal `true` only for that approval; copying the client response or
+always returning `true` defeats this boundary. Requester confirmation is still
+required, but cannot replace the independent approval. Rejection, provider
+errors, expiry, changed bindings, and reused pending state prevent dispatch.
+
+The host-only `details` contains deeply frozen normalized argument values,
+the non-secret credential binding, the complete compiled policy when activating
+standing authority, the approval deadline, and an abort signal. These values
+remain untrusted data; the host must display them safely for informed operator
+approval. They are never included in the redacted MCP presentation. Providers
+must honor the signal and release prompts or other work when aborted. Expiry or
+request cancellation denies promptly; providers that ignore cancellation retain
+a bounded slot until they settle, and exhausted capacity fails closed.
+`compileExactPolicy` and its template/constraint types are exported from
+`@knitli/openapi-mcp/stdio` for constructing exact policies in embeddings.
 Destructive operations require the stronger destructive acknowledgment. An operator
 may supply narrowly bound `exactPolicies` for eligible create/update operations;
 they are not broad scopes or a general confirmation bypass. Do not construct policy
@@ -369,8 +395,9 @@ parent must be a real, owner-only directory. Generic startup errors are delibera
 to avoid exposing config secrets; validate with `parseOpenApiStdioConfig` in a
 controlled operator process. Missing environment credentials or OAuth elicitation
 must be resolved before a call can proceed. An action refused for lack of
-confirmation needs an elicitation-capable client or an eligible reviewed exact
-policy. Do not retry a changed action with old approval state.
+confirmation needs an embedding with an independent operator approval provider;
+the built-in CLI has no such channel. Do not retry a changed action with old
+approval state.
 
 From the repository, the package checks are:
 

package/dist/runtime/types.d.ts

@@ -323,7 +323,7 @@ export interface SafeApprovalPresentation {
     preparedCallDigest: Sha256;
 }
 export interface ActionAuthorizer {
-    authorize(call: PreparedCall, credential: CredentialAuthorizationBinding, context: AuthorizationContext): Promise<AuthorizationDecision>;
+    authorize(call: PreparedCall, credential: CredentialAuthorizationBinding, context: AuthorizationContext, signal?: AbortSignal): Promise<AuthorizationDecision>;
     consume(decision: AuthorizedActionDecision, call: PreparedCall, credential: CredentialAuthorizationBinding): Promise<void>;
 }
 export interface AuthorizedActionDecision {

package/dist/stdio/authorizer.d.ts

@@ -1,5 +1,5 @@
 import { type ServerContext } from "@modelcontextprotocol/server";
-import type { ActionAuthorizer, VerifiedActionRequestState } from "../runtime/types.ts";
+import type { ActionAuthorizer, CredentialAuthorizationBinding, JsonObject, SafeApprovalPresentation, VerifiedActionRequestState } from "../runtime/types.ts";
 import { type CompiledExactPolicy } from "./exact-policy.ts";
 interface InternalLimits {
     readonly pending: number;
@@ -16,10 +16,19 @@ export interface AuthorizerTestOptions {
 }
 export interface ClientElicitationAuthorizerOptions extends AuthorizerTestOptions {
     readonly elicitationAvailable: () => boolean;
+    /** Authenticate operator approval outside the MCP requester; never trust inputResponses. */
+    readonly approve?: (presentation: SafeApprovalPresentation, context: TrustedActionApprovalContext) => Promise<boolean>;
 }
-export interface ExactPolicyAuthorizerOptions extends AuthorizerTestOptions {
+/** Host-only values; never include these details in an MCP response. */
+export interface TrustedActionApprovalContext {
+    readonly normalizedArguments: Readonly<JsonObject>;
+    readonly credentialBinding: CredentialAuthorizationBinding;
+    readonly policy?: CompiledExactPolicy;
+    readonly expiresAt: number;
+    readonly signal: AbortSignal;
+}
+export interface ExactPolicyAuthorizerOptions extends ClientElicitationAuthorizerOptions {
     readonly templates: readonly CompiledExactPolicy[];
-    readonly elicitationAvailable: () => boolean;
 }
 export interface StatefulActionAuthorizer extends ActionAuthorizer {
     readonly requestStateVerifier: (state: string, context?: ServerContext) => Promise<VerifiedActionRequestState>;

package/dist/stdio/authorizer.js

@@ -153,17 +153,21 @@ function snapshotContext(context) {
 class LedgerActionAuthorizer {
     requestStateVerifier;
     #elicitationAvailable;
+    #approve;
     #now;
     #randomBytes;
     #limits;
     #policies;
     #pending = new Map();
+    #approving = new WeakSet();
+    #approvalsInFlight = 0;
     #receipts = new Map();
     #decisions = new WeakMap();
     #activations = new Map();
     #requestState;
     constructor(options, policies = []) {
         this.#elicitationAvailable = options.elicitationAvailable;
+        this.#approve = options.approve;
         this.#now = options.now ?? Date.now;
         this.#randomBytes = options.randomBytes ?? defaultRandom;
         this.#limits = normalizeLimits(options.limits);
@@ -177,13 +181,15 @@ class LedgerActionAuthorizer {
             now: this.#now,
             isPending: (payload) => {
                 const pending = this.#pending.get(payload.pendingId);
-                return pending !== undefined && exactPayloadMatch(payload, pending);
+                return (pending !== undefined &&
+                    !this.#approving.has(pending) &&
+                    exactPayloadMatch(payload, pending));
             },
         });
         this.requestStateVerifier = this.#requestState.verify;
         Object.freeze(this);
     }
-    async authorize(call, credential, context) {
+    async authorize(call, credential, context, signal) {
         let ownedContext;
         try {
             ownedContext = snapshotContext(context);
@@ -202,8 +208,10 @@ class LedgerActionAuthorizer {
             // Resume is deliberately handled before active-policy matching. An
             // echoed confirmation can never be bypassed by a newly active policy.
             if (ownedContext.kind === "resume") {
-                return await this.#resume(prepared, ownedCredential, ownedContext);
+                return await this.#resume(prepared, ownedCredential, ownedContext, signal);
             }
+            if (signal?.aborted)
+                return deny("Action request was cancelled");
             const now = this.#now();
             this.#prune(now);
             const policy = this.#matchingPolicy(prepared, now);
@@ -264,16 +272,19 @@ class LedgerActionAuthorizer {
             throw deniedError();
         });
     }
-    async #resume(call, credential, context) {
+    async #resume(call, credential, context, signal) {
         const payload = this.#requestState.read(context.requestState);
         if (payload === undefined)
             return deny("Invalid confirmation state");
         const pending = this.#pending.get(payload.pendingId);
-        if (pending === undefined || !exactPayloadMatch(payload, pending)) {
+        if (pending === undefined ||
+            this.#approving.has(pending) ||
+            !exactPayloadMatch(payload, pending)) {
             return deny("Invalid confirmation state");
         }
         const now = this.#now();
-        if (now >= pending.expiresAt ||
+        if (signal?.aborted ||
+            now >= pending.expiresAt ||
             call.preparedCallDigest !== pending.callDigest ||
             credential.bindingDigest !== pending.credentialBindingDigest) {
             this.#pending.delete(pending.pendingId);
@@ -318,37 +329,112 @@ class LedgerActionAuthorizer {
             ? this.#activationKey(policy.policyDigest, credential.bindingDigest)
             : undefined;
         const newActivation = activationKey !== undefined && !this.#activations.has(activationKey);
-        if (this.#receipts.size >= this.#limits.receipts ||
+        if (this.#approvalsInFlight >= this.#limits.pending ||
+            this.#receipts.size >= this.#limits.receipts ||
             (newActivation && this.#activations.size >= this.#limits.activations)) {
-            // Capacity denial is retriable and must not spend a valid human answer.
+            // Before independent approval, capacity denial leaves the pending request retriable.
             return deny("Authorization capacity is exhausted");
         }
-        let decision;
+        // Reserve the pending slot while the independent channel is awaiting approval.
+        this.#approving.add(pending);
         try {
-            decision = this.#mintReceipt(call, credential, policy ? "exact-policy" : "per-call", policy?.policyDigest, Math.min(now + RECEIPT_TTL_MS, activationExpiresAt ?? Number.MAX_SAFE_INTEGER));
+            if (!(await this.#awaitApproval(pending, call, credential, signal))) {
+                return deny("Trusted operator approval was not accepted");
+            }
+            const approvedAt = this.#now();
+            if (signal?.aborted ||
+                approvedAt >= pending.expiresAt ||
+                this.#pending.get(pending.pendingId) !== pending) {
+                return deny("Confirmation expired or no longer matches");
+            }
+            this.#prune(approvedAt);
+            if (activationKey !== undefined &&
+                !this.#activations.has(activationKey) &&
+                this.#activations.size >= this.#limits.activations) {
+                return deny("Authorization capacity is exhausted");
+            }
+            const decision = this.#mintReceipt(call, credential, policy ? "exact-policy" : "per-call", policy?.policyDigest, Math.min(approvedAt + RECEIPT_TTL_MS, activationExpiresAt ?? Number.MAX_SAFE_INTEGER));
+            if (policy !== undefined &&
+                activationKey !== undefined &&
+                activationExpiresAt !== undefined) {
+                this.#activations.set(activationKey, Object.freeze({
+                    policyDigest: policy.policyDigest,
+                    credentialBindingDigest: credential.bindingDigest,
+                    expiresAt: activationExpiresAt,
+                }));
+            }
+            return decision;
         }
-        catch {
-            return deny("Authorization capacity is exhausted");
+        finally {
+            if (this.#pending.get(pending.pendingId) === pending) {
+                this.#pending.delete(pending.pendingId);
+            }
         }
-        if (policy !== undefined &&
-            activationKey !== undefined &&
-            activationExpiresAt !== undefined) {
-            this.#activations.set(activationKey, Object.freeze({
-                policyDigest: policy.policyDigest,
-                credentialBindingDigest: credential.bindingDigest,
-                expiresAt: activationExpiresAt,
-            }));
+    }
+    async #awaitApproval(pending, call, credential, signal) {
+        const approve = this.#approve;
+        const expiresAt = Math.min(pending.expiresAt, pending.activationExpiresAt ?? pending.expiresAt);
+        const remaining = expiresAt - this.#now();
+        if (approve === undefined ||
+            signal?.aborted ||
+            !Number.isFinite(remaining) ||
+            remaining <= 0)
+            return false;
+        const controller = new AbortController();
+        let stop = () => { };
+        const interrupted = new Promise((resolve) => {
+            stop = () => {
+                controller.abort();
+                resolve(false);
+            };
+        });
+        const timer = setTimeout(stop, remaining);
+        timer.unref();
+        signal?.addEventListener("abort", stop, { once: true });
+        try {
+            const details = Object.freeze({
+                normalizedArguments: call.normalizedArguments,
+                credentialBinding: credential,
+                ...(pending.policy === undefined ? {} : { policy: pending.policy }),
+                expiresAt,
+                signal: controller.signal,
+            });
+            this.#approvalsInFlight++;
+            let result;
+            try {
+                result = approve(pending.presentation, details);
+            }
+            catch {
+                this.#approvalsInFlight--;
+                return false;
+            }
+            // Providers that ignore cancellation still occupy a bounded slot until they settle.
+            const approval = Promise.resolve(result).then((accepted) => {
+                this.#approvalsInFlight--;
+                return accepted === true;
+            }, () => {
+                this.#approvalsInFlight--;
+                return false;
+            });
+            return await Promise.race([approval, interrupted]);
+        }
+        finally {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", stop);
+            controller.abort();
         }
-        this.#pending.delete(pending.pendingId);
-        return decision;
     }
     async #requestConfirmation(call, credential, policy, activationExpiresAt) {
+        if (this.#approve === undefined) {
+            return deny("Trusted operator approval is unavailable");
+        }
         if (!this.#elicitationAvailable()) {
             return deny("Client elicitation is unavailable");
         }
         const now = this.#now();
         this.#prune(now);
-        if (this.#pending.size >= this.#limits.pending) {
+        if (this.#pending.size >= this.#limits.pending ||
+            this.#approvalsInFlight >= this.#limits.pending) {
             return deny("Authorization capacity is exhausted");
         }
         let pendingId;
@@ -365,21 +451,22 @@ class LedgerActionAuthorizer {
         if (policy !== undefined && activationExpiresAt === undefined) {
             return deny("Policy activation is invalid");
         }
+        const presentation = renderApproval(call, credential, policy === undefined
+            ? undefined
+            : {
+                policyDigest: policy.policyDigest,
+                expiresAt: activationExpiresAt,
+                template: policy.template,
+            });
         const pending = Object.freeze({
             pendingId,
             callDigest: call.preparedCallDigest,
             credentialBindingDigest: credential.bindingDigest,
             expiresAt,
+            presentation,
             ...(policy === undefined ? {} : { policy }),
             ...(activationExpiresAt === undefined ? {} : { activationExpiresAt }),
         });
-        const presentation = renderApproval(call, credential, policy === undefined
-            ? undefined
-            : {
-                policyDigest: policy.policyDigest,
-                expiresAt: activationExpiresAt,
-                template: policy.template,
-            });
         this.#pending.set(pendingId, pending);
         try {
             const requestState = await this.#requestState.mint({

package/dist/stdio/index.d.ts

@@ -1,6 +1,9 @@
 import { type StdioServerHandle } from "@modelcontextprotocol/server/stdio";
+import type { ClientElicitationAuthorizerOptions } from "./authorizer.ts";
 import { type OpenApiStdioConfig } from "./config.ts";
+export type { StatefulActionAuthorizer, TrustedActionApprovalContext, } from "./authorizer.ts";
 export { type OpenApiStdioConfig, parseOpenApiStdioConfig } from "./config.ts";
-export { createOpenApiMcpServer, type OpenApiMcpServerOptions, } from "./server.ts";
+export { type ArgumentConstraint, type CompiledExactPolicy, compileExactPolicy, type ExactPolicyTemplate, } from "./exact-policy.ts";
+export { createOpenApiMcpServer, createStdioActionAuthorizer, type OpenApiMcpServerOptions, } from "./server.ts";
 /** Owns process-local credentials/catalogs independently of disposable SDK probes. */
-export declare function serveOpenApiStdio(input: OpenApiStdioConfig): Promise<StdioServerHandle>;
+export declare function serveOpenApiStdio(input: OpenApiStdioConfig, approve?: ClientElicitationAuthorizerOptions["approve"]): Promise<StdioServerHandle>;

package/dist/stdio/index.js

@@ -10,9 +10,10 @@ import { compileExactPolicy } from "./exact-policy.js";
 import { createStdioSearchRuntime } from "./search.js";
 import { createOpenApiMcpServer, createStdioActionAuthorizer, } from "./server.js";
 export { parseOpenApiStdioConfig } from "./config.js";
-export { createOpenApiMcpServer, } from "./server.js";
+export { compileExactPolicy, } from "./exact-policy.js";
+export { createOpenApiMcpServer, createStdioActionAuthorizer, } from "./server.js";
 /** Owns process-local credentials/catalogs independently of disposable SDK probes. */
-export async function serveOpenApiStdio(input) {
+export async function serveOpenApiStdio(input, approve) {
     const config = parseOpenApiStdioConfig(input);
     const stores = [];
     const providers = [];
@@ -57,7 +58,7 @@ export async function serveOpenApiStdio(input) {
         // GenerationStore provides per-catalog CAS, not a cross-catalog transaction.
         for (const entry of admitted)
             await admitExecutableRelease({ store: entry.store, trust: config.trust, generations, limits }, entry.verified);
-        const authorizer = createStdioActionAuthorizer(templates);
+        const authorizer = createStdioActionAuthorizer(templates, approve);
         const routes = [];
         for (const profile of config.profiles) {
             const catalogs = admitted.filter((entry) => entry.config.profileId === profile.profileId);

package/dist/stdio/server.d.ts

@@ -2,11 +2,11 @@ import { McpServer } from "@modelcontextprotocol/server";
 import type { CredentialProvider, OpenApiRuntime } from "../runtime/types.ts";
 import { type RuntimeLimits } from "../runtime/versions.ts";
 import type { createLocalDispatchBoundary } from "../sqlite/guarded-fetch.ts";
-import { type StatefulActionAuthorizer } from "./authorizer.ts";
+import { type ClientElicitationAuthorizerOptions, type StatefulActionAuthorizer } from "./authorizer.ts";
 import type { CompiledExactPolicy } from "./exact-policy.ts";
 type Boundary = ReturnType<typeof createLocalDispatchBoundary>;
 /** One authorizer across factory instances preserves opaque continuation ownership. */
-export declare function createStdioActionAuthorizer(templates?: readonly CompiledExactPolicy[]): StatefulActionAuthorizer;
+export declare function createStdioActionAuthorizer(templates?: readonly CompiledExactPolicy[], approve?: ClientElicitationAuthorizerOptions["approve"]): StatefulActionAuthorizer;
 export interface OpenApiServerRoute {
     readonly catalogId: string;
     readonly releaseId: string;

package/dist/stdio/server.js

@@ -8,11 +8,18 @@ import { resolveRuntimeLimits, } from "../runtime/versions.js";
 import { createClientElicitationActionAuthorizer, createExactPolicyActionAuthorizer, } from "./authorizer.js";
 const requestCapabilities = new AsyncLocalStorage();
 /** One authorizer across factory instances preserves opaque continuation ownership. */
-export function createStdioActionAuthorizer(templates = []) {
+export function createStdioActionAuthorizer(templates = [], approve) {
     const elicitationAvailable = () => requestCapabilities.getStore()?.form === true;
     return templates.length
-        ? createExactPolicyActionAuthorizer({ templates, elicitationAvailable })
-        : createClientElicitationActionAuthorizer({ elicitationAvailable });
+        ? createExactPolicyActionAuthorizer({
+            templates,
+            elicitationAvailable,
+            approve,
+        })
+        : createClientElicitationActionAuthorizer({
+            elicitationAvailable,
+            approve,
+        });
 }
 const argumentsSchema = z.strictObject({
     path: z.record(z.string(), z.json()).optional(),
@@ -264,7 +271,7 @@ async function executeAction(route, authorizer, input, ctx) {
             kind: "resume",
             requestState: state,
             inputResponses: ctx.mcpReq.inputResponses,
-        });
+        }, ctx.mcpReq.signal);
     if (decision.status === "denied")
         throw new OpenApiMcpError("ACTION_DENIED");
     if (decision.status === "input-required")
@@ -335,7 +342,7 @@ export function createOpenApiMcpServer(options) {
         return outcome(await route.boundary.transport.dispatchRead(plan), snapshot);
     }));
     server.registerTool("action", {
-        description: "Request one verified action with client approval or an explicitly activated exact policy.",
+        description: "Request one verified action with independent operator approval or an explicitly activated exact policy. Actions are denied when a trusted approval provider is unavailable.",
         inputSchema: actionSchema,
     }, (input, ctx) => handle(ctx, () => executeAction(routeFor(input.operation), options.authorizer, input, ctx)));
     return server;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@knitli/openapi-mcp",
   "private": false,
-  "version": "1.4.1",
+  "version": "2.0.0",
   "type": "module",
   "description": "Compile signed OpenAPI catalogs and serve verified search and authorized API calls over MCP.",
   "license": "MIT OR Apache-2.0",