devise-api 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2d86e2276841e4ca3ae7497278542d686da38368f5f5cdf76629abd463c7976f
-  data.tar.gz: 3f33438f2a503b0f1bd510e6020c0d88f61a82715aff8b701a1872a4901ffb75
+  metadata.gz: b59405402be8f8b9db001a874ea536a0ecf10d0fbf7acf8205b921d9fcc9b6b9
+  data.tar.gz: 9bb3114fcbb15fe38af1e46bf009508991f2ac32fccdff7da6626f33c1d11e15
 SHA512:
-  metadata.gz: acea2091463ddb32d14df2c6b6aaf88e55549796b79ba35855ffdd08f3f78e8a5e5d9f305f48a855a2f3d17aa2cee2c8e7fce7ce07efda222af9de785a9f57cf
-  data.tar.gz: 8cecc648a297705d7d7f82420aa48fd6f4ed7d8899ba721cf0002cbae34f9f1e3fae5032877a4efa826f609c50592f894f9407adeeed6a12c7ca856b2dd9c5d2
+  metadata.gz: d797c3f5a67bb5e2f0e0293d828b617b3b55e151d0648dce25739f1b9e7a0594da1c24ba605c677b6806df8ed1dc6d3762548ca91dbd2afe3280462df4d19d8b
+  data.tar.gz: d1cff639ba814071d5b3e5e5e3f3680f363fb25514a264e98c55bcf077bfe1cc1c4ad3b85d7f8974dc13975f0d233c57d04533efcca5856763c73e93380cac6c

data/.claude/commands/commit.md

