Local Encrypted Vault Architecture

🔐 Local Encrypted Vault Architecture

Kryptofolio is built on a Privacy-First Architecture. Sensitive credentials — such as Kraken API keys, Binance secrets, and AI agent tokens — are never stored in plaintext and never leave your local machine.

Because Kryptofolio runs locally as a native application or in isolated containers, it does not rely on third-party cloud Key Management Services (such as AWS KMS or Google Cloud KMS). Instead, it implements a self-contained, authenticated cryptographic vault.

---

🛡️ Security Mitigations & Cryptographic Primitives

1. Authenticated Encryption (AES-256-GCM)

The vault uses the Galois/Counter Mode (GCM) of the Advanced Encryption Standard (AES) with a 256-bit key:

• Every encrypted secret produces a 12-byte random Initialization Vector (IV) and a 16-byte Authentication Tag.
• If the SQLite database file (kryptofolio.db) is modified or tampered with outside the application, the cipher automatically rejects the payload upon decryption.

2. V8 RAM Memory Scrubbing

In Node.js, JavaScript strings are immutable primitives managed by the V8 garbage collector. They cannot be reliably cleared from RAM on demand, leaving them exposed to heap scraping attacks.

To prevent this:

• The cryptographic adapter operates strictly with Node.js Buffer instances.
• Immediately after transmitting credentials to an exchange adapter, the backend executes:

  sensitiveBuffer.fill(0);

  This immediately overwrites the plaintext memory addresses with zeros before releasing the buffer.

3. Automatic Log Redaction

The backend uses Pino configured with strict redaction paths:

redact: ['apiKey', 'apiSecret', '*.password', 'authorization'];

Even in debug mode, secrets are filtered before writing to console logs or log files.

---

🔄 Vault Operation Sequence

sequenceDiagram
    autonumber
    participant User
    participant UI as Vue UI (Vault Settings)
    participant Hono as Hono Backend API
    participant UseCase as StoreCredentialUseCase
    participant Crypto as AesGcmCryptographyAdapter
    participant DB as SQLite Vault (kryptofolio.db)

    User->>UI: Submits API Key & Secret (e.g. Kraken)
    UI->>Hono: POST /api/credentials/vault/KRAKEN_API
    Hono->>UseCase: storeCredential(payload)
    UseCase->>Crypto: encrypt(Buffer.from(JSON.stringify(payload)))
    Note over Crypto: Generates random IV<br/>and encrypts with AES-256-GCM
    Crypto-->>UseCase: { ciphertext, iv, authTag }
    UseCase->>DB: INSERT into vault_credentials
    Hono->>Crypto: sensitiveBuffer.fill(0) (RAM Scrub)
    Hono-->>UI: 200 OK (Configured & Saved)

---

📋 Dynamic Vault Registry

Rather than hardcoding exchange forms in the Vue frontend, Kryptofolio uses a Dynamic Vault Registry:

• The backend exposes GET /api/credentials/vault/providers, returning the schema and field specifications for each provider:

  [
    {
      "id": "KRAKEN_API",
      "name": "Kraken",
      "fields": [
        { "key": "apiKey", "label": "API Key", "type": "text" },
        { "key": "apiSecret", "label": "API Secret", "type": "password" }
      ]
    }
  ]

• The Vue UI dynamically renders input controls based on this definition, ensuring seamless extensibility whenever new exchange adapters are introduced.

---

🤖 AI Provider Credentials

The AI Portfolio Advisor reuses this vault for its model-provider API keys (openai, anthropic, google, opencode, ollama-cloud), registered under the ai-model category. A locked vault makes the advisor skip every keyed provider, and because the master key lives only in process memory, a backend restart re-locks it. See AI Advisor: Providers & Models and Audit & Privacy.