api_keys 0.4.3 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6396edccad39aa17e98758d5219a3640755173bee395740b18bcf27eef9fa68b
-  data.tar.gz: a07b09b4765d970d8d7ee8c68c897aae7c6721a5bfb9e9c53b15362551072b4a
+  metadata.gz: fc838865e865c63ea4e694fc1d413ec5e6f4cad1237ec2441568d9252074af29
+  data.tar.gz: 420baff40ec1495f7c2b8dfb704e8856105dca708c379382a092323cb6781d2c
 SHA512:
-  metadata.gz: e6ab972672ad010c5bdcf83f4d1866e4140d604ffa2ec90118bd60742ac9686d81c29b0b061bd2442879ec4efe012f5dc002accb7a1179bbdbbda0e10dd337d2
-  data.tar.gz: ae0da1c536629537979cd1e9d5b1e85e535fb8f9e82a9fc3b93013ffb759ea45086aea7fcc1a702a82595bfa1040bf2d0b92fa8a260e8f80124d8efa996d7106
+  metadata.gz: 7acff018339fd77d6007dfe2a18b7bc272420756a4792a8f028973b4eebb40ec518e919cd47d032b27462cc66fdddf7536233fa68fe71dfbd769eb06acb0f167
+  data.tar.gz: 36decdf7512ebeb96a729e5353a9e4f66d92f20b4c58e6cdaf4bd280e26749d388d0b7d50b5f1cb2c8065c50408f24f2781a6df50eb7706a045c89e86bb84d85

data/CHANGELOG.md

