devise-api 0.2.0 → 0.3.0

data/app/controllers/devise/api/tokens_controller.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-# rubocop:disable Metrics/ClassLength
 module Devise
   module Api
     class TokensController < Devise.api.config.base_controller.constantize
@@ -10,144 +9,94 @@ module Devise
 
       respond_to :json
 
-      # rubocop:disable Metrics/AbcSize
       def sign_up
-        unless Devise.api.config.sign_up.enabled
-          error_response = Devise::Api::Responses::ErrorResponse.new(request, error: :sign_up_disabled,
-                                                                              resource_class: resource_class)
-
-          return render json: error_response.body, status: error_response.status
-        end
+        return render_error_response(error: :sign_up_disabled) unless Devise.api.config.sign_up.enabled
 
         Devise.api.config.before_sign_up.call(sign_up_params, request, resource_class)
 
         service = Devise::Api::ResourceOwnerService::SignUp.new(params: sign_up_params,
                                                                 resource_class: resource_class).call
-
-        if service.success?
-          token = service.success
-
-          call_devise_trackable!(token.resource_owner)
-
-          token_response = Devise::Api::Responses::TokenResponse.new(request, token: token, action: __method__)
-
-          Devise.api.config.after_successful_sign_up.call(token.resource_owner, token, request)
-
-          return render json: token_response.body, status: token_response.status
-        end
-
-        error_response = Devise::Api::Responses::ErrorResponse.new(request,
-                                                                   resource_class: resource_class,
-                                                                   **service.failure)
-
-        render json: error_response.body, status: error_response.status
+        render_resource_owner_service_result(service, action: __method__)
       end
-      # rubocop:enable Metrics/AbcSize
 
-      # rubocop:disable Metrics/AbcSize
       def sign_in
         Devise.api.config.before_sign_in.call(sign_in_params, request, resource_class)
 
         service = Devise::Api::ResourceOwnerService::SignIn.new(params: sign_in_params,
                                                                 resource_class: resource_class).call
-
-        if service.success?
-          token = service.success
-
-          call_devise_trackable!(token.resource_owner)
-
-          token_response = Devise::Api::Responses::TokenResponse.new(request, token: service.success,
-                                                                              action: __method__)
-
-          Devise.api.config.after_successful_sign_in.call(token.resource_owner, token, request)
-
-          return render json: token_response.body, status: token_response.status
-        end
-
-        error_response = Devise::Api::Responses::ErrorResponse.new(request,
-                                                                   resource_class: resource_class,
-                                                                   **service.failure)
-
-        render json: error_response.body, status: error_response.status
+        render_resource_owner_service_result(service, action: __method__)
       end
-      # rubocop:enable Metrics/AbcSize
 
       def info
-        token_response = Devise::Api::Responses::TokenResponse.new(request, token: current_devise_api_token,
-                                                                            action: __method__)
-
-        render json: token_response.body, status: token_response.status
+        render_token_response(current_devise_api_token, action: __method__)
       end
 
-      # rubocop:disable Metrics/AbcSize
       def revoke
         Devise.api.config.before_revoke.call(current_devise_api_token, request)
 
         service = Devise::Api::TokensService::Revoke.new(devise_api_token: current_devise_api_token).call
+        return render_error_response(**service.failure) if service.failure?
 
-        if service.success?
-          token_response = Devise::Api::Responses::TokenResponse.new(request, token: service.success,
-                                                                              action: __method__)
-
-          Devise.api.config.after_successful_revoke.call(service.success&.resource_owner, service.success, request)
-
-          return render json: token_response.body, status: token_response.status
-        end
-
-        error_response = Devise::Api::Responses::ErrorResponse.new(request,
-                                                                   resource_class: resource_class,
-                                                                   **service.failure)
-
-        render json: error_response.body, status: error_response.status
+        token = service.success
+        Devise.api.config.after_successful_revoke.call(token&.resource_owner, token, request)
+        render_token_response(token, action: __method__)
       end
-      # rubocop:enable Metrics/AbcSize
 
-      # rubocop:disable Metrics/AbcSize
       def refresh
