fix(guardrails): route PII validation through app runtime

Author: TheodoreSpeaks

apps/sim/app/api/guardrails/pii/validate/route.test.ts

@@ -0,0 +1,67 @@
+/**
+ * @vitest-environment node
+ */
+import { createMockRequest, hybridAuthMockFns } from '@sim/testing'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { mockValidatePII } = vi.hoisted(() => ({
+  mockValidatePII: vi.fn(),
+}))
+
+vi.mock('@/lib/guardrails/validate_pii', () => ({
+  validatePII: mockValidatePII,
+}))
+
+import { POST } from '@/app/api/guardrails/pii/validate/route'
+
+describe('POST /api/guardrails/pii/validate', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    hybridAuthMockFns.mockCheckInternalAuth.mockResolvedValue({ success: true })
+    mockValidatePII.mockResolvedValue({ passed: true, detectedEntities: [] })
+  })
+
+  it('authenticates before validating the request body', async () => {
+    hybridAuthMockFns.mockCheckInternalAuth.mockResolvedValue({
+      success: false,
+      error: 'Internal authentication required',
+    })
+
+    const response = await POST(createMockRequest('POST', { text: 42 }))
+
+    expect(response.status).toBe(401)
+    expect(mockValidatePII).not.toHaveBeenCalled()
+  })
+
+  it('runs Presidio validation inside the app boundary', async () => {
+    const request = createMockRequest('POST', {
+      text: 'email a@b.com',
+      entityTypes: ['EMAIL_ADDRESS'],
+      mode: 'mask',
+      language: 'en',
+    })
+
+    const response = await POST(request)
+
+    expect(response.status).toBe(200)
+    await expect(response.json()).resolves.toEqual({ passed: true, detectedEntities: [] })
+    expect(mockValidatePII).toHaveBeenCalledWith({
+      text: 'email a@b.com',
+      entityTypes: ['EMAIL_ADDRESS'],
+      mode: 'mask',
+      language: 'en',
+      customPatterns: undefined,
+      requestId: 'mock-request-id',
+      abortSignal: request.signal,
+    })
+  })
+
+  it('rejects malformed input before calling Presidio', async () => {
+    const response = await POST(
+      createMockRequest('POST', { text: 'claim', entityTypes: [], mode: 'invalid' })
+    )
+
+    expect(response.status).toBe(400)
+    expect(mockValidatePII).not.toHaveBeenCalled()
+  })
+})

apps/sim/app/api/guardrails/pii/validate/route.ts

@@ -0,0 +1,35 @@
+import { type NextRequest, NextResponse } from 'next/server'
+import { guardrailsPiiValidateContract } from '@/lib/api/contracts'
+import { parseRequest } from '@/lib/api/server'
+import { checkInternalAuth } from '@/lib/auth/hybrid'
+import { generateRequestId } from '@/lib/core/utils/request'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import { validatePII } from '@/lib/guardrails/validate_pii'
+
+/**
+ * App-container capability boundary for single-text PII validation. Presidio is
+ * intentionally ECS-internal, so remote workflow runtimes authenticate here
+ * instead of importing its client and attempting to reach `PII_URL` directly.
+ */
+export const POST = withRouteHandler(async (request: NextRequest) => {
+  const auth = await checkInternalAuth(request, { requireWorkflowId: false })
+  if (!auth.success) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  const parsed = await parseRequest(guardrailsPiiValidateContract, request, {})
+  if (!parsed.success) return parsed.response
+
+  const { text, entityTypes, mode, language, customPatterns } = parsed.data.body
+  const result = await validatePII({
+    text,
+    entityTypes,
+    mode,
+    language,
+    customPatterns,
+    requestId: generateRequestId(),
+    abortSignal: request.signal,
+  })
+
+  return NextResponse.json(guardrailsPiiValidateContract.response.schema.parse(result))
+})

apps/sim/lib/api/contracts/hotspots.ts

@@ -20,6 +20,35 @@ const guardrailsMaskBatchResponseSchema = z.object({
   masked: z.array(z.string()),
 })
 
