@blamejs/blamejs-shop 0.4.16 → 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) {
@@ -604,6 +820,8 @@ function mount(router, deps) {
   var stockTransfers     = deps.stockTransfers     || null; // location→location transfer console (dispatch/receive FSM) disabled when absent
   var inventoryWriteoffs = deps.inventoryWriteoffs || null; // reason-coded write-off / shrinkage console disabled when absent
   var quotes          = deps.quotes          || null; // RFQ negotiation console (queue/detail/respond/withdraw/convert) disabled when absent
+  var emailCampaigns     = deps.emailCampaigns     || null; // consent-gated broadcast/campaign console disabled when absent
+  var mailingAudiences   = deps.mailingAudiences   || null; // audience picker for the campaign console (target-an-audience dropdown)
   // Read-only activity log at /admin/audit. Defaults ON — the framework
   // audit chain is always booted by createApp, so the screen always has a
   // data source (unlike the optional primitives above, which default off).
@@ -617,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 };
+  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 */ }
 
@@ -645,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");
     };
@@ -5703,6 +5996,250 @@ function mount(router, deps) {
     ));
   }
 
+  // ---- email campaigns (consent-gated broadcast) ----------------------
+  //
+  // The marketing-broadcast console. An operator authors a campaign
+  // (subject + Markdown body), targets an existing mailing audience, sees
+  // the RESOLVED REACHABLE count (who is actually marketing-consented +
+  // deliverable right now — never the raw membership), test-sends to their
+  // own inbox, then sends. Consent is resolved AT SEND TIME, per recipient:
+  // only a marketing-consented (newsletter-subscribed, not suppressed)
+  // recipient with a deliverable plaintext address gets the broadcast, and
+  // someone who unsubscribes after the send starts is honored mid-send.
+  // Every broadcast carries an RFC 8058 one-click List-Unsubscribe header
+  // pair plus an in-body unsubscribe link. The operator-authored body is
+  // treated as hostile: it renders escape-by-default (any `<` lands as
+  // `&lt;`; links pass the https-only safeUrl gate) so a compromised admin
+  // key can't inject script into mail or stored XSS into this console.
+  if (emailCampaigns) {
+    var _campaignAudiences = function () {
+      if (!mailingAudiences) return Promise.resolve([]);
+      return mailingAudiences.listAudiences({ include_archived: false });
+    };
+
+    // List — every campaign with status + per-campaign delivery counts.
+    // Content-negotiated: bearer → the JSON array; browser → the table.
+    router.get("/admin/campaigns", _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 rows = await emailCampaigns.listCampaigns(status ? { status: status } : {});
+        _json(res, 200, { campaigns: rows, can_broadcast: emailCampaigns.canBroadcast() });
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var rows = await emailCampaigns.listCampaigns({});
+        // Roll each campaign's per-recipient send ledger up for the count
+        // column — bounded read per row (the list is operator-scale).
+        var withCounts = [];
+        for (var i = 0; i < rows.length; i += 1) {
+          var counts = null;
+          try { counts = await emailCampaigns.sendCounts(rows[i].slug); }
+          catch (_e) { counts = null; }
+          withCounts.push({ campaign: rows[i], counts: counts });
+        }
+        _sendHtml(res, 200, renderAdminCampaigns({
+          shop_name: deps.shop_name, nav_available: navAvailable,
+          rows: withCounts, can_broadcast: emailCampaigns.canBroadcast(),
+          sent:    url && url.searchParams.get("sent"),
+          saved:   url && url.searchParams.get("saved"),
+          tested:  url && url.searchParams.get("tested"),
+          notice:  (url && url.searchParams.get("err")) ? _campaignErrNotice(url.searchParams.get("err")) : null,
+        }));
+      },
+    ));
+
+    // New-campaign form — its own GET so a bad submit's err redirect
+    // keeps the operator's context.
+    router.get("/admin/campaigns/new", _pageOrApi(true,
+      R(async function (_req, res) {
+        _json(res, 200, { audiences: await _campaignAudiences() });
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        _sendHtml(res, 200, renderAdminCampaignNew({
+          shop_name: deps.shop_name, nav_available: navAvailable,
+          audiences: await _campaignAudiences(),
+          notice: (url && url.searchParams.get("err")) ? _campaignErrNotice(url.searchParams.get("err")) : null,
+        }));
+      },
+    ));
+
+    function _campaignInput(body) {
+      return {
+        slug:          body.slug,
+        subject:       body.subject,
+        body_html:     body.body_html,
+        // Markdown source is the single authored body; the text alt is
+        // derived from it at send time, so persist the same source in
+        // both columns (the renderer produces the HTML + text views).
+        body_text:     body.body_text != null && body.body_text !== "" ? body.body_text : body.body_html,
+        audience_slug: body.audience_slug,
+        from_address:  body.from_address,
+        from_name:     body.from_name,
+        reply_to:      body.reply_to != null && body.reply_to !== "" ? body.reply_to : undefined,
+      };
+    }
+
+    // Create — composes defineCampaign (validates slug / subject / body /
+    // audience / sender identity, throws TypeError → 400 / err redirect).
+    router.post("/admin/campaigns", _pageOrApi(false,
+      W("email_campaign.create", async function (req, res) {
+        var c;
+        try { c = await emailCampaigns.defineCampaign(_campaignInput(req.body || {})); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        _json(res, 201, c);
+        return { id: c.slug };
+      }),
+      async function (req, res) {
+        try { await emailCampaigns.defineCampaign(_campaignInput(req.body || {})); }
+        catch (e) {
+          var n = _safeNotice(e, "email_campaign.create");
+          if (n.status >= 500) throw e;
+          return _redirect(res, "/admin/campaigns/new?err=bad");
+        }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".email_campaign.create", outcome: "success" });
+        _redirect(res, "/admin/campaigns?saved=1");
+      },
+    ));
+
+    // Detail — the campaign + its rendered (escape-by-default) preview, the
+    // resolved reachable count (computed live), the send-ledger counts, and
+    // the test-send + send actions. Content-negotiated.
+    router.get("/admin/campaigns/:slug", _pageOrApi(true,
+      R(async function (req, res) {
+        var c = await emailCampaigns.getCampaign(req.params.slug);
+        if (!c) return _problem(res, 404, "email-campaign-not-found");
+        var reach = null;
+        try { reach = await emailCampaigns.reachability(req.params.slug); }
+        catch (_e) { reach = null; }
+        var counts = await emailCampaigns.sendCounts(req.params.slug);
+        _json(res, 200, Object.assign({}, c, { reachability: reach, send_counts: counts, can_broadcast: emailCampaigns.canBroadcast() }));
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var c = await emailCampaigns.getCampaign(req.params.slug);
+        if (!c) return _sendHtml(res, 404, renderAdminCampaigns({
+          shop_name: deps.shop_name, nav_available: navAvailable, rows: [],
+          can_broadcast: emailCampaigns.canBroadcast(), notice: "Campaign not found.",
+        }));
+        var preview = null;
+        try { preview = await emailCampaigns.previewCampaign(req.params.slug); }
+        catch (_e) { preview = null; }
+        var reach = null;
+        try { reach = await emailCampaigns.reachability(req.params.slug); }
+        catch (_e) { reach = null; }
+        var counts = await emailCampaigns.sendCounts(req.params.slug);
+        _sendHtml(res, 200, renderAdminCampaign({
+          shop_name: deps.shop_name, nav_available: navAvailable,
+          campaign: c, preview: preview, reachability: reach, counts: counts,
+          can_broadcast: emailCampaigns.canBroadcast(),
+          sent:   url && url.searchParams.get("sent"),
+          tested: url && url.searchParams.get("tested"),
+          notice: (url && url.searchParams.get("err")) ? _campaignErrNotice(url.searchParams.get("err")) : null,
+        }));
+      },
+    ));
+
+    // Test-send — render + mail the campaign to ONE operator-supplied
+    // address (bypasses the audience + consent gate; it's the operator's
+    // own inbox). Rate-bound on the shared send window.
+    router.post("/admin/campaigns/:slug/test", _pageOrApi(false,
+      W("email_campaign.test", async function (req, res) {
+        var slug = req.params.slug;
+        var out;
+        try { out = await emailCampaigns.testSend(slug, (req.body || {}).to); }
+        catch (e) {
+          if (e instanceof TypeError) {
+            var code = e.code === "EMAIL_CAMPAIGN_RATE_LIMITED" ? 429 : 400;
+            return _problem(res, code, e.code === "EMAIL_CAMPAIGN_RATE_LIMITED" ? "rate-limited" : "bad-request", e.message);
+          }
+          _safeNotice(e, "email_campaign.test");
+          return _problem(res, 502, "send-failed", "The test message could not be sent.");
+        }
+        _json(res, 200, out);
+        return { id: slug };
+      }),
+      async function (req, res) {
+        var slug = req.params.slug;
+        var enc = encodeURIComponent(slug);
+        try { await emailCampaigns.testSend(slug, (req.body || {}).to); }
+        catch (e) {
+          if (e instanceof TypeError) {
+            var reason = e.code === "EMAIL_CAMPAIGN_RATE_LIMITED" ? "rate" : "test";
+            return _redirect(res, "/admin/campaigns/" + enc + "?err=" + reason);
+          }
+          _safeNotice(e, "email_campaign.test");
+          return _redirect(res, "/admin/campaigns/" + enc + "?err=send");
+        }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".email_campaign.test", outcome: "success", metadata: { slug: slug } });
+        _redirect(res, "/admin/campaigns/" + enc + "?tested=1");
+      },
+    ));
+
+    // Send — the consent-gated broadcast. Resolves reachability at the
+    // send moment, drains the audience, only marketing-consented +
+    // deliverable recipients receive, every message carries the one-click
+    // unsubscribe pair. One bad address is counted, never fatal.
+    router.post("/admin/campaigns/:slug/send", _pageOrApi(false,
+      W("email_campaign.send", async function (req, res) {
+        var slug = req.params.slug;
+        var c = await emailCampaigns.getCampaign(slug);
+        if (!c) return _problem(res, 404, "email-campaign-not-found");
+        var out;
+        try { out = await emailCampaigns.broadcast(slug); }
+        catch (e) {
+          if (e instanceof TypeError) {
+            var code = e.code === "EMAIL_CAMPAIGN_BROADCAST_UNAVAILABLE" ? 409 : 400;
+            return _problem(res, code, e.code === "EMAIL_CAMPAIGN_BROADCAST_UNAVAILABLE" ? "broadcast-unavailable" : "bad-request", e.message);
+          }
+          throw e;
+        }
+        _json(res, 200, out);
+        return { id: slug };
+      }),
+      async function (req, res) {
+        var slug = req.params.slug;
+        var enc = encodeURIComponent(slug);
+        var c = await emailCampaigns.getCampaign(slug);
+        if (!c) return _redirect(res, "/admin/campaigns?err=notfound");
+        try { await emailCampaigns.broadcast(slug); }
+        catch (e) {
+          if (e instanceof TypeError) {
+            var reason = e.code === "EMAIL_CAMPAIGN_BROADCAST_UNAVAILABLE" ? "unavailable" : "send";
+            return _redirect(res, "/admin/campaigns/" + enc + "?err=" + reason);
+          }
+          _safeNotice(e, "email_campaign.send");
+          return _redirect(res, "/admin/campaigns/" + enc + "?err=send");
+        }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".email_campaign.send", outcome: "success", metadata: { slug: slug } });
+        _redirect(res, "/admin/campaigns/" + enc + "?sent=1");
+      },
+    ));
+
+    // Cancel — terminal off-ramp for a draft / scheduled campaign.
+    router.post("/admin/campaigns/:slug/cancel", _pageOrApi(false,
+      W("email_campaign.cancel", async function (req, res) {
+        var slug = req.params.slug;
+        var reason = (req.body || {}).reason || "Cancelled from the console.";
+        var out;
+        try { out = await emailCampaigns.cancelCampaign(slug, reason); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        _json(res, 200, out);
+        return { id: slug };
+      }),
+      async function (req, res) {
+        var slug = req.params.slug;
+        var enc = encodeURIComponent(slug);
+        var reason = (req.body || {}).reason || "Cancelled from the console.";
+        try { await emailCampaigns.cancelCampaign(slug, reason); }
+        catch (e) { if (!(e instanceof TypeError)) throw e; return _redirect(res, "/admin/campaigns/" + enc + "?err=cancel"); }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".email_campaign.cancel", outcome: "success", metadata: { slug: slug } });
+        _redirect(res, "/admin/campaigns?saved=1");
+      },
+    ));
+  }
+
   // ---- gift wraps -----------------------------------------------------
   //
   // The operator-defined gift-wrap catalog: define / update / archive a wrap
