api_keys 0.4.3 → 0.5.1

data/app/controllers/api_keys/keys_controller.rb

@@ -4,7 +4,8 @@ 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,
+                  :dashboard_scope_choices, :restriction_field_text
 
     # GET /keys
     def index
@@ -48,12 +49,15 @@ 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
     def create
       submitted_params = api_key_params
+      # If creation fails, the re-rendered form shows these instead of
+      # re-checking every scope the owner had cleared.
+      @submitted_scopes = submitted_params[:scopes]
 
       # Use the HasApiKeys helper method to create the key
       begin
@@ -62,7 +66,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 +80,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
@@ -96,7 +104,17 @@ module ApiKeys
 
     # PATCH/PUT /keys/:id
     def update
-      if @api_key.update(api_key_update_params)
+      attributes = api_key_update_params
+      if attributes.key?(:scopes)
+        attributes[:scopes] = scopes_after_editing_offered_choices(attributes[:scopes])
+      elsif held_scopes_within_ceiling != Array(@api_key.scopes)
+        # No scope boxes were shown, but the key still holds a scope its type
+        # no longer allows; without dropping it no edit could ever be saved.
+        attributes[:scopes] = held_scopes_within_ceiling
+      end
+      skip_untouched_restriction_fields!(attributes)
+
+      if @api_key.update(attributes)
         redirect_to keys_path, notice: "API key updated successfully."
       else
         flash.now[:alert] = "Failed to update API key: #{@api_key.errors.full_messages.join(', ')}"
@@ -133,18 +151,104 @@ 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[:scopes]&.reject!(&:blank?) # Filter out blank strings
+      permitted_params = submitted.permit(:name, :expires_at_preset, :key_type,
+                                          :allowed_origins, :allowed_ips, scopes: [])
+      normalize_submitted_scopes!(permitted_params)
+    end
+
+    # Each scope checkbox group renders an empty sentinel (`scopes[]=""`), so a
+    # submitted form always carries the parameter. Stripping blanks turns the
+    # sentinel alone into `[]`: the owner cleared every box and means "none",
+    # and the model's validations decide whether that is allowed. Only an
+    # absent parameter (`nil`) means "not specified": create_api_key! then
+    # applies the default scopes and update leaves the current ones alone.
+    def normalize_submitted_scopes!(permitted_params)
+      permitted_params[:scopes]&.reject!(&:blank?)
       permitted_params
     end
 
