fix(managed-agent): proxy routes no longer 500 on decrypt failure

Followup on PR #5769 review: Cursor Bugbot flagged that
`getDecryptedApiKey` still throws on ciphertext decrypt failure, so
the five proxy routes (agents / environments / environment-detail /
vaults / memory-stores) surface a 500 to the client instead of a
controlled response. My prior tool-level try/catch only handled the
workflow-block invocation path.

Change: `getDecryptedApiKey` now returns a discriminated result —
`{ ok: true, apiKey } | { ok: false, reason: 'not_found' | 'decrypt_failed' }`
— so callers can render each failure mode with the correct status:
- `not_found` → 404 "Connection not found" (unchanged)
- `decrypt_failed` → 502 with an actionable "rotate the API key to
  re-encrypt" hint, matching the tool-side message

New `apiKeyFailureResponse` helper in `lib/managed-agents/proxy.ts`
keeps the mapping in one place — each proxy route now reads:
    const keyResult = await getDecryptedApiKey({ id, workspaceId })
    if (!keyResult.ok) return apiKeyFailureResponse(keyResult)
    const apiKey = keyResult.apiKey

Tool call site (`run_session.server.ts`) collapses its previous
try/catch to the same `keyResult.ok` check — cleaner and shares the
same error phrasing.

Tests updated: `getDecryptedApiKey` cases now assert the shape;
added a third case that mocks `decryptSecret` to reject and asserts
`{ ok: false, reason: 'decrypt_failed' }`. All 87 tests pass.

Author: Ricardo DeMatos

apps/sim/app/api/managed-agent-connections/[id]/agents/route.ts

@@ -12,6 +12,7 @@ import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 import { getDecryptedApiKey } from '@/lib/managed-agents/connections'
 import {
   type AnthropicListPage,
+  apiKeyFailureResponse,
   ManagedAgentProxyError,
   proxyManagedAgentsGet,
 } from '@/lib/managed-agents/proxy'
