[API] Identity backup and recovery endpoints (7 endpoints)

[umwelt]

Overview

The API client expects 7 backup/recovery endpoints that don't exist on the ZHTP node, preventing users from backing up and recovering their identities.

Problem

API Client Expects (from Issue #4):

• Backup phrase generation endpoints
• Recovery phrase validation endpoints
• Identity recovery from phrase endpoints
• Backup status/verification endpoints

ZHTP Node Has:

• NO backup or recovery HTTP API endpoints ❌
• RecoveryPhraseManager exists in lib-identity but not exposed via API

Impact: Users cannot back up their identities or recover lost accounts. Critical security feature missing.

Required Endpoints

1. POST /api/v1/identity/backup/generate

Purpose: Generate recovery phrase for existing identity

Request:

{
  "identity_id": "...",
  "session_token": "..."
}

Response:

{
  "status": "success",
  "recovery_phrase": "word1 word2 word3 ... word20",
  "phrase_hash": "..."
}

2. POST /api/v1/identity/backup/verify

Purpose: Verify user wrote down recovery phrase correctly

Request:

{
  "identity_id": "...",
  "recovery_phrase": "word1 word2 ... word20"
}

Response:

{
  "status": "success",
  "verified": true
}

3. POST /api/v1/identity/recover

Purpose: Recover identity from recovery phrase

Request:

{
  "recovery_phrase": "word1 word2 ... word20"
}

Response:

{
  "status": "success",
  "identity": { ... },
  "session_token": "..."
}

4. GET /api/v1/identity/backup/status

Purpose: Check if identity has backup configured

Response:

{
  "has_recovery_phrase": true,
  "backup_date": 1234567890,
  "verified": true
}

5. POST /api/v1/identity/backup/export

Purpose: Export encrypted identity backup

Request:

{
  "identity_id": "...",
  "passphrase": "..."
}

Response:

{
  "backup_data": "encrypted_backup_blob",
  "created_at": 1234567890
}

6. POST /api/v1/identity/backup/import

Purpose: Restore identity from encrypted backup

Request:

{
  "backup_data": "encrypted_backup_blob",
  "passphrase": "..."
}

Response:

{
  "status": "success",
  "identity": { ... },
  "session_token": "..."
}

7. POST /api/v1/identity/seed/verify

Purpose: Verify seed phrase is correct

Request:

{
  "identity_id": "...",
  "seed_phrase": "word1 word2 ... word12"
}

Response:

{
  "verified": true
}

Implementation Requirements

1. Use Existing RecoveryPhraseManager

   • lib-identity already has RecoveryPhraseManager
   • Expose it via HTTP API in IdentityHandler

2. Secure Phrase Storage

   • Store phrase hash, not plain phrase
   • Encrypt recovery data at rest

3. Recovery Flow

   • Validate recovery phrase
   • Retrieve identity from storage
   • Create new session
   • Return identity + session token

4. Security Considerations

   • Rate limit recovery attempts
   • Log recovery attempts for security audit
   • Require additional verification for high-value accounts (optional for alpha)

Files to Modify

• zhtp/src/api/handlers/identity/mod.rs - Add backup/recovery handlers
• lib-identity/src/recovery/mod.rs - May need additional methods

Acceptance Criteria

• Recovery phrase generation endpoint implemented
• Recovery phrase verification endpoint implemented
• Identity recovery from phrase endpoint implemented
• Backup status endpoint implemented
• Backup export/import endpoints implemented
• Seed phrase verification endpoint implemented
• RecoveryPhraseManager integrated with HTTP API
• Users can generate and verify recovery phrases
• Users can recover identities from recovery phrases
• Tests added for backup/recovery flow
• API client backup flow works end-to-end

Priority

P0 - CRITICAL - Essential security feature for alpha

Related Issues

• API Client Issue: [FRONTEND]: Backup and recovery system missing in ZHTP node Sovereign-Network-API-Client#4
• Meta Issue: [META] Missing API endpoints - Tracking Issue #112

Dependencies

• RecoveryPhraseManager from lib-identity (already exists)
• Session management for post-recovery authentication