sharenet/passport/ARCHITECTURE.md

Sharenet Passport Architecture

Overview

The Sharenet Passport library provides a unified API for cryptographic operations and file storage that works seamlessly across both native and WASM targets. The architecture uses Rust's conditional compilation to automatically select the appropriate implementation based on the target platform.

Architecture Diagram

┌─────────────────────────────────────────────────────────────┐
│                    Public API Surface                       │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ Bip39MnemonicGenerator, Ed25519KeyDeriver,          │   │
│  │ XChaCha20FileEncryptor, FileSystemStorage           │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                 Infrastructure Layer                        │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────┐ │
│  │     Crypto      │  │    Storage      │  │    RNG      │ │
│  │                 │  │                 │  │    Time     │ │
│  └─────────────────┘  └─────────────────┘  └─────────────┘ │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│              Target-Specific Implementations                │
│  ┌─────────────────────────────────────────────────────┐   │
│  │        Native (std)           │       WASM          │   │
│  │ • OsRng                       │ • getrandom(js)     │   │
│  │ • File system                 │ • LocalStorage      │   │
│  │ • SystemTime                  │ • web-time          │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

Module Structure

Core Modules

• domain/: Domain entities, traits, and error types
• application/: Use cases and application logic
• infrastructure/: Platform-specific implementations

Infrastructure Layer

• infrastructure/crypto/: Unified cryptographic API
  • shared/: Shared utilities and constants
  • native/: Native implementations using std
  • wasm/: WASM implementations using browser APIs
• infrastructure/storage/: Unified storage API
  • native/: File system storage
  • wasm/: Browser LocalStorage
• infrastructure/rng/: Random number generation abstraction
• infrastructure/time/: Time abstraction

Target Selection

The library automatically selects implementations based on the target architecture:

• Native targets (x86_64, aarch64, etc.): Use native implementations
• WASM targets (wasm32-unknown-unknown): Use WASM implementations

Conditional Compilation

// In infrastructure/crypto/mod.rs
#[cfg(any(not(target_arch = "wasm32"), feature = "force-native"))]
mod native;

#[cfg(any(target_arch = "wasm32", feature = "force-wasm"))]
mod wasm;

Optional Override Features

For testing and special cases, optional features allow manual override:

• force-wasm: Use WASM implementation even on native targets
• force-native: Use native implementation even on WASM targets

These features are mutually exclusive and will trigger a compile error if both are enabled.

Testing Strategy

Target-Specific Tests

• Native tests: Located in src/infrastructure/crypto/native_test.rs
• WASM tests: Located in src/infrastructure/crypto/wasm_test.rs

Test Runners

• Native: Standard cargo test
• WASM: wasm-bindgen-test-runner configured in .cargo/config.toml

Dependencies

Target-Specific Dependencies

• WASM-only: gloo-storage, web-time, getrandom with JS feature
• Native-only: getrandom with std feature
• Shared: bip39, ed25519-dalek, chacha20poly1305

Public API Consistency

The public API remains identical regardless of target:

// Same API on both targets
use sharenet_passport::{
    Bip39MnemonicGenerator,
    Ed25519KeyDeriver,
    XChaCha20FileEncryptor,
    FileSystemStorage,
};

Development Workflow

Testing Both Targets

# Test native
cargo test

# Test WASM
cargo test --target wasm32-unknown-unknown

# Test with override features
cargo test --features force-wasm
cargo test --features force-native

Building for Different Targets

# Build native
cargo build

# Build WASM
cargo build --target wasm32-unknown-unknown

Adding New Target-Specific Code

1. Add shared logic to the appropriate shared/ module
2. Implement native version in native/ module
3. Implement WASM version in wasm/ module
4. Update the aggregator module to export the unified API
5. Add target-specific tests

Cryptographic Consistency

All implementations produce identical cryptographic outputs for the same inputs, ensuring cross-platform compatibility.