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]>

Author: grdsdev

packages/gotrue/lib/gotrue.dart

@@ -8,6 +8,7 @@ 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,122 @@
+import 'dart:convert';
+import 'dart:typed_data';
+
+/// Base64URL encoding and decoding utilities for JWT operations.
+/// Extracted and adapted from RFC 4648 specification.
+class Base64Url {
+  static const String _chars =
+      'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+  static const int _bits = 6;
+
+  /// Decodes a base64url encoded string to bytes
+  ///
+  /// [input] The base64url encoded string to decode
+  /// [loose] If true, allows lenient parsing that doesn't strictly validate padding
+  static Uint8List decode(String input, {bool loose = false}) {
+    // Remove padding characters
+    String string = input.replaceAll('=', '');
+
+    // Build character lookup table
+    final Map<String, int> codes = {};
+    for (int i = 0; i < _chars.length; i++) {
+      codes[_chars[i]] = i;
+    }
+
+    // For loose mode or when there's actual content, skip strict validation
+    // The validation below will catch actual errors during decoding
+    if (!loose && string.isNotEmpty) {
+      final remainder = (string.length * _bits) % 8;
+      // Allow if remainder is 0 or if it's 2 or 4 (valid base64 partial bytes)
+      if (remainder != 0 && remainder != 2 && remainder != 4) {
+        throw FormatException('Invalid base64url string length');
+      }
+    }
+
+    // Calculate output size
+    final int outputLength = (string.length * _bits) ~/ 8;
+    final Uint8List out = Uint8List(outputLength);
+
+    // Decode the string
+    int bits = 0; // Number of bits currently in the buffer
+    int buffer = 0; // Bits waiting to be written out, MSB first
+    int written = 0; // Next byte to write
+
+    for (int i = 0; i < string.length; i++) {
+      final String char = string[i];
+      final int? value = codes[char];
+
+      if (value == null) {
+        throw FormatException('Invalid character in base64url string: $char');
+      }
+
+      // Append the bits to the buffer
+      buffer = (buffer << _bits) | value;
+      bits += _bits;
+
+      // Write out some bits if the buffer has a byte's worth
+      if (bits >= 8) {
+        bits -= 8;
+        out[written++] = 0xff & (buffer >> bits);
+      }
+    }
+
+    // Verify that we have received just enough bits
+    if (bits >= _bits || (0xff & (buffer << (8 - bits))) != 0) {
+      if (!loose) {
+        throw FormatException('Unexpected end of base64url data');
+      }
+    }
+
+    return out;
+  }
+
+  /// Encodes bytes to a base64url encoded string
+  ///
+  /// [data] The bytes to encode
+  /// [pad] If true, adds padding characters to the output
+  static String encode(List<int> data, {bool pad = false}) {
+    final int mask = (1 << _bits) - 1;
+    String out = '';
+
+    int bits = 0; // Number of bits currently in the buffer
+    int buffer = 0; // Bits waiting to be written out, MSB first
+
+    for (int i = 0; i < data.length; i++) {
+      // Slurp data into the buffer
+      buffer = (buffer << 8) | (0xff & data[i]);
+      bits += 8;
+
+      // Write out as much as we can
+      while (bits > _bits) {
+        bits -= _bits;
+        out += _chars[mask & (buffer >> bits)];
+      }
+    }
+
+    // Handle partial character
+    if (bits > 0) {
+      out += _chars[mask & (buffer << (_bits - bits))];
+    }
+
+    // Add padding characters until we hit a byte boundary
+    if (pad) {
+      while ((out.length * _bits) % 8 != 0) {
+        out += '=';
+      }
+    }
+
+    return out;
+  }
+
+  /// Decodes a base64url string to a UTF-8 string
+  static String decodeToString(String input, {bool loose = false}) {
+    final bytes = decode(input, loose: loose);
+    return utf8.decode(bytes);
+  }
+
+  /// Encodes a UTF-8 string to base64url
+  static String encodeFromString(String input, {bool pad = false}) {
+    final bytes = utf8.encode(input);
+    return encode(bytes, pad: pad);
+  }
+}

packages/gotrue/lib/src/gotrue_client.dart

@@ -1336,4 +1336,51 @@ class GoTrueClient {
     );
     return exception;
   }
+
+  /// Gets the claims from a JWT token.
+  ///
+  /// This method verifies the JWT by calling [getUser] to validate against the server.
+  /// It supports both symmetric (HS256) and asymmetric (RS256, ES256) JWTs.
+  ///
+  /// [jwt] The JWT token to get claims from. If not provided, uses the current session's access token.
+  ///
+  /// Returns a [GetClaimsResponse] containing the JWT claims, or throws an [AuthException] on error.
+  ///
+  /// Note: This is an experimental API and may change in future versions.
+  Future<GetClaimsResponse> getClaims([String? jwt]) async {
+    try {
+      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
+      validateExp(decoded.payload.exp);
+
+      // Verify the JWT by calling getUser
+      // This works for both symmetric and asymmetric JWTs
+      final userResponse = await getUser(token);
+      if (userResponse.user == null) {
+        throw AuthException('Failed to verify JWT');
+      }
+
+      // If getUser succeeds, the JWT is valid and we can trust the claims
+      return GetClaimsResponse(claims: decoded.payload.claims);
+    } on AuthException {
+      rethrow;
+    } catch (error) {
+      throw AuthUnknownException(
+        message: 'Unknown error occurred while getting claims',
+        originalError: error,
+      );
+    }
+  }
 }

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, loose: true);
+    final header = JwtHeader.fromJson(json.decode(headerJson));
+
+    // Decode payload
+    final payloadJson = Base64Url.decodeToString(rawPayload, loose: true);
+    final payload = JwtPayload.fromJson(json.decode(payloadJson));
+
+    // Decode signature
+    final signature = Base64Url.decode(rawSignature, loose: true);
+
+    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)';
+}