[P2] Implement Backup & Recovery API methods (7 endpoints)

[umwelt]

Overview

Implement complete backup and recovery API methods to match the ZHTP node's fully implemented backup/recovery system.

Parent Issue

Part of #17 - Priority 2 tasks

Node Status

✅ All 7 backup/recovery endpoints implemented on node (Issue #115 - CLOSED)

Missing/Incomplete Methods

Backup & Recovery (7 endpoints)

1. ✅ generateRecoveryPhrase() - May need verification

   • POST /api/v1/identity/backup/generate

2. ✅ verifyRecoveryPhrase() - May need verification

   • POST /api/v1/identity/backup/verify

3. ✅ recoverIdentity() - May need verification

   • POST /api/v1/identity/recover

4. ❌ getBackupStatus() - MISSING

   • GET /api/v1/identity/backup/status

5. ✅ exportBackup() - Implemented, verify alignment

   • POST /api/v1/identity/backup/export

6. ✅ importBackup() - Implemented, verify alignment

   • POST /api/v1/identity/backup/import

7. ✅ verifySeedPhrase() - Implemented, verify alignment

   • POST /api/v1/identity/seed/verify

TypeScript Types Needed

interface GenerateRecoveryPhraseRequest {
  identity_id: string;
  session_token: string;
}

interface GenerateRecoveryPhraseResponse {
  status: string;
  phrase_hash: string;
  recovery_phrase?: string; // Returned ONCE only
  instructions: string;
}

interface VerifyRecoveryPhraseRequest {
  identity_id: string;
  recovery_phrase: string; // 20 words
}

interface RecoverIdentityRequest {
  recovery_phrase: string; // 20 words
}

interface BackupStatusResponse {
  has_recovery_phrase: boolean;
  backup_date?: number;
  verified: boolean;
}

interface ExportBackupRequest {
  identity_id: string;
  passphrase: string; // Min 12 characters
}

interface ExportBackupResponse {
  backup_data: string; // Base64 encoded
  created_at: number;
}

interface ImportBackupRequest {
  backup_data: string; // Base64
  passphrase: string;
}

interface VerifySeedPhraseRequest {
  identity_id: string;
  seed_phrase: string; // 12 words BIP39
}

Implementation Tasks

1. Add Missing Method

• Implement getBackupStatus(identity_id: string): Promise<BackupStatusResponse>

2. Verify Existing Methods

• Verify exportBackup() request/response matches node
• Verify importBackup() request/response matches node
• Verify verifySeedPhrase() for 12-word BIP39 support
• Verify recoverIdentity() uses 20-word phrases

3. Update Type Definitions

• Add/update types in src/core/types.ts
• Ensure 20-word recovery phrase support
• Ensure 12-word seed phrase support
• Add backup status types

4. Security Considerations

• Implement zeroization for passphrases (if applicable in TS)
• Add warnings about recovery phrase security
• Document passphrase minimum length (12 chars)
• Note rate limits in JSDoc comments

5. Testing

• Unit tests for all backup/recovery methods
• Integration tests with node
• Test error handling
• Test passphrase validation

Security Notes from Node

Rate Limits:

• Export: 5 requests/hour per IP
• Import: 3 requests/hour per IP
• Recovery: 3 requests/hour per IP

Passphrase Requirements:

• Minimum 12 characters
• Maximum 128 characters
• Zeroized after use on node side

Recovery Phrases:

• 20 words (not BIP39, custom system)
• Returned ONCE on generation
• Never logged or cached

Seed Phrases:

• 12 words (BIP39 compatible)
• For wallet recovery

Acceptance Criteria

• All 7 endpoints have corresponding methods
• Type definitions complete and accurate
• JSDoc documentation for all methods
• Security warnings documented
• Unit tests pass
• Integration tests pass
• README updated with backup/recovery examples

Related Issues

• Parent: [IMPLEMENTATION GUIDE] Complete ZHTP Node API Endpoint Reference #17
• Node: [API] Identity backup and recovery endpoints (7 endpoints) The-Sovereign-Network#115 (closed)
• API Client: [FRONTEND]: Backup and recovery system missing in ZHTP node #4

Estimated Effort

Medium - 4-6 hours

[umwelt]

✅ Implementation Complete

All backup & recovery methods have been implemented and tested:

Implemented:

• ✅ getBackupStatus() - GET /api/v1/identity/backup/status
• ✅ exportBackup() - Fixed parameter name (password → passphrase)
• ✅ importBackup() - Fixed parameter name and return type
• ✅ verifySeedPhrase() - Verified implementation
• ✅ exportSeedPhrases() - Verified implementation

Type Updates:

• ✅ BackupData - Updated to match node response
• ✅ SeedVerification - Updated to match node response
• ✅ ImportBackupResponse - New type added

Tests:

• ✅ 5 new comprehensive tests added
• ✅ 2 existing tests fixed
• ✅ All tests passing (81/81)

Pull Request: #27
Ready for review and merge.