@effect-auth/core 0.1.0-alpha.16 → 0.1.0-alpha.19

package/README.md

@@ -6,44 +6,71 @@ The current alpha surface is primitive-first: service contracts, small helpers,
 
 ## Public API Surface
 
-The root import is the stable alpha primitive surface:
+The root entry is metadata-only:
 
 ```ts
-import { PasswordLogin, Sessions, UserId } from "@effect-auth/core";
+import { packageName } from "@effect-auth/core";
 ```
 
-Root exports are runtime-neutral auth primitives, service contracts, factory functions, reference layers, identifiers, storage ports, and policy helpers. They should not require framework, database, Cloudflare, Alchemy, SimpleWebAuthn, or test-only dependencies.
+Import every auth primitive, service, layer, identifier, and integration from its named public subpath:
 
-Primitive module subpaths mirror the root surface for focused imports and are also stable alpha API. Examples include `@effect-auth/core/Password`, `@effect-auth/core/Sessions`, `@effect-auth/core/OAuth`, `@effect-auth/core/Jwt`, `@effect-auth/core/ApiKey`, `@effect-auth/core/Storage`, and `@effect-auth/core/StorageMigrations`.
+```ts
+import { UserId } from "@effect-auth/core/Identifiers";
+import { PasswordLogin } from "@effect-auth/core/Password";
+import { Sessions } from "@effect-auth/core/Sessions";
+```
+
+Runtime-neutral primitive subpaths are stable alpha API. Examples include `@effect-auth/core/Password`, `@effect-auth/core/Sessions`, `@effect-auth/core/OAuth`, `@effect-auth/core/Jwt`, `@effect-auth/core/ApiKey`, `@effect-auth/core/Storage`, and `@effect-auth/core/RateLimiter`.
+
+Utility subpaths are stable alpha APIs:
+
+```txt
+@effect-auth/core/StorageMigrations
+```
 
 Integration subpaths are public but opt-in. They may expose runtime-specific or transport-specific types and require the app to install their adapter packages when used:
 
 ```txt
 @effect-auth/core/Client
 @effect-auth/core/HttpApi
-@effect-auth/core/EffectQbSqliteStorage
-@effect-auth/core/RateLimiter
+@effect-auth/core/PasskeyBrowser
 ```
 
-Adapter subpaths are public alpha adapters. Their names may still be normalized before beta:
+Storage and runtime adapter subpaths are public alpha adapters. Their names may still be normalized before beta:
 
 ```txt
+@effect-auth/core/EffectQbSqliteStorage
+@effect-auth/core/DrizzleEffectSqliteStorage
+@effect-auth/core/DrizzleD1SqliteStorage
+@effect-auth/core/DrizzleBunSqliteStorage
+@effect-auth/core/DrizzleNodeSqliteStorage
 @effect-auth/core/CloudflareEmail
+@effect-auth/core/CloudflareRequestMetadata
 @effect-auth/core/CloudflareRateLimitDurableObject
 @effect-auth/core/AlchemyCloudflareEmail
 @effect-auth/core/AlchemyCloudflareRateLimitDurableObject
 @effect-auth/core/PasskeySimpleWebAuthn
+@effect-auth/core/StorageSchemaGenerator
+@effect-auth/core/DevelopmentSeed
 ```
 
 `@effect-auth/core/Testing` is test/dev-only API. Do not wire it into production applications.
 
