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>

db/migrate/20250612150749_create_doorkeeper_tables.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+class CreateDoorkeeperTables < ActiveRecord::Migration[7.2]
+  def change
+    create_table :oauth_applications do |t|
+      t.string  :name,    null: false
+      t.string  :uid,     null: false
+      # Remove `null: false` or use conditional constraint if you are planning to use public clients.
+      t.string  :secret,  null: false
+
+      # Remove `null: false` if you are planning to use grant flows
+      # that doesn't require redirect URI to be used during authorization
+      # like Client Credentials flow or Resource Owner Password.
+      t.text    :redirect_uri, null: false
+      t.string  :scopes,       null: false, default: ''
+      t.boolean :confidential, null: false, default: true
+      t.timestamps             null: false
+    end
+
+    add_index :oauth_applications, :uid, unique: true
+
+    create_table :oauth_access_grants do |t|
+      t.references :resource_owner,  null: false
+      t.references :application,     null: false
+      t.string   :token,             null: false
+      t.integer  :expires_in,        null: false
+      t.text     :redirect_uri,      null: false
+      t.string   :scopes,            null: false, default: ''
+      t.datetime :created_at,        null: false
+      t.datetime :revoked_at
+    end
+
+    add_index :oauth_access_grants, :token, unique: true
+    add_foreign_key(
+      :oauth_access_grants,
+      :oauth_applications,
+      column: :application_id
+    )
+
+    create_table :oauth_access_tokens do |t|
+      t.references :resource_owner, index: true
+
+      # Remove `null: false` if you are planning to use Password
+      # Credentials Grant flow that doesn't require an application.
+      t.references :application,    null: false
+
+      # If you use a custom token generator you may need to change this column
+      # from string to text, so that it accepts tokens larger than 255
+      # characters. More info on custom token generators in:
+      # https://github.com/doorkeeper-gem/doorkeeper/tree/v3.0.0.rc1#custom-access-token-generator
+      #
+      # t.text :token, null: false
+      t.string :token, null: false
+
+      t.string   :refresh_token
+      t.integer  :expires_in
+      t.string   :scopes
+      t.datetime :created_at, null: false
+      t.datetime :revoked_at
+
+      # The authorization server MAY issue a new refresh token, in which case
+      # *the client MUST discard the old refresh token* and replace it with the
+      # new refresh token. The authorization server MAY revoke the old
+      # refresh token after issuing a new refresh token to the client.
+      # @see https://datatracker.ietf.org/doc/html/rfc6749#section-6
+      #
+      # Doorkeeper implementation: if there is a `previous_refresh_token` column,
+      # refresh tokens will be revoked after a related access token is used.
+      # If there is no `previous_refresh_token` column, previous tokens are
+      # revoked as soon as a new access token is created.
+      #
+      # Comment out this line if you want refresh tokens to be instantly
+      # revoked after use.
+      t.string   :previous_refresh_token, null: false, default: ""
+    end
+
+    add_index :oauth_access_tokens, :token, unique: true
+
+    # See https://github.com/doorkeeper-gem/doorkeeper/issues/1592
+    if ActiveRecord::Base.connection.adapter_name == "SQLServer"
+      execute <<~SQL.squish
+        CREATE UNIQUE NONCLUSTERED INDEX index_oauth_access_tokens_on_refresh_token ON oauth_access_tokens(refresh_token)
+        WHERE refresh_token IS NOT NULL
+      SQL
+    else
+      add_index :oauth_access_tokens, :refresh_token, unique: true
+    end
+
+    add_foreign_key(
+      :oauth_access_tokens,
+      :oauth_applications,
+      column: :application_id
+    )
+
+    # Uncomment below to ensure a valid reference to the resource owner's table
+    # add_foreign_key :oauth_access_grants, <model>, column: :resource_owner_id
+    # add_foreign_key :oauth_access_tokens, <model>, column: :resource_owner_id
+  end
+end

db/migrate/20250612154522_fix_doorkeeper_resource_owner_id_for_uuid.rb

@@ -0,0 +1,9 @@
+class FixDoorkeeperResourceOwnerIdForUuid < ActiveRecord::Migration[7.1]
+  def up
+    change_column :oauth_access_tokens, :resource_owner_id, :string
+  end
+
+  def down
+    change_column :oauth_access_tokens, :resource_owner_id, :integer
+  end
+end

db/migrate/20250613002027_create_api_keys.rb

