@vinkius-core/mcp-fusion 2.7.0 → 2.8.0

package/dist/introspection/CryptoAttestation.d.ts

@@ -0,0 +1,143 @@
+import type { ServerDigest } from './BehaviorDigest.js';
+/**
+ * Configuration for zero-trust attestation.
+ *
+ * Passed to `AttachOptions.zeroTrust` in ServerAttachment.
+ */
+export interface ZeroTrustConfig {
+    /**
+     * The signing strategy to use.
+     * - `'hmac'` — HMAC-SHA256 with a shared secret (built-in)
+     * - A custom `AttestationSigner` for external KMS integration
+     */
+    readonly signer: 'hmac' | AttestationSigner;
+    /**
+     * For `'hmac'` mode: the shared secret.
+     * Read from environment in production (never hardcode).
+     */
+    readonly secret?: string;
+    /**
+     * Expected server digest hash from a known-good build.
+     * When set, runtime verification will fail-fast if the
+     * re-computed digest doesn't match.
+     */
+    readonly expectedDigest?: string;
+    /**
+     * Whether to fail-fast on attestation failure.
+     * Default: `true` in production, `false` in development.
+     */
+    readonly failOnMismatch?: boolean;
+    /**
+     * Whether to expose the attestation in MCP capabilities.
+     * Default: `true`.
+     */
+    readonly exposeCapability?: boolean;
+}
+/**
+ * Pluggable signer interface for external KMS integration.
+ *
+ * Implementations should be stateless and async-safe.
+ * The `sign()` method receives the canonical digest string
+ * and returns a signature (hex-encoded or base64).
+ */
+export interface AttestationSigner {
+    /** Human-readable name (e.g., 'sigstore', 'aws-kms') */
+    readonly name: string;
+    /** Sign a digest string */
+    sign(digest: string): Promise<string>;
+    /** Verify a digest against a signature */
+    verify(digest: string, signature: string): Promise<boolean>;
+}
+/**
+ * Result of an attestation operation.
+ */
+export interface AttestationResult {
+    /** Whether the attestation was successful */
+    readonly valid: boolean;
+    /** The computed digest */
+    readonly computedDigest: string;
+    /** The expected digest (if configured) */
+    readonly expectedDigest: string | null;
+    /** The signature (if signing was performed) */
+    readonly signature: string | null;
+    /** Signer identity */
+    readonly signerName: string;
+    /** ISO-8601 timestamp of attestation */
+    readonly attestedAt: string;
+    /** Human-readable error message, if invalid */
+    readonly error: string | null;
+}
+/**
+ * Capability structure exposed via MCP `server.capabilities`.
+ *
+ * Clients can inspect this to verify the server's behavioral
+ * identity before trusting tool responses.
+ */
+export interface FusionTrustCapability {
+    /** Current server behavioral digest */
+    readonly serverDigest: string;
+    /** Attestation signature (if signed) */
+    readonly signature: string | null;
+    /** Signer identity */
+    readonly signerName: string;
+    /** ISO-8601 timestamp of last attestation */
+    readonly attestedAt: string;
+    /** Number of tools covered by the attestation */
+    readonly toolCount: number;
+    /** Whether the attestation passed verification */
+    readonly verified: boolean;
+}
+/**
+ * Create an HMAC-SHA256 signer from a shared secret.
+ *
+ * @param secret - The shared secret (should be ≥32 bytes)
+ * @returns An `AttestationSigner` using HMAC-SHA256
+ */
+export declare function createHmacSigner(secret: string): AttestationSigner;
+/**
+ * Sign a server digest and produce an attestation result.
+ *
+ * @param serverDigest - The server's behavioral digest
+ * @param config - Zero-trust configuration
+ * @returns Attestation result with signature
+ */
+export declare function attestServerDigest(serverDigest: ServerDigest, config: ZeroTrustConfig): Promise<AttestationResult>;
+/**
+ * Verify a previously signed attestation.
+ *
+ * @param serverDigest - The current server digest
+ * @param signature - The signature to verify
+ * @param config - Zero-trust configuration
+ * @returns Attestation result with verification status
+ */
+export declare function verifyAttestation(serverDigest: ServerDigest, signature: string, config: ZeroTrustConfig): Promise<AttestationResult>;
+/**
+ * Runtime capability pinning — check that the current digest
+ * matches what was attested at build time.
+ *
+ * Designed to be called once at server startup in the `attach()` flow.
+ *
+ * @param currentDigest - Re-computed server digest
+ * @param config - Zero-trust configuration
+ * @returns Attestation result
+ * @throws If `failOnMismatch` is true and the digest doesn't match
+ */
+export declare function verifyCapabilityPin(currentDigest: ServerDigest, config: ZeroTrustConfig): Promise<AttestationResult>;
+/**
+ * Build the `fusionTrust` capability object for MCP exposure.
+ *
+ * @param attestation - A completed attestation result
+ * @param toolCount - Number of tools in the registry
+ * @returns Capability structure for `server.capabilities`
+ */
+export declare function buildTrustCapability(attestation: AttestationResult, toolCount: number): FusionTrustCapability;
+/**
+ * Error thrown when zero-trust attestation fails with failOnMismatch.
+ *
+ * Carries the full `AttestationResult` for programmatic inspection.
+ */
+export declare class AttestationError extends Error {
+    readonly attestation: AttestationResult;
+    constructor(message: string, attestation: AttestationResult);
+}
+//# sourceMappingURL=CryptoAttestation.d.ts.map

