@kya-os/mcp-i 0.1.0-alpha.2.2 → 0.1.0-alpha.2.4

package/README.md

@@ -1,10 +1,34 @@
 # @kya-os/mcp-i
 
-Ultra-light MCP Identity auto-registration. Give any MCP server a verifiable identity with just 2 lines of code.
+The SEO package for AI agents. Register your MCP server and get automatic directory listings in 2 lines of code.
 
-## The Vision
+[![npm version](https://img.shields.io/npm/v/@kya-os/mcp-i.svg)](https://www.npmjs.com/package/@kya-os/mcp-i)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![MCP-I Conformance](https://img.shields.io/badge/MCP--I-Level%202-green)](https://modelcontextprotocol-identity.io)
 
-Make MCP-I adoption a no-brainer for the hundreds of thousands of MCP servers. Zero friction, immediate benefits.
+## Why Your MCP Server Needs This
+
+**For MCP Server Developers:**
+
+- **Get a DID** - Your agent gets a permanent, cryptographic identity from knowthat.ai
+- **Automatic Directory Listings** - Submit to multiple directories with zero extra work
+- **Build Reputation** - Every interaction is signed and verifiable
+- **Future-Proof** - Ready for the decentralized agent ecosystem
+- **Production-Ready** - Optimized for Lambda, Edge, Next.js, and traditional deployments
+
+**For Directory Maintainers:**
+
+- **Easy Integration** - List MCP-I compliant agents automatically
+- **Verified Agents** - Only list agents with cryptographic proof
+- **Join the Network** - Tap into the growing MCP-I ecosystem
+
+## How It Works
+
+1. **Identity Registration**: Your agent is registered with knowthat.ai (the MCP-I registry)
+2. **DID Generation**: You get a `did:web:knowthat.ai:agents:your-agent` identifier
+3. **Directory Submission**: Based on your preferences, knowthat.ai submits your agent to directories
+4. **Cryptographic Signing**: All agent responses are signed with your private key
+5. **Verification**: Anyone can verify your agent's identity and authenticity
 
 ## Installation
 
@@ -12,86 +36,262 @@ Make MCP-I adoption a no-brainer for the hundreds of thousands of MCP servers. Z
 npm install @kya-os/mcp-i
 ```
 
-## Usage
+## Quick Start
 
-### Option 1: Zero Configuration (Recommended)
+### 1. Zero Configuration (Recommended)
 
 ```typescript
-import "@kya-os/mcp-i/auto";  // That's it! Your server now has identity
+import "@kya-os/mcp-i/auto";
+// That's it! Your server now has cryptographic identity
 ```
 
-### Option 2: With Configuration
+### 2. Production Configuration
 
 ```typescript
 import { enableMCPIdentity } from "@kya-os/mcp-i";
 
+const identity = await enableMCPIdentity({
+  name: "Production Agent",
+
+  // Auto-detect runtime (Lambda, Edge, Node.js)
+  storage: "auto",
+  transport: "auto",
+
+  // Encrypt private keys at rest
+  encryptionPassword: process.env.AGENT_KEY_PASSWORD,
+
+  // Professional logging
+  logLevel: "error", // or 'silent' for production
+
+  // Directory preferences (optional)
+  directories: "verified", // List on all verified directories
+  // OR directories: ["smithery", "glama"] // Specific directories
+  // OR directories: "none" // No directory listings
+});
+
+// Enable automatic key rotation
+await identity.enableAutoRotation({
+  maxAge: 90 * 24 * 60 * 60 * 1000, // 90 days
+  maxSignatures: 1_000_000, // 1M signatures
+});
+```
+
+### 3. Lambda/Edge Runtime
+
+```typescript
+// Automatic configuration for serverless
+const identity = await enableMCPIdentity({
+  name: "Serverless Agent",
+  storage: "memory", // No file system needed
+  transport: "fetch", // Native fetch for edge
+  logLevel: "silent", // No console output
+});
+```
+
+## Production Features
+
+### Performance Optimizations
+
+- **Lazy Loading**: Crypto libraries load only when needed
+- **Signature Caching**: Repeated signatures are 10x faster
+- **Precomputed Values**: DIDs and keys cached in memory
+- **Optimized Transport**: Auto-selects axios vs fetch
+
+### Security Features
+
+- **Key Encryption**: Private keys encrypted with AES-256-GCM
+- **Key Rotation**: Automatic rotation based on age/usage
+- **Nonce Tracking**: Prevents replay attacks
+- **Timestamp Validation**: Configurable tolerance windows
+
+### Runtime Support
+
+- **AWS Lambda**: Automatic memory storage
+- **Vercel Edge**: Native fetch transport
+- **Cloudflare Workers**: Full compatibility
+- **Node.js**: Traditional file storage
+
+### Directory Listings
+
+```typescript
+// Configure directory listings
 await enableMCPIdentity({
-  name: "Calendar Booker",
-  description: "Professional calendar booking for AI agents",
-  repository: "https://github.com/awesome-dev/calendar-booker"
+  name: "My Agent",
+
+  // Option 1: List on all verified directories
+  directories: "verified",
+
+  // Option 2: List on specific directories
+  directories: ["smithery", "glama"],
+
+  // Option 3: No directory listings (registry only)
+  directories: "none",
 });
+
+// Directory preferences are sent to knowthat.ai
+// The registry handles submissions to your chosen directories
 ```
 
-## What Happens
-
-1. **First Run**: Automatically registers with knowthat.ai and gets a DID
-2. **Identity Saved**: Persists to `.env.local` and `.mcp-identity.json`
-3. **All Responses Signed**: Every response includes `_mcp_identity` field
-4. **MCP-I Handshake**: Automatically handles challenge-response authentication
-5. **Capabilities Advertised**: Server advertises MCP-I support to clients
-
-## Example Response
-
-```json
-{
-  "content": [{
-    "type": "text",
-    "text": "Event booked successfully!"
-  }],
-  "_mcp_identity": {
-    "did": "did:web:knowthat.ai:agents:calendar-booker",
-    "signature": "0x3045...",
-    "timestamp": "2025-01-31T10:00:00Z",
-    "conformanceLevel": 2
-  }
+## Advanced Usage
+
+### Key Rotation
+
+```typescript
+// Check key health
+const health = identity.checkKeyHealth();
+console.log(`Key age: ${health.age}ms`);
+console.log(`Signatures: ${health.signatureCount}`);
+console.log(`Should rotate: ${health.shouldRotate}`);
+
+// Manual rotation
+const result = await identity.rotateKeys("security-policy");
+if (result.success) {
+  console.log(`Grace period ends: ${result.gracePeriodEnd}`);
 }
+
+// Automatic rotation
+await identity.enableAutoRotation({
+  maxAge: 30 * 24 * 60 * 60 * 1000, // 30 days
+  maxSignatures: 500_000, // 500k signatures
+});
 ```
 
-## Benefits
+### Edit/Claim URLs
 
-- ✅ **Verification Badge** on Smithery and other directories
-- 🔝 **Priority Discovery** in search results
-- 🔐 **Access to Identity-Aware APIs** with higher rate limits
-- 📊 **Analytics & Reputation** tracking
-- 🛡️ **Protection Against Impersonation**
+```typescript
+// Get signed URLs for editing
+const { editUrl, claimUrl } = await identity.requestEditAccess();
 
-## How It Works
+// Edit URL - for existing agents
+console.log("Edit your agent:", editUrl);
 
-The package automatically:
-1. Patches the MCP Server class to inject identity into all responses
-2. Handles MCP-I challenge-response authentication
-3. Advertises capabilities in server info
-4. Works with all transports (STDIO, SSE, HTTP)
+// Claim URL - for draft/unclaimed agents
+console.log("Claim your agent:", claimUrl);
+```
 
-## Environment Variables
+### Custom Storage
 
-After first run, these are saved automatically:
+```typescript
+// Encrypted file storage
+await enableMCPIdentity({
+  storage: "file",
+  persistencePath: "/secure/location/.identity",
+  encryptionPassword: "strong-password",
+});
+
+// Memory storage with custom key
+await enableMCPIdentity({
+  storage: "memory",
+  memoryKey: "agent-123", // Useful for multiple agents
+});
+```
+
+### Custom Logger
+
+```typescript
+await enableMCPIdentity({
+  logger: {
+    debug: (msg, ...args) => myLogger.debug(msg, args),
+    info: (msg, ...args) => myLogger.info(msg, args),
+    warn: (msg, ...args) => myLogger.warn(msg, args),
+    error: (msg, ...args) => myLogger.error(msg, args),
+  },
+});
+```
+
+## API Reference
+
+### `enableMCPIdentity(options?)`
+
+Main function to enable identity for your MCP server.
+
+**Options:**
+
+```typescript
+interface MCPIdentityOptions {
+  // Basic info
+  name?: string;
+  description?: string;
+  repository?: string;
+
+  // Storage
+  storage?: "file" | "memory" | "auto";
+  persistencePath?: string;
+  memoryKey?: string;
+  encryptionPassword?: string;
+
+  // Transport
+  transport?: "axios" | "fetch" | "auto";
+
+  // Security
+  timestampTolerance?: number; // Default: 60000ms
+  enableNonceTracking?: boolean; // Default: true
+
+  // Directory listings
+  directories?: string[] | "verified" | "none"; // Default: "verified"
+
+  // Development
+  mode?: "development" | "production";
+
+  // Logging
+  logger?: Logger;
+  logLevel?: "debug" | "info" | "warn" | "error" | "silent";
+}
+```
+
+### `MCPIdentity` Methods
+
+- `sign(message)`: Sign with caching
+- `verify(message, signature, publicKey?)`: Verify signatures
+- `respondToChallenge(challenge)`: MCP-I authentication
+- `signResponse(response)`: Add identity to responses
+- `requestEditAccess()`: Get edit/claim URLs
+- `rotateKeys(reason?)`: Manual key rotation
+- `enableAutoRotation(policy?)`: Automatic rotation
+- `checkKeyHealth()`: Key rotation status
+
+## Files Created
 
-```bash
-AGENT_DID="did:web:knowthat.ai:agents:your-agent"
-AGENT_PUBLIC_KEY="base64-encoded-public-key"
-AGENT_PRIVATE_KEY="base64-encoded-private-key"
-AGENT_ID="uuid"
-AGENT_SLUG="your-agent-slug"
 ```
+.mcp-identity.json    # Your agent's identity (encrypted if password set)
+```
+
+## Security Best Practices
+
+1. **Use encryption in production**: Always set `encryptionPassword`
+2. **Enable key rotation**: Set up automatic rotation policies
+3. **Secure storage**: Use appropriate file permissions
+4. **Monitor key health**: Check rotation status regularly
+5. **Add to .gitignore**: Never commit identity files
+
+## Performance Tips
+
+1. **Use memory storage** for Lambda/Edge runtimes
+2. **Enable signature caching** (automatic)
+3. **Use 'silent' log level** in production
+4. **Let transport auto-select** based on runtime
+5. **Preload identity** during cold starts
+
+## Troubleshooting
+
+### Lambda/Edge Issues
+
+- Ensure `storage: 'memory'` or `'auto'`
+- Use `transport: 'fetch'` for edge runtimes
+- Set `logLevel: 'silent'` to avoid console issues
+
+### Key Rotation Failures
+
+- Check network connectivity to knowthat.ai
+- Verify current keys are not corrupted
+- Manual rotation: `await identity.rotateKeys('recovery')`
 
-## Security
+### Performance Issues
 
-- Private keys are stored locally, never sent to knowthat.ai
-- All responses are cryptographically signed with Ed25519
-- Challenge-response prevents replay attacks
-- Nonce tracking prevents reuse
+- Verify signature caching is working
+- Check lazy loading (should see delayed first signature)
+- Use memory storage when possible
 
 ## License
 
-MIT
+MIT

package/dist/auto.d.ts

@@ -1,13 +1 @@
-/**
- * Auto-initialization for MCP Identity
- *
- * Just import this file to automatically enable MCP-I for any MCP server:
- *
- * ```typescript
- * import "@kya-os/mcp-i/auto";
- * ```
- *
- * That's it! Your MCP server now has identity.
- */
 export {};
-//# sourceMappingURL=auto.d.ts.map

package/dist/auto.js

@@ -1,24 +1,13 @@
 "use strict";
-/**
- * Auto-initialization for MCP Identity
- *
- * Just import this file to automatically enable MCP-I for any MCP server:
- *
- * ```typescript
- * import "@kya-os/mcp-i/auto";
- * ```
- *
- * That's it! Your MCP server now has identity.
- */
 Object.defineProperty(exports, "__esModule", { value: true });
 const index_1 = require("./index");
-// Auto-initialize on import
+const logger_1 = require("./logger");
 (async () => {
     try {
         await (0, index_1.enableMCPIdentity)();
     }
     catch (error) {
-        console.error('[MCP-I] Failed to auto-initialize:', error);
+        const logger = (0, logger_1.getLogger)();
+        logger.error('[MCP-I] Failed to auto-initialize:', error);
     }
 })();
-//# sourceMappingURL=auto.js.map

package/dist/crypto.d.ts

@@ -1,32 +1,16 @@
-/**
- * Cryptographic utilities for MCP-I
- * Implements Ed25519 signing and verification for challenge-response authentication
- */
-/**
- * Generate a new Ed25519 key pair
- */
-export declare function generateKeyPair(): Promise<{
+export interface PrecomputedKeyPair {
     publicKey: string;
     privateKey: string;
-}>;
-/**
- * Sign a message with Ed25519
- */
+    publicKeyBytes?: Uint8Array;
+    privateKeyBytes?: Uint8Array;
+}
+export declare function generateKeyPair(): Promise<PrecomputedKeyPair>;
 export declare function sign(message: string | Buffer, privateKeyBase64: string): Promise<string>;
-/**
- * Verify an Ed25519 signature
- */
 export declare function verify(message: string | Buffer, signatureBase64: string, publicKeyBase64: string): Promise<boolean>;
-/**
- * Generate a cryptographically secure nonce
- */
-export declare function generateNonce(length?: number): string;
-/**
- * Constant-time string comparison to prevent timing attacks
- */
+export declare function generateNonce(length?: number): Promise<string>;
+export declare function generateNonceSync(length?: number): string;
 export declare function constantTimeEqual(a: string, b: string): boolean;
-/**
- * Convert Ed25519 public key to did:key format
- */
 export declare function publicKeyToDid(publicKeyBase64: string): string;
-//# sourceMappingURL=crypto.d.ts.map
+export declare function encrypt(data: string, password: string): Promise<string>;
+export declare function decrypt(encryptedData: string, password: string): Promise<string>;
+export declare function clearCache(): void;

package/dist/crypto.js

@@ -1,8 +1,4 @@
 "use strict";
-/**
- * Cryptographic utilities for MCP-I
- * Implements Ed25519 signing and verification for challenge-response authentication
- */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -41,57 +37,93 @@ exports.generateKeyPair = generateKeyPair;
 exports.sign = sign;
 exports.verify = verify;
 exports.generateNonce = generateNonce;
+exports.generateNonceSync = generateNonceSync;
 exports.constantTimeEqual = constantTimeEqual;
 exports.publicKeyToDid = publicKeyToDid;
-const ed25519 = __importStar(require("@noble/ed25519"));
-const crypto_1 = require("crypto");
-/**
- * Generate a new Ed25519 key pair
- */
+exports.encrypt = encrypt;
+exports.decrypt = decrypt;
+exports.clearCache = clearCache;
+let ed25519 = null;
+let cryptoModule = null;
+const signatureCache = new Map();
+const MAX_CACHE_SIZE = 100;
+async function loadEd25519() {
+    if (!ed25519) {
+        ed25519 = await Promise.resolve().then(() => __importStar(require('@noble/ed25519')));
+    }
+    return ed25519;
+}
+async function loadCrypto() {
+    if (!cryptoModule) {
+        cryptoModule = await Promise.resolve().then(() => __importStar(require('crypto')));
+    }
+    return cryptoModule;
+}
 async function generateKeyPair() {
-    const privateKey = ed25519.utils.randomPrivateKey();
-    const publicKey = await ed25519.getPublicKeyAsync(privateKey);
+    const ed = await loadEd25519();
+    const privateKeyBytes = ed.utils.randomPrivateKey();
+    const publicKeyBytes = await ed.getPublicKeyAsync(privateKeyBytes);
+    const publicKey = Buffer.from(publicKeyBytes).toString('base64');
+    const privateKey = Buffer.from(privateKeyBytes).toString('base64');
     return {
-        publicKey: Buffer.from(publicKey).toString('base64'),
-        privateKey: Buffer.from(privateKey).toString('base64')
+        publicKey,
+        privateKey,
+        publicKeyBytes,
+        privateKeyBytes
     };
 }
-/**
- * Sign a message with Ed25519
- */
 async function sign(message, privateKeyBase64) {
+    const messageStr = typeof message === 'string' ? message : message.toString('base64');
+    const cacheKey = `${privateKeyBase64}:${messageStr}`;
+    const cached = signatureCache.get(cacheKey);
+    if (cached) {
+        return cached;
+    }
+    const ed = await loadEd25519();
     const messageBuffer = typeof message === 'string'
         ? Buffer.from(message, 'utf-8')
         : message;
     const privateKey = Buffer.from(privateKeyBase64, 'base64');
-    const signature = await ed25519.signAsync(messageBuffer, privateKey);
-    return Buffer.from(signature).toString('base64');
+    const signature = await ed.signAsync(messageBuffer, privateKey);
+    const signatureBase64 = Buffer.from(signature).toString('base64');
+    if (signatureCache.size >= MAX_CACHE_SIZE) {
+        const firstKey = signatureCache.keys().next().value;
+        if (firstKey) {
+            signatureCache.delete(firstKey);
+        }
+    }
+    signatureCache.set(cacheKey, signatureBase64);
+    return signatureBase64;
 }
-/**
- * Verify an Ed25519 signature
- */
 async function verify(message, signatureBase64, publicKeyBase64) {
     try {
+        const ed = await loadEd25519();
         const messageBuffer = typeof message === 'string'
             ? Buffer.from(message, 'utf-8')
             : message;
         const signature = Buffer.from(signatureBase64, 'base64');
         const publicKey = Buffer.from(publicKeyBase64, 'base64');
-        return await ed25519.verifyAsync(signature, messageBuffer, publicKey);
+        return await ed.verifyAsync(signature, messageBuffer, publicKey);
     }
     catch {
         return false;
     }
 }
-/**
- * Generate a cryptographically secure nonce
- */
-function generateNonce(length = 32) {
-    return (0, crypto_1.randomBytes)(length).toString('hex');
+async function generateNonce(length = 32) {
+    const crypto = await loadCrypto();
+    return crypto.randomBytes(length).toString('hex');
+}
+function generateNonceSync(length = 32) {
+    if (typeof globalThis.crypto !== 'undefined' && globalThis.crypto.getRandomValues) {
+        const bytes = new Uint8Array(length);
+        globalThis.crypto.getRandomValues(bytes);
+        return Buffer.from(bytes).toString('hex');
+    }
+    else {
+        const crypto = require('crypto');
+        return crypto.randomBytes(length).toString('hex');
+    }
 }
-/**
- * Constant-time string comparison to prevent timing attacks
- */
 function constantTimeEqual(a, b) {
     if (a.length !== b.length) {
         return false;
@@ -102,16 +134,64 @@ function constantTimeEqual(a, b) {
     }
     return result === 0;
 }
-/**
- * Convert Ed25519 public key to did:key format
- */
 function publicKeyToDid(publicKeyBase64) {
     const publicKey = Buffer.from(publicKeyBase64, 'base64');
-    // Multicodec ed25519-pub header (0xed 0x01)
     const multicodec = Buffer.from([0xed, 0x01]);
     const multikey = Buffer.concat([multicodec, publicKey]);
-    // Base58 encode (simplified - in production use a proper base58 library)
-    // For now, just return a placeholder
     return `did:key:z${multikey.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '')}`;
 }
-//# sourceMappingURL=crypto.js.map
+async function encrypt(data, password) {
+    const encoder = new TextEncoder();
+    const salt = new Uint8Array(16);
+    globalThis.crypto.getRandomValues(salt);
+    const keyMaterial = await globalThis.crypto.subtle.importKey('raw', encoder.encode(password), 'PBKDF2', false, ['deriveKey']);
+    const key = await globalThis.crypto.subtle.deriveKey({
+        name: 'PBKDF2',
+        salt,
+        iterations: 100000,
+        hash: 'SHA-256'
+    }, keyMaterial, { name: 'AES-GCM', length: 256 }, false, ['encrypt']);
+    const iv = new Uint8Array(12);
+    globalThis.crypto.getRandomValues(iv);
+    const encrypted = await globalThis.crypto.subtle.encrypt({ name: 'AES-GCM', iv }, key, encoder.encode(data));
+    const combined = new Uint8Array(salt.length + iv.length + encrypted.byteLength);
+    combined.set(salt);
+    combined.set(iv, salt.length);
+    combined.set(new Uint8Array(encrypted), salt.length + iv.length);
+    return 'enc:' + Buffer.from(combined).toString('base64');
+}
+async function decrypt(encryptedData, password) {
+    let dataToDecrypt = encryptedData;
+    if (encryptedData.startsWith('enc:')) {
+        dataToDecrypt = encryptedData.slice(4);
+    }
+    if (!dataToDecrypt || dataToDecrypt.length < 44) {
+        return encryptedData;
+    }
+    const encoder = new TextEncoder();
+    const decoder = new TextDecoder();
+    try {
+        const combined = Buffer.from(dataToDecrypt, 'base64');
+        if (combined.length < 29) {
+            return encryptedData;
+        }
+        const salt = combined.slice(0, 16);
+        const iv = combined.slice(16, 28);
+        const encrypted = combined.slice(28);
+        const keyMaterial = await globalThis.crypto.subtle.importKey('raw', encoder.encode(password), 'PBKDF2', false, ['deriveKey']);
+        const key = await globalThis.crypto.subtle.deriveKey({
+            name: 'PBKDF2',
+            salt: new Uint8Array(salt),
+            iterations: 100000,
+            hash: 'SHA-256'
+        }, keyMaterial, { name: 'AES-GCM', length: 256 }, false, ['decrypt']);
+        const decrypted = await globalThis.crypto.subtle.decrypt({ name: 'AES-GCM', iv: new Uint8Array(iv) }, key, new Uint8Array(encrypted));
+        return decoder.decode(decrypted);
+    }
+    catch (error) {
+        throw new Error('Failed to decrypt data: invalid password or corrupted data');
+    }
+}
+function clearCache() {
+    signatureCache.clear();
+}

package/dist/dev-helper.d.ts

@@ -0,0 +1,3 @@
+import { MCPIdentity } from './index';
+export declare function initWithDevExperience(options?: any): Promise<MCPIdentity>;
+export declare function showAgentStatus(identity: MCPIdentity): void;