@spree/docs 0.1.67 → 0.1.69

package/dist/developer/admin/authentication.md

@@ -21,7 +21,7 @@ This will tell Spree to use your `AdminUser` model for the admin panel. You will
 include Spree::UserMethods
 ```
 
-In your `config/initializers/routes.rb` file, you will need define devise routes for the 2nd model:
+In your `config/initializers/routes.rb` file, you will need to define devise routes for the 2nd model:
 
 ```ruby
 Spree::Core::Engine.routes.prepend_routes do

package/dist/developer/contributing/creating-an-extension.md

@@ -70,7 +70,7 @@ Once you have added the gem, it's time to bundle:
 bundle install
 ```
 
-Finally, let's run the `spree_simple_sales` install generator to copy over the migration we just created answer **yes** if prompted to run migrations:
+Finally, let's run the `spree_simple_sales` install generator to copy over the migration we just created. Answer **yes** if prompted to run migrations:
 
 ```bash
 # context: Your Spree store's app root (i.e. Rails.root); not the extension's root path.

package/dist/developer/customization/authentication.md

@@ -24,7 +24,7 @@ Now, run the generator to set up Spree integration with Devise:
 bin/rails g spree:authentication:devise
 ```
 
-This will create the a new file in `lib/spree/authentication_helpers.rb` that serves as a bridge between Spree and your existing authentication system routes. You can then use this file to customize the routes to your liking. It should automatically pick up standard Devise routes.
+This will create a new file in `lib/spree/authentication_helpers.rb` that serves as a bridge between Spree and your existing authentication system routes. You can then use this file to customize the routes to your liking. It should automatically pick up standard Devise routes.
 
 Secondly, this generator will add necessary modules to your `User` model.
 
@@ -68,7 +68,7 @@ Now, run the generator to set up Spree integration with your custom authenticati
 bin/rails g spree:authentication:custom
 ```
 
-This will create the a new file in `lib/spree/authentication_helpers.rb` that serves as a bridge between Spree and your existing authentication system routes. You will need to customize this file to fit your needs.
+This will create a new file in `lib/spree/authentication_helpers.rb` that serves as a bridge between Spree and your existing authentication system routes. You will need to customize this file to fit your needs.
 
 Secondly, this generator will add necessary modules to your `User` model.
 

package/dist/developer/customization/checkout.md

@@ -10,7 +10,7 @@ The Spree checkout process has been designed for maximum flexibility. It's been
 
 ## The Checkout Flow DSL
 
-Spree comes with a new checkout DSL that allows you succinctly define the different steps of your checkout. This new DSL allows you to customize _just_ the checkout flow, while maintaining the unrelated admin states, such as "canceled" and "resumed", that an order can transition to. Ultimately, it provides a shorter syntax compared with overriding the entire state machine for the `Spree::Order` class.
+Spree comes with a new checkout DSL that allows you to succinctly define the different steps of your checkout. This new DSL allows you to customize _just_ the checkout flow, while maintaining the unrelated admin states, such as "canceled" and "resumed", that an order can transition to. Ultimately, it provides a shorter syntax compared with overriding the entire state machine for the `Spree::Order` class.
 
 The default checkout flow for Spree is defined like this, adequately demonstrating the abilities of this new system:
 

package/dist/developer/customization/v4/checkout.md

@@ -10,7 +10,7 @@ The Spree checkout process has been designed for maximum flexibility. It's been
 
 ## The Checkout Flow DSL
 
-Spree comes with a new checkout DSL that allows you succinctly define the different steps of your checkout. This new DSL allows you to customize _just_ the checkout flow, while maintaining the unrelated admin states, such as "canceled" and "resumed", that an order can transition to. Ultimately, it provides a shorter syntax compared with overriding the entire state machine for the `Spree::Order` class.
+Spree comes with a new checkout DSL that allows you to succinctly define the different steps of your checkout. This new DSL allows you to customize _just_ the checkout flow, while maintaining the unrelated admin states, such as "canceled" and "resumed", that an order can transition to. Ultimately, it provides a shorter syntax compared with overriding the entire state machine for the `Spree::Order` class.
 
 The default checkout flow for Spree is defined like this, adequately demonstrating the abilities of this new system:
 

