api_keys 0.5.0 → 0.6.0

data/app/controllers/api_keys/keys_controller.rb

@@ -3,8 +3,13 @@
 module ApiKeys
   # Controller for managing API keys belonging to the current owner.
   class KeysController < ApplicationController
+    ALREADY_SHOWN_ALERT = "This API key's token was already shown and cannot be shown again. " \
+                          "If you did not save it, revoke this key and create a new one."
+
     before_action :set_api_key, only: [:show, :edit, :update, :revoke]
-    helper_method :key_types_feature_enabled?, :api_keys_allowed_restriction_kinds
+    helper ApiKeys::Helpers::ViewHelpers
+    helper_method :key_types_feature_enabled?, :api_keys_allowed_restriction_kinds,
+                  :dashboard_scope_choices, :restriction_field_text, :api_keys_displayed_scopes
 
     # GET /keys
     def index
@@ -35,15 +40,24 @@ module ApiKeys
     # Shows the newly generated key's plaintext token ONCE.
     # This is not a standard show action, it's used transiently after creation.
     def show
-      # Key is set by set_api_key
-      # We need to retrieve the plaintext token stored temporarily
-      # after creation. This relies on how we handle creation.
-      # We'll likely store it in the session flash or pass it directly.
-      @plaintext_token = ApiKeys::TokenSession.retrieve_once(session, api_key: @api_key)
-      unless @plaintext_token
-        # If accessed directly without the token, redirect or show an error
-        redirect_to keys_path, alert: "API key token can only be shown once immediately after creation."
-      end
+      # Key is set by set_api_key. The plaintext token comes from the one-time
+      # session handoff written by create; it is released once, ever. This
+      # action opens no database transaction, so the durable claim commits
+      # before the token is rendered; keep it that way. A retrieval inside a
+      # transaction (for example a host around_action wrapping every request
+      # in one) is refused and the handoff kept, see ApiKeys::TokenSession.
+      retrieval = ApiKeys::TokenSession.retrieve_once_with_status(session, api_key: @api_key)
+      @plaintext_token = retrieval.token
+      return if @plaintext_token
+
+      # A replayed copy of the session, or a refresh after the token page,
+      # gets an explicit answer instead of the generic one.
+      alert = if retrieval.already_shown? || @api_key.token_shown?
+                ALREADY_SHOWN_ALERT
+              else
+                "API key token can only be shown once immediately after creation."
+              end
+      redirect_to keys_path, alert: alert
     end
 
     # GET /keys/new
@@ -54,13 +68,27 @@ module ApiKeys
     # 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]
+
+      # A `scopes: :ceiling` type is authorized by its live permissions, so
+      # the form offers no scopes for it and any submitted (cleared boxes, or
+      # a crafted request) are ignored. The key stores the type's current
+      # ceiling as its metadata.
+      type_config = requested_key_type_config(submitted_params[:key_type])
+      scopes = if ApiKeys::ApiKey.scopes_follow_ceiling_for?(type_config)
+                 type_config[:permissions].map(&:to_s)
+               else
+                 submitted_params[:scopes]
+               end
 
       # Use the HasApiKeys helper method to create the key
       begin
         # create_api_key! now returns the ApiKey instance
         @api_key = current_api_keys_owner.create_api_key!(
           name: submitted_params[:name],
-          scopes: submitted_params[:scopes],
+          scopes: scopes,
           expires_at: parse_expiration(submitted_params[:expires_at_preset]),
           key_type: submitted_params[:key_type].presence,
           # The model normalizes these raw strings; no parser needed here.
@@ -100,7 +128,25 @@ module ApiKeys
 
     # PATCH/PUT /keys/:id
     def update
-      if @api_key.update(api_key_update_params)
+      attributes = api_key_update_params
+      if @api_key.scopes_follow_ceiling?
+        # The type's live ceiling authorizes this key and its stored scopes are
+        # metadata. The form offers no scope boxes for it, so any submitted
+        # scopes (the sentinel, or a crafted request) are ignored, and held
+        # scopes outside a narrowed ceiling are kept: the model lets such a key
+        # save as long as its scopes are not written.
+        attributes.delete(:scopes)
+      else
+        # The form speaks only for the scopes it offered (see
+        # ApiKey#scopes_after_form_edit). Without a scopes parameter (no boxes
+        # were shown) it still drops held scopes the current ceiling excludes,
+        # or no edit of such a key could ever be saved.
+        edited = @api_key.scopes_after_form_edit(offered: dashboard_scope_choices, checked: attributes[:scopes])
+        attributes[:scopes] = edited if attributes.key?(:scopes) || edited != Array(@api_key.scopes)
+      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(', ')}"
@@ -139,10 +185,62 @@ module ApiKeys
 
       permitted_params = submitted.permit(:name, :expires_at_preset, :key_type,
                                           :allowed_origins, :allowed_ips, scopes: [])