+export const guardrailsPiiValidateBodySchema = z
+  .object({
+    text: z.string().max(10_000_000, 'Text is too long'),
+    entityTypes: z.array(z.string().min(1, 'Entity type cannot be empty')).max(200),
+    mode: z.enum(['block', 'mask']),
+    language: z.string().min(1, 'Language cannot be empty').max(20).optional(),
+    customPatterns: z.array(customPatternSchema).max(20).optional(),
+  })
+  .strict()
+
+export const detectedPiiEntitySchema = z
+  .object({
+    type: z.string().min(1, 'Entity type cannot be empty').max(100),
+    start: z.number().int().nonnegative(),
+    end: z.number().int().nonnegative(),
+    score: z.number().min(0).max(1),
+    text: z.string().max(10_000_000, 'Detected text is too long'),
+  })
+  .strict()
+
+export const guardrailsPiiValidateResponseSchema = z
+  .object({
+    passed: z.boolean(),
+    error: z.string().max(1_000).optional(),
+    detectedEntities: z.array(detectedPiiEntitySchema),
+    maskedText: z.string().max(10_000_000, 'Masked text is too long').optional(),
+  })
+  .strict()
+
 /**
  * Internal batch PII masking. Called server-to-server (internal JWT) from the
  * log-redaction persist path so Presidio always runs in the app container,
@@ -38,6 +67,23 @@ export const guardrailsMaskBatchContract = defineRouteContract({
 export type GuardrailsMaskBatchBody = z.input<typeof guardrailsMaskBatchBodySchema>
 export type GuardrailsMaskBatchResult = z.output<typeof guardrailsMaskBatchResponseSchema>
 
+/**
+ * Internal single-text PII validation. The workflow executor can run outside
+ * the app network, while only the app task can reach the Presidio service.
+ */
+export const guardrailsPiiValidateContract = defineRouteContract({
+  method: 'POST',
+  path: '/api/guardrails/pii/validate',
+  body: guardrailsPiiValidateBodySchema,
+  response: {
+    mode: 'json',
+    schema: guardrailsPiiValidateResponseSchema,
+  },
+})
+
+export type GuardrailsPiiValidateBody = z.input<typeof guardrailsPiiValidateBodySchema>
+export type GuardrailsPiiValidateResult = z.output<typeof guardrailsPiiValidateResponseSchema>
+
 const chatMessageSchema = z.object({
   role: z.enum(['user', 'assistant', 'system']),
   content: z.string(),

apps/sim/lib/guardrails/validation-client.test.ts

@@ -0,0 +1,80 @@
+/**
+ * @vitest-environment node
+ */
+import { resetUrlsMock, urlsMockFns } from '@sim/testing'
+import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+afterAll(resetUrlsMock)
+
+const { mockToken } = vi.hoisted(() => ({
+  mockToken: vi.fn(),
+}))
+
+vi.mock('@/lib/auth/internal', () => ({ generateInternalToken: mockToken }))
+
+import { validatePIIViaHttp } from '@/lib/guardrails/validation-client'
+
+describe('validatePIIViaHttp', () => {
+  const mockBaseUrl = urlsMockFns.mockGetInternalApiBaseUrl
+  let fetchMock: ReturnType<typeof vi.fn>
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockToken.mockResolvedValue('internal-token')
+    mockBaseUrl.mockReturnValue('https://app.example.com')
+    fetchMock = vi.fn(async () =>
+      Response.json({ passed: true, detectedEntities: [], maskedText: 'clean' })
+    )
+    vi.stubGlobal('fetch', fetchMock)
+  })
+
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  it('calls the authenticated app capability with the caller signal', async () => {
+    const controller = new AbortController()
+
+    await expect(
+      validatePIIViaHttp(
+        {
+          text: 'clean',
+          entityTypes: ['EMAIL_ADDRESS'],
+          mode: 'mask',
+          language: 'en',
+        },
+        controller.signal
+      )
+    ).resolves.toEqual({ passed: true, detectedEntities: [], maskedText: 'clean' })
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      'https://app.example.com/api/guardrails/pii/validate',
+      expect.objectContaining({
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          authorization: 'Bearer internal-token',
+        },
+        signal: controller.signal,
+      })
+    )
+  })
+
+  it('fails on an HTTP error without retrying', async () => {
+    fetchMock.mockResolvedValueOnce(new Response('unavailable', { status: 503 }))
+
+    await expect(
+      validatePIIViaHttp({ text: 'claim', entityTypes: [], mode: 'block' })
+    ).rejects.toThrow('PII validation request failed (503): unavailable')
+    expect(fetchMock).toHaveBeenCalledOnce()
+  })
+
+  it('fails when the endpoint returns an invalid success body', async () => {
+    fetchMock.mockResolvedValueOnce(Response.json({ passed: true }))
+
+    await expect(
+      validatePIIViaHttp({ text: 'claim', entityTypes: [], mode: 'block' })
+    ).rejects.toThrow()
+    expect(fetchMock).toHaveBeenCalledOnce()
+  })
+})

