fix(plaid): complete integration remediation

Author: Bill Leoutsakos

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

@@ -23,10 +23,12 @@ import { BlockInfoCard } from "@/components/ui/block-info-card"
 
 - Select the stored Plaid Item once per block. Reconnect after rotating the Item access token or app credentials for that same Item and environment; use a new credential for a different Item or environment. The opaque credential ID stays the same for existing workflows. Deleting the Sim credential removes only the local encrypted copy and does not revoke or remove the Item at Plaid.
 - Plaid Item credentials are workspace credentials and are available according to workspace credential permissions. Use dedicated, access-controlled workflows for Auth and Identity data.
-- Transaction Sync returns one page per call. Preserve `nextCursor` and continue while `hasMore` is true. If Plaid returns `TRANSACTIONS_SYNC_MUTATION_DURING_PAGINATION`, discard that batch and restart from the cursor where the batch began. A cursor belongs to its account-filter stream; start with no cursor after changing the account filter.
-- Account fields offer single- and multi-account selectors backed by the selected Item. Institution lookup offers searchable results and hydrates a saved selection by ID. Advanced manual fields remain available for account or institution IDs that cannot be loaded in the editor. Account filters are optional and default to all accounts on the Item.
+- Transaction Sync returns one page per call. Preserve `nextCursor` and continue while `hasMore` is true. Cursors are at most 256 characters. If Plaid returns `TRANSACTIONS_SYNC_MUTATION_DURING_PAGINATION`, discard that batch and restart from the cursor where the batch began. A cursor belongs to its account-filter stream; start with no cursor after changing the account filter. `daysRequested` applies only before Transactions is initialized; in Production, values below 30 still request at least 30 days.
+- Account fields offer single- and multi-account selectors backed by the selected Item. Institution lookup offers searchable results and hydrates a saved selection by ID. Advanced manual fields remain available for account or institution IDs that cannot be loaded in the editor. Account filters are optional and default to all accounts on the Item. The standard Auth selector includes checking, savings, and cash-management accounts but cannot prove that an account is debitable, and it excludes limited-purpose checking accounts that a Plaid customer has specifically enabled; use the advanced manual field only when the account is known to be eligible for the configured Auth use case.
 - Institution search returns at most ten matches. The Search Institutions action remains available when you need its full institution records or want to supply non-US country codes and product filters.
-- Get Balances usually completes in under ten seconds but can take 30 seconds or more. `minLastUpdatedDatetime` is an RFC 3339 date-time and is required by Plaid only for certain Capital One non-depository requests.
+- Get Balances usually completes in under ten seconds but can take 30 seconds or more. Each successful `/accounts/balance/get` call is billable. For evaluating insufficient-funds risk on a proposed ACH transaction, Plaid recommends `/signal/evaluate`; use Get Balances for other real-time balance needs. `minLastUpdatedDatetime` is an RFC 3339 date-time and is required by Plaid only for certain Capital One non-depository requests.
+- Every successful action returns `requestId`. Include it when troubleshooting in Plaid's Activity Log or contacting Plaid Support.
+- Sim accepts Plaid provider responses up to 10 MiB. Account endpoints are not automatically paginated; each action returns the single response supplied by Plaid.
 - Get Auth account and routing numbers, and Get Identity personally identifiable information, are standard tool outputs. They can enter workflow and execution state, downstream blocks, Agent or model context, and requests to the configured model provider. `hiddenFromDisplay` suppresses only the Get Auth source block's `numbers` field from log display; it does not enforce non-persistence or prevent downstream access. Send Auth numbers only to an approved non-Plaid-partner payment processor, and do not route Auth or Identity data to Agents, models, or durable sinks unless that transmission and retention are explicitly approved.
 - Plaid Sandbox is useful for contract testing but does not reproduce all Production institution behavior. Product access, optional fields, consent, and institution-specific errors still need Production validation.
 {/* MANUAL-CONTENT-END */}
@@ -48,16 +50,17 @@ Incrementally sync transactions for a linked Item. Omit the cursor on the first
 
 | Parameter | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
