Package Exports

@authrim/setup
@authrim/setup/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@authrim/setup) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@authrim/setup

CLI and Web UI for setting up Authrim OIDC Provider on Cloudflare Workers

Overview

@authrim/setup is the official setup tool for deploying Authrim to Cloudflare Workers. It provides both an interactive CLI and a Web UI to guide you through:

Provisioning Cloudflare resources (D1 databases, KV namespaces, Queues)
Generating cryptographic keys and secrets
Configuring environment-specific settings
Deploying all Authrim workers in the correct order
Setting up the initial administrator account
Managing existing environments (view, inspect, delete)

Quick Start

# Full setup with Web UI (recommended)
npx @authrim/setup

# Manage existing environments (no source download needed)
npx @authrim/setup manage

# Or install globally
npm install -g @authrim/setup
authrim-setup

Usage Modes

1. Web UI Mode (Default)

Run without arguments to launch the interactive Web UI:

npx @authrim/setup

This opens a browser with a step-by-step wizard featuring:

New Setup: Create a new Authrim deployment from scratch
Load Config: Resume or redeploy using an existing configuration
Manage Environments: View and delete existing environments

2. Environment Management Mode

Manage existing Authrim environments without downloading source code:

npx @authrim/setup manage

Features:

Auto-detect all Authrim environments in your Cloudflare account
View resource counts (Workers, D1, KV, Queues, R2)
Delete environments with granular resource selection
Real-time progress display

3. CLI Mode

For terminal-based setup or CI/CD integration:

npx @authrim/setup --cli

4. Deploy Existing Configuration

If you already have an authrim-config.json:

npx @authrim/setup deploy --config ./authrim-config.json --env prod

Commands

`init` (default)

Initialize a new Authrim project:

authrim-setup init [options]

Options:
  --cli              Use CLI mode instead of Web UI
  --config <path>    Load existing configuration file
  --keep <path>      Keep source files at specified path
  --env <name>       Environment name (prod, staging, dev)

`manage`

Manage existing Authrim environments (no source code required):

authrim-setup manage [options]

Options:
  --port <number>    Web UI port (default: 3456)
  --no-browser       Do not open browser automatically

`deploy`

Deploy Authrim to Cloudflare:

authrim-setup deploy [options]

Options:
  -c, --config <path>  Config file path (default: "authrim-config.json")
  -e, --env <env>      Environment name
  --component <name>   Deploy single component
  --dry-run            Preview without deploying
  --skip-secrets       Skip secrets upload
  --skip-ui            Skip UI deployment
  -y, --yes            Skip confirmation prompts

`download`

Download Authrim source code only:

authrim-setup download [options]

Options:
  -o, --output <path>  Output directory (default: "./authrim")
  --repo <repository>  GitHub repository (default: "sgrastar/authrim")
  --ref <gitRef>       Git tag or branch (default: latest release)
  --force              Overwrite existing directory

`status`

Check deployment status:

authrim-setup status [options]

Options:
  -c, --config <path>  Config file path

`config`

Manage configuration:

authrim-setup config [options]

Options:
  --show       Show current configuration
  --validate   Validate configuration file
  --json       Output in JSON format

Web UI Features

Resource Provisioning

Before creating resources, the UI shows a preview of what will be created:

📋 Resource Names:
  D1 Databases:
  • prod-authrim-core-db
  • prod-authrim-pii-db

  KV Namespaces:
  • PROD-CLIENTS_CACHE
  • PROD-SETTINGS
  • PROD-AUTHRIM_CONFIG
  ...

  Cryptographic Keys:
  • .keys/private.pem (RSA Private Key)
  • .keys/public.jwk.json (JWK Public Key)
  ...

Real-time Progress

All operations show real-time progress:

📦 Provisioning 10 resources...

📊 D1 Databases (0/2)
  ⏳ Creating: prod-authrim-core-db...
  ✅ prod-authrim-core-db (ID: 12345678...)
  ⏳ Creating: prod-authrim-pii-db...
  ✅ prod-authrim-pii-db (ID: 87654321...)
📊 D1 Databases (2/2) ✓

🗄️ KV Namespaces (0/8)
  ⏳ Creating: PROD-CLIENTS_CACHE...
  ...

Environment Management

Delete environments with granular control:

⚠️ Delete Environment: prod

Select resources to delete:
☑ Workers (12 workers)
☑ D1 Databases (2 databases)
☑ KV Namespaces (8 namespaces)
☐ Queues (0 queues)
☐ R2 Buckets (0 buckets)

[Cancel] [🗑️ Delete Selected]

Configuration Files

authrim-config.json

The main configuration file containing all environment settings:

{
  "version": "1.0.0",
  "environment": {
    "prefix": "prod"
  },
  "urls": {
    "api": {
      "custom": "https://auth.example.com",
      "auto": "https://prod-ar-router.workers.dev"
    },
    "loginUi": {
      "custom": "https://login.example.com",
      "auto": "https://prod-ar-ui.pages.dev"
    },
    "adminUi": {
      "custom": null,
      "auto": "https://prod-ar-ui.pages.dev/admin"
    }
  },
  "components": {
    "api": true,
    "loginUi": true,
    "adminUi": true,
    "saml": false,
    "async": false,
    "vc": false
  },
  "keys": {
    "keyId": "kid-xxxxxxxx",
    "secretsPath": "./.keys/"
  }
}