@@ -56,10 +57,9 @@ export const GET = withRouteHandler(async (request: NextRequest, context: RouteC
       return NextResponse.json({ error: 'Access denied' }, { status: 403 })
     }
 
-    const apiKey = await getDecryptedApiKey({ id, workspaceId })
-    if (!apiKey) {
-      return NextResponse.json({ error: 'Connection not found' }, { status: 404 })
-    }
+    const keyResult = await getDecryptedApiKey({ id, workspaceId })
+    if (!keyResult.ok) return apiKeyFailureResponse(keyResult)
+    const apiKey = keyResult.apiKey
 
     try {
       const body = await proxyManagedAgentsGet<AnthropicListPage<AnthropicAgent>>(

apps/sim/app/api/managed-agent-connections/[id]/environments/[envId]/route.ts

@@ -11,6 +11,7 @@ import { generateRequestId } from '@/lib/core/utils/request'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 import { getDecryptedApiKey } from '@/lib/managed-agents/connections'
 import {
+  apiKeyFailureResponse,
   ManagedAgentProxyError,
   proxyManagedAgentsGet,
 } from '@/lib/managed-agents/proxy'
@@ -60,10 +61,9 @@ export const GET = withRouteHandler(async (request: NextRequest, context: RouteC
       return NextResponse.json({ error: 'Access denied' }, { status: 403 })
     }
 
-    const apiKey = await getDecryptedApiKey({ id, workspaceId })
-    if (!apiKey) {
-      return NextResponse.json({ error: 'Connection not found' }, { status: 404 })
-    }
+    const keyResult = await getDecryptedApiKey({ id, workspaceId })
+    if (!keyResult.ok) return apiKeyFailureResponse(keyResult)
+    const apiKey = keyResult.apiKey
 
     try {
       const body = await proxyManagedAgentsGet<AnthropicEnvironment>(

apps/sim/app/api/managed-agent-connections/[id]/environments/route.ts

@@ -12,6 +12,7 @@ import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 import { getDecryptedApiKey } from '@/lib/managed-agents/connections'
 import {
   type AnthropicListPage,
+  apiKeyFailureResponse,
   ManagedAgentProxyError,
   proxyManagedAgentsGet,
 } from '@/lib/managed-agents/proxy'
@@ -56,10 +57,9 @@ export const GET = withRouteHandler(async (request: NextRequest, context: RouteC
       return NextResponse.json({ error: 'Access denied' }, { status: 403 })
     }
 
-    const apiKey = await getDecryptedApiKey({ id, workspaceId })
-    if (!apiKey) {
-      return NextResponse.json({ error: 'Connection not found' }, { status: 404 })
-    }
+    const keyResult = await getDecryptedApiKey({ id, workspaceId })
+    if (!keyResult.ok) return apiKeyFailureResponse(keyResult)
+    const apiKey = keyResult.apiKey
 
     try {
       const body = await proxyManagedAgentsGet<AnthropicListPage<AnthropicEnvironment>>(

apps/sim/app/api/managed-agent-connections/[id]/memory-stores/route.ts

@@ -11,6 +11,7 @@ import { generateRequestId } from '@/lib/core/utils/request'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 import { getDecryptedApiKey } from '@/lib/managed-agents/connections'
 import {
+  apiKeyFailureResponse,
   ManagedAgentProxyError,
   proxyManagedAgentsGet,
 } from '@/lib/managed-agents/proxy'
@@ -69,10 +70,9 @@ export const GET = withRouteHandler(async (request: NextRequest, context: RouteC
       return NextResponse.json({ error: 'Access denied' }, { status: 403 })
     }
 
-    const apiKey = await getDecryptedApiKey({ id, workspaceId })
-    if (!apiKey) {
-      return NextResponse.json({ error: 'Connection not found' }, { status: 404 })
-    }
+    const keyResult = await getDecryptedApiKey({ id, workspaceId })
+    if (!keyResult.ok) return apiKeyFailureResponse(keyResult)
+    const apiKey = keyResult.apiKey
 
     try {
       const body = await proxyManagedAgentsGet<AnthropicMemoryStorePage>(

apps/sim/app/api/managed-agent-connections/[id]/vaults/route.ts

@@ -12,6 +12,7 @@ import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 import { getDecryptedApiKey } from '@/lib/managed-agents/connections'
 import {
   type AnthropicListPage,
+  apiKeyFailureResponse,
   ManagedAgentProxyError,
   proxyManagedAgentsGet,
 } from '@/lib/managed-agents/proxy'
@@ -54,10 +55,9 @@ export const GET = withRouteHandler(async (request: NextRequest, context: RouteC
       return NextResponse.json({ error: 'Access denied' }, { status: 403 })
     }
 
-    const apiKey = await getDecryptedApiKey({ id, workspaceId })
-    if (!apiKey) {
-      return NextResponse.json({ error: 'Connection not found' }, { status: 404 })
-    }
+    const keyResult = await getDecryptedApiKey({ id, workspaceId })
+    if (!keyResult.ok) return apiKeyFailureResponse(keyResult)
+    const apiKey = keyResult.apiKey
 
     try {
       const body = await proxyManagedAgentsGet<AnthropicListPage<AnthropicVault>>(

apps/sim/lib/managed-agents/connections.test.ts

@@ -169,19 +169,29 @@ describe('getDecryptedApiKey', () => {
     dbState.whereCalls = []
   })
 
-  it('returns the decrypted plaintext when the connection exists', async () => {
+  it('returns {ok:true, apiKey} when the connection exists', async () => {
     dbState.selectResults = [[baseRow]]
-    const key = await getDecryptedApiKey({ id: 'conn_1', workspaceId: 'ws_A' })
-    expect(key).toBe(PLAINTEXT_KEY)
+    const result = await getDecryptedApiKey({ id: 'conn_1', workspaceId: 'ws_A' })
+    expect(result).toEqual({ ok: true, apiKey: PLAINTEXT_KEY })
     // The DB lookup must include BOTH id and workspaceId (no cross-workspace read).
     expect(JSON.stringify(dbState.whereCalls[0])).toContain('conn_1')
     expect(JSON.stringify(dbState.whereCalls[0])).toContain('ws_A')
   })
 
-  it('returns null when the connection does not exist for that workspace', async () => {
+  it('returns {ok:false, reason:"not_found"} when the connection does not exist', async () => {
     dbState.selectResults = [[]]
-    const key = await getDecryptedApiKey({ id: 'conn_1', workspaceId: 'ws_A' })
-    expect(key).toBeNull()
+    const result = await getDecryptedApiKey({ id: 'conn_1', workspaceId: 'ws_A' })
+    expect(result).toEqual({ ok: false, reason: 'not_found' })
+  })
+
+  it('returns {ok:false, reason:"decrypt_failed"} when the ciphertext cannot be decrypted', async () => {
+    // Simulates the post-ENCRYPTION_KEY-rotation case: row exists but the
+    // stored blob no longer decrypts. Callers must render this as an
+    // actionable 502 rather than a 500.
+    dbState.selectResults = [[baseRow]]
+    mockDecryptSecret.mockRejectedValueOnce(new Error('bad auth tag'))
+    const result = await getDecryptedApiKey({ id: 'conn_1', workspaceId: 'ws_A' })
+    expect(result).toEqual({ ok: false, reason: 'decrypt_failed' })
   })
 })
 

apps/sim/lib/managed-agents/connections.ts

@@ -86,19 +86,38 @@ export async function getConnection(params: {
   return rows[0] ?? null
 }
 
+/**
+ * Result of {@link getDecryptedApiKey}. Callers must distinguish the two
+ * failure modes so they can surface the right message:
+ *   - `not_found`: the row does not exist for this workspace — 404.
+ *   - `decrypt_failed`: the row exists but its ciphertext cannot be
+ *     decoded (typically after an `ENCRYPTION_KEY` rotation) — a
+ *     controlled 502 with a "rotate the API key to re-encrypt" hint.
+ */
+export type DecryptedApiKeyResult =
+  | { ok: true; apiKey: string }
+  | { ok: false; reason: 'not_found' | 'decrypt_failed' }
+
 /**
  * Decrypts the stored API key for a given connection. Server-side only —
  * never expose the return value to the browser. Callers are proxy routes
- * and the workflow-block tool.
+ * and the workflow-block tool. Returns a discriminated result rather
+ * than throwing so callers can respond with an actionable status code
+ * (404 vs 502) instead of leaking an unhandled 500.
  */
 export async function getDecryptedApiKey(params: {
   id: string
   workspaceId: string
-}): Promise<string | null> {
+}): Promise<DecryptedApiKeyResult> {
   const row = await getConnection(params)
-  if (!row) return null
-  const { decrypted } = await decryptSecret(row.encryptedApiKey)
-  return decrypted
+  if (!row) return { ok: false, reason: 'not_found' }
+  try {
+    const { decrypted } = await decryptSecret(row.encryptedApiKey)
+    return { ok: true, apiKey: decrypted }
+  } catch (err) {
+    logger.warn(`Failed to decrypt api key for connection ${params.id}`, { error: err })
+    return { ok: false, reason: 'decrypt_failed' }
+  }
 }
 
 export interface CreateConnectionInput {

apps/sim/lib/managed-agents/proxy.ts

@@ -1,4 +1,6 @@
 import { createLogger } from '@sim/logger'
+import { NextResponse } from 'next/server'
+import type { DecryptedApiKeyResult } from '@/lib/managed-agents/connections'
 import {
   ANTHROPIC_API_BASE,
   ANTHROPIC_VERSION,
@@ -58,3 +60,24 @@ export interface AnthropicListPage<T> {
   has_more?: boolean
   last_id?: string
 }
+
+/**
+ * Map a {@link DecryptedApiKeyResult} failure to the correct HTTP
+ * response for a proxy route. Keeps the "not_found → 404" and
+ * "decrypt_failed → 502 + actionable message" mapping in one place so
+ * every proxy route surfaces the same UX for the same failure mode.
+ */
+export function apiKeyFailureResponse(
+  failure: Extract<DecryptedApiKeyResult, { ok: false }>
+): NextResponse {
+  if (failure.reason === 'decrypt_failed') {
+    return NextResponse.json(
+      {
+        error:
+          'Managed Agent connection could not be decrypted — the workspace encryption key may have rotated. Rotate the API key in Settings → Managed Agents to re-encrypt.',
+      },
+      { status: 502 }
+    )
+  }
+  return NextResponse.json({ error: 'Connection not found' }, { status: 404 })
+}

apps/sim/tools/managed_agent/run_session.server.ts

@@ -83,33 +83,18 @@ const impl: ManagedAgentServerImpl = async (
     return { success: false, output: {}, error: 'aborted' }
   }
 
-  let apiKey: string | null
-  try {
-    apiKey = await getDecryptedApiKey({ id: params.connection, workspaceId })
-  } catch (error) {
-    // The stored ciphertext could not be decrypted — most commonly a rotated
-    // ENCRYPTION_KEY invalidating an existing row. Translate the exception
-    // into the tool's declared error shape rather than rejecting the promise
-    // (which would surface as an unhandled workflow failure).
-    logger.warn('Failed to decrypt Managed Agent api key', {
-      workspaceId,
-      connectionId: params.connection,
-      error: getErrorMessage(error),
-    })
+  const keyResult = await getDecryptedApiKey({ id: params.connection, workspaceId })
+  if (!keyResult.ok) {
     return {
       success: false,
       output: {},
       error:
-        'Managed Agent connection could not be decrypted — the workspace encryption key may have rotated. Rotate the API key in Settings → Managed Agents to re-encrypt.',
-    }
-  }
-  if (!apiKey) {
-    return {
-      success: false,
-      output: {},
-      error: 'Managed Agent connection not found. Reconnect the Claude workspace and retry.',
+        keyResult.reason === 'decrypt_failed'
+          ? 'Managed Agent connection could not be decrypted — the workspace encryption key may have rotated. Rotate the API key in Settings → Managed Agents to re-encrypt.'
+          : 'Managed Agent connection not found. Reconnect the Claude workspace and retry.',
     }
   }
+  const apiKey = keyResult.apiKey
 
   if (isPayloadDebugEnabled()) {
     logger.info('Managed agent tool raw params (pre-normalization)', {