-| `cursor` | string | No | Cursor from a previous sync \(nextCursor\); omit to start from the beginning |
+| `cursor` | string | No | Cursor from a previous sync \(nextCursor\), up to 256 characters; omit to start from the beginning |
 | `count` | number | No | Number of updates to fetch per page \(Plaid requires 1-500; default 100\) |
 | `accountId` | string | No | Scope the sync \(and cursor\) to a single account ID |
 | `includeOriginalDescription` | boolean | No | Include the unmodified original_description from the institution |
-| `daysRequested` | number | No | Days of history to request \(Plaid allows 1-730; default 90\). Only applies before Transactions is initialized on the Item |
+| `daysRequested` | number | No | Days of history to request \(Plaid allows 1-730; default 90 and Production requests at least 30\). Only applies before Transactions is initialized on the Item |
 
 #### Output
 
 | Parameter | Type | Description |
 | --------- | ---- | ----------- |
+| `requestId` | string | Unique Plaid request ID for troubleshooting and support |
 | `added` | array | Transactions added since the cursor |
 |   ↳ `transaction_id` | string | Unique ID of the transaction |
 |   ↳ `account_id` | string | ID of the account the transaction belongs to |
@@ -161,6 +164,7 @@ List the accounts linked to an Item with their names, types, and balances. Balan
 
 | Parameter | Type | Description |
 | --------- | ---- | ----------- |
+| `requestId` | string | Unique Plaid request ID for troubleshooting and support |
 | `accounts` | array | Accounts linked to the Item |
 |   ↳ `account_id` | string | Unique Plaid account ID |
 |   ↳ `name` | string | Account name |
@@ -195,6 +199,7 @@ Get real-time balances for the accounts linked to an Item. The live institution
 
 | Parameter | Type | Description |
 | --------- | ---- | ----------- |
+| `requestId` | string | Unique Plaid request ID for troubleshooting and support |
 | `accounts` | array | Accounts with refreshed real-time balances |
 |   ↳ `account_id` | string | Unique Plaid account ID |
 |   ↳ `name` | string | Account name |
