From dc3609bd75f9b55ba1595ee365b86f10a3b30098 Mon Sep 17 00:00:00 2001 From: Continuist Date: Sat, 4 Oct 2025 12:40:51 -0400 Subject: [PATCH] Add restructuring to use a sharenet-passport library crate --- docs/workspace-restructuring-plan.md | 361 +++++++++++++++++++++++++++ 1 file changed, 361 insertions(+) create mode 100644 docs/workspace-restructuring-plan.md diff --git a/docs/workspace-restructuring-plan.md b/docs/workspace-restructuring-plan.md new file mode 100644 index 0000000..5c14052 --- /dev/null +++ b/docs/workspace-restructuring-plan.md @@ -0,0 +1,361 @@ +# Workspace Restructuring Plan + +## Overview + +This document outlines the plan to restructure the Sharenet Passport project into a Cargo workspace with a library crate (`sharenet-passport`) and a CLI wrapper crate (`sharenet-passport-cli`). The goal is to enable reuse of the core passport functionality in multiple contexts (CLI, web/WASM, embedded) while maintaining Clean Architecture principles. + +## Target Architecture + +### Workspace Structure + +``` +sharenet-passport-creator/ +├── Cargo.toml # Workspace manifest +├── sharenet-passport/ # Library crate (core functionality) +│ ├── Cargo.toml +│ └── src/ +│ ├── lib.rs +│ ├── domain/ +│ ├── application/ +│ └── infrastructure/ +├── sharenet-passport-cli/ # CLI crate (command-line interface) +│ ├── Cargo.toml +│ └── src/ +│ ├── main.rs +│ ├── cli/ +│ └── interface/ +└── docs/ +``` + +## Implementation Details + +### 1. Workspace Configuration + +**Root `Cargo.toml`:** +```toml +[workspace] +members = ["sharenet-passport", "sharenet-passport-cli"] +resolver = "2" + +[workspace.dependencies] +# Common dependencies shared across workspace members +bip39 = "2.1" +ed25519-dalek = { version = "2.1", features = ["serde"] } +chacha20poly1305 = "0.10" +hkdf = "0.12" +sha2 = "0.10" +rand = "0.8" +rand_core = "0.6" +serde = { version = "1.0", features = ["derive"] } +serde_cbor = "0.11" +thiserror = "1.0" +zeroize = { version = "1.7", features = ["zeroize_derive"] } +hex = "0.4" +``` + +### 2. Library Crate (`sharenet-passport`) + +**Purpose**: Core passport creation, management, and verification functionality + +**`sharenet-passport/Cargo.toml`:** +```toml +[package] +name = "sharenet-passport" +version = "0.1.0" +edition = "2021" +description = "Core library for Sharenet Passport creation and management" +authors = ["Your Name "] +license = "MIT OR Apache-2.0" +repository = "https://git.sharenet.sh/your-org/sharenet-passport" + +[dependencies] +# Inherit from workspace dependencies +bip39.workspace = true +ed25519-dalek.workspace = true +chacha20poly1305.workspace = true +hkdf.workspace = true +sha2.workspace = true +rand.workspace = true +rand_core.workspace = true +serde.workspace = true +serde_cbor.workspace = true +thiserror.workspace = true +zeroize.workspace = true +hex.workspace = true + +[lib] +crate-type = ["cdylib", "rlib"] # Support both native and WASM + +[features] +default = ["std"] +std = [] # Standard library support +alloc = [] # No-std with alloc support +wasm = ["alloc"] # WASM target support + +[publish] +registry = "sharenet" +``` + +### 3. CLI Crate (`sharenet-passport-cli`) + +**Purpose**: Command-line interface wrapper around the library + +**`sharenet-passport-cli/Cargo.toml`:** +```toml +[package] +name = "sharenet-passport-cli" +version = "0.1.0" +edition = "2021" +description = "CLI interface for Sharenet Passport" +authors = ["Your Name "] + +[dependencies] +sharenet-passport = { path = "../sharenet-passport" } +clap = { version = "4.4", features = ["derive"] } +rpassword = "7.2" + +[dev-dependencies] +assert_matches = "1.5" +tempfile = "3.8" +``` + +## Clean Architecture Preservation + +### Domain Layer (Pure Business Logic) + +**Location**: `sharenet-passport/src/domain/` + +**Characteristics**: +- Pure Rust, no external dependencies +- No I/O operations +- WASM-compatible +- Contains entities, traits, and domain errors + +**Key Files**: +- `entities.rs` - Core data structures (Passport, RecoveryPhrase, etc.) +- `traits.rs` - Abstract interfaces (MnemonicGenerator, KeyDeriver, etc.) +- `error.rs` - Domain-specific errors + +### Application Layer (Use Cases) + +**Location**: `sharenet-passport/src/application/` + +**Characteristics**: +- Generic over infrastructure traits +- Orchestrates domain and infrastructure +- No concrete implementations +- Dependency injection via traits + +**Key Files**: +- `use_cases.rs` - Business use cases (CreatePassport, Import, Export, etc.) +- `error.rs` - Application-specific errors + +### Infrastructure Layer (Platform Implementations) + +**Location**: `sharenet-passport/src/infrastructure/` + +**Characteristics**: +- Concrete implementations of domain traits +- Platform-specific code +- Optional features via conditional compilation +- Separate modules for different concerns + +**Key Files**: +- `crypto.rs` - Cryptographic implementations +- `storage.rs` - File system operations + +## Code Organization + +### Library Public API (`sharenet-passport/src/lib.rs`) + +```rust +// Re-export public API +pub mod domain; +pub mod application; +pub mod infrastructure; + +// Public API surface +pub use domain::entities::{Passport, RecoveryPhrase, PassportFile}; +pub use domain::traits::{MnemonicGenerator, KeyDeriver, FileEncryptor, FileStorage}; +pub use application::use_cases::{ + CreatePassportUseCase, + ImportFromRecoveryUseCase, + ImportFromFileUseCase, + ExportPassportUseCase, + SignCardUseCase +}; +pub use infrastructure::{ + Bip39MnemonicGenerator, + Ed25519KeyDeriver, + XChaCha20FileEncryptor, + FileSystemStorage +}; +``` + +### CLI Entry Point (`sharenet-passport-cli/src/main.rs`) + +```rust +use sharenet_passport::{ + application::use_cases::*, + infrastructure::*, + domain::entities::* +}; + +// CLI-specific code remains here +mod cli; +mod interface; + +use clap::Parser; +use crate::cli::commands::{Cli, Commands}; +use crate::cli::interface::CliInterface; + +fn main() -> Result<(), Box> { + let cli = Cli::parse(); + let interface = CliInterface::new(); + + // CLI command handling + match cli.command { + Commands::Create { output } => { + interface.handle_create(&output)?; + } + // ... other commands + } + + Ok(()) +} +``` + +## Feature Flags Strategy + +### Library Features + +- **`std`** (default): Standard library features including file I/O +- **`alloc`**: No-std with allocator support for embedded systems +- **`wasm`**: WASM-specific optimizations and bindings + +### Usage Examples + +**For Web/WASM Applications:** +```toml +sharenet-passport = { version = "0.1", default-features = false, features = ["wasm"] } +``` + +**For Embedded Systems:** +```toml +sharenet-passport = { version = "0.1", default-features = false, features = ["alloc"] } +``` + +**For CLI Applications:** +```toml +sharenet-passport = { version = "0.1" } # Uses default std features +``` + +## Private Registry Configuration + +### Cargo Configuration + +Add to `~/.cargo/config.toml`: +```toml +[registries.sharenet] +index = "https://git.sharenet.sh/api/v1/crates/{crate}/index" +``` + +### Publishing + +```bash +cd sharenet-passport +cargo publish --registry sharenet +``` + +## Benefits + +### 1. Reusability +- **CLI**: Full command-line interface +- **Web/WASM**: Browser-based passport management +- **Embedded**: Resource-constrained environments +- **Mobile**: Native mobile applications + +### 2. Maintainability +- Clear separation of concerns +- Independent versioning of library vs CLI +- Shared dependency management +- Easier testing and mocking + +### 3. Deployment Flexibility +- Library can be published to private registry +- CLI can be distributed as standalone binary +- Web components can be compiled to WASM +- Embedded systems can use minimal features + +### 4. Development Workflow +- Shared code changes affect all consumers +- Independent development of CLI features +- Parallel testing of different components +- Clear API boundaries + +## Usage Examples + +### Web Application Usage + +```rust +use sharenet_passport::{ + domain::entities::Passport, + application::use_cases::CreatePassportUseCase, + infrastructure::{Bip39MnemonicGenerator, Ed25519KeyDeriver} +}; + +// Web-specific infrastructure implementations +struct WebFileEncryptor; +struct WebStorage; + +impl FileEncryptor for WebFileEncryptor { /* ... */ } +impl FileStorage for WebStorage { /* ... */ } + +let use_case = CreatePassportUseCase::new( + Bip39MnemonicGenerator, + Ed25519KeyDeriver, + WebFileEncryptor, + WebStorage, +); +``` + +### CLI Usage (Unchanged) + +```bash +# Existing CLI commands continue to work +sharenet-passport-cli create --output my-passport.spf +sharenet-passport-cli import-recovery --output restored.spf +sharenet-passport-cli info --file passport.spf +``` + +## Testing Strategy + +### Library Tests +- Unit tests for domain logic +- Integration tests for use cases +- WASM tests using `wasm-bindgen-test` +- Feature-flag specific tests + +### CLI Tests +- End-to-end command tests +- File system integration tests +- Cross-platform compatibility tests +- User interaction tests + +## Migration Considerations + +### Backward Compatibility +- Existing CLI commands remain unchanged +- File formats remain compatible +- API surface remains stable +- Documentation updates minimal + +### Development Impact +- Shared workspace dependencies +- Unified build process +- Consistent testing approach +- Clear separation of library vs CLI concerns + +--- + +This restructuring enables the Sharenet Passport core functionality to be reused across multiple platforms while maintaining the Clean Architecture principles and enabling private registry publishing to git.sharenet.sh. \ No newline at end of file