fix(zoho-desk): five-audit round - serializer trigger-advanced leak, scopes, paging

Five independent audits (OAuth/scopes, tools-vs-docs, block/selectors,
blast-radius, /validate-trigger). Findings, most severe first.

A trigger-mode field was a live tool-mode required param. `shouldSerializeSubBlock`
excluded `mode: 'trigger'` but not `'trigger-advanced'`, so the trigger's required
`manualOrgId` validated on every tool operation. Reproduced against the real
serializer: with the Organization field pinned to advanced, running
List Organizations failed with "Missing required fields: Organization ID" - a
field that operation does not even render, and which the user could not clear
without switching operations. Fixed in the serializer rather than locally,
because the Google Sheets/Drive/Calendar pollers have the identical shape.

`limit=200` on /organizations was an undocumented parameter I added by
extrapolating from /departments and /agents. Zoho documents NO parameters for
that endpoint and its sample is a bare GET; the other siblings cap at 100 and
Zoho answers out-of-range with 422. Since orgId gates every tool and both other
selectors, a 422 there would have made the whole integration unreachable. Reverted
to Zoho's documented shape.

`descriptionText` was HTML-stripping plain text. The previous round made the strip
unconditional after finding Zoho sends no `descriptionContentType`, but Zoho's REST
samples show plain descriptions while only the webhook payload is HTML - and the
webhook path runs this over contact/account/department bodies too. html-to-text is
not identity on plain text: it decodes entities and deletes tag-shaped content
("a < b > c", XML snippets). Now sniffs for markup first.

`omitUnset` made every documented field-clear impossible. Zoho's own PATCH sample
uses `"classification": ""` and `"productId": ""` to clear. Dropping `''` meant no
scalar field could be cleared. Now drops only undefined/null - the serializer-null
case it was written for - and forwards `''`.

status/priority leaked between operations. One shared subBlock served both the
list_tickets filter and the update_ticket value, and subBlock values survive an
operation switch, so a filter of "Open,On Hold" could be PATCHed onto a ticket and
an update value could silently filter a later list. Split per operation.

Auth: `invalid_code` added to TERMINAL_ERRORS - it is Zoho's code for a revoked
refresh token, so without it the previous round's refresh fix never actually
dead-flagged the credential it was written for. The shared refresh body-error
branch now also requires `!data.access_token`, so no provider can have a
successful refresh misclassified. The token route now uses the validating
`extractZohoDeskBaseFromScope` instead of a private regex with no https/allowlist
check - that value is injected into every tool call. Scope list falls back to the
requested scopes when Zoho omits `scope`, which would otherwise flag every
credential as needing reconnect. The Self Client mint no longer sends
`aaaserver.profile.READ`, a scope that grant never uses.

Trigger: `includePrevState` now set for every *_Update event, not just tickets -
it defaults to false, so prevState was permanently null for contact/agent/task/
article updates while the trigger advertised it. `departmentIds` is only sent for
events Zoho documents as accepting it, and the field is conditioned accordingly.
Empty filters serialize as `null`, matching Zoho's examples, rather than `{}`.
JWKS fetch bounded to 1.5s - jose's default is 5000ms, exactly Zoho's whole
delivery deadline, and Zoho publishes no retry. The create-time validation POST
fallback is now matched by the pending-verification probe. Ticket_Delete added.

All 17 webhook event ids, the POST /api/v1/webhooks body contract, and the JWT
claim/JWKS specifics are now confirmed verbatim against Zoho's webhook
documentation - previously 12 of 17 events and the entire subscription contract
were unverified.

Author: waleedlatif1

apps/docs/content/docs/en/integrations/zoho_desk.mdx

@@ -70,7 +70,7 @@ List tickets from a Zoho Desk organization with optional filters. Returns a list
 |   ↳ `ticketNumber` | string | Human-readable ticket number |
 |   ↳ `subject` | string | Ticket subject |
 |   ↳ `description` | string | Ticket description \(raw; may be HTML\) |
-|   ↳ `descriptionText` | string | Plain-text rendering of the description with HTML stripped \(Zoho sends ticket descriptions as HTML\) |
+|   ↳ `descriptionText` | string | Plain-text rendering of the description: HTML stripped when the body contains markup, otherwise the description verbatim |
 |   ↳ `status` | string | Ticket status |
 |   ↳ `statusType` | string | Status category \(Open/Closed/On Hold\) |
 |   ↳ `priority` | string | Ticket priority |
