@mohasinac/appkit 4.70.0 → 4.71.2

package/dist/features/auth/permissions/constants.d.ts

@@ -11,11 +11,49 @@
  * Permission naming: admin:resource:action
  * Ban action naming: plain verb phrase — write_reviews, place_bids, etc.
  */
-export type Permission = "admin:dashboard:view" | "admin:users:read" | "admin:users:write" | "admin:users:delete" | "admin:user-bans:read" | "admin:user-bans:write" | "admin:products:read" | "admin:products:write" | "admin:products:delete" | "admin:orders:read" | "admin:orders:write" | "admin:returns:read" | "admin:returns:write" | "admin:stores:read" | "admin:stores:write" | "admin:store-addresses:read" | "admin:addresses:read" | "admin:addresses:write" | "admin:analytics:view" | "admin:payouts:read" | "admin:payouts:write" | "admin:audit-log:read" | "admin:categories:read" | "admin:categories:write" | "admin:categories:delete" | "admin:parts:read" | "admin:parts:write" | "admin:parts:delete" | "admin:beys:read" | "admin:beys:write" | "admin:beys:delete" | "admin:brands:read" | "admin:brands:write" | "admin:brands:delete" | "admin:coupons:read" | "admin:coupons:write" | "admin:coupons:delete" | "admin:deals:read" | "admin:deals:write" | "admin:featured:read" | "admin:featured:write" | "admin:reviews:read" | "admin:reviews:write" | "admin:reviews:delete" | "admin:blog:read" | "admin:blog:write" | "admin:blog:delete" | "admin:blog:publish" | "admin:bids:read" | "admin:bids:write" | "admin:offers:read" | "admin:offers:write" | "admin:media:read" | "admin:media:write" | "admin:media:delete" | "admin:site:read" | "admin:site:write" | "admin:settings:write" | "admin:navigation:read" | "admin:navigation:write" | "admin:sections:read" | "admin:sections:write" | "admin:carousel:read" | "admin:carousel:write" | "admin:carousel:delete" | "admin:ads:read" | "admin:ads:write" | "admin:ads:delete" | "admin:faqs:read" | "admin:faqs:write" | "admin:faqs:delete" | "admin:tester-checklist:read" | "admin:tester-checklist:write" | "admin:tester-checklist:delete" | "admin:tester-feedback:read" | "admin:tester-feedback:write" | "admin:newsletter:read" | "admin:newsletter:write" | "admin:contact:read"
+export type Permission = "admin:dashboard:view" | "admin:users:read" | "admin:users:write" | "admin:users:delete" | "admin:user-bans:read" | "admin:user-bans:write" | "admin:products:read" | "admin:products:write" | "admin:products:delete" | "admin:orders:read" | "admin:orders:write"
+/**
+ * ── The order PAYMENT OVERRIDE — a money-path power with its own gate ──────
+ *
+ * Three actions in `_internal/server/features/orders/actions.ts` hang off
+ * this and nothing else: `adminVerifyPaymentAction` (declares a manual
+ * cash/UPI payment received, flips the order to `paid`/`processing`),
+ * `adminRequestProofReuploadAction` (clears the proof and extends the payment
+ * window) and `adminRejectPaymentAsFraudAction` (cancels the order, restores
+ * stock, and enqueues a 7-day hard-ban cascade on the buyer's account).
+ *
+ * 🛑 Deliberately NOT `admin:orders:write`, and that is the whole decision.
+ * `orders:write` names "edit an order" — fix an address, bump a status. None
+ * of the three above is an edit: one asserts money arrived, one moves a
+ * deadline, one bans a human being. Owner, 2026-11-08, choosing explicit
+ * moderation permissions over the `moderator`→`employee` fold: an order
+ * override is a money-path power and must not come bundled with editing a
+ * review. Same reasoning as `admin:points:write` below.
+ *
+ * 🛑 Granted by the `payment_reviewer` preset ONLY, and that preset is in no
+ * role bundle — so no account holds this because of a role, ever. An admin
+ * bypasses the array entirely, which is what keeps "admin sees and does
+ * everything" true without naming it here.
+ */
+ | "admin:orders:payment-override" | "admin:returns:read" | "admin:returns:write" | "admin:stores:read" | "admin:stores:write" | "admin:store-addresses:read" | "admin:addresses:read" | "admin:addresses:write" | "admin:analytics:view" | "admin:payouts:read" | "admin:payouts:write" | "admin:audit-log:read" | "admin:categories:read" | "admin:categories:write" | "admin:categories:delete" | "admin:parts:read" | "admin:parts:write" | "admin:parts:delete" | "admin:beys:read" | "admin:beys:write" | "admin:beys:delete" | "admin:brands:read" | "admin:brands:write" | "admin:brands:delete" | "admin:coupons:read" | "admin:coupons:write" | "admin:coupons:delete" | "admin:deals:read" | "admin:deals:write" | "admin:featured:read" | "admin:featured:write" | "admin:reviews:read" | "admin:reviews:write" | "admin:reviews:delete" | "admin:blog:read" | "admin:blog:write" | "admin:blog:delete" | "admin:blog:publish" | "admin:bids:read" | "admin:bids:write" | "admin:offers:read" | "admin:offers:write" | "admin:media:read" | "admin:media:write" | "admin:media:delete" | "admin:site:read" | "admin:site:write" | "admin:settings:write" | "admin:navigation:read" | "admin:navigation:write" | "admin:sections:read" | "admin:sections:write" | "admin:carousel:read" | "admin:carousel:write" | "admin:carousel:delete" | "admin:ads:read" | "admin:ads:write" | "admin:ads:delete" | "admin:faqs:read" | "admin:faqs:write" | "admin:faqs:delete" | "admin:tester-checklist:read" | "admin:tester-checklist:write" | "admin:tester-checklist:delete" | "admin:tester-feedback:read" | "admin:tester-feedback:write" | "admin:newsletter:read" | "admin:newsletter:write" | "admin:contact:read"
 /** Destructive/mutating contact-submission actions. Added 2026-08-29 —
  * `DELETE /api/admin/contact-submissions/[id]` declared `admin:contact:delete`,
  * which is not a member of this union and therefore could never be granted. */