package/dist/developer/how-to/custom-api-authentication.md

@@ -0,0 +1,301 @@
+---
+title: Integrate a Third-Party Identity Provider
+description: Step-by-step guide to plugging a custom identity provider (Auth0, Okta, Firebase, Cognito, or any JWT issuer) into the Spree Store API.
+---
+
+import { Since } from '/snippets/since.mdx';
+
+
+## Overview
+
+Spree's Store API ships with a pluggable authentication system. You register a **strategy class** for a named provider, and the existing login endpoints will dispatch to it — no controller patching, no route overrides, no fork.
+
+By the end of this guide you'll have:
+
+- A custom strategy that verifies a third-party JWT against a JWKS endpoint
+- A user account auto-provisioned on first login, reused on subsequent logins
+- A standard **Spree-issued JWT + refresh token** returned to the client
+- All Store API endpoints (cart, checkout, account) protected by Spree's own JWT — the third-party token is only used at the exchange step
+
+> **INFO:** The same pattern works for Admin API integrations via `admin_authentication_strategies`. Examples in this guide target the Store API; substitute `Spree.admin_user_class` and the admin endpoints where noted.
+
+## Architecture
+
+```
+Client → POST /api/v3/store/auth/login
+            { provider: "my_idp", token: "<third-party JWT>" }
+              │
+              ▼
+   AuthController looks up the strategy by `provider` key
+              │
+              ▼
+   YourStrategy#authenticate
+     • verifies the JWT against the IdP's JWKS
+     • finds or creates a Spree::UserIdentity → Spree user
+     • returns success(user) or failure(message)
+              │
+              ▼
+   Spree issues its own JWT (HS256, iss=spree, aud=store_api)
+   + a rotatable RefreshToken
+              │
+              ▼
+Client → subsequent calls with `Authorization: Bearer <Spree JWT>`
+```
+
+The third-party JWT proves identity **once, at login**. After that, the client uses the Spree JWT for everything, and `/auth/refresh` rotates it via Spree's own refresh-token mechanism. Your existing CanCanCan rules, `current_user`, and serializer params just work.
+
+## Step 1: Create the Strategy Class
+
+Subclass `Spree::Authentication::Strategies::BaseStrategy` and implement two methods: `provider` (a string identifier) and `authenticate` (returns a `Spree::ServiceModule::Result`).
+
+```ruby app/models/my_app/auth/external_jwt_strategy.rb
+module MyApp
+  module Auth
+    class ExternalJwtStrategy < Spree::Authentication::Strategies::BaseStrategy
+      PROVIDER = 'external_idp'.freeze
+
+      def provider
+        PROVIDER
+      end
+
+      def authenticate
+        token = params[:token] || extract_bearer
+        return failure(I18n.t('spree.api.unauthorized')) if token.blank?
+
+        payload = verify_with_jwks(token)
+
+        user = find_or_create_user_from_oauth(
+          provider: PROVIDER,
+          uid:      payload.fetch('sub'),
+          info:     {
+            email:      payload['email'],
+            first_name: payload['given_name'],
+            last_name:  payload['family_name']
+          }
+        )
+
+        success(user)
+      rescue JWT::DecodeError, JWT::ExpiredSignature, JWT::InvalidIssuerError, JWT::InvalidAudError, KeyError => e
+        failure(e.message)
+      end
+
+      private
+
+      def verify_with_jwks(token)
+        jwks_loader = ->(opts) { jwks(force: opts[:invalidate]) }
+
+        JWT.decode(
+          token, nil, true,
+          algorithms: ['RS256'],
+          iss:        ENV.fetch('EXTERNAL_IDP_ISSUER'),
+          aud:        ENV.fetch('EXTERNAL_IDP_AUDIENCE'),
+          verify_iss: true,
+          verify_aud: true,
+          jwks:       jwks_loader
+        ).first
+      end
+
+      def jwks(force: false)
+        Rails.cache.fetch('external_idp:jwks', expires_in: 1.hour, force: force) do
+          uri = URI(ENV.fetch('EXTERNAL_IDP_JWKS_URL'))
+          JSON.parse(Net::HTTP.get(uri))
+        end
+      end
+
+      def extract_bearer
+        header = request_env['HTTP_AUTHORIZATION'].to_s
+        header.start_with?('Bearer ') ? header.split(' ', 2).last : nil
+      end
+    end
+  end
+end
+```
+
+### What the base class gives you
+
+`Spree::Authentication::Strategies::BaseStrategy` (in `spree_core`) exposes a few helpers so your subclass stays small:
+
+| Helper | Purpose |
+|---|---|
+| `success(user)` | Wrap a user in a successful `ServiceModule::Result` |
+| `failure(message)` | Wrap an error message in a failed result |
+| `find_user_by_email(email)` | Lookup against `Spree.user_class` |
+| `find_or_create_user_from_oauth(provider:, uid:, info:, tokens: {})` | Calls `Spree::UserIdentity.find_or_create_from_oauth` with the right `user_class` |
+| `params`, `request_env`, `user_class` | Reader access to the controller-supplied inputs |
+
+`find_or_create_user_from_oauth` returns the **user**, not the identity. It creates the `Spree::UserIdentity` row on first login (mapping `provider + uid → user`) and reuses it on subsequent logins — so repeat sign-ins land on the same Spree customer.
+
+## Step 2: Register the Strategy
+
+Add the strategy to `Spree.store_authentication_strategies` in an initializer. The key you choose here is what clients will send as `provider` in the login payload.
+
+```ruby config/initializers/spree.rb
+Rails.application.config.after_initialize do
+  Spree.store_authentication_strategies.add(:external_idp, MyApp::Auth::ExternalJwtStrategy)
+end
+```
+
+`Spree.store_authentication_strategies` is a `Spree::Authentication::StrategyRegistry`. The full API:
+
+| Method | Purpose |
+|---|---|
+| `add(key, strategy_class)` | Register a strategy. Overwrites any existing entry under the same key — that's how you swap the built-in `:email` strategy. |
+| `remove(key)` | Unregister a strategy. Idempotent (returns `nil` if the key was never registered). |
+| `[key]` | Look up a registered class. |
+| `key?(key)`, `keys`, `values`, `each`, `to_h` | Standard introspection. |
+
+> **WARNING:** `Spree::UserIdentity` validates that `provider` is a registered strategy key. Registration must happen during boot — before the first login attempt.
+
+For an admin-side equivalent, register under `Spree.admin_authentication_strategies` instead and instantiate your strategy against `Spree.admin_user_class`:
+
+```ruby
+Spree.admin_authentication_strategies.add(:okta, MyApp::Auth::OktaStrategy)
+```
+
+## Step 3: Call the Exchange Endpoint
+
+`POST /api/v3/store/auth/login` is the single dispatcher. The `provider` field in the body selects the strategy — omit it for built-in email/password, set it to your registered key for everything else. The remaining body fields are whatever your strategy reads from `params`.
+
+```http
+POST /api/v3/store/auth/login
+X-Spree-API-Key: pk_your_publishable_key
+Content-Type: application/json
+
+{
+  "provider": "external_idp",
+  "token":    "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIs..."
+}
+```
+
+The response is the standard Spree auth payload:
+
+```json
+{
+  "token":         "<Spree HS256 JWT, aud=store_api>",
+  "refresh_token": "rt_xxxxxxxxxxxx",
+  "user":          { "id": "user_...", "email": "...", "first_name": "...", "...": "..." }
+}
+```
+
+From here, the client sends `Authorization: Bearer <Spree JWT>` on every subsequent Store API call. When the JWT expires (default: 1 hour), the client hits `POST /api/v3/store/auth/refresh` with the refresh token to rotate both.
+
+From `@spree/sdk` the same call looks like:
+
+```ts
+import { createClient } from '@spree/sdk'
+
+const client = createClient({ baseUrl: 'https://your-store.com', publishableKey: '<pk>' })
+
+const auth = await client.auth.login({
+  provider: 'external_idp',
+  token:    thirdPartyJwt,
+})
+```
+
+`LoginCredentials` is a discriminated union — pass `{ email, password }` for the built-in strategy, or `{ provider, ...customFields }` for any strategy you registered.
+
+## Account Linking
+
+The naive flow above will create a brand new Spree user the first time a given `(provider, uid)` is seen — even if a user with the same email already exists from a password signup. If you want **same-email-means-same-customer**, look up by email first and attach an identity to the existing user:
+
+```ruby
+def authenticate
+  payload = verify_with_jwks(params[:token])
+  email   = payload.fetch('email')
+
+  user = find_user_by_email(email)
+
+  if user
+    user.identities.find_or_create_by!(provider: PROVIDER, uid: payload['sub']) do |identity|
+      identity.info = { email: email, name: payload['name'] }
+    end
+  else
+    user = find_or_create_user_from_oauth(
+      provider: PROVIDER,
+      uid:      payload['sub'],
+      info:     { email: email, first_name: payload['given_name'], last_name: payload['family_name'] }
+    )
+  end
+
+  success(user)
+end
+```
+
+> **WARNING:** **Only link by email if your IdP guarantees `email_verified`.** Silent linking against an unverified email is a known account-takeover vector: an attacker registers `victim@example.com` at the IdP without proving ownership, then logs into Spree as the real victim. Check the `email_verified` claim (or equivalent) before linking, and reject otherwise.
+
+## Logout
+
+```http
+POST /api/v3/store/auth/logout
+Content-Type: application/json
+
+{ "refresh_token": "rt_xxxxxxxxxxxx" }
+```
+
+This revokes the Spree refresh token. The Spree JWT itself remains valid until it expires naturally (short-lived by design — default 1 hour). Spree does **not** call the IdP's revocation endpoint; if you need single sign-out, do that from the client.
+
+## Security Notes
+
+A few things worth getting right:
+
+- **Don't try to pass the third-party JWT through to protected endpoints.** Spree's `JwtAuthentication` concern verifies `iss: 'spree'` and `aud: 'store_api'` with HS256 against the Spree secret — a foreign RS256 token will never validate, and you don't want it to. The exchange-at-login model is the right one.
+- **JWKS caching and rotation.** Cache the JWKS (the example uses a 1-hour TTL) but make sure your loader honors the `invalidate: true` option so that an unrecognized `kid` triggers a refetch. Otherwise key rotation at the IdP locks users out for up to the TTL.
+- **Validate `iss` and `aud` claims.** Always. The example passes `verify_iss: true, verify_aud: true` to `JWT.decode` — don't drop those.
+- **Algorithm pinning.** Hard-code `algorithms: ['RS256']` (or whatever your IdP uses). Never let the token's own `alg` header decide — the classic `alg: none` and HS-as-RS confusion attacks both exploit lax algorithm selection.
+- **Rate limiting.** `POST /auth/login` is rate-limited per IP via `Spree::Api::Config[:rate_limit_login]`. Tune it in your app config if needed — the same limit applies to email/password and provider-dispatched logins.
+
+## Testing
+
+A strategy is a plain Ruby class — test it in isolation without booting a controller:
+
+```ruby spec/models/my_app/auth/external_jwt_strategy_spec.rb
+require 'rails_helper'
+
+RSpec.describe MyApp::Auth::ExternalJwtStrategy do
+  let(:rsa_private) { OpenSSL::PKey::RSA.generate(2048) }
+  let(:jwks)        { { keys: [JWT::JWK.new(rsa_private).export] } }
+
+  let(:token) do
+    JWT.encode(
+      { sub: 'idp-user-123', email: 'alice@example.com', iss: 'https://idp.example', aud: 'spree' },
+      rsa_private, 'RS256'
+    )
+  end
+
+  before do
+    stub_request(:get, ENV['EXTERNAL_IDP_JWKS_URL']).to_return(body: jwks.to_json)
+  end
+
+  subject(:result) do
+    described_class.new(
+      params:      { provider: 'external_idp', token: token },
+      request_env: {}
+    ).authenticate
+  end
+
+  it 'provisions a Spree user on first login' do
+    expect { result }.to change(Spree.user_class, :count).by(1)
+    expect(result).to be_success
+    expect(result.value.email).to eq('alice@example.com')
+  end
+
+  it 'reuses the user on subsequent logins' do
+    described_class.new(params: { token: token }, request_env: {}).authenticate
+    expect { result }.not_to change(Spree.user_class, :count)
+  end
+
+  it 'fails on an expired token' do
+    expired = JWT.encode({ sub: 'x', exp: 1.hour.ago.to_i, iss: 'https://idp.example', aud: 'spree' }, rsa_private, 'RS256')
+    result  = described_class.new(params: { token: expired }, request_env: {}).authenticate
+    expect(result).not_to be_success
+  end
+end
+```
+
+## Reference
+
+- `Spree::Authentication::Strategies::BaseStrategy` — `spree/core/app/models/spree/authentication/strategies/base_strategy.rb`
+- `Spree::UserIdentity` — `spree/core/app/models/spree/user_identity.rb`
+- `Spree::Api::V3::Store::AuthController` — `spree/api/app/controllers/spree/api/v3/store/auth_controller.rb`
+- `Spree::Api::V3::JwtAuthentication` — `spree/api/app/controllers/concerns/spree/api/v3/jwt_authentication.rb`
+- See also: [Authentication](../customization/authentication.md) for `Spree.user_class` integration.

