@effect-auth/core 0.1.0-alpha.0 → 0.1.0-alpha.10

package/README.md

@@ -4,22 +4,41 @@ Composable Effect-first authentication primitives.
 
 The current alpha surface is intentionally small: service contracts and small helpers that can be wired with application-owned layers.
 
+## HTTP Client
+
+`@effect-auth/core/Client` exposes a browser-friendly client generated from the same `AuthApi` contract used by the server. It accepts plain JSON input types, includes cookies by default, and decodes successful/error responses through Effect Schema.
+
+```ts
+import { createAuthClient } from "@effect-auth/core/Client";
+
+const authClient = createAuthClient();
+
+const result = await authClient.password.signIn({
+  email: "reader@example.com",
+  password: "correct horse battery staple",
+});
+
+const session = await authClient.session.currentOrUndefined();
+```
+
+Use `@effect-auth/core/HttpApi` when you are wiring the server or need the raw `HttpApi` contract. Use `@effect-auth/core/Client` in application UI code.
+
 ## Policy
 
 `Policy` is an `Effect` used for authorization. Success means access is allowed. `AuthzError` means access is denied. Other failures stay operational errors.
 
 ```ts
-import { Effect } from "effect"
-import * as Policy from "@effect-auth/core/Policy"
+import { Effect } from "effect";
+import * as Policy from "@effect-auth/core/Policy";
 
-const canEditProject = Policy.deny("missing-permission")
+const canEditProject = Policy.deny("missing-permission");
 
 const updateProject = Effect.succeed({ updated: true }).pipe(
   Policy.require(canEditProject)
-)
+);
 
-const decision = Policy.check(canEditProject)
-const detailed = Policy.checkDetailed(canEditProject)
+const decision = Policy.check(canEditProject);
+const detailed = Policy.checkDetailed(canEditProject);
 ```
 
 Use `Policy.check` when callers should branch on allowed/denied and let operational errors fail. Use `Policy.checkDetailed` when callers need a value for allowed, denied, or failed.
@@ -27,41 +46,441 @@ Use `Policy.check` when callers should branch on allowed/denied and let operatio
 Policies compose with `all`, `any`, and `not`:
 
 ```ts
-declare const isProjectOwner: Policy.Policy
-declare const hasUpdateGrant: Policy.Policy
-declare const isSuspended: Policy.Policy
+declare const isProjectOwner: Policy.Policy;
+declare const hasUpdateGrant: Policy.Policy;
+declare const isSuspended: Policy.Policy;
 
-const canEditProject = Policy.any(
-  isProjectOwner,
-  hasUpdateGrant
-)
+const canEditProject = Policy.any(isProjectOwner, hasUpdateGrant);
 
 const canEditAndNotSuspended = Policy.all(
   canEditProject,
   Policy.not(isSuspended, "account-disabled")
-)
+);
+```
+
+Step-up gates live in `@effect-auth/core/StepUp` and can be converted to policies when a product action requires stronger or fresher auth:
+
+```ts
+import { Duration } from "effect";
+import * as Policy from "@effect-auth/core/Policy";
+import * as StepUp from "@effect-auth/core/StepUp";
+
+const canGenerateApiKey = StepUp.toPolicy({
+  aal: "aal2",
+  maxAge: Duration.minutes(15),
+});
+
+const generateApiKey = createApiKey.pipe(Policy.require(canGenerateApiKey));
+```
+
+## Rate Limiter
+
+`RateLimiter` is a small auth-oriented wrapper around Effect's persistent rate limiter. It keeps the public auth API focused on policies and safe keys while delegating fixed-window/token-bucket mechanics to `effect/unstable/persistence`.
+
+```ts
+import { Duration, Effect } from "effect";
+import { EmailHash, type IpHash } from "@effect-auth/core/Identifiers";
+import * as RateLimit from "@effect-auth/core/RateLimiter";
+
+const PasswordSignInEmailLimit = RateLimit.RateLimitPolicy.fixedWindow({
+  id: "auth.password.sign_in.email",
+  key: RateLimit.RateLimitKey.emailHash(EmailHash("hmac-email-hash")),
+  limit: 5,
+  window: Duration.minutes(10),
+});
+
+const signIn = Effect.gen(function* () {
+  yield* RateLimit.require(PasswordSignInEmailLimit);
+
+  return yield* Effect.succeed({ ok: true });
+});
+```
+
+`fixedWindowBy` and `tokenBucketBy` accept any safe `RateLimitKey`, including composite keys built from other safe keys:
+
+```ts
+declare const ipHash: IpHash;
+declare const emailHash: EmailHash;
+
+const PasswordSignInIpEmailLimit = RateLimit.RateLimitPolicy.fixedWindowBy({
+  id: "auth.password.sign_in.ip_email",
+  by: RateLimit.RateLimitKey.combine(
+    "ip-email",
+    RateLimit.RateLimitKey.ipHash(ipHash),
+    RateLimit.RateLimitKey.emailHash(emailHash)
+  ),
+  limit: 5,
+  window: Duration.minutes(10),
+});
+```
+
+Use `RateLimitKey.emailHash`, `ipHash`, `userAgentHash`, `customHash`, or `combine` with values produced by `Privacy` or another app-owned hashing layer; raw emails, IPs, tokens, and user agents should not be used as store keys. `PrivacyLive({ secret })` provides a production HMAC implementation with conservative input normalization. Use a dedicated secret such as `AUTH_PRIVACY_SECRET`, separate from session and challenge secrets. `RateLimiterMemoryLive` is process-local for tests/dev, and production deployments can provide a persistent Effect `RateLimiterStore` such as Redis or `@effect-auth/core/CloudflareRateLimitDurableObject`.
+
+```ts
+import { Redacted } from "effect";
+import { PrivacyLive } from "@effect-auth/core/Privacy";
+
+const AuthPrivacyLive = PrivacyLive({
+  secret: Redacted.make(env.AUTH_PRIVACY_SECRET),
+});
+```
+
+The built-in HTTP auth API includes default IP and email rate limits. Production deployments still provide their own durable `RateLimiter` store and HMAC `Privacy` secret. `AuthServicesLive` below stands for your app-owned auth service wiring.
+
+```ts
+import { Layer, Redacted } from "effect";
+import { RateLimiter as PersistenceRateLimiter } from "effect/unstable/persistence";
+import { AuthHttpApiLive } from "@effect-auth/core/HttpApi";
+import {
+  RateLimitStoreDurableObject,
+  type CloudflareRateLimitDurableObjectNamespace,
+} from "@effect-auth/core/CloudflareRateLimitDurableObject";
+import { PrivacyLive } from "@effect-auth/core/Privacy";
+import { RateLimiterLive } from "@effect-auth/core/RateLimiter";
+
+export const makeAuthHttpApiLayer = (
+  namespace: CloudflareRateLimitDurableObjectNamespace,
+  privacySecret: string
+) => {
+  const DurableObjectRateLimiterLive = RateLimiterLive.pipe(
+    Layer.provide(PersistenceRateLimiter.layer),
+    Layer.provide(RateLimitStoreDurableObject.layer({ namespace }))
+  );
+
+  return AuthHttpApiLive.pipe(
+    Layer.provide(AuthServicesLive),
+    Layer.provide(DurableObjectRateLimiterLive),
+    Layer.provide(PrivacyLive({ secret: Redacted.make(privacySecret) }))
+  );
+};
+```
+
+`AuthHttpApiLive` enforces IP limits in HTTP middleware and email limits after schema decoding in the built-in handlers. A single request may consume both a request-level rule and a payload-level rule. `RateLimitPolicy.all(...)` is still available for custom flows and consumes sequentially; put the most specific limits first, such as `ip + email`, then broader limits such as `email`.
+
+Advanced apps can replace the `AuthApiRateLimit` service directly. `AuthApiRateLimitMiddlewareLive` delegates request-level checks to that service, so custom policies can still use the built-in endpoint middleware and handler hooks.
+
+Use `AuthHttpApiBareLive` only when you explicitly do not want built-in auth rate limits:
+
+```ts
+import { Layer } from "effect";
+import { AuthHttpApiBareLive } from "@effect-auth/core/HttpApi";
+
+export const AuthHttpApiLayer = AuthHttpApiBareLive.pipe(
+  Layer.provide(AuthServicesLive)
+);
 ```
 
 ## AuthFlow
 