- | "admin:contact:write" | "admin:moderation:read" | "admin:roles:read"
+ | "admin:contact:write" | "admin:moderation:read"
+/**
+ * ACT on the moderation queue — flag a suspicious draw entry, resolve a
+ * queued report.
+ *
+ * Added 2026-11-08 because `PATCH /api/giveaway-entries/[id]/flag` was gated
+ * a role tuple naming the dead `moderator` with no permission at all (the
+ * literal is not quoted — `audit-permission-role-mismatch.mjs` matches such
+ * a line textually and a comment reciting it keeps the audit red), so the
+ * fold made
+ * it reachable by every employee; and gating a WRITE on `:read` would be the
+ * kind of near-miss that reads as correct for ever. Paired with `:read` the
+ * way every other resource in this union is.
+ */
+ | "admin:moderation:write" | "admin:roles:read"
 /**
  * Skip OTP + payment when placing an order. Replaces
  * `siteSettings.featureFlags.adminCheckoutBypass`: a capability granted to a
@@ -37,7 +75,7 @@ export type Permission = "admin:dashboard:view" | "admin:users:read" | "admin:us
  * mechanism — and revoking it is a permission change, which the admin audit
  * log already records.
  */
- | "tester:admin-surfaces" | "admin:events:read" | "admin:events:write" | "admin:events:delete" | "admin:event-entries:read" | "admin:event-entries:write" | "admin:support-tickets:read" | "admin:support-tickets:write" | "admin:shipments:read" | "admin:shipments:write" | "admin:catalogue:read" | "admin:catalogue:write" | "admin:inventory:read" | "admin:inventory:write" | "admin:grouped-listings:read" | "admin:grouped-listings:write" | "admin:support-tickets:assign" | "admin:support-tickets:close" | "admin:scammers:read" | "admin:scammers:write" | "admin:scammers:verify" | "admin:scammers:delete" | "admin:sessions:read" | "admin:sessions:delete" | "admin:notifications:read" | "admin:notifications:write" | "admin:carts:read" | "admin:wishlists:read" | "admin:feature-flags:read" | "admin:feature-flags:write" | "admin:team:read" | "admin:team:write" | "admin:maintenance:view-server-errors" | "admin:maintenance:view-client-errors" | "admin:maintenance:view-function-errors" | "admin:maintenance:view-cloud-logs" | "admin:maintenance:view-payment-rollbacks" | "admin:maintenance:run-analysis" | "admin:maintenance:purge-errors" | "admin:maintenance:view-gateway-events" | "admin:maintenance:view-obligations" | "admin:payment-cases:read" | "admin:payment-cases:write" | "admin:protection-claims:read" | "admin:protection-claims:write"
+ | "tester:admin-surfaces" | "admin:events:read" | "admin:events:write" | "admin:events:delete" | "admin:event-entries:read" | "admin:event-entries:write" | "admin:support-tickets:read" | "admin:support-tickets:write" | "admin:shipments:read" | "admin:shipments:write" | "admin:catalogue:read" | "admin:catalogue:write" | "admin:inventory:read" | "admin:inventory:write" | "admin:grouped-listings:read" | "admin:grouped-listings:write" | "admin:support-tickets:assign" | "admin:support-tickets:close" | "admin:scammers:read" | "admin:scammers:write" | "admin:scammers:verify" | "admin:scammers:delete" | "admin:sessions:read" | "admin:sessions:delete" | "admin:notifications:read" | "admin:notifications:write" | "admin:carts:read" | "admin:wishlists:read" | "admin:feature-flags:read" | "admin:feature-flags:write" | "admin:team:read" | "admin:team:write" | "admin:maintenance:view-server-errors" | "admin:maintenance:view-client-errors" | "admin:maintenance:view-function-errors" | "admin:maintenance:view-cloud-logs" | "admin:maintenance:view-payment-rollbacks" | "admin:maintenance:run-analysis" | "admin:maintenance:purge-errors" | "admin:maintenance:view-gateway-events" | "admin:maintenance:view-obligations" | "admin:maintenance:view-cache" | "admin:maintenance:clear-cache" | "admin:payment-cases:read" | "admin:payment-cases:write" | "admin:protection-claims:read" | "admin:protection-claims:write"
 /**
  * Credit or debit a buyer's points by hand.
  *
@@ -54,6 +92,83 @@ export type Permission = "admin:dashboard:view" | "admin:users:read" | "admin:us
  * different from a decision that moves money.
  */
  | "admin:points:write";
