99 lines
3.8 KiB
Markdown
99 lines
3.8 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
# Format
|
|
make reformat # uv run ruff format src/ tests/
|
|
|
|
# Lint (with auto-fix)
|
|
make lint # uv run ruff check src/ tests/ --fix
|
|
|
|
# Type checking
|
|
make typecheck # uv run ty check src/
|
|
|
|
# Tests
|
|
make test # uv run python -m pytest -v
|
|
uv run pytest tests/test_foo.py::test_specific # single test
|
|
|
|
# All checks
|
|
make check
|
|
|
|
# Dev server
|
|
OIDC_OP_ISSUER=http://localhost:8000 OIDC_OP_DEBUG=true \
|
|
uv run uvicorn porchlight.app:create_app \
|
|
--factory --host 127.0.0.1 --port 8000 --reload --reload-dir src
|
|
```
|
|
|
|
### End-to-end tests (Playwright/Node)
|
|
|
|
```bash
|
|
# One-time setup
|
|
cd tests/e2e && npm install && npm run setup && cd ../..
|
|
|
|
# Run e2e tests (starts/stops the server automatically)
|
|
./tests/e2e/run.sh
|
|
|
|
# Run a specific spec
|
|
./tests/e2e/run.sh tests/e2e/login.spec.js
|
|
|
|
# Run with visible browser
|
|
E2E_HEADLESS=0 ./tests/e2e/run.sh
|
|
```
|
|
|
|
## Architecture
|
|
|
|
Porchlight is an OpenID Connect (OIDC) Provider + user management app built on **FastAPI** with **idpyoidc** for the OIDC protocol layer. UI is server-side **Jinja2** templates with **HTMX** for interactivity. Storage defaults to **SQLite** via `aiosqlite`.
|
|
|
|
### Request flow
|
|
|
|
```
|
|
Browser/RP → FastAPI routes → Service classes → Repository layer → SQLite
|
|
↕
|
|
idpyoidc (OIDC protocol)
|
|
```
|
|
|
|
### Module layout
|
|
|
|
- `src/porchlight/app.py` — FastAPI app factory (`create_app()`), lifespan, middleware stack
|
|
- `src/porchlight/config.py` — Settings loaded from env vars (`OIDC_OP_*` prefix) and optional TOML file
|
|
- `src/porchlight/models.py` — Pydantic domain models (`User`, `WebAuthnCredential`, `MagicLink`, `Consent`)
|
|
- `src/porchlight/validation.py` — Form-validation models (`ProfileUpdate` with email/phone/URL validation)
|
|
- `src/porchlight/dependencies.py` — FastAPI dependency injection helpers
|
|
- `src/porchlight/csrf.py` — Synchronizer-token CSRF middleware (exempt: `/token`, `/userinfo`)
|
|
- `src/porchlight/authn/` — Password (`argon2`) and WebAuthn (`fido2`) authentication services + routes
|
|
- `src/porchlight/manage/` — Authenticated user credential & profile management routes
|
|
- `src/porchlight/admin/` — Admin user management routes (user list, invite creation, profile editing)
|
|
- `src/porchlight/invite/` — Magic-link invitation service (proquint tokens, time-limited)
|
|
- `src/porchlight/oidc/` — OIDC endpoints (discovery, JWKS, `/authorization`, `/token`, `/userinfo`)
|
|
- `src/porchlight/store/` — Repository pattern: `protocols.py` defines interfaces; `sqlite/` has the concrete implementation; `mongodb/` is a stub
|
|
- `src/porchlight/cli.py` — Typer CLI (`create-invite`, `initial-admin`)
|
|
|
|
### Storage layer
|
|
|
|
`store/protocols.py` defines `UserRepository`, `CredentialRepository`, `MagicLinkRepository`, and `ConsentRepository` as Protocol classes. The SQLite implementation lives in `store/sqlite/repositories.py`. Migrations run automatically on startup from `store/sqlite/migrations/*.sql`.
|
|
|
|
### Configuration
|
|
|
|
All settings use the `OIDC_OP_` env-var prefix (see `config.py`). Key vars:
|
|
|
|
| Variable | Notes |
|
|
|---|---|
|
|
| `OIDC_OP_ISSUER` | **Required.** Must match the public-facing URL. |
|
|
| `OIDC_OP_SESSION_SECRET` | Session signing key |
|
|
| `OIDC_OP_DEBUG` | Enables Swagger UI |
|
|
| `OIDC_OP_SQLITE_PATH` | DB file path (default `data/oidc_op.db`) |
|
|
| `OIDC_OP_CONFIG_FILE` | Optional TOML file for clients and advanced config |
|
|
|
|
OIDC relying parties (clients) are defined in the TOML config file under `[clients.<id>]`.
|
|
|
|
### Test fixtures
|
|
|
|
`tests/conftest.py` provides:
|
|
- `settings` — in-memory SQLite, test issuer
|
|
- `client` — async `httpx.AsyncClient` with ASGI transport
|
|
- CSRF token extraction helper
|
|
|
|
Unit and integration tests use in-memory SQLite; e2e tests use a seeded file-based DB (`tests/e2e/setup_db.py`).
|