apps/sim/lib/guardrails/validation-client.ts

@@ -0,0 +1,43 @@
+import type { GuardrailsPiiValidateBody, GuardrailsPiiValidateResult } from '@/lib/api/contracts'
+import {
+  guardrailsPiiValidateBodySchema,
+  guardrailsPiiValidateContract,
+  guardrailsPiiValidateResponseSchema,
+} from '@/lib/api/contracts'
+import { generateInternalToken } from '@/lib/auth/internal'
+import { getInternalApiBaseUrl } from '@/lib/core/utils/urls'
+
+/**
+ * Validates one string through the app-container PII capability boundary.
+ *
+ * Workflow tool operations execute both in the app task and in Trigger.dev
+ * workers, but only the app network can reach the ECS-internal Presidio
+ * service. Always using this boundary keeps manual and scheduled verdicts on
+ * one path and prevents the worker bundle from importing the Presidio client.
+ */
+export async function validatePIIViaHttp(
+  input: GuardrailsPiiValidateBody,
+  signal?: AbortSignal
+): Promise<GuardrailsPiiValidateResult> {
+  const body = guardrailsPiiValidateBodySchema.parse(input)
+  const token = await generateInternalToken()
+  const url = `${getInternalApiBaseUrl()}${guardrailsPiiValidateContract.path}`
+
+  // boundary-raw-fetch: cross-process capability call to the authenticated app-container PII endpoint
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      authorization: `Bearer ${token}`,
+    },
+    body: JSON.stringify(body),
+    signal,
+  })
+
+  if (!response.ok) {
+    const detail = await response.text().catch(() => '')
+    throw new Error(`PII validation request failed (${response.status}): ${detail.slice(0, 200)}`)
+  }
+
+  return guardrailsPiiValidateResponseSchema.parse(await response.json())
+}

apps/sim/lib/internal/guardrails/operations.test.ts

@@ -19,7 +19,7 @@ const mocks = vi.hoisted(() => ({
   requireBillingAttribution: vi.fn(),
   validateHallucination: vi.fn(),
   validateJson: vi.fn(),
-  validatePII: vi.fn(),
+  validatePIIViaHttp: vi.fn(),
   validateRegex: vi.fn(),
 }))
 
@@ -41,8 +41,10 @@ vi.mock('@/lib/guardrails/validate_hallucination', () => ({
   validateHallucination: mocks.validateHallucination,
 }))
 vi.mock('@/lib/guardrails/validate_json', () => ({ validateJson: mocks.validateJson }))
-vi.mock('@/lib/guardrails/validate_pii', () => ({ validatePII: mocks.validatePII }))
 vi.mock('@/lib/guardrails/validate_regex', () => ({ validateRegex: mocks.validateRegex }))
