feat: Adds API Tokens and Two-Factor Authentication

[kantorge]

Enhances application security and external integration capabilities by introducing personal API token management and optional two-factor authentication (2FA).

• Personal Access Tokens (PATs): Empowers users to create, name, scope with granular abilities (e.g., accounts:read, transactions:write), optionally set expiration dates, and revoke API tokens from their settings. This enables secure programmatic access to the API for scripts and automations.
• Two-Factor Authentication (TOTP): Allows users to opt-in for TOTP-based 2FA using an authenticator app, significantly increasing account security. Includes generation of recovery codes for emergency access and an operator 'break-glass' Artisan command to disable 2FA.
• Enhanced API Security: Implements per-user/IP API rate limiting across all environments and provides granular abilities for API tokens. Initial token enforcement ensures ownership scoping, with full ability enforcement planned as a follow-up.
• Improved API Documentation: Configures Scramble to accurately document bearer token authentication for the auto-generated OpenAPI specification, providing clear guidance for token usage. Introduces configurable access control for the /docs/api route in non-local environments.
• User Interface: Integrates new Vue components into the user settings page for seamless management of API tokens and 2FA settings, along with a dedicated Blade view for the 2FA login challenge.
• Core Integrations: Leverages existing Laravel Sanctum capabilities for tokens and integrates the laragear/two-factor package for TOTP, aligning with existing customizations without requiring a full migration to Laravel Fortify.
• Infrastructure Updates: Includes necessary database migrations for personal access tokens and 2FA-related user fields, new configuration options, and console commands for scheduled token pruning.

Summary by CodeRabbit

• New Features
  • Added personal API token management in account settings (token list, create with ability-based permissions + max lifetime expiry, one-time plaintext reveal/copy, revoke).
  • Added two-factor authentication settings (TOTP enroll/verify, recovery-code generation/copy/regenerate) plus step-up login challenges.
  • Added API endpoints for token + 2FA management and enforced ability-based authorization for bearer-token requests.
  • Added break-glass console command to disable 2FA for a user.
  • Added production gating for API documentation access.
• Documentation
  • Published/updated API access + 2FA specifications and end-to-end flow docs (including environment variable guidance and rollout notes).
• Localization
  • Added translated UI strings for token and 2FA management.
• Chores
  • Added API rate limiting and scheduled pruning of expired tokens.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 584e77f3-a68a-4073-a210-48d4a1be8836

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds Sanctum personal access token management, optional TOTP-based two-factor authentication, login challenges, ability-scoped middleware across API controllers, security settings interfaces, API rate limiting, configurable API documentation access, localization, and extensive feature coverage.

Changes

API access and two-factor authentication

Layer / File(s)	Summary
Security foundation and configuration .ai/docs/features/api-access-and-2fa/*, .env.example, config/*, bootstrap/app.php, app/Providers/AppServiceProvider.php, database/migrations/*, routes/console.php	Adds feature documentation, token and 2FA configuration, Sanctum ability aliases, token pruning, per-user/IP rate limiting, and configurable API documentation access.
Personal access token lifecycle app/Enums/ApiTokenAbility.php, app/Http/Requests/ApiTokenRequest.php, app/Services/ApiTokenService.php, app/Http/Controllers/API/ApiTokenApiController.php, routes/api.php, tests/Feature/API/ApiTokenApiControllerTest.php, tests/Feature/Services/*	Adds scoped token validation, creation, listing, revocation, expiry enforcement, session-only management, and service/controller tests.
Two-factor enrollment and login app/Models/User.php, app/Http/Controllers/API/TwoFactorApiController.php, app/Http/Controllers/Auth/LoginController.php, app/Console/Commands/*, resources/views/auth/*, tests/Feature/*TwoFactor*	Integrates TOTP enrollment, confirmation, disabling, recovery-code regeneration, break-glass disabling, and the session login challenge flow.
Security settings interface resources/js/user/*, lang/*.json	Adds profile sections for token and 2FA management, including one-time token/recovery-code displays, clipboard actions, confirmations, and localized messages. TwoFactorSettings.vue contains a standalone __, methods entry.
Ability-scoped middleware app/Http/Controllers/API/*ApiController.php, tests/Feature/API/ApiAbilityEnforcementTest.php	Applies abilities:read, abilities:write, and abilities:settings middleware to controller actions and adds representative bearer-token enforcement tests.
Existing test authentication updates tests/Feature/API/*, tests/Feature/Ai*, tests/Feature/GoogleDrive*, tests/Feature/Import*, tests/Unit/Http/Controllers/API/*	Updates existing tests to authenticate with explicit wildcard Sanctum abilities.
Operational and documentation validation tests/Feature/RateLimiterTest.php, tests/Feature/ViewApiDocsGateTest.php, tests/DuskTestCase.php, UPGRADE.md, CLAUDE.md, AGENTS.md	Validates limiter keys and API documentation access modes, cleans persisted Dusk configuration overrides, and documents operational changes.

Estimated code review effort: 5 (Critical) | ~120 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Settings
  participant ApiTokenApiController
  participant ApiTokenService
  participant Sanctum
  Settings->>ApiTokenApiController: submit token name, abilities, expiry
  ApiTokenApiController->>ApiTokenService: validate and create token
  ApiTokenService->>Sanctum: persist personal access token
  Sanctum-->>Settings: return plaintext token once
  Settings->>ApiTokenApiController: revoke token id
  ApiTokenApiController->>ApiTokenService: delete owned token

Loading

sequenceDiagram
  participant User
  participant LoginController
  participant TwoFactorLoginHelper
  participant ChallengeView
  User->>LoginController: submit email and password
  LoginController->>TwoFactorLoginHelper: attemptWhen credentials
  TwoFactorLoginHelper-->>ChallengeView: pending 2FA challenge
  User->>ChallengeView: submit TOTP or recovery code
  ChallengeView->>LoginController: post 2fa_code
  LoginController->>TwoFactorLoginHelper: verify code
  TwoFactorLoginHelper-->>User: authenticate session

Loading

Possibly related PRs

• kantorge/yaffa#371: Adds payee update behavior that this PR gates with token abilities.
• kantorge/yaffa#478: Adds the account-summary action that this PR gates with abilities:write.
• kantorge/yaffa#482: Adds transaction/category-learning API behavior covered by this PR’s ability middleware changes.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 58.13% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the pull request’s primary changes: API token management and two-factor authentication.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/api_access_improvements

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}