@@ -0,0 +1,17 @@
+class CreateApiKeys < ActiveRecord::Migration[7.2]
+  def change
+    create_table :api_keys, id: :uuid do |t|
+      t.string :key
+      t.string :name
+      t.references :user, null: false, foreign_key: true, type: :uuid
+      t.json :scopes
+      t.datetime :last_used_at
+      t.datetime :expires_at
+      t.datetime :revoked_at
+
+      t.timestamps
+    end
+    add_index :api_keys, :key
+    add_index :api_keys, :revoked_at
+  end
+end

db/migrate/20250613100842_add_display_key_to_api_keys.rb

@@ -0,0 +1,6 @@
+class AddDisplayKeyToApiKeys < ActiveRecord::Migration[7.2]
+  def change
+    add_column :api_keys, :display_key, :string, null: false
+    add_index :api_keys, :display_key, unique: true
+  end
+end

db/migrate/20250613101036_remove_key_from_api_keys.rb

@@ -0,0 +1,5 @@
+class RemoveKeyFromApiKeys < ActiveRecord::Migration[7.2]
+  def change
+    remove_column :api_keys, :key, :string
+  end
+end

db/migrate/20250613101051_remove_key_index_from_api_keys.rb

@@ -0,0 +1,5 @@
+class RemoveKeyIndexFromApiKeys < ActiveRecord::Migration[7.2]
+  def change
+    remove_index :api_keys, :key if index_exists?(:api_keys, :key)
+  end
+end

db/migrate/20250613152743_fix_doorkeeper_access_grants_resource_owner_id_for_uuid.rb

@@ -0,0 +1,9 @@
+class FixDoorkeeperAccessGrantsResourceOwnerIdForUuid < ActiveRecord::Migration[7.2]
+  def up
+    change_column :oauth_access_grants, :resource_owner_id, :string
+  end
+
+  def down
+    change_column :oauth_access_grants, :resource_owner_id, :bigint
+  end
+end

db/schema.rb

@@ -10,7 +10,7 @@
 #
 # It's strongly recommended that you check this file into your version control system.
 
-ActiveRecord::Schema[7.2].define(version: 2025_06_10_181219) do
+ActiveRecord::Schema[7.2].define(version: 2025_06_13_152743) do
   # These are extensions that must be enabled in order to support this database
   enable_extension "pgcrypto"
   enable_extension "plpgsql"
@@ -88,6 +88,21 @@ ActiveRecord::Schema[7.2].define(version: 2025_06_10_181219) do
     t.index ["addressable_type", "addressable_id"], name: "index_addresses_on_addressable"
   end
 
+  create_table "api_keys", id: :uuid, default: -> { "gen_random_uuid()" }, force: :cascade do |t|
+    t.string "name"
+    t.uuid "user_id", null: false
+    t.json "scopes"
+    t.datetime "last_used_at"
+    t.datetime "expires_at"
+    t.datetime "revoked_at"
+    t.datetime "created_at", null: false
+    t.datetime "updated_at", null: false
+    t.string "display_key", null: false
+    t.index ["display_key"], name: "index_api_keys_on_display_key", unique: true
+    t.index ["revoked_at"], name: "index_api_keys_on_revoked_at"
+    t.index ["user_id"], name: "index_api_keys_on_user_id"
+  end
+
   create_table "balances", id: :uuid, default: -> { "gen_random_uuid()" }, force: :cascade do |t|
     t.uuid "account_id", null: false
     t.date "date", null: false
@@ -199,7 +214,12 @@ ActiveRecord::Schema[7.2].define(version: 2025_06_10_181219) do
     t.boolean "excluded", default: false
     t.string "plaid_id"
     t.jsonb "locked_attributes", default: {}
+    t.index ["account_id", "date"], name: "index_entries_on_account_id_and_date"
     t.index ["account_id"], name: "index_entries_on_account_id"
+    t.index ["amount"], name: "index_entries_on_amount"
+    t.index ["date"], name: "index_entries_on_date"
+    t.index ["entryable_id", "entryable_type"], name: "index_entries_on_entryable"
+    t.index ["excluded"], name: "index_entries_on_excluded"
     t.index ["import_id"], name: "index_entries_on_import_id"
   end
 
@@ -210,6 +230,7 @@ ActiveRecord::Schema[7.2].define(version: 2025_06_10_181219) do
     t.date "date", null: false
     t.datetime "created_at", null: false
     t.datetime "updated_at", null: false
+    t.index ["date", "from_currency", "to_currency"], name: "index_exchange_rates_on_date_and_currencies"
     t.index ["from_currency", "to_currency", "date"], name: "index_exchange_rates_on_base_converted_date_unique", unique: true
     t.index ["from_currency"], name: "index_exchange_rates_on_from_currency"
     t.index ["to_currency"], name: "index_exchange_rates_on_to_currency"
