fix(auth): fix getClaims() crash with asymmetric JWTs on first call (#1300)

Fixed a crash in getClaims() that occurred when verifying JWTs signed
with asymmetric algorithms (RS256, ES256) on the first call.

The issue was that _jwks was force-unwrapped (_jwks!) before it was
initialized. On the first call to getClaims() with an asymmetric JWT
containing a 'kid' header, _jwks would be null, causing a null check
operator error.

The fix passes an empty JWKSet when the cache is null:
_jwks ?? JWKSet(keys: []). This allows _fetchJwk() to handle the first
call gracefully by fetching from the server and populating the cache.

Changes:
- Updated getClaims() to use null-coalescing operator instead of force-unwrap
- Added test case to reproduce and verify the fix for SDK-627
- Enhanced documentation to clarify JWKS caching behavior for asymmetric JWTs

Linear: SDK-627

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: grdsdev

packages/gotrue/lib/src/gotrue_client.dart

@@ -1397,6 +1397,11 @@ class GoTrueClient {
   ///
   /// If the project is not using an asymmetric JWT signing key (like ECC or
   /// RSA) it always sends a request to the Auth server (similar to [getUser]) to verify the JWT.
+  ///
+  /// For JWTs signed with asymmetric algorithms (RS256, ES256, etc.), the JWKS
+  /// is fetched from the server on the first call and cached for subsequent calls.
+  /// The cache is refreshed automatically after 10 minutes.
+  ///
   /// [jwt] An optional specific JWT you wish to verify, not the one you
   ///       can obtain from [currentSession].
   /// [options] Various additional options that allow you to customize the
@@ -1428,7 +1433,7 @@ class GoTrueClient {
     final signingKey =
         (decoded.header.alg.startsWith('HS') || decoded.header.kid == null)
             ? null
-            : await _fetchJwk(decoded.header.kid!, _jwks!);
+            : await _fetchJwk(decoded.header.kid!, _jwks ?? JWKSet(keys: []));
 
     // If symmetric algorithm, fallback to getUser()
     if (signingKey == null) {

packages/gotrue/test/get_claims_test.dart

@@ -207,6 +207,54 @@ void main() {
     });
   });
 
+  group('getClaims with asymmetric JWTs', () {
+    late GoTrueClient client;
+
+    setUp(() {
+      final asyncStorage = TestAsyncStorage();
+
+      client = GoTrueClient(
+        url: gotrueUrl,
+        headers: {
+          'Authorization': 'Bearer $anonToken',
+          'apikey': anonToken,
+        },
+        asyncStorage: asyncStorage,
+        flowType: AuthFlowType.implicit,
+      );
+    });
+
+    test('getClaims() with RS256 JWT on first call should not crash (SDK-627)',
+        () async {
+      // This test reproduces the bug reported in SDK-627
+      // A JWT with RS256 algorithm and kid in header
+      // Header: {"alg":"RS256","typ":"JWT","kid":"test-key-id"}
+      // Payload: {"sub":"1234567890","aud":"authenticated","exp":9999999999,"iat":1516239022,"email":"test@example.com","role":"authenticated"}
+      // Signature: dummy base64url encoded signature (not cryptographically valid, but structurally valid)
+      const rs256Jwt =
+          'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InRlc3Qta2V5LWlkIn0.eyJzdWIiOiIxMjM0NTY3ODkwIiwiYXVkIjoiYXV0aGVudGljYXRlZCIsImV4cCI6OTk5OTk5OTk5OSwiaWF0IjoxNTE2MjM5MDIyLCJlbWFpbCI6InRlc3RAZXhhbXBsZS5jb20iLCJyb2xlIjoiYXV0aGVudGljYXRlZCJ9.SW52YWxpZFNpZ25hdHVyZURhdGFIZXJlVGhhdElzTm90UmVhbEJ1dFZhbGlkQmFzZTY0VXJs';
+
+      // Before the fix, this would crash with:
+      // "Null check operator used on a null value"
+      // because _jwks is null on first call and the code does _jwks!
+      //
+      // After the fix, this should attempt to fetch JWKS from the server
+      // and fail gracefully (either with network error or invalid signature)
+      // but NOT crash with null error
+      try {
+        await client.getClaims(rs256Jwt);
+        // If we get here, the server responded successfully (unlikely in test env)
+      } catch (e) {
+        // The important part is that it should NOT crash with null error
+        // It may fail with network error, invalid signature, etc.
+        // but the error message should not contain null-related errors
+        expect(e.toString(), isNot(contains('Unexpected null value')));
+        expect(e.toString(), isNot(contains('Null check operator')));
+      }
+      // Test passes if we get here without null error
+    });
+  });
+
   group('JWT helper functions', () {
     test('decodeJwt() successfully decodes valid JWT', () {
       // A sample JWT with known values