@gauts/auth 0.2.2 → 0.3.1

package/README.md

@@ -1,55 +1,136 @@
 # `@gauts/auth`
 
-Reusable password authentication and opaque server-side sessions for Node.js applications.
+Reusable password authentication and database-backed opaque sessions for Node.js applications.
 
-`@gauts/auth` validates sessions through Redis and stores durable session history in a database. Redis is the authentication authority; the database is never used as an authentication fallback.
+The package stores only a SHA-256 token hash in the database. Browser integration uses three cookies with separate responsibilities:
+
+```text
+session cookie -> opaque token
+cache cookie   -> short signed session snapshot
+renew cookie   -> untrusted renewal marker
+```
+
+Only the opaque session token authenticates. It remains stable during sliding renewal, but the session can never exceed its configured maximum lifetime. The optional cache is disabled when omitted and never replaces database validation for unsafe methods, renewal, logout, WebSockets, or direct core calls.
 
 ## Requirements
 
 - Node.js 22 or newer.
-- A connected Redis client.
-- A Prisma client containing the required session model, or a custom `DbAdapter`.
-- Hono 4 when using the Hono adapter.
+- A database adapter, or a Prisma client containing the required schema contract.
+- Hono 4 when using `@gauts/auth/hono`.
+- Next.js 15 or newer when using `@gauts/auth/next`.
 
 ## Installation
 
-For Hono, Prisma, and Redis:
+For Hono and Prisma:
+
+```bash
+npm install @gauts/auth hono @prisma/client
+```
+
+For the Next.js adapter, the application must already use Next.js:
 
 ```bash
-npm install @gauts/auth hono redis @prisma/client
+npm install @gauts/auth next
 ```
 
-`hono` and `redis` are optional peer dependencies. The Prisma adapter does not import Prisma at runtime; it receives the generated client from the application.
+`hono` and `next` are optional peer dependencies. The Prisma adapter receives the consuming application's generated client and does not import Prisma at runtime.
+
+## Package entry points
+
+| Import | Purpose |
+| --- | --- |
+| `@gauts/auth` | Framework-independent password and session core types. |
+| `@gauts/auth/prisma` | Prisma implementation of the database adapter. |
+| `@gauts/auth/hono` | Hono cookies, session methods, and middleware. |
+| `@gauts/auth/next` | Next.js renewal scheduling and `Set-Cookie` forwarding. |
 
 ## Flow
 
 Login:
 
 ```text
-password -> configured algorithm -> database session row
-                                 -> Redis session
-                                 -> opaque HttpOnly cookie
+credentials accepted
+    -> generate 256-bit opaque token
+    -> store SHA-256 token hash in DB
+    -> load current account and user relations
+    -> validate configured status and role rules
+    -> write opaque session token cookie
+    -> write 24-hour renewal marker
+    -> optionally write signed short cache
 ```
 
-Authenticated HTTP request:
+Protected `GET` or `HEAD`:
 
 ```text
-cookie -> SHA-256 hash -> Redis -> client validation -> route
-                               -> renewal due -> database expiry
-                                              -> Redis TTL
-                                              -> cookie expiry
+opaque session token
+    -> valid signed cache bound to token and client?
+        -> yes: expose cached session, account, and user
+        -> no: perform indexed DB validation and issue a fresh cache
 ```
 
-The browser receives one random 256-bit opaque token. The token remains the same throughout the session. Redis and the database store only its SHA-256 hash.
+Unsafe methods and direct core calls:
 
-Sessions use sliding inactivity expiry. Activity before `renewInterval` performs no expiry write. The first eligible HTTP request after `renewInterval` extends the database expiry, Redis TTL, and browser cookie expiry.
+```text
+opaque session token
+    -> SHA-256 token
+    -> indexed DB lookup
+    -> expiry, revocation, account, user, and client validation
+    -> clear any existing cache after successful unsafe validation
+    -> route
+```
+
+Renewal:
 
-## Prisma model
+```text
+Next checks the renewal marker
+    -> marker exists: no API call
+    -> marker missing: POST /auth/renew
+    -> API performs full DB validation
+    -> DB expires_at = min(now + ttl, created_at + maxLifetime)
+    -> Set-Cookie with same token, a new marker, and a fresh cache
+```
 
-The default Prisma model is `auth_sessions`:
+`auth.session.resolve()` is always DB-backed and read-only. Only the explicit renewal operation updates database expiry, and neither activity nor renewal can extend the session beyond `maxLifetime`.
+
+## Prisma schema contract
+
+The Prisma adapter resolves authentication through this relation chain:
+
+```text
+account_sessions -> account -> user
+```
+
+The default Prisma client delegate is `account_sessions`. A different session model delegate can be selected through `config.table`.
+
+### Complete minimal schema
+
+This is a complete MySQL/MariaDB example. If `users` and `user_accounts` already exist, merge the required fields and relations into those models instead of duplicating them.
 
 ```prisma
-model auth_sessions {
+model users {
+  id      String @id @default(uuid()) @db.VarChar(255)
+  role    String @db.VarChar(255)
+  status  String @db.VarChar(255)
+
+  accounts user_accounts[]
+}
+
+model user_accounts {
+  id         String  @id @default(uuid()) @db.VarChar(255)
+  user_id    String  @db.VarChar(255)
+  email      String  @db.VarChar(255)
+  name       String  @db.VarChar(255)
+  role       String  @db.VarChar(255)
+  status     String  @db.VarChar(255)
+  timezone   String? @db.VarChar(255)
+
+  user     users              @relation(fields: [user_id], references: [id], onDelete: Cascade)
+  sessions account_sessions[]
+
+  @@index([user_id])
+}
+
+model account_sessions {
   id          String    @id @default(uuid()) @db.VarChar(255)
   account_id  String    @db.VarChar(255)
   token_hash  String    @unique @db.VarChar(64)
@@ -61,130 +142,202 @@ model auth_sessions {
   created_at  DateTime  @default(now()) @db.Timestamp(0)
   updated_at  DateTime? @db.Timestamp(0)
 
+  account user_accounts @relation(fields: [account_id], references: [id], onDelete: Cascade)
+
   @@index([account_id])
   @@index([expires_at])
   @@index([revoked_at])
 }
 ```
 
