Add public key token storage for non-revocable publishable keys

Non-revocable keys create a UX problem: if users lose the token, they're
locked out forever since they can't delete and recreate the key. This is
especially problematic with limit: 1 configurations.

This adds a `public: true` option for key types that stores the plaintext
token in metadata, allowing users to view it again in the dashboard.

Security: Token storage ONLY happens when BOTH conditions are met:
- public: true is set in the key type configuration
- revocable: false is set (non-revocable keys only)

This double-check ensures secret keys are NEVER stored, even if someone
accidentally sets public: true on them (since secret keys are revocable
by default).

Changes:
- Add public_key_type? and viewable_token methods to ApiKey model
- Store token in metadata during creation for public keys
- Add Show/Copy buttons in dashboard for public keys
- Document public option in configuration, initializer, and README
- Add 20 tests including 10 security tests verifying secret keys
  are never stored under any circumstances

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: rameerez

README.md

@@ -555,6 +555,67 @@ pk.destroy!    # Raises ApiKeys::Errors::KeyNotRevocableError
 
 The dashboard UI automatically hides the revoke button for non-revocable keys.
 
+### Public Keys (Viewable Tokens)
+
+#### The Problem: Non-Revocable Key Lockout
+
+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.
+
+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.
+
+#### The Solution: Storing Public Keys
+
+For publishable keys—which are *designed* to be embedded in client-side code and distributed apps—there's no security benefit to hiding the token. These keys are meant to be public! Stripe, for example, lets you view your publishable key anytime in the dashboard.
+
+The `public: true` option stores the plaintext token in metadata so users can view it again:
+
+```ruby
+config.key_types = {
+  publishable: {
+    prefix: "pk",
+    permissions: %w[read validate],
+    revocable: false,
+    public: true,   # Store token for later viewing
+    limit: 1
+  },
+  secret: {
+    prefix: "sk",
+    permissions: :all
+    # public: false (default) - NEVER store secret keys!
+  }
+}
+```
+
+#### Security: Why This is Safe
+
+> [!IMPORTANT]
+> The `public` option only works when BOTH conditions are met:
+>  - `public: true` is set in the key type configuration
+>  - `revocable: false` is set (non-revocable keys only)
+
+This double-check is a deliberate safety measure:
+
+1. **Secret keys are NEVER stored** — Even if you accidentally set `public: true` on a secret key type, the gem checks for `revocable: false` as well. Secret keys are revocable by default, so they're protected.
+
+2. **Revocable keys are NEVER stored** — If a key can be revoked, users can always delete it and create a new one. There's no lockout risk, so no need to store the token.
+
+3. **Only truly public keys are stored** — Publishable keys with limited permissions, designed for client-side embedding, are the only keys that get stored. These tokens provide no security benefit when hidden—they're meant to be distributed.
+
+> [!WARNING]
+> ⚠️ **Never set `public: true` on secret keys or any key type with sensitive permissions.** The gem prevents this by requiring `revocable: false`, but you should also never configure it that way.
+
+When a key is public, the dashboard shows a "Show" button to reveal the full token:
+
+```ruby
+pk = user.create_api_key!(key_type: :publishable)
+pk.public_key_type?  # => true
+pk.viewable_token    # => "pk_test_abc123..." (the full token)
+
+sk = user.create_api_key!(key_type: :secret)
+sk.public_key_type?  # => false
+sk.viewable_token    # => nil (not stored)
+```
+
 ### Environment Isolation
 
 With `strict_environment_isolation = true`, keys can only authenticate in their matching environment:

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

@@ -22,7 +22,16 @@
       </span>
     <% end %>
   </td>
-  <td><code><%= key.masked_token %></code></td>
+  <td>
+    <code><%= key.masked_token %></code>
+    <% if key.public_key_type? && key.viewable_token.present? %>
+      <button type="button" onclick="this.nextElementSibling.style.display='inline'; this.style.display='none';" style="margin-left: 8px; font-size: 0.75em; padding: 2px 6px; cursor: pointer;" title="Show full token">Show</button>
+      <span style="display: none;">
+        <code style="word-break: break-all;"><%= key.viewable_token %></code>
+        <button type="button" onclick="navigator.clipboard.writeText('<%= key.viewable_token %>'); alert('Copied!');" style="margin-left: 4px; font-size: 0.75em; padding: 2px 6px; cursor: pointer;" title="Copy to clipboard">Copy</button>
+      </span>
+    <% end %>
+  </td>
 
 
   <td title="<%= key.created_at.strftime('%Y-%m-%d %H:%M:%S %Z') %>">

