feat(gotrue): introduce getClaims method to verify and extract JWT claims (#1246)

* feat(gotrue): introduce getClaims method to verify and extract JWT claims

This introduces a new `getClaims` method that supports verifying JWTs
(both symmetric and asymmetric) and returns the entire set of claims
in the JWT payload.

Key changes:
- Add `getClaims()` method to GoTrueClient for JWT verification and claims extraction
- Implement base64url encoding/decoding utilities (RFC 4648)
- Add JWT types: JwtHeader, JwtPayload, DecodedJwt, GetClaimsResponse
- Add helper functions: decodeJwt() and validateExp()
- Add AuthInvalidJwtException for JWT-related errors
- Include comprehensive tests for getClaims, JWT helpers, and base64url utilities

The method verifies JWTs by calling getUser() to validate against the
server, supporting both HS256 (symmetric) and RS256/ES256 (asymmetric)
algorithms.

Note: This is an experimental API and may change in future versions.

Ported from: supabase/auth-js#1030

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* feat(gotrue): make getClaims() non-experimental, add options parameter

Following up on the initial getClaims implementation, this commit:

- Removes experimental status from getClaims() method
- Adds GetClaimsOptions class with allowExpired parameter
- Updates getClaims() to accept optional options parameter
- Improves documentation to better describe the method's behavior
- Exports helper functions (decodeJwt, validateExp) for public use
- Adds tests for allowExpired option

The allowExpired option allows users to extract claims from expired
JWTs without throwing an error during expiration validation. This is
useful for scenarios where you need to access JWT data even after
expiration.

Ported from: supabase/auth-js#1078

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* feat(gotrue): clarify getClaims fallback behavior for key rotation

Updates getClaims() documentation and comments to clarify that the
method always uses server-side verification via getUser(). This approach
gracefully handles edge cases such as:

- Key rotation scenarios where JWKS cache might not have the new signing key
- Symmetric JWTs (HS256) that require server-side verification
- Revoked or invalidated tokens that are still unexpired

This aligns the implementation intent with the auth-js behavior where
getClaims() falls back to getUser() when the signing key is not found
in JWKS or when client-side verification is not available.

The Flutter implementation uses this server-side verification approach
for all JWT types, providing robust and consistent validation regardless
of the signing algorithm.

Related: supabase/auth-js#1080

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* reimplement as claude did it wrong

* fix tests

* remove unused import

* fix(gotrue): preserve padding in base64url encoding when requested

Fixed the _base64ToBase64url method to preserve padding characters
when pad=true is specified. Previously, padding was always stripped
during conversion, causing encode(data, pad: true) to return unpadded
output.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* invert condition to check for signingKey only once

* fix: simplify base64url decoding

* update pointycastle to latest versions

* throw AuthInvalidJwtException error

* fix: bump dart_jsonwebtoken

* fix: use dart_jsonwebtoken for verifying jwt

# Conflicts:
#	packages/gotrue/pubspec.yaml

* downgrade dart_jsonwebtoken

* fix: support dart_jsonwebtoken up to 4.0.0

---------

Co-authored-by: Claude <[email protected]>

Author: grdsdev

packages/gotrue/lib/gotrue.dart

@@ -4,10 +4,12 @@ export 'src/constants.dart'
     hide Constants, GenerateLinkTypeExtended, AuthChangeEventExtended;
 export 'src/gotrue_admin_api.dart';
 export 'src/gotrue_client.dart';
+export 'src/helper.dart' show decodeJwt, validateExp;
 export 'src/types/auth_exception.dart';
 export 'src/types/auth_response.dart' hide ToSnakeCase;
 export 'src/types/auth_state.dart';
 export 'src/types/gotrue_async_storage.dart';
+export 'src/types/jwt.dart';
 export 'src/types/mfa.dart';
 export 'src/types/types.dart';
 export 'src/types/session.dart';

packages/gotrue/lib/src/base64url.dart

@@ -0,0 +1,14 @@
+import 'dart:convert';
+
+class Base64Url {
+  /// Decodes a base64url string to a UTF-8 string
+  static String decodeToString(String input) {
+    final normalized = base64Url.normalize(input);
+    return utf8.decode(base64Url.decode(normalized));
+  }
+
+  static List<int> decodeToBytes(String input) {
+    final normalized = base64Url.normalize(input);
+    return base64Url.decode(normalized);
+  }
+}

packages/gotrue/lib/src/constants.dart

@@ -24,6 +24,9 @@ class Constants {
 
   /// The name of the header that contains API version.
   static const apiVersionHeaderName = 'x-supabase-api-version';
+
+  /// The TTL for the JWKS cache.
+  static const jwksTtl = Duration(minutes: 10);
 }
 
 class ApiVersions {

packages/gotrue/lib/src/gotrue_client.dart

@@ -3,6 +3,7 @@ import 'dart:convert';
 import 'dart:math';
 
 import 'package:collection/collection.dart';
+import 'package:dart_jsonwebtoken/dart_jsonwebtoken.dart';
 import 'package:gotrue/gotrue.dart';
 import 'package:gotrue/src/constants.dart';
 import 'package:gotrue/src/fetch.dart';
@@ -58,6 +59,9 @@ class GoTrueClient {
   /// Completer to combine multiple simultaneous token refresh requests.
   Completer<AuthResponse>? _refreshTokenCompleter;
 
+  JWKSet? _jwks;
+  DateTime? _jwksCachedAt;
+
   final _onAuthStateChangeController = BehaviorSubject<AuthState>();
   final _onAuthStateChangeControllerSync =
       BehaviorSubject<AuthState>(sync: true);
@@ -1336,4 +1340,104 @@ class GoTrueClient {
     );
     return exception;
   }
+
+  Future<JWK?> _fetchJwk(String kid, JWKSet suppliedJwks) async {
+    // try fetching from the supplied jwks
+    final jwk = suppliedJwks.keys.firstWhereOrNull((jwk) => jwk.kid == kid);
+    if (jwk != null) {
+      return jwk;
+    }
+
+    final now = DateTime.now();
+
+    // try fetching from cache
+    final cachedJwk = _jwks?.keys.firstWhereOrNull((jwk) => jwk.kid == kid);
+
+    // jwks exists and it isn't stale
+    if (cachedJwk != null &&
+        _jwksCachedAt != null &&
+        _jwksCachedAt!.add(Constants.jwksTtl).isAfter(now)) {
+      return cachedJwk;
+    }
+
+    // jwk isn't cached in memory so we need to fetch it from the well-known endpoint
+    final jwksResponse = await _fetch.request(
+      '$_url/.well-known/jwks.json',
+      RequestMethodType.get,
+      options: GotrueRequestOptions(headers: _headers),
+    );
+
+    final jwks = JWKSet.fromJson(jwksResponse as Map<String, dynamic>);
+
+    if (jwks.keys.isEmpty) {
+      return null;
+    }
+
+    _jwks = jwks;
+    _jwksCachedAt = now;
+
+    // find the signing key
+    return jwks.keys.firstWhereOrNull((jwk) => jwk.kid == kid);
+  }
+
+  /// Extracts the JWT claims present in the access token by first verifying the
+  /// JWT against the server's JSON Web Key Set endpoint
+  /// `/.well-known/jwks.json` which is often cached, resulting in significantly
+  /// faster responses. Prefer this method over [getUser] which always
+  /// sends a request to the Auth server for each JWT.
+  ///
+  /// 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.
+  /// [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
+  ///           behavior of this method.
+  ///
+  /// Returns a [GetClaimsResponse] containing the JWT claims, or throws an [AuthException] on error.
+  Future<GetClaimsResponse> getClaims([
+    String? jwt,
+    GetClaimsOptions? options,
+  ]) async {
+    String token = jwt ?? '';
+
+    if (token.isEmpty) {
+      final session = currentSession;
+      if (session == null) {
+        throw AuthSessionMissingException('No session found');
+      }
+      token = session.accessToken;
+    }
+
+    // Decode the JWT to get the payload
+    final decoded = decodeJwt(token);
+
+    // Validate expiration unless allowExpired is true
+    if (!(options?.allowExpired ?? false)) {
+      validateExp(decoded.payload.exp);
+    }
+
+    final signingKey =
+        (decoded.header.alg.startsWith('HS') || decoded.header.kid == null)
+            ? null
+            : await _fetchJwk(decoded.header.kid!, _jwks!);
+
+    // If symmetric algorithm, fallback to getUser()
+    if (signingKey == null) {
+      await getUser(token);
+      return GetClaimsResponse(
+          claims: decoded.payload,
+          header: decoded.header,
+          signature: decoded.signature);
+    }
+
+    try {
+      JWT.verify(token, signingKey.rsaPublicKey);
+      return GetClaimsResponse(
+          claims: decoded.payload,
+          header: decoded.header,
+          signature: decoded.signature);
+    } catch (e) {
+      throw AuthInvalidJwtException('Invalid JWT signature: $e');
+    }
+  }
 }

packages/gotrue/lib/src/helper.dart

@@ -2,6 +2,9 @@ import 'dart:convert';
 import 'dart:math';
 
 import 'package:crypto/crypto.dart';
+import 'package:gotrue/src/base64url.dart';
+import 'package:gotrue/src/types/auth_exception.dart';
+import 'package:gotrue/src/types/jwt.dart';
 
 /// Converts base 10 int into String representation of base 16 int and takes the last two digets.
 String dec2hex(int dec) {
@@ -30,3 +33,60 @@ void validateUuid(String id) {
     throw ArgumentError('Invalid id: $id, must be a valid UUID');
   }
 }
+
+/// Decodes a JWT token without performing validation
+///
+/// Returns a [DecodedJwt] containing the header, payload, signature, and raw parts.
+/// Throws [AuthInvalidJwtException] if the JWT structure is invalid.
+DecodedJwt decodeJwt(String token) {
+  final parts = token.split('.');
+  if (parts.length != 3) {
+    throw AuthInvalidJwtException('Invalid JWT structure');
+  }
+
+  final rawHeader = parts[0];
+  final rawPayload = parts[1];
+  final rawSignature = parts[2];
+
+  try {
+    // Decode header
+    final headerJson = Base64Url.decodeToString(rawHeader);
+    final header = JwtHeader.fromJson(json.decode(headerJson));
+
+    // Decode payload
+    final payloadJson = Base64Url.decodeToString(rawPayload);
+    final payload = JwtPayload.fromJson(json.decode(payloadJson));
+
+    // Decode signature
+    final signature = Base64Url.decodeToBytes(rawSignature);
+
+    return DecodedJwt(
+      header: header,
+      payload: payload,
+      signature: signature,
+      raw: JwtRawParts(
+        header: rawHeader,
+        payload: rawPayload,
+        signature: rawSignature,
+      ),
+    );
+  } catch (e) {
+    if (e is AuthInvalidJwtException) {
+      rethrow;
+    }
+    throw AuthInvalidJwtException('Failed to decode JWT: $e');
+  }
+}
+
+/// Validates the expiration time of a JWT
+///
+/// Throws [AuthException] if the exp claim is missing or the JWT has expired.
+void validateExp(int? exp) {
+  if (exp == null) {
+    throw AuthException('Missing exp claim');
+  }
+  final timeNow = DateTime.now().millisecondsSinceEpoch / 1000;
+  if (exp <= timeNow) {
+    throw AuthException('JWT has expired');
+  }
+}

packages/gotrue/lib/src/types/auth_exception.dart

@@ -103,3 +103,15 @@ class AuthWeakPasswordException extends AuthException {
   String toString() =>
       'AuthWeakPasswordException(message: $message, statusCode: $statusCode, reasons: $reasons)';
 }
+
+class AuthInvalidJwtException extends AuthException {
+  AuthInvalidJwtException(super.message)
+      : super(
+          statusCode: '400',
+          code: 'invalid_jwt',
+        );
+
+  @override
+  String toString() =>
+      'AuthInvalidJwtException(message: $message, statusCode: $statusCode, code: $code)';
+}