zenith_identity library
zenith_identity — Enterprise multi-tenant scoping, identity &
policy authorization for Flutter/Dart.
Built on top of flutter_zenith's core container and reactive node engine.
Sub-systems:
- Scope: Multi-tenant container runtime with 3-tier hierarchy and captive dependency detection.
- Identity: Sealed auth state machine, anonymous linking, biometric lock, back-channel revocation.
- Storage: Per-tenant namespaced storage and offline outbox isolation.
- Authorization: Declarative policy engine with reactive Flutter widgets.
- Widgets: Scope tunnelling, modal bridge, and declarative auth swap.
- Concurrency: Cancellation tokens with physical task abort.
- Enterprise: Cryptographic zeroization and database file isolation.
Classes
-
AsyncData<
T> - The successful state of an AsyncValue, holding the result value.
-
AsyncError<
T> - The error state of an AsyncValue, holding the error and stackTrace.
-
AsyncLoading<
T> - The loading state of an AsyncValue.
-
AsyncValue<
T> - A sealed union representing the state of an asynchronous operation.
- AuthAnonymous
- A guest/anonymous session identified by anonId.
-
AuthAuthenticated<
T> -
A fully authenticated session carrying session data of type
T. -
AuthLocked<
T> - The session is biometric-locked. The underlying scope and database handles remain open for instant unlock; UI mutations are paused.
- AuthMigrating
- A transitional state while migrating data from an anonymous container (fromId) to an authenticated container (toId).
- AuthorizationResult
- The result of evaluating a ZenithPolicy against a UserSecurityContext.
- AuthUnauthenticated
- No active session. The user has signed out or never signed in.
- InMemoryDatabasePool
- Simulated connections for tests; never touches physical storage.
- InMemoryStorageDriver
- An in-memory StorageDriver backed by a plain Dart Map.
- IpcListenerEntry
- Internal bookkeeping for a ReceivePort listener registered via ZenithTenantScope.listenToInterIsolateInvalidations.
- OutboxMutation
- A single queued offline mutation waiting to be dispatched.
- PolicyRef
- A minimal reactive ref passed to ZenithPolicy.evaluate and ZenithPolicy.evaluateAsync, providing watch access to ZenithNodes.
- RequireAuthenticatedUser
- Requires the user to have a valid authenticated session.
- RequireEntitlement
- Requires the user's entitlements to contain entitlement.
- RequireMaxMonthlyBandwidth
- Requires the user's consumed bandwidth to be under quotaGb GB.
- RequireRole
- Requires the user to hold role in their roles list.
- StorageDriver
- A raw storage driver with async read/write, used by ZenithPartitionedStorage as the physical backing.
- UserSecurityContext
- A security context capturing the claims, roles, and entitlements for a user.
- ZenithAuthorizationService
- Evaluates ZenithPolicy instances against UserSecurityContexts.
- ZenithAuthorizeView
- A declarative Flutter widget that shows different UI depending on whether a ZenithPolicy grants access.
- ZenithAuthScope
- A widget that declaratively switches between authenticated and unauthenticated UI based on a ZenithIdentityCoordinator's state.
- ZenithAuthState
-
Extended authentication state hierarchy for the
zenith_identitylayer. - ZenithCancellationToken
- A one-shot cancellation signal passed to async tasks so they can abort in-flight work (HTTP calls, DB operations) when the owning scope ends.
- ZenithConcurrencyRunner
-
A concurrency runner that supports the
restartablepattern via explicit ZenithCancellationTokens. - ZenithDatabaseHandle
- Abstract handle to a single database connection for one tenant.
- ZenithDatabasePool
- Owns one connection per tenant. Supply a real driver factory explicitly. Use InMemoryDatabasePool for simulated connections in tests.
- ZenithDrainable
- Abstraction for objects that can perform bounded-time cleanup work before a tenant scope is finally destroyed.
- ZenithDrainableCallback
- A convenience ZenithDrainable backed by a plain async callback.
-
ZenithFamily<
T, Arg> -
A strongly typed family identifier that creates a ZenithKey for any
argument. -
ZenithFamilyRegistry<
T, Arg> - Tracks the keys created for one ZenithFamily within a logical scope.
- ZenithIdentityCoordinator
- Coordinates the full identity lifecycle for a mobile application.
- ZenithInvalidateMessage
- An inter-isolate invalidation message that is safe to send across isolate boundaries (contains only plain Dart primitives).
-
ZenithKey<
T> - A strongly typed identifier for nodes managed by a ZenithContainer.
-
ZenithNode<
T> -
An atomic, observable state cell holding a value of type
T. - ZenithObserverTracker
- Optional interface for subscribers that also want to track which nodes are being read (used internally by ZenithBuilder and ComputedNode for automatic dependency collection).
- ZenithOutboxEngine
- An offline mutation queue that ensures a signed-out tenant's queued writes cannot be dispatched under another user's session, with error resilience, capped exponential backoff windows, clock-drift guards, and dead-letter queue isolation.
-
ZenithOverride<
T> - Pairs a ZenithKey with a factory override function for testing or scoping. Registering a ZenithOverride with a ZenithContainer causes ZenithContainer.getOrCreate to use factory instead of the factory passed at the call site whenever key is requested.
- ZenithPartitionedStorage
- A tenant-namespaced storage wrapper.
- ZenithPolicy
- A named collection of authorization rules evaluated against a UserSecurityContext.
- ZenithRequirement
- Contract for a single authorization condition.
- ZenithRouteGuard
- Evaluates a ZenithPolicy synchronously at the navigation layer, returning a redirect path if access is denied.
- ZenithScopeManager
- Manages the root application scope and all tenant child scopes.
- ZenithScopeProvider
- An InheritedWidget that exposes a ZenithTenantScope to its subtree.
- ZenithSecureBytes
- A secure byte buffer that wraps a Uint8List and implements Zeroizable.
- ZenithSubscriber
- ZenithTenantScope
- A named, isolated container scope managed by ZenithScopeManager.
- ZenithUserScope
- A ZenithTenantScope extended with workspace-scoped child scopes, implementing the 3-tier hierarchy:
- ZenithZone
- Global zone state for automatic dependency tracking.
- Zeroizable
- Interface for objects that hold sensitive memory buffers (cryptographic keys, tokens, PII) and must overwrite them with zeros on disposal.
Enums
- RevocationReason
- Reasons a remote authority may revoke a session.
- ZenithLifetime
- The scope lifetime tier used by the Captive Dependency Guard to detect when a longer-lived container holds a direct reference to a shorter-lived one.
Extensions
-
SafeAsyncNodeX
on ZenithNode<
AsyncValue< T> > - Adds mounted-safe async execution helpers directly on async state nodes.
- ZenithScopeBridgeX on BuildContext
- BuildContext extension providing zenithShowModalBottomSheet, a drop-in replacement for showModalBottomSheet that preserves the parent ZenithTenantScope across the Navigator boundary.
- ZenithScopeContextX on BuildContext
- BuildContext extension for convenient scope resolution.
Typedefs
- ZenithSubscription = void Function()
- Interface for objects that want to be notified when a ZenithNode changes.
Exceptions / Errors
- ZenithCaptiveDependencyException
- Thrown when a singleton lifetime registration attempts to directly resolve a scoped dependency from a child/scoped container.
- ZenithMigrationException
- Thrown when an anonymous-to-authenticated migration fails.