84 lines
2.6 KiB
Markdown
84 lines
2.6 KiB
Markdown
|
# CLAUDE.md
|
||
|
|
|
||
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
|
|
||
|
|
## Project Overview
|
||
|
|
|
||
|
|
auth0mock is a Node.js/Express 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
|
||
|
|
# Install dependencies
|
||
|
|
yarn install
|
||
|
|
|
||
|
|
# Start production server (port 3333)
|
||
|
|
yarn start
|
||
|
|
|
||
|
|
# Development with auto-reload (nodemon)
|
||
|
|
yarn dev
|
||
|
|
|
||
|
|
# Format code
|
||
|
|
yarn lintfix
|
||
|
|
|
||
|
|
# Check formatting
|
||
|
|
yarn lint
|
||
|
|
```
|
||
|
|
|
||
|
|
## Architecture
|
||
|
|
|
||
|
|
This is a single-file Express application (`app.js`) that implements:
|
||
|
|
|
||
|
|
**Authentication Endpoints:**
|
||
|
|
|
||
|
|
- `POST /oauth/token` - Token exchange (OAuth 2.0 authorization code flow)
|
||
|
|
- `GET /authorize` - Authorization endpoint with HTML login form
|
||
|
|
- `POST /code` - Code generation for PKCE flow
|
||
|
|
|
||
|
|
**Discovery Endpoints:**
|
||
|
|
|
||
|
|
- `GET /.well-known/openid-configuration` - OIDC discovery document
|
||
|
|
- `GET /.well-known/jwks.json` - JSON Web Key Set for token verification
|
||
|
|
|
||
|
|
**Management API (Auth0-compatible):**
|
||
|
|
|
||
|
|
- `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
|
||
|
|
|
||
|
|
**Key Implementation Details:**
|
||
|
|
|
||
|
|
- RSA 2048-bit key pair generated at startup using `node-jose`
|
||
|
|
- In-memory session and user storage (not persistent)
|
||
|
|
- PKCE support with code challenge verification
|
||
|
|
- Custom claims for admin (`https://unbound.se/admin`) and email (`https://unbound.se/email`)
|
||
|
|
|
||
|
|
## Environment Variables
|
||
|
|
|
||
|
|
| Variable | Default | Purpose |
|
||
|
|
| ------------ | -------------------------- | -------------------------------- |
|
||
|
|
| `ISSUER` | `localhost:3333` | JWT issuer claim |
|
||
|
|
| `AUDIENCE` | `https://generic-audience` | JWT audience claim |
|
||
|
|
| `USERS_FILE` | `./users.json` | Path to initial users JSON file |
|
||
|
|
| `DEBUG` | (unset) | Debug logging (`app*` to enable) |
|
||
|
|
|
||
|
|
## 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"
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
## 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.
|