@spree/docs 0.1.177 → 0.1.178

package/dist/developer/customization/permissions.md

@@ -1,265 +1,70 @@
 ---
 title: Permissions
+description: The permission catalog, staff roles, and how extensions register their own permissions.
 ---
 
-Spree uses [CanCanCan](https://github.com/CanCanCommunity/cancancan) for authorization. The permission system allows you to define granular access control for different user roles.
+Staff roles and their permissions are managed as data — in the dashboard under **Settings → Roles**, through the Admin API (`/api/v3/admin/roles`), or in seeds. There is nothing to configure in Ruby for day-to-day permission management. This page covers what extension and host-application developers can plug into.
 
-## Permission Sets (Recommended)
+## The permission catalog
 
-Permission Sets provide a clean, modular way to manage permissions. Each permission set is a reusable group of permissions that can be assigned to roles.
+Every grantable capability is a flat key of the form `read_<resource>` or `write_<resource>` — the same vocabulary secret API keys use as scopes. `write_*` implies the matching `read_*`. Discover the catalog at runtime with `GET /api/v3/admin/permissions`; the role editor and the API-key scope picker are both rendered from it.
 
-### How It Works
+Keys are per resource, not per action. The money-adjacent areas (`payments`, `refunds`, `gift_cards`, `store_credits`) are separate resources from `orders`, so "view orders but don't refund" needs no special casing.
 
-1. **Roles** - Determine which permission sets govern a user's access (e.g., `admin`, `customer_service`)
-2. **Permission Sets** - Contain the logic defining what actions users can perform on resources
-3. **Role Configuration** - Associates roles with their corresponding permission sets
-
-### Configuring Roles
-
-In your `config/initializers/spree.rb`, configure which permission sets are assigned to each role:
-
-```ruby
-Rails.application.config.after_initialize do
-  # Default permissions for all users (guests and logged-in customers)
-  Spree.permissions.assign(:default, [Spree::PermissionSets::DefaultCustomer])
-
-  # Full admin access
-  Spree.permissions.assign(:admin, [Spree::PermissionSets::SuperUser])
-
-  # Custom role with specific permissions
-  Spree.permissions.assign(:customer_service, [
-    Spree::PermissionSets::DashboardDisplay,
-    Spree::PermissionSets::OrderManagement,
-    Spree::PermissionSets::UserDisplay
-  ])
-
-  # Merchandiser role for product management
-  Spree.permissions.assign(:merchandiser, [
-    Spree::PermissionSets::DashboardDisplay,
-    Spree::PermissionSets::ProductManagement,
-    Spree::PermissionSets::StockManagement
-  ])
-end
-```
-
-### Built-in Permission Sets
-
-| Permission Set | Description |
-|---------------|-------------|
-| `SuperUser` | Full admin access with safety restrictions |
-| `DefaultCustomer` | Basic storefront permissions (browse, checkout, manage own account) |
-| `DashboardDisplay` | View admin dashboard |
-| `OrderDisplay` | Read-only access to orders |
-| `OrderManagement` | Full order management (view, edit, refund, etc.) |
-| `ProductDisplay` | Read-only access to products and catalog |
-| `ProductManagement` | Full catalog management (products, variants, taxonomies) |
-| `UserDisplay` | Read-only access to users |
-| `UserManagement` | Full user management |
-| `StockDisplay` | Read-only access to inventory |
-| `StockManagement` | Full inventory management |
-| `PromotionManagement` | Manage promotions and coupon codes |
-| `ConfigurationManagement` | Manage store settings, shipping, taxes, etc. |
-| `RoleManagement` | Manage roles (except the protected admin role) |
-
-### Creating Custom Permission Sets
-
-Create a new permission set in `app/models/spree/permission_sets/`:
-
-```ruby
-# app/models/spree/permission_sets/warehouse_management.rb
-module Spree
-  module PermissionSets
-    class WarehouseManagement < Base
-      def activate!
-        can :manage, Spree::StockItem
-        can :manage, Spree::StockLocation
-        can :manage, Spree::StockMovement
-        can :manage, Spree::Shipment
-        can [:read, :admin], Spree::Order
-      end
-    end
-  end
-end
-```
-
-Then assign it to a role:
-
-```ruby
-Spree.permissions.assign(:warehouse_staff, [
-  Spree::PermissionSets::DashboardDisplay,
-  Spree::PermissionSets::WarehouseManagement
-])
-```
-
-### Permission Set API
-
-Within a permission set, you have access to:
-
-- `can(action, subject, conditions = {})` - Grant permission
-- `cannot(action, subject, conditions = {})` - Deny permission
-- `can?(action, subject)` - Check if permission exists
-- `user` - The current user
-- `store` - The current store (for multi-store setups)
-
-```ruby
-module Spree
-  module PermissionSets
-    class OrderManagementForOwnOrders < Base
-      def activate!
-        # Users can only manage orders they created
-        can :manage, Spree::Order, created_by_id: user.id
-
-        # But cannot cancel any order
-        cannot :cancel, Spree::Order
-
-        # Unless it's cancellable
-        can :cancel, Spree::Order, &:allow_cancel?
-      end
-    end
-  end
-end
-```
-
-### Managing Permission Configuration
+Roles as code is plain ActiveRecord:
 
 ```ruby
-# Assign permission sets to a role
-Spree.permissions.assign(:customer_service, [
-  Spree::PermissionSets::OrderDisplay,
-  Spree::PermissionSets::UserManagement
-])
-
-# Add more permission sets to an existing role
-Spree.permissions.assign(:customer_service, [
-  Spree::PermissionSets::StockDisplay
-])
-
-# Clear all permission sets from a role
-Spree.permissions.clear(:customer_service)
-
-# Check what permission sets a role has
-Spree.permissions.permission_sets_for(:customer_service)
-# => [Spree::PermissionSets::OrderDisplay, ...]
-
-# Check if a role is configured
-Spree.permissions.role_configured?(:customer_service)
-# => true
+# db/seeds.rb
+Spree::Role.find_or_create_by!(name: 'support')
+  .update!(permissions: %w[read_orders read_customers], description: 'Read-only support')
 ```
 
-## Users and Roles
+A role with `mutable: false` (set from seeds or the console) renders read-only in the dashboard — for roles the application does not want store staff to edit. The `admin` role is always protected.
 
-Spree comes with an `admin` role by default. You can create more roles in the Admin Panel or via Rails console:
+## Registering extension permissions
 
-```ruby
-Spree::Role.find_or_create_by(name: 'customer_service')
-Spree::Role.find_or_create_by(name: 'merchandiser')
-Spree::Role.find_or_create_by(name: 'warehouse_staff')
-```
-
-Assign a role to a user:
+Register your models as a catalog resource once; the keys appear in the role editor and become mintable API-key scopes with no further wiring:
 
 ```ruby
-user = Spree.user_class.find_by(email: 'john@example.com')
-role = Spree::Role.find_by(name: 'customer_service')
-user.spree_roles << role
+# in your engine's initializer
+Spree.permissions.register_resource(:reviews, group: :catalog, subjects: -> {
+  [SpreeReviews::Review]
+})
 ```
 
-### Default Role Behavior
+- `group` places the row in the permission pickers (`:orders`, `:catalog`, `:marketing`, `:customers`, `:settings`, `:access`, `:analytics` — or your own).
+- `subjects` is a lambda returning the CanCanCan subjects the keys grant; it resolves lazily, so load order does not matter.
+- Pass `write: false` for read-only resources.
 
-- Users with **no roles assigned** automatically get the `:default` role permissions
-- No `RoleUser` records are created for regular customers
-- Only users with special permissions need explicit role assignments
+Localize the labels in your engine's locale file under `spree.permissions_catalog.resources.<name>` (`label` and `description`), and declare the same resource on your admin controllers with `scoped_resource :reviews`.
 
-## Legacy Approach: Custom Ability Classes
+## Beyond the catalog
 
-> **NOTE:** The permission sets approach above is recommended for new projects. The legacy approach below is supported for backward compatibility.
+The catalog is deliberately flat: it answers "may this role touch this kind of record", and that is the whole grant vocabulary. Two rules that do *not* belong in it:
 
-### Adding Custom Permissions via Decorator
-
-Create a new ability class in `app/models/customer_service_ability.rb`:
-
-```ruby
-class CustomerServiceAbility
-  include CanCan::Ability
-
-  def initialize(user)
-    if user.respond_to?(:has_spree_role?) && user.has_spree_role?('customer_service')
-      can :manage, Spree::Order
-    end
-  end
-end
-```
-
-Register it via a decorator in `app/models/spree/ability_decorator.rb`:
-
-```ruby
-module Spree
-  module AbilityDecorator
-    def abilities_to_register
-      [CustomerServiceAbility]
-    end
-  end
-
-  Ability.prepend(AbilityDecorator)
-end
-```
-
-### Replacing the Ability Class
-
-You can replace the entire ability class via [Dependencies](dependencies.md):
+- **Record-state rules** ("a completed order cannot be deleted") live on models and workflows, so they bind every caller — including secret API keys, which never consult CanCanCan.
+- **Row-level restrictions** (a support agent limited to one market) are not expressible as keys. Replace the ability class outright:
 
 ```ruby
 # config/initializers/spree.rb
-Spree::Dependencies.ability_class = 'CustomAbility'
+Spree::Dependencies.ability_class = 'MyApp::Ability'
 ```
 
 ```ruby
-# app/models/custom_ability.rb
-class CustomAbility < Spree::Ability
+# app/models/my_app/ability.rb
+class MyApp::Ability < Spree::Ability
   def initialize(user, options = {})
-    alias_cancan_delete_action
-
-    @user = user || Spree.user_class.new
-    @store = options[:store] || Spree::Current.store
-
-    if @user.respond_to?(:has_spree_role?) && @user.has_spree_role?('admin')
-      apply_admin_permissions(@user, options)
-    elsif @user.respond_to?(:has_spree_role?) && @user.has_spree_role?(:customer_service)
-      apply_customer_service_permissions(@user)
-    else
-      apply_user_permissions(@user, options)
-    end
+    super
+    return unless user.respond_to?(:market_id) && user.market_id
 
-    protect_admin_role
-  end
-
-  protected
-
-  def apply_customer_service_permissions(user)
-    can :manage, Spree::Order
-    can [:read, :admin], Spree.user_class
+    cannot :manage, Spree::Order
+    can [:read, :admin], Spree::Order, market_id: user.market_id
   end
 end
 ```
 
-## CanCanCan Reference
-
-Spree's permission system is built on CanCanCan. Key concepts:
+## How enforcement works
 
-- `can :action, Subject` - Grant permission
-- `can :manage, Subject` - Grant all actions (create, read, update, destroy)
-- `cannot :action, Subject` - Explicitly deny permission
-- `can :action, Subject, conditions` - Conditional permission
-
-```ruby
-# Examples
-can :read, Spree::Product                           # Can read any product
-can :manage, Spree::Order, user_id: user.id        # Can manage own orders
-can :update, Spree::Order do |order|               # Block conditions
-  order.user == user && !order.completed?
-end
-cannot :destroy, Spree::Order                       # Cannot destroy any order
-can :destroy, Spree::Order, &:can_be_deleted?      # Unless it's deletable
-```
+Every Admin API controller declares its resource (`scoped_resource :orders`). Each request checks the principal's keys — a staff member's role permissions on the current store, or a secret key's scopes — against `read_<resource>` or `write_<resource>` for the action. A missing key produces a 403 naming it in `details.required_permission`. Behind that gate, keys compile to CanCanCan rules for record-level concerns, and `GET /api/v3/admin/me` returns both the rule dump the dashboard mirrors and `permission_keys`, the flat key list.
 
-See the [CanCanCan documentation](https://github.com/CanCanCommunity/cancancan) for more details.
+Storefront customers are not part of this system — customer authorization is ownership, enforced by the Store API's scoped lookups, with nothing to configure. The one swappable piece is `Spree::Storefront::AccessPolicy` (via `Spree::Dependencies.storefront_access_policy_class`): a generic `readable?` / `writable?` / `scope` protocol that defaults to "the caller owns the record", with carts and orders adding guest-token access. Replace it only when access must widen beyond the owner, such as company accounts sharing purchases or wishlists.