+/**
+ * 🛑 THE cap on how many roles one user may hold — the DEFAULT, not the rule.
+ *
+ * Owner, 2026-11-07: *"they can have more than 3 in future, for now 3"*. So
+ * the literal `3` appears exactly here and nowhere else: not in the schema,
+ * not in the validator, not in the admin UI. Read it through
+ * `getMaxRolesPerUser()` in `features/auth/auth-helpers`, which prefers a
+ * configured override and falls back to this.
+ *
+ * Raising it must be a settings change, never a deploy — which is only true as
+ * long as nobody restates the number.
+ */
+export declare const DEFAULT_MAX_ROLES_PER_USER = 3;
+/**
+ * ── Roles are bundles of permissions, and the bundles are DATA ───────────────
+ *
+ * `permissionsFor(user)` unions the bundle of every role the user holds with
+ * the per-user `permissions[]` array. Editing this map is how a role gains or
+ * loses a capability — no code change, no new branch anywhere.
+ *
+ * 🛑 EVERY bundle is EMPTY, and that is a decision, not an oversight:
+ *
+ *   - `admin` short-circuits to `isAdmin: true` and never consults a list, so
+ *     an entry here would be dead weight. Admin sees everything, everywhere.
+ *   - `user`, `seller` and `tester` hold no ADMIN-console permissions at all.
+ *     Their abilities are ownership-scoped ("edit your own store", "bid on a
+ *     listing"), enforced at the resource, not by an `admin:*` key.
+ *   - `employee` is configured ENTIRELY per person through `permissions[]` +
+ *     `PERMISSION_GROUPS`. Holding the role grants nothing on its own.
+ *
+ * ── 🛑 THE DEFAULT GRANT FOR MODERATION IS: **NOT GRANTED** ─────────────────
+ *
+ * `employee` used to carry `admin:moderation:read` here, and that single entry
+ * was the whole problem. Collapsing `moderator` into `employee` (A9, owner
+ * 2026-11-07) made `isModeratorUser()` true for every employee, so ~20
+ * moderator-gated actions — order payment overrides, review and product
+ * moderation, support tickets, draw-entry oversight — widened to every
+ * existing employee account as a side effect of a role rename. Nobody decided
+ * that; it fell out of the fold.
+ *
+ * Owner, 2026-11-08, asked to choose: **keep the fold, and gate those sites on
+ * an explicit moderation permission.** So the fold stays (`moderator` is not
+ * coming back as a role — `rolesOf()` folds the name away on read), and the
+ * power becomes a GRANT:
+ *
+ *   employee WITHOUT the grant  → denied every moderation site.
+ *   employee WITH the grant     → allowed exactly what was granted.
+ *   admin                       → allowed unconditionally, never consults this.
+ *   user / seller / tester      → gain nothing; `permissions[]` is not even
+ *                                 honoured for seller/user (see
+ *                                 `ROLE_GRANTS_EXPLICIT_PERMISSIONS`).
+ *
+ * ⚠ Do not "fix" a moderation surface by adding a key back to the `employee`
+ * bundle. That reinstates exactly the widening the owner rejected, and it does
+ * it silently. Grant it to the person, or add it to a preset below.
+ */
+export declare const ROLE_PERMISSION_BUNDLES: Record<string, Permission[]>;
+/**
+ * Which roles have their per-user `permissions[]` array HONOURED on top of
+ * their bundle.
+ *
+ * 🛑 This is a security boundary expressed as data, and it exists so
+ * `permissionsFor()` does not have to ask "what role is this?".
+ *
+ * Why it is not simply "always honour the array": `permissions[]` is written
+ * by the admin team UI for employees. A stray `admin:users:write` sitting on a
+ * SELLER document — a leftover from a demotion, a bad import, a bulk edit —
+ * would otherwise become live admin access the moment the resolver started
+ * unioning. The previous resolver returned `[]` for every non-employee role,
+ * so honouring the array unconditionally would have been a silent widening
+ * dressed up as a refactor.
+ *
+ * `tester` is included because `tester:admin-surfaces` is granted through this
+ * very array (see `canTestAdminSurfaces`) — that is the one non-employee role
+ * whose fine-grained grants are real.
+ */
+export declare const ROLE_GRANTS_EXPLICIT_PERMISSIONS: Record<string, boolean>;
 /**
  * Granular user actions that can be soft-banned individually.
  * A user may have multiple simultaneous soft bans of different types.
@@ -64,7 +179,17 @@ export type BannedAction = "write_reviews" | "write_blog_comments" | "join_event
  * Preset permission bundles. "custom" = no preset, permissions set individually.
  * Used for display and for pre-filling the permissions editor when inviting employees.
  */
