Why effect-auth
Learn the design goals behind Effect-native authentication.
effect-auth is for applications that want authentication inside the same typed Effect service graph as the rest of their backend. Capabilities are services, implementations are Layers, expected failures stay typed until the HTTP boundary, and runtime dependencies remain visible instead of hiding behind globals or callback registries.
There is no hosted control plane and no prescribed application user model. You choose the routes, features, storage, runtime, deployment, and the point where an authenticated subject maps to your domain; you also operate migrations, secrets, email, abuse controls, and monitoring.
Explicit infrastructure boundaries
| effect-auth provides | Your application provides |
|---|---|
| Typed auth services, Layers, expected errors, and standard operations | Runtime wiring, deployment, secrets, observability, and incident response |
| Store contracts plus maintained SQLite/D1 and PostgreSQL implementations | Migration execution, backups, retention, recovery, and database operations |
| Operation-specific security, error projection, and cookie consequences | Authorization, tenancy, route policy, CORS, and controls around direct service use |
Runtime concerns such as randomness, time, hashing, email, and configuration enter through replaceable services. Custom stores must preserve atomic consumption, compare-and-set updates, uniqueness, and token rotation; matching table shapes is insufficient. See Storage and Security Policies.
Fit and tradeoffs
| Good fit | Not a good fit |
|---|---|
| An Effect backend that wants auth in its typed dependency graph | A team that does not want to operate Effect-based infrastructure |
| App-owned routes, deployment, data, and user mapping | A hosted dashboard, managed users, and outsourced auth operations |
| APIs mixing standard endpoints with selected custom workflows | A framework app better served by a mature framework-native package |
| Teams prepared to review security and storage contracts | Teams expecting domain services to secure arbitrary endpoints automatically |
Current maturity
effect-auth is alpha software. Choose hosted or framework-native auth when delegated operations, administrative tooling, ecosystem breadth, or stability matter more than Effect-native composition. If the tradeoff fits, run the maintained example.