package/dist/developer/upgrades/4.1-to-4.2.md

@@ -39,7 +39,7 @@ If you used that gem in the past you need to remove it. Multi-Currency is now in
 
 All international configuration is now kept on the `Store` model in the database rather than in initializer files.
 
-If you used `spree_i18n` gem before please remove any `SpreeI18n::Config`references from your `config/initializers/spree.rb` file.
+If you used `spree_i18n` gem before please remove any `SpreeI18n::Config` references from your `config/initializers/spree.rb` file.
 
 ## Optional Add `deface` gem
 

package/dist/developer/upgrades/5.2-to-5.3.md

@@ -71,9 +71,9 @@ This rake task will enqueue background jobs to populate the product metrics for
 
 ### Replace `auto_strip_attributes` gem usage
 
-`auto_strip_attributes` gem [was removed from Spree](https://github.com/spree/spree/pull/13462) due to bugs and conflicts with translations feature. Also it's not required anymore as built-in Rails `normalizes` provides the same feature without an additional depepdency. 
+`auto_strip_attributes` gem [was removed from Spree](https://github.com/spree/spree/pull/13462) due to bugs and conflicts with translations feature. Also it's not required anymore as built-in Rails `normalizes` provides the same feature without an additional dependency.
 
-If you used `auto_stripe_attributes` in your application, you will need to change it to `normalizez`, eg.
+If you used `auto_strip_attributes` in your application, you will need to change it to `normalizes`, eg.
 
 Replace
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spree/docs",
-  "version": "0.1.67",
+  "version": "0.1.69",
   "description": "Spree Commerce developer documentation for AI agents and local reference",
   "type": "module",
   "license": "CC-BY-4.0",