@kya-os/mcp-i 0.1.0 → 1.2.0

package/dist/runtime/well-known.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Well-Known Endpoints for XMCP-I Runtime
+ *
+ * Handles /.well-known/did.json and /.well-known/agent.json endpoints
+ * according to requirements 7.1, 7.2, 7.3, 7.4, 7.5.
+ */
+import { AgentIdentity } from "./identity";
+/**
+ * DID Document structure (W3C DID Core specification)
+ */
+export interface DIDDocument {
+    "@context": string[];
+    id: string;
+    verificationMethod: VerificationMethod[];
+    authentication: string[];
+    assertionMethod: string[];
+    keyAgreement?: string[];
+    capabilityInvocation?: string[];
+    capabilityDelegation?: string[];
+    service?: ServiceEndpoint[];
+}
+/**
+ * Verification Method for DID Document
+ */
+export interface VerificationMethod {
+    id: string;
+    type: string;
+    controller: string;
+    publicKeyMultibase?: string;
+    publicKeyJwk?: any;
+}
+/**
+ * Service Endpoint for DID Document
+ */
+export interface ServiceEndpoint {
+    id: string;
+    type: string;
+    serviceEndpoint: string;
+}
+/**
+ * Agent Document structure (XMCP-I specific)
+ */
+export interface AgentDocument {
+    id: string;
+    capabilities: {
+        "mcp-i": ["handshake", "signing", "verification"];
+    };
+    registry?: {
+        kta?: string;
+        mcp?: string;
+    };
+    metadata?: {
+        name?: string;
+        description?: string;
+        version?: string;
+    };
+}
+/**
+ * Well-known endpoint configuration
+ */
+export interface WellKnownConfig {
+    environment: "development" | "production";
+    baseUrl?: string;
+    agentMetadata?: {
+        name?: string;
+        description?: string;
+        version?: string;
+    };
+    registryUrls?: {
+        kta?: string;
+        mcp?: string;
+    };
+}
+/**
+ * Well-known endpoints manager
+ */
+export declare class WellKnownManager {
+    private identity;
+    private config;
+    constructor(identity: AgentIdentity, config: WellKnownConfig);
+    /**
+     * Generate DID document for /.well-known/did.json
+     * Requirements: 7.1, 7.5
+     */
+    generateDIDDocument(): DIDDocument;
+    /**
+     * Generate agent document for /.well-known/agent.json
+     * Requirements: 7.2, 7.3
+     */
+    generateAgentDocument(): AgentDocument;
+    /**
+     * Get HTTP headers for DID document
+     * Requirements: 7.4, 7.5
+     */
+    getDIDDocumentHeaders(): Record<string, string>;
+    /**
+     * Get HTTP headers for agent document
+     * Requirements: 7.2, 7.5
+     */
+    getAgentDocumentHeaders(): Record<string, string>;
+    /**
+     * Encode public key as multibase (base58btc with 'z' prefix for Ed25519)
+     */
+    private encodePublicKeyMultibase;
+    /**
+     * Simple base58 encoding (use proper library in production)
+     */
+    private encodeBase58;
+    /**
+     * Update configuration
+     */
+    updateConfig(config: Partial<WellKnownConfig>): void;
+    /**
+     * Get current configuration
+     */
+    getConfig(): WellKnownConfig;
+}
+/**
+ * Express/HTTP handler for well-known endpoints
+ */
+export interface WellKnownHandler {
+    handleDIDDocument(): {
+        status: number;
+        headers: Record<string, string>;
+        body: string;
+    };
+    handleAgentDocument(): {
+        status: number;
+        headers: Record<string, string>;
+        body: string;
+    };
+}
+/**
+ * Create well-known endpoint handler
+ */
+export declare function createWellKnownHandler(identity: AgentIdentity, config: WellKnownConfig): WellKnownHandler;
+/**
+ * Utility functions
+ */
+/**
+ * Validate DID document structure
+ */
+export declare function validateDIDDocument(doc: any): doc is DIDDocument;
+/**
+ * Validate agent document structure
+ */
+export declare function validateAgentDocument(doc: any): doc is AgentDocument;
+/**
+ * Extract DID from URL path (for did:web resolution)
+ */
+export declare function extractDIDFromPath(path: string, baseUrl: string): string | null;

package/dist/runtime/well-known.js

