Add whoami and can-i data-plane access diagnostics

[mkrueger]

Summary

Adds two RBAC / access diagnostic commands (issue #163, "G5. RBAC / access diagnostics") that rely solely on data-plane operations — no control-plane / Azure.ResourceManager (ARM) dependency, so they survive the planned ARM removal.

Fixes #163

whoami

Reports the current credential type and, for Microsoft Entra ID connections, the principal id, tenant id, application id, user principal name, display name, identity type, and token expiry decoded from the Cosmos DB access token.

• The token signature is not validated; claims are used for local display only.
• Account-key and emulator connections use a master key and have no Entra identity, so only the credential type is reported.
• Data-plane RBAC role assignments are a control-plane concept and are intentionally not enumerated.

can-i <read|query|write|manage>

Probes whether the current identity can perform an action against a container without mutating data, reporting allow, deny, or indeterminate:

• read — point read of a random id
• query — a COUNT query
• write — delete of a random, almost-certainly-nonexistent id (non-mutating; allow is a heuristic inference of write access from delete permission)
• manage — cannot be probed on the data plane, always reported indeterminate

Account-key and emulator connections use a master key and report allow with method key. Entra connections use method probe and include the observed HTTP status code. Probes use the Cosmos stream APIs so 401/403/404 responses are handled via status codes rather than exceptions.

--format support

Both commands accept --format / -f (table default, json, csv), following the ls command pattern (also honors the COSMOSDB_SHELL_FORMAT environment variable). The rich table renders interactively; json/csv (and redirected output) defer to PrintState.

Implementation notes

• ShellInterpreter now tracks the active TokenCredential and a credential-type label, committed atomically inside Connect() (the single success choke point) to avoid stale credentials after a failed account switch.
• New JwtClaims helper decodes a JWT payload (base64url) without signature validation for local introspection.
• Both commands are auto-discovered via reflection and exposed over MCP via McpAnnotation.

Scope vs. #163 (partial)

This addresses #163 but does not fully satisfy its acceptance criteria, by design — the role/scope enumeration parts depend on the control-plane (ARM), which is planned for removal. Shipped vs. deferred:

• ✅ whoami reports identity (credential type, principal, tenant, app id, UPN, display name, token expiry)
• ✅ can-i returns non-destructive allow/deny for read/query/write
• ✅ Degrades gracefully for key/emulator; structured output; docs + tests
• ❌ Deferred/blocked on the ARM decision: whoami resolvable role assignments, can-i governing role assignment, and a determinate manage result

Tests & docs

• Focused offline unit tests for whoami, can-i, and JwtClaims (not-connected, key-auth, invalid action/format, manage, json/csv output). Full offline suite green (1791 tests).
• Localization strings added to lang/en.ftl (passes LocalizationKeyAuditTests / HelpCommandVerificationTests).
• Updated docs/commands.md (new Diagnostics section), README.md, and CHANGELOG.md.

Addresses #163 (see scope note above — intentionally not auto-closing).

Note: stacked on dev/mkrueger/mcp-structured-content (PR #168) to keep the diff focused; GitHub will retarget the base to main once #168 merges.

[github-code-quality]

Code Coverage Overview

Languages: C#

C# / code-coverage/dotnet

The overall coverage in the dev/mkrueger/rbac-di... branch remains at 61%, unchanged from the main branch.

Show a code coverage summary of the most impacted files.

File	main b334f69	dev/mkrueger/rbac-di... 94a0bc8	+/-
D:\a\CosmosDBSh...lInterpreter.cs	52%	52%	0%
D:\a\CosmosDBSh...ponseFactory.cs	89%	90%	+1%
D:\a\CosmosDBSh...CommandState.cs	80%	86%	+6%
D:\a\CosmosDBSh...hoamiCommand.cs	0%	29%	+29%
D:\a\CosmosDBSh...\CanICommand.cs	0%	38%	+38%
D:\a\CosmosDBSh...il\JwtClaims.cs	0%	89%	+89%

---

_{Updated July 13, 2026 13:11 UTC
Code Coverage is in Public Preview. Learn more and provide us with your feedback.}

[Copilot]

Pull request overview

This PR adds two new diagnostics commands to the Cosmos DB Shell—whoami (identity introspection) and can-i (data-plane access probing)—designed to rely only on data-plane operations (no ARM dependency) and to support table/json/csv output patterns used elsewhere in the CLI.

Changes:

• Add whoami to report credential type and (for Entra-based auth) identity details decoded from the Cosmos access token.
• Add can-i <read|query|write|manage> to probe container-scoped data-plane permissions and return allow/deny/indeterminate.
• Extend MCP tool responses to emit first-class structuredContent while keeping a byte-equivalent JSON text block; update docs/localization/tests accordingly.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
README.md	Mentions the new whoami / can-i diagnostics and --format support.
docs/mcp.md	Documents dual text + structuredContent payload for MCP tool results.
docs/commands.md	Adds a new Diagnostics section describing whoami / can-i usage and semantics.
CosmosDBShell/lang/en.ftl	Adds localized strings for both new commands and their output fields/errors.
CosmosDBShell/Azure.Data.Cosmos.Shell.Util/JwtClaims.cs	Adds a helper to decode JWT payload claims without signature validation (display-only).
CosmosDBShell/Azure.Data.Cosmos.Shell.Mcp/McpResponseFactory.cs	Emits MCP structured content and reuses its raw JSON for the text block to keep them equivalent.
CosmosDBShell/Azure.Data.Cosmos.Shell.Core/ShellInterpreter.cs	Tracks active TokenCredential + credential type label at the successful connection choke point.
CosmosDBShell/Azure.Data.Cosmos.Shell.Commands/WhoamiCommand.cs	Implements whoami command execution, formatting, and interactive table rendering.
CosmosDBShell/Azure.Data.Cosmos.Shell.Commands/CanICommand.cs	Implements can-i action probing via stream APIs and maps status codes to decisions.
CosmosDBShell.Tests/UtilTest/JwtClaimsTests.cs	Adds unit tests for JWT payload decoding and claim selection behavior.
CosmosDBShell.Tests/McpResponseFactoryTests.cs	Adds tests ensuring structured content matches the JSON text block exactly.
CosmosDBShell.Tests/CommandTests/WhoamiCommandTests.cs	Adds offline tests for disconnected/key-auth branches and format validation/output.
CosmosDBShell.Tests/CommandTests/CanICommandTests.cs	Adds offline tests for validation, manage semantics, key-auth branch, and format validation/output.
CHANGELOG.md	Adds entries for the new diagnostics commands and MCP structured tool results.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated no new comments.