Add comprehensive API v1 with OAuth and API key authentication (#2389)

* OAuth

* Add API test routes and update Doorkeeper token handling for test environment

- Introduced API namespace with test routes for controller testing in the test environment.
- Updated Doorkeeper configuration to allow fallback to plain tokens in the test environment for easier testing.
- Modified schema to change resource_owner_id type from bigint to string.

* Implement API key authentication and enhance access control

- Replaced Doorkeeper OAuth authentication with a custom method supporting both OAuth and API keys in the BaseController.
- Added methods for API key authentication, including validation and logging.
- Introduced scope-based authorization for API keys in the TestController.
- Updated routes to include API key management endpoints.
- Enhanced logging for API access to include authentication method details.
- Added tests for API key functionality, including validation, scope checks, and access control enforcement.

* Add API key rate limiting and usage tracking

- Implemented rate limiting for API key authentication in BaseController.
- Added methods to check rate limits, render appropriate responses, and include rate limit headers in responses.
- Updated routes to include a new usage resource for tracking API usage.
- Enhanced tests to verify rate limit functionality, including exceeding limits and per-key tracking.
- Cleaned up Redis data in tests to ensure isolation between test cases.

* Add Jbuilder for JSON rendering and refactor AccountsController

- Added Jbuilder gem for improved JSON response handling.
- Refactored index action in AccountsController to utilize Jbuilder for rendering JSON.
- Removed manual serialization of accounts and streamlined response structure.
- Implemented a before_action in BaseController to enforce JSON format for all API requests.

* Add transactions resource to API routes

- Added routes for transactions, allowing index, show, create, update, and destroy actions.
- This enhancement supports comprehensive transaction management within the API.

* Enhance API authentication and onboarding handling

- Updated BaseController to skip onboarding requirements for API endpoints and added manual token verification for OAuth authentication.
- Improved error handling and logging for invalid access tokens.
- Introduced a method to set up the current context for API requests, ensuring compatibility with session-like behavior.
- Excluded API paths from onboarding redirects in the Onboardable concern.
- Updated database schema to change resource_owner_id type from bigint to string for OAuth access grants.

* Fix rubocop offenses

- Fix indentation and spacing issues
- Convert single quotes to double quotes
- Add spaces inside array brackets
- Fix comment alignment
- Add missing trailing newlines
- Correct else/end alignment

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Fix API test failures and improve test reliability

- Fix ApiRateLimiterTest by removing mock users method and using fixtures
- Fix UsageControllerTest by removing mock users method and using fixtures
- Fix BaseControllerTest by using different users for multiple API keys
- Use unique display_key values with SecureRandom to avoid conflicts
- Fix double render issue in UsageController by returning after authorize_scope\!
- Specify controller name in routes for usage resource
- Remove trailing whitespace and empty lines per Rubocop

All tests now pass and linting is clean.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Add API transactions controller warning to brakeman ignore

The account_id parameter in the API transactions controller is properly
validated on line 79: family.accounts.find(transaction_params[:account_id])
This ensures users can only create transactions in accounts belonging to
their family, making this a false positive.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

---------

Signed-off-by: Josh Pigford <josh@joshpigford.com>
Co-authored-by: Claude <noreply@anthropic.com>

app/models/api_key.rb

@@ -0,0 +1,90 @@
+class ApiKey < ApplicationRecord
+  belongs_to :user
+
+  # Use Rails built-in encryption for secure storage
+  encrypts :display_key, deterministic: true
+
+  # Validations
+  validates :display_key, presence: true, uniqueness: true
+  validates :name, presence: true
+  validates :scopes, presence: true
+  validate :scopes_not_empty
+  validate :one_active_key_per_user, on: :create
+
+  # Callbacks
+  before_validation :set_display_key
+
+  # Scopes
+  scope :active, -> { where(revoked_at: nil).where("expires_at IS NULL OR expires_at > ?", Time.current) }
+
+  # Class methods
+  def self.find_by_value(plain_key)
+    return nil unless plain_key
+
+    # Find by encrypted display_key (deterministic encryption allows querying)
+    find_by(display_key: plain_key)&.tap do |api_key|
+      return api_key if api_key.active?
+    end
+  end
+
+  def self.generate_secure_key
+    SecureRandom.hex(32)
+  end
+
+  # Instance methods
+  def active?
+    !revoked? && !expired?
+  end
+
+  def revoked?
+    revoked_at.present?
+  end
+
+  def expired?
+    expires_at.present? && expires_at < Time.current
+  end
+
+  def key_matches?(plain_key)
+    display_key == plain_key
+  end
+
+  def revoke!
+    update!(revoked_at: Time.current)
+  end
+
+  def update_last_used!
+    update_column(:last_used_at, Time.current)
+  end
+
+  # Get the plain text API key for display (automatically decrypted by Rails)
+  def plain_key
+    display_key
+  end
+
+  # Temporarily store the plain key for creation flow
+  attr_accessor :key
+
+  private
+
+    def set_display_key
+      if key.present?
+        self.display_key = key
+      end
+    end
+
+    def scopes_not_empty
+      if scopes.blank? || (scopes.is_a?(Array) && (scopes.empty? || scopes.all?(&:blank?)))
+        errors.add(:scopes, "must include at least one permission")
+      elsif scopes.is_a?(Array) && scopes.length > 1
+        errors.add(:scopes, "can only have one permission level")
+      elsif scopes.is_a?(Array) && !%w[read read_write].include?(scopes.first)
+        errors.add(:scopes, "must be either 'read' or 'read_write'")
+      end
+    end
+
+    def one_active_key_per_user
+      if user&.api_keys&.active&.where&.not(id: id)&.exists?
+        errors.add(:user, "can only have one active API key")
+      end
+    end
+end