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),
);

Pull Request Test Coverage Report for Build 18494104211

Details

64 of 141 (45.39%) changed or added relevant lines in 5 files are covered.
No unchanged relevant lines lost coverage.
Overall coverage decreased (-1.2%) to 79.677%

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	35	40.0%
packages/gotrue/lib/src/types/jwt.dart	21	75	28.0%

Totals
Change from base Build 18341715674:	-1.2%
Covered Lines:	3301
Relevant Lines:	4143

💛 - Coveralls

packages/gotrue/lib/src/gotrue_client.dart

packages/gotrue/lib/src/base64url.dart

packages/gotrue/lib/src/gotrue_client.dart

packages/gotrue/pubspec.yaml

packages/gotrue/lib/src/gotrue_client.dart

Vinzent03 · 2025-10-13T23:23:48Z

Okay seems like pointycastle v4.0 needs Dart 3.4.0, but we only support Dart 3.3.0. Great...
I think it should be possible to allow a range of 3< v <4 for pointycastle.
But now that I saw the version bump for dart_jsonwebtoken, can't we simply use that for the verifying? https://pub.dev/packages/dart_jsonwebtoken#check-if-the-jwt-made-is-correct
In the latest version, dart_jsonwebtoken uses pointycastle under the hood either way.

grdsdev · 2025-10-14T09:53:37Z

Yes @Vinzent03 I think we can use dart_jsonwebtoken directly, let me try that.

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

# Conflicts: # packages/gotrue/pubspec.yaml

Vinzent03 · 2025-10-14T23:50:17Z

packages/gotrue/pubspec.yaml

  logging: ^1.2.0
-  web: '>=0.5.0 <2.0.0'
+  web: ">=0.5.0 <2.0.0"
+  dart_jsonwebtoken: ^2.17.0


Suggested change

dart_jsonwebtoken: ^2.17.0

dart_jsonwebtoken: ">=2.17.0 <4.0.0"

I know these versions conflicts are really tedious, be I think we should support if possible the latest version. This constraint should use 3.0.0 for people with at least Dart 3.4.0 and fallback to 2.17.0 for people below that.

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

packages/gotrue/lib/src/gotrue_client.dart Outdated Show resolved Hide resolved

packages/gotrue/lib/src/gotrue_client.dart Show resolved Hide resolved

packages/gotrue/lib/src/base64url.dart Outdated Show resolved Hide resolved

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

Vinzent03 requested changes Oct 13, 2025

View reviewed changes

packages/gotrue/lib/src/gotrue_client.dart Outdated Show resolved Hide resolved

packages/gotrue/pubspec.yaml Outdated Show resolved Hide resolved

packages/gotrue/lib/src/gotrue_client.dart Show resolved Hide resolved

grdsdev requested a review from Vinzent03 October 13, 2025 15:34

grdsdev and others added 13 commits October 14, 2025 07:35

reimplement as claude did it wrong

0d90c22

fix tests

ba4d47d

remove unused import

4c6fd96

invert condition to check for signingKey only once

7f3f070

fix: simplify base64url decoding

cf5bb83

update pointycastle to latest versions

5cb3398

throw AuthInvalidJwtException error

b68f297

fix: bump dart_jsonwebtoken

b5e84c1

fix: use dart_jsonwebtoken for verifying jwt

4875df0

# Conflicts: # packages/gotrue/pubspec.yaml

grdsdev force-pushed the feat/gotrue-get-claims branch from 0f1a053 to 4875df0 Compare October 14, 2025 10:35

downgrade dart_jsonwebtoken

dec4598

Vinzent03 reviewed Oct 14, 2025

View reviewed changes

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

Uh oh!

grdsdev commented Oct 6, 2025 •

edited

Loading

Uh oh!

coveralls commented Oct 7, 2025 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Vinzent03 commented Oct 13, 2025

Uh oh!

grdsdev commented Oct 14, 2025

Uh oh!

Vinzent03 Oct 14, 2025 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	dart_jsonwebtoken: ^2.17.0
	dart_jsonwebtoken: ">=2.17.0 <4.0.0"

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

Uh oh!

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 18494104211

Details

💛 - Coveralls

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Vinzent03 commented Oct 13, 2025

Uh oh!

grdsdev commented Oct 14, 2025

Uh oh!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

grdsdev commented Oct 6, 2025 •

edited

Loading

coveralls commented Oct 7, 2025 •

edited

Loading

Vinzent03 Oct 14, 2025 •

edited

Loading