@kya-os/mcp-i-core 1.2.3-canary.7 → 1.3.1

package/GPT-5.md

@@ -0,0 +1,1169 @@
+## Phase 4 — User DID & Identity Linking (Polished Plan, MCP‑I §3.1 Compliant)
+
+Status: Ready for implementation
+Scope: MCP‑I Identity, Consent, Delegation, OAuth Linking, Cross‑Agent Validation
+Primary repos: `xmcp-i` (this), AgentShield/bouncer dashboard (API), Know‑That‑AI (reputation – advisory)
+
+### Executive Summary
+Phase 4 delivers persistent User identity by linking OAuth identities to User DIDs and using the User DID as `issuerDid` for delegations. It fixes consent→delegation gaps, resolves multi‑tenant conflicts, and aligns on strict API contracts and error formats. The outcome is spec‑compliant delegation across sessions and agents, with robust observability and privacy controls.
+
+— Core moves
+- Use OAuth identity → User DID linking for persistence.
+- Delegation issuance: `issuerDid` = User DID, `subjectDid` = Agent DID.
+- Store delegation tokens per user+agent; session cache is a fast path.
+- Validate with decentralized VCs first; fall back to OAuth verification if needed.
+- Strict API parity with AgentShield wrapper `{ success, data, metadata }` and error `{ code, message, details }`.
+
+— Why this is game‑changing
+- True cross‑agent portability via DID/VCs, not just OAuth sessions.
+- Seamless UX: first consent creates delegation; later sessions just work.
+- Enterprise‑ready controls: audit, privacy APIs, and chain validation.
+
+
+### Architecture Overview
+
+1) Identity model (three DIDs)
+- Server DID: Receiver of MCP calls (bouncer or app server)
+- Agent DID: Requesting software (Claude Desktop, SaaS agents, other MCP servers)
+- User DID: Human user granting permission; becomes `issuerDid` in delegations
+
+2) Persistence & linking
+- OAuth callback links `oauth:{provider}:{subject}` → `userDid` (KV)
+- `UserDidManager` retrieves/creates User DID based on session or OAuth identity
+
+3) Delegation issuance (Consent → AgentShield)
+- Consent approval constructs a spec‑aligned request embedding `issuerDid` and `subjectDid`
+- Transitional compatibility: if AgentShield endpoint hasn’t adopted `issuer_did`/`subject_did`, include `issuerDid` in `metadata` and continue using `agent_did` until API parity lands; add deprecation header to surface the gap
+
+4) Token storage (multi‑tenant safe)
+- Primary key: `delegation:user:{userDid}:agent:{agentDid}` (KV)
+- Session key: `delegation:session:{sessionId}` (short TTL for speed)
+
+5) Verification order (Edge verification policy)
+- First try decentralized VC verification (DID + VC chain, CRISP constraints, revocation)
+- If absent or invalid, fall back to AgentShield OAuth verification
+- Always produce audit logs and parity‑safe error wrappers
+
+
+### End‑to‑End Flows
+
+1) First‑time consent
+2. Handshake initializes session; `agentDid` captured; ephemeral `userDid` is generated
+3. Tool call requires scopes → raise `DelegationRequiredError` with consent URL
+4. User approves on consent page; page posts approval to `/consent/approve`
+5. Service constructs delegation creation payload with `issuerDid` and `subjectDid`
+6. AgentShield returns a delegation token (and/or VC); store per user+agent and session
+7. Success page auto‑closes and returns control to client
+
+8) Return session
+9. Handshake finds OAuth cookie or identity → retrieve `userDid` via link
+10. Tool call: delegation token found via session key or user+agent cache
+11. No consent required; call proceeds
+
+12) Cross‑agent validation
+13. External agent calls bouncer; provides agent DID
+14. Verify VC chain; if unavailable, call AgentShield `delegations/verify` for that `agent_did` + scopes
+15. Decision response uses standard success/error wrapper
+
+
+### API Contracts and Parity
+
+All endpoints must follow the wrapper:
+```json
+{ "success": true, "data": { ... }, "metadata": { ... } }
+```
+Errors:
+```json
+{ "code": "string", "message": "string", "details": { ... } }
+```
+
+AgentShield endpoints (must remain parity‑consistent)
+- POST `/api/v1/bouncer/delegations/verify`
+  - Request: `{ agent_did: string, scopes: string[], credential_jwt?: string, timestamp?: number, client_info?: any }`
+  - Response: `{ success, data: { valid: boolean, reason?: string, expiresAt?: number } }`
+- GET `/api/v1/bouncer/config/{projectId}`
+  - Response: `{ success, data: { tools: Record<string, { scopes: string[], requiresDelegation: boolean }> } }`
+- POST `/api/v1/bouncer/proofs`
+  - Request: `{ proof: string, session: { id: string, audience: string, agentDid: string } }`
+  - Response: `{ success, data: { verified: boolean, ... } }`
+
+Delegation creation (transitional until AgentShield upgrades)
+- If AgentShield supports spec names now:
+  - Request: `{ issuer_did: string, subject_did: string, scopes: string[], expires_in_days?: number, constraints?: {...}, metadata?: {...} }`
+- If not yet:
+  - Request: `{ agent_did: string, scopes: string[], expires_in_days?: number, metadata?: { issuer_did: string, subject_did: string, ... } }`
+  - Include a `Deprecation: use-issuer_did/subject_did` header where possible
+
+
+### Contracts and Validation (in `@kya-os/contracts`)
+
+Consent Approval (back‑compat + new fields optional)
+```ts
+export const consentApprovalRequestSchema = z.object({
+  tool: z.string().min(1),
+  scopes: z.array(z.string()),
+  agent_did: z.string(),
+  session_id: z.string(),
+  project_id: z.string(),
+  termsAccepted: z.boolean(),
+  termsVersion: z.string().max(50).optional(),
+  customFields: z.record(z.union([z.string(), z.boolean()])).optional(),
+
+  // NEW (optional; back‑compatible)
+  oauth_identity: z.object({
+    provider: z.enum(['google','github','microsoft','custom']),
+    subject: z.string(),
+    email: z.string().email().optional(),
+    name: z.string().optional(),
+  }).optional(),
+  user_did: z.string().optional(),
+});
+```
+
+Handshake (optional client info)
+```ts
+export const HandshakeRequestSchema = z.object({
+  nonce: z.string().min(1),
+  audience: z.string().min(1),
+  timestamp: z.number().int().positive(),
+  agentDid: z.string().startsWith('did:').optional(),
+  clientInfo: z.object({
+    name: z.string(),
+    version: z.string(),
+    platform: z.string(),
+  }).optional(),
+});
+```
+
+Error Types (shared)
+```ts
+export const AgentErrorSchema = z.object({
+  code: z.string(),
+  message: z.string(),
+  details: z.unknown().optional(),
+});
+```
+
+
+### Implementation Changes (xmcp‑i)
+
+1) Consent → Delegation creation (fix critical gap)
+- File: `packages/mcp-i-cloudflare/src/services/consent.service.ts`
+- Build delegation request with `issuerDid` and `subjectDid`:
+```ts
+const userDid = await this.getUserDidForSession(request.session_id);
+const delegationRequest = {
+  issuer_did: userDid,
+  subject_did: request.agent_did,
+  scopes: request.scopes,
+  expires_in_days: expiresInDays,
+  ...(request.customFields && Object.keys(request.customFields).length > 0
+    ? { metadata: request.customFields }
+    : {}),
+};
+```
+
+2) User DID retrieval
+- Add private method in `ConsentService`:
+```ts
+private async getUserDidForSession(sessionId: string): Promise<string> {
+  const session = await this.sessionStorage.get(sessionId);
+  if (session?.userDid) return session.userDid;
+  const userDidManager = new UserDidManager({ crypto: this.cryptoProvider, storage: this.userDidStorage });
+  const userDid = await userDidManager.getOrCreateUserDid(sessionId);
+  await this.sessionStorage.set(sessionId, { ...session, userDid });
+  return userDid;
+}
+```
+
+3) OAuth callback → link identity to DID
+- File: `packages/mcp-i-cloudflare/src/runtime/oauth-handler.ts`
+- Link key: `oauth:{provider}:{subject}` → `{ userDid, email?, name?, linkedAt, lastUsed }`
+- Set `user_did` cookie post‑callback
+
+4) Multi‑tenant storage keys
+- File: `packages/mcp-i-cloudflare/src/services/consent.service.ts`
+```ts
+const userAgentKey = `delegation:user:${userDid}:agent:${agentDid}`;
+await this.delegationStorage.set(userAgentKey, token, { expirationTtl: 24 * 60 * 60 });
+await this.delegationStorage.set(`delegation:session:${sessionId}`, { token, userDid, agentDid }, { expirationTtl: 60 * 60 });
+```
+
+5) Identity modes (optional, clear behavior)
+- File: `packages/mcp-i-core/src/identity/user-did-manager.ts`
+- Add `mode: 'ephemeral' | 'persistent' | 'hybrid'` and gate behavior accordingly.
+
+6) Consent page: include `oauth_identity` / `user_did` when available
+- File: `packages/mcp-i-cloudflare/src/services/consent-page-renderer.ts`
+- In the submission JS, conditionally attach both fields if present in session.
+
+7) Audit logs
+- Log: consent shown, approval submitted, delegation created, verification success/failure, OAuth link events.
+
+
+### Verification and Chains
+
+— Requirements
+- Validate VC structure against MCP‑I §3.1 VC shape; verify signatures and trust roots.
+- Verify delegation chains with parent VCs recursively; detect cycles; respect revocation.
+- Use `resolve_delegation_chain(...)` first; only fallback to OAuth‑based verification if no valid VC chain exists.
+
+— Behavior
+- On any failure, return `{ code, message, details }` with appropriate HTTP code and parity wrapper.
+
+
+### Privacy & Security
+
+— Privacy service (optional but recommended)
+- Handlers: export, delete (forget), opt‑out (switch user to ephemeral), review (list identities+delegations).
+
+— Security hardening
+- Rate limit identity linking and delegation issuance per subject and per session.
+- Require email verification toggle for risky link operations.
+- CSP, XSS hardening (already present in consent renderer), secure cookies, SameSite=strict.
+
+
+### Migration & Compatibility
+
+— Transitional plan for AgentShield parity
+- Phase 4 immediately adds `issuerDid` into `metadata` when `issuer_did`/`subject_did` are not accepted yet.
+- Coordinate dashboard/API update to accept spec names; once deployed, switch client to send first‑class fields and stop duplicating in `metadata`.
+- Add `@validate-api-parity` to CI for any API file changes and ensure contracts in `@kya-os/contracts` are the single source of truth.
+
+— Back‑compat
+- New consent fields `oauth_identity`, `user_did` are optional.
+- Handshake `clientInfo` optional.
+
+
+### Observability & Tests
+
+— Unit
+- `UserDidManager` (all modes), OAuth→DID linking, storage keys, consent validation
+
+— Integration
+- OAuth login → consent → delegation; session continuity; multi‑tenant issuance
+
+— E2E
+- First‑time consent + later reuse; data deletion; chain validation happy/negative paths
+
+— Metrics & logs
+- Latency of DID ops (<100ms p95), issuance/verification rate, error codes distribution
+
+
+### Implementation Checklist
+
+Week 1
+- Fix delegation creation with `issuerDid` + `subjectDid`
+- Add `getUserDidForSession` and tests
+- Extend consent schema with optional `oauth_identity`/`user_did`
+
+Week 2
+- OAuth callback linking to DID + tests
+- Multi‑tenant storage keys + tests
+- Optional: identity modes in `UserDidManager`
+
+Week 3
+- Privacy endpoints (export/delete/opt‑out/review) and tests
+- Optional: handshake `clientInfo` + registry
+- Parity validation command passes; docs updated
+
+Success criteria
+- User DID persists across sessions via OAuth
+- Delegations include correct `issuerDid` (User) and `subjectDid` (Agent)
+- No storage collisions across users for the same agent
+- VC chain validated when present; OAuth fallback otherwise
+- API parity checks clean; error formats consistent
+
+
+### Risks & Mitigations
+
+— Performance: cache user DID and session delegations; async persistence
+— Parity drift: block merges on `@validate-api-parity`; contracts as single source of truth
+— Security: link throttling, optional email verification, strict audit logs
+— Privacy: delete/export/opt‑out endpoints; secure storage scopes
+
+
+### Notes on Current Code Reality (validated)
+- `consent.service.ts` currently posts `{ agent_did, scopes, expires_in_days }` and lacks `issuerDid` → must be fixed (Priority 1).
+- `oauth-handler.ts` performs token exchange but does not yet link to User DID → add linking.
+- `user-did-manager.ts` supports ephemeral DIDs; extend with modes if needed.
+- `consentApprovalRequestSchema` lacks `oauth_identity`/`user_did` → add optional fields to support persistence (back‑compatible).
+- `HandshakeRequestSchema` does not include `clientInfo` → optional addition for future reputation mapping.
+
+
+### Deliverables
+- Updated contracts: consent schema (optional fields), optional handshake `clientInfo`
+- Updated services: consent service, OAuth handler, consent renderer JS
+- Updated storage keys: user+agent, session fast path
+- Optional identity modes + privacy service
+- Docs and parity validation green
+
+# Phase 4: User DID & Identity Linking Implementation Plan
+
+**Document Version:** 1.1
+**Created:** November 2024
+**Updated:** January 2025
+**Status:** Ready for Implementation
+**Priority:** CRITICAL - Addresses fundamental identity architecture gaps
+**Branch:** feat/delegation-handling
+
+## 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.
+
+## Prerequisites Complete ✅
+
+The following foundational work has been completed in the current branch (feat/delegation-handling):
+
+### 1. Scaffolder Refactor (V3 Architecture) - COMPLETE
+- **MCPICloudflareServer class created**: All services now hidden in the package
+- **Clean scaffolded output**: Users only see ~100 lines of configuration
+- **Services moved to package**: DelegationService, ProofService, AdminService, ConsentService
+- **Constants extracted**: No more hardcoded URLs in templates
+
+### 2. Consent Service Implementation - COMPLETE
+- **ConsentService class created**: Full consent flow implementation
+- **Transport detection**: Automatic HTTP/SSE/STDIO detection
+- **Consent rendering**: Complete with XSS protection
+- **Integration ready**: Hooks in place for OAuth and User DID
+
+### 3. Proof Submission Fix - COMPLETE
+- **Automatic submission**: Proofs now submitted after tool execution
+- **ProofService integrated**: Proper initialization in runtime
+- **AgentShield integration**: Proofs visible in dashboard
+
+### What This Means for Phase 4
+With the scaffolder refactor and consent service complete, we have:
+- ✅ Clean architecture to build upon
+- ✅ ConsentService ready for OAuth integration (Part B)
+- ✅ MCPICloudflareServer ready for User DID fixes (Part A)
+- ✅ Infrastructure in place for storage improvements (Part C)
+
+**Time Saved:** ~5 days of implementation already complete
+**Adjusted Timeline:** 3-4 days remaining for Phase 4 implementation
+
+## 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
+
+- 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.