package/dist/introspection/CryptoAttestation.d.ts.map

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

package/dist/introspection/CryptoAttestation.js

@@ -0,0 +1,194 @@
+/**
+ * CryptoAttestation — Zero-Trust Runtime Verification
+ *
+ * **Evolution 1: Zero-Trust Runtime**
+ *
+ * Provides cryptographic attestation and capability pinning
+ * for MCP Fusion tool contracts. This module enables:
+ *
+ * 1. **Digital Signing**: Sign a `ToolContract` or `ServerDigest`
+ *    using HMAC-SHA256 (built-in) or pluggable external signers
+ *    (Sigstore, AWS KMS, Azure Key Vault).
+ *
+ * 2. **Runtime Verification**: At server startup, re-compute the
+ *    behavioral digest and compare it against the expected
+ *    (signed) digest. If they differ, fail fast with a clear
+ *    attestation error.
+ *
+ * 3. **Capability Pinning**: Expose a `fusionTrust` capability
+ *    in the MCP `server.capabilities` that clients can inspect
+ *    to verify the server's behavioral identity.
+ *
+ * **Zero-overhead principle**: When attestation is not configured,
+ * no cryptographic operations execute — the attach flow is
+ * identical to the default path.
+ *
+ * @module
+ */
+import { createHmac, timingSafeEqual } from 'node:crypto';
+// ============================================================================
+// HMAC Signer (Built-in)
+// ============================================================================
+/**
+ * Create an HMAC-SHA256 signer from a shared secret.
+ *
+ * @param secret - The shared secret (should be ≥32 bytes)
+ * @returns An `AttestationSigner` using HMAC-SHA256
+ */
+export function createHmacSigner(secret) {
+    return {
+        name: 'hmac-sha256',
+        async sign(digest) {
+            return hmacSign(digest, secret);
+        },
+        async verify(digest, signature) {
+            const expected = hmacSign(digest, secret);
+            return timingSafeCompare(expected, signature);
+        },
+    };
+}
+// ============================================================================
+// Attestation Operations
+// ============================================================================
+/**
+ * Sign a server digest and produce an attestation result.
+ *
+ * @param serverDigest - The server's behavioral digest
+ * @param config - Zero-trust configuration
+ * @returns Attestation result with signature
+ */
+export async function attestServerDigest(serverDigest, config) {
+    const signer = resolveSigner(config);
+    const signature = await signer.sign(serverDigest.digest);
+    const attestedAt = new Date().toISOString();
+    // Verify against expected digest if configured
+    if (config.expectedDigest) {
+        const matches = serverDigest.digest === config.expectedDigest;
+        return {
+            valid: matches,
+            computedDigest: serverDigest.digest,
+            expectedDigest: config.expectedDigest,
+            signature,
+            signerName: signer.name,
+            attestedAt,
+            error: matches ? null : `Attestation failed: computed digest ${serverDigest.digest} does not match expected ${config.expectedDigest}`,
+        };
+    }
+    return {
+        valid: true,
+        computedDigest: serverDigest.digest,
+        expectedDigest: null,
+        signature,
+        signerName: signer.name,
+        attestedAt,
+        error: null,
+    };
+}
+/**
+ * Verify a previously signed attestation.
+ *
+ * @param serverDigest - The current server digest
+ * @param signature - The signature to verify
+ * @param config - Zero-trust configuration
+ * @returns Attestation result with verification status
+ */
+export async function verifyAttestation(serverDigest, signature, config) {
+    const signer = resolveSigner(config);
+    const verified = await signer.verify(serverDigest.digest, signature);
+    const attestedAt = new Date().toISOString();
+    return {
+        valid: verified,
+        computedDigest: serverDigest.digest,
+        expectedDigest: config.expectedDigest ?? null,
+        signature,
+        signerName: signer.name,
+        attestedAt,
+        error: verified ? null : `Signature verification failed for digest ${serverDigest.digest}`,
+    };
+}
+/**
+ * Runtime capability pinning — check that the current digest
+ * matches what was attested at build time.
+ *
+ * Designed to be called once at server startup in the `attach()` flow.
+ *
+ * @param currentDigest - Re-computed server digest
+ * @param config - Zero-trust configuration
+ * @returns Attestation result
+ * @throws If `failOnMismatch` is true and the digest doesn't match
+ */
+export async function verifyCapabilityPin(currentDigest, config) {
+    const result = await attestServerDigest(currentDigest, config);
+    if (!result.valid && (config.failOnMismatch ?? true)) {
+        throw new AttestationError(`[MCP Fusion] Zero-Trust attestation failed: ${result.error}`, result);
+    }
+    return result;
+}
+/**
+ * Build the `fusionTrust` capability object for MCP exposure.
+ *
+ * @param attestation - A completed attestation result
+ * @param toolCount - Number of tools in the registry
+ * @returns Capability structure for `server.capabilities`
+ */
+export function buildTrustCapability(attestation, toolCount) {
+    return {
+        serverDigest: attestation.computedDigest,
+        signature: attestation.signature,
+        signerName: attestation.signerName,
+        attestedAt: attestation.attestedAt,
+        toolCount,
+        verified: attestation.valid,
+    };
+}
+// ============================================================================
+// Attestation Error
+// ============================================================================
+/**
+ * Error thrown when zero-trust attestation fails with failOnMismatch.
+ *
+ * Carries the full `AttestationResult` for programmatic inspection.
+ */
+export class AttestationError extends Error {
+    attestation;
+    constructor(message, attestation) {
+        super(message);
+        this.name = 'AttestationError';
+        this.attestation = attestation;
+    }
+}
+// ============================================================================
+// Internals
+// ============================================================================
+/**
+ * Resolve the signer from config.
+ * @internal
+ */
+function resolveSigner(config) {
+    if (config.signer === 'hmac') {
+        if (!config.secret) {
+            throw new Error('[MCP Fusion] HMAC signer requires a secret. Set zeroTrust.secret or use a custom signer.');
+        }
+        return createHmacSigner(config.secret);
+    }
+    return config.signer;
+}
+/**
+ * HMAC-SHA256 sign.
+ * @internal
+ */
+function hmacSign(data, secret) {
+    return createHmac('sha256', secret).update(data, 'utf8').digest('hex');
+}
+/**
+ * Timing-safe string comparison to prevent timing attacks.
+ * @internal
+ */
+function timingSafeCompare(a, b) {
+    if (a.length !== b.length)
+        return false;
+    const bufA = Buffer.from(a, 'utf8');
+    const bufB = Buffer.from(b, 'utf8');
+    return timingSafeEqual(bufA, bufB);
+}
+//# sourceMappingURL=CryptoAttestation.js.map

