Permissions matrix

Cahier §3 defines eight profiles and §3.1 the principles: least privilege, permissions per action (voir, créer, modifier, supprimer, valider, exporter, administrer), delegates limited to their zone and resellers to their own data, every critical action historised. This page is the reference the server's guard, the back-office menus and the permission tests are built from (ACL-01 to ACL-05, ADM-02). The default role sets below are seeded by the database migration; HOCO can adjust staff roles in BO-62 within the guard rails.

How a request is authorisedCopy Anchor Link

Every API operation runs the same checks, in this order; the first failure stops the request.

The interface hides what the user cannot do (menus of BO-03, buttons, allowedActions returned by detail endpoints), but hiding is never the protection: the server enforces every rule (ACL-05).

Permission catalogueCopy Anchor Link

Keys are <module>.<action>. Only the combinations below exist (75 keys, 68 in V1); the catalogue is served by admin.permissions.list.

RolesCopy Anchor Link

A user has one UserType. Staff users can hold several staff roles (their permissions add up); DELEGATE and RESELLER are system roles held alone. SUPER_ADMIN, DELEGATE and RESELLER cannot be edited; the five other staff roles can.

Role × permission matrixCopy Anchor Link

Columns: SA super admin · CA commercial admin · SM stock manager · FM finance manager · DM delivery manager · DIR direction · DEL delegate · RES reseller.

Values: ✓ granted · — not granted · read-only the role only views this module · own the user's own records only · zone records in the delegate's scope (scope rules) · credit only see conditional rules. Delegates and resellers hold no back-office permission key: their cells describe what their own scoped operations (delegate.*, reseller self operations) give them.

Reports are filtered too: each report declares the view permissions it needs (a margin report needs finance.view), so a role only sees the reports of its modules in admin.reports.list.

Conditional rulesCopy Anchor Link

Some operations need more than their permission key:

Sensitive fieldsCopy Anchor Link

Data scope rulesCopy Anchor Link

Scopes are query filters added by the server to every read and write; a client parameter can never widen them.

Reseller — self

• Order, Invoice, Payment, CreditNote, ReturnRequest, Ticket, ResellerAddress, ResellerDocument, Favorite, Cart, V2 LoyaltyAccount: resellerId = :myResellerId.
• Catalog: visible products per BR-60; prices of :myCustomerType; promotions and banners whose audience matches the reseller; announcements targeted to them.
• Live events (events.stream): only events about their own orders, returns, tickets and notifications.

Guest — no session

• Only auth: optional and public operations: catalog, facets, promotions, banners, support WhatsApp number. Products without ALLOW rules; price: null; no cart, no favorites, no orders.

Delegate — delegate (decided rule)

-- Resellers and prospects a delegate may read and act on
reseller.assignedDelegateId = :me
OR (
  reseller.assignedDelegateId IS NULL
  AND reseller.zoneId IN (:myZoneIds)
  AND reseller.status IN ('NEW_PROSPECT','TO_CONTACT','INTERESTED','NOT_INTERESTED','TO_FOLLOW_UP')
)
OR reseller.id IN (
  SELECT v.resellerId FROM Visit v JOIN Tour t ON t.id = v.tourId
  WHERE t.delegateId = :me AND t.date BETWEEN :today - 7 AND :today + 30
)

• Assigned resellers: full field access (sheet, history, notes, photos, tasks, invitations, assisted orders, read-only orders).
• Unassigned prospects of the delegate's zones: visible so that delegates pick them up instead of creating duplicates; a prospect assigned to another delegate of the same zone is not visible.
• Tour-derived access: a reseller planned in one of the delegate's tours (from 7 days back to 30 days ahead) is accessible even if assigned to someone else — this covers replacements during leave.
• Orders: order.resellerId in the assigned resellers or order.sourceDelegateId = :me; read-only, without purchase prices.
• Tours and visits: tour.delegateId = :me. Tasks: assigneeId = :me. Invitations, objectives, performance, reports, location pings: delegateId = :me.
• Duplicate phone check (delegate.resellers.checkPhone) searches every record but returns details only for records in scope (BR-04).

Staff — no row filter in V1: a staff role sees every record of the modules it holds. A regional restriction of staff (for example a manager limited to the West) would be a change request.

Guard railsCopy Anchor Link