-Login methods should verify a factor, then hand the result to `AuthFlow`. `AuthFlow` decides whether to issue a session, require MFA, require verification, or deny the attempt.
+Login methods should verify a factor, then hand the result to `AuthFlow`. `AuthFlow` returns a flat `AuthResult` tagged enum: authenticated, step-up/verification requirements, or successful auth outcomes such as invalid credentials.
 
 ```ts
-import { Effect } from "effect"
-import { AuthFlow } from "@effect-auth/core/AuthFlow"
-import type { UserId } from "@effect-auth/core/Identifiers"
+import { Effect } from "effect";
+import { AuthFlow } from "@effect-auth/core/AuthFlow";
+import type { UserId } from "@effect-auth/core/Identifiers";
 
 export const completePassword = (userId: UserId) =>
   Effect.gen(function* () {
-    const authFlow = yield* AuthFlow
+    const authFlow = yield* AuthFlow;
 
     return yield* authFlow.completePrimaryFactor({
       userId,
       method: "password",
       amr: ["pwd"],
-      aal: "aal1"
+      aal: "aal1",
+    });
+  });
+```
+
+Service contracts expose small `make` factories for typed layer wiring:
+
+```ts
+import { Effect, Layer } from "effect";
+import { AuthFlow, AuthResult } from "@effect-auth/core/AuthFlow";
+import type { IssuedSession } from "@effect-auth/core/Sessions";
+
+declare const issuedSession: IssuedSession;
+
+const AuthFlowLive = Layer.succeed(
+  AuthFlow,
+  AuthFlow.make({
+    startPrimaryFactor: () =>
+      Effect.succeed(AuthResult.PolicyDenied({ reason: "test" })),
+    completePrimaryFactor: () =>
+      Effect.succeed(AuthResult.PolicyDenied({ reason: "test" })),
+    completeMfa: () =>
+      Effect.succeed(AuthResult.PolicyDenied({ reason: "test" })),
+    complete: () =>
+      Effect.succeed(AuthResult.Authenticated({ session: issuedSession })),
+  })
+);
+```
+
+The same pattern is available on core services such as `AuditLog.make`, `Sessions.make`, `SessionCookie.make`, `Challenge.make`, `Crypto.make`, `Privacy.make`, and `WaitUntil.make`.
+
+The first default live implementations are available for the phase-3 web session path:
+
+```ts
+import { Layer, Redacted } from "effect";
+import { AuthFlowLive } from "@effect-auth/core/AuthFlow";
+import { ChallengeLive } from "@effect-auth/core/Challenge";
+import { WebCryptoLive } from "@effect-auth/core/Crypto";
+import {
+  PasswordLoginLive,
+  PasswordRegistrationLive,
+  Pbkdf2PasswordHasherLive,
+} from "@effect-auth/core/Password";
+import { SessionCookieLive, SessionsLive } from "@effect-auth/core/Sessions";
+import { EffectQbSqliteAuthStorageLive } from "@effect-auth/core/EffectQbSqliteStorage";
+
+const AuthLive = Layer.mergeAll(
+  WebCryptoLive(),
+  EffectQbSqliteAuthStorageLive(executor),
+  Pbkdf2PasswordHasherLive(),
+  SessionsLive({ secret: Redacted.make(env.AUTH_SESSION_SECRET) }),
+  SessionCookieLive(),
+  ChallengeLive({ secret: Redacted.make(env.AUTH_CHALLENGE_SECRET) }),
+  AuthFlowLive,
+  PasswordLoginLive,
+  PasswordRegistrationLive
+);
+```
+
+`SessionsLive` stores only `sessionId` plus HMAC secret hash in the database. The browser cookie contains the opaque bearer token in `sessionId.secret` format.
+
+## Password
+
+`PasswordLogin` verifies a password factor and hands the result to `AuthFlow`. It does not create sessions directly.
+
+```ts
+import { Effect, Redacted } from "effect";
+import { Email } from "@effect-auth/core/Identifiers";
+import { PasswordLogin } from "@effect-auth/core/Password";
+
+export const signIn = Effect.gen(function* () {
+  const password = yield* PasswordLogin;
+
+  return yield* password.signIn({
+    email: Email("user@example.com"),
+    password: Redacted.make("correct horse battery staple"),
+  });
+});
+```
+
+`PasswordLoginLive` requires `UserStore`, `CredentialStore`, `PasswordHasher`, and `AuthFlow`. Invalid credentials return `AuthResult.InvalidCredentials()`, while storage/hash/session failures stay as typed errors.
+
+`PasswordRegistration` creates a user and password credential, then hands the primary password factor to `AuthFlow`.
+
+```ts
+import { Effect, Redacted } from "effect";
+import { Email } from "@effect-auth/core/Identifiers";
+import { PasswordRegistration } from "@effect-auth/core/Password";
+
+export const signUp = Effect.gen(function* () {
+  const registration = yield* PasswordRegistration;
+
+  return yield* registration.signUp({
+    email: Email("user@example.com"),
+    password: Redacted.make("correct horse battery staple"),
+  });
+});
+```
+
+Duplicate emails fail with `EmailAlreadyRegisteredError`; callers decide whether to expose that as a conflict, a neutral response, or another boundary-specific behavior.
+
+`Pbkdf2PasswordHasherLive` is the first reference hasher. It uses Web Crypto PBKDF2-SHA256 and stores hashes as `pbkdf2-sha256$iterations$salt$hash`.
+
+```ts
+import { Layer } from "effect";
+import { WebCryptoLive } from "@effect-auth/core/Crypto";
+import { Pbkdf2PasswordHasherLive } from "@effect-auth/core/Password";
+
+const PasswordHashingLive = Layer.mergeAll(
+  WebCryptoLive(),
+  Pbkdf2PasswordHasherLive()
+);
+```
+
+## HTTP API
+
+`@effect-auth/core/HttpApi` contains the first Effect v4 HttpApi contract for the built-in auth surface. It exports `AuthApi`, module-owned endpoint groups, and handler layers for the core services.
+
+```ts
+import { Layer } from "effect";
+import { HttpRouter } from "effect/unstable/http";
+import { AuthHttpApiLive } from "@effect-auth/core/HttpApi";
+import { PrivacyLive } from "./auth/privacy";
+import { RateLimiterLive } from "./auth/rate-limiter";
+
+export const AuthRoutesLive = HttpRouter.serve(
+  AuthHttpApiLive.pipe(
+    Layer.provide(AuthServicesLive),
+    Layer.provide(RateLimiterLive),
+    Layer.provide(PrivacyLive)
+  )
+);
+```
+
+The contract currently includes these endpoint groups:
+
+| Group | Endpoints |
+| --- | --- |
+| Password | `POST /auth/password/sign-in`, `POST /auth/password/sign-up`, `POST /auth/password/reset/start`, `POST /auth/password/reset/verify`, `POST /auth/password/set`, `POST /auth/password/change`. |
+| Sessions | `GET /auth/session`, `POST /auth/session/refresh`, `POST /auth/logout`, `GET /auth/sessions`, `POST /auth/sessions/revoke`, `POST /auth/sessions/revoke-others`. |
+| Email verification | `POST /auth/email-verification/start`, `POST /auth/email-verification/verify`. |
+| Email OTP | `POST /auth/email-otp/start`, `POST /auth/email-otp/verify`. |
+| Magic link | `POST /auth/magic-link/start`, `POST /auth/magic-link/verify`. |
+| Login approval | `POST /auth/login-approval/approve`, `POST /auth/login-approval/status`, `POST /auth/login-approval/finalize`. |
+| Security | `POST /auth/security/login/report`. |
+
+`AuthHttpApiLive` wires the full built-in surface. Apps can own the final HTTP contract and reuse individual endpoints, handlers, or services when a feature needs app-specific payloads or responses.
+
+`Authenticated` results set the configured session cookie and never include the opaque session token in JSON bodies. Invalid credentials and disabled accounts map to the same `401 invalid_credentials` response by default. Duplicate password sign-up emails fail as `EmailAlreadyRegisteredError` in the domain layer and map to a `409 email_already_registered` HTTP API error.
+
+`SessionApi` reads the configured session cookie and validates it with `Sessions`, returning a safe current-session JSON body or `401 unauthenticated`. Refresh extends the current session when it is eligible, commits the refreshed session cookie, and returns the safe current-session JSON body. Safe authenticated bodies include session claims when present, but never include the opaque session token. Logout revokes the current session when present and clears the session cookie with a `204` response.
+
+`AuthHttpApiLive` includes `AuthOriginCheckMiddlewareLive()` for cookie-based unsafe methods and built-in IP/email rate limits for auth abuse control. Origin checks allow same-origin requests, reject cross-origin browser requests with `403 request_rejected`, and allow missing `Origin`/`Referer` headers by default for non-browser clients. Browser-only apps can compose their own `HttpApiBuilder.layer(AuthApi)` and provide `AuthOriginCheckMiddlewareLive({ allowMissingOrigin: false })`.
+
+`AuthCsrfMiddlewareLive()` is available for apps that want double-submit CSRF checks on unsafe cookie endpoints. It compares the `__Host-csrf` cookie to the `x-csrf-token` header by default and rejects mismatches with `403 request_rejected`. App-owned HTTP handlers should map core `AuthzError` policy failures to safe `403 policy_denied` responses without exposing policy reasons or internal details.
+
+Apps using `AuthCsrfMiddleware` must issue the CSRF token themselves, usually from an app-owned bootstrap endpoint or page render. The token should be high-entropy, set as the `__Host-csrf` cookie, and echoed by browser code in the `x-csrf-token` header on unsafe cookie requests:
+
+```ts
+const csrfToken = crypto.randomUUID();
+
+return new Response(JSON.stringify({ csrfToken }), {
+  headers: {
+    "content-type": "application/json",
+    "set-cookie": `__Host-csrf=${encodeURIComponent(csrfToken)}; Path=/; Secure; HttpOnly; SameSite=Lax`,
+  },
+});
+
+await fetch("/auth/session/refresh", {
+  method: "POST",
+  credentials: "include",
+  headers: { "x-csrf-token": csrfToken },
+});
+```
+
+`AuthRequestMetadataMiddlewareLive()` can provide method, URL, origin, user-agent, and trusted proxy IP metadata to app-owned handlers. Built-in auth rate limiting is configured in one place with `AuthHttpApiConfigLive(...)`. It applies IP limits in HTTP middleware, then payload-level email limits after schema decoding:
+
+```ts
+import { Duration, Layer } from "effect";
+import {
+  AuthHttpApiConfigLive,
+  AuthHttpApiLive,
+} from "@effect-auth/core/HttpApi";
+import { PrivacyLive } from "./auth/privacy";
+import { RateLimiterLive } from "./auth/rate-limiter";
+
+export const AuthHttpApiLayer = AuthHttpApiLive.pipe(
+  Layer.provide(
+    AuthHttpApiConfigLive({
+      rateLimit: {
+        trustProxyHeaders: true,
+        passwordSignIn: {
+          byIp: { limit: 20, window: Duration.minutes(10) },
+          byEmail: { limit: 5, window: Duration.minutes(10) },
+        },
+        passwordSignUp: {
+          byIp: false,
+          byEmail: { limit: 3, window: Duration.hours(1) },
+        },
+        emailVerificationStart: false,
+      },
     })
+  ),
+  Layer.provide(AuthServicesLive),
+  Layer.provide(RateLimiterLive),
+  Layer.provide(PrivacyLive)
+);
+```
+
+Using `AuthHttpApiLive` without `AuthHttpApiConfigLive(...)` uses conservative defaults for `passwordSignIn`, `passwordSignUp`, and `emailVerificationStart`. In `rateLimit` config, `true` means default rules, `false` disables that endpoint or rule, omitted values keep defaults, and an object overrides `limit`, `window`, or `tokens`. Use `AuthHttpApiBareLive` to opt out explicitly. `AuthHttpApiLive` never installs a process-local store by itself; production apps still provide a durable `RateLimiter` and `PrivacyLive`.
+
+```ts
+import { AuthHttpApiBareLive } from "@effect-auth/core/HttpApi";
+
+export const AuthHttpApiLayer = AuthHttpApiBareLive.pipe(
+  Layer.provide(AuthServicesLive)
+);
+```
+
+`EmailVerificationApi` exposes `start` and `verify` endpoints. `start` calls `EmailVerificationFlow` to issue and send a verification challenge through the app-owned `EmailDelivery` adapter. `verify` calls `EmailVerification` and returns `204` on success. When the request includes a valid current session cookie for the same user, `verify` also marks that session's claims as email verified and removes the `email_verification` requirement. Error responses are generic and do not include emails, user ids, challenge secrets, or provider details.
+
+Password HTTP handlers can start `EmailVerificationFlow` automatically when a custom auth flow returns `RequiresEmailVerification`. The HTTP response remains `requires_email_verification` and does not include the user id, email, challenge secret, or delivery provider details.
+
+You can own the final HTTP contract while reusing core endpoints. For example, replace only password sign-up with an app-specific phone payload and keep the default sign-in endpoint:
+
+```ts
+import { Effect, Schema } from "effect";
+import {
+  HttpApi,
+  HttpApiBuilder,
+  HttpApiEndpoint,
+  HttpApiGroup,
+} from "effect/unstable/httpapi";
+import {
+  AuthBadRequestError,
+  AuthEmailAlreadyRegisteredError,
+  AuthHttp,
+  AuthInternalError,
+  AuthOriginCheckMiddleware,
+  AuthPolicyDeniedError,
+  AuthRateLimitedError,
+  AuthSchemaErrorMiddleware,
+  makePasswordSignInHandler,
+  passwordSignInEndpoint,
+  PasswordAuthSuccess,
+} from "@effect-auth/core/HttpApi";
+import { EmailSchema } from "@effect-auth/core/Identifiers";
+import { PasswordLogin } from "@effect-auth/core/Password";
+
+const PhoneNumber = Schema.String.check(Schema.isPattern(/^\+[1-9]\d{7,14}$/));
+
+const PhoneSignUpBody = Schema.Struct({
+  email: EmailSchema,
+  password: Schema.String,
+  phone: PhoneNumber,
+});
+
+const phoneSignUpEndpoint = HttpApiEndpoint.post("signUp", "/sign-up", {
+  payload: PhoneSignUpBody,
+  success: PasswordAuthSuccess,
+  error: [
+    AuthBadRequestError,
+    AuthEmailAlreadyRegisteredError,
+    AuthPolicyDeniedError,
+    AuthRateLimitedError,
+    AuthInternalError,
+  ],
+});
+
+class PasswordApi extends HttpApiGroup.make("password")
+  .add(passwordSignInEndpoint, phoneSignUpEndpoint)
+  .prefix("/auth/password")
+  .middleware(AuthSchemaErrorMiddleware)
+  .middleware(AuthOriginCheckMiddleware) {}
+
+class AppAuthApi extends HttpApi.make("AppAuthApi").add(PasswordApi) {}
+
+export const AppPasswordApiLive = HttpApiBuilder.group(
+  AppAuthApi,
+  "password",
+  Effect.fn("app.auth.password.group")(function* (handlers) {
+    const password = yield* PasswordLogin;
+    const authHttp = yield* AuthHttp;
+
+    return handlers
+      .handle("signIn", makePasswordSignInHandler({ password, authHttp }))
+      .handle(
+        "signUp",
+        Effect.fn("app.auth.password.sign_up")(function* ({ payload }) {
+          return yield* signUpWithPhone(payload, authHttp);
+        })
+      );
   })
+);
 ```
 
 ## Sessions
