Upload documentation/ARCHITECTURE.md with huggingface_hub

documentation/ARCHITECTURE.md

@@ -0,0 +1,463 @@
+# Architecture & Flow Diagrams
+
+This document provides visual representations of the Solana Secure Signer architecture.
+
+---
+
+## 🏗️ System Architecture
+
+```
+┌───────────────────────────────────────────────────────────────────────┐
+│                         USER APPLICATION LAYER                        │
+│  ┌─────────────────────────────────────────────────────────────┐     │
+│  │               Your Python CLI (Coldstar SOL)                 │     │
+│  │  • Transaction building                                      │     │
+│  │  • Network communication                                     │     │
+│  │  • User interface                                            │     │
+│  └───────────────┬────────────────────────────┬─────────────────┘     │
+│                  │                            │                       │
+│                  │                            │                       │
+└──────────────────┼────────────────────────────┼───────────────────────┘
+                   │                            │
+                   ▼                            ▼
+┌───────────────────────────────────────────────────────────────────────┐
+│                      INTEGRATION LAYER                                │
+│  ┌──────────────────────────┐   ┌────────────────────────────────┐   │
+│  │   FFI Integration        │   │   CLI Subprocess Integration   │   │
+│  │   (Fast, Direct)         │   │   (Portable, Isolated)         │   │
+│  │                          │   │                                │   │
+│  │  • ctypes bindings       │   │  • subprocess.run()            │   │
+│  │  • Shared library        │   │  • stdin/stdout JSON           │   │
+│  │  • Direct function calls │   │  • Process isolation           │   │
+│  └────────────┬─────────────┘   └────────────┬───────────────────┘   │
+│               │                              │                       │
+└───────────────┼──────────────────────────────┼───────────────────────┘
+                │                              │
+                └──────────┬───────────────────┘
+                           ▼
+┌───────────────────────────────────────────────────────────────────────┐
+│                      RUST SIGNING CORE                                │
+│  ┌─────────────────────────────────────────────────────────────┐     │
+│  │                    Public API                                │     │
+│  │  • sign_transaction(container, passphrase, tx)              │     │
+│  │  • create_encrypted_container(key, passphrase)              │     │
+│  └────────────┬────────────────────────────────────────────────┘     │
+│               ▼                                                       │
+│  ┌─────────────────────────────────────────────────────────────┐     │
+│  │                 Signing Logic (signer.rs)                    │     │
+│  │  1. Derive decryption key (Argon2id)                        │     │
+│  │  2. Decrypt ciphertext (AES-256-GCM)                        │     │
+│  │  3. Copy to secure buffer                                   │     │
+│  │  4. Sign with Ed25519                                       │     ��
+│  │  5. Return signature                                        │     │
+│  └────────────┬────────────────────────────────────────────────┘     │
+│               ▼                                                       │
+│  ┌─────────────────────────────────────────────────────────────┐     │
+│  │            Secure Memory (secure_memory.rs)                  │     │
+│  │  • SecureBuffer: mlock/VirtualLock                          │     │
+│  │  • Automatic zeroization on drop                            │     │
+│  │  • Panic-safe cleanup                                       │     │
+│  └─────────────────────────────────────────────────────────────┘     │
+│                                                                       │
+│  Dependencies: ed25519-dalek, aes-gcm, argon2, zeroize, region       │
+└───────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 🔄 Signing Flow (Detailed)
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│ PHASE 1: INPUT PREPARATION                                          │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                     │
+│  Python Application                                                 │
+│  ├─ Load encrypted container (JSON file)                           │
+│  ├─ Get passphrase (user input, secure)                            │
+│  └─ Prepare unsigned transaction bytes                             │
+│                                                                     │
+│  Status: ✅ No sensitive data yet                                   │
+└──────────────────────────┬──────────────────────────────────────────┘
+                           ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│ PHASE 2: ENTER RUST SECURE ZONE                                    │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                     │
+│  FFI Boundary / CLI Invocation                                      │
+│  ├─ Serialize inputs to JSON/bytes                                 │
+│  ├─ Call: sign_transaction_ffi() or subprocess                     │
+│  └─ Enter Rust memory space                                        │
+│                                                                     │
+│  Status: ✅ Encrypted data crosses boundary                         │
+└──────────────────────────┬──────────────────────────────────────────┘
+                           ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│ PHASE 3: KEY DERIVATION                                            │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                     │
+│  Argon2id Key Derivation                                           │
+│  ├─ Input: passphrase + salt from container                        │
+│  ├─ Compute: memory-hard hash                                      │
+│  ├─ Output: 32-byte AES key                                        │
+│  └─ Zeroize: passphrase copy                                       │
+│                                                                     │
+│  Status: ✅ Passphrase zeroized, no plaintext key yet               │
+└──────────────────────────┬──────────────────────────────────────────┘
+                           ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│ PHASE 4: MEMORY ALLOCATION & LOCKING                               │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                     │
+│  SecureKeyBuffer::new_secret_key()                                  │
+│  ├─ Allocate: 32 bytes on heap                                     │
+│  ├─ Lock: mlock()/VirtualLock() syscall                            │
+│  ├─ Verify: lock succeeded or return error                         │
+│  └─ Initialize: fill with zeros                                    │
+│                                                                     │
+│  Memory State:                                                      │
+│  ┌────────────────────────────────────┐                            │
+│  │  Locked RAM (32 bytes)             │                            │
+│  │  [0, 0, 0, ..., 0]  (all zeros)    │                            │
+│  │  Status: LOCKED, not swappable     │                            │
+│  └────────────────────────────────────┘                            │
+│                                                                     │
+│  Status: ✅ Secure buffer ready, no sensitive data yet              │
+└──────────────────────────┬──────────────────────────────────────────┘
+                           ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│ PHASE 5: DECRYPTION                                                │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                     │
+│  AES-256-GCM Decryption                                             │
+│  ├─ Input: ciphertext + nonce + derived key                        │
+│  ├─ Decrypt: to temporary Vec<u8>                                  │
+│  ├─ Verify: authentication tag                                     │
+│  └─ Output: plaintext key (32 bytes)                               │
+│                                                                     │
+│  Temporary State:                                                   │
+│  ┌────────────────────────────────────┐                            │
+│  │  Stack/Heap (decrypted_bytes)      │                            │
+│  │  [k₀, k₁, k₂, ..., k₃₁]            │                            │
+│  │  Status: PLAINTEXT KEY! ⚠️          │                            │
+│  └────────────────────────────────────┘                            │
+│                                                                     │
+│  Status: ⚠️ CRITICAL - Plaintext key in temporary buffer            │
+└──────────────────────────┬──────────────────────────────────────────┘
+                           ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│ PHASE 6: SECURE TRANSFER                                           │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                     │
+│  Copy to Locked Buffer                                             │
+│  ├─ Copy: decrypted_bytes → secure_key buffer                      │
+│  ├─ Zeroize: decrypted_bytes (constant-time)                       │
+│  └─ Verify: no copies remain                                       │
+│                                                                     │
+│  Before:                            After:                          │
+│  ┌──────────────────────┐           ┌──────────────────────┐       │
+│  │  Temporary Buffer    │           │  Temporary Buffer    │       │
+│  │  [k₀, k₁, ..., k₃₁]  │  ───────> │  [0, 0, ..., 0]      │       │
+│  │  (plaintext key)     │           │  (zeroized)          │       │
+│  └──────────────────────┘           └──────────────────────┘       │
+│                                                                     │
+│  ┌──────────────────────┐           ┌──────────────────────┐       │
+│  │  Locked Buffer       │           │  Locked Buffer       │       │
+│  │  [0, 0, ..., 0]      │  ───────> │  [k₀, k₁, ..., k₃₁]  │       │
+│  │  (empty)             │           │  (plaintext key)     │       │
+│  └──────────────────────┘           └──────────────────────┘       │
+│                                                                     │
+│  Status: ✅ Key in locked memory, temporary copy zeroized           │
+└──────────────────────────┬──────────────────────────────────────────┘
+                           ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│ PHASE 7: SIGNING                                                   │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                     │
+│  Ed25519 Signing                                                    │
+│  ├─ Create: SigningKey from locked buffer (borrow, no copy)        │
+│  ├─ Sign: signature = signing_key.sign(transaction)                │
+│  ├─ Output: 64-byte signature                                      │
+│  └─ Note: SigningKey borrows, doesn't own the key                  │
+│                                                                     │
+│  Memory State:                                                      │
+│  ┌────────────────────────────────────┐                            │
+│  │  Locked Buffer                     │                            │
+│  │  [k₀, k₁, k₂, ..., k₃₁]  ◄─────── SigningKey borrows            │
+│  │  Status: LOCKED, being used        │                            │
+│  └────────────────────────────────────┘                            │
+│                                                                     │
+│  Status: ⚠️ Key still in memory, being used for signing             │
+└──────────────────────────┬──────────────────────────────────────────┘
+                           ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│ PHASE 8: RESULT PREPARATION                                        │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                     │
+│  Build Signed Transaction                                          │
+│  ├─ Allocate: new Vec<u8> for result                               │
+│  ├─ Append: signature (64 bytes, public data)                      │
+│  ├─ Append: original transaction                                   │
+│  └─ Return: SignedTransaction struct                               │
+│                                                                     │
+│  Status: ✅ Public signature ready, key still in locked buffer      │
+└──────────────────────────┬──────────────────────────────────────────┘
+                           ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│ PHASE 9: AUTOMATIC CLEANUP (Drop)                                  │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                     │
+│  SecureKeyBuffer::drop() automatically called                       │
+│  ├─ Trigger: secure_key goes out of scope                          │
+│  ├─ Zeroize: data.zeroize() (constant-time)                        │
+│  ├─ Unlock: munlock()/VirtualUnlock()                              │
+│  └─ Extra: manual write_bytes for paranoia                         │
+│                                                                     │
+│  Before Drop:                       After Drop:                     │
+│  ┌──────────────────────┐           ┌──────────────────────┐       │
+│  │  Locked Buffer       │           │  Unlocked Memory     │       │
+│  │  [k₀, k₁, ..., k₃₁]  │  ───────> │  [0, 0, ..., 0]      │       │
+│  │  (plaintext key)     │           │  (zeroized)          │       │
+│  │  Status: LOCKED      │           │  Status: FREE        │       │
+│  └──────────────────────┘           └──────────────────────┘       │
+│                                                                     │
+│  Note: This happens even if signing panicked!                      │
+│                                                                     │
+│  Status: ✅ Key completely erased from memory                       │
+└──────────────────────────┬──────────────────────────────────────────┘
+                           ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│ PHASE 10: RETURN TO PYTHON                                         │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                     │
+│  FFI Boundary / CLI Output                                          │
+│  ├─ Serialize: SignedTransaction to JSON                           │
+│  ├─ Return: to Python via FFI or stdout                            │
+│  └─ Python receives: signature + signed transaction                │
+│                                                                     │
+│  Data Returned to Python:                                          │
+│  • signature: [s₀, s₁, ..., s₆₃] (64 bytes, public)                │
+│  • signed_tx: signature + transaction (public)                     │
+│                                                                     │
+│  Status: ✅ Only public data crosses boundary                       │
+└─────────────────────────────────────────────────────────────────────┘
+
+SECURITY SUMMARY:
+═══════════════════════════════════════════════════════════════════════
+• Plaintext key existed in locked memory for phases 6-8 only
+• Key was zeroized immediately after use (phase 9)
+• No copies of plaintext key exist outside locked buffer
+• Cleanup is guaranteed even on panic
+• Only public data (signature) returned to Python
+• Private key NEVER exposed to Python memory space
+═══════════════════════════════════════════════════════════════════════
+```
+
+---
+
+## 📦 Data Flow (Input → Output)
+
+```
+INPUT (Python)                    SECURE ZONE (Rust)              OUTPUT (Python)
+═══════════════                   ═══════════════════             ═══════════════
+
+┌──────────────┐                                                 ┌──────────────┐
+│  Encrypted   │                                                 │   Signature  │
+│  Container   │────────┐                                        │  (64 bytes)  │
+│  (JSON)      │        │                                        │              │
+└──────────────┘        │                                        └──────────────┘
+                        │                                                 ▲
+┌──────────────┐        │         ┌─────────────────────┐                │
+│  Passphrase  │────────┼────────>│  Rust Signing Core  │────────────────┤
+│  (string)    │        │         │                     │                │
+└──────────────┘        │         │  1. Decrypt         │        ┌──────────────┐
+                        │         │  2. Lock memory     │        │   Signed     │
+┌──────────────┐        │         │  3. Sign            │        │  Transaction │
+│  Unsigned TX │────────┘         │  4. Zeroize         │        │   (bytes)    │
+│  (bytes)     │                  │  5. Return          │        └──────────────┘
+└──────────────┘                  └─────────────────────┘                 ▲
+                                                                           │
+                                     Private key exists                    │
+                                     here only! Never                      │
+                                     leaves this box.                      │
+                                                                           │
+                                     ┌──────────────────┐                  │
+                                     │  Locked Memory   │                  │
+                                     │  ┌────────────┐  │                  │
+                                     │  │ Private    │  │                  │
+                                     │  │ Key        │  │                  │
+                                     │  │ (32 bytes) │  │                  │
+                                     │  └────────────┘  │                  │
+                                     │  Auto-zeroized!  │                  │
+                                     └──────────────────┘                  │
+                                                                           │
+══════════════════════════════════════════════════════════════════════════│══
+                              FFI / CLI Boundary                          │
+══════════════════════════════════════════════════════════════════════════╧══
+
+Legend:
+────> Data flow
+═══> Security boundary
+┌───┐ Data container
+```
+
+---
+
+## 🔒 Memory Safety Guarantees
+
+```
+╔═══════════════════════════════════════════════════════════════════════╗
+║                     MEMORY SAFETY GUARANTEES                          ║
+╚═══════════════════════════════════════════════════════════════════════╝
+
+Guarantee 1: MEMORY LOCKING
+┌──────────────────────────────��──────────────────────────────────────┐
+│  RAM                                                                 │
+│  ┌───────────────────────────────────┐                              │
+│  │  Locked Pages (via mlock)         │  ◄── Private key here        │
+│  │  Cannot be swapped to disk        │                              │
+│  └───────────────────────────────────┘                              │
+│                    ║                                                 │
+│                    ║ BLOCKED (no swap)                               │
+│                    ▼                                                 │
+│  ┌───────────────────────────────────┐                              │
+│  │  Disk / Swap File                 │  ◄── Key never reaches here  │
+│  │  ✘ Private key CANNOT be here     │                              │
+│  └───────────────────────────────────┘                              │
+└─────────────────────────────────────────────────────────────────────┘
+
+Guarantee 2: ZEROIZATION
+┌─────────────────────────────────────────────────────────────────────┐
+│  Before Drop:                    After Drop:                         │
+│  ┌─────────────────┐             ┌─────────────────┐                │
+│  │ [k₀, k₁, ..., k₃₁]│             │ [0, 0, ..., 0]  │                │
+│  │  Private key     │  ────────>  │  All zeros      │                │
+│  │  SENSITIVE! ⚠️    │             │  Safe ✅         │                │
+│  └─────────────────┘             └─────────────────┘                │
+│                                                                      │
+│  Method: zeroize crate (constant-time, not optimized out)           │
+└─────────────────────────────────────────────────────────────────────┘
+
+Guarantee 3: PANIC SAFETY
+┌─────────────────────────────────────────────────────────────────────┐
+│  Normal Flow:          Panic Flow:                                   │
+│  ┌──────────┐          ┌──────────┐                                 │
+│  │  Signing │          │  Signing │                                 │
+│  │  Success │          │  PANIC!  │                                 │
+│  └────┬─────┘          └────┬─────┘                                 │
+│       │                     │                                        │
+│       ▼                     ▼                                        │
+│  ┌──────────┐          ┌──────────┐                                 │
+│  │  Drop    │          │  Drop    │  ◄── Drop ALWAYS runs            │
+│  │  Runs    │          │  Runs    │                                 │
+│  └────┬─────┘          └────┬─────┘                                 │
+│       │                     │                                        │
+│       ▼                     ▼                                        │
+│  ┌──────────┐          ┌──────────┐                                 │
+│  │ Zeroized │          │ Zeroized │  ◄── Key erased in both cases   │
+│  └──────────┘          └──────────┘                                 │
+└─────────────────────────────────────────────────────────────────────┘
+
+Guarantee 4: NO COPIES
+┌─────────────────────────────────────────────────────────────────────┐
+│  ONLY ONE instance of plaintext key exists:                          │
+│                                                                      │
+│  ┌────────────────────────────────────────────────┐                 │
+│  │  SecureKeyBuffer                               │                 │
+│  │  ┌──────────────────────────────────┐          │                 │
+│  │  │  Private Key (32 bytes)          │  ◄─────── Single instance  │
+│  │  │  [k₀, k₁, k₂, ..., k₃₁]          │          │                 │
+│  │  └──────────────────────────────────┘          │                 │
+│  │                   ▲                             │                 │
+│  │                   │ borrow (no copy)            │                 │
+│  │                   │                             │                 │
+│  │         ┌─────────┴──────────┐                  │                 │
+│  │         │   SigningKey        │                 │                 │
+│  │         │   (borrows data)    │                 │                 │
+│  │         └─────────────────────┘                 │                 │
+│  └────────────────────────────────────────────────┘                 │
+│                                                                      │
+│  All other buffers (decryption, etc.) are zeroized immediately       │
+└─────────────────────────────────────────────────────────────────────┘
+
+Guarantee 5: EPHEMERAL LIFECYCLE
+┌─────────────────────────────────────────────────────────────────────┐
+│  Function Scope:                                                     │
+│                                                                      │
+│  fn sign_transaction(...) {                                         │
+│      let secure_key = SecureKeyBuffer::new();  ◄── Created          │
+│      // ... decrypt into secure_key ...                             │
+│      // ... use for signing ...                                     │
+│      return signature;                                              │
+│  } ◄── secure_key dropped here, automatic cleanup                   │
+│                                                                      │
+│  Key exists ONLY during function execution                          │
+│  No global variables, no caching, no persistence                    │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 🎯 Integration Comparison
+
+```
+╔═══════════════════════════════════════════════════════════════════════╗
+║                    INTEGRATION MODE COMPARISON                        ║
+╚═══════════════════════════════════════════════════════════════════════╝
+
+┌─────────────────────────────────────────────────────────────────────┐
+│  FFI Mode (libsolana_secure_signer.so/dll/dylib)                     │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                      │
+│  Python ←──(ctypes)──→ Rust Library                                 │
+│                                                                      │
+│  Pros:                                                               │
+│  ✅ Fastest (no process overhead)                                    │
+│  ✅ Direct function calls                                            │
+│  ✅ Minimal latency (~0.1ms overhead)                                │
+│                                                                      │
+│  Cons:                                                               │
+│  ⚠️ Requires compiled library for platform                           │
+│  ⚠️ Shared memory space (less isolated)                              │
+│                                                                      │
+│  Use When:                                                           │
+│  • Production deployments                                            │
+│  • High transaction throughput                                       │
+│  • Minimal latency required                                          │
+└─────────────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────────────┐
+│  CLI Mode (solana-signer binary)                                     │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                      │
+│  Python ──(subprocess)──→ Rust Binary ──(exit)──→ All memory freed  │
+│                                                                      │
+│  Pros:                                                               │
+│  ✅ Maximum isolation (separate process)                             │
+│  ✅ Platform-agnostic (just needs binary)                            │
+│  ✅ Automatic cleanup (process exit)                                 │
+│  ✅ No FFI complexity                                                │
+│                                                                      │
+│  Cons:                                                               │
+│  ⚠️ Slower (process startup ~10-50ms)                                │
+│  ⚠️ IPC overhead (JSON serialization)                                │
+│                                                                      │
+│  Use When:                                                           │
+│  • Development/testing                                               │
+│  • Maximum security isolation                                        │
+│  • Cross-platform portability                                        │
+│  • Occasional signing (not high frequency)                           │
+└─────────────────────────────────────────────────────────────────────┘
+
+Performance Comparison:
+┌────────────────┬──────────┬───────────┬──────────────┐
+│  Operation     │   FFI    │    CLI    │  Difference  │
+├────────────────┼──────────┼───────────┼──────────────┤
+│  Overhead      │  ~0.1ms  │  ~10-50ms │  100-500x    │
+│  Throughput    │  High    │  Low      │  -           │
+│  Memory Safety │  Good    │  Excellent│  CLI better  │
+│  Portability   │  Medium  │  High     │  CLI better  │
+└────────────────┴──────────┴───────────┴──────────────┘
+```
+
+This completes the visual documentation! 🎉