-SQL migrations are packaged as files for copy/read workflows, but the supported TypeScript API is `@effect-auth/core/StorageMigrations` and `authStorageMigrations`. Raw SQL files are not importable package subpaths.
+SQL migrations are packaged as files for copy/read workflows, but the supported TypeScript APIs are `authStorageMigrations` from `@effect-auth/core/StorageMigrations` and `postgresAuthStorageMigrations` from `@effect-auth/core/PostgresStorageMigrations`. Raw SQL files are not importable package subpaths.
+
+For fresh PostgreSQL or SQLite/D1 schema planning, `@effect-auth/core/StorageSchemaGenerator` exposes the same deterministic feature resolver used by the public API at `https://effect-auth.itsbroly.com/api/generator/v1`. Tools and AI agents should call `/catalog`, choose the database and adapter, then request `migration-sql`, `development-seed`, and, for Drizzle, `drizzle-schema`; they should not infer physical tables from store service types. `@effect-auth/core/DevelopmentSeed` provides the fixed 100-user, development-only runtime program used by generated seed launchers. Maintained runtime bridges are available for Drizzle PostgreSQL, D1, Bun SQLite, Node SQLite, and application-provided Effect SQLite databases.
+
+Before beta, breaking changes are still allowed when they simplify this API surface. Keep the root metadata-only and add public APIs through explicit subpaths.
+
+### Cloudflare Request Metadata
+
+`@effect-auth/core/CloudflareRequestMetadata` is an opt-in Worker-boundary adapter for login-risk composition. It uses structural request types and reads geographic facts from Cloudflare's `request.cf`. Client IP is omitted unless `trustCloudflareConnectingIp` is explicitly enabled at a verified Cloudflare boundary. It does not require `@cloudflare/workers-types`, `nodejs_compat`, or an IP database.
 
-Before beta, breaking changes are still allowed when they simplify this API surface. Prefer adding new app-specific code through subpaths instead of expanding the root barrel.
+Call `readCloudflareRequestMetadata(request)` in Worker-owned code, then pass its coarse `request`, `locationKey`, and safe `metadata` fields into custom risk composition. Missing or malformed preview metadata produces unknown fields rather than an error. Never construct the input from browser JSON or forwarded geographic headers. Persist only the returned `durable` projection; the full result may contain transient IP and city values.
 
 ## 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.
+`@effect-auth/core/Client` exposes one browser-friendly client for the standard user-facing auth groups. Applications still choose which groups to mount and which policies to apply on the server. The client 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";
@@ -56,13 +83,100 @@ const result = await authClient.password.signIn({
 });
 
 const session = await authClient.session.currentOrUndefined();
+
+if (authClient.passkey.isSupported()) {
+  await authClient.passkey.signIn();
+}
 ```
 
+`createAuthClient()` also includes combined email auth, passkeys, TOTP, recovery codes, login MFA, and step-up. Its passkey methods complete the standard start/browser/finish sequence. The focused `createPasskeyClient`, `createTotpClient`, `createMfaClient`, and other factories remain available for custom paths and low-level protocol control.
+
+Authentication continuations such as `requires_mfa`, `requires_email_verification`, and `requires_login_approval` are successful protocol results, not exceptions. Handle the returned discriminated union in the UI.
+
 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.
 
+### HTTP Operations
+
+Applications that own their routes can use the per-feature operation services instead of mounting the built-in API groups. Every built-in HTTP API group has a corresponding portable, typed operations service and `Live` layer. Each layer acquires its feature dependencies once and exposes ready endpoint operations with the same responses, cookies, errors, optional-service behavior, extension hooks, configuration, and security checks as the built-in handlers.
+
+```ts
+import { Effect } from "effect";
+import {
+  PasswordHttpOperations,
+  PasswordHttpOperationsLive,
+  type PasswordHttpOperationsService,
+} from "@effect-auth/core/HttpApi/Password";
+
+const signIn = (
+  input: Parameters<PasswordHttpOperationsService["signIn"]>[0]
+) => PasswordHttpOperations.use((operations) => operations.signIn(input));
+
+// Provide PasswordLogin, PasswordRegistration, PasswordReset,
+// PasswordManagement, Sessions, SessionCookie, AuthHttp,
+// EmailVerificationFlow, and an explicit AuthRateLimit layer.
+const PasswordRoutesLive = PasswordHttpOperationsLive;
+```
+
+`@effect-auth/core/HttpApi/Password` also exports the standalone `PasswordHttpApiLive` preset and the password endpoint contracts without loading the full server API assembly. The broad `@effect-auth/core/HttpApi` entry remains the aggregate boundary for `CoreAuthHttpApiLive` and cross-feature composition.
+
+Feature operation services can also be replaced directly in tests with `FeatureHttpOperations.of(...)`. Secured feature layers always require `AuthRateLimit`; they never install a no-op implementation.
+
+### Client Composition
+
+The standard client is a starting point rather than an all-or-nothing abstraction. Its `protocol` option is a deep patch:
+
+- omitted properties keep the standard implementation,
+- functions and objects replace or extend it,
+- `null` removes an operation or group,
+- `extensions` adds app-owned auth operations under a collision-free namespace.
+
+```ts
+const auth = createAuthClient({
+  protocol: {
+    passkey: null,
+    password: {
+      signUp: customSignUp,
+    },
+    extensions: {
+      organization: {
+        select: selectActiveOrganization,
+      },
+    },
+  },
+});
+
+await auth.password.signUp(customInput);
+await auth.extensions.organization.select({ organizationId: "org-1" });
+```
+
+Literal `null` values also remove the corresponding property from the inferred client type.
+
+Use `defineAuthHttpApiExtension` for an app-owned auth `HttpApi` contract that should share the standard client's base URL, Fetch configuration, cookies, cancellation, runtime, and disposal:
+
+```ts
+const appAuthExtension = defineAuthHttpApiExtension(
+  AppAuthExtensionApi,
+  ({ run }) => ({
+    discoverSso: (email: string, options?: AuthClientRequestOptions) =>
+      run(
+        (client) => client.appAuth.discoverSso({ payload: { email } }),
+        options
+      ),
+  })
+);
+
+const auth = createAuthClient({
+  protocol: { extensions: appAuthExtension },
+});
+
+await auth.extensions.discoverSso("reader@example.com");
+```
+
+Extension contracts should contain browser-safe endpoint/schema declarations, use unique group identifiers, and require no client-side middleware services. Product APIs that merely require an auth cookie should remain separate from the auth client.
+
 ## Policy
 
-`Policy` is an `Effect` used for authorization. Success means access is allowed. `AuthzError` means access is denied. Other failures stay operational errors.
+`Policy` is an `Effect` used for authorization. Success means access is allowed. `AuthorizationError` means access is denied. Other failures stay operational errors.
 
 ```ts
 import { Effect } from "effect";
