fix: sanitize internal exception messages in client-visible errors

[ez-lbz]

What changed

1. Sanitize internal exception messages before they reach clients (CWE-209)

Problem: Raw Error messages — which can contain stack traces, file paths, and library names — were propagated verbatim to client-visible error responses in four places: the REST error body, the JSON-RPC error envelope, the gRPC error details, and the FAILED task message synthesized when an agent executor throws. This leaks server internals (fingerprinting / information disclosure). All SDKs shared the gap.

Fix (src/errors/base.ts):

• Added clientSafeErrorMessage(error): semantic A2AError messages are deliberate protocol text and are kept; unknown/internal errors are replaced with 'An unexpected error occurred.', with the internal detail logged server-side via console.error so diagnostics are not lost.

Fix (src/errors/index.ts):

• Re-exports clientSafeErrorMessage for consumers.

Fix (src/errors/rest.ts):

• toRestErrorBody uses clientSafeErrorMessage (semantic messages and error-code semantics preserved).

Fix (src/errors/json_rpc.ts):

• toJsonRpcError uses clientSafeErrorMessage for non-A2A errors, keeping the INTERNAL_ERROR (-32603) code.

Fix (src/server/grpc/grpc_service.ts):

• mapToError uses clientSafeErrorMessage for non-A2A errors, keeping UNKNOWN status.

Fix (src/server/request_handler/default_request_handler.ts):

• The FAILED task message synthesized by _runExecutor, _runStreamExecutor, and _handleProcessingError now uses Agent execution failed. / Event processing loop failed. for raw errors (the detail is already logged right above each site); semantic A2AError messages keep the Agent execution error: <msg> / Event processing loop failed: <msg> form.

Testing

• npm test — 68 test files, 1511 tests passed.
• npx tsc --noEmit (no errors in src/) and npx tsc --noEmit -p tsconfig.test.json pass.
• New regression tests: toRestErrorBody/toJsonRpcError replace raw Error messages with the generic string while preserving codes, and keep semantic A2AError messages; gRPC mapToError returns generic details for raw errors.
• Tests updated for the behavior change (raw error messages no longer appear in client-visible output): default_request_handler.spec.ts (blocking/non-blocking executor failures, event-loop failure), streaming_errors.spec.ts (×2), auth_required.spec.ts, error_envelope.spec.ts, and express_app.spec.ts (JSON-RPC fallback error handling) now assert the sanitized generic message.

Behavior change: internal exception messages are no longer sent to clients on any transport or in synthesized FAILED task messages; semantic A2A error messages and codes are unchanged.

[github-actions]

🧪 Code Coverage

⬇️ Download Full Report

	Base	PR	Delta
src/errors/base.ts	98.02%	98.12%	🟢 +0.10%
src/server/request_handler/default_request_handler.ts	87.99%	87.86%	🔴 -0.13%
Total	91.21%	91.2%	🔴 -0.01%

Generated by coverage-comment.yml

[JakubWorek]

Hi @ez-lbz, looks like this PR contains commit not related to the description, taken from #625. Could you please update the branch to contain only relevant changes?

[ez-lbz]

Hi @JakubWorek, thanks for the review note. I've updated the branch:

• Removed the three commits belonging to fix: validate push notification URLs and REST listTasks params #625 (push notification URL validation, REST listTasks param validation, ITK loopback webhooks) — the branch now contains only this PR's own changes.
• Rebased onto the latest main and resolved the merge conflicts.

All CI checks (test, test-edge, coverage, eslint, integration, ITK, tck-test, approvals, Validate PR Title) are green on the new head.

Thanks again!