@kya-os/mcp-i-core 1.3.13 → 1.3.15

package/OPUS-plan.md

@@ -1,352 +0,0 @@
-# Phase 4 Master Plan: User DID & Identity Linking for MCP-I
-
-**Document Version:** 2.0 (Polished)
-**Date:** November 2024
-**Status:** Ready for Implementation
-**Impact:** Game-Changing Identity Foundation
-
-## Executive Summary
-
-This master plan addresses the critical gap in the MCP-I implementation: persistent user identity. Currently, User DIDs are ephemeral, OAuth integration is disconnected, and delegation creation doesn't follow the MCP-I specification. This plan provides a comprehensive solution that will establish persistent user identity through OAuth linking while maintaining full MCP-I spec compliance.
-
-**Key Innovation:** By linking OAuth identities to persistent User DIDs, we enable true session continuity while preserving the decentralized, cryptographically verifiable nature of the MCP-I identity model.
-
-## Critical Architecture Insights
-
-### The Three-DID Model (Clarified)
-
-Based on comprehensive analysis, the MCP-I architecture requires tracking three distinct DIDs:
-
-1. **User DID** (`issuerDid`): The human who grants permissions
-   - Currently ephemeral `did:key:z6MkUser...`
-   - Phase 4 makes persistent via OAuth linking
-   - Used as `issuerDid` in delegations
-
-2. **Agent DID** (`subjectDid`): The AI/software receiving permissions
-   - Examples: `did:key:z6MkClaude...` (Claude Desktop)
-   - Used as `subjectDid` in delegations
-   - Captured during MCP-I handshake
-
-3. **Server DID** (`serverDid`): The MCP-I server/bouncer
-   - Example: `did:web:service-x-bouncer`
-   - Provides services and validates delegations
-   - Can also act as an agent when calling upstream services
-
-### OAuth Integration Architecture
-
-The AgentShield dashboard already provides OAuth provider configuration:
-- Database: `bouncer_configs` table with OAuth fields
-- UI: `/dashboard/bouncer/config/[projectId]/page.tsx`
-- Current Limitation: Project-level OAuth (not tool-specific)
-
-### Cross-Agent Delegation Validation
-
-The bouncer architecture supports validating delegations from ANY agent:
-- Local agents (Claude Desktop)
-- External SaaS agents (`did:web:agent:saavvy-shopping-mcp`)
-- Other bouncers acting as agents
-- Validation via centralized AgentShield database
-
-## Implementation Plan (Refined)
-
-### Part A: Fix Core Delegation Flow (Critical - 2 days)
-
-**Problem:** API schema mismatch causing delegation creation failures.
-
-**Solution:**
-
-```typescript
-// Before (BROKEN):
-const delegationRequest = {
-  agent_did: request.agent_did,
-  scopes: request.scopes,
-  expires_in_days: expiresInDays,
-};
-
-// After (FIXED):
-const userDid = await this.getUserDidForSession(request.session_id);
-const delegationRecord: DelegationRecord = {
-  id: generateDelegationId(),
-  issuerDid: userDid,                    // User who grants
-  subjectDid: request.agent_did,        // Agent who receives
-  vcId: generateVcId(),
-  constraints: {
-    scopes: request.scopes,
-    notAfter: calculateExpiry(expiresInDays),
-  },
-  signature: await this.signDelegation(...),
-  status: 'active',
-  createdAt: Date.now(),
-};
-
-const delegationRequest = {
-  delegation: delegationRecord  // Full record as expected by API
-};
-```
-
-### Part B: OAuth Identity Linking (Priority - 3 days)
-
-**Innovation:** Link OAuth identities to persistent User DIDs.
-
-```typescript
-// OAuth callback handler enhancement
-async handleOAuthCallback(request: Request): Promise<Response> {
-  const { provider, userInfo } = await this.validateOAuthCallback(request);
-  
-  // Create persistent User DID linked to OAuth identity
-  const userDid = await this.linkOAuthToUserDid(provider, userInfo.sub);
-  
-  // Store mapping for future retrieval
-  await this.identityStorage.set(
-    `oauth:${provider}:${userInfo.sub}`,
-    {
-      userDid,
-      email: userInfo.email,
-      linkedAt: new Date().toISOString(),
-    },
-    { expirationTtl: 90 * 24 * 60 * 60 } // 90 days
-  );
-  
-  return new Response(null, {
-    status: 302,
-    headers: {
-      'Location': '/consent',
-      'Set-Cookie': `user_did=${userDid}; HttpOnly; Secure; SameSite=Strict`
-    }
-  });
-}
-```
-
-### Part C: Multi-Tenant Storage Fix (1 day)
-
-**Problem:** User delegations overwrite each other.
-
-**Solution:** User+Agent scoped storage keys.
-
-```typescript
-// Storage key structure
-const keys = {
-  primary: `delegation:user:${userDid}:agent:${agentDid}`,
-  session: `delegation:session:${sessionId}`,
-  agent: `delegation:agent:${agentDid}:users` // List of users
-};
-```
-
-### Part D: Identity Mode Configuration (2 days)
-
-**Innovation:** Support different deployment scenarios.
-
-```typescript
-export enum IdentityMode {
-  EPHEMERAL = 'ephemeral',   // Dev/test: New DID per session
-  PERSISTENT = 'persistent',  // Production: OAuth required
-  HYBRID = 'hybrid'          // Flexible: OAuth optional
-}
-
-// Mode-based behavior
-switch (config.identityMode) {
-  case IdentityMode.EPHEMERAL:
-    return generateEphemeralDid();
-  case IdentityMode.PERSISTENT:
-    if (!oauthIdentity) throw new Error('OAuth required');
-    return getOrCreatePersistentDid(oauthIdentity);
-  case IdentityMode.HYBRID:
-    return oauthIdentity 
-      ? getOrCreatePersistentDid(oauthIdentity)
-      : generateEphemeralDid();
-}
-```
-
-### Part E: Security & Privacy (2 days)
-
-**GDPR Compliance & Security:**
-
-```typescript
-class PrivacyService {
-  async handleRequest(request: PrivacyRequest) {
-    switch (request.type) {
-      case 'export':
-        return this.exportUserData(request.userDid);
-      case 'delete':
-        return this.deleteAllUserData(request.userDid);
-      case 'opt-out':
-        return this.switchToEphemeral(request.userDid);
-    }
-  }
-}
-```
-
-### Part F: Enhanced Handshake (1 day)
-
-**Proper DID Exchange:**
-
-```typescript
-async handleHandshake(request: HandshakeRequest) {
-  const identity = await this.getIdentity();
-  const userDid = await this.userDidManager.getOrCreateUserDid(sessionId);
-  
-  const session = {
-    id: sessionId,
-    userDid,                    // Human user DID
-    agentDid: request.agentDid, // AI agent DID
-    serverDid: identity.did,    // Server/bouncer DID
-    createdAt: Date.now(),
-  };
-  
-  return {
-    sessionId,
-    serverDid: identity.did,
-    userDid,  // Include for transparency
-    capabilities: ['identity', 'proof', 'delegation'],
-  };
-}
-```
-
-## Architecture Validation
-
-### Scenario 1: Claude Desktop → Service X
-```
-1. Claude Desktop (agentDid) → Handshake → service-x-bouncer (serverDid)
-2. Tool call requires delegation
-3. OAuth flow → User authenticates with GitHub
-4. User DID created/retrieved: did:key:z6MkUserPersistent
-5. Delegation: User (issuerDid) → Claude (subjectDid)
-6. Future sessions: Same User DID via GitHub identity
-```
-
-### Scenario 2: SaaS Agent → Service X
-```
-1. saavvy-shopping-mcp (agentDid) → Handshake → service-x-bouncer
-2. Delegation validation via AgentShield API
-3. Cross-agent delegation works seamlessly
-```
-
-### Scenario 3: Chained Delegations (Future)
-```
-1. User → Shopping Assistant (local MCP)
-2. Shopping Assistant → Service X (delegation chain)
-3. Memory graph storage tracks relationships
-```
-
-## Success Metrics
-
-### Technical Metrics
-- ✅ User DIDs persist across sessions via OAuth
-- ✅ Delegations include proper `issuerDid` and `subjectDid`
-- ✅ API schema matches AgentShield expectations
-- ✅ Multi-tenant conflicts resolved
-- ✅ <100ms overhead for DID operations
-- ✅ 95% test coverage for new code
-
-### Business Impact
-- 🎯 Users authenticate once, delegations persist
-- 🎯 True "Know Your User" capability
-- 🎯 Foundation for reputation systems
-- 🎯 GDPR compliant with privacy controls
-- 🎯 Enterprise-ready identity management
-
-## Risk Mitigation
-
-### Risk: Performance Impact
-- **Mitigation:** Aggressive caching, async operations
-- **Monitoring:** Track p95 latency for DID operations
-
-### Risk: Privacy Concerns  
-- **Mitigation:** Clear consent, data deletion API, identity modes
-- **Compliance:** GDPR audit before launch
-
-### Risk: OAuth Provider Downtime
-- **Mitigation:** Multi-provider support, graceful fallback
-- **Monitoring:** Provider health checks
-
-## Timeline
-
-### Week 1: Foundation (5 days)
-- Days 1-2: Part A - Fix delegation API
-- Days 3-5: Part B - OAuth integration (partial)
-
-### Week 2: Core Identity (5 days)
-- Days 6-7: Part B - Complete OAuth linking
-- Day 8: Part C - Storage fixes
-- Days 9-10: Part D - Identity modes
-
-### Week 3: Enhancement (4 days)
-- Days 11-12: Part E - Security/privacy
-- Day 13: Part F - Enhanced handshake
-- Day 14: Integration testing
-
-**Total: 14 working days**
-
-## Testing Strategy
-
-### Unit Tests
-```typescript
-describe('OAuth Identity Linking', () => {
-  it('creates persistent User DID for new OAuth identity');
-  it('retrieves same User DID for returning OAuth user');
-  it('handles multiple OAuth providers per user');
-  it('respects identity mode configuration');
-});
-```
-
-### Integration Tests
-- Full OAuth → Consent → Delegation flow
-- Multi-user, multi-agent scenarios
-- Cross-session persistence validation
-
-### E2E Tests
-- User journey: Login → Approve → Return next day
-- Privacy: Request data export/deletion
-- Security: Token expiration, revocation
-
-## Why This Plan Is Game-Changing
-
-### 1. **True Persistent Identity**
-Unlike current ephemeral DIDs, users maintain identity across sessions, enabling:
-- Reputation building
-- Audit trails
-- Compliance tracking
-
-### 2. **OAuth Bridge to Decentralized Identity**
-Leverages familiar OAuth while establishing decentralized DIDs:
-- Easy user onboarding
-- Enterprise integration ready
-- Progressive decentralization path
-
-### 3. **Multi-Agent Ecosystem Ready**
-Supports complex delegation scenarios:
-- Agent-to-agent delegations
-- Service composition
-- Delegation chains
-
-### 4. **Privacy-First Architecture**
-Users control their identity:
-- Choose persistence level
-- Delete data anytime
-- Switch modes dynamically
-
-### 5. **MCP-I Spec Compliance**
-Full alignment with spec while solving real-world needs:
-- Proper issuer/subject model
-- W3C VC compatibility
-- CRISP constraints support
-
-## Comparison with V3 Plan
-
-### Dependencies Identified
-1. V3 Scaffolder Refactor MUST complete first
-2. Consent service creation can merge with Part A fixes
-3. Security work can parallelize
-
-### Unified Approach
-- Phase 4 provides detailed implementation for V3's Phase 1
-- Total timeline: 3 weeks with parallel work
-- Clear execution order established
-
-## Conclusion
-
-This Phase 4 plan transforms the MCP-I implementation from a proof-of-concept to a production-ready identity system. By establishing persistent User DIDs through OAuth linking, we create a foundation for trust, reputation, and compliance in the AI agent ecosystem.
-
-The plan addresses all critical issues identified during review, provides clear implementation steps, and maintains full MCP-I specification compliance while solving real-world identity persistence needs.
-
-**This is not just an implementation plan—it's the blueprint for the future of verifiable AI agent identity.**