-export type EmployeeGroup = "content_moderator" | "review_manager" | "blog_poster" | "community_manager" | "event_handler" | "newsletter_manager" | "seo_manager" | "ad_manager" | "site_manager" | "catalog_manager" | "finance_manager" | "data_analyst" | "customer_support" | "support_agent" | "store_onboarding" | "trust_and_safety" | "auction_monitor" | "scam_moderator" | "maintenance_employee" | "custom";
+export type EmployeeGroup = "content_moderator" | "review_manager" | "blog_poster" | "community_manager" | "event_handler" | "newsletter_manager" | "seo_manager" | "ad_manager" | "site_manager" | "catalog_manager" | "finance_manager" | "data_analyst" | "customer_support" | "support_agent" | "store_onboarding" | "trust_and_safety"
+/**
+ * The ONLY preset that carries `admin:orders:payment-override`.
+ *
+ * Narrow on purpose — dashboard, read orders, override a payment, nothing
+ * else. It exists so the money-path power is grantable from the admin UI
+ * (`getPermissionsForDomain` only lists permissions some preset names) while
+ * staying out of every broader bundle: `trust_and_safety` and
+ * `customer_support` both touch orders and deliberately do NOT hold it.
+ */
+ | "payment_reviewer" | "collector_drop_monitor" | "scam_moderator" | "maintenance_employee" | "custom";
 /**
  * Pre-defined permission bundles for each EmployeeGroup.
  * Admin always bypasses; these bundles are only relevant for role=employee.
@@ -83,7 +208,7 @@ export declare const ROUTE_PERMISSION_MAP: Record<string, Permission>;
  *
  * Defaults on store creation: ["suggest_brands", "create_coupons"]
  */
-export type StoreCapability = "advanced_listing_types" | "host_auctions" | "host_preorders" | "create_categories" | "suggest_brands" | "create_coupons" | "bulk_listing_import" | "extended_return_window" | "verified_seller" | "featured_placement" | "promotional_banner" | "priority_support" | "multiple_stores" | "custom_store_slug" | "api_access" | "lower_commission_rate" | "early_access_features" | "advanced_analytics" | "whatsapp_catalog_sync";
+export type StoreCapability = "advanced_listing_types" | "host_collector_drops" | "host_preorders" | "create_categories" | "suggest_brands" | "create_coupons" | "bulk_listing_import" | "extended_return_window" | "verified_seller" | "featured_placement" | "promotional_banner" | "priority_support" | "multiple_stores" | "custom_store_slug" | "api_access" | "lower_commission_rate" | "early_access_features" | "advanced_analytics" | "whatsapp_catalog_sync";
 export declare const ALL_STORE_CAPABILITIES: StoreCapability[];
 /** Narrow an untrusted string to a real capability. */
 export declare function isStoreCapability(value: unknown): value is StoreCapability;

package/dist/features/auth/permissions/constants.js

@@ -12,6 +12,108 @@
  * Ban action naming: plain verb phrase — write_reviews, place_bids, etc.
  */
 // ============================================================================