@@ -12195,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(),
@@ -12237,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) {
@@ -12598,6 +13380,7 @@ var ADMIN_NAV_ITEMS = [
   { key: "pick-lists",   href: "/admin/pick-lists",   label: "Pick lists",   requires: "pickLists" },
   { key: "announcements", href: "/admin/announcements", label: "Announcements", requires: "announcementBar" },
   { key: "promo-banners", href: "/admin/promo-banners", label: "Promo banners", requires: "promoBanners" },
+  { key: "campaigns",    href: "/admin/campaigns",    label: "Email campaigns", requires: "emailCampaigns" },
   { key: "blog",         href: "/admin/blog",         label: "Blog",         requires: "blog" },
   { key: "help",         href: "/admin/help",         label: "Help center",  requires: "knowledgeBase" },
   { key: "pages",        href: "/admin/pages",        label: "Pages",        requires: "storefrontPages" },
@@ -12606,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" },
 ];
@@ -12671,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
@@ -12691,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
@@ -15421,6 +16356,195 @@ function renderAdminInvReceive(opts) {
   return _renderAdminShell(opts.shop_name, "Receive stock", body, "inventory-receive", opts.nav_available);
 }
 
+// ---- email campaign console renders ----------------------------------
+
+// Map an ?err= code on a campaign console redirect to an operator-facing
+// notice. The codes are emitted by the campaign routes, never operator
+// free text, so no escaping concern here.
+function _campaignErrNotice(code) {
+  if (code === "bad")         return "Check the campaign — slug, subject, body, audience, and a valid sender address are all required.";
+  if (code === "rate")        return "Send rate limit reached. Try again in a moment.";
+  if (code === "test")        return "The test recipient address wasn't valid.";
+  if (code === "send")        return "The send couldn't be completed. Check the error log.";
+  if (code === "unavailable") return "Broadcast isn't available — this deployment has no deliverable-address source (newsletter list) or no configured unsubscribe origin.";
+  if (code === "cancel")      return "That campaign can't be cancelled from its current state.";
+  if (code === "notfound")    return "Campaign not found.";
+  return "That action couldn't be completed.";
+}
+
+function _campaignStatusPill(status) {
+  var cls = "status-pill";
+  if (status === "sent")      cls = "status-pill status-pill--ok";
+  if (status === "cancelled") cls = "status-pill status-pill--muted";
+  if (status === "sending")   cls = "status-pill status-pill--warn";
+  return "<span class=\"" + cls + "\">" + _htmlEscape(String(status)) + "</span>";
+}
+
+// Per-recipient delivery counts cell — "12 sent · 3 skipped · 1 failed".
+// All four outcomes roll into a compact summary; a zero-everything
+// campaign shows an em-dash.
+function _campaignCountsSummary(counts) {
+  if (!counts) return "<span class=\"meta\">—</span>";
+  var sent = Number(counts.sent || 0);
+  var skipped = Number(counts.skipped_unsubscribed || 0) + Number(counts.skipped_suppressed || 0);
+  var failed = Number(counts.failed || 0);
+  if (!sent && !skipped && !failed) return "<span class=\"meta\">—</span>";
+  var parts = [];
+  parts.push(_htmlEscape(String(sent)) + " sent");
+  if (skipped) parts.push(_htmlEscape(String(skipped)) + " skipped");
+  if (failed)  parts.push(_htmlEscape(String(failed)) + " failed");
+  return _htmlEscape(parts.join(" · "));
+}
+
+function renderAdminCampaigns(opts) {
+  opts = opts || {};
+  var rows = opts.rows || [];
+  var saved  = opts.saved  ? "<div class=\"banner banner--ok\">Campaign saved.</div>" : "";
+  var sent   = opts.sent   ? "<div class=\"banner banner--ok\">Campaign sent.</div>" : "";
+  var tested = opts.tested ? "<div class=\"banner banner--ok\">Test message sent.</div>" : "";
+  var notice = opts.notice ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+
+  // Honesty banner — when the broadcast path isn't wired (no deliverable
+  // address source / no unsubscribe origin), say so plainly. Campaigns
+  // can still be authored + previewed; the Send action will refuse.
+  var reachBanner = opts.can_broadcast
+    ? ""
+    : "<div class=\"banner banner--warn\">Sending is unavailable: this store has no deliverable-address source " +
+      "(a newsletter subscriber list with plaintext addresses) or no configured unsubscribe origin. " +
+      "Customer email is stored hash-only, so only newsletter subscribers are reachable. You can still draft and preview campaigns.</div>";
+
+  var tableRows = rows.map(function (rc) {
+    var c = rc.campaign;
+    var enc = encodeURIComponent(c.slug);
+    return "<tr>" +
+      "<td><a href=\"/admin/campaigns/" + enc + "\">" + _htmlEscape(c.subject) + "</a><div class=\"meta\"><code>" + _htmlEscape(c.slug) + "</code></div></td>" +
+      "<td>" + _htmlEscape(c.audience_slug) + "</td>" +
+      "<td>" + _campaignStatusPill(c.status) + "</td>" +
+      "<td>" + _campaignCountsSummary(rc.counts) + "</td>" +
+      "</tr>";
+  }).join("");
+
+  var list = rows.length
+    ? "<div class=\"panel\">" + _tableWrap("<table><thead><tr><th scope=\"col\">Subject</th><th scope=\"col\">Audience</th><th scope=\"col\">Status</th><th scope=\"col\">Delivery</th></tr></thead><tbody>" + tableRows + "</tbody></table>") + "</div>"
+    : "<p class=\"empty\">No campaigns yet. Create one to broadcast to a mailing audience.</p>";
+
+  var body =
+    "<section><h2>Email campaigns</h2>" +
+      "<p class=\"meta\">Broadcast a message to a mailing audience. Only marketing-consented, reachable subscribers receive a campaign — consent is checked at send time, and every message carries a one-click unsubscribe.</p>" +
+      saved + sent + tested + notice + reachBanner +
+      "<div class=\"actions-row\"><a class=\"btn\" href=\"/admin/campaigns/new\">New campaign</a></div>" +
+      list +
+    "</section>";
+  return _renderAdminShell(opts.shop_name, "Email campaigns", body, "campaigns", opts.nav_available);
+}
+
+function renderAdminCampaignNew(opts) {
+  opts = opts || {};
+  var audiences = opts.audiences || [];
+  var notice = opts.notice ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+
+  var audOptions = audiences.map(function (a) {
+    return "<option value=\"" + _htmlEscape(a.slug) + "\">" + _htmlEscape(a.title) + " (" + _htmlEscape(a.slug) + ")</option>";
+  }).join("");
+  var audField = audiences.length
+    ? "<label class=\"form-field\"><span>Audience</span><select name=\"audience_slug\" required>" + audOptions + "</select>" +
+        "<small>The mailing audience to broadcast to. Manage audiences from the mailing-audiences API.</small></label>"
+    : "<label class=\"form-field\"><span>Audience slug</span><input type=\"text\" name=\"audience_slug\" maxlength=\"64\" required>" +
+        "<small>No mailing audiences are defined yet — enter the slug of one you've created via the API.</small></label>";
+
+  var body =
+    "<section class=\"mw-42\"><h2>New campaign</h2>" + notice +
+      "<form method=\"post\" action=\"/admin/campaigns\">" +
+        _setupField("Campaign slug", "slug", "", "text", "Lowercase id, e.g. spring-sale-2026.", " maxlength=\"64\" required") +
+        _setupField("Subject", "subject", "", "text", "The email subject line.", " maxlength=\"200\" required") +
+        "<label class=\"form-field\"><span>Body (Markdown)</span>" +
+          "<textarea name=\"body_html\" rows=\"10\" maxlength=\"100000\" required></textarea>" +
+          "<small>Markdown — headings, lists, links, bold/italic. Rendered escape-by-default: raw HTML is shown as text, links must be https.</small></label>" +
+        audField +
+        _setupField("From address", "from_address", "", "email", "The sender address (must be a domain you can send from).", " maxlength=\"254\" required") +
+        _setupField("From name", "from_name", "", "text", "The friendly sender name.", " maxlength=\"100\" required") +
+        _setupField("Reply-to", "reply_to", "", "email", "Optional — where replies land.", " maxlength=\"254\"") +
+        "<div class=\"actions-row\"><button type=\"submit\" class=\"btn\">Create campaign</button>" +
+          "<a class=\"btn btn--ghost\" href=\"/admin/campaigns\">Cancel</a></div>" +
+      "</form>" +
+    "</section>";
+  return _renderAdminShell(opts.shop_name, "New campaign", body, "campaigns", opts.nav_available);
+}
+
+function renderAdminCampaign(opts) {
+  opts = opts || {};
+  var c = opts.campaign;
+  var enc = encodeURIComponent(c.slug);
+  var sent   = opts.sent   ? "<div class=\"banner banner--ok\">Campaign sent.</div>" : "";
+  var tested = opts.tested ? "<div class=\"banner banner--ok\">Test message sent.</div>" : "";
+  var notice = opts.notice ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+
+  // Resolved reachable count — the true send size, computed live. The
+  // operator sees this BEFORE confirming a send.
+  var reach = opts.reachability;
+  var reachPanel = reach
+    ? "<div class=\"panel\"><h3 class=\"subhead\">Reachable recipients</h3>" +
+        "<p class=\"big-stat\">" + _htmlEscape(String(reach.reachable)) + "</p>" +
+        "<p class=\"meta\">Resolved at send time from " + _htmlEscape(String(reach.resolved)) + " audience members: " +
+          _htmlEscape(String(reach.reachable)) + " reachable, " +
+          _htmlEscape(String(reach.suppressed)) + " suppressed, " +
+          _htmlEscape(String(reach.unsubscribed)) + " unsubscribed, " +
+          _htmlEscape(String(reach.no_address)) + " with no deliverable address.</p>" +
+      "</div>"
+    : "<div class=\"panel\"><p class=\"meta\">Reachability can't be resolved — no deliverable-address source is wired.</p></div>";
+
+  // Per-recipient delivery counts from the send ledger.
+  var counts = opts.counts || {};
+  var countsPanel = "<div class=\"panel\"><h3 class=\"subhead\">Delivery</h3>" +
+    "<ul class=\"kv-list\">" +
+      "<li><span>Sent</span><strong>" + _htmlEscape(String(counts.sent || 0)) + "</strong></li>" +
+      "<li><span>Skipped (unsubscribed)</span><strong>" + _htmlEscape(String(counts.skipped_unsubscribed || 0)) + "</strong></li>" +
+      "<li><span>Skipped (suppressed)</span><strong>" + _htmlEscape(String(counts.skipped_suppressed || 0)) + "</strong></li>" +
+      "<li><span>Failed</span><strong>" + _htmlEscape(String(counts.failed || 0)) + "</strong></li>" +
+    "</ul></div>";
+
+  // Rendered preview — the renderer already escaped the operator body, so
+  // the preview HTML is splice-safe (no double-escape). Spliced literally
+  // so a `$` in the body can't trip String.replace dollar substitution.
+  var previewBody = opts.preview ? opts.preview.body_html : "<span class=\"meta\">Preview unavailable.</span>";
+  var previewPanel = "<div class=\"panel\"><h3 class=\"subhead\">Preview</h3>" +
+    "<div class=\"mail-preview\">RAW_PREVIEW_BODY</div></div>";
+
+  // Send / test actions only when the campaign isn't terminal.
+  var isTerminal = c.status === "sent" || c.status === "cancelled";
+  var actions = "";
+  if (!isTerminal) {
+    var sendBtn = opts.can_broadcast
+      ? "<form method=\"post\" action=\"/admin/campaigns/" + enc + "/send\" class=\"form-inline\">" +
+          "<button class=\"btn\" type=\"submit\">Send to " + _htmlEscape(reach ? String(reach.reachable) : "0") + " recipient(s)</button></form>"
+      : "<span class=\"meta\">Sending is unavailable on this deployment.</span>";
+    actions =
+      "<div class=\"panel\"><h3 class=\"subhead\">Send a test</h3>" +
+        "<form method=\"post\" action=\"/admin/campaigns/" + enc + "/test\" class=\"form-inline\">" +
+          "<input type=\"email\" name=\"to\" placeholder=\"you@example.com\" maxlength=\"254\" required>" +
+          "<button class=\"btn btn--ghost\" type=\"submit\">Send test</button></form></div>" +
+      "<div class=\"panel\"><h3 class=\"subhead\">Send campaign</h3>" + sendBtn +
+        "<form method=\"post\" action=\"/admin/campaigns/" + enc + "/cancel\" class=\"form-inline mt\">" +
+          "<button class=\"btn btn--ghost btn--sm\" type=\"submit\">Cancel campaign</button></form></div>";
+  }
+
+  var meta = "<p class=\"meta\">Audience <code>" + _htmlEscape(c.audience_slug) + "</code> · " +
+    "from " + _htmlEscape(c.from_name) + " &lt;" + _htmlEscape(c.from_address) + "&gt; · " +
+    _campaignStatusPill(c.status) + "</p>";
+
+  var body =
+    "<section><h2>" + _htmlEscape(c.subject) + "</h2>" + meta +
+      sent + tested + notice +
+      reachPanel + countsPanel + previewPanel + actions +
+      "<div class=\"actions-row mt\"><a class=\"btn btn--ghost\" href=\"/admin/campaigns\">&larr; All campaigns</a></div>" +
+    "</section>";
+  var html = _renderAdminShell(opts.shop_name, c.subject, body, "campaigns", opts.nav_available);
+  // Splice the already-escaped preview body literally (it contains only the
+  // fixed tag set the escape-by-default renderer emits; the operator's
+  // bytes were escaped before this point).
+  return _spliceRaw(html, "RAW_PREVIEW_BODY", previewBody);
+}
+
 // Location→location transfer console: the open form + the open-transfer
 // queue with the FSM action legal from each row's status. Reasons,
 // carriers, and tracking numbers are operator free text — escaped.
@@ -20478,4 +21602,6 @@ module.exports = {
   renderAdminPickupLocations: renderAdminPickupLocations,
   renderAdminPickups:      renderAdminPickups,
   renderAdminGiftWraps:    renderAdminGiftWraps,
+  renderOperators:         renderOperators,
+  renderOperatorSignin:    renderOperatorSignin,
 };