Plugin Capabilities
Choose the execution model before implementing a handler. A bundled registry capability such as notifier.email is not the same contract as Runner notifier.send.
Bundled API
Section titled “Bundled API”ar-lib-plugin exposes registration methods for notifiers, IdPs, and authenticators. Built-in human-verification plugins provide configuration; their runtime checks use Authrim’s authentication/Runner paths. Use the actual types in core/types.ts and core/registry.ts; declaring a capability string alone does not connect a new handler to a login flow.
A notifier implements send(notification): Promise<SendResult>. The notification contains the channel, recipient, body, and optional email/template metadata. Results include success and optional messageId, errorCode, and retryable. Do not log notification bodies or credentials in a production handler.
Runner contracts
Section titled “Runner contracts”| Capability / group | Current contract |
|---|---|
notifier.send | Notification delivery; asynchronous invocation can reference a stored encrypted intent |
hook.account.lifecycle | Account-event hook; the installation resolver currently accepts account.created, not every conceivable lifecycle event |
human_verification.verify | Synchronous human-verification decision |
policy.decision | Synchronous policy decision |
flow.{hookName} | Synchronous flow hook for a supported calling path |
A capability must have a registered installation, compatible policy, and a real caller. Names permitted by a manifest do not automatically create new public endpoints or flow nodes.
Synchronous responses
Section titled “Synchronous responses”Dynamic synchronous hooks receive a JSON payload at /internal/plugin-sync/{group} with an X-Authrim-Plugin-Contract header. Successful responses use HTTP 200 and exactly these result fields:
{"decision":"deny","reasonCode":"policy_rejected"}Human-verification and policy groups allow allow or deny; flow hooks allow continue or deny. reasonCode uses the constrained code format defined by the Runner. Invalid responses, timeouts, and unavailable execution in SyncHookService resolve to denial. Do not advertise fail_open as universally supported merely because the manifest schema contains that value.
Asynchronous responses
Section titled “Asynchronous responses”The dynamic asynchronous endpoint is /internal/plugin-hook. The envelope includes tenant, installation, capability, event version, idempotency key, and a reference or resolved delivery payload. A successful handler returns HTTP 204. Failures enter the Runner’s retry/dead-letter policy rather than becoming a synchronous login response.
External effects must tolerate retries. Use the idempotency key with the downstream operation; returning 204 before the required effect succeeds can lose work.
Host access
Section titled “Host access”Approved interfaces and plugin resources are injected by the Runner. Account metadata writes use a dedicated scoped service with operation ID and expected version; they are not arbitrary SQL against the account database. Outbound requests pass through the gateway’s host and credential policy.
See Creating Plugins for a minimal contract example and Deployment for artifact publication.