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.

Update Platform auth model for Spree 6

Damian Legawiecce1e0ed87634
diff --git a/docs/plans/6.0-platform-auth.md b/docs/plans/6.0-platform-auth.md
index 6694414f38..dee3c3ec47 100644
--- a/docs/plans/6.0-platform-auth.md
+++ b/docs/plans/6.0-platform-auth.md
@@ -4,7 +4,7 @@
**Target:** Spree 5.4 (RefreshToken ✓) + Spree 6.0 (Devise removal, User→Customer rename)
**Depends on:** Admin SPA (6.0-admin-spa.md — removes Rails admin, kills Devise dependency) for Devise removal
**Author:** Damian + Claude
-**Last updated:** 2026-03-17
+**Last updated:** 2026-07-28
## Summary
@@ -72,7 +72,8 @@ Two changes in one plan:
- **Add refresh token support (5.4).** Short-lived access JWT (15 min) + long-lived refresh token (stored in DB, rotatable, revocable). Better UX for React admin and Next.js storefront — silent refresh instead of forced re-login. Ships in 5.4 — can't wait for 6.0 because every storefront has broken session management without it.
- **Rate limiting on auth endpoints.** Use Rails `rate_limit` DSL on login, register, and password reset endpoints. Baked in, not optional.
- **Account lockout after failed attempts.** Track `failed_attempts` and `locked_at` on Customer/AdminUser model. Simple, no Devise dependency.
-- **Remove all Devise generators.** Drop `spree/authentication/devise/` generator directory.
+- **Default models ship in the gem — the host app owns no auth code (2026-07-28).** `Spree::Customer` and `Spree::AdminUser` live in `spree_core` like any other Spree model (`Product`, `Order`). The only historic reason for a host-app-owned user model was Devise — `devise_for` routes and the `devise :...` declaration require an app-local class; dropping Devise removes that constraint. Gem-owned models mean every auth improvement (lockout tuning, rate limiting, MFA/passkeys, token hardening) arrives via a normal gem upgrade + migration instead of a changelog entry asking users to hand-edit scaffolded code. This matches the broader 6.0 strategy: customization via configuration and existing extension systems, not Rails code in the host app. Apps needing extra customer columns add their own migrations against `spree_customers` or use metafields.
+- **No authentication generators at all.** Remove both `spree/authentication/devise/` and `spree/authentication/custom/` generator directories. The `inject_into_file` scaffolding is fragile (silently degrades to "add these lines manually" when the class definition doesn't match its anchor) and produces code frozen at generation time. Custom user classes remain fully supported — `Spree.customer_class = 'MyApp::User'` + one concern include — as a **documented recipe**, not generated code.
- **Keep the adapter pattern.** `Spree.store_authentication_strategies` lets developers plug in Auth0, Clerk, Firebase, LDAP, etc. by implementing `BaseStrategy`.
### User → Customer/AdminUser rename
@@ -83,7 +84,7 @@ Two changes in one plan:
- **`Spree::Customer` includes `has_secure_password`** and all auth concerns by default. Production-ready out of the box, not a "legacy" placeholder.
- **`Spree::AdminUser` includes `has_secure_password`** and admin auth concerns.
- **Prefix IDs: `cust_` for Customer, `adm_` for AdminUser.**
-- **Concerns renamed:** `Spree::UserMethods` → `Spree::CustomerMethods`, `Spree::AdminUserMethods` stays as-is. Aliases for one release.
+- **Concerns renamed + consolidated:** `Spree::UserMethods` → `Spree::CustomerMethods`, `Spree::AdminUserMethods` stays as-is. Aliases for one release. `CustomerMethods` absorbs `Spree::UserAddress` and `Spree::UserPaymentSource` (today the generator injects all three) so a custom user class needs **exactly one include** — `include Spree::CustomerMethods` — to be a valid `Spree.customer_class`.
- **Database tables stay configurable.** `Spree.customer_class` can point to any model — `User`, `Customer`, whatever the app uses. The rename is about the Spree interface and defaults, not forcing a table name.
## Design Details
@@ -326,7 +327,11 @@ end
### Phase 2: Data migration (for existing Devise-based installs)
-No data migration is needed — just change `user_class` to `customer_class` in Spree initializer. For both Devise-based and custom user models.
+Two supported paths:
+
+**Path A — move onto the gem models (recommended, default for spree-starter installs).** A rake task copies rows from the app's user table(s) into `spree_customers` / `spree_admin_users`, mapping `encrypted_password` → `password_digest`. **Passwords survive with zero resets:** Devise's `encrypted_password` is a plain bcrypt digest — the exact format `has_secure_password` reads — as long as no Devise pepper is configured (the spree-starter default). The task must abort loudly if `Devise.pepper` is set (peppered digests can't be verified by `has_secure_password`; those installs use Path B or force resets). Devise reset/remember/confirmation tokens do not carry over — `generates_token_for` replaces reset tokens, and in-flight reset emails simply expire.
+
+**Path B — keep a custom user model.** No data migration: point `Spree.customer_class` at the existing model, replace the old three-concern include set with `include Spree::CustomerMethods`, and add `has_secure_password` (works against the existing `encrypted_password` column via `alias_attribute :password_digest, :encrypted_password` or a column rename). For apps with shared auth DBs, SSO-owned user tables, or non-bcrypt setups.
### Phase 3: Rename config accessors + concerns
@@ -347,9 +352,10 @@ No data migration is needed — just change `user_class` to `customer_class` in
- Add rate limiting to auth endpoints
- Add account lockout to Customer/AdminUser
-### Phase 5: Remove Devise
+### Phase 5: Remove Devise + all authentication generators
- Delete `spree/core/lib/generators/spree/authentication/devise/` directory
+- Delete `spree/core/lib/generators/spree/authentication/custom/` directory
- Delete `spree/admin/lib/generators/spree/admin/devise/` directory
- Delete `spree/admin/app/controllers/spree/admin/user_sessions_controller.rb`
- Delete `spree/admin/app/controllers/spree/admin/user_passwords_controller.rb`
@@ -357,6 +363,16 @@ No data migration is needed — just change `user_class` to `customer_class` in
- Remove Warden references from controller helpers
- Delete `Spree::LegacyUser` and `Spree::LegacyAdminUser`
+### Phase 5b: spree-starter changes
+
+The starter currently ships the host-app auth code the generator produced. At 6.0:
+
+- Remove `app/models/spree/user.rb` (the Devise `Spree::User` model)
+- Remove the `devise` gem from the Gemfile
+- Remove `lib/spree/authentication_helpers.rb` and its `to_prepare` wiring in `config/initializers/spree.rb`
+- Remove `devise_for` routes and the `Devise.parent_controller` initializer block
+- Ship the Path A migration rake task invocation in the upgrade guide
+
### Phase 6: Cleanup (still 6.0)
- Remove deprecation alias for `user_class` (keep only `customer_class`)
diff --git a/docs/plans/decisions.md b/docs/plans/decisions.md
index 3cfb9e9e03..9b7587ccdb 100644
--- a/docs/plans/decisions.md
+++ b/docs/plans/decisions.md
@@ -382,3 +382,29 @@ behavior), dashboard UI, API fields. Industry: the hosted market leader combines
(merchant-controlled), OSS platform A stacks all valid with caps, OSS platform C stacks
priority-ordered, OSS platform B winner-only — merchant control is the differentiated
middle.
+
+## 2026-07-28: Customer/AdminUser models ship in the gem — no host-app model, no auth generators
+
+Review of `6.0-platform-auth.md` surfaced an unstated inversion: today's default
+production setup is a host-app-owned Devise `Spree::User` (scaffolded by the
+`spree/authentication/devise` generator), while the plan's gem-shipped
+`Spree::Customer`/`Spree::AdminUser` were only implicit. Made explicit:
+**default models live in `spree_core` like any other Spree model; the host app
+owns no auth code by default; both authentication generator directories
+(`devise/` AND `custom/`) are deleted.** The only historic reason for an
+app-local user model was Devise's `devise_for`/`devise :...` requirement —
+dropping Devise removes it.
+
+Rationale: auth is the worst place for generated-then-orphaned code (lockout,
+rate limiting, future MFA never reach a scaffolded model without hand-merges);
+matches the 6.0 strategy of customization via configuration over Rails code in
+the host app. Custom user classes stay fully supported via
+`Spree.customer_class` + a single `include Spree::CustomerMethods` (which
+absorbs `UserAddress` + `UserPaymentSource`) — a documented recipe, not a
+generator.
+
+Migration bonus: Devise's `encrypted_password` is a plain bcrypt digest — the
+same format `has_secure_password` reads — so the rake task migrating
+spree-starter installs onto `spree_customers` copies it to `password_digest`
+and **no customer resets their password** (task aborts loudly if
+`Devise.pepper` is set).