@consilioweb/payload-support 2.0.1 → 4.0.0

package/src/utils/features.ts

@@ -0,0 +1,297 @@
+/**
+ * Ticketing feature flags — single source of truth (client + server).
+ *
+ * Flags are stored SERVER-side, in the `support-settings` row of
+ * `payload-preferences` (see `readSettings.ts` and `endpoints/settings.ts`).
+ * A flag toggled on one machine therefore applies to every browser and to
+ * server-side code (hooks, cron endpoints) alike.
+ *
+ * `localStorage` is still used, but demoted to a plain CACHE: it lets admin
+ * views paint synchronously on first render and keeps them usable when the
+ * settings endpoint is unreachable. It is never authoritative.
+ *
+ * Two flags are *projections* of settings that already lived server-side long
+ * before this module, and are deliberately NOT stored twice:
+ *   - `autoClose`     ← `settings.autoClose.enabled`
+ *   - `autoCloseDays` ← `settings.autoClose.daysBeforeClose`
+ * The `autoClose` block stays authoritative; the flags are recomputed on read
+ * and dropped on write. See `projectAutoClose` / `stripProjectedFeatures`.
+ */
+
+/**
+ * Feature flags for the ticketing module.
+ * Each feature can be enabled/disabled by the admin.
+ * When disabled, the corresponding UI section is hidden entirely.
+ */
+export interface TicketingFeatures {
+  /** Time tracking: timer, manual entries, billing */
+  timeTracking: boolean
+  /** AI features: sentiment, synthesis, suggestion, rewrite */
+  ai: boolean
+  /** Satisfaction surveys: CSAT rating after resolution */
+  satisfaction: boolean
+  /** Live chat integration: chat → ticket conversion */
+  chat: boolean
+  /** Email tracking: pixel tracking, open/sent status per message */
+  emailTracking: boolean
+  /** Canned responses: quick reply templates */
+  canned: boolean
+  /** Ticket merge: combine two tickets into one */
+  merge: boolean
+  /** Snooze: temporarily hide a ticket */
+  snooze: boolean
+  /** External messages: add messages received outside the system */
+  externalMessages: boolean
+  /** Client history: past tickets, projects, notes sidebar */
+  clientHistory: boolean
+  /** Activity log: audit trail of actions on the ticket */
+  activityLog: boolean
+  /** Split ticket: extract a message into a new ticket */
+  splitTicket: boolean
+  /** Scheduled replies: send a message at a future date */
+  scheduledReplies: boolean
+  /** Auto-close: automatically resolve inactive tickets (projection of settings.autoClose.enabled) */
+  autoClose: boolean
+  /** Auto-close delay in days (projection of settings.autoClose.daysBeforeClose) */
+  autoCloseDays: number
+  /** Round-robin: distribute new tickets evenly among agents */
+  roundRobin: boolean
+}
+
+/** Default features — all enabled except round-robin */
+export const DEFAULT_TICKETING_FEATURES: TicketingFeatures = {
+  timeTracking: true,
+  ai: true,
+  satisfaction: true,
+  chat: true,
+  emailTracking: true,
+  canned: true,
+  merge: true,
+  snooze: true,
+  externalMessages: true,
+  clientHistory: true,
+  activityLog: true,
+  splitTicket: true,
+  scheduledReplies: true,
+  autoClose: true,
+  autoCloseDays: 7,
+  roundRobin: false,
+}
+
+type BooleanFeatureKey = Exclude<keyof TicketingFeatures, 'autoCloseDays'>
+
+const BOOLEAN_FEATURE_KEYS: readonly BooleanFeatureKey[] = [
+  'timeTracking',
+  'ai',
+  'satisfaction',
+  'chat',
+  'emailTracking',
+  'canned',
+  'merge',
+  'snooze',
+  'externalMessages',
+  'clientHistory',
+  'activityLog',
+  'splitTicket',
+  'scheduledReplies',
+  'autoClose',
+  'roundRobin',
+]
+
+/** Flags derived from another settings block — never persisted inside `features`. */
+const PROJECTED_FEATURE_KEYS = ['autoClose', 'autoCloseDays'] as const
+
+/**
+ * Coerce arbitrary input (stale localStorage, hand-edited preference row, older
+ * plugin version) into a complete, well-typed feature set. Unknown keys are
+ * dropped and wrongly-typed values fall back to their default.
+ */
+export function normalizeFeatures(raw: unknown): TicketingFeatures {
+  const out = { ...DEFAULT_TICKETING_FEATURES }
+  if (!raw || typeof raw !== 'object') return out
+
+  const src = raw as Record<string, unknown>
+  for (const key of BOOLEAN_FEATURE_KEYS) {
+    if (typeof src[key] === 'boolean') out[key] = src[key] as boolean
+  }
+
+  const days = src.autoCloseDays
+  if (typeof days === 'number' && Number.isFinite(days) && days >= 1) {
+    out.autoCloseDays = Math.floor(days)
+  }
+
+  return out
+}
+
+/** Shape of the `autoClose` settings block the two projected flags mirror. */
+export interface AutoCloseProjectionSource {
+  enabled?: boolean
+  daysBeforeClose?: number
+}
+
+/** Recompute the projected flags from the authoritative `autoClose` block. */
+export function projectAutoClose(
+  features: TicketingFeatures,
+  autoClose: AutoCloseProjectionSource | undefined,
+): TicketingFeatures {
+  if (!autoClose) return features
+  return {
+    ...features,
+    autoClose: typeof autoClose.enabled === 'boolean' ? autoClose.enabled : features.autoClose,
+    autoCloseDays:
+      typeof autoClose.daysBeforeClose === 'number' && autoClose.daysBeforeClose >= 1
+        ? Math.floor(autoClose.daysBeforeClose)
+        : features.autoCloseDays,
+  }
+}
+
+/**
+ * Drop the projected flags before persisting, so `features` and the `autoClose`
+ * block can never disagree.
+ */
+export function stripProjectedFeatures(
+  features: TicketingFeatures,
+): Omit<TicketingFeatures, (typeof PROJECTED_FEATURE_KEYS)[number]> {
+  const out = { ...features } as Record<string, unknown>
+  for (const key of PROJECTED_FEATURE_KEYS) delete out[key]
+  return out as Omit<TicketingFeatures, (typeof PROJECTED_FEATURE_KEYS)[number]>
+}
+
+// ─── Client-side cache ───────────────────────────────────
+
+/** localStorage key. Was the source of truth before 2.1 — now only a cache. */
+export const FEATURES_CACHE_KEY = 'ticketing_features'
+/** Set once the pre-2.1 localStorage values have been pushed to the server. */
+export const FEATURES_ADOPTED_KEY = 'ticketing_features_adopted'
+/** Admin-only settings endpoint backing the flags. */
+export const FEATURES_ENDPOINT = '/api/support/settings'
+
+/** localStorage can throw (Safari private mode, disabled storage) — never let it bubble. */
+function storage(): Storage | null {
+  try {
+    if (typeof window === 'undefined' || !window.localStorage) return null
+    return window.localStorage
+  } catch {
+    return null
+  }
+}
+
+/** Read the cached flags, or `null` when nothing usable is cached. */
+export function readFeaturesCache(): TicketingFeatures | null {
+  const store = storage()
+  if (!store) return null
+  try {
+    const stored = store.getItem(FEATURES_CACHE_KEY)
+    if (!stored) return null
+    return normalizeFeatures(JSON.parse(stored))
+  } catch {
+    return null
+  }
+}
+
+/** Refresh the cache with the values the server just confirmed. */
+export function writeFeaturesCache(features: TicketingFeatures): void {
+  const store = storage()
+  if (!store) return
+  try {
+    store.setItem(FEATURES_CACHE_KEY, JSON.stringify(features))
+  } catch {
+    /* quota exceeded / storage disabled — the server copy still stands */
+  }
+}
+
+/**
+ * Synchronous read used for first paint. Returns the cache when present, the
+ * defaults otherwise. Callers must still refresh from the server — see
+ * `useFeatures`.
+ */
+export function getFeatures(): TicketingFeatures {
+  return readFeaturesCache() ?? { ...DEFAULT_TICKETING_FEATURES }
+}
+
+// ─── One-shot migration of pre-2.1 localStorage ──────────
+
+/** True once this browser's legacy flags have been handed over to the server. */
+export function hasAdoptedLegacyFeatures(): boolean {
+  const store = storage()
+  if (!store) return true // nothing to migrate without storage
+  try {
+    return store.getItem(FEATURES_ADOPTED_KEY) === '1'
+  } catch {
+    return true
+  }
+}
+
+export function markLegacyFeaturesAdopted(): void {
+  const store = storage()
+  if (!store) return
+  try {
+    store.setItem(FEATURES_ADOPTED_KEY, '1')
+  } catch {
+    /* ignore */
+  }
+}
+
+/**
+ * Flags this browser configured before the server became authoritative, or
+ * `null` when there is nothing to migrate (no local values, or already done).
+ */
+export function readLegacyFeatures(): TicketingFeatures | null {
+  if (hasAdoptedLegacyFeatures()) return null
+  return readFeaturesCache()
+}
+
+// ─── Server round-trips ──────────────────────────────────
+
+export interface FetchedFeatures {
+  features: TicketingFeatures
+  /** False when the server has never had feature flags saved (fresh install). */
+  configured: boolean
+  /** True when the values come from the cache/defaults because the call failed. */
+  offline: boolean
+}
+
+/**
+ * Read the flags from the server. Falls back to the local cache, then to the
+ * defaults: a failed settings call must never leave a ticket screen unusable.
+ */
+export async function fetchFeatures(signal?: AbortSignal): Promise<FetchedFeatures> {
+  try {
+    const res = await fetch(FEATURES_ENDPOINT, { credentials: 'include', signal })
+    if (res.ok) {
+      const data = (await res.json()) as {
+        features?: unknown
+        featuresConfigured?: boolean
+        autoClose?: AutoCloseProjectionSource
+      }
+      const features = projectAutoClose(normalizeFeatures(data.features), data.autoClose)
+      writeFeaturesCache(features)
+      return { features, configured: data.featuresConfigured === true, offline: false }
+    }
+  } catch {
+    /* network error / aborted — fall through to the cache */
+  }
+  return { features: getFeatures(), configured: false, offline: true }
+}
+
+/**
+ * Persist the flags server-side, then refresh the local cache.
+ *
+ * @returns true when the server accepted the write.
+ */
+export async function saveFeatures(features: TicketingFeatures): Promise<boolean> {
+  const normalized = normalizeFeatures(features)
+  try {
+    const res = await fetch(FEATURES_ENDPOINT, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      credentials: 'include',
+      body: JSON.stringify({ features: normalized }),
+    })
+    if (!res.ok) return false
+    writeFeaturesCache(normalized)
+    return true
+  } catch {
+    return false
+  }
+}