@@ -80,6 +194,29 @@ 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.
 
+Permission policies read a trusted `CurrentPrincipal`, not session-specific
+`CurrentActor`. `Permissions` checks are subject-first, so the same policy seam
+can authorize a user, service account, API key, or another app-defined subject:
+
+```ts
+import { Effect } from "effect";
+import {
+  CurrentPrincipal,
+  PermissionSubject,
+} from "@effect-auth/core/Permission";
+
+const principal = PermissionSubject.user(validated.actor.userId);
+
+const authorized = operation.pipe(
+  Effect.provideService(CurrentPrincipal, CurrentPrincipal.of(principal))
+);
+```
+
+`CurrentActor` remains the authenticated session context containing `userId`
+and `sessionId`. Credential adapters must choose the authorization principal
+explicitly at a trusted boundary; never accept it from request input. Machine
+credential scopes and durable permissions are cumulative restrictions.
+
 Policies compose with `all`, `any`, and `not`:
 
 ```ts
@@ -162,12 +299,13 @@ const AuthPrivacyLive = PrivacyLive({
 });
 ```
 
-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.
+The built-in HTTP auth API consumes standard limits through `AuthRateLimitStandardLive(config)`. Production deployments provide a durable `RateLimiter` store and HMAC `Privacy` secret. In `config`, an undefined operation uses its standard rules, a rule array replaces them, and `null` disables that operation. `AuthServicesLive` below stands for your app-owned auth service wiring.
 
 ```ts
-import { Layer, Redacted } from "effect";
+import { Duration, Layer, Redacted } from "effect";
 import { RateLimiter as PersistenceRateLimiter } from "effect/unstable/persistence";
-import { AuthHttpApiLive } from "@effect-auth/core/HttpApi";
+import { AuthRateLimitStandardLive } from "@effect-auth/core/AuthRateLimit";
+import { CoreAuthHttpApiLive } from "@effect-auth/core/HttpApi";
 import {
   RateLimitStoreDurableObject,
   type CloudflareRateLimitDurableObjectNamespace,
@@ -184,29 +322,43 @@ export const makeAuthHttpApiLayer = (
     Layer.provide(RateLimitStoreDurableObject.layer({ namespace }))
   );
 
-  return AuthHttpApiLive.pipe(
+  return CoreAuthHttpApiLive.pipe(
     Layer.provide(AuthServicesLive),
+    Layer.provide(
+      AuthRateLimitStandardLive({
+        // Keep standard sign-in rules, replace sign-up, disable reset-start.
+        "auth.password.sign_up": [
+          {
+            id: "app.password.sign_up.ip",
+            key: "ip",
+            limit: 5,
+            window: Duration.hours(1),
+          },
+        ],
+        "auth.password.reset_start": null,
+      })
+    ),
     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:
+`AuthRateLimitStandardLive()` applies all standard rules. The explicit escape hatch is `AuthRateLimitNoopLive`; use it only when another boundary enforces equivalent controls or while deliberately running without them:
 
 ```ts
 import { Layer } from "effect";
