[P3] Implement Guardian Social Recovery methods (9 endpoints)

[umwelt]

Overview

Implement complete guardian social recovery API methods to match the ZHTP node's fully implemented guardian system.

Parent Issue

Part of #17 - Priority 3 tasks

Node Status

✅ All 9 guardian recovery endpoints implemented on node (Issue #116 - CLOSED)

Current Status in Client

Some methods exist but need verification and completion.

Missing/Incomplete Methods

Guardian Management (9 endpoints)

1. ✅ addGuardian() - Implemented, needs verification

   • POST /api/v1/identity/guardians/add

2. ❌ removeGuardian() - Exists but verify DELETE method

   • DELETE /api/v1/identity/guardians/{guardian_id}

3. ✅ listGuardians() - Implemented, needs verification

   • GET /api/v1/identity/guardians

4. ✅ initiateRecovery() - Implemented, needs verification

   • POST /api/v1/identity/recovery/initiate

5. ✅ approveRecovery() - Implemented, needs verification

   • POST /api/v1/identity/recovery/{recovery_id}/approve

6. ❌ completeRecovery() - MISSING

   • POST /api/v1/identity/recovery/{recovery_id}/complete

7. ❌ rejectRecovery() - MISSING

   • POST /api/v1/identity/recovery/{recovery_id}/reject

8. ✅ getRecoveryStatus() - Implemented, needs verification

   • GET /api/v1/identity/recovery/{recovery_id}/status

9. ❌ getPendingRecoveries() - MISSING

   • GET /api/v1/identity/recovery/pending

TypeScript Types Needed

interface AddGuardianRequest {
  identity_id: string;
  guardian_did: string;
  guardian_name: string;
}

interface Guardian {
  guardian_id: string;
  guardian_did: string;
  name: string;
  added_at: number;
}

interface GuardianListResponse {
  guardians: Guardian[];
  threshold: number; // M-of-N threshold
}

interface InitiateRecoveryRequest {
  identity_did: string;
  requester_device: string;
}

interface RecoverySession {
  recovery_id: string;
  status: 'initiated' | 'pending' | 'approved' | 'rejected' | 'completed' | 'expired';
  approvals: number;
  required: number;
  expires_at: number;
}

interface ApproveRecoveryRequest {
  guardian_did: string;
  signature: string;
}

interface CompleteRecoveryResponse {
  status: string;
  identity: {
    identity_id: string;
    did: string;
  };
  session_token: string;
}

interface PendingRecovery {
  recovery_id: string;
  identity_did: string;
  identity_name: string;
  initiated_at: number;
}

Implementation Tasks

1. Add Missing Methods

• completeRecovery(recovery_id: string): Promise<CompleteRecoveryResponse>
• rejectRecovery(recovery_id: string, guardian_did: string): Promise<void>
• getPendingRecoveries(): Promise<PendingRecovery[]>

2. Verify Existing Methods

• Verify addGuardian() matches node spec
• Verify removeGuardian() uses DELETE method
• Verify listGuardians() returns threshold
• Verify initiateRecovery() request format
• Verify approveRecovery() signature handling
• Verify getRecoveryStatus() response format

3. Update Type Definitions

• Add/update types in src/core/types.ts
• Add recovery status enum
• Add threshold configuration types
• Add signature types

4. Security Considerations

• Guardian signature verification
• Session authentication for guardian actions
• Rate limiting awareness (3 recovery/hour)
• Recovery expiration handling (24-48 hours)

5. Testing

• Unit tests for all guardian methods
• Integration tests for full recovery flow
• Test M-of-N threshold logic
• Test expiration handling
• Test duplicate approval prevention

Guardian Recovery Flow

// 1. User adds guardians
await client.addGuardian(identity_id, guardian_did_1, "Alice");
await client.addGuardian(identity_id, guardian_did_2, "Bob");
await client.addGuardian(identity_id, guardian_did_3, "Charlie");

// 2. User loses access, initiates recovery
const recovery = await client.initiateRecovery(identity_did, "new-phone");

// 3. Guardians approve (need M-of-N, e.g., 2 of 3)
await client.approveRecovery(recovery.recovery_id, guardian_did_1, signature_1);
await client.approveRecovery(recovery.recovery_id, guardian_did_2, signature_2);

// 4. Complete recovery after threshold met
const result = await client.completeRecovery(recovery.recovery_id);
// Returns new session token for recovered identity

Security Notes from Node

Rate Limits:

• Recovery initiation: 3 requests/hour per IP

Expiration:

• Recovery requests expire after 24-48 hours (configurable)

Threshold:

• M-of-N guardians must approve
• Configurable per identity (default 2 of 3)

Signatures:

• Guardian approvals require valid signatures
• Prevents unauthorized recovery attempts

Acceptance Criteria

• All 9 endpoints have corresponding methods
• Type definitions complete and accurate
• JSDoc documentation for all methods
• Full recovery flow works end-to-end
• Unit tests pass
• Integration tests pass
• README updated with guardian recovery examples

Related Issues

• Parent: [IMPLEMENTATION GUIDE] Complete ZHTP Node API Endpoint Reference #17
• Node: [API] Guardian social recovery system (9 endpoints) The-Sovereign-Network#116 (closed)
• API Client: [FRONTEND]: Guardian recovery system missing in ZHTP node #5

Estimated Effort

Medium-Large - 6-8 hours