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

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

* feat(auth): make getClaims non-experimental, add global JWKS cache

This commit applies changes from auth-js PR #1078 to improve getClaims
performance and remove its experimental status.

Key changes:
- Add global JWKS cache shared across all clients with the same storage key
- Implement JWKS cache expiry with TTL (10 minutes)
- Add GetClaimsOptions struct with allowExpired and custom jwks options
- Remove experimental warning from getClaims documentation
- Update getClaims to accept options parameter instead of separate jwks param
- Add CachedJWKS struct to track cache timestamps
- Implement GlobalJWKSCache actor for thread-safe global caching

Performance improvements:
- Global cache significantly reduces JWKS fetches in serverless environments
- Cache TTL prevents stale keys while minimizing network requests
- Especially beneficial for AWS Lambda, Cloud Functions, etc.

Breaking change:
- getClaims now accepts GetClaimsOptions instead of JWKS parameter
- Old: getClaims(jwt:jwks:)
- New: getClaims(jwt:options:)

Migration:
```swift
// Before
let response = try await client.auth.getClaims(jwks: customJWKS)

// After
let response = try await client.auth.getClaims(
  options: GetClaimsOptions(jwks: customJWKS)
)

// With allowExpired
let response = try await client.auth.getClaims(
  options: GetClaimsOptions(allowExpired: true)
)
```

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

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

* feat(auth): add graceful fallback for JWK not found in JWKS

This commit applies changes from auth-js PR #1080 to handle key rotation
scenarios more gracefully.

Key changes:
- Change fetchJWK to return optional JWK? instead of throwing errors
- Return nil when JWKS is empty or key not found in JWKS
- Restructure getClaims logic to try fetching JWK first
- Fallback to server-side verification (getUser) if key not found
- Handle symmetric algorithms (HS256) and RS256 with nil check

Why this matters:
When developers rotate keys faster than cache TTL (10 minutes), a JWT
may be signed with a key ID that's not yet in the cached JWKS. Instead
of failing with an error, the method now gracefully falls back to
server-side verification via getUser().

This ensures:
- Zero downtime during key rotation
- Better resilience against cache staleness
- Transparent fallback for users

Example scenario:
1. JWKS is cached with key ID "abc123"
2. Admin rotates standby key to active (new key ID "xyz789")
3. User receives JWT signed with "xyz789"
4. fetchJWK returns nil (key not in cache)
5. getClaims automatically falls back to getUser()
6. Verification succeeds server-side

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

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

* fix jwt verify

* test: add tests for getClaims method

* fallback to getUser if Security isn't available

* fix encoding implementation of JWTClaims type

---------

Co-authored-by: Claude <[email protected]>

Author: grdsdev

Sources/Auth/AuthClient.swift

@@ -30,6 +30,34 @@ struct AuthClientLoggerDecorator: SupabaseLogger {
   }
 }
 
+/// JWKS cache TTL (Time To Live) - 10 minutes
+private let JWKS_TTL: TimeInterval = 10 * 60
+
+/// Cached JWKS value with timestamp
+private struct CachedJWKS {
+  let jwks: JWKS
+  let cachedAt: Date
+}
+
+/// Global JWKS cache shared across all clients with the same storage key.
+/// This is especially useful for shared-memory execution environments such as
+/// AWS Lambda or serverless functions. Regardless of how many clients are created,
+/// if they share the same storage key they will use the same JWKS cache,
+/// significantly speeding up getClaims() with asymmetric JWTs.
+private actor GlobalJWKSCache {
+  private var cache: [String: CachedJWKS] = [:]
+
+  func get(for key: String) -> CachedJWKS? {
+    cache[key]
+  }
+
+  func set(_ value: CachedJWKS, for key: String) {
+    cache[key] = value
+  }
+}
+
+private let globalJWKSCache = GlobalJWKSCache()
+
 public actor AuthClient {
   static var globalClientID = 0
   nonisolated let clientID: AuthClientID
@@ -1448,6 +1476,150 @@ public actor AuthClient {
 
     return url
   }
+
+  /// Fetches a JWK from the JWKS endpoint with caching
+  /// Returns nil if the key is not found, allowing graceful fallback to server-side verification
+  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
+    }
+
+    let now = date()
+    let storageKey = configuration.storageKey ?? defaultStorageKey
+
+    // Try fetching from global cache
+    if let cached = await globalJWKSCache.get(for: storageKey),
+      let jwk = cached.jwks.keys.first(where: { $0.kid == kid })
+    {
+      // Check if cache is still valid (not stale)
+      if cached.cachedAt.addingTimeInterval(JWKS_TTL) > now {
+        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)
+
+    // Return nil if JWKS is empty (will fallback to getUser)
+    guard !fetchedJWKS.keys.isEmpty else {
+      return nil
+    }
+
+    // Cache the JWKS globally
+    await globalJWKSCache.set(
+      CachedJWKS(jwks: fetchedJWKS, cachedAt: now),
+      for: storageKey
+    )
+
+    // Find the signing key - return nil if not found (will fallback to getUser)
+    // This handles key rotation scenarios where the JWT is signed with a key not yet in the cache
+    return fetchedJWKS.keys.first(where: { $0.kid == kid })
+  }
+
+  /// Extracts the JWT claims present in the access token by first verifying the
+  /// JWT against the server's JSON Web Key Set endpoint `/.well-known/jwks.json`
+  /// which is often cached, resulting in significantly faster responses. Prefer
+  /// this method over ``user(jwt:)`` which always sends a request to the Auth
+  /// server for each JWT.
+  ///
+  /// If the project is not using an asymmetric JWT signing key (like ECC or RSA)
+  /// it always sends a request to the Auth server (similar to ``user(jwt:)``) to
+  /// verify the JWT.
+  ///
+  /// - Parameters:
+  ///   - jwt: An optional specific JWT you wish to verify, not the one you can obtain from ``session``.
+  ///   - options: Various additional options that allow you to customize the behavior of this method.
+  ///
+  /// - Returns: A `JWTClaimsResponse` containing the verified claims, header, and signature.
+  ///
+  /// - Throws: `AuthError.jwtVerificationFailed` if verification fails, or `AuthError.sessionMissing` if no session exists.
+  public func getClaims(
+    jwt: String? = nil,
+    options: GetClaimsOptions = GetClaimsOptions()
+  ) 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 unless allowExpired is true
+    if !options.allowExpired {
+      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
+
+    // Try to fetch the signing key for asymmetric JWTs
+    // Returns nil if: no alg, symmetric algorithm (HS256/HS512), no kid, or key not found in JWKS
+    let signingKey: JWK?
+    if let alg, !alg.hasPrefix("HS"), let kid {
+      // Only attempt to fetch JWK for asymmetric algorithms with a kid
+      signingKey = try await fetchJWK(kid: kid, jwks: options.jwks)
+    } else {
+      signingKey = nil
+    }
+
+    // If no signing key available (symmetric algorithm, RS256, no kid, or key not found),
+    // fallback to server-side verification via getUser()
+    guard
+      let signingKey,
+      let alg = signingKey.alg,
+      let algorithm = JWTAlgorithm(rawValue: alg)
+    else {
+      _ = 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)
+    }
+
+    let isValid = algorithm.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/Internal/JWK+RSA.swift

