Contributing to Opake#

Contributions welcome — from humans and AI agents alike.

Getting started#

1. Clone the repo
2. Install Rust 1.75+ via rustup
3. Run the test suite: cargo test
4. Run the linter: cargo clippy -- -D warnings
5. For web frontend work: install Bun, then cd web && bun install

Code style#

• cargo fmt before every commit (enforced by CI and pre-commit hook)
• cargo clippy -- -D warnings must pass
• No unwrap() in library code — use ? and proper error types
• opake-core uses thiserror for typed errors; opake-cli and opake-appview use anyhow for application errors
• Prefer &str parameters, String for owned data
• Avoid .clone() unless necessary

Architecture#

opake-core      platform-agnostic library (compiles to WASM)
                - encryption/decryption (AES-256-GCM, x25519 key wrapping)
                - XRPC client with automatic token refresh
                - document operations (upload, download, list, delete, resolve)
                - device pairing (ephemeral DH key exchange, identity transfer)
                - AT Protocol record types and lexicon constants
                - Storage trait + config/identity/session types (storage.rs)
                - shared config path resolution (paths.rs)

opake-cli       CLI binary wrapping opake-core
                - clap command definitions
                - FileStorage (impl Storage over filesystem, TOML + JSON)
                - user interaction (prompts, formatting)

opake-appview   indexer + REST API for grant/keyring discovery
                - Jetstream firehose consumer
                - SQLite storage (WAL mode)
                - Axum API with DID-scoped Ed25519 auth
                - rate limiting via tower_governor

opake-derive    proc-macro crate
                - #[derive(RedactedDebug)] with #[redact] field attribute
                - generates Debug impls showing byte length instead of content
                - used by opake-core (ContentKey, Session) and opake-cli (Identity)

web/            React SPA (Vite + TanStack Router + Tailwind/daisyUI)
                - opake-core via WASM (wasm-pack build)
                - IndexedDbStorage (impl Storage over Dexie.js/IndexedDB)
                - Zustand stores, Web Worker for off-main-thread crypto
                - cabinet file browser UI with panel navigation

opake-core must never depend on filesystem, stdin, or any platform-specific API. All I/O goes through the Storage trait — FileStorage (CLI) and IndexedDbStorage (web) are the platform-specific implementations.

See docs/ARCHITECTURE.md for the detailed crate structure and encryption model, and docs/FLOWS.md for sequence diagrams of every operation.

Testing#

• Small test suites live inline in #[cfg(test)] modules. Larger test suites are extracted to sibling *_tests.rs files using #[cfg(test)] #[path = "..._tests.rs"] mod tests; — keeps implementation files focused
• Test contracts, not implementations — assert on inputs and outputs
• Name regression tests after the bug: bug__float_not_rounding_correctly
• Use MockTransport (from opake-core/src/test_utils.rs) for XRPC tests — enqueue responses, assert on captured requests
• Shared test fixtures live in documents/mod.rs (mock_client, dummy_document, etc.)
• The test-utils feature flag gates test infrastructure in opake-core

cargo test                          # all Rust tests
cargo test -p opake-core            # core only
cargo test -p opake-cli             # CLI only
cargo test -p opake-appview         # appview only
cargo test -- --test-output         # show println output

cd web && bun run test              # web frontend tests (Vitest + fake-indexeddb)

Commit messages#

• Imperative mood ("Add feature", not "Added feature")
• First line under 72 characters
• Body explains the why, not the what

AI agents#

AI-assisted contributions are welcome. No special rules beyond:

• Code must be indistinguishable from hand-written. No // Generated by comments, no boilerplate disclaimers.
• No Co-Authored-By trailers unless the human contributor requests it.
• Same quality bar as any other contribution — tests, clippy, formatting.

Pull requests#

• Keep PRs focused. One logical change per PR.
• All CI checks must pass (fmt, clippy, test).
• Describe what changed and why in the PR body.

Project management#

This project uses crosslink for issue tracking and AI agent workflow. After cloning, run crosslink init to set up hooks and the local issue database. The rule files in .crosslink/rules/ have been trimmed from crosslink's defaults — Rust-specific rules are deferred to cargo clippy and the project's CLAUDE.md.