fix(oracle-epm-tax-reporting): guard upload directories and clarify status inputs

Author: Bill Leoutsakos

apps/docs/content/docs/integrations/oracle_epm_tax_reporting.mdx

@@ -364,7 +364,7 @@ Inspect a submitted planning or supplemental job using its correct route family.
 | Parameter | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
 | `oauthCredential` | string | Yes | Reusable Oracle EPM service-account credential |
-| `application` | string | No | Exact Tax Reporting application name; use application discovery or a tenant-specific reference. |
+| `application` | string | No | Exact Tax Reporting application name. Required for planning \(default\) and supplemental_collection jobs; omit only for supplemental_dimension. |
 | `jobId` | string | Yes | Submitted Oracle job instance ID, not a job definition name. |
 | `jobFamily` | string | No | planning \(default\), supplemental_collection \(fcmjobs\), or supplemental_dimension \(sdm/jobs\). Use the family that submitted the job. |
 | `waitForCompletion` | boolean | No | Wait at most 120 seconds, subject to the execution deadline. Default false. Timeout or local cancellation does not cancel the Oracle job; check its status before resubmitting. |
@@ -672,7 +672,7 @@ Inspect a report job using the documented standalone route or the distinct route
 | --------- | ---- | -------- | ----------- |
 | `oauthCredential` | string | Yes | Reusable Oracle EPM service-account credential |
 | `jobId` | string | Yes | Submitted Oracle job instance ID, not a job definition name. |
-| `module` | string | No | Report generation: FCM \(Task Manager\) or SDM. Report status: FCCS \(Task Manager\) or SDM. |
+| `module` | string | No | FCCS \(Task Manager\) or SDM. Required for standalone \(default\) and generated_report status routes; omit only for user_details. |
 | `reportStatusRoute` | string | No | standalone \(default\): documented /arm job endpoint; generated_report: route used by Generate Report Job Status links; user_details: route used by User Details Job Status links. They are not interchangeable. |
 | `waitForCompletion` | boolean | No | Wait at most 120 seconds, subject to the execution deadline. Default false. Timeout or local cancellation does not cancel the Oracle job; check its status before resubmitting. |
 | `downloadReport` | boolean | No | Store the completed report as a Sim file using its validated report-content link \(default false\). Requires a workflow execution context. |

apps/sim/lib/internal/oracle-epm-tax-reporting/client.test.ts

@@ -114,4 +114,15 @@ describe('Tax Reporting route contracts', () => {
     ).rejects.toThrow()
     expect(mocks.fetch).toHaveBeenCalledTimes(1)
   })
+
+  it('rejects upload directory traversal at the declared endpoint boundary', async () => {
+    await expect(
+      createTaxReportingClient(auth).request(taxEndpoints.upload_file, {
+        pathParams: { fileName: 'tax.csv' },
+        query: { extDirPath: 'inbox/../outbox' },
+        stream: Buffer.from('tax'),
+      })
+    ).rejects.toThrow()
+    expect(mocks.fetch).not.toHaveBeenCalled()
+  })
 })

apps/sim/lib/internal/oracle-epm-tax-reporting/client.ts

@@ -9,6 +9,7 @@ import type {
   OracleEpmPathPart,
   OracleEpmRouteSpace,
 } from '@/lib/internal/oracle-epm/types'
+import { TAX_UPLOAD_DIRECTORY_PATTERN } from '@/tools/oracle_epm_tax_reporting/utils'
 
 /** Product-owned limits; requests never retry a potentially accepted mutation. */
 export const TAX_JSON_BYTES = 2 * 1024 * 1024
