@try-works/dsh-model-as-tool 0.1.3 → 0.4.0

package/lib/mcp/host-binding.js

@@ -22,8 +22,13 @@
  *
  * @module @try-works/dsh-model-as-tool/mcp/host-binding
  */
+import { Ajv } from 'ajv';
+import { redactText } from "./../receipt.js";
+import { accountInvocation, classifyOutcome, PhaseTimer, } from "../invocation-accounting.js";
 /** The reserved root field the host authors, never the implementation. */
 const RESERVED_META = 'meta';
+const ajv = new Ajv({ allErrors: true, strict: false, allowUnionTypes: true });
+const payloadValidators = new Map();
 /**
  * Derive the payload schema from a contract's final output schema (§16.4).
  *
@@ -44,6 +49,40 @@ export function derivePayloadSchema(outputSchema) {
     }
     return clone;
 }
+/** Render Ajv errors as bounded, path-qualified text. */
+function renderValidationErrors(errors) {
+    return (errors ?? [])
+        .map(error => `${error.instancePath || '(root)'} ${error.message ?? 'is invalid'}`)
+        .slice(0, 8)
+        .join('; ');
+}
+/** Validator for the externally advertised payload schema. */
+function payloadValidator(contract) {
+    const existing = payloadValidators.get(contract.contract);
+    if (existing !== undefined)
+        return existing;
+    const validate = ajv.compile(derivePayloadSchema(contract.outputSchema));
+    payloadValidators.set(contract.contract, validate);
+    return validate;
+}
+/**
+ * Convert a host result into the MCP payload shape and validate it.
+ *
+ * Host-native results may include the reserved `meta` envelope because the DSH tool contract
+ * validates that full value. MCP §16.4 publishes the payload schema with `meta` removed, so the
+ * external value must be the same payload with only that reserved field omitted. A malformed host
+ * result is returned as a tool error rather than a success-shaped `structuredContent`.
+ */
+function payloadForMcp(contract, value) {
+    const payload = typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? Object.fromEntries(Object.entries(value).filter(([key]) => key !== RESERVED_META))
+        : value;
+    const validate = payloadValidator(contract);
+    if (!validate(payload)) {
+        return { ok: false, reason: `tool result violates the advertised MCP output schema: ${renderValidationErrors(validate.errors)}` };
+    }
+    return { ok: true, value: payload };
+}
 /**
  * Build the MCP host surface over a DSH tool surface.
  *
@@ -78,7 +117,7 @@ export function createMcpHost(options) {
             }
             return out;
         },
-        async callTool(name, args, signal) {
+        async callTool(name, args, signal, caller) {
             const definition = options.surface.published.find(tool => tool.toolName === name);
             // A tool that is not EXPORTABLE must not be callable either. Looking only for
             // its presence in `published` would let a client invoke by name exactly the
@@ -92,14 +131,67 @@ export function createMcpHost(options) {
                     isError: true,
                 };
             }
-            const outcome = await options.surface.execute({
-                name,
-                arguments: args,
-                signal,
-                // Server-issued, monotonically increasing. A caller-supplied identity would
-                // let a caller forge a receipt (BASE-05).
-                callId: `mcp_${Date.now().toString(36)}_${(++counter).toString(36)}`,
-            });
+            /**
+             * ACCOUNTING, wrapped around the dispatch (OBS-02).
+             *
+             * The timer measures the external call's own phases and the outcome is classified
+             * from what was OBSERVED, not assumed — a cancelled external call must not be
+             * recorded as a failure, so the abort state is read from the caller's own signal.
+             * The CALLER'S grant identity rides the record (SEC-04): identity only, never the
+             * payload, so the operator can tell which client called.
+             */
+            const callId = `mcp_${Date.now().toString(36)}_${(++counter).toString(36)}`;
+            const timer = new PhaseTimer();
+            timer.begin('inference');
+            let outcome;
+            try {
+                outcome = await options.surface.execute({
+                    name,
+                    arguments: args,
+                    signal,
+                    // Server-issued, monotonically increasing. A caller-supplied identity would
+                    // let a caller forge a receipt (BASE-05).
+                    callId,
+                    ...caller === undefined ? {} : { caller },
+                });
+            }
+            catch (error) {
+                options.onAccounted?.(accountInvocation({
+                    receiptId: callId,
+                    timings: timer.finish(),
+                    failureClass: classifyOutcome({ ok: false, aborted: signal.aborted }),
+                    reason: error instanceof Error ? redactText(error.message) : String(error),
+                    input: args,
+                    engineVersion: options.engineVersion ?? 'unknown',
+                    ...caller === undefined ? {} : { grantId: caller.grantId, clientId: caller.clientId },
+                }));
+                throw error;
+            }
+            // CORRELATION (the round-65 review's finding): the contract payload's
+            // reserved meta carries the NATIVE receipt id the host dispatch issued, so
+            // the external accounting joins the native ring by that id when the result
+            // carries one — the two rings are no longer unjoinable. A value without
+            // meta (a tool that predates the meta contract) falls back to the
+            // server-issued id.
+            const nativeReceiptId = (() => {
+                const meta = outcome.value?.meta;
+                return typeof meta?.receiptId === 'string' ? meta.receiptId : callId;
+            })();
+            options.onAccounted?.(accountInvocation({
+                receiptId: nativeReceiptId,
+                timings: timer.finish(),
+                failureClass: classifyOutcome({
+                    ok: outcome.isError !== true,
+                    aborted: signal.aborted,
+                    refused: outcome.isError === true,
+                }),
+                ...outcome.isError === true && outcome.message !== undefined ? { reason: redactText(outcome.message) } : {},
+                input: args,
+                // An error carries no result, so nothing crossed the boundary as output.
+                output: outcome.isError === true ? undefined : outcome.value,
+                engineVersion: options.engineVersion ?? 'unknown',
+                ...caller === undefined ? {} : { grantId: caller.grantId, clientId: caller.clientId },
+            }));
             if (outcome.isError) {
                 return {
                     structured: null,
@@ -108,12 +200,13 @@ export function createMcpHost(options) {
                     isError: true,
                 };
             }
+            const payload = payloadForMcp(definition.contract, outcome.value ?? null);
+            if (!payload.ok) {
+                return { structured: null, text: payload.reason, isError: true };
+            }
             return {
-                // The canonical value, post-policy, exactly as the host returned it: a
-                // redaction here would be a content-only control, which MCP-11 says is not a
-                // confidentiality control at all.
-                structured: outcome.value ?? null,
-                text: renderBounded(outcome.value),
+                structured: payload.value,
+                text: renderBounded(payload.value),
             };
         },
     };

