Merge pull request #303 from mgtmdccix-oss/feat/wallet-key-version

feat(wallets): add keyVersion field to Wallet

Author: Jambox11

prisma/migrations/20260602_add_wallet_key_version/migration.sql

@@ -0,0 +1,10 @@
+-- Migration: add keyVersion field to Wallet
+--
+-- keyVersion tracks the key algorithm/derivation scheme version on a wallet.
+-- It is distinct from:
+--   encryptionVersion  – the envelope/KMS format used to encrypt the secret material
+--   secretVersion      – a monotonic counter incremented on every key rotation
+--
+-- Default value of 1 is applied to all existing rows so no data migration is needed.
+
+ALTER TABLE "Wallet" ADD COLUMN "keyVersion" INTEGER NOT NULL DEFAULT 1;

prisma/schema.prisma

@@ -156,6 +156,11 @@ model Wallet {
   /// Supports rotation by incrementing secret material while preserving history.
   secretVersion Int @default(1)
 
+  /// Key algorithm/derivation scheme version (e.g. 1 = Stellar Ed25519 via stellar-sdk).
+  /// Increment when the key algorithm or derivation path changes so consumers can detect
+  /// stale material and trigger re-encryption or re-issuance.
+  keyVersion Int @default(1)
+
   network WalletNetwork
   status  WalletStatus  @default(PROVISIONING)
 

src/key-management/domain/key-types.ts

@@ -30,6 +30,8 @@ export interface GeneratedKeyPair {
 export interface EncryptedKeyMaterial {
   encryptedData: string;
   encryptionVersion: number;
+  /** Key algorithm/derivation scheme version. Matches Wallet.keyVersion. */
+  keyVersion: number;
   keyType: KeyType;
   publicKey: string;
 }

src/key-management/key-management.controller.ts

@@ -45,6 +45,7 @@ export class KeyManagementController {
       publicKey: result.publicKey,
       encryptedData: result.encryptedData,
       encryptionVersion: result.encryptionVersion,
+      keyVersion: result.keyVersion,
       keyType: result.keyType,
       // Note: No private key is ever returned
     };

src/key-management/key-management.service.spec.ts

@@ -71,6 +71,7 @@ describe('KeyManagementService', () => {
       expect(result).toHaveProperty('publicKey');
       expect(result).toHaveProperty('keyType', KeyType.STELLAR_ED25519);
       expect(result).toHaveProperty('encryptionVersion');
+      expect(result).toHaveProperty('keyVersion', 1);
 
       // Critical: Should NOT contain plaintext private key
       expect(result).not.toHaveProperty('privateKey');

src/key-management/key-management.service.ts

@@ -119,6 +119,7 @@ export class KeyManagementService {
       return {
         encryptedData,
         encryptionVersion: 1,
+        keyVersion: 1,
         keyType: request.keyType,
         publicKey: keyPair.publicKey,
       };
@@ -269,7 +270,8 @@ export class KeyManagementService {
 
       return {
         encryptedData: newEncryptedData,
-        encryptionVersion: 2, // Increment version
+        encryptionVersion: 2, // Increment encryption envelope version
+        keyVersion: currentKeyVersion, // Key algorithm version is unchanged on re-encryption
         keyType,
         publicKey: '', // Would derive from private key in production
       };

src/wallets/domain/wallet.model.ts

@@ -37,6 +37,13 @@ export interface Wallet {
   /** Supports rotation by incrementing secret material while preserving history. */
   secretVersion: number;
 
+  /**
+   * Key algorithm/derivation scheme version (e.g. 1 = Stellar Ed25519 via stellar-sdk).
+   * Increment when the key algorithm or derivation path changes so consumers can detect
+   * stale material and trigger re-encryption or re-issuance.
+   */
+  keyVersion: number;
+
   /** Mainnet/testnet separation. */
   network: WalletNetwork;
 

src/wallets/wallet-creation-orchestrator.service.ts

@@ -465,6 +465,7 @@ export class WalletCreationOrchestrator {
           status: 'PROVISIONING', // Start in PROVISIONING (Issue #188)
           encryptionVersion: 1,
           secretVersion: 1,
+          keyVersion: 1,
         },
       });
       phaseTimings['wallet-persist'] = Date.now() - t;
@@ -624,6 +625,7 @@ export class WalletCreationOrchestrator {
       encryptedSecret: prismaWallet.encryptedSecret,
       encryptionVersion: prismaWallet.encryptionVersion,
       secretVersion: prismaWallet.secretVersion,
+      keyVersion: prismaWallet.keyVersion ?? 1,
       network: prismaWallet.network as WalletNetwork,
       status: prismaWallet.status as WalletStatus,
       statusReason: prismaWallet.statusReason,

src/wallets/wallets.service.spec.ts

@@ -107,6 +107,7 @@ describe('WalletsService', () => {
         status: 'ACTIVE',
         encryptionVersion: 1,
         secretVersion: 1,
+        keyVersion: 1,
         statusReason: null,
         statusChangedAt: new Date(),
         rotatedFromId: null,
@@ -289,6 +290,7 @@ describe('WalletsService', () => {
         publicKey: 'old-public-key',
         encryptedSecret: 'old-encrypted-secret',
         secretVersion: 1,
+        keyVersion: 1,
       };
 
       const updatedWallet = {
@@ -297,6 +299,7 @@ describe('WalletsService', () => {
         publicKey: 'new-public-key',
         encryptedSecret: 'new-encrypted-secret',
         secretVersion: 2,
+        keyVersion: 2,
         network: WalletNetwork.TESTNET,
         status: 'ACTIVE',
         encryptionVersion: 1,

src/wallets/wallets.service.ts

@@ -91,6 +91,7 @@ export class WalletsService {
           status: 'ACTIVE',
           encryptionVersion: encryptedKeyMaterial.encryptionVersion,
           secretVersion: 1,
+          keyVersion: 1,
         },
       });
 
@@ -330,6 +331,7 @@ export class WalletsService {
       encryptedSecret: prismaWallet.encryptedSecret,
       encryptionVersion: prismaWallet.encryptionVersion,
       secretVersion: prismaWallet.secretVersion,
+      keyVersion: prismaWallet.keyVersion ?? 1,
       network: prismaWallet.network as WalletNetwork,
       status: prismaWallet.status as WalletStatus,
       statusReason: prismaWallet.statusReason,