hostprovider: wire the state and continue protocol capability

Git 2.46 added the `state` capability to the credential helper
protocol, gating two new attributes:

  state[]   -- opaque per-helper key/value pairs Git stores between
               invocations and replays back when calling the same
               helper, so providers can carry context across the
               get + store/erase command cycle without their own
               sidecar storage.

  continue  -- a boolean signal from helper to Git indicating that
               the credential just returned is a non-final part of
               a multistage authentication flow; Git is expected to
               call the helper again after a follow-up 401.

This is the marquee feature behind issue #2057. It unlocks
optimistic account selection (try one account, remember the
choice in state, fall through to a different account on 401),
multistage authentication for NTLM/Kerberos-style flows, and any
provider scenario that benefits from per-request memory.

Surface
-------

* GitCapabilities.State flag added and included in the advertised
  set so the negotiation handshake is functional end-to-end.

* GitRequest.State exposes a lazy IReadOnlyDictionary<string,string>
  of incoming state. Only entries whose key begins with the
  reserved `gcm.` prefix are kept (per the protocol's "ignore
  values that don't match its prefix" rule); the prefix is
  stripped from dictionary keys. Malformed entries are silently
  discarded.

* GitResponse grows a fourth shape: Continue(credential) returns
  a response that carries a credential and signals `continue=1`.
  The shape matrix is now Ok / Continue / Cancel / Yield, all
  mutually exclusive, enforced by the constructor.

* GitResponse adds a curated state surface:
    State    -- IReadOnlyDictionary<string,string> view for reads
                and enumeration; standard IDictionary patterns
                (indexer, TryGetValue, ContainsKey, foreach) work.
    SetState -- the single mutation path; validates every entry
                and silently no-ops on Cancel/Yield.
    WithState -- fluent equivalent of SetState that returns the
                 same instance for chaining at the return site.

  There is no IDictionary mutation surface and no GetState/TryGetState
  forwarder: writes always go through the validating method, reads
  go through the dictionary view. Smaller API surface, no
  duplicated semantics.

* SetState always validates key and value against the wire
  protocol rules (no '=' in key, no newline or NUL anywhere, no
  empty key, no leading `gcm.` prefix) and throws ArgumentException
  on violations regardless of response shape: those are
  programming errors that should surface at the call site rather
  than being silently dropped on the wire.

* On Cancel and Yield shapes SetState then silently no-ops:
  state has no meaning when no credential is being returned, so
  providers that build a response speculatively and then switch
  shape don't have to remember to strip state.

* Constants.CredentialProtocol gains StateKey, ContinueKey, and
  GcmStatePrefix so the wire vocabulary lives in one place.

Wire emission
-------------

GetCommand writes its response in protocol order: capability[]
directives first (the spec requires these precede any value
depending on them), then scalar fields (protocol/host/path/
username/password and AdditionalProperties), then continue=1,
then state[]= entries, then the terminating blank line.

state[] and continue are gated on the negotiated `state`
capability. If a provider sets either but the capability was not
negotiated with Git, both are silently dropped with a trace
message. Dropping continue is loud in the trace specifically
because it changes auth semantics: Git will treat the credential
as final and likely fail on the next 401.

Out of scope
------------

No in-tree provider produces state or continue yet. Wiring
specific scenarios (AzureRepos multi-account MSAL, GitHub
account selection, etc.) is left to follow-up commits that can
focus on each scenario's design without needing to also land
infrastructure.

Signed-off-by: Matthew John Cheetham <mjcheetham@outlook.com>
Assisted-by: Claude Opus 4.7

Author: mjcheetham

src/Core.Tests/Commands/CapabilityCommandTests.cs

@@ -21,8 +21,8 @@ public void CapabilityCommand_Execute_WritesVersionAndAdvertisedCapabilities()
         // older Gits and helpers treat anything else as "no capabilities supported".
         Assert.StartsWith("version 0\n", actualOutput);
 
-        // GCM advertises no capabilities yet; only the version line should be emitted.
-        Assert.Equal("version 0\n", actualOutput);
+        // GCM advertises the state capability.
+        Assert.Equal("version 0\ncapability state\n", actualOutput);
     }
 
     [Fact]

src/Core.Tests/Commands/GetCommandTests.cs

@@ -1,3 +1,4 @@
+using System;
 using System.Collections.Generic;
 using System.IO;
 using System.Text;
@@ -99,10 +100,12 @@ public async Task GetCommand_ExecuteAsync_AdditionalProperties_AreEmitted()
         }
 
         [Fact]