@@ -408,6 +429,48 @@ ActiveRecord::Schema[7.2].define(version: 2025_06_10_181219) do
     t.index ["chat_id"], name: "index_messages_on_chat_id"
   end
 
+  create_table "oauth_access_grants", force: :cascade do |t|
+    t.string "resource_owner_id", null: false
+    t.bigint "application_id", null: false
+    t.string "token", null: false
+    t.integer "expires_in", null: false
+    t.text "redirect_uri", null: false
+    t.string "scopes", default: "", null: false
+    t.datetime "created_at", null: false
+    t.datetime "revoked_at"
+    t.index ["application_id"], name: "index_oauth_access_grants_on_application_id"
+    t.index ["resource_owner_id"], name: "index_oauth_access_grants_on_resource_owner_id"
+    t.index ["token"], name: "index_oauth_access_grants_on_token", unique: true
+  end
+
+  create_table "oauth_access_tokens", force: :cascade do |t|
+    t.string "resource_owner_id"
+    t.bigint "application_id", null: false
+    t.string "token", null: false
+    t.string "refresh_token"
+    t.integer "expires_in"
+    t.string "scopes"
+    t.datetime "created_at", null: false
+    t.datetime "revoked_at"
+    t.string "previous_refresh_token", default: "", null: false
+    t.index ["application_id"], name: "index_oauth_access_tokens_on_application_id"
+    t.index ["refresh_token"], name: "index_oauth_access_tokens_on_refresh_token", unique: true
+    t.index ["resource_owner_id"], name: "index_oauth_access_tokens_on_resource_owner_id"
+    t.index ["token"], name: "index_oauth_access_tokens_on_token", unique: true
+  end
+
+  create_table "oauth_applications", force: :cascade do |t|
+    t.string "name", null: false
+    t.string "uid", null: false
+    t.string "secret", null: false
+    t.text "redirect_uri", null: false
+    t.string "scopes", default: "", null: false
+    t.boolean "confidential", default: true, null: false
+    t.datetime "created_at", null: false
+    t.datetime "updated_at", null: false
+    t.index ["uid"], name: "index_oauth_applications_on_uid", unique: true
+  end
+
   create_table "other_assets", id: :uuid, default: -> { "gen_random_uuid()" }, force: :cascade do |t|
     t.datetime "created_at", null: false
     t.datetime "updated_at", null: false
@@ -606,6 +669,7 @@ ActiveRecord::Schema[7.2].define(version: 2025_06_10_181219) do
     t.datetime "created_at", null: false
     t.datetime "updated_at", null: false
     t.index ["tag_id"], name: "index_taggings_on_tag_id"
+    t.index ["taggable_id", "taggable_type"], name: "index_taggings_on_taggable_id_and_type"
     t.index ["taggable_type", "taggable_id"], name: "index_taggings_on_taggable"
   end
 
@@ -718,6 +782,7 @@ ActiveRecord::Schema[7.2].define(version: 2025_06_10_181219) do
   add_foreign_key "accounts", "plaid_accounts"
   add_foreign_key "active_storage_attachments", "active_storage_blobs", column: "blob_id"
   add_foreign_key "active_storage_variant_records", "active_storage_blobs", column: "blob_id"
+  add_foreign_key "api_keys", "users"
   add_foreign_key "balances", "accounts", on_delete: :cascade
   add_foreign_key "budget_categories", "budgets"
   add_foreign_key "budget_categories", "categories"
@@ -737,6 +802,8 @@ ActiveRecord::Schema[7.2].define(version: 2025_06_10_181219) do
   add_foreign_key "invitations", "users", column: "inviter_id"
   add_foreign_key "merchants", "families"
   add_foreign_key "messages", "chats"
+  add_foreign_key "oauth_access_grants", "oauth_applications", column: "application_id"
+  add_foreign_key "oauth_access_tokens", "oauth_applications", column: "application_id"
   add_foreign_key "plaid_accounts", "plaid_items"
   add_foreign_key "plaid_items", "families"
   add_foreign_key "rejected_transfers", "transactions", column: "inflow_transaction_id"

db/seeds/oauth_applications.rb

@@ -0,0 +1,14 @@
+# Create OAuth applications for Maybe's first-party apps
+# These are the only OAuth apps that will exist - external developers use API keys
+
+# Maybe iOS App
+ios_app = Doorkeeper::Application.find_or_create_by(name: "Maybe iOS") do |app|
+  app.redirect_uri = "maybe://oauth/callback"
+  app.scopes = "read_accounts read_transactions read_balances"
+  app.confidential = false # Public client (mobile app)
+end
+
+puts "Created OAuth applications:"
+puts "iOS App - Client ID: #{ios_app.uid}"
+puts ""
+puts "External developers should use API keys instead of OAuth."