Use the documented configuration, generators and host hooks when integrating AddAuth. Check the release notes before updating a 0.x application.
This reference describes the published 0.2.2 integration surface. It does not announce a 1.0 release or a new support commitment. The maintained security support policy names the release line receiving fixes.
Supported environments
| Boundary | Verified scope |
|---|---|
| Ruby and Rails | Ruby 3.3, 3.4 and 4.0 with Rails 8.0 and 8.1. Use patched releases on maintained Ruby series. A permissive gem dependency is not evidence for an untested future Rails line. |
| Authentication database | SQLite and PostgreSQL have real store/request contracts. User, Session and installed AddAuth records must share one connection pool. Other adapters require their concurrency and rollback contracts to be verified. |
| Jobs | Durable Active Job delivery is required in production. Local acceptance covers Sidekiq/Redis and Solid Queue with a separate queue database. The queue recipe describes the boundary. |
| Abuse counters | A shared store must atomically initialize and increment counters with expiry across processes. Solid Cache is unsuitable for this role; use the separate counter configuration. |
| Browsers | Local Chrome acceptance covers Turbo, permitted no-JavaScript paths and virtual WebAuthn. Physical devices, hybrid ceremonies, other browsers and assistive technology need host-specific verification. |
Application integration surface
| Surface | Use and limits |
|---|---|
AddAuth.configure | The settings, callbacks, units and defaults in Configuration. Keep eligibility, trusted recovery addresses and resource authorization in the host. |
| Rails authentication integration | The generators extend the stock User, Session and Authentication concern. Preserve the generated inclusion order and hardened cookie/session hooks. Use require_add_auth_authentication to protect management routes in hosts that allow anonymous pages. |
| Reauthentication | require_elevated_session(purpose:, **options) guards navigation. with_elevated_session(purpose:) { ... } rechecks proof while performing the database mutation. Follow the complete write example; host authorization is still required. |
| Lifecycle | AddAuth::Rails::UserLifecycle invalidates proofs on normal password/address updates. Updates that skip callbacks need an explicit host invalidation procedure. Do not call its private callback as an API. |
| Routes and generated UI | The enabled paths and generators in Generators & commands. Ejected files remain host-owned; retain the baseline manifest and review upstream changes. There is no add_auth_for routing DSL or multi-realm registry. |
| Adapters | Documented digest and challenge contracts are extension points. WebAuthn signature verification is supplied by the WebAuthn library. Password verification uses the host’s Rails API. |
| Test helpers | AddAuth::Testing.delivered_link(mail, purpose:) and with_virtual_authenticator(driver, **options) { ... } are plain Ruby helpers. See Testing your integration. No framework-specific sign-in shortcut is promised. |
Results and monitoring
AddAuth::Result exposes success?, failure?, user, strategy, credential, reason, session and grant. Result inspection omits credential material; associated objects can still contain sensitive state. Never serialize a whole Result into logs or a public response. Internal failure reasons are mapped to deliberately generic public messages.
Use the documented maintenance and delivery events for monitoring. A completed bounded pass does not establish an empty backlog. Doctor checks configuration and known incompatibilities; its sequential cache probe cannot certify concurrent behavior or a live deployment.
Avoid coupling to internals
AddAuth::Rails::Runtime, store classes, private lifecycle callbacks, job payloads, cookie/token encodings and persistence implementation details are not general extension APIs. The plain Ruby Core separates policy from Rails; that architecture does not promise standalone packaging or compatibility for every constructor. Open a focused issue when a documented hook cannot support a reusable host need.
Next, use the upgrade rehearsal before changing an installed version.