diff --git a/ProcessMaker/Jobs/ErrorHandling.php b/ProcessMaker/Jobs/ErrorHandling.php index 31fd41f6e9..28f684e817 100644 --- a/ProcessMaker/Jobs/ErrorHandling.php +++ b/ProcessMaker/Jobs/ErrorHandling.php @@ -222,6 +222,24 @@ public static function convertResponseToException($result) $message = $rawMessage ?: 'Script execution failed with unknown error'; } + // Keep executor diagnostics before reducing the response to a UI exception. + // Do not log the response wholesale: metadata/output can contain request data or secrets. + Log::error('Script microservice execution failed', [ + 'message' => $message, + 'diagnostics' => self::scriptErrorDiagnostics(Arr::only($result, [ + 'error_message', 'error', 'exception', 'message', + ])), + 'output_diagnostics' => self::scriptErrorDiagnostics( + is_array($result['output'] ?? null) + ? Arr::only($result['output'], ['error_message', 'error', 'exception', 'code', 'file', 'line', 'trace']) + : [] + ), + 'correlation' => self::scriptErrorDiagnostics(Arr::only( + is_array($result['metadata'] ?? null) ? $result['metadata'] : [], + ['script_id', 'executor_uuid', 'executor_type', 'executor_version', 'instance_uuid', 'script_task'] + )), + ]); + throw new ScriptException($message); } } @@ -243,14 +261,77 @@ private static function extractScriptErrorMessage(array $result): string $result['message'] ?? null, ]; + $fallback = ''; foreach ($candidates as $candidate) { $message = self::extractMessageCandidate($candidate); if (!empty($message)) { - return $message; + // Microservice 1.2.1 returns the exit status in error_message and the + // actionable cause in error.error (1.0.0 used message/output.error). + // Contract fixtures cover both formats; do not gate this on an executor image tag. + if (!preg_match('/^Script execution failed(?: with exit code:\s*-?\d+| with unknown error)?[.!]?$/i', $message)) { + return $message; + } + $fallback = $fallback ?: $message; } } - return ''; + return $fallback; + } + + /** + * Retain bounded, sanitized executor diagnostics and identifiers, never stack arguments. + */ + private static function scriptErrorDiagnostics(mixed $value, int $depth = 0): mixed + { + if (is_string($value)) { + return mb_strcut(self::redactScriptErrorDetails($value), 0, 8000, 'UTF-8'); + } + if (!is_array($value) || $depth >= 4) { + return is_int($value) || is_float($value) || is_bool($value) ? $value : null; + } + + $allowed = ['error_message', 'message', 'detail', 'error', 'exception', 'code', 'file', 'line', + 'trace', 'class', 'function', 'type', 'script_id', 'executor_uuid', 'executor_type', + 'executor_version', 'instance_uuid', 'script_task', 'definition_id', 'instance_id', 'token_id']; + $diagnostics = []; + foreach (array_slice($value, 0, 30, true) as $key => $item) { + if ($key === 'trace') { + // Text traces may contain unlabeled arguments. Keep only structured frames. + $frames = self::scriptTraceDiagnostics($item, $depth + 1); + if ($frames !== []) { + $diagnostics[$key] = $frames; + } + continue; + } + if (is_int($key) || in_array($key, $allowed, true)) { + $diagnostics[$key] = self::scriptErrorDiagnostics($item, $depth + 1); + } + } + + return $diagnostics; + } + + private static function scriptTraceDiagnostics(mixed $trace, int $depth): array + { + if (!is_array($trace) || $depth >= 4) { + return []; + } + + $frames = []; + foreach (array_slice(array_is_list($trace) ? $trace : [$trace], 0, 30) as $frame) { + if (!is_array($frame)) { + continue; + } + $fields = array_filter( + Arr::only($frame, ['file', 'line', 'class', 'function', 'type']), + fn ($field) => is_string($field) || is_int($field) + ); + if ($fields !== []) { + $frames[] = self::scriptErrorDiagnostics($fields, $depth + 1); + } + } + + return $frames; } /** @@ -313,14 +394,25 @@ public static function sanitizeScriptErrorMessage(string $message): string */ public static function redactScriptErrorDetails(string $details): string { + $redacted = preg_replace( + [ + '/("(?:authorization|api[_-]?(?:token|key)|password)"\s*:\s*)"(?:\\\\.|[^"\\\\\r\n]++)*+"/i', + '/("(?:(?:access|refresh|callback)[_-]?token|client[_-]?secret)"\s*:\s*)"(?:\\\\.|[^"\\\\\r\n]++)*+"/i', + ], + '$1"[REDACTED]"', + $details + ) ?? '[REDACTED]'; $redacted = preg_replace( '/\bauthorization\b\s*[:=]\s*[^\r\n]*/i', 'Authorization=[REDACTED]', - $details - ) ?? $details; + $redacted + ) ?? $redacted; $redacted = preg_replace('/\bBearer\s+\S+/i', 'Bearer [REDACTED]', $redacted) ?? $redacted; $redacted = preg_replace( - '/\b(api[_-]?token|access[_-]?token|client[_-]?secret|password)\b\s*[:=]\s*[^\s,;]+/i', + [ + '/\b(api[_-]?(?:token|key)|password)\b\s*[:=]\s*[^\s,;]+/i', + '/\b((?:access|refresh|callback)[_-]?token|client[_-]?secret)\b\s*[:=]\s*[^\s,;]+/i', + ], '$1=[REDACTED]', $redacted ) ?? $redacted; diff --git a/tests/Fixtures/script-microservice/1.0.0/php-validation-error.json b/tests/Fixtures/script-microservice/1.0.0/php-validation-error.json new file mode 100644 index 0000000000..9ff6490f2b --- /dev/null +++ b/tests/Fixtures/script-microservice/1.0.0/php-validation-error.json @@ -0,0 +1,12 @@ +{ + "status": "error", + "metadata": {}, + "message": "Script execution failed with exit code: 1", + "output": { + "error": "variableName is required", + "code": 0, + "file": "/opt/executor/script.php", + "line": 88, + "trace": "#0 /opt/executor/bootstrap.php: validateConfig()" + } +} diff --git a/tests/Fixtures/script-microservice/1.2.1/php-validation-error.json b/tests/Fixtures/script-microservice/1.2.1/php-validation-error.json new file mode 100644 index 0000000000..9a4ff34582 --- /dev/null +++ b/tests/Fixtures/script-microservice/1.2.1/php-validation-error.json @@ -0,0 +1,18 @@ +{ + "status": "error", + "metadata": { + "script_id": 42, + "executor_uuid": "00000000-0000-4000-8000-000000000001", + "executor_version": "v2026.12.2", + "instance_uuid": "00000000-0000-4000-8000-000000000002" + }, + "output": {}, + "error_message": "Script execution failed with exit code: 1", + "error": { + "error": "variableName is required", + "code": 0, + "file": "/opt/executor/script.php", + "line": 88, + "trace": "#0 /opt/executor/bootstrap.php: validateConfig()" + } +} diff --git a/tests/Fixtures/script-microservice/README.md b/tests/Fixtures/script-microservice/README.md new file mode 100644 index 0000000000..a18f833a82 --- /dev/null +++ b/tests/Fixtures/script-microservice/README.md @@ -0,0 +1,24 @@ +# Script microservice error contracts + +These sanitized fixtures preserve the response structures observed during FOUR-34463 +validation. Identifiers and executor diagnostics are illustrative; no credentials or +request documents are included. + +- API 1.0.0: the generic execution message is in `message`, with diagnostics in `output`. +- API 1.2.1 (`script-executor-service:1.2.1-develop`): the generic execution message is + in `error_message`, with diagnostics in `error`. The actionable cause is `error.error`. + +`ScriptMicroserviceErrorContractTest` verifies that both formats expose the actionable +cause while preserving sanitized diagnostics in application logs. An actionable top-level +message retains precedence. An exit-status message is a fallback when no cause is available. +Exit codes 1 and 255 follow the same policy. API versions and executor image versions are +separate; response interpretation must not depend on an executor image tag. + +Text traces are deliberately omitted from diagnostic logs because positional arguments +can contain document content or unlabeled secrets. Only structured frames with scalar +`file`, `line`, `class`, `function`, and `type` fields are retained; arguments, objects, +text entries, and unknown trace formats are excluded. The fixtures retain text traces +to verify this omission for both response contracts. + +Future microservice upgrades should validate these contracts and add fixtures for changed +responses. A valid error JSON response alone does not ensure compatible message selection. diff --git a/tests/unit/ScriptMicroserviceErrorContractTest.php b/tests/unit/ScriptMicroserviceErrorContractTest.php new file mode 100644 index 0000000000..b2681a67fb --- /dev/null +++ b/tests/unit/ScriptMicroserviceErrorContractTest.php @@ -0,0 +1,337 @@ +previousLogger = Log::getFacadeRoot(); + $this->logger = new class extends AbstractLogger { + public array $records = []; + + public function log($level, string|\Stringable $message, array $context = []): void + { + $this->records[] = compact('level', 'message', 'context'); + } + }; + Log::swap($this->logger); + } + + protected function tearDown(): void + { + if ($this->previousLogger !== null) { + Log::swap($this->previousLogger); + } else { + Log::clearResolvedInstance('log'); + } + parent::tearDown(); + } + + public static function errorContracts(): array + { + return [ + 'API 1.0.0 standard PHP' => ['1.0.0', 1], + 'API 1.2.1 standard PHP' => ['1.2.1', 1], + 'API 1.2.1 custom PHP exit status' => ['1.2.1', 255], + ]; + } + + #[DataProvider('errorContracts')] + public function testVersionedContractsExposeTheCauseAndKeepDiagnostics(string $version, int $exitCode): void + { + $response = $this->fixture($version); + $field = $version === '1.2.1' ? 'error_message' : 'message'; + $response[$field] = 'Script execution failed with exit code: ' . $exitCode; + + $this->assertSame('variableName is required', $this->exceptionFor($response)->getMessage()); + $this->assertCount(1, $this->logger->records); + $log = $this->logger->records[0]; + $diagnostics = $version === '1.2.1' + ? $log['context']['diagnostics']['error'] + : $log['context']['output_diagnostics']; + $this->assertSame('/opt/executor/script.php', $diagnostics['file']); + $this->assertSame(88, $diagnostics['line']); + $this->assertArrayNotHasKey('trace', $diagnostics); + if ($version === '1.2.1') { + $this->assertSame(42, $log['context']['correlation']['script_id']); + $this->assertSame('v2026.12.2', $log['context']['correlation']['executor_version']); + } + $this->assertSame('error', $log['level']); + $this->assertSame('Script microservice execution failed', $log['message']); + } + + public function testActionableTopLevelMessageKeepsPrecedence(): void + { + $response = $this->fixture('1.2.1'); + $response['error_message'] = 'Document conversion failed'; + $this->assertSame('Document conversion failed', $this->exceptionFor($response)->getMessage()); + } + + public function testGenericMessageIsKeptWhenOnlyDiagnosticsAreAvailable(): void + { + $response = $this->fixture('1.2.1'); + unset($response['error']['error']); + $this->assertSame($response['error_message'], $this->exceptionFor($response)->getMessage()); + } + + public function testDiagnosticsAndCorrelationAreSanitizedWithoutLoggingRequestData(): void + { + $response = $this->fixture('1.2.1'); + $response['error']['error'] = "PHP Fatal error: Uncaught Exception: variableName is required in /opt/executor/script.php:88\nStack trace:"; + $response['error']['trace'] = [ + ['file' => '/opt/executor/bootstrap.php', 'line' => 20, 'function' => 'validateConfig', + 'args' => [['password' => 'private-argument']], 'object' => ['private' => 'payload']], + ['file' => '/opt/executor/script.php', 'line' => 88, + 'function' => "Authorization: Basic private-auth\nBearer private-bearer\npassword=private-password"], + ]; + $response['metadata']['user_email'] = 'private@example.invalid'; + $response['metadata']['secrets'] = ['api_token' => 'private-token']; + $response['metadata']['script_task'] = ['instance_id' => 123, 'token_id' => 456, 'data' => 'private-data']; + $response['output']['document'] = 'private-document'; + + $message = $this->exceptionFor($response)->getMessage(); + $this->assertSame('variableName is required', $message); + $context = $this->logger->records[0]['context']; + $this->assertSame(123, $context['correlation']['script_task']['instance_id']); + $this->assertSame(456, $context['correlation']['script_task']['token_id']); + $this->assertSame('/opt/executor/bootstrap.php', $context['diagnostics']['error']['trace'][0]['file']); + $this->assertSame('validateConfig', $context['diagnostics']['error']['trace'][0]['function']); + $encoded = json_encode($context, JSON_THROW_ON_ERROR); + $this->assertStringContainsString('[REDACTED]', $encoded); + $this->assertStringNotContainsString('private-', $encoded); + $this->assertStringNotContainsString('private@', $encoded); + $this->assertStringNotContainsString('args', $encoded); + $this->assertStringNotContainsString('object', $encoded); + } + + public function testSuccessfulResponseDoesNotProduceAnErrorLog(): void + { + ErrorHandling::convertResponseToException(['status' => 'success', 'output' => ['value' => 1]]); + $this->assertSame([], $this->logger->records); + } + + public function testLegacyTimeoutRemainsATimeout(): void + { + $this->expectException(ScriptTimeoutException::class); + ErrorHandling::convertResponseToException(['status' => 'error', 'message' => 'Command exceeded timeout of 30 seconds']); + } + + public function testDiagnosticStringsAreBounded(): void + { + $response = $this->fixture('1.2.1'); + $response['error']['detail'] = str_repeat('x', 20000); + $this->exceptionFor($response); + $this->assertSame(8000, strlen($this->logger->records[0]['context']['diagnostics']['error']['detail'])); + } + + public function testJsonCredentialsInDiagnosticDetailsAreRedacted(): void + { + $response = $this->fixture('1.2.1'); + $response['error']['detail'] = '{"client_secret":"private-secret", "callback_token":"private-callback"}'; + $this->exceptionFor($response); + $detail = $this->logger->records[0]['context']['diagnostics']['error']['detail']; + $this->assertSame('{"client_secret":"[REDACTED]", "callback_token":"[REDACTED]"}', $detail); + } + + public static function pcreJitModes(): array + { + return ['JIT enabled' => ['1'], 'JIT disabled' => ['0']]; + } + + #[DataProvider('pcreJitModes')] + #[RunInSeparateProcess] + #[PreserveGlobalState(false)] + public function testCredentialsAreRedactedBeforeTruncatingDiagnostics(string $jit): void + { + $previousJit = ini_get('pcre.jit'); + ini_set('pcre.jit', $jit); + try { + $response = $this->fixture('1.2.1'); + $response['error']['detail'] = json_encode(['Authorization' => 'Basic private-auth', 'password' => str_repeat('private-password', 1000)]); + $this->exceptionFor($response); + $detail = $this->logger->records[0]['context']['diagnostics']['error']['detail']; + $this->assertSame('{"Authorization":"[REDACTED]","password":"[REDACTED]"}', $detail); + } finally { + ini_set('pcre.jit', $previousJit); + } + } + + public function testRegexFailureNeverReturnsUnredactedDetails(): void + { + $previousLimit = ini_get('pcre.backtrack_limit'); + ini_set('pcre.backtrack_limit', '1'); + try { + $details = '{"password":"private-password"}'; + $this->assertSame('[REDACTED]', ErrorHandling::redactScriptErrorDetails($details)); + } finally { + ini_set('pcre.backtrack_limit', $previousLimit); + } + } + + public static function unsafeTextTraces(): array + { + $trace = "#0 /opt/executor/script.php(88): validateConfig('private-document-content', 'unlabeled-secret')"; + + return [ + 'text trace' => [$trace], + 'text frames in array' => [[$trace, '#1 {main}']], + 'unknown trace format' => [['unexpected' => $trace]], + 'mixed frames' => [[$trace, ['file' => '/opt/executor/bootstrap.php', 'line' => 20, + 'function' => 'validateConfig', 'args' => ['private-document-content', 'unlabeled-secret']]]], + ]; + } + + #[DataProvider('unsafeTextTraces')] + public function testTextTraceArgumentsNeverReachDiagnosticLogs(mixed $trace): void + { + $response = $this->fixture('1.2.1'); + $response['error']['trace'] = $trace; + $response['output']['trace'] = $trace; + $this->assertSame('variableName is required', $this->exceptionFor($response)->getMessage()); + + $context = $this->logger->records[0]['context']; + $encoded = json_encode($context, JSON_THROW_ON_ERROR); + $this->assertStringNotContainsString('private-document-content', $encoded); + $this->assertStringNotContainsString('unlabeled-secret', $encoded); + if (is_array($trace) && array_is_list($trace) && is_array(end($trace))) { + $expected = [['file' => '/opt/executor/bootstrap.php', 'line' => 20, 'function' => 'validateConfig']]; + $this->assertSame($expected, $context['diagnostics']['error']['trace']); + $this->assertSame($expected, $context['output_diagnostics']['trace']); + } else { + $this->assertArrayNotHasKey('trace', $context['diagnostics']['error']); + $this->assertArrayNotHasKey('trace', $context['output_diagnostics']); + } + } + + public function testSingleStructuredTraceFrameKeepsOnlyScalarFrameFields(): void + { + $response = $this->fixture('1.2.1'); + $response['error']['trace'] = ['file' => '/opt/executor/script.php', 'line' => 88, + 'class' => 'Validator', 'function' => 'validateConfig', 'type' => '::', + 'args' => ['private-document-content'], 'object' => ['secret' => 'private-object'], + 'unknown' => 'private-extra']; + $this->exceptionFor($response); + $this->assertSame([['file' => '/opt/executor/script.php', 'line' => 88, + 'class' => 'Validator', 'function' => 'validateConfig', 'type' => '::']], + $this->logger->records[0]['context']['diagnostics']['error']['trace']); + } + + public static function escapedCredentialValues(): array + { + return [ + 'escaped quote' => ['prefix"SECRET_SUFFIX'], + 'escaped backslash' => ['prefix\\SECRET_SUFFIX'], + 'backslash followed by quote' => ['prefix\\"SECRET_SUFFIX'], + 'trailing backslash' => ['SECRET_SUFFIX\\'], + ]; + } + + #[DataProvider('escapedCredentialValues')] + public function testEscapedJsonCredentialsAreCompletelyRedacted(string $secret): void + { + $details = json_encode(['password' => $secret, 'client_secret' => $secret, + 'Authorization' => $secret, 'detail' => 'Useful diagnostic'], JSON_THROW_ON_ERROR); + $expected = ['password' => '[REDACTED]', 'client_secret' => '[REDACTED]', + 'Authorization' => '[REDACTED]', 'detail' => 'Useful diagnostic']; + + $this->assertSame($expected, json_decode(ErrorHandling::redactScriptErrorDetails($details), true, 512, JSON_THROW_ON_ERROR)); + $response = $this->fixture('1.2.1'); + $response['error']['detail'] = $details; + $this->exceptionFor($response); + $logged = $this->logger->records[0]['context']['diagnostics']['error']['detail']; + $this->assertSame($expected, json_decode($logged, true, 512, JSON_THROW_ON_ERROR)); + $this->assertStringNotContainsString('SECRET_SUFFIX', $logged); + } + + public function testExistingPlainTextCredentialRedactionRemainsCompatible(): void + { + $details = "Authorization: Basic private-auth\nBearer private-bearer\npassword=private-password"; + $this->assertSame("Authorization=[REDACTED]\nBearer [REDACTED]\npassword=[REDACTED]", + ErrorHandling::redactScriptErrorDetails($details)); + } + + public static function credentialNames(): array + { + $names = ['Authorization', 'PASSWORD']; + foreach (['apiToken', 'apiKey', 'accessToken', 'refreshToken', 'callbackToken', 'clientSecret'] as $name) { + $names[] = $name; + $names[] = strtolower(preg_replace('/([a-z])([A-Z])/', '$1_$2', $name)); + $names[] = strtoupper(preg_replace('/([a-z])([A-Z])/', '$1-$2', $name)); + } + + return array_combine($names, array_map(fn ($name) => [$name], $names)); + } + + #[DataProvider('credentialNames')] + public function testCredentialFamiliesRemainRedacted(string $name): void + { + $json = json_encode([$name => 'private-secret', 'detail' => 'Useful diagnostic'], JSON_THROW_ON_ERROR); + $this->assertSame([$name => '[REDACTED]', 'detail' => 'Useful diagnostic'], + json_decode(ErrorHandling::redactScriptErrorDetails($json), true, 512, JSON_THROW_ON_ERROR)); + $this->assertSame($name . '=[REDACTED]', ErrorHandling::redactScriptErrorDetails($name . '=private-secret')); + } + + public function testDiagnosticScalarsAndDepthLimitRemainUnchanged(): void + { + $response = $this->fixture('1.2.1'); + $response['error']['detail'] = ['detail' => [ + 'code' => 0, 'line' => 1.5, 'message' => false, 'exception' => null, + 'file' => new \stdClass(), 'function' => 'validateConfig', + 'error' => ['detail' => 'Beyond the depth limit'], + ]]; + $this->exceptionFor($response); + + $this->assertSame(['detail' => [ + 'code' => 0, 'line' => 1.5, 'message' => false, 'exception' => null, + 'file' => null, 'function' => 'validateConfig', 'error' => null, + ]], $this->logger->records[0]['context']['diagnostics']['error']['detail']); + } + + public static function fallbackResponses(): array + { + return [ + 'plain legacy message' => [['status' => 'error', 'message' => 'Plain failure'], 'Plain failure'], + 'missing diagnostics' => [['status' => 'error'], 'Script execution failed with unknown error'], + 'generic message only' => [['status' => 'error', 'error_message' => 'Script execution failed with exit code: 255'], 'Script execution failed with exit code: 255'], + 'structured detail' => [['status' => 'error', 'error' => ['detail' => 'Invalid document']], 'Invalid document'], + 'legacy stderr' => [['status' => 'error', 'output' => ['stderr' => "Invalid document\nStack trace:"]], 'Invalid document'], + ]; + } + + #[DataProvider('fallbackResponses')] + public function testFallbackCompatibility(array $response, string $message): void + { + $this->assertSame($message, $this->exceptionFor($response)->getMessage()); + } + + private function fixture(string $version): array + { + return json_decode(file_get_contents(__DIR__ . '/../Fixtures/script-microservice/' . $version . '/php-validation-error.json'), true, 512, JSON_THROW_ON_ERROR); + } + + private function exceptionFor(array $response): ScriptException + { + try { + ErrorHandling::convertResponseToException($response); + } catch (ScriptException $exception) { + return $exception; + } + $this->fail('An error response must throw ScriptException'); + } +}