@aisy/core 0.1.0

package/dist/mcp/index.js

@@ -0,0 +1,215 @@
+import { createHash } from 'node:crypto';
+// ---------------------------------------------------------------------------
+// Canonical descriptor hashing (ADR-0013, CSO-M2)
+// sha256 over name + description + inputSchema + rwClassInputs, tools sorted
+// by name, object keys deep-sorted — byte-stable for identical descriptors.
+// ---------------------------------------------------------------------------
+function sortDeep(value) {
+    if (Array.isArray(value))
+        return value.map(sortDeep);
+    if (value !== null && typeof value === 'object') {
+        const out = {};
+        for (const key of Object.keys(value).sort()) {
+            out[key] = sortDeep(value[key]);
+        }
+        return out;
+    }
+    return value;
+}
+export function canonicalDescriptorHash(tools) {
+    const canonical = [...tools]
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .map(t => sortDeep({
+        name: t.name,
+        description: t.description,
+        inputSchema: t.inputSchema,
+        rwClassInputs: t.rwClassInputs ?? {},
+    }));
+    return createHash('sha256').update(JSON.stringify(canonical), 'utf8').digest('hex');
+}
+// ---------------------------------------------------------------------------
+// makeMCPManager — the deterministic connect gauntlet + call path (ADR-0013).
+// Pure code; no model decision anywhere on this surface.
+// ---------------------------------------------------------------------------
+export function makeMCPManager(deps) {
+    const entryFor = (name) => deps.allowlist?.servers.find(s => s.name === name);
+    /** Per-process minimal-scope env: ONLY the server's own token (CSO-M4). */
+    const envFor = (entry) => {
+        if (entry.tokenEnv === null)
+            return {};
+        const token = deps.resolveToken(entry.tokenEnv);
+        if (token === null)
+            return 'unresolved';
+        return { [entry.tokenEnv]: token };
+    };
+    const hostOf = (endpoint) => {
+        try {
+            return new URL(endpoint).host;
+        }
+        catch {
+            return endpoint;
+        }
+    };
+    return {
+        verifyHash(entry, live) {
+            return canonicalDescriptorHash(live) === entry.descriptorHash;
+        },
+        // Connect gauntlet: allowlist -> pin present -> hash present -> egress ->
+        // token -> spawn -> live pin -> tools/list -> hash verify -> menu.
+        // Every refusal happens BEFORE the next side effect (fail-closed).
+        async connect(name) {
+            const entry = entryFor(name);
+            if (!entry) {
+                deps.emit('mcp.refused', { server: name, reason: 'not-allowlisted' });
+                return { kind: 'refused', reason: 'not-allowlisted' };
+            }
+            if (!entry.pin) {
+                deps.emit('mcp.refused', { server: name, reason: 'no-pin' });
+                return { kind: 'refused', reason: 'no-pin' };
+            }
+            if (!entry.descriptorHash) {
+                deps.emit('mcp.refused', { server: name, reason: 'no-hash' });
+                return { kind: 'refused', reason: 'no-hash' };
+            }
+            // HTTP endpoints must be on the Safety egress allowlist BEFORE any contact.
+            if (entry.transport === 'streamable-http' && entry.endpoint) {
+                if (!deps.isEgressAllowed(hostOf(entry.endpoint))) {
+                    deps.emit('mcp.refused', { server: name, reason: 'egress-blocked' });
+                    return { kind: 'refused', reason: 'egress-blocked' };
+                }
+            }
+            // Fail-closed on unresolved tokens — never a shared/fallback credential.
+            const env = envFor(entry);
+            if (env === 'unresolved') {
+                deps.emit('mcp.refused', { server: name, reason: 'token-unresolved' });
+                return { kind: 'refused', reason: 'token-unresolved' };
+            }
+            const handle = deps.spawnProcess(entry.command ?? [entry.endpoint ?? ''], env);
+            try {
+                // Live version must equal the pin BEFORE tools/list is trusted.
+                const livePin = await deps.resolvePin(handle);
+                if (livePin !== entry.pin) {
+                    deps.emit('mcp.refused', { server: name, reason: 'pin-mismatch' });
+                    return { kind: 'refused', reason: 'pin-mismatch' };
+                }
+                const live = await deps.fetchDescriptors(handle);
+                const liveHash = canonicalDescriptorHash(live);
+                if (liveHash !== entry.descriptorHash) {
+                    // Rug-pull defense: server disabled until an operator approves the diff.
+                    // The card carries BOTH the previously-approved (pinned) descriptors and
+                    // the new (live) set, so the operator can see exactly what changed.
+                    const diffCard = {
+                        server: name,
+                        oldHash: entry.descriptorHash,
+                        newHash: liveHash,
+                        descriptorDiff: { previous: entry.descriptors ?? [], live },
+                    };
+                    deps.emit('mcp.disabled_hash_mismatch', { server: name });
+                    deps.emit('mcp.diff_card_emitted', diffCard);
+                    return { kind: 'disabled', reason: 'hash-mismatch', diffCard };
+                }
+                // Menu derivation: human-authored summary verbatim; null -> quarantined
+                // generation; generation failure -> tool OMITTED (never raw description).
+                const menu = [];
+                for (const policy of entry.tools) {
+                    let summary = policy.summary;
+                    if (summary === null) {
+                        const descriptor = live.find(t => t.name === policy.tool);
+                        // Entering the quarantined-generation path is observable regardless of
+                        // outcome — a silent generator failure must still reach Observability.
+                        deps.emit('mcp.summary_quarantined', { server: name, tool: policy.tool });
+                        summary = descriptor ? await deps.generateSummary(descriptor) : null;
+                    }
+                    if (summary === null)
+                        continue;
+                    menu.push({
+                        name: `${name}.${policy.tool}`,
+                        summary,
+                        rw: policy.outboundSink ? 'write' : 'read',
+                        tier: policy.tier,
+                    });
+                }
+                deps.emit('mcp.connected', { server: name });
+                return { kind: 'connected', menu };
+            }
+            finally {
+                // One-shot gauntlet process; the call path spawns its own.
+                handle.terminate();
+            }
+        },
+        // Resolve + invoke. `outboundSink`/`tier` always come from the human
+        // policy; capability narrowing and the motivated-call block run in code.
+        async call(namespaced, args, argProvenance = 'operator') {
+            if (!deps.allowlist)
+                throw new Error('cold start: MCP allowlist not loaded — call_mcp refused');
+            // The name is the menu's `${server}.${tool}` join. Both server names and
+            // tool names may legitimately contain '.', so a naive indexOf('.') split
+            // is ambiguous and can mis-route to the wrong policy (or fail closed on a
+            // valid call). Resolve authoritatively against the allowlist: find the
+            // (entry, policy) pair whose `${entry.name}.${policy.tool}` equals the
+            // namespaced name. Reject when the parse is ambiguous or yields an empty
+            // server/tool segment (fail-closed) — never silently bypass the policy.
+            const dot = namespaced.indexOf('.');
+            if (dot <= 0 || dot >= namespaced.length - 1) {
+                throw new Error(`malformed mcp call '${namespaced}' — expected non-empty server.tool`);
+            }
+            let entry;
+            let policy;
+            for (const candidate of deps.allowlist.servers) {
+                const prefix = `${candidate.name}.`;
+                if (!namespaced.startsWith(prefix))
+                    continue;
+                const toolName = namespaced.slice(prefix.length);
+                const match = candidate.tools.find(t => t.tool === toolName);
+                if (match) {
+                    if (policy)
+                        throw new Error(`ambiguous mcp call '${namespaced}' — matches multiple allowlist policies`);
+                    entry = candidate;
+                    policy = match;
+                }
+            }
+            if (!entry || !policy)
+                throw new Error(`mcp tool '${namespaced}' has no allowlist policy`);
+            const server = entry.name;
+            const tool = policy.tool;
+            // ADR-0027: while an untrusted span is in context, outbound sinks are locked.
+            if (policy.outboundSink && deps.hasUntrustedSpan?.()) {
+                throw new Error(`mcp call '${namespaced}' denied: outbound locked (untrusted span in context)`);
+            }
+            // Motivated-call block: untrusted-derived args never reach a sink.
+            if (policy.outboundSink && argProvenance === 'untrusted') {
+                throw new Error(`mcp call '${namespaced}' denied: motivated call blocked (untrusted args on outbound sink)`);
+            }
+            // Egress is enforced per request, not only at connect (spec §8 "Egress
+            // redirection"). The call path spawns its own process and may run with no
+            // prior connect(), so re-check the endpoint host before any contact.
+            if (entry.transport === 'streamable-http' && entry.endpoint && !deps.isEgressAllowed(hostOf(entry.endpoint))) {
+                throw new Error(`mcp call '${namespaced}' denied: egress blocked for '${entry.endpoint}'`);
+            }
+            const env = envFor(entry);
+            if (env === 'unresolved')
+                throw new Error(`mcp server '${server}' token unresolved — fail-closed`);
+            const resolved = {
+                server,
+                tool,
+                args,
+                outboundSink: policy.outboundSink,
+                tier: policy.tier,
+            };
+            deps.onResolved?.(resolved);
+            const handle = deps.spawnProcess(entry.command ?? [entry.endpoint ?? ''], env);
+            try {
+                const text = deps.invokeTool ? await deps.invokeTool(handle, resolved) : '';
+                // Every result enters context as untrusted (ADR-0028); the classifier is
+                // advisory and lives in Safety (05) — absent here, the result is
+                // quarantined, never admitted as trusted.
+                deps.emit('mcp.result_quarantined', { server, tool });
+                return { provenance: 'untrusted', text, server };
+            }
+            finally {
+                handle.terminate();
+            }
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/mcp/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"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"}

package/dist/mcp/types.d.ts

@@ -0,0 +1,148 @@
+export type McpTransport = "stdio" | "streamable-http";
+/** Human-owned, version-controlled entry in the MCP allowlist config.
+ *  `tier` and `outboundSink` live here; they are NEVER derived from descriptor text (CSO-M2). */
+export interface McpServerEntry {
+    name: string;
+    transport: McpTransport;
+    endpoint?: string;
+    command?: string[];
+    pin: string;
+    descriptorHash: string;
+    descriptors?: RawDescriptor[];
+    tokenEnv: string | null;
+    tools: McpToolPolicy[];
+}
+/** Per-tool policy — human-authored at allowlist time.
+ *  The sole authority for `tier` and `outboundSink`; descriptor text is not an input. */
+export interface McpToolPolicy {
+    tool: string;
+    tier: 0 | 1 | 2 | 3;
+    outboundSink: boolean;
+    summary: string | null;
+}
+export type ConnectResult = {
+    kind: "connected";
+    menu: McpMenuLine[];
+} | {
+    kind: "refused";
+    reason: "not-allowlisted" | "no-pin" | "no-hash" | "pin-mismatch" | "egress-blocked" | "token-unresolved";
+} | {
+    kind: "disabled";
+    reason: "hash-mismatch";
+    diffCard: DiffCard;
+};
+/** One namespaced line injected into the model's tool menu.
+ *  Raw `description`, full `inputSchema`, endpoint URLs, tokens, and hashes are kept out of the prompt. */
+export interface McpMenuLine {
+    name: string;
+    summary: string;
+    rw: "read" | "write";
+    tier: 0 | 1 | 2 | 3;
+}
+/** The untrusted descriptor shape returned by a server's `tools/list` call.
+ *  This is input to descriptor hashing only — it never reaches the prompt verbatim. */
+export interface RawDescriptor {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    rwClassInputs?: Record<string, unknown>;
+}
+/** A model-selected tool resolved to a concrete call, ready for PreToolUse hook gating.
+ *  `outboundSink` and `tier` are always taken from `McpToolPolicy`, never from descriptor. */
+export interface ResolvedMcpCall {
+    server: string;
+    tool: string;
+    args: Record<string, unknown>;
+    outboundSink: boolean;
+    tier: 0 | 1 | 2 | 3;
+}
+/** Every MCP tools/call result is wrapped in this type at ingestion.
+ *  `provenance` is set by code, never by the model (ADR-0028). */
+export interface UntrustedResultSpan {
+    provenance: "untrusted";
+    text: string;
+    server: string;
+}
+/** Emitted when the live descriptor hash mismatches the stored value.
+ *  Server stays disabled until an operator reviews and approves the diff. */
+export interface DiffCard {
+    server: string;
+    oldHash: string;
+    newHash: string;
+    descriptorDiff: DescriptorDiff;
+}
+/** Old-vs-new descriptor pair shown to the operator on a rug-pull (hash mismatch).
+ *  `previous` is the human-approved set stored in the allowlist entry (empty if none was recorded);
+ *  `live` is the set just fetched from the server. */
+export interface DescriptorDiff {
+    previous: RawDescriptor[];
+    live: RawDescriptor[];
+}
+export interface McpClient {
+    /** Deterministic connect gauntlet (ADR-0013). Pure code; no model call. */
+    connect(name: string): Promise<ConnectResult>;
+    /** Canonical sha256 over name + description + inputSchema + rwClassInputs, sorted by name (CSO-M2).
+     *  Byte-stable: identical descriptors always produce the same hash. */
+    descriptorHash(tools: RawDescriptor[]): string;
+    /** Resolve a model-selected `server.tool` to a concrete call.
+     *  The returned call re-enters Tools & Hooks (04) PreToolUse; this method NEVER executes a write. */
+    resolve(namespaced: string, args: unknown): ResolvedMcpCall;
+    /** Execute an already hook-approved call against the per-process, minimal-scope server.
+     *  Returns the result span tagged `untrusted` for Safety's classifier (ADR-0028). */
+    invokeApproved(call: ResolvedMcpCall): Promise<UntrustedResultSpan>;
+}
+/** Allowlist config — the human-owned, version-controlled source of truth. */
+export interface McpAllowlistConfig {
+    servers: McpServerEntry[];
+}
+/** Hash record stored per server after first-approval (mirrors the allowlist fields). */
+export interface McpDescriptorHash {
+    server: string;
+    hash: string;
+}
+/** Observability events this component emits (Observability 12). */
+export type McpEvent = "mcp.connected" | "mcp.refused" | "mcp.disabled_hash_mismatch" | "mcp.diff_card_emitted" | "mcp.summary_quarantined" | "mcp.result_classified" | "mcp.result_quarantined";
+export interface McpManagerDeps {
+    /** Loaded allowlist config; absent = cold-start, fail-closed. */
+    allowlist: McpAllowlistConfig | null;
+    /** Check whether an HTTP endpoint host is on the Safety egress allowlist. */
+    isEgressAllowed(host: string): boolean;
+    /** Resolve a token by env name; returns null if unresolved. */
+    resolveToken(envName: string): string | null;
+    /** Emit an observability event. */
+    emit(event: McpEvent, payload?: unknown): void;
+    /** Stub for the quarantined summary-generation pass (Eng-9).
+     *  Returns null on failure (tool omitted from menu rather than falling back to raw description). */
+    generateSummary(descriptor: RawDescriptor): Promise<string | null>;
+    /** Spy-able spawn shim — returns an opaque process handle. */
+    spawnProcess(command: string[], env: Record<string, string>): McpProcessHandle;
+    /** Fetch the live tools/list from a server process. */
+    fetchDescriptors(handle: McpProcessHandle): Promise<RawDescriptor[]>;
+    /** Resolve live version/digest from a server process (before tools/list). */
+    resolvePin(handle: McpProcessHandle): Promise<string>;
+    /** Capability-narrowing input (ADR-0027): true while an untrusted span is in context. */
+    hasUntrustedSpan?: () => boolean;
+    /** Execute an approved tools/call against a running server (injectable seam, Eng-11). */
+    invokeTool?: (handle: McpProcessHandle, call: ResolvedMcpCall) => Promise<string>;
+    /** Test seam: observe the policy-resolved call before invocation. */
+    onResolved?: (call: ResolvedMcpCall) => void;
+}
+/** Opaque handle to a running MCP server process (stdio) or HTTP session. */
+export interface McpProcessHandle {
+    readonly id: string;
+    readonly env: Record<string, string>;
+    terminate(): void;
+}
+/** The public manager surface (narrow waist — the model only reaches this via `call_mcp`). */
+export interface McpManager {
+    /** Run the full connect gauntlet for a named server (ADR-0013). */
+    connect(name: string): Promise<ConnectResult>;
+    /** Resolve + invoke an already-approved `server.tool` call.
+     *  `argProvenance` is code-assigned by the caller (ADR-0028); untrusted-derived
+     *  args on an outbound sink are blocked (motivated-call, ADR-0027). */
+    call(namespaced: string, args: Record<string, unknown>, argProvenance?: "operator" | "untrusted"): Promise<UntrustedResultSpan>;
+    /** Return true if the stored hash for the entry matches the recomputed hash.
+     *  Used by the connect gauntlet; exposed for testing. */
+    verifyHash(entry: McpServerEntry, live: RawDescriptor[]): boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/mcp/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/mcp/types.ts"],"names":[],"mappings":"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"}

package/dist/mcp/types.js

@@ -0,0 +1,4 @@
+// MCP component (07) — pure types. No implementation, no external deps.
+// See docs/specs/07-mcp.md §3.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/mcp/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/mcp/types.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,+BAA+B"}

package/dist/memory/index.d.ts

@@ -0,0 +1,6 @@
+import type { Memory, MemoryStoreDeps } from './types.js';
+export type { Memory, Memory as MemoryStore, MemoryStoreDeps, MemoryFact } from './types.js';
+export type { FactKey, MemoryOp, GuardVerdict, CommitResult, RankedHit, LazyLoadStep, ForgetListEntry, FrozenSnapshot, IntegrityResult, } from './types.js';
+export { CorruptIndexError, ForgetListTamperError, BypassError, GuardBlocked, } from './types.js';
+export declare function makeMemoryStore(deps: MemoryStoreDeps): Memory;
+//# sourceMappingURL=index.d.ts.map

package/dist/memory/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/memory/index.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,MAAM,EAEN,eAAe,EAOhB,MAAM,YAAY,CAAA;AAGnB,YAAY,EAAE,MAAM,EAAE,MAAM,IAAI,WAAW,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE5F,YAAY,EACV,OAAO,EACP,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,YAAY,EACZ,eAAe,EACf,cAAc,EACd,eAAe,GAChB,MAAM,YAAY,CAAA;AAEnB,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,WAAW,EACX,YAAY,GACb,MAAM,YAAY,CAAA;AAmInB,wBAAgB,eAAe,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAoW7D"}