-      permitted_params[:scopes]&.reject!(&:blank?) # Filter out blank strings
+      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
 
+    # 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 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.
@@ -151,7 +249,7 @@ module ApiKeys
       raise ActionController::ParameterMissing, :api_key unless submitted.respond_to?(:permit)
 
       permitted_params = submitted.permit(:name, :allowed_origins, :allowed_ips, scopes: [])
-      permitted_params[:scopes]&.reject!(&:blank?) # Filter out blank strings
+      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
@@ -200,6 +298,30 @@ module ApiKeys
       end.uniq
     end
 
+    # The permissions a key actually has, for display. A `scopes: :ceiling` key
+    # is authorized by its type's live ceiling, so showing the list it stored
+    # at creation would misstate what it can do.
+    #
+    # @param api_key [ApiKeys::ApiKey]
+    # @return [Array<String>]
+    def api_keys_displayed_scopes(api_key)
+      return Array(api_key.key_type_config[:permissions]).map(&:to_s) if api_key.scopes_follow_ceiling?
+
+      api_key.scopes.is_a?(Array) ? api_key.scopes : []
+    end
+
+    # The configuration of the key type a create request resolves to, the way
+    # create_api_key! resolves it (the submitted type, else the default), or
+    # nil when there is none or it is unknown.
+    #
+    # @return [Hash, nil]
+    def requested_key_type_config(key_type_param)
+      type_name = key_type_param.presence || ApiKeys.configuration.default_key_type
+      return nil if type_name.blank?
+
+      (ApiKeys.configuration.key_types || {}).find { |name, _settings| name.to_s == type_name.to_s }&.last
+    end
+
     # Check if key types feature is enabled
     def key_types_feature_enabled?
       ApiKeys.configuration.key_types.present? && ApiKeys.configuration.key_types.any?

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

@@ -33,7 +33,11 @@
           <% if config[:permissions] != :all %>
             <small class="api-keys-form-help">
               <strong><%= type.to_s.humanize %>:</strong>
-              Limited to <%= config[:permissions]&.join(", ") || "no" %> permissions
+              <% if ApiKeys::ApiKey.scopes_follow_ceiling_for?(config) %>
+                Always has exactly the <%= config[:permissions].join(", ") %> permissions
+              <% else %>
+                Limited to <%= config[:permissions]&.join(", ") || "no" %> permissions
+              <% end %>
               <% unless config.fetch(:revocable, true) %>
                 <em>(cannot be revoked)</em>
               <% end %>
@@ -64,20 +68,29 @@
       %>
     </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? %>
-      <div>
+    <%# The offered scopes are the owner's default scopes. The controller reads %>
+    <%# the same list (dashboard_scope_choices) when it saves the form. A key type %>
+    <%# with `scopes: :ceiling` has no scopes to choose: the script below hides and %>
+    <%# disables these boxes and shows that type's live permissions instead, and %>
+    <%# the controller ignores scopes submitted for it. %>
+    <% @available_scopes = dashboard_scope_choices %>
+    <% if @available_scopes.present? %>
+      <%= tag.div data: { api_keys_scope_choices: "" }, hidden: api_key.scopes_follow_ceiling? do %>
         <%= 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)
