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

This commit adds JWT claims verification and extraction functionality
to the Auth client, porting the feature from auth-js PR #1030.

Key changes:
- Add Base64URL encoding/decoding utilities
- Extend JWT helper to decode full JWT (header, payload, signature)
- Add JWK types (JWK, JWKS, JWTHeader, JWTClaims, etc.)
- Add JWTVerifier for asymmetric JWT signature verification (ES256)
- Implement getClaims method in AuthClient
- Add jwtVerificationFailed error to AuthError

The getClaims method verifies JWT signatures and returns claims:
- For HS256 (symmetric) and RS256 JWTs: validates server-side via getUser
- For ES256 JWTs: verifies signature client-side using CryptoKit
- Supports custom JWKS or fetches from /.well-known/jwks.json
- Caches JWKS to minimize network requests

Note: RS256 client-side verification will be added once swift-crypto's
RSA API becomes public. Currently falls back to server-side verification.

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

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

Author: grdsdev

Sources/Auth/AuthClient.swift

@@ -53,6 +53,9 @@ public actor AuthClient {
   nonisolated private var sessionStorage: SessionStorage { Dependencies[clientID].sessionStorage }
   nonisolated private var pkce: PKCE { Dependencies[clientID].pkce }
 
+  /// Cache for JWKS (JSON Web Key Set)
+  private var jwksCache: JWKS?
+
   /// Returns the session, refreshing it if necessary.
   ///
   /// If no session can be found, a ``AuthError/sessionMissing`` error is thrown.
@@ -1448,6 +1451,114 @@ public actor AuthClient {
 
     return url
   }
+
+  /// Fetches a JWK from the JWKS endpoint
+  private func fetchJWK(kid: String, jwks: JWKS? = nil) async throws -> JWK {
+    // Try fetching from the supplied jwks
+    if let jwk = jwks?.keys.first(where: { $0.kid == kid }) {
+      return jwk
+    }
+
+    // Try fetching from cache
+    if let jwk = jwksCache?.keys.first(where: { $0.kid == kid }) {
+      return jwk
+    }
+
+    // Fetch from well-known endpoint
+    let response = try await api.execute(
+      HTTPRequest(
+        url: configuration.url.appendingPathComponent(".well-known/jwks.json"),
+        method: .get
+      )
+    )
+
+    let fetchedJWKS = try response.decoded(as: JWKS.self, decoder: configuration.decoder)
+
+    guard !fetchedJWKS.keys.isEmpty else {
+      throw AuthError.jwtVerificationFailed(message: "JWKS is empty")
+    }
+
+    // Cache the JWKS
+    jwksCache = fetchedJWKS
+
+    // Find the signing key
+    guard let jwk = fetchedJWKS.keys.first(where: { $0.kid == kid }) else {
+      throw AuthError.jwtVerificationFailed(message: "No matching signing key found in JWKS")
+    }
+
+    return jwk
+  }
+
+  /// Verifies and extracts claims from a JWT.
+  ///
+  /// This method verifies the JWT signature and returns the claims if valid. For symmetric JWTs (HS256),
+  /// it validates against the server using the `getUser` method. For asymmetric JWTs (RS256, ES256),
+  /// it verifies the signature using the JWKS (JSON Web Key Set) from the well-known endpoint.
+  ///
+  /// - Parameters:
+  ///   - jwt: The JWT to verify. If nil, uses the access token from the current session.
+  ///   - jwks: Optional JWKS to use for verification. If nil, fetches from the server.
+  ///
+  /// - Returns: A `JWTClaimsResponse` containing the verified claims, header, and signature.
+  ///
+  /// - Throws: `AuthError.jwtVerificationFailed` if verification fails, or `AuthError.sessionMissing` if no session exists.
+  ///
+  /// - Note: This is an experimental method and may change in future versions.
+  public func getClaims(jwt: String? = nil, jwks: JWKS? = nil) async throws -> JWTClaimsResponse {
+    let token: String
+    if let jwt {
+      token = jwt
+    } else {
+      guard let session = try? await session else {
+        throw AuthError.sessionMissing
+      }
+      token = session.accessToken
+    }
+
+    guard let decodedJWT = JWT.decode(token) else {
+      throw AuthError.jwtVerificationFailed(message: "Invalid JWT structure")
+    }
+
+    // Validate expiration
+    if let exp = decodedJWT.payload["exp"] as? TimeInterval {
+      let now = Date().timeIntervalSince1970
+      if exp <= now {
+        throw AuthError.jwtVerificationFailed(message: "JWT has expired")
+      }
+    }
+
+    let alg = decodedJWT.header["alg"] as? String
+    let kid = decodedJWT.header["kid"] as? String
+
+    // If symmetric algorithm (HS256), RS256 (not yet fully supported), or no kid, fallback to getUser()
+    // RS256 will be fully supported client-side once swift-crypto's RSA API is public
+    if alg == "HS256" || alg == "RS256" || kid == nil {
+      _ = try await user(jwt: token)
+      // getUser succeeds, so claims can be trusted
+      let claims = try configuration.decoder.decode(JWTClaims.self, from: JSONSerialization.data(withJSONObject: decodedJWT.payload))
+      let header = try configuration.decoder.decode(JWTHeader.self, from: JSONSerialization.data(withJSONObject: decodedJWT.header))
+      return JWTClaimsResponse(claims: claims, header: header, signature: decodedJWT.signature)
+    }
+
+    // Asymmetric JWT verification using CryptoKit (currently only ES256)
+    guard let kid else {
+      throw AuthError.jwtVerificationFailed(message: "Missing kid in JWT header")
+    }
+
+    let signingKey = try await fetchJWK(kid: kid, jwks: jwks)
+
+    let isValid = try JWTVerifier.verify(jwt: decodedJWT, jwk: signingKey)
+
+    guard isValid else {
+      throw AuthError.jwtVerificationFailed(message: "Invalid JWT signature")
+    }
+
+    // Decode claims and header
+    let claims = try configuration.decoder.decode(JWTClaims.self, from: JSONSerialization.data(withJSONObject: decodedJWT.payload))
+    let header = try configuration.decoder.decode(JWTHeader.self, from: JSONSerialization.data(withJSONObject: decodedJWT.header))
+
+    return JWTClaimsResponse(claims: claims, header: header, signature: decodedJWT.signature)
+  }
 }
 
 extension AuthClient {

Sources/Auth/AuthError.swift

@@ -114,6 +114,7 @@ extension ErrorCode {
   //#nosec G101 -- Not a secret value.
   public static let invalidCredentials = ErrorCode("invalid_credentials")
   public static let emailAddressNotAuthorized = ErrorCode("email_address_not_authorized")
+  public static let invalidJWT = ErrorCode("invalid_jwt")
 }
 
 public enum AuthError: LocalizedError, Equatable {
@@ -261,13 +262,17 @@ public enum AuthError: LocalizedError, Equatable {
   /// Error thrown when an error happens during implicit grant flow.
   case implicitGrantRedirect(message: String)
 
+  /// Error thrown when JWT verification fails.
+  case jwtVerificationFailed(message: String)
+
   public var message: String {
     switch self {
     case .sessionMissing: "Auth session missing."
     case let .weakPassword(message, _),
       let .api(message, _, _, _),
       let .pkceGrantCodeExchange(message, _, _),
-      let .implicitGrantRedirect(message):
+      let .implicitGrantRedirect(message),
+      let .jwtVerificationFailed(message):
       message
     // Deprecated cases
     case .missingExpClaim: "Missing expiration claim in the access token."
@@ -283,6 +288,7 @@ public enum AuthError: LocalizedError, Equatable {
     case .weakPassword: .weakPassword
     case let .api(_, errorCode, _, _): errorCode
     case .pkceGrantCodeExchange, .implicitGrantRedirect: .unknown
+    case .jwtVerificationFailed: .invalidJWT
     // Deprecated cases
     case .missingExpClaim, .malformedJWT, .invalidRedirectScheme, .missingURL: .unknown
     }

Sources/Auth/JWTVerifier.swift

@@ -0,0 +1,70 @@
+//
+//  JWTVerifier.swift
+//  Supabase
+//
+//  Created by Claude on 06/10/25.
+//
+
+import CryptoKit
+import Foundation
+
+enum JWTVerifier {
+  /// Verifies an asymmetric JWT signature using CryptoKit
+  static func verify(
+    jwt: DecodedJWT,
+    jwk: JWK
+  ) throws -> Bool {
+    guard let alg = jwt.header["alg"] as? String else {
+      throw AuthError.jwtVerificationFailed(message: "Missing alg in JWT header")
+    }
+
+    let message = "\(jwt.raw.header).\(jwt.raw.payload)".data(using: .utf8)!
+
+    switch alg {
+    case "RS256":
+      // RS256 (RSA) verification requires swift-crypto's _RSA which is not yet public API
+      // For now, we fall back to server-side verification via getUser()
+      throw AuthError.jwtVerificationFailed(
+        message: "RS256 JWTs are currently verified server-side via getUser()"
+      )
+    case "ES256":
+      return try verifyES256(message: message, signature: jwt.signature, jwk: jwk)
+    case "HS256":
+      // Symmetric keys should be verified server-side via getUser
+      throw AuthError.jwtVerificationFailed(
+        message: "HS256 JWTs must be verified server-side"
+      )
+    default:
+      throw AuthError.jwtVerificationFailed(message: "Unsupported algorithm: \(alg)")
+    }
+  }
+
+  private static func verifyES256(message: Data, signature: Data, jwk: JWK) throws -> Bool {
+    guard
+      let xString = jwk.x,
+      let yString = jwk.y,
+      let xData = Base64URL.decode(xString),
+      let yData = Base64URL.decode(yString)
+    else {
+      throw AuthError.jwtVerificationFailed(message: "Invalid EC JWK")
+    }
+
+    // For P256, we need to construct the X9.63 representation
+    // X9.63 format: 0x04 + x + y for uncompressed point
+    var x963Data = Data([0x04])
+    x963Data.append(xData)
+    x963Data.append(yData)
+
+    // Create EC public key from JWK
+    let publicKey = try P256.Signing.PublicKey(
+      x963Representation: x963Data
+    )
+
+    let isValid = publicKey.isValidSignature(
+      try P256.Signing.ECDSASignature(rawRepresentation: signature),
+      for: SHA256.hash(data: message)
+    )
+
+    return isValid
+  }
+}