package/dist/introspection/CryptoAttestation.js.map

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

package/dist/introspection/EntitlementScanner.d.ts

@@ -0,0 +1,124 @@
+/**
+ * EntitlementScanner — AST-Based Blast Radius Analysis
+ *
+ * **Evolution 5: Blast Radius**
+ *
+ * Performs static analysis of handler source files to detect
+ * I/O capabilities (filesystem, network, subprocess, crypto)
+ * that expand the tool's blast radius beyond what its
+ * declarative contract suggests.
+ *
+ * **Key insight**: A tool declared as `readOnly: true` that
+ * imports `child_process` has a mismatch between its declared
+ * contract and its actual capabilities. This scanner detects
+ * such mismatches and reports them as entitlement violations.
+ *
+ * **Implementation approach**: Instead of a full TypeScript AST
+ * parser (which would require `typescript` as a dependency),
+ * this module uses regex-based pattern matching on source text.
+ * This is deliberately conservative — it may over-report but
+ * never under-report.
+ *
+ * **Contract integration**: The entitlement report is embedded
+ * in the `ToolContract.entitlements` field, making entitlement
+ * changes trackable via `ContractDiff`.
+ *
+ * Pure-function module: no state, no side effects.
+ *
+ * @module
+ */
+import type { HandlerEntitlements } from './ToolContract.js';
+/**
+ * Complete entitlement report for a handler.
+ */
+export interface EntitlementReport {
+    /** Resolved entitlements */
+    readonly entitlements: HandlerEntitlements;
+    /** All detected entitlement matches */
+    readonly matches: readonly EntitlementMatch[];
+    /** Entitlement violations (declared vs detected mismatches) */
+    readonly violations: readonly EntitlementViolation[];
+    /** Whether the handler is considered safe */
+    readonly safe: boolean;
+    /** Human-readable summary */
+    readonly summary: string;
+}
+/**
+ * A single entitlement match detected in source code.
+ */
+export interface EntitlementMatch {
+    /** Which entitlement category */
+    readonly category: EntitlementCategory;
+    /** The specific API/import detected */
+    readonly identifier: string;
+    /** Pattern that matched */
+    readonly pattern: string;
+    /** Source text (context around the match) */
+    readonly context: string;
+    /** Line number in the source (1-based) */
+    readonly line: number;
+}
+/**
+ * An entitlement violation — mismatch between declaration and detection.
+ */
+export interface EntitlementViolation {
+    /** Which entitlement is violated */
+    readonly category: EntitlementCategory;
+    /** What was declared (e.g., readOnly: true) */
+    readonly declared: string;
+    /** What was detected */
+    readonly detected: string;
+    /** Severity */
+    readonly severity: 'warning' | 'error';
+    /** Human-readable description */
+    readonly description: string;
+}
+/** Entitlement categories */
+export type EntitlementCategory = 'filesystem' | 'network' | 'subprocess' | 'crypto';
+/**
+ * Declaration claims for validation against detected entitlements.
+ */
+export interface EntitlementClaims {
+    /** Whether the action is declared as readOnly */
+    readonly readOnly?: boolean;
+    /** Whether the action is declared as destructive */
+    readonly destructive?: boolean;
+    /** Explicitly allowed entitlements (bypasses violation detection) */
+    readonly allowed?: readonly EntitlementCategory[];
+}
+/**
+ * Scan source text for entitlement patterns.
+ *
+ * @param source - The source code text to scan
+ * @param fileName - File name for reporting (optional)
+ * @returns All entitlement matches found
+ */
+export declare function scanSource(source: string, fileName?: string): readonly EntitlementMatch[];
+/**
+ * Build `HandlerEntitlements` from detected matches.
+ *
+ * @param matches - Detected entitlement matches
+ * @returns Aggregated entitlements
+ */
+export declare function buildEntitlements(matches: readonly EntitlementMatch[]): HandlerEntitlements;
+/**
+ * Validate detected entitlements against declared claims.
+ *
+ * Uses a rule table instead of imperative branching.
+ * Each rule encodes a policy check as pure data.
+ *
+ * @param matches - Detected matches
+ * @param claims - Declared claims from action metadata
+ * @returns Violations found
+ */
+export declare function validateClaims(matches: readonly EntitlementMatch[], claims: EntitlementClaims): readonly EntitlementViolation[];
+/**
+ * Perform a complete entitlement scan and validation.
+ *
+ * @param source - Handler source code
+ * @param claims - Declared claims for validation
+ * @param fileName - Optional file name for reporting
+ * @returns Complete entitlement report
+ */
+export declare function scanAndValidate(source: string, claims?: EntitlementClaims, fileName?: string): EntitlementReport;
+//# sourceMappingURL=EntitlementScanner.d.ts.map

