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

[grdsdev]

Summary

This PR ports the getClaims feature from auth-js#1030 and follow-up improvements from auth-js#1078 and auth-js#1080 to supabase-swift. The getClaims method allows developers to verify and extract claims from JWTs with significant performance improvements through global caching and graceful key rotation handling.

What changed

New Types

• JWK, JWKS: JSON Web Key and JSON Web Key Set types for asymmetric key verification
• JWTHeader, JWTClaims: Strongly-typed JWT header and claims structures
• JWTClaimsResponse: Response type containing verified claims, header, and signature
• AudienceClaim: Enum to handle audience claim as either string or array
• GetClaimsOptions: Options struct with allowExpired and custom jwks parameters
• CachedJWKS: Internal struct tracking JWKS with timestamp
• GlobalJWKSCache: Actor for thread-safe global JWKS caching

New Files

• Base64URL.swift: Base64URL encoding/decoding utilities
• JWTVerifier.swift: JWT signature verification using Apple Security
• DecodedJWT: Extended JWT helper to decode complete JWT structure

Modified Files

• AuthClient.swift:
  • Added getClaims(jwt:options:) method for JWT verification
  • Added global JWKS caching with TTL (10 minutes)
  • Added fetchJWK(kid:jwks:) private method with cache expiry checking
  • Implemented graceful fallback when JWK not found (key rotation support)
• AuthError.swift: Added jwtVerificationFailed error case
• Types.swift: Added all new JWT-related types and GetClaimsOptions
• JWT.swift: Added decode(_:) method to return full JWT structure

How it works

The getClaims method provides flexible JWT verification with performance optimizations:

1. Symmetric JWTs (HS256): Verified server-side via getUser() API call
2. Asymmetric JWTs (RS256): Verified client-side via using Apple Security
3. Global JWKS Cache: Shared across all clients with the same storage key, especially beneficial for serverless environments
4. Graceful Key Rotation: Automatically falls back to server-side verification when JWK not found in cache

Usage Example

// Verify current session's JWT
let response = try await client.auth.getClaims()
print("User ID: \(response.claims.sub ?? "N/A")")
print("Email: \(response.claims.email ?? "N/A")")
print("Role: \(response.claims.role ?? "N/A")")

// Verify specific JWT
let customToken = "eyJhbGci..."
let response = try await client.auth.getClaims(jwt: customToken)

// Allow expired JWTs (useful for testing)
let response = try await client.auth.getClaims(
  options: GetClaimsOptions(allowExpired: true)
)

// Use custom JWKS
let customJWKS = JWKS(keys: [...])
let response = try await client.auth.getClaims(
  options: GetClaimsOptions(jwks: customJWKS)
)

Related

• Source PR: feat: introduce getClaims method to verify asymmetric JWTs auth-js#1030
• Follow-up PR (global cache): feat: make getClaims() non experimental, add global cache auth-js#1078
• Follow-up PR (key rotation): feat: fallback to getUser() if the kid of the JWT is not found auth-js#1080

🤖 Generated with Claude Code

[coveralls]

Pull Request Test Coverage Report for Build 18316862621

Details

• 193 of 331 (58.31%) changed or added relevant lines in 7 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage decreased (-0.8%) to 77.283%

---

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
Sources/Helpers/JWT.swift	25	26	96.15%
Sources/Helpers/Base64URL.swift	12	18	66.67%
Sources/Auth/Internal/JWTAlgorithm.swift	0	13	0.0%
Sources/Auth/AuthClient.swift	104	127	81.89%
Sources/Auth/Types.swift	49	95	51.58%
Sources/Auth/Internal/JWK+RSA.swift	0	49	0.0%

Totals
Change from base Build 18289195894:	-0.8%
Covered Lines:	5872
Relevant Lines:	7598

---

💛 - Coveralls