api_keys 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f2eb256f13ca90621678457aba6cfb4892da3c0497f6932b797f1648a672c009
-  data.tar.gz: c74450d08743ee817e41590e200fe244621c742b2f5687e257499b31867f4e6e
+  metadata.gz: 3183ee0be98a005fd2fc318937f9f8aeb6d8a6c0528a0b75d7234e55cde80480
+  data.tar.gz: 67080c1cddf08ee647657c8845a9332c61279249d8c9765ea0ad6fda4e4961a3
 SHA512:
-  metadata.gz: 2807a51c53e139efbb8d464067b9640e682ef72d7c70c95e8ba1c3d16f97e6818d4e89251e1db40a4be516c9e1294057c1e2903e2e7d55669576044d0e2952a5
-  data.tar.gz: 5927cd629287b119d7224306c4e28f35d3dd38241951735ceffeaaada381317e48a0168464e4f101828ef9ba3a7634bc13b9b9146e7725a6bf50f982aaeaa1b4
+  metadata.gz: ff1adbe9b462443d7f278013030780bfc99ec2ef5acb6a814966a3530950147069bf33cc79d3d35ae8f6af8f76bf43b3a9a42d9692e22f9757df3c172b186535
+  data.tar.gz: 6f3f9febcd26069d345739d6268c8bcd4acce174ccdd2c24f915c8cfabf5404c2aa708e3538219ad8be30c8392d633101a6f1e52d7b099e123bf01474511859e

data/CHANGELOG.md

