Agent Skill · Spree Commerce

spree-security

Use when the user is hardening a Spree app, responding to a security finding, reviewing a PR for security issues, setting up secrets management, configuring CSP/CORS, or asking about Spree-specific security (CanCanCan scopes, encrypted preferences, webhook HMAC, PCI scope). Covers both standard Rails security practices (CSRF, mass assignment, SQL injection, secrets in repo) AND the Spree-specific pieces (publishable vs secret keys, scope enforcement, SSRF on webhooks, CanCanCan abilities). Common phrasings include "Spree security", "CSP", "CORS", "secret key", "leaked key", "SQL injection", "Strong Params", "CanCanCan", "PCI", "webhook signature", "SSRF".

View SKILL.md on GitHub → Source repository Provider profile
Provider: Spree Commerce Path in repo: skills/spree-security/SKILL.md

Skill body

Spree Security

Spree inherits Rails’ security model and adds an e-commerce attack surface (payment data, customer PII, admin credentials, webhook endpoints). This skill covers both.

The threat model in three sentences

  1. The storefront is internet-facing — every visitor can hit it. Threats: XSS via product content, IDOR on orders, abuse of cart endpoints.
  2. The admin is staff-only but credentials get phished — assume someone is going to log in as a regular admin sometimes. Threats: privilege escalation, broad data exfiltration, malicious extension upload.
  3. The payments path touches money and PCI. Threats: card data leaking into logs/DB, gateway response tampering, refund abuse.

Everything below maps to one of these.

Standard Rails security (don’t skip these)

Secrets — not in the repo

Production credentials live in config/credentials.yml.enc (Rails encrypted credentials) or environment variables. Never check raw secrets into git.

# Read credentials
EDITOR="code --wait" bin/rails credentials:edit --environment production

# Look up
Rails.application.credentials.stripe[:secret_key]

If a secret leaks into a commit (even on a private repo): rotate immediately, then rewrite history (git filter-repo, bfg). Rotation order:

  1. Rotate the key in the provider (Stripe, AWS, etc.).
  2. Update credentials/env.
  3. Deploy.
  4. Then clean history. The order matters — clean history first and the leaked key keeps working until rotation.

Spree’s spree/agent-skills plugin (installed via /plugin install spree@spree in Claude Code) ships a PostToolUse hook that warns when Claude appears to be writing a known-shape secret (Stripe live keys, AWS keys, GitHub PATs, OpenAI/Anthropic keys, plaintext sensitive env names). It’s a tripwire, not a substitute for review.

Strong Parameters

Always whitelist params in controllers; never params.permit! or splat user input into mass-assignment:

# ✅
def permitted_params
  params.permit(:name, :description, :slug, metadata: {})
end

# ❌ — accepts anything, including admin_id / is_admin / etc.
Spree::Product.create!(params[:product])

Spree v3 controllers use flat params.permit(...) — no nested wrapping. See spree-api-v3 and spree-resource for the convention.

SQL injection

Use parameterized queries:

# ✅
Spree::Product.where('price > ?', user_value)
Spree::Product.where(price: user_value)

# ❌ — string interpolation
Spree::Product.where("price > #{user_value}")

Ransack is safe by default — but only filters on allowlisted attributes. Declare per model:

self.whitelisted_ransackable_attributes = %w[name slug created_at price]
self.whitelisted_ransackable_associations = %w[variants categories]
self.whitelisted_ransackable_scopes = %w[available in_stock]

Filtering on an un-allowlisted attribute is silently ignored — Ransack’s default ignore_unknown_conditions: true drops the unknown condition (Spree’s v3 controllers call ransack, not ransack!), so the user can’t exfiltrate password_digest via q[password_digest_eq]=.... But there’s no error signal either: the response is 200 and that filter simply doesn’t apply, while any valid conditions in the same query still do.

Mass assignment

Same answer as Strong Parameters above — params.permit is the mass-assignment defense; nothing extra is needed on the model.

Do not reach for attr_readonly here: it blocks all writes after creation, not just mass assignment. With Rails 7.1+ defaults, assigning a readonly attribute on a persisted record raises ActiveRecord::ReadonlyAttributeError (on older defaults the write is silently dropped). Putting it on encrypted_password breaks Devise password changes and password resets for every existing user. Reserve attr_readonly for genuinely immutable columns:

