Merge development into main for v1.3.0 release

- Add registerIdentity() method for client-side key registration (iOS)
- Add RegisterIdentityRequest and RegisterIdentityResponse types
- Fix duplicate FetchAdapter type in zhtp-api-core.ts
- Version bump to 1.3.0

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: umwelt

dist/core/types.d.ts

@@ -204,6 +204,58 @@ export interface SignupResponse {
     created_at: number;
     citizenship_result?: CitizenshipResult;
 }
+/**
+ * Request for registering an identity with client-generated keys.
+ * Used by iOS/Android where private keys stay on device.
+ * Calls POST /api/v1/identity/register
+ */
+export interface RegisterIdentityRequest {
+    /** Decentralized Identifier: "did:zhtp:{64-char-hex}" */
+    did: string;
+    /** Base64-encoded Dilithium5 public key (~2592 bytes) */
+    public_key: string;
+    /** Base64-encoded Kyber1024 public key (~1568 bytes) - optional for PQC */
+    kyber_public_key?: string;
+    /** Base64-encoded node ID: Blake3(did || device_id) - 32 bytes */
+    node_id: string;
+    /** Device identifier (e.g., "5A63A821-595A-4A71-88FB-3A5448D2A8B6") */
+    device_id: string;
+    /** Optional display name */
+    display_name?: string;
+    /** Identity type: "human", "device", or "organization" (default: "human") */
+    identity_type?: string;
+    /**
+     * Base64-encoded signature proving ownership of private key.
+     * Signs the message: "ZHTP_REGISTER:{did}:{timestamp}"
+     */
+    registration_proof: string;
+    /** Unix timestamp in seconds when signature was created (must be within 300s of server time) */
+    timestamp: number;
+}
+/**
+ * Response from client-side identity registration.
+ * Use identity_id for keystore path: Documents/keystore/{identity_id}/
+ */
+export interface RegisterIdentityResponse {
+    /** Always "registered" on success */
+    status: 'registered';
+    /** 64-character hex string - USE THIS for keystore path */
+    identity_id: string;
+    /** Full DID: "did:zhtp:{identity_id}" */
+    did: string;
+    /** Device identifier echoed back */
+    device_id: string;
+    /** Identity type: "human", "device", or "organization" */
+    identity_type: string;
+    /** Blockchain transaction hash, or null if blockchain registration failed (non-fatal) */
+    blockchain_tx: string | null;
+    /** Welcome bonus amount (5000 for humans, 0 for others) */
+    welcome_bonus: number;
+    /** Unix timestamp when registered */
+    registered_at: number;
+    /** True if kyber_public_key was provided */
+    pqc_enabled: boolean;
+}
 export interface LoginResponse {
     status: string;
     identity_id: string;

dist/core/types.d.ts.map

@@ -3,7 +3,7 @@
  * All API method implementations for various operations
  */
 import { ZhtpApiCore } from './zhtp-api-core';
-import { Identity, Wallet, NetworkStatus, DaoProposal, DaoStats, Transaction, Delegate, ProposalDetails, TreasuryRecord, DApp, SmartContract, ContractDeploymentResult, ContractExecutionResult, Asset, NodeStatus, SignupRequest, LoginRequest, BackupData, BackupVerification, BackupStatus, ImportBackupResponse, SeedVerification, SeedPhrases, Guardian, GuardianResponse, RecoverySession, RecoveryStatus, CitizenshipResult, ProofData, GenerateProofRequest, WalletListResponse, SimpleSendRequest, CrossWalletTransferRequest, TransactionHistoryResponse, NetworkPeersResponse, NetworkStatsResponse, GasInfoResponse, AddPeerRequest, AddPeerResponse, ProtocolInfoResponse, HealthCheckResponse, VersionResponse, CapabilitiesResponse, ProtocolStatsResponse, Web4RegisterRequest, Web4RegisterResponse, Web4ResolveResponse, Web4DomainLookupResponse } from './types';
+import { Identity, Wallet, NetworkStatus, DaoProposal, DaoStats, Transaction, Delegate, ProposalDetails, TreasuryRecord, DApp, SmartContract, ContractDeploymentResult, ContractExecutionResult, Asset, NodeStatus, SignupRequest, LoginRequest, RegisterIdentityRequest, RegisterIdentityResponse, BackupData, BackupVerification, BackupStatus, ImportBackupResponse, SeedVerification, SeedPhrases, Guardian, GuardianResponse, RecoverySession, RecoveryStatus, CitizenshipResult, ProofData, GenerateProofRequest, VerifyProofResponse, WalletListResponse, WalletBalanceResponse, SimpleSendRequest, CrossWalletTransferRequest, TransactionHistoryResponse, NetworkPeersResponse, NetworkStatsResponse, GasInfoResponse, AddPeerRequest, AddPeerResponse, ProtocolInfoResponse, HealthCheckResponse, VersionResponse, CapabilitiesResponse, ProtocolStatsResponse, Web4RegisterRequest, Web4RegisterResponse, Web4ResolveResponse, Web4DomainLookupResponse } from './types';
 export declare abstract class ZhtpApiMethods extends ZhtpApiCore {
     signIn(did: string, passphrase: string): Promise<Identity>;
     createIdentity(data: any): Promise<Identity>;
@@ -15,6 +15,39 @@ export declare abstract class ZhtpApiMethods extends ZhtpApiCore {
      * Login with existing identity
      */
     login(request: LoginRequest): Promise<Identity>;
+    /**
+     * Register identity with client-generated keys (iOS/Android)
+     *
+     * Use this for mobile apps where private keys are generated and stored on device.
+     * Private keys NEVER leave the device - only public keys are sent to server.
+     *
+     * @param request - Registration request with public keys and proof
+     * @returns Registration response with identity_id for keystore path
+     *
+     * @example
+     * ```typescript
+     * // iOS generates keys locally
+     * const did = `did:zhtp:${identityHash}`;
+     * const timestamp = Math.floor(Date.now() / 1000);
+     * const message = `ZHTP_REGISTER:${did}:${timestamp}`;
+     * const signature = sign(message, privateKey);
+     *
+     * const response = await api.registerIdentity({
+     *   did,
+     *   public_key: base64PublicKey,
+     *   kyber_public_key: base64KyberPublicKey,
+     *   node_id: base64NodeId, // Blake3(did || device_id)
+     *   device_id: deviceUUID,
+     *   display_name: "User's iPhone",
+     *   identity_type: "human",
+     *   registration_proof: base64Signature,
+     *   timestamp,
+     * });
+     *
+     * // Store locally using: Documents/keystore/{response.identity_id}/
+     * ```
+     */
+    registerIdentity(request: RegisterIdentityRequest): Promise<RegisterIdentityResponse>;
     /**
      * Map signup response from backend to Identity interface
      */
@@ -23,10 +56,94 @@ export declare abstract class ZhtpApiMethods extends ZhtpApiCore {
      * Map login response from backend to Identity interface
      */
     private mapLoginResponseToIdentity;
-    recoverIdentity(method: 'seed' | 'backup' | 'social', data: string): Promise<Identity>;
-    recoverIdentityFromSeed(recoveryData: Record<string, any>): Promise<Identity>;
+    /**
+     * Recover identity from recovery phrase (20-word phrase)
+     *
+     * SECURITY WARNINGS:
+     * 1. This endpoint is rate-limited to 3 attempts per hour per IP
+     * 2. Requires exactly 20 words
+     * 3. Creates a new session upon successful recovery
+     *
+     * @param recoveryPhrase - 20-word recovery phrase
+     * @returns Recovered identity info and new session token
+     * @throws Error if recovery phrase is invalid or rate limit exceeded
+     */
+    recoverIdentity(recoveryPhrase: string): Promise<{
+        status: string;
+        identity: {
+            identity_id: string;
+            did: string;
+        };
+        session_token: string;
+    }>;
+    /**
+     * @deprecated Use recoverIdentity() with recovery phrase instead
+     */
+    recoverIdentityFromSeed(recoveryData: Record<string, any>): Promise<any>;
+    /**
+     * @deprecated Use importBackup() instead
+     */
     restoreIdentityFromBackup(backupData: Record<string, any>): Promise<Identity>;
+    /**
+     * @deprecated Guardian recovery endpoints not yet implemented in node
+     */
     recoverIdentityWithGuardians(guardianData: Record<string, any>): Promise<Identity>;
+    /**
+     * Generate a recovery phrase for identity backup
+     *
+     * SECURITY WARNINGS:
+     * 1. Recovery phrase is returned ONCE and must be displayed immediately
+     * 2. Client MUST display securely and NEVER store in logs/cache
+     * 3. Use HTTPS only to prevent network sniffing
+     * 4. Requires active authenticated session
+     *
+     * @param identityId - Identity ID to generate recovery phrase for
+     * @param sessionToken - Active session token for authentication
+     * @returns Recovery phrase hash, phrase (for display only), and instructions
+     * @throws Error if session is invalid or identity not found
+     */
+    generateRecoveryPhrase(identityId: string, sessionToken: string): Promise<{
+        status: string;
+        phrase_hash: string;
+        recovery_phrase: string;
+        instructions: string;
+    }>;
+    /**
+     * Verify a recovery phrase is correct (20 words)
+     *
+     * SECURITY WARNINGS:
+     * 1. Recovery phrase must be exactly 20 words
+     * 2. Never log or store recovery phrases
+     * 3. This endpoint prevents typos before using for recovery
+     *
+     * @param identityId - Identity ID that owns the recovery phrase
+     * @param recoveryPhrase - 20-word recovery phrase to verify
+     * @returns Verification result (true if valid, false if invalid)
+     * @throws Error if recovery phrase format is invalid
+     */
+    verifyRecoveryPhrase(identityId: string, recoveryPhrase: string): Promise<{
+        status: string;
+        verified: boolean;
+    }>;
+    /**
+     * Reset password using recovery phrase
+     *
+     * SECURITY WARNINGS:
+     * 1. This endpoint invalidates all existing sessions after successful reset
+     * 2. Requires valid 20-word recovery phrase
+     * 3. Use a strong new password (minimum 12 characters recommended)
+     * 4. Cannot be reversed - old password will no longer work
+     *
+     * @param identityId - Identity ID (can also use DID format "did:zhtp:xxx")
+     * @param recoveryPhrase - Valid 20-word recovery phrase
+     * @param newPassword - New password to set
+     * @returns Confirmation of password reset and session invalidation
+     * @throws Error if recovery phrase is invalid or identity not found
+     */
+    resetPassword(identityId: string, recoveryPhrase: string, newPassword: string): Promise<{
+        status: string;
+        message: string;
+    }>;
     /**
      * Export encrypted identity backup
      *
@@ -79,6 +196,9 @@ export declare abstract class ZhtpApiMethods extends ZhtpApiCore {
      * @throws Error if seed phrase format is invalid
      */
     verifySeedPhrase(identityId: string, seedPhrase: string): Promise<SeedVerification>;
+    /**
+     * @deprecated This endpoint is not available in the node API
+     */
     exportSeedPhrases(identityId: string): Promise<SeedPhrases>;
     addGuardian(identityId: string, sessionToken: string, guardianDid: string, guardianPublicKey: number[], guardianName: string): Promise<GuardianResponse>;
     listGuardians(sessionToken: string): Promise<{
@@ -107,16 +227,62 @@ export declare abstract class ZhtpApiMethods extends ZhtpApiCore {
             expires_at: number;
         }>;
     }>;
-    cancelRecovery(recoveryId: string): Promise<void>;
     applyCitizenship(identityId: string, applicationData?: Record<string, any>): Promise<CitizenshipResult>;
+    /**
+     * @deprecated ZK DID endpoints not yet implemented in the node
+     */
     createZkDid(didData?: Record<string, any>): Promise<any>;
-    getIdentity(did: string): Promise<Identity>;
+    /**
+     * Get identity information by ID
+     *
+     * @param identityId - Identity ID (hex format) or DID
+     * @returns Identity information including type, access level, and timestamps
+     * @throws Error if identity not found
+     */
+    getIdentity(identityId: string): Promise<{
+        status: string;
+        identity_id: string;
+        identity_type: string;
+        access_level: string;
+        created_at: number;
+        last_active: number;
+    }>;
+    /**
+     * @deprecated This endpoint is not available in the node API
+     */
     verifyIdentity(did: string, requirements?: Record<string, any>): Promise<boolean>;
+    /**
+     * @deprecated This endpoint is not available in the node API
+     */
     checkIdentityExists(identifier: string): Promise<boolean>;
+    /**
+     * @deprecated This endpoint is not available in the node API. Use signIn() or login() instead.
+     */
     signInWithIdentity(identity: Identity, passphrase: string): Promise<{
         token: string;
         identity: Identity;
     }>;
+    /**
+     * Sign a message with an identity's private key
+     *
+     * SECURITY NOTES:
+     * 1. Uses post-quantum CRYSTALS-Dilithium2 algorithm
+     * 2. Signature is 2420 bytes
+     * 3. For verifying message authenticity and identity ownership
+     *
+     * @param identityId - Identity ID (hex format) to sign with
+     * @param message - Message to sign
+     * @returns Signature, algorithm, and public key
+     * @throws Error if identity not found or signing fails
+     */
+    signMessage(identityId: string, message: string): Promise<{
+        success: boolean;
+        identity_id: string;
+        message: string;
+        signature: string;
+        signature_algorithm: string;
+        public_key: string;
+    }>;
     /**
      * Get list of connected network peers
      * @returns Peer information including peer IDs, types, and connection status
@@ -160,7 +326,7 @@ export declare abstract class ZhtpApiMethods extends ZhtpApiCore {
      * @param identityId - Identity ID (hex string)
      * @returns Detailed balance information for the wallet
      */
-    getWalletBalance(walletType: string, identityId: string): Promise<number>;
+    getWalletBalance(walletType: string, identityId: string): Promise<WalletBalanceResponse>;
     /**
      * Get comprehensive wallet statistics for an identity
      * @param identityId - Identity ID (hex string)
@@ -321,7 +487,7 @@ export declare abstract class ZhtpApiMethods extends ZhtpApiCore {
      *   console.log(`Verified claim: ${verification.claim}`);
      * }
      */
-    verifyZkProof(proof: ProofData): Promise<boolean>;
+    verifyZkProof(proof: ProofData): Promise<VerifyProofResponse>;
     testConnection(): Promise<boolean>;
     /**
      * Get protocol information including version, node ID, and supported features