Storage

Effect Auth exposes focused Effect services, not one Storage service. Programs require only tags used by enabled features. Exported *StoreService, record, row, and input types are the authoritative signatures; construct implementations with each tag's make function.

For deployment choices and ownership, see Storage Overview. For implementation and concurrency guidance, see Custom Database.

Base services

The base contracts are exported from @effect-auth/core/Storage and fail with StorageError.

SessionStore.findById returns stored rows even when expired or revoked; policy interprets lifecycle fields. VerificationStore.consume succeeds only when a row exists, is unconsumed, matches an optional type, and has expiresAt > consumedAt. Concurrent consumers have at most one winner.

StorageError carries entity, operation, message, and optional cause. StorageError.fromUnknown(entity, operation, cause) maps backend failures without exposing row contents or secrets.

Feature-owned services

Feature contracts and errors live in the named public module. The maintained SQLite bundle implements these services. * requires eligibility and mutation in one atomic statement or transaction; CAS also requires the expected prior state.

RateLimitStore is public but is not in the maintained SQLite bundle. Supply a feature-specific implementation when required.

IdentityManagement relies on storage, not a preflight availability query, for correctness. Replace, revoke, and primary mutations match owner, active state, and expectedUpdatedAt; revoke additionally prevents removing the final login-eligible identity. Custom adapters must make those checks and writes atomic. The OAuth bridge likewise commits its new user, optional trusted verified-email identity, and provider account together. A provider-account race resolves to the winner; an email uniqueness race becomes an explicit-linking result rather than a partial user or silent merge.

Results, time, and encoding

Driver, timeout, uniqueness, serialization, and decode failures belong in the Effect error channel: StorageError for base stores and the owning module's error elsewhere. Never convert backend failures to Option.none().

Identifiers are branded runtime strings. UnixMillis values are finite epoch-millisecond numbers; use exact boundaries and caller-supplied mutation times, not database time. Preserve optional fields. Metadata, claims, scopes, canonical AMR, transports, request context, and versioned authentication events must round-trip losslessly; SQLite encodes structures as JSON text and booleans as compatible values. Materialized AAL/AMR/timestamps must match central derivation on every read and write. Raw events are security provenance: keep them server-side and never include them in ordinary session HTTP responses. Store hashes and ciphertext unchanged.

Maintained SQLite entry points

All return the same service set; options can replace AuthSqliteTables and tune login-risk history. Constructors acquiring a client are scoped. Provided executors and databases remain application-owned.

Migrations

authStorageMigrations from @effect-auth/core/StorageMigrations is the authoritative ordered array of AuthStorageMigration { id, sql }. It contains 0001_auth_storage through 0026_auth_user_identity, covering the maintained bundle. Apply each entry once, in order, before traffic and record its id. Migration 0026_auth_user_identity upgrades the published email-first user schema to identity-first storage and backfills each existing email as the user's primary global identity. Adapters never migrate automatically.