+// ROLES AS DATA — the role → permission bundles, and the role-count cap
+// ============================================================================
+/**
+ * 🛑 THE cap on how many roles one user may hold — the DEFAULT, not the rule.
+ *
+ * Owner, 2026-11-07: *"they can have more than 3 in future, for now 3"*. So
+ * the literal `3` appears exactly here and nowhere else: not in the schema,
+ * not in the validator, not in the admin UI. Read it through
+ * `getMaxRolesPerUser()` in `features/auth/auth-helpers`, which prefers a
+ * configured override and falls back to this.
+ *
+ * Raising it must be a settings change, never a deploy — which is only true as
+ * long as nobody restates the number.
+ */
+export const DEFAULT_MAX_ROLES_PER_USER = 3;
+/**
+ * ── Roles are bundles of permissions, and the bundles are DATA ───────────────
+ *
+ * `permissionsFor(user)` unions the bundle of every role the user holds with
+ * the per-user `permissions[]` array. Editing this map is how a role gains or
+ * loses a capability — no code change, no new branch anywhere.
+ *
+ * 🛑 EVERY bundle is EMPTY, and that is a decision, not an oversight:
+ *
+ *   - `admin` short-circuits to `isAdmin: true` and never consults a list, so
+ *     an entry here would be dead weight. Admin sees everything, everywhere.
+ *   - `user`, `seller` and `tester` hold no ADMIN-console permissions at all.
+ *     Their abilities are ownership-scoped ("edit your own store", "bid on a
+ *     listing"), enforced at the resource, not by an `admin:*` key.
+ *   - `employee` is configured ENTIRELY per person through `permissions[]` +
+ *     `PERMISSION_GROUPS`. Holding the role grants nothing on its own.
+ *
+ * ── 🛑 THE DEFAULT GRANT FOR MODERATION IS: **NOT GRANTED** ─────────────────
+ *
+ * `employee` used to carry `admin:moderation:read` here, and that single entry
+ * was the whole problem. Collapsing `moderator` into `employee` (A9, owner
+ * 2026-11-07) made `isModeratorUser()` true for every employee, so ~20
+ * moderator-gated actions — order payment overrides, review and product
+ * moderation, support tickets, draw-entry oversight — widened to every
+ * existing employee account as a side effect of a role rename. Nobody decided
+ * that; it fell out of the fold.
+ *
+ * Owner, 2026-11-08, asked to choose: **keep the fold, and gate those sites on
+ * an explicit moderation permission.** So the fold stays (`moderator` is not
+ * coming back as a role — `rolesOf()` folds the name away on read), and the
+ * power becomes a GRANT:
+ *
+ *   employee WITHOUT the grant  → denied every moderation site.
+ *   employee WITH the grant     → allowed exactly what was granted.
+ *   admin                       → allowed unconditionally, never consults this.
+ *   user / seller / tester      → gain nothing; `permissions[]` is not even
+ *                                 honoured for seller/user (see
+ *                                 `ROLE_GRANTS_EXPLICIT_PERMISSIONS`).
+ *
+ * ⚠ Do not "fix" a moderation surface by adding a key back to the `employee`
+ * bundle. That reinstates exactly the widening the owner rejected, and it does
+ * it silently. Grant it to the person, or add it to a preset below.
+ */
+export const ROLE_PERMISSION_BUNDLES = {
+    admin: [],
+    employee: [],
+    /*
+     * Legacy alias. `rolesOf()` folds `moderator` to `employee`, so a normalised
+     * role set never contains it and this entry is never read — it exists so the
+     * map stays total against the `UserRole` union while the union still carries
+     * the deprecated member for un-backfilled documents. Empty for the same
+     * reason `employee` is: a stored `moderator` document must not out-grant a
+     * backfilled one.
+     */
+    moderator: [],
+    seller: [],
+    tester: [],
+    user: [],
+};
+/**
+ * Which roles have their per-user `permissions[]` array HONOURED on top of
+ * their bundle.
+ *
+ * 🛑 This is a security boundary expressed as data, and it exists so
+ * `permissionsFor()` does not have to ask "what role is this?".
+ *
+ * Why it is not simply "always honour the array": `permissions[]` is written
+ * by the admin team UI for employees. A stray `admin:users:write` sitting on a
+ * SELLER document — a leftover from a demotion, a bad import, a bulk edit —
+ * would otherwise become live admin access the moment the resolver started
+ * unioning. The previous resolver returned `[]` for every non-employee role,
+ * so honouring the array unconditionally would have been a silent widening
+ * dressed up as a refactor.
+ *
+ * `tester` is included because `tester:admin-surfaces` is granted through this
+ * very array (see `canTestAdminSurfaces`) — that is the one non-employee role
+ * whose fine-grained grants are real.
+ */
+export const ROLE_GRANTS_EXPLICIT_PERMISSIONS = {
+    admin: true, // moot — admin short-circuits before the array is read
+    employee: true,
+    moderator: true, // legacy alias of employee; never present after folding
+    tester: true,
+    seller: false,
+    user: false,
+};
+// ============================================================================
 // PERMISSION GROUP PRESETS
 // ============================================================================
 /**
@@ -21,6 +123,13 @@
 export const PERMISSION_GROUPS = {
     content_moderator: [
         "admin:dashboard:view",
+        /*
+         * The moderation hub itself. Named by the four moderation presets and by
+         * nothing else — it is no longer in any ROLE bundle, so "make this person
+         * a content moderator" is now the act that grants it.
+         */
+        "admin:moderation:read",
+        "admin:moderation:write",
         "admin:reviews:read",
         "admin:reviews:write",
         "admin:reviews:delete",
