Development Guide

uv sync --dev

uv run hdc-auth-proxy

https://cognito-idp.{region}.amazonaws.com/{user_pool_id}/.well-known/jwks.json

HDC_PROXY_ENV_STATE=dev uv run hdc-auth-proxy

uv run hdc-auth-proxy   # picks up .env.dev if HDC_PROXY_ENV_STATE=dev

========================================================
  DEV MODE ACTIVE -- NOT FOR PRODUCTION
  Pre-populated test data loaded. Auth is NOT secure.
========================================================
Dev credentials:
  Bearer token : dev-token
  API key      : dev-api-key
  Subject      : dev-user (analyst role, read:data scope)

# 401 — no credentials
curl http://localhost:8000/v1/data/indicators

# 200 — valid Bearer token (analyst can read data)
curl -H "Authorization: Bearer dev-token" http://localhost:8000/v1/data/indicators

# 401 — invalid token
curl -H "Authorization: Bearer bad-token" http://localhost:8000/v1/data/indicators

# 403 — analyst cannot access admin endpoints
curl -H "Authorization: Bearer dev-token" http://localhost:8000/v1/admin/users

# 200 — API key on public resource
curl -H "X-API-Key: dev-api-key" http://localhost:8000/public/health

# .env
COGNITO_USER_POOL_ID=eu-west-1_abc123
COGNITO_CLIENT_ID=my-app-client
HDC_PROXY_UPSTREAM_URL=http://localhost:9000
SESSION_SECRET_KEY=my-secret

uv run hdc-auth-proxy   # .env is loaded automatically

COGNITO_USER_POOL_ID=eu-west-1_abc123 \
COGNITO_CLIENT_ID=my-app-client \
HDC_PROXY_UPSTREAM_URL=http://localhost:9000 \
uv run hdc-auth-proxy

HDC_PROXY_ENV_STATE=dev \
COGNITO_USER_POOL_ID=eu-west-1_abc123 \
COGNITO_CLIENT_ID=my-app-client \
uv run hdc-auth-proxy

COGNITO_USER_POOL_ID=eu-west-1_abc123 \
COGNITO_CLIENT_ID=my-app-client \
COGNITO_DOMAIN=mypool.auth.eu-west-1.amazoncognito.com \
COGNITO_CALLBACK_URI=http://localhost:8000/auth/callback \
SESSION_SECRET_KEY=dev-secret-key \
uv run hdc-auth-proxy

aws cognito-idp create-user-pool \
  --pool-name hdc-auth-pool \
  --username-attributes email \
  --auto-verified-attributes email \
  --region eu-west-1

aws cognito-idp create-user-pool-client \
  --user-pool-id eu-west-1_abc123 \
  --client-name hdc-auth-proxy \
  --no-generate-secret \
  --explicit-auth-flows ALLOW_USER_SRP_AUTH ALLOW_REFRESH_TOKEN_AUTH \
  --allowed-o-auth-flows code \
  --allowed-o-auth-scopes openid profile email \
  --allowed-o-auth-flows-user-pool-client \
  --callback-urls '["http://localhost:8000/auth/callback"]' \
  --supported-identity-providers COGNITO \
  --region eu-west-1

aws cognito-idp create-user-pool-domain \
  --user-pool-id eu-west-1_abc123 \
  --domain hdc-auth-dev \
  --region eu-west-1

aws cognito-idp admin-create-user \
  --user-pool-id eu-west-1_abc123 \
  --username analyst@wfp.org \
  --user-attributes Name=email,Value=analyst@wfp.org Name=email_verified,Value=true \
  --temporary-password 'TempPass123!' \
  --region eu-west-1

aws cognito-idp admin-set-user-password \
  --user-pool-id eu-west-1_abc123 \
  --username analyst@wfp.org \
  --password 'YourPermanentPass123!' \
  --permanent \
  --region eu-west-1

COGNITO_USER_POOL_ID=eu-west-1_abc123
COGNITO_REGION=eu-west-1
COGNITO_CLIENT_ID=your-client-id-here
COGNITO_DOMAIN=hdc-auth-dev.auth.eu-west-1.amazoncognito.com
COGNITO_CALLBACK_URI=http://localhost:8000/auth/callback
COGNITO_SCOPES=openid profile email
SESSION_SECRET_KEY=your-secret-key-here
SESSION_SECURE=false

python3 -c "import secrets; print(secrets.token_urlsafe(32))"

uv run hdc-auth-proxy   # loads .env automatically, then .env.prod on top (if it exists)

# Login redirect (should return 302 to Cognito)
curl -v http://localhost:8000/auth/login 2>&1 | grep -i location

# After browser login, check the session cookie works:
curl -b "hdc_session=<cookie-value>" http://localhost:8000/v1/data/indicators

Client → ProxyHandler
           ├── Extract credential (Authorization: Bearer or X-API-Key header)
           │     └── Missing → 401
           ├── Authenticate (validate token or API key → resolve Principal)
           │     └── Invalid → 401
           ├── Authorize (match resource + permission against policy rules)
           │     └── Denied → 403
           └── Forward to upstream → StreamingResponse
                 └── Upstream error → 502

uv run pytest -m "not e2e"    # Tiers 1-3 (no Docker)
uv run pytest                  # All tiers (requires Docker for Tier 4)
uv run pytest -m e2e           # Tier 4 only (requires Docker)

uv run pytest tests/ -v --ignore=tests/test_integration_oidc.py --ignore=tests/test_integration_cognito.py

uv run pytest tests/test_integration_oidc.py -v

uv run pytest tests/test_integration_cognito.py -v

uv run pytest tests/e2e/ -m e2e -v

uv run pytest tests/adapters/http/ -v      # HTTP adapter
uv run pytest tests/adapters/oidc/ -v      # OIDC adapter
uv run pytest tests/adapters/cognito/ -v   # Cognito adapter
uv run pytest tests/adapters/memory/ -v    # In-memory adapters

uv run ruff format --check .   # formatting
uv run ruff check .            # linting
uv run ty check                # type checking