Contributing to Auth Framework

Thank you for your interest in contributing to the Auth Framework project! This guide will help you get started with making contributions.

Code of Conduct

This project adheres to the Rust Code of Conduct. By participating, you are expected to uphold this code.

How to Contribute

Reporting Bugs

Before creating bug reports, please check the issue tracker to see if the problem has already been reported. When creating a bug report, include:

A clear, descriptive title
Steps to reproduce the issue
Expected vs actual behavior
Environment information (Rust version, OS, etc.)
Relevant code snippets or error messages

Suggesting Enhancements

Enhancement suggestions are welcome! When proposing an enhancement:

Use a clear, descriptive title
Provide detailed description of the enhancement
Explain why this enhancement would be useful
Include code examples if applicable

Pull Requests

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Ensure all tests pass (cargo test)
Add tests for new functionality
Update documentation as needed
Run cargo fmt to format your code
Run cargo clippy to check for linting issues
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Setup

Prerequisites

Rust 1.85+ (stable, edition 2024)
Git

Local Development

Clone the repository:

git clone https://github.com/ciresnave/auth-framework.git
cd auth-framework

Install dependencies:
```
cargo build
```
Run tests:
```
cargo test
```

Run examples:

cargo run --example complete_rest_api_server --features api-server

Project Structure

auth-framework/
├── src/
│   ├── lib.rs               # Library entry point and module declarations
│   ├── auth.rs              # Core authentication framework
│   ├── auth_operations.rs   # High-level auth operation wrappers
│   ├── config.rs            # Configuration management
│   ├── credentials.rs       # Credential types and handling
│   ├── errors.rs            # Error types and handling
│   ├── storage.rs           # Storage backend trait and implementations
│   ├── tokens.rs            # Token management
│   ├── client.rs            # OAuth/OIDC client
│   ├── api/                 # REST API endpoints (auth, MFA, users, etc.)
│   ├── server/              # OAuth2/OIDC/SAML server implementations
│   │   ├── oauth/           # OAuth 2.0 server (device flow, PAR, DPoP, etc.)
│   │   └── oidc/            # OpenID Connect (CIBA, JARM, backchannel logout)
│   ├── protocols/           # Protocol implementations
│   │   ├── kerberos.rs      # Kerberos 5 with SPNEGO and AES-CTS
│   │   ├── gnap.rs          # GNAP (Grant Negotiation and Authorization)
│   │   ├── radius.rs        # RADIUS authentication
│   │   ├── openid4vp.rs     # OpenID for Verifiable Presentations
│   │   ├── uma.rs           # UMA 2.0 (User-Managed Access)
│   │   ├── cas.rs           # Central Authentication Service
│   │   ├── scim.rs          # SCIM 2.0 provisioning
│   │   └── ws_*.rs          # WS-Federation, WS-Trust, WS-Security
│   ├── admin/               # Admin interfaces (CLI, TUI, Web GUI)
│   ├── auth_modular/        # Modular authentication architecture
│   ├── security/            # Crypto, JWT validation, secure operations
│   ├── session/             # Session management with geo-IP
│   ├── methods/             # Auth methods (passkeys, MFA, hardware tokens)
│   └── distributed/        # Distributed rate limiting
├── tests/                   # Integration tests
├── examples/                # Example applications
├── docs/                    # Documentation (guides, API, architecture)
├── ffi/                     # FFI bindings for multi-language support
├── sdks/                    # Language SDKs (Python, JavaScript)
├── docker/                  # Docker configurations
├── k8s/                     # Kubernetes manifests
└── migration/               # Database migration tools

Testing

Running Tests

# Run all tests
cargo test

# Run specific test
cargo test test_name

# Run tests with output
cargo test -- --nocapture

# Run doc tests
cargo test --doc

Test Coverage

We aim for comprehensive test coverage. When adding new features:

Add unit tests for new functions
Add integration tests for new features
Test error conditions
Test edge cases

Writing Tests

#[cfg(test)]
mod tests {
    use super::*;
    use tokio_test;

    #[tokio::test]
    async fn test_feature() {
        // Test implementation
    }
}

Documentation

Code Documentation

Use /// for public API documentation
Use //! for module-level documentation
Include examples in documentation when helpful
Document error conditions and panics

README Updates

When making changes that affect the public API:

Update the README.md with new examples
Update the feature list if applicable
Update configuration examples

Coding Standards

Style Guide

Follow Rust naming conventions
Use cargo fmt for consistent formatting
Run cargo clippy and address warnings
Keep functions focused and reasonably sized
Use meaningful variable and function names

Error Handling

Use the Result type for fallible operations
Create specific error types for different failure modes
Provide helpful error messages
Don't panic in library code (except for invariant violations)

Performance Considerations

Profile performance-critical code
Use appropriate data structures
Consider memory allocations in hot paths
Add benchmarks for performance-sensitive features

Security Considerations

This is a security-focused library. When contributing:

Follow secure coding practices
Consider timing attacks and side-channel vulnerabilities
Use constant-time operations for sensitive comparisons
Validate all inputs
Don't log sensitive information
Use secure defaults

Release Process

Update version in Cargo.toml
Update CHANGELOG.md
Create release commit
Tag the release
Push to main repository
Create GitHub release
Publish to crates.io

Getting Help

Check the documentation
Look at existing code for patterns
Ask questions in issues or discussions
Reach out to maintainers if needed

Recognition

Contributors will be recognized in the project's README and changelog.

Thank you for contributing to Auth Framework!

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History