-        public async Task GetCommand_ExecuteAsync_NoNegotiatedCapabilities_EmitsNoCapabilityLines()
+        public async Task GetCommand_ExecuteAsync_NegotiatedCapability_EchoesIntersection()
         {
-            // GCM advertises no capabilities yet; even when Git declares some,
-            // the intersection is empty and no capability[] lines should be emitted.
+            // Git advertises authtype + state; GCM advertises state. The intersection
+            // (state) MUST be echoed back via `capability[]=state` per the protocol's
+            // capability negotiation rules. The unsupported authtype MUST NOT be
+            // echoed.
             ICredential testCredential = new GitCredential("alice", "hunter2");
             var stdin = "protocol=https\nhost=example.com\ncapability[]=authtype\ncapability[]=state\n\n";
 
@@ -116,6 +119,30 @@ public async Task GetCommand_ExecuteAsync_NoNegotiatedCapabilities_EmitsNoCapabi
 
             await command.ExecuteAsync();
 
+            string actualOutput = context.Streams.Out.ToString().Replace("\r\n", "\n");
+
+            Assert.Contains("capability[]=state\n", actualOutput);
+            Assert.DoesNotContain("capability[]=authtype", actualOutput);
+        }
+
+        [Fact]
+        public async Task GetCommand_ExecuteAsync_NoCapabilityFromGit_EmitsNoCapabilityLines()
+        {
+            // Git declares no capabilities; even though GCM advertises state, the
+            // intersection is empty and no capability[] lines should be emitted.
+            ICredential testCredential = new GitCredential("alice", "hunter2");
+            var stdin = "protocol=https\nhost=example.com\n\n";
+
+            var providerMock = new Mock<IHostProvider>();
+            providerMock.Setup(x => x.GetCredentialAsync(It.IsAny<GitRequest>()))
+                        .ReturnsAsync(new GitResponse(testCredential));
+            var providerRegistry = new TestHostProviderRegistry { Provider = providerMock.Object };
+            var context = new TestCommandContext { Streams = { In = stdin } };
+
+            var command = new GetCommand(context, providerRegistry);
+
+            await command.ExecuteAsync();
+
             string actualOutput = context.Streams.Out.ToString();
 
             Assert.DoesNotContain("capability", actualOutput);
@@ -170,6 +197,137 @@ public async Task GetCommand_ExecuteAsync_YieldedResponse_EmitsEmptyResponse()
             Assert.Equal("\n", actualOutput);
         }
 
