Plugin System Overview

The Authrim Plugin System provides a modular architecture for integrating external services and custom functionality into the Authrim identity platform. Plugins are bundled with Workers at deploy time, while their configuration can be resolved from environment bootstrap values and KV-backed global or tenant overrides.

What Plugins Can Do

Plugin Type	Capability Pattern	Examples
Notifier	notifier.{channel}	Email, SMS, Push notifications
Identity Provider	idp.{provider}	Google, SAML, OIDC federation
Authenticator	authenticator.{method}	TOTP, Passkey, OTP
Flow	flow.{name}	Custom authentication flow nodes (future)

Architecture

The plugin system follows a three-layer architecture that separates Worker request handling, plugin capability registration, and runtime infrastructure access:

flowchart TB
    subgraph Application["Application Layer"]
        direction LR
        A1[ar-auth]
        A2[ar-token]
        A3[ar-userinfo]
        A4[ar-management]
    end

    subgraph Plugin["Plugin Layer"]
        direction LR
        P1[Notifier<br/>email, sms, push]
        P2[IdP<br/>provider handlers]
        P3[Authenticator<br/>method handlers]
    end

    subgraph Infra["Infrastructure Layer"]
        direction LR
        I1[Storage Stores<br/>D1, KV, DO, tenant profiles]
        I2[Policy Infra<br/>ReBAC, ABAC]
    end

    Application -->|PluginContext| Plugin
    Plugin -->|store and policy interfaces| Infra

Layer Characteristics

Aspect	Plugin Layer	Infrastructure Layer
Switching	Deploy-time code, runtime config	Runtime storage profile or deployment resource change
Failure Impact	Usually limited to the capability using the plugin	Can affect shared storage, policy, or protocol state
Tenant Variance	Global defaults plus tenant overrides	Depends on the selected runtime storage profile
Configuration	Worker bootstrap env + KV config	.authrim, wrangler bindings, D1/KV/DO resources

Design Principles

Principle	Description
Hybrid Configuration	Static code bundling with bootstrap env and KV-based configuration
Type Safety	Full TypeScript support with Zod schema validation
Cloudflare Native	Designed for Workers and explicit deployment bindings
Multi-Tenant	Tenant-specific plugin configuration supported where the Worker loads the plugin

Cloudflare Workers Limitations

Since Authrim runs on Cloudflare Workers, plugin loading is intentionally explicit:

Important Constraints

• No runtime plugin marketplace loading: Authrim does not download or import arbitrary plugin code at request time
• Code Bundling Required: Plugins must be included in the Worker bundle that uses them
• Configuration Can Be Dynamic: Worker env values can bootstrap built-ins, then KV can provide global and tenant-specific overrides
• Maximum Nesting Depth: Configuration objects are limited to 20 levels for security

Trust Levels

Plugin trust is determined by distribution source, not metadata claims:

Trust Level	Source	UI Display
official	Built into ar-lib-plugin/builtin/	Authrim Official (Built-in)
official	npm @authrim/* scope	Authrim Official (npm)
community	Other npm packages or local files	Community Plugin

Community Plugin Disclaimer

Community plugins are provided by third parties. Authrim does not guarantee their security, reliability, or compatibility. Use at your own risk.

Built-in Plugins

Authrim currently registers these official notifier plugins for discovery. ar-auth bootstraps the email plugins from Worker env values when configured, then resolves KV overrides through the plugin context.

Plugin ID	Type	Description
notifier-console	Notifier	Console logger for development
notifier-cloudflare	Notifier	Cloudflare Email Service binding
notifier-resend	Notifier	Resend Email API

Authenticator and identity-provider plugin capabilities are part of the plugin API, but only notifier plugins are auto-registered for Admin UI discovery today. Register additional capability plugins explicitly in the Worker that uses them.

Plugin Lifecycle

┌─────────────────────────────────────────────────────────┐
│                   Plugin Lifecycle                       │
├─────────────────────────────────────────────────────────┤
│  1. RESOLVE CONFIG                                       │
│     ├── Merge bootstrap env, global KV, tenant KV         │
│     └── Validate config against schema                   │
├─────────────────────────────────────────────────────────┤
│  2. INITIALIZE (optional)                                │
│     ├── Connect to external services                     │
│     ├── Warm up caches                                   │
│     └── Validate dependencies                            │
├─────────────────────────────────────────────────────────┤
│  3. REGISTER                                             │
│     ├── Register capabilities with registry              │
│     └── Must be synchronous, no side effects             │
├─────────────────────────────────────────────────────────┤
│  4. ACTIVE                                               │
│     └── Plugin handles requests via registered handlers  │
├─────────────────────────────────────────────────────────┤
│  5. HEALTH / ADMIN INSPECTION                            │
│     ├── Expose schema and status                         │
│     └── Report dependency health when implemented         │
└─────────────────────────────────────────────────────────┘

Next Steps

• Creating Plugins - Build your first Authrim plugin
• Plugin Capabilities - Implement handlers for each capability type
• Configuration Schema - Define and validate plugin configuration
• Deployment & Distribution - Package and publish your plugin
• Admin UI Management - Manage plugins through the Admin Console
• Plugin Management API - API reference for plugin management