@@ -121,7 +121,7 @@ Retrieve a single Zoho Desk ticket by ID.
 |   ↳ `ticketNumber` | string | Human-readable ticket number |
 |   ↳ `subject` | string | Ticket subject |
 |   ↳ `description` | string | Ticket description \(raw; may be HTML\) |
-|   ↳ `descriptionText` | string | Plain-text rendering of the description with HTML stripped \(Zoho sends ticket descriptions as HTML\) |
+|   ↳ `descriptionText` | string | Plain-text rendering of the description: HTML stripped when the body contains markup, otherwise the description verbatim |
 |   ↳ `status` | string | Ticket status |
 |   ↳ `statusType` | string | Status category \(Open/Closed/On Hold\) |
 |   ↳ `priority` | string | Ticket priority |
@@ -182,7 +182,7 @@ Update fields on an existing Zoho Desk ticket.
 |   ↳ `ticketNumber` | string | Human-readable ticket number |
 |   ↳ `subject` | string | Ticket subject |
 |   ↳ `description` | string | Ticket description \(raw; may be HTML\) |
-|   ↳ `descriptionText` | string | Plain-text rendering of the description with HTML stripped \(Zoho sends ticket descriptions as HTML\) |
+|   ↳ `descriptionText` | string | Plain-text rendering of the description: HTML stripped when the body contains markup, otherwise the description verbatim |
 |   ↳ `status` | string | Ticket status |
 |   ↳ `statusType` | string | Status category \(Open/Closed/On Hold\) |
 |   ↳ `priority` | string | Ticket priority |
@@ -296,7 +296,7 @@ Add a comment to a Zoho Desk ticket.
 
 ### `zoho_desk_list_threads`
 
-List conversation threads on a Zoho Desk ticket, newest first (Zoho sorts by sendDateTime descending by default).
+List conversation threads on a Zoho Desk ticket, newest first (Zoho sorts by sendDateTime descending by default). Returns a list projection: message bodies (content, summary, to/cc/bcc) come back only from Get Thread.
 
 #### Input
 
