Skip to content

development.md

Latest commit

 

History

History
300 lines (218 loc) · 7.04 KB

development.md

File metadata and controls

300 lines (218 loc) · 7.04 KB

Development Guide

This guide will help you set up your development environment for Authrim.

Table of Contents

Prerequisites

Before you begin, ensure you have the following installed:

Initial Setup

1. Clone and Install

# Clone the repository
git clone https://github.com/sgrastar/authrim.git
cd authrim

# Install dependencies
pnpm install

# Login to Cloudflare
wrangler login

2. Generate Keys

./scripts/setup-keys.sh

This generates:

  • .keys/private.pem - Private key for JWT signing
  • .keys/public.jwk.json - Public key in JWK format
  • .keys/metadata.json - Key metadata including Key ID

3. Configure Local Environment

# Create .dev.vars with environment variables
./scripts/setup-local-vars.sh

# Generate wrangler.toml for local development
./scripts/setup-local-wrangler.sh

4. Set Up Cloud Resources

# Create KV namespaces (automatically initializes default settings)
./scripts/setup-kv.sh --env=dev

# Create D1 database
./scripts/setup-d1.sh

# Deploy Durable Objects
./scripts/setup-durable-objects.sh

5. (Optional) Configure Email

./scripts/setup-resend.sh --env=local

Without Resend, magic links return URLs instead of sending emails (useful for development).

6. Start Development Server

pnpm run dev

This starts all workers in development mode. Access endpoints at http://localhost:8787.

Development Workflow

Quick Start

pnpm run dev     # Start dev server with hot reload

Testing Endpoints

# Discovery endpoint
curl http://localhost:8787/.well-known/openid-configuration | jq

# JWKS endpoint
curl http://localhost:8787/.well-known/jwks.json | jq

# Authorization flow
# Navigate to:
# http://localhost:8787/authorize?response_type=code&client_id=test-client&redirect_uri=http://localhost:3000/callback&scope=openid&state=random-state

Code Quality

Before committing, run:

pnpm run test           # Run tests
pnpm run lint           # Run ESLint
pnpm run typecheck      # TypeScript type checking
pnpm run format:check   # Check formatting

Project Structure

authrim/
├── packages/
│   ├── ar-lib-core/      # Shared utilities, types, Durable Objects
│   ├── ar-discovery/     # Discovery & JWKS endpoints
│   ├── ar-auth/          # Authorization & consent
│   ├── ar-token/         # Token endpoint
│   ├── ar-userinfo/      # UserInfo endpoint
│   ├── ar-management/    # Admin API & client registration
│   ├── ar-async/         # Device Flow & CIBA
│   ├── ar-saml/          # SAML IdP/SP
│   ├── ar-policy/        # Policy evaluation service (ReBAC)
│   ├── ar-bridge/        # External IdP integration
│   ├── ar-vc/            # Verifiable Credentials
│   ├── ar-router/        # Unified router (test/dev)
│   └── ar-ui/            # SvelteKit frontend
├── scripts/              # Setup & deployment scripts
├── migrations/           # D1 database migrations
├── load-testing/         # Performance benchmarks
└── docs/                 # Documentation

Worker Overview

Worker Purpose Endpoints
ar-discovery OIDC Discovery /.well-known/*
ar-auth Authorization /authorize, /consent, /setup
ar-token Token issuance /token
ar-userinfo User info /userinfo
ar-management Admin API /api/admin/*, /register, /introspect, /revoke
ar-async Async flows /device_authorization, /bc-authorize
ar-policy Policy (ReBAC) /api/policy/*
ar-router Request routing All (test mode only)

Available Scripts

Development

pnpm run dev              # Start all workers with hot reload
pnpm run build            # Build all packages
pnpm run build:api        # Build API workers only (exclude UI)

Testing

pnpm run test             # Run unit tests
pnpm run test:e2e         # Run E2E tests (Playwright)
pnpm run test:e2e:ui      # Run E2E tests with UI
pnpm run test:lighthouse  # Run Lighthouse performance tests

Code Quality

pnpm run lint             # Run ESLint
pnpm run typecheck        # TypeScript type checking
pnpm run format           # Format code with Prettier
pnpm run format:check     # Check code formatting

Deployment

pnpm run deploy           # Deploy workers with retry logic
pnpm run deploy:ui        # Deploy UI to Cloudflare Pages
pnpm run deploy:all       # Deploy everything

Database

pnpm run migrate:create <name>   # Create new migration file

For applying migrations:

wrangler d1 migrations list authrim-db
wrangler d1 migrations apply authrim-db

Troubleshooting

Port 8787 already in use

# Kill the process using the port
lsof -ti:8787 | xargs kill -9

# Or use a different port
wrangler dev --port 8788

KV namespace not found

Ensure KV namespaces are created:

wrangler kv namespace list
./scripts/setup-kv.sh --env=dev

Private key not found

Regenerate keys:

./scripts/setup-keys.sh
./scripts/setup-local-vars.sh

TypeScript errors

pnpm run typecheck

esbuild platform mismatch (WSL)

If you see @esbuild/win32-x64 vs @esbuild/linux-x64 errors:

rm -rf node_modules pnpm-lock.yaml
pnpm install

Always install dependencies in the environment where you run the code.

View logs

# Development
wrangler dev --log-level debug

# Production
wrangler tail --env production

Inspect KV data

wrangler kv key list --binding=CLIENTS
wrangler kv key get "key-name" --binding=CLIENTS

Setup Flow Summary

setup-keys.sh
    ↓
setup-local-vars.sh
    ↓
setup-local-wrangler.sh
    ↓
setup-kv.sh --env=dev  ← Automatically initializes settings
    ↓
setup-d1.sh + setup-durable-objects.sh
    ↓
setup-resend.sh --env=local (optional)
    ↓
pnpm run dev

Resources

Happy coding! 🚀