@@ -1,3 +1,25 @@
+## [0.5.0] - 2026-08-25
+
+### Added
+
+- Request restrictions: per-key `allowed_origins` (exact hosts and `*.subdomain` wildcards, matched against the browser's Origin with Referer fallback) and `allowed_ips` (IPv4/IPv6, exact or CIDR). Enforced inside `Authenticator.call` for every key on every request, including token-cache hits, so no controller can forget to check and a tightened allowlist takes effect on the next call. Failures answer 403 with `origin_not_allowed` / `ip_not_allowed`. Empty restrictions mean unrestricted, so existing keys are unaffected.
+- `ApiKeys::Restrictions` value object: normalization, matching, and the forgiving parsers dashboards want (`.normalize_origins`, `.normalize_ips`, `.extract_origin_host`). Host applications can delete their own origin parsers.
+- Per-key-type restriction ceilings via `key_types[...][:restrictions]`, mirroring the way `permissions:` caps scopes. Omitted allows both kinds; `[]` forbids restrictions for that type.
+- `config.client_ip_resolver` (defaults to `request.remote_ip`, which honors Rails' trusted proxies).
+- `rails generate api_keys:add_restrictions` for existing installations; new installs create the column from the start.
+- Dashboard: origin and IP fields on the key form (shown dynamically per the selected key type's ceiling), expiration only for expirable key types, preserved form values after errors, and a "Restricted" badge.
+- Model surface: `restrictions`, `restricted?`, `allowed_origins`/`allowed_ips` readers and raw-string writers, `restricted`/`unrestricted` scopes, and `create_api_key!(restrictions:, allowed_origins:, allowed_ips:)`.
+- Refusal attribution: every failure after a key has been identified (revoked, expired, type/environment configuration, isolation, and request restrictions) carries its `api_key_id`; lookup failures do not.
+
+### Changed
+
+- `public: true` is now independent of `revocable:`. Public key types remain subject to a finite non-empty permission ceiling, but can use the normal rotation, revocation, deletion, and expiration lifecycle.
+
+### Security
+
+- Restriction failures never echo the configured allowlist back to the caller.
+- Every restriction failure mode fails closed: a locked list plus an unreadable origin, an unresolvable client IP, an unknown kind, a scalar policy, or an unparseable stored entry refuses the request. Generated migrations add a database check that the policy is a JSON object where the adapter supports it.
+
 ## [0.4.3] - 2026-08-24
 
 - Republish of 0.4.2 with a clean package: the 0.4.2 gem shipped carrying a stray 200 KB `api_keys-0.4.1.gem` blob at its root (committed by accident during the release, harmless but dead weight). No code changes. Prefer this over 0.4.2.

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, 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.
+`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 and limit to a finite permission set.
 
 [ 🟢 [Live interactive demo website](https://apikeys.rameerez.com) ]
 
@@ -41,6 +41,15 @@ rails db:migrate
 
 The generated migration is idempotent and uses a concurrent PostgreSQL index where supported.
 
+To lock keys to specific web origins or IP addresses (see [Restrict where a key can be used](#restrict-where-a-key-can-be-used-origins-and-ips)), add the restrictions column:
+
+```bash
+rails generate api_keys:add_restrictions
+rails db:migrate
+```
+
+New installations get this column from the start, so this is only for upgrades.
+
 ## 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:
@@ -152,6 +161,7 @@ Once configured, your users can:
 - set expiration dates
 - attach scopes / permissions to individual keys
 - add and edit the key names
+- lock a key to specific web origins or IP addresses
 - revoke instantly
 - see the status of all their keys
 
@@ -354,6 +364,10 @@ Filter keys by type and status:
 @org.api_keys.expired              # Past expiration date
 @org.api_keys.revoked              # Manually revoked
 
+# By request restrictions
+@org.api_keys.restricted           # Locked to specific origins and/or IPs
+@org.api_keys.unrestricted         # Usable from anywhere
+
 # Chain them
 @org.api_keys.publishable.active
 @org.api_keys.secret.inactive.order(created_at: :desc)
@@ -382,7 +396,9 @@ current_org.can_create_api_key?(key_type: :publishable)
   expires_at: 30.days.from_now,         # Explicit date
   expires_at_preset: "30_days",         # OR use preset (takes precedence)
   environment: :live,                   # Defaults to current_environment
-  metadata: { team: "backend" }         # Optional JSON metadata
+  metadata: { team: "backend" },        # Optional JSON metadata
+  allowed_origins: "example.com",       # Optional: lock to web origins
+  allowed_ips: "10.0.0.0/8"             # Optional: lock to IP addresses
 )
 ```
 
@@ -418,6 +434,12 @@ Methods available on `ApiKeys::ApiKey` instances:
 @api_key.scopes                   # => ["read", "write"]
 @api_key.allows_scope?("read")    # => true
 
+# Request restrictions (where the key may be used from)
+@api_key.allowed_origins          # => ["example.com", "*.example.com"]
+@api_key.allowed_ips              # => ["203.0.113.7", "10.0.0.0/8"]
+@api_key.restricted?              # => true if either list has entries
+@api_key.restrictions             # => ApiKeys::Restrictions value object
+
 # Metadata
 @api_key.name                     # => "Production Server"
 @api_key.created_at
@@ -1042,7 +1064,7 @@ end
 
 This is especially useful if you want to build custom monitoring, usage tracking or auditing systems on top of the `api_keys` gem.
 
-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 `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`. `api_key_id` is present on success and on every refusal where the key was identified but a policy said no (missing scope, environment isolation, origin or IP restrictions), so refused traffic stays attributable to the key that sent it; only lookup failures leave it `nil`. 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.
 
@@ -1071,10 +1093,12 @@ 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_...`): 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.
+- **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 may be revoked, rotated, and expired unless you explicitly configure `revocable: false`.
 
 - **Secret keys** (`sk_test_...`, `sk_live_...`): Sensitive server-side credentials whose exact access depends on their scopes. They can be revoked anytime.
 
+Publishable keys pair naturally with [request restrictions](#restrict-where-a-key-can-be-used-origins-and-ips): lock them to your customers' domains so a lifted key is useless on anyone else's site.
+
 ### Configuration
 
 Enable key types in your initializer:
@@ -1086,13 +1110,16 @@ ApiKeys.configure do |config|
     publishable: {
       prefix: "pk",                    # Token prefix → pk_test_, pk_live_
       permissions: %w[read validate],  # Scope ceiling (max permissions allowed)
-      revocable: false,                # Cannot be revoked or deleted
-      limit: 1                         # Max 1 per owner per environment
+      public: true,                    # Store token so it remains viewable
+      limit: 1,                        # Max 1 per owner per environment
+      restrictions: [:origins]         # May be locked to domains, not to IPs
     },
     secret: {
       prefix: "sk",
-      permissions: :all                # No scope restrictions
+      permissions: :all,               # No scope restrictions
+      restrictions: [:ips]             # May be locked to IPs, not to domains
       # revocable defaults to true, limit defaults to nil (unlimited)
+      # restrictions defaults to both kinds allowed
     }
   }
 
@@ -1116,7 +1143,7 @@ end
 ### Creating Typed Keys
 
 ```ruby
-# Create a publishable key (limited permissions, cannot be revoked)
+# Create a publishable key (limited permissions, viewable and revocable)
 pk = user.create_api_key!(
   name: "Production App",
   key_type: :publishable,
@@ -1154,14 +1181,25 @@ sk.scopes  # => ["read", "validate", "issue_license", "admin"]
 
 ### Non-Revocable Keys
 
-Keys with `revocable: false` protect against accidental deletion:
+Keys with `revocable: false` protect against accidental deletion. Configure
+that lifecycle explicitly on the key type that needs it:
 
 ```ruby
-pk = user.create_api_key!(key_type: :publishable)
+ApiKeys.configure do |config|
+  config.key_types = {
+    permanent_server: {
+      prefix: "skp",
+      permissions: :all,
+      revocable: false
+    }
+  }
+end
 
-pk.revocable?  # => false
-pk.revoke!     # Raises ApiKeys::Errors::KeyNotRevocableError
-pk.destroy!    # Raises ApiKeys::Errors::KeyNotRevocableError
+key = user.create_api_key!(key_type: :permanent_server)
+
+key.revocable?  # => false
+key.revoke!     # Raises ApiKeys::Errors::KeyNotRevocableError
+key.destroy!    # Raises ApiKeys::Errors::KeyNotRevocableError
 ```
 
 The dashboard UI automatically hides the revoke button for non-revocable keys.
@@ -1169,11 +1207,11 @@ Deleting the owning record still cascades deletion to all of its API keys, inclu
 
 ### Public Keys (Viewable Tokens)
 
-#### The Problem: Non-Revocable Key Lockout
+#### Why Public Tokens Are Viewable
 
-Non-revocable keys create a potential UX nightmare: if a user creates a publishable key, doesn't copy it immediately, and closes the page—they're locked out. The token is gone forever (we only store the hash), and they can't delete the key to create a new one (it's non-revocable). They're stuck with a useless key slot they can never use or remove.
+Ordinary secret keys cannot be recovered after their one-time display. That is the right default for confidential credentials, but it provides no secrecy benefit for a token deliberately embedded in public client code. It can also lock an owner out when a non-revocable public key is combined with `limit: 1`.
 
-This is especially problematic when combined with `limit: 1`, which restricts users to a single publishable key per environment. A user who loses their token would be permanently locked out of creating publishable keys.
+Public keys solve that display problem independently of lifecycle policy: they can be revocable (the default) or explicitly non-revocable.
 
 #### The Solution: Storing Public Keys
 
@@ -1186,7 +1224,6 @@ config.key_types = {
   publishable: {
     prefix: "pk",
     permissions: %w[read validate],
-    revocable: false,
     public: true,   # Store token for later viewing
     limit: 1
   },
@@ -1201,16 +1238,15 @@ config.key_types = {
 #### Security constraints
 
 > [!IMPORTANT]
-> The `public` option only works when all of these conditions are met:
+> The `public` option only works when both 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`)
 
 These checks are deliberate safety measures:
 
-1. **Configuration is validated early** — Public types must explicitly be non-revocable and have a finite, non-empty permission ceiling.
+1. **Configuration is validated early** — Public types must 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.
+2. **Revocability is independent** — Public keys may remain viewable while also being revocable and expirable. `revocable: false` is available only when a permanently deployed identifier is truly required.
 
 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.
 
@@ -1279,6 +1315,103 @@ rails db:migrate
 
 Existing keys without `key_type`/`environment` continue to work normally (backwards compatible).
 
+## Restrict where a key can be used (origins and IPs)
+
+A publishable key lives in your customer's page source, in plain sight. Without any control over *where* it can be used, anyone can lift it and use it from their own website. Lock the key to your customers' domains and a stolen key is useless anywhere else. The same applies to secret keys on the server side: lock them to the addresses your customer's servers actually call from.
+
+Any key can carry two lists:
+
+- **Allowed web origins**: bare hosts, matched against the browser's `Origin` header (falling back to `Referer`). Supports `*.` subdomain wildcards.
+- **Allowed IP addresses**: single IPv4/IPv6 addresses or CIDR ranges.
+
+Both are enforced inside the gem, on every authenticated request, for every key. There is no controller to opt in and no endpoint that can forget.
+
+### Upgrading an existing installation
+
+New installations already have the column. To add it to an existing app:
+
+```bash
+rails generate api_keys:add_restrictions
+rails db:migrate
+```
+
+### Usage
+
+```ruby
+# At creation time
+key = user.create_api_key!(
+  name: "Widget key",
+  key_type: :publishable,
+  allowed_origins: "example.com, *.example.com"
+)
+
+# Or any time after: raw strings are parsed and normalized for you
+key.allowed_ips = "203.0.113.7, 10.0.0.0/8"
+key.save!
+
+key.allowed_origins   # => ["example.com", "*.example.com"]
+key.allowed_ips       # => ["203.0.113.7", "10.0.0.0/8"]
+key.restricted?       # => true
+```
+
+Origin input is deliberately forgiving: full URLs, trailing slashes, ports, commas, and newlines are all accepted and reduced to bare lowercase hosts. `https://Shop.example/` becomes `shop.example`. Your dashboard never needs its own parser.
+
+### Semantics
+
+| Rule | Behavior |
+|---|---|
+| Within one list | **OR** — any entry that matches admits the request |
+| Across both lists | **AND** — every list that has entries must pass |
+| Empty (or absent) lists | **Unrestricted** — presence is the toggle, so existing keys are unaffected |
+| `example.com` | Matches that exact host. Case-insensitive, port-blind, scheme-blind |
+| `*.example.com` | Matches `a.example.com` and `a.b.example.com`, but **not** the apex `example.com`. List both to cover both |
+| `*` alone | Invalid. An empty list already means "anywhere" |
+| IP entries | `203.0.113.7` matches exactly; `10.0.0.0/8` and `2001:db8::/32` match their whole range |
+| No readable origin on an origins-locked key | **Refused.** Every failure mode fails closed |
+| Refusal response | `403 Forbidden` with `origin_not_allowed`, `ip_not_allowed`, or `restriction_misconfigured` for damaged policy data |
+
+An origins-locked key is therefore unusable from origin-less server code, which is exactly the point of locking a browser key.
+
+### Per-key-type restriction ceilings
+
+Key types can cap which kinds of restrictions their keys may carry, the same way `permissions:` caps scopes:
+
+```ruby
+config.key_types = {
+  publishable: { prefix: "pk", permissions: %w[read], public: true,
+                 restrictions: [:origins] },   # Browser keys lock to domains
+  secret:      { prefix: "sk", permissions: :all,
+                 restrictions: [:ips] }        # Server keys lock to addresses
+}
+```
+
+Omitting `restrictions:` allows both kinds. `restrictions: []` forbids restrictions for that type. A key carrying a kind its type forbids fails validation.
+
+### Resolving the client IP
+
+IP checks use `request.remote_ip`, which honors Rails' `config.action_dispatch.trusted_proxies`. Configure that Rails setting for your reverse proxy or CDN and keep the default resolver whenever possible.
+
+Only read a vendor header directly when your network ingress rejects requests that did not come through that vendor. Otherwise a client can send the same header and choose the address your allowlist sees:
+
+```ruby
+# config/initializers/api_keys.rb
+config.client_ip_resolver = ->(request) do
+  request.headers.fetch("CF-Connecting-IP")
+end
+```
+
+### Dashboard
+
+The mounted dashboard renders only the expiration and request-restriction fields supported by the selected key type, and a **Restricted** badge next to keys carrying a policy. Restriction edits remain available on non-revocable keys so an owner can still tighten an allowlist.
+
+### Security notes
+
+- `Origin` and `Referer` are **browser-enforced** headers. They are trustworthy coming from a real browser and trivially forged by `curl`. Origin restrictions are a browser-context control: they stop a lifted public key from working on someone else's *website*. They are not secrecy. Pair them with keys that cannot spend anything dangerous.
+- IP restrictions inherit the truthfulness of their resolver. Configure Rails' `trusted_proxies`; only trust a CDN-supplied header when direct access to the origin is blocked, or callers can spoof the address being checked.
+- Everything fails closed: a locked list plus an unreadable request context, an unknown policy kind, or malformed stored policy data is a refusal, never a pass.
+- Refusals never echo the configured allowlist back to the caller. Reflecting your domains to an unauthenticated attacker would be a reconnaissance gift. If you want a more explicit message, override it through i18n (`api_keys.errors.origin_not_allowed`).
+- Restriction checks read the current database row on every request, cache or no cache. Tightening the origins of a leaked publishable key takes effect on the very next call.
+
 ## Enterprise-ready by design
 The `api_keys` gem ships with:
 

data/app/controllers/api_keys/keys_controller.rb

@@ -4,7 +4,7 @@ module ApiKeys
   # Controller for managing API keys belonging to the current owner.
   class KeysController < ApplicationController
     before_action :set_api_key, only: [:show, :edit, :update, :revoke]
-    helper_method :key_types_feature_enabled?
+    helper_method :key_types_feature_enabled?, :api_keys_allowed_restriction_kinds
 
     # GET /keys
     def index
@@ -48,7 +48,7 @@ module ApiKeys
 
     # GET /keys/new
     def new
-      @api_key = current_api_keys_owner.api_keys.build
+      @api_key = current_api_keys_owner.api_keys.build(key_type: ApiKeys.configuration.default_key_type)
     end
 
     # POST /keys
@@ -62,7 +62,10 @@ module ApiKeys
           name: submitted_params[:name],
           scopes: submitted_params[:scopes],
           expires_at: parse_expiration(submitted_params[:expires_at_preset]),
-          key_type: submitted_params[:key_type].presence
+          key_type: submitted_params[:key_type].presence,
+          # The model normalizes these raw strings; no parser needed here.
+          allowed_origins: submitted_params[:allowed_origins],
+          allowed_ips: submitted_params[:allowed_ips]
           # Metadata could be added here if needed
         )
 
@@ -73,6 +76,7 @@ module ApiKeys
       rescue ActiveRecord::RecordInvalid => e
         # If create! fails due to validation (e.g., quota exceeded)
         @api_key = e.record # Get the invalid ApiKey instance
+        @api_key.expires_at_preset = submitted_params[:expires_at_preset]
         flash.now[:alert] = "Failed to create API key: #{e.record.errors.full_messages.join(', ')}"
         render :new, status: :unprocessable_entity
       rescue ArgumentError
@@ -133,18 +137,23 @@ module ApiKeys
       submitted = params.require(:api_key)
       raise ActionController::ParameterMissing, :api_key unless submitted.respond_to?(:permit)
 
-      permitted_params = submitted.permit(:name, :expires_at_preset, :key_type, scopes: [])
+      permitted_params = submitted.permit(:name, :expires_at_preset, :key_type,
+                                          :allowed_origins, :allowed_ips, scopes: [])
       permitted_params[:scopes]&.reject!(&:blank?) # Filter out blank strings
       permitted_params
     end
 
-    # Only allow updating name and scopes.
+    # Only allow updating name, scopes, and request restrictions.
+    # Restriction edits stay available on non-revocable keys so an owner can
+    # still tighten the policy even when lifecycle operations are disabled.
     def api_key_update_params
       submitted = params.require(:api_key)
       raise ActionController::ParameterMissing, :api_key unless submitted.respond_to?(:permit)
 
-      permitted_params = submitted.permit(:name, scopes: [])
+      permitted_params = submitted.permit(:name, :allowed_origins, :allowed_ips, scopes: [])
       permitted_params[:scopes]&.reject!(&:blank?) # Filter out blank strings
+      permitted_params.delete(:allowed_origins) unless ApiKeys::ApiKey.restrictions_column?
+      permitted_params.delete(:allowed_ips) unless ApiKeys::ApiKey.restrictions_column?
       permitted_params
     end
 
@@ -163,10 +172,32 @@ module ApiKeys
     end
 
     def rebuild_api_key_for_form(submitted_params)
-      current_api_keys_owner.api_keys.build(
+      api_key = current_api_keys_owner.api_keys.build(
         name: submitted_params[:name],
-        scopes: submitted_params[:scopes]
+        scopes: submitted_params[:scopes],
+        key_type: submitted_params[:key_type]
       )
+      api_key.expires_at_preset = submitted_params[:expires_at_preset]
+      if ApiKeys::ApiKey.restrictions_column?
+        api_key.allowed_origins = submitted_params[:allowed_origins] unless submitted_params[:allowed_origins].nil?
+        api_key.allowed_ips = submitted_params[:allowed_ips] unless submitted_params[:allowed_ips].nil?
+      end
+      api_key
+    end
+
+    # Which restriction kinds the form may offer for a given key.
+    # A typed key answers with its own ceiling; an unsaved key that has not
+    # picked a type yet offers everything any configured type allows.
+    #
+    # @param api_key [ApiKeys::ApiKey]
+    # @return [Array<Symbol>]
+    def api_keys_allowed_restriction_kinds(api_key)
+      return api_key.allowed_restriction_kinds if api_key.persisted?
+      return ApiKeys::Restrictions::KINDS.dup unless key_types_feature_enabled?
+
+      ApiKeys.configuration.key_types.flat_map do |_type, settings|
+        ApiKeys::ApiKey.restriction_kinds_for(settings)
+      end.uniq
     end
 
     # Check if key types feature is enabled

data/app/views/api_keys/keys/_form.html.erb

@@ -1,5 +1,6 @@
 <%# Shared form for creating and editing API Keys %>
-<%= form_with(model: [:keys, api_key], url: (api_key.persisted? ? key_path(api_key) : keys_path), local: true) do |form| %>
+<%= form_with(model: [:keys, api_key], url: (api_key.persisted? ? key_path(api_key) : keys_path),
+              local: true, html: { id: "api-keys-key-form" }) do |form| %>
   <% if api_key.errors.any? %>
     <div class="api-keys-form-errors">
       <strong><%= pluralize(api_key.errors.count, "error") %> prohibited this API key from being saved:</strong>
@@ -47,7 +48,7 @@
       <%= form.text_field :name, placeholder: "e.g., myproject-production-key" %>
     </div>
 
-    <div>
+    <div data-api-keys-expiration>
       <%= form.label :expires_at_preset, "Expiration" %>
       <%= form.select :expires_at_preset,
           options_for_select([
@@ -57,7 +58,7 @@
             ["60 days", "60_days"],
             ["90 days", "90_days"],
             ["365 days", "365_days"] # Common presets
-          ], api_key.expires_at.present? ? nil : "no_expiration"), # Default selection
+          ], api_key.expires_at_preset.presence || (api_key.expires_at.present? ? nil : "no_expiration")), # Default selection
           {}, # html options
           {} # data attributes
       %>
@@ -87,6 +88,8 @@
       </div>
     <% end %>
 
+    <%= render "api_keys/keys/restriction_fields", form: form, api_key: api_key %>
+
   <% end %>
 
   <%# Fields editable on EDIT %>
@@ -119,6 +122,8 @@
         <% end %>
       </div>
     <% end %>
+
+    <%= render "api_keys/keys/restriction_fields", form: form, api_key: api_key %>
   <% end %>
 
   <div>
@@ -127,9 +132,45 @@
       <%= link_to "Cancel", keys_path %>
     <% else %>
       <h4><strong>Keep it safe</strong></h4>
-      <p>Your API key will only be shown once after creation. <strong>Your key cannot be recovered:</strong> copy it immediately and store it securely.</p>
+      <p>Secret API keys are only shown once after creation. Copy the new key immediately and store it securely.</p>
       <%= form.submit "Create API Key" %>
       <%= link_to "Cancel", keys_path %>
     <% end %>
   </div>
 <% end %>
+
+<% if !api_key.persisted? && ApiKeys.configuration.key_types.present? %>
+  <% key_type_policies = ApiKeys.configuration.key_types.to_h do |type, config| %>
+    <% [type.to_s, {
+      restrictions: ApiKeys::ApiKey.restriction_kinds_for(config).map(&:to_s),
+      expirable: ApiKeys::ApiKey.revocable_for(config)
+    }] %>
+  <% end %>
+  <script nonce="<%= content_security_policy_nonce %>">
+    (() => {
+      const form = document.getElementById("api-keys-key-form");
+      const keyType = form && form.querySelector("#api_key_key_type");
+      if (!form || !keyType) return;
+
+      const policies = <%= raw json_escape(key_type_policies.to_json) %>;
+      const updatePolicyFields = () => {
+        const policy = policies[keyType.value];
+
+        form.querySelectorAll("[data-api-keys-restriction-kind]").forEach((container) => {
+          const enabled = policy && policy.restrictions.includes(container.dataset.apiKeysRestrictionKind);
+          container.hidden = !enabled;
+          container.querySelectorAll("input, select, textarea").forEach((input) => { input.disabled = !enabled; });
+        });
+
+        form.querySelectorAll("[data-api-keys-expiration]").forEach((container) => {
+          const enabled = policy && policy.expirable;
+          container.hidden = !enabled;
+          container.querySelectorAll("input, select, textarea").forEach((input) => { input.disabled = !enabled; });
+        });
+      };
+
+      keyType.addEventListener("change", updatePolicyFields);
+      updatePolicyFields();
+    })();
+  </script>
+<% end %>

data/app/views/api_keys/keys/_key_badges.html.erb

@@ -9,6 +9,13 @@
   </span>
 <% end %>
 
+<% if key.restricted? %>
+  <span class="api-keys-badge api-keys-badge-restricted"
+        title="Usable only from specific <%= key.restrictions.kinds.map { |kind| kind == :ips ? 'IP addresses' : 'web origins' }.to_sentence %>">
+    Restricted
+  </span>
+<% end %>
+
 <% if key.environment.present? %>
   <% is_live = key.environment == 'live' %>
   <span class="api-keys-badge api-keys-badge-env <%= is_live ? 'api-keys-badge-live' : 'api-keys-badge-test' %>">

data/app/views/api_keys/keys/_restriction_fields.html.erb

@@ -0,0 +1,32 @@
+<%# Optional request restriction fields: where a key may be used from. %>
+<%# Locals: form (required), api_key (required) %>
+<%# Only rendered when the restrictions column exists and the key's type allows the kind. %>
+
+<% if ApiKeys::ApiKey.restrictions_column? %>
+  <% allowed_kinds = api_keys_allowed_restriction_kinds(api_key) %>
+
+  <% if allowed_kinds.include?(:origins) %>
+    <div data-api-keys-restriction-kind="origins">
+      <%= form.label :allowed_origins, "Allowed web origins (optional)" %>
+      <%= form.text_field :allowed_origins,
+                          value: api_key.allowed_origins.join(", "),
+                          placeholder: "example.com, *.example.com" %>
+      <small class="api-keys-form-help">
+        Leave empty to allow any origin. Requests from a browser must come from one of these hosts.
+        Use <code>*.example.com</code> to allow every subdomain.
+      </small>
+    </div>
+  <% end %>
+
+  <% if allowed_kinds.include?(:ips) %>
+    <div data-api-keys-restriction-kind="ips">
+      <%= form.label :allowed_ips, "Allowed IP addresses (optional)" %>
+      <%= form.text_field :allowed_ips,
+                          value: api_key.allowed_ips.join(", "),
+                          placeholder: "203.0.113.7, 10.0.0.0/8" %>
+      <small class="api-keys-form-help">
+        Leave empty to allow any address. Accepts single IPv4/IPv6 addresses and CIDR ranges.
+      </small>
+    </div>
+  <% end %>
+<% end %>

data/app/views/layouts/api_keys/application.html.erb

@@ -36,6 +36,8 @@
       --api-keys-badge-live-color: #155724;
       --api-keys-badge-test-bg: #f8d7da;
       --api-keys-badge-test-color: #721c24;
+      --api-keys-badge-restricted-bg: #e2e3e5;
+      --api-keys-badge-restricted-color: #383d41;
 
       /* Status colors */
       --api-keys-status-active-color: green;
@@ -152,6 +154,8 @@
         --api-keys-badge-live-color: #9ae6b4;
         --api-keys-badge-test-bg: #742a2a;
         --api-keys-badge-test-color: #feb2b2;
+        --api-keys-badge-restricted-bg: #2d3748;
+        --api-keys-badge-restricted-color: #cbd5e0;
       }
 
       body {
@@ -212,7 +216,7 @@
     .api-keys-status-active { color: var(--api-keys-status-active-color); }
     .api-keys-status-revoked { color: var(--api-keys-status-revoked-color); }
     .api-keys-status-expired { color: var(--api-keys-status-expired-color); }
-    .api-keys-badge-type, .api-keys-badge-env {
+    .api-keys-badge-type, .api-keys-badge-env, .api-keys-badge-restricted {
       margin-left: 0.25rem;
       padding: 0.15rem 0.4rem;
       border-radius: 3px;
@@ -234,6 +238,10 @@
       color: var(--api-keys-badge-test-color);
       background-color: var(--api-keys-badge-test-bg);
     }
+    .api-keys-badge-restricted {
+      color: var(--api-keys-badge-restricted-color);
+      background-color: var(--api-keys-badge-restricted-bg);
+    }
 
     .api-keys-button-text {
       padding-left: 0.2em;

data/lib/api_keys/authentication.rb

@@ -13,6 +13,11 @@ module ApiKeys
     extend ActiveSupport::Concern
     include ApiKeys::Logging
 
+    # Failures where the credential is valid but the request context is refused.
+    # The key itself is fine, so these answer 403 rather than 401 — the same
+    # distinction `:missing_scope` already makes.
+    FORBIDDEN_ERROR_CODES = %i[origin_not_allowed ip_not_allowed restriction_misconfigured].freeze
+
     included do
       # Helper methods to access the authenticated key and its owner
       helper_method :current_api_key, :current_api_owner, :current_api_user
@@ -88,7 +93,8 @@ module ApiKeys
       else
         # Authentication failed
         log_debug "[ApiKeys Auth] Authentication failed. Error: #{result.error_code}, Message: #{result.message}"
-        render_unauthorized(error_code: result.error_code, message: result.message)
+        status = FORBIDDEN_ERROR_CODES.include?(result.error_code) ? :forbidden : :unauthorized
+        render_unauthorized(error_code: result.error_code, message: result.message, status: status)
       end
 
       # Enqueue after_authentication callback asynchronously regardless of success/failure