Add whoami and can-i data-plane access diagnostics

[Mike Krüger (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.

Sample:

[github-code-quality]

Code Coverage Overview

Languages: C#

C# / code-coverage/dotnet

The overall line coverage in commit adda968 in the dev/mkrueger/rbac-di... branch is 61%. The line coverage in commit c2aac52 in the main branch is 62%.

Show a line coverage summary of the most impacted files.

File	main c2aac52	dev/mkrueger/rbac-di... adda968	+/-
D:\a\CosmosDBSh...lInterpreter.cs	63%	63%	0%
D:\a\CosmosDBSh...CommandState.cs	89%	91%	+2%
D:\a\CosmosDBSh...hoamiCommand.cs	0%	24%	+24%
D:\a\CosmosDBSh...\CanICommand.cs	0%	35%	+35%
D:\a\CosmosDBSh...il\JwtClaims.cs	0%	89%	+89%

---

_{Updated August 28, 2026 13:38 UTC}

[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.

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

Suppressed comments (3)

Previously missed (2) — in code that hasn't changed since the last review.

CosmosDBShell/Azure.Data.Cosmos.Shell.Commands/WhoamiCommand.cs:77

• The AuthenticationFailedException wrapper drops the original exception, which makes verbose/diagnostic output lose the per-credential failure details (inner exceptions, stack trace). Preserve the inner exception when rethrowing CommandException so troubleshooting whoami token acquisition failures remains actionable.

            catch (AuthenticationFailedException ex)
            {
                throw new CommandException("whoami", MessageService.GetArgsString("command-whoami-token-error", "message", ex.Message));
            }

CosmosDBShell/Azure.Data.Cosmos.Shell.Commands/CanICommand.cs:175

• MapDecision treats HTTP 404 as "allow" for read/write probes. A 404 can also mean the target database/container does not exist, so reporting "allow" can be misleading (similar to the query probe, where 404 is already treated as indeterminate). Consider disambiguating NotFound cases (e.g., via a follow-up container metadata read, Cosmos substatus, or returning indeterminate with a targeted note) so missing resources don't look like successful authorization.

            case HttpStatusCode.Forbidden:
            case HttpStatusCode.Unauthorized:
                return ("deny", null);
            case HttpStatusCode.OK:
            case HttpStatusCode.NoContent:
            case HttpStatusCode.NotFound:
            case HttpStatusCode.PreconditionFailed:
                return ("allow", null);

CosmosDBShell/Azure.Data.Cosmos.Shell.Commands/CanICommand.cs:145

• The PR description states the query probe is a COUNT query, but the implementation uses a minimal SELECT TOP 1 ... query with MaxItemCount = 1 (see ProbeQueryAsync) to avoid expensive scans. Please update the PR description to match the implemented behavior so reviewers/users aren't misled.

    private static async Task<HttpStatusCode> ProbeQueryAsync(Container container, CancellationToken token)
    {
        // A minimal TOP 1 query with a single-item page proves query authorization without
        // forcing a full scan (as an aggregate like COUNT would) on large containers.
        var requestOptions = new QueryRequestOptions { MaxItemCount = 1 };
        using var iterator = container.GetItemQueryStreamIterator(
            new QueryDefinition("SELECT TOP 1 c.id FROM c"),
            requestOptions: requestOptions);
        using var response = await iterator.ReadNextAsync(token);
        return response.StatusCode;