devise-api 0.2.0 → 0.3.0

data/docs/architecture.md

@@ -0,0 +1,145 @@
+# Architecture
+
+`devise-api` is a Rails engine gem that adds opaque-token API authentication (access + refresh tokens) on top of [Devise](https://github.com/heartcombo/devise). It plugs into Devise's own extension mechanism: it registers an `:api` module via `Devise.add_module`, so host models opt in with `devise :api` and routes appear automatically through `devise_for`.
+
+## Core invariants
+
+These two decisions shape every file in the gem:
+
+1. **One global configuration object.** `Devise.api` (installed in `lib/devise/api.rb` as a `mattr_accessor` holding a `Devise::Api::Configuration` instance) is the single source of truth. Every tunable — token TTLs, generators, callbacks, header names, base classes — is read at *use time* from `Devise.api.config.*`. There is no per-model configuration.
+2. **Base classes are strings, resolved lazily.** `base_token_model` (default `'Devise::Api::Token'`) and `base_controller` (default `'::DeviseController'`) are stored as class *names* and `constantize`d at each use site. This lets host apps substitute subclasses without load-order problems. **Library code must never reference `Devise::Api::Token` directly** — always go through `Devise.api.config.base_token_model.constantize`.
+
+## Component map
+
+```mermaid
+graph TD
+    subgraph "Host Rails app"
+        RM["Model with `devise :api`"]
+        RT["routes.rb — devise_for :users"]
+        INIT["initializer — Devise.setup { config.api.configure }"]
+    end
+
+    subgraph "Routing layer"
+        MAP["ActionDispatch::Routing::Mapper#devise_api<br/>lib/devise/api/rails/routes.rb"]
+    end
+
+    subgraph "Controller layer"
+        TC["Devise::Api::TokensController<br/>app/controllers/devise/api/tokens_controller.rb"]
+        HLP["Controllers::Helpers (mixed into ALL ActionController)<br/>lib/devise/api/controllers/helpers.rb"]
+    end
+
+    subgraph "Service layer (dry-monads)"
+        SI["ResourceOwnerService::SignIn"]
+        SU["ResourceOwnerService::SignUp"]
+        AU["ResourceOwnerService::Authenticate"]
+        CR["TokensService::Create"]
+        RF["TokensService::Refresh"]
+        RV["TokensService::Revoke"]
+    end
+
+    subgraph "Response layer"
+        TR["Responses::TokenResponse"]
+        ER["Responses::ErrorResponse"]
+    end
+
+    subgraph "Persistence"
+        TK["Devise::Api::Token (AR model)<br/>devise_api_tokens table"]
+    end
+
+    CFG[("Devise.api.config<br/>Dry::Configurable")]
+
+    RT --> MAP --> TC
+    TC --> SI & SU & RF & RV
+    SI --> AU
+    SI --> CR
+    SU --> CR
+    RF --> CR
+    TC --> TR & ER
+    HLP --> TK
+    TC --> HLP
+    CR & RV --> TK
+    RM -- "has_many :access_tokens" --> TK
+    INIT -.configures.-> CFG
+    CFG -.read at use time by.-> TC & TK & HLP & TR & ER & CR
+```
+
+## Boot / integration sequence
+
+What happens when a host app uses the gem — the "magic" is concentrated in `lib/devise/api.rb`:
+
+1. `require 'devise/api'` (via Bundler) loads configuration, responses, helpers, and generator.
+2. `Devise.api = Devise::Api::Configuration.new` installs the global config.
+3. `Devise::Models::Api` is defined: an `ActiveSupport::Concern` that adds `has_many :access_tokens` (polymorphic `resource_owner`, `dependent: :destroy`) and the class method `supported_devise_modules` (a `devise_modules.inquiry` used throughout to feature-detect `trackable?` / `lockable?` / `confirmable?`).
+4. `Devise.add_module :api, strategy: false, controller: :tokens, route: { api: %i[revoke refresh sign_up sign_in info] }` registers the module with Devise. `strategy: false` means **no Warden strategy is registered** — authentication of API requests is done exclusively by the controller helpers, not by Warden middleware.
+5. `ActiveSupport.on_load(:action_controller)` includes `Devise::Api::Controllers::Helpers` into **every** controller, so `authenticate_devise_api_token!`, `current_devise_api_token`, and `current_devise_api_user` are available anywhere.
+6. `Devise::Api::Rails::Engine` (an isolated engine) makes `app/controllers` and `app/services` autoloadable.
+7. `lib/devise/api/rails/routes.rb` reopens `ActionDispatch::Routing::Mapper` to define `#devise_api`, which Devise's `devise_for` dispatches to (because of the `route:` key in step 4). It draws, under `/<scope>/tokens` (path segment and controller both overridable):
+   - `POST sign_up`, `POST sign_in`, `POST refresh`, `POST revoke`, `GET info`
+
+## Request lifecycle
+
+Every `TokensController` action follows the same template — **callback → service → response**:
+
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant TC as TokensController
+    participant CB as Config callbacks
+    participant S as Service (dry-monads)
+    participant R as TokenResponse / ErrorResponse
+
+    C->>TC: POST /users/tokens/sign_in
+    TC->>CB: before_sign_in.call(params, request, resource_class)
+    TC->>S: ResourceOwnerService::SignIn.new(params:, resource_class:).call
+    alt Success(token)
+        S-->>TC: Success(Devise::Api::Token)
+        TC->>TC: call_devise_trackable! (if trackable)
+        TC->>R: TokenResponse.new(request, token:, action: :sign_in)
+        TC->>CB: after_successful_sign_in.call(owner, token, request)
+        TC-->>C: 200 { token, refresh_token, expires_in, token_type, resource_owner }
+    else Failure(hash)
+        S-->>TC: Failure(error: :invalid_authentication, record: user)
+        TC->>R: ErrorResponse.new(request, resource_class:, **failure)
+        TC-->>C: 401/400/422 { error, error_description, lockable?, confirmable? }
+    end
+```
+
+Key details:
+
+- The controller inherits from `Devise.api.config.base_controller.constantize` (default `::DeviseController`), so Devise's `resource_class` (derived from the route scope, e.g. `devise_for :users` → `User`) is available for free. CSRF verification is skipped; `wrap_parameters false`.
+- Services return `Success(token)` or `Failure(hash)` where the hash is `{ error: <symbol>, record: <model or nil> }` — splatted directly into `ErrorResponse.new`. The error symbol must exist in `ErrorResponse::ERROR_TYPES` and have a locale entry.
+- Only `info` runs `authenticate_devise_api_token!`. `revoke` and `refresh` look up the token themselves and respond based on what they find (`revoke` with an unknown token still returns `204`).
+- `refresh` looks tokens up **by `refresh_token` column**, everything else by `access_token` column — same extraction logic (`find_devise_api_token`), different lookup.
+
+## Token extraction
+
+`Controllers::Helpers#find_devise_api_token` honors `Devise.api.config.authorization.location`:
+
+- `:header` — `request.headers['Authorization']`, stripping the `'Bearer '` scheme prefix (both header name and scheme configurable)
+- `:params` — `params['access_token']` (key configurable)
+- `:both` (default) — params first, then header
+
+## Directory layout (engine-loaded vs require-loaded)
+
+```
+app/                                  # autoloaded via the engine
+  controllers/devise/api/tokens_controller.rb
+  services/devise/api/                # BaseService + 2 service namespaces
+lib/devise/api.rb                     # entry point: module registration, global config
+lib/devise/api/
+  configuration.rb                    # Dry::Configurable settings tree
+  token.rb                            # ActiveRecord model (required at load, NOT autoloaded)
+  controllers/helpers.rb              # mixed into ActionController
+  responses/{token,error}_response.rb # plain Ruby response builders
+  rails/{engine,routes}.rb
+  generators/install_generator.rb     # rails g devise_api:install
+  generators/templates/migration.rb.erb
+config/locales/en.yml                 # all user-facing strings (devise.api.error_response.*)
+spec/dummy/                           # full Rails 7 host app used by the test suite
+```
+
+## Dependency notes
+
+- **dry-rb stack** (`dry-configurable`, `dry-initializer`, `dry-monads`, `dry-types`): configuration + service objects. `BaseService` defines the shared `Types` module (`include Dry.Types()`).
+- **devise** `>= 4.7.2`: model registration, `find_for_authentication`, `valid_password?`, `friendly_token`, lockable/confirmable/trackable integration.
+- **rails** `>= 6.0`, Ruby `>= 2.7`.

data/docs/configuration.md

@@ -0,0 +1,84 @@
+# Configuration Reference
+
+All settings live on the single global `Devise.api.config`, a `Dry::Configurable` tree defined in `lib/devise/api/configuration.rb`. Host apps configure it inside `Devise.setup`:
+
+```ruby
+# config/initializers/devise.rb
+Devise.setup do |config|
+  config.api.configure do |api|
+    api.access_token.expires_in = 30.minutes
+  end
+end
+```
+
+Settings are read **at use time**, never cached at boot — changing them (e.g. in a test) takes effect immediately.
+
+## `access_token`
+
+| Setting | Default | Type | Consumed by |
+|---|---|---|---|
+| `expires_in` | `1.hour` | `ActiveSupport::Duration` | `TokensService::Create` (stored per-row as integer seconds), `Token#expired?` via stored `expires_in` |
+| `expires_in_infinite` | `proc { \|owner\| false }` | proc → bool | `Token#expired?` (skips expiry check) and the `expires_in` presence validation |
+| `generator` | `proc { \|owner\| Devise.friendly_token(60) }` | proc → String | `Token.generate_uniq_access_token` (looped until unique) |
+
+## `refresh_token`
+
+| Setting | Default | Type | Consumed by |
+|---|---|---|---|
+| `enabled` | `true` | bool | refresh action gate, `refresh_token` presence validation, `TokenResponse` (omits field), `Token.generate_uniq_refresh_token` (returns `nil` when disabled) |
+| `expires_in` | `1.week` | Duration | `Token#refresh_token_expired?` — computed from `created_at`, **not stored per-row** (a config change retroactively affects existing tokens) |
+| `expires_in_infinite` | `proc { \|owner\| false }` | proc → bool | `Token#refresh_token_expired?` |
+| `generator` | `proc { \|owner\| Devise.friendly_token(60) }` | proc → String | `Token.generate_uniq_refresh_token` |
+| `rotation_enabled` | `false` | bool | `TokensService::Refresh` (revokes the presented token in the same transaction as minting the new one) and the `refresh` action's reuse detection (a rotated/revoked refresh token presented again triggers `Token#revoke_family!`) |
+
+## `sign_up`
+
+| Setting | Default | Consumed by |
+|---|---|---|
+| `enabled` | `true` | `sign_up` action gate (→ `sign_up_disabled` error) |
+| `extra_fields` | `[]` | permitted sign-up params **and** extra keys in the `resource_owner` response object (both directions!) |
+
+## `error_response`
+
+| Setting | Default | Consumed by |
+|---|---|---|
+| `verbose_account_state` | `true` | `ErrorResponse` — when `false`, the `lockable`/`confirmable` metadata blocks are omitted from error bodies (the locked/unconfirmed `error_description` specialization is kept) |
+
+## `paranoid`
+
+| Setting | Default | Consumed by |
+|---|---|---|
+| `paranoid` | `false` | `Authenticate` (unknown account returns `invalid_authentication` instead of `invalid_email`/`invalid_login`) and `ErrorResponse` (always the generic description, never lockable/confirmable details). Mirrors Devise's `config.paranoid`: makes existent and non-existent accounts indistinguishable to callers. |
+
+## `authorization`
+
+| Setting | Default | Consumed by |
+|---|---|---|
+| `key` | `'Authorization'` | header name read by `extract_devise_api_token_from_headers` |
+| `scheme` | `'Bearer'` | prefix stripped from the header; echoed as `token_type` in responses |
+| `location` | `:both` | `:header`, `:params`, or `:both` (params win); anything else raises `ArgumentError` |
+| `params_key` | `'access_token'` | param name read by `extract_devise_api_token_from_params` |
+
+## Base classes (string names, `constantize`d at use sites)
+
+| Setting | Default | Notes |
+|---|---|---|
+| `base_token_model` | `'Devise::Api::Token'` | Used for the `has_many :access_tokens` class name, all token lookups, association class names inside `Token` itself, and uniqueness checks in the generators. Subclass `Devise::Api::Token` and point this at it. |
+| `base_controller` | `'::DeviseController'` | Superclass of `TokensController`, resolved **at class-definition time** — must be set before the controller is first loaded. |
+
+## Lifecycle callbacks
+
+All default to no-op procs. Called by `TokensController` around each action:
+
+| Setting | Signature | Timing |
+|---|---|---|
+| `before_sign_in` | `(params, request, resource_class)` | before `SignIn` service |
+| `before_sign_up` | `(params, request, resource_class)` | after the enabled-gate, before `SignUp` service |
+| `before_refresh` | `(token, request)` | after token found & not revoked, before `Refresh` service |
+| `before_revoke` | `(token, request)` | before `Revoke` service (token may be `nil`) |
+| `after_successful_sign_in` | `(resource_owner, token, request)` | after success, before render |
+| `after_successful_sign_up` | `(resource_owner, token, request)` | after success, before render |
+| `after_successful_refresh` | `(resource_owner, token, request)` | after success, before render |
+| `after_successful_revoke` | `(resource_owner_or_nil, token, request)` | after success, before render |
+
+`before_*` return values are ignored — they cannot halt the request (raise if you need to abort, or use a controller `before_action` in a subclassed controller).

data/docs/data-model.md

@@ -0,0 +1,80 @@
+# Data Model
+
+One table, one model: `Devise::Api::Token` (`lib/devise/api/token.rb`) backed by `devise_api_tokens`. The resource owner (User, Customer, …) is polymorphic, so multiple Devise models share the table.
+
+## Schema
+
+From the generator template (`lib/devise/api/generators/templates/migration.rb.erb`); primary/foreign key types follow the host app's generator config (UUID-safe):
+
+| Column | Type | Null | Index | Notes |
+|---|---|---|---|---|
+| `resource_owner_type` / `resource_owner_id` | string / fk | no | composite | polymorphic owner |
+| `access_token` | string | no | yes, **unique** | opaque token, stored **in plaintext** |
+| `refresh_token` | string | yes | yes, **unique** | `nil` when refresh disabled |
+| `expires_in` | integer | no | — | access-token TTL in seconds, snapshotted at creation |
+| `revoked_at` | datetime | yes | — | non-nil ⇒ revoked |
+| `previous_refresh_token` | string | yes | yes | links a token to the refresh token it was minted from |
+| `created_at` / `updated_at` | datetime | no | — | expiry math is based on `created_at` |
+
+Uniqueness is enforced in three layers: unique DB indexes on `access_token`/`refresh_token` (the backstop), ActiveRecord uniqueness validations, and generate-and-retry loops (`generate_uniq_access_token` / `generate_uniq_refresh_token`). If a concurrent insert still hits the index, `TokensService::Create` rescues `ActiveRecord::RecordNotUnique` and retries with a fresh token (up to 3 attempts). Installs created before the unique indexes shipped should add them via migration (see CHANGELOG).
+
+## Entity relationships
+
+```mermaid
+erDiagram
+    RESOURCE_OWNER ||--o{ DEVISE_API_TOKEN : "has_many :access_tokens (dependent: destroy)"
+    DEVISE_API_TOKEN |o--o{ DEVISE_API_TOKEN : "previous_refresh -> refreshes"
+
+    DEVISE_API_TOKEN {
+        string access_token
+        string refresh_token
+        int expires_in
+        datetime revoked_at
+        string previous_refresh_token
+    }
+```
+
+The self-reference is keyed on token *strings*, not ids: `belongs_to :previous_refresh` joins `previous_refresh_token → refresh_token`; `has_many :refreshes` is the inverse. A refresh chain is therefore walkable in both directions.
+
+## Token lifecycle
+
+```mermaid
+stateDiagram-v2
+    [*] --> active : sign_in / sign_up / refresh (TokensService::Create)
+    active --> expired : now > created_at + expires_in
+    active --> revoked : revoke (revoked_at set)
+    expired --> refreshable : refresh_token still valid
+    note right of refreshable
+        refresh mints a NEW row with
+        previous_refresh_token = old refresh_token.
+        Default: the old row is NOT revoked or deleted.
+        With rotation_enabled: the old row is revoked.
+    end note
+    refreshable --> [*]
+```
+
+Predicates on `Token`:
+
+- `expired?` — `Time.current > created_at + expires_in.seconds`, unless `access_token.expires_in_infinite.(owner)`. The per-row `expires_in` snapshot means config changes only affect *new* tokens.
+- `refresh_token_expired?` — `Time.current > created_at + Devise.api.config.refresh_token.expires_in.seconds`, unless infinite. **Not** snapshotted — reads current config, so changing `refresh_token.expires_in` retroactively re-times existing tokens.
+- `revoked?` — `revoked_at.present?`. `active?` = not expired and not revoked.
+
+Mutators: `revoke!` (stamps `revoked_at`, idempotent) and `revoke_family!` (walks to the chain root via `previous_refresh`, then revokes the root and every descendant via `refreshes` — used by refresh-token reuse detection).
+
+The model also filters `access_token`/`refresh_token`/`previous_refresh_token` from `#inspect` via `filter_attributes`, and the engine adds the same keys to the host app's `filter_parameters` (request-log redaction). Raw SQL logging can still print token values.
+
+## Refresh semantics (important)
+
+`TokensService::Refresh`:
+
+1. Controller finds the row by `refresh_token` column; rejects unknown (`invalid_refresh_token`, 400) or revoked (`revoked_token`, 401) tokens.
+2. With `refresh_token.rotation_enabled`, a presented token that is revoked **or already has `refreshes`** is treated as reuse: the whole family is revoked (`revoke_family!`) and `revoked_token` is returned.
+3. Service rejects if `refresh_token_expired?` (`expired_refresh_token`).
+4. Otherwise mints a **new** token row (`previous_refresh_token` = the presented refresh token) and returns it. With rotation enabled, the presented token is revoked in the same transaction.
+5. **Without rotation (the default)** the old row keeps its state: its access token stays usable until its own expiry, and its refresh token **can be presented again** until the refresh-token TTL passes — see [analysis/security-review.md](analysis/security-review.md) (SEC-2, resolved via the opt-in flag).
+
+Revoking (`TokensService::Revoke`) only stamps `revoked_at` on the *presented access token's row* — not the whole chain, and not other sessions.
+
+## Cleanup
+
+Nothing prunes dead rows. Expired/revoked tokens accumulate until the resource owner is destroyed (`dependent: :destroy`). Host apps that care should add their own sweep job (candidate future feature).

data/docs/development.md

@@ -0,0 +1,52 @@
+# Development Guide
+
+## Setup
+
+```bash
+bin/setup            # bundle install (+ any local setup)
+bin/console          # IRB with the gem loaded
+```
+
+Requirements: Ruby >= 2.7 (CI tests 2.7–3.2), Bundler. The test suite needs no external services (sqlite3 in-repo dummy app).
+
+## Everyday commands
+
+```bash
+bundle exec rake                 # DEFAULT task = rspec + rubocop; the pre-push check
+bundle exec rake rspec           # tests only
+bundle exec rubocop              # lint only (or: bundle exec rubocop -a for safe autocorrect)
+bundle exec rubocop --config .rubocop.yml --parallel   # exactly what CI runs
+```
+
+Style highlights (`.rubocop.yml`): target Ruby 2.7, single quotes, 120-char lines, `Style/Documentation` off, method/ABC limits at 30. The codebase currently has no `rubocop:disable` comments — prefer refactoring (extracted helpers, constants) over adding them.
+
+## Repo conventions
+
+- Every Ruby file starts with `# frozen_string_literal: true`.
+- Library code resolves the token model and controller through `Devise.api.config` — see the invariants in [architecture.md](architecture.md).
+- User-facing strings live in `config/locales/en.yml` only (keys under `devise.api.error_response`). The install generator copies this file into host apps as `devise_api.en.yml` — additions are picked up by new installs automatically, but existing apps keep their copied version.
+- Commit style in history: conventional-commit-ish prefixes (`feat:`, `fix:`, `docs:`) with PR number suffix, e.g. `fix: nil memoization (#48)`.
+
+## Versioning & release
+
+- Version constant: `lib/devise/api/version.rb` (currently `0.2.0`). SemVer intent; still pre-1.0 so minor bumps may break.
+- `CHANGELOG.md` exists but has not been maintained past the initial release — update it as part of any release work.
+- Release flow (maintainer): bump `version.rb` → update CHANGELOG → `bundle exec rake release` (tags, pushes, publishes to rubygems.org). Gem files are `git ls-files` minus `bin|test|spec|features` (see gemspec) — nothing in `spec/dummy` ships.
+
+## CI
+
+Two workflows on every push, matrix over Ruby 2.7.7 / 3.0.5 / 3.1.3 / 3.2.0:
+
+- `test.yml` — `bundle install` + `bundle exec rake rspec`
+- `rubocop.yml` — `bundle exec rubocop --config .rubocop.yml --parallel`
+
+SimpleCov coverage runs with the suite (95% line minimum enforced on full-suite runs — see [testing.md](testing.md)). No scheduled builds, no release automation.
+
+## Pointers for common change types
+
+| Change | Touch points |
+|---|---|
+| New endpoint action | `rails/routes.rb`, `Devise.add_module` route list in `lib/devise/api.rb`, controller, service, `TokenResponse::ACTIONS`, request specs, [api-reference.md](api-reference.md) |
+| New error type | service, `ErrorResponse::ERROR_TYPES` + `#status` mapping, `config/locales/en.yml`, specs, [api-reference.md](api-reference.md) |
+| New config setting | `configuration.rb`, use site(s), `configuration_spec.rb`, README config block, [configuration.md](configuration.md) |
+| Schema change | generator template, dummy migrations + schema, `Token` model, upgrade migration guidance, [data-model.md](data-model.md) |

data/docs/extending.md

@@ -0,0 +1,75 @@
+# Extending & Customization Points
+
+Supported ways for a host app to change behavior, ordered from lightest to heaviest. Everything here is exercised by the test suite or README examples — treat as public API.
+
+## 1. Configuration
+
+Most behavior is a config knob — TTLs, generators, header/param names, callbacks, sign-up fields. See [configuration.md](configuration.md). The `before_*` / `after_successful_*` procs cover most "hook into the flow" needs without subclassing.
+
+## 2. Custom routes / controller per scope
+
+```ruby
+devise_for :customers,
+           controllers: { tokens: 'customers/api/tokens' },  # controller override
+           path: 'accounts'                                   # path scope override
+```
+
+The `:tokens` key is read by `Mapper#devise_api` (`lib/devise/api/rails/routes.rb`). The path segment itself comes from `mapping.path_names.fetch(:tokens, 'tokens')`, so `devise_for :users, path_names: { tokens: 'sessions' }` renames the `/tokens` segment. Covered by `spec/routing/customized_routes_spec.rb`.
+
+The custom controller should subclass `Devise::Api::TokensController` (the dummy app's `spec/dummy/app/controllers/devise/api/customized_tokens_controller.rb` is the reference example).
+
+## 3. Response decorators
+
+Response classes are plain Ruby — `prepend` a module to reshape payloads:
+
+```ruby
+module Devise::Api::Responses::TokenResponseDecorator
+  def body
+    default_body.merge(roles: resource_owner.roles)
+  end
+end
+
+Devise::Api::Responses::TokenResponse.prepend Devise::Api::Responses::TokenResponseDecorator
+```
+
+Same pattern works for `ErrorResponse`. Useful methods to override: `body`, `default_body`, `default_resource_owner`, `status`.
+
+## 4. Custom token model
+
+Subclass and point config at it (as a **string**):
+
+```ruby
+class ApiToken < Devise::Api::Token
+  # scopes, extra columns, etc.
+end
+
+Devise.setup do |config|
+  config.api.configure { |api| api.base_token_model = 'ApiToken' }
+end
+```
+
+Every lookup, association, and generator in the gem resolves through `Devise.api.config.base_token_model.constantize`, so the subclass is used everywhere consistently.
+
+## 5. Custom base controller
+
+`api.base_controller = 'Api::BaseController'` changes what `TokensController` inherits from. Caveat: the superclass is resolved when `TokensController` is first loaded, so set it in the Devise initializer (before any request). The base must provide Devise's controller API (`resource_class` etc.) — subclassing `DeviseController` or including its behavior is the safe route.
+
+## 6. Custom services in the host app
+
+`Devise::Api::BaseService` is designed to be inherited by host-app services (dry-initializer options + dry-monads). See README "Using devise base services". This is additive — the gem never calls host services.
+
+## Protected-endpoint integration (the common case)
+
+```ruby
+class Api::V1::BaseController < ActionController::Base
+  skip_before_action :verify_authenticity_token, raise: false
+  before_action :authenticate_devise_api_token!
+end
+```
+
+Helpers available in **every** controller (mixed in on load): `authenticate_devise_api_token!`, `current_devise_api_token`, `current_devise_api_user`, `current_devise_api_refresh_token`.
+
+## What is NOT a supported extension point
+
+- Reaching into `Devise::Api::Token` by constant from library code (breaks `base_token_model` substitution).
+- Per-model/per-scope configuration — config is global; two Devise scopes share TTLs, callbacks, and token model. If you need per-scope behavior, branch inside the callback procs (they receive `resource_class`/`resource_owner`).

data/docs/services.md

@@ -0,0 +1,72 @@
+# Service Layer Contracts
+
+All services live in `app/services/devise/api/` and inherit `Devise::Api::BaseService`, which wires:
+
+- **dry-initializer** — declare inputs with `option :name, type: Types::X`
+- **dry-monads** — `Success` / `Failure` returns, do-notation (`yield another_service_call` unwraps a `Success` or short-circuits the whole `call` with the inner `Failure`)
+- a shared `Types` module (`include Dry.Types()`)
+
+## Universal contract
+
+```
+service = SomeService.new(**options).call
+service.success? → service.success  # a Devise::Api::Token (or resource owner for Authenticate)
+service.failure? → service.failure  # { error: Symbol, record: <AR model or nil> }
+```
+
+The failure hash is splatted straight into `ErrorResponse.new(request, resource_class:, **failure)`, so:
+- `error:` **must** be a symbol from `ErrorResponse::ERROR_TYPES` with a locale entry (see [api-reference.md](api-reference.md)).
+- `record:` (optional) supplies validation messages and lockable/confirmable context.
+
+## Composition graph
+
+```mermaid
+graph LR
+    SignIn --> Authenticate
+    SignIn --> Create
+    SignUp --> Create
+    Refresh --> Create
+    Revoke
+```
+
+## ResourceOwnerService
+
+### `Authenticate`
+- **Inputs:** `params: Types::Hash`, `resource_class: Types::Class`
+- **Logic:** `find_for_authentication(params.slice(*authentication_keys))` → `valid_for_authentication? { valid_password? }` (increments `failed_attempts` for lockable) → `active_for_authentication?` (fails for locked/unconfirmed).
+- **Success:** the resource owner. **Failures:** no record → `:invalid_email` when `:email` is an authentication key, `:invalid_login` otherwise, or `:invalid_authentication` when `paranoid` is enabled (all with `record: nil`); wrong password / inactive account → `:invalid_authentication` (record attached).
+
+### `SignIn`
+- **Inputs:** `params`, `resource_class`
+- **Logic:** `Authenticate` → `TokensService::Create`; resets lockable failed attempts on success.
+- **Success:** the new `Devise::Api::Token`. **Failures:** propagated from children.
+
+### `SignUp`
+- **Inputs:** `params`, `resource_class`
+- **Logic:** inside a DB transaction: `resource_class.new(params).save` → `TokensService::Create`.
+- **Success:** the new token. **Failures:** `:resource_owner_create_error` (record attached) or propagated. The transaction works because do-notation's `yield` raises `Dry::Monads::Do::Halt` on a `Failure` — the exception unwinds through the `transaction` block (rolling back the already-saved user if token creation fails) before the `Do` wrapper converts it back into the `Failure` return value.
+
+### `TokensService`
+
+### `Create`
+- **Inputs:** `resource_owner` (untyped), `previous_refresh_token: String | Nil = nil`
+- **Logic:** guards `resource_owner.respond_to?(:access_tokens)` → builds row with generated unique access/refresh tokens, `expires_in` snapshot from config, `previous_refresh_token` passthrough. Rescues `ActiveRecord::RecordNotUnique` from the unique token indexes and retries with freshly generated tokens (`MAX_TOKEN_GENERATION_ATTEMPTS = 3`), then re-raises.
+- **Success:** the token. **Failures:** `:invalid_resource_owner`, `:devise_api_token_create_error`.
+
+### `Refresh`
+- **Inputs:** `devise_api_token` (typed `Types.Instance(<base_token_model>)` — resolved at class load), `resource_owner` (defaults to the token's owner)
+- **Logic:** reject if `refresh_token_expired?` → `Create` with `previous_refresh_token` set. With `refresh_token.rotation_enabled`, the new token is minted and the presented token revoked in one transaction (a `Create` failure rolls back and leaves the presented token untouched); otherwise the old token is **not** revoked.
+- **Failures:** `:expired_refresh_token` or propagated.
+
+### `Revoke`
+- **Inputs:** `devise_api_token` (optional — may be `nil`)
+- **Logic:** blank token → `Success(nil)`; already revoked/expired → `Success(token)` (idempotent); else stamp `revoked_at = Time.current`.
+- **Failures:** `:devise_api_token_revoke_error`.
+
+## Conventions for new services
+
+1. Inherit `Devise::Api::BaseService`; declare inputs with `option` + `Types`.
+2. Return `Success(value)` / `Failure(error: :symbol, record: model_or_nil)` — never raise for expected outcomes.
+3. New error symbols require: `ERROR_TYPES` entry, status mapping in `ErrorResponse#status`, locale string, api-reference row.
+4. Compose via do-notation (`yield`), not manual `if service.success?` nesting.
+5. Cover behavior with both request specs and service unit specs asserting the monad contract (see `spec/services/**`).

data/docs/testing.md

@@ -0,0 +1,65 @@
+# Testing Guide
+
+## Commands
+
+```bash
+bundle exec rake            # rspec + rubocop — what CI runs; run before finishing any change
+bundle exec rake rspec      # full suite
+bundle exec rspec spec/requests/tokens_spec.rb          # one file
+bundle exec rspec spec/requests/tokens_spec.rb:95       # one example/context by line
+bundle exec rspec --only-failures                       # uses .rspec_status
+```
+
+CI (`.github/workflows/test.yml`, `rubocop.yml`) runs on push across Ruby 2.7 / 3.0 / 3.1 / 3.2.
+
+## Coverage
+
+SimpleCov runs automatically with every spec run (started at the top of `spec/spec_helper.rb`, before the gem
+is required); the HTML report lands in `coverage/index.html` and the summary in `coverage/.last_run.json`.
+A **95% line-coverage minimum** is enforced whenever `CI` or `ENFORCE_COVERAGE` is set — `bundle exec rake`
+sets `ENFORCE_COVERAGE` via the `enforce_coverage` prerequisite task, so full-suite runs (local and CI) fail
+below the bar while single-file `bundle exec rspec` runs stay unaffected. Branch coverage is reported but not
+enforced. `lib/devise/api/version.rb` is filtered because the gemspec loads it before SimpleCov can start.
+
+## How the suite is wired
+
+- `spec/spec_helper.rb` sets `RAILS_ENV=test`, starts SimpleCov, requires the gem, then boots the **dummy Rails app** at `spec/dummy` (`require 'dummy/config/environment'`) — a real Rails 7 app with sqlite3 whose `User` model enables `database_authenticatable, registerable, recoverable, rememberable, validatable, confirmable, lockable, trackable, :api` (schema: `spec/dummy/db/schema.rb`). A second bare model, `AdminUser` (`database_authenticatable, registerable, validatable, :api` only), exists to exercise the "optional Devise module not enabled" branches (non-trackable sign-in, error/token responses without `lockable`/`confirmable` info); it has its own `devise_for :admin_users` routes.
+- `DatabaseCleaner` wraps every example; spec types are inferred from file location; monkey-patching is disabled (`RSpec.describe` only).
+- `spec/supports/` is auto-required: FactoryBot setup, ActiveRecord config, and two request-spec helpers:
+  - `authentication_headers_for(owner, token = nil, token_type = :access_token)` → `{ Authorization: "Bearer …" }` (creates a token via FactoryBot when none given; pass `:refresh_token` to authenticate refresh calls)
+  - `parsed_body` → `JSON.parse(response.body, object_class: OpenStruct)` (assert with `parsed_body.error`, etc.)
+
+## Factories (`spec/factories/`)
+
+- `:user` — Faker email/password.
+- `:admin_user` — Faker email/password (bare model without optional Devise modules).
+- `:devise_api_token` — random hex tokens, `expires_in: 1.hour`, associated `:user`. Traits: `:access_token_expired` (backdates `created_at` 2h), `:refresh_token_expired` (2 months), `:revoked`.
+
+Note the traits work by **backdating `created_at`** because all expiry math derives from it — keep that in mind when adding time-sensitive specs (or use `travel_to`).
+
+## Where coverage lives (map)
+
+| Area | Spec | State |
+|---|---|---|
+| All 5 endpoints × valid/invalid/expired/revoked × header/param | `spec/requests/tokens_spec.rb` (~700 lines) | ✅ primary coverage |
+| Endpoints for a bare model (no trackable/lockable/confirmable) | `spec/requests/admin_user_tokens_spec.rb` | ✅ |
+| `authenticate_devise_api_token!` on a host controller | `spec/requests/authentication_spec.rb` (via dummy `HomeController`) | ✅ |
+| Non-default config (disabled sign_up/refresh, extra_fields, `:header`/`:params`-only location, revoke failure) | `spec/requests/configuration_overrides_spec.rb` | ✅ |
+| Refresh-token rotation + family-revocation reuse detection (`rotation_enabled`) | `spec/requests/refresh_token_rotation_spec.rb` | ✅ |
+| Enumeration hardening (`paranoid`, `error_response.verbose_account_state`) | `spec/requests/paranoid_mode_spec.rb` | ✅ |
+| Engine initializer (`filter_parameters`) | `spec/devise/api/engine_spec.rb` | ✅ |
+| Default + customized routes (`controllers:`, `path:`, `path_names:` overrides) | `spec/routing/*.rb` | ✅ |
+| Config defaults + overrides on fresh instances | `spec/devise/api/configuration_spec.rb` | ✅ |
+| Response classes (incl. locked/unconfirmed/bare-model variants, disabled refresh, extra_fields) | `spec/devise/api/responses/*_spec.rb` | ✅ |
+| **Service objects** (monad contract: `Success`/`Failure` per branch) | `spec/services/**` | ✅ |
+| Token model (`active?`, expiry incl. `expires_in_infinite`, generator collision retry, conditional validations, `revoke!`/`revoke_family!`, unique-index backstop, `#inspect` redaction) | `spec/devise/api/token_spec.rb` | ✅ |
+| Controller helpers (extraction rescue, invalid location `ArgumentError`, memoized refresh-token lookup) | `spec/devise/api/controllers/helpers_spec.rb` | ✅ |
+| Generator (migration template, locale copy) | `spec/devise/api/generators/install_generator_spec.rb` | ✅ |
+
+## Conventions for new specs
+
+1. **Behavior → request spec.** Follow the existing pattern in `tokens_spec.rb`: one `describe` per endpoint, `context` per scenario, assert status + `parsed_body` fields + DB side effects (`Devise::Api::Token.count`, `revoked_at`).
+2. When filling in service specs, test the monad contract: `.call` returns `Success(token)` / `Failure(error:, record:)` for each branch documented in [services.md](services.md).
+3. Config-dependent specs must restore config after (the global `Devise.api.config` leaks between examples — wrap changes in `around` blocks or reset in `after`).
+4. Routing specs that redraw routes must restore them (see `customized_routes_spec.rb` `after :all` reload pattern).
+5. RuboCop: `Metrics/BlockLength` is excluded for `spec/**/*_spec.rb` — long request specs are fine.

data/lib/devise/api/configuration.rb

@@ -18,6 +18,7 @@ module Devise
         setting :expires_in, default: 1.week, reader: true
         setting :generator, default: proc { |_resource_owner| ::Devise.friendly_token(60) }, reader: true
         setting :expires_in_infinite, default: proc { |_resource_owner| false }, reader: true
+        setting :rotation_enabled, default: false, reader: true
       end
 
       setting :sign_up, reader: true do
@@ -32,6 +33,12 @@ module Devise
         setting :params_key, default: 'access_token', reader: true
       end
 
+      setting :error_response, reader: true do
+        setting :verbose_account_state, default: true, reader: true
+      end
+
+      setting :paranoid, default: false, reader: true
+
       setting :base_token_model, default: 'Devise::Api::Token', reader: true
       setting :base_controller, default: '::DeviseController', reader: true
 

data/lib/devise/api/controllers/helpers.rb

@@ -32,13 +32,15 @@ module Devise
         end
 
         def current_devise_api_refresh_token
-          token = find_devise_api_token
+          return @current_devise_api_refresh_token if defined?(@current_devise_api_refresh_token)
 
-          Devise.api.config.base_token_model.constantize.find_by(refresh_token: token)
+          token = find_devise_api_token
+          devise_api_token_model = Devise.api.config.base_token_model.constantize
+          @current_devise_api_refresh_token = devise_api_token_model.find_by(refresh_token: token)
         end
 
         def current_devise_api_token
-          return @current_devise_api_token if @current_devise_api_token
+          return @current_devise_api_token if defined?(@current_devise_api_token)
 
           token = find_devise_api_token
           devise_api_token_model = Devise.api.config.base_token_model.constantize

data/lib/devise/api/generators/templates/migration.rb.erb

@@ -7,8 +7,8 @@ class CreateDeviseApiTables < ActiveRecord::Migration<%= migration_version %>
 
     create_table :devise_api_tokens, id: primary_key_type  do |t|
       t.belongs_to :resource_owner, null: false, polymorphic: true, index: true, type: foreign_key_type
-      t.string :access_token, null: false, index: true
-      t.string :refresh_token, null: true, index: true
+      t.string :access_token, null: false, index: { unique: true }
+      t.string :refresh_token, null: true, index: { unique: true }
       t.integer :expires_in, null: false
       t.datetime :revoked_at, null: true
       t.string :previous_refresh_token, null: true, index: true

data/lib/devise/api/rails/engine.rb

@@ -5,6 +5,12 @@ module Devise
     module Rails
       class Engine < ::Rails::Engine
         isolate_namespace Devise::Api
+
+        # Keep raw token secrets out of the host app's request logs (tokens can arrive as
+        # query/body params when authorization.location is :params or :both)
+        initializer 'devise.api.filter_parameters' do |app|
+          app.config.filter_parameters |= %i[access_token refresh_token previous_refresh_token]
+        end
       end
     end
   end