+vi.mock('@/lib/guardrails/validation-client', () => ({
+  validatePIIViaHttp: mocks.validatePIIViaHttp,
+}))
 vi.mock('@/ee/access-control/utils/permission-check', () => ({
   assertPermissionsAllowed: mocks.assertPermissionsAllowed,
   ModelNotAllowedError: class ModelNotAllowedError extends Error {},
@@ -78,7 +80,7 @@ describe('executeGuardrailsValidation', () => {
     mocks.validateHallucination.mockResolvedValue({ passed: true, score: 8 })
     mocks.validateJson.mockReturnValue({ passed: true })
     mocks.validateRegex.mockReturnValue({ passed: true })
-    mocks.validatePII.mockResolvedValue({ passed: true, detectedEntities: [] })
+    mocks.validatePIIViaHttp.mockResolvedValue({ passed: true, detectedEntities: [] })
   })
 
   it('runs hallucination work once with authorized scope, billing, provenance, and signal', async () => {
@@ -146,6 +148,38 @@ describe('executeGuardrailsValidation', () => {
     expect(mocks.requireBillingAttribution).not.toHaveBeenCalled()
   })
 
+  it('routes PII validation through the app-container capability boundary', async () => {
+    const controller = new AbortController()
+
+    const result = await executeGuardrailsValidation(
+      {
+        validationType: 'pii',
+        input: 'email a@b.com',
+        piiEntityTypes: ['EMAIL_ADDRESS'],
+        piiMode: 'mask',
+        piiLanguage: 'en',
+      },
+      {
+        actorUserId: 'user-1',
+        headers: new Headers(),
+        requestId: 'request-1',
+        signal: controller.signal,
+      }
+    )
+
+    expect(result.output.passed).toBe(true)
+    expect(mocks.validatePIIViaHttp).toHaveBeenCalledWith(
+      {
+        text: 'email a@b.com',
+        entityTypes: ['EMAIL_ADDRESS'],
+        mode: 'mask',
+        language: 'en',
+        customPatterns: undefined,
+      },
+      controller.signal
+    )
+  })
+
   it('conceals inaccessible workflow validation as a failed verdict without provider work', async () => {
     workflowAuthzMockFns.mockAuthorizeWorkflowByWorkspacePermission.mockResolvedValueOnce({
       allowed: false,

apps/sim/lib/internal/guardrails/operations.ts

@@ -12,11 +12,10 @@ import {
 import { checkAndBillPayerOverageThreshold } from '@/lib/billing/threshold-billing'
 import { prepareCopilotEnvironmentContext } from '@/lib/copilot/environment-context'
 import { inspectModelInputProvenanceRequest } from '@/lib/execution/model-input-provenance'
-import type { CustomPiiPattern } from '@/lib/guardrails/pii-entities'
 import { validateHallucination } from '@/lib/guardrails/validate_hallucination'
 import { validateJson } from '@/lib/guardrails/validate_json'
-import { validatePII } from '@/lib/guardrails/validate_pii'
 import { validateRegex } from '@/lib/guardrails/validate_regex'
+import { validatePIIViaHttp } from '@/lib/guardrails/validation-client'
 import { GuardrailsOperationError } from '@/lib/internal/guardrails/errors'
 import type { GuardrailsValidationInput } from '@/lib/internal/guardrails/input'
 import type { InternalToolOperationContext } from '@/lib/internal/tool-operations/types'
@@ -250,15 +249,16 @@ async function executeValidation(
     })
   }
   if (input.validationType === 'pii') {
-    return validatePII({
-      text: inputString,
-      entityTypes: input.piiEntityTypes || [],
-      mode: input.piiMode === 'mask' ? 'mask' : 'block',
-      language: input.piiLanguage || 'en',
-      customPatterns: input.piiCustomPatterns as CustomPiiPattern[] | undefined,
-      requestId: context.requestId,
-      abortSignal: context.signal,
-    })
+    return validatePIIViaHttp(
+      {
+        text: inputString,
+        entityTypes: input.piiEntityTypes || [],
+        mode: input.piiMode === 'mask' ? 'mask' : 'block',
+        language: input.piiLanguage || 'en',
+        customPatterns: input.piiCustomPatterns,
+      },
+      context.signal
+    )
   }
   return { passed: false, error: 'Unknown validation type' }
 }