authrim-lock.json

Records provisioned resource IDs for re-deployment:

{
  "version": "1.0.0",
  "env": "prod",
  "d1": {
    "DB": { "name": "prod-authrim-core-db", "id": "..." },
    "PII_DB": { "name": "prod-authrim-pii-db", "id": "..." }
  },
  "kv": {
    "CLIENTS_CACHE": { "name": "PROD-CLIENTS_CACHE", "id": "..." },
    "SETTINGS": { "name": "PROD-SETTINGS", "id": "..." }
  }
}

.keys/ Directory

Contains sensitive cryptographic material (gitignored):

.keys/
├── private.pem              # RSA private key for JWT signing
├── public.jwk.json          # Public key in JWK format
├── rp_token_encryption_key.txt
├── admin_api_secret.txt
├── key_manager_secret.txt
└── setup_token.txt          # Initial admin setup token

Resource Naming Convention

Resources are named using the environment prefix:

Resource Type	Naming Pattern	Example (prod)
Workers	`{env}-ar-{component}`	`prod-ar-auth`
D1 Database	`{env}-authrim-{type}-db`	`prod-authrim-core-db`
KV Namespace	`{ENV}-{NAME}`	`PROD-CLIENTS_CACHE`
Queue	`{env}-audit-queue`	`prod-audit-queue`
R2 Bucket	`{env}-authrim-avatars`	`prod-authrim-avatars`

Deployment Order

Authrim workers are deployed in a specific order to satisfy dependencies:

Level 0: ar-lib-core         # Durable Objects definitions (always first)
Level 1: ar-discovery        # Discovery endpoint
Level 2: ar-auth, ar-token, ar-userinfo, ar-management  # Core services (parallel)
Level 3: ar-async, ar-saml, ar-vc, ar-bridge           # Optional (parallel)
Level 4: ar-router           # Service bindings (always last)
Level 5: ar-ui               # Cloudflare Pages (optional)

Initial Admin Setup

After deployment, the CLI displays a one-time setup URL:

━━━ Initial Admin Setup ━━━

To create the initial administrator account, visit:

  https://auth.example.com/setup?token=abc123...

⚠️  Important:
  • This link expires in 1 hour
  • Setup can only be completed once
  • You will need to register a Passkey (biometric/security key)

This URL allows you to:

Register a Passkey as the system administrator
Access the Admin Dashboard
Create OAuth clients and configure settings

Security Features

Session Token Authentication: API endpoints require session tokens to prevent unauthorized access
Path Traversal Prevention: Key storage directory is validated to prevent directory traversal attacks
Command Injection Prevention: Browser launch URLs are validated to prevent shell injection
Error Sanitization: Error messages are sanitized to prevent information leakage
Operation Locking: Concurrent operations are serialized to prevent race conditions
Localhost-Only Web UI: Web UI only binds to localhost for security
Auto Port Selection: If default port is in use, automatically finds an available port (3456-3465)

Requirements

Node.js >= 20.0.0
Wrangler CLI installed and authenticated
Cloudflare account with Workers Paid plan (for D1, KV, Durable Objects)

Development

Local Testing

# From the authrim repository root
cd packages/setup

# Run in development mode
pnpm dev

# Build and run
pnpm build
pnpm start

# Run tests
pnpm test

Using with pnpm link

# In packages/setup
pnpm build
pnpm link --global

# In another directory
authrim-setup --help

Troubleshooting

"Wrangler is not installed"

Install wrangler globally:

npm install -g wrangler
wrangler login

"Not logged in to Cloudflare"

Authenticate with Cloudflare:

wrangler login

"Lock file not found"

Run the init command first to provision resources:

authrim-setup init --env prod

"Port 3456 is already in use"

The tool automatically tries ports 3456-3465. If all are in use:

# Find process using the port
lsof -i :3456

# Kill the process
kill <PID>

# Or specify a different port
authrim-setup manage --port 4000

Deployment fails with "Service Bindings"

Ensure all dependent workers are deployed. The ar-router must be deployed last as it references other workers via Service Bindings.

License

Apache License 2.0 - see LICENSE for details.

@authrim/setup

Package Exports

Readme

@authrim/setup

Overview

Quick Start

Usage Modes

1. Web UI Mode (Default)

2. Environment Management Mode

3. CLI Mode

4. Deploy Existing Configuration

Commands

init (default)

manage

deploy

download

status

config

Web UI Features

Resource Provisioning

Real-time Progress

Environment Management

Configuration Files

authrim-config.json

authrim-lock.json

.keys/ Directory

Resource Naming Convention

Deployment Order

Initial Admin Setup

Security Features

Requirements

Development

Local Testing

Using with pnpm link

Troubleshooting

"Wrangler is not installed"

"Not logged in to Cloudflare"

"Lock file not found"

"Port 3456 is already in use"

Deployment fails with "Service Bindings"

License

Related

`init` (default)

`manage`

`deploy`

`download`

`status`

`config`