class Spree::Order < Spree.base_class
  attr_readonly :number  # generated once, never changes
end

CSRF

Rails handles CSRF for browser sessions automatically (protect_from_forgery with: :exception). API controllers skip CSRF (token auth replaces it). Don’t disable CSRF on form-rendering controllers — that’s how XSS becomes RCE-via-admin.

CSP (Content Security Policy)

Lock down what scripts/styles/images can load:

# config/initializers/content_security_policy.rb
Rails.application.config.content_security_policy do |policy|
  policy.default_src :self
  policy.font_src    :self, :https, :data
  policy.img_src     :self, :https, :data
  policy.script_src  :self, 'https://js.stripe.com'
  policy.style_src   :self, :unsafe_inline   # the Rails admin's inline styles need this; relax over time
  policy.connect_src :self, 'https://api.stripe.com'
end

The storefront should have a stricter policy than the admin. If your storefront uses a separate domain (Next.js consuming the Store API), set CSP on that app, not on the Rails app.

XSS

Rails auto-escapes ERB output. Where you raw-render user content (rich text descriptions, product copy from CSV import), sanitize:

ActionController::Base.helpers.sanitize(product.description, tags: %w[p br strong em a ul li], attributes: %w[href])

Sanitize before storing OR before rendering, but pick one and be consistent.

CORS

