Plugin System Overview

The Authrim Plugin System provides a modular, extensible architecture for integrating external services and custom functionality into the Authrim identity platform.

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 concerns and provides clear boundaries:

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

    subgraph Plugin["Plugin Layer"]
        direction LR
        P1[Notifier
email, sms, push]
        P2[IdP
google, saml]
        P3[Authenticator
totp, passkey]
    end

    subgraph Infra["Infrastructure Layer"]
        direction LR
        I1[Storage
KV, D1, DO]
        I2[Policy Engine
ReBAC]
    end

    Application -->|PluginContext| Plugin
    Plugin -->|Storage/Policy| Infra

Layer Characteristics

Aspect	Plugin Layer	Infrastructure Layer
Switching	Dynamic (KV config)	Deploy-time (restart required)
Failure Impact	Only affected feature	Full system outage
Tenant Variance	Can differ per tenant	Usually shared
Configuration	Admin API + Admin UI	Environment variables

Design Principles

Principle	Description
Hybrid Configuration	Static code bundling with dynamic KV-based configuration
Type Safety	Full TypeScript support with Zod schema validation
Cloudflare Native	Optimized for Cloudflare Workers (no dynamic imports)
Multi-Tenant	Tenant-specific plugin configurations supported

Cloudflare Workers Limitations

Since Authrim runs on Cloudflare Workers, the plugin system has specific constraints:

Important Constraints

• No Dynamic Imports: Cloudflare Workers don’t support dynamic import()
• Code Bundling Required: All plugins must be statically bundled at deploy time
• Configuration Only Dynamic: Only configuration changes are dynamic (via KV)
• 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 includes these official plugins out of the box:

Plugin ID	Type	Description
notifier-console	Notifier	Console logger for development
notifier-resend	Notifier	Resend Email API
authenticator-totp	Authenticator	TOTP (RFC 6238)

Plugin Lifecycle

┌─────────────────────────────────────────────────────────┐
│                   Plugin Lifecycle                       │
├─────────────────────────────────────────────────────────┤
│  1. LOAD                                                 │
│     ├── Validate config against schema                   │
│     └── Create plugin instance                           │
├─────────────────────────────────────────────────────────┤
│  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. SHUTDOWN (optional)                                  │
│     ├── Close connections                                │
│     └── Cleanup resources                                │
└─────────────────────────────────────────────────────────┘

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