Enhance Microsoft Authentication API for better account management

[mjcheetham]

Refs: git-ecosystem#2057

Summary

Reshapes IMicrosoftAuthentication around an explicit IMicrosoftAccount parameter type, so callers can identify accounts by stable HomeAccountId (preferred), by UserName (fallback), or both — without losing information at the API boundary.

The previous shape took a bare string userName for GetTokenForUserAsync and had no equivalent of app.GetAccountsAsync() / app.RemoveAsync() at all. That worked fine for single-tenant single-account users, but it lost information in two important scenarios: guest accounts where the same UPN exists in two tenants (the same UPN, different HomeAccountId), and callers that already carry a stable id from persistent storage (forced to translate down to a UPN and back). Pivoting the surface around an account abstraction removes both classes of bug at the source.

No provider behaviour changes for end-users. The Azure Repos provider is updated mechanically alongside the API changes that touch its callers, but the AzRepos product features that motivated the reshape (binding manager rewrite, new login/logout/list verbs) ship in a follow-on PR on top of this one.

What's in this PR

Seven commits, ordered as a readable story.

Two preparatory renames

1. msauth: extract and rename SPI class to own file
   Rename ServicePrincipalIdentity → MicrosoftServicePrincipalIdentity for consistency with the other Microsoft* types, and move it to its own file alongside MicrosoftWorkloadFederationOptions. Pure refactor.

2. msauth: rename MicrosoftAuthenticationFlowType and make private
MicrosoftAuthenticationFlowType was a public enum at the GitCredentialManager.Authentication namespace level despite being used only inside MicrosoftAuthentication. Move it to a nested internal InteractiveFlowType so the public surface shrinks and the name reads naturally now that it's scoped.

The IMicrosoftAccount surface (4 commits)

3. msauth: add IMicrosoftAuthentication.GetUserAccountsAsync
   New enumeration method on the interface so callers can list cached Microsoft accounts without going through MSAL directly. Introduces the IMicrosoftAccount abstraction (UPN + opaque HomeAccountId) and a publicly constructible MicrosoftAccount POCO sitting next to it. Relaxes CreatePublicClientApplicationAsync to skip WithAuthority/WithRedirectUri when null, since the cache is keyed by client id only.

   IMicrosoftAccount ships with an IEquatable<IMicrosoftAccount> contract so any implementer must opt in to value semantics from the start: accounts are natural keys (dedupe a cached list, compare a stored value against a fresh enumeration, use as a dictionary key) and reference equality would silently break those scenarios. The concrete MicrosoftAccount implements equality with OrdinalIgnoreCase on both fields — HomeAccountId because MSAL's own AccountId.Equals compares its Identifier case-insensitively, and UserName because UPNs are case-insensitive per RFC 5321. GetHashCode is a manual xor combine of the two field hashes rather than HashCode.Combine, so the type stays buildable on .NET Framework 4.7.2 without pulling in Microsoft.Bcl.HashCode.

4. msauth: surface the full account from authentication results
   Replaces IMicrosoftAuthenticationResult.AccountUpn (bare string) with a full IMicrosoftAccount Account property. The result now exposes the stable HomeAccountId alongside the display name, so callers persisting a record don't have to re-enumerate the cache to find it.

5. msauth: add RemoveUserAccountAsync
   Counterpart to GetUserAccountsAsync. Takes an IMicrosoftAccount from the start (no string-first version ever shipped); resolves against the MSAL cache HomeAccountId-first with a UPN fallback, trace-warning on mismatch or ambiguity. String comparisons use OrdinalIgnoreCase throughout to match MSAL's own AccountId.Equals semantics.

6. msauth: accept IMicrosoftAccount on GetTokenForUserAsync
   Pivots the pre-existing string userName parameter to IMicrosoftAccount. Internal resolution prefers HomeAccountId when present, falls back to UserName, trace-warns on mismatch or multi-match.

   The silent-acquisition helper unifies behind a single GetAccessTokenSilentlyAsync(app, scopes, IAccount, msaPt): callers with an explicit cached account pass it through, and the broker's "default OS account" path resolves to PublicClientApplication.OperatingSystemAccount (an IAccount sentinel) and goes through the same path. The MSA-passthrough tenant-id workaround switches to a null-safe lookup so it no-ops cleanly when the sentinel's HomeAccountId isn't populated.

   Adds a new MicrosoftAuthenticationExtensions static class to host an [Obsolete] extension that preserves the pre-existing (…, string userName, …) signature. Existing in-tree production call sites keep building with a deprecation warning as a TODO list; the only remaining production caller (the Azure Repos OAuth path) migrates in the follow-on PR, which then deletes the extension.