package/lib/mcp/http.d.ts

@@ -16,7 +16,10 @@
  *
  * @module @try-works/dsh-model-as-tool/mcp/http
  */
-import { type McpHost } from './server.ts';
+import type { McpHost } from './server.ts';
+import { type LocalOAuthServer } from './oauth.ts';
+import { type RateLimitPolicy } from './rate-limit.ts';
+import { type ClientGrantConfig } from './client-grant.ts';
 /** How the endpoint authenticates. */
 export interface StaticTokenAuth {
     /**
@@ -31,7 +34,31 @@ export interface StaticTokenAuth {
     readonly token: string;
     /** The caller identity recorded for the grant, for receipts and audit. */
     readonly clientId: string;
+    /**
+     * The durable credential store holding GENERATED static-token credentials (SEC-01).
+     *
+     * When present, a presented bearer token is also checked against the stored
+     * credentials (constant-time over the whole registry), and the matched client's
+     * OWN identity drives grants, receipts and rate limiting — never the configured
+     * primary `clientId`. Absent keeps the single-token behavior.
+     */
+    readonly registry?: import('./credential-store.ts').ClientCredentialStore;
+}
+/** The OAuth 2.1 resource-server scheme (P26-15). */
+export interface OAuthResourceServerAuth {
+    /**
+     * The scheme this endpoint implements: the local embedded authorization server
+     * issues HS256 credentials and this endpoint verifies them per RFC 6750, with
+     * audience and scope validation and per-client revocation.
+     */
+    readonly scheme: 'oauth-resource-server';
+    /** The embedded server: verifier, issuer and revocation registry. */
+    readonly server: LocalOAuthServer;
+    /** The scope a caller must hold to reach the MCP endpoint. */
+    readonly requiredScope?: readonly string[];
 }
