Repository navigation
Refactor: Consolidate JWKS fetching and expose a unified JWT verifier for downstream SDKs #299
Description
Background
Across firebase_admin_sdk and downstream consumers like firebase_functions (which depends on firebase_admin_sdk), there are multiple overlapping implementations of JWT signature verification, JWKS / X.509 certificate fetching, and public key caching.
Currently, firebase_admin_sdk maintains both UrlKeyFetcher (for X.509 PEM certs) and JwksFetcher (for JSON Web Key Sets) in lib/src/utils/jwt.dart.
Current Inconsistencies & Duplication
- Inconsistent Key Caching & TTLs:
UrlKeyFetcherparses HTTPCache-Control: max-ageheaders via string splitting and tracks expiration viaDateTime.JwksFetcherignores HTTPCache-Controlheaders entirely, hardcoding a static 6-hour TTL (6 * 60 * 60 * 1000) and tracking expiration via epoch integer comparison.- Meanwhile, downstream in
firebase_functions,AuthBlockingTokenVerifierhand-rolled a third key fetcher (_getGoogleKeys()) that parsesCache-Control: max-agevia regex and defaults to a 1-hour TTL.
- Inconsistent Clock Skew and Claim Validation:
- Neither
FirebaseTokenVerifiernorAppCheckTokenVerifiersupports clock-skew tolerance on timestamps (iat,exp). However, Auth Blocking events infirebase_functionsrequire a 5-minute clock skew oniat. - Audience (
aud) claim handling varies: ID token verification assumesString, App Check assumesList, and downstream functions must handle bothStringandListpolymorphically.
- Neither
- Lack of Reusability for Downstream Packages:
- Because
PublicKeySignatureVerifierandJwksFetcherare either marked@internalor lack configuration ergonomics (v3 JWKS endpoints, clock skew, polymorphic audience matching),firebase_functionswas forced to duplicate the entire JWT verification stack from scratch.
- Because
Proposed Action Items
- Unify
JwksFetcherandUrlKeyFetcherto share standard HTTPCache-Control: max-ageparsing (with a sensible default fallback like 1 hour). - Support configurable clock-skew tolerance (e.g., an optional
Duration clockSkewparameter) inPublicKeySignatureVerifierand claim validation. - Support polymorphic audience (
aud) matching (Stringvs.List<String>). - Expose a clean, reusable JWT verification primitive (or align with an upstream foundation like
google_cloud_server_auth) so downstream SDKs likefirebase_functionscan delete their custom verifiers and rely directly onfirebase_admin_sdk.
Activity
demolaf commentedon Jul 10, 2026
@kevmoo currently looking into this, i've self-assigned but if it's quite urgent I can unassign too.
kevmoo commentedon Jul 10, 2026
demolaf commentedon Jul 13, 2026
@kevmoo so either googleapis.dart or google-cloud-dart?
kevmoo commentedon Jul 13, 2026
Maybe
google-cloud-dart. Is my thought. Need to discuss/design. CC @brianquinlanbrianquinlan commentedon Jul 16, 2026
Is this something that should live in
package:webcryptoor something that can be built with the primitives inpackage:webcrypto?kevmoo commentedon Jul 17, 2026
@brianquinlan thinking the crypto bits go into pkg:webcripto and the JWT bits go into a new package
kevmoo commentedon Jul 17, 2026
...a new package under google-cloud-dart
brianquinlan commentedon Jul 17, 2026
A new package? Or in
package:google_cloud? If the functionality is relatively simple and doesn't introduce a bunch of new dependencies then adding it topackage:google_cloudmight be the most practical approach.Do you know how the other cloud languages approach this? For Python, JWT functionality seems to live in the auth package: https://google-auth.readthedocs.io/en/latest/index.html
kevmoo commentedon Jul 20, 2026
Likely in google-cloud-dart somewhere. I need to write up my thoughts here!