@effect-auth/core 0.1.0-alpha.1 → 0.1.0-alpha.2

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,87 +46,479 @@ 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")
-)
+);
+```
+
+## 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, denied } from "@effect-auth/core/AuthFlow"
+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(denied("policy-denied")),
-    completePrimaryFactor: () => Effect.succeed(denied("policy-denied")),
-    completeMfa: () => Effect.succeed(denied("policy-denied")),
-    complete: () => Effect.succeed(denied("policy-denied"))
+    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 { KyselyAuthStorageLive } from "@effect-auth/core/KyselyStorage";
+
+const AuthLive = Layer.mergeAll(
+  WebCryptoLive(),
+  KyselyAuthStorageLive(db),
+  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 password and session auth. It exports `AuthApi`, module-owned `PasswordApi` and `SessionApi` 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 `POST /auth/password/sign-in`, `POST /auth/password/sign-up`, `GET /auth/session`, `POST /auth/session/refresh`, `POST /auth/logout`, `POST /auth/email-verification/start`, and `POST /auth/email-verification/verify`.
+
+`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.
+
+Default password HTTP handlers start `EmailVerificationFlow` automatically when password sign-in or sign-up 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
 
 `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. Kysely 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 what happens before a session is created. The default mode is `allow-unverified` for compatibility. Use `limited-session` to issue sessions with an `email_verification` requirement, or `require-before-session` to return `RequiresEmailVerification` without creating a session.
+
+```ts
+import { AuthFlowLiveWithEmailVerificationPolicy } from "@effect-auth/core/AuthFlow";
+
+export const AllowUnverifiedAuthFlowLive =
+  AuthFlowLiveWithEmailVerificationPolicy({
+    mode: "allow-unverified",
+  });
+
+export const LimitedSessionAuthFlowLive =
+  AuthFlowLiveWithEmailVerificationPolicy({
+    mode: "limited-session",
+  });
+
+export const RequireBeforeSessionAuthFlowLive =
+  AuthFlowLiveWithEmailVerificationPolicy({
+    mode: "require-before-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()));
 ```
 
 ## Challenge
@@ -115,29 +526,97 @@ export const createBrowserSession = (userId: UserId) =>
 `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 Kysely, future Drizzle/effect-qb, or app-owned adapters provide the implementations.
+Storage is exposed as ORM-free ports. Core flows depend on store services, while Kysely, effect-qb, future Drizzle, or app-owned adapters provide the implementations.
 
 ```ts
-import { Effect, Option } from "effect"
-import { SessionStore, VerificationStore } from "@effect-auth/core/Storage"
+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()),
@@ -145,43 +624,47 @@ const SessionStoreLive = SessionStore.make({
   refresh: () => Effect.succeed(Option.none()),
   rotate: () => Effect.succeed(Option.none()),
   revoke: () => Effect.void,
-  revokeAllForUser: () => 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)
-})
+  deleteExpired: () => Effect.succeed(0),
+});
 ```
 
 The first storage adapter is Kysely-based. Applications own their Kysely instance and database dialect, while `@effect-auth/core/KyselyStorage` implements the auth store contracts:
 
 ```ts
-import { makeKyselyStorage } from "@effect-auth/core/KyselyStorage"
+import { makeKyselyStorage } from "@effect-auth/core/KyselyStorage";
 
-const { sessionStore, verificationStore } = makeKyselyStorage(db)
+const { userStore, credentialStore, sessionStore, verificationStore } =
+  makeKyselyStorage(db);
 ```
 
 For Cloudflare D1, use the first-party Kysely dialect instead of an external D1 dialect package:
 
 ```ts
-import { makeD1Kysely } from "@effect-auth/core/D1Kysely"
-import { KyselyAuthStorageLive, type KyselyAuthDatabase } from "@effect-auth/core/KyselyStorage"
+import { makeD1Kysely } from "@effect-auth/core/D1Kysely";
+import {
+  KyselyAuthStorageLive,
+  type KyselyAuthDatabase,
+} from "@effect-auth/core/KyselyStorage";
 
 interface DB extends KyselyAuthDatabase {
   // app tables live here too
 }
 
-const db = makeD1Kysely<DB>(env.DB)
-const StorageLive = KyselyAuthStorageLive(db)
+const db = makeD1Kysely<DB>(env.DB);
+const StorageLive = KyselyAuthStorageLive(db);
 ```
 
-The default schema expects `auth_session` and `auth_verification` tables in the Kysely database type:
+The default schema expects `auth_user`, `auth_credential`, `auth_session`, and `auth_verification` tables in the Kysely database type:
 
 ```ts
-import type { KyselyAuthDatabase } from "@effect-auth/core/KyselyStorage"
+import type { KyselyAuthDatabase } from "@effect-auth/core/KyselyStorage";
 
 interface DB extends KyselyAuthDatabase {
   // app tables live here too
@@ -191,5 +674,83 @@ interface DB extends KyselyAuthDatabase {
 The default schema is also exported as SQL and as package assets:
 
 ```ts
-import { authStorageMigrations } from "@effect-auth/core/StorageMigrations"
+import { authStorageMigrations } from "@effect-auth/core/StorageMigrations";
+```
+
+Effect-qb SQLite/D1 storage is also available. The default path uses the same auth schema and requires no table mapping:
+
+```ts
+import { EffectQbSqliteAuthStorageLive } from "@effect-auth/core/EffectQbSqliteStorage";
+
+const StorageLive = EffectQbSqliteAuthStorageLive(executor);
+```
+
+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 mappings follow the same pattern.
+});
+
+const StorageLive = EffectQbSqliteAuthStorageLive(executor, {
+  tables: authTables,
+});
 ```