fix(security): sanitize REST path parameters to prevent injection attacks

[Linux2010]

Summary

Fixes #805 — REST task/request ID sanitization.

REST transport path parameters (task_id, push_id) were directly interpolated into URL paths without validation. Starlette accepts null bytes (\x00), newlines (\n), and other control characters in path parameters, which could lead to injection attacks.

Changes

New: src/a2a/utils/sanitizers.py

• sanitize_path_id(value, param_name) — validates path parameter values against a safe character set [A-Za-z0-9._-], rejecting:
  • Empty strings
  • Null bytes and control characters (0x00-0x1F, 0x7F)
  • Bare . and .. (path traversal risk)
  • Path traversal sequences (../../)
  • Spaces, slashes, and other unsafe characters

Modified: src/a2a/server/routes/rest_dispatcher.py

• All request.path_params["id"] and request.path_params["push_id"] usages now go through sanitize_path_id() before being passed to request handlers

Modified: src/a2a/client/transports/rest.py

• All request.id and request.task_id URL interpolations now go through sanitize_path_id() before constructing URL paths

New: tests/utils/test_sanitizers.py

• 22 unit tests covering valid IDs, control characters, dot/double-dot rejection, path traversal, unicode, etc.

Modified: tests/server/routes/test_rest_dispatcher.py

• 8 integration tests verifying malicious path parameters are rejected with HTTP 400

Test Results

• All tests pass across Python 3.10–3.14
• Coverage: 93% (above 88% threshold), new module at 100%
• Lint: clean (ruff + ty)

Security Impact

• Before: GET /tasks/abc%00def → accepted, null byte passed to task store
• After: GET /tasks/abc%00def → HTTP 400, InvalidRequestError: id contains control characters
• Before: GET /tasks/.. → accepted, potential path traversal
• After: GET /tasks/.. → HTTP 400, InvalidRequestError: id cannot be "." or ".."

Review Notes

• Gemini Code Assist flagged that . and .. were allowed by the regex — this was addressed in commit 8afe7f3 (reject bare dot/double-dot) and 2b86f44 (add corresponding tests)

[gemini-code-assist]

Code Review

This pull request introduces path parameter sanitization via a new sanitize_path_id utility to prevent injection of control characters and path traversal sequences across REST client and server dispatcher layers. The review feedback correctly identifies a security vulnerability where single dot (.) and double dot (..) are permitted by the sanitization regex, which could lead to path traversal or routing bypass when interpolated into URL paths. It is recommended to explicitly reject these values and add corresponding unit tests.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

The current sanitization logic allows single dot (.) and double dot (..) as valid path IDs because they match the _PATH_ID_PATTERN regex (^[A-Za-z0-9._-]+$). While forward slashes are rejected, allowing . and .. can still lead to path traversal or routing bypass/normalization issues when interpolated into URL paths (e.g., /tasks/.. or /tasks/../pushNotificationConfigs).

We should explicitly reject . and .. to prevent these security risks.

Suggested change

	if not value:
	raise InvalidRequestError(
	message=f'{param_name} must not be empty',
	)
	if not value:
	raise InvalidRequestError(
	message=f'{param_name} must not be empty',
	)
	if value in ('.', '..'):
	raise InvalidRequestError(
	message=f'{param_name} cannot be "." or ".."',
	)

References

1. For unsupported input values, fail explicitly by raising an error instead of silently falling back to a default value.

[Linux2010]

Good catch! This has been addressed in commit 8afe7f3 ("fix(security): reject '.' and '..' as path IDs to prevent path traversal"), which adds an explicit check for bare . and .. before the regex match. These values now raise InvalidRequestError: id cannot be "." or "..".

[gemini-code-assist]

Add unit tests to verify that single dot (.) and double dot (..) are correctly rejected by sanitize_path_id to prevent path traversal risks.

Suggested change

	def test_path_traversal_rejected(self) -> None:
	"""Path traversal sequence raises InvalidRequestError."""
	with pytest.raises(InvalidRequestError, match='invalid characters'):
	sanitize_path_id('../../etc/passwd')
	def test_path_traversal_rejected(self) -> None:
	"""Path traversal sequence raises InvalidRequestError."""
	with pytest.raises(InvalidRequestError, match='invalid characters'):
	sanitize_path_id('../../etc/passwd')
	def test_dot_and_double_dot_rejected(self) -> None:
	"""Single dot and double dot are rejected as path traversal risks."""
	with pytest.raises(InvalidRequestError, match='cannot be "\\." or "\\.\\."'):
	sanitize_path_id('.')
	with pytest.raises(InvalidRequestError, match='cannot be "\\." or "\\.\\."'):
	sanitize_path_id('..')

[Linux2010]

Done! Added in commit 2b86f44 ("test: add dot/double-dot rejection tests for sanitize_path_id"). The test suite now includes test_dot_rejected, test_double_dot_rejected, and test_dot_and_double_dot_rejected covering this case.

[github-actions]

🧪 Code Coverage (vs main)

⬇️ Download Full Report

	Base	PR	Delta
src/a2a/utils/sanitizers.py (new)	—	100.00%	—
Total	92.97%	92.99%	🟢 +0.02%

Generated by coverage-comment.yml