# Gondulf IndieAuth Server

A self-hosted IndieAuth server implementation following the W3C IndieAuth specification. IndieAuth enables users to use their own domain as their identity when signing into third-party applications.

## Features

- Full W3C IndieAuth specification compliance
- Client self-registration capability
- Built on OAuth 2.0 with PKCE support
- Simple, maintainable codebase
- Single administrator model

## Requirements

- Python 3.10 or higher
- SQLite 3.35 or higher
- uv (for environment management)

## Installation

### 1. Install uv

**Linux/macOS:**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

**Using pip:**
```bash
pip install uv
```

Verify installation:
```bash
uv --version
```

### 2. Clone the Repository

```bash
git clone <repository-url> gondulf
cd gondulf
```

### 3. Set Up Development Environment

```bash
# Create virtual environment
uv venv

# Install the project in development mode with all dependencies
uv pip install -e ".[dev,test]"
```

## Usage

### Running the Development Server

```bash
uv run uvicorn src.gondulf.main:app --reload --host 127.0.0.1 --port 8000
```

The server will be available at `http://127.0.0.1:8000`

### Running Tests

```bash
# Run all tests
uv run pytest

# Run with coverage report
uv run pytest --cov=src/gondulf --cov-report=term-missing

# Run specific test categories
uv run pytest -m unit
uv run pytest -m integration
uv run pytest -m e2e
```

### Code Quality Checks

```bash
# Linting
uv run ruff check .

# Type checking
uv run mypy src/gondulf

# Format code
uv run ruff format .

# Security scanning
uv run bandit -r src/gondulf
```

## Development Workflow

All commands use `uv run` to execute within the project's virtual environment - no activation required.

**Common commands:**
- `uv run python script.py` - Run a Python script
- `uv run pytest` - Run tests
- `uv run ruff check .` - Lint code
- `uv pip install package` - Add a dependency
- `uv pip list` - List installed packages

See `/docs/standards/development-environment.md` for detailed development environment documentation.

## Project Structure

```
gondulf/
├── src/
│   └── gondulf/          # Main application code
│       └── __init__.py
├── tests/                # Test suite
│   ├── unit/            # Unit tests
│   ├── integration/     # Integration tests
│   └── e2e/             # End-to-end tests
├── docs/                # Documentation
│   ├── architecture/    # System architecture
│   ├── designs/         # Feature designs
│   ├── decisions/       # Architecture Decision Records
│   ├── standards/       # Coding and process standards
│   └── roadmap/         # Version planning
└── pyproject.toml       # Project configuration
```

## Documentation

- **Architecture Overview**: `/docs/architecture/overview.md`
- **IndieAuth Protocol**: `/docs/architecture/indieauth-protocol.md`
- **Coding Standards**: `/docs/standards/coding.md`
- **Testing Standards**: `/docs/standards/testing.md`
- **Git Workflow**: `/docs/standards/git.md`

## Contributing

This project follows strict architectural and development standards. Please review:

1. `/docs/standards/coding.md` - Coding conventions
2. `/docs/standards/testing.md` - Testing requirements
3. `/docs/standards/git.md` - Git workflow and commit format

All code must:
- Include comprehensive tests (minimum 80% coverage)
- Pass linting and type checking
- Follow conventional commits format
- Be reviewed before merging to main

## License

MIT License - see LICENSE file for details

## References

- [W3C IndieAuth Specification](https://www.w3.org/TR/indieauth/)
- [OAuth 2.0 Authorization Framework](https://datatracker.ietf.org/doc/html/rfc6749)
- [PKCE (RFC 7636)](https://datatracker.ietf.org/doc/html/rfc7636)