-        unless Devise.api.config.refresh_token.enabled
-          error_response = Devise::Api::Responses::ErrorResponse.new(request,
-                                                                     resource_class: resource_class,
-                                                                     error: :refresh_token_disabled)
-
-          return render json: error_response.body, status: error_response.status
-        end
+        return render_error_response(error: :refresh_token_disabled) unless Devise.api.config.refresh_token.enabled
+        return render_error_response(error: :invalid_refresh_token) if current_devise_api_refresh_token.blank?
+        return handle_refresh_token_reuse if refresh_token_reused?
+        return render_error_response(error: :revoked_token) if current_devise_api_refresh_token.revoked?
 
-        if current_devise_api_refresh_token.blank?
-          error_response = Devise::Api::Responses::ErrorResponse.new(request, error: :invalid_token,
-                                                                              resource_class: resource_class)
-
-          return render json: error_response.body, status: error_response.status
-        end
-
-        if current_devise_api_refresh_token.revoked?
-          error_response = Devise::Api::Responses::ErrorResponse.new(request, error: :revoked_token,
-                                                                              resource_class: resource_class)
+        perform_refresh
+      end
 
-          return render json: error_response.body, status: error_response.status
-        end
+      private
 
+      def perform_refresh
         Devise.api.config.before_refresh.call(current_devise_api_refresh_token, request)
 
         service = Devise::Api::TokensService::Refresh.new(devise_api_token: current_devise_api_refresh_token).call
+        return render_error_response(**service.failure) if service.failure?
 
-        if service.success?
-          token_response = Devise::Api::Responses::TokenResponse.new(request, token: service.success,
-                                                                              action: __method__)
+        token = service.success
+        Devise.api.config.after_successful_refresh.call(token.resource_owner, token, request)
+        render_token_response(token, action: :refresh)
+      end
 
-          Devise.api.config.after_successful_refresh.call(service.success.resource_owner, service.success, request)
+      def render_resource_owner_service_result(service, action:)
+        return render_error_response(**service.failure) if service.failure?
 
-          return render json: token_response.body, status: token_response.status
-        end
+        token = service.success
+        call_devise_trackable!(token.resource_owner)
+        Devise.api.config.public_send("after_successful_#{action}").call(token.resource_owner, token, request)
+        render_token_response(token, action: action)
+      end
 
-        error_response = Devise::Api::Responses::ErrorResponse.new(request,
-                                                                   resource_class: resource_class,
-                                                                   **service.failure)
+      def render_token_response(token, action:)
+        token_response = Devise::Api::Responses::TokenResponse.new(request, token: token, action: action)
+
+        render json: token_response.body, status: token_response.status
+      end
+
+      def render_error_response(**failure)
+        error_response = Devise::Api::Responses::ErrorResponse.new(request, resource_class: resource_class, **failure)
 
         render json: error_response.body, status: error_response.status
       end
-      # rubocop:enable Metrics/AbcSize
 