@@ -85,7 +98,21 @@
             <%= form.label "scopes_#{scope.parameterize}", class: "form-check-label" do %><code><%= scope %></code><% end %>
           </div>
         <% end %>
-      </div>
+      <% end %>
+    <% end %>
+
+    <% ApiKeys.configuration.key_types.to_h.each do |type, config| %>
+      <% next unless ApiKeys::ApiKey.scopes_follow_ceiling_for?(config) %>
+      <%= tag.div class: "api-keys-ceiling-scopes", data: { api_keys_ceiling_contract: type.to_s },
+                  hidden: api_key.key_type.to_s != type.to_s do %>
+        <p><strong>Permissions</strong></p>
+        <% config[:permissions].each do |scope| %>
+          <kbd class="tag is-small"><%= scope %></kbd>
+        <% end %>
+        <small class="api-keys-form-help">
+          <%= type.to_s.humanize %> keys always have exactly these permissions, and follow the key type when it changes.
+        </small>
+      <% end %>
     <% end %>
 
     <%= render "api_keys/keys/restriction_fields", form: form, api_key: api_key %>
@@ -99,19 +126,48 @@
       <%= 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? %>
+    <%# A `scopes: :ceiling` key is authorized by its type's live permissions and %>
+    <%# its stored scopes are metadata, so the form shows the live ceiling and %>
+    <%# offers nothing to edit; the controller ignores scopes submitted for it. %>
+    <%# Any other key gets the owner's default scopes as boxes, and a save edits %>
+    <%# only those: it keeps every other scope the key holds, except scopes its %>
+    <%# type no longer allows (ApiKey#scopes_after_form_edit). %>
+    <% @available_scopes = dashboard_scope_choices %>
+    <% dropped_scopes = api_key.scopes_follow_ceiling? ? [] : 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 api_key.scopes_follow_ceiling? %>
+      <div class="api-keys-ceiling-scopes">
+        <p><strong>Permissions / Scopes</strong></p>
+        <% api_keys_displayed_scopes(api_key).each do |scope| %>
+          <kbd class="tag is-small"><%= scope %></kbd>
+        <% end %>
+        <small class="api-keys-form-help">
+          Permissions follow the <%= api_key.key_type.humanize.downcase %> key type and update automatically when it changes.
+        </small>
+      </div>
+    <% elsif @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)
@@ -143,7 +199,8 @@
   <% 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)
+      expirable: ApiKeys::ApiKey.revocable_for(config),
+      ceiling: ApiKeys::ApiKey.scopes_follow_ceiling_for?(config)
     }] %>
   <% end %>
   <script nonce="<%= content_security_policy_nonce %>">
@@ -167,6 +224,17 @@
           container.hidden = !enabled;
           container.querySelectorAll("input, select, textarea").forEach((input) => { input.disabled = !enabled; });
         });
+
+        // A scopes: :ceiling type has no scopes to choose: hide and disable the
+        // boxes (so none are submitted) and show that type's live permissions.
+        const ceiling = Boolean(policy && policy.ceiling);
+        form.querySelectorAll("[data-api-keys-scope-choices]").forEach((container) => {
+          container.hidden = ceiling;
+          container.querySelectorAll("input, select, textarea").forEach((input) => { input.disabled = ceiling; });
+        });
+        form.querySelectorAll("[data-api-keys-ceiling-contract]").forEach((container) => {
+          container.hidden = !(ceiling && container.dataset.apiKeysCeilingContract === keyType.value);
+        });
       };
 
       keyType.addEventListener("change", updatePolicyFields);

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

@@ -40,11 +40,13 @@
     <% else %>
       <em>Never used</em>
     <% end %>
+    <%= render partial: 'api_keys/keys/refusal_notice', locals: { key: key, compact: true } %>
   </td>
 
   <td class="api-keys-cell-scopes">