@@ -1,3 +1,54 @@
+## [Unreleased]
+
+## [0.4.0] - 2026-08-09
+
+This security-focused release hardens authentication, authorization, credential handling, the self-serve dashboard, background jobs, configuration, dependencies, CI, and the release supply chain. Upgrading is strongly recommended. Existing installations must apply the authentication lookup migration before deploying this version.
+
+### Security
+
+- Make token caching a non-authoritative ID lookup hint: every hit reloads current database state and cryptographically re-verifies the presented token, so revocation, expiration, scope changes, and cache poisoning fail closed.
+- Replace token-derived SHA1 cache identifiers with SHA256 and prevent plaintext tokens, digests, stored public tokens, request objects, and authentication result objects from leaking through gem logs, inspection, serialization, errors, or async callback arguments.
+- Bound token sizes, bcrypt input length, bcrypt cost, and bcrypt candidate work; add an indexed prefix/last-four/algorithm lookup for existing installations.
+- Bound historical-prefix discovery and fall back to an indexed last-four lookup so cache poisoning or unusually many retired prefixes cannot create unbounded request work or strand valid bcrypt keys.
+- Serialize all quota checks and inserts by locking the owner row, including direct Active Record creation paths.
+- Enforce immutable authentication identity fields, supported digest formats, bounded scopes/metadata/identifiers/session payloads, runtime permission ceilings, configured key types, and fail-closed environment isolation.
+- Require every newly created key to have a configured type once key-types mode is enabled; existing untyped legacy keys remain compatible.
+- Require explicit finite permissions and `revocable: false` for intentionally stored public tokens.
+- Fail closed when dashboard owner authentication is missing or ineffective; bind one-time session tokens to their created key; reject malformed create/update payloads; scope every dashboard lookup to the current owner; and add no-store, anti-framing, referrer, MIME-sniffing, and permissions headers.
+- Apply an enforcing nonce-based dashboard Content Security Policy and remove inline handlers, un-nonced scripts, third-party assets, and inline style attributes from credential-bearing views.
+- Enforce HTTPS authentication by default in production, disable query-string credentials in the demo, and remove third-party code from pages that handle tokens.
+- Pin GitHub Actions to immutable commits and add dependency auditing, Brakeman, CodeQL, dependency review, and Dependabot configuration.
+- Remove the unused Claude Code workflow and its third-party CI/OIDC surface.
+- Encrypt one-time secret-token handoffs inside the Rails session with an application-derived AES-256-GCM key, bind them to the created key, expire them after ten minutes, and delete them on first retrieval. Legacy in-flight plaintext handoffs remain readable for upgrade continuity but are never newly written.
+
+### Reliability
+
+- Execute authentication callbacks exactly once with serializable, credential-free context hashes.
+- Resolve job queues dynamically, prevent out-of-order/future jobs from corrupting usage timestamps, and keep request counters atomic.
+- Validate security-sensitive global and per-owner configuration early and store permission policy as defensive frozen copies.
+- Ensure each appraisal excludes the next Rails line's prereleases; Rails 7.2 uses its upstream-compatible Minitest 5 while Rails 8/default suites remain on Minitest 6.
+- Return `403 Forbidden` when a valid key lacks a required scope while retaining `401 Unauthorized` for missing or invalid credentials.
+- Honor the public `parent_controller` configuration (with a backward-compatible internal Engine fallback), cascade owner deletion across non-revocable keys, and debounce `last_used_at` jobs for one minute by default when exact request counting is disabled.
+- Remove redundant single-column polymorphic-owner indexes from new-install migrations and exclude development-only metadata from built gems.
+- Resolve every finding recorded in [issue #12](https://github.com/rameerez/api_keys/issues/12) through a code fix, test, explicit bounded design, or superseding hardening control.
+
+### Upgrade notes
+
+- Existing installations should run `rails generate api_keys:add_authentication_index` and `rails db:migrate` before deploying this version.
+- Invalid expiration presets now raise `ArgumentError` instead of silently creating a key without expiration.
+- Authentication identity fields (`token_digest`, algorithm, prefix, last four, owner, key type, and environment) can no longer be changed through normal Active Record updates after creation.
+- Typed keys with blank or retired environments now fail closed. Repair any such legacy rows before deployment; untyped legacy keys are unaffected.
+- When `key_types` is configured, new keys must pass `key_type:` or use a configured `default_key_type`; this does not invalidate existing untyped keys.
+- Authentication callbacks now execute asynchronously exactly once with small, credential-free context hashes instead of request, result, or model objects. Update callback consumers and ensure the application has a durable Active Job backend where delivery matters.
+- Production authentication now requires HTTPS by default and fails closed when a request appears insecure. Verify TLS termination and trusted proxy forwarding before deployment.
+- Scope and permission policy is enforced at creation, update, and authentication time. Malformed scopes and scopes above a configured ceiling are rejected; blank scopes deny access whenever a scope policy is enabled.
+- Reassess every permission ceiling configured with `public: true`. The gem validates that public tokens are non-revocable and finitely scoped, but only the host application can determine whether each named permission is safe for an untrusted client.
+- The actively security-tested matrix is Ruby 3.3, 3.4, and 4.0 with Rails 7.2, 8.0, and 8.1. The gemspec continues to permit Ruby 3.1+ for compatibility, but older runtimes are outside the documented security-support matrix.
+- Missing-scope responses now use HTTP 403 instead of 401. Clients that branch on the previous status should update.
+- New one-time token handoffs are encrypted and expire after ten minutes. Custom integrations must use `ApiKeys::TokenSession` rather than reading its internal session payload directly.
+- `last_used_at` updates are debounced for one minute by default when `track_requests_count` is false. Set `stats_update_interval = 0` for per-request timestamps; enabling exact request counting necessarily enqueues a stats job for every successful authentication.
+- Deleting an owner now removes all associated API-key rows, including non-revocable types. Direct user-level `revoke!`, `destroy`, and `destroy!` protections remain unchanged.
+
 ## [0.3.0] - 2026-02-09
 
 - Add Stripe-style key types and environments (publishable/secret keys with test/live isolation)

data/README.md

@@ -5,7 +5,7 @@
 > [!TIP]
 > **🚀 Ship your next Rails app 10x faster!** I've built **[RailsFast](https://railsfast.com/?ref=api_keys)**, a production-ready Rails boilerplate template that comes with everything you need to launch a software business in days, not weeks. Go [check it out](https://railsfast.com/?ref=api_keys)!
 
-`api_keys` makes it simple to add secure, production-ready API key authentication to any Rails app. Generate keys, restrict scopes, auto-expire tokens, revoke tokens, gate endpoints. It also provides a self-serve dashboard for your users to self-issue and manage their API keys themselves. All tokens are hashed securely by default, and never stored in plaintext.
+`api_keys` makes it simple to add secure, production-ready API key authentication to any Rails app. Generate keys, restrict scopes, auto-expire tokens, revoke tokens, and gate endpoints. It also provides a self-serve dashboard for users to issue and manage their own API keys. Secret tokens are hashed and shown only once. Plaintext is stored only for a key type that you explicitly mark as public, non-revocable, and limited to a finite permission set.
 
 [ 🟢 [Live interactive demo website](https://apikeys.rameerez.com) ]
 
@@ -30,6 +30,17 @@ rails db:migrate
 
 And you're done!
 
+### Upgrading an existing installation
+
+Install the bounded bcrypt authentication lookup index before deploying the current hardening changes:
+
+```bash
+rails generate api_keys:add_authentication_index
+rails db:migrate
+```
+
+The generated migration is idempotent and uses a concurrent PostgreSQL index where supported.
+
 ## Quick Start
 
 Just add `has_api_keys` to your desired model. For example, if you want your `User` records to have API keys, you'd have:
@@ -101,6 +112,16 @@ class ApplicationController < ActionController::Base
 end
 ```
 
+If the mounted dashboard should inherit from a different controller, configure it in the same initializer before the engine controllers load:
+
+```ruby
+ApiKeys.configure do |config|
+  config.parent_controller = "Admin::ApplicationController"
+end
+```
+
+The setting accepts a controller class or a valid constant-name string and defaults to `::ApplicationController`.
+
 #### Common scenarios
 
 **Organization with user membership:**
@@ -260,7 +281,7 @@ module Settings
     end
 
     def success
-      @token = ApiKeys::TokenSession.retrieve_once(session)
+      @token = ApiKeys::TokenSession.retrieve_once(session, api_key: @api_key)
       redirect_to settings_api_keys_path, alert: "Token can only be shown once." and return if @token.blank?
     end
 
@@ -407,20 +428,26 @@ Methods available on `ApiKeys::ApiKey` instances:
 
 ### Token Session Helper
 
-Manages the "show token once" pattern for secret keys:
+Manages the "show token once" pattern for secret keys. The helper encrypts each handoff with an application-derived AES-256-GCM key, binds it to the created key, expires it after ten minutes, and deletes it on first retrieval. The session contains only ciphertext and the non-secret key ID—not the plaintext token—even when the host uses Rails' encrypted cookie session store.
 
 ```ruby
 # Store token after creation
 ApiKeys::TokenSession.store(session, @api_key)
 
-# Retrieve and clear (returns nil on subsequent calls)
-@token = ApiKeys::TokenSession.retrieve_once(session)
+# Retrieve and clear, bound to the expected key (nil on mismatch or reuse)
+@token = ApiKeys::TokenSession.retrieve_once(session, api_key: @api_key)
 
 # With custom session key (if managing multiple token types)
 ApiKeys::TokenSession.store(session, @api_key, key: :my_custom_key)
-@token = ApiKeys::TokenSession.retrieve_once(session, key: :my_custom_key)
+@token = ApiKeys::TokenSession.retrieve_once(
+  session,
+  key: :my_custom_key,
+  api_key: @api_key
+)
 ```
 
+Treat the session payload as private implementation detail; use `store`, `available?`, and `retrieve_once` rather than reading it directly. A failed, expired, tampered, mismatched, or reused handoff returns `nil` and fails closed.
+
 ---
 
 ### Expiration Options Helper
@@ -668,7 +695,7 @@ If you want to write your own front-end instead of using the provided dashboard,
 ```ruby
 @api_key = @user.create_api_key!(
   name: "my-key",
-  scopes: "['read', 'write']",
+  scopes: %w[read write],
   expires_at: 42.days.from_now
 )
 
@@ -677,14 +704,14 @@ plaintext_token = @api_key.token
 # => ak_123abc...
 ```
 
-For security reasons, the **gem does not store the generated key** in the database.
+For security reasons, the gem does not store generated **secret** keys in the database.
 
-We only store a secure hash (SHA256 by default), so the API key / API token itself is only available in plaintext immediately after creation, as `@api_key.token` – the `.token` method won't work any other time.
+Only a secure digest is stored (SHA256 by default), so a secret token is available as `@api_key.token` only on the newly created in-memory object. Reloading clears it. The explicit public-key mode described below is the sole plaintext-storage exception.
 
 With this token, your users can make calls to your endpoints by attaching it as an `"Authorization: Bearer ak_123abc..."` in their HTTP calls headers, like this:
 
 ```bash
-curl -X GET -H "Authorization: Bearer ak_123abc..."   "http://example.com/api/endpoint"
+curl -X GET -H "Authorization: Bearer YOUR_API_KEY" "https://example.com/api/endpoint" # gitleaks:allow
 ```
 
 ### Listing all keys for users
@@ -814,6 +841,8 @@ You can require a specific scope for any endpoint like:
 authenticate_api_key!(scope: "write")
 ```
 
+A missing or invalid credential returns HTTP 401. A valid key that lacks the requested scope is authenticated but unauthorized, so it returns HTTP 403 with `error: "missing_scope"`.
+
 It may be cleaner if you pass it as a Proc to `before_action` – and it may result in better-organized code if you do it endpoint-per-endpoint, immediately before each method definition, like this:
 
 ```ruby
@@ -904,7 +933,7 @@ By default, the `api_key` gem expects API keys to come *exclusively* as HTTP Aut
 https://example.com/api/endpoint?api_key=ak_123abc...
 ```
 
-This is not recommended security-wise because you'll be leaking API tokens everywhere in your logs, but if you want to enable this, just set the query param name you're expecting the API key token to be in:
+Do not enable this in production. URLs routinely reach logs, browser history, analytics, proxies, caches, and referrer data. If a constrained development/test integration requires it, set the expected parameter name explicitly:
 
 ```ruby
 config.query_param = "api_key"
@@ -912,7 +941,7 @@ config.query_param = "api_key"
 
 ### Changing the hashing function to `bcrypt` for maximum security
 
-By default, the `api_keys` gem hashes tokens using `sha256`, which is the industry standard for API keys (used by Stripe, GitHub, AWS). SHA256 is secure for high-entropy tokens because the 192 bits of randomness make brute-force attacks computationally infeasible. We use SHA256 and not other hasing algorithms for fast token lookup and low-latency API authentication.
+By default, `api_keys` hashes tokens using SHA256. A fast digest is appropriate here because tokens are generated from 192 bits of randomness by default (and never less than 128 bits), rather than chosen by a human. It also permits indexed, low-latency authentication.
 
 If you need slower, password-grade hashing (e.g., for extremely sensitive tokens), you can switch to bcrypt:
 
@@ -920,47 +949,53 @@ If you need slower, password-grade hashing (e.g., for extremely sensitive tokens
 config.hash_strategy = :bcrypt
 ```
 
-Note: bcrypt is ~50–100x slower than SHA256. For most API use cases, sha256 is more than sufficient.
+Note: bcrypt is substantially slower than SHA256. For most API use cases, SHA256 is appropriate because generated tokens have at least 128 bits of cryptographic randomness.
 
-`sha256` has O(1) lookup, `bcrypt` doesn't. This means that if you switch to `bcrypt`, you may observe ~100ms lags on every API call, for every token auth that's not cached.
+`sha256` has a direct digest lookup; bcrypt requires a bounded candidate lookup and an expensive comparison. Add the authentication index shown in the upgrade section before enabling bcrypt. The gem rejects total bcrypt token values over 72 bytes to prevent bcrypt's historical input truncation behavior, so keep the configured prefix plus encoded random portion within that bound.
 
-For 99% of APIs, `sha256` is more than secure enough — and far better for performance.
+Use SHA256 for ordinary high-entropy API keys unless your threat model specifically calls for a deliberately expensive verifier.
 
 ### Increase cache TTL
 
-We cache token lookups to improve performance, especially for repeated requests. This keeps `bcrypt` and `sha256` strategies fast under load.
+We cache only the database ID lookup hint. Every cache hit reloads the current row and cryptographically re-verifies the presented token; cached records never authorize a request by themselves.
 
-By default, we use a 5-second TTL, which offers a strong balance: most requests benefit from caching, while revoked keys stop working almost immediately.
+By default, the hint uses a 5-second TTL. Revocation, expiration, scope changes, environment changes, and other stored authorization state are checked from the database on every request and take effect immediately for new authentication attempts.
 
-If security is your top priority (e.g. rapid revocation after suspected key compromise), you can disable caching entirely:
+You can disable the lookup hint if you prefer not to use Rails.cache:
 
 ```ruby
 config.cache_ttl = 0.seconds # disables caching
 ```
 
-If performance matters more than real-time revocation, increase the TTL to reduce DB hits:
+Increase the TTL to reduce repeated lookup work without making cached state authoritative:
 
 ```ruby
-config.cache_ttl = 2.minutes # boosts performance at cost of slower revocation
+config.cache_ttl = 2.minutes
 ```
 
-⚠️ Security note: Revoked keys may remain valid for up to cache_ttl. For strict real-time revocation, set cache_ttl = 0.
-
 
 ## Callbacks: analytics, logging, usage monitoring & auditing
 
-The gem offers two callbacks that get executed every single time an API key is checked and authenticated (through `authenticate_api_key!` in controllers, for example)
+The controller concern can enqueue two callbacks for each authentication attempt. To keep secrets out of job payloads, callbacks receive small serializable context hashes—not request, result, or model objects.
 
 You can define logic for them:
 ```ruby
-config.before_authentication = ->(request) { Rails.logger.info "Authenticating request: #{request.uuid}" }
+config.before_authentication = ->(context) do
+  Rails.logger.info "Authenticating request: #{context[:request_uuid]}"
+end
 
-config.after_authentication = ->(result) { MyAnalytics.track_auth(result) }
+config.after_authentication = ->(context) do
+  MyAnalytics.track_auth(
+    success: context[:success],
+    error_code: context[:error_code],
+    api_key_id: context[:api_key_id]
+  )
+end
 ```
 
 This is especially useful if you want to build custom monitoring, usage tracking or auditing systems on top of the `api_keys` gem.
 
-Since these callbacks get called every single time an endpoint request is made, we can't just execute the code synchronously, blocking the thread and making the endpoint lag. Instead, we enqueue an async job that process the callback code, however long it is. You can configure which queue these jobs get enqueued to.
+The `before_authentication` context contains `request_uuid`. The `after_authentication` context contains `success`, `error_code`, `api_key_id`, and, when scopes were requested, `required_scope_check`. Jobs are asynchronous, so “before” means it is enqueued before verification; queue execution order is not guaranteed. Configure a persistent Active Job backend and the callback queue appropriate for your application.
 
 The downside of this, of course, is that callbacks will only work if you have a valid, well-configured Active Job backend for your Rails app, like Sidekiq or [`solid_queue`](https://github.com/rails/solid_queue/), which comes by default in Rails 8. If Active Job is not well configured, well, your callbacks just won't get executed.
 
@@ -972,6 +1007,15 @@ There's also a `track_requests_count` config option that you can turn on so the
 
 But again, this is turned off by default for performance purposes, and depends on having a working, well-configured Active Job backend.
 
+When exact request counting is off, `last_used_at` updates are debounced for one minute by default to avoid one queue insert and database write for every high-volume API call:
+
+```ruby
+config.stats_update_interval = 5.minutes # coarser, lower write volume
+config.stats_update_interval = 0         # record every successful request
+```
+
+Enabling `track_requests_count` bypasses this debounce because every successful request must be counted. Set `enable_async_operations = false` if the application handles statistics and callbacks elsewhere and wants the gem to enqueue no background jobs.
+
 ## Key Types: Stripe-style Publishable & Secret Keys
 
 For applications that distribute software with embedded API keys (desktop apps, mobile apps, CLI tools), you may want to differentiate between key types with different permission levels. The `api_keys` gem supports Stripe-style publishable/secret key types with optional test/live environment isolation.
@@ -980,9 +1024,9 @@ For applications that distribute software with embedded API keys (desktop apps,
 
 When you distribute software with an embedded API key, that key can potentially be extracted by malicious users. Key types solve this by letting you create:
 
-- **Publishable keys** (`pk_test_...`, `pk_live_...`): Safe to embed in distributed apps. Limited permissions (e.g., can only validate licenses, not issue new ones). Cannot be revoked (to prevent accidentally breaking all deployed apps).
+- **Publishable keys** (`pk_test_...`, `pk_live_...`): Intentionally exposed identifiers. Embed them only when every configured permission is safe for an untrusted public client; assume anyone can extract and abuse them. They cannot be revoked individually.
 
-- **Secret keys** (`sk_test_...`, `sk_live_...`): Full access, meant for server-side use only. Can be revoked anytime.
+- **Secret keys** (`sk_test_...`, `sk_live_...`): Sensitive server-side credentials whose exact access depends on their scopes. They can be revoked anytime.
 
 ### Configuration
 
@@ -1015,6 +1059,10 @@ ApiKeys.configure do |config|
 
   # Enable strict environment isolation (test keys fail in prod, live keys fail in dev)
   config.strict_environment_isolation = true
+
+  # Optional: use this type when create_api_key! omits key_type.
+  # Without a default, every new key must specify key_type explicitly.
+  config.default_key_type = :secret
 end
 ```
 
@@ -1029,7 +1077,7 @@ pk = user.create_api_key!(
 )
 pk.token  # => "pk_live_abc123..."
 
-# Create a secret key (full access)
+# Create a secret key (access is controlled by its scopes/type ceiling)
 sk = user.create_api_key!(
   name: "Admin Dashboard",
   key_type: :secret
@@ -1070,6 +1118,7 @@ pk.destroy!    # Raises ApiKeys::Errors::KeyNotRevocableError
 ```
 
 The dashboard UI automatically hides the revoke button for non-revocable keys.
+Deleting the owning record still cascades deletion to all of its API keys, including non-revocable types, so account deletion and privacy-erasure flows cannot be blocked. The non-revocable guard applies to direct key-level user actions, not owner lifecycle cleanup.
 
 ### Public Keys (Viewable Tokens)
 
@@ -1081,7 +1130,7 @@ This is especially problematic when combined with `limit: 1`, which restricts us
 
 #### The Solution: Storing Public Keys
 
-For publishable keys—which are *designed* to be embedded in client-side code and distributed apps—there's no security benefit to hiding the token. These keys are meant to be public! Stripe, for example, lets you view your publishable key anytime in the dashboard.
+For publishable keys that grant *only operations safe for an unauthenticated public client*, hiding the token provides no secrecy benefit: distributed clients necessarily expose it. Never use this design for a permission that protects confidential data or sensitive actions.
 
 The `public: true` option stores the plaintext token in metadata so users can view it again:
 
@@ -1102,23 +1151,24 @@ config.key_types = {
 }
 ```
 
-#### Security: Why This is Safe
+#### Security constraints
 
 > [!IMPORTANT]
-> The `public` option only works when BOTH conditions are met:
+> The `public` option only works when all of these conditions are met:
 >  - `public: true` is set in the key type configuration
 >  - `revocable: false` is set (non-revocable keys only)
+>  - `permissions` is a finite, non-empty array (never `:all`)
 
-This double-check is a deliberate safety measure:
+These checks are deliberate safety measures:
 
-1. **Secret keys are NEVER stored** — Even if you accidentally set `public: true` on a secret key type, the gem checks for `revocable: false` as well. Secret keys are revocable by default, so they're protected.
+1. **Configuration is validated early** — Public types must explicitly be non-revocable and have a finite, non-empty permission ceiling.
 
 2. **Revocable keys are NEVER stored** — If a key can be revoked, users can always delete it and create a new one. There's no lockout risk, so no need to store the token.
 
-3. **Only truly public keys are stored** — Publishable keys with limited permissions, designed for client-side embedding, are the only keys that get stored. These tokens provide no security benefit when hidden—they're meant to be distributed.
+3. **Your application defines what is public** — The gem cannot infer the business impact of a permission name. Only mark a type public when every permission in its ceiling is safe for an unauthenticated client to possess.
 
 > [!WARNING]
-> ⚠️ **Never set `public: true` on secret keys or any key type with sensitive permissions.** The gem prevents this by requiring `revocable: false`, but you should also never configure it that way.
+> ⚠️ **Never set `public: true` on secret keys or any key type with sensitive permissions.** Validation prevents `:all` and missing permission ceilings, but your application remains responsible for classifying each named permission correctly.
 
 When a key is public, the dashboard shows a "Show" button to reveal the full token:
 
@@ -1143,6 +1193,10 @@ With `strict_environment_isolation = true`, keys can only authenticate in their
 
 This prevents accidentally using test keys in production (or vice versa).
 
+Typed keys always require a non-blank stored environment. When `environments` is configured, authentication also rejects typed keys whose stored environment is no longer configured, even if strict isolation is disabled. Untyped legacy keys remain compatible.
+
+Once `key_types` is configured, all newly created keys must supply `key_type:` or use `default_key_type`; the gem will not silently create a new untyped key outside the configured permission and environment policy. Existing untyped keys created before enabling the feature continue to authenticate under the documented legacy rules.
+
 ### Key Limits
 
 The `limit` option restricts how many keys of a type can exist per owner per environment:
@@ -1181,7 +1235,7 @@ Existing keys without `key_type`/`environment` continue to work normally (backwa
 ## Enterprise-ready by design
 The `api_keys` gem ships with:
 
- - Flexible storage
+ - Active Record storage across supported Rails databases
  - Async hooks
  - ActiveJob support
  - Polymorphic ownership (User, Org, etc.)
@@ -1203,11 +1257,17 @@ There's a demo Rails app showcasing the features in the `api_keys` gem under `te
 
 ## Testing
 
-Run the test suite with `bundle exec rake test`
+Run the default test suite with `bundle exec rake test`. Run all supported Rails appraisals with:
+
+```bash
+bundle exec appraisal rails-7.2 rake test
+bundle exec appraisal rails-8.0 rake test
+bundle exec appraisal rails-8.1 rake test
+```
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then run `bundle exec rake test`. You can also run `bin/console` for an interactive prompt.
 
 To install this gem onto your local machine, run `bundle exec rake install`.
 
@@ -1215,6 +1275,8 @@ To install this gem onto your local machine, run `bundle exec rake install`.
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/rameerez/api_keys. Our code of conduct is: just be nice and make your mom proud of what you do and post online.
 
+Please report vulnerabilities privately as described in [SECURITY.md](SECURITY.md), not in a public issue.
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/SECURITY.md

@@ -0,0 +1,33 @@
+# Security Policy
+
+`api_keys` handles authentication credentials. Please report suspected vulnerabilities privately and avoid including real API keys, production data, or customer information in any report.
+
+## Supported versions
+
+Security fixes are released for the latest published version. The maintained test matrix covers Ruby 3.3, 3.4, and 4.0 with patched Rails 7.2, 8.0, and 8.1 releases. Older Ruby and Rails versions may remain installable for compatibility, but runtimes that no longer receive upstream security fixes are not security-supported.
+
+## Reporting a vulnerability
+
+Use GitHub's **Report a vulnerability** button on the [`api_keys` security advisories page](https://github.com/rameerez/api_keys/security/advisories) so the report and any proposed fix remain private. If GitHub's private reporting flow is unavailable, email `rubygems@rameerez.com` with the subject `api_keys security report`.
+
+Include:
+
+- the affected version and environment;
+- a minimal reproduction or proof of concept;
+- the impact you believe is possible; and
+- any suggested mitigation or patch.
+
+Do not open a public issue for an undisclosed vulnerability. We will acknowledge the report, investigate it, and coordinate disclosure and credit with you. If the issue affects downstream applications, we will prioritize a patched release and clear upgrade guidance.
+
+## Operational security
+
+Applications remain responsible for:
+
+- trusted TLS/proxy configuration, endpoint authorization, and request rate limiting;
+- encrypted, `Secure`, `HttpOnly`, appropriately `SameSite` session cookies for the one-time dashboard token handoff;
+- database, cache, queue, log, backup, and observability access controls;
+- filtering any query-parameter credential name from application and proxy logs if that opt-in transport is enabled;
+- classifying every permission on a `public: true` key type as safe for an untrusted public client and maintaining a disable/replacement procedure for non-revocable identifiers; and
+- prompt dependency/runtime patching and a durable background-job backend where callbacks or usage statistics are required.
+
+The gem bounds authentication work, but applications should still rate-limit credential endpoints. Do not treat a key prefix, last four characters, cache entry, or public key as proof of authorization.

data/app/controllers/api_keys/application_controller.rb

@@ -1,11 +1,13 @@
 # frozen_string_literal: true
 
+require "securerandom"
+
 module ApiKeys
   # Base controller for the ApiKeys engine.
   # Inherits from the host application's configured controller
   # (defaults to ::ApplicationController).
   # Includes common engine functionality.
-  class ApplicationController < ApiKeys::Engine.config.parent_controller.constantize
+  class ApplicationController < ApiKeys.configuration.parent_controller_class
     # Protect from forgery if the parent controller does
     # This ensures CSRF protection behaves consistently with the host app.
     protect_from_forgery with: :exception if respond_to?(:protect_from_forgery)
@@ -13,28 +15,61 @@ module ApiKeys
     # Include the main controller concern which bundles authentication and tenant resolution
     include ApiKeys::Controller
 
+    # The dashboard renders credential material, so give it an enforcing,
+    # self-contained CSP even when the host application has not configured one.
+    # Preserve any host directives we do not explicitly tighten.
+    before_action :prepare_api_keys_content_security_policy_nonce
+    if respond_to?(:content_security_policy)
+      content_security_policy do |policy|
+        policy.default_src :none
+        policy.base_uri :none
+        policy.object_src :none
+        policy.frame_ancestors :none
+        policy.frame_src :none
+        policy.form_action :self
+        # Rails appends the per-request nonce to these directives. `none` leaves
+        # the nonce as the only effective source instead of trusting every
+        # same-origin script or stylesheet.
+        policy.script_src :none
+        policy.style_src :none
+        policy.img_src :self, :data
+        policy.connect_src :self
+      end
+      content_security_policy_report_only false
+    end
+
     # Ensure the owner is authenticated for all actions within this engine
     # This uses the configured authentication method (defaults to authenticate_user!)
     before_action :authenticate_api_keys_owner!
+    after_action :set_api_keys_security_headers
 
     private
 
+    def prepare_api_keys_content_security_policy_nonce
+      return unless request.respond_to?(:content_security_policy_nonce_generator=)
+
+      request.content_security_policy_nonce_generator ||= ->(_request) { SecureRandom.base64(16) }
+      directives = Array(request.content_security_policy_nonce_directives)
+      request.content_security_policy_nonce_directives = directives | %w[script-src style-src]
+      request.content_security_policy_nonce
+    end
+
     # Authenticates the owner accessing the engine.
     # Uses the configured authentication method from ApiKeys.configuration
     def authenticate_api_keys_owner!
       auth_method = ApiKeys.configuration.authenticate_owner_method
 
-      # Try to call the configured authentication method
-      if auth_method && respond_to?(auth_method, true)
-        send(auth_method)
-      elsif auth_method && defined?(auth_method)
-        send(auth_method)
-      else
-        # Fallback: check if owner is present
-        unless current_api_keys_owner
-          redirect_to main_app.root_path, alert: "You need to sign in before continuing." rescue render plain: "Unauthorized", status: :unauthorized
+      if auth_method.present?
+        unless respond_to?(auth_method, true)
+          log_error "[ApiKeys Security] Configured owner authentication method is unavailable."
+          return render_api_keys_unauthorized
         end
+
+        send(auth_method)
+        return if performed?
       end
+
+      render_api_keys_unauthorized unless current_api_keys_owner
     end
 
     # Helper method to access the current owner from the host application.
@@ -52,5 +87,18 @@ module ApiKeys
     # Expose current_api_keys_owner as a helper method for views
     helper_method :current_api_keys_owner
 
+    def render_api_keys_unauthorized
+      render plain: "Unauthorized", status: :unauthorized
+    end
+
+    def set_api_keys_security_headers
+      response.headers["Cache-Control"] = "no-store, private"
+      response.headers["Pragma"] = "no-cache"
+      response.headers["Referrer-Policy"] = "no-referrer"
+      response.headers["X-Content-Type-Options"] = "nosniff"
+      response.headers["X-Frame-Options"] = "DENY"
+      response.headers["Permissions-Policy"] = "camera=(), microphone=(), geolocation=()"
+    end
+
   end
 end