feat(oracle-epm): add guarded foundation

Author: Bill Leoutsakos

apps/sim/lib/api/contracts/credentials.test.ts

@@ -3,6 +3,7 @@
  */
 import { describe, expect, it } from 'vitest'
 import {
+  createCredentialBodySchema,
   updateCredentialByIdBodySchema,
   workspaceCredentialSchema,
 } from '@/lib/api/contracts/credentials'
@@ -46,3 +47,24 @@ describe('workspaceCredentialSchema unredacted', () => {
     expect(workspaceCredentialSchema.safeParse(credential).success).toBe(false)
   })
 })
+
+describe('Oracle EPM service-account credential contract', () => {
+  const valid = {
+    workspaceId: '00000000-0000-4000-8000-000000000001',
+    type: 'service_account' as const,
+    providerId: 'oracle-epm-service-account',
+    orgId: 'https://epm.example.com/gateway',
+    clientId: 'integration.user@example.com',
+    clientSecret: 'password',
+  }
+
+  it('accepts the descriptor-required integration-user fields', () => {
+    expect(createCredentialBodySchema.safeParse(valid).success).toBe(true)
+  })
+
+  it.each(['orgId', 'clientId', 'clientSecret'] as const)('rejects a missing %s', (field) => {
+    expect(createCredentialBodySchema.safeParse({ ...valid, [field]: undefined }).success).toBe(
+      false
+    )
+  })
+})

apps/sim/lib/credentials/client-credential-accounts/descriptors.test.ts

@@ -7,6 +7,7 @@ import {
   getClientCredentialAccountDescriptor,
   NETSUITE_SERVICE_ACCOUNT_PROVIDER_ID,
   normalizeNetSuiteSuiteTalkOrigin,
+  ORACLE_EPM_SERVICE_ACCOUNT_PROVIDER_ID,
   partitionClientCredentialFields,
   resolveClientCredentialAuthMethod,
   resolveSalesforceAuthMethod,
@@ -19,6 +20,7 @@ const salesforce = getClientCredentialAccountDescriptor(SALESFORCE_SERVICE_ACCOU
 const box = getClientCredentialAccountDescriptor(BOX_SERVICE_ACCOUNT_PROVIDER_ID)!
 const zohoDesk = getClientCredentialAccountDescriptor(ZOHO_DESK_SERVICE_ACCOUNT_PROVIDER_ID)!
 const netSuite = getClientCredentialAccountDescriptor(NETSUITE_SERVICE_ACCOUNT_PROVIDER_ID)!
+const oracleEpm = getClientCredentialAccountDescriptor(ORACLE_EPM_SERVICE_ACCOUNT_PROVIDER_ID)!
 
 const ids = (fields: { id: string }[]) => fields.map((field) => field.id)
 
@@ -51,6 +53,14 @@ describe('partitionClientCredentialFields', () => {
         multiline: true,
       })
     })
