@spree/docs 0.1.257 → 0.1.259

package/dist/developer/cli/quickstart.md

@@ -195,6 +195,17 @@ spree api-key create --name "Admin" --type secret --scopes read_all     # Admin
 spree api-key revoke <id>                              # Revoke a key
 ```
 
+### `spree encryption init`
+
+Generate [Active Record encryption](../deployment/environment_variables.md#active-record-encryption) keys — Spree encrypts webhook signing secrets, payment gateway customer IDs and OAuth tokens with them. New projects already have keys; use this for projects created before they were generated at setup.
+
+```bash
+spree encryption init            # Add ACTIVE_RECORD_ENCRYPTION_* keys to the project's .env
+spree encryption init --print    # Print a fresh set without writing anything (e.g. for your hosting provider)
+```
+
+It never overwrites keys `.env` already sets, and there is no `--force`: changing the keys makes data encrypted with them unreadable. Afterwards, recreate the containers so they load the new `.env` (`spree update`, or `spree dev` for an ejected project — `spree restart` keeps the old environment), and back the keys up in your secret manager.
+
 ### `spree api`
 
 Call the Admin API with generic `get`/`post`/`patch`/`delete` commands — zero-config inside a project (a read-only key is minted on first use), env vars or profiles for remote stores. See [Admin API from the CLI](admin-api.md) for the full guide.

package/dist/developer/core-concepts/payments.md

@@ -637,7 +637,7 @@ Maps a Spree customer to their provider-specific customer profile. This enables
 | `payment_method_id` | The gateway this customer belongs to | `1` |
 | `customer_id` | The Spree customer | `42` |
 
-A customer has at most one record per payment method, and `profile_id` is encrypted with Active Record Encryption where it is configured.
+A customer has at most one record per payment method, and `profile_id` is encrypted with [Active Record encryption](../deployment/environment_variables.md#active-record-encryption) where it is configured.
 
 > **NOTE:** This one is internal — the API does not expose it. It is listed here because
 >   gateway integrations rely on it; nothing a storefront does will read it.

package/dist/developer/create-spree-app/quickstart.md

@@ -63,7 +63,7 @@ my-store/
 │   ├── seller-dashboard/     # Seller panel, for marketplaces (React)
 │   └── storefront/           # Next.js storefront (unless --no-storefront)
 │       └── .env.local        # API URL + publishable key
-├── .env                      # SECRET_KEY_BASE, SPREE_PORT, SPREE_VERSION_TAG, SPREE_SAMPLE_DATA
+├── .env                      # SECRET_KEY_BASE, encryption keys, SPREE_PORT, SPREE_VERSION_TAG, SPREE_SAMPLE_DATA
 ├── .spree/                   # CLI credentials — gitignored, created on first run
 ├── docker-compose.yml        # Spree backend (prebuilt image) + Postgres + Meilisearch
 ├── docker-compose.dev.yml    # Alternative: build from local server/

package/dist/developer/deployment/aws.md

@@ -49,6 +49,11 @@ services:
     environment:
       DATABASE_URL: postgres://spree:YOUR_PASSWORD@your-db.abc123.eu-west-1.rds.amazonaws.com:5432/spree_production
       SECRET_KEY_BASE: generate-with-openssl-rand-hex-64
+      # Active Record encryption — generate with `spree encryption init --print`
+      # or `bin/rails db:encryption:init`; never change them once data is encrypted
+      ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY: ...
+      ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY: ...
+      ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT: ...
       RAILS_HOST: store.example.com
       # Uploads to S3 (recommended) — see /developer/deployment/assets
       # AWS_REGION: eu-west-1

package/dist/developer/deployment/aws_ecs.md

@@ -222,6 +222,9 @@ Create the following secrets in AWS Secrets Manager:
 |---|---|---|
 | `spree/database-url` | `DATABASE_URL` | PostgreSQL connection URL |
 | `spree/secret-key-base` | `SECRET_KEY_BASE` | Generate with `bin/rails secret` |
+| `spree/ar-encryption-primary-key` | `ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY` | [Active Record encryption](environment_variables.md#active-record-encryption) keys — generate all three with `bin/rails db:encryption:init` (or `spree encryption init --print`). Never change them once data is encrypted |
+| `spree/ar-encryption-deterministic-key` | `ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY` | Generated together with the primary key |
+| `spree/ar-encryption-key-derivation-salt` | `ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT` | Generated together with the primary key |
 
 Optional secrets for email delivery, file storage, and error tracking:
 
@@ -292,6 +295,18 @@ One task definition runs the whole app — the web server also runs background j
         {
           "name": "SECRET_KEY_BASE",
           "valueFrom": "arn:aws:secretsmanager:${AWS_REGION}:${AWS_ACCOUNT_ID}:secret:spree/secret-key-base"
+        },
+        {
+          "name": "ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY",
+          "valueFrom": "arn:aws:secretsmanager:${AWS_REGION}:${AWS_ACCOUNT_ID}:secret:spree/ar-encryption-primary-key"
+        },
+        {
+          "name": "ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY",
+          "valueFrom": "arn:aws:secretsmanager:${AWS_REGION}:${AWS_ACCOUNT_ID}:secret:spree/ar-encryption-deterministic-key"
+        },
+        {
+          "name": "ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT",
+          "valueFrom": "arn:aws:secretsmanager:${AWS_REGION}:${AWS_ACCOUNT_ID}:secret:spree/ar-encryption-key-derivation-salt"
         }
       ],
       "logConfiguration": {
@@ -351,6 +366,18 @@ Switches to [split mode](quickstart.md#web-and-worker): background jobs move int
         {
           "name": "SECRET_KEY_BASE",
           "valueFrom": "arn:aws:secretsmanager:${AWS_REGION}:${AWS_ACCOUNT_ID}:secret:spree/secret-key-base"
+        },
+        {
+          "name": "ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY",
+          "valueFrom": "arn:aws:secretsmanager:${AWS_REGION}:${AWS_ACCOUNT_ID}:secret:spree/ar-encryption-primary-key"
+        },
+        {
+          "name": "ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY",
+          "valueFrom": "arn:aws:secretsmanager:${AWS_REGION}:${AWS_ACCOUNT_ID}:secret:spree/ar-encryption-deterministic-key"
+        },
+        {
+          "name": "ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT",
+          "valueFrom": "arn:aws:secretsmanager:${AWS_REGION}:${AWS_ACCOUNT_ID}:secret:spree/ar-encryption-key-derivation-salt"
         }
       ],
       "logConfiguration": {

package/dist/developer/deployment/docker.md

@@ -54,6 +54,11 @@ services:
     environment:
       DATABASE_URL: postgres://postgres@postgres:5432/spree_production
       SECRET_KEY_BASE: change-me-to-a-real-secret
+      # Active Record encryption — generate with `spree encryption init --print`
+      # or `bin/rails db:encryption:init`; never change them once data is encrypted
+      ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY: change-me
+      ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY: change-me
+      ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT: change-me
       RAILS_FORCE_SSL: "false"
       RAILS_ASSUME_SSL: "false"
       # Public host used in generated URLs (images/attachments in API
@@ -93,6 +98,10 @@ Background jobs run inside the web container by default. When job load deserves
     environment:
       DATABASE_URL: postgres://postgres@postgres:5432/spree_production
       SECRET_KEY_BASE: change-me-to-a-real-secret
+      # the same encryption keys as web
+      ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY: change-me
+      ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY: change-me
+      ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT: change-me
       RAILS_HOST: localhost:3000
     command: bin/jobs
 ```
