zuraffa_auth_firebase 7.3.8
zuraffa_auth_firebase: ^7.3.8 copied to clipboard
Firebase adapter for zuraffa_auth — anonymous/Google/Apple sign-in on the AuthProvider port with the credential stream token-exchange flows consume; firebase_auth, google_sign_in and sign_in_with_appl [...]
zuraffa_auth_firebase #
Firebase adapter for zuraffa_auth — anonymous/Google/Apple sign-in
on the AuthProvider port plus the credential stream vendure-style token
exchanges consume. firebase_auth, google_sign_in, and
sign_in_with_apple are implementation details of this package: the
consuming app has zero direct imports of any of them.
The sign-in dispatch, token lifecycle, and failure taxonomy are pure Dart in
the app-facing package (FirebaseAuthProvider over the FirebaseAuthGateway
seam), fully testable against an in-memory gateway — this package owns the
platform plumbing: the envelope-and-taxonomy channel and the plugin-wired
gateway.
// after Firebase.initializeApp():
registerFirebaseAuthDependencies(
getIt,
gateway: FirebasePluginsGateway().channel,
);
registerAuthDependencies(getIt, providers: getIt<List<AuthProvider>>());
final auth = getIt<AuthService>();
await auth.signIn(
'firebase-google',
const AuthCredentials(identifier: '', secret: ''),
);
final session = await auth.restore(); // relaunch resolves the same identity
// the vendure-style exchange: subscribe once, exchange every credential
final provider = getIt<FirebaseAuthProvider>(instanceName: 'firebase-google');
if (provider is CredentialStreamProvider) {
provider.credentialStream.listen((credential) {
if (credential == null) return; // signed out
// credential.token.accessToken — the short-lived identity token
// credential.subject — the Firebase uid
// → exchange for the storefront session
});
}
Credential stream semantics #
CredentialStreamProvider.credentialStream is a broadcast stream of
AuthResult?:
- the current credential arrives on subscription — exactly once, as the
gateway protocol's first emission (mirroring firebase_auth's
idTokenChanges): the exchange re-subscribing after offline mode never waits cold and never receives the same credential twice; - every subsequent change arrives as it happens — sign-in, token refresh
(the gateway force-refreshes on the provider's
refresh), and sign-out; - a
nullelement is signed-out — the same shapevendure_client-style consumers branch on.
No Firebase type ever crosses the boundary: the identity token is the result
token's accessToken (short-lived JWT the backend verifies) and subject
is the Firebase uid.
Channel protocol #
The gateway seam is injectable (FirebaseAuthGateway); the plugin-wired
implementation speaks this protocol:
call method |
Args | Result | Errors |
|---|---|---|---|
signInAnonymously |
extras | {uid, idToken, email?, displayName?, expiresAt?} |
see below |
signInWithGoogle |
extras | same payload | see below |
signInWithApple |
extras (nonce flows through) |
same payload | see below |
refreshToken |
token fields + forceRefresh: true |
{uid, idToken, expiresAt?} |
see below |
signOut |
accessToken |
any (best-effort) | swallowed by the provider |
Events: credentialChanges — {uid, idToken, …} payloads or null
(signed-out), current credential first.
Errors arrive as {'error': {'code', 'message'}} payloads (or thrown
transport failures → channel_error). Taxonomy: no_credentials → typed
invalid_credentials; user_cancelled / network_request_failed /
too_many_requests / timeout → recoverable; unknown and provider-specific
codes → non-recoverable, preserved verbatim. Plugin codes normalize at the
gateway: firebase's network-request-failed/too-many-requests/
user-cancelled and the plugin cancellations (Apple's canceled, Google's
cancelled) map to the taxonomy above.
Real-project setup #
- Add a Firebase project and drop the platform config files
(
google-services.json/GoogleService-Info.plist) as the firebase_core setup guides describe; callawait Firebase.initializeApp()before registering. - Google (Android/iOS/macOS/Web): configure the SHA-1/SHA-256 release
fingerprints and the reversed client-id URL scheme;
google_sign_in7.x needs no init call — the gateway usesGoogleSignIn.instancedirectly. - Apple (iOS/macOS): enable Sign in with Apple for the app id and add the entitlement; the gateway generates the nonce, hashes it, and hands firebase the raw nonce with the identity token.
- Anonymous sign-in must be enabled in the Firebase console (Authentication → Sign-in method).
The three method instances register together
(firebase-anonymous / firebase-google / firebase-apple); wire them into
the root registerAuthDependencies and AuthService's restore/auto-refresh
works unchanged — persistence runs through zuraffa_session.