improvement(utils): add shared utility functions and replace inline patterns (#4214)

* improvement(utils): add shared utility functions and replace inline patterns

Add sleep, toError, safeJsonParse, isNonNull helpers and invariant/assertNever
assertions. Replace all inline implementations across the codebase with these
shared utilities for consistency. Zero behavioral changes.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(agiloft): remove import type from .server module to fix client bundle build

Turbopack resolves .server.ts modules even for type-only imports,
pulling dns/promises into client bundles. Define SecureFetchResponse
locally instead.

* fix(agiloft): revert to client-safe imports to fix build

The SSRF upgrade to input-validation.server introduced dns/promises
into client bundles via tools/registry.ts. Revert to the original
client-safe validateExternalUrl + fetch. The SSRF DNS-pinning upgrade
for agiloft directExecution should be done via API routes in a
separate PR.

* feat(agiloft): add API route for retrieve_attachment, matching established file patterns

Convert retrieve_attachment from directExecution to standard API route
pattern, consistent with Slack download and Google Drive download tools.

- Create /api/tools/agiloft/retrieve with DNS validation, auth lifecycle,
  and base64 file response matching the { file: { name, mimeType, data,
  size } } convention
- Update retrieve_attachment tool to use request/transformResponse
  instead of directExecution, removing the dependency on
  executeAgiloftRequest from the tool definition
- File output type: 'file' enables FileToolProcessor to store downloaded
  files in execution filesystem automatically

* shopify

* fix(agiloft): add optional flag to nullable lock record block outputs

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(agiloft): revert optional flag on block outputs — property only exists on tool outputs

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* chore(utils): remove unused utilities (asserts, safeJsonParse, isNonNull)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: waleedlatif1

.claude/rules/global.md

@@ -30,5 +30,25 @@ const shortId = generateShortId()
 const tiny = generateShortId(8)
 ```
 
+## Common Utilities
+Use shared helpers from `@/lib/core/utils/helpers` instead of writing inline implementations:
+
+- `sleep(ms)` — async delay. Never write `new Promise(resolve => setTimeout(resolve, ms))`
+- `toError(value)` — normalize unknown caught values to `Error`. Never write `e instanceof Error ? e : new Error(String(e))`
+- `toError(value).message` — get error message safely. Never write `e instanceof Error ? e.message : String(e)`
+
+```typescript
+// ✗ Bad
+await new Promise(resolve => setTimeout(resolve, 1000))
+const msg = error instanceof Error ? error.message : String(error)
+const err = error instanceof Error ? error : new Error(String(error))
+
+// ✓ Good
+import { sleep, toError } from '@/lib/core/utils/helpers'
+await sleep(1000)
+const msg = toError(error).message
+const err = toError(error)
+```
+
 ## Package Manager
 Use `bun` and `bunx`, not `npm` and `npx`.

.cursor/rules/global.mdc

@@ -37,5 +37,25 @@ const shortId = generateShortId()
 const tiny = generateShortId(8)
 ```
 
+## Common Utilities
+Use shared helpers from `@/lib/core/utils/helpers` instead of writing inline implementations:
+
+- `sleep(ms)` — async delay. Never write `new Promise(resolve => setTimeout(resolve, ms))`
+- `toError(value)` — normalize unknown caught values to `Error`. Never write `e instanceof Error ? e : new Error(String(e))`
+- `toError(value).message` — get error message safely. Never write `e instanceof Error ? e.message : String(e)`
+
+```typescript
+// ✗ Bad
+await new Promise(resolve => setTimeout(resolve, 1000))
+const msg = error instanceof Error ? error.message : String(error)
+const err = error instanceof Error ? error : new Error(String(error))
+
+// ✓ Good
+import { sleep, toError } from '@/lib/core/utils/helpers'
+await sleep(1000)
+const msg = toError(error).message
+const err = toError(error)
+```
+
 ## Package Manager
 Use `bun` and `bunx`, not `npm` and `npx`.

CLAUDE.md

@@ -8,6 +8,7 @@ You are a professional software engineer. All code must follow best practices: a
 - **Comments**: Use TSDoc for documentation. No `====` separators. No non-TSDoc comments
 - **Styling**: Never update global styles. Keep all styling local to components
 - **ID Generation**: Never use `crypto.randomUUID()`, `nanoid`, or `uuid` package. Use `generateId()` (UUID v4) or `generateShortId()` (compact) from `@/lib/core/utils/uuid`
+- **Common Utilities**: Use shared helpers from `@/lib/core/utils/helpers` instead of inline implementations. `sleep(ms)` for delays, `toError(e)` to normalize caught values.
 - **Package Manager**: Use `bun` and `bunx`, not `npm` and `npx`
 
 ## Architecture

apps/sim/app/academy/components/sandbox-canvas-provider.tsx

@@ -12,6 +12,7 @@ import type {
 } from '@/lib/academy/types'
 import { validateExercise } from '@/lib/academy/validation'
 import { cn } from '@/lib/core/utils/cn'
+import { sleep } from '@/lib/core/utils/helpers'
 import { getEffectiveBlockOutputs } from '@/lib/workflows/blocks/block-outputs'
 import { getQueryClient } from '@/app/_shell/providers/get-query-client'
 import { GlobalCommandsProvider } from '@/app/workspace/[workspaceId]/providers/global-commands-provider'
@@ -323,7 +324,7 @@ export function SandboxCanvasProvider({
       for (let i = 0; i < plan.length; i++) {
         const step = plan[i]
         setActiveBlocks(workflowId, new Set([step.blockId]))
-        await new Promise((resolve) => setTimeout(resolve, step.delay))
+        await sleep(step.delay)
         addConsole({
           workflowId,
           blockId: step.blockId,

apps/sim/app/api/auth/oauth/utils.ts

@@ -4,6 +4,7 @@ import { account, credential, credentialSetMember } from '@sim/db/schema'
 import { createLogger } from '@sim/logger'
 import { and, desc, eq, inArray } from 'drizzle-orm'
 import { decryptSecret } from '@/lib/core/security/encryption'
+import { toError } from '@/lib/core/utils/helpers'
 import { refreshOAuthToken } from '@/lib/oauth'
 import {
   getMicrosoftRefreshTokenExpiry,
@@ -331,7 +332,7 @@ export async function getOAuthToken(userId: string, providerId: string): Promise
       return accessToken
     } catch (error) {
       logger.error(`Error refreshing token for user ${userId}, provider ${providerId}`, {
-        error: error instanceof Error ? error.message : String(error),
+        error: toError(error).message,
         stack: error instanceof Error ? error.stack : undefined,
         providerId,
         userId,
@@ -460,7 +461,7 @@ export async function refreshAccessTokenIfNeeded(
       return refreshedToken.accessToken
     } catch (error) {
       logger.error(`[${requestId}] Error refreshing token for credential`, {
-        error: error instanceof Error ? error.message : String(error),
+        error: toError(error).message,
         stack: error instanceof Error ? error.stack : undefined,
         providerId: credential.providerId,
         credentialId,
@@ -664,7 +665,7 @@ export async function getCredentialsForCredentialSet(
         }
       } catch (error) {
         logger.error(`Failed to refresh token for user ${cred.userId}, provider ${providerId}`, {
-          error: error instanceof Error ? error.message : String(error),
+          error: toError(error).message,
         })
         continue
       }

apps/sim/app/api/auth/oauth2/shopify/store/route.ts

@@ -5,6 +5,7 @@ import { and, eq } from 'drizzle-orm'
 import { type NextRequest, NextResponse } from 'next/server'
 import { getSession } from '@/lib/auth'
 import { getBaseUrl } from '@/lib/core/utils/urls'
+import { isSameOrigin } from '@/lib/core/utils/validation'
 import { processCredentialDraft } from '@/lib/credentials/draft-processor'
 import { safeAccountInsert } from '@/app/api/auth/oauth/utils'
 
@@ -113,7 +114,7 @@ export async function GET(request: NextRequest) {
 
     const returnUrl = request.cookies.get('shopify_return_url')?.value
 
-    const redirectUrl = returnUrl || `${baseUrl}/workspace`
+    const redirectUrl = returnUrl && isSameOrigin(returnUrl) ? returnUrl : `${baseUrl}/workspace`
     const finalUrl = new URL(redirectUrl)
     finalUrl.searchParams.set('shopify_connected', 'true')
 

apps/sim/app/api/auth/shopify/authorize/route.ts

@@ -4,6 +4,7 @@ import { getSession } from '@/lib/auth'
 import { env } from '@/lib/core/config/env'
 import { getBaseUrl } from '@/lib/core/utils/urls'
 import { generateId } from '@/lib/core/utils/uuid'
+import { isSameOrigin } from '@/lib/core/utils/validation'
 import { getScopesForService } from '@/lib/oauth/utils'
 
 const logger = createLogger('ShopifyAuthorize')
@@ -192,7 +193,7 @@ export async function GET(request: NextRequest) {
       path: '/',
     })
 
-    if (returnUrl) {
+    if (returnUrl && isSameOrigin(returnUrl)) {
       response.cookies.set('shopify_return_url', returnUrl, {
         httpOnly: true,
         secure: process.env.NODE_ENV === 'production',

apps/sim/app/api/auth/socket-token/route.ts

@@ -3,6 +3,7 @@ import { headers } from 'next/headers'
 import { NextResponse } from 'next/server'
 import { auth } from '@/lib/auth'
 import { isAuthDisabled } from '@/lib/core/config/feature-flags'
+import { toError } from '@/lib/core/utils/helpers'
 
 const logger = createLogger('SocketTokenAPI')
 
@@ -36,7 +37,7 @@ export async function POST() {
     }
 
     logger.error('Failed to generate socket token', {
-      error: error instanceof Error ? error.message : String(error),
+      error: toError(error).message,
       stack: error instanceof Error ? error.stack : undefined,
     })
     return NextResponse.json({ error: 'Failed to generate token' }, { status: 500 })

apps/sim/app/api/auth/sso/register/route.ts

@@ -147,6 +147,32 @@ export async function POST(request: NextRequest) {
       oidcConfig.userInfoEndpoint = userInfoEndpoint
       oidcConfig.jwksEndpoint = jwksEndpoint
 
+      const userProvidedEndpoints: Record<string, string | undefined> = {
+        authorizationEndpoint,
+        tokenEndpoint,
+        userInfoEndpoint,
+        jwksEndpoint,
+      }
+
+      for (const [name, endpointUrl] of Object.entries(userProvidedEndpoints)) {
+        if (endpointUrl) {
+          const endpointValidation = await validateUrlWithDNS(endpointUrl, `OIDC ${name}`)
+          if (!endpointValidation.isValid) {
+            logger.warn('Explicitly provided OIDC endpoint failed SSRF validation', {
+              endpoint: name,
+              url: endpointUrl,
+              error: endpointValidation.error,
+            })
+            return NextResponse.json(
+              {
+                error: `OIDC ${name} failed security validation: ${endpointValidation.error}`,
+              },
+              { status: 400 }
+            )
+          }
+        }
+      }
+
       const needsDiscovery =
         !oidcConfig.authorizationEndpoint || !oidcConfig.tokenEndpoint || !oidcConfig.jwksEndpoint
 

apps/sim/app/api/billing/switch-plan/route.ts

@@ -17,6 +17,7 @@ import {
   hasUsableSubscriptionStatus,
 } from '@/lib/billing/subscriptions/utils'
 import { isBillingEnabled } from '@/lib/core/config/feature-flags'
+import { toError } from '@/lib/core/utils/helpers'
 import { captureServerEvent } from '@/lib/posthog/server'
 
 const logger = createLogger('SwitchPlan')
@@ -185,7 +186,7 @@ export async function POST(request: NextRequest) {
   } catch (error) {
     logger.error('Failed to switch subscription', {
       userId: session?.user?.id,
-      error: error instanceof Error ? error.message : String(error),
+      error: toError(error).message,
     })
     return NextResponse.json(
       { error: error instanceof Error ? error.message : 'Failed to switch plan' },