🔒 Security & Encryption

use fula_crypto::{
    // Key management
    KekKeyPair, DekKey, KeyManager,
    // Sharing primitives
    ShareBuilder, ShareRecipient, SharePermissions, ShareMode, SnapshotBinding,
    // Inbox for async/offline sharing
    ShareEnvelopeBuilder, ShareInbox,
    // Secret links
    SecretLinkBuilder, SecretLink,
};

// ══════════════════════════════════════════════════════════════════════════════
// SETUP: Alice and Bob each have their own key pairs
// ══════════════════════════════════════════════════════════════════════════════

// Alice (owner) creates her identity
let alice_keypair = KekKeyPair::generate();
let alice_public_key = alice_keypair.public_key().clone();

// Bob (recipient) creates his identity
let bob_keypair = KekKeyPair::generate();
let bob_public_key = bob_keypair.public_key().clone();

// Alice has encrypted files with a DEK for her /photos/ folder
let photos_dek = DekKey::generate();

// ══════════════════════════════════════════════════════════════════════════════
// OPTION 1: Direct Share (synchronous - both online)
// ══════════════════════════════════════════════════════════════════════════════

// Alice creates a share token for Bob
let share_token = ShareBuilder::new(
    &alice_keypair,           // Alice's keypair (for future signing)
    &bob_public_key,          // Bob's public key (DEK encrypted for him)
    &photos_dek,              // The DEK that decrypts the files
)
    .path_scope("/photos/vacation/")  // Bob can only access this folder
    .expires_in(7 * 24 * 3600)        // Expires in 1 week
    .read_only()                       // Bob cannot modify files
    .build()?;

// Alice sends share_token to Bob (via any channel - encrypted for Bob only)
// The token contains: wrapped DEK, path scope, expiry, permissions

// Bob receives and accepts the share
let bob_handler = ShareRecipient::new(&bob_keypair);
let access = bob_handler.accept_share(&share_token)?;

// Bob can now decrypt files in /photos/vacation/
assert!(access.is_path_allowed("/photos/vacation/beach.jpg"));  // ✓ allowed
assert!(!access.is_path_allowed("/photos/family/"));             // ✗ denied
assert!(access.can_read);                                        // ✓ read access
assert!(!access.can_write);                                      // ✗ no write

// Bob uses access.dek to decrypt file content:
// let plaintext = aead.decrypt(&nonce, &ciphertext)?;

// ══════════════════════════════════════════════════════════════════════════════
// OPTION 2: Secret Link (shareable URL with key in fragment)
// ══════════════════════════════════════════════════════════════════════════════

// Alice creates a secret link she can send via email/chat
let secret_link = SecretLinkBuilder::new(&share_token, "https://gateway.functionland.io")
    .label("Hawaii Trip 2024")
    .build()?;

let url = secret_link.to_url()?;
// => "https://gateway.functionland.io/fula/share/abc123#eyJ2ZXJzaW9uIjoxLC..."
//    Server sees: /fula/share/abc123 (opaque ID)
//    Client sees: #... fragment with encrypted token

// Bob opens the link in his browser/app
let parsed_link = SecretLink::parse(&url)?;
let extracted_token = parsed_link.extract_token();

// Bob accepts and uses it as above
let access = bob_handler.accept_share(&extracted_token)?;

// ══════════════════════════════════════════════════════════════════════════════
// OPTION 3: Async Inbox (offline sharing - Bob picks up later)
// ══════════════════════════════════════════════════════════════════════════════

// Alice creates a share envelope with rich metadata
let (envelope, inbox_entry) = ShareEnvelopeBuilder::new(
    &alice_keypair,
    &bob_public_key,
    &photos_dek,
)
    .path_scope("/photos/vacation/")
    .expires_in(7 * 24 * 3600)
    .read_only()
    .label("Hawaii Trip 2024")                    // Human-readable label
    .message("Hey Bob, check out these pics!")    // Personal message
    .sharer_name("Alice")                         // Sharer display name
    .metadata("album", "vacation-2024")           // Custom metadata
    .build()?;

// Alice stores the inbox entry for Bob (via PrivateForest)
let inbox_path = ShareInbox::entry_storage_path(&bob_public_key, &inbox_entry.id);
// => "/.fula/inbox/<bob-key-hash>/<entry-id>.share"

// Later: Bob comes online and checks his inbox
let mut bob_inbox = ShareInbox::new();

// Bob loads entries from storage
bob_inbox.add_entry(inbox_entry);

// Bob lists pending shares
let pending = bob_inbox.list_pending(&bob_keypair);
println!("You have {} new shares", pending.len());  // "You have 1 new shares"

// Bob accepts Alice's share
let entry_id = pending[0].id.clone();
let accepted_envelope = bob_inbox.accept_entry(&entry_id, &bob_keypair)?;

println!("From: {:?}", accepted_envelope.sharer_name);    // "Alice"
println!("Message: {:?}", accepted_envelope.message);     // "Hey Bob, check out..."
println!("Path: {}", accepted_envelope.token.path_scope); // "/photos/vacation/"

// Bob uses the ShareToken from the envelope
let access = bob_handler.accept_share(&accepted_envelope.token)?;

// ══════════════════════════════════════════════════════════════════════════════
// OPTION 4: Snapshot Share (immutable version only)
// ══════════════════════════════════════════════════════════════════════════════

// Alice wants to share a specific report version that won't change
let report_hash = "abc123def456...";  // BLAKE3 hash of file content
let report_size = 1024;               // File size in bytes
let report_modified = 1699876543;     // Modification timestamp

let snapshot_share = ShareBuilder::new(&alice_keypair, &bob_public_key, &photos_dek)
    .path_scope("/documents/report.pdf")
    .snapshot_with(report_hash, report_size, report_modified)  // Bind to version
    .read_only()
    .build()?;

// Later: Bob tries to access the file
let current_hash = "abc123def456...";  // Current file hash
if snapshot_share.is_snapshot_valid(current_hash) {
    // File hasn't changed, access granted
    let access = bob_handler.accept_share(&snapshot_share)?;
} else {
    // File was modified, snapshot share is no longer valid
    println!("The shared file has been modified since the share was created");
}

// ══════════════════════════════════════════════════════════════════════════════
// SUMMARY: Who Controls What
// ══════════════════════════════════════════════════════════════════════════════
//
// ALICE (Application/Owner) decides:
//   - WHO to share with (Bob's public key)
//   - WHAT to share (path scope)
//   - HOW LONG (expiry)
//   - WHAT PERMISSIONS (read/write/delete)
//   - WHAT MODE (temporal vs snapshot)
//
// FULA PROTOCOL handles:
//   - HPKE encryption of DEK so only Bob can decrypt
//   - Unique share ID generation
//   - Expiry validation
//   - Path scope enforcement
//   - Snapshot binding verification
//   - Inbox entry encryption
//   - Secret link key isolation (fragment never sent to server)