-      private
+      # A revoked or already-refreshed refresh token presented again while rotation is enabled means the
+      # token was leaked or replayed: revoke the whole token family (OAuth2 Security BCP).
+      def refresh_token_reused?
+        Devise.api.config.refresh_token.rotation_enabled &&
+          (current_devise_api_refresh_token.revoked? || current_devise_api_refresh_token.refreshes.exists?)
+      end
+
+      def handle_refresh_token_reuse
+        current_devise_api_refresh_token.revoke_family!
+
+        render_error_response(error: :revoked_token)
+      end
 
       def sign_up_params
         params.permit(*Devise.api.config.sign_up.extra_fields, *resource_class.authentication_keys,
@@ -164,15 +113,6 @@ module Devise
 
         resource_owner.update_tracked_fields!(request)
       end
-
-      def current_devise_api_refresh_token
-        return @current_devise_api_refresh_token if @current_devise_api_refresh_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
     end
   end
 end
-# rubocop:enable Metrics/ClassLength

data/app/services/devise/api/resource_owner_service/authenticate.rb

@@ -8,8 +8,8 @@ module Devise
         option :resource_class, type: Types::Class
 
         def call
-          resource = resource_class.find_for_authentication(email: params[:email])
-          return Failure(error: :invalid_email, record: nil) if resource.blank?
+          resource = resource_class.find_for_authentication(params.slice(*resource_class.authentication_keys))
+          return Failure(error: resource_not_found_error, record: nil) if resource.blank?
           return Failure(error: :invalid_authentication, record: resource) unless authenticate!(resource)
 
           Success(resource)
@@ -17,6 +17,13 @@ module Devise
 
         private
 
+        def resource_not_found_error
+          return :invalid_authentication if Devise.api.config.paranoid
+          return :invalid_email if resource_class.authentication_keys.map(&:to_sym).include?(:email)
+
+          :invalid_login
+        end
+
         def authenticate!(resource)
           resource.valid_for_authentication? do
             resource.valid_password?(params[:password])

data/app/services/devise/api/tokens_service/create.rb

@@ -4,6 +4,10 @@ module Devise
   module Api
     module TokensService
       class Create < Devise::Api::BaseService
+        # Retries after ActiveRecord::RecordNotUnique when two concurrent requests win the
+        # application-level uniqueness check with the same generated token (see unique DB indexes)
+        MAX_TOKEN_GENERATION_ATTEMPTS = 3
+
         option :resource_owner
         option :previous_refresh_token, type: Types::String | Types::Nil, default: proc { nil }
 
@@ -17,17 +21,21 @@ module Devise
 
         private
 
-        def authenticate_service
-          Devise::Api::ResourceOwnerService::Authenticate.new(params: params,
-                                                              resource_class: resource_class).call
-        end
-
         def create_devise_api_token
-          devise_api_token = resource_owner.access_tokens.new(params)
+          attempts = 0
+
+          begin
+            devise_api_token = resource_owner.access_tokens.new(params)
+
+            return Success(devise_api_token) if devise_api_token.save
 
-          return Success(devise_api_token) if devise_api_token.save
+            Failure(error: :devise_api_token_create_error, record: devise_api_token)
+          rescue ::ActiveRecord::RecordNotUnique
+            attempts += 1
+            retry if attempts < MAX_TOKEN_GENERATION_ATTEMPTS
 
-          Failure(error: :devise_api_token_create_error, record: devise_api_token)
+            raise
+          end
         end
 
         def params

data/app/services/devise/api/tokens_service/refresh.rb

@@ -9,9 +9,9 @@ module Devise
 
         def call
           return Failure(error: :expired_refresh_token) if devise_api_token.refresh_token_expired?
+          return create_devise_api_token unless Devise.api.config.refresh_token.rotation_enabled
 
-          devise_api_token = yield create_devise_api_token
-          Success(devise_api_token)
+          create_devise_api_token_with_rotation
         end
 
         private
@@ -20,6 +20,21 @@ module Devise
           Devise::Api::TokensService::Create.new(resource_owner: resource_owner,
                                                  previous_refresh_token: devise_api_token.refresh_token).call
         end
+
+        # Mints the replacement token and revokes the presented refresh token atomically, so a
+        # rotated refresh token can never be replayed (its reuse triggers family revocation upstream)
+        def create_devise_api_token_with_rotation
+          result = nil
+
+          devise_api_token.class.transaction do
+            result = create_devise_api_token
+            raise ::ActiveRecord::Rollback if result.failure?
+
+            devise_api_token.revoke!
+          end
+
+          result
+        end
       end
     end
   end

data/app/services/devise/api/tokens_service/revoke.rb

@@ -9,7 +9,7 @@ module Devise
         def call
           return Success(devise_api_token) if devise_api_token.blank?
           return Success(devise_api_token) if devise_api_token.revoked? || devise_api_token.expired?
-          return Success(devise_api_token) if devise_api_token.update(revoked_at: Time.zone.now)
+          return Success(devise_api_token) if devise_api_token.update(revoked_at: Time.current)
 
           Failure(error: :devise_api_token_revoke_error, record: devise_api_token)
         end

data/config/locales/en.yml

@@ -11,6 +11,7 @@ en:
         sign_up_disabled: "Sign up is disabled for this application"
         invalid_refresh_token: "Refresh token is invalid"
         invalid_email: "Email is invalid"
+        invalid_login: "Login credentials are invalid"
         invalid_resource_owner: "Resource owner is invalid"
         resource_owner_create_error: "Resource owner could not be created"
         devise_api_token_create_error: "Token could not be created"

data/docs/README.md

@@ -0,0 +1,32 @@
+# devise-api Documentation
+
+Internal documentation for contributors and AI coding agents. These documents describe the codebase as it **is** (reference docs) and as it **should evolve** (analysis docs). Keep them in sync with the code: any PR that changes behavior described here must update the matching document.
+
+## Reference
+
+| Document | Contents |
+|----------|----------|
+| [architecture.md](architecture.md) | Big-picture design: components, boot/integration sequence, request lifecycle, diagrams |
+| [api-reference.md](api-reference.md) | HTTP endpoints, request/response payloads, full error catalog with statuses |
+| [configuration.md](configuration.md) | Every `Devise.api.config` setting: type, default, where it is consumed |
+| [data-model.md](data-model.md) | `devise_api_tokens` schema, token state machine, refresh chains |
+| [services.md](services.md) | Service-object contracts: inputs, success/failure values, composition |
+| [extending.md](extending.md) | Supported customization points for host applications |
+| [testing.md](testing.md) | Test layout, dummy app, helpers/factories, conventions, coverage map |
+| [development.md](development.md) | Setup, commands, CI, release process |
+
+## Analysis (working documents)
+
+| Document | Contents |
+|----------|----------|
+| [analysis/security-review.md](analysis/security-review.md) | Security posture review: findings ranked by severity, with remediation notes |
+| [analysis/known-issues.md](analysis/known-issues.md) | Code-quality findings: bugs, dead code, inconsistencies, doc drift |
+
+## Ground rules for AI-driven development in this repo
+
+1. **Read [architecture.md](architecture.md) first.** It explains the two invariants that shape everything: the single `Devise.api.config` global, and the string-based `base_token_model` / `base_controller` indirection (`constantize` at use sites — never hardcode `Devise::Api::Token` or the controller class in library code).
+2. **Behavioral changes need request specs.** End-to-end coverage lives in `spec/requests/`; service specs (`spec/services/`) assert the monad contracts (see [testing.md](testing.md)).
+3. **Error types are public API.** Adding/renaming a symbol in `ErrorResponse::ERROR_TYPES` requires a locale entry in `config/locales/en.yml`, a status mapping, and an entry in [api-reference.md](api-reference.md).
+4. **Schema changes touch three places:** the generator template (`lib/devise/api/generators/templates/migration.rb.erb`), the dummy app (`spec/dummy/db/migrate` + `spec/dummy/db/schema.rb`), and [data-model.md](data-model.md). Host apps upgrade via new migrations, so also consider an upgrade path.
+5. **Run `bundle exec rake` before finishing** — it runs RSpec and RuboCop, exactly what CI runs.
+6. **Check [analysis/known-issues.md](analysis/known-issues.md) before "fixing" something** — several quirks are documented there with context on whether changing them breaks the public API (e.g. the `failed_attemps` response-field typo).

data/docs/analysis/known-issues.md

@@ -0,0 +1,56 @@
+# Known Issues & Code-Quality Findings
+
+Working backlog from a full-codebase review (`main` @ `bd49310`, v0.2.0), updated after the 2026-08 fix pass. Ordered by user impact. Security-relevant items live in [security-review.md](security-review.md) and are only cross-referenced here. Check this list before "fixing" surprising code — some quirks are shipped public API.
+
+## Open
+
+### KI-8 · `refresh_token.expires_in` is not snapshotted per row
+Access-token TTL is copied into the row (`expires_in` column); refresh-token TTL is computed from *live config* at check time, so changing the config re-times every existing token (see [data-model.md](../data-model.md)). At minimum keep documented; ideally add a `refresh_token_expires_in` column for symmetry.
+
+### KI-14 · Non-default configuration is untested (mostly resolved)
+`spec/requests/configuration_overrides_spec.rb` covers `authorization.location = :header`/`:params` exclusively, `sign_up.enabled = false`, `refresh_token.enabled = false` and `sign_up.extra_fields` end-to-end; `spec/requests/refresh_token_rotation_spec.rb` and `spec/requests/paranoid_mode_spec.rb` cover `rotation_enabled`, `paranoid` and `verbose_account_state`; `spec/devise/api/token_spec.rb` covers `expires_in_infinite` procs and custom generators; `spec/devise/api/configuration_spec.rb` covers overrides on fresh instances. Still untested: custom `authorization.key`/`scheme`/`params_key` and `base_token_model`/`base_controller` overrides.
+
+## Resolved
+
+### KI-1 · ~~`failed_attemps` typo is public API~~ (resolved 2026-08)
+`ErrorResponse#devise_lockable_info` now emits both the canonical `failed_attempts` and the deprecated misspelled `failed_attemps` (kept for backward compatibility). Drop the typo at the next major release; changelogged.
+
+### KI-2 · ~~`invalid_refresh_token` error type is unreachable~~ (resolved 2026-08)
+The `refresh` action now returns `invalid_refresh_token` (400) for missing/unknown refresh tokens instead of the generic `invalid_token` (401). Breaking-ish for clients matching on the error symbol; changelogged.
+
+### KI-3 · ~~`invalid_email` hardcodes "email" while lookup uses `authentication_keys`~~ (resolved 2026-08)
+`Authenticate` now returns `invalid_email` only when `:email` is one of the model's `authentication_keys`, and a new generic `invalid_login` (400, "Login credentials are invalid") otherwise. With `paranoid` enabled, both collapse into `invalid_authentication`.
+
+### KI-4 · ~~Duplicate, divergent `current_devise_api_refresh_token`~~ (resolved 2026-08)
+Consolidated into `Controllers::Helpers` with memoization mirroring `current_devise_api_token`; the controller-level override was deleted.
+
+### KI-5 · ~~Dead method in `TokensService::Create`~~ (resolved)
+`#authenticate_service` was never called and referenced `params` / `resource_class`, which didn't exist on this service — it would have `NameError`d if invoked. Copy-paste leftover; deleted as part of the coverage push.
+
+### KI-6 · ~~RBS stub~~ (resolved 2026-08)
+`sig/devise/api.rbs` declared only the `VERSION` constant; the `sig/` directory was removed.
+
+### KI-7 · ~~Mixed time sources~~ (resolved 2026-08)
+Standardized on `Time.current` (`Token#expired?`/`#refresh_token_expired?`/`#revoke!`, `TokensService::Revoke`).
+
+### KI-9 · ~~CHANGELOG stale~~ (resolved 2026-08)
+Backfilled 0.1.0 → 0.2.0 from git history plus an Unreleased section for the current pass. Releases without changelog entries should fail review.
+
+### KI-10 · ~~Controller carries rubocop-disable scar tissue~~ (resolved 2026-08)
+`TokensController` now uses private `render_token_response` / `render_error_response` / `render_resource_owner_service_result` / `perform_refresh` helpers; all `rubocop:disable` comments are gone.
+
+### KI-11 · ~~README nits~~ (resolved 2026-08)
+Fixed the "orginally" typo, the `rake rspec` command, and the service example (`.new(...).call` instead of the non-existent class-level `.call`).
+
+### KI-12 · ~~Service specs are placeholders~~ (resolved)
+All six `spec/services/**` files now assert the monad contracts (`Success`/`Failure` per branch, per [services.md](../services.md)), including the failure paths unreachable through the HTTP API (`:invalid_resource_owner`, `:devise_api_token_create_error`, `:devise_api_token_revoke_error`, sign-up transaction rollback).
+
+### KI-13 · ~~No generator specs~~ (resolved)
+`rails g devise_api:install` is covered by `spec/devise/api/generators/install_generator_spec.rb` (migration template rendering with the current Active Record version, unique token indexes, locale copy, migration numbering).
+
+## Cross-references into security review
+
+- Non-unique token indexes → [SEC-4](security-review.md) (resolved)
+- Plaintext token storage → [SEC-1](security-review.md) (open; log filtering shipped)
+- No refresh rotation → [SEC-2](security-review.md) (resolved, opt-in `rotation_enabled`)
+- Default `:both` token location + GET `info` → [SEC-3](security-review.md) (documented; default unchanged)

data/docs/analysis/security-review.md

@@ -0,0 +1,53 @@
+# Security Review
+
+Static review of the codebase as of `main` @ `bd49310` (v0.2.0, 2026-08), updated after the 2026-08 hardening pass. This is the working document for the "security hardening" milestone: each finding has an ID, severity, and remediation sketch. When a finding is fixed, move it to the *Resolved* section with the PR reference.
+
+Severity scale: **High** = practical account/session compromise under a realistic threat model; **Medium** = meaningful weakening of the security posture; **Low** = defense-in-depth / hardening; **Info** = document-and-accept candidates.
+
+## Open findings
+
+### SEC-1 · High · Tokens stored in plaintext
+`devise_api_tokens.access_token` / `refresh_token` are stored as-is (`lib/devise/api/token.rb`, migration template). Anyone with read access to the DB (backup leak, SQL injection elsewhere in the host app, log of the row) holds live bearer credentials for every active session.
+
+**Remediation:** store a digest (e.g. `SHA256`) and look up by digest; return the raw token only once at creation. Needs a migration path (dual-read window or forced re-login) and is a breaking change for host apps that query tokens directly — consider a `hash_token_secrets` config flag defaulting on in the next minor. This also resolves SEC-6.
+
+**Partial mitigation shipped (2026-08):** token values are now filtered from request logs (`filter_parameters` via the engine initializer) and from `Token#inspect` (`filter_attributes`), addressing GH-51. Raw SQL logging can still print values; digest storage remains the real fix.
+
+### SEC-3 · Medium · Tokens accepted in URL params by default
+`authorization.location` defaults to `:both`, and `info` is a GET route — so `GET /users/tokens/info?access_token=…` is a documented usage. Query-string tokens end up in server/proxy/CDN access logs, browser history, and potentially `Referer` headers.
+
+**Remediation:** change the default to `:header` (breaking; needs a major-version changelog callout). **Interim (shipped 2026-08):** the README "Security recommendations" section now tells host apps to set `api.authorization.location = :header`, and token params are filtered from request logs. `:params`/`:both` remain opt-in-by-default until the next breaking release.
+
+### SEC-6 · Low · Token lookup is not constant-time
+`find_by(access_token: token)` compares via DB index. With 60-char `friendly_token` entropy the timing side channel is not practically exploitable, noted for completeness. Hashing tokens (SEC-1) makes this moot.
+
+### SEC-8 · Info · No rate limiting
+The gem relies entirely on Devise `lockable` (if enabled) to slow credential stuffing; `sign_in`/`sign_up`/`refresh` are otherwise unthrottled. Out of scope to implement in-gem. The README "Security recommendations" section now recommends `rack-attack` (or equivalent) on the token endpoints; keeping open as Info in case in-gem throttling hooks are ever wanted.
+
+### SEC-9 · Info · `sign_up.extra_fields` is a mass-assignment and disclosure lever
+Fields listed there are both *writable at sign-up* and *echoed in every token/info response* (`TokenResponse#default_resource_owner`). A host app adding `:role` or `:admin` here creates a privilege-escalation hole. Warnings shipped 2026-08 in the README (config example + "Security recommendations"); keeping open as Info because the sharp edge itself remains.
+
+### SEC-10 · Info · Deliberate CSRF skip
+`skip_before_action :verify_authenticity_token` is correct for bearer-token endpoints; note that accepting tokens from params (`SEC-3`) is what keeps CSRF relevant — cookie-less bearer auth in the header is not CSRF-able.
+
+## Positive observations
+
+- Default generators use `Devise.friendly_token(60)` — ample entropy, URL-safe.
+- Password verification delegates to Devise (`valid_password?` is constant-time via `Devise.secure_compare` internally; lockable counters handled by `valid_for_authentication?`).
+- `dependent: :destroy` on the owner association prevents orphaned live tokens after account deletion.
+- Params are strictly `permit`ted from `authentication_keys` + Devise defaults + explicit config.
+- Sign-up wraps user+token creation in a transaction; do-notation failure unwinds roll it back.
+
+## Resolved
+
+### SEC-2 · Medium · No refresh-token rotation invalidation or reuse detection — *resolved 2026-08 (opt-in)*
+`TokensService::Refresh` minted a new token but left the presented refresh token fully usable until its own TTL. Fixed with the OAuth2 Security BCP pattern behind `refresh_token.rotation_enabled` (default `false` for backward compatibility): each refresh revokes the presented token (same transaction as the mint), and presenting a rotated/revoked refresh token again revokes the whole token family (`Token#revoke_family!`) and returns `revoked_token`. Recommended `true` in the README; consider defaulting on at the next breaking release. Covered by `spec/requests/refresh_token_rotation_spec.rb` and `spec/services/tokens_service/refresh_spec.rb`.
+
+### SEC-4 · Low · Token uniqueness not enforced by the database — *resolved 2026-08*
+The migration template now creates `unique: true` indexes on `access_token` and `refresh_token` (existing installs: add the migration listed in the CHANGELOG), and `TokensService::Create` rescues `ActiveRecord::RecordNotUnique` with a regenerate-and-retry (3 attempts). Covered by `spec/devise/api/token_spec.rb` ("database uniqueness") and `spec/services/tokens_service/create_spec.rb`.
+
+### SEC-5 · Low · Account enumeration via differentiated errors — *resolved 2026-08 (opt-in)*
+`paranoid` config flag (default `false`, mirroring Devise's `config.paranoid`): unknown accounts, wrong passwords, and locked/unconfirmed accounts all return the same generic `invalid_authentication` (401) with no lockable/confirmable details. Covered by `spec/requests/paranoid_mode_spec.rb`.
+
+### SEC-7 · Low · Lockable error payload aids brute-force pacing — *resolved 2026-08 (opt-in)*
+`error_response.verbose_account_state` config flag (default `true` for compatibility, recommended `false`): when disabled, the `lockable`/`confirmable` metadata blocks (`max_attempts`, `failed_attempts`, `locked_at`, `unlock_at`, …) are omitted from error responses. `paranoid` implies it. Covered by `spec/requests/paranoid_mode_spec.rb`.

data/docs/api-reference.md

@@ -0,0 +1,95 @@
+# HTTP API Reference
+
+All endpoints are drawn by `devise_for :<scope>` for any model with the `:api` module. Examples below use `devise_for :users`. Path segment (`tokens`) and controller are customizable — see [extending.md](extending.md).
+
+| Route helper | Verb | Path | Action | Auth required |
+|---|---|---|---|---|
+| `sign_up_user_tokens` | POST | `/users/tokens/sign_up` | `sign_up` | no |
+| `sign_in_user_tokens` | POST | `/users/tokens/sign_in` | `sign_in` | no |
+| `refresh_user_tokens` | POST | `/users/tokens/refresh` | `refresh` | refresh token |
+| `revoke_user_tokens` | POST | `/users/tokens/revoke` | `revoke` | access token (silently no-ops if absent/invalid) |
+| `info_user_tokens` | GET | `/users/tokens/info` | `info` | access token (via `authenticate_devise_api_token!`) |
+
+Tokens are sent per `authorization` config (default `:both`): `Authorization: Bearer <token>` header **or** `access_token` query/body param (params win over header). The **same extraction** is used for access and refresh tokens — `refresh` expects the *refresh* token in the same slot.
+
+With `refresh_token.rotation_enabled` (default off), a successful `refresh` also revokes the presented refresh token, and presenting a rotated/revoked refresh token again revokes its whole token family and returns `revoked_token` (reuse detection).
+
+## Success payloads
+
+Built by `Devise::Api::Responses::TokenResponse` (`lib/devise/api/responses/token_response.rb`).
+
+### Default token body (`sign_in` 200, `refresh` 200, `sign_up` 201)
+
+```json
+{
+  "token": "<access_token>",
+  "refresh_token": "<refresh_token>",
+  "expires_in": 3600,
+  "token_type": "Bearer",
+  "resource_owner": { "id": 1, "email": "a@b.c", "created_at": "...", "updated_at": "..." }
+}
+```
+
+- `refresh_token` is omitted (`compact`) when `refresh_token.enabled` is `false`.
+- `resource_owner` contains `id, email, created_at, updated_at` plus any configured `sign_up.extra_fields`.
+- `sign_up` on a confirmable model additionally merges `"confirmable": { "confirmed": false, "message": "<signed_up_but_unconfirmed locale>" }` and still returns `201` with tokens (unconfirmed users get tokens at sign-up; they cannot sign *in* until confirmed).
+
+### `info` (200)
+
+Returns just the `resource_owner` object (same key set as above).
+
+### `revoke` (204)
+
+Empty body. Returned even when no/invalid token was supplied (revoke is idempotent-by-design; see known-issues).
+
+## Error payload
+
+Built by `Devise::Api::Responses::ErrorResponse` (`lib/devise/api/responses/error_response.rb`):
+
+```json
+{
+  "error": "<error_type>",
+  "error_description": ["human readable message(s)"],
+  "lockable":   { "locked": true, "max_attempts": 5, "failed_attempts": 5, "failed_attemps": 5, "locked_at": "...", "unlock_at": "..." },
+  "confirmable": { "confirmed": false, "confirmation_sent_at": "..." }
+}
+```
+
+- `lockable` / `confirmable` blocks appear **only** for `invalid_authentication` errors on models with those Devise modules (`compact` removes them otherwise), and only while `error_response.verbose_account_state` is `true` (the default) and `paranoid` is `false` — see [configuration.md](configuration.md).
+- `failed_attempts` is the canonical key; `failed_attemps` is the original shipped typo, kept for backward compatibility until the next major release (see [analysis/known-issues.md](analysis/known-issues.md)).
+- `error_description` comes from `record.errors.full_messages` when a record with validation errors is attached; otherwise from `config/locales/en.yml` under `devise.api.error_response.<error>`. With `paranoid` enabled, `invalid_authentication` always uses the generic message (no locked/unconfirmed specialization).
+
+## Error catalog
+
+Source of truth: `ErrorResponse::ERROR_TYPES` + `#status`. Every symbol must have a locale entry.
+
+| `error` | HTTP status | Raised by / when |
+|---|---|---|
+| `invalid_authentication` | 401 | `Authenticate` — bad password, locked, or unconfirmed account (description specializes per module state unless `paranoid`); with `paranoid` enabled, also returned when no account matches |
+| `invalid_token` | 401 | helpers `authenticate_devise_api_token!` (no/unknown access token) |
+| `expired_token` | 401 | helpers — access token past `expires_in` |
+| `expired_refresh_token` | 401 | `TokensService::Refresh` — refresh token past `refresh_token.expires_in` |
+| `revoked_token` | 401 | helpers / `refresh` — token has `revoked_at`; also the reuse-detection response when `refresh_token.rotation_enabled` revokes a token family |
+| `invalid_email` | 400 | `Authenticate` — no resource found and `:email` is one of the model's `authentication_keys` (and `paranoid` is off) |
+| `invalid_login` | 400 | `Authenticate` — no resource found and the model authenticates by non-email keys (and `paranoid` is off) |
+| `invalid_refresh_token` | 400 | `refresh` action — no/unknown refresh token presented |
+| `refresh_token_disabled` | 400 | `refresh` action when `refresh_token.enabled` is false |
+| `sign_up_disabled` | 400 | `sign_up` action when `sign_up.enabled` is false |
+| `invalid_resource_owner` | 400 | `TokensService::Create` — owner doesn't respond to `access_tokens` (model lacks `:api`) |
+| `resource_owner_create_error` | 422 | `SignUp` — model validation failure (description = validation messages) |
+| `devise_api_token_create_error` | 422 | `TokensService::Create` — token row failed to save |
+| `devise_api_token_revoke_error` | 422 | `TokensService::Revoke` — update failed |
+
+## Accepted parameters
+
+- **sign_in**: `resource_class.authentication_keys` (usually `email`) + Devise's default sign-in params (`password`, `remember_me`).
+- **sign_up**: authentication keys + Devise's default sign-up params (`password`, `password_confirmation`) + `Devise.api.config.sign_up.extra_fields`.
+- Params are `permit`ted then `.to_h` — anything else is dropped.
+
+## Devise module interplay
+
+| Devise module on the model | Effect |
+|---|---|
+| `trackable` | `sign_in`/`sign_up` call `update_tracked_fields!(request)` |
+| `lockable` | failed sign-ins increment `failed_attempts` (via `valid_for_authentication?`); lock state reported in error payload; successful sign-in resets attempts |
+| `confirmable` | unconfirmed users can sign **up** (get tokens + confirmable notice) but cannot sign **in** (`active_for_authentication?` fails → `invalid_authentication` with unconfirmed description) |