# Contributing to entropy-auth
Thank you for your interest in contributing! This document covers the essentials for getting started.
## Prerequisites
- **Rust 1.85+** (edition 2024; see `rust-version` in `Cargo.toml` for the definitive MSRV). Install via [rustup](https://rustup.rs/).
- **Git** for version control.
## Getting Started
```bash
git clone git@gitlab.com:entropysoftworks/crates/auth.git
cd auth
cargo test --all-features
```
## Development Workflow
### Running Tests
```bash
cargo test --all-features
```
### Linting
Clippy runs in pedantic mode with all warnings treated as errors:
```bash
cargo clippy --all-features --all-targets -- -D warnings -W clippy::pedantic
```
### Formatting
```bash
cargo fmt --check
```
### Documentation
```bash
RUSTDOCFLAGS="-D warnings" cargo doc --all-features --no-deps
```
Documentation builds must produce no warnings.
## Code Standards
- **`#![deny(unsafe_code)]`** in production code. `unsafe` is only permitted for `core::ptr::write_volatile` secret-scrubbing in `crypto/zeroize.rs`, `crypto/sha1.rs`, and `crypto/sha2.rs`, with scoped `#[allow(unsafe_code)]` and `// SAFETY:` comments. The CSPRNG uses `rand_core::OsRng` and adds no `unsafe`.
- **`deny(missing_docs)`** — every public item must have a doc comment.
- **`warn(clippy::pedantic)`** — pedantic lints are enforced.
- **Minimal, audited dependencies** — runtime dependencies are limited to the audited set declared in `Cargo.toml` (always-on: `argon2`, `tracing`, `aes-gcm`, `rand_core`, `webauthn-rs`, `serde`, `serde_json`; behind `asym-jwt`: `ed25519-dalek`, `p256`, `rsa`, `sha2`). Hash, MAC, and encoding primitives are self-implemented on `std`. Adding any new runtime dependency requires explicit discussion and approval, and it must pass `cargo deny`.
- All public types must be `Send + Sync` where possible. Compile-time assertions in `lib.rs` enforce this.
- Error types must implement `std::error::Error`, `Debug`, `Clone`, `Display`.
## Crypto Implementation Rules
- **Every crypto implementation must be tested against published test vectors.** No exceptions.
- SHA-1/SHA-256/SHA-512: NIST CAVP vectors.
- HMAC: RFC 4231 vectors.
- Memory-hard and asymmetric primitives (Argon2id, AES-GCM, WebAuthn, the
asymmetric JWT algorithms) are delegated to audited crates rather than
hand-rolled; tests cover this crate's wiring around them.
- All new crypto code requires a security review before merge.
## Security Review Checklist
Before submitting a PR that touches security-sensitive code:
- [ ] No secret material in error messages, `Debug` output, or log calls.
- [ ] All types holding secrets implement `Drop` with zeroization.
- [ ] All secret comparisons use `constant_time_eq`.
- [ ] Input length limits enforced on all public functions.
- [ ] Null bytes rejected in validated identifier inputs (`util::validation`).
- [ ] Known-answer tests pass for all crypto.
## Architecture Notes
- **crypto/ and encoding/ are the foundation** — no upward dependencies.
- Single responsibility per module — one concept per file.
- Comments explain *why*, not *what*.
- `SECURITY:` prefixed comments for security-relevant decisions.
- `NOTE:` prefixed comments for non-obvious behavior.
### `#[non_exhaustive]` enums and match exhaustiveness
Enums marked `#[non_exhaustive]` use exhaustive matching internally (no
wildcard `_` arm). This forces every `match` site to be updated when a
variant is added.
## Commit Messages
Write concise commit messages that focus on _why_ rather than _what_. Use present tense ("add feature" not "added feature").
## Pull/Merge Requests
1. Create a feature branch from `main`.
2. Ensure all checks pass: tests, clippy, rustfmt, and doc build.
3. Open an MR targeting `main`.
4. CI runs automatically on merge request events.
## License
By contributing, you agree that your contributions will be licensed under the MIT License.