Plugin System Overview
Authrim has two related extension models: the bundled TypeScript plugin API and the Plugin Runner’s installation/capability model. They have different loading, configuration, and execution contracts.
Execution models
Section titled “Execution models”| Model | How code runs | Configuration / scope |
|---|---|---|
Bundled AuthrimPlugin | Imported into the Worker and registered through ar-lib-plugin | Zod schema, bootstrap configuration, and global/tenant overrides |
Runner in_process | A handler already present in the Runner’s registry | Installation and capability policy; a manifest alone does not create a handler |
Runner dynamic_worker | An approved bundle loaded through PLUGIN_LOADER from PLUGIN_BUNDLES in R2 | Tenant installation, pinned artifact/policy, scoped host interfaces and outbound access |
Dynamic loading is implemented. It is not arbitrary npm installation from the Admin UI: Setup discovers and validates manifests, publishes artifacts and policies, and the Runner verifies the selected artifact before execution.
Built-in discovery
Section titled “Built-in discovery”The built-in registry includes notifier and human-verification plugins:
notifier-console,notifier-cloudflare,notifier-resendhuman-verification-cloudflare-turnstilehuman-verification-google-recaptchahuman-verification-hcaptcha
Being listed does not mean a plugin is enabled or has usable credentials. TOTP and other interfaces in ar-lib-plugin must not be confused with automatic registration of every authenticator or provider.
Runner responsibilities
Section titled “Runner responsibilities”The Runner resolves tenant installations, handles synchronous hooks and asynchronous delivery, validates policy and version state, and limits external access. Notifications can use encrypted payload intents, with a reference carried through the asynchronous hook path.
Custom workers receive approved host interfaces and plugin-resource wrappers, not the parent Worker’s entire environment or unrestricted access to Core/PII. Plugin-owned D1, KV, and R2 resources have declared scope, access, and provisioning requirements.
Lifecycle
Section titled “Lifecycle”For a dynamic plugin: prepare manifest and bundle → publish through Setup → configure tenant credentials/resources → enable the installation → execute supported calls → observe failures and delivery state. Publishing a new artifact and rolling it out to existing installations are distinct actions.
Disabling stops use of an installation; uninstalling is a separate operation with resource cleanup handling. Neither should be described as deleting a package from a live Worker filesystem.