-These field names and compatible types are required. Additional indexes, relations, and optional/defaulted fields are allowed. Do not add required fields without defaults unless the application supplies them separately.
+The adapter requires these Prisma field and relation names:
 
-Create migrations through the consuming application's normal Prisma workflow. The package never creates or runs migrations.
+| Path | Required fields |
+| --- | --- |
+| Session model | `id`, `account_id`, `token_hash`, `ip`, `platform`, `agent`, `expires_at`, `revoked_at`, `created_at`, `updated_at` |
+| `account` relation | `id`, `email`, `name`, `role`, `status`, `timezone` |
+| `account.user` relation | `id`, `role`, `status` |
 
-## Quick start with Hono
+The relation fields must be named `account` and `user`, because those are the names selected by the adapter. Prisma also requires the inverse relations; their field names (`sessions` and `accounts` above) can be changed because the adapter never queries them.
 
-### 1. Define the session data
+Application models may contain additional fields, defaults, indexes, and relations. `role` and `status` may use application-specific Prisma enums instead of `String`; Prisma returns both as strings to the adapter. For other database providers, replace the native `@db.*` annotations with compatible types and keep `agent` large enough to store the complete User-Agent.
 
-The generic passed to `createHonoAuth` defines the application data cached in Redis and exposed on authenticated requests. Keep it small and never include secrets or password hashes.
+`config.table` is the Prisma client delegate name, not the physical database table name. For example, a Prisma model named `AdminSession` mapped with `@@map("account_sessions")` normally uses the `adminSession` delegate.
 
-```ts
-type AccountSession = {
-    email: string;
-    role: "admin" | "owner";
-};
-```
+Create migrations through the consuming application's normal Prisma workflow. The package never creates or runs migrations.
 
-### 2. Create one auth instance
+## Hono quick start
+
+The Hono adapter provides methods and middleware; it does not register routes automatically. The application remains responsible for creating its login, renewal, logout, and protected endpoints.
+
+### Create one auth instance
 
 ```ts
 import { createHonoAuth } from "@gauts/auth/hono";
-import { createDbAdapter } from "@gauts/auth/prisma";
-import { createRedisAdapter } from "@gauts/auth/redis";
+import { createPrismaAdapter } from "@gauts/auth/prisma";
 
-export const auth = createHonoAuth<AccountSession>({
-    getIp: (c) => getTrustedClientIp(c),
-    db: createDbAdapter({
+export const auth = createHonoAuth({
+    secret: process.env.AUTH_SECRET,
+
+    db: createPrismaAdapter({
         client: prisma,
+        config: {
+            account: {
+                status: ["ACTIVE", "PENDING"],
+            },
+            user: {
+                status: ["ACTIVE", "PENDING"],
+            },
+        },
     }),
-    redis: createRedisAdapter({
-        client: redis,
-        config: { prefix: "my-app:auth" },
-    }),
+
+    getIp: (c) => getTrustedClientIp(c),
+
+    session: {
+        validation: ["agent"],
+    },
+
+    cache: {
+        ttl: 60,
+    },
 });
 ```
 
-Both clients must already be initialized by the application. The package does not connect, reconnect, disconnect, or close them.
+`secret` is required only when `cache` is configured. Supply at least 32 high-entropy bytes from the API environment. It is never shared with the Next.js application.
 
-`createDbAdapter` uses `auth_sessions` by default. `config` is optional:
+`createHonoAuth` is the normal Hono entry point: it creates the framework-independent core and attaches the Hono methods in one object. Use `createAuth` plus `createHonoAdapter` only when the same core instance must be composed manually:
 
 ```ts
-const db = createDbAdapter({
-    client: prisma,
-    config: {
-        table: "admin_sessions",
-    },
+import { createAuth } from "@gauts/auth";
+import { createHonoAdapter } from "@gauts/auth/hono";
+
+const core = createAuth({ db });
+const hono = createHonoAdapter({
+    auth: core,
+    cache: { ttl: 60 },
+    getIp: (c) => getTrustedClientIp(c),
+    secret: process.env.AUTH_SECRET,
 });
 ```
 
-When `table` is supplied, TypeScript only accepts a compatible model from that generated Prisma client.
+Do not create a second core for the adapter; pass the existing `core` instance through `auth`.
+
+Only `account_id` is stored in the session row. The Prisma adapter loads the current `account` and `user` relations during authentication; no dynamic account data is copied into the session.
 
-### 3. Type the Hono application
+### Type the application
 
 ```ts
 import { Hono } from "hono";
 import type { HonoAuthEnv } from "@gauts/auth/hono";
 
-const app = new Hono<HonoAuthEnv<AccountSession>>();
+const app = new Hono<HonoAuthEnv>();
 ```
 
