feat: add state parameter support to OAuth provider sign-in

Author: Tr00d

Gotrue/Helpers.cs

@@ -108,6 +108,10 @@ internal static ProviderAuthState GetUrlForProvider(string url, Constants.Provid
 			if (attr == null)
 				throw new Exception("Unknown provider");
 
+			var state = !string.IsNullOrEmpty(options.State) ? options.State : GenerateNonce();
+			query.Add("state", state);
+			result.State = state;
+
 			query.Add("provider", attr.Mapping);
 
 			if (!string.IsNullOrEmpty(options.Scopes))

Gotrue/ProviderAuthState.cs

@@ -18,6 +18,12 @@ public class ProviderAuthState
         /// </summary>
         public string? PKCEVerifier { get; set; }
 
+        /// <summary>
+        /// The state parameter included in the OAuth URL for CSRF protection (RFC 6749 §10.12).
+        /// Validate this against the state echoed back in the OAuth callback.
+        /// </summary>
+        public string State { get; set; } = null!;
+
         /// <summary>
         /// Constructor
         /// </summary>

Gotrue/SignInOptions.cs

@@ -29,5 +29,13 @@ public class SignInOptions
         /// PKCE is recommended for mobile and server-side applications.
         /// </summary>
         public OAuthFlowType FlowType { get; set; } = OAuthFlowType.Implicit;
+
+        /// <summary>
+        /// An optional state parameter for CSRF protection (RFC 6749 §10.12).
+        /// If not provided, one will be generated automatically.
+        /// Store the returned <see cref="ProviderAuthState.State"/> value and validate it
+        /// against the state echoed back in the OAuth callback.
+        /// </summary>
+        public string? State { get; set; }
     }
 }

GotrueTests/PKCE/PkceContractTests.cs

@@ -77,6 +77,27 @@ public async Task ResetPasswordForEmailPkce_ChallengeIsHashOfVerifier()
 		request.ReadJsonBodyField("code_challenge").Should().Be(S256(state.PKCEVerifier!), "server must receive BASE64URL(SHA256(verifier)) per RFC 7636 §4.2");
 	}
 
+	[TestMethod("SignInWithProvider: auto-generates state and includes it in the URL")]
+	public async Task SignInWithProvider_AutoGeneratesState()
+	{
+		var result = await client.SignIn(Provider.Github, new SignInOptions { FlowType = OAuthFlowType.PKCE });
+		result.State.Should().NotBeNullOrEmpty();
+		result.Uri.Query.Should().Contain($"state={result.State}");
+	}
+
+	[TestMethod("SignInWithProvider: uses developer-provided state and includes it in the URL")]
+	public async Task SignInWithProvider_UsesDeveloperProvidedState()
+	{
+		var customState = "my-server-generated-csrf-token";
+		var result = await client.SignIn(Provider.Github, new SignInOptions
+		{
+			FlowType = OAuthFlowType.PKCE,
+			State = customState
+		});
+		result.State.Should().Be(customState);
+		result.Uri.Query.Should().Contain($"state={customState}");
+	}
+
 	private static string S256(string verifier)
 	{
 		using var sha = SHA256.Create();