@@ -0,0 +1,38 @@
+Create a git commit for the current staged/unstaged changes.
+
+## Steps
+
+1. Run `git status` and `git diff` to review all changes
+2. Run `git log --oneline -5` to match the project's recent commit style
+3. Stage only relevant files — never stage `.env`, `*.pem`, credentials, or build artifacts (`*.gem`, `pkg/`)
+4. Draft a commit message following the format below
+5. Create the commit
+
+## Commit Message Format
+
+```
+<type>(<scope>): <description>
+```
+
+**Types:** `feat` | `fix` | `refactor` | `chore` | `docs` | `test` | `perf`
+
+**Scopes** (lowercase, optional — this repo's history mostly omits the scope; use one only when it adds clarity): `tokens` | `services` | `responses` | `config` | `model` | `routes` | `generators` | `locales` | `specs` | `docs` | `ci`
+
+**Rules:**
+- Description explains WHY, not WHAT
+- Use present tense ("add", not "added")
+- If changes span multiple areas, omit the scope
+- Keep under 72 characters
+
+## Examples
+
+```
+feat(tokens): add token rotation on refresh to block replay
+fix(responses): correct translation key for unconfirmed signup message
+refactor(services): extract error rendering shared by controller actions
+chore(ci): add Ruby 3.3 to the test matrix
+test(specs): cover non-default authorization locations
+docs: document refresh chain semantics in data-model
+```
+
+$ARGUMENTS

data/.claude/commands/create-branch.md

@@ -0,0 +1,57 @@
+Create a new git branch following the project's naming conventions.
+
+## Branch Naming Format
+
+```
+{type}/{description}
+```
+
+## Types
+
+| Type | Use Case |
+|------|----------|
+| `feature` | New functionality, endpoints, entities |
+| `fix` | Bug fixes, issue corrections |
+| `chore` | Maintenance, config, non-feature changes |
+| `refactor` | Code restructuring without behavior change |
+| `ci` | CI/CD pipeline changes |
+| `test` | Test additions or modifications |
+| `docs` | Documentation only changes |
+| `hotfix` | Urgent production fixes |
+
+## Description Rules
+
+1. Use **kebab-case** (words separated by hyphens)
+2. Start with a **verb**: `add-`, `fix-`, `update-`, `remove-`, `complete-`, `enable-`, `change-`
+3. **Lowercase only** — no uppercase letters
+4. Be descriptive but concise
+
+## Workflow
+
+1. Infer the branch type from context (default to `feature` for new functionality)
+2. Generate a descriptive branch name based on: $ARGUMENTS (or the work done in the session)
+3. **Immediately create and checkout the branch** — no confirmation needed:
+
+```bash
+git checkout -b {type}/{description}
+```
+
+4. Report the branch name to the user after creation
+
+## Examples
+
+| Description | Branch Name |
+|-------------|-------------|
+| Adding email notifications | `feature/add-email-notification-structure` |
+| Fixing login timeout | `fix/login-timeout-issue` |
+| Updating Redis config | `chore/update-redis-configuration` |
+| Refactoring ticket service | `refactor/ticket-service` |
+| Adding user repo tests | `test/add-user-repository-tests` |
+
+## Anti-patterns
+
+- No uppercase: `Feature/Add-Users`
+- No underscores: `feature_add_users`
+- No camelCase: `feature/AddUserEndpoint`
+- Missing type prefix: `add-users`
+- Too vague: `feature/users` (no verb)

data/.claude/commands/create-pr.md

@@ -0,0 +1,41 @@
+Analyze all commits on the current branch (compared to main) and create a comprehensive PR.
+
+## Steps
+
+1. Run `git log main..HEAD` and `git diff main...HEAD` to understand all changes
+2. Generate PR title in conventional format: `<type>(<scope>): <description>`
+3. Push the branch to remote if not already pushed
+4. Create PR using GitHub CLI:
+
+```bash
+gh pr create --title "<title>" --body "<body>"
+```
+
+## PR Body Template
+
+```markdown
+## Summary
+- [1-3 bullet points describing what changed and why]
+
+## Changes
+- [List of significant code changes by file/area]
+
+## Architecture Impact
+- [Any cross-service changes, new events, DB migrations]
+
+## Test Plan
+- [ ] Unit tests added/updated
+- [ ] Integration tests pass
+- [ ] Manual testing completed
+- [ ] Migration tested on clean DB
+
+## Related
+- Closes #issue-number (if applicable)
+```
+
+## Rules
+
+- Never include credentials or secrets in PR description
+- Link related issues with `Closes #N` syntax
+- If migration exists, mention it explicitly in Architecture Impact
+- Scope: $ARGUMENTS (optional: specific context or issue number)

data/CHANGELOG.md

@@ -1,4 +1,57 @@
-## [Unreleased]
+# Changelog
+
+## [0.3.0] - 2026-08-25
+
+### Added
+- Refresh token rotation with reuse detection behind `refresh_token.rotation_enabled` (default `false`): each refresh revokes the presented refresh token, and presenting an already-rotated/revoked refresh token revokes the whole token family (SEC-2)
+- Paranoid mode behind `paranoid` (default `false`): unknown accounts and wrong passwords both return the generic `invalid_authentication` error with no lockable/confirmable details, preventing account enumeration (SEC-5)
+- `error_response.verbose_account_state` (default `true`): set to `false` to omit the `lockable`/`confirmable` metadata blocks from error responses (SEC-7)
+- `Devise::Api::Token#revoke!` and `#revoke_family!` helpers
+- New `invalid_login` error (HTTP 400) returned instead of `invalid_email` when the model's `authentication_keys` do not include `:email`
+- Lockable error responses now include the correctly spelled `failed_attempts` key alongside the deprecated `failed_attemps` (the misspelling will be removed in the next major release)
+- `access_token`, `refresh_token` and `previous_refresh_token` are added to the host app's `filter_parameters`, and the token model filters them from `#inspect` output (GH-51)
+
+### Changed
+- **Breaking-ish:** `POST /<scope>/tokens/refresh` with an unknown refresh token now returns `invalid_refresh_token` (HTTP 400) instead of `invalid_token` (HTTP 401)
+- The install generator's migration now creates **unique** indexes on `access_token` and `refresh_token`; token creation rescues `ActiveRecord::RecordNotUnique` and retries with a fresh token (SEC-4). Existing installs should add a migration:
+  ```ruby
+  remove_index :devise_api_tokens, :access_token
+  remove_index :devise_api_tokens, :refresh_token
+  add_index :devise_api_tokens, :access_token, unique: true
+  add_index :devise_api_tokens, :refresh_token, unique: true
+  ```
+- `current_devise_api_refresh_token` is now memoized in the shared controller helpers (the duplicate controller-level override was removed)
+- Internal time handling standardized on `Time.current`
+
+### Removed
+- Vestigial RBS stub (`sig/devise/api.rbs`)
+
+## [0.2.0] - 2024-09-27
+
+- Resource lookup uses the model's `authentication_keys` instead of hardcoding `email` (#46)
+- Fixed nil memoization of `current_devise_api_token` / `current_devise_api_refresh_token` (#48)
+- Fixed the translation key for the unconfirmed signup message (#49)
+
+## [0.1.3] - 2023-08-08
+
+- Fixed `AbstractController::DoubleRenderError` on refresh (#29)
+- Allowed defining extra fields for sign up via `sign_up.extra_fields` (#36, #38)
+- Disabled parameter wrapping in `TokensController` (#42)
+
+## [0.1.2] - 2023-05-30
+
+- Added `sign_up.enabled` option to disable the sign up endpoint (#15)
+- Fixed refresh behavior (#14)
+- Fixed undefined variable error in the controller helper (#25)
+- Migration template respects the configured primary/foreign key types (#23)
+
+## [0.1.1] - 2023-01-14
+
+- Fixed invalid strategy error (#2)
+
+## [0.1.0] - 2023-01-14
+
+- First public release: `:api` Devise module with token sign up / sign in / refresh / revoke / info endpoints (#1)
 
 ## [0.0.0] - 2023-01-09
 

data/CLAUDE.md

@@ -0,0 +1,49 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+`devise-api` is a Rails engine gem that adds token-based API authentication (access tokens + refresh tokens) to Devise. It registers an `:api` Devise module that models opt into via `devise :api`. Supports Ruby >= 2.7, Rails >= 6.0.
+
+## Documentation
+
+`docs/` holds the detailed internal documentation — start at `docs/README.md` (index + ground rules for working in this repo). Highlights:
+
+- `docs/architecture.md` — components, boot sequence, request lifecycle (with diagrams)
+- `docs/api-reference.md` — endpoints, payloads, full error catalog
+- `docs/configuration.md`, `docs/data-model.md`, `docs/services.md`, `docs/extending.md`, `docs/testing.md`, `docs/development.md`
+- `docs/analysis/security-review.md` and `docs/analysis/known-issues.md` — the vetted backlog of security findings (SEC-*) and code-quality issues (KI-*). **Consult these before changing surprising code** (some quirks, like the `failed_attemps` response-field typo, are shipped public API), and update them when you fix an item.
+
+Docs are contractual: a PR that changes behavior described in `docs/` must update the matching document.
+
+## Commands
+
+```bash
+bundle install                  # install dependencies
+bundle exec rake                # default task: rspec + rubocop (what CI runs)
+bundle exec rake rspec          # run the full test suite
+bundle exec rspec spec/services/tokens_service/refresh_spec.rb        # run one spec file
+bundle exec rspec spec/services/tokens_service/refresh_spec.rb:12     # run one example by line
+bundle exec rubocop             # lint (config in .rubocop.yml, single quotes, 120-char lines)
+```
+
+Tests run against the dummy Rails app in `spec/dummy` (sqlite3, schema in `spec/dummy/db/schema.rb`). `spec/spec_helper.rb` boots it via `require 'dummy/config/environment'`; DatabaseCleaner wraps each example. If token/schema fields change, the dummy app's migrations and schema must be updated alongside the generator template.
+
+## Architecture
+
+Everything is configured through a single global: `Devise.api.config` (a `Dry::Configurable` instance defined in `lib/devise/api/configuration.rb`, installed as `Devise.api` in `lib/devise/api.rb`). Config includes token expiry/generators, sign_up enablement/extra_fields, authorization header/params location, before/after callbacks for each action, and — importantly — `base_token_model` and `base_controller`, which are **string class names resolved with `constantize` at use sites** so host apps can substitute their own subclasses. When touching model/controller references, use the config values, never hardcode `Devise::Api::Token`.
+
+Flow of a request:
+
+1. **Routes** — `lib/devise/api/rails/routes.rb` monkey-patches `ActionDispatch::Routing::Mapper#devise_api`, which `devise_for` invokes because `lib/devise/api.rb` calls `Devise.add_module :api, route: {...}`. Draws POST `sign_up`/`sign_in`/`revoke`/`refresh` and GET `info` under `/<scope>/tokens`.
+2. **Controller** — `app/controllers/devise/api/tokens_controller.rb` (inherits from configurable `base_controller`, default `::DeviseController`). Each action runs the configured `before_*` callback, delegates to a service, then renders a `TokenResponse` or `ErrorResponse` and fires the `after_successful_*` callback.
+3. **Services** — `app/services/devise/api/**`, all inheriting `Devise::Api::BaseService` which wires up dry-initializer (`option :x, type: Types::...`) and dry-monads (`Success`/`Failure` + do-notation `yield`). Two namespaces: `ResourceOwnerService` (`Authenticate`, `SignIn`, `SignUp`) and `TokensService` (`Create`, `Refresh`, `Revoke`). Services compose: e.g. `SignIn` yields `Authenticate` then `TokensService::Create`. Failures are hashes like `{ error: :invalid_authentication, record: ... }` splatted into `ErrorResponse`.
+4. **Responses** — `lib/devise/api/responses/`. `ErrorResponse` maps a symbolic error type (see its `ERROR_TYPES` list) to an i18n message (`config/locales/en.yml`, keys under `devise.api.responses`) and HTTP status. `TokenResponse` shapes the JSON per action.
+
+Supporting pieces:
+
+- **Token model** — `lib/devise/api/token.rb` (`devise_api_tokens` table, polymorphic `resource_owner`). Knows `expired?`/`revoked?`/`active?` and generates unique tokens via the configured generator procs. Refresh chains are linked through `previous_refresh_token`.
+- **Controller helpers** — `lib/devise/api/controllers/helpers.rb` is included into all of ActionController on load: `authenticate_devise_api_token!`, `current_devise_api_token`, `current_devise_api_user`. Token extraction honors `authorization.location` (`:header`, `:params`, `:both`).
+- **Devise module** — `Devise::Models::Api` in `lib/devise/api.rb` adds the `access_tokens` association and `supported_devise_modules`; the codebase checks that inquiry to conditionally support optional Devise modules (trackable, lockable, confirmable).
+- **Generator** — `rails generate devise_api:install` (`lib/devise/api/generators/install_generator.rb`) copies the migration template and locale file into the host app.

data/Gemfile

@@ -47,3 +47,6 @@ gem 'rspec-core'
 
 # Common code needed by the other RSpec gems. Not intended for direct use [https://github.com/rspec/rspec-support]
 gem 'rspec-support'
+
+# Code coverage analysis tool for Ruby [https://github.com/simplecov-ruby/simplecov]
+gem 'simplecov', '~> 0.22', require: false

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    devise-api (0.1.3)
+    devise-api (0.3.0)
       devise (>= 4.7.2)
       dry-configurable (~> 1.0, >= 1.0.1)
       dry-initializer (>= 3.1.1)
@@ -98,6 +98,7 @@ GEM
       responders
       warden (~> 1.2.3)
     diff-lcs (1.5.0)
+    docile (1.4.1)
     dry-configurable (1.0.1)
       dry-core (~> 1.0, < 2)
       zeitwerk (~> 2.6)
@@ -236,6 +237,12 @@ GEM
     rubocop-ast (1.24.1)
       parser (>= 3.1.1.0)
     ruby-progressbar (1.11.0)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.13.2)
+    simplecov_json_formatter (0.1.4)
     sprockets (4.2.0)
       concurrent-ruby (~> 1.0)
       rack (>= 2.2.4, < 4)
@@ -260,6 +267,7 @@ PLATFORMS
   arm64-darwin-21
   arm64-darwin-22
   arm64-darwin-23
+  arm64-darwin-25
 
 DEPENDENCIES
   awesome_print
@@ -275,6 +283,7 @@ DEPENDENCIES
   rspec-rails (~> 6.0, >= 6.0.1)
   rspec-support
   rubocop (~> 1.21)
+  simplecov (~> 0.22)
   sprockets-rails
   sqlite3 (~> 1.4)