@@ -228,6 +233,7 @@ Get account-holder identity information (names, emails, phone numbers, and addre
 
 | Parameter | Type | Description |
 | --------- | ---- | ----------- |
+| `requestId` | string | Unique Plaid request ID for troubleshooting and support |
 | `accounts` | array | Accounts with their owners identity data |
 |   ↳ `account_id` | string | Unique Plaid account ID |
 |   ↳ `name` | string | Account name |
@@ -279,6 +285,7 @@ Get account and routing numbers for depository accounts linked to an Item (ACH f
 
 | Parameter | Type | Description |
 | --------- | ---- | ----------- |
+| `requestId` | string | Unique Plaid request ID for troubleshooting and support |
 | `accounts` | array | Depository accounts on the Item |
 |   ↳ `account_id` | string | Unique Plaid account ID |
 |   ↳ `name` | string | Account name |
@@ -330,6 +337,7 @@ Get metadata and health status for a linked Item, including its institution, ena
 
 | Parameter | Type | Description |
 | --------- | ---- | ----------- |
+| `requestId` | string | Unique Plaid request ID for troubleshooting and support |
 | `item` | object | Item metadata |
 |   ↳ `item_id` | string | Unique ID of the Item |
 |   ↳ `institution_id` | string | Plaid institution ID the Item is linked to |
@@ -380,6 +388,7 @@ Search financial institutions supported by Plaid by name, returning at most 10
 
 | Parameter | Type | Description |
 | --------- | ---- | ----------- |
+| `requestId` | string | Unique Plaid request ID for troubleshooting and support |
 | `institutions` | array | Institutions matching the search |
 |   ↳ `institution_id` | string | Unique Plaid institution ID |
 |   ↳ `name` | string | Institution name |
@@ -388,7 +397,7 @@ Search financial institutions supported by Plaid by name, returning at most 10
 |   ↳ `url` | string | Institution website URL |
 |   ↳ `primary_color` | string | Institution brand color \(hex\) |
 |   ↳ `routing_numbers` | array | Known routing numbers for the institution |
-|   ↳ `oauth` | boolean | Whether the institution uses an OAuth login flow |
+|   ↳ `oauth` | boolean | Whether some Items may require OAuth or the institution may be migrating to OAuth |
 | `count` | number | Number of institutions returned |
 
 ### Plaid Get Institution
@@ -406,6 +415,7 @@ Get details for a financial institution by its Plaid institution ID
 
 | Parameter | Type | Description |
 | --------- | ---- | ----------- |
+| `requestId` | string | Unique Plaid request ID for troubleshooting and support |
 | `institution` | object | Institution details |
 |   ↳ `institution_id` | string | Unique Plaid institution ID |
 |   ↳ `name` | string | Institution name |
@@ -414,6 +424,6 @@ Get details for a financial institution by its Plaid institution ID
 |   ↳ `url` | string | Institution website URL |
 |   ↳ `primary_color` | string | Institution brand color \(hex\) |
 |   ↳ `routing_numbers` | array | Known routing numbers for the institution |
-|   ↳ `oauth` | boolean | Whether the institution uses an OAuth login flow |
+|   ↳ `oauth` | boolean | Whether some Items may require OAuth or the institution may be migrating to OAuth |
 
 

apps/sim/app/api/tools/plaid/options/route.test.ts

@@ -2,24 +2,22 @@
  * @vitest-environment node
  */
 import { authMockFns, createMockRequest } from '@sim/testing'
+import { NextRequest } from 'next/server'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
 const { mockExecute } = vi.hoisted(() => ({ mockExecute: vi.fn() }))
 
-vi.mock('@/lib/credentials/application/list-plaid-options', async () => {
-  const { credentialOperations } = await vi.importActual<
-    typeof import('@/lib/credentials/application/operations')
-  >('@/lib/credentials/application/operations')
-  return {
-    listPlaidOptions: {
-      operation: credentialOperations.read,
-      execute: mockExecute,
-    },
-  }
-})
+vi.mock('@/lib/credentials/application/list-plaid-options', () => ({
+  listPlaidOptions: {
+    operation: { id: 'credentials.read' },
+    execute: mockExecute,
+  },
+}))
 
+import { PLAID_OPTIONS_REQUEST_MAX_BYTES } from '@/lib/api/contracts/selectors/plaid'
 import { OrchestrationError } from '@/lib/core/orchestration/types'
 import { POST } from '@/app/api/tools/plaid/options/route'
+import { PlaidGatewayError, PlaidProviderError } from '@/tools/plaid/utils.server'
 
 const body = {
   kind: 'accounts',
@@ -31,6 +29,19 @@ function request(requestBody: unknown = body, headers: Record<string, string> =
   return createMockRequest('POST', requestBody, headers)
 }
 
+function rawRequest(
+  requestBody: string,
+  signal?: AbortSignal,
+  headers: Record<string, string> = {}
+) {
+  return new NextRequest('http://localhost:3000/api/tools/plaid/options', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', ...headers },
+    body: requestBody,
+    signal,
+  })
+}
+
 describe('POST /api/tools/plaid/options', () => {
   beforeEach(() => {
     vi.clearAllMocks()
@@ -82,6 +93,33 @@ describe('POST /api/tools/plaid/options', () => {
     expect(mockExecute).not.toHaveBeenCalled()
   })
 
+  it('rejects invalid JSON before application execution', async () => {
+    const response = await POST(rawRequest('{"kind":'))
+
+    expect(response.status).toBe(400)
+    await expect(response.json()).resolves.toMatchObject({
+      error: 'Request body must be valid JSON',
+    })
+    expect(mockExecute).not.toHaveBeenCalled()
+  })
+
+  it('rejects an actual body larger than the Plaid selector-route ceiling', async () => {
+    const response = await POST(
+      rawRequest(
+        JSON.stringify({
+          ...body,
+          padding: 'x'.repeat(PLAID_OPTIONS_REQUEST_MAX_BYTES),
+        })
+      )
+    )
+
+    expect(response.status).toBe(413)
+    await expect(response.json()).resolves.toMatchObject({
+      error: `Request body exceeds the maximum allowed size of ${PLAID_OPTIONS_REQUEST_MAX_BYTES} bytes`,
+    })
+    expect(mockExecute).not.toHaveBeenCalled()
+  })
+
   it('accepts long provider identifiers within the route byte ceiling', async () => {
     const query = 'x'.repeat(10_001)
     const response = await POST(
@@ -110,4 +148,65 @@ describe('POST /api/tools/plaid/options', () => {
     expect(response.status).toBe(status)
     expect(JSON.stringify(await response.json())).not.toContain('item-token')
   })
+
+  it('preserves sanitized Plaid provider errors', async () => {
+    mockExecute.mockRejectedValueOnce(
+      new PlaidProviderError(400, {
+        error_code: 'ITEM_LOGIN_REQUIRED',
+        error_type: 'ITEM_ERROR',
+        request_id: 'plaid-request-1',
+      })
+    )
+
+    const response = await POST(request())
+
+    expect(response.status).toBe(400)
+    await expect(response.json()).resolves.toMatchObject({
+      error_code: 'ITEM_LOGIN_REQUIRED',
+      error_type: 'ITEM_ERROR',
+      request_id: 'plaid-request-1',
+    })
+  })
+
+  it('projects Plaid gateway failures as a safe 502 response', async () => {
+    mockExecute.mockRejectedValueOnce(new PlaidGatewayError('Plaid request timed out'))
+
+    const response = await POST(request())
+
+    expect(response.status).toBe(502)
+    await expect(response.json()).resolves.toMatchObject({ error: 'Plaid request timed out' })
+  })
+
+  it('returns 499 when selector execution fails after the client disconnects', async () => {
+    const controller = new AbortController()
+    mockExecute.mockImplementationOnce(async () => {
+      controller.abort()
+      throw new DOMException('The operation was aborted.', 'AbortError')
+    })
+
+    const response = await POST(rawRequest(JSON.stringify(body), controller.signal))
+
+    expect(response.status).toBe(499)
+    await expect(response.json()).resolves.toMatchObject({ error: 'Client cancelled request' })
+  })
+
+  it('fails closed on an unexpected selector error', async () => {
+    mockExecute.mockRejectedValueOnce(new Error('item-token-should-not-leak'))
+
+    const response = await POST(request())
+
+    expect(response.status).toBe(500)
+    const responseBody = await response.json()
+    expect(responseBody).toMatchObject({ error: 'Internal server error' })
+    expect(JSON.stringify(responseBody)).not.toContain('item-token-should-not-leak')
+  })
+
+  it('fails closed when selector output violates the response contract', async () => {
+    mockExecute.mockResolvedValueOnce({ options: [{ id: '', label: '' }] })
+
+    const response = await POST(request())
+
+    expect(response.status).toBe(500)
+    await expect(response.json()).resolves.toMatchObject({ error: 'Internal server error' })
+  })
 })

apps/sim/app/api/tools/plaid/options/route.ts

@@ -1,4 +1,7 @@
-import { plaidOptionsContract } from '@/lib/api/contracts/selectors/plaid'
+import {
+  PLAID_OPTIONS_REQUEST_MAX_BYTES,
+  plaidOptionsContract,
+} from '@/lib/api/contracts/selectors/plaid'
 import {
   defineInternalJsonRoute,
   internalRateLimits,
@@ -16,7 +19,7 @@ export const POST = defineInternalJsonRoute({
   operation: credentialOperations.read,
   rateLimit: internalRateLimits.none({ reason: 'Bounded editor selector request' }),
   errorPolicy: plaidErrorPolicy,
-  parseOptions: { maxBodyBytes: 64 * 1024 },
+  parseOptions: { maxBodyBytes: PLAID_OPTIONS_REQUEST_MAX_BYTES },
   mapInput: ({ body }, { request }) => ({ body, signal: request.signal }),
   useCase: listPlaidOptions,
 })