ente/rust/CLAUDE.md

CLAUDE.md

Commit & PR Guidelines

⚠️ CRITICAL: From the default template, use ONLY: Co-Authored-By: Claude noreply@anthropic.com ⚠️

Pre-commit/PR Checklist (RUN BEFORE EVERY COMMIT OR PR!)

CRITICAL: CI will fail if ANY of these checks fail. Run ALL commands and ensure they ALL pass.

# 1. Format code
cargo fmt

# 2. Check for clippy warnings (THIS MUST PASS - CI fails on any warning)
cargo clippy --all-targets --all-features -- -D warnings
# If this fails, fix the warnings manually (not all can be auto-fixed)

# 3. Build with warnings as errors (THIS MUST PASS - matches CI environment)
RUSTFLAGS="-D warnings" cargo build

# 4. Verify formatting is correct (THIS MUST PASS - CI checks this)
cargo fmt --check

Why CI might fail even after running these:

• Skipping any command above
• Assuming auto-fix tools handle everything (they don't)
• Not fixing warnings that clippy reports
• Making changes after running the checks

Commit & PR Message Rules

These rules apply to BOTH commit messages AND pull request descriptions

• Keep messages CONCISE (no walls of text)
• Subject line under 72 chars (no body text unless critical)
• NO emojis
• NO promotional text or links (except Co-Authored-By line)

Additional Guidelines

• Check git status before committing to avoid adding temporary/binary files
• Never commit to main branch
• All CI checks must pass - run the checklist commands above before committing or creating PR

Development Commands

Build and Test

# Format code (required before commits)
cargo fmt

# Run linter (must pass for CI)
cargo clippy --all-targets --all-features

# Build the project
cargo build

# Run in development
cargo run -- <command>

# Build release version
cargo build --release

CI Requirements

The codebase must pass the GitHub Actions workflow at ../.github/workflows/rust-lint.yml which runs:

1. cargo fmt --check - Code formatting check
2. cargo clippy --all-targets --all-features - Linting with all warnings as errors (RUSTFLAGS: -D warnings)
3. cargo build - Build verification

Important FFI Note: When working with libsodium FFI bindings, always use std::ffi::c_char for C char pointer casts (e.g., as *const std::ffi::c_char), NOT raw i8 casts. The CI environment may have different type expectations than local development.

Architecture Overview

CLI for ente.io with end-to-end encryption, multi-account and multi-app support.

Core Modules

api/ - HTTP client for ente.io API

• client.rs: Base HTTP client with auth token management
• auth.rs: SRP (Secure Remote Password) authentication implementation
• methods.rs: API method implementations (collections, files, user info)
• models.rs: API request/response data structures
• retry.rs: Retry logic with exponential backoff for rate limiting

crypto/ - Cryptographic operations using libsodium

• argon.rs: Argon2id key derivation
• chacha.rs: ChaCha20-Poly1305 encryption/decryption
• stream.rs: XChaCha20-Poly1305 streaming decryption for large files
• kdf.rs: Blake2b key derivation
• All crypto MUST use libsodium-sys-stable (statically linked)

storage/ - SQLite persistence layer

• schema.rs: Database schema for accounts, files, collections
• account.rs: Account CRUD operations with multi-app support
• sync.rs: Sync state management (last sync times, file tracking)
• config.rs: Key-value configuration store
• Uses rusqlite with bundled SQLite for portability

cli/ - Command-line argument parsing

• account.rs: Account command argument structures
• export.rs: Export command argument structures
• version.rs: Version information constants
• Uses clap for argument parsing

commands/ - Command implementation logic

• account.rs: Account management implementation (add, list, update, get-token)
• export.rs: Photo export orchestration with filtering support
• sync.rs: Synchronization logic execution

models/ - Data structures

• account.rs: Account model with encrypted credentials
• file.rs: File metadata and encryption info
• collection.rs: Albums/collections with sharing support
• metadata.rs: Decrypted file metadata (title, timestamps, location)
• filter.rs: Export filtering options (shared/hidden albums, emails)
• error.rs: Error types using thiserror

sync/ - Synchronization engine

• engine.rs: Core sync orchestration and state management
• files.rs: File synchronization logic
• download.rs: File download and decryption implementation

utils/ - Utility functions

• mod.rs: Config directory management with platform-specific defaults

Key Implementation Details

1. Authentication Flow: SRP-based authentication storing tokens in SQLite, supports multiple apps (photos, locker, auth)
2. Multi-Account Support: SQLite-based storage with per-account/per-app token management
3. File Organization: Export to export_dir/AlbumName/filename structure (files in "Uncategorized" if no album)
4. Export Filtering: Support for filtering by shared/hidden albums and specific user emails
5. Encryption: Files encrypted with ChaCha20-Poly1305, streaming decryption for large files, keys derived via Argon2/Blake2b
6. Async Runtime: Uses tokio with full features for concurrent operations
7. Error Handling: Propagate errors with ? operator, use anyhow for context
8. Configuration: Platform-specific config directories (Linux: ~/.config/ente-cli, macOS: ~/Library/Application Support/ente-cli, Windows: %APPDATA%/ente-cli)

Security Guidelines

NEVER commit sensitive information:

• No real email addresses, usernames, or account IDs in code or documentation
• No authentication tokens, API keys, or passwords (even for test accounts)
• No debug logs that output credentials, keys, or personal information
• Use generic examples like "user@example.com" in documentation
• Remove all log::debug! statements that print sensitive data before committing
• Avoid logging encrypted keys, nonces, or tokens even in encrypted form

Environment Variables

• ENTE_CLI_CONFIG_DIR: Override default config directory
• RUST_LOG: Set log level (debug, info, warn, error, trace)