Pico-Auth

Minimal JWT auth server for the Pico ecosystem.

Pico-Auth is a ready-to-run authentication server built on top of the pico-framework stack. It provides:

• JWT tokens with auto-generated key pairs (RS256 default, ML-DSA-65/87 optional)
• Refresh token rotation with SHA-256 hashed storage
• RBAC with four built-in roles: superadmin, org_admin, operator, viewer
• Group management with CRUD API, membership, and groups JWT claim
• OIDC discovery endpoints (.well-known/openid-configuration, JWKS)
• Bcrypt password hashing (72-byte input limit enforced)
• Post-quantum ready: ML-DSA-65 / ML-DSA-87 signing via optional pqc extra
• Zero-config startup with auto-created admin user

Requires Python 3.11+

Architecture

Pico-Auth uses the full Pico stack with dependency injection:

Installation

pip install -e ".[dev]"

# With post-quantum (ML-DSA) support
pip install -e ".[dev,pqc]"

Quick Start

1. Run the Server

python -m pico_auth.main

The server starts on http://localhost:8100 with:

• An auto-created admin user (admin@pico.local / admin)
• SQLite database at auth.db
• Auto-generated keys at ~/.pico-auth/ (RSA PEM or ML-DSA binary, depending on algorithm)

2. Register a User

curl -X POST http://localhost:8100/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "alice@example.com", "password": "secret123", "display_name": "Alice"}'

3. Login

curl -X POST http://localhost:8100/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "alice@example.com", "password": "secret123"}'

Returns:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "a1b2c3d4...",
  "token_type": "Bearer",
  "expires_in": 900
}

4. Access Protected Endpoint

curl http://localhost:8100/api/v1/auth/me \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

API Endpoints

Configuration

All settings are loaded from application.yaml and can be overridden with environment variables:

auth:
  data_dir: "~/.pico-auth"              # Key storage directory
  access_token_expire_minutes: 15        # JWT lifetime
  refresh_token_expire_days: 7           # Refresh token lifetime
  issuer: "http://localhost:8100"        # JWT issuer claim
  audience: "pico-bot"                   # JWT audience claim
  algorithm: "RS256"                     # RS256, ML-DSA-65, or ML-DSA-87
  auto_create_admin: true                # Create admin on startup
  admin_email: "admin@pico.local"        # Default admin email
  admin_password: "admin"                # Default admin password

database:
  url: "sqlite+aiosqlite:///auth.db"     # Database URL
  echo: false                            # SQL logging

auth_client:
  enabled: true                          # Enable auth middleware
  issuer: "http://localhost:8100"        # Must match auth.issuer
  audience: "pico-bot"                   # Must match auth.audience
  accepted_algorithms:                   # Algorithms accepted for verification
    - "RS256"
    - "ML-DSA-65"
    - "ML-DSA-87"

fastapi:
  title: "Pico Auth API"
  version: "0.2.0"

Environment variable override example:

AUTH_ISSUER=https://auth.myapp.com AUTH_ADMIN_PASSWORD=strong-password python -m pico_auth.main

# With ML-DSA-65 post-quantum algorithm
AUTH_ALGORITHM=ML-DSA-65 python -m pico_auth.main

JWT Token Claims

Access tokens include:

Ecosystem

Pico-Auth is built on:

Development

# Install in dev mode
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Run with coverage
pytest --cov=pico_auth --cov-report=term-missing tests/

# Full test matrix
tox

# Lint
ruff check pico_auth/ tests/

# Docker E2E tests (requires Docker and ../pico-client-auth)
pytest tests/test_docker_e2e.py -m docker -v

Docker E2E tests build a local image (Dockerfile.local), start a container, and run HTTP tests against it. They are excluded from the default test suite — use -m docker to run them. See Docker E2E Test for details.

License

MIT - LICENSE