@kya-os/mcp-i-core 1.3.7-canary.0 → 1.3.7-canary.clientinfo.20251126041014

package/PHASE_4_USER_DID_IDENTITY_LINKING_PLAN.md

@@ -0,0 +1,1240 @@
+Based on my comprehensive investigation, I can now answer all your questions with empirical evidence from the codebase:
+
+A. MCP-I Handshake Usage
+
+Yes, we use the MCP-I handshake! It occurs in packages/mcp-i-core/src/runtime/base.ts (lines 109-150):
+
+async handleHandshake(request: any): Promise<any> {
+// Creates session with:
+// - agentDid: from request (MCP client's DID)
+// - serverDid: our server's DID
+// - userDid: generated for the user
+}
+
+When it occurs: During initial MCP connection between client and server.
+
+Note: Our implementation is simplified compared to the full spec - we don't implement the cryptographic challenge-response, but we do exchange DIDs and establish sessions.
+
+B. OAuth Provider UI in AgentShield Dashboard
+
+Yes, I was aware! The OAuth provider UI exists at:
+
+- Database: bouncer_configs table with OAuth fields
+- UI: /dashboard/bouncer/config/[projectId]/page.tsx
+- Providers: GitHub, Google, Microsoft, Slack, Stripe, etc.
+
+Expected Flow:
+
+1. Customer adds OAuth provider (e.g., GitHub) in bouncer dashboard
+2. Tool requires delegation → triggers OAuth flow with that provider
+3. User authenticates via GitHub OAuth
+4. UserDID linked to GitHub identity (this is what Phase 4 adds!)
+5. Future calls: Same UserDID retrieved via GitHub identity, no re-delegation needed
+
+Critical Finding: Currently OAuth is project-level, not tool-specific. All tools in a project use the same OAuth provider.
+
+C. Tool-to-OAuth Assignment
+
+Current State: Tools CANNOT be assigned to specific OAuth providers.
+
+How it works now:
+
+- Tools specify abstract scopes: ['files:read', 'files:write']
+- Project configures ONE OAuth provider
+- Scopes auto-translate: files:read → GitHub: ['public_repo']
+
+North Star Architecture (for future):
+// Add tool-specific OAuth mapping
+toolOAuthMappings: {
+'github_code_reader': { provider: 'github', scopes: ['repo'] },
+'google_drive_reader': { provider: 'google', scopes: ['drive.readonly'] },
+'slack_messenger': { provider: 'slack', scopes: ['chat:write'] }
+}
+
+Iterative Approach:
+
+- Phase 4: Single OAuth provider per project (current)
+- Phase 5: Multiple providers, tool-specific assignment
+- Phase 6: Dynamic provider selection based on context
+
+D. DID Tracking Confirmation
+
+Yes, after Phase 4 we track ALL these DIDs:
+
+1. ✅ UserDID: The human user (issuerDid in delegations)
+   - Currently ephemeral did:key:z6MkUser...
+   - Phase 4 makes it persistent via OAuth linking
+
+2. ✅ MCP Client DID: The AI client (e.g., Claude Desktop)
+   - Tracked as agentDid in handshake
+   - Example: did:key:z6MkClaude...
+
+3. ✅ Agent DID: Same as MCP Client DID
+   - The entity making tool calls (subjectDid in delegations)
+
+4. ✅ Server/Bouncer DID: The MCP-I server
+   - Example: did:web:service-x-bouncer
+
+E. Cross-Agent Delegation Validation
+
+YES! The bouncer can validate delegations from ANY agent:
+
+Evidence from agent-shield/apps/web/app/api/v1/bouncer/delegations/verify/route.ts:
+
+- Accepts any agent_did
+- Queries centralized AgentShield database
+- Returns valid/invalid for that agent+scopes combination
+
+This means service-x-bouncer can validate delegations for:
+
+- Local agents (Claude Desktop)
+- External SaaS agents (did:web:agent:saavvy-shopping-mcp)
+- Other bouncers acting as agents
+
+F. Scenario Explanations
+
+Scenario 1: Claude Desktop + service-x-bouncer
+
+Claude Desktop (agentDid) → Handshake → service-x-bouncer (serverDid)
+→ Tool call → Check delegation → OAuth flow → User grants (userDid)
+→ Delegation stored → Tool executes
+
+Scenario 2: SaaS Agent → service-x
+
+saavvy-shopping-mcp (agentDid) → Handshake → service-x-bouncer (serverDid)
+
+- ✅ Can do handshake: Yes, any agent can handshake
+- ✅ Can validate delegations: Yes, via AgentShield API
+- What it enables: Session-based tool calls with delegation verification
+- Note: Still requires human (UserDID) to grant initial delegation
+
+Scenario 3: Shopping Assistant → service-x
+
+Claude → shopping-assistant (local MCP) → service-x-bouncer (remote)
+Two options:
+
+1. Direct delegation: User authorizes shopping-assistant to service-x
+2. Delegation chain: shopping-assistant's existing delegation chains to service-x (future feature)
+
+G. Agent DID Classification
+
+Yes, Agent DIDs apply to ALL of these:
+
+An "Agent" = Any software making tool calls to an MCP-I server
+
+- ✅ MCP servers ('shopping-assistant'): Has agentDid when calling others
+- ✅ Bouncers ('service-x-bouncer'): Has serverDid when receiving, agentDid when calling upstream
+- ✅ SaaS businesses ('saavvy-shopping-mcp'): Has agentDid when calling MCP-I APIs
+- ✅ AI Clients (Claude Desktop): Primary use case, has agentDid
+
+H. MCP Client Identity & Reputation Guidance
+
+- **Persistent MCP Client Identity**: The handshake already surfaces `clientInfo`; Phase 4 formalizes storing a durable client identifier (client-issued DID preferred, otherwise a signed instance token) in the session envelope so telemetry survives chat restarts.
+- **Dashboard Attribution**: Delegation/proof logs must include `{ issuerDid, subjectDid, clientInstanceId }` so operators can separate “service agent” activity from the upstream MCP client that initiated the call.
+- **Multi-Hop Enforcement**: If an intermediate MCP-I runtime (e.g., Honey) calls downstream services, we treat that runtime’s DID as the delegation subject while propagating the origin client metadata for reputation scoring and selective throttling.
+
+```markdown
+# Updated Phase 4 Plan with Architecture Clarifications
+
+Based on a comprehensive analysis, here's the refined plan addressing all architectural concerns:
+
+## Part A: Fix Core Delegation Flow (Priority 1)
+
+✅ Already in plan - No changes needed
+
+- Update delegation creation to include proper `issuerDid` (UserDID)
+- Fix API schema to send full `DelegationRecord`
+
+## Part B: OAuth Integration with AgentShield Dashboard (Priority 2)
+
+Updated to reflect existing OAuth UI:
+
+1. Leverage existing OAuth provider configuration in `bouncer_configs`
+2. Link OAuth identity to persistent UserDID during consent flow
+3. Store mapping in KV: `oauth:github:user123 → did:key:z6MkUser...`
+4. Future tool calls retrieve UserDID via OAuth identity
+
+## Part C: MCP-I Handshake Enhancement (NEW - Priority 3)
+
+Add proper DID exchange during handshake:
+
+1. Ensure `agentDid` is captured from MCP client
+2. Generate/retrieve persistent UserDID if OAuth session exists
+3. Store all DIDs in session context:
+   - `agentDid` (MCP client/agent making request)
+   - `serverDid` (bouncer/service receiving request)
+   - `userDid` (human who grants delegations)
+
+## Part D: Cross-Agent Delegation Support (Priority 4)
+
+Ensure delegations work across different agents:
+
+1. Verify AgentShield API accepts any `agent_did` format
+2. Test delegation validation for external agents (`did:web`)
+3. Document how SaaS agents can integrate with bouncers
+
+## Part E: Future Enhancements (Document but don't implement)
+
+### Tool-Specific OAuth Providers (Phase 5):
+
+- Design schema for tool → OAuth provider mapping
+- Plan migration from project-level to tool-level OAuth
+
+### Delegation Chains (Phase 6):
+
+- Enable Agent A → Agent B → Agent C delegations
+- Leverage existing `memory-graph-storage.ts`
+
+## Implementation Changes Needed:
+
+1. Fix UserDID persistence via OAuth linking (main goal)
+2. Ensure handshake captures all DIDs correctly
+3. Document multi-agent scenarios for customers
+4. Test cross-agent delegation validation
+
+## Success Criteria:
+
+- UserDID persists across sessions via OAuth
+- All 3 DID types tracked (User, Agent, Server)
+- External agents can validate delegations
+- OAuth provider from dashboard is used for consent
+- Documentation explains all scenarios clearly
+
+This plan maintains Phase 4's core goal (persistent User identity) while ensuring it fits properly into the broader MCP-I architecture for multi-agent delegation scenarios.
+```
+
+# Execution Order Analysis for V3 and Phase 4 Plans
+
+## Critical Dependencies Found
+
+### 1. Scaffolder Refactor (V3) Must Be First
+
+The V3 Scaffolder Cleanup is foundational, creating the `MCPICloudflareServer` class and organizing all services into packages. This setup is crucial for:
+
+- Creating `packages/mcp-i-cloudflare/src/services/consent.service.ts`
+- Supporting Phase 4's modifications to the consent service
+- Ensuring Phase 4 changes are correctly placed
+
+### 2. Phase 4 Part A with Consent Implementation
+
+- V3's Consent Screen Implementation introduces the consent service.
+- Phase 4 Part A addresses critical bugs in delegation creation, particularly the missing `issuerDid`.
+- These tasks should be combined to prevent integration issues.
+
+### 3. Overlap in Identity Work
+
+- V3 Phase 1: "Identity & DID Management"
+- Phase 4: "User DID & Identity Linking"
+- Both phases cover similar work; Phase 4 details the implementation for V3 Phase 1.
+
+## Recommended Execution Order
+
+### Week 1: Foundation (Must be Sequential)
+
+1. **V3 Scaffolder Cleanup (2-3 days)** - **FIRST PRIORITY**
+   - Create `MCPICloudflareServer` class and organize services into packages.
+2. **V3 Consent + Phase 4 Part A (3-4 days) - COMBINED**
+   - Implement consent service with proper `issuerDid`.
+   - Introduce `getUserDidForSession` method from the start.
+
+### Week 2: Core Identity (Can Parallelize Some)
+
+**Parallel Track 1:**
+
+- **Phase 4 Parts B & C (3 days)**
+- Focus on OAuth integration and fix multi-tenant storage.
+
+**Parallel Track 2:**
+
+- **V3 Phase 2: Security Fixes (2-3 days)**
+- Work on `CryptoService` in core package independently.
+
+### Week 3: Integration & Enhancement
+
+3. **Phase 4 Part D & E (3 days)**
+   - Configure identity modes and ensure security and privacy enhancements.
+
+4. **V3 Phase 3: Integration & Storage (2-3 days)**
+   - Integrate with AgentShield and manage storage providers.
+
+5. **Phase 4 Part F (1 day - Optional)**
+   - Map MCP Client.
+
+## What Can Be Done in Parallel?
+
+**Highly Parallelizable:**
+
+- **V3 Security Fixes (CryptoService)** are independent.
+- Documentation updates and test writing can proceed at any time.
+
+**Somewhat Parallelizable (with coordination):**
+
+- Phase 4 Part B's OAuth Handler, once consent service is established.
+- Storage providers (V3 Phase 3) can be independent of identity work.
+- Phase 4 Part E's Privacy Service can be built standalone.
+
+**Must Be Sequential:**
+
+- **Scaffolder Refactor → Everything else**
+- **Consent Service creation → OAuth integration**
+- **User DID implementation → OAuth linking**
+
+## Unified Timeline
+
+```gantt
+title Implementation Timeline
+dateFormat  YYYY-MM-DD
+section Foundation
+Scaffolder Refactor          :crit, done, s1, 2024-11-09, 3d
+Consent + Fix Delegation     :crit, active, s2, after s1, 4d
+
+section Identity
+OAuth Integration            :b1, after s2, 2d
+Fix Storage Conflicts        :b2, after b1, 1d
+Security Fixes (Parallel)    :b3, after s2, 3d
+
+section Enhancement
+Identity Modes               :c1, after b2, 1d
+Privacy Controls             :c2, after c1, 2d
+Integration & Storage        :c3, after b3, 3d
+MCP Client Mapping           :c4, after c2, 1d
+```
+
+```markdown
+## Key Insight: Phase 4 IS Phase 1
+
+Phase 4 essentially represents the detailed implementation of V3's Phase 1 ("Identity & DID Management").
+
+- **V3 Phase 1 states:** "Identity & DID Management (2-3 days)"
+- **Phase 4 provides:** A 12-day detailed implementation
+
+## Recommendation
+
+1. Begin with the V3 Scaffolder Refactor as current proof submission work.
+2. Implement Consent with Phase 4 Part A fixes, ensuring code integrity.
+3. Skip V3 Phase 1; use Phase 4 for implementation.
+4. Parallelize security tasks during identity implementation.
+5. Complete integration work as scheduled.
+
+**Total timeline:** Approximately 3 weeks with opportunities for parallel work.
+```
+
+# Phase 4: User DID & Identity Linking Implementation Plan
+
+**Document Version:** 1.0
+**Created:** November 2024
+**Status:** Planning
+**Priority:** CRITICAL - Addresses fundamental identity architecture gaps
+
+## Executive Summary
+
+This document outlines the implementation plan for adding User DID persistence and OAuth identity linking to the MCP-I framework. The plan addresses critical issues identified during review including API schema mismatches, disconnected OAuth/consent flows, and missing User DID integration. Since we haven't launched yet, this plan assumes no existing users and implements the correct architecture from the start.
+
+## Critical Issues Identified During Review
+
+### 1. API Schema Mismatch (CRITICAL)
+
+- **Current State**: Consent service sends simplified request (agent_did, scopes, expires_in_days)
+- **Expected**: AgentShield API expects full DelegationRecord with issuerDid and subjectDid
+- **Impact**: Current implementation likely fails or creates invalid delegations
+- **Evidence**: `consent.service.ts:358-366` vs `schemas.ts:153-155`
+
+### 2. OAuth Identity Not Captured
+
+- **Current State**: Consent flow doesn't extract OAuth identity from approval requests
+- **Problem**: OAuth handler exists (`oauth-handler.ts`) but isn't integrated with consent flow
+- **Impact**: Can't link OAuth identity to User DIDs for persistence
+
+### 3. User DID Not Used as IssuerDid
+
+- **Current State**: UserDidManager generates DIDs but they're not passed to delegation creation
+- **Evidence**: TODO at `consent.service.ts:486-501` confirms this is known issue
+- **Impact**: All delegations missing proper issuerDid (User DID)
+
+### 4. MCP Client Info Not Available
+
+- **Current State**: Handshake schema doesn't include clientInfo.name
+- **Evidence**: `handshake.ts:7-12` only has optional agentDid
+- **Impact**: Can't map MCP clients to reputation DIDs as planned
+
+### 5. No Migration Strategy
+
+- **Problem**: Existing delegations use ephemeral DIDs that become invalid
+- **Impact**: Breaking change without backward compatibility
+
+### 6. Multi-Tenant Conflicts
+
+- **Current State**: Multiple users delegating to same agent overwrite each other
+- **Evidence**: Known issue documented at `consent.service.ts:486-506`
+
+## Revised Implementation Plan
+
+### Part A: Fix Core Delegation Flow (Priority 1 - 2 days)
+
+#### A.1: Update Delegation Creation to Include User DID
+
+**Location**: `packages/mcp-i-cloudflare/src/services/consent.service.ts`
+
+**Current Code** (lines 358-366):
+
+```typescript
+const delegationRequest = {
+  agent_did: request.agent_did,
+  scopes: request.scopes,
+  expires_in_days: expiresInDays,
+  ...(request.customFields && Object.keys(request.customFields).length > 0
+    ? { metadata: request.customFields }
+    : {}),
+};
+```
+
+**Updated Code**:
+
+```typescript
+// Extract or generate User DID
+const userDid = await this.getUserDidForSession(request.session_id);
+
+const delegationRequest = {
+  // Core delegation fields
+  issuer_did: userDid,           // NEW: User DID (who grants permission)
+  subject_did: request.agent_did, // RENAMED: Agent DID (who receives permission)
+  scopes: request.scopes,
+  expires_in_days: expiresInDays,
+
+  // Optional OAuth linking (for future persistence)
+  oauth_identity: request.oauth_identity ? {
+    provider: request.oauth_identity.provider,
+    subject: request.oauth_identity.subject,
+    email: request.oauth_identity.email
+  } : undefined
+
+  // Custom metadata
+  ...(request.customFields && Object.keys(request.customFields).length > 0
+    ? { metadata: request.customFields }
+    : {}),
+};
+```
+
+**Expected Outcome**:
+
+- Delegations include proper issuerDid (User DID)
+- OAuth identity captured for future linking
+- API properly structured from the start
+
+**Test Coverage**:
+
+```typescript
+describe("Delegation Creation", () => {
+  it("should include issuerDid when creating delegation", async () => {
+    const result = await consentService.createDelegation(request);
+    expect(result.delegation.issuerDid).toBeDefined();
+    expect(result.delegation.issuerDid).toMatch(/^did:key:z6Mk/);
+  });
+
+  it("should capture OAuth identity when provided", async () => {
+    const request = {
+      ...baseRequest,
+      oauth_identity: { provider: "google", subject: "123" },
+    };
+    const result = await consentService.createDelegation(request);
+    expect(result.delegation.oauth_identity).toBeDefined();
+  });
+});
+```
+
+#### A.2: Add getUserDidForSession Method
+
+**Location**: `packages/mcp-i-cloudflare/src/services/consent.service.ts`
+
+**New Method**:
+
+```typescript
+private async getUserDidForSession(sessionId: string): Promise<string> {
+  // Try to get existing User DID from session
+  const session = await this.sessionStorage.get(sessionId);
+  if (session?.userDid) {
+    return session.userDid;
+  }
+
+  // Generate new User DID using UserDidManager
+  const userDidManager = new UserDidManager({
+    crypto: this.cryptoProvider,
+    storage: this.userDidStorage // KV-based storage
+  });
+
+  const userDid = await userDidManager.getOrCreateUserDid(sessionId);
+
+  // Store in session for future use
+  await this.sessionStorage.set(sessionId, {
+    ...session,
+    userDid
+  });
+
+  return userDid;
+}
+```
+
+**Expected Outcome**:
+
+- Consistent User DID per session
+- Automatic generation if not exists
+- Session-scoped persistence
+
+**Test Coverage**:
+
+```typescript
+describe("getUserDidForSession", () => {
+  it("should return existing User DID from session", async () => {
+    const sessionId = "test-session";
+    const expectedDid = "did:key:z6MkExisting";
+    await sessionStorage.set(sessionId, { userDid: expectedDid });
+
+    const result = await consentService.getUserDidForSession(sessionId);
+    expect(result).toBe(expectedDid);
+  });
+
+  it("should generate new User DID if not in session", async () => {
+    const sessionId = "new-session";
+    const result = await consentService.getUserDidForSession(sessionId);
+    expect(result).toMatch(/^did:key:z6Mk/);
+  });
+});
+```
+
+### Part B: Integrate OAuth with Consent Flow (Priority 2 - 2 days)
+
+#### B.1: Update ConsentApprovalRequest Schema
+
+**Location**: `packages/contracts/src/consent/schemas.ts`
+
+**Add OAuth Identity Fields**:
+
+```typescript
+export const consentApprovalRequestSchema = z.object({
+  // Existing fields
+  agent_did: z.string(),
+  session_id: z.string(),
+  scopes: z.array(z.string()),
+  project_id: z.string(),
+
+  // NEW: OAuth identity fields
+  oauth_identity: z
+    .object({
+      provider: z.enum(["google", "github", "microsoft", "custom"]),
+      subject: z.string(), // OAuth user ID
+      email: z.string().email().optional(),
+      name: z.string().optional(),
+    })
+    .optional(),
+
+  // NEW: Persistent User DID
+  user_did: z.string().optional(),
+
+  // Existing optional fields
+  termsAccepted: z.boolean().optional(),
+  customFields: z.record(z.unknown()).optional(),
+});
+```
+
+**Expected Outcome**:
+
+- Consent approval can include OAuth identity
+- Clean API design from the start
+- Supports persistent User DIDs
+
+#### B.2: Extract OAuth Identity in Consent Page
+
+**Location**: `packages/mcp-i-cloudflare/src/services/consent-page-renderer.ts`
+
+**Update Consent Page JavaScript**:
+
+```javascript
+// In consent page template
+async function approveConsent() {
+  // Extract OAuth identity from session/cookie if available
+  const oauthIdentity = await getOAuthIdentityFromSession();
+
+  const approvalRequest = {
+    agent_did: '${config.agentDid}',
+    session_id: '${config.sessionId}',
+    scopes: ${JSON.stringify(config.scopes)},
+    project_id: '${config.projectId}',
+
+    // Include OAuth identity if available
+    ...(oauthIdentity && { oauth_identity: oauthIdentity }),
+
+    // Include User DID if already persistent
+    ...(window.userDid && { user_did: window.userDid }),
+
+    termsAccepted: document.getElementById('terms-checkbox')?.checked,
+  };
+
+  const response = await fetch('/consent/approve', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(approvalRequest)
+  });
+}
+```
+
+**Expected Outcome**:
+
+- OAuth identity passed to approval endpoint
+- User DID included when available
+- Progressive enhancement approach
+
+#### B.3: Connect OAuth Handler to User DID Creation
+
+**Location**: `packages/mcp-i-cloudflare/src/runtime/oauth-handler.ts`
+
+**Add Identity Linking**:
+
+```typescript
+export class OAuthHandler {
+  async handleCallback(request: Request): Promise<Response> {
+    // Existing OAuth token validation
+    const { provider, userInfo } = await this.validateOAuthCallback(request);
+
+    // NEW: Create or retrieve User DID for OAuth identity
+    const userDid = await this.linkOAuthToUserDid(provider, userInfo.sub);
+
+    // Store OAuth<->DID mapping
+    await this.identityStorage.set(
+      `oauth:${provider}:${userInfo.sub}`,
+      {
+        userDid,
+        email: userInfo.email,
+        name: userInfo.name,
+        linkedAt: new Date().toISOString(),
+        lastUsed: new Date().toISOString(),
+      },
+      { expirationTtl: 30 * 24 * 60 * 60 } // 30 days
+    );
+
+    // Set session cookie with User DID
+    return new Response(null, {
+      status: 302,
+      headers: {
+        Location: "/consent",
+        "Set-Cookie": `user_did=${userDid}; HttpOnly; Secure; SameSite=Strict`,
+      },
+    });
+  }
+
+  private async linkOAuthToUserDid(
+    provider: string,
+    subject: string
+  ): Promise<string> {
+    const linkKey = `oauth:${provider}:${subject}`;
+
+    // Check for existing link
+    const existing = await this.identityStorage.get(linkKey);
+    if (existing?.userDid) {
+      // Update last used timestamp
+      await this.identityStorage.set(linkKey, {
+        ...existing,
+        lastUsed: new Date().toISOString(),
+      });
+      return existing.userDid;
+    }
+
+    // Generate new persistent User DID
+    const userDidManager = new UserDidManager({
+      crypto: this.cryptoProvider,
+      storage: this.identityStorage,
+    });
+
+    const userDid = await userDidManager.generateUserDid();
+    return userDid;
+  }
+}
+```
+
+**Expected Outcome**:
+
+- OAuth identities automatically linked to User DIDs
+- Persistent mapping stored in KV
+- Same User DID returned for same OAuth identity
+
+**Test Coverage**:
+
+```typescript
+describe("OAuth to User DID Linking", () => {
+  it("should create new User DID for new OAuth identity", async () => {
+    const result = await oauthHandler.linkOAuthToUserDid("google", "user123");
+    expect(result).toMatch(/^did:key:z6Mk/);
+  });
+
+  it("should return existing User DID for known OAuth identity", async () => {
+    const firstDid = await oauthHandler.linkOAuthToUserDid("google", "user123");
+    const secondDid = await oauthHandler.linkOAuthToUserDid(
+      "google",
+      "user123"
+    );
+    expect(secondDid).toBe(firstDid);
+  });
+
+  it("should update lastUsed timestamp on retrieval", async () => {
+    await oauthHandler.linkOAuthToUserDid("google", "user123");
+    const link = await identityStorage.get("oauth:google:user123");
+    const firstTime = link.lastUsed;
+
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    await oauthHandler.linkOAuthToUserDid("google", "user123");
+    const updatedLink = await identityStorage.get("oauth:google:user123");
+    expect(updatedLink.lastUsed).not.toBe(firstTime);
+  });
+});
+```
+
+### Part C: Fix Multi-Tenant Storage Conflicts (Priority 3 - 1 day)
+
+#### C.1: Update Delegation Token Storage Keys
+
+**Location**: `packages/mcp-i-cloudflare/src/services/consent.service.ts`
+
+**Current Problem** (lines 486-501):
+
+- Tokens stored with agent-scoped keys only
+- Multiple users → same agent = overwrite
+
+**Fix Storage Keys**:
+
+```typescript
+private async storeDelegationToken(
+  token: string,
+  userDid: string,
+  agentDid: string,
+  sessionId: string
+): Promise<void> {
+  // Primary key: User + Agent (prevents conflicts)
+  const userAgentKey = `delegation:user:${userDid}:agent:${agentDid}`;
+  await this.delegationStorage.set(userAgentKey, token, {
+    expirationTtl: 24 * 60 * 60 // 24 hours
+  });
+
+  // Session key for fast lookup
+  const sessionKey = `delegation:session:${sessionId}`;
+  await this.delegationStorage.set(sessionKey, {
+    token,
+    userDid,
+    agentDid
+  }, {
+    expirationTtl: 60 * 60 // 1 hour
+  });
+}
+
+private async retrieveDelegationToken(
+  sessionId: string,
+  agentDid: string
+): Promise<string | null> {
+  // Try session key first (fastest)
+  const sessionData = await this.delegationStorage.get(`delegation:session:${sessionId}`);
+  if (sessionData?.token) {
+    return sessionData.token;
+  }
+
+  // Try user+agent key
+  const userDid = await this.getUserDidForSession(sessionId);
+  if (userDid) {
+    const token = await this.delegationStorage.get(`delegation:user:${userDid}:agent:${agentDid}`);
+    if (token) {
+      return token;
+    }
+  }
+
+  return null;
+}
+```
+
+**Expected Outcome**:
+
+- No more multi-tenant conflicts
+- Fast session-based lookup
+- Clean storage architecture
+
+**Test Coverage**:
+
+```typescript
+describe("Multi-tenant Delegation Storage", () => {
+  it("should store delegations per user+agent combination", async () => {
+    const user1Did = "did:key:z6MkUser1";
+    const user2Did = "did:key:z6MkUser2";
+    const agentDid = "did:key:z6MkAgent";
+
+    await consentService.storeDelegationToken(
+      "token1",
+      user1Did,
+      agentDid,
+      "session1"
+    );
+    await consentService.storeDelegationToken(
+      "token2",
+      user2Did,
+      agentDid,
+      "session2"
+    );
+
+    const token1 = await delegationStorage.get(
+      `delegation:user:${user1Did}:agent:${agentDid}`
+    );
+    const token2 = await delegationStorage.get(
+      `delegation:user:${user2Did}:agent:${agentDid}`
+    );
+
+    expect(token1).toBe("token1");
+    expect(token2).toBe("token2");
+  });
+});
+```
+
+### Part D: Identity Mode Configuration (Priority 4 - 1 day)
+
+#### D.1: Support Different Identity Modes
+
+**Location**: `packages/mcp-i-core/src/identity/user-did-manager.ts`
+
+**Add Configuration for Identity Modes**:
+
+```typescript
+export interface UserDidManagerConfig {
+  // Existing fields...
+
+  /**
+   * Identity mode
+   * - 'ephemeral': Generate new DID per session (for development/testing)
+   * - 'persistent': Link to OAuth, reuse across sessions (for production)
+   * - 'hybrid': Ephemeral by default, persistent after OAuth login (flexible)
+   */
+  mode: "ephemeral" | "persistent" | "hybrid";
+}
+
+export class UserDidManager {
+  async getOrCreateUserDid(
+    sessionId: string,
+    oauthIdentity?: OAuthIdentity
+  ): Promise<string> {
+    // Mode-based behavior
+    switch (this.config.mode) {
+      case "ephemeral":
+        // Testing mode - always generate new
+        return this.generateEphemeralDid(sessionId);
+
+      case "persistent":
+        // Production mode - require OAuth identity
+        if (!oauthIdentity) {
+          throw new Error("OAuth identity required in persistent mode");
+        }
+        return this.getOrCreatePersistentDid(oauthIdentity);
+
+      case "hybrid":
+        // Flexible mode - use OAuth if available
+        if (oauthIdentity) {
+          return this.getOrCreatePersistentDid(oauthIdentity);
+        } else {
+          return this.generateEphemeralDid(sessionId);
+        }
+    }
+  }
+}
+```
+
+**Expected Outcome**:
+
+- Support for different deployment scenarios
+- Clear separation between dev/test/production modes
+- Flexible configuration based on needs
+
+### Part E: Security & Privacy Enhancements (Priority 5 - 2 days)
+
+#### E.1: OAuth Account Verification
+
+**Location**: `packages/mcp-i-cloudflare/src/runtime/oauth-handler.ts`
+
+**Add Verification Step**:
+
+```typescript
+private async verifyOAuthAccountOwnership(
+  provider: string,
+  subject: string,
+  email?: string
+): Promise<boolean> {
+  // For account linking, require email verification
+  if (email && this.config.requireEmailVerification) {
+    const verificationToken = await this.generateVerificationToken();
+    await this.sendVerificationEmail(email, verificationToken);
+
+    // Store pending verification
+    await this.pendingVerifications.set(
+      `verify:${provider}:${subject}`,
+      { token: verificationToken, email },
+      { expirationTtl: 15 * 60 } // 15 minutes
+    );
+
+    return false; // Requires verification completion
+  }
+
+  // Check for suspicious patterns
+  const recentLinks = await this.getRecentLinks(subject);
+  if (recentLinks.length > this.config.maxLinksPerHour) {
+    console.warn('Suspicious linking activity detected:', subject);
+    return false;
+  }
+
+  return true;
+}
+```
+
+**Expected Outcome**:
+
+- Prevents unauthorized account linking
+- Email verification for sensitive operations
+- Rate limiting on identity linking
+
+#### E.2: Privacy Controls
+
+**Location**: `packages/mcp-i-cloudflare/src/services/privacy.service.ts`
+
+**New Privacy Service**:
+
+```typescript
+export class PrivacyService {
+  async handlePrivacyRequest(
+    request: PrivacyRequest
+  ): Promise<PrivacyResponse> {
+    switch (request.type) {
+      case "export":
+        // GDPR: Right to data portability
+        return this.exportUserData(request.userDid);
+
+      case "delete":
+        // GDPR: Right to be forgotten
+        return this.deleteUserData(request.userDid);
+
+      case "opt-out":
+        // Switch to ephemeral mode for user
+        return this.setUserMode(request.userDid, "ephemeral");
+
+      case "review":
+        // Show all linked identities and delegations
+        return this.getUserDataSummary(request.userDid);
+    }
+  }
+
+  private async deleteUserData(userDid: string): Promise<PrivacyResponse> {
+    // Delete OAuth links
+    const links = await this.identityStorage.list({ prefix: `oauth:*:*` });
+    for (const link of links) {
+      if (link.value.userDid === userDid) {
+        await this.identityStorage.delete(link.key);
+      }
+    }
+
+    // Delete delegations
+    await this.delegationStorage.delete(`delegation:user:${userDid}:*`);
+
+    // Delete User DID
+    await this.userDidStorage.delete(userDid);
+
+    return { success: true, message: "All user data deleted" };
+  }
+}
+```
+
+**Expected Outcome**:
+
+- GDPR compliance
+- User control over data
+- Privacy-first design
+
+**Test Coverage**:
+
+```typescript
+describe("Privacy Controls", () => {
+  it("should delete all user data on request", async () => {
+    const userDid = "did:key:z6MkUser";
+    await privacyService.deleteUserData(userDid);
+
+    const links = await identityStorage.list({ prefix: `oauth:` });
+    const userLinks = links.filter((l) => l.value.userDid === userDid);
+    expect(userLinks).toHaveLength(0);
+  });
+
+  it("should export user data in portable format", async () => {
+    const result = await privacyService.exportUserData(userDid);
+    expect(result.data).toHaveProperty("identities");
+    expect(result.data).toHaveProperty("delegations");
+    expect(result.format).toBe("json");
+  });
+});
+```
+
+### Part F: MCP Client Mapping (Optional - 1 day)
+
+Since MCP handshake doesn't include clientInfo.name, we'll make this optional:
+
+#### F.1: Extend Handshake Schema (If Possible)
+
+**Location**: `packages/contracts/src/handshake.ts`
+
+```typescript
+export const HandshakeRequestSchema = z.object({
+  agentDid: z.string().optional(),
+
+  // NEW: Optional client information
+  clientInfo: z
+    .object({
+      name: z.string(), // "Claude Desktop", "OpenAI GPT", etc.
+      version: z.string(), // "1.0.0"
+      platform: z.string(), // "desktop", "web", "mobile"
+    })
+    .optional(),
+});
+```
+
+#### F.2: Registry-Based Mapping
+
+**Location**: `packages/mcp-i-core/src/client/registry.ts`
+
+```typescript
+export const MCP_CLIENT_REGISTRY = {
+  // Well-known clients with reputation DIDs
+  "Claude Desktop": {
+    did: "did:web:knowthat.ai:clients:claude",
+    reputation: "verified",
+    firstSeen: "2024-01-01",
+  },
+  "OpenAI GPT": {
+    did: "did:web:knowthat.ai:clients:openai",
+    reputation: "verified",
+    firstSeen: "2024-01-01",
+  },
+  // Add more as they're discovered
+};
+
+export function getClientDid(clientName?: string): string | undefined {
+  if (!clientName) return undefined;
+  return MCP_CLIENT_REGISTRY[clientName]?.did;
+}
+```
+
+**Expected Outcome**:
+
+- Optional enhancement
+- Graceful degradation if not available
+- Foundation for future reputation system
+
+## Implementation Schedule
+
+### Week 1: Core Fixes
+
+- Day 1-2: Part A - Fix Core Delegation Flow
+  - [ ] Update delegation creation to include issuerDid
+  - [ ] Add getUserDidForSession method
+  - [ ] Write and run tests
+  - **Touchpoints**: update `packages/mcp-i-cloudflare/src/services/consent.service.ts`, centralize keys in `packages/mcp-i-cloudflare/src/constants/storage-keys.ts`, and expand `packages/contracts/src/consent/schemas.ts` validation for `oauth_identity` plus `user_did`.
+
+- Day 3-4: Part B - OAuth Integration (partial)
+  - [ ] Update schemas
+  - [ ] Extract OAuth identity in consent page
+  - [ ] Begin OAuth handler updates
+
+### Week 2: Integration & Migration
+
+- Day 5: Part B - Complete OAuth Integration
+  - [ ] Finish OAuth to User DID linking
+  - [ ] Test OAuth flow end-to-end
+
+- Day 6: Part C - Fix Storage Conflicts
+  - [ ] Update delegation storage keys
+  - [ ] Test multi-tenant scenarios
+
+- Day 7-8: Part D - Identity Mode Configuration
+  - [ ] Implement mode selection (ephemeral/persistent/hybrid)
+  - [ ] Add mode-specific logic
+  - [ ] Test different deployment scenarios
+
+### Week 3: Security & Polish
+
+- Day 9-10: Part E - Security & Privacy
+  - [ ] OAuth verification
+  - [ ] Privacy controls
+  - [ ] GDPR compliance testing
+
+- Day 11: Part F - Optional MCP Client Mapping
+  - [ ] Extend handshake if possible
+  - [ ] Set up client registry
+
+- Day 12: Integration Testing & Documentation
+  - [ ] Full end-to-end testing
+  - [ ] Update documentation
+  - [ ] Performance testing
+
+## Success Metrics
+
+### Functional Requirements
+
+- [ ] User DIDs persist across sessions when using OAuth
+- [ ] Delegations include correct issuerDid (User) and subjectDid (Agent)
+- [ ] OAuth identity correctly linked to User DIDs
+- [ ] Multi-tenant conflicts resolved
+- [ ] Clean architecture from the start
+
+### Non-Functional Requirements
+
+- [ ] <100ms overhead for DID operations
+- [ ] GDPR compliance for data operations
+- [ ] 95% test coverage for new code
+- [ ] Clear separation between dev/test/prod modes
+
+### Security Requirements
+
+- [ ] OAuth account verification prevents unauthorized linking
+- [ ] Rate limiting on identity operations
+- [ ] Audit trail for all identity changes
+- [ ] Secure token storage with encryption
+
+## Risk Mitigation
+
+### Risk 1: Performance Impact
+
+- **Mitigation**: Caching, async operations
+- **Monitoring**: Track DID operation latency
+
+### Risk 2: Privacy Concerns
+
+- **Mitigation**: Clear mode selection (ephemeral/persistent/hybrid), data deletion API
+- **Compliance**: GDPR audit before release
+
+### Risk 3: OAuth Provider Issues
+
+- **Mitigation**: Support multiple providers, graceful fallback to ephemeral
+- **Monitoring**: Track OAuth success rates
+
+## Testing Strategy
+
+### Unit Tests
+
+- UserDidManager with all three modes
+- OAuth to DID linking logic
+- Multi-tenant storage operations
+- Privacy service operations
+
+### Integration Tests
+
+- Full OAuth login → consent → delegation flow
+- Session continuity across multiple requests
+- Mode switching (ephemeral → persistent → hybrid)
+- Multi-user, multi-agent scenarios
+
+### E2E Tests
+
+- User logs in with Google → approves delegation → uses tool
+- User returns next day → same DID → previous delegations work
+- User deletes account → all data removed
+
+### Performance Tests
+
+- 1000 concurrent DID operations
+- OAuth linking under load
+- Storage operations with 10k+ entries
+
+## Documentation Updates
+
+### API Documentation
+
+- New fields in ConsentApprovalRequest
+- OAuth identity linking endpoints
+- Privacy control endpoints
+
+### Configuration Guide
+
+- How to choose between identity modes
+- Setting up OAuth providers
+- Configuring for different environments
+
+### User Guide
+
+- Benefits of persistent identity
+- Privacy controls and data deletion
+- OAuth account linking process
+
+## Conclusion
+
+This plan addresses all critical issues identified in the review and implements the correct architecture from the start. The implementation is broken into manageable phases with clear dependencies and success metrics.
+
+The key improvements include:
+
+1. Proper User DID integration as issuerDid
+2. OAuth identity linking for persistence
+3. Multi-tenant conflict resolution
+4. Comprehensive security and privacy controls
+5. Clear mode selection for different deployment scenarios
+
+By following this plan, we'll establish a robust identity foundation that enables true user persistence while maintaining the flexibility to support both ephemeral and persistent modes based on use case requirements.
+
+## Comparison to Initial Analysis
+
+### What Changed from Original Plan
+
+The initial analysis suggested a simpler OAuth bridging approach. After review feedback, the plan now addresses:
+
+1. **API Schema Alignment**: Fixed to send full DelegationRecord with issuerDid and subjectDid
+2. **OAuth Integration**: Properly integrated with consent flow (not separate)
+3. **User DID Usage**: Actually used as issuerDid (was missing before)
+4. **No Legacy Support**: Since we haven't launched, no need for backward compatibility
+
+### What Remains from Original Plan
+
+1. **Core Concept**: OAuth identity → User DID linking for persistence
+2. **Three-Layer DIDs**: Server/Bouncer, Agent, and User DIDs
+3. **MCP Client Mapping**: Optional enhancement for reputation tracking
+4. **Session Continuity**: Tracking users across chat sessions
+
+## MCP-I Specification Alignment
+
+### Full Compliance with MCP-I Spec
+
+This implementation aligns with the [MCP-I specification](https://modelcontextprotocol-identity.io) and [schemas](https://schema.modelcontextprotocol-identity.io/):
+
+1. **DID Architecture** ✅
+   - Server DID: `did:web:` or `did:key:` format per spec
+   - Agent DID: Properly used as subjectDid in delegations
+   - User DID: Properly used as issuerDid in delegations
+
+2. **Delegation Model** ✅
+   - Format: User (issuerDid) → Agent (subjectDid)
+   - Includes scopes, constraints, and expiration
+   - Follows W3C Verifiable Credential wrapper format
+
+3. **Proof Format** ✅
+   - JWS compact format (header.payload.signature)
+   - All required meta fields present
+   - SHA-256 hashing with proper prefixes
+
+4. **Consent Flow** ✅
+   - Required parameters: tool, scopes, agent_did, session_id, project_id
+   - Proper approval handling
+   - Delegation creation upon approval
+
+5. **Security Requirements** ✅
+   - Ed25519 signatures
+   - Proper nonce handling
+   - Session-based security
+
+### Key Alignment Points
+
+- **issuerDid**: Always the User DID (who grants permission)
+- **subjectDid**: Always the Agent DID (who receives permission)
+- **Delegation Storage**: Properly scoped to prevent multi-tenant conflicts
+- **OAuth Integration**: Enhances but doesn't replace DID-based identity
+
+### Level 3 Enterprise Features
+
+While this plan doesn't implement full Level 3 compliance (OAuth 2.1 bridging, anomaly detection), it provides:
+
+- Foundation for OAuth identity management
+- Clear path to Level 3 if needed
+- Level 1-2 compliance out of the box
+
+The implementation maintains full spec compliance while addressing real-world needs for persistent user identity across sessions.