+        [Fact]
+        public async Task GetCommand_ExecuteAsync_StateNegotiated_EmitsStateLinesWithGcmPrefix()
+        {
+            ICredential testCredential = new GitCredential("alice", "hunter2");
+            var response = GitResponse.Ok(testCredential);
+            response.SetState("github.account", "alice");
+            response.SetState("azure.tenant", "contoso");
+
+            var stdin = "protocol=https\nhost=example.com\ncapability[]=state\n\n";
+
+            var providerMock = new Mock<IHostProvider>();
+            providerMock.Setup(x => x.GetCredentialAsync(It.IsAny<GitRequest>()))
+                        .ReturnsAsync(response);
+            var providerRegistry = new TestHostProviderRegistry { Provider = providerMock.Object };
+            var context = new TestCommandContext { Streams = { In = stdin } };
+
+            var command = new GetCommand(context, providerRegistry);
+
+            await command.ExecuteAsync();
+
+            string actualOutput = context.Streams.Out.ToString().Replace("\r\n", "\n");
+
+            Assert.Contains("state[]=gcm.github.account=alice\n", actualOutput);
+            Assert.Contains("state[]=gcm.azure.tenant=contoso\n", actualOutput);
+        }
+
+        [Fact]
+        public async Task GetCommand_ExecuteAsync_StateNotNegotiated_DropsStateLines()
+        {
+            ICredential testCredential = new GitCredential("alice", "hunter2");
+            var response = GitResponse.Ok(testCredential);
+            response.SetState("github.account", "alice");
+
+            // Git did NOT advertise the state capability.
+            var stdin = "protocol=https\nhost=example.com\n\n";
+
+            var providerMock = new Mock<IHostProvider>();
+            providerMock.Setup(x => x.GetCredentialAsync(It.IsAny<GitRequest>()))
+                        .ReturnsAsync(response);
+            var providerRegistry = new TestHostProviderRegistry { Provider = providerMock.Object };
+            var context = new TestCommandContext { Streams = { In = stdin } };
+
+            var command = new GetCommand(context, providerRegistry);
+
+            await command.ExecuteAsync();
+
+            string actualOutput = context.Streams.Out.ToString();
+
+            Assert.DoesNotContain("state[]", actualOutput);
+        }
+
+        [Fact]
+        public async Task GetCommand_ExecuteAsync_ContinueNegotiated_EmitsContinue1AlongsideCredential()
+        {
+            ICredential testCredential = new GitCredential("alice", "hunter2");
+            var stdin = "protocol=https\nhost=example.com\ncapability[]=state\n\n";
+
+            var providerMock = new Mock<IHostProvider>();
+            providerMock.Setup(x => x.GetCredentialAsync(It.IsAny<GitRequest>()))
+                        .ReturnsAsync(GitResponse.Continue(testCredential));
+            var providerRegistry = new TestHostProviderRegistry { Provider = providerMock.Object };
+            var context = new TestCommandContext { Streams = { In = stdin } };
+
+            var command = new GetCommand(context, providerRegistry);
+
+            await command.ExecuteAsync();
+
+            string actualOutput = context.Streams.Out.ToString().Replace("\r\n", "\n");
+
+            Assert.Contains("username=alice\n", actualOutput);
+            Assert.Contains("password=hunter2\n", actualOutput);
+            Assert.Contains("continue=1\n", actualOutput);
+        }
+
+        [Fact]
+        public async Task GetCommand_ExecuteAsync_ContinueNotNegotiated_DropsContinueLine()
+        {
+            ICredential testCredential = new GitCredential("alice", "hunter2");
+            var stdin = "protocol=https\nhost=example.com\n\n";
+
+            var providerMock = new Mock<IHostProvider>();
+            providerMock.Setup(x => x.GetCredentialAsync(It.IsAny<GitRequest>()))
+                        .ReturnsAsync(GitResponse.Continue(testCredential));
+            var providerRegistry = new TestHostProviderRegistry { Provider = providerMock.Object };
+            var context = new TestCommandContext { Streams = { In = stdin } };
+
+            var command = new GetCommand(context, providerRegistry);
+
+            await command.ExecuteAsync();
+
+            string actualOutput = context.Streams.Out.ToString();
+
+            // Credential still emitted; continue silently dropped.
+            Assert.Contains("username=alice", actualOutput);
+            Assert.DoesNotContain("continue=", actualOutput);
+        }
+
+        [Fact]
+        public async Task GetCommand_ExecuteAsync_OutputOrdering_CapabilitiesFirstThenScalarsThenContinueThenState()
+        {
+            ICredential testCredential = new GitCredential("alice", "hunter2");
+            var response = GitResponse.Continue(testCredential);
+            response.SetState("k", "v");
+
+            var stdin = "protocol=https\nhost=example.com\ncapability[]=state\n\n";
+
+            var providerMock = new Mock<IHostProvider>();
+            providerMock.Setup(x => x.GetCredentialAsync(It.IsAny<GitRequest>()))
+                        .ReturnsAsync(response);
+            var providerRegistry = new TestHostProviderRegistry { Provider = providerMock.Object };
+            var context = new TestCommandContext { Streams = { In = stdin } };
+
+            var command = new GetCommand(context, providerRegistry);
+
+            await command.ExecuteAsync();
+
+            string actualOutput = context.Streams.Out.ToString().Replace("\r\n", "\n");
+
+            int posCapability = actualOutput.IndexOf("capability[]=state", StringComparison.Ordinal);
+            int posUsername   = actualOutput.IndexOf("username=", StringComparison.Ordinal);
+            int posContinue   = actualOutput.IndexOf("continue=1", StringComparison.Ordinal);
+            int posState      = actualOutput.IndexOf("state[]=", StringComparison.Ordinal);
+
+            Assert.True(posCapability >= 0 && posUsername > posCapability,
+                "capability[] must precede scalar fields");
+            Assert.True(posContinue > posUsername,
+                "continue=1 must follow scalar fields");
+            Assert.True(posState > posContinue,
+                "state[] must follow continue=1");
+        }
+
         #region Helpers
 
         private static IDictionary<string, string> ParseDictionary(StringBuilder sb) => ParseDictionary(sb.ToString());

src/Core.Tests/GitCapabilitiesTests.cs