@@ -103,6 +112,7 @@ Background jobs run inside the web container by default. When job load deserves
 | --- | --- | --- |
 | `DATABASE_URL` | PostgreSQL connection URL | `postgres://user:pass@host:5432/spree` |
 | `SECRET_KEY_BASE` | Secret key for session encryption | Generate with `bin/rails secret` |
+| `ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY`, `ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY`, `ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT` | Keys Spree encrypts secrets at rest with — see [Active Record encryption](environment_variables.md#active-record-encryption). Never change them once data is encrypted | Generate with `spree encryption init --print` or `bin/rails db:encryption:init` |
 | `RAILS_HOST` | Public host used in generated URLs — image/attachment URLs in API responses, email links | `store.example.com` |
 | `SOLID_QUEUE_IN_PUMA` | Run background jobs inside the web container (default `true`); set `false` when running a dedicated worker | `true` |
 

package/dist/developer/deployment/environment_variables.md

@@ -1,6 +1,6 @@
 ---
 title: Environment Variables
-description: Reference for Spree deployment environment variables — database, web server, background jobs, SMTP, file storage, and application settings.
+description: Reference for Spree deployment environment variables — database, secrets and encryption keys, web server, background jobs, SMTP, file storage, and application settings.
 ---
 
 Spree uses environment variables for all deployment configuration. No secrets or credentials are stored in the codebase.
@@ -14,7 +14,58 @@ These two variables are all a production deployment strictly needs:
 | `DATABASE_URL` | Database connection URL — see [Database Configuration](database.md) | `postgres://user:pass@localhost:5432/spree` |
 | `SECRET_KEY_BASE` | Secret used to encrypt sessions and cookies. Generate with `openssl rand -hex 64` | `2fad5c0b79d25e4765d3018d8c740f8c3a665f0e5c...` |
 
-You'll almost always want to set [`RAILS_HOST`](#urls-and-hosts) too — without it, generated URLs point at `localhost`.
+You'll almost always want to set [`RAILS_HOST`](#urls-and-hosts) too — without it, generated URLs point at `localhost`, and the three [Active Record encryption](#active-record-encryption) keys — without them, secrets Spree stores are kept in plain text.
+
+## Active Record encryption
+
+Spree encrypts sensitive values at rest with [Active Record encryption](https://guides.rubyonrails.org/active_record_encryption.html): webhook endpoint signing secrets, payment gateway customer IDs, and the OAuth tokens stored on user identities. It does so only when encryption keys are configured — without them, these values are stored in plain text and a production app logs a warning at boot.
+
+| Variable | Description |
+| --- | --- |
+| `ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY` | Key for (non-deterministic) encrypted attributes |
+| `ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY` | Key for deterministic encrypted attributes — the ones Spree looks records up by, such as webhook signing secrets and gateway customer IDs |
+| `ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT` | Salt for deriving the encryption keys |
+
+Set all three. Each is a random string — generate a set with any of:
+
+
+```bash Spree CLI
+spree encryption init           # writes a set to your project's .env (never overwrites existing keys)
+spree encryption init --print   # prints a fresh set, e.g. for your hosting provider
+```
+
+```bash Without Spree CLI
+bin/rails db:encryption:init
+```
+
+
+- **New projects** — `create-spree-app` generates the keys into `.env`, and the [Render Blueprint](render.md) generates them for production.
+- **Production** — use a separate set of keys from development and store it in your secret manager as a backup.
+- **Rails credentials** — instead of env vars, you can put the values printed by `bin/rails db:encryption:init` under `active_record_encryption` in your encrypted credentials. When both are present, the env vars win.
+
+> **WARNING:** Never change or lose the keys once data is encrypted — records encrypted with them become unreadable. Rails supports [rotating the primary key](https://guides.rubyonrails.org/active_record_encryption.html#rotating-keys) by adding the new key and keeping the old one, but it doesn't support rotating the deterministic key — and webhook endpoint secrets and gateway customer IDs are encrypted deterministically. Keep `ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY` and `ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT` unchanged unless you plan a migration that re-encrypts those records.
+
+### Enabling encryption on an existing installation
+
+Records written before the keys were set are stored in plain text. OAuth tokens on user identities stay readable and are encrypted on their next write. Webhook endpoint secrets and gateway customer IDs are not readable in plain text once encryption is on, so enable encryption with plaintext support first, then encrypt the existing rows:
+
+1. Allow reading and looking up plaintext rows in `config/application.rb`:
+
+   ```ruby
+   config.active_record.encryption.support_unencrypted_data = true
+   config.active_record.encryption.extend_queries = true
+   ```
+
+2. Set the three keys ([see above](#active-record-encryption)) and deploy.
+3. Encrypt the existing rows from a Rails console (`spree console` or `bin/rails console`):
+
+   ```ruby
+   [Spree::WebhookEndpoint, Spree::GatewayCustomer, Spree::UserIdentity].each { |model| model.find_each(&:encrypt) }
+   ```
+
+4. Remove the two settings from step 1 and deploy again.
+
+Apps created from an older `spree-starter` also need `config/application.rb` to read the env vars — see the [5.6 to 6.0 upgrade guide](../upgrades/5.6-to-6.0.md#enable-active-record-encryption).
 
 ## URLs and Hosts
 

package/dist/developer/deployment/render.md

@@ -37,7 +37,7 @@ The `/jobs` dashboard uses HTTP Basic auth: user `jobs`, with a password the Blu
 
 ### Environment Variables
 
-Render sets `DATABASE_URL` and `SECRET_KEY_BASE` automatically from the Blueprint. For additional configuration (SMTP, file storage, Sentry, etc.), see [Environment Variables](environment_variables.md).
+Render sets `DATABASE_URL`, `SECRET_KEY_BASE` and the three [Active Record encryption](environment_variables.md#active-record-encryption) keys automatically from the Blueprint. Copy the encryption keys from the **Environment** tab into your secret manager as a backup — never change them once data is encrypted. For additional configuration (SMTP, file storage, Sentry, etc.), see [Environment Variables](environment_variables.md).
 
 Generated URLs (images and attachments in API responses, email links) automatically use Render's `RENDER_EXTERNAL_HOSTNAME` (`<your-app-name>.onrender.com`). When you attach a custom domain, set [`RAILS_HOST`](environment_variables.md#urls-and-hosts) to it — it takes precedence.
 

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

@@ -141,6 +141,8 @@ end
 
 `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.
 
+> **NOTE:** Any `access_token` and `refresh_token` you pass in `tokens` are stored on the identity and encrypted at rest with Active Record encryption. Configure the encryption keys in production (`bin/rails db:encryption:init`, then store the output in your encrypted credentials). Without them, Spree stores the tokens in plain text.
+
 ## Step 2: Register the Strategy
 
 Add the strategy to a registry in `config/initializers/spree.rb`. **This is the only line that decides which API the provider serves** — `store_authentication_strategies` for customer login, `admin_authentication_strategies` for staff login. Register with both to allow the same provider on either surface. The key you choose here is what clients send as `provider` in the login payload.
@@ -182,7 +184,7 @@ The strategy is instantiated with the surface's user class automatically — `Sp
 
 > **TIP:** Restrict a surface to SSO by removing the built-in email/password strategy after adding yours: `Spree.admin_authentication_strategies.remove(:email)` locks staff to your provider; the store side stays on email/password.
 
-> **WARNING:** `Spree::UserIdentity` validates that `provider` is a registered strategy key. Registration must happen during boot — before the first login attempt.
+> **WARNING:** `Spree::UserIdentity` validates that `provider` is a key registered in the store, admin or seller strategy registry. Registration must happen during boot — before the first login attempt.
 
 ## Step 3: Call the Exchange Endpoint
 

package/dist/developer/security/security_policy.md

@@ -63,6 +63,7 @@ Spree API is built on **Ruby on Rails** which provides strong security defaults
 We recommend:
 
 - Keeping Spree and all dependencies up to date
+- Configuring [Active Record encryption](../deployment/environment_variables.md#active-record-encryption) keys in production — without them, webhook signing secrets, payment gateway customer IDs and OAuth tokens are stored in plain text
 - Following the [Rails Security Guide](https://guides.rubyonrails.org/security.html)
 - Using [bundler-audit](https://github.com/rubysec/bundler-audit) to scan for known vulnerabilities in dependencies
 - Running [brakeman](https://github.com/presidentbeef/brakeman) for static security analysis

package/dist/developer/upgrades/5.6-to-6.0.md

@@ -178,6 +178,41 @@ bundle exec rake spree:upgrade:migrate_country_state_codes
 
 Countries and states are no longer database records in 6.0. Addresses, delivery zone members, market countries, stock locations and stores now name them by ISO code (`country_code`, `state_code`), and this task fills those columns from the old `country_id` / `state_id` references. The old `country_iso` / `state_abbr` names still work on addresses for one release.
 
+## Enable Active Record encryption
+
+Spree encrypts webhook endpoint signing secrets, payment gateway customer IDs and the OAuth tokens on user identities with [Active Record encryption](https://guides.rubyonrails.org/active_record_encryption.html) — but only when encryption keys are configured. Without keys these values are stored in plain text. New 6.0 projects get keys at setup; upgraded applications need to add them.
+
+**1. Make the app read the keys.** Projects created from `spree-starter` read them from the `ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY`, `ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY` and `ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT` env vars, falling back to the `active_record_encryption` entry in Rails credentials. If your `config/application.rb` predates this, add inside the `Application` class:
+
+```ruby config/application.rb
+%i[primary_key deterministic_key key_derivation_salt].each do |key|
+  value = ENV["ACTIVE_RECORD_ENCRYPTION_#{key.upcase}"].presence ||
+    credentials.dig(:active_record_encryption, key).presence
+  config.active_record.encryption[key] = value if value
+end
+```
+
+Setting the keys in `config.active_record.encryption` (rather than only in credentials) matters: Spree checks that configuration when it decides whether to encrypt webhook secrets and gateway customer IDs.
+
+**2. Generate keys for development and production** — a separate set for each environment:
+
+
+```bash Spree CLI (Docker)
+spree encryption init           # adds a set to your project's .env (never overwrites existing keys)
+spree encryption init --print   # prints a set for your production host
+```
+
+```bash Without Spree CLI
+bin/rails db:encryption:init    # prints a set; put it in env vars or encrypted credentials
+```
+
+
+Recreate the containers so they pick up the new `.env` (`spree update`, or `spree dev` for an ejected project — `spree restart` keeps the old environment). Set the keys on your production host **before** deploying, and store them in your secret manager.
+
+> **WARNING:** Never change or lose the keys once data is encrypted — the encrypted records become unreadable.
+
+**3. Encrypt existing rows.** Rows written before the keys were set are plain text. OAuth tokens on user identities stay readable and are encrypted on their next write. Webhook endpoint secrets and gateway customer IDs can't be read in plain text once encryption is on — follow [Enabling encryption on an existing installation](../deployment/environment_variables.md#enabling-encryption-on-an-existing-installation): turn on `support_unencrypted_data` and `extend_queries`, deploy with the keys, run `find_each(&:encrypt)` over `Spree::WebhookEndpoint`, `Spree::GatewayCustomer` and `Spree::UserIdentity`, then turn the two settings off again.
+
 ## The Cart/Order split
 
 The single biggest change. What used to be one `Spree::Order` living through checkout and beyond is now two models:

package/package.json

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