-`auth.requireSession` installs both values:
+`auth.requireSession` installs:
 
 ```ts
 const session = c.get("session");
 const account = c.get("account");
+const user = c.get("user");
 ```
 
-### 4. Login
+The values have these shapes:
 
-The application owns request validation, account lookup, rate limiting, status checks, and error responses.
+```ts
+type AuthAccount = {
+    email: string;
+    id: string;
+    name: string;
+    role: string;
+    status: string;
+    timezone: string | null;
+    user: AuthUser;
+};
+
+type AuthUser = {
+    id: string;
+    role: string;
+    status: string;
+};
+
+type Session = {
+    account_id: string;
+    client: {
+        agent: string | null;
+        ip: string | null;
+        platform: string | null;
+    };
+    created_at: Date;
+    expires_at: Date;
+    id: string;
+    renew_at: Date;
+};
+```
+
+### Login
+
+The application owns input validation, credential lookup, rate limiting, and error responses. The adapter access rules validate current account and user status/role before the session is accepted.
 
 ```ts
+const DUMMY_PASSWORD_HASH =
+    "$argon2id$v=19$m=65536,p=4,t=3$PUotpfVXonc0VRFuV1pKZQ$oxxA8DMvGRTSbZvh2Dkokeyih9sbKeodWYROqVxP9BI";
+
 app.post("/auth/login", async (c) => {
-    const { email, password } = await c.req.json<{
+    const body = await c.req.json<{
         email: string;
         password: string;
     }>();
-    const account = await findAccount(email);
-
-    if (
-        !account ||
-        !(await auth.password.verify({
-            password,
-            storedHash: account.password_hash,
-        }))
-    ) {
+    const account = await findAccount(body.email);
+    const passwordValid = await auth.password.verify({
+        password: body.password,
+        storedHash: account?.passwordHash ?? DUMMY_PASSWORD_HASH,
+    });
+
+    if (!account || !passwordValid) {
         return c.json({ error: "Invalid credentials." }, 401);
     }
 
-    const session = await auth.createSession({
+    await auth.createSession({
         account_id: account.id,
         context: c,
-        data: {
-            email: account.email,
-            role: account.role,
-        },
     });
 
-    return c.json({ account: session.data });
+    return c.json({ authenticated: true });
 });
 ```
 
-`createSession` inserts the database row, creates the Redis session, writes the cookie, and returns the public session. The raw token remains internal to the Hono adapter.
+The dummy hash ensures that unknown accounts still perform the configured password verification. Precompute it once with the same algorithm and cost as the application; never generate it inside the request handler. Keep the response identical for unknown accounts and invalid passwords.
 
-### 5. Protect routes
+Only `account_id` is persisted by the session. Email, roles, statuses, password hashes, and other dynamic account data never enter the session table.
+
+### Protect routes
 
 ```ts
 app.get("/account", auth.requireSession, (c) => {
     return c.json({
         account: c.get("account"),
         session_id: c.get("session").id,
+        user: c.get("user"),
     });
 });
 ```
 
-`requireSession` authenticates the request. It does not apply application roles or permissions.
+`requireSession` authenticates the request. With cache configured, only `GET` and `HEAD` may use it. Every other method validates through the database and clears the short cache after successful validation. It does not apply application-specific route roles or permissions.
+
+### Renewal endpoint
+
+```ts
+app.post("/auth/renew", async (c) => {
+    await auth.renewSession(c);
+    return c.body(null, 204);
+});
+```
+
+`renewSession` always performs full database validation. It independently derives whether renewal is due from `created_at` and the last database renewal; the renewal marker never authorizes renewal.
+
+If renewal is not yet due, database expiry is not changed. The API still returns the authoritative session cookie, renewal marker, and cache.
 
-### 6. Logout
+### Logout
 
 ```ts
 app.post("/auth/logout", async (c) => {
@@ -193,33 +346,66 @@ app.post("/auth/logout", async (c) => {
 });
 ```
 
-Logout deletes the Redis session, records revocation in the database, and clears the cookie. Backend revocation removes access; clearing the cookie is client cleanup.
+Logout marks the database session as revoked and then clears all three cookies. If database revocation fails, the cookies are not cleared and the error is propagated.
 
-## Configuration
+## Next.js renewal adapter
 
-### `createHonoAuth`
+The Next.js adapter does not authenticate sessions. It calls the private API renewal URL only when the renewal marker is missing.
 
 ```ts
-const auth = createHonoAuth<AccountSession>({
-    getIp,
-    db,
-    redis,
-    password,
-    session,
-    cookie,
+import { createNextAuth } from "@gauts/auth/next";
+
+export const nextAuth = createNextAuth({
+    renewUrl: `${process.env.NEXT_PRIVATE_API_URL}/auth/renew`,
 });
 ```
 
