mirror of
https://github.com/CloudNebulaProject/barycenter.git
synced 2026-04-10 13:10:42 +00:00
docs: add README and contributing guidelines
Add comprehensive project documentation including: - README.md with project overview, features, and quick start guide - CONTRIBUTING.md with Conventional Commits and Gitflow workflow The contributing guide establishes development standards: - Gitflow branching model (main, develop, feature/*, release/*, hotfix/*) - Conventional Commits specification for commit messages - Pull request process and code style guidelines 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Till Wegmueller
parent
64b31e40df
commit
1a8f8f000f
2 changed files with 411 additions and 0 deletions
253
CONTRIBUTING.md
Normal file
253
CONTRIBUTING.md
Normal file
|
|
@ -0,0 +1,253 @@
|
|||
# Contributing to Barycenter
|
||||
|
||||
Thank you for your interest in contributing to Barycenter! This document provides guidelines and instructions for contributing to the project.
|
||||
|
||||
## Code of Conduct
|
||||
|
||||
Be respectful, inclusive, and collaborative. We're here to build great software together.
|
||||
|
||||
## Development Workflow
|
||||
|
||||
We use **Gitflow** as our branching model. Please familiarize yourself with this workflow before contributing.
|
||||
|
||||
### Branch Structure
|
||||
|
||||
#### Main Branches
|
||||
|
||||
- `main` - Production-ready code. Only release and hotfix branches merge here.
|
||||
- `develop` - Integration branch for features. Default branch for development.
|
||||
|
||||
#### Supporting Branches
|
||||
|
||||
- `feature/*` - New features and non-emergency bug fixes
|
||||
- `release/*` - Release preparation (version bumps, final testing)
|
||||
- `hotfix/*` - Emergency fixes for production issues
|
||||
|
||||
### Workflow Steps
|
||||
|
||||
#### Working on a New Feature
|
||||
|
||||
1. **Create a feature branch from `develop`:**
|
||||
```bash
|
||||
git checkout develop
|
||||
git pull origin develop
|
||||
git checkout -b feature/your-feature-name
|
||||
```
|
||||
|
||||
2. **Make your changes** following our commit conventions (see below)
|
||||
|
||||
3. **Push your branch:**
|
||||
```bash
|
||||
git push -u origin feature/your-feature-name
|
||||
```
|
||||
|
||||
4. **Create a Pull Request** targeting `develop`
|
||||
|
||||
#### Creating a Release
|
||||
|
||||
1. **Create a release branch from `develop`:**
|
||||
```bash
|
||||
git checkout develop
|
||||
git pull origin develop
|
||||
git checkout -b release/v1.2.0
|
||||
```
|
||||
|
||||
2. **Update version numbers** and finalize changelog
|
||||
|
||||
3. **Create PR to `main`** and after merge, tag the release:
|
||||
```bash
|
||||
git tag -a v1.2.0 -m "Release version 1.2.0"
|
||||
git push origin v1.2.0
|
||||
```
|
||||
|
||||
4. **Merge back to `develop`** to include any release changes
|
||||
|
||||
#### Hotfix Process
|
||||
|
||||
1. **Create a hotfix branch from `main`:**
|
||||
```bash
|
||||
git checkout main
|
||||
git pull origin main
|
||||
git checkout -b hotfix/v1.2.1
|
||||
```
|
||||
|
||||
2. **Fix the issue** and update version number
|
||||
|
||||
3. **Create PR to `main`** and after merge, tag the hotfix
|
||||
|
||||
4. **Merge back to `develop`** to include the fix
|
||||
|
||||
## Commit Message Convention
|
||||
|
||||
We follow **Conventional Commits** specification. This leads to more readable commit history and enables automated changelog generation.
|
||||
|
||||
### Commit Message Format
|
||||
|
||||
```
|
||||
<type>(<scope>): <subject>
|
||||
|
||||
<body>
|
||||
|
||||
<footer>
|
||||
```
|
||||
|
||||
#### Type
|
||||
|
||||
Must be one of the following:
|
||||
|
||||
- `feat` - A new feature
|
||||
- `fix` - A bug fix
|
||||
- `docs` - Documentation only changes
|
||||
- `style` - Changes that don't affect code meaning (formatting, whitespace)
|
||||
- `refactor` - Code change that neither fixes a bug nor adds a feature
|
||||
- `perf` - Performance improvement
|
||||
- `test` - Adding or updating tests
|
||||
- `build` - Changes to build system or dependencies
|
||||
- `ci` - Changes to CI configuration files and scripts
|
||||
- `chore` - Other changes that don't modify src or test files
|
||||
- `revert` - Reverts a previous commit
|
||||
|
||||
#### Scope (Optional)
|
||||
|
||||
The scope should specify the place of the commit change:
|
||||
|
||||
- `auth` - Authentication/authorization
|
||||
- `token` - Token endpoint and generation
|
||||
- `jwks` - Key management and JWKS
|
||||
- `storage` - Database and storage layer
|
||||
- `config` - Configuration management
|
||||
- `web` - Web server and routing
|
||||
- `oidc` - OpenID Connect specific features
|
||||
- `oauth` - OAuth 2.0 specific features
|
||||
|
||||
#### Subject
|
||||
|
||||
- Use imperative, present tense: "add" not "added" nor "adds"
|
||||
- Don't capitalize first letter
|
||||
- No period (.) at the end
|
||||
- Maximum 50 characters
|
||||
|
||||
#### Body (Optional)
|
||||
|
||||
- Explain **what** and **why** (not how)
|
||||
- Wrap at 72 characters
|
||||
- Separate from subject with a blank line
|
||||
|
||||
#### Footer (Optional)
|
||||
|
||||
- Reference issues: `Closes #123` or `Fixes #456`
|
||||
- Note breaking changes: `BREAKING CHANGE: description`
|
||||
|
||||
### Examples
|
||||
|
||||
#### Simple Feature
|
||||
```
|
||||
feat(auth): add PKCE S256 support
|
||||
|
||||
Implements code_challenge and code_verifier validation
|
||||
according to RFC 7636.
|
||||
|
||||
Closes #42
|
||||
```
|
||||
|
||||
#### Bug Fix
|
||||
```
|
||||
fix(token): validate token expiration correctly
|
||||
|
||||
Token validation was not properly checking the exp claim
|
||||
against current time, allowing expired tokens to be used.
|
||||
```
|
||||
|
||||
#### Breaking Change
|
||||
```
|
||||
feat(config)!: change database configuration format
|
||||
|
||||
BREAKING CHANGE: Database connection string now requires
|
||||
explicit mode parameter. Update config.toml:
|
||||
|
||||
Old: connection_string = "sqlite://db.sqlite"
|
||||
New: connection_string = "sqlite://db.sqlite?mode=rwc"
|
||||
```
|
||||
|
||||
#### Documentation
|
||||
```
|
||||
docs: update README with configuration examples
|
||||
```
|
||||
|
||||
#### Multiple Changes
|
||||
```
|
||||
refactor(storage): simplify client lookup logic
|
||||
|
||||
- Remove redundant database queries
|
||||
- Add connection pooling
|
||||
- Improve error messages
|
||||
|
||||
Related to #78
|
||||
```
|
||||
|
||||
## Pull Request Process
|
||||
|
||||
1. **Update documentation** if you're changing functionality
|
||||
2. **Add tests** for new features or bug fixes
|
||||
3. **Ensure all tests pass**: `cargo test`
|
||||
4. **Ensure code compiles**: `cargo check`
|
||||
5. **Format your code**: `cargo fmt`
|
||||
6. **Run clippy**: `cargo clippy`
|
||||
7. **Update CHANGELOG.md** if applicable
|
||||
8. **Reference related issues** in the PR description
|
||||
9. **Request review** from maintainers
|
||||
|
||||
### PR Title
|
||||
|
||||
PR titles should also follow Conventional Commits format:
|
||||
|
||||
```
|
||||
feat(auth): implement social login providers
|
||||
fix(token): correct ID token expiration handling
|
||||
docs: update API endpoint documentation
|
||||
```
|
||||
|
||||
## Code Style
|
||||
|
||||
- Follow Rust standard style guidelines
|
||||
- Run `cargo fmt` before committing
|
||||
- Address `cargo clippy` warnings
|
||||
- Use meaningful variable and function names
|
||||
- Add comments for complex logic
|
||||
- Keep functions focused and small
|
||||
|
||||
## Testing
|
||||
|
||||
- Write unit tests for new functions
|
||||
- Add integration tests for new endpoints
|
||||
- Test both success and error cases
|
||||
- Aim for meaningful test coverage
|
||||
|
||||
```bash
|
||||
# Run all tests
|
||||
cargo test
|
||||
|
||||
# Run specific test
|
||||
cargo test test_name
|
||||
|
||||
# Run with output
|
||||
cargo test -- --nocapture
|
||||
```
|
||||
|
||||
## Documentation
|
||||
|
||||
- Update `CLAUDE.md` for significant architectural changes
|
||||
- Document all public APIs
|
||||
- Include examples in documentation
|
||||
- Update README.md for user-facing changes
|
||||
|
||||
## Questions or Problems?
|
||||
|
||||
- Open an issue for bugs or feature requests
|
||||
- Tag issues appropriately (`bug`, `enhancement`, `question`)
|
||||
- Provide detailed reproduction steps for bugs
|
||||
- Search existing issues before creating new ones
|
||||
|
||||
## License
|
||||
|
||||
By contributing, you agree that your contributions will be licensed under the same license as the project.
|
||||
158
README.md
Normal file
158
README.md
Normal file
|
|
@ -0,0 +1,158 @@
|
|||
# Barycenter
|
||||
|
||||
An OpenID Connect Identity Provider (IdP) implementing OAuth 2.0 Authorization Code flow with PKCE.
|
||||
|
||||
## Overview
|
||||
|
||||
Barycenter is a lightweight, standards-compliant OpenID Connect Identity Provider written in Rust. It implements the OAuth 2.0 Authorization Code flow with Proof Key for Code Exchange (PKCE), making it suitable for modern web and mobile applications.
|
||||
|
||||
## Features
|
||||
|
||||
- **OAuth 2.0 Authorization Code Flow** with PKCE (S256)
|
||||
- **Dynamic Client Registration** - RFC 7591 compliant
|
||||
- **Token Endpoint** - Multiple authentication methods (client_secret_basic, client_secret_post)
|
||||
- **ID Token Signing** - RS256 with proper at_hash and nonce support
|
||||
- **UserInfo Endpoint** - Bearer token authentication
|
||||
- **Discovery** - OpenID Connect Discovery and JWKS publication
|
||||
- **Property Storage** - Simple key-value storage for user properties
|
||||
|
||||
## Technology Stack
|
||||
|
||||
- **Language**: Rust
|
||||
- **Web Framework**: [axum](https://github.com/tokio-rs/axum)
|
||||
- **Database**: SQLite via [SeaORM](https://www.sea-ql.org/SeaORM/)
|
||||
- **Cryptography**: [josekit](https://github.com/hidekatsu-izuno/josekit-rs) for JOSE/JWT operations
|
||||
- **Configuration**: [config-rs](https://github.com/mehcode/config-rs) with TOML support
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Rust 1.70 or later
|
||||
- SQLite 3
|
||||
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/CloudNebulaProject/barycenter.git
|
||||
cd barycenter
|
||||
|
||||
# Build the project
|
||||
cargo build --release
|
||||
```
|
||||
|
||||
### Configuration
|
||||
|
||||
Create a `config.toml` file (see `config.toml` for example):
|
||||
|
||||
```toml
|
||||
[server]
|
||||
host = "127.0.0.1"
|
||||
port = 8080
|
||||
public_base_url = "http://localhost:8080"
|
||||
|
||||
[database]
|
||||
connection_string = "sqlite://crabidp.db?mode=rwc"
|
||||
|
||||
[keys]
|
||||
jwks_path = "data/jwks.json"
|
||||
private_key_path = "data/private_key.pem"
|
||||
signing_algorithm = "RS256"
|
||||
```
|
||||
|
||||
### Running
|
||||
|
||||
```bash
|
||||
# Run with default config
|
||||
cargo run
|
||||
|
||||
# Run with custom config
|
||||
cargo run -- --config path/to/config.toml
|
||||
|
||||
# Run with debug logging
|
||||
RUST_LOG=debug cargo run
|
||||
```
|
||||
|
||||
## Development
|
||||
|
||||
### Building
|
||||
|
||||
```bash
|
||||
# Debug build
|
||||
cargo build
|
||||
|
||||
# Release build
|
||||
cargo build --release
|
||||
|
||||
# Check without building
|
||||
cargo check
|
||||
```
|
||||
|
||||
### Testing
|
||||
|
||||
```bash
|
||||
# Run all tests
|
||||
cargo test
|
||||
|
||||
# Run tests with logging
|
||||
RUST_LOG=debug cargo test
|
||||
```
|
||||
|
||||
### Logging
|
||||
|
||||
Set the `RUST_LOG` environment variable to control logging levels:
|
||||
|
||||
```bash
|
||||
# Debug level for all modules
|
||||
RUST_LOG=debug cargo run
|
||||
|
||||
# Trace level for barycenter only
|
||||
RUST_LOG=barycenter=trace cargo run
|
||||
```
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### Discovery
|
||||
- `GET /.well-known/openid-configuration` - OpenID Provider metadata
|
||||
- `GET /.well-known/jwks.json` - Public signing keys
|
||||
|
||||
### OAuth/OIDC
|
||||
- `GET /authorize` - Authorization endpoint
|
||||
- `POST /token` - Token endpoint
|
||||
- `GET /userinfo` - UserInfo endpoint
|
||||
- `POST /connect/register` - Dynamic client registration
|
||||
|
||||
### Properties (Non-standard)
|
||||
- `GET /properties/:owner/:key` - Get property value
|
||||
- `PUT /properties/:owner/:key` - Set property value
|
||||
|
||||
## Project Status
|
||||
|
||||
This is an early-stage implementation. See `docs/next-iteration-plan.md` for planned features and `docs/oidc-conformance.md` for OpenID Connect compliance details.
|
||||
|
||||
**Currently Implemented:**
|
||||
- Authorization Code flow with PKCE (S256)
|
||||
- Dynamic client registration
|
||||
- Token issuance and validation
|
||||
- ID Token generation with RS256 signing
|
||||
- UserInfo endpoint
|
||||
|
||||
**Pending Implementation:**
|
||||
- User authentication and session management
|
||||
- Consent flow
|
||||
- Refresh tokens
|
||||
- Token revocation and introspection
|
||||
- OpenID Federation support
|
||||
|
||||
## Contributing
|
||||
|
||||
Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct, development workflow, and the process for submitting pull requests.
|
||||
|
||||
## License
|
||||
|
||||
[Add your license here]
|
||||
|
||||
## Acknowledgments
|
||||
|
||||
Built with support from the OpenID Connect and OAuth 2.0 communities.
|
||||
Loading…
Add table
Reference in a new issue