package/dist/introspection/EntitlementScanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EntitlementScanner.d.ts","sourceRoot":"","sources":["../../src/introspection/EntitlementScanner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAM7D;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAC9B,4BAA4B;IAC5B,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC;IAC3C,uCAAuC;IACvC,QAAQ,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC9C,+DAA+D;IAC/D,QAAQ,CAAC,UAAU,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACrD,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,6BAA6B;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC7B,iCAAiC;IACjC,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IACvC,uCAAuC;IACvC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,2BAA2B;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACjC,oCAAoC;IACpC,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IACvC,+CAA+C;IAC/C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,wBAAwB;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,eAAe;IACf,QAAQ,CAAC,QAAQ,EAAE,SAAS,GAAG,OAAO,CAAC;IACvC,iCAAiC;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAChC;AAED,6BAA6B;AAC7B,MAAM,MAAM,mBAAmB,GAAG,YAAY,GAAG,SAAS,GAAG,YAAY,GAAG,QAAQ,CAAC;AAErF;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAC9B,iDAAiD;IACjD,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,oDAAoD;IACpD,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,qEAAqE;IACrE,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;CACrD;AAsED;;;;;;GAMG;AACH,wBAAgB,UAAU,CACtB,MAAM,EAAE,MAAM,EACd,QAAQ,CAAC,EAAE,MAAM,GAClB,SAAS,gBAAgB,EAAE,CAyB7B;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC7B,OAAO,EAAE,SAAS,gBAAgB,EAAE,GACrC,mBAAmB,CAWrB;AA4ED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC1B,OAAO,EAAE,SAAS,gBAAgB,EAAE,EACpC,MAAM,EAAE,iBAAiB,GAC1B,SAAS,oBAAoB,EAAE,CAOjC;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC3B,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,iBAAsB,EAC9B,QAAQ,CAAC,EAAE,MAAM,GAClB,iBAAiB,CAgBnB"}