-| Property   | Required | Purpose                                                              |
-| ---------- | -------- | -------------------------------------------------------------------- |
-| `getIp`    | Yes      | Returns the trusted client IP from the Hono context.                 |
-| `db`       | Yes      | Stores durable session history.                                      |
-| `redis`    | Yes      | Stores and validates active sessions.                                |
-| `password` | No       | Selects password algorithm and cost limits. Defaults to Argon2id.    |
-| `session`  | No       | Configures expiry, renewal, maximum sessions, and client validation. |
-| `cookie`   | No       | Configures the Hono session cookie.                                  |
+The controlled header list is also exported for application fetchers that need to follow the same forwarding policy:
+
+```ts
+import { FORWARD_HEADERS } from "@gauts/auth/next";
+```
+
+Use it in `proxy.ts` before returning the browser-facing response:
+
+```ts
+import type { NextRequest } from "next/server";
+import { NextResponse } from "next/server";
+
+export const proxy = async (request: NextRequest) => {
+    const response = NextResponse.next();
+    const renewal = await nextAuth.renew({
+        request,
+        response,
+    });
+
+    if (renewal.status === 401) {
+        return NextResponse.redirect(new URL("/login", request.url));
+    }
+
+    if (renewal.status !== null && renewal.status >= 500) {
+        return NextResponse.redirect(new URL("/maintenance", request.url));
+    }
+
+    return renewal.response;
+};
+```
+
+Result semantics:
+
+| `attempted` | `status` | Meaning |
+| --- | ---: | --- |
+| `false` | `null` | Session token and renewal marker exist. |
+| `false` | `401` | Session token is missing or malformed. No API call occurred. |
+| `true` | HTTP status | `/auth/renew` was called and its `Set-Cookie` headers were copied. |
 
-Configuration is resolved once when the auth instance is created. Invalid configuration throws `AUTH_CONFIG_INVALID` during startup.
+The adapter forwards only the session cookie and the client/origin headers required for session and CSRF validation. If the browser request has no `Origin`, it uses the public origin from `NextRequest`. Other cookies, `Authorization`, and arbitrary request headers are never forwarded. Renewal rejects redirects and times out after five seconds. `renewUrl` must point to the application's trusted private API.
+
+Protected API endpoints remain responsible for real authentication. The renewal marker is only a browser scheduling mechanism and never acts as a refresh token.
+
+Apply the proxy only to protected application routes, or skip renewal handling for public routes before calling `nextAuth.renew`. Otherwise a missing cookie produces `status: 401`, which is correct for protected routes but not for login or public pages.
+
+## Configuration
 
 ### Password
 
@@ -227,158 +413,116 @@ Argon2id is the default:
 
 ```ts
 password: {
-  algorithm: "argon2id",
+    algorithm: "argon2id",
 }
 ```
 
-| Argon2id property |      Default |                Allowed | Purpose                           |
-| ----------------- | -----------: | ---------------------: | --------------------------------- |
-| `algorithm`       | `"argon2id"` |           `"argon2id"` | Selects Argon2id. May be omitted. |
-| `hashLength`      |         `32` |           `16` to `64` | Hash output length in bytes.      |
-| `maxBytes`        |       `1024` |     `1` to `1,048,576` | Maximum UTF-8 password size.      |
-| `memoryCost`      |     `65,536` | `8,192` to `1,048,576` | Memory cost in KiB.               |
-| `parallelism`     |          `4` |            `1` to `16` | Number of lanes.                  |
-| `timeCost`        |          `3` |            `1` to `10` | Number of iterations.             |
+| Argon2id property | Default | Allowed |
+| --- | ---: | ---: |
+| `hashLength` | `32` | `16` to `64` |
+| `maxBytes` | `1024` | `1` to `1,048,576` |
+| `memoryCost` | `65,536` | `8,192` to `1,048,576` |
+| `parallelism` | `4` | `1` to `16` |
+| `timeCost` | `3` | `1` to `10` |
 
-Applications with bcrypt hashes must select bcrypt explicitly:
+Applications with existing bcrypt hashes must select bcrypt explicitly:
 
 ```ts
 password: {
-  algorithm: "bcrypt",
+    algorithm: "bcrypt",
 }
 ```
 
-| bcrypt property  |  Default |                   Allowed | Purpose                                       |
-| ---------------- | -------: | ------------------------: | --------------------------------------------- |
-| `algorithm`      | Required |                `"bcrypt"` | Selects bcrypt for hashing and verification.  |
-| `maxBytes`       |     `72` |               `1` to `72` | Maximum UTF-8 size accepted for new hashes.   |
-| `rounds`         |     `12` |               `4` to `31` | Cost factor.                                  |
-| `verifyMaxBytes` |     `72` | `maxBytes` to `1,048,576` | Maximum UTF-8 size accepted for verification. |
+| bcrypt property | Default | Allowed |
+| --- | ---: | ---: |
+| `maxBytes` | `72` | `1` to `72` |
+| `rounds` | `12` | `4` to `31` |
+| `verifyMaxBytes` | `72` | `maxBytes` to `1,048,576` |
 
 The selected algorithm is used for both hashing and verification. The package never detects algorithms, migrates hashes, rehashes passwords, or falls back to another algorithm.
 
-bcrypt ignores bytes after the first 72. Keep `verifyMaxBytes` at `72` unless preserving historical truncation is an explicit application requirement.
-
 ### Session
 
 ```ts
 session: {
-  max: 10,
-  renewInterval: 24 * 60 * 60,
-  ttl: 7 * 24 * 60 * 60,
-  validation: ["agent"],
+    maxLifetime: 30 * 24 * 60 * 60,
+    renewInterval: 24 * 60 * 60,
+    ttl: 7 * 24 * 60 * 60,
+    validation: ["agent"],
 }
 ```
 
 Time values are seconds.
 