@@ -69,45 +488,364 @@ export const completePassword = (userId: UserId) =>
 `Sessions` is the server-side session authority. Transports such as cookies are separate services so browser, API, and custom transports can share the same session strategy.
 
 ```ts
-import { Effect } from "effect"
-import type { UserId } from "@effect-auth/core/Identifiers"
-import { SessionCookie, Sessions } from "@effect-auth/core/Sessions"
+import { Effect } from "effect";
+import type { UserId } from "@effect-auth/core/Identifiers";
+import { SessionCookie, Sessions } from "@effect-auth/core/Sessions";
 
 export const createBrowserSession = (userId: UserId) =>
   Effect.gen(function* () {
-    const sessions = yield* Sessions
-    const sessionCookie = yield* SessionCookie
+    const sessions = yield* Sessions;
+    const sessionCookie = yield* SessionCookie;
 
     const issued = yield* sessions.create({
       userId,
       method: "password",
       amr: ["pwd"],
-      aal: "aal1"
-    })
+      aal: "aal1",
+      claims: {
+        emailVerified: false,
+        requirements: ["email_verification"],
+      },
+    });
 
-    const cookie = yield* sessionCookie.commit(issued)
+    const cookie = yield* sessionCookie.commit(issued);
 
-    return { issued, cookie }
-  })
+    return { issued, cookie };
+  });
+```
+
+`SessionClaims` are a safe, transport-visible session summary. They currently include `emailVerified` and `requirements`, and are returned by password auth success, current-session, and refresh HTTP responses when present. Use `Sessions.updateClaims` to update an active session without rotating the opaque session token. Effect-QB storage persists claims in the existing `auth_session.metadata` column, so no additional storage migration is required.
+
+Password auth passes the user's email verification state into `AuthFlow`, where `EmailVerificationSessionPolicy` decides whether unverified users get a normal session or a constrained session. The default mode is `allow-unverified` for compatibility. Use `limited-session` to issue sessions with an `email_verification` requirement. Per-login email approval is a separate `UserSecurityPolicy` / `LoginApprovalPolicy` concern, not an email verification session mode.
+
+```ts
+import { AuthFlowLiveWithEmailVerificationPolicy } from "@effect-auth/core/AuthFlow";
+
+export const AllowUnverifiedAuthFlowLive =
+  AuthFlowLiveWithEmailVerificationPolicy({
+    mode: "allow-unverified",
+  });
+
+export const LimitedSessionAuthFlowLive =
+  AuthFlowLiveWithEmailVerificationPolicy({
+    mode: "limited-session",
+  });
+```
+
+For `limited-session`, protect sensitive app routes by requiring the current session to be email verified. This policy expects your route middleware to provide `CurrentSession`.
+
+```ts
+import { Effect } from "effect";
+import * as Policy from "@effect-auth/core/Policy";
+
+export const updateBillingSettings = Effect.gen(function* () {
+  return yield* saveBillingSettings();
+}).pipe(Policy.require(Policy.requireEmailVerified()));
+```
+
+`LoginApprovalPolicy` is a separate primary-factor decision for high-security sign-in flows. It decides whether a verified primary factor can continue to session creation or should require app-owned login approval. When `AuthFlow` has a `LoginApprovalFlow` and `AuthFlowState`, it stores the pending primary factor, issues a `login-approval` challenge, and returns `AuthResult.RequiresLoginApproval`. The HTTP response is `requires_login_approval` and includes only `flowId`, `approvalChallengeId`, `channel`, `sessionBinding`, `sameDeviceRequired`, and `reason`.
+
+The built-in HTTP API completes approval with `POST /auth/login-approval/approve` using `flowId`, `approvalChallengeId`, and an optional challenge `secret`. It verifies the approval, checks the approval belongs to the pending `flowId`, consumes `AuthFlowState`, marks the user email verified when the approval requested it, and creates the session. `sessionBinding: "originating-device"` protects the pending auth flow state with an HttpOnly `__Host-login-approval` cookie secret; approving from another device fails before session creation. `sessionBinding: "approval-device"` creates the session on the device that completes approval. `sessionBinding: "none"` records an approval review but does not create a user session from the approval response; the originating device finalizes later with `LoginApprovalFinalize`.
+
+Custom policy code is the primary extension point. Presets such as `mode: "new-device"` are convenience defaults for simple apps; high-security apps should model product-specific risk logic directly in `LoginApprovalPolicy.custom`.
+
+```ts
+import { Effect, Layer } from "effect";
+import { AuthFlowStateLive, AuthFlowLive } from "@effect-auth/core/AuthFlow";
+import {
+  LoginApprovalDecision,
+  LoginApprovalDeliveryFromAuthMailerLive,
+  LoginApprovalFlowLive,
+  LoginApprovalLive,
+  LoginApprovalPolicy,
+  LoginApprovalPolicyLive,
+} from "@effect-auth/core/LoginApproval";
+import {
+  LoginRiskContext,
+  LoginRiskEngine,
+  LoginRiskSignal,
+} from "@effect-auth/core/LoginRisk";
+
+export const SimpleEmailApprovalPolicyLive = LoginApprovalPolicyLive({
+  mode: "new-device",
+  channel: "email",
+  sessionBinding: "originating-device",
+  requireForUnverifiedEmail: true,
+  skipMethods: ["passkey"],
+  skipWhenAalAtLeast: "aal2",
+});
+
+export const RiskBasedApprovalPolicyLive = Layer.succeed(
+  LoginApprovalPolicy,
+  LoginApprovalPolicy.custom((input) =>
+    Effect.succeed(
+      input.risk.hasSignal("impossible-travel")
+        ? LoginApprovalDecision.emailCode({
+            reason: "impossible-travel",
+          })
+        : LoginApprovalDecision.continue()
+    )
+  )
+);
+
+export const AppLoginRiskEngineLive = Layer.succeed(
+  LoginRiskEngine,
+  LoginRiskEngine.custom((input) =>
+    Effect.succeed(
+      input.request?.country === "AU"
+        ? LoginRiskContext.make({
+            level: "critical",
+            signals: [
+              LoginRiskSignal.make({
+                type: "impossible-travel",
+                level: "critical",
+              }),
+            ],
+          })
+        : LoginRiskContext.make({ level: "low", signals: [] })
+    )
+  )
+);
+
+export const AppLoginApprovalLive = Layer.mergeAll(
+  AppLoginRiskEngineLive,
+  AuthFlowStateLive(),
+  LoginApprovalLive(),
+  LoginApprovalFlowLive,
+  LoginApprovalDeliveryFromAuthMailerLive,
+  AuthFlowLive
+);
 ```
 