package/src/utils/fireWebhooks.ts

@@ -1,11 +1,18 @@
 import type { Payload } from 'payload'
 import type { CollectionSlugs } from './slugs'
 import { dbFind, dbUpdate } from './db'
+import { safeFetch } from './urlSafety'
 
 /**
  * Fire all active webhooks matching the given event.
  * Uses fire-and-forget pattern (Promise.allSettled) so hook callers are never blocked.
  * Each webhook request has a 10-second timeout.
+ *
+ * @deprecated Use `dispatchWebhook` instead. This transport sends the endpoint
+ * secret IN CLEAR in the `X-Webhook-Secret` header, which contradicts the
+ * description of the `secret` field (HMAC-SHA256 signature) and defeats the point
+ * of signing. No hook in the plugin calls it any more — it stays exported only
+ * because it is part of the public surface, and will be removed in the next major.
  */
 export async function fireWebhooks(
   payload: Payload,
@@ -33,7 +40,9 @@ export async function fireWebhooks(
     await Promise.allSettled(
       endpoints.docs.map(async (endpoint: any) => {
         try {
-          const res = await fetch(endpoint.url, {
+          // Same SSRF guards as `dispatchWebhook` — this transport is deprecated
+          // but still exported, so it must not stay an open door.
+          const res = await safeFetch(endpoint.url, {
             method: 'POST',
             headers: {
               'Content-Type': 'application/json',

package/src/utils/generateTicketSynthesis.ts

@@ -2,12 +2,13 @@ import type { Payload } from 'payload'
 import type { CollectionSlugs } from './slugs'
 import { readSupportSettings, type SupportSettings } from './readSettings'
 import { dbFindByID, dbUpdate, dbFind } from './db'
+import { resolveOllamaBaseUrl } from './aiProvider'
 
 function getClient(aiSettings: SupportSettings['ai']) {
   // eslint-disable-next-line @typescript-eslint/no-require-imports
   const Anthropic = require('@anthropic-ai/sdk').default
   if (aiSettings.provider === 'ollama') {
-    const baseURL = process.env.OLLAMA_API_URL || 'https://ollama.orkelis.app/v1'
+    const baseURL = resolveOllamaBaseUrl()
     return new Anthropic({ apiKey: 'ollama', baseURL })
   }
   return new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY })

package/src/utils/index.ts

@@ -1,5 +1,7 @@
-export { readSupportSettings, DEFAULT_SETTINGS } from './readSettings'
-export type { SupportSettings } from './readSettings'
+export { readSupportSettings, readSupportSettingsState, mergeSupportSettings, invalidateSupportSettingsCache, DEFAULT_SETTINGS } from './readSettings'
+export type { SupportSettings, SupportSettingsState } from './readSettings'
+export { DEFAULT_TICKETING_FEATURES, normalizeFeatures, projectAutoClose, stripProjectedFeatures } from './features'
+export type { TicketingFeatures } from './features'
 export { resolveSlugs, DEFAULT_SLUGS } from './slugs'
 export type { CollectionSlugs } from './slugs'
 export { RateLimiter } from './rateLimiter'

package/src/utils/rateLimiter.ts

@@ -119,27 +119,61 @@ export class PayloadRateLimitStore implements RateLimitStore {
   }
 }
 
+/**
+ * Identity part of a rate-limit key for an authenticated caller.
+ *
+ * Ids are per-collection sequences: support-client #7 and agent #7 are different
+ * people with the same `id`. Keying a limiter on `String(user.id)` alone let one
+ * consume the other's budget, so the auth collection travels with the id.
+ */
+export function principalRateKey(
+  user: { id?: unknown; collection?: unknown } | null | undefined,
+): string {
+  if (!user || user.id === undefined || user.id === null) return 'anonymous'
+  const collection = typeof user.collection === 'string' && user.collection ? user.collection : 'unknown'
+  return `${collection}:${String(user.id)}`
+}
+
 export class RateLimiter {
   private readonly store: RateLimitStore
-
+  private readonly prefix: string
+
+  /**
+   * @param namespace  Endpoint-scoped prefix for every key this limiter writes.
+   *   The store is SHARED (`rateLimitStore: 'payload'` builds one instance for
+   *   all endpoints), and the raw keys collide across endpoints: `ip` was used
+   *   by both the login and the chatbot limiter — 10 forged chatbot requests
+   *   locked a victim out of the portal for 15 minutes — and `String(user.id)`
+   *   by five different endpoints. Always pass one; it is optional only because
+   *   `RateLimiter` is part of the published API surface.
+   */
   constructor(
     private readonly windowMs: number,
     private readonly maxRequests: number,
     store?: RateLimitStore,
+    namespace?: string,
   ) {
     this.store = store ?? new MemoryRateLimitStore()
+    this.prefix = namespace ? `${namespace}:` : ''
+  }
+
+  /** The key actually written to the store. Exposed for assertions in tests. */
+  scopedKey(key: string): string {
+    return `${this.prefix}${key}`
   }
 
   async check(key: string, context?: unknown): Promise<boolean> {
+    const scoped = this.scopedKey(key)
     const entry = context === undefined
-      ? await this.store.increment(key, this.windowMs)
-      : await this.store.increment(key, this.windowMs, context)
+      ? await this.store.increment(scoped, this.windowMs)
+      : await this.store.increment(scoped, this.windowMs, context)
     return entry.count > this.maxRequests
   }
 
   async reset(key: string, context?: unknown): Promise<void> {
-    if (context === undefined) await this.store.reset(key)
-    else await this.store.reset(key, context)
+    const scoped = this.scopedKey(key)
+    if (context === undefined) await this.store.reset(scoped)
+    else await this.store.reset(scoped, context)
   }
 }
 import { commitTransaction, initTransaction, killTransaction, type PayloadRequest } from 'payload'

package/src/utils/readSettings.ts

@@ -1,14 +1,69 @@
 import type { Payload } from 'payload'
 import { dbFind } from './db'
+import {
+  DEFAULT_TICKETING_FEATURES,
+  normalizeFeatures,
+  projectAutoClose,
+  type TicketingFeatures,
+} from './features'
 
-const PREF_KEY = 'support-settings'
+export const SUPPORT_SETTINGS_PREF_KEY = 'support-settings'
+const PREF_KEY = SUPPORT_SETTINGS_PREF_KEY
 const USER_PREFS_KEY_PREFIX = 'support-user-prefs'
+/** Pre-2.1 standalone round-robin row — read as a fallback, then folded into `features`. */
+const LEGACY_ROUND_ROBIN_KEY = 'support-round-robin'
+
+/**
+ * Key under which `plugin.ts` publishes the resolved staff collection slug on
+ * `config.custom`. It is the ONE source of truth shared by the read path (here)
+ * and the write path (`requireAdmin` → `slugs.users`).
+ */
+export const SUPPORT_STAFF_SLUG_CONFIG_KEY = 'supportStaffCollection'
+
+/**
+ * Owner scope for every `payload-preferences` row this plugin reads back.
+ *
+ * `payload-preferences` is writable by ANY authenticated principal, whatever its
+ * auth collection: Payload's `POST /api/payload-preferences/:key` handler only
+ * checks `!!req.user` before upserting the row. Reading a plugin-wide row by key
+ * alone therefore lets a front-office user (or a support-client) plant their own
+ * row and have the whole plugin read it — replyTo addresses, SLA escalation
+ * address, AI provider, feature flags.
+ *
+ * Every read below is constrained to `user.relationTo = <staff collection>`, the
+ * same scope the WRITE path already uses (endpoints/settings.ts, signature.ts,
+ * user-prefs.ts all upsert with `req.user.collection`, and all three are guarded
+ * by `requireAdmin`, which compares against `slugs.users`).
+ *
+ * TWO SOURCES OF TRUTH WERE THE BUG: this used to resolve the scope from
+ * `config.admin.user`, which Payload defaults to the FIRST auth collection of
+ * the app when the integrator did not declare it (config/sanitize.js). On a host
+ * whose first auth collection is the front office and whose staff collection is
+ * declared through `collectionSlugs.users`, the read scope named the front
+ * office while the write scope named the staff — and the poisoning this scope
+ * was added to defeat was open again. So the plugin now PUBLISHES the resolved
+ * `slugs.users` on `config.custom` (see plugin.ts) and reads it back here.
+ * `config.admin.user` remains a last-resort fallback for callers using these
+ * helpers outside of a plugin-built config; there is no plugin deployment in
+ * which it is consulted.
+ */
+export function resolveStaffPrefSlug(payload: Payload, staffSlug?: string): string {
+  if (staffSlug) return staffSlug
+  const config = (payload as unknown as {
+    config?: { admin?: { user?: string }; custom?: Record<string, unknown> }
+  }).config
+  const registered = config?.custom?.[SUPPORT_STAFF_SLUG_CONFIG_KEY]
+  if (typeof registered === 'string' && registered) return registered
+  return config?.admin?.user || 'users'
+}
 
 export interface SupportSettings {
   email: { fromAddress: string; fromName: string; replyToAddress: string }
   ai: { provider: string; model: string; enableSentiment: boolean; enableSynthesis: boolean; enableSuggestion: boolean; enableRewrite: boolean }
   sla: { firstResponseMinutes: number; resolutionMinutes: number; businessHoursOnly: boolean; escalationEmail: string }
   autoClose: { enabled: boolean; daysBeforeClose: number; reminderDaysBefore: number }
+  /** Ticketing feature flags — server-authoritative since 2.1 (used to be per-browser localStorage). */
+  features: TicketingFeatures
 }
 
 export interface UserPrefs {
@@ -21,6 +76,7 @@ export const DEFAULT_SETTINGS: SupportSettings = {
   ai: { provider: 'anthropic', model: 'claude-haiku-4-5-20251001', enableSentiment: true, enableSynthesis: true, enableSuggestion: true, enableRewrite: true },
   sla: { firstResponseMinutes: 120, resolutionMinutes: 1440, businessHoursOnly: true, escalationEmail: '' },
   autoClose: { enabled: true, daysBeforeClose: 7, reminderDaysBefore: 2 },
+  features: { ...DEFAULT_TICKETING_FEATURES },
 }
 
 export const DEFAULT_USER_PREFS: UserPrefs = {
@@ -32,43 +88,170 @@ export const DEFAULT_USER_PREFS: UserPrefs = {
 // (the afterChange hook chain). The settings doc changes rarely, so a short TTL
 // + explicit invalidation on save (endpoints/settings.ts) avoids redundant DB
 // reads of the same `payload-preferences` row.
-let settingsCache: { value: SupportSettings; ts: number } | null = null
+// Keyed by the STAFF SLUG the read was scoped to: a single shared slot would
+// serve one install's (or one test's) settings to another whose scope differs.
+// Bounded — the key comes from config, never from a request — but capped anyway
+// so an integrator calling the exported helper with arbitrary slugs cannot grow
+// it without limit.
+const settingsCache = new Map<string, { value: SupportSettingsState; ts: number }>()
 const SETTINGS_TTL_MS = 60_000
+const SETTINGS_CACHE_MAX = 8
+
+/** Rate-limits the "settings row exists but is not staff-owned" warning, per scope. */
+const warnedForeignSettingsRow = new Set<string>()
+
+export interface SupportSettingsState {
+  settings: SupportSettings
+  /**
+   * False when the preference row carries no `features` object yet — a
+   * pre-2.1 install, or a fresh one. Clients use it to decide whether their
+   * legacy `localStorage` flags should seed the server.
+   */
+  featuresConfigured: boolean
+}
 
 /** Invalidate the settings cache — call right after writing support settings. */
 export function invalidateSupportSettingsCache(): void {
-  settingsCache = null
+  settingsCache.clear()
+  warnedForeignSettingsRow.clear()
 }
 
-export async function readSupportSettings(payload: Payload): Promise<SupportSettings> {
-  if (settingsCache && Date.now() - settingsCache.ts < SETTINGS_TTL_MS) {
-    return settingsCache.value
+/**
+ * Merge a stored preference value onto the defaults.
+ * Exported for the settings endpoint, which must not re-implement the merge.
+ */
+export function mergeSupportSettings(
+  stored: Partial<SupportSettings> | undefined | null,
+  base: SupportSettings = DEFAULT_SETTINGS,
+): SupportSettings {
+  const autoClose = { ...base.autoClose, ...stored?.autoClose }
+  return {
+    email: { ...base.email, ...stored?.email },
+    ai: { ...base.ai, ...stored?.ai },
+    sla: { ...base.sla, ...stored?.sla },
+    autoClose,
+    // `autoClose` / `autoCloseDays` are projections of the block above, so they
+    // are recomputed here rather than trusted from whatever was persisted.
+    features: projectAutoClose(
+      normalizeFeatures({ ...base.features, ...(stored?.features as object | undefined) }),
+      autoClose,
+    ),
+  }
+}
+
+export async function readSupportSettingsState(
+  payload: Payload,
+  staffSlug?: string,
+): Promise<SupportSettingsState> {
+  const staff = resolveStaffPrefSlug(payload, staffSlug)
+  const cached = settingsCache.get(staff)
+  if (cached && Date.now() - cached.ts < SETTINGS_TTL_MS) {
+    return cached.value
+  }
+  let value: SupportSettingsState = {
+    settings: mergeSupportSettings(null),
+    featuresConfigured: false,
   }
-  let value: SupportSettings = { ...DEFAULT_SETTINGS }
   try {
     const prefs = await dbFind(payload, 'payload-preferences', {
-      where: { key: { equals: PREF_KEY } },
+      // Sibling keys are AND-ed by Payload. The `user.relationTo` clause is the
+      // security boundary: without it any authenticated principal can plant a
+      // `support-settings` row and own the plugin's server settings.
+      where: { key: { equals: PREF_KEY }, 'user.relationTo': { equals: staff } },
+      // The upsert is scoped per admin user, so several rows can share the key.
+      // Sorting makes "last write wins" deterministic instead of arbitrary.
+      sort: '-updatedAt',
       limit: 1, depth: 0, overrideAccess: true,
     })
     if (prefs.docs.length > 0) {
       const stored = prefs.docs[0].value as Partial<SupportSettings>
-      value = {
-        email: { ...DEFAULT_SETTINGS.email, ...stored.email },
-        ai: { ...DEFAULT_SETTINGS.ai, ...stored.ai },
-        sla: { ...DEFAULT_SETTINGS.sla, ...stored.sla },
-        autoClose: { ...DEFAULT_SETTINGS.autoClose, ...stored.autoClose },
+      const featuresConfigured = !!stored.features && typeof stored.features === 'object'
+      const settings = mergeSupportSettings(stored)
+
+      // Pre-2.1 installs enabled round-robin through its own preference row.
+      // Honour it until the first save writes `features` — after that the
+      // legacy row is ignored, and both write paths land in `features`.
+      if (!featuresConfigured) {
+        settings.features.roundRobin = await readLegacyRoundRobin(payload, staff)
       }
+
+      value = { settings, featuresConfigured }
+    } else {
+      await warnOnForeignSettingsRow(payload, staff)
     }
   } catch { /* fallback to defaults */ }
-  settingsCache = { value, ts: Date.now() }
+  if (settingsCache.size >= SETTINGS_CACHE_MAX && !settingsCache.has(staff)) settingsCache.clear()
+  settingsCache.set(staff, { value, ts: Date.now() })
   return value
 }
 
-export async function readUserPrefs(payload: Payload, userId: string | number): Promise<UserPrefs> {
+/**
+ * The scoped read came back empty. That is normal on a fresh install, but it is
+ * also what an operator sees when the settings row was written under another
+ * owner than the resolved staff collection: the row exists, is ignored,
+ * and the whole plugin silently runs on the defaults — a `try/catch` away from
+ * any signal. So: if a row with this key exists under ANOTHER owner, say so.
+ *
+ * Same message covers the other case, deliberately: a `support-settings` row
+ * owned by a non-staff principal is exactly the poisoning attempt this scope was
+ * added to defeat, and the operator should hear about it. Once per cache window
+ * at most (the extra query only runs when nothing was found).
+ */
+async function warnOnForeignSettingsRow(payload: Payload, staff: string): Promise<void> {
+  if (warnedForeignSettingsRow.has(staff)) return
+  try {
+    const any = await dbFind(payload, 'payload-preferences', {
+      where: { key: { equals: PREF_KEY } },
+      limit: 1, depth: 0, overrideAccess: true,
+    })
+    if (any.docs.length === 0) return // fresh install — nothing to report
+    if (warnedForeignSettingsRow.size >= SETTINGS_CACHE_MAX) warnedForeignSettingsRow.clear()
+    warnedForeignSettingsRow.add(staff)
+    console.warn(
+      `[support] A "${PREF_KEY}" preference row exists but none is owned by the "${staff}" collection: ` +
+        'the plugin is running on its DEFAULT settings. Either the staff auth collection differs from ' +
+        '`admin.user`, or the row was written by a principal that is not staff — in which case it is ' +
+        'ignored on purpose.',
+    )
+  } catch {
+    /* diagnostic only — never let it change the outcome */
+  }
+}
+
+export async function readSupportSettings(
+  payload: Payload,
+  staffSlug?: string,
+): Promise<SupportSettings> {
+  return (await readSupportSettingsState(payload, staffSlug)).settings
+}
+
+async function readLegacyRoundRobin(payload: Payload, staff: string): Promise<boolean> {
+  try {
+    const prefs = await dbFind(payload, 'payload-preferences', {
+      where: { key: { equals: LEGACY_ROUND_ROBIN_KEY }, 'user.relationTo': { equals: staff } },
+      limit: 1, depth: 0, overrideAccess: true,
+    })
+    if (prefs.docs.length > 0) {
+      return (prefs.docs[0].value as { enabled?: boolean })?.enabled === true
+    }
+  } catch { /* ignore — defaults to disabled */ }
+  return DEFAULT_TICKETING_FEATURES.roundRobin
+}
+
+export async function readUserPrefs(
+  payload: Payload,
+  userId: string | number,
+  staffSlug?: string,
+): Promise<UserPrefs> {
   try {
     const key = `${USER_PREFS_KEY_PREFIX}-${userId}`
+    // Ids collide across auth collections: a support-client with id 7 would
+    // otherwise own `support-user-prefs-7`, the row read back for agent 7.
     const prefs = await dbFind(payload, 'payload-preferences', {
-      where: { key: { equals: key } },
+      where: {
+        key: { equals: key },
+        'user.relationTo': { equals: resolveStaffPrefSlug(payload, staffSlug) },
+      },
       limit: 1, depth: 0, overrideAccess: true,
     })
     if (prefs.docs.length > 0) {