Installation

This guide covers the detailed installation and configuration process for Authrim.

System Requirements

Requirement	Minimum Version
Node.js	>= 22.0.0
pnpm	>= 9.0.0
Git	Latest
Cloudflare Account	Free tier or higher

Installation Steps

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 Cryptographic Keys

Generate the RSA keys used for JWT signing:

./scripts/setup-keys.sh

This creates:

File	Purpose
.keys/private.pem	RSA private key for JWT signing
.keys/public.jwk.json	Public key in JWK format
.keys/metadata.json	Key ID and metadata

3. Configure Environment Variables

# 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 Cloudflare Resources

KV Namespaces

./scripts/setup-kv.sh --env=dev

This creates the following KV namespaces:

• CLIENTS - OAuth client registrations
• SETTINGS - System configuration
• STATE_STORE - Authorization codes and state
• NONCE_STORE - Replay protection

D1 Database

./scripts/setup-d1.sh

Creates the authrim-db D1 database for:

• User accounts
• Session data
• Audit logs

Durable Objects

./scripts/setup-durable-objects.sh

Deploys Durable Objects for:

• KeyManager - Cryptographic key management
• AuthorizationCodeStore - Auth code storage with strong consistency
• SessionStore - Session management
• RefreshTokenRotator - Refresh token rotation

5. Optional: Configure Email (Resend)

For magic link authentication:

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

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

Project Structure

authrim/
├── packages/
│   ├── shared/           # Shared utilities, types, Durable Objects
│   ├── op-discovery/     # Discovery & JWKS endpoints
│   ├── op-auth/          # Authorization & consent
│   ├── op-token/         # Token endpoint
│   ├── op-userinfo/      # UserInfo endpoint
│   ├── op-management/    # Admin API & client registration
│   ├── op-async/         # Device Flow & CIBA
│   ├── op-saml/          # SAML IdP/SP
│   ├── scim/             # SCIM 2.0 provisioning
│   ├── policy-core/      # Policy engine core
│   ├── policy-service/   # Policy evaluation service
│   ├── external-idp/     # External IdP integration
│   ├── router/           # Unified router (test/dev)
│   └── ui/               # SvelteKit frontend
├── scripts/              # Setup & deployment scripts
├── migrations/           # D1 database migrations
├── conformance/          # OpenID conformance testing
└── docs/                 # Documentation

Worker Architecture

Worker	Purpose	Endpoints
op-discovery	OIDC Discovery	/.well-known/*
op-auth	Authorization	/authorize, /consent
op-token	Token issuance	/token, /introspect, /revoke
op-userinfo	User info	/userinfo
op-management	Admin API	/api/admin/*, /register
op-async	Async flows	/device_authorization, /bc-authorize
scim	User provisioning	/scim/v2/*
router	Request routing	All (development 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

Conformance Testing

pnpm run conformance:basic    # Run Basic OP tests
pnpm run conformance:config   # Run Config OP tests
pnpm run conformance:dynamic  # Run Dynamic OP tests
pnpm run conformance:fapi2    # Run FAPI 2.0 tests
pnpm run conformance:all      # Run all conformance tests

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

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

Private key not found

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

TypeScript errors

pnpm run typecheck

View logs

# Development
wrangler dev --log-level debug

# Production
wrangler tail --env production

Next Steps

• Deployment Guide - Deploy to production
• OIDC Configuration - Configure OpenID Connect
• API Reference - Explore the API