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.

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.mdx
index 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.rb
index 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 Spree
false
end
+ # 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 Spree
force_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 audience
diff --git a/spree/api/spec/lib/spree/api/oauth_redirect_uri_spec.rb b/spree/api/spec/lib/spree/api/oauth_redirect_uri_spec.rb
index 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' do
confidential: 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' do
expect(build_with('http://example.test/callback')).not_to be_valid
end
- # 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' do
expect(build_with('http://localhost/callback')).not_to be_valid
end
+
+ 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
+ end
end
# 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' do
expect(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' do
expect(authorizable?('https://evil.test/callback')).to be(false)
end
end
+
+ 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
+ end
end