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.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Add secret API key hashing (Stripe model) (#13673)
Damian Legawiec55ab06a89f4a
diff --git a/server/db/schema.rb b/server/db/schema.rbindex 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 databaseenable_extension "pg_catalog.plpgsql"enable_extension "pg_trgm"@@ -164,14 +164,17 @@ ActiveRecord::Schema[8.1].define(version: 2026_02_26_165442) dot.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: falset.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: trueendcreate_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.rbindex 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 Spreehelper '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.rbindex 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 Spreeenddef 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..]}"+ endendendenddiff --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.erbindex 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.erbindex 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.ymlindex 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 revokedrevoked_at: Revoked atrevoked_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: Activerevoked: Revokeddiff --git a/spree/admin/spec/controllers/spree/admin/api_keys_controller_spec.rb b/spree/admin/spec/controllers/spree/admin/api_keys_controller_spec.rbindex 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' docreate_keyapi_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))endenddiff --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.rbindex 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 Spreeextend ActiveSupport::Concernincluded do+ # @!attribute [r] current_api_key+ # The authenticated API key for the current request.+ # @return [Spree::ApiKey, nil]attr_reader :current_api_keyend+ # 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 otherwisedef authenticate_api_key!@current_api_key = current_store.api_keys.active.publishable.find_by(token: extract_api_key)@@ -24,8 +31,14 @@ module Spreetrueend+ # 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 otherwisedef 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.idunless @current_api_keyrender_error(@@ -42,6 +55,9 @@ module Spreeprivate+ # Extracts the API key from the request headers or params.+ #+ # @return [String, nil] the API key tokendef extract_api_keyrequest.headers['X-Spree-Api-Key'].presence || params[:api_key]enddiff --git a/spree/core/app/models/spree/api_key.rb b/spree/core/app/models/spree/api_key.rbindex 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 SpreePREFIXES = { 'publishable' => 'pk_', 'secret' => 'sk_' }.freezeTOKEN_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: truebelongs_to :revoked_by, polymorphic: true, optional: truevalidates :name, presence: truevalidates :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: truebefore_validation :generate_token, on: :create@@ -22,26 +30,73 @@ module Spreescope :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) keydef publishable?key_type == 'publishable'end+ # @return [Boolean] whether this is a secret (Admin API) keydef secret?key_type == 'secret'end+ # @return [Boolean] whether this key has not been revokeddef 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 succeededdef revoke!(user = nil)update!(revoked_at: Time.current, revoked_by: user)endprivate+ # 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+ endendendenddiff --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.rbnew file mode 100644index 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+enddiff --git a/spree/core/spec/models/spree/api_key_spec.rb b/spree/core/spec/models/spree/api_key_spec.rbindex 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 doexpect(api_key).not_to be_validend- 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_validexpect(duplicate.errors[:token]).to be_presentend- 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+ endend- 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+ endendend@@ -147,6 +209,36 @@ RSpec.describe Spree::ApiKey, type: :model doendend+ 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' doit 'belongs to store' doexpect(api_key.store).to eq(store)