-    <% if key.scopes.present? %>
-      <% key.scopes.each do |scope| %>
+    <% displayed_scopes = api_keys_displayed_scopes(key) %>
+    <% if displayed_scopes.present? %>
+      <% displayed_scopes.each do |scope| %>
         <kbd class="api-keys-scope-tag tag is-small"><%= scope %></kbd>
       <% end %>
     <% else %>

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

@@ -0,0 +1,24 @@
+<%# Refused-but-identified traffic for one key: requests that presented this key's %>
+<%# real token and were refused by a policy. Renders nothing until one is recorded, %>
+<%# and nothing on installations without the refusal stats columns. %>
+<%# Locals: key (required), compact (optional, for the key list) %>
+
+<% refused_at = key.last_refused_at %>
+<% if refused_at %>
+  <% reason = api_key_refusal_reason(key) %>
+  <% still_refused = key.last_used_at.nil? || refused_at > key.last_used_at %>
+  <% if local_assigns[:compact] %>
+    <small class="api-keys-refusal-text" title="<%= refused_at.utc.strftime('%Y-%m-%d %H:%M:%S UTC') %>">
+      Refused <%= time_ago_in_words(refused_at) %> ago: <%= reason %>
+    </small>
+  <% else %>
+    <p class="api-keys-refusal-notice" role="status">
+      <strong><%= still_refused ? "Requests are arriving but refused" : "Some requests were refused" %>:</strong>
+      last at <time datetime="<%= refused_at.utc.iso8601 %>"><%= refused_at.utc.strftime("%Y-%m-%d %H:%M:%S UTC") %></time>
+      (<%= time_ago_in_words(refused_at) %> ago), because <%= reason %>.
+      <% if ApiKeys.configuration.track_requests_count && key.refusals_count.positive? %>
+        <%= pluralize(key.refusals_count, "refusal") %> recorded so far.
+      <% end %>
+    </p>
+  <% end %>
+<% end %>

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

@@ -1,6 +1,8 @@
 <%# 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) %>
@@ -9,7 +11,7 @@
     <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(", "),
+                          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.
@@ -22,7 +24,7 @@
     <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(", "),
+                          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.

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

@@ -35,16 +35,13 @@
   </div>
 
 
-  <% if api_key.scopes.present? %>
+  <% displayed_scopes = api_keys_displayed_scopes(api_key) %>
+  <% if displayed_scopes.present? %>
     <div class="api-keys-token-scopes">
       <p><strong>Permissions</strong></p>
 
-      <% if api_key.scopes.present? %>
-        <% api_key.scopes.each do |scope| %>
-          <kbd class="tag is-small"><%= scope %></kbd>
-        <% end %>
-      <% else %>
-        &mdash;
+      <% displayed_scopes.each do |scope| %>
+        <kbd class="tag is-small"><%= scope %></kbd>
       <% end %>
     </div>
   <% end %>

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

@@ -1,5 +1,7 @@
 <div class="col-5">
   <h2>Edit API Key: <%= @api_key.name.presence || @api_key.masked_token %></h2>
 
+  <%= render 'refusal_notice', key: @api_key %>
+
   <%= render 'form', api_key: @api_key %> 
 </div>

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

@@ -198,6 +198,12 @@
     [hidden] { display: none !important; }
     .api-keys-form-errors { color: var(--api-keys-danger-color); }
     .api-keys-form-help { display: block; color: var(--color-darkGrey, #666); }
+    .api-keys-refusal-notice {
+      padding: 0.8em 1em;
+      border-left: 4px solid var(--api-keys-warning-color);
+      background-color: var(--bg-secondary-color, #f9f9f9);
+    }
+    .api-keys-refusal-text { display: block; color: var(--api-keys-danger-color); }
     .api-keys-empty-state { text-align: center; padding: 2em; }
     .api-keys-expired-text { color: var(--api-keys-status-expired-color); }
     .api-keys-token-panel { padding: 1em; margin: 1em 0; border-radius: 4px; }

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.