@@ -0,0 +1,258 @@
+"use strict";
+/**
+ * Well-Known Endpoints for XMCP-I Runtime
+ *
+ * Handles /.well-known/did.json and /.well-known/agent.json endpoints
+ * according to requirements 7.1, 7.2, 7.3, 7.4, 7.5.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WellKnownManager = void 0;
+exports.createWellKnownHandler = createWellKnownHandler;
+exports.validateDIDDocument = validateDIDDocument;
+exports.validateAgentDocument = validateAgentDocument;
+exports.extractDIDFromPath = extractDIDFromPath;
+/**
+ * Well-known endpoints manager
+ */
+class WellKnownManager {
+    identity;
+    config;
+    constructor(identity, config) {
+        this.identity = identity;
+        this.config = config;
+    }
+    /**
+     * Generate DID document for /.well-known/did.json
+     * Requirements: 7.1, 7.5
+     */
+    generateDIDDocument() {
+        const keyId = `#${this.identity.keyId}`;
+        // Convert base64 public key to multibase format
+        const publicKeyMultibase = this.encodePublicKeyMultibase(this.identity.publicKey);
+        const didDocument = {
+            "@context": [
+                "https://www.w3.org/ns/did/v1",
+                "https://w3id.org/security/suites/ed25519-2020/v1",
+            ],
+            id: this.identity.did,
+            verificationMethod: [
+                {
+                    id: keyId,
+                    type: "Ed25519VerificationKey2020",
+                    controller: this.identity.did,
+                    publicKeyMultibase,
+                },
+            ],
+            authentication: [keyId],
+            assertionMethod: [keyId],
+        };
+        return didDocument;
+    }
+    /**
+     * Generate agent document for /.well-known/agent.json
+     * Requirements: 7.2, 7.3
+     */
+    generateAgentDocument() {
+        const agentDocument = {
+            id: this.identity.did,
+            capabilities: {
+                "mcp-i": ["handshake", "signing", "verification"], // Exact capability triplet
+            },
+        };
+        // Add registry URLs if configured
+        if (this.config.registryUrls) {
+            agentDocument.registry = { ...this.config.registryUrls };
+        }
+        // Add metadata if configured
+        if (this.config.agentMetadata) {
+            agentDocument.metadata = { ...this.config.agentMetadata };
+        }
+        return agentDocument;
+    }
+    /**
+     * Get HTTP headers for DID document
+     * Requirements: 7.4, 7.5
+     */
+    getDIDDocumentHeaders() {
+        const headers = {
+            "Content-Type": "application/did+json",
+        };
+        // Add caching headers based on environment
+        if (this.config.environment === "production") {
+            headers["Cache-Control"] = "public, max-age=300"; // 5 minutes
+        }
+        else {
+            headers["Cache-Control"] = "no-store";
+        }
+        return headers;
+    }
+    /**
+     * Get HTTP headers for agent document
+     * Requirements: 7.2, 7.5
+     */
+    getAgentDocumentHeaders() {
+        const headers = {
+            "Content-Type": "application/json",
+        };
+        // Always no-store for agent document in dev, public cache in prod
+        if (this.config.environment === "production") {
+            headers["Cache-Control"] = "public, max-age=300"; // 5 minutes
+        }
+        else {
+            headers["Cache-Control"] = "no-store";
+        }
+        return headers;
+    }
+    /**
+     * Encode public key as multibase (base58btc with 'z' prefix for Ed25519)
+     */
+    encodePublicKeyMultibase(base64PublicKey) {
+        // For Ed25519, we use base58btc encoding with 'z' prefix
+        // This is a simplified implementation - in production, use proper multibase library
+        const publicKeyBytes = Buffer.from(base64PublicKey, "base64");
+        // Ed25519 public key prefix (0xed01) + key bytes
+        const prefixedKey = Buffer.concat([
+            Buffer.from([0xed, 0x01]), // Ed25519 multicodec prefix
+            publicKeyBytes,
+        ]);
+        // Convert to base58btc (simplified - use proper base58 library in production)
+        const base58 = this.encodeBase58(prefixedKey);
+        return `z${base58}`; // 'z' prefix indicates base58btc
+    }
+    /**
+     * Simple base58 encoding (use proper library in production)
+     */
+    encodeBase58(buffer) {
+        const alphabet = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+        let num = BigInt("0x" + buffer.toString("hex"));
+        let result = "";
+        while (num > 0) {
+            const remainder = num % 58n;
+            result = alphabet[Number(remainder)] + result;
+            num = num / 58n;
+        }
+        // Handle leading zeros
+        for (let i = 0; i < buffer.length && buffer[i] === 0; i++) {
+            result = "1" + result;
+        }
+        return result;
+    }
+    /**
+     * Update configuration
+     */
+    updateConfig(config) {
+        this.config = { ...this.config, ...config };
+    }
+    /**
+     * Get current configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+}
+exports.WellKnownManager = WellKnownManager;
+/**
+ * Create well-known endpoint handler
+ */
+function createWellKnownHandler(identity, config) {
+    const manager = new WellKnownManager(identity, config);
+    return {
+        handleDIDDocument() {
+            try {
+                const didDocument = manager.generateDIDDocument();
+                const headers = manager.getDIDDocumentHeaders();
+                return {
+                    status: 200,
+                    headers,
+                    body: JSON.stringify(didDocument, null, 2),
+                };
+            }
+            catch (error) {
+                return {
+                    status: 500,
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify({
+                        error: "Failed to generate DID document",
+                        message: error instanceof Error ? error.message : "Unknown error",
+                    }),
+                };
+            }
+        },
+        handleAgentDocument() {
+            try {
+                const agentDocument = manager.generateAgentDocument();
+                const headers = manager.getAgentDocumentHeaders();
+                return {
+                    status: 200,
+                    headers,
+                    body: JSON.stringify(agentDocument, null, 2),
+                };
+            }
+            catch (error) {
+                return {
+                    status: 500,
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify({
+                        error: "Failed to generate agent document",
+                        message: error instanceof Error ? error.message : "Unknown error",
+                    }),
+                };
+            }
+        },
+    };
+}
+/**
+ * Utility functions
+ */
+/**
+ * Validate DID document structure
+ */
+function validateDIDDocument(doc) {
+    return (typeof doc === "object" &&
+        doc !== null &&
+        Array.isArray(doc["@context"]) &&
+        typeof doc.id === "string" &&
+        doc.id.startsWith("did:") &&
+        Array.isArray(doc.verificationMethod) &&
+        Array.isArray(doc.authentication) &&
+        Array.isArray(doc.assertionMethod));
+}
+/**
+ * Validate agent document structure
+ */
+function validateAgentDocument(doc) {
+    return (typeof doc === "object" &&
+        doc !== null &&
+        typeof doc.id === "string" &&
+        doc.id.startsWith("did:") &&
+        typeof doc.capabilities === "object" &&
+        Array.isArray(doc.capabilities["mcp-i"]) &&
+        doc.capabilities["mcp-i"].length === 3 &&
+        doc.capabilities["mcp-i"].includes("handshake") &&
+        doc.capabilities["mcp-i"].includes("signing") &&
+        doc.capabilities["mcp-i"].includes("verification"));
+}
+/**
+ * Extract DID from URL path (for did:web resolution)
+ */
+function extractDIDFromPath(path, baseUrl) {
+    try {
+        // For did:web, the DID is constructed from the domain and path
+        // Example: /.well-known/did.json -> did:web:example.com
+        // Example: /agents/my-agent/.well-known/did.json -> did:web:example.com:agents:my-agent
+        const url = new URL(baseUrl);
+        const domain = url.hostname;
+        // Remove /.well-known/did.json from path
+        const cleanPath = path.replace("/.well-known/did.json", "");
+        if (cleanPath === "") {
+            return `did:web:${domain}`;
+        }
+        // Convert path segments to DID path components
+        const pathComponents = cleanPath.split("/").filter(Boolean);
+        const didPath = pathComponents.join(":");
+        return `did:web:${domain}:${didPath}`;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/storage/config.d.ts

@@ -0,0 +1,28 @@
+import { StorageMode, StorageConfig } from "@kya-os/contracts/registry";
+/**
+ * Storage configuration utilities for XMCP-I
+ */
+/**
+ * Detects and validates the storage mode from environment variables
+ */
+export declare function detectStorageMode(): StorageMode;
+/**
+ * Creates a complete storage configuration with defaults
+ */
+export declare function createStorageConfig(overrides?: Partial<StorageConfig>): StorageConfig;
+/**
+ * Validates storage mode configuration
+ */
+export declare function validateStorageMode(mode: string): mode is StorageMode;
+/**
+ * Gets storage mode description for logging/debugging
+ */
+export declare function getStorageModeDescription(mode: StorageMode): string;
+/**
+ * Determines if encryption is required for the given storage mode
+ */
+export declare function isEncryptionRequired(mode: StorageMode): boolean;
+/**
+ * Determines if receipt verification is available for the given storage mode
+ */
+export declare function isReceiptVerificationAvailable(_mode: StorageMode): boolean;

package/dist/storage/config.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectStorageMode = detectStorageMode;
+exports.createStorageConfig = createStorageConfig;
+exports.validateStorageMode = validateStorageMode;
+exports.getStorageModeDescription = getStorageModeDescription;
+exports.isEncryptionRequired = isEncryptionRequired;
+exports.isReceiptVerificationAvailable = isReceiptVerificationAvailable;
+const registry_1 = require("@kya-os/contracts/registry");
+/**
+ * Storage configuration utilities for XMCP-I
+ */
+/**
+ * Detects and validates the storage mode from environment variables
+ */
+function detectStorageMode() {
+    const envValue = process.env[registry_1.STORAGE_MODE_ENV_VAR];
+    if (!envValue) {
+        return registry_1.DEFAULT_STORAGE_MODE;
+    }
+    const result = registry_1.StorageModeSchema.safeParse(envValue);
+    if (!result.success) {
+        console.warn(`Invalid ${registry_1.STORAGE_MODE_ENV_VAR}="${envValue}". Valid values: ktaEncrypted, hybridReceiptsOnly, selfHostedAuthoritative. Using default: ${registry_1.DEFAULT_STORAGE_MODE}`);
+        return registry_1.DEFAULT_STORAGE_MODE;
+    }
+    return result.data;
+}
+/**
+ * Creates a complete storage configuration with defaults
+ */
+function createStorageConfig(overrides) {
+    const mode = detectStorageMode();
+    const config = {
+        mode,
+        encryptionEnabled: mode === "ktaEncrypted",
+        receiptVerificationEnabled: true,
+        ktaBaseURL: "https://knowthat.ai",
+        ...overrides,
+    };
+    const result = registry_1.StorageConfigSchema.safeParse(config);
+    if (!result.success) {
+        throw new Error(`Invalid storage configuration: ${result.error.message}`);
+    }
+    return result.data;
+}
+/**
+ * Validates storage mode configuration
+ */
+function validateStorageMode(mode) {
+    return registry_1.StorageModeSchema.safeParse(mode).success;
+}
+/**
+ * Gets storage mode description for logging/debugging
+ */
+function getStorageModeDescription(mode) {
+    switch (mode) {
+        case "ktaEncrypted":
+            return "KTA stores encrypted credential/delegation objects";
+        case "hybridReceiptsOnly":
+            return "KTA stores receipts only; objects stored by issuer/recipient";
+        case "selfHostedAuthoritative":
+            return "Customer stores object + log; KTA mirrors receipt/pointer";
+        default:
+            return "Unknown storage mode";
+    }
+}
+/**
+ * Determines if encryption is required for the given storage mode
+ */
+function isEncryptionRequired(mode) {
+    return mode === "ktaEncrypted";
+}
+/**
+ * Determines if receipt verification is available for the given storage mode
+ */
+function isReceiptVerificationAvailable(_mode) {
+    // All modes support receipt verification
+    return true;
+}

package/dist/storage/delegation.d.ts

@@ -0,0 +1,59 @@
+import { Delegation, DelegationRequest, DelegationResponse, Receipt, StorageConfig } from "@kya-os/contracts/registry";
+/**
+ * Delegation management for XMCP-I runtime
+ */
+export interface DelegationManager {
+    /**
+     * Issue a new delegation
+     */
+    issue(request: DelegationRequest): Promise<DelegationResponse>;
+    /**
+     * Revoke an existing delegation
+     */
+    revoke(delegationRef: string): Promise<Receipt>;
+    /**
+     * Check if a delegation is active
+     */
+    isActive(delegationRef: string): Promise<boolean>;
+    /**
+     * Get delegation details
+     */
+    get(delegationRef: string): Promise<Delegation | null>;
+    /**
+     * List active delegations for a subject
+     */
+    listBySubject(subject: string): Promise<Delegation[]>;
+}
+/**
+ * Default delegation manager implementation
+ */
+export declare class DefaultDelegationManager implements DelegationManager {
+    private config;
+    constructor(config?: Partial<StorageConfig>);
+    issue(request: DelegationRequest): Promise<DelegationResponse>;
+    revoke(_delegationRef: string): Promise<Receipt>;
+    isActive(delegationRef: string): Promise<boolean>;
+    get(delegationRef: string): Promise<Delegation | null>;
+    listBySubject(_subject: string): Promise<Delegation[]>;
+    /**
+     * Encrypt delegation payload for audience
+     */
+    private encryptDelegation;
+}
+/**
+ * Create delegation manager instance
+ */
+export declare function createDelegationManager(config?: Partial<StorageConfig>): DelegationManager;
+/**
+ * Delegation context for runtime use
+ */
+export interface DelegationContext {
+    delegationRef?: string;
+    scopes: string[];
+    audience?: string;
+    expiresAt: number;
+}
+/**
+ * Extract delegation context from proof metadata
+ */
+export declare function extractDelegationContext(delegationRef?: string): DelegationContext | null;