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

grdsdev · 2025-10-06T20:37:53Z

Summary

This PR ports the getClaims method from supabase/auth-js#1030 to the Flutter client. The method supports verifying JWTs (both symmetric and asymmetric) and returns the entire set of claims in the JWT payload.

Close #1117

Changes

✨ New getClaims() method in GoTrueClient for JWT verification and claims extraction
📦 Base64URL utilities (RFC 4648 compliant) for encoding/decoding JWT parts
🔒 JWT types: JwtHeader, JwtPayload, DecodedJwt, GetClaimsResponse
🛠️ Helper functions: decodeJwt() and validateExp()
🚨 New exception: AuthInvalidJwtException for JWT-related errors
✅ Comprehensive tests for getClaims, JWT helpers, and base64url utilities

Implementation Details

The method handles different JWT signature algorithms:

HS256 (symmetric): Verified server-side via getUser() call - we cannot verify HMAC signatures client-side without the secret key
RS256/ES256 (asymmetric): Verified client-side using public key from JWKS endpoint

Usage Example

// Get claims from current session
final response = await client.getClaims();
print(response.claims['sub']); // User ID
print(response.claims['email']); // User email
print(response.claims['role']); // User role

// Get claims from explicit JWT
final response = await client.getClaims(jwt: accessToken);

// Allow expired tokens (useful for inspecting claims without validation)
final response = await client.getClaims(
  jwt: expiredToken,
  options: GetClaimsOptions(allowExpired: true),
);

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

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

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

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

coveralls · 2025-10-07T09:45:49Z

Pull Request Test Coverage Report for Build 18412233238

Warning: This coverage report may be inaccurate.

This pull request's base commit is no longer the HEAD commit of its target branch. This means it includes changes from outside the original pull request, including, potentially, unrelated coverage changes.

For more information on this, see Tracking coverage changes with pull request builds.
To avoid this issue with future PRs, see these Recommended CI Configurations.
For a quick fix, rebase this PR at GitHub. Your next report should be accurate.

Details

64 of 144 (44.44%) changed or added relevant lines in 5 files are covered.
No unchanged relevant lines lost coverage.
Overall coverage decreased (-1.3%) to 79.619%

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
packages/gotrue/lib/src/types/auth_exception.dart	2	4	50.0%
packages/gotrue/lib/src/gotrue_client.dart	14	41	34.15%
packages/gotrue/lib/src/types/jwt.dart	21	72	29.17%

Totals
Change from base Build 18289898404:	-1.3%
Covered Lines:	3301
Relevant Lines:	4146

💛 - Coveralls

Vinzent03 · 2025-10-10T14:55:25Z

packages/gotrue/lib/src/gotrue_client.dart

+    }
+
+    final signingKey =
+        (decoded.header.kid == null || decoded.header.alg.startsWith('HS'))


This case here can't be the case here anymore, right? If the token is symmetric getUser() would already have been called and returned.

Yeah, this check doesn't make sense, it always evaluate to false.

I've change the condition to better align with JS implementation, so it only calls getUser once.

Vinzent03 · 2025-10-10T14:56:42Z

packages/gotrue/lib/src/gotrue_client.dart

+    _jwksCachedAt = now;
+
+    // find the signing key
+    return jwks.keys.firstWhereOrNull((jwk) => jwk.kid == kid);


The js sdk throws an exception if no jwk could have been found, and I think we should do the same, because a missing public key with an asymmetric token is not solvable, right?

Where it throwing? I'm following this implementation https://github.com/supabase/supabase-js/blob/master/packages/core/auth-js/src/GoTrueClient.ts#L3380

packages/gotrue/lib/src/base64url.dart

grdsdev marked this pull request as draft October 6, 2025 20:38

grdsdev added the enhancement New feature or request label Oct 6, 2025

grdsdev and others added 5 commits October 6, 2025 17:50

reimplement as claude did it wrong

9d0f978

fix tests

47310ff

remove unused import

7e144e1

grdsdev requested review from Vinzent03 and dshukertjr and removed request for Vinzent03 October 7, 2025 09:40

grdsdev marked this pull request as ready for review October 7, 2025 09:40

Vinzent03 requested changes Oct 10, 2025

View reviewed changes

grdsdev added 2 commits October 10, 2025 13:11

invert condition to check for signingKey only once

77b89b8

fix: simplify base64url decoding

31a69c8

grdsdev requested a review from Vinzent03 October 10, 2025 16:19

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

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

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

grdsdev commented Oct 6, 2025 •

edited

Loading

Uh oh!

coveralls commented Oct 7, 2025 •

edited

Loading

Uh oh!

Vinzent03 Oct 10, 2025

Uh oh!

grdsdev Oct 10, 2025

Uh oh!

Vinzent03 Oct 10, 2025

Uh oh!

grdsdev Oct 10, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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

Are you sure you want to change the base?

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

Conversation

grdsdev commented Oct 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Implementation Details

Usage Example

Related

Uh oh!

coveralls commented Oct 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Test Coverage Report for Build 18412233238

Warning: This coverage report may be inaccurate.

Details

💛 - Coveralls

Uh oh!

Vinzent03 Oct 10, 2025

Choose a reason for hiding this comment

Uh oh!

grdsdev Oct 10, 2025

Choose a reason for hiding this comment

Uh oh!

Vinzent03 Oct 10, 2025

Choose a reason for hiding this comment

Uh oh!

grdsdev Oct 10, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

grdsdev commented Oct 6, 2025 •

edited

Loading

coveralls commented Oct 7, 2025 •

edited

Loading