@blamejs/blamejs-shop 0.4.17 → 0.4.18

package/lib/admin.js

@@ -68,6 +68,93 @@ var ACTIVITY_PANEL_LIMIT = 50;
 // and every write is drop-silent / fire-and-forget.
 var _errorLogSink = null;
 
+// ---- multi-operator RBAC model -----------------------------------------
+//
+// A single shared ADMIN_API_KEY guarded the whole console historically.
+// Per-operator identity layers on without weakening that gate: the
+// ADMIN_API_KEY remains the bootstrap / break-glass credential, mapped to
+// the OWNER role so an upgrade never locks the operator out. With zero
+// operator rows the console behaves byte-for-byte as before — every check
+// below resolves the ADMIN_API_KEY caller to owner, and owner holds every
+// permission.
+//
+// Enforcement lives at the SAME chokepoint the bearer gate always used —
+// the `_wrap` wrapper (and its `W`/`R` aliases). Every mutating route
+// already names its audit action (`W("product.update", ...)`); the action
+// is mapped to a required permission, so read-only operators are denied on
+// the verb itself, not merely hidden in the nav. Read routes (`R`, no
+// audit action) demand no permission beyond a valid credential.
+
+// The three built-in roles and their permission grants. `owner` holds the
+// full set including operator management; `manager` covers catalog /
+// orders / customers / marketing writes; `viewer` is read-only — it holds
+// NO write permission, so every `W`-wrapped route refuses it. The role set
+// is the v1-defensible surface; operators wanting finer-grained custom
+// roles compose lib/operator-roles.js on top.
+var OPERATOR_PERMISSIONS = Object.freeze([
+  "catalog.write",   // products, variants, prices, media, inventory, collections, merchandising, marketing content
+  "orders.write",    // orders, returns, exchanges, refunds, fulfilment, exports, quotes, gift cards
+  "customers.write", // customer records, segments, notes, store credit
+  "settings.write",  // shop configuration
+  "operators.manage", // create / disable / re-role other operators
+]);
+
+var ROLE_GRANTS = Object.freeze({
+  owner:   Object.freeze(OPERATOR_PERMISSIONS.slice()),
+  manager: Object.freeze(["catalog.write", "orders.write", "customers.write"]),
+  viewer:  Object.freeze([]),
+});
+
+// Map a `W(...)` audit-action's first segment to the permission it
+// requires. Every mutating admin route is covered; an action whose prefix
+// is not listed falls back to `catalog.write` (the broad merchandising
+// grant) so a newly-added write route is gated rather than silently open.
+var _ACTION_PERMISSION = Object.freeze({
+  // catalog / merchandising / marketing content
+  product: "catalog.write", variant: "catalog.write", price: "catalog.write",
+  catalog: "catalog.write", collection: "catalog.write", media: "catalog.write",
+  inventory: "catalog.write", search_ranking: "catalog.write",
+  search_suggestion: "catalog.write", trust_badge: "catalog.write",
+  gift: "catalog.write", preorder: "catalog.write", quantity_discount: "catalog.write",
+  auto_discount: "catalog.write", coupon_policy: "catalog.write",
+  promo_banner: "catalog.write", announcement: "catalog.write", blog: "catalog.write",
+  page: "catalog.write", help: "catalog.write", survey: "catalog.write",
+  hours: "catalog.write", delivery_holiday: "catalog.write",
+  delivery_transit: "catalog.write", tax_rate: "catalog.write",
+  shipping_zone: "catalog.write", payment_domain: "catalog.write",
+  webhook: "catalog.write", subscription_plan: "catalog.write", loyalty: "catalog.write",
+  // orders / fulfilment / post-purchase
+  order: "orders.write", return: "orders.write", exchange: "orders.write",
+  rating: "orders.write", review: "orders.write", question: "orders.write",
+  answer: "orders.write", pick_list: "orders.write", pickup: "orders.write",
+  export: "orders.write", tax_filing: "orders.write", quote: "orders.write",
+  gift_card: "orders.write", subscription: "orders.write",
+  cart_recovery_code: "orders.write", support: "orders.write",
+  // customers
+  customer: "customers.write", customer_segment: "customers.write",
+  // shop configuration
+  config: "settings.write",
+  // operator management (mounted by this feature)
+  operator: "operators.manage",
+});
+
+// Permission a `W(auditAction, ...)` route requires, derived from the
+// action's first dotted segment. Unmapped prefixes default to the broad
+// merchandising write so an un-mapped new route fails closed for viewers.
+function _permissionForAction(auditAction) {
+  if (typeof auditAction !== "string" || !auditAction.length) return "catalog.write";
+  var seg = auditAction.split(".")[0];
+  return _ACTION_PERMISSION[seg] || "catalog.write";
+}
+
+// True when `role` grants `permission`. The owner role always grants
+// everything; an unknown role grants nothing (fails closed).
+function _roleGrants(role, permission) {
+  var grants = ROLE_GRANTS[role];
+  if (!grants) return false;
+  return grants.indexOf(permission) !== -1;
+}
+
 // Per-request store for the double-submit CSRF token. The admin console is
 // container-only and has no locale ALS (unlike the storefront), so it gets
 // its own: a sync middleware in `mount()` seeds the request's `req.csrfToken`
@@ -368,12 +455,22 @@ function _secureForReq(req) {
 }
 function _adminCookieName(secure) { return secure ? ADMIN_COOKIE_NAME_SECURE : ADMIN_COOKIE_NAME; }
 
