auth0mock/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

auth0mock is a Go application that simulates an Auth0 authentication server for local development. It provides OAuth 2.0 and OpenID Connect (OIDC) endpoints compatible with the Auth0 API, allowing developers to test authentication flows without connecting to the actual Auth0 service.

## Development Commands

```bash
# Build the service
go build -o auth0mock ./cmd/service

# Run the service
go run ./cmd/service

# Run tests
go test ./... -v

# Run tests with coverage
go test ./... -coverprofile=coverage.txt -covermode=atomic

# Format code
gofumpt -w .
goimports -w .

# Run pre-commit hooks
pre-commit run --all-files
```

## Architecture

```
auth0mock/
├── cmd/service/         # Entry point, HTTP server setup, configuration
├── auth/                # JWT/JWK generation and signing, PKCE verification
├── handlers/            # HTTP handlers for all endpoints
│   └── templates/       # Embedded HTML templates (login form)
├── store/               # In-memory session and user storage
├── public/              # Static files (favicon)
├── k8s/                 # Kubernetes deployment manifests
└── Dockerfile           # Multi-stage Go build
```

**Key Packages:**
- `auth/jwt.go` - RSA key generation, JWT signing using lestrrat-go/jwx/v2
- `auth/pkce.go` - PKCE verification (S256 and plain methods)
- `store/sessions.go` - Thread-safe session storage with TTL and cleanup
- `store/users.go` - Thread-safe user storage with JSON file loading
- `handlers/oauth.go` - OAuth token exchange, authorization, code generation
- `handlers/discovery.go` - OIDC discovery and JWKS endpoints
- `handlers/management.go` - Auth0 Management API endpoints

## HTTP Endpoints

**Authentication:**
- `POST /oauth/token` - Token exchange (authorization code and client_credentials)
- `GET /authorize` - Authorization endpoint with HTML login form
- `POST /code` - Code generation for PKCE flow

**Discovery:**
- `GET /.well-known/openid-configuration` - OIDC discovery document
- `GET /.well-known/jwks.json` - JSON Web Key Set

**Management API:**
- `GET /api/v2/users-by-email` - Get user by email
- `POST /api/v2/users` - Create user
- `PATCH /api/v2/users/{userid}` - Update user
- `POST /api/v2/tickets/password-change` - Password change ticket

**Session:**
- `GET /userinfo` - User information
- `POST /tokeninfo` - Decode JWT token
- `GET /v2/logout` - Logout and session cleanup

## Environment Variables

| Variable | Default | Purpose |
|----------|---------|---------|
| `PORT` | `3333` | HTTP listen port |
| `ISSUER` | `localhost:3333` | JWT issuer (without https://) |
| `AUDIENCE` | `https://generic-audience` | JWT audience |
| `USERS_FILE` | `./users.json` | Path to initial users JSON file |
| `ADMIN_CUSTOM_CLAIM` | `https://unbound.se/admin` | Admin custom claim key |
| `EMAIL_CUSTOM_CLAIM` | `https://unbound.se/email` | Email custom claim key |
| `LOG_LEVEL` | `info` | Log level (debug, info, warn, error) |
| `LOG_FORMAT` | `text` | Log format (text, json) |

## Initial Users

Create a `users.json` file to seed users on startup:

```json
{
  "email@test.com": {
    "given_name": "John",
    "family_name": "Doe",
    "user_id": "auth0|email@test.com",
    "email": "email@test.com"
  }
}
```

## Key Implementation Details

- RSA 2048-bit key pair generated at startup using `lestrrat-go/jwx/v2`
- In-memory session storage with 5-minute TTL and automatic cleanup
- Proper PKCE verification (S256 method with SHA256 hash)
- Thread-safe stores using `sync.RWMutex`
- Graceful shutdown with signal handling

## Integration with Shiny

This service is used for local development and acceptance testing of the Shiny platform. The gateway and frontend services are configured to accept tokens signed by this mock server when running locally.