googleapis / googleapis/google-cloud-dart

feat(auth): add package:google_cloud_auth for server-side Google ID token & OIDC verification

Open
#322 2 comments 1 reaction 1 assignee Claimed by @brianquinlan View on GitHub
type: feature request
Dominant language
Dart
Stars
23
Forks
15
Avg merge
1d 9h
Merged PRs (30d)
21

Description

Add a new package, `package:google_cloud_auth`, to `google-cloud-dart` under `pkgs/google_cloud_auth/`.

This package provides canonical, pure-Dart server-side authentication primitives for Google Cloud and Dart backends, enabling fast in-memory verification of inbound Google ID tokens (RS256) and OpenID Connect (OIDC) tokens against public JSON Web Key Sets (JWKS).

## Motivation & Ecosystem Context

In other Google Cloud language SDKs (Node.js `google-auth-library`, Python `google-auth`, Go `cloud.google.com/go/auth`, Java `google-auth-library-java`), developers have official libraries to verify inbound Google ID tokens locally against Google's public JWKS.

In Dart, this capability has been missing from official packages, forcing major downstream Dart systems into expensive workarounds:
- **`pub.dev` Login:** Makes remote HTTP round-trips to `oauth2.googleapis.com/tokeninfo` (a debug endpoint) on every login request.
- **`pub.dev` Automated Publishing:** Spawns a standalone Go child process (`pkg/signature_verifier`) and uses temporary disk files to verify RSA-SHA256 signatures on GitHub Actions and Google Cloud WIF OIDC tokens.
- **Firebase Dart SDKs:** Bundle duplicate JWKS caching engines relying on third-party crypto packages (`dart_jsonwebtoken` / `pointycastle`).

`package:google_cloud_auth` consolidates these use cases into a single, officially maintained Google package with zero native C/C++ compilation requirements.

## Scope & Capabilities

1. **Pure-Dart RS256 Verification Engine:**
- Inlined `BigInt.modPow` + `package:crypto` SHA-256 (`EMSA-PKCS1-v1_5`).
- Zero native build dependencies (no CMake or C/C++ compiler required).
- Validated against 100% of NIST test vectors.
2. **JWS Wire Parser & Base64URL:**
- Strict RFC 7515/7519 envelope splitting and unpadded base64url decoding.
3. **In-Memory JWKS Cache:**
- Honors HTTP `Cache-Control: max-age` and `Age` headers.
- Handles key rotation automatically via single cache-busting re-fetch on unknown `kid`.
4. **Generic `IdTokenVerifier`:**
- Verifies arbitrary OIDC tokens (GitHub Actions, Firebase, Auth0, etc.).
- Enforces `iss`, `aud`, `exp`, `iat`, with configurable clock-skew tolerance.
5. **Google Specialization (`GoogleIdTokenVerifier`) & Shelf Middleware:**
- Pre-configured with Google certs (`oauth2/v3/certs`) and Google issuers (`accounts.google.com`).
- Validates Google-specific claims (`email_verified`, `hd`).
- Provides `shelf` middleware (`googleAuth`) with hardened default-deny dev auth bypass.

## Proposed Package Layout

```
pkgs/google_cloud_auth/
├── pubspec.yaml
├── README.md
├── CHANGELOG.md
├── analysis_options.yaml
├── lib/
│ ├── google_cloud_auth.dart # Canonical public entry point (re-exports verifiers & middleware)
│ └── src/
│ ├── crypto/
│ │ └── rsa_verify.dart # ~65-line pure-Dart RS256 (BigInt.modPow + package:crypto SHA-256)
│ ├── jwks/
│ │ └── jwks_cache.dart # Cache-Control-honoring in-memory JWKS key cache & rotation
│ ├── jwt/
│ │ └── jws_parser.dart # JWS header.payload.signature splitting & unpadded base64url decoding
│ ├── verifier/
│ │ ├── id_token_verifier.dart # Generic OIDC ID token verifier (iss, aud, exp, iat, clock-skew)
│ │ └── google_id_token_verifier.dart# Google Cloud specialization (accounts.google.com, email_verified)
│ └── shelf/
│ └── google_auth_middleware.dart # Shelf authentication middleware & hardened dev auth bypass
└── test/
├── crypto/
│ └── rsa_verify_test.dart # NIST RS256 test vectors & padding boundary tests
├── jwks/
│ └── jwks_cache_test.dart # Cache-Control max-age & key rotation tests
├── jwt/
│ └── jws_parser_test.dart # JWS header/payload format tests
├── verifier/
│ ├── id_token_verifier_test.dart # Generic OIDC claim validation tests
│ └── google_id_token_verifier_test.dart# Google ID token tests
└── shelf/
└── google_auth_middleware_test.dart# Shelf middleware & dev bypass tests
```

## Milestone & Release Plan

- **v0.1.0-wip (MVP):**
- Scaffold package under `pkgs/google_cloud_auth`.
- Inlined pure-Dart RS256 engine passing 100% of NIST test vectors.
- JWKS cache with auto-rotation on unknown `kid`.
- Generic `IdTokenVerifier` and `GoogleIdTokenVerifier`.
- Shelf `googleAuth` middleware.
- Integration fixtures for `pub.dev` and Firebase use cases.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.