-function _setAdminCookie(req, res) {
+function _setAdminCookie(req, res, operator) {
   var secure = _secureForReq(req);
-  _adminJar().writeSealed(res, _adminCookieName(secure), JSON.stringify({
+  // The bootstrap / break-glass sign-in (ADMIN_API_KEY) sets `admin:true`
+  // with no operator identity → resolves to the owner role. A per-operator
+  // sign-in additionally carries the operator id + built-in role, so the
+  // resolver names WHO is acting and gates them on their role's grants.
+  var claims = {
     admin: true,
     exp:   Date.now() + b.constants.TIME.hours(12),
-  }), { expires: new Date(Date.now() + b.constants.TIME.hours(12)), secure: secure });
+  };
+  if (operator && typeof operator === "object" && operator.id) {
+    claims.operator_id = String(operator.id);
+    claims.role        = String(operator.role || "viewer");
+  }
+  _adminJar().writeSealed(res, _adminCookieName(secure), JSON.stringify(claims),
+    { expires: new Date(Date.now() + b.constants.TIME.hours(12)), secure: secure });
 }
 function _clearAdminCookie(req, res) {
   // Expire-now must match the live request's protocol so the cleared
@@ -404,26 +501,104 @@ function _takeGiftCardReveal(req, res, id) {
   try { env = JSON.parse(raw); } catch (_e) { return null; }
   return (env && env.id === id && typeof env.code === "string") ? env.code : null;
 }
-function _adminCookieValid(req) {
+
+// One-time reveal of a freshly-minted operator API key. Same Post/Redirect/
+// Get reveal pattern as the gift-card code: the plaintext is stashed in a
+// sealed, HttpOnly, /admin-scoped cookie and read exactly once on the
+// redirect target — never placed in the URL / Location / history / access
+// log. A reload after the reveal shows the operator row with no key.
+var OPERATOR_KEY_REVEAL_COOKIE = "op_key_reveal";
+function _stashOperatorKeyReveal(res, id, plaintext) {
+  _adminJar().writeSealed(res, OPERATOR_KEY_REVEAL_COOKIE, JSON.stringify({ id: id, key: plaintext }),
+    { expires: new Date(Date.now() + b.constants.TIME.hours(1)) });
+}
+function _takeOperatorKeyReveal(req, res) {
+  var raw = _adminJar().readSealed(req, OPERATOR_KEY_REVEAL_COOKIE);
+  if (raw === null) return null;
+  _adminJar().clear(res, OPERATOR_KEY_REVEAL_COOKIE);
+  var env;
+  try { env = JSON.parse(raw); } catch (_e) { return null; }
+  return (env && typeof env.id === "string" && typeof env.key === "string") ? env : null;
+}
+// Read the sealed admin-session cookie's claims, or null when absent /
+// invalid / expired. Returns `{ admin, exp, operator_id?, role? }` so the
+// resolver can name a per-operator session; `_adminCookieValid` keeps the
+// boolean shape every existing caller expects.
+function _adminCookieClaims(req) {
   // Resolve the prefixed name first and the bare name second so an admin
   // session set in either environment (or mid-rollout) is recognised.
   var raw = _adminJar().readSealed(req, ADMIN_COOKIE_NAME_SECURE);
   if (raw === null) raw = _adminJar().readSealed(req, ADMIN_COOKIE_NAME);
-  if (raw === null) return false;
+  if (raw === null) return null;
   var env;
-  try { env = JSON.parse(raw); } catch (_e) { return false; }
-  return !!(env && env.admin === true && env.exp && env.exp > Date.now());
+  try { env = JSON.parse(raw); } catch (_e) { return null; }
+  if (!(env && env.admin === true && env.exp && env.exp > Date.now())) return null;
+  return env;
+}
+function _adminCookieValid(req) {
+  return !!_adminCookieClaims(req);
 }
 
 // HTML-page auth: a valid admin cookie OR the bearer token (so existing
 // tooling that sends the header still reaches the dashboard). Never
 // throws — a missing vault surfaces as "not authed" so the caller can
-// render the login form rather than 500.
+// render the login form rather than 500. NOTE: this resolves only the
+// CREDENTIAL — permission enforcement happens at the write chokepoint
+// (`_wrap`), so a viewer reaching a read page here is correct.
 function _htmlAuthed(req, expectedToken) {
   if (_authOk(_readBearer(req), expectedToken)) return true;
   try { return _adminCookieValid(req); } catch (_e) { return false; }
 }
 
+// Resolve the acting operator for a request. Returns an actor:
+//   { kind: "owner"|"operator", operator_id, role, via }
+// or null when no valid credential is presented. Resolution order:
+//   1. ADMIN_API_KEY bearer  → owner (bootstrap / break-glass).
+//   2. Per-operator API-key bearer → that operator (role from the row).
+//   3. Admin session cookie  → owner (bootstrap cookie) OR the operator
+//      named in the cookie's claims (role re-read from the live row so a
+//      mid-session role change / disable takes effect immediately).
+// The ADMIN_API_KEY path is timing-safe and checked first so it always
+// works even when the operator-accounts table is empty or unwired.
+async function _resolveActor(req, authCtx) {
+  var bearer = _readBearer(req);
+  if (_authOk(bearer, authCtx.expectedToken)) {
+    return { kind: "owner", operator_id: "owner", role: "owner", via: "admin_api_key" };
+  }
+  var accounts = authCtx.operatorAccounts;
+  // Per-operator bearer API key. timingSafeEqual lives inside verifyApiKey,
+  // and an unknown key burns the same compare as a known one.
+  if (bearer && accounts) {
+    var byKey = null;
+    try { byKey = await accounts.verifyApiKey(bearer); } catch (_e) { byKey = null; }
+    if (byKey) {
+      return { kind: "operator", operator_id: byKey.id, role: byKey.role, via: "operator_api_key" };
+    }
+  }
+  // Session cookie.
+  var claims = null;
+  try { claims = _adminCookieClaims(req); } catch (_e) { claims = null; }
+  if (!claims) return null;
+  if (!claims.operator_id) {
+    // Bootstrap cookie — ADMIN_API_KEY pasted in the browser, owner role.
+    return { kind: "owner", operator_id: "owner", role: "owner", via: "admin_cookie" };
+  }
+  // Per-operator session. Re-read the live row so a role change or a
+  // disable applied mid-session is honoured on the very next request
+  // rather than waiting for the 12h cookie to expire.
+  if (accounts) {
+    var live = null;
+    try { live = await accounts.getById(claims.operator_id); } catch (_e) { live = null; }
+    if (!live || live.status !== "active") return null;
+    return { kind: "operator", operator_id: live.id, role: live.role, via: "operator_cookie" };
+  }
+  // No accounts handle wired but the cookie names an operator — treat the
+  // sealed claim's role as authoritative (the cookie is vault-sealed, so it
+  // can't be forged); fail closed to viewer if the role is unexpected.
+  var role = ROLE_GRANTS[claims.role] ? claims.role : "viewer";
+  return { kind: "operator", operator_id: String(claims.operator_id), role: role, via: "operator_cookie" };
+}
+
 function _problem(res, status, code, detail) {
   return b.problemDetails.send(res, {
     type:   "/problems/" + code,
@@ -517,13 +692,54 @@ function _safeNotice(e, auditAction) {
 }
 
 function _wrap(handler, opts) {
-  // Every admin handler routes through this wrapper: bearer-token
-  // gate, error-to-problem-details translation, audit write on the
-  // mutating ops. `opts.audit` is the audit action name; omit for
-  // read-only routes.
+  // Every admin handler routes through this wrapper — the ONE chokepoint
+  // where the admin credential is checked. It resolves the acting operator
+  // (owner via ADMIN_API_KEY, or a per-operator key / session), enforces
+  // the route's permission on the mutating ops, translates thrown errors
+  // to problem-details, and writes the success audit. `opts.audit` is the
+  // audit action name (present on writes, absent on read-only routes);
+  // `opts.authCtx` carries the expected token + the operator-accounts
+  // handle + the audit-log peer.
+  var authCtx = opts.authCtx || { expectedToken: opts.expectedToken };
   return async function (req, res) {
-    var token = _readBearer(req);
-    if (!_authOk(token, opts.expectedToken)) return _problem(res, 401, "unauthorized");
+    var actor = await _resolveActor(req, authCtx);
+    if (!actor) return _problem(res, 401, "unauthorized");
+    // Permission gate — only mutating routes (those naming an audit
+    // action) require a write permission. Read routes (R, no audit
+    // action) admit any authenticated operator, viewer included. The
+    // owner role always passes; a viewer holds no write grant, so every
+    // W-wrapped route refuses it on the verb itself — not merely hidden
+    // in the nav.
+    if (opts.audit) {
+      var permission = _permissionForAction(opts.audit);
+      if (!_roleGrants(actor.role, permission)) {
+        // Audit the denied attempt through the chained operator log when
+        // wired (drop-silent — a recording failure must never change the
+        // 403 the operator sees), plus the framework audit sink.
+        if (authCtx.operatorAuditLog && typeof authCtx.operatorAuditLog.record === "function") {
+          try {
+            await authCtx.operatorAuditLog.record({
+              actor_type:    "operator",
+              actor_id:      actor.operator_id,
+              action:        "permission.denied:" + opts.audit,
+              resource_kind: "operator_permission",
+              resource_id:   permission,
+              before:        null,
+              after:         { role: actor.role, required: permission },
+            });
+          } catch (_e) { /* drop-silent */ }
+        }
+        b.audit.safeEmit({
+          action:   AUDIT_NAMESPACE + ".permission.denied",
+          outcome:  "failure",
+          metadata: { action: opts.audit, role: actor.role, required: permission },
+        });
+        return _problem(res, 403, "forbidden", "Your role does not permit this action.");
+      }
+    }
+    // Expose the resolved actor so a handler can stamp WHO into a downstream
+    // record (operator-management routes read this).
+    req.operatorActor = actor;
     try {
       var result = await handler(req, res);
       if (opts.audit && result && result !== false) {
@@ -619,13 +835,24 @@ function mount(router, deps) {
   var errorLog        = deps.errorLog || null;
   _errorLogSink       = errorLog;
 
+  // Multi-operator staff console. When `deps.operatorAccounts` is wired the
+  // /admin/operators screen mounts, per-operator credentials authenticate
+  // alongside ADMIN_API_KEY, and the role gate enforces read-only / scoped
+  // operators on the write chokepoint. ADMIN_API_KEY ALWAYS works as the
+  // bootstrap / break-glass owner credential regardless — with no operator
+  // rows wired or present, the console behaves exactly as before. The
+  // operator-audit-log peer (defaults ON when the framework audit chain is
+  // booted) chains every operator-management action + role-denied attempt.
+  var operatorAccounts = deps.operatorAccounts || null;
+  var operatorAuditLog = deps.operatorAuditLog || null;
+
   // Which optional console sections are wired — gates their nav links so a
   // signed-in admin is never sent to a route that wasn't mounted. Passed
   // into every authed render call as `nav_available`.
   // `reports` is always present in the nav (read-only sales summary needs no
   // extra dep); its route mounts unconditionally and renders an unconfigured
   // notice when the salesReports primitive isn't wired.
-  var navAvailable = { analytics: !!deps.analytics, returns: !!returns, reviews: !!reviews, productQa: !!productQa, subscriptions: !!deps.subscriptions, preorder: !!deps.preorder, webhooks: !!deps.webhooks, collections: !!deps.collections, customers: !!deps.customers, customerSegments: !!customerSegments, giftcards: !!deps.giftcards, announcementBar: !!deps.announcementBar, promoBanners: !!deps.promoBanners, blog: !!deps.blog, knowledgeBase: !!deps.knowledgeBase, customerSurveys: !!deps.customerSurveys, storefrontPages: !!deps.storefrontPages, businessHours: !!deps.businessHours, taxRates: !!deps.taxRates, shippingZones: !!deps.shippingZones, deliveryEstimate: !!deps.deliveryEstimate, autoDiscount: !!deps.autoDiscount, discountAllocation: !!deps.discountAllocation, quantityDiscounts: !!deps.quantityDiscounts, loyalty: !!deps.loyalty, pickLists: !!pickLists, salesTaxFilings: !!salesTaxFilings, shippingLabels: !!shippingLabels, supportTickets: !!supportTickets, complianceExport: !!complianceExport, orderExchanges: !!orderExchanges, orderRatings: !!orderRatings, clickAndCollect: !!clickAndCollect, giftOptions: !!giftOptions, searchRanking: !!searchRanking, searchSuggestions: !!searchSuggestions, trustBadges: !!trustBadges, orderExport: !!orderExport, auditLog: auditLog, errorLog: !!errorLog, carts: !!cart, inventoryLocations: !!inventoryLocations, inventoryReceive: !!inventoryReceive, stockTransfers: !!stockTransfers, inventoryWriteoffs: !!inventoryWriteoffs, quotes: !!deps.quotes, emailCampaigns: !!emailCampaigns };
+  var navAvailable = { analytics: !!deps.analytics, returns: !!returns, reviews: !!reviews, productQa: !!productQa, subscriptions: !!deps.subscriptions, preorder: !!deps.preorder, webhooks: !!deps.webhooks, collections: !!deps.collections, customers: !!deps.customers, customerSegments: !!customerSegments, giftcards: !!deps.giftcards, announcementBar: !!deps.announcementBar, promoBanners: !!deps.promoBanners, blog: !!deps.blog, knowledgeBase: !!deps.knowledgeBase, customerSurveys: !!deps.customerSurveys, storefrontPages: !!deps.storefrontPages, businessHours: !!deps.businessHours, taxRates: !!deps.taxRates, shippingZones: !!deps.shippingZones, deliveryEstimate: !!deps.deliveryEstimate, autoDiscount: !!deps.autoDiscount, discountAllocation: !!deps.discountAllocation, quantityDiscounts: !!deps.quantityDiscounts, loyalty: !!deps.loyalty, pickLists: !!pickLists, salesTaxFilings: !!salesTaxFilings, shippingLabels: !!shippingLabels, supportTickets: !!supportTickets, complianceExport: !!complianceExport, orderExchanges: !!orderExchanges, orderRatings: !!orderRatings, clickAndCollect: !!clickAndCollect, giftOptions: !!giftOptions, searchRanking: !!searchRanking, searchSuggestions: !!searchSuggestions, trustBadges: !!trustBadges, orderExport: !!orderExport, auditLog: auditLog, errorLog: !!errorLog, carts: !!cart, inventoryLocations: !!inventoryLocations, inventoryReceive: !!inventoryReceive, stockTransfers: !!stockTransfers, inventoryWriteoffs: !!inventoryWriteoffs, quotes: !!deps.quotes, emailCampaigns: !!emailCampaigns, operators: !!operatorAccounts };
 
   try { b.audit.registerNamespace(AUDIT_NAMESPACE); } catch (_e) { /* idempotent */ }
 
@@ -647,26 +874,90 @@ function mount(router, deps) {
     });
   }
 
+  // The auth context every wrapped route resolves through — the bootstrap
+  // token plus the per-operator credential store + the chained audit peer.
+  // Threaded into `_wrap` so the single chokepoint owns BOTH the credential
+  // resolution and the role gate.
+  var authCtx = {
+    expectedToken:    expectedToken,
+    operatorAccounts: operatorAccounts,
+    operatorAuditLog: operatorAuditLog,
+  };
+
   var W = function (auditAction, h) {
-    return _wrap(h, { expectedToken: expectedToken, audit: auditAction });
+    var wrapped = _wrap(h, { authCtx: authCtx, audit: auditAction });
+    // Tag the wrapped fn with its audit action so `_pageOrApi` can derive
+    // the same write permission for the browser-form (cookie) branch
+    // without each route having to restate it.
+    wrapped._adminWriteAction = auditAction;
+    return wrapped;
   };
   var R = function (h) {
-    return _wrap(h, { expectedToken: expectedToken });
+    return _wrap(h, { authCtx: authCtx });
   };
 
   // Content-negotiate one endpoint between the JSON API and the HTML
-  // console: a bearer token routes to `apiHandler` (the JSON contract,
-  // unchanged for tooling); a browser admin-cookie session routes to
-  // `htmlHandler` (the rendered console page). Unauthenticated GETs show
-  // the sign-in form; other methods bounce to /admin.
+  // console: a bearer credential (ADMIN_API_KEY or a per-operator key)
+  // routes to `apiHandler` (the JSON contract, unchanged for tooling); a
+  // browser admin-cookie session routes to `htmlHandler` (the rendered
+  // console page). Unauthenticated GETs show the sign-in form; other
+  // methods bounce to /admin. The actor is stamped onto `req` so the html
+  // handler can render WHO is signed in. NOTE: `_pageOrApi` wraps GET
+  // reads (and a handful of negotiated POSTs whose page form posts a
+  // create); the inner apiHandler is itself a `W(...)`/`R(...)` wrap, so
+  // the permission gate still fires on the write — this resolver only
+  // picks the response SHAPE, never bypasses the gate.
+  // The html/cookie branch of a negotiated POST runs the mutation inline,
+  // so the role gate (which lives in the JSON apiHandler's W-wrap) would
+  // otherwise be skipped on the browser-form path. `W(...)` tags its
+  // wrapped fn with `_adminWriteAction`; reading it here applies the SAME
+  // permission to the cookie branch with zero per-route restatement. A
+  // negotiated GET passes a plain (read) apiHandler with no tag → no gate.
   function _pageOrApi(isGet, apiHandler, htmlHandler) {
+    var writeAction = (apiHandler && apiHandler._adminWriteAction) || null;
     return async function (req, res) {
-      if (_authOk(_readBearer(req), expectedToken)) return apiHandler(req, res);
+      var bearer = _readBearer(req);
+      // Any valid bearer (owner or operator) gets the JSON contract.
+      if (_authOk(bearer, expectedToken)) return apiHandler(req, res);
+      if (bearer && operatorAccounts) {
+        var byKey = null;
+        try { byKey = await operatorAccounts.verifyApiKey(bearer); } catch (_e) { byKey = null; }
+        if (byKey) return apiHandler(req, res);
+      }
       // Mirror _htmlAuthed: a missing vault makes the cookie check throw;
       // treat that as "not authed" rather than 500-ing the route.
       var cookieOk = false;
       try { cookieOk = _adminCookieValid(req); } catch (_e) { cookieOk = false; }
-      if (cookieOk) return htmlHandler(req, res);
+      if (cookieOk) {
+        // Role gate on the browser-form mutation path — a viewer reaching a
+        // create/edit form POST is refused on the verb, not merely hidden in
+        // the nav. Resolve the actor and check the write permission; deny
+        // with a 403 page when the role doesn't grant it.
+        if (writeAction) {
+          var actor = await _resolveActor(req, authCtx);
+          if (!actor) { return _redirect(res, "/admin"); }
+          var perm = _permissionForAction(writeAction);
+          if (!_roleGrants(actor.role, perm)) {
+            if (operatorAuditLog && typeof operatorAuditLog.record === "function") {
+              try {
+                await operatorAuditLog.record({
+                  actor_type: "operator", actor_id: actor.operator_id,
+                  action: "permission.denied:" + writeAction,
+                  resource_kind: "operator_permission", resource_id: perm,
+                  before: null, after: { role: actor.role, required: perm },
+                });
+              } catch (_e) { /* drop-silent */ }
+            }
+            b.audit.safeEmit({
+              action: AUDIT_NAMESPACE + ".permission.denied", outcome: "failure",
+              metadata: { action: writeAction, role: actor.role, required: perm },
+            });
+            return _sendHtml(res, 403, _renderAdminForbidden(deps.shop_name, navAvailable, perm));
+          }
+          req.operatorActor = actor;
+        }
+        return htmlHandler(req, res);
+      }
       if (isGet) return _sendHtml(res, 200, renderAdminLogin({ shop_name: deps.shop_name }));
       return _redirect(res, "/admin");
     };
@@ -12441,6 +12732,16 @@ function mount(router, deps) {
 
     router.post("/admin/setup", async function (req, res) {
       if (!_htmlAuthed(req, expectedToken)) return _redirect(res, "/admin");
+      // Saving shop configuration is settings.write — owner only. A
+      // manager/viewer reaching the form POST is refused on the verb.
+      var setupActor = await _resolveActor(req, authCtx);
+      if (!setupActor || !_roleGrants(setupActor.role, "settings.write")) {
+        b.audit.safeEmit({
+          action: AUDIT_NAMESPACE + ".permission.denied", outcome: "failure",
+          metadata: { action: "config.put", role: setupActor ? setupActor.role : null, required: "settings.write" },
+        });
+        return _sendHtml(res, 403, _renderAdminForbidden(deps.shop_name, navAvailable, "settings.write"));
+      }
       var body = req.body || {};
       var values = {
         shop_name:     (typeof body.shop_name === "string"     ? body.shop_name     : "").trim(),
@@ -12483,6 +12784,241 @@ function mount(router, deps) {
     });
   }
 
+  // ---- multi-operator staff console -----------------------------------
+  //
+  // Mounted only when the deployment wires `deps.operatorAccounts`. The
+  // ADMIN_API_KEY caller (owner) bootstraps the first operator while authed
+  // via the break-glass key; thereafter each operator has their own login.
+  // Every mutation runs through `W("operator.*", ...)`, so the chokepoint
+  // enforces the `operators.manage` permission (owner-only) and audits both
+  // the action and any role-denied attempt — no per-route guard.
+  if (operatorAccounts) {
+    // The operator sign-in form — reachable unauthenticated (it IS the
+    // sign-in). An already-signed-in operator is bounced to the dashboard.
+    router.get("/admin/operators/signin", async function (req, res) {
+      if (_htmlAuthed(req, expectedToken)) return _redirect(res, "/admin");
+      _sendHtml(res, 200, renderOperatorSignin({ shop_name: deps.shop_name }));
+    });
+
+    // Operator email+password sign-in. NOT permission-gated — this IS the
+    // primary-credential challenge. On success it mints a per-operator
+    // session cookie carrying the operator id + role, so the resolver names
+    // WHO is acting on every subsequent request and gates them on their
+    // role. A miss re-renders the form with a generic notice (no oracle on
+    // which half — email vs password — failed).
+    router.post("/admin/operators/signin", async function (req, res) {
+      var body  = req.body || {};
+      var email = typeof body.email === "string" ? body.email : "";
+      var pass  = typeof body.password === "string" ? body.password : "";
+      var account = null;
+      try { account = await operatorAccounts.verifyPassword({ email: email, password: pass }); }
+      catch (_e) { account = null; }
+      if (!account) {
+        return _sendHtml(res, 401, renderOperatorSignin({ shop_name: deps.shop_name, error: true }));
+      }
+      try { _setAdminCookie(req, res, account); }
+      catch (e) {
+        if (e && e.code === "vault/not-initialized") {
+          return _sendHtml(res, 503, renderOperatorSignin({ shop_name: deps.shop_name }));
+        }
+        throw e;
+      }
+      // Chained audit of the successful staff sign-in when wired.
+      if (operatorAuditLog && typeof operatorAuditLog.record === "function") {
+        try {
+          await operatorAuditLog.record({
+            actor_type: "operator", actor_id: account.id,
+            action: "operator.signin", resource_kind: "operator_account",
+            resource_id: account.id, before: null, after: { role: account.role },
+          });
+        } catch (_e) { /* drop-silent */ }
+      }
+      _redirect(res, "/admin");
+    });
+
+    // The operators console — list + create form. Negotiated: bearer →
+    // JSON list, cookie → rendered page. The `R(...)`/list read admits any
+    // operator with a valid credential, but the CREATE/disable/role
+    // mutations below are gated on operators.manage, so a non-owner sees
+    // the page but every action 403s.
+    router.get("/admin/operators", _pageOrApi(true,
+      R(async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var status = url && url.searchParams.get("status");
+        var listOpts = {};
+        if (status === "active" || status === "disabled") listOpts.status = status;
+        var rows = await operatorAccounts.listAccounts(listOpts);
+        _json(res, 200, { rows: rows });
+        return false;
+      }),
+      async function (req, res) {
+        var rows = await operatorAccounts.listAccounts({});
+        var created = null;
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        if (url && url.searchParams.get("created")) created = url.searchParams.get("created");
+        // One-time API-key reveal (read-once, then cleared).
+        var reveal = null;
+        try { reveal = _takeOperatorKeyReveal(req, res); } catch (_e) { reveal = null; }
+        _sendHtml(res, 200, renderOperators({
+          shop_name: deps.shop_name, nav_available: navAvailable,
+          operators: rows, created_id: created, reveal: reveal,
+          actor: req.operatorActor || null,
+        }));
+      },
+    ));
+
+    // Create an operator. The first operator is created by the ADMIN_API_KEY
+    // owner; thereafter any owner can. `created_by` is the acting operator's
+    // id (or the "owner" sentinel for the break-glass key).
+    router.post("/admin/operators", _pageOrApi(false,
+      W("operator.create", async function (req, res) {
+        var body = req.body || {};
+        var account = await operatorAccounts.createAccount({
+          email:        body.email,
+          display_name: body.display_name,
+          password:     body.password,
+          role:         body.role,
+          mint_api_key: body.mint_api_key === "1" || body.mint_api_key === "on" || body.mint_api_key === true,
+          created_by:   (req.operatorActor && req.operatorActor.operator_id) || "owner",
+        });
+        _json(res, 201, account);
+        return account;
+      }),
+      async function (req, res) {
+        var body = req.body || {};
+        var made;
+        try {
+          made = await operatorAccounts.createAccount({
+            email:        body.email,
+            display_name: body.display_name,
+            password:     body.password,
+            role:         body.role,
+            mint_api_key: body.mint_api_key === "1" || body.mint_api_key === "on",
+            created_by:   (req.operatorActor && req.operatorActor.operator_id) || "owner",
+          });
+        } catch (e) {
+          var n = _safeNotice(e, "operator.create");
+          var rows = await operatorAccounts.listAccounts({});
+          return _sendHtml(res, n.status, renderOperators({
+            shop_name: deps.shop_name, nav_available: navAvailable,
+            operators: rows, notice: n.message, actor: req.operatorActor || null,
+          }));
+        }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".operator.create", outcome: "success", metadata: { id: made.id } });
+        // The freshly-minted API key (if any) is shown ONCE on the redirect
+        // target via a one-time sealed reveal cookie — never in the URL.
+        if (made.api_key) _stashOperatorKeyReveal(res, made.id, made.api_key);
+        _redirect(res, "/admin/operators?created=" + encodeURIComponent(made.id));
+      },
+    ));
+
+    // Disable an operator (the v1 revoke). Their password + API key stop
+    // authenticating on the next request; a live cookie session is refused
+    // by the resolver's live-row re-read.
+    router.post("/admin/operators/:id/disable", _pageOrApi(false,
+      W("operator.disable", async function (req, res) {
+        var out = await operatorAccounts.setStatus({
+          id: req.params.id, status: "disabled",
+          actor_id: (req.operatorActor && req.operatorActor.operator_id) || "owner",
+        });
+        _json(res, 200, out);
+        return out;
+      }),
+      _operatorActionHtml(function (req) {
+        return operatorAccounts.setStatus({
+          id: req.params.id, status: "disabled",
+          actor_id: (req.operatorActor && req.operatorActor.operator_id) || "owner",
+        });
+      }, "operator.disable"),
+    ));
+
+    router.post("/admin/operators/:id/enable", _pageOrApi(false,
+      W("operator.enable", async function (req, res) {
+        var out = await operatorAccounts.setStatus({
+          id: req.params.id, status: "active",
+          actor_id: (req.operatorActor && req.operatorActor.operator_id) || "owner",
+        });
+        _json(res, 200, out);
+        return out;
+      }),
+      _operatorActionHtml(function (req) {
+        return operatorAccounts.setStatus({
+          id: req.params.id, status: "active",
+          actor_id: (req.operatorActor && req.operatorActor.operator_id) || "owner",
+        });
+      }, "operator.enable"),
+    ));
+
+    // Change an operator's built-in role.
+    router.post("/admin/operators/:id/role", _pageOrApi(false,
+      W("operator.set_role", async function (req, res) {
+        var out = await operatorAccounts.setRole({
+          id: req.params.id, role: (req.body || {}).role,
+          actor_id: (req.operatorActor && req.operatorActor.operator_id) || "owner",
+        });
+        _json(res, 200, out);
+        return out;
+      }),
+      _operatorActionHtml(function (req) {
+        return operatorAccounts.setRole({
+          id: req.params.id, role: (req.body || {}).role,
+          actor_id: (req.operatorActor && req.operatorActor.operator_id) || "owner",
+        });
+      }, "operator.set_role"),
+    ));
+
+    // Rotate (or first-mint) an operator's per-operator API key. The new
+    // plaintext is revealed once on the redirect target.
+    router.post("/admin/operators/:id/rotate-key", _pageOrApi(false,
+      W("operator.rotate_key", async function (req, res) {
+        var out = await operatorAccounts.rotateApiKey({
+          id: req.params.id,
+          actor_id: (req.operatorActor && req.operatorActor.operator_id) || "owner",
+        });
+        _json(res, 200, out);
+        return out;
+      }),
+      async function (req, res) {
+        var out;
+        try {
+          out = await operatorAccounts.rotateApiKey({
+            id: req.params.id,
+            actor_id: (req.operatorActor && req.operatorActor.operator_id) || "owner",
+          });
+        } catch (e) {
+          var n = _safeNotice(e, "operator.rotate_key");
+          var rows = await operatorAccounts.listAccounts({});
+          return _sendHtml(res, n.status, renderOperators({
+            shop_name: deps.shop_name, nav_available: navAvailable,
+            operators: rows, notice: n.message, actor: req.operatorActor || null,
+          }));
+        }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".operator.rotate_key", outcome: "success", metadata: { id: out.id } });
+        if (out.api_key) _stashOperatorKeyReveal(res, out.id, out.api_key);
+        _redirect(res, "/admin/operators?created=" + encodeURIComponent(out.id));
+      },
+    ));
+  }
+
+  // Shared html-handler factory for the simple operator lifecycle POSTs
+  // (disable / enable / role) — run the mutation, surface a bad-input
+  // notice as a re-rendered page, otherwise PRG back to the list.
+  function _operatorActionHtml(mutate, auditAction) {
+    return async function (req, res) {
+      try { await mutate(req); }
+      catch (e) {
+        var n = _safeNotice(e, auditAction);
+        var rows = await operatorAccounts.listAccounts({});
+        return _sendHtml(res, n.status, renderOperators({
+          shop_name: deps.shop_name, nav_available: navAvailable,
+          operators: rows, notice: n.message, actor: req.operatorActor || null,
+        }));
+      }
+      b.audit.safeEmit({ action: AUDIT_NAMESPACE + "." + auditAction, outcome: "success", metadata: { id: req.params.id } });
+      _redirect(res, "/admin/operators");
+    };
+  }
+
   // ---- ping (auth check) ----------------------------------------------
 
   router.get("/admin/ping", R(async function (_req, res) {
@@ -12853,6 +13389,7 @@ var ADMIN_NAV_ITEMS = [
   { key: "hours",        href: "/admin/hours",        label: "Hours",        requires: "businessHours" },
   { key: "giftcards",    href: "/admin/gift-cards",    label: "Gift cards",   requires: "giftcards" },
   { key: "webhooks",     href: "/admin/webhooks",     label: "Webhooks",     requires: "webhooks" },
+  { key: "operators",    href: "/admin/operators",    label: "Operators",    requires: "operators" },
   { key: "integrations", href: "/admin/integrations", label: "Integrations" },
   { key: "setup",        href: "/admin/setup",        label: "Setup" },
 ];
@@ -12918,6 +13455,26 @@ function renderAdminConfirm(opts) {
   return _renderAdminShell(opts.shop_name, opts.heading || "Confirm", body, opts.active, opts.nav_available);
 }
 
+// 403 page shown when a signed-in operator's role does not grant the
+// permission a browser-form mutation requires. The required permission is
+// stated plainly so the operator knows what to ask the owner for. `perm`
+// is one of the closed OPERATOR_PERMISSIONS tokens (never untrusted), but
+// it is escaped anyway to keep the render escape-by-default.
+function _renderAdminForbidden(shopName, navAvailable, perm) {
+  var name = shopName || "blamejs.shop";
+  var body =
+    "<section class=\"mw-42\">" +
+      "<h2>Not permitted</h2>" +
+      "<div class=\"banner banner--err\">Your role does not permit this action.</div>" +
+      "<div class=\"panel\">" +
+        "<p>This action requires the <code>" + _htmlEscape(perm || "") + "</code> permission. " +
+        "Ask an owner to grant your account a role that includes it.</p>" +
+        "<a class=\"btn btn--ghost\" href=\"/admin\">Back to dashboard</a>" +
+      "</div>" +
+    "</section>";
+  return _renderAdminShell(name, "Not permitted", body, null, navAvailable);
+}
+
 function renderAdminLogin(opts) {
   opts = opts || {};
   var err = opts.error
@@ -12938,11 +13495,142 @@ function renderAdminLogin(opts) {
           "</label>" +
           "<button type=\"submit\" class=\"btn\">Sign in</button>" +
         "</form>" +
+        "<p class=\"signin-lede\"><a href=\"/admin/operators/signin\">Sign in as an operator &rarr;</a></p>" +
       "</div>" +
     "</div>";
   return _renderAdminShell(shopName, "Sign in", body, null);
 }
 
+// Per-operator email + password sign-in form. Distinct from the
+// ADMIN_API_KEY sign-in (renderAdminLogin) — that one is the bootstrap /
+// break-glass owner credential; this is the everyday staff login.
+function renderOperatorSignin(opts) {
+  opts = opts || {};
+  var err = opts.error
+    ? "<div class=\"banner banner--err\">Those credentials didn't match, or the account is disabled.</div>"
+    : "";
+  var shopName = opts.shop_name || "blamejs.shop";
+  var body =
+    "<div class=\"signin-wrap\">" +
+      "<div class=\"signin-card\">" +
+        "<div class=\"signin-mark\"><span class=\"dot\"></span>" + _htmlEscape(shopName) + " admin</div>" +
+        "<h2>Operator sign in</h2>" +
+        "<p class=\"signin-lede\">Sign in with your operator email and password.</p>" +
+        err +
+        "<form method=\"post\" action=\"/admin/operators/signin\">" +
+          "<label class=\"form-field\"><span>Email</span>" +
+            "<input type=\"email\" name=\"email\" autocomplete=\"username\" autofocus required>" +
+          "</label>" +
+          "<label class=\"form-field\"><span>Password</span>" +
+            "<input type=\"password\" name=\"password\" autocomplete=\"current-password\" required>" +
+          "</label>" +
+          "<button type=\"submit\" class=\"btn\">Sign in</button>" +
+        "</form>" +
+        "<p class=\"signin-lede\"><a href=\"/admin\">Use the admin API key instead &rarr;</a></p>" +
+      "</div>" +
+    "</div>";
+  return _renderAdminShell(shopName, "Operator sign in", body, null);
+}
+
+// The operators console: the roster table + the create form. Owner-only
+// actions (create / disable / re-role / rotate key) render for every
+// signed-in operator, but the role gate at the chokepoint 403s a non-owner
+// who submits one — the page never lies about authority by hiding the
+// controls, it relies on the verb-level gate. Every operator-authored
+// string (email / display name) is esc()'d on render.
+function renderOperators(opts) {
+  opts = opts || {};
+  var shopName  = opts.shop_name || "blamejs.shop";
+  var operators = Array.isArray(opts.operators) ? opts.operators : [];
+  var notice    = opts.notice
+    ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>"
+    : "";
+
+  // One-time API-key reveal panel (Post/Redirect/Get — shown once).
+  var reveal = "";
+  if (opts.reveal && typeof opts.reveal.key === "string") {
+    reveal =
+      "<div class=\"banner banner--warn\">" +
+        "<strong>New API key — copy it now.</strong> It is shown once and never again.<br>" +
+        "<code>" + _htmlEscape(opts.reveal.key) + "</code>" +
+      "</div>";
+  } else if (opts.created_id) {
+    reveal = "<div class=\"banner banner--ok\">Operator saved.</div>";
+  }
+
+  var rows = operators.length
+    ? operators.map(function (o) {
+        var idShort = _htmlEscape(String(o.id || "").slice(0, 8));
+        var statusPill = o.status === "disabled"
+          ? "<span class=\"status-pill cancelled\">disabled</span>"
+          : "<span class=\"status-pill paid\">active</span>";
+        var roleOptions = ["owner", "manager", "viewer"].map(function (r) {
+          return "<option value=\"" + r + "\"" + (o.role === r ? " selected" : "") + ">" + r + "</option>";
+        }).join("");
+        var roleForm =
+          "<form method=\"post\" action=\"/admin/operators/" + _htmlEscape(o.id) + "/role\" class=\"form-inline\">" +
+            "<select name=\"role\" aria-label=\"Role\">" + roleOptions + "</select>" +
+            "<button class=\"btn btn--ghost btn--sm\" type=\"submit\">Set role</button>" +
+          "</form>";
+        var statusForm = o.status === "disabled"
+          ? "<form method=\"post\" action=\"/admin/operators/" + _htmlEscape(o.id) + "/enable\" class=\"form-inline\">" +
+              "<button class=\"btn btn--ghost btn--sm\" type=\"submit\">Enable</button></form>"
+          : "<form method=\"post\" action=\"/admin/operators/" + _htmlEscape(o.id) + "/disable\" class=\"form-inline\">" +
+              "<button class=\"btn btn--danger btn--sm\" type=\"submit\">Disable</button></form>";
+        var keyForm =
+          "<form method=\"post\" action=\"/admin/operators/" + _htmlEscape(o.id) + "/rotate-key\" class=\"form-inline\">" +
+            "<button class=\"btn btn--ghost btn--sm\" type=\"submit\">" + (o.has_api_key ? "Rotate key" : "Mint key") + "</button>" +
+          "</form>";
+        return "<tr>" +
+          "<td>" + _htmlEscape(o.display_name) + "<br><span class=\"meta\">" + _htmlEscape(o.email) + "</span></td>" +
+          "<td><span class=\"meta\">" + idShort + "</span></td>" +
+          "<td>" + roleForm + "</td>" +
+          "<td>" + statusPill + "</td>" +
+          "<td>" + (o.has_api_key ? "yes" : "no") + "</td>" +
+          "<td class=\"actions-row\">" + statusForm + keyForm + "</td>" +
+          "</tr>";
+      }).join("")
+    : "<tr><td colspan=\"6\" class=\"empty\">No operators yet. The admin API key is the owner until you add one.</td></tr>";
+
+  var table = _tableWrap(
+    "<table><thead><tr>" +
+      "<th scope=\"col\">Operator</th><th scope=\"col\">ID</th><th scope=\"col\">Role</th>" +
+      "<th scope=\"col\">Status</th><th scope=\"col\">API key</th><th scope=\"col\">Actions</th>" +
+    "</tr></thead><tbody>" + rows + "</tbody></table>");
+
+  var createForm =
+    "<section><h2>Add an operator</h2><div class=\"panel\">" +
+      "<form method=\"post\" action=\"/admin/operators\">" +
+        "<label class=\"form-field\"><span>Display name</span>" +
+          "<input type=\"text\" name=\"display_name\" maxlength=\"128\" required></label>" +
+        "<label class=\"form-field\"><span>Email</span>" +
+          "<input type=\"email\" name=\"email\" autocomplete=\"off\" required></label>" +
+        "<label class=\"form-field\"><span>Password</span>" +
+          "<input type=\"password\" name=\"password\" autocomplete=\"new-password\" minlength=\"12\" required>" +
+          "<small>At least 12 characters. Hashed with Argon2id — never stored in the clear.</small></label>" +
+        "<label class=\"form-field\"><span>Role</span>" +
+          "<select name=\"role\">" +
+            "<option value=\"manager\">manager — catalog, orders, customers, marketing</option>" +
+            "<option value=\"viewer\">viewer — read-only</option>" +
+            "<option value=\"owner\">owner — everything, including operators</option>" +
+          "</select></label>" +
+        "<label class=\"form-field form-field--check\">" +
+          "<input type=\"checkbox\" name=\"mint_api_key\" value=\"1\"> " +
+          "<span>Also mint a bearer API key (for CLI / automation)</span></label>" +
+        "<button type=\"submit\" class=\"btn\">Create operator</button>" +
+      "</form>" +
+    "</div></section>";
+
+  var body =
+    "<section><h2>Operators</h2>" +
+      notice + reveal +
+      "<p class=\"signin-lede\">The admin API key is always the break-glass owner. Add operators so each person signs in with their own credential and role.</p>" +
+      "<div class=\"panel\">" + table + "</div>" +
+    "</section>" + createForm;
+
+  return _renderAdminShell(shopName, "Operators", body, "operators", opts.nav_available);
+}
+
 function renderAdminLanding(opts) {
   opts = opts || {};
   var setupBanner = opts.setup_complete
@@ -20914,4 +21602,6 @@ module.exports = {
   renderAdminPickupLocations: renderAdminPickupLocations,
   renderAdminPickups:      renderAdminPickups,
   renderAdminGiftWraps:    renderAdminGiftWraps,
+  renderOperators:         renderOperators,
+  renderOperatorSignin:    renderOperatorSignin,
 };