+
+    it('declares the Oracle EPM integration user without a UI-specific implementation', () => {
+      const { visible, required } = partitionClientCredentialFields(oracleEpm, undefined)
+      expect(ids(visible)).toEqual(['orgId', 'clientId', 'clientSecret'])
+      expect(ids(required)).toEqual(['orgId', 'clientId', 'clientSecret'])
+      expect(oracleEpm.connectNoun).toBe('integration user')
+      expect(oracleEpm.fields.find((field) => field.id === 'clientSecret')?.secret).toBe(true)
+    })
   })
 
   describe('Salesforce, which offers two grants', () => {

apps/sim/lib/credentials/client-credential-accounts/descriptors.ts

@@ -111,13 +111,15 @@ export const BOX_SERVICE_ACCOUNT_PROVIDER_ID = 'box-service-account' as const
 export const SALESFORCE_SERVICE_ACCOUNT_PROVIDER_ID = 'salesforce-service-account' as const
 export const ZOHO_DESK_SERVICE_ACCOUNT_PROVIDER_ID = 'zoho-desk-service-account' as const
 export const NETSUITE_SERVICE_ACCOUNT_PROVIDER_ID = 'netsuite-service-account' as const
+export const ORACLE_EPM_SERVICE_ACCOUNT_PROVIDER_ID = 'oracle-epm-service-account' as const
 
 export type ClientCredentialAccountProviderId =
   | typeof ZOOM_SERVICE_ACCOUNT_PROVIDER_ID
   | typeof BOX_SERVICE_ACCOUNT_PROVIDER_ID
   | typeof SALESFORCE_SERVICE_ACCOUNT_PROVIDER_ID
   | typeof ZOHO_DESK_SERVICE_ACCOUNT_PROVIDER_ID
   | typeof NETSUITE_SERVICE_ACCOUNT_PROVIDER_ID
+  | typeof ORACLE_EPM_SERVICE_ACCOUNT_PROVIDER_ID
 
 /**
  * Exact account-specific SuiteTalk origin accepted by NetSuite's OAuth and
@@ -531,6 +533,37 @@ export const CLIENT_CREDENTIAL_ACCOUNT_DESCRIPTORS: Record<
     helpText:
       'Use the account-specific SuiteTalk URL and the client ID, certificate ID, and private key from one OAuth 2.0 client-credentials mapping.',
   },
+  [ORACLE_EPM_SERVICE_ACCOUNT_PROVIDER_ID]: {
+    providerId: ORACLE_EPM_SERVICE_ACCOUNT_PROVIDER_ID,
+    serviceLabel: 'Oracle EPM Cloud',
+    connectNoun: 'integration user',
+    fields: [
+      {
+        id: 'orgId',
+        label: 'Environment URL',
+        placeholder: 'https://example.oraclecloud.com/epmcloud',
+        secret: false,
+        hintPattern: /^https:\/\//,
+        hintMessage: 'Expected the full HTTPS URL for one Oracle EPM environment.',
+      },
+      {
+        id: 'clientId',
+        label: 'Integration username',
+        placeholder: 'integration.user@example.com',
+        secret: false,
+      },
+      {
+        id: 'clientSecret',
+        label: 'Password',
+        placeholder: 'Paste the integration user password',
+        secret: true,
+      },
+    ],
+    docsUrl:
+      'https://docs.oracle.com/en/cloud/saas/enterprise-performance-management-common/prest/overview.html',
+    helpText:
+      'The credential is bound to one EPM environment. Use a dedicated integration user with only the permissions its workflows require.',
+  },
 }
 
 /**

apps/sim/lib/credentials/client-credential-accounts/minters/oracle-epm.test.ts

@@ -0,0 +1,55 @@
+/** @vitest-environment node */
+import { describe, expect, it, vi } from 'vitest'
+import { mintOracleEpmServiceAccountToken } from '@/lib/credentials/client-credential-accounts/minters/oracle-epm'
+import { TokenServiceAccountValidationError } from '@/lib/credentials/token-service-accounts/errors'
+
+describe('mintOracleEpmServiceAccountToken', () => {
+  it('mints Basic authentication locally and binds the normalized destination', async () => {
+    const fetchSpy = vi.spyOn(globalThis, 'fetch')
+    const result = await mintOracleEpmServiceAccountToken({
+      orgId: ' https://EPM.example.com/gateway/ ',
+      clientId: 'integration.user@example.com',
+      clientSecret: 'password',
+    })
+    expect(Buffer.from(result.accessToken, 'base64').toString()).toBe(
+      'integration.user@example.com:password'
+    )
+    expect(result).toMatchObject({
+      expiresInSeconds: 600,
+      instanceUrl: 'https://epm.example.com/gateway',
+      identity: {
+        principal: null,
+        auditMetadata: { environmentUrl: 'https://epm.example.com/gateway' },
+        storedMetadata: { environmentUrl: 'https://epm.example.com/gateway' },
+      },
+    })
+    expect(JSON.stringify(result.identity)).not.toContain('password')
+    expect(JSON.stringify(result.identity)).not.toContain('integration.user')
+    expect(fetchSpy).not.toHaveBeenCalled()
+    fetchSpy.mockRestore()
+  })
+
+  it.each([
+    { clientId: 'user:name', clientSecret: 'password' },
+    { clientId: 'user\nname', clientSecret: 'password' },
+    { clientId: 'user', clientSecret: 'pass\nword' },
+    { clientId: '', clientSecret: 'password' },
+  ])('rejects unsafe Basic credential text', async (credentials) => {
+    await expect(
+      mintOracleEpmServiceAccountToken({
+        orgId: 'https://epm.example.com',
+        ...credentials,
+      })
+    ).rejects.toBeInstanceOf(TokenServiceAccountValidationError)
+  })
+
+  it('does not reflect secrets in validation errors', async () => {
+    const secret = 'password-with-newline\n'
+    const error = await mintOracleEpmServiceAccountToken({
+      orgId: 'https://epm.example.com',
+      clientId: 'user',
+      clientSecret: secret,
+    }).catch((value: unknown) => value)
+    expect(JSON.stringify(error)).not.toContain(secret)
+  })
+})

apps/sim/lib/credentials/client-credential-accounts/minters/oracle-epm.ts

@@ -0,0 +1,76 @@
+import type {
+  ClientCredentialAccountFields,
+  ClientCredentialAccountMintOptions,
+  ClientCredentialAccountMintResult,
+} from '@/lib/credentials/client-credential-accounts/server'
+import {
+  requireClientSecret,
+  TokenServiceAccountValidationError,
+} from '@/lib/credentials/token-service-accounts/errors'
+import { normalizeOracleEpmDestination } from '@/lib/internal/oracle-epm/destination'
+
+const SYNTHETIC_TOKEN_TTL_SECONDS = 600
+const MAX_USERNAME_BYTES = 255
+const MAX_AUTH_VALUE_BYTES = 1_024
+const FORBIDDEN_CREDENTIAL_TEXT = /[\u0000-\u001f\u007f]/
+
+function invalidCredentials(reason: string): TokenServiceAccountValidationError {
+  return new TokenServiceAccountValidationError('invalid_credentials', 400, {
+    step: 'oracle_epm_basic_auth',
+    reason,
+  })
+}
+
+/**
+ * Builds credential-bound Basic authentication locally. Oracle EPM does not
+ * expose a token mint for this v1 flow, so connect performs no network probe.
+ */
+export async function mintOracleEpmServiceAccountToken(
+  fields: ClientCredentialAccountFields,
+  _options?: ClientCredentialAccountMintOptions
+): Promise<ClientCredentialAccountMintResult> {
+  let instanceUrl: string
+  try {
+    instanceUrl = normalizeOracleEpmDestination(fields.orgId)
+  } catch {
+    throw new TokenServiceAccountValidationError('site_not_found', 400, {
+      step: 'oracle_epm_destination_validation',
+      reason: 'environment URL must be a valid HTTPS Oracle EPM destination',
+    })
+  }
+
+  const username = fields.clientId.trim()
+  const password = requireClientSecret(
+    fields.clientSecret,
+    'oracle_epm_basic_auth',
+    'Oracle EPM Cloud'
+  )
+  if (
+    !username ||
+    username.includes(':') ||
+    FORBIDDEN_CREDENTIAL_TEXT.test(username) ||
+    Buffer.byteLength(username, 'utf8') > MAX_USERNAME_BYTES
+  ) {
+    throw invalidCredentials('integration username is invalid')
+  }
+  if (
+    !password ||
+    FORBIDDEN_CREDENTIAL_TEXT.test(password) ||
+    Buffer.byteLength(password, 'utf8') > MAX_AUTH_VALUE_BYTES
+  ) {
+    throw invalidCredentials('password is invalid')
+  }
+
+  const hostname = new URL(instanceUrl).hostname
+  return {
+    accessToken: Buffer.from(`${username}:${password}`, 'utf8').toString('base64'),
+    expiresInSeconds: SYNTHETIC_TOKEN_TTL_SECONDS,
+    instanceUrl,
+    identity: {
+      displayName: `Oracle EPM ${hostname}`,
+      principal: null,
+      auditMetadata: { environmentUrl: instanceUrl },
+      storedMetadata: { environmentUrl: instanceUrl },
+    },
+  }
+}

apps/sim/lib/credentials/client-credential-accounts/server.test.ts

@@ -3,7 +3,10 @@
  */
 import { describe, expect, it } from 'vitest'
 import { CLIENT_CREDENTIAL_ACCOUNT_SECRET_TYPE } from '@/lib/credentials/client-credential-accounts/descriptors'
-import { parseClientCredentialAccountSecretBlob } from '@/lib/credentials/client-credential-accounts/server'
+import {
+  getClientCredentialAccountMinter,
+  parseClientCredentialAccountSecretBlob,
+} from '@/lib/credentials/client-credential-accounts/server'
 
 const MALFORMED = 'Stored client-credential service-account secret is malformed'
 
@@ -19,6 +22,10 @@ function blob(overrides: Record<string, unknown> = {}): string {
 }
 
 describe('parseClientCredentialAccountSecretBlob', () => {
+  it('registers the Oracle EPM minter in the generic client-credential pipeline', () => {
+    expect(getClientCredentialAccountMinter('oracle-epm-service-account')).toBeTypeOf('function')
+  })
+
   it('returns the parsed blob when it matches the expected provider', () => {
     const parsed = parseClientCredentialAccountSecretBlob(blob(), 'zoom-service-account')
     expect(parsed.clientId).toBe('cid')
@@ -117,4 +124,22 @@ describe('parseClientCredentialAccountSecretBlob', () => {
       )
     ).toThrow(MALFORMED)
   })
+
+  it('requires the complete Oracle EPM integration-user blob', () => {
+    const oracleBlob = blob({
+      providerId: 'oracle-epm-service-account',
+      orgId: 'https://epm.example.com/gateway',
+      clientId: 'integration.user@example.com',
+      clientSecret: 'password',
+    })
+    expect(
+      parseClientCredentialAccountSecretBlob(oracleBlob, 'oracle-epm-service-account')
+    ).toMatchObject({ orgId: 'https://epm.example.com/gateway' })
+    expect(() =>
+      parseClientCredentialAccountSecretBlob(
+        blob({ providerId: 'oracle-epm-service-account', clientSecret: '' }),
+        'oracle-epm-service-account'
+      )
+    ).toThrow(MALFORMED)
+  })
 })

apps/sim/lib/credentials/client-credential-accounts/server.ts

@@ -5,13 +5,15 @@ import {
   getClientCredentialAccountDescriptor,
   isClientCredentialAccountProviderId,
   NETSUITE_SERVICE_ACCOUNT_PROVIDER_ID,
+  ORACLE_EPM_SERVICE_ACCOUNT_PROVIDER_ID,
   partitionClientCredentialFields,
   SALESFORCE_SERVICE_ACCOUNT_PROVIDER_ID,
   ZOHO_DESK_SERVICE_ACCOUNT_PROVIDER_ID,
   ZOOM_SERVICE_ACCOUNT_PROVIDER_ID,
 } from '@/lib/credentials/client-credential-accounts/descriptors'
 import { mintBoxServiceAccountToken } from '@/lib/credentials/client-credential-accounts/minters/box'
 import { mintNetSuiteServiceAccountToken } from '@/lib/credentials/client-credential-accounts/minters/netsuite'
+import { mintOracleEpmServiceAccountToken } from '@/lib/credentials/client-credential-accounts/minters/oracle-epm'
 import { mintSalesforceServiceAccountToken } from '@/lib/credentials/client-credential-accounts/minters/salesforce'
 import { mintZohoDeskServiceAccountToken } from '@/lib/credentials/client-credential-accounts/minters/zoho-desk'
 import { mintZoomServiceAccountToken } from '@/lib/credentials/client-credential-accounts/minters/zoom'
@@ -29,8 +31,8 @@ export interface ClientCredentialAccountFields {
   clientSecret?: string
   /**
    * Provider-specific org identifier (Zoom Account ID, Box Enterprise ID,
-   * Salesforce My Domain host, Zoho Desk organization ID, or NetSuite
-   * SuiteTalk origin).
+   * Salesforce My Domain host, Zoho Desk organization ID, NetSuite SuiteTalk
+   * origin, or an Oracle EPM environment URL).
    */
   orgId: string
   /**
@@ -84,8 +86,8 @@ export interface ClientCredentialAccountMintResult {
   accessToken: string
   expiresInSeconds: number
   /**
-   * Provider API origin the minted token must be used against (Salesforce or
-   * NetSuite), forwarded to tools alongside the token.
+   * Provider API destination the minted token must be used against (Salesforce,
+   * NetSuite, or Oracle EPM), forwarded to tools alongside the token.
    */
   instanceUrl?: string
   /**
@@ -130,6 +132,7 @@ const CLIENT_CREDENTIAL_ACCOUNT_MINTERS: Record<
   [SALESFORCE_SERVICE_ACCOUNT_PROVIDER_ID]: mintSalesforceServiceAccountToken,
   [ZOHO_DESK_SERVICE_ACCOUNT_PROVIDER_ID]: mintZohoDeskServiceAccountToken,
   [NETSUITE_SERVICE_ACCOUNT_PROVIDER_ID]: mintNetSuiteServiceAccountToken,
+  [ORACLE_EPM_SERVICE_ACCOUNT_PROVIDER_ID]: mintOracleEpmServiceAccountToken,
 }
 
 export function getClientCredentialAccountMinter(

apps/sim/lib/credentials/orchestration/index.test.ts

@@ -414,6 +414,38 @@ describe('performUpdateCredential — service-account secret rotation', () => {
     )
   })
 
+  it('threads Oracle EPM integration-user fields through reconnect without reading old secrets', async () => {
+    mockCredential({
+      providerId: 'oracle-epm-service-account',
+      displayName: 'Production EPM',
+    })
+    mockIsClientCredentialAccountProviderId.mockReturnValue(true)
+    mockVerifyAndBuildServiceAccountSecret.mockResolvedValue({
+      providerId: 'oracle-epm-service-account',
+      encryptedServiceAccountKey: 'new-cipher',
+      displayName: 'Production EPM',
+      auditMetadata: {},
+    })
+
+    await performUpdateCredential({
+      credentialId: 'cred-1',
+      userId: 'user-1',
+      orgId: 'https://epm.example.com/gateway',
+      clientId: 'integration.user@example.com',
+      clientSecret: 'rotated-password',
+    })
+
+    expect(mockDecryptSecret).not.toHaveBeenCalled()
+    expect(mockVerifyAndBuildServiceAccountSecret).toHaveBeenCalledWith(
+      'oracle-epm-service-account',
+      expect.objectContaining({
+        orgId: 'https://epm.example.com/gateway',
+        clientId: 'integration.user@example.com',
+        clientSecret: 'rotated-password',
+      })
+    )
+  })
+
   it('surfaces a rebuild failure as a validation error and writes nothing', async () => {
     mockCredential()
     mockStoredBlob({ type: 'service_account', client_email: OLD_EMAIL })

apps/sim/lib/credentials/service-account-provider-ids.test.ts

@@ -16,6 +16,7 @@ describe('isServiceAccountProviderId', () => {
     expect(isServiceAccountProviderId('notion-service-account')).toBe(true)
     expect(isServiceAccountProviderId('salesforce-service-account')).toBe(true)
     expect(isServiceAccountProviderId('netsuite-service-account')).toBe(true)
+    expect(isServiceAccountProviderId('oracle-epm-service-account')).toBe(true)
   })
 
   it('is case- and whitespace-insensitive', () => {
@@ -52,6 +53,7 @@ describe('getServiceAccountConnectNoun', () => {
   it('names the client-credential secret', () => {
     expect(getServiceAccountConnectNoun('zoom-service-account')).toBe('server-to-server app')
     expect(getServiceAccountConnectNoun('netsuite-service-account')).toBe('OAuth certificate')
+    expect(getServiceAccountConnectNoun('oracle-epm-service-account')).toBe('integration user')
   })
 
   it('calls a custom Slack bot a custom bot', () => {