feat(server): log sanitized details for upstream auth rejections [SAO-17523]

[josjeon]

Summary

Unexpected upstream 4xx authorization rejections currently log only the operation and HTTP status. This adds bounded, sanitized diagnostics showing whether target context was sent, the shape of its target fields, and the validation error kind and field path. The details appear in warning text and structured JSON, including when the host application owns logging.

Implements SAO-17523, a subtask of SAO-17418.

For example, an upstream uuid_parsing error at body.context.target_id is logged with that error kind and path, while the identifier is represented only as a string length. The client still receives 502 AUTH_UPSTREAM_REJECTED.

Scope

• Summarize target context by presence and field shape; omit target values and credentials.
• Retain only allowlisted validation kinds and field-path segments. Drop input, msg, and ctx; replace unknown kinds/segments with safe placeholders.
• Limit the summary to five errors and four path segments. Parse bodies up to 64 KiB; oversized or unusable bodies receive an explicit status and an unknown total.
• Emit indexed validation dictionaries so host-managed logging preserves the diagnostic fields. Agent Control JSON logs use proper JSON serialization and retain exception/stack information.
• Rebase onto current main, preserving string operation labels and identity resolution. Add regression coverage for identity lookup returning 400/422 and typed internal diagnostic summaries.

Risk and Rollout

Low risk: the added work occurs on unexpected upstream 4xx responses. Existing authorization decisions and API error mappings remain unchanged. No migration or configuration change is required; revert the PR to roll back.

The original incident's rejected caller payload and root cause remain unconfirmed. Multitenant staging validation of deployed logs remains a follow-up.

Testing

• make check passed on Python 3.12 with an isolated local PostgreSQL database: 2,560 tests passed and 1 optional test skipped; all Ruff and mypy checks passed.
• Regression coverage includes 989 server tests, emitted text/JSON logs, redaction, malformed/deeply nested/oversized validation bodies, bounded error lists, and identity lookup 400/422 responses.
• Independent security, logging, and reliability reviews found no actionable defects.
• All seven PR commits have verified SSH signatures with author email josjeon@cisco.com.
• GitHub checks passed: Python CI, UI CI, TypeScript SDK CI, server image build, and PR title validation.

Checklist

• Linked ticket and scoped acceptance criteria.
• Added automated coverage for sanitized diagnostics and rendered text/JSON output.
• Preserved current main identity and authorization behavior.
• Verify deployed multitenant staging logs for malformed and oversized upstream responses, including absence of caller values.

AI Tool Assistance Usage Statement

• AI assistance was used for implementation, tests, review, and this description; the changes were reviewed and validated.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!