Spree also ships an admin-manageable CORS allowlist for the Admin API — per-store Spree::AllowedOrigin records (validated to be origin-only http(s) URLs), managed in the dashboard under Settings → Allowed origins or via the Admin API (/api/v3/admin/allowed_origins). The spree-starter app’s config/initializers/cors.rb consults it dynamically (cached, exact-match in production) for /api/v3/admin/* with credentials: true — so admin/dashboard origins belong in that allowlist, not in hand-written allow blocks. For your storefront origin on /api/v3/store/*, add a static allow block as shown below.

If your storefront is a separate origin (typical for Next.js):

# config/initializers/cors.rb
Rails.application.config.middleware.insert_before 0, Rack::Cors do
  allow do
    origins 'https://my-storefront.com', /https:\/\/.*\.my-storefront\.com/
    resource '/api/v3/store/*',
             headers: :any,
             methods: %i[get post put patch delete options],
             expose: %w[x-spree-api-version]
  end
end

Never origins '*' in production for paths that accept credentials. Allowlist explicit storefront origins.

Spree-specific security

Publishable key vs secret key

pk_*  — Publishable key.  Safe to ship in client-side code.  Identifies store, permits public Store API endpoints only.
sk_*  — Secret key.       Server-to-server only. Never bundle into mobile apps or browser JS.

A leaked pk_ is annoying but not catastrophic (rate limit, rotate). A leaked sk_ is a breach — rotate immediately and audit Spree::WebhookDelivery/admin audit logs for unauthorized activity.

Scopes on secret keys

When creating a secret key for an integration (Settings → API keys → Create secret key), grant only the scopes the integration needs. Don’t hand out write_all to every app.

Need to sync orders out? → read_orders
Need to update inventory? → write_stock
Need to create refunds? → write_refunds

If the integration is later compromised, the blast radius is limited to what its scopes permit. The full scope list is in the spree-api-v3 skill.

CanCanCan abilities (admin JWT auth)

Admin users authenticate via JWT and authorize via Spree::Ability, which builds permissions from Permission Sets assigned to the user’s roles. Customize by defining a permission set and assigning it to a role:

# app/models/my_app/permission_sets/wholesale_orders.rb
module MyApp
  module PermissionSets
    class WholesaleOrders < Spree::PermissionSets::Base
      def activate!
        # Wholesale managers can read+update wholesale orders but never destroy
        can [:read, :update], Spree::Order, channel: { code: 'wholesale' }
        cannot :destroy, Spree::Order
      end
    end
  end
end

# config/initializers/spree.rb
Rails.application.config.after_initialize do
  Spree.permissions.assign(:wholesale_manager, [
    Spree::PermissionSets::DashboardDisplay,
    MyApp::PermissionSets::WholesaleOrders
  ])
end

(The role itself must exist: Spree::Role.find_or_create_by(name: 'wholesale_manager').)

Defaults are restrictive — users with no roles get only Spree::PermissionSets::DefaultCustomer. Build up explicit grants per role by composing built-in sets (OrderManagement, ProductDisplay, StockManagement, …) with custom ones; don’t hand every role SuperUser.

Payment method preferences

Payment methods (Stripe, Adyen, PayPal, etc.) store their gateway credentials as Spree preferences on the Spree::PaymentMethod record. These end up in spree_payment_methods.preferences as a serialized column.

Two precautions:

If a gateway secret leaks (committed to git, exposed in a log, copied to a chat), rotate at the provider first (Stripe dashboard, Adyen back office), then update the admin preference, then audit recent transactions.

Webhook signature verification (HMAC)

Outbound webhooks are signed with HMAC-SHA256. Receivers MUST verify — see the spree-events-webhooks skill for the exact algorithm + timing-safe comparison + replay rejection. Spree won’t tell you if your receiver is unverified; that’s the receiver’s responsibility.

Webhook SSRF protection

Inbound URL validation: in production, webhook endpoint URLs are checked against private IP ranges (RFC 1918, loopback, link-local) via ssrf_filter. Admin can’t (easily) make Spree POST to http://internal-erp.localhost:8080 from outside the trusted network.

In development this is disabled so localhost webhooks work. Never run development settings in production; this gap is a real SSRF in deployed apps if you copy Rails.env.development? checks blindly.

PCI DSS scope

Spree never stores raw PANs. Payment data flows through tokenization at the gateway:

PCI scope reduction relies on this. Don’t add fields to spree_credit_cards that hold raw card data. If you find yourself wanting to, it’s a sign you’re building the wrong integration pattern — gateway tokenization is the right answer.

If a regulator asks for your PCI SAQ:

Customer-data isolation

Multi-store stores share a database. Always scope queries through current_store:

# ✅
@orders = current_store.orders.where(user: current_user)

# ❌ — leaks orders from other stores
@orders = Spree::Order.where(user: current_user)

The Store API does this automatically via the Spree::Api::V3::Store::ResourceController base class. Custom controllers must replicate the pattern.

IDOR (Insecure Direct Object Reference)

Customer A trying to load /api/v3/store/orders/or_<customerB_order>. The Store API’s OrdersController#scope restricts to the current user’s orders (or the guest order token), so the lookup returns 404 — but if you override scope/find_resource or write a custom controller, you must replicate that scoping.

Prefixed IDs don’t help here — they’re discoverable (sequential PKs under the hood). Always authorize, never rely on ID opacity.

Rate limiting

Spree’s v3 API ships application-level rate limiting out of the box, built on Rails’ rate_limit and backed by Rails.cache:

Exceeding a limit returns 429 with error code rate_limit_exceeded and Retry-After / X-RateLimit-* headers. All limits are tunable via Spree::Api::Config preferences: rate_limit_per_key, rate_limit_window, rate_limit_login, rate_limit_register, rate_limit_refresh, rate_limit_password_reset. One operational caveat: counters live in Rails.cache, so multi-process deployments need a shared cache store (Redis/Memcached) — with an in-process store each worker counts independently.

Still layer defense in depth on top:

Tune the numbers to your traffic shape — the defaults cap a leaked publishable key at 300 req/min, but a scraper rotating IPs without a key still warrants the CDN layer.

Dependency hygiene

bundle audit                # CVEs in Ruby gems
npm audit / pnpm audit      # CVEs in JS deps
brakeman                    # Rails static analysis

Run these in CI. The spree/agent-skills plugin doesn’t ship a CI workflow — you wire these into your own.

Admin upload safety

Admins can upload images and CSVs (imports). Risks:

Sensitive logs

Filter sensitive params at the Rails level:

# config/initializers/filter_parameter_logging.rb
Rails.application.config.filter_parameters += %i[
  password password_confirmation
  api_key secret_key publishable_key
  card_number cvv cvc
  authentication_token reset_password_token
  stripe_token adyen_token
]

Without this, a POST /admin/payments with form data will write the secret_key to production.log. Real incident.

A short checklist for a new Spree deployment

Where to read further