@@ -125,7 +126,7 @@ export const taxEndpoints = {
     body: 'stream',
     maxRequestBytes: TAX_UPLOAD_BYTES,
     query: {
-      extDirPath: { kind: 'string', maxBytes: 255, pattern: /^(inbox|outbox)(\/[^/\\]+)*$/ },
+      extDirPath: { kind: 'string', maxBytes: 255, pattern: TAX_UPLOAD_DIRECTORY_PATTERN },
     },
   }),
   download_file: endpoint(files, repositoryFile, {

apps/sim/lib/internal/oracle-epm-tax-reporting/operations.test.ts

@@ -435,22 +435,50 @@ describe('Tax Reporting provider behavior', () => {
     }
   )
 
-  it('rejects an unsafe report status link before a second authenticated request', async () => {
-    mocks.fetch.mockResolvedValueOnce(
-      Response.json({
-        status: -1,
-        links: [
-          {
-            rel: 'Job Status',
-            href: 'https://other.example.com/HyperionPlanning/rest/fcmapi/v1/fcm/job/224',
-            action: 'GET',
-          },
-        ],
-      })
-    )
+  it.each([false, true])(
+    'rejects an unsafe report status link without another request when waiting is %s',
+    async (waitForCompletion) => {
+      mocks.fetch.mockResolvedValueOnce(
+        Response.json({
+          status: -1,
+          links: [
+            {
+              rel: 'Job Status',
+              href: 'https://other.example.com/HyperionPlanning/rest/fcmapi/v1/fcm/job/224',
+              action: 'GET',
+            },
+          ],
+        })
+      )
+      await expect(
+        execute('generate_user_details_report', { fileName: 'users.csv', waitForCompletion })
+      ).rejects.toThrow()
+      expect(mocks.fetch).toHaveBeenCalledTimes(1)
+    }
+  )
+
+  it('returns a trackable no-wait report snapshot without polling or resubmitting', async () => {
+    const report = {
+      status: -1,
+      details: 'In Process',
+      links: [
+        {
+          rel: 'Job Status',
+          href: auth.instanceUrl + '/HyperionPlanning/rest/fcmapi/v1/fcm/job/224',
+          action: 'GET',
+        },
+      ],
+    }
+    mocks.fetch.mockResolvedValueOnce(Response.json(report))
+    expect(await execute('generate_user_details_report', { fileName: 'users.csv' })).toEqual(report)
+    expect(mocks.fetch).toHaveBeenCalledTimes(1)
+  })
+
+  it('reports an untrackable pending submission without retrying even when not waiting', async () => {
+    mocks.fetch.mockResolvedValueOnce(Response.json({ status: -1 }))
     await expect(
-      execute('generate_user_details_report', { fileName: 'users.csv', waitForCompletion: true })
-    ).rejects.toThrow()
+      execute('generate_user_details_report', { fileName: 'users.csv' })
+    ).rejects.toThrow('do not resubmit automatically')
     expect(mocks.fetch).toHaveBeenCalledTimes(1)
   })
 
@@ -460,16 +488,31 @@ describe('Tax Reporting provider behavior', () => {
       'not found'
     )
     expect(mocks.fetch).not.toHaveBeenCalled()
-    await execute('upload_file', { file: sourceFile, fileName: 'tax.csv', directory: 'inbox' })
+    await execute('upload_file', {
+      file: sourceFile,
+      fileName: 'tax.csv',
+      directory: 'inbox/Tax data/v1.2',
+    })
     expect(mocks.open).toHaveBeenLastCalledWith(
       expect.objectContaining({ userId: 'trusted-user', maxBytes: 10 * 1024 * 1024 })
     )
     expect(mocks.fetch.mock.calls[0][2].body).toEqual(Buffer.from('tax'))
     expect(mocks.fetch.mock.calls[0][0]).toContain(
-      'applicationsnapshots/tax.csv/contents?extDirPath=inbox'
+      'applicationsnapshots/tax.csv/contents?extDirPath=inbox%2FTax+data%2Fv1.2'
     )
   })
 
+  it.each(['inbox/../outbox', 'outbox/.', 'inbox/nested/..', 'inbox/./nested'])(
+    'rejects upload directory %s before reading the source or submitting a mutation',
+    (directory) => {
+      expect(() =>
+        execute('upload_file', { file: sourceFile, fileName: 'tax.csv', directory })
+      ).toThrow()
+      expect(mocks.open).not.toHaveBeenCalled()
+      expect(mocks.fetch).not.toHaveBeenCalled()
+    }
+  )
+
   it('stores downloads as canonical files and rejects Oracle JSON error bodies', async () => {
     mocks.fetch.mockResolvedValueOnce(
       new Response('report', { headers: { 'content-type': 'text/csv' } })

apps/sim/lib/internal/oracle-epm-tax-reporting/operations.ts

@@ -191,7 +191,9 @@ function getReportLink(
 ) {
   const candidates = job.links?.filter((link) => link.rel === 'Job Status') ?? []
   if (candidates.length !== 1)
-    throw new TaxReportingContractError('Tax Reporting did not return exactly one Job Status link')
+    throw new TaxReportingContractError(
+      'Tax Reporting accepted a pending report without exactly one Job Status link; do not resubmit automatically'
+    )
   const link = candidates[0]
   return client.validateReturnedLink(policy, {
     rel: 'Job Status',

apps/sim/lib/internal/oracle-epm-tax-reporting/schema.ts

@@ -1,6 +1,9 @@
 import { z } from 'zod'
 import { userFileSchema } from '@/lib/api/contracts/primitives'
-import { assertTaxInputBudget } from '@/tools/oracle_epm_tax_reporting/utils'
+import {
+  assertTaxInputBudget,
+  TAX_UPLOAD_DIRECTORY_PATTERN,
+} from '@/tools/oracle_epm_tax_reporting/utils'
 
 const name = z.string().min(1).max(255)
 const text = z.string().max(16384)
@@ -181,7 +184,7 @@ const operationShapes = {
   upload_file: {
     file: userFileSchema,
     fileName: name,
-    directory: name.regex(/^(inbox|outbox)(\/[^/\\]+)*$/).optional(),
+    directory: name.regex(TAX_UPLOAD_DIRECTORY_PATTERN).optional(),
   },
   download_file: { fileName: name },
 } as const

apps/sim/tools/generated/tool-metadata.ts

@@ -20,7 +20,12 @@ export const oracleEpmTaxReportingGetJobStatusTool: InternalToolConfig<
   oauth: taxOAuth,
   params: {
     ...taxAuthParams,
-    application: { ...taxFields.application, required: false },
+    application: {
+      ...taxFields.application,
+      required: false,
+      description:
+        'Exact Tax Reporting application name. Required for planning (default) and supplemental_collection jobs; omit only for supplemental_dimension.',
+    },
     jobId: taxFields.jobId,
     jobFamily: taxFields.jobFamily,
     waitForCompletion: taxFields.waitForCompletion,

apps/sim/tools/oracle_epm_tax_reporting/get_job_status.ts

@@ -21,7 +21,12 @@ export const oracleEpmTaxReportingGetReportStatusTool: InternalToolConfig<
   params: {
     ...taxAuthParams,
     jobId: taxFields.jobId,
-    module: { ...taxFields.module, required: false },
+    module: {
+      ...taxFields.module,
+      required: false,
+      description:
+        'FCCS (Task Manager) or SDM. Required for standalone (default) and generated_report status routes; omit only for user_details.',
+    },
     reportStatusRoute: taxFields.reportStatusRoute,
     waitForCompletion: taxFields.waitForCompletion,
     downloadReport: taxFields.downloadReport,

apps/sim/tools/oracle_epm_tax_reporting/get_report_status.ts

@@ -1,5 +1,8 @@
 import type { OAuthConfig, ToolConfig } from '@/tools/types'
 
+/** Raw Oracle upload directories; never normalize caller-supplied dot segments. */
+export const TAX_UPLOAD_DIRECTORY_PATTERN = /^(inbox|outbox)(\/(?!\.{1,2}(?:\/|$))[^/\\]+)*$/
+
 export const taxOAuth = {
   required: true,
   provider: 'oracle_epm_tax_reporting',