@stellect/wallet-native

Stellar-native wallet implementation for Stellect. Handles key generation, AES-256-GCM encrypted storage, local policy enforcement, and isolated signing.

Install

npm install @stellect/wallet-native

Usage

import { NativeStellarProvider } from '@stellect/wallet-native';

// Set STELLECT_PASSPHRASE env var for key encryption
const wallet = new NativeStellarProvider({ network: 'stellar:testnet' });

// Create a wallet (generates keypair, encrypts, funds on testnet)
const descriptor = await wallet.createWallet('agent-default');
console.log(descriptor.publicKey); // G...

// Sign a transaction (policy check -> decrypt -> sign -> wipe)
const result = await wallet.sign('agent-default', {
  type: 'auth_entry',
  payload: authEntryBase64,
  context: { amount: '0.001', service: 'weather' },
});

// Check balance
const balance = await wallet.getBalance('agent-default');

Security Model

1. Policy-before-decrypt — Policy engine evaluates BEFORE any key material is touched
2. Scoped decryption — Secret key decrypted inside sign(), never returned or stored
3. AES-256-GCM — Keys encrypted with scrypt-derived key (N=16384, r=8, p=1)
4. Audit trail — Every sign() logged to append-only JSONL

Storage

Wallet files stored at ~/.stellect/wallets/{name}.json:

{
  "version": 1,
  "algorithm": "aes-256-gcm",
  "salt": "hex...",
  "iv": "hex...",
  "tag": "hex...",
  "encrypted": "hex...",
  "metadata": { "publicKey": "G...", "network": "stellar:testnet" }
}

Tests

npm test  # 27 tests: keystore, policy-engine, signer, native-provider

License

MIT