-    # Only allow updating name and scopes.
+    # The scopes the dashboard offers as checkboxes: the owner's configured
+    # default scopes. The form renders exactly this list, and an update edits
+    # only scopes in it.
+    #
+    # @return [Array<String>]
+    def dashboard_scope_choices
+      Array(current_api_keys_owner.class.api_keys_settings.dig(:default_scopes))
+    end
+
+    # The edit form can only speak for the scopes it showed. Checked choices
+    # are granted and unchecked ones removed; any other scope the key holds
+    # (for example one granted programmatically, or a type permission outside
+    # the owner's defaults) is kept, in its current order. A submitted value
+    # that was never offered is ignored.
+    #
+    # A held scope outside the key's current ceiling is dropped, whether
+    # offered or not: authentication already denies it, so no access changes,
+    # and keeping it would make every save of the key (a rename, or tightening
+    # a non-revocable key's origins) fail the ceiling validation. A newly
+    # checked scope outside the ceiling is kept, so validation reports it.
+    #
+    # @param submitted [Array<String>] Checked boxes, sentinel already stripped.
+    # @return [Array<String>]
+    def scopes_after_editing_offered_choices(submitted)
+      offered = dashboard_scope_choices
+      held = Array(@api_key.scopes)
+      kept = held_scopes_within_ceiling.select { |scope| !offered.include?(scope) || submitted.include?(scope) }
+      added = offered.select { |scope| submitted.include?(scope) && !held.include?(scope) }
+      kept + added
+    end
+
+    # The key's scopes without those its current ceiling excludes.
+    #
+    # @return [Array<String>]
+    def held_scopes_within_ceiling
+      Array(@api_key.scopes).select { |scope| @api_key.scope_within_ceiling?(scope) }
+    end
+
+    # The text the form puts in a restriction field. Usable entries appear as
+    # they are stored; anything else a stored policy holds (null, false, a
+    # number, a blank string) is shown as JSON, so the owner can see it.
+    #
+    # @return [String]
+    def restriction_field_text(api_key, kind)
+      api_key.restrictions.public_send(kind).map do |entry|
+        if entry.is_a?(String) && entry.valid_encoding? && !entry.strip.empty?
+          entry
+        else
+          begin
+            JSON.generate(entry)
+          rescue StandardError
+            entry.inspect
+          end
+        end
+      end.join(", ")
+    end
+
+    # A restriction field submitted exactly as it was rendered was not
+    # touched, so its kind is left alone. Re-parsing the text would rewrite
+    # the stored list, and a malformed stored entry could come back as an
+    # empty (unrestricted) list or as a different, valid one. Left alone, a
+    # malformed stored policy keeps failing validation, so the save is refused
+    # until the owner corrects the field.
+    def skip_untouched_restriction_fields!(attributes)
+      { allowed_origins: :origins, allowed_ips: :ips }.each do |field, kind|
+        next unless attributes.key?(field)
+
+        attributes.delete(field) if attributes[field] == restriction_field_text(@api_key, kind)
+      end
+    end
+
+    # 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[:scopes]&.reject!(&:blank?) # Filter out blank strings
+      permitted_params = submitted.permit(:name, :allowed_origins, :allowed_ips, scopes: [])
+      normalize_submitted_scopes!(permitted_params)
+      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 +267,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,26 +58,32 @@
             ["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
       %>
     </div>
 
-    <%# This assumes a variable `@available_scopes` is passed to the view, %>
-    <%# containing an array of scope strings allowed for this context. %>
-    <%# This list might come from global configuration or owner-specific settings. %>
-    <%# Example: @available_scopes = ["read", "write", "admin"] %>
-    <% @available_scopes = current_api_keys_owner.class.api_keys_settings.dig(:default_scopes) %>
-    <% if defined?(@available_scopes) && @available_scopes.present? %>
+    <%# The offered scopes are the owner's default scopes. The controller reads %>
+    <%# the same list (dashboard_scope_choices) when it saves the form. %>
+    <% @available_scopes = dashboard_scope_choices %>
+    <% if @available_scopes.present? %>
       <div>
         <%= form.label :scopes, "Permissions" %>
+        <%# Browsers omit unchecked boxes, so clearing every box would send no scopes %>
+        <%# parameter at all and the key would silently get the defaults. This empty %>
+        <%# sentinel makes "none" explicit; blank values are stripped server-side. %>
+        <%# (Scopes are configured here, so an empty list grants nothing.) %>
+        <%= hidden_field_tag "#{form.object_name}[scopes][]", "", id: nil if api_key.scopes_enforced? %>
+        <%# A fresh form starts with every scope checked; after a failed submission %>
+        <%# it shows exactly what was submitted, so a cleared box stays cleared. %>
+        <% submitted_scopes = @submitted_scopes %>
         <% @available_scopes.each do |scope| %>
           <div class="form-check">
             <%= form.check_box :scopes,
                                { multiple: true, # Submits as an array
                                  class: "form-check-input",
-                                 checked: true,
+                                 checked: submitted_scopes.nil? || submitted_scopes.include?(scope),
                                  id: "api_key_scopes_#{scope.parameterize}" }, # Unique ID
                                scope, # Value submitted when checked
                                nil # Value submitted when unchecked (not needed here)
@@ -87,6 +94,8 @@
       </div>
     <% end %>
 
+    <%= render "api_keys/keys/restriction_fields", form: form, api_key: api_key %>
+
   <% end %>
 
   <%# Fields editable on EDIT %>
@@ -96,19 +105,35 @@
       <%= form.text_field :name %>
     </div>
 
-    <%# Define available scopes for the edit form context %>
-    <%# This assumes the available scopes are the same as the default ones. %>
-    <%# Consider passing @available_scopes from the controller if logic is more complex. %>
-    <% @available_scopes = current_api_keys_owner.class.api_keys_settings.dig(:default_scopes) %>
-    <% if defined?(@available_scopes) && @available_scopes.present? %>
+    <%# The edit form offers the owner's default scopes and edits only those: %>
+    <%# saving keeps every other scope the key holds, except scopes its type no %>
+    <%# longer allows (see the controller's scopes_after_editing_offered_choices). %>
+    <% @available_scopes = dashboard_scope_choices %>
+    <% dropped_scopes = Array(api_key.scopes).reject { |scope| api_key.scope_within_ceiling?(scope) } %>
+    <% if dropped_scopes.any? %>
+      <small class="api-keys-form-help">
+        <%= safe_join(dropped_scopes.map { |scope| content_tag(:code, scope) }, ", ") %>
+        <%= dropped_scopes.one? ? "is" : "are" %> no longer allowed for this key and will be removed when you save.
+      </small>
+    <% end %>
+    <% if @available_scopes.present? %>
       <div>
         <%= form.label :scopes, "Permissions / Scopes" %>
+        <%# Empty sentinel: clearing every box must remove every offered scope, not keep the old ones. %>
+        <%= hidden_field_tag "#{form.object_name}[scopes][]", "", id: nil if api_key.scopes_enforced? %>
+        <% kept_scopes = Array(api_key.scopes) - @available_scopes - dropped_scopes %>
+        <% if kept_scopes.any? %>
+          <small class="api-keys-form-help">
+            This key also holds <%= safe_join(kept_scopes.map { |scope| content_tag(:code, scope) }, ", ") %>,
+            which this form does not change.
+          </small>
+        <% end %>
         <% @available_scopes.each do |scope| %>
           <div class="form-check">
             <%= form.check_box :scopes,
                                { multiple: true, # Submits as an array
                                  class: "form-check-input",
-                                 checked: api_key.scopes&.include?(scope), # Check if scope is already assigned
+                                 checked: api_key.scopes&.include?(scope) && !dropped_scopes.include?(scope),
                                  id: "api_key_scopes_#{scope.parameterize}_edit" }, # Unique ID for edit form
                                scope, # Value submitted when checked
                                nil # Value submitted when unchecked (not needed here)
@@ -119,6 +144,8 @@
         <% end %>
       </div>
     <% end %>
+
+    <%= render "api_keys/keys/restriction_fields", form: form, api_key: api_key %>
   <% end %>
 
   <div>
@@ -127,9 +154,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,34 @@
+<%# 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. %>
+<%# Values come from restriction_field_text: unusable stored entries (null, false, numbers, %>
+<%# blanks) show as JSON, and an untouched field leaves the stored list as it is on save. %>
+
+<% 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: restriction_field_text(api_key, :origins),
+                          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: restriction_field_text(api_key, :ips),
+                          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/api_keys/security/best_practices.html.erb

@@ -24,7 +24,7 @@
         <li><strong>Assume anyone can copy and abuse them</strong> from browser JavaScript, mobile apps, or public code</li>
         <li><strong>Grant only public-safe operations</strong> and enforce authorization server-side for every permission</li>
         <li><strong>Always visible</strong> &mdash; you can view the full key anytime in your dashboard</li>
-        <li><strong>Cannot be revoked individually</strong> &mdash; maintain an application-level disable/replacement procedure</li>
+        <li><strong>Revoke and replace a leaked key</strong> &mdash; publishable keys can be revoked like any other key, unless their key type is configured with <code>revocable: false</code>; keep an application-level disable/replacement procedure for those</li>
       </ul>
     </section>
   <% 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/docs/reviews/2026-10-18-0-5-1/01-astra-review-of-0-5-0.md

@@ -0,0 +1,55 @@
+# Adversarial security review of api_keys 0.5.0 (Codex Astra, 2026-10-18, at main ab6cc19)
+
+Scope: `lib/`, the dashboard under `app/`, generators and migration templates, SECURITY.md and the README's security claims, read-only, against the threat model in the prompt (an unauthenticated client, a low-privilege or other-tenant key holder, a timing observer, a misconfigured host app). Verdict: BLOCK; every finding below was answered in 0.5.1 (PR #64), see 02 and 03.
+
+Reviewed `ab6cc19` read-only, including all requested source files. Confirmed the principal edge cases with isolated, in-memory Ruby checks; did not run the full suite.
+
+## Blocking
+
+1. **IP restrictions are bypassable when Rails is directly reachable without a sanitizing proxy.** The default resolver trusts `request.remote_ip` ([configuration.rb:597](lib/api_keys/configuration.rb:597)), and authentication accepts its result ([authenticator.rb:479](lib/api_keys/services/authenticator.rb:479)).
+
+   **Attack:** Hold a valid key restricted to `203.0.113.7`; connect from a disallowed address; send `X-Forwarded-For: 203.0.113.7`. In the reproduction, adding that header changed authentication from `ip_not_allowed` to success. This is deployment-dependent and falls within the stated misconfiguration threat model. Rails explicitly documents this behavior in [RemoteIp](https://api.rubyonrails.org/classes/ActionDispatch/RemoteIp.html).
+
+   **Fix:** Document and test direct-server deployments explicitly. Without a proxy, resolve the socket peer or strip forwarding headers before Rails. Behind a proxy, prevent direct access and sanitize forwarding headers; configuring `trusted_proxies` alone does not establish that boundary.
+
+2. **Clearing every dashboard scope silently preserves permissions.** Both checkbox groups suppress unchecked values ([form:77](app/views/api_keys/keys/_form.html.erb:77), [form:111](app/views/api_keys/keys/_form.html.erb:111)). Consequently, clearing everything submits no `scopes` parameter. Updating leaves existing scopes untouched ([keys_controller.rb:103](app/controllers/api_keys/keys_controller.rb:103)); creation substitutes default scopes ([has_api_keys.rb:283](lib/api_keys/models/concerns/has_api_keys.rb:283)).
+
+   **Attack:** A client holds a read-scoped key. Its owner unchecks every permission and saves successfully. The client continues accessing read-protected endpoints. Creating a supposedly permissionless key similarly grants defaults.
+
+   **Fix:** Submit an explicit empty-array sentinel and normalize it to `[]`. Test the actual rendered form submission.
+
+## Should fix
+
+- **Malformed restriction values can become unrestricted.** `filter_map` drops `false` and `nil` rather than preserving them for validation ([restrictions.rb:140](lib/api_keys/restrictions.rb:140), [restrictions.rb:205](lib/api_keys/restrictions.rb:205)). Verified that `{"ips":false}`, `{"ips":[false]}`, and `{"ips":[null]}` become unrestricted; `key.update!(allowed_ips: false)` persists `{}`. The same applies to origins. This contradicts [CHANGELOG.md:21](CHANGELOG.md:21). Preserve invalid entries and reject them; distinguish an intentionally empty list from malformed data.
+
+- **Policy changes can prevent revocation of an active key.** `revoke!` performs a fully validated update ([api_key.rb:215](lib/api_keys/models/api_key.rb:215)). After reducing a ceiling from `read,write` to `read`, an existing `read,write` key fails revocation validation ([api_key.rb:652](lib/api_keys/models/api_key.rb:652)) while remaining active and authorized for `read` ([api_key.rb:349](lib/api_keys/models/api_key.rb:349)). Confirmed in memory. Make revocation an atomic operation independent of unrelated validations, retaining the explicit revocability guard.
+
+- **The token handoff is replayable, despite the one-time claim.** Retrieval only deletes the payload from the supplied session ([token_session.rb:89](lib/api_keys/helpers/token_session.rb:89)). Replaying a pre-consumption CookieStore cookie—or making concurrent requests with it—can recover the same token during its ten-minute lifetime. A copied-session reproduction returned the token twice. This contradicts the reused-handoff guarantee at [README.md:473](README.md:473); it does not bypass dashboard ownership. Use an atomic server-side consume operation for a genuine one-time guarantee, or qualify the documentation.
+
+- **Header parsing precedes encoding and size validation.** The Bearer regex executes at [authenticator.rb:129](lib/api_keys/services/authenticator.rb:129), before the checks at [authenticator.rb:345](lib/api_keys/services/authenticator.rb:345). An invalid UTF-8 header string raises an uncaught `ArgumentError`; oversized headers are scanned before rejection. Validate the raw header first and return a controlled credential failure. Internet reachability of the encoding case depends on the server/middleware’s string handling.
+
+## Nits
+
+- The dashboard security page says publishable keys cannot be revoked individually ([best_practices:27](app/views/api_keys/security/best_practices.html.erb:27)), although revocability defaults to true ([api_key.rb:402](lib/api_keys/models/api_key.rb:402)).
+- The prefix table still promises untyped creation when key types are configured ([README.md:942](README.md:942)); creation now requires a supplied or default type ([has_api_keys.rb:257](lib/api_keys/models/concerns/has_api_keys.rb:257)).
+
+## Missing tests
+
+- **Real proxy resolution:** restriction tests supply an already-resolved fake `remote_ip`, missing forwarding-header spoofing and proxy-chain behavior ([request_restrictions_test.rb:12](test/request_restrictions_test.rb:12)).
+- **Dashboard abuse:** actual all-unchecked form submissions; CSRF rejection with protection enabled; cross-owner update/revoke attempts. Current tests disable CSRF and exercise cross-owner show only ([keys_controller_test.rb:50](test/controllers/keys_controller_test.rb:50), [keys_controller_test.rb:330](test/controllers/keys_controller_test.rb:330)).
+- **Malformed restriction matrices:** false/null scalars and array members. Existing non-string tests use integers ([restrictions_test.rb:344](test/restrictions_test.rb:344)).
+- **Handoff replay/concurrency and browser history restoration:** current retrieval tests mutate one Hash ([token_session_test.rb:61](test/helpers/token_session_test.rb:61)).
+- **Revocation after ceiling changes and malformed header encodings:** existing tests cover ordinary revocation and oversized tokens separately ([api_key_test.rb:486](test/models/api_key_test.rb:486), [authenticator_test.rb:272](test/services/authenticator_test.rb:272)).
+- **Production database behavior:** quota concurrency, generated constraints, and authentication-index execution on PostgreSQL/MySQL. The suite uses an independently defined in-memory SQLite schema ([test_helper.rb:51](test/test_helper.rb:51)).
+
+## Blue team
+
+- **Enforce tenant and role authorization yourself.** Tenant resolution returns an object or `nil`; it does not compare against a requested tenant ([tenant_resolution.rb:26](lib/api_keys/tenant_resolution.rb:26)). Every dashboard owner can select every configured key type ([form:23](app/views/api_keys/keys/_form.html.erb:23)). Gate dashboard membership and type issuance appropriately, and scope resource queries to the authenticated owner.
+- **Treat origins as browser-context restrictions.** Non-browser clients can forge them, as acknowledged at [README.md:1409](README.md:1409). Public permissions must remain safe under arbitrary replay.
+- **Rate-limit before authentication and queue insertion.** Bcrypt guesses matching a prefix/last-four bucket trigger expensive comparisons, exposing bucket existence through timing ([authenticator.rb:218](lib/api_keys/services/authenticator.rb:218)). Distinct revoked/expired responses identify already-known complete tokens, not their missing characters ([authenticator.rb:104](lib/api_keys/services/authenticator.rb:104)).
+- **Do not use callbacks or counters as exactly-once business events.** Attempts enqueue callbacks; statistics debounce depends on a completed database update, so queue lag permits bursts. Duplicate job delivery increments counters again ([authentication.rb:154](lib/api_keys/authentication.rb:154), [authentication.rb:186](lib/api_keys/authentication.rb:186), [update_stats_job.rb:53](lib/api_keys/jobs/update_stats_job.rb:53)). Monitor queue depth and make consequential consumers idempotent.
+- **Apply deployment controls independently:** TLS, protected sessions, credential filtering, and maintained dependencies. Installable dependency floors are broader than security support ([api_keys.gemspec:40](api_keys.gemspec:40), [SECURITY.md:7](SECURITY.md:7)); operational requirements are listed at [SECURITY.md:26](SECURITY.md:26).
+
+VERDICT: BLOCK
+
+The blocking concerns are authorization behavior at integration boundaries: spoofable client-IP resolution in an explicitly in-scope deployment and a dashboard action that silently fails to remove permissions. The malformed-policy, revocation, and handoff findings also weaken stated security guarantees. Address these with focused regression tests before treating 0.5.0 as ready under this threat model.

data/docs/reviews/2026-10-18-0-5-1/02-astra-re-review-of-0-5-1.md

@@ -0,0 +1,36 @@
+# Re-review of the 0.5.1 fixes (Codex Astra, 2026-10-18, at f247984, PR #64)
+
+Scope: `git diff fd598aa..f247984`, the answer to review 01, read-only. Verdict: BLOCK only on the handoff guarantee being overstated (the consumption marker lives in the cache, so cache loss within the handoff lifetime re-opens replay for a copied cookie), plus one documentation nit; both were applied in the next commit (wording in README, SECURITY.md and the CHANGELOG; a test that pins the cache-loss replay; the blank-member sentence qualified). Durable consumption state is planned for 0.6.0. Every original attack is closed; the client-IP finding is closed by documentation and tests of the deployment shapes, with the default unchanged.
+
+## Blocking
+
+**Scope:** The requested checkout remains at `fd598aa`; its diff is empty. I reviewed the available candidate `fd598aa..f247984` in `/Users/javi/GitHub/api_keys-security` instead. This was code inspection only; “would fail on 0.5.0” below is a static assessment.
+
+- **IP spoofing: documented mitigation, unchanged default.** The real middleware tests perform the original attack and explicitly expect spoofed authentication to succeed; the socket-peer and proxy-chain tests verify the documented deployment configurations. These tests would also pass on 0.5.0: they establish deployment requirements, not changed protection. This satisfies the requested documentation/test remedy, but directly reachable installations must apply it. No new runtime behavior. [request_restrictions_test.rb:852](test/request_restrictions_test.rb:852)
+
+- **All-unchecked dashboard scopes: closed.** Tests serialize the rendered form after removing every checkbox’s checked attribute, submit it, and verify permissions disappear on creation and update. Both would fail on 0.5.0. Updates now preserve scopes outside the displayed choices and ignore submitted additions outside those choices; the form explicitly identifies retained scopes. [keys_controller_test.rb:357](test/controllers/keys_controller_test.rb:357), [keys_controller.rb:181](app/controllers/api_keys/keys_controller.rb:181), [_form.html.erb:118](app/views/api_keys/keys/_form.html.erb:118)
+
+## Should fix
+
+- **Malformed restrictions: original attacks closed.** False/null members survive coercion and fail validation; stored malformed values refuse authentication. Tests exercise both stored corruption and writer updates, including the original false/null cases, and would fail on 0.5.0. Scalar `nil` remains an intentional clearing operation on input. Untouched malformed dashboard fields retain their stored meaning instead of becoming unrestricted. [restrictions.rb:232](lib/api_keys/restrictions.rb:232), [request_restrictions_test.rb:698](test/request_restrictions_test.rb:698), [keys_controller.rb:214](app/controllers/api_keys/keys_controller.rb:214)
+
+- **Revocation after policy changes: closed for clean loaded records.** The tests narrow an issued key’s ceiling, establish that validation fails, then revoke it—including through a warm authentication cache. They would fail on 0.5.0. The revocability guard and save callbacks remain; instances carrying other pending edits still validate and can fail revocation. That limitation is explicit and tested, rather than silently saving those edits unvalidated. [api_key.rb:232](lib/api_keys/models/api_key.rb:232), [authenticator_test.rb:319](test/services/authenticator_test.rb:319), [api_key_test.rb:553](test/models/api_key_test.rb:553)
+
+- **Handoff replay: improved, but the guarantee remains overstated.** Copied-session and threaded tests perform the attack and would fail on 0.5.0. However, consumption exists only as a cache marker: consume once, clear the cache, then replay the still-valid copied session, and the write succeeds again. Shared, atomic storage alone therefore does not establish the README’s “at most once” guarantee; marker retention is also required. Document cache-loss replay or use durable consumption state. Cache failure now withholds the token—a deliberate availability change. [token_session.rb:202](lib/api_keys/helpers/token_session.rb:202), [token_session_test.rb:215](test/helpers/token_session_test.rb:215), [README.md:481](README.md:481)
+
+- **Header parsing: original attacks closed.** Raw size/encoding checks precede the regex. Tests supply invalid UTF-8 and explicitly forbid matching an oversized header; both would fail on 0.5.0. The new compatibility boundary is a 576-byte complete header limit, including Bearer whitespace. [authenticator.rb:138](lib/api_keys/services/authenticator.rb:138), [authenticator_test.rb:350](test/services/authenticator_test.rb:350)
+
+## Nits
+
+- Both previous documentation errors are corrected. [best_practices.html.erb:27](app/views/api_keys/security/best_practices.html.erb:27), [README.md:961](README.md:961)
+- The new claim that blank array members fail validation is too broad: the writer test explicitly accepts `allowed_ips: [""]` and clears restrictions. Qualify the input-path distinction. [README.md:1386](README.md:1386), [request_restrictions_test.rb:768](test/request_restrictions_test.rb:768)
+
+## Missing tests
+
+- Add consumption-marker loss followed by replay. Current concurrency coverage uses one process and `MemoryStore`, not a production shared backend. [token_session_test.rb:225](test/helpers/token_session_test.rb:225)
+- CSRF rejection and cross-owner writes are now meaningfully covered; these establish existing protections and should pass on 0.5.0. Browser-history restoration remains uncovered by the controller replay test. [keys_controller_test.rb:562](test/controllers/keys_controller_test.rb:562), [keys_controller_test.rb:596](test/controllers/keys_controller_test.rb:596), [keys_controller_test.rb:638](test/controllers/keys_controller_test.rb:638)
+- PostgreSQL/MySQL concurrency, migration constraints, and index execution remain unverified; the suite still defines an in-memory SQLite schema. [test_helper.rb:51](test/test_helper.rb:51)
+
+VERDICT: BLOCK
+
+The candidate substantially addresses the original review, but I would correct the remaining handoff guarantee and add cache-loss replay coverage before publishing it as the security-fix release. The documented IP configuration remains mandatory. This assessment covers `f247984`, not the requested merged `main`, which currently contains none of these fixes.

data/docs/reviews/2026-10-18-0-5-1/03-opus-review-of-0-5-1.md

@@ -0,0 +1,5 @@
+# Independent review of the 0.5.1 fixes (Claude Opus 5.5, 2026-10-18, at 0a3183b then f247984, PR #64)
+
+Scope: the branch against Astra's findings (01), with the suite run and the attack tests checked against the 0.5.0 sources (35 of the 53 added tests fail there). Verdict: PASS, with four should-fix items that were applied in the second commit: dashboard edits change only the scopes the form offered and keep the rest (a rename no longer strips a scope the owner's defaults do not list); nil and blank restriction inputs clear a kind as the list writers do, while stored rows stay strictly read; the form builder's sentinel takes an explicit `include_hidden:` override and the README says per-owner defaults need a key built from its owner; Solid Cache's `unless_exist` (SELECT FOR UPDATE then upsert, which locks nothing for an absent key on PostgreSQL) is named next to FileStore. Nits applied: a stored malformed policy round-trips through the edit form as JSON and refuses to save until corrected; a README line on a cleared key becoming unrestricted if scope configuration is later removed; a README line on a second GET of the token page getting nothing; a test for `available?` when the cache read raises. Noted for 0.6: resolving the client IP through `remote_ip` only when `remote_addr` is a trusted proxy.
+
+The review's own text is summarised above; its numbered findings and verdict were delivered in the session transcript rather than as a file.

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