Plus diagnostics (1 commit)

7. msauth: surface the authentication flow on the result
   Adds a public MicrosoftAuthenticationFlow enum and a Flow property on IMicrosoftAuthenticationResult so consumers can tell (a) whether MSAL prompted the user (IsInteractive() extension method), and (b) which technique was used. Nine values collapse all the paths into named buckets: Unknown (escape hatch), ServicePrincipal, ManagedIdentity, WorkloadFederation, Silent, BrokerSilent, BrokerInteractive, EmbeddedWebView, SystemWebView, DeviceCode.

   Silent vs BrokerSilent is determined at the silent return site by inspecting MSAL's own AuthenticationResultMetadata.TokenSource — broker-cached tokens behave differently from MSAL-cached tokens on revocation and tenant-switch scenarios, and surfacing the distinction is free.

   No consumer reads Flow today — surfacing it now is preparation for picker policy, future telemetry, and trace diagnostics that already had no good way to learn this without log scraping.

What this enables (deliberately not in this PR)

• Azure Repos consumer migration + product changes.
  A follow-on PR migrates the AzRepos OAuth caller to the new API, deletes the obsolete [Obsolete] extension (zero remaining callers), and rebuilds the binding manager around the new account abstraction. The "no translation helpers at the provider boundary" cleanliness win is the headline of that PR — and is only possible because this PR pivoted the API first.

• Other providers.
  GitHub, Bitbucket, and GitLab don't use IMicrosoftAuthentication today. If they ever do, they'll get the new shape from day one.

Compatibility

• Out-of-tree callers of the string-userName overload.
  Continue to compile via the [Obsolete] extension method. Deprecation warning shows up as a TODO; behaviour is preserved exactly — the extension wraps by constructing new MicrosoftAccount(homeAccountId: null, userName), which is the "UPN-only" shape that resolves identically to today.

• Out-of-tree implementers of IMicrosoftAccount.
  Newly required to implement IEquatable<IMicrosoftAccount>. This is a deliberate contract upgrade: any implementer that didn't already have value semantics was silently broken in dictionary scenarios; the interface now surfaces that requirement at compile time.

• Out-of-tree implementers of IMicrosoftAuthenticationResult.
  Newly required to implement Flow. The Unknown enum value exists specifically so implementers that don't classify can return it.

• AccountUpn → Account on IMicrosoftAuthenticationResult.
  Source-breaking for anyone reading the property. The new shape exposes strictly more information (UPN remains accessible via Account.UserName).

Testing

• Full unit test suite passes (Core, AzureRepos, GitHub, Bitbucket, GitLab).
• AzureReposHostProviderTests mock setups migrated to the new interface signature; each setup hoists a local var expectedAccount = new MicrosoftAccount(homeAccountId: null, userName: …) (or IMicrosoftAccount expectedAccount = null for the unconstrained case) and passes it directly to Setup. The value-equality contract in commit 3 is what lets Moq match these by value rather than reference.

Notes for reviewers

• The two IMicrosoftAccount shape decisions worth eyeballing: HomeAccountId-wins-on-mismatch precedence (commit 5, reused in commit 6) and UPN-only-multi-match traces-warn-and-picks-first (also commits 5 + 6). Both are documented at the resolution site.
• The OrdinalIgnoreCase choice for HomeAccountId comparisons matches MSAL's own AccountId.Equals (Microsoft.Identity.Client AccountId.cs, line ~84). The same comparer is used by the equality contract in commit 3 and the resolution helper introduced in commit 5.
• Each commit builds cleanly and tests pass at every step. Commit 6 emits one expected deprecation warning at the Azure Repos call site, which the follow-on PR clears.

Closes part of git-ecosystem#2057.