-| Property        |     Default |                                             Allowed | Purpose                                                                                    |
-| --------------- | ----------: | --------------------------------------------------: | ------------------------------------------------------------------------------------------ |
-| `max`           |        `10` |                                     `1` to `10,000` | Maximum active sessions per account.                                                       |
-| `renewInterval` |    `86,400` |                                    `1` to `ttl - 1` | Minimum activity interval between expiry writes.                                           |
-| `ttl`           |   `604,800` |                                `60` to `31,536,000` | Inactivity lifetime on creation and renewal.                                               |
-| `validation`    | `["agent"]` | Unique combination of `agent`, `ip`, and `platform` | Client fields compared during validation. An empty array disables client-field comparison. |
+| Property | Default | Allowed | Purpose |
+| --- | ---: | ---: | --- |
+| `maxLifetime` | `2,592,000` | `ttl` to `31,536,000` | Maximum lifetime from the original login, regardless of activity. |
+| `renewInterval` | `86,400` | `1` to `ttl - 1` | Minimum interval before renewal is due. |
+| `ttl` | `604,800` | `60` to `31,536,000` | Sliding inactivity lifetime. |
+| `validation` | `["agent"]` | Unique `agent`, `ip`, `platform` fields | Exact client fields compared on every validation. |
+
+The authoritative limits are derived from the immutable creation time and the last successful renewal:
+
+```text
+maxExpiresAt = created_at + maxLifetime
+expires_at   = min(now + ttl, maxExpiresAt)
+renew_at    = min((updated_at ?? created_at) + renewInterval, maxExpiresAt)
+```
 
-Expiry is sliding and has no forced absolute lifetime. The opaque token is not rotated during renewal.
+`maxLifetime` must be greater than or equal to `ttl`. It is enforced by the session core and requires a new login after the limit is reached; no additional database column is required.
 
 ### Cookie
 
 ```ts
 cookie: {
-  domain: undefined,
-  name: "__Host-session",
-  path: "/",
-  sameSite: "Lax",
-  secure: true,
+    cacheName: "__cac",
+    domain: undefined,
+    name: "__sec",
+    path: "/",
+    renewName: "__ren",
+    sameSite: "Lax",
+    secure: true,
 }
 ```
 
-| Property   | Default            | Purpose                                              |
-| ---------- | ------------------ | ---------------------------------------------------- |
-| `name`     | `"__Host-session"` | Cookie name.                                         |
-| `domain`   | Not set            | Optional domain; without it the cookie is host-only. |
-| `path`     | `"/"`              | Cookie path.                                         |
-| `sameSite` | `"Lax"`            | `"Strict"`, `"Lax"`, or `"None"`.                    |
-| `secure`   | `true`             | Sends the cookie only over HTTPS.                    |
-
 `HttpOnly` is always enabled.
 
+- The session cookie contains only the stable opaque token and expires with the database session.
+- The cache cookie contains the signed snapshot and expires after `cache.ttl`.
+- The renewal cookie contains the fixed value `1` and expires at the authoritative `renew_at` time.
+- Cookie names default to `__sec`, `__cac`, and `__ren`.
+- All three names must be valid and unique.
+
 - `__Host-` requires `secure: true`, `path: "/"`, and no domain.
 - `__Secure-` requires `secure: true`.
 - `SameSite=None` requires `secure: true`.
-- Local HTTP development with `secure: false` requires a custom name without a secure prefix.
-
-### Redis adapter
-
-```ts
-import { createClient } from "redis";
-import { createRedisAdapter } from "@gauts/auth/redis";
-
-const redis = createClient({ url: process.env.REDIS_URL });
-await redis.connect();
-
-const adapter = createRedisAdapter({
-    client: redis,
-    config: {
-        prefix: "my-app:auth",
-    },
-});
-```
-
-`config` is optional. The prefix defaults to `gauts:auth`, supports letters, numbers, `:`, `_`, and `-`, and has a maximum of 128 characters.
-
-```text
-<prefix>:session:<sha256-token-hash>
-```
-
-Redis failures throw `REDIS_UNAVAILABLE`. Authentication never falls back to the database.
-
-### Prisma adapter
-
-Default model:
+- Local HTTP development requires `secure: false`.
 
-```ts
-import { createDbAdapter } from "@gauts/auth/prisma";
-
-const db = createDbAdapter({
-    client: prisma,
-});
-```
+### Signed session cache
 
-Custom compatible model:
+The cache is disabled by default. Enable it explicitly:
 
 ```ts
-const db = createDbAdapter({
-    client: prisma,
-    config: {
-        table: "admin_sessions",
-    },
-});
+secret: process.env.AUTH_SECRET,
+cache: {
+    ttl: 60,
+}
 ```
 
-The adapter owns the five database operations required by the session service: create, find one, find active, revoke, and update expiry. Applications do not implement those queries.
-
-The default model is `auth_sessions`. If that model does not exist, `config.table` is required. TypeScript rejects a selected model whose generated result does not contain the complete session record shape.
+`ttl` is measured in seconds and must be an integer from `1` through the configured session TTL. The secret must contain at least 32 bytes and should be generated from a cryptographically secure source.
 
-Database failures are exposed by the auth core as `DB_UNAVAILABLE`.
+The cache payload:
 
-### Custom database adapter
+- is signed with HMAC-SHA-256 using a domain-separated context;
+- is cryptographically bound to the opaque session token;
+- contains the resolved session, account, user, and its own expiry;
+- compares the same configured IP, User-Agent, and platform fields on every hit;
+- never extends the authoritative session expiry;
+- is accepted only for `GET` and `HEAD` requests.
 
-Applications not using Prisma can implement the exported `DbAdapter` contract:
+An absent, expired, malformed, altered, token-mismatched, or client-mismatched cache is a cache miss. The adapter then performs normal database authentication. A real configured client mismatch is therefore still detected and revoked by the database session service.
 