-import { AuthHttpApiBareLive } from "@effect-auth/core/HttpApi";
+import { AuthRateLimitNoopLive } from "@effect-auth/core/AuthRateLimit";
+import { CoreAuthHttpApiLive } from "@effect-auth/core/HttpApi";
 
-export const AuthHttpApiLayer = AuthHttpApiBareLive.pipe(
-  Layer.provide(AuthServicesLive)
+export const AuthHttpApiLayer = CoreAuthHttpApiLive.pipe(
+  Layer.provide(AuthServicesLive),
+  Layer.provide(AuthRateLimitNoopLive)
 );
 ```
 
+App-owned workflows can use `RateLimiter.require`, `StepUp`/`Policy` requirements, and `Guard.requireAll` directly. At an HTTP boundary, pipe the composed effect through `mapAuthGuardErrors` so rate-limit, step-up, policy, privacy, and permission failures become the declared auth HTTP errors while unrelated application errors remain unchanged.
+
 ## AuthFlow
 
 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.
@@ -240,7 +392,7 @@ declare const issuedSession: IssuedSession;
 
 const AuthFlowLive = Layer.succeed(
   AuthFlow,
-  AuthFlow.make({
+  AuthFlow.of({
     startPrimaryFactor: () =>
       Effect.succeed(AuthResult.PolicyDenied({ reason: "test" })),
     completePrimaryFactor: () =>
@@ -255,6 +407,31 @@ const AuthFlowLive = Layer.succeed(
 
 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 reference flow is a resumable pipeline. It assesses risk before deciding whether MFA is required, resumes the same risk and approval path after MFA, and preserves MFA freshness through a later login-approval challenge. Applications can provide `AuthFlowPipeline` to run app-owned policy checks or deny the flow without replacing the reference orchestration. Pipeline stages cannot replace authentication state, claims, risk, or trusted request facts:
+
+```ts
+import { Effect, Layer } from "effect";
+import {
+  AuthFlowLive,
+  AuthFlowPipeline,
+  AuthFlowPipelineLive,
+} from "@effect-auth/core/AuthFlow";
+
+const AppAuthPipelineLive = AuthFlowPipelineLive([
+  {
+    phases: ["before-login-approval"],
+    run: (context) =>
+      invitationIsValid(context.input)
+        ? Effect.succeed(AuthFlowPipeline.continueWith())
+        : Effect.succeed(AuthFlowPipeline.deny("Invitation required")),
+  },
+]);
+
+const AppAuthFlowLive = AuthFlowLive.pipe(Layer.provide(AppAuthPipelineLive));
+```
+
+Available phases are `before-risk`, `after-risk`, `before-mfa`, `after-mfa`, and `before-login-approval`. Every stage receives `mfaSatisfied`, so stages can distinguish the initial primary-factor pass from a resumed MFA flow. Stages run again when the flow resumes; side effects that must execute exactly once should use an idempotency key or inspect `mfaSatisfied`.
+
 The first default live implementations are available for the phase-3 web session path:
 
 ```ts
@@ -340,17 +517,17 @@ const PasswordHashingLive = Layer.mergeAll(
 
 ## 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.
+`@effect-auth/core/HttpApi` contains the first Effect v4 HttpApi contract for the built-in auth surface. It exports `CoreAuthHttpApi`, 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 { CoreAuthHttpApiLive } from "@effect-auth/core/HttpApi";
 import { PrivacyLive } from "./auth/privacy";
 import { RateLimiterLive } from "./auth/rate-limiter";
 
 export const AuthRoutesLive = HttpRouter.serve(
-  AuthHttpApiLive.pipe(
+  CoreAuthHttpApiLive.pipe(
     Layer.provide(AuthServicesLive),
     Layer.provide(RateLimiterLive),
     Layer.provide(PrivacyLive)
@@ -360,25 +537,25 @@ export const AuthRoutesLive = HttpRouter.serve(
 
 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`. |
+| 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.
+`CoreAuthHttpApiLive` wires the full built-in surface. Apps can own the final HTTP contract and reuse individual endpoints, services, and the public OAuth/WebAuthn protocol adapters 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.
+`SessionHttpApiGroup` 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 })`.
+`CoreAuthHttpApiLive` includes `AuthOriginCheckMiddlewareLive()` for cookie-based unsafe methods and requires an `AuthRateLimit` service for built-in operation limits. 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(CoreAuthHttpApi)` 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.
+`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 use `mapAuthGuardErrors` to map core guard failures to safe HTTP errors 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:
 
@@ -399,127 +576,93 @@ await fetch("/auth/session/refresh", {
 });
 ```
 
-`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:
+`AuthRequestMetadataMiddlewareLive()` can provide method, URL, origin, user-agent, and trusted proxy IP metadata to app-owned handlers. IP metadata uses direct request headers by default; set `requestMetadata.trustProxyHeaders` when your deployment terminates trusted proxy headers before the app:
 
 ```ts
-import { Duration, Layer } from "effect";
+import { Layer } from "effect";
+import { AuthRateLimitStandardLive } from "@effect-auth/core/AuthRateLimit";
 import {
   AuthHttpApiConfigLive,
-  AuthHttpApiLive,
+  CoreAuthHttpApiLive,
 } from "@effect-auth/core/HttpApi";
-import { PrivacyLive } from "./auth/privacy";
-import { RateLimiterLive } from "./auth/rate-limiter";
 
-export const AuthHttpApiLayer = AuthHttpApiLive.pipe(
+export const AuthHttpApiLayer = CoreAuthHttpApiLive.pipe(
   Layer.provide(
     AuthHttpApiConfigLive({
-      rateLimit: {
+      requestMetadata: {
         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(AuthRateLimitStandardLive()),
   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.
+`EmailVerificationHttpApiGroup` 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:
+Application workflow handlers belong in the app. Compose domain/application effects with guards, then map only guard failures into the endpoint's HTTP error contract:
 
 ```ts
-import { Effect, Schema } from "effect";
+import { Duration, Effect, Schema } from "effect";
 import {
   HttpApi,
   HttpApiBuilder,
   HttpApiEndpoint,
   HttpApiGroup,
 } from "effect/unstable/httpapi";
+import * as Guard from "@effect-auth/core/Guard";
+import * as RateLimiter from "@effect-auth/core/RateLimiter";
 import {
-  AuthBadRequestError,
-  AuthEmailAlreadyRegisteredError,
-  AuthHttp,
   AuthInternalError,
-  AuthOriginCheckMiddleware,
-  AuthPolicyDeniedError,
   AuthRateLimitedError,
-  AuthSchemaErrorMiddleware,
-  makePasswordSignInHandler,
-  passwordSignInEndpoint,
-  PasswordAuthSuccess,
+  mapAuthGuardErrors,
 } 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 updateProfileEndpoint = HttpApiEndpoint.post("update", "/profile", {
+  payload: Schema.Struct({ displayName: Schema.String }),
+  success: Schema.Struct({ updated: Schema.Boolean }),
+  error: [AuthRateLimitedError, AuthInternalError],
 });
 
-const phoneSignUpEndpoint = HttpApiEndpoint.post("signUp", "/sign-up", {
-  payload: PhoneSignUpBody,
-  success: PasswordAuthSuccess,
-  error: [
-    AuthBadRequestError,
-    AuthEmailAlreadyRegisteredError,
-    AuthPolicyDeniedError,
-    AuthRateLimitedError,
-    AuthInternalError,
-  ],
+const UpdateProfileRateLimit = RateLimiter.RateLimitPolicy.fixedWindow({
+  id: "app.profile.update",
+  key: RateLimiter.RateLimitKey.global,
+  limit: 20,
+  window: Duration.minutes(1),
 });
 
-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);
-        })
-      );
-  })
+class ProfileHttpApiGroup extends HttpApiGroup.make("profile")
+  .add(updateProfileEndpoint)
+  .prefix("/auth") {}
+
+class AppApi extends HttpApi.make("AppApi").add(ProfileHttpApiGroup) {}
+
+const updateProfile = (displayName: string) =>
+  Effect.succeed({ updated: displayName.length > 0 });
+
+export const ProfileHttpApiGroupLive = HttpApiBuilder.group(
+  AppApi,
+  "profile",
+  (handlers) =>
+    handlers.handle(
+      "update",
+      Effect.fn("app.auth.profile.update")(function* ({ payload }) {
+        return yield* updateProfile(payload.displayName).pipe(
+          Guard.requireAll(RateLimiter.require(UpdateProfileRateLimit)),
+          mapAuthGuardErrors
+        );
+      })
+    )
 );
 ```
 
+Use `Guard.requireAll` with `RateLimiter.require(...)`, `AuthRateLimit.require(...)`, direct `StepUp` effects, direct `Policy` effects, or any app-owned guard. This keeps workflow ownership local instead of importing a thin core handler factory. `mapAuthGuardErrors` preserves unrelated domain errors, so include those separately in the endpoint error schema.
+
 ## 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.
@@ -556,15 +699,15 @@ export const createBrowserSession = (userId: UserId) =>
 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";
+import { AuthFlowWithEmailVerificationPolicyLive } from "@effect-auth/core/AuthFlow";
 
 export const AllowUnverifiedAuthFlowLive =
-  AuthFlowLiveWithEmailVerificationPolicy({
+  AuthFlowWithEmailVerificationPolicyLive({
     mode: "allow-unverified",
   });
 
 export const LimitedSessionAuthFlowLive =
-  AuthFlowLiveWithEmailVerificationPolicy({
+  AuthFlowWithEmailVerificationPolicyLive({
     mode: "limited-session",
   });
 ```
@@ -721,7 +864,7 @@ import {
 } from "@effect-auth/core/EmailVerification";
 import type { ChallengeId, Email, UserId } from "@effect-auth/core/Identifiers";
 
-const emailDelivery = EmailDelivery.make({
+const emailDelivery = EmailDelivery.of({
   sendEmailVerification: ({ email, secret, challengeId }) =>
     sendMail({
       to: email,
@@ -796,19 +939,19 @@ import {
   VerificationStore,
 } from "@effect-auth/core/Storage";
 
-const UserStoreLive = UserStore.make({
+const UserStoreLive = UserStore.of({
   findById: () => Effect.succeed(Option.none()),
   findByEmail: () => Effect.succeed(Option.none()),
   insert: () => Effect.void,
   markEmailVerified: () => Effect.succeed(Option.none()),
 });
 
-const CredentialStoreLive = CredentialStore.make({
+const CredentialStoreLive = CredentialStore.of({
   findPasswordByUserId: () => Effect.succeed(Option.none()),
   insertPassword: () => Effect.void,
 });
 
-const SessionStoreLive = SessionStore.make({
+const SessionStoreLive = SessionStore.of({
   findById: () => Effect.succeed(Option.none()),
   insert: () => Effect.void,
   refresh: () => Effect.succeed(Option.none()),
@@ -817,7 +960,7 @@ const SessionStoreLive = SessionStore.make({
   revokeAllForUser: () => Effect.void,
 });
 
-const VerificationStoreLive = VerificationStore.make({
+const VerificationStoreLive = VerificationStore.of({
   findById: () => Effect.succeed(Option.none()),
   insert: () => Effect.void,
   consume: () => Effect.succeed(Option.none()),
@@ -829,9 +972,10 @@ The default schema is exported as SQL and as package assets:
 
 ```ts
 import { authStorageMigrations } from "@effect-auth/core/StorageMigrations";
+import { postgresAuthStorageMigrations } from "@effect-auth/core/PostgresStorageMigrations";
 ```
 
-Effect-QB SQLite/D1 storage is the first-party durable adapter. The default path uses the auth schema and requires no table mapping:
+Effect-QB SQLite/D1 storage is a first-party durable adapter. The default path uses the auth schema and requires no table mapping:
 
 ```ts
 import { EffectQbSqliteAuthStorageLive } from "@effect-auth/core/EffectQbSqliteStorage";
@@ -841,6 +985,18 @@ const StorageLive = EffectQbSqliteAuthStorageLive(executor);
 
 `EffectQbSqliteAuthStorageLive` provides all durable auth stores in the default schema, including audit log storage, domain verification storage, and the OAuth provider-token vault for already-encrypted provider token ciphertexts. Apps still own provider-token encryption, KMS/secrets-service policy, DNS/HTTP proof checking, and tenant authorization before values reach storage.
 
+The native Effect-QB Postgres adapter also provides the complete grouped store set, including `PermissionStore`. Apply the exported Postgres migrations through `0009_auth_permissions`, then provide `EffectQbPostgresCoreStoresLive(sql)` or construct `makeEffectQbPostgresPermissionStore(executor)` directly.
+
+Application-owned queries can reuse the adapter's canonical table objects instead of redeclaring `Table.make(...)` metadata:
+
+```ts
+import { effectQbPostgresTables } from "@effect-auth/core/EffectQbPostgresStorage";
+
+const { user, session, permissionDefinition } = effectQbPostgresTables;
+```
+
+Use the public store services for auth mutations unless custom writes preserve the adapter's security and atomicity invariants.
+
 For Cloudflare D1, create an effect-qb SQLite executor from the D1 binding:
 
 ```ts
@@ -861,6 +1017,20 @@ import { DrizzleD1SqliteAuthStorageLive } from "@effect-auth/core/DrizzleD1Sqlit
 const StorageLive = DrizzleD1SqliteAuthStorageLive(env.DB);
 ```
 
+Runtime-specific Drizzle SQLite helpers are available for Node and Bun. They construct the matching Drizzle Effect SQLite database from the Effect SQL client layer, then reuse the same auth storage bridge:
+
+```ts
+import { DrizzleBunSqliteAuthStorageLive } from "@effect-auth/core/DrizzleBunSqliteStorage";
+
+const StorageLive = DrizzleBunSqliteAuthStorageLive({
+  filename: "auth.sqlite",
+});
+```
+
+Install the matching runtime package when using a runtime-specific subpath, such as `@effect/sql-sqlite-bun` or `@effect/sql-sqlite-node`.
+
+Database and ORM packages used only by storage subpaths are optional peers. The metadata-only root does not load them; install the matching optional peers for the adapter subpath your application imports.
+
 If your app already builds a Drizzle Effect SQLite database, use the generic subpath instead. This keeps D1-specific dependencies out of non-D1 runtimes:
 
 ```ts
@@ -874,9 +1044,11 @@ Both Drizzle paths use the same default auth schema and table mapping options as
 ```ts
 import { makeD1DrizzleEffectSqliteDatabase } from "@effect-auth/core/DrizzleD1SqliteStorage";
 
-const drizzle = yield* makeD1DrizzleEffectSqliteDatabase(env.DB, {
-  relations,
-});
+const drizzle =
+  yield *
+  makeD1DrizzleEffectSqliteDatabase(env.DB, {
+    relations,
+  });
 ```
 
 Applications with their own Effect-QB tables can map semantic auth fields to app-owned columns with `defineEffectQbAuthTables`:
@@ -932,7 +1104,9 @@ const authTables = defineEffectQbAuthTables({
   // credential/session/verification/audit/review/trusted-device/passkey/TOTP/recovery-code/API-key/refresh-token/OAuth-account/provider-token-vault/domain-verification mappings follow the same pattern.
 });
 
-const StorageLive = EffectQbSqliteAuthStorageLive(executor, {
+const StorageLive = EffectQbSqliteAuthStorageLive(executor, atomic, {
   tables: authTables,
 });
 ```
+
+Mappings used by atomic composite stores must select direct bound columns and return literal driver values from mutation functions. Expression-valued mutation mappings require an application-owned store implementation.