Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Add secret API key hashing (Stripe model) (#13673)

Damian Legawiec55ab06a89f4a
diff --git a/server/db/schema.rb b/server/db/schema.rb
index b8400ac22c..041e94beca 100644
--- a/server/db/schema.rb
+++ b/server/db/schema.rb
@@ -10,7 +10,7 @@
#
# It's strongly recommended that you check this file into your version control system.
-ActiveRecord::Schema[8.1].define(version: 2026_02_26_165442) do
+ActiveRecord::Schema[8.1].define(version: 2026_02_27_081642) do
# These are extensions that must be enabled in order to support this database
enable_extension "pg_catalog.plpgsql"
enable_extension "pg_trgm"
@@ -164,14 +164,17 @@ ActiveRecord::Schema[8.1].define(version: 2026_02_26_165442) do
t.bigint "revoked_by_id"
t.string "revoked_by_type"
t.bigint "store_id", null: false
- t.string "token", null: false
+ t.string "token"
+ t.string "token_digest"
+ t.string "token_prefix"
t.datetime "updated_at", null: false
t.index ["created_by_type", "created_by_id"], name: "index_spree_api_keys_on_created_by"
t.index ["key_type"], name: "index_spree_api_keys_on_key_type"
t.index ["revoked_by_type", "revoked_by_id"], name: "index_spree_api_keys_on_revoked_by"
t.index ["store_id", "key_type"], name: "index_spree_api_keys_on_store_id_and_key_type"
t.index ["store_id"], name: "index_spree_api_keys_on_store_id"
- t.index ["token"], name: "index_spree_api_keys_on_token", unique: true
+ t.index ["token"], name: "index_spree_api_keys_on_token", unique: true, where: "(token IS NOT NULL)"
+ t.index ["token_digest"], name: "index_spree_api_keys_on_token_digest", unique: true
end
create_table "spree_assets", force: :cascade do |t|
diff --git a/spree/admin/app/controllers/spree/admin/api_keys_controller.rb b/spree/admin/app/controllers/spree/admin/api_keys_controller.rb
index efee27f075..8955427f21 100644
--- a/spree/admin/app/controllers/spree/admin/api_keys_controller.rb
+++ b/spree/admin/app/controllers/spree/admin/api_keys_controller.rb
@@ -8,6 +8,27 @@ module Spree
helper 'spree/admin/api_keys'
+ def create
+ invoke_callbacks(:create, :before)
+ set_created_by
+ @object.attributes = permitted_resource_params
+ if @object.save
+ invoke_callbacks(:create, :after)
+ if @object.secret?
+ # Pass plaintext token via flash so the show page can display it once.
+ # Flash is stored in the encrypted session cookie and auto-cleared after one request.
+ # Skip the success flash — the token warning banner is sufficient feedback.
+ flash[:plaintext_token] = @object.plaintext_token
+ else
+ flash[:success] = message_after_create
+ end
+ redirect_to location_after_create, status: :see_other
+ else
+ invoke_callbacks(:create, :fails)
+ render action: :new, status: :unprocessable_content
+ end
+ end
+
def revoke
@object = scope.find_by_prefix_id!(params[:id])
@object.revoke!(try_spree_current_user)
diff --git a/spree/admin/app/helpers/spree/admin/api_keys_helper.rb b/spree/admin/app/helpers/spree/admin/api_keys_helper.rb
index e0556a1c09..f27f8638e6 100644
--- a/spree/admin/app/helpers/spree/admin/api_keys_helper.rb
+++ b/spree/admin/app/helpers/spree/admin/api_keys_helper.rb
@@ -24,8 +24,12 @@ module Spree
end
def masked_api_key(api_key)
- token = api_key.token
- "#{token[0..6]}#{'*' * 16}#{token[-4..]}"
+ if api_key.secret?
+ "#{api_key.token_prefix}#{'*' * 15}"
+ else
+ token = api_key.token
+ "#{token[0..6]}#{'*' * 16}#{token[-4..]}"
+ end
end
end
end
diff --git a/spree/admin/app/views/spree/admin/api_keys/_token_card.html.erb b/spree/admin/app/views/spree/admin/api_keys/_token_card.html.erb
index e1fe4d4752..7802985ff2 100644
--- a/spree/admin/app/views/spree/admin/api_keys/_token_card.html.erb
+++ b/spree/admin/app/views/spree/admin/api_keys/_token_card.html.erb
@@ -3,25 +3,52 @@
<h5 class="card-title"><%= Spree.t(:api_key) %></h5>
</div>
<div class="card-body">
- <% if @api_key.active? %>
+ <% if !@api_key.active? %>
+ <div class="bg-red-50 border border-red-200 rounded-md p-4">
+ <div class="flex items-center">
+ <%= icon 'alert-triangle', class: 'text-red-500 mr-2' %>
+ <span class="text-red-700"><%= Spree.t('admin.api_keys.key_revoked_message') %></span>
+ </div>
+ </div>
+ <% elsif @api_key.secret? && flash[:plaintext_token].present? %>
+ <div class="bg-yellow-50 border border-yellow-200 rounded-md p-4 mb-4">
+ <div class="flex items-center">
+ <%= icon 'alert-triangle', class: 'text-yellow-600 mr-2' %>
+ <span class="text-yellow-800 text-sm font-medium"><%= Spree.t('admin.api_keys.token_warning') %></span>
+ </div>
+ </div>
<div data-controller="password-visibility" class="input-group gap-0 pr-1">
- <input type="password" class="grow text-truncate" data-password-visibility-target="input" spellcheck="false" value="<%= @api_key.token %>" readonly>
+ <input type="password" class="grow text-truncate" data-password-visibility-target="input" spellcheck="false" value="<%= flash[:plaintext_token] %>" readonly>
<button type="button" class="btn hover:bg-gray-100 p-1 mr-1 rounded" data-action="password-visibility#toggle">
<span data-password-visibility-target="icon"><%= icon 'eye', class: 'mr-0' %></span>
<span data-password-visibility-target="icon" class="hidden"><%= icon 'eye-off', class: 'mr-0' %></span>
</button>
- <%= clipboard_component(@api_key.token,
- button_class: 'btn hover:bg-gray-100 p-1 rounded',
+ <%= clipboard_component(flash[:plaintext_token],
+ button_class: 'btn hover:bg-gray-100 p-1 rounded',
icon_class: 'mr-0') %>
</div>
- <% else %>
- <div class="bg-red-50 border border-red-200 rounded-md p-4">
- <div class="flex items-center">
- <%= icon 'alert-triangle', class: 'text-red-500 mr-2' %>
- <span class="text-red-700"><%= Spree.t('admin.api_keys.key_revoked_message') %></span>
+ <% elsif @api_key.secret? %>
+ <div class="bg-gray-50 border border-gray-200 rounded-md p-4">
+ <div class="flex items-center mb-2">
+ <%= icon 'lock', class: 'text-gray-500 mr-2' %>
+ <span class="text-gray-700 text-sm font-medium"><%= Spree.t('admin.api_keys.secret_key_hidden') %></span>
</div>
+ <code class="text-sm text-gray-500"><%= @api_key.token_prefix %><%= '***************' %></code>
+ </div>
+ <% else %>
+ <div data-controller="password-visibility" class="input-group gap-0 pr-1">
+ <input type="password" class="grow text-truncate" data-password-visibility-target="input" spellcheck="false" value="<%= @api_key.token %>" readonly>
+
+ <button type="button" class="btn hover:bg-gray-100 p-1 mr-1 rounded" data-action="password-visibility#toggle">
+ <span data-password-visibility-target="icon"><%= icon 'eye', class: 'mr-0' %></span>
+ <span data-password-visibility-target="icon" class="hidden"><%= icon 'eye-off', class: 'mr-0' %></span>
+ </button>
+
+ <%= clipboard_component(@api_key.token,
+ button_class: 'btn hover:bg-gray-100 p-1 rounded',
+ icon_class: 'mr-0') %>
</div>
<% end %>
</div>
diff --git a/spree/admin/app/views/spree/admin/api_keys/_usage_info.html.erb b/spree/admin/app/views/spree/admin/api_keys/_usage_info.html.erb
index cf5d0eef3d..72eccbae48 100644
--- a/spree/admin/app/views/spree/admin/api_keys/_usage_info.html.erb
+++ b/spree/admin/app/views/spree/admin/api_keys/_usage_info.html.erb
@@ -8,9 +8,10 @@
</p>
<h6 class="font-medium text-sm mb-2"><%= Spree.t('admin.api_keys.example_request') %></h6>
+ <% example_token = flash[:plaintext_token] || @api_key.token || "#{@api_key.token_prefix}..." %>
<div class="bg-gray-900 rounded-md p-4 overflow-x-auto">
<pre class="text-green-400 text-sm font-mono whitespace-pre-wrap"><code>curl -X GET "https://your-store.com/api/v3/store/products" \
- -H "X-Spree-Api-Key: <%= @api_key.token %>"</code></pre>
+ -H "X-Spree-Api-Key: <%= example_token %>"</code></pre>
</div>
</div>
</div>
diff --git a/spree/admin/config/locales/en.yml b/spree/admin/config/locales/en.yml
index efadaf82e3..efda2b1197 100644
--- a/spree/admin/config/locales/en.yml
+++ b/spree/admin/config/locales/en.yml
@@ -20,6 +20,7 @@ en:
revoked: API key has been revoked
revoked_at: Revoked at
revoked_by: Revoked by
+ secret_key_hidden: This secret key cannot be revealed. If you've lost it, revoke this key and create a new one.
statuses:
active: Active
revoked: Revoked
diff --git a/spree/admin/spec/controllers/spree/admin/api_keys_controller_spec.rb b/spree/admin/spec/controllers/spree/admin/api_keys_controller_spec.rb
index 23d60b564a..7ef797d932 100644
--- a/spree/admin/spec/controllers/spree/admin/api_keys_controller_spec.rb
+++ b/spree/admin/spec/controllers/spree/admin/api_keys_controller_spec.rb
@@ -105,11 +105,20 @@ RSpec.describe Spree::Admin::ApiKeysController, type: :controller do
}
end
- it 'generates a token with sk_ prefix' do
+ it 'stores token_digest and token_prefix instead of plaintext token' do
create_key
api_key = Spree::ApiKey.last
- expect(api_key.token).to start_with('sk_')
+ expect(api_key.token).to be_nil
+ expect(api_key.token_digest).to be_present
+ expect(api_key.token_prefix).to start_with('sk_')
+ end
+
+ it 'passes plaintext_token via flash for one-time display' do
+ create_key
+
+ expect(flash[:plaintext_token]).to start_with('sk_')
+ expect(response).to redirect_to(spree.admin_api_key_path(Spree::ApiKey.last))
end
end
diff --git a/spree/api/app/controllers/concerns/spree/api/v3/api_key_authentication.rb b/spree/api/app/controllers/concerns/spree/api/v3/api_key_authentication.rb
index 20e7d4c0fb..0c0f580610 100644
--- a/spree/api/app/controllers/concerns/spree/api/v3/api_key_authentication.rb
+++ b/spree/api/app/controllers/concerns/spree/api/v3/api_key_authentication.rb
@@ -5,9 +5,16 @@ module Spree
extend ActiveSupport::Concern
included do
+ # @!attribute [r] current_api_key
+ # The authenticated API key for the current request.
+ # @return [Spree::ApiKey, nil]
attr_reader :current_api_key
end
+ # Authenticates a publishable API key (pk_*) for Store API requests.
+ # Looks up the key by plaintext token scoped to the current store.
+ #
+ # @return [Boolean] true if authentication succeeded, false otherwise
def authenticate_api_key!
@current_api_key = current_store.api_keys.active.publishable.find_by(token: extract_api_key)
@@ -24,8 +31,14 @@ module Spree
true
end
+ # Authenticates a secret API key (sk_*) for Admin API requests.
+ # Computes the HMAC-SHA256 digest of the provided token and looks up
+ # by +token_digest+, then verifies it belongs to the current store.
+ #
+ # @return [Boolean] true if authentication succeeded, false otherwise
def authenticate_secret_key!
- @current_api_key = current_store.api_keys.active.secret.find_by(token: extract_api_key)
+ @current_api_key = Spree::ApiKey.find_by_secret_token(extract_api_key)
+ @current_api_key = nil if @current_api_key && @current_api_key.store_id != current_store.id
unless @current_api_key
render_error(
@@ -42,6 +55,9 @@ module Spree
private
+ # Extracts the API key from the request headers or params.
+ #
+ # @return [String, nil] the API key token
def extract_api_key
request.headers['X-Spree-Api-Key'].presence || params[:api_key]
end
diff --git a/spree/core/app/models/spree/api_key.rb b/spree/core/app/models/spree/api_key.rb
index 30dce7d333..8bce45521f 100644
--- a/spree/core/app/models/spree/api_key.rb
+++ b/spree/core/app/models/spree/api_key.rb
@@ -6,13 +6,21 @@ module Spree
PREFIXES = { 'publishable' => 'pk_', 'secret' => 'sk_' }.freeze
TOKEN_LENGTH = 24
+ # @!attribute [r] plaintext_token
+ # The raw token value, only available in memory immediately after creation
+ # of a secret key. Not persisted to the database.
+ # @return [String, nil]
+ attr_reader :plaintext_token
+
belongs_to :store, class_name: 'Spree::Store'
belongs_to :created_by, polymorphic: true, optional: true
belongs_to :revoked_by, polymorphic: true, optional: true
validates :name, presence: true
validates :key_type, presence: true, inclusion: { in: KEY_TYPES }
- validates :token, presence: true, uniqueness: { scope: spree_base_uniqueness_scope }
+ validates :token, presence: true, uniqueness: { scope: spree_base_uniqueness_scope }, if: :publishable?
+ validates :token_digest, presence: true, uniqueness: true, if: :secret?
+ validates :token_prefix, presence: true, if: :secret?
validates :store, presence: true
before_validation :generate_token, on: :create
@@ -22,26 +30,73 @@ module Spree
scope :publishable, -> { where(key_type: 'publishable') }
scope :secret, -> { where(key_type: 'secret') }
+ # Finds an active secret API key by computing the HMAC-SHA256 digest
+ # of the provided plaintext token and looking up by +token_digest+.
+ #
+ # @param plaintext [String] the raw secret key (e.g. "sk_abc123...")
+ # @return [Spree::ApiKey, nil] the matching active secret key, or nil
+ def self.find_by_secret_token(plaintext)
+ return nil if plaintext.blank?
+
+ digest = compute_token_digest(plaintext)
+ active.secret.find_by(token_digest: digest)
+ end
+
+ # Computes the HMAC-SHA256 hex digest for a given plaintext token.
+ #
+ # @param plaintext [String] the raw token value
+ # @return [String] the hex-encoded HMAC-SHA256 digest
+ def self.compute_token_digest(plaintext)
+ OpenSSL::HMAC.hexdigest('SHA256', hmac_secret, plaintext)
+ end
+
+ # Returns the HMAC secret used for token hashing.
+ #
+ # @return [String] the application's secret key base
+ def self.hmac_secret
+ Rails.application.secret_key_base
+ end
+
+ # @return [Boolean] whether this is a publishable (Store API) key
def publishable?
key_type == 'publishable'
end
+ # @return [Boolean] whether this is a secret (Admin API) key
def secret?
key_type == 'secret'
end
+ # @return [Boolean] whether this key has not been revoked
def active?
revoked_at.nil?
end
+ # Revokes this API key by setting +revoked_at+ to the current time.
+ #
+ # @param user [Object, nil] the user who performed the revocation
+ # @return [Boolean] true if the update succeeded
def revoke!(user = nil)
update!(revoked_at: Time.current, revoked_by: user)
end
private
+ # Generates the token on creation. For publishable keys, stores the raw token
+ # in the +token+ column. For secret keys, computes an HMAC-SHA256 digest stored
+ # in +token_digest+, saves the first 12 characters as +token_prefix+ for display,
+ # and exposes the raw value via {#plaintext_token} (available only in memory).
def generate_token
- self.token ||= "#{PREFIXES[key_type]}#{SecureRandom.base58(TOKEN_LENGTH)}"
+ raw_token = "#{PREFIXES[key_type]}#{SecureRandom.base58(TOKEN_LENGTH)}"
+
+ if secret?
+ @plaintext_token = raw_token
+ self.token_prefix = raw_token[0, 12]
+ self.token_digest = self.class.compute_token_digest(raw_token)
+ self.token = nil
+ else
+ self.token ||= raw_token
+ end
end
end
end
diff --git a/spree/core/db/migrate/20260226100000_add_token_digest_to_spree_api_keys.rb b/spree/core/db/migrate/20260226100000_add_token_digest_to_spree_api_keys.rb
new file mode 100644
index 0000000000..6212227338
--- /dev/null
+++ b/spree/core/db/migrate/20260226100000_add_token_digest_to_spree_api_keys.rb
@@ -0,0 +1,21 @@
+class AddTokenDigestToSpreeApiKeys < ActiveRecord::Migration[7.2]
+ def change
+ add_column :spree_api_keys, :token_digest, :string
+ add_column :spree_api_keys, :token_prefix, :string
+
+ add_index :spree_api_keys, :token_digest, unique: true
+
+ # Replace the unconditional unique index on token with one that only covers
+ # non-NULL values (publishable keys). Secret keys store token as NULL
+ # and use token_digest for lookups instead.
+ change_column_null :spree_api_keys, :token, true
+ remove_index :spree_api_keys, :token
+ if ActiveRecord::Base.connection.adapter_name == 'Mysql2'
+ # MySQL doesn't support partial indexes, but treats NULL as distinct
+ # in unique indexes so multiple secret keys with NULL token are allowed
+ add_index :spree_api_keys, :token, unique: true
+ else
+ add_index :spree_api_keys, :token, unique: true, where: 'token IS NOT NULL'
+ end
+ end
+end
diff --git a/spree/core/spec/models/spree/api_key_spec.rb b/spree/core/spec/models/spree/api_key_spec.rb
index e83107fb17..21d393c79a 100644
--- a/spree/core/spec/models/spree/api_key_spec.rb
+++ b/spree/core/spec/models/spree/api_key_spec.rb
@@ -32,32 +32,94 @@ RSpec.describe Spree::ApiKey, type: :model do
expect(api_key).not_to be_valid
end
- it 'requires unique token' do
- duplicate = build(:api_key, store: store, token: api_key.token)
+ it 'requires unique token for publishable keys' do
+ duplicate = build(:api_key, :publishable, store: store, token: api_key.token)
expect(duplicate).not_to be_valid
expect(duplicate.errors[:token]).to be_present
end
- end
- describe 'token generation' do
- it 'generates token on create' do
- new_key = build(:api_key, store: store, token: nil)
- new_key.save!
- expect(new_key.token).to be_present
+ it 'validates token_digest presence for secret keys' do
+ key = described_class.new(name: 'test', key_type: 'secret', store: store)
+ # Skip the generate_token callback to test the validation directly
+ key.instance_variable_set(:@_generate_token_called, true)
+ described_class.skip_callback(:validation, :before, :generate_token, raise: false)
+ expect(key).not_to be_valid
+ expect(key.errors[:token_digest]).to be_present
+ ensure
+ described_class.set_callback(:validation, :before, :generate_token, on: :create)
end
- it 'generates publishable key with pk_ prefix' do
- key = create(:api_key, :publishable, store: store)
- expect(key.token).to start_with('pk_')
+ it 'validates token_prefix presence for secret keys' do
+ key = described_class.new(name: 'test', key_type: 'secret', store: store)
+ key.token_digest = 'some_digest'
+ described_class.skip_callback(:validation, :before, :generate_token, raise: false)
+ expect(key).not_to be_valid
+ expect(key.errors[:token_prefix]).to be_present
+ ensure
+ described_class.set_callback(:validation, :before, :generate_token, on: :create)
end
+ end
- it 'generates secret key with sk_ prefix' do
- key = create(:api_key, :secret, store: store)
- expect(key.token).to start_with('sk_')
+ describe 'token generation' do
+ context 'publishable keys' do
+ it 'generates token on create' do
+ new_key = build(:api_key, :publishable, store: store, token: nil)
+ new_key.save!
+ expect(new_key.token).to be_present
+ end
+
+ it 'generates publishable key with pk_ prefix' do
+ key = create(:api_key, :publishable, store: store)
+ expect(key.token).to start_with('pk_')
+ end
+
+ it 'generates token of correct length' do
+ expect(api_key.token.length).to eq(3 + Spree::ApiKey::TOKEN_LENGTH)
+ end
+
+ it 'does not set plaintext_token' do
+ key = create(:api_key, :publishable, store: store)
+ expect(key.plaintext_token).to be_nil
+ end
+
+ it 'does not set token_digest' do
+ key = create(:api_key, :publishable, store: store)
+ expect(key.token_digest).to be_nil
+ end
end
- it 'generates token of correct length' do
- expect(api_key.token.length).to eq(3 + Spree::ApiKey::TOKEN_LENGTH)
+ context 'secret keys' do
+ it 'generates secret key with sk_ prefix in plaintext_token' do
+ key = create(:api_key, :secret, store: store)
+ expect(key.plaintext_token).to start_with('sk_')
+ end
+
+ it 'does not store plaintext token in token column' do
+ key = create(:api_key, :secret, store: store)
+ expect(key.token).to be_nil
+ end
+
+ it 'stores token_digest as HMAC-SHA256 hex' do
+ key = create(:api_key, :secret, store: store)
+ expected_digest = OpenSSL::HMAC.hexdigest('SHA256', Rails.application.secret_key_base, key.plaintext_token)
+ expect(key.token_digest).to eq(expected_digest)
+ end
+
+ it 'stores first 12 chars as token_prefix' do
+ key = create(:api_key, :secret, store: store)
+ expect(key.token_prefix).to eq(key.plaintext_token[0, 12])
+ end
+
+ it 'generates plaintext_token of correct length' do
+ key = create(:api_key, :secret, store: store)
+ expect(key.plaintext_token.length).to eq(3 + Spree::ApiKey::TOKEN_LENGTH)
+ end
+
+ it 'plaintext_token is not available on fresh load from database' do
+ key = create(:api_key, :secret, store: store)
+ reloaded_key = described_class.find(key.id)
+ expect(reloaded_key.plaintext_token).to be_nil
+ end
end
end
@@ -147,6 +209,36 @@ RSpec.describe Spree::ApiKey, type: :model do
end
end
+ describe '.find_by_secret_token' do
+ it 'finds a secret key by its plaintext token' do
+ key = create(:api_key, :secret, store: store)
+ found = described_class.find_by_secret_token(key.plaintext_token)
+ expect(found).to eq(key)
+ end
+
+ it 'returns nil for wrong token' do
+ create(:api_key, :secret, store: store)
+ expect(described_class.find_by_secret_token('sk_wrong_token')).to be_nil
+ end
+
+ it 'returns nil for blank token' do
+ expect(described_class.find_by_secret_token('')).to be_nil
+ expect(described_class.find_by_secret_token(nil)).to be_nil
+ end
+
+ it 'does not find revoked secret keys' do
+ key = create(:api_key, :secret, store: store)
+ plaintext = key.plaintext_token
+ key.revoke!
+ expect(described_class.find_by_secret_token(plaintext)).to be_nil
+ end
+
+ it 'does not find publishable keys' do
+ key = create(:api_key, :publishable, store: store)
+ expect(described_class.find_by_secret_token(key.token)).to be_nil
+ end
+ end
+
describe 'associations' do
it 'belongs to store' do
expect(api_key.store).to eq(store)