@try-works/dsh-tool-mode 0.0.0-stage → 0.5.44

package/lib/mcp/credential-store.js

@@ -0,0 +1,461 @@
+/**
+ * The operator-owned client credential store (SEC-01).
+ *
+ * SEC-01's generation clause: credentials are generated with high-entropy secrets,
+ * stored with suitable host protection (owner-only), and revocable independently per
+ * application. Before this module the OAuth client registry was in-memory only and the
+ * static-token mode accepted exactly one configured token — nothing could GENERATE a
+ * credential and nothing persisted it, so a restart lost every client and a generated
+ * secret could not exist.
+ *
+ * This store is the durable half. The security properties it now holds, each pinned
+ * by test:
+ *
+ * - one JSON document per deployment (`credentials.json`), written to a CRYPTO-RANDOM
+ *   temp name opened EXCLUSIVELY (`wx`) — a predictable temp name is a hardlink target
+ *   an attacker on the same account can pre-plant, so the name is unguessable and a
+ *   pre-existing name FAILS instead of being overwritten — then fsync'd and atomically
+ *   renamed over the document. A rename replaces a planted SYMLINK at the target rather
+ *   than following it;
+ * - Windows: an EXPLICIT owner-only DACL is applied to the temp file BEFORE the rename
+ *   (inheritance removed, the owner alone granted full control) and the store fails
+ *   closed when the ACL cannot be secured. POSIX mode 0600 alone is not sufficient on
+ *   Windows, and "the profile directory inherits it" is not a control;
+ * - MUTATIONS serialize through an in-process mutex AND an exclusive sidecar lock file,
+ *   and re-read the document inside the critical section — two concurrent writers can
+ *   no longer each persist a snapshot that silently drops the other's entry;
+ * - a CORRUPT or unreadable document makes MUTATIONS fail closed (a generation refused,
+ *   the bytes untouched) while READS deny: authentication cannot succeed on a store
+ *   the host cannot vouch for, and a generation can never overwrite a malformed
+ *   document "as if empty". A MISSING document is the only empty start;
+ * - reads are served from the FILE, fresh on every lookup, so a revocation through any
+ *   surface takes effect on the very next request;
+ * - `bySecret` matches STATIC-TOKEN credentials only: an OAuth resource-server secret
+ *   presented as a static bearer must never authenticate through this path (scheme
+ *   confusion);
+ * - the secret is compared CONSTANT-TIME (SHA-256 digests over equal-length input);
+ * - every mutation throws when it cannot persist: a generation that cannot be written
+ *   must leave nothing usable rather than an in-memory-only credential that a restart
+ *   silently forgets (fail-closed, SEC-01).
+ *
+ * @module @try-works/dsh-tool-mode/mcp/credential-store
+ */
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { closeSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { basename, dirname, join, parse } from 'node:path';
+import { homedir } from 'node:os';
+/** A document that EXISTS but cannot be vouched for. Mutations refuse; reads deny. */
+export class CorruptCredentialStoreError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CorruptCredentialStoreError';
+    }
+}
+/**
+ * Generate a fresh client credential directly over the store (the primitive
+ * the human-only CLI and tests use — the model-visible `model_tools` surface
+ * refuses generation entirely, SEC-01: the secret must never reach a model).
+ * @param store - the durable store.
+ * @param options - clientId (≤64 chars), scheme, scope.
+ * @returns the credential with the secret exactly once.
+ */
+export function generateCredential(store, options) {
+    if (typeof options.clientId !== 'string' || options.clientId.length === 0 || options.clientId.length > 64) {
+        throw new Error('clientId must be a non-empty string of at most 64 characters');
+    }
+    if (options.scheme !== 'static-token' && options.scheme !== 'oauth-resource-server') {
+        throw new Error('scheme must be static-token or oauth-resource-server');
+    }
+    if (store.get(options.clientId) !== undefined) {
+        throw new Error(`a credential for ${JSON.stringify(options.clientId)} already exists; revoke it first`);
+    }
+    const secret = randomBytes(32).toString('base64url');
+    const scope = options.scope === undefined || options.scope.length === 0 ? ['mcp:call'] : [...options.scope];
+    const createdAt = new Date().toISOString();
+    store.upsert({ clientId: options.clientId, secret, scheme: options.scheme, scope, createdAt });
+    return { clientId: options.clientId, secret, scheme: options.scheme, scope, createdAt };
+}
+/**
+ * Derive the default credential-store file, next to the host's own state
+ * (SEC-01: owner-only home protection).
+ * @param env - the environment to read; defaults to the process environment.
+ * @returns the absolute path.
+ */
+export function defaultCredentialStoreFile(env = process.env) {
+    const home = env.DSH_HOME !== undefined && env.DSH_HOME.length > 0
+        ? env.DSH_HOME
+        : join(homedir(), '.dsh');
+    return join(home, 'model-as-tool', 'credentials.json');
+}
+/**
+ * Apply an explicit owner-only DACL to one file on Windows (icacls: inheritance
+ * removed, the current owner alone granted full control), and fail closed when
+ * the ACL cannot be secured. On POSIX the caller's 0600 mode bits are the
+ * control and this is a no-op.
+ * @param file - the file to secure, BEFORE it is published (renamed) into place.
+ */
+export function applyOwnerOnlyDacl(file) {
+    if (process.platform !== 'win32')
+        return;
+    const owner = process.env.USERNAME;
+    if (owner === undefined || owner.length === 0) {
+        throw new Error('the credential file ACL cannot be secured: no Windows USERNAME to grant ownership to');
+    }
+    const result = spawnSync('icacls', [file, '/inheritance:r', '/grant:r', `${owner}:(F)`], {
+        windowsHide: true,
+        encoding: 'utf8',
+    });
+    if (result.status !== 0) {
+        throw new Error(`the credential file ACL cannot be secured: icacls failed with status ${result.status ?? 'unknown'}`
+            + `: ${(result.stderr ?? result.stdout ?? '').trim()}`);
+    }
+}
+/**
+ * Refuse a reparse point (symlink or Windows junction) at a path the store is
+ * about to write THROUGH: a junctioned credential home is an untrusted target,
+ * and the store fails closed rather than persisting plaintext secrets into a
+ * location the operator did not own by construction.
+ * @param path - the directory (or file) to check.
+ */
+function assertNoReparsePoint(path) {
+    try {
+        if (lstatSync(path).isSymbolicLink()) {
+            throw new Error(`the credential store refuses ${path}: it is a symbolic link or junction (untrusted target)`);
+        }
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+}
+/**
+ * The trusted root the credential store lives under by default: DSH_HOME when
+ * set, otherwise `~/.dsh`. Ancestor validation walks from HERE down to the
+ * store directory — system junctions ABOVE the trusted root are never part of
+ * the trust question. A store outside the trusted root (an explicit --store)
+ * is validated from the filesystem root instead, and any reparse point in the
+ * chain fails it closed.
+ */
+function trustedCredentialRoot(env = process.env) {
+    return env.DSH_HOME !== undefined && env.DSH_HOME.length > 0
+        ? env.DSH_HOME
+        : join(homedir(), '.dsh');
+}
+/**
+ * Walk EVERY ancestor component from the bounded trusted root down to the
+ * store directory and refuse any reparse point — not just the immediate parent:
+ * a junction higher in the chain redirects the whole write just as surely.
+ * @param file - the credential document path.
+ */
+function assertTrustedStoreAncestors(file) {
+    const dir = dirname(file);
+    const root = trustedCredentialRoot();
+    const start = dir === root || dir.startsWith(root + '\\') || dir.startsWith(root + '/')
+        ? root
+        : parse(dir).root;
+    // Collect the ancestor chain from `start` down to `dir` (bounded by the path
+    // depth, which is small), then check each component that EXISTS.
+    const chain = [];
+    let cursor = dir;
+    while (cursor !== start && cursor !== parse(cursor).root && cursor.length > 0) {
+        chain.push(cursor);
+        const parent = dirname(cursor);
+        if (parent === cursor)
+            break;
+        cursor = parent;
+    }
+    chain.push(cursor);
+    for (const component of chain.reverse()) {
+        assertNoReparsePoint(component);
+    }
+}
+/** Is the pid alive? `undefined` means "cannot tell" — callers fail closed. */
+function isProcessAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return undefined;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ESRCH')
+            return false;
+        return undefined;
+    }
+}
+/** Read a lock record; undefined when the lock is unreadable or corrupt. */
+function readLockRecord(lockPath) {
+    try {
+        const parsed = JSON.parse(readFileSync(lockPath, 'utf8'));
+        if (typeof parsed !== 'object' || parsed === null)
+            return undefined;
+        const candidate = parsed;
+        if (typeof candidate.token !== 'string' || candidate.token.length === 0
+            || typeof candidate.pid !== 'number' || typeof candidate.at !== 'number') {
+            return undefined;
+        }
+        return { token: candidate.token, pid: candidate.pid, at: candidate.at };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A real blocking sleep, without burning the CPU. */
+function sleep(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/**
+ * Create (or open) the file-backed credential store.
+ * @param file - the absolute path of the credentials document.
+ * @param hooks - TEST-ONLY lock hooks; production passes nothing.
+ * @returns the store.
+ */
+export function createFileCredentialStore(file, hooks = {}) {
+    const staleLockMs = hooks.staleLockMs ?? 30_000;
+    const lockDeadlineMs = hooks.lockDeadlineMs ?? 10_000;
+    const probeAlive = hooks.isProcessAlive ?? isProcessAlive;
+    /**
+     * The cross-process lock: an unguessable ownership token plus the holder's
+     * pid, so a stale lock is only ever stolen from a holder PROVEN DEAD. A live
+     * holder is never stolen from, unknown liveness fails closed (the contender
+     * keeps waiting, then refuses), and release removes ONLY a token-owned lock
+     * — a successor's lock is never touched.
+     */
+    const acquireFileLock = () => {
+        const lockPath = `${file}.lock`;
+        const token = randomBytes(16).toString('hex');
+        const deadline = Date.now() + lockDeadlineMs;
+        for (;;) {
+            try {
+                const fd = openSync(lockPath, 'wx');
+                try {
+                    writeFileSync(fd, JSON.stringify({ token, pid: process.pid, at: Date.now() }), 'utf8');
+                }
+                finally {
+                    closeSync(fd);
+                }
+                const release = () => {
+                    // Release ONLY a token-owned lock: if the record no longer carries OUR
+                    // token, the lock is a successor's (or was removed) — never remove it.
+                    const held = readLockRecord(lockPath);
+                    if (held === undefined || held.token !== token)
+                        return;
+                    try {
+                        rmSync(lockPath, { force: true });
+                    }
+                    catch {
+                        // Already gone: nothing to release.
+                    }
+                };
+                return { token, release };
+            }
+            catch (error) {
+                const code = error.code;
+                /**
+                 * Windows reports EPERM rather than EEXIST when `open(..., 'wx')` loses the
+                 * race to an existing lock file (the two-process test caught this as an
+                 * occasional hard failure). Both mean "somebody holds it": treat EPERM as
+                 * contention and let the normal holder/stale logic decide, never as a
+                 * permanent failure that drops a writer.
+                 */
+                if (code !== 'EEXIST' && code !== 'EPERM')
+                    throw error;
+                // A held lock: examine WHO holds it before even considering theft.
+                const held = readLockRecord(lockPath);
+                if (held !== undefined) {
+                    const age = Date.now() - held.at;
+                    const alive = probeAlive(held.pid);
+                    if (alive === false && age > staleLockMs) {
+                        // The holder is PROVEN DEAD and the lock is stale: take it over.
+                        // (An unreadable/corrupt record is NOT this case — fail closed below.)
+                        try {
+                            rmSync(lockPath, { force: true });
+                        }
+                        catch {
+                            // Released between the read and the removal: retry the acquire.
+                        }
+                        continue;
+                    }
+                    // A LIVE holder (or unknown liveness) is never stolen from — the
+                    // contender waits, then fails closed at the deadline.
+                }
+                if (Date.now() > deadline) {
+                    throw new Error('the credential store is locked by another writer; the mutation was not attempted');
+                }
+                sleep(25);
+            }
+        }
+    };
+    /** Read the CURRENT document. STRICT for mutations: corruption refuses them. */
+    const read = (strict) => {
+        let text;
+        try {
+            text = readFileSync(file, 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                // A MISSING document is the only empty start. Nothing else is.
+                return new Map();
+            }
+            if (strict) {
+                throw new CorruptCredentialStoreError(`the credentials document cannot be read and no mutation will guess its contents: `
+                    + `${error instanceof Error ? error.message : String(error)}`);
+            }
+            return new Map();
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch (error) {
+            if (strict) {
+                throw new CorruptCredentialStoreError(`the credentials document is not valid JSON and will not be overwritten as if empty: `
+                    + `${error instanceof Error ? error.message : String(error)}`);
+            }
+            return new Map();
+        }
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+            if (strict)
+                throw new CorruptCredentialStoreError('the credentials document is not a JSON object');
+            return new Map();
+        }
+        const document = parsed;
+        if (!Array.isArray(document.clients)) {
+            if (strict)
+                throw new CorruptCredentialStoreError('the credentials document has no clients array');
+            return new Map();
+        }
+        const next = new Map();
+        for (const entry of document.clients) {
+            const candidate = entry;
+            if (typeof candidate.clientId !== 'string' || typeof candidate.secret !== 'string'
+                || (candidate.scheme !== 'static-token' && candidate.scheme !== 'oauth-resource-server')
+                || !Array.isArray(candidate.scope)) {
+                // A malformed ENTRY corrupts the document: a mutation would silently drop
+                // it on the next persist, and authentication cannot vouch for it either.
+                if (strict) {
+                    throw new CorruptCredentialStoreError(`the credentials document carries a malformed client entry (id ${JSON.stringify(candidate.clientId)})`);
+                }
+                return new Map();
+            }
+            next.set(candidate.clientId, candidate);
+        }
+        return next;
+    };
+    const persist = (clients, token) => {
+        const document = {
+            version: 1,
+            clients: [...clients.values()],
+        };
+        // SEC-01: the temp name is crypto-random and opened EXCLUSIVELY — a planted
+        // hardlink/symlink at a predictable name cannot be overwritten, and a
+        // pre-existing name fails the write instead of clobbering an unrelated file.
+        const temp = join(dirname(file), `.${basename(file)}.tmp-${randomBytes(12).toString('hex')}`);
+        const fd = openSync(temp, 'wx', 0o600);
+        try {
+            // The file WE created must be a regular file: 'wx' already excludes
+            // pre-existing entries (hardlinks and junctions included); this is the
+            // belt-and-braces check.
+            const created = lstatSync(temp);
+            if (!created.isFile() || created.isSymbolicLink()) {
+                throw new Error(`the credential temp file is not a regular file: refusing to write plaintext secrets through it`);
+            }
+            // Owner-only BEFORE the first secret byte: the empty file's ACL is
+            // secured while it holds NOTHING, so no plaintext ever exists under an
+            // inherited broad ACL (the reviewer's inherited Everyone:R +
+            // Authenticated Users:M finding).
+            applyOwnerOnlyDacl(temp);
+            writeFileSync(fd, JSON.stringify(document, null, 2), 'utf8');
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        // The publish is refused unless OUR token still owns the lock: a writer
+        // that somehow lost its lock must never publish a stale snapshot over the
+        // successor's state.
+        const held = readLockRecord(`${file}.lock`);
+        if (held === undefined || held.token !== token) {
+            rmSync(temp, { force: true });
+            throw new Error('the credential store lost its write lock; the publish is refused');
+        }
+        renameSync(temp, file);
+    };
+    /**
+     * One serialized mutation: the ancestor chain is checked for reparse points
+     * BEFORE anything (lock file included) is written through it, the parent
+     * directory is created (a first-generation store starts from nothing), then
+     * the file lock excludes other processes and the read-modify-write runs
+     * fully SYNCHRONOUSLY inside it — Node's single thread makes the section
+     * atomic for this process too, so two concurrent writers cannot each persist
+     * a snapshot that drops the other's entry or resurrects a just-revoked
+     * credential.
+     */
+    const mutation = (body) => {
+        assertTrustedStoreAncestors(file);
+        mkdirSync(dirname(file), { recursive: true });
+        const { token, release } = acquireFileLock();
+        try {
+            const clients = read(true);
+            // TEST-ONLY: simulate a writer paused after its strict read, holding the
+            // lock while other processes contend (the reviewer's 31 s repro, without
+            // the wait).
+            if (hooks.holdLockAfterReadMs !== undefined)
+                sleep(hooks.holdLockAfterReadMs);
+            return body(clients, token);
+        }
+        finally {
+            release();
+        }
+    };
+    return {
+        file,
+        list() {
+            // Reads DENY on corruption (empty list) rather than crash the auth path.
+            return [...read(false).values()];
+        },
+        get(clientId) {
+            return read(false).get(clientId);
+        },
+        bySecret(secret) {
+            // CONSTANT-TIME over the STATIC-TOKEN entries: the digest equalizes lengths,
+            // and the loop never exits early on a match. OAuth resource-server secrets
+            // are NEVER matched here — scheme confusion would let an OAuth secret pass
+            // as a static bearer.
+            const digest = createHash('sha256').update(secret).digest();
+            let found;
+            for (const candidate of read(false).values()) {
+                if (candidate.scheme !== 'static-token')
+                    continue;
+                const candidateDigest = createHash('sha256').update(candidate.secret).digest();
+                if (timingSafeEqual(digest, candidateDigest))
+                    found = candidate;
+            }
+            return found;
+        },
+        upsert(credential) {
+            mutation((clients, token) => {
+                // PERSIST FIRST inside the critical section: a credential that cannot be
+                // written must never be registered as usable anywhere (SEC-01).
+                clients.set(credential.clientId, credential);
+                persist(clients, token);
+            });
+        },
+        delete(clientId) {
+            mutation((clients, token) => {
+                if (!clients.has(clientId))
+                    return;
+                clients.delete(clientId);
+                persist(clients, token);
+            });
+        },
+    };
+}
+/** Remove a credential store file, for tests that need a fresh deployment. */
+export function removeCredentialStoreFile(file) {
+    rmSync(file, { force: true });
+    rmSync(`${file}.lock`, { force: true });
+}
+//# sourceMappingURL=credential-store.js.map

package/lib/mcp/export-policy.d.ts

@@ -0,0 +1,25 @@
+/**
+ * BASE-06 — the MCP export allowlist is a separate control from the native
+ * `models` selection.
+ *
+ * `undefined` or a list containing `*` means the deployment did not configure a
+ * separate MCP allowlist and preserves the existing surface. An EMPTY allowlist is
+ * meaningful: it exports no inference tools. A named allowlist admits exactly those
+ * names.
+ *
+ * Denied rows are returned as WITHHELD rows (with a reason) rather than removed,
+ * so the existing MCP host status surface can explain why a tool is absent.
+ *
+ * @module @try-works/dsh-tool-mode/mcp/export-policy
+ */
+import type { PublishedTool } from './host-binding.ts';
+/** The stable reason recorded for a tool denied by the allowlist. */
+export declare const MCP_EXPORT_DENIED_REASON = "the MCP export allowlist does not name this tool";
+/**
+ * Apply the operator's MCP export allowlist to the assembled publication surface.
+ * @param published - every tool the host could publish.
+ * @param allowlist - configured names; undefined means no separate MCP restriction.
+ * @returns the same rows, with denied rows carrying a withholding reason.
+ */
+export declare function applyMcpExportPolicy(published: readonly PublishedTool[], allowlist: readonly string[] | undefined): readonly PublishedTool[];
+//# sourceMappingURL=export-policy.d.ts.map

package/lib/mcp/export-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export-policy.d.ts","sourceRoot":"","sources":["../../src/mcp/export-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAEtD,qEAAqE;AACrE,eAAO,MAAM,wBAAwB,qDAAqD,CAAA;AAE1F;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,SAAS,aAAa,EAAE,EACnC,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GACvC,SAAS,aAAa,EAAE,CAM1B"}

package/lib/mcp/export-policy.js

@@ -0,0 +1,31 @@
+/**
+ * BASE-06 — the MCP export allowlist is a separate control from the native
+ * `models` selection.
+ *
+ * `undefined` or a list containing `*` means the deployment did not configure a
+ * separate MCP allowlist and preserves the existing surface. An EMPTY allowlist is
+ * meaningful: it exports no inference tools. A named allowlist admits exactly those
+ * names.
+ *
+ * Denied rows are returned as WITHHELD rows (with a reason) rather than removed,
+ * so the existing MCP host status surface can explain why a tool is absent.
+ *
+ * @module @try-works/dsh-tool-mode/mcp/export-policy
+ */
+/** The stable reason recorded for a tool denied by the allowlist. */
+export const MCP_EXPORT_DENIED_REASON = 'the MCP export allowlist does not name this tool';
+/**
+ * Apply the operator's MCP export allowlist to the assembled publication surface.
+ * @param published - every tool the host could publish.
+ * @param allowlist - configured names; undefined means no separate MCP restriction.
+ * @returns the same rows, with denied rows carrying a withholding reason.
+ */
+export function applyMcpExportPolicy(published, allowlist) {
+    if (allowlist === undefined || allowlist.includes('*'))
+        return published;
+    const allowed = new Set(allowlist);
+    return published.map(tool => allowed.has(tool.toolName)
+        ? tool
+        : { ...tool, notExportableReason: MCP_EXPORT_DENIED_REASON });
+}
+//# sourceMappingURL=export-policy.js.map

package/lib/mcp/host-binding.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Binding the MCP surface to the real DSH tool registry (MCP-08, MCP-09, MCP-12).
+ *
+ * Two requirements shape this module, and both are about where data comes from
+ * rather than what it looks like:
+ *
+ * - **MCP-09**: DSH's model-facing `schemas()` projection INTENTIONALLY omits the
+ *   output schema, so an export built from it would publish a tool with no declared
+ *   result shape. The canonical schemas therefore come from the CONTRACTS, which is
+ *   the only place that has them; `schemas()` is never consulted for a schema.
+ * - **MCP-08**: invocation goes through the host's `execute` path with a
+ *   server-issued call identity and the caller's abort signal. Resolving a tool and
+ *   calling it directly would bypass the grant, the receipt and the result policy —
+ *   the three things the host path exists to apply — so this module is given an
+ *   executor rather than a registry to reach into.
+ *
+ * §16.4 defines the payload derivation precisely: an implementation returns the
+ * domain payload with the reserved root `meta` OMITTED, and the payload schema is
+ * the final tool schema with only that property and its required entry removed.
+ * Everything else is preserved, because a schema that quietly dropped more would
+ * under-declare the result.
+ *
+ * @module @try-works/dsh-tool-mode/mcp/host-binding
+ */
+import type { ToolContract } from '@try-works/tool-mode-contracts';
+import type { ExternalCaller } from './client-grant.ts';
+import type { McpHost } from './server.ts';
+import { type InvocationAccounting } from '../invocation-accounting.ts';
+/**
+ * Derive the payload schema from a contract's final output schema (§16.4).
+ *
+ * Only the reserved `meta` property and its `required` entry are removed. The rest
+ * of the schema — including constraints on the remaining properties — is preserved
+ * verbatim, because removing anything else would advertise a looser result than the
+ * contract actually enforces.
+ * @param outputSchema - the contract's output schema, including `meta`.
+ * @returns the payload schema.
+ */
+export declare function derivePayloadSchema(outputSchema: Readonly<Record<string, unknown>>): Record<string, unknown>;
+/** One published tool as the host knows it. */
+export interface PublishedTool {
+    /** The tool name a caller uses. */
+    readonly toolName: string;
+    /** The contract it implements, which carries the canonical schemas. */
+    readonly contract: ToolContract;
+    /**
+     * Why this tool is not exportable, when it is not (MCP-12).
+     *
+     * A host tool using a non-JSON callback, a UI-only API, an unsupported attachment
+     * or a non-exportable policy must be REJECTED WITH A REASON rather than partly
+     * serialized, so the reason travels with the tool instead of being discovered by a
+     * caller whose call fails in a way nobody can explain.
+     */
+    readonly notExportableReason?: string;
+}
+/** What the binding needs from the host. */
+export interface HostSurface {
+    /** The tools the host currently publishes. */
+    readonly published: readonly PublishedTool[];
+    /**
+     * Tools the host deliberately WITHHELD, by name, with the recorded reason (MCP-12).
+     *
+     * A caller that guesses a withheld name must learn why it is absent rather than
+     * receiving the same `unknown tool` answer as a name that never existed. The map
+     * is the publication decision, not a second lookup: it may include names omitted
+     * from `published` entirely.
+     */
+    readonly withheld?: ReadonlyMap<string, string>;
+    /**
+     * Execute one tool through the host path (MCP-08).
+     *
+     * Takes a server-issued call identity and the caller's signal; the implementation
+     * MUST route this through the same execution path a native call uses.
+     */
+    execute(request: {
+        readonly name: string;
+        readonly arguments: Readonly<Record<string, unknown>>;
+        readonly signal: AbortSignal;
+        /** Server-issued. A caller-supplied id would let a caller forge a receipt. */
+        readonly callId: string;
+        /**
+         * The AUTHENTICATED external caller and its derived grant (SEC-04).
+         *
+         * Absent for calls with no client identity (native paths). When present, the
+         * implementation MUST authorize the call against THIS caller's grant rather than
+         * the host's own — an external client is not the operator.
+         */
+        readonly caller?: ExternalCaller;
+    }): Promise<{
+        readonly isError: boolean;
+        readonly value?: unknown;
+        readonly message?: string;
+    }>;
+}
+/**
+ * Build the MCP host surface over a DSH tool surface.
+ *
+ * @param options - the host surface and this server's identity.
+ * @returns the MCP host the dispatch layer consumes.
+ */
+export declare function createMcpHost(options: {
+    readonly surface: HostSurface;
+    readonly serverInfo: {
+        readonly name: string;
+        readonly version: string;
+    };
+    /** Called for each tool withheld, so a reason is recorded rather than lost. */
+    readonly onWithheld?: (tool: PublishedTool) => void;
+    /**
+     * Called once per EXTERNAL invocation, with its accounting (OBS-02).
+     *
+     * Wired EXPLICITLY because an external call is not automatically an agent-loop
+     * transcript: DSH observes `ctx.tools.execute`, and an MCP caller reaches the same
+     * pipeline through a different door. Without this the external half of the traffic has
+     * no receipt at all.
+     *
+     * It receives TIMINGS, A CLASS and SIZES — never the payload. The result is deliberately
+     * NOT passed in, so an implementation of this hook cannot duplicate a large result into a
+     * second log, which is the other half of what OBS-02 forbids.
+     *
+     * The invoked TOOL NAME rides alongside the accounting (task-13): external MCP calls are
+     * not session events, so a ledger that answers "which tools were used over MCP" needs
+     * the name here rather than re-deriving it from a session log that does not exist.
+     */
+    readonly onAccounted?: (accounting: InvocationAccounting, toolName: string) => void;
+    /** The engine that served the call, recorded WITH the measurement (OBS-05). */
+    readonly engineVersion?: string;
+    /** Operator-blocked confidential tools (MCP-11); refused before lookup/execution. */
+    readonly confidentialTools?: readonly string[];
+    /**
+     * The catalog caching policy carried on `tools/list` and `server/discover` (P26-14).
+     *
+     * Accepted as the UNVALIDATED config shape and validated HERE, once, so a bad
+     * operator value is refused with a named error at construction rather than surfacing
+     * as a per-request failure. Absent = private/0.
+     */
+    readonly cachePolicy?: {
+        readonly ttlMs?: number;
+        readonly cacheScope?: string;
+    };
+    /** Explicit catalog facts attached to discovery results (P26-14). */
+    readonly catalogFacts?: () => Record<string, unknown>;
+}): McpHost;
+//# sourceMappingURL=host-binding.d.ts.map

package/lib/mcp/host-binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-binding.d.ts","sourceRoot":"","sources":["../../src/mcp/host-binding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAA;AAGlE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AACvD,OAAO,KAAK,EAAE,OAAO,EAA4C,MAAM,aAAa,CAAA;AACpF,OAAO,EAIL,KAAK,oBAAoB,EAC1B,MAAM,6BAA6B,CAAA;AAsBpC;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAC9C,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASzB;AAED,+CAA+C;AAC/C,MAAM,WAAW,aAAa;IAC5B,mCAAmC;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAA;IAC/B;;;;;;;OAOG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;CACtC;AA+CD,4CAA4C;AAC5C,MAAM,WAAW,WAAW;IAC1B,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,EAAE,SAAS,aAAa,EAAE,CAAA;IAC5C;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/C;;;;;OAKG;IACH,OAAO,CAAC,OAAO,EAAE;QACf,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;QACrB,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;QACrD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;QAC5B,8EAA8E;QAC9E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;QACvB;;;;;;WAMG;QACH,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,CAAA;KACjC,GAAG,OAAO,CAAC;QACV,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;QACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;QACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAC1B,CAAC,CAAA;CACH;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE;IACrC,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAA;IAC7B,QAAQ,CAAC,UAAU,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;IACxE,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,IAAI,CAAA;IACnD;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,UAAU,EAAE,oBAAoB,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAA;IACnF,+EAA+E;IAC/E,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC/B,qFAAqF;IACrF,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9C;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAChF,qEAAqE;IACrE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACtD,GAAG,OAAO,CA2JV"}