-```ts
-import type { DbAdapter } from "@gauts/auth";
-
-const db = {
-    create: async (session) => {},
-    find: async ({ account_id, session_id }) => null,
-    findActive: async ({ account_id, now }) => [],
-    revoke: async ({ revoked_at, session_ids }) => {},
-    updateExpiry: async ({ expires_at, session_id, updated_at }) => {},
-} satisfies DbAdapter;
-```
-
-The adapter must persist only token hashes, never raw tokens. `find` must scope by both `account_id` and `session_id`. `findActive` must return only non-revoked rows whose `expires_at` is greater than `now`.
+Unsafe methods always query the database. Renewal and logout also query the database directly. `auth.session.resolve()` never uses the browser cache, which keeps WebSocket and non-HTTP integrations DB-backed.
 
 ### Trusted client IP
 
@@ -386,11 +530,9 @@ The adapter must persist only token hashes, never raw tokens. `find` must scope
 getIp: (c) => getTrustedClientIp(c);
 ```
 
-`getIp` runs during login and every authenticated HTTP request. It may be synchronous or asynchronous and returns `string`, `null`, or `undefined`.
+Only the application knows which proxy and forwarding header are trusted. The package normalizes the returned value but never chooses `X-Forwarded-For`, `CF-Connecting-IP`, or a socket address itself.
 
-Only the application knows which reverse proxies and forwarding headers are trusted. The package does not select `X-Forwarded-For`, `CF-Connecting-IP`, socket addresses, or another source. It canonicalizes the value returned by the application.
-
-The Hono adapter reads the remaining metadata from request headers:
+The Hono adapter reads:
 
 ```ts
 type SessionClientInput = {
@@ -401,278 +543,163 @@ type SessionClientInput = {
 ```
 
 - IPv4, IPv4-mapped IPv6, and IPv6 are canonicalized.
-- `::1` becomes `127.0.0.1`.
 - Invalid or empty IP values become `null`.
-- Platform comes from `Sec-CH-UA-Platform`, is unquoted and limited to 255 characters.
-- Agent comes from `User-Agent` and is stored in full without truncation.
-- No GeoIP, DNS, country, or database lookup is performed.
-
-## Password API
+- Platform comes from `Sec-CH-UA-Platform`, is normalized, and is limited to 255 characters.
+- User-Agent comes from `User-Agent` and is stored in full.
+- No GeoIP, DNS, country, or external lookup is performed.
+- Every field selected in `session.validation` is required during creation and validation. Missing or invalid configured fields never match.
 
-### `auth.password.algorithm`
+## Database adapter
 
-The resolved algorithm: `"argon2id"` or `"bcrypt"`.
+The core depends only on the exported `DbAdapter` contract. It does not import Prisma or depend on a specific ORM. `createPrismaAdapter` is the Prisma implementation exposed through `@gauts/auth/prisma`; other ORM implementations can use their own package subpath and factory name.
 
-### `auth.password.hash(password)`
-
-Validates the UTF-8 byte length and creates a hash using the configured algorithm.
+Default Prisma delegate (`account_sessions`):
 
 ```ts
-const password_hash = await auth.password.hash(password);
-```
+import { createPrismaAdapter } from "@gauts/auth/prisma";
 
-### `auth.password.verify({ password, storedHash })`
-
-Verifies only with the configured algorithm. A hash from another algorithm or an invalid hash returns `false`.
-
-```ts
-const valid = await auth.password.verify({
-    password,
-    storedHash: account.password_hash,
+const db = createPrismaAdapter({
+    client: prisma,
+    config: {
+        account: {
+            status: ["ACTIVE"],
+        },
+        user: {
+            status: ["ACTIVE"],
+        },
+    },
 });
 ```
 
-Invalid password size throws `PASSWORD_INPUT_INVALID`. Wrong credentials return `false`.
-
-## Hono API
-
-### `auth.createSession({ account_id, context, data })`
-
-Creates the database and Redis session, writes the HttpOnly cookie, and returns `Session<TData>`.
-
-### `auth.resolveSession(context)`
-
-Reads and validates the cookie and returns `Session<TData>`.
-
-- Throws `SESSION_INVALID` when the cookie or Redis session is missing or invalid.
-- Clears an invalid cookie.
-- Compares configured client fields.
-- Renews database expiry, Redis TTL, and cookie expiry only when due.
-- Revokes the backend session and throws `SESSION_CLIENT_MISMATCH` after a mismatch.
-
-### `auth.requireSession`
-
-Middleware that calls `resolveSession` and sets:
+Custom compatible Prisma delegate:
 
 ```ts
-c.set("session", session);
-c.set("account", session.data);
+const db = createPrismaAdapter({
+    client: prisma,
+    config: {
+        account: {
+            status: ["ACTIVE"],
+        },
+        table: "admin_sessions",
+        user: {
+            status: ["ACTIVE"],
+        },
+    },
+});
 ```
 
-### `auth.revokeSession(context)`
-
-Revokes the session represented by the request cookie and clears that cookie. Returns the revoked session IDs.
-
-### `auth.clearSession(context)`
-
-Deletes only the response cookie. It does not revoke Redis or update the database and must not be used as logout.
-
-### `auth.getToken(context)`
-
-Returns the raw cookie token or `null`. Never log, persist, or expose this value in a response.
-
-## Core session API
-
-The same instance exposes the framework-independent `auth.session` service.
-
-### `auth.session.create({ account_id, client, data })`
-
-Creates a session and returns:
+Access rules:
 
 ```ts
-{
-    session: Session<TData>;
-    token: string;
-}
+const db = createPrismaAdapter({
+    client: prisma,
+    config: {
+        account: {
+            status: ["ACTIVE", "PENDING"],
+        },
+        user: {
+            role: ["ADMIN"],
+            status: ["ACTIVE", "PENDING"],
+        },
+    },
+});
 ```
 
-Prefer `auth.createSession` in Hono applications because the core cannot write the browser cookie.
+Account and user status lists are required because the package cannot know which application-specific values grant access. Roles are unrestricted unless configured. Every list must contain unique non-empty strings. A role rule controls authentication for the entire application; route-level authorization remains the application's responsibility.
 
-### `auth.session.resolve({ client, token })`
+The configured arrays are access allowlists, not declarations of every enum value that exists in the application.
 
-Validates and renews when due. It returns `null` for an invalid or expired session, otherwise:
+Custom database adapters implement:
 
 ```ts
-{
-    renewed: boolean;
-    session: Session<TData>;
-}
-```
-
-A framework using the core directly must update the cookie expiry when `renewed` is `true`.
-
-### `auth.session.validate({ client, token })`
-
-Validates without renewing Redis, database expiry, or cookie expiry. A configured client mismatch still revokes the backend session.
-
-### `auth.session.list(account_id)`
-
-Returns sessions that are active in both the database and Redis. The public result never contains `token_hash`.
-
-### `auth.session.revoke({ account_id, session_id })`
-
-Revokes one session after confirming it belongs to the supplied account. Throws `SESSION_NOT_FOUND` when it is absent or already revoked.
-
-### `auth.session.revokeAccount(account_id)`
-
-Revokes every active session for one account.
-
-### `auth.session.revokeToken(token)`
-
-Revokes the Redis session represented by a raw token and records the revocation in the database. Invalid or absent tokens return an empty array.
-
-### `auth.session.sync({ account_id, data })`
-
-Replaces the cached `data` in every active Redis session for the account while preserving tokens and TTLs.
-
-Use it after changing cached account data. Use `revokeAccount` when a change must force re-authentication.
-
-## Public session shapes
-
-```ts
-type Session<TData> = {
-    account_id: string;
-    client: {
-        agent: string | null;
-        ip: string | null;
-        platform: string | null;
-    };
-    created_at: Date;
-    data: TData;
-    expires_at: Date;
-    id: string;
-    touched_at: Date;
-};
-```
+import type { DbAdapter } from "@gauts/auth";
 
-```ts
-type ActiveSession = {
-    account_id: string;
-    agent: string | null;
-    created_at: Date;
-    expires_at: Date;
-    id: string;
-    ip: string | null;
-    platform: string | null;
-    revoked_at: Date | null;
-    updated_at: Date | null;
-};
+const db = {
+    create: async (session) => {},
+    find: async ({ account_id, session_id }) => null,
+    findActive: async ({ account_id, now }) => [],
+    findToken: async (token_hash) => null,
+    revoke: async ({ revoked_at, session_ids }) => {},
+    updateExpiry: async ({ expires_at, session_id, updated_at }) => {},
+} satisfies DbAdapter;
 ```
 
-## Client validation
+`findToken` must use the token hash and never accept or persist a raw token. It returns the current nested `account`, its `user`, and an `allowed` result derived from the adapter's access rules.
 
-The default compares the complete User-Agent:
+## Core session API
 
 ```ts
-session: {
-  validation: ["agent"],
-}
+await auth.session.create({ account_id, client });
+await auth.session.resolve({ client, token });
+await auth.session.renew({ client, token });
+await auth.session.list(account_id);
+await auth.session.revoke({ account_id, session_id });
+await auth.session.revokeToken(token);
+await auth.session.revokeAccount(account_id);
 ```
 
-An administration application can also bind IP and platform:
+- `resolve` performs read-only authentication.
+- `renew` validates and updates expiry only when due.
+- `list` returns active, non-expired sessions without token hashes.
+- revocation retains database history through `revoked_at`.
+- the package does not limit session count or delete historical rows; retention and cleanup belong to the application.
 
-```ts
-session: {
-  validation: ["ip", "agent", "platform"],
-}
-```
+## Performance and cache policy
 
-An empty array validates only the opaque token:
+The package contains no Redis or in-process cache. The optional signed browser cache avoids shared infrastructure and works across API instances that use the same `AUTH_SECRET`.
 
-```ts
-session: {
-  validation: [],
-}
-```
+Without cache, each `requireSession` performs:
 
-Comparison is exact after normalization. A configured mismatch deletes the Redis session and records revocation in the database, so both the suspicious client and legitimate browser must authenticate again.
+```text
+1 Prisma relation lookup by indexed account_sessions.token_hash
+```
 
-Exact IP validation can log out legitimate users on VPN, mobile, or rotating networks. Client matching is defense in depth; it does not replace TLS, secure cookies, CSRF protection, XSS prevention, or explicit re-authentication for sensitive actions.
+With a valid cache, `GET` and `HEAD` avoid that lookup until `cache.ttl` expires. Cache misses perform the normal indexed lookup and return a new cache cookie. Prisma loads current relations through the session query; the exact number of SQL statements depends on Prisma's configured relation load strategy.
 
-## Expiration and renewal
+Cookie caching has an explicit consistency tradeoff: revocation and account/user changes made elsewhere may remain visible to safe requests until the short cache expires. Unsafe methods never accept the cache, so writes observe current database state. A 60-second TTL limits the stale-read window to at most one minute.
 
-- Creation assigns `ttl` to Redis, the database row, and the cookie.
-- Requests before `renewInterval` validate without expiry writes.
-- The first eligible HTTP request after `renewInterval` sets expiry to `now + ttl` in Redis and the database.
-- The Hono adapter sends `Set-Cookie` only when renewal occurs.
-- The opaque token never changes during renewal.
-- Continued eligible HTTP activity can keep a session alive indefinitely.
-- A session without renewal activity expires after `ttl`.
-- `validate` never renews; `resolve` renews only when due.
+Logout clears the current browser's cache immediately. Cookies on another device cannot be remotely deleted, so immediate cross-device read revocation requires disabling the cache or using shared server-side state outside this package.
 
 ## Errors
 
-All package errors have `name: "AuthError"` and a typed `code`.
-
-```ts
-import { isAuthError } from "@gauts/auth";
-
-app.onError((error, c) => {
-    if (!isAuthError(error)) {
-        return c.json({ error: "Internal server error." }, 500);
-    }
-
-    if (error.code === "REDIS_UNAVAILABLE" || error.code === "DB_UNAVAILABLE") {
-        return c.json({ error: "Authentication service unavailable." }, 503);
-    }
-
-    return c.json({ error: error.message }, 401);
-});
-```
-
-| Code                      | Meaning                                                                |
-| ------------------------- | ---------------------------------------------------------------------- |
-| `AUTH_CONFIG_INVALID`     | Invalid startup configuration or adapter contract.                     |
-| `PASSWORD_INPUT_INVALID`  | Empty or oversized password input.                                     |
-| `SESSION_CLIENT_MISMATCH` | A configured client field changed and the backend session was revoked. |
-| `SESSION_DATA_INVALID`    | Required session input or stored Redis payload is invalid.             |
-| `SESSION_INVALID`         | Hono cookie or Redis session is missing, expired, or invalid.          |
-| `SESSION_LIMIT_REACHED`   | The account already has the maximum active sessions.                   |
-| `SESSION_NOT_FOUND`       | The selected session is absent or already revoked.                     |
-| `DB_UNAVAILABLE`          | The database adapter failed or returned invalid session data.          |
-| `REDIS_UNAVAILABLE`       | Redis failed or returned invalid data; authentication fails closed.    |
-
-Applications decide final HTTP statuses and public messages.
-
-## Framework-independent usage
-
 ```ts
-import { createAuth } from "@gauts/auth";
-import { createDbAdapter } from "@gauts/auth/prisma";
-import { createRedisAdapter } from "@gauts/auth/redis";
-
-const auth = createAuth<AccountSession>({
-    db: createDbAdapter({ client: prisma }),
-    redis: createRedisAdapter({ client: redis }),
-});
-```
-
-The application must then extract client input, read and secure the raw token, call `resolve`, and deliver renewed cookie expiry when `renewed` is `true`.
-
-Hono applications should normally use `createHonoAuth`. `createHonoAdapter` remains available when deliberately composing the core and Hono adapter separately.
-
-## Application responsibilities
-
-The package does not provide:
-
-- Registration, account lookup, OTP, OAuth, password reset, or email flows.
-- Endpoints or UI components.
-- Roles, permissions, or application authorization policies.
-- Prisma migrations or database/Redis connection lifecycle.
-- Trusted proxy policy.
-- Rate limiting, CSRF, CORS, CSP, logging, or notifications.
-
-The application must use HTTPS in production, protect login endpoints, validate input, prevent account enumeration, define trusted proxies, and apply CSRF and XSS protections.
-
-Never log raw passwords, raw session tokens, cookies, password hashes, or Redis session payloads.
-
-## Package exports
-
-```text
-@gauts/auth         createAuth, isAuthError, and core types
-@gauts/auth/prisma  createDbAdapter and Prisma adapter types
-@gauts/auth/redis   createRedisAdapter and Redis adapter types
-@gauts/auth/hono    createHonoAuth, createHonoAdapter, and Hono types
-```
-
-The compiled Hono example is available in [`examples/hono`](./examples/hono).
+type AuthErrorCode =
+    | "AUTH_CONFIG_INVALID"
+    | "PASSWORD_INPUT_INVALID"
+    | "SESSION_CLIENT_MISMATCH"
+    | "SESSION_DATA_INVALID"
+    | "SESSION_INVALID"
+    | "SESSION_NOT_FOUND"
+    | "DB_UNAVAILABLE";
+```
+
+Use `isAuthError(error)` before reading `error.code`.
+
+The package does not choose HTTP responses. A typical application mapping is:
+
+| Code | Suggested HTTP status |
+| --- | ---: |
+| `AUTH_CONFIG_INVALID` | `500` during startup |
+| `PASSWORD_INPUT_INVALID` | `400` |
+| `SESSION_CLIENT_MISMATCH` | `403` |
+| `SESSION_DATA_INVALID` | `400` |
+| `SESSION_INVALID` | `401` |
+| `SESSION_NOT_FOUND` | `404` |
+| `DB_UNAVAILABLE` | `503` |
+
+Applications may use a different response policy, but database failures and invalid sessions must continue to fail closed.
+
+## Security responsibilities
+
+The package provides session primitives, not a complete application security policy. Consuming applications remain responsible for:
+
+- TLS and trusted-proxy configuration;
+- CSRF, CORS, and origin validation;
+- login and renewal rate limiting;
+- equivalent password verification work for unknown accounts;
+- account status and authorization rules;
+- re-authentication for sensitive actions;
+- database migrations and cleanup;
+- never logging passwords, raw tokens, cookie headers, or password hashes.
+
+Exact IP/User-Agent/platform matching is defense in depth. It does not prevent every stolen-cookie replay scenario.