@kya-os/mcp-i-core 1.2.3-canary.6 → 1.3.0

package/OPUS-plan.md

@@ -0,0 +1,352 @@
+# 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.**