+/** The union of supported authentication schemes. */
+export type HttpAuth = StaticTokenAuth | OAuthResourceServerAuth;
 /** Transport configuration. */
 export interface HttpTransportConfig {
     /** Path the endpoint serves. */
@@ -50,9 +77,31 @@ export interface HttpTransportConfig {
      * rather than a missing one, and CORS is not used as authentication anywhere.
      */
     readonly allowedOrigins: readonly string[];
-    readonly auth: StaticTokenAuth;
+    readonly auth: HttpAuth;
+    /**
+     * Per-client request rate limiting (AT-12).
+     *
+     * Absent means the DEFAULT policy applies — 60 requests per client per minute — so
+     * the transport is bounded by default rather than only when someone remembers to ask.
+     * A policy overrides the default; `false` disables limiting explicitly. The count is
+     * keyed on the AUTHENTICATED client identity (the static-token `clientId` or the OAuth
+     * subject), never on the socket address, and an unauthenticated request never moves a
+     * counter — counting auth failures would leak credential existence through 429 timing.
+     */
+    readonly rateLimit?: RateLimitPolicy | false;
+    /**
+     * Per-client external grants (SEC-04).
+     *
+     * After authentication, each client's grant is DERIVED here — from this
+     * configuration, the authenticated identity and the live published surface — and
+     * travels with the call as caller identity. Absent means the default: every client
+     * is granted exactly the live surface, recorded under its own `external:<clientId>`
+     * grant identity. A request body can never supply or extend a grant (BASE-05).
+     */
+    readonly grants?: ClientGrantConfig;
 }
-/** A conservative default: loopback, the illustrative port, a small body cap. */
+/** A conservative default: loopback, the illustrative port, a small body cap,
+ * and the default per-client rate limit (AT-12). */
 export declare const DEFAULT_HTTP_CONFIG: Omit<HttpTransportConfig, 'auth'>;
 /** One HTTP request, described rather than received. */
 export interface HttpRequestDescription {
@@ -75,35 +124,36 @@ export interface HttpResponseDescription {
 /** Whether an address is loopback. */
 export declare function isLoopback(address: string): boolean;
 /**
- * Build the request handler.
- *
- * Ordering is deliberate and matches P26-16's list: transport identity (loopback,
- * size, method, path) is settled before authentication, and authentication before
- * any protocol parsing. A request that is not from the loopback is refused without
- * its token being examined at all.
- * @param config - the transport configuration.
- * @param host - the MCP surface.
- * @returns the handler.
+ * Shared, guarded Fetch/stream core. The Node adapter's toNodeHandler is NOT
+ * used directly: its early 413 has a different wire envelope, it does not watch
+ * IncomingMessage.aborted, and its close/drain listeners are not removed.
+ * Use its official bounded Request conversion only AFTER our unchanged gate.
  */
+export declare function createHttpStreamHandler(config: HttpTransportConfig, host: McpHost): (request: HttpRequestDescription, signal?: AbortSignal) => Promise<Response>;
+/** Finite, materializing test facade; production sockets use the stream core. */
 export declare function createHttpHandler(config: HttpTransportConfig, host: McpHost): (request: HttpRequestDescription) => Promise<HttpResponseDescription>;
 /**
  * Whether this transport may claim OAuth conformance.
  *
- * It may not. `P26-15` permits a static-token mode while forbidding the claim, and
- * this returns false so a status report or a compatibility matrix cannot assert
- * otherwise by accident.
- * @returns always false, for the static-token scheme.
+ * The static-token scheme may not; the oauth-resource-server scheme may, because
+ * it verifies HS256 credentials, audience, expiry and scope against the embedded
+ * server and answers RFC 6750 challenges — a conformant subset, not an invention.
+ * The claim is per-DEPLOYMENT, which is what a status report needs: a host using
+ * static tokens must still report false.
+ * @param auth - the live auth configuration.
+ * @returns whether the live scheme may claim the OAuth 2.1 resource-server profile.
  */
-export declare function claimsOAuthConformance(): boolean;
+export declare function claimsOAuthConformance(auth: HttpAuth): boolean;
 /**
  * The authentication profile this transport reports.
  *
  * A machine-readable statement of what is actually implemented, so a client or an
  * operator can tell custom authentication from the OAuth profile without reading
  * the source.
+ * @param auth - the live auth configuration.
  * @returns the auth profile description.
  */
-export declare function authProfile(): Record<string, unknown>;
+export declare function authProfile(auth: HttpAuth): Record<string, unknown>;
 /** A bound endpoint. */
 export interface BoundEndpoint {
     /** The address actually bound, which for port 0 is the one the OS chose. */

package/lib/mcp/http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/mcp/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AASH,OAAO,EAAY,KAAK,OAAO,EAAE,MAAM,aAAa,CAAA;AAGpD,sCAAsC;AACtC,MAAM,WAAW,eAAe;IAC9B;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;IAC/B,qDAAqD;IACrD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B;AAED,+BAA+B;AAC/B,MAAM,WAAW,mBAAmB;IAClC,gCAAgC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,YAAY;IACZ,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,mDAAmD;IACnD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1C,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;CAC/B;AAED,iFAAiF;AACjF,eAAO,MAAM,mBAAmB,EAAE,IAAI,CAAC,mBAAmB,EAAE,MAAM,CAMjE,CAAA;AAED,wDAAwD;AACxD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,uCAAuC;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAA;IAC9D,oBAAoB;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,kDAAkD;IAClD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;CAC/B;AAED,yBAAyB;AACzB,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAED,sCAAsC;AACtC,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAMnD;AAgCD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,mBAAmB,EAC3B,IAAI,EAAE,OAAO,GACZ,CAAC,OAAO,EAAE,sBAAsB,KAAK,OAAO,CAAC,uBAAuB,CAAC,CAkGvE;AASD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAEhD;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQrD;AAED,wBAAwB;AACxB,MAAM,WAAW,aAAa;IAC5B,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,uCAAuC;IACvC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,yCAAyC;IACzC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACvB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,mBAAmB,EAC3B,IAAI,EAAE,OAAO,GACZ,OAAO,CAAC,aAAa,CAAC,CA8DxB"}
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/mcp/http.ts"],"names":[],"mappings":"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"}