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
Fix: Allowed http://localhost OAuth redirect URIs with an explicit port (#15043)
Damian Legawiececa9057a8ce6
diff --git a/docs/developer/mcp/quick-start.mdx b/docs/developer/mcp/quick-start.mdxindex 4e710cfbfc..4b392aa774 100644--- a/docs/developer/mcp/quick-start.mdx+++ b/docs/developer/mcp/quick-start.mdx@@ -43,9 +43,18 @@ Paste the URL into your MCP client. It sends you to your store, you sign in, and<Tabs><Tab title="Claude Code">+ Register Claude Code under **Settings → OAuth clients** in your Spree+ dashboard with the redirect URI `http://localhost:3118/callback`. Any+ free port other than 80 works, as long as the same port is passed below. Then add the+ server with the client ID that registration shows:+```bash- claude mcp add --transport http spree https://your-store.com/api/v3/admin/mcp+ claude mcp add --transport http --client-id <client-id> --callback-port 3118 \+ spree https://your-store.com/api/v3/admin/mcp```++ The port must be fixed: Claude Code calls back on `localhost`, and your+ store only accepts the exact port that was registered.</Tab><Tab title="Claude Desktop / claude.ai">**Settings → Connectors → Add custom connector**, then paste the URL.diff --git a/spree/api/lib/spree/api/oauth.rb b/spree/api/lib/spree/api/oauth.rbindex aa6106c9fd..318f7dd5d6 100644--- a/spree/api/lib/spree/api/oauth.rb+++ b/spree/api/lib/spree/api/oauth.rb@@ -15,23 +15,11 @@ module Spree# which is why this lives in `spree_api` rather than in any one gem that# happens to need it.module Oauth- # Protected resources, each registered by the surface that owns it as a- # path relative to this application's own origin.- #- # Spree::Api::Oauth.register_resource(:admin, '/api/v3/admin')- #- # A path rather than a full URL because the identifier must equal the- # URL the client was actually pointed at: the origin comes from the- # request where there is one, and from the application's configured- # URL options otherwise. A store's own `url` column is deliberately not- # consulted — it describes the storefront, which is frequently neither- # the host nor the scheme the Admin API answers on.- # Whether a redirect URI points at the machine the client runs on.+ # Whether a redirect URI points at the machine the client runs on, by IP+ # literal (`127.0.0.1`, `[::1]`).## Decided by parsing the host as an address, the same way Doorkeeper- # does when it ignores the port of a loopback redirect — so `localhost`- # is deliberately not loopback here either, and a registration must use- # the IP literal for an ephemeral port to match.+ # does when it ignores the port of a loopback redirect.## @param uri [URI, String]# @return [Boolean]@@ -44,6 +32,36 @@ module Spreefalseend+ # Whether a redirect URI may use plain http: an IP-literal loopback, or+ # `localhost` with an explicit port.+ #+ # Claude Code only ever calls back on `http://localhost:<port>`. The port+ # is required because Doorkeeper ignores it only for IP literals, so a+ # port-less `localhost` registration could never match an authorization.+ #+ # @param uri [URI, String]+ # @return [Boolean]+ def self.local_redirect_uri?(uri)+ uri = URI.parse(uri.to_s) unless uri.respond_to?(:host)+ return true if loopback_uri?(uri)++ uri.host.to_s.casecmp?('localhost') &&+ (1..65_535).cover?(uri.port) && uri.port != uri.default_port+ rescue StandardError+ false+ end++ # Protected resources, each registered by the surface that owns it as a+ # path relative to this application's own origin.+ #+ # Spree::Api::Oauth.register_resource(:admin, '/api/v3/admin')+ #+ # A path rather than a full URL because the identifier must equal the+ # URL the client was actually pointed at: the origin comes from the+ # request where there is one, and from the application's configured+ # URL options otherwise. A store's own `url` column is deliberately not+ # consulted — it describes the storefront, which is frequently neither+ # the host nor the scheme the Admin API answers on.mattr_accessor :resources, default: {}class << self@@ -191,9 +209,9 @@ module Spree# A redirect URI is where authorization codes are delivered, so a# plain-http one hands them to anyone on the path — except a- # loopback one, which never leaves the machine. A terminal client- # listens on an ephemeral local port and has no certificate for- # it, so RFC 8252 §7.3 makes that the recommended shape, and+ # loopback or `localhost` one, which never leaves the machine. A+ # terminal client listens on a local port and has no certificate+ # for it, so RFC 8252 §7.3 makes that the recommended shape, and# refusing it would lock out Claude Code and Codex entirely.## Passed as a callable so the exemption is per URI rather than@@ -201,7 +219,7 @@ module Spreeforce_ssl_in_redirect_uri do |uri|next false if Rails.env.development?- !Spree::Api::Oauth.loopback_uri?(uri)+ !Spree::Api::Oauth.local_redirect_uri?(uri)end# RFC 8707. Registering the validator is what binds an audiencediff --git a/spree/api/spec/lib/spree/api/oauth_redirect_uri_spec.rb b/spree/api/spec/lib/spree/api/oauth_redirect_uri_spec.rbindex 22313699f3..d5017a55cc 100644--- a/spree/api/spec/lib/spree/api/oauth_redirect_uri_spec.rb+++ b/spree/api/spec/lib/spree/api/oauth_redirect_uri_spec.rb@@ -10,6 +10,15 @@ RSpec.describe 'OAuth redirect URIs' doconfidential: false, redirect_uri: redirect_uri)end+ def authorizable?(redirect_uri)+ ::Doorkeeper::OAuth::PreAuthorization.new(+ ::Doorkeeper.config,+ { client_id: application.uid, response_type: 'code', redirect_uri: redirect_uri,+ scope: 'read_products', code_challenge: 'c' * 43, code_challenge_method: 'S256' },+ create(:admin_user)+ ).authorizable?+ end+# A plain-http callback hands codes to anyone on the path — except a# loopback one, which never leaves the machine. A terminal client listens on# a local port and has no certificate for it.@@ -32,12 +41,26 @@ RSpec.describe 'OAuth redirect URIs' doexpect(build_with('http://example.test/callback')).not_to be_validend- # Doorkeeper decides loopback by parsing the host as an address, so a name- # is not loopback — and a registration using one would have every- # ephemeral port refused at authorization anyway.- it 'refuses localhost by name' do+ # Claude Code calls back on `http://localhost:<port>` and never on the IP+ # literal, so it can only be registered by name.+ it 'accepts localhost by name with an explicit port' do+ expect(build_with('http://localhost:3118/callback')).to be_valid+ end++ # Doorkeeper ignores the port only for IP literals, so a port-less+ # `localhost` registration could never be authorized.+ it 'refuses localhost by name without a port' doexpect(build_with('http://localhost/callback')).not_to be_validend++ it 'refuses localhost on a port no client can listen on' do+ expect(build_with('http://localhost:0/callback')).not_to be_valid+ expect(build_with('http://localhost:65536/callback')).not_to be_valid+ end++ it 'refuses a host that only starts with localhost' do+ expect(build_with('http://localhost.example.test:3118/callback')).not_to be_valid+ endend# RFC 8252 §7.3: a terminal client picks its port at run time, so the@@ -50,15 +73,6 @@ RSpec.describe 'OAuth redirect URIs' do)end- def authorizable?(redirect_uri)- ::Doorkeeper::OAuth::PreAuthorization.new(- ::Doorkeeper.config,- { client_id: application.uid, response_type: 'code', redirect_uri: redirect_uri,- scope: 'read_products', code_challenge: 'c' * 43, code_challenge_method: 'S256' },- create(:admin_user)- ).authorizable?- end-it 'is authorized whatever port it chose' doexpect(authorizable?('http://127.0.0.1:49821/callback')).to be(true)expect(authorizable?('http://127.0.0.1:60007/callback')).to be(true)@@ -68,4 +82,20 @@ RSpec.describe 'OAuth redirect URIs' doexpect(authorizable?('https://evil.test/callback')).to be(false)endend++ describe 'a terminal client calling back on localhost' do+ let(:application) do+ store.oauth_applications.create!(+ name: 'Claude Code', confidential: false, redirect_uri: 'http://localhost:3118/callback'+ )+ end++ it 'is authorized on the registered port' do+ expect(authorizable?('http://localhost:3118/callback')).to be(true)+ end++ it 'is refused on any other port' do+ expect(authorizable?('http://localhost:49821/callback')).to be(false)+ end+ endend