Contributing

Code style

Formatting

Format all Rust code with rustfmt before committing:

cargo fmt

Lints

Address all Clippy warnings:

cargo clippy -- -D warnings

No speculative code

Follow the project’s simplicity-first rule: minimum code that solves the problem. No features beyond what was asked. No abstractions for single-use code. See CLAUDE.md at the root of the repository for the full rule set.

Running tests

cargo test

Tests are self-contained and do not require external services. GSSAPI and LDAP functionality is tested via integration tests that mock the underlying system calls.

Build checklist

Before submitting a change, verify:

cargo check         # no compile errors
cargo fmt --check   # no formatting drift
cargo clippy -- -D warnings  # no lint warnings
cd webui && npm run build    # TypeScript clean, SPA builds

Adding a new OAuth2 endpoint

1. Add the handler function to src/routes/oauth2.rs.
2. Register the route in oauth2::router().
3. Update the discovery documents in src/routes/discovery.rs if the endpoint is advertised in RFC 8414 or OIDC Discovery (add it to AuthorizationServerMetadata or OidcProviderMetadata).
4. Document the endpoint in RFC Support Reference.

Adding a new CRDT field

1. Add the field to IdpCrdt in src/crdt/mod.rs with the appropriate CRDT type.
2. Add persistence in load_from_db and persist_to_db.
3. Add a merge call in IdpCrdt::merge.
4. Add the corresponding database table(s) to migrations/{sqlite,postgres,mariadb}/.
5. Document the new table in Database.

Changing the AEAD key derivation

Any change to how wrapping_key or refresh_key is derived is a breaking change for existing tokens and sessions. All in-flight tokens signed or encrypted with the old keys will fail to decode. Plan a migration that:

1. Rotates the wrapping key in the CRDT.
2. Accepts tokens encrypted with either the old or new key during a transition window.

Dependency rules

Do not add ring, aws-lc-rs, jsonwebtoken, hmac, or sha2 as direct dependencies. The native-ossl + synta-certificate stack is the single cryptographic backend for the project.

Commit messages

Follow conventional commits: type(scope): short description. Types: feat, fix, refactor, docs, test, chore. Keep the subject line under 72 characters and use the imperative mood (“add”, “fix”, “remove”, not “added”, “fixed”, “removed”).