1. The last active SUPER_ADMIN cannot be removed, suspended, disabled or lose the role (409 LAST_SUPER_ADMIN).
2. No escalation: a user can only grant a role, or add a permission to a role, if they hold every permission concerned themselves (403 PERMISSION_ESCALATION). Only roles.administer holders edit roles.
3. No self-service: nobody edits their own roles or permissions, or suspends or disables themselves (403 SELF_MODIFICATION_FORBIDDEN).
4. Fixed roles: SUPER_ADMIN always holds every permission; DELEGATE and RESELLER have no back-office permission and cannot be combined with staff roles.
5. Delegates never see purchase prices, margins, other prices than the assisted reseller's, stock quantities, credit limits or other delegates' positions.
6. Resellers never see another reseller's data, another customer type's price or a stock quantity; their customer type is never editable by them.
7. Financial actions are separated: confirming an order (orders.validate) does not give the right to override credit (finance.validate) or stock (stock.validate); every override is a separate AuditLog entry with its reason.
8. Exports respect scope and masking: an export never contains a field or a record its requester cannot see on screen.
9. Real-time streams are filtered: admin.events.stream sends an event only to sessions holding the view permission of its module (orders events need orders.view, positions need field.view); events.stream only carries the caller's own events.
10. Changes apply at once: each session carries a permission version; after a role change, the next request reloads the permission set and open streams are re-authorised — no sign-out needed.
11. Sensitive operations need recent authentication in the back-office (see conditional rules).

Audit of permission changesCopy Anchor Link

Entries are immutable and readable in BO-63 with audit.view; they follow the audit retention of BR-84.

Test checklist for ACL-05Copy Anchor Link

The permission tests of SRV-28 are generated from endpoints.json and this page, and run in CI on every pull request.

1. Every staff operation × every role: call each admin.* operation with a user of each seeded role; expect 2xx when the matrix grants the permission, 403 PERMISSION_DENIED otherwise (one test per cell, generated).
2. Audience gates: a reseller token on a delegate.* or admin.* operation, a delegate token on a reseller or admin.* operation → 403.
3. Reseller scope: reseller B reads, cancels, returns or claims on reseller A's order, invoice, ticket, address or document id → 404 NOT_FOUND; files.downloadUrl on A's private file → 404.
4. Delegate scope: a reseller assigned to the delegate → 200; an unassigned prospect of their zone → 200; a prospect of their zone assigned to another delegate → 404; a reseller in one of their tours of next week → 200; the same reseller 31 days ahead → 404.
5. Guests: catalog and facets answer without a session with price: null and no price facet; cart, favorites, orders → 401.
6. Sensitive fields: admin.products.get as CA, SM and DM has no purchasePrice; as FM it has. Reseller and delegate responses contain no quantity, no other customer-type price, no purchase price, no credit limit (delegate) — checked by schema snapshot.
7. Account gates: a suspended user gets 403 ACCOUNT_SUSPENDED on every operation except appConfig.get and public ones; a pending reseller gets 403 ACCOUNT_PENDING_VALIDATION on cart.checkout, orders.confirmAssisted and returns.create, and prices according to catalog.pricesVisibleBeforeValidation.
8. Conditional rules: CA cannot validate with a stock override; FM can validate an order pending only for CREDIT_OVER_LIMIT and nothing else; DM can move an order to PREPARING but cannot cancel it; SM can receive a return but cannot approve it; a REPLACEMENT order created by admin.tickets.resolve stays SUBMITTED until orders.validate.
9. Customer type: profile.update with customerType → 403 FIELD_NOT_EDITABLE; admin.resellers.update without a reason → 422 REASON_REQUIRED; with a reason → an AuditLog entry with before and after.
10. Guard rails: removing the last super admin → 409; granting a permission one does not hold → 403 PERMISSION_ESCALATION; editing one's own roles → 403.
11. Immediate effect: remove orders.validate from CA; the next CA request to admin.orders.validate → 403 without signing out; the open SSE stream stops carrying order events.
12. Streams and search: admin.events.stream for SM carries stock.alert but no delegate.position; admin.search for DM returns no invoices; events.stream for reseller A never carries reseller B's events.
13. Exports: a CA export of the catalog has no purchase-price column; a delegate cannot reach any export.
14. Interface: for each role, a snapshot of the back-office menu (BO-03) matches the matrix; hidden buttons correspond to refused operations.
15. Audit: every permission change, override, customer-type change and user status change produces exactly one AuditLog entry with actor, before and after.