+The default preset policy is `mode: "never"`. Passkeys or other high-assurance methods can bypass preset approval with `skipMethods` or `skipWhenAalAtLeast`. Approval `channel` and `reason` are open strings, so apps can model `admin`, `sms`, `push`, `manual-review`, or risk-specific reasons without extending core. `LoginApprovalDecision.emailCode`, `emailLink`, `sms`, `adminReview`, and `custom` set semantic `sessionBinding`; `sameDeviceRequired` remains available as the low-level legacy flag. `adminReview` uses `sessionBinding: "none"`, `LoginApprovalReview.approve` / `deny` record the out-of-band decision, and `LoginApprovalFinalize.complete` creates the session only for the originating device. Email is required only for the built-in email delivery path; non-email channels can omit it and use a custom `LoginApprovalDelivery`. `AuthFlow` always supplies policy with typed `device` and `risk`; the default risk engine returns `LoginRiskContext.make({ level: "unknown", signals: [] })`, and apps can provide `LoginRiskEngine` to calculate impossible travel, IP reputation, tenant policy, or other risk signals. `LoginRiskContext` and `LoginRiskSignal` are `Schema.Class` values, so custom engines should return `LoginRiskContext.make(...)`; policies can use helpers such as `input.risk.hasSignal(...)`, `input.risk.getSignal(...)`, and `input.risk.isAtLeast(...)`. `LoginRiskEngine` receives request context only when the primary-factor integration supplies it; core does not trust proxy or geo headers by default.
+
+`LoginApproval.inspect` validates a login approval challenge without consuming it. Use it for GET preview pages or admin panels that need to display pending approval details. For admin, push, or Slack approvals, configure `LoginApprovalReview` with a persistent store, let the out-of-band actor call `approve` or `deny`, then have the user's original browser poll review status and call `LoginApprovalFinalize.complete` with its pending-cookie secret. The built-in HTTP API exposes this originating-browser path as `POST /auth/login-approval/status` and `POST /auth/login-approval/finalize`, also available as `client.loginApproval.status(...)` and `client.loginApproval.finalize(...)`. `EffectQbSqliteAuthStorageLive` provides durable `LoginApprovalReviewStore`; the included `LoginApprovalReviewStoreMemoryLive` is for tests and local composition.
+
+`AuthFlowState` stores a short-lived, single-use pending primary-factor result in the existing challenge store. It is the bridge between “password/passkey/OTP verified” and “approval/MFA completed, now create a session”. The stored state contains `userId`, `method`, `amr`, `aal`, optional session claims, and app metadata such as `redirectTo`.
+
+```ts
+import { AuthFlowStateLive } from "@effect-auth/core/AuthFlow";
+
+export const AppAuthFlowStateLive = AuthFlowStateLive();
+```
+
+## Trusted Devices
+
+`TrustedDevice` is a small boundary for “remember this device” login policy. It stores only an HMAC hash of an opaque device token and returns `LoginDeviceContext` as `unknown`, `new`, or `known`. `LoginApprovalPolicy({ mode: "new-device" })` can use that context to require approval only for first-time devices.
+
+```ts
+import { Layer, Redacted } from "effect";
+import {
+  TrustedDeviceCookieLive,
+  TrustedDeviceLive,
+  TrustedDeviceStoreMemoryLive,
+} from "@effect-auth/core/TrustedDevice";
+
+export const AppTrustedDeviceLive = Layer.mergeAll(
+  TrustedDeviceStoreMemoryLive,
+  TrustedDeviceLive({ secret: Redacted.make("trusted-device-secret") }),
+  TrustedDeviceCookieLive()
+);
+```
+
+The built-in password sign-in, email OTP verify, and magic-link verify HTTP handlers read the HttpOnly `__Host-auth-device` cookie when `TrustedDeviceCookie` is provided and pass the trusted-device token into `AuthFlow`; `AuthFlow` resolves the device status centrally with `TrustedDevice`. `POST /auth/login-approval/approve` accepts `rememberDevice: true`; when `TrustedDevice` and `TrustedDeviceCookie` are provided it trusts the approved user/device and sets `__Host-auth-device` with the final session response. `EffectQbSqliteAuthStorageLive` provides durable `TrustedDeviceStore`; the in-memory store is intended for tests and local composition.
+
 ## Challenge
 
 `Challenge` is the shared primitive for short-lived proofs: email OTP, magic link, passkey challenges, OAuth state, reset password, and MFA.
 
 ```ts
-import { Duration, Effect, Redacted } from "effect"
-import { Challenge } from "@effect-auth/core/Challenge"
+import { Duration, Effect, Redacted } from "effect";
+import { Challenge } from "@effect-auth/core/Challenge";
 
 export const issueEmailOtp = (email: string, code: string) =>
   Effect.gen(function* () {
-    const challenge = yield* Challenge
+    const challenge = yield* Challenge;
 
     return yield* challenge.issue({
       type: "email-otp",
       subject: email,
       ttl: Duration.minutes(10),
-      secret: Redacted.make(code)
-    })
-  })
+      secret: Redacted.make(code),
+    });
+  });
+```
+
+## Email Verification
+
+`EmailVerification` composes `Challenge` with `UserStore.markEmailVerified`. It issues an `email-verification` challenge for an unverified user email, then verifies the challenge and marks the user email as verified. `EmailVerificationFlow` adds the app-owned `EmailDelivery` port so issuing and sending happen together without baking a mail provider into core.
+
+```ts
+import { Effect, Redacted } from "effect";
+import {
+  EmailDelivery,
+  EmailVerification,
+  EmailVerificationFlow,
+} from "@effect-auth/core/EmailVerification";
+import type { ChallengeId, Email, UserId } from "@effect-auth/core/Identifiers";
+
+const emailDelivery = EmailDelivery.make({
+  sendEmailVerification: ({ email, secret, challengeId }) =>
+    sendMail({
+      to: email,
+      subject: "Verify your email",
+      body:
+        secret === undefined
+          ? `Open /verify-email?challenge=${challengeId}`
+          : `Your verification code is ${Redacted.value(secret)}`,
+    }),
+});
+
+export const startEmailVerification = (
+  userId: UserId,
+  email: Email,
+  code: string
+) =>
+  Effect.gen(function* () {
+    const flow = yield* EmailVerificationFlow;
+
+    return yield* flow.start({
+      userId,
+      email,
+      secret: Redacted.make(code),
+    });
+  });
+
+export const verifyEmail = (challengeId: ChallengeId, code: string) =>
+  Effect.gen(function* () {
+    const emailVerification = yield* EmailVerification;
+
+    return yield* emailVerification.verify({
+      challengeId,
+      secret: Redacted.make(code),
+    });
+  });
+```
+
+## Storage
+
+Storage is exposed as ORM-free ports. Core flows depend on store services, while Effect-QB, future Drizzle, or app-owned adapters provide the implementations.
+
+```ts
+import { Effect, Option } from "effect";
+import {
+  CredentialStore,
+  SessionStore,
+  UserStore,
+  VerificationStore,
+} from "@effect-auth/core/Storage";
+
+const UserStoreLive = UserStore.make({
+  findById: () => Effect.succeed(Option.none()),
+  findByEmail: () => Effect.succeed(Option.none()),
+  insert: () => Effect.void,
+  markEmailVerified: () => Effect.succeed(Option.none()),
+});
+
+const CredentialStoreLive = CredentialStore.make({
+  findPasswordByUserId: () => Effect.succeed(Option.none()),
+  insertPassword: () => Effect.void,
+});
+
+const SessionStoreLive = SessionStore.make({
+  findById: () => Effect.succeed(Option.none()),
+  insert: () => Effect.void,
+  refresh: () => Effect.succeed(Option.none()),
+  rotate: () => Effect.succeed(Option.none()),
+  revoke: () => Effect.void,
+  revokeAllForUser: () => Effect.void,
+});
+
+const VerificationStoreLive = VerificationStore.make({
+  findById: () => Effect.succeed(Option.none()),
+  insert: () => Effect.void,
+  consume: () => Effect.succeed(Option.none()),
+  deleteExpired: () => Effect.succeed(0),
+});
+```
+
+The default schema is exported as SQL and as package assets:
+
+```ts
+import { authStorageMigrations } from "@effect-auth/core/StorageMigrations";
+```
+
+Effect-QB SQLite/D1 storage is the first-party durable adapter. The default path uses the auth schema and requires no table mapping:
+
+```ts
+import { EffectQbSqliteAuthStorageLive } from "@effect-auth/core/EffectQbSqliteStorage";
+
+const StorageLive = EffectQbSqliteAuthStorageLive(executor);
+```
+
+`EffectQbSqliteAuthStorageLive` provides all durable auth stores in the default schema, including the OAuth provider-token vault for already-encrypted provider token ciphertexts. Apps still own provider-token encryption and KMS/secrets-service policy before values reach storage.
+
+For Cloudflare D1, create an effect-qb SQLite executor from the D1 binding:
+
+```ts
+import {
+  EffectQbSqliteAuthStorageLive,
+  makeD1EffectQbSqliteExecutor,
+} from "@effect-auth/core/EffectQbSqliteStorage";
+
+const executor = makeD1EffectQbSqliteExecutor(env.DB);
+const StorageLive = EffectQbSqliteAuthStorageLive(executor);
+```
+
+Applications with their own Effect-QB tables can map semantic auth fields to app-owned columns with `defineEffectQbAuthTables`:
+
+```ts
+import { Column, Query, Table } from "effect-qb/sqlite";
+import {
+  defineEffectQbAuthTables,
+  EffectQbSqliteAuthStorageLive,
+} from "@effect-auth/core/EffectQbSqliteStorage";
+
+const users = Table.make("users", {
+  user_id: Column.text().pipe(Column.primaryKey),
+  email_address: Column.text(),
+  verified_at: Column.int().pipe(Column.nullable),
+  inserted_at: Column.int(),
+  updated_at: Column.int(),
+  disabled_at: Column.int().pipe(Column.nullable),
+  metadata_json: Column.text().pipe(Column.nullable),
+});
+
+const authTables = defineEffectQbAuthTables({
+  user: {
+    table: users,
+    select: {
+      id: users.user_id,
+      email: users.email_address,
+      emailVerified: users.verified_at,
+      createdAt: users.inserted_at,
+      updatedAt: users.updated_at,
+      disabledAt: users.disabled_at,
+      metadata: users.metadata_json,
+    },
+    insert: (row) =>
+      ({
+        user_id: row.id,
+        email_address: row.email,
+        verified_at: row.emailVerified ? Number(row.updatedAt) : null,
+        inserted_at: Number(row.createdAt),
+        updated_at: Number(row.updatedAt),
+        disabled_at:
+          row.disabledAt === undefined ? null : Number(row.disabledAt),
+        metadata_json:
+          row.metadata === undefined ? null : JSON.stringify(row.metadata),
+      }) satisfies Query.MutationInputOf<Table.InsertOf<typeof users>>,
+    markEmailVerified: (input) =>
+      ({
+        verified_at: Number(input.updatedAt),
+        updated_at: Number(input.updatedAt),
+      }) satisfies Query.MutationInputOf<Table.UpdateOf<typeof users>>,
+  },
+
+  // credential/session/verification/review/trusted-device/passkey/TOTP/recovery-code/API-key/refresh-token/OAuth-account/provider-token-vault mappings follow the same pattern.
+});
+
+const StorageLive = EffectQbSqliteAuthStorageLive(executor, {
+  tables: authTables,
+});
 ```