@@ -5,11 +5,12 @@ namespace GitCredentialManager.Tests;
 public class GitCapabilitiesTests
 {
     [Fact]
-    public void Advertised_DefaultsToNone()
+    public void Advertised_IncludesState()
     {
-        // Until specific capability handling is wired up piecemeal, GCM
-        // advertises no capabilities back to Git.
-        Assert.Equal(GitCapabilities.None, Constants.SupportedCapabilities);
+        // GCM advertises support for the state capability so the negotiation
+        // handshake is functional end-to-end. Individual providers opt in to
+        // emitting state/continue piecemeal.
+        Assert.True(Constants.SupportedCapabilities.HasFlag(GitCapabilities.State));
     }
 
     [Fact]
@@ -27,15 +28,35 @@ public void ParseName_UnknownName_ReturnsNone()
         Assert.Equal(GitCapabilities.None, GitCapabilitiesUtils.ParseName("totally-unknown"));
     }
 
+    [Fact]
+    public void ParseName_State_ReturnsStateFlag()
+    {
+        Assert.Equal(GitCapabilities.State, GitCapabilitiesUtils.ParseName("state"));
+        Assert.Equal(GitCapabilities.State, GitCapabilitiesUtils.ParseName("STATE"));
+        Assert.Equal(GitCapabilities.State, GitCapabilitiesUtils.ParseName("State"));
+    }
+
     [Fact]
     public void ToProtocolName_None_Throws()
     {
         Assert.Throws<System.ArgumentException>(() => GitCapabilitiesUtils.ToProtocolName(GitCapabilities.None));
     }
 
+    [Fact]
+    public void ToProtocolName_State_ReturnsStateString()
+    {
+        Assert.Equal("state", GitCapabilitiesUtils.ToProtocolName(GitCapabilities.State));
+    }
+
     [Fact]
     public void ToProtocolNames_None_ReturnsEmpty()
     {
         Assert.Empty(GitCapabilitiesUtils.ToProtocolNames(GitCapabilities.None));
     }
+
+    [Fact]
+    public void ToProtocolNames_State_ReturnsStateOnly()
+    {
+        Assert.Equal(new[] { "state" }, GitCapabilitiesUtils.ToProtocolNames(GitCapabilities.State));
+    }
 }

src/Core.Tests/GitRequestTests.cs

@@ -387,5 +387,81 @@ public void GitRequest_Capabilities_UnknownNames_AreSilentlyDiscarded()
 
             Assert.Equal(GitCapabilities.None, request.Capabilities);
         }
+
+        [Fact]
+        public void GitRequest_State_NoStateInput_IsEmpty()
+        {
+            var dict = new Dictionary<string, string>
+            {
+                ["protocol"] = "https",
+                ["host"]     = "example.com",
+            };
+
+            var request = new GitRequest(dict);
+
+            Assert.Empty(request.State);
+        }
+
+        [Fact]
+        public void GitRequest_State_KeepsOnlyGcmPrefixedEntries_AndStripsPrefix()
+        {
+            var dict = new Dictionary<string, IList<string>>
+            {
+                ["protocol"] = new[] { "https" },
+                ["host"]     = new[] { "example.com" },
+                ["state"]    = new[]
+                {
+                    "gcm.github.account=alice",
+                    "other-helper.foo=bar", // not ours; ignored
+                    "gcm.azure.tenant=contoso",
+                },
+            };
+
+            var request = new GitRequest(dict);
+
+            Assert.Equal(2, request.State.Count);
+            Assert.Equal("alice", request.State["github.account"]);
+            Assert.Equal("contoso", request.State["azure.tenant"]);
+            Assert.False(request.State.ContainsKey("other-helper.foo"));
+        }
+
+        [Fact]
+        public void GitRequest_State_MalformedEntries_AreSilentlyDiscarded()
+        {
+            var dict = new Dictionary<string, IList<string>>
+            {
+                ["protocol"] = new[] { "https" },
+                ["host"]     = new[] { "example.com" },
+                ["state"]    = new[]
+                {
+                    "gcm.valid=ok",
+                    "gcm.no-equals", // malformed: no '='
+                    "=value-without-key", // malformed: empty key
+                    "gcm.=empty-key-after-prefix", // empty key after prefix-strip
+                },
+            };
+
+            var request = new GitRequest(dict);
+
+            Assert.Single(request.State);
+            Assert.Equal("ok", request.State["valid"]);
+        }
+
+        [Fact]
+        public void GitRequest_State_ValueMayContainEquals()
+        {
+            // Only the FIRST '=' separates key from value; the value may itself
+            // contain additional '=' characters.
+            var dict = new Dictionary<string, IList<string>>
+            {
+                ["protocol"] = new[] { "https" },
+                ["host"]     = new[] { "example.com" },
+                ["state"]    = new[] { "gcm.token=abc=def=ghi" },
+            };
+
+            var request = new GitRequest(dict);
+
+            Assert.Equal("abc=def=ghi", request.State["token"]);
+        }
     }
 }