lib/api_keys/configuration.rb

@@ -63,9 +63,12 @@ class Configuration
     #     - :permissions [Array<String>, :all] Scope ceiling for this type
     #     - :revocable [Boolean] Whether keys can be revoked (default: true)
     #     - :limit [Integer, nil] Max keys per owner per environment (nil = unlimited)
+    #     - :public [Boolean] If true AND revocable: false, store plaintext token in
+    #       metadata so it can be viewed again in dashboard. Use ONLY for publishable
+    #       keys that are designed to be embedded in distributed apps. (default: false)
     #   @example
     #     config.key_types = {
-    #       publishable: { prefix: "pk", permissions: %w[read], revocable: false, limit: 1 },
+    #       publishable: { prefix: "pk", permissions: %w[read], revocable: false, public: true, limit: 1 },
     #       secret: { prefix: "sk", permissions: :all }
     #     }
     #

lib/api_keys/models/api_key.rb

@@ -102,6 +102,24 @@ def environment_config
       ApiKeys.configuration.environments&.dig(environment.to_sym)
     end
 
+    # Returns true if this key type is configured as public AND non-revocable.
+    # Only these keys have their plaintext token stored in metadata for later viewing.
+    # This is used for publishable keys that are designed to be embedded in distributed apps.
+    def public_key_type?
+      return false if key_type.blank?
+      config = key_type_config
+      return false if config.nil?
+      config[:public] == true && config[:revocable] == false
+    end
+
+    # Returns the stored plaintext token for public, non-revocable keys.
+    # Returns nil for all other key types (the token is only available at creation time).
+    # @return [String, nil] The full plaintext token, or nil if not stored
+    def viewable_token
+      return nil unless public_key_type?
+      metadata&.dig("token")
+    end
+
     # Override destroy to prevent destroying non-revocable keys
     def destroy
       raise ApiKeys::Errors::KeyNotRevocableError unless revocable?
@@ -237,6 +255,14 @@ def generate_token_and_digest
       if ApiKeys.configuration.expire_after.present? && self.expires_at.nil?
         self.expires_at = ApiKeys.configuration.expire_after.from_now
       end
+
+      # Store plaintext token in metadata for public, non-revocable keys.
+      # This allows users to view the token again in the dashboard.
+      # SECURITY: Only do this for keys explicitly configured as public: true
+      # AND revocable: false (e.g., publishable keys for distributed apps).
+      if public_key_type?
+        self.metadata = (self.metadata || {}).merge("token" => @token)
+      end
     end
 
     # == Validation Helpers ==

lib/generators/api_keys/templates/initializer.rb

@@ -111,18 +111,24 @@
   # - permissions: Scope ceiling - array of allowed scopes, or :all for unrestricted
   # - revocable:   Whether keys of this type can be revoked/deleted (default: true)
   # - limit:       Max keys of this type per owner per environment (nil = unlimited)
+  # - public:      If true AND revocable: false, stores plaintext token in metadata
+  #                so it can be viewed again in the dashboard. Use ONLY for publishable
+  #                keys designed to be embedded in distributed apps. (default: false)
+  #                SECURITY: NEVER set public: true on secret keys!
   #
   # config.key_types = {
   #   publishable: {
   #     prefix: "pk",                    # → pk_test_, pk_live_
   #     permissions: %w[read validate],  # Can ONLY have these scopes
   #     revocable: false,                # Cannot be revoked - protects deployed apps!
+  #     public: true,                    # Store token for later viewing in dashboard
   #     limit: 1                         # Only 1 publishable key per environment
   #   },
   #   secret: {
   #     prefix: "sk",                    # → sk_test_, sk_live_
   #     permissions: :all                # No scope restrictions
   #     # revocable: true (default)
+  #     # public: false (default) - NEVER store secret keys!
   #     # limit: nil (default = unlimited)
   #   }
   # }