@@ -30,6 +139,7 @@ export const PERMISSION_GROUPS = {
     ],
     review_manager: [
         "admin:dashboard:view",
+        "admin:moderation:read",
         "admin:reviews:read",
         "admin:reviews:write",
         "admin:reviews:delete",
@@ -207,8 +317,19 @@ export const PERMISSION_GROUPS = {
         "admin:users:read",
         "admin:notifications:write",
     ],
+    /*
+     * 🛑 `admin:orders:payment-override` is deliberately ABSENT here, even
+     * though this preset holds `admin:orders:read` and the fraud-rejection path
+     * is arguably trust-and-safety work. Verifying that money arrived is a
+     * finance decision, not a safety one, and the three override actions are one
+     * permission — granting the ban half would grant the "declare this payment
+     * received" half with it. Use `payment_reviewer` alongside this preset when
+     * one person genuinely does both.
+     */
     trust_and_safety: [
         "admin:dashboard:view",
+        "admin:moderation:read",
+        "admin:moderation:write",
         "admin:users:read",
         "admin:users:write",
         "admin:user-bans:read",
@@ -216,6 +337,20 @@ export const PERMISSION_GROUPS = {
         "admin:orders:read",
         "admin:products:read",
         "admin:products:write",
+        /*
+         * ⚠ Added 2026-11-08 by the lane that gated `DELETE /api/products/[id]` on
+         * this key, because `verify-moderation-permissions.mjs` caught that
+         * `admin:products:delete` appeared in NO preset — so it matched no
+         * `getPermissionsForDomain()` result, had no checkbox in the employee
+         * editor, and was therefore declarable in code and ungrantable in the UI.
+         * Same latent defect as `admin:moderation:read` had, and the same reason a
+         * permission ends up bolted onto a role instead.
+         *
+         * `trust_and_safety` and not `catalog_manager`: taking down a counterfeit
+         * or illegal listing is a safety act. Curating the catalogue is not a
+         * mandate to archive someone else's listing.
+         */
+        "admin:products:delete",
         "admin:reviews:read",
         "admin:reviews:write",
         "admin:reviews:delete",
@@ -233,7 +368,7 @@ export const PERMISSION_GROUPS = {
         "admin:scammers:write",
         "admin:scammers:verify",
     ],
-    auction_monitor: [
+    collector_drop_monitor: [
         "admin:dashboard:view",
         "admin:bids:read",
         "admin:bids:write",
@@ -246,6 +381,8 @@ export const PERMISSION_GROUPS = {
     ],
     scam_moderator: [
         "admin:dashboard:view",
+        "admin:moderation:read",
+        "admin:moderation:write",
         "admin:scammers:read",
         "admin:scammers:write",
         "admin:scammers:verify",
@@ -254,6 +391,26 @@ export const PERMISSION_GROUPS = {
         "admin:media:read",
         "admin:media:write",
     ],
+    /*
+     * ── The money-path override, in one narrow preset ─────────────────────────
+     *
+     * `admin:orders:payment-override` appears HERE AND NOWHERE ELSE: not in
+     * `ROLE_PERMISSION_BUNDLES` (so no role confers it), not in
+     * `trust_and_safety`, not in `customer_support`. Picking this preset, or
+     * ticking the single checkbox it makes visible, is the only way a non-admin
+     * ever gets to declare a manual payment received, extend a payment window,
+     * or reject a proof as fraud (which cancels the order and enqueues a 7-day
+     * hard ban).
+     *
+     * `admin:orders:read` rides with it because reviewing a proof without being
+     * able to open the order is not a usable grant — but note there is no
+     * `admin:orders:write`: this preset cannot edit orders, only decide payments.
+     */
+    payment_reviewer: [
+        "admin:dashboard:view",
+        "admin:orders:read",
+        "admin:orders:payment-override",
+    ],
     maintenance_employee: [
         "admin:dashboard:view",
         "admin:maintenance:view-server-errors",
@@ -272,6 +429,13 @@ export const PERMISSION_GROUPS = {
          */
         "admin:maintenance:view-gateway-events",
         "admin:maintenance:view-obligations",
+        /*
+         * View-only. `clear-cache` is deliberately NOT granted here — same
+         * exclusion as `purge-errors`, which this role also lacks. Wiping a
+         * repository's cache site-wide is a blunter action than looking at one;
+         * admin role bypasses this map entirely when it's actually needed.
+         */
+        "admin:maintenance:view-cache",
     ],
 };
 // ============================================================================
@@ -373,7 +537,7 @@ export const ROUTE_PERMISSION_MAP = {
  */
 const STORE_CAPABILITY_MAP = {
     advanced_listing_types: true,
-    host_auctions: true,
+    host_collector_drops: true,
     host_preorders: true,
     create_categories: true,
     suggest_brands: true,
@@ -491,6 +655,16 @@ export const PERMISSION_DOMAINS = [
     },
     { label: "Events", prefix: "admin:events:|admin:event-entries:" },
     { label: "Support & Safety", prefix: "admin:support-tickets:|admin:scammers:" },
+    /*
+     * 🛑 Moderation had NO domain until 2026-11-08, so `admin:moderation:read`
+     * and `admin:roles:read` had no checkbox in the employee-permission editor
+     * and no row in the permissions catalogue — they were declarable in code and
+     * ungrantable in the UI. That is the reason the moderation key was bolted
+     * onto the `employee` role bundle instead, which is the widening this lane
+     * exists to undo. The domain must stay, or the grant becomes unreachable and
+     * someone will "fix" it by bundling it onto the role again.
+     */
+    { label: "Moderation", prefix: "admin:moderation:|admin:roles:" },
 ];
 /** True when `perm` starts with any of the `|`-separated prefixes in `prefix`. */
 export function matchesDomain(perm, prefix) {

package/dist/features/auth/repository/user.repository.d.ts

@@ -6,34 +6,56 @@ export declare class UserRepository extends BaseRepository<UserDocument> {
     static readonly SIEVE_FIELDS: FirebaseSieveFields;
     constructor();
     /**
-     * Plaintext PII. **Opt-in and named** — for the account's own settings page,
-     * the payout run, and any mail that has to reach the person.
+     * ── THE role dual-read, at the REPOSITORY BOUNDARY (1.43) ────────────────
+     *
+     * Normalises `role` ⇄ `roles` ⇄ `primaryRole` on EVERY read path — findById,
+     * findBy, the Sieve list, findByRole, every ad-hoc query — because they all
+     * map through `mapDoc`, which is exactly what `BaseRepository.mapDoc`
+     * documents it is there for.
+     *
+     * 🛑 Why it is here and not in an adapter. The `altRegionName` rename put its
+     * dual-read in an adapter that only the LIST route used, while pages kept
+     * receiving the RAW document from `getCategoryBySlug`. Result: 200 OK,
+     * content silently blank, and no typecheck could have caught it. For a ROLE
+     * field the equivalent failure is not a blank block — it is a user silently
+     * losing or gaining access. So the normalisation lives at the one place
+     * every reader passes through.
+     *
+     * Three guarantees for callers:
+     *   1. `roles` is always a non-empty, alias-folded, de-duplicated array.
+     *   2. `primaryRole` is always a role the user actually holds (display only).
+     *   3. `role` is overwritten with the HIGHEST-RANKED held role — not with
+     *      `primaryRole`. Deliberate: any guard not yet converted to the set
+     *      compares the scalar against a hierarchy, so handing it the highest
+     *      rank under-grants nothing such a comparison would have allowed. Using
+     *      `primaryRole` here would reintroduce the exact lockout 1.43 removes
+     *      (admin whose primary reads "user" fails `role === "admin"`).
+     *
+     * Remove once `scripts/backfill-user-roles.mjs --apply --drop-old` has run
+     * and no stored document is missing `roles`.
+     */
+    protected mapDoc<D = UserDocument>(snap: Parameters<BaseRepository<UserDocument>["mapDoc"]>[0]): D;
+    /**
+     * Plaintext PII. **Opt-in and named** — for the account's own settings page
+     * and any mail that has to reach the person.
+     *
+     * 🛑 `payoutDetails`/`shippingConfig` moved to `sellerProfiles/{uid}`
+     * (2026-11-05) — `SellerProfileRepository.revealProfile` is their
+     * equivalent now, not this method.
      */
     revealUser(doc: UserDocument): UserPlain;
     /** As `revealUser`, for a list read. */
     revealUsers(docs: readonly UserDocument[]): UserPlain[];
     /**
      * Masked PII — **the default for every admin list and every public
-     * surface.** Decrypts first, then masks, because the mask helpers refuse
-     * ciphertext by design.
+     * surface.**
      *
-     * `payoutDetails` and `shippingConfig` are decrypted and then masked
-     * member-by-member: a UPI handle or account number reaching an admin table
-     * unmasked is the most damaging value this document carries.
+     * 🛑 `payoutDetails`/`shippingConfig` moved to `sellerProfiles/{uid}` —
+     * `SellerProfileRepository.maskedProfile` is their equivalent now.
      */
     maskedUser(doc: UserDocument): UserPlain;
     /** As `maskedUser`, for a list read. */
     maskedUsers(docs: readonly UserDocument[]): UserPlain[];
-    /**
-     * Mask every string member of an already-decrypted nested object.
-     *
-     * The field list is derived from the object rather than hard-coded, because
-     * `USER_PII_FIELDS` does not name these members and a second list here would
-     * have to be kept in step with `decryptPayoutDetails`'s own (Root Cause #42).
-     * Every string in a payout or shipping block is sensitive, so "all of them"
-     * is the correct list, not an approximation.
-     */
-    private maskNested;
     /**
      * Declared, not hand-rolled.
      *
@@ -59,15 +81,6 @@ export declare class UserRepository extends BaseRepository<UserDocument> {
      * searchable without anyone having to remember to re-run the backfill.
      */
     protected buildTokensIndexFor(data: Record<string, JsonValue>): Record<string, string[]> | null;
-    /**
-     * The base hook, plus the nested objects it cannot see.
-     *
-     * `piiFields` is a flat list of top-level names, so a nested blob has to be
-     * encrypted separately. Calling `super.applyWriteHooks` FIRST keeps a single
-     * encryption path with one extra step on top, rather than two parallel paths
-     * that have to agree — which is what the hand-rolled override was.
-     */
-    protected applyWriteHooks<D extends object>(data: D): D;
     createWithId(id: string, data: Partial<UserPlain>): Promise<UserDocument>;
     create(input: Omit<UserPlain, "id" | "createdAt" | "updatedAt">): Promise<UserDocument>;
     findByUid(uid: string): Promise<UserDocument | null>;
@@ -81,6 +94,17 @@ export declare class UserRepository extends BaseRepository<UserDocument> {
     findBySlug(slug: string): Promise<UserDocument | null>;
     findByEmail(email: string): Promise<UserDocument | null>;
     findByPhone(phoneNumber: string): Promise<UserDocument | null>;
+    /**
+     * Every user HOLDING `role` — including those who hold it alongside others.
+     *
+     * 🛑 `array-contains` on `roles`, not `== role`. An equality query on the
+     * legacy scalar would return only accounts whose single highest-ranked role
+     * happens to be this one, so a `seller` who is also an `employee` would be
+     * missing from the seller list — silently, with a 200.
+     *
+     * Takes the role through `rolesOf` first so `findByRole("moderator")`
+     * resolves to the folded `employee` instead of matching nothing.
+     */
     findByRole(role: UserRole): Promise<UserDocument[]>;
     findVerified(limit?: number): Promise<UserDocument[]>;
     findActive(limit?: number): Promise<UserDocument[]>;
@@ -94,6 +118,37 @@ export declare class UserRepository extends BaseRepository<UserDocument> {
     markEmailAsVerified(uid: string): Promise<UserDocument>;
     disable(uid: string): Promise<UserDocument>;
     enable(uid: string): Promise<UserDocument>;
+    /**
+     * ── The role SET writers ─────────────────────────────────────────────────
+     *
+     * 🛑 All three funnel through `setRoles`, which is the only method that
+     * writes a role field. One writer means the three fields can never drift
+     * apart in storage the way they could if `addRole` patched `roles` while
+     * something else patched `role`.
+     *
+     * `primaryRole` is preserved when the user still holds it and re-derived
+     * when they do not — removing someone's primary role must not leave a
+     * display label pointing at access they no longer have.
+     */
+    setRoles(uid: string, roles: readonly UserRole[], opts?: {
+        primaryRole?: UserRole;
+    }): Promise<UserDocument>;
+    /**
+     * ADD a role — the owner's actual requirement: *"upgrading someone is
+     * ADDING a role, not replacing the one they have."* A no-op when already
+     * held; throws when it would exceed `getMaxRolesPerUser()`.
+     */
+    addRole(uid: string, role: UserRole): Promise<UserDocument>;
+    /** REMOVE a role. Refuses to leave an account with no role at all. */
+    removeRole(uid: string, role: UserRole): Promise<UserDocument>;
+    /** Change which held role is DISPLAYED. Grants and revokes nothing. */
+    setPrimaryRole(uid: string, role: UserRole): Promise<UserDocument>;
+    /**
+     * @deprecated REPLACES the whole role set with one role. Kept because the
+     * admin role-change route and the `becomeSeller` flow still call it, but
+     * "upgrade" should be `addRole` — replacing is what loses a seller their
+     * buyer role. Audit each remaining caller before deleting this.
+     */
     updateRole(uid: string, role: UserRole): Promise<UserDocument>;
     updateProfile(uid: string, data: {
         displayName?: string;
@@ -107,15 +162,20 @@ export declare class UserRepository extends BaseRepository<UserDocument> {
         avatarMetadata?: UserDocument["avatarMetadata"];
     }): Promise<UserDocument>;
     isEmailRegistered(email: string): Promise<boolean>;
+    /**
+     * How many users HOLD `role`. `array-contains`, matching `findByRole` —
+     * the count and the list must not disagree about what "a seller" is.
+     *
+     * ⚠ Counts no longer partition: a seller+employee is counted in both, so
+     * the role counts sum to more than the user total. That is correct under a
+     * role set; any dashboard presenting them as a pie chart is now wrong.
+     */
     countByRole(role: UserRole): Promise<number>;
     countActive(): Promise<number>;
     countDisabled(): Promise<number>;
     countNewSince(since: Date): Promise<number>;
     updateLoginMetadata(uid: string): Promise<void>;
     list(model: SieveModel): Promise<FirebaseSieveResult<UserDocument>>;
-    findByStoreSlug(storeSlug: string): Promise<UserDocument | null>;
     updateStoreApproval(uid: string, storeStatus: "pending" | "approved" | "rejected"): Promise<UserDocument>;
-    listSellers(model: SieveModel): Promise<FirebaseSieveResult<UserDocument>>;
-    listSellersForAdmin(model: SieveModel): Promise<FirebaseSieveResult<UserDocument>>;
 }
 export declare const userRepository: UserRepository;