@@ -330,6 +330,9 @@ List conversation threads on a Zoho Desk ticket, newest first (Zoho sorts by sen
 |   ↳ `bcc` | string | BCC email address |
 |   ↳ `replyTo` | string | Reply-to email address |
 |   ↳ `isForward` | boolean | Whether the thread is a forward |
+|   ↳ `isContentTruncated` | boolean | Whether Zoho truncated the thread content; fetch fullContentURL for the rest |
+|   ↳ `fullContentURL` | string | URL returning the untruncated thread content |
+|   ↳ `plainText` | string | Zoho's own plain-text rendering of the thread, when it supplies one |
 |   ↳ `status` | string | Delivery status of an outgoing thread \(SUCCESS/FAILED/DRAFT\) |
 |   ↳ `isDescriptionThread` | boolean | Whether this thread is the ticket's original description |
 |   ↳ `visibility` | string | Thread visibility \(e.g. public\) |
@@ -383,6 +386,9 @@ Retrieve the full content of a single Zoho Desk ticket thread.
 |   ↳ `bcc` | string | BCC email address |
 |   ↳ `replyTo` | string | Reply-to email address |
 |   ↳ `isForward` | boolean | Whether the thread is a forward |
+|   ↳ `isContentTruncated` | boolean | Whether Zoho truncated the thread content; fetch fullContentURL for the rest |
+|   ↳ `fullContentURL` | string | URL returning the untruncated thread content |
+|   ↳ `plainText` | string | Zoho's own plain-text rendering of the thread, when it supplies one |
 |   ↳ `status` | string | Delivery status of an outgoing thread \(SUCCESS/FAILED/DRAFT\) |
 |   ↳ `isDescriptionThread` | boolean | Whether this thread is the ticket's original description |
 |   ↳ `visibility` | string | Thread visibility \(e.g. public\) |
@@ -504,6 +510,6 @@ Trigger a workflow when a Zoho Desk event occurs (ticket, comment, thread, conta
 | `eventType` | string | The Zoho Desk event type \(e.g. Ticket_Add\) |
 | `eventTime` | string | Event time in milliseconds since epoch |
 | `orgId` | string | Zoho Desk organization ID |
-| `payload` | json | The full resource that changed \(ticket, comment, thread, etc.\). For comment/thread events a derived plain-text `contentText` is added alongside the raw `content` + `contentType`. |
+| `payload` | json | The full resource that changed \(ticket, comment, thread, etc.\). Comment and thread events gain a derived plain-text `contentText` alongside the raw `content` + `contentType`; ticket events gain `descriptionText` alongside `description`. |
 | `prevState` | json | Previous state of the resource \(update events only\) |
 

apps/sim/app/api/auth/oauth/token/route.ts

@@ -20,6 +20,7 @@ import {
   resolveOAuthAccountId,
   resolveServiceAccountToken,
 } from '@/app/api/auth/oauth/utils'
+import { extractZohoDeskBaseFromScope } from '@/tools/zoho_desk/host-allowlist'
 
 export const dynamic = 'force-dynamic'
 
@@ -29,7 +30,6 @@ const SALESFORCE_INSTANCE_URL_REGEX = /__sf_instance__:([^\s]+)/
 // Stop at a comma or whitespace: better-auth persists Zoho's scopes comma-joined
 // (no spaces), so a greedy `\S+` would swallow the whole scope list into the host.
 // The Desk base URL itself never contains a comma or space.
-const ZOHO_DESK_BASE_URL_REGEX = /__zoho_domain__:([^\s,]+)/
 
 /**
  * Get an access token for a specific credential
@@ -300,10 +300,10 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
       // assume a host. Surface it as apiDomain for tool param injection.
       let apiDomain: string | undefined
       if (credential.providerId === 'zoho-desk' && credential.scope) {
-        const domainMatch = credential.scope.match(ZOHO_DESK_BASE_URL_REGEX)
-        if (domainMatch) {
-          apiDomain = domainMatch[1]
-        }
+        // Use the shared extractor, not a local regex: it also enforces https +
+        // the Zoho apex allowlist. This value is injected into EVERY tool call,
+        // so an unvalidated host here would receive the OAuth token.
+        apiDomain = extractZohoDeskBaseFromScope(credential.scope)
       }
 
       return NextResponse.json(
@@ -424,10 +424,10 @@ export const GET = withRouteHandler(async (request: NextRequest) => {
       // assume a host. Surface it as apiDomain for tool param injection.
       let apiDomain: string | undefined
       if (credential.providerId === 'zoho-desk' && credential.scope) {
-        const domainMatch = credential.scope.match(ZOHO_DESK_BASE_URL_REGEX)
-        if (domainMatch) {
-          apiDomain = domainMatch[1]
-        }
+        // Use the shared extractor, not a local regex: it also enforces https +
+        // the Zoho apex allowlist. This value is injected into EVERY tool call,
+        // so an unvalidated host here would receive the OAuth token.
+        apiDomain = extractZohoDeskBaseFromScope(credential.scope)
       }
 
       return NextResponse.json(

apps/sim/app/api/tools/zoho_desk/attachment/route.ts

@@ -89,6 +89,15 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
       )
     }
 
+    // A 204 (or any non-200 success) carries no body, so arrayBuffer() would
+    // yield zero bytes and the route would report success with an empty file.
+    if (response.status !== 200) {
+      return NextResponse.json(
+        { success: false, error: `Attachment returned no content (HTTP ${response.status})` },
+        { status: 502 }
+      )
+    }
+
     const arrayBuffer = await response.arrayBuffer()
 
     // ToolFileData (consumed by FileToolProcessor) keys the file name as `name`.

apps/sim/app/api/tools/zoho_desk/organizations/route.ts

@@ -41,14 +41,15 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
   let organizationsUrl: URL
   try {
     organizationsUrl = assertZohoUrl(`${apiBase}/organizations`)
-    // Zoho's listing APIs default to a page size of 10. Without an explicit
-    // limit, an account with more than ten accessible portals would silently get
-    // a truncated dropdown - and because every other selector and every tool
-    // call is gated on orgId, a missing portal is unreachable except through the
-    // advanced manual field. 200 is the documented per-page ceiling on the
-    // sibling listing endpoints and is far above any real portal count, so this
-    // needs no drain loop.
-    organizationsUrl.searchParams.set('limit', '200')
+    // Deliberately sends NO query parameters. Zoho's `/organizations` doc block
+    // lists none at all - not `from`, not `limit` - and its own sample is a bare
+    // GET. An earlier revision passed `limit=200` by extrapolating from
+    // /departments and /agents, but the other siblings (/tickets, /contacts,
+    // /comments) cap at 100 and Zoho answers an out-of-range value with 422
+    // INVALID_DATA. Since `orgId` gates every tool and both other selectors, a
+    // 422 here would make the whole integration unreachable except through the
+    // manual field - a far worse failure than the known downside of sending
+    // nothing, which is Zoho's default page size (10 portals).
   } catch {
     return NextResponse.json({ error: 'Credential resolved to a non-Zoho host' }, { status: 400 })
   }

apps/sim/blocks/blocks/zoho-desk.ts

@@ -174,19 +174,39 @@ export const ZohoDeskBlock: BlockConfig<ZohoDeskResponse> = {
       placeholder: 'New subject',
       condition: { field: 'operation', value: 'update_ticket' },
     },
+    // status/priority are deliberately split per operation rather than shared.
+    // A subBlock keeps its value when the operation changes, and the two uses are
+    // semantically opposite: on list_tickets they are filters (comma-separated,
+    // matching), on update_ticket they are the new value written to the ticket.
+    // Sharing one field meant a filter of "Open,On Hold" could be PATCHed onto a
+    // ticket, and an update value of "Closed" could silently filter a later list.
     {
       id: 'status',
       title: 'Status',
       type: 'short-input',
-      placeholder: 'e.g. Open, Closed',
-      condition: { field: 'operation', value: ['update_ticket', 'list_tickets'] },
+      placeholder: 'e.g. Closed',
+      condition: { field: 'operation', value: 'update_ticket' },
     },
     {
       id: 'priority',
       title: 'Priority',
       type: 'short-input',
       placeholder: 'e.g. High',
-      condition: { field: 'operation', value: ['update_ticket', 'list_tickets'] },
+      condition: { field: 'operation', value: 'update_ticket' },
+    },
+    {
+      id: 'statusFilter',
+      title: 'Status',
+      type: 'short-input',
+      placeholder: 'Filter, e.g. Open,On Hold',
+      condition: { field: 'operation', value: 'list_tickets' },
+    },
+    {
+      id: 'priorityFilter',
+      title: 'Priority',
+      type: 'short-input',
+      placeholder: 'Filter, e.g. High,Urgent',
+      condition: { field: 'operation', value: 'list_tickets' },
     },
     {
       id: 'assigneeId',
@@ -405,6 +425,10 @@ export const ZohoDeskBlock: BlockConfig<ZohoDeskResponse> = {
           limit: rawLimit,
           contentType,
           isPublic,
+          status: rawStatus,
+          priority: rawPriority,
+          statusFilter: rawStatusFilter,
+          priorityFilter: rawPriorityFilter,
           customFields: rawCustomFields,
           departmentIds: rawDepartmentIds,
           ...rest
@@ -459,6 +483,17 @@ export const ZohoDeskBlock: BlockConfig<ZohoDeskResponse> = {
         // stale (or half-typed) JSON left behind after switching away from
         // Update Ticket would otherwise fail every unrelated operation with
         // "Invalid JSON provided for custom fields" - on runs that never send it.
+        // Both tools take `status` / `priority`; pick the field belonging to the
+        // selected operation so a stale value from the other one can never leak.
+        const activeStatus = params.operation === 'list_tickets' ? rawStatusFilter : rawStatus
+        const activePriority = params.operation === 'list_tickets' ? rawPriorityFilter : rawPriority
+        if (activeStatus !== undefined && activeStatus !== null && activeStatus !== '') {
+          result.status = activeStatus
+        }
+        if (activePriority !== undefined && activePriority !== null && activePriority !== '') {
+          result.priority = activePriority
+        }
+
         if (params.operation === 'update_ticket' && rawCustomFields !== undefined) {
           if (typeof rawCustomFields === 'string') {
             if (rawCustomFields.trim()) {
@@ -488,7 +523,9 @@ export const ZohoDeskBlock: BlockConfig<ZohoDeskResponse> = {
     contentType: { type: 'string', description: 'Comment content type (plainText/html)' },
     isPublic: { type: 'boolean', description: 'Whether a comment is public' },
     subject: { type: 'string', description: 'Ticket subject' },
-    status: { type: 'string', description: 'Ticket status' },
+    status: { type: 'string', description: 'Ticket status to set' },
+    statusFilter: { type: 'string', description: 'Status filter for listing tickets' },
+    priorityFilter: { type: 'string', description: 'Priority filter for listing tickets' },
     priority: { type: 'string', description: 'Ticket priority' },
     assigneeId: { type: 'string', description: 'Assignee (agent) ID' },
     description: { type: 'string', description: 'Ticket description' },

apps/sim/lib/auth/auth.ts

@@ -2123,8 +2123,18 @@ export const auth = betterAuth({
             const deskBase = deriveZohoDeskBaseFromApiDomain(
               typeof data.api_domain === 'string' ? data.api_domain : undefined
             )
-            const grantedScopes =
+            // Zoho's docs are inconsistent about whether the Desk token response
+            // carries `scope` (the Mail sample has it; the CRM/Creator samples do
+            // not). If it is absent, fall back to the scopes we requested and were
+            // granted by completing the flow - otherwise the stored scope list is
+            // just the domain marker, and the credential picker would show a
+            // permanent "needs update / reconnect" badge on every connection.
+            // Mirrors the existing Box fallback in this file.
+            const reportedScopes =
               typeof data.scope === 'string' ? data.scope.split(/[\s,]+/).filter(Boolean) : []
+            const grantedScopes = reportedScopes.length
+              ? reportedScopes
+              : getCanonicalScopesForProvider('zoho-desk')
             tokens.scopes = [`__zoho_domain__:${deskBase}`, ...grantedScopes]
             return tokens
           },

apps/sim/lib/credentials/client-credential-accounts/minters/zoho-desk.test.ts

@@ -154,8 +154,11 @@ describe('mintZohoDeskServiceAccountToken', () => {
     expect(body.get('grant_type')).toBe('client_credentials')
     expect(body.get('client_id')).toBe('zoho-cid')
     expect(body.get('client_secret')).toBe('zoho-secret')
-    expect(body.get('scope')).toBe(SCOPES.join(','))
+    // Comma-separated, and Desk-only: `aaaserver.profile.READ` belongs to the
+    // interactive OAuth flow's getUserInfo call, which this grant never makes.
+    expect(body.get('scope')).toBe('Desk.tickets.READ,Desk.contacts.READ')
     expect(body.get('scope')).not.toContain(' ')
+    expect(body.get('scope')).not.toContain('aaaserver')
     expect(body.get('soid')).toBe('ZohoDesk.600123456')
     expect(mockGetCanonicalScopesForProvider).toHaveBeenCalledWith('zoho-desk')
   })

apps/sim/lib/credentials/client-credential-accounts/minters/zoho-desk.ts

@@ -165,7 +165,14 @@ export async function mintZohoDeskServiceAccountToken(
 
   // Zoho requires a comma-separated scope list on this endpoint; a
   // space-separated list is rejected as an invalid scope.
-  const scope = getCanonicalScopesForProvider('zoho-desk').join(',')
+  // Only the Desk.* scopes. `aaaserver.profile.READ` exists for the interactive
+  // OAuth flow's getUserInfo call; this grant never hits the Accounts profile
+  // endpoint (identity is synthesized from orgId, and skipIdentity bypasses it
+  // entirely at execution time). Sending an Accounts-server scope on the Desk
+  // soid grant risks an opaque invalid_scope rejection for no benefit.
+  const scope = getCanonicalScopesForProvider('zoho-desk')
+    .filter((s) => s.startsWith('Desk.'))
+    .join(',')
 
   const res = await fetchProvider(
     `${dataCenter.accountsBase}/oauth/v2/token`,

apps/sim/lib/integrations/integrations.json

@@ -21844,7 +21844,7 @@
         },
         {
           "name": "List Threads",
-          "description": "List conversation threads on a Zoho Desk ticket, newest first (Zoho sorts by sendDateTime descending by default)."
+          "description": "List conversation threads on a Zoho Desk ticket, newest first (Zoho sorts by sendDateTime descending by default). Returns a list projection: message bodies (content, summary, to/cc/bcc) come back only from Get Thread."
         },
         {
           "name": "Get Thread",

apps/sim/lib/oauth/oauth.ts

@@ -1886,13 +1886,30 @@ export async function refreshOAuthToken(
     // execution retries a refresh that can never succeed. Classify on the body
     // before trusting the status, matching the token-exchange and service-account
     // mint paths, which already do this.
-    if (data && typeof data === 'object' && typeof data.error === 'string' && data.error) {
+    // The `!data.access_token` guard matters because this branch runs for EVERY
+    // provider: without it, a provider that ever returns an informational `error`
+    // alongside a valid token would have all its credentials fail refresh - and
+    // if that string is one of TERMINAL_ERRORS, be marked dead for an hour. No
+    // current provider does that, but the branch should not depend on it. Zoho's
+    // failure bodies carry no token, so the guard costs nothing here.
+    if (
+      data &&
+      typeof data === 'object' &&
+      typeof data.error === 'string' &&
+      data.error &&
+      !data.access_token
+    ) {
       logger.error('Token refresh failed with an error body:', {
         status: response.status,
+        statusText: response.statusText,
         error: data.error,
         errorDescription:
           typeof data.error_description === 'string' ? data.error_description : null,
         providerId,
+        tokenEndpoint: config.tokenEndpoint,
+        hasClientId: !!config.clientId,
+        hasClientSecret: !!config.clientSecret,
+        hasRefreshToken: !!refreshToken,
       })
       return {
         ok: false,