rtdb-admin 0.1.0

Service account authentication and token lifecycle management for rtdb-rs
Documentation

rtdb-admin

Service-account authentication and token lifecycle management for the RTDB Rust ecosystem.

rtdb-admin owns credential loading, JWT/OAuth exchange, token caching, expiry, refresh, and authenticated rtdb-rs client lifecycle. It is intentionally separate from Firebase database transport, typed models, and synchronized application state.

RTDB Rust ecosystem

application
   |
   +-- rtdb-sync
   |     synchronized state, durability, offline queue/replay
   |
   +-- rtdb-typed
   |     Serde models, typed CRUD, queries, realtime events
   |
   +-- rtdb-admin
   |     service-account loading, OAuth exchange, token lifecycle
   |
   `-- rtdb-rs
         Firebase REST + query + SSE transport
                  |
                  v
          Firebase Realtime Database
Crate Responsibility
rtdb-rs Raw Firebase REST/query/SSE transport
rtdb-typed Typed Serde CRUD, collections, queries, patches, and realtime events
rtdb-admin Service-account credentials, OAuth exchange, expiry, refresh, and authenticated client lifecycle
rtdb-sync Synchronized state, local writes, durability, offline replay, and reconciliation

rtdb-admin should be used when an application needs long-running server-side service-account authentication. It does not reimplement rtdb-rs transport and it does not place service-account lifecycle inside rtdb-typed or rtdb-sync.

Current release line

The current package is 0.1.0.

It includes:

  • validated service-account JSON/file/environment loading
  • in-memory credential representation with secret-safe diagnostics
  • credential fingerprints without printing private keys
  • RS256 JWT assertions
  • OAuth token exchange
  • token expiry tracking
  • configurable refresh-before-expiry behavior
  • concurrency-safe cached refresh / single-flight behavior
  • explicit invalidation and shutdown
  • proactive refresh support
  • readiness and refresh metrics
  • bounded multi-identity credential management
  • optional authenticated rtdb-rs client integration
  • failure, timeout, malformed-response, and concurrent-refresh tests

Responsibility boundary

application/server
        |
   rtdb-admin
   credentials
   JWT assertion
   OAuth exchange
   expiry/refresh
   client replacement
        |
     rtdb-rs
   REST + SSE
        |
 Firebase RTDB

The credential manager is the authority for service-account and access-token lifecycle. Database paths, queries, SSE parsing, typed models, offline journals, and synchronization policy remain in their respective crates.

rtdb-rs integration

Enable the optional client integration feature:

[dependencies]
rtdb-admin = { version = "0.1.0", features = ["rtdb-client"] }

The integration layer can create or update authenticated RtdbClient values while keeping refresh policy in rtdb-admin.

This is particularly useful for long-lived services where one-hour token assumptions and ad-hoc refresh logic would otherwise leak into application code.

Concurrency behavior

Authentication infrastructure tends to fail under concurrency if every request independently refreshes the same expiring token. rtdb-admin therefore treats refresh coordination as a first-class concern.

The local stress suite covers scenarios including:

  • 100 concurrent single-flight callers
  • 64 callers around an expiry boundary
  • 128 callers during an outage/failure condition
  • 100 managed identities
  • 1,000 concurrent identity consumers

The ecosystem stress harness in rtdb-sync also exercises short controlled token lifetimes, repeated refresh, and active authenticated-client replacement while raw, typed, and synchronized RTDB traffic is running against the Firebase Emulator.

Security model

Real service-account private keys, OAuth access tokens, refresh artifacts, and credential-bearing fixtures must never be committed to this repository.

Normal tests use fake credentials and localhost token endpoints. Real Google/Firebase validation remains opt-in through documented environment variables.

rtdb-admin keeps credential lifecycle separate from rtdb-sync persistence. Durable application snapshots and mutation journals must never be treated as credential stores.

Validation

Run the local source gates with:

cargo fmt --all --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets --all-features

Package and publication validation is part of the coordinated ecosystem release gate. The current manifest expects rtdb-rs 0.3.2; that exact crates.io dependency graph can only be validated after the matching transport release is published.

Relationship to rtdb-typed

rtdb-typed consumes authenticated transport and provides typed Serde models, CRUD, queries, collections, partial patches, and realtime events. It does not own service-account keys or refresh logic.

Relationship to rtdb-sync

rtdb-sync owns long-lived synchronized state, reconnect behavior, local writes, conflict policy, durable snapshots, offline mutation journals, crash recovery, and replay. It may use an authenticated transport produced by rtdb-admin, but credential lifecycle remains outside persistence and synchronization.

Scope

rtdb-admin is not a general Firebase Admin SDK replacement. It focuses on the authentication and token lifecycle needed by the RTDB Rust stack. It does not implement Firestore, Storage, FCM, Firebase Auth user administration, Remote Config, Functions deployment, or security-rule administration.

License

MIT