continuist
05674b4caa
Some checks failed
Podman Rootless Demo / test-backend (push) Has been skipped
Podman Rootless Demo / test-frontend (push) Has been skipped
Podman Rootless Demo / build-backend (push) Has been skipped
Podman Rootless Demo / build-frontend (push) Failing after 5m32s
Podman Rootless Demo / deploy-prod (push) Has been skipped
149 lines
No EOL
6.5 KiB
Markdown
149 lines
No EOL
6.5 KiB
Markdown
# 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
|
|
|
|
```rust
|
|
// 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:
|
|
|
|
```rust
|
|
// Same API on both targets
|
|
use sharenet_passport::{
|
|
Bip39MnemonicGenerator,
|
|
Ed25519KeyDeriver,
|
|
XChaCha20FileEncryptor,
|
|
FileSystemStorage,
|
|
};
|
|
```
|
|
|
|
## Development Workflow
|
|
|
|
### Testing Both Targets
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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. |