Security: lock JsonWebToken trust-boundary contract (#6 disposition)

[corinagum]

Summary

Documents the layered authentication model the SDK uses for inbound JSON Web Tokens. .NET half of a 3-SDK PR set.

Why

Security scan finding "JsonWebToken No Signature Verification" flagged the JsonWebToken accessor class for using JwtSecurityTokenHandler.ReadJwtToken() (decode-only, no signature verification). A cross-SDK audit confirmed this is intentional architecture: signature verification runs at the ASP.NET Core JwtBearer middleware configured by TokenValidator.ConfigureValidation (Libraries/Microsoft.Teams.Plugins/Microsoft.Teams.Plugins.AspNetCore/Extensions/TokenValidator.cs), applied to endpoints via .RequireAuthorization(...). The accessor exists as a typed view over already-validated payloads. Every consumer of decoded claims is downstream of either a JwtBearer validation or a trusted identity-infrastructure source.

This PR makes the architectural invariant explicit at the constructor site so future readers (and the scanner on its next pass) see the design intent locally.

What

XML documentation on both JsonWebToken constructors explaining that they perform no signature verification, where verification actually happens, and the rule that callers must not construct from raw network input.

Scope note: core/ (2.1)

core/ was audited separately and does not have an equivalent decode-only public accessor. Its inbound JWT validation is enforced at the middleware level with ValidateIssuerSigningKey = true and RequireSignedTokens = true hardcoded; there is no public API to misuse. The finding does not apply to core/. This PR scopes to Libraries/ only.

What this does not change

• No runtime behavior change. No signature verification added or removed.
• No API surface change. JsonWebToken keeps its current name (verified public in the packable Microsoft.Teams.Api assembly, including via IContext<TActivity>.UserGraphToken and AspNetCorePlugin.ExtractToken() return type; a rename would have been breaking).
• No effect on the activity pipeline. JWT validation continues to happen via JwtBearer middleware exactly as before.

Related PRs

• TypeScript: Security: lock JsonWebToken trust-boundary contract teams.ts#586
• Python: Security: lock JsonWebToken trust-boundary contract teams.py#432
• Documentation: Docs: layered trust model for JWT validation teams-sdk#2850

[Copilot]

Pull request overview

This PR clarifies the security/trust-boundary contract for Microsoft.Teams.Api.Auth.JsonWebToken by documenting that it is a decode-only, typed accessor over an already-validated JWT payload (i.e., it does not perform signature, issuer/audience, or lifetime validation itself), and by pointing readers to where validation occurs in the ASP.NET Core pipeline.

Changes:

• Added XML documentation to JsonWebToken(string token) describing the decode-only behavior and explicit trust-boundary requirements.
• Added XML documentation to JsonWebToken(Token.Response response) aligning it with the same trust-boundary contract.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.