diff --git a/docs/passport-profiles-implementation.md b/docs/passport-profiles-implementation.md new file mode 100644 index 0000000..062f576 --- /dev/null +++ b/docs/passport-profiles-implementation.md @@ -0,0 +1,325 @@ +# Passport Profiles Implementation Plan + +## Overview + +This document outlines the detailed implementation plan for extending the Sharenet Passport system to support multiple profiles per node using the .spf (Sharenet Passport File) format. The system will allow a single Passport to maintain multiple identities across different nodes and networks, with unlimited profiles per node. + +## Core Design Principles + +- **Portability**: Maintain .spf file portability while extending functionality +- **Backward Compatibility**: Existing .spf files remain valid +- **Security**: Profile data encrypted separately from core identity +- **Scalability**: No limits on profiles per node or total profiles +- **Flexibility**: Support multiple usernames on the same node + +## Updated Data Structures + +### Extended .spf File Format + +```rust +#[derive(Debug, Serialize, Deserialize)] +pub struct PassportProfileFile { + // Core passport data (existing) + pub enc_seed: Vec, + pub kdf: String, + pub cipher: String, + pub salt: Vec, + pub nonce: Vec, + pub public_key: Vec, + pub did: String, + pub created_at: u64, + pub version: String, + + // New profile system + pub profiles: Vec, + pub global_preferences: GlobalPreferences, + pub default_profile_id: Option, // UUID of default profile +} +``` + +### Profile Data Structures + +```rust +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct NodeProfile { + pub id: String, // UUID v4 + pub node_did: String, // Node's DID + pub network_id: String, // Network identifier + pub username: String, // Username granted on this node + pub display_name: Option, // Optional display name + pub avatar_url: Option, // Optional avatar URL + pub membership_vc: Option>, // Encrypted membership credential + pub status: ProfileStatus, // Active, suspended, etc. + pub created_at: u64, + pub last_used: u64, + pub preferences: NodePreferences, // Node-specific preferences + pub capabilities: Vec, // Capabilities supported by this node +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct GlobalPreferences { + pub default_visibility: VisibilityMode, + pub default_distribution: DistributionMode, + pub auto_backup: bool, + pub sync_across_devices: bool, + pub theme: ThemePreference, + pub language: String, + pub notification_settings: NotificationSettings, + pub security_settings: SecuritySettings, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct NodePreferences { + pub auto_accept_requests: bool, + pub default_card_ttl: Option, // Time-to-live in seconds + pub storage_quota: Option, // MB limit + pub notification_rules: Vec, + pub custom_fields: HashMap, // Node-specific custom preferences +} +``` + +### Updated Visibility and Distribution Modes + +```rust +#[derive(Debug, Clone, Serialize, Deserialize)] +pub enum VisibilityMode { + Public, + Direct, + Node, + Federation, // Was "trustset" + Group, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub enum DistributionMode { + Recipients, // Was "to_recipients_only" + Node, // Was "this_node_only" + Federation, // Was "trusted_nodes" + Public, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub enum ProfileStatus { + Active, + Suspended, + Revoked, + PendingVerification, +} +``` + +## Profile Management Architecture + +### Core Features + +1. **Multiple Profiles per Node**: Unlimited profiles on the same node with different usernames +2. **Profile Switching**: Dynamic switching between active profiles +3. **Profile Migration**: Seamless movement between devices +4. **Profile Backup/Restore**: Complete state backup and restoration +5. **Profile Templates**: Pre-configured templates for common use cases + +### Profile Operations + +- `create_profile()` - Create new profile for a node +- `switch_profile()` - Change active profile +- `update_profile()` - Modify profile preferences +- `delete_profile()` - Remove profile (soft delete) +- `export_profile()` - Export single profile +- `import_profile()` - Import profile from backup + +### Node Integration + +- Automatic profile discovery when joining nodes +- Profile synchronization across devices +- Conflict resolution for profile updates +- Graceful handling of node unavailability + +## Implementation Roadmap + +### Phase 1: Core Data Structures (Week 1-2) + +#### 1.1 Extend Domain Entities +**File**: `src/domain/entities.rs` +- Add `PassportProfileFile` struct +- Add profile-related enums and structs +- Update `Passport` to include profile management methods +- Implement updated visibility and distribution modes + +#### 1.2 Update Storage Layer +**File**: `src/infrastructure/storage.rs` +- Modify file format to support profiles +- Add migration path for existing .spf files +- Ensure backward compatibility +- Update file encryption to handle profile data + +### Phase 2: Profile Management (Week 3-4) + +#### 2.1 Add Profile Use Cases +**File**: `src/application/use_cases.rs` +- `CreateProfileUseCase` - Create new node profiles +- `SwitchProfileUseCase` - Change active profile +- `UpdateProfileUseCase` - Modify profile settings +- `ExportProfileUseCase` - Export individual profiles +- `ImportProfileUseCase` - Import profiles from backup + +#### 2.2 Update CLI Interface +**Files**: `src/cli/commands.rs`, `src/cli/interface.rs` +- Add profile management commands: + - `profile create` - Create new profile + - `profile list` - List all profiles + - `profile switch` - Change active profile + - `profile update` - Modify profile settings + - `profile export` - Export profile + - `profile import` - Import profile + +### Phase 3: Integration & Testing (Week 5-6) + +#### 3.1 Node Integration +- Profile discovery during node join process +- Automatic profile creation for new nodes +- Profile synchronization across devices +- Federation-aware profile distribution + +#### 3.2 Comprehensive Testing +- Unit tests for all new functionality +- Integration tests with mock nodes +- Migration tests for existing passports +- Federation distribution testing + +### Phase 4: Advanced Features (Week 7-8) + +#### 4.1 Security Enhancements +- Profile data encryption with separate keys +- Audit logging for profile changes +- Revocation support for compromised profiles +- Rate limiting on profile operations + +#### 4.2 User Experience +- Profile templates for common use cases +- Bulk profile operations +- Conflict resolution UI +- Enhanced profile visualization + +## File Structure Changes + +``` +src/ +├── domain/ +│ ├── entities.rs # Extended with profile structures +│ ├── profile_entities.rs # New: Profile-specific entities +│ └── traits.rs # Add profile management traits +├── application/ +│ ├── use_cases.rs # Extended with profile use cases +│ └── profile_use_cases.rs # New: Profile-specific use cases +└── infrastructure/ + ├── profile_storage.rs # New: Profile-specific storage logic + └── profile_crypto.rs # New: Profile encryption/decryption +``` + +## Migration Strategy + +### Backward Compatibility +- Existing .spf files automatically get empty profile arrays +- Old visibility/distribution modes mapped to new ones +- Migration utilities for bulk conversion + +### Gradual Migration +- Users can migrate profiles incrementally +- Export/import tools for format conversion +- Fallback support for minimal profile data + +### Data Migration Path +1. **Detection**: Identify existing .spf files without profiles +2. **Conversion**: Add empty profile arrays and default preferences +3. **Validation**: Ensure migrated files remain functional +4. **Cleanup**: Remove migration artifacts after successful conversion + +## Security Considerations + +### Data Protection +- Profile data encrypted with separate keys from seed +- Sensitive preferences stored encrypted +- Profile operations require authentication +- Audit trails for all profile modifications + +### Access Control +- Rate limiting on profile operations +- Session management for profile switching +- Revocation mechanisms for compromised profiles +- Secure profile backup/restore + +### Privacy +- Profile metadata minimization +- Encrypted profile synchronization +- Selective profile sharing +- Privacy-preserving profile discovery + +## API Changes + +### CLI Commands +```bash +# Profile Management +sharenet-passport profile create --node --username +sharenet-passport profile list +sharenet-passport profile switch +sharenet-passport profile update --setting value +sharenet-passport profile export --output file.spf +sharenet-passport profile import --input file.spf + +# Enhanced existing commands +sharenet-passport create --profiles-enabled +sharenet-passport info --show-profiles +``` + +### Programmatic API +```rust +// Profile management +passport.create_profile(node_did, username, preferences) +passport.switch_profile(profile_id) +passport.export_profile(profile_id) -> ProfileData +passport.import_profile(profile_data) + +// Profile querying +passport.list_profiles() -> Vec +passport.get_active_profile() -> Option +passport.find_profiles_by_node(node_did) -> Vec +``` + +## Testing Strategy + +### Unit Tests +- Profile creation and validation +- Profile switching and state management +- Profile encryption/decryption +- Migration path testing + +### Integration Tests +- Node profile discovery +- Profile synchronization +- Federation distribution +- Multi-device scenarios + +### Performance Testing +- Large profile sets +- Concurrent profile operations +- Memory usage with many profiles +- File I/O performance + +## Success Metrics + +- **Backward Compatibility**: 100% of existing .spf files remain functional +- **Performance**: <10ms overhead for profile operations +- **Security**: No sensitive profile data exposed in plaintext +- **Usability**: Intuitive profile management interface +- **Reliability**: Zero data loss during migration + +## Future Enhancements + +- **Profile Templates**: Pre-configured profile types +- **Profile Analytics**: Usage patterns and optimization +- **Advanced Federation**: Cross-federation profile sharing +- **Profile Recovery**: Enhanced backup and restore mechanisms +- **Profile Marketplace**: Community-shared profile templates + +--- + +This implementation plan provides a comprehensive roadmap for extending the Sharenet Passport system with robust profile management while maintaining the security, portability, and usability characteristics of the .spf file format. \ No newline at end of file