@@ -0,0 +1,72 @@
+//
+//  JWK+RSA.swift
+//  Supabase
+//
+//  Created by Guilherme Souza on 07/10/25.
+//
+
+import Foundation
+
+#if canImport(Security)
+
+  extension JWK {
+    var rsaPublishKey: SecKey? {
+      guard kty == "RSA",
+        alg == "RS256",
+        let n,
+        let modulus = Base64URL.decode(n),
+        let e,
+        let exponent = Base64URL.decode(e)
+      else {
+        return nil
+      }
+
+      let encodedKey = encodeRSAPublishKey(modulus: [UInt8](modulus), exponent: [UInt8](exponent))
+      return generateRSAPublicKey(from: encodedKey)
+    }
+  }
+
+  extension JWK {
+    fileprivate func encodeRSAPublishKey(modulus: [UInt8], exponent: [UInt8]) -> Data {
+      var prefixedModulus: [UInt8] = [0x00]  // To indicate that the number is not negative
+      prefixedModulus.append(contentsOf: modulus)
+      let encodedModulus = prefixedModulus.derEncode(as: 2)  // Integer
+      let encodedExponent = exponent.derEncode(as: 2)  // Integer
+      let encodedSequence = (encodedModulus + encodedExponent).derEncode(as: 48)  // Sequence
+      return Data(encodedSequence)
+    }
+
+    fileprivate func generateRSAPublicKey(from derEncodedData: Data) -> SecKey? {
+      let sizeInBits = derEncodedData.count * MemoryLayout<UInt8>.size
+      let attributes: [CFString: Any] = [
+        kSecAttrKeyType: kSecAttrKeyTypeRSA,
+        kSecAttrKeyClass: kSecAttrKeyClassPublic,
+        kSecAttrKeySizeInBits: NSNumber(value: sizeInBits),
+        kSecAttrIsPermanent: false,
+      ]
+      return SecKeyCreateWithData(derEncodedData as CFData, attributes as CFDictionary, nil)
+    }
+  }
+
+  extension [UInt8] {
+    fileprivate func derEncode(as dataType: UInt8) -> [UInt8] {
+      var encodedBytes: [UInt8] = [dataType]
+      var numberOfBytes = count
+      if numberOfBytes < 128 {
+        encodedBytes.append(UInt8(numberOfBytes))
+      } else {
+        let lengthData = Data(
+          bytes: &numberOfBytes,
+          count: MemoryLayout.size(ofValue: numberOfBytes)
+        )
+        let lengthBytes = [UInt8](lengthData).filter({ $0 != 0 }).reversed()
+        encodedBytes.append(UInt8(truncatingIfNeeded: lengthBytes.count) | 0b10000000)
+        encodedBytes.append(contentsOf: lengthBytes)
+      }
+      encodedBytes.append(contentsOf: self)
+      return encodedBytes
+    }
+
+  }
+
+#endif

Sources/Auth/Internal/JWTAlgorithm.swift

@@ -0,0 +1,33 @@
+//
+//  JWTVerifier.swift
+//  Supabase
+//
+//  Created by Claude on 06/10/25.
+//
+
+import Foundation
+
+enum JWTAlgorithm: String {
+  case rs256 = "RS256"
+
+  func verify(
+    jwt: DecodedJWT,
+    jwk: JWK
+  ) -> Bool {
+    let message = "\(jwt.raw.header).\(jwt.raw.payload)".data(using: .utf8)!
+    switch self {
+    case .rs256:
+      #if canImport(Security)
+        return SecKeyVerifySignature(
+          jwk.rsaPublishKey!,
+          .rsaSignatureMessagePKCS1v15SHA256,
+          message as CFData,
+          jwt.signature as CFData,
+          nil
+        )
+      #else
+        return false
+      #endif
+    }
+  }
+}