@gauts/auth 0.2.1 → 0.3.0

package/README.md

@@ -1,299 +1,705 @@
 # `@gauts/auth`
 
-Reusable password and opaque server-side session authentication for Node.js applications.
+Reusable password authentication and database-backed opaque sessions for Node.js applications.
 
-`@gauts/auth` validates sessions through Redis and records session history through an application-owned database adapter. It does not create endpoints, database models, users, or application authorization rules.
+The package stores only a SHA-256 token hash in the database. Browser integration uses three cookies with separate responsibilities:
 
-## Design
+```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.
 
-- Argon2id by default, with explicit bcrypt support.
-- One stable 256-bit opaque browser token per session.
-- SHA-256 token hashes in Redis and the session records database.
-- Redis-authoritative authentication with no database fallback.
-- Sliding inactivity expiration without an absolute lifetime.
-- Configurable client validation, using the complete User-Agent by default.
-- Framework integrations through explicit package exports.
+## Requirements
+
+- Node.js 22 or newer.
+- 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 and Prisma:
+
 ```bash
-npm install @gauts/auth redis hono
+npm install @gauts/auth hono @prisma/client
 ```
 
-## Setup
+For the Next.js adapter, the application must already use Next.js:
 
-```ts
-import { createAuth, type SessionRecords } from "@gauts/auth";
-import { createHonoAdapter } from "@gauts/auth/hono";
-import { createRedisStore } from "@gauts/auth/redis";
-
-const records: SessionRecords = {
-  create: (session) => db.sessions.create(session),
-  find: ({ accountId, sessionId }) =>
-    db.sessions.find({ accountId, sessionId }),
-  findActive: ({ accountId, now }) =>
-    db.sessions.findActive({ accountId, now }),
-  revoke: ({ revokedAt, sessionIds }) =>
-    db.sessions.revoke({ revokedAt, sessionIds }),
-  updateExpiry: ({ expiresAt, sessionId, updatedAt }) =>
-    db.sessions.updateExpiry({ expiresAt, sessionId, updatedAt }),
-};
+```bash
+npm install @gauts/auth next
+```
 
-type AccountSession = {
-  email: string;
-  role: "owner" | "admin";
-};
+`hono` and `next` are optional peer dependencies. The Prisma adapter receives the consuming application's generated client and does not import Prisma at runtime.
 
-const auth = createAuth<AccountSession>({
-  redis: createRedisStore({ client: redis, config: { prefix: "my-app:auth" } }),
-  records,
-  session: {
-    ttl: 60 * 60 * 24 * 7,
-    renewInterval: 60 * 60 * 24,
-    max: 10,
-    validation: ["userAgent"],
-  },
-});
+## Package entry points
 
-const hono = createHonoAdapter({
-  auth,
-  getIp: (c) => getTrustedClientIp(c),
-});
+| 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
+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
 ```
 
-The application must obtain the client IP according to its own trusted-proxy configuration. The package canonicalizes the supplied IPv4 or IPv6 value but never decides which forwarding headers are trusted.
+Protected `GET` or `HEAD`:
 
-## Client information
+```text
+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 application supplies `getIp` because only its deployment knows which proxies and forwarding
-headers are trusted. The Hono adapter reads User-Agent and platform directly from the request.
+Unsafe methods and direct core calls:
 
-The resulting client information has this shape:
+```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
+```
 
-```ts
-type SessionClientInput = {
-  ip?: string | null;
-  userAgent?: string | null;
-  platform?: string | null;
-};
+Renewal:
+
+```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
 ```
 
-- `validation` selects which client fields are compared on authenticated requests.
-- `userAgent` is compared by default.
-- `ip` and `platform` are always stored as session metadata, even when they are not compared.
-- IPv4, IPv4-mapped IPv6, and IPv6 values are canonicalized by the package.
-- Platform is unquoted, trimmed, and limited to 255 characters.
-- User-Agent is stored and compared in full without truncation.
+`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`.
 
-`getIp` runs during session creation and on every authenticated request. It should only resolve the
-trusted request IP and must not perform unrelated account or database work.
+## Prisma schema contract
 
-## Passwords
+The Prisma adapter resolves authentication through this relation chain:
 
-Argon2id is the default:
+```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 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)
+  ip          String?   @db.VarChar(45)
+  platform    String?   @db.VarChar(255)
+  agent       String?   @db.Text
+  expires_at  DateTime  @db.Timestamp(0)
+  revoked_at  DateTime? @db.Timestamp(0)
+  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])
+}
+```
+
+The adapter requires these Prisma field and relation names:
+
+| 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` |
+
+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.
+
+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.
+
+`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.
+
+Create migrations through the consuming application's normal Prisma workflow. The package never creates or runs migrations.
+
+## 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
-const hash = await auth.password.hash(password);
-const valid = await auth.password.verify({ password, storedHash: hash });
+import { createHonoAuth } from "@gauts/auth/hono";
+import { createPrismaAdapter } from "@gauts/auth/prisma";
+
+export const auth = createHonoAuth({
+    secret: process.env.AUTH_SECRET,
+
+    db: createPrismaAdapter({
+        client: prisma,
+        config: {
+            account: {
+                status: ["ACTIVE", "PENDING"],
+            },
+            user: {
+                status: ["ACTIVE", "PENDING"],
+            },
+        },
+    }),
+
+    getIp: (c) => getTrustedClientIp(c),
+
+    session: {
+        validation: ["agent"],
+    },
+
+    cache: {
+        ttl: 60,
+    },
+});
 ```
 
-Applications whose database contains bcrypt hashes select bcrypt explicitly:
+`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.
+
+`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 auth = createAuth({
-  password: {
-    algorithm: "bcrypt",
-  },
-  redis: createRedisStore({ client: redis }),
-  records,
+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,
 });
 ```
 
-New bcrypt hashes reject passwords above 72 bytes. Applications with historical hashes created from longer bcrypt input can opt into a larger verification-only boundary without permitting new truncated hashes:
+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.
+
+### Type the application
 
 ```ts
-password: {
-  algorithm: "bcrypt",
-  maxBytes: 72,
-  verifyMaxBytes: 1024,
-}
+import { Hono } from "hono";
+import type { HonoAuthEnv } from "@gauts/auth/hono";
+
+const app = new Hono<HonoAuthEnv>();
 ```
 
-The configured algorithm is used for both hashing and verification. The package does not detect, convert, migrate, or fall back to another algorithm.
+`auth.requireSession` installs:
 
-## Login
+```ts
+const session = c.get("session");
+const account = c.get("account");
+const user = c.get("user");
+```
 
-The application owns the endpoint and account lookup:
+The values have these shapes:
 
 ```ts
-app.post("/auth/login", async (c) => {
-  const { email, password } = await c.req.json();
-  const account = await findAccount(email);
-
-  if (
-    !account ||
-    !(await auth.password.verify({
-      password,
-      storedHash: account.passwordHash,
-    }))
-  ) {
-    return c.json({ error: "Invalid credentials." }, 401);
-  }
-
-  const session = await hono.createSession({
-    accountId: account.id,
-    context: c,
-    data: {
-      email: account.email,
-      role: account.role,
-    },
-  });
+type AuthAccount = {
+    email: string;
+    id: string;
+    name: string;
+    role: string;
+    status: string;
+    timezone: string | null;
+    user: AuthUser;
+};
 
-  return c.json({ account: session.data });
-});
+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;
+};
 ```
 
-Applications must apply their own login rate limiting and account-enumeration protection.
+### Login
 
-## Protected routes
+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
-app.get("/account", hono.requireSession, async (c) => {
-  const session = c.get("session");
-  const account = await findAccountById(session.accountId);
+const DUMMY_PASSWORD_HASH =
+    "$argon2id$v=19$m=65536,p=4,t=3$PUotpfVXonc0VRFuV1pKZQ$oxxA8DMvGRTSbZvh2Dkokeyih9sbKeodWYROqVxP9BI";
 
-  return c.json({ account });
+app.post("/auth/login", async (c) => {
+    const body = await c.req.json<{
+        email: string;
+        password: string;
+    }>();
+    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);
+    }
+
+    await auth.createSession({
+        account_id: account.id,
+        context: c,
+    });
+
+    return c.json({ authenticated: true });
 });
 ```
 
-The middleware reads the cookie, resolves Redis, compares the configured client fields, renews expiry when due, and places the typed session in the Hono context. It does not load application data from the database.
+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.
+
+Only `account_id` is persisted by the session. Email, roles, statuses, password hashes, and other dynamic account data never enter the session table.
 
-Applications that need to populate additional Hono context variables can resolve through the same adapter without duplicating its cookie behavior:
+### Protect routes
 
 ```ts
-const requireAccount = async (c, next) => {
-  const session = await hono.resolveSession(c);
+app.get("/account", auth.requireSession, (c) => {
+    return c.json({
+        account: c.get("account"),
+        session_id: c.get("session").id,
+        user: c.get("user"),
+    });
+});
+```
 
-  c.set("account", session.data);
-  await next();
-};
+`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);
+});
 ```
 
-## Logout
+`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.
+
+### Logout
 
 ```ts
 app.post("/auth/logout", async (c) => {
-  await hono.revokeSession(c);
-  return c.body(null, 204);
+    await auth.revokeSession(c);
+    return c.body(null, 204);
 });
 ```
 
-The adapter clears the cookie only after backend revocation succeeds. Infrastructure errors are
-propagated so the application can return its own service-error response.
+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.
+
+## Next.js renewal adapter
 
-## Active sessions
+The Next.js adapter does not authenticate sessions. It calls the private API renewal URL only when the renewal marker is missing.
 
 ```ts
-const sessions = await auth.session.list(accountId);
+import { createNextAuth } from "@gauts/auth/next";
 
-await auth.session.revoke({
-  accountId,
-  sessionId,
+export const nextAuth = createNextAuth({
+    renewUrl: `${process.env.NEXT_PRIVATE_API_URL}/auth/renew`,
 });
-
-await auth.session.revokeAccount(accountId);
 ```
 
-The records database supplies session history. Redis is checked in a batch before a session is reported as active. Token hashes are never returned by `list`.
+The controlled header list is also exported for application fetchers that need to follow the same forwarding policy:
 
-## Synchronizing session data
+```ts
+import { FORWARD_HEADERS } from "@gauts/auth/next";
+```
 
-When cached session claims change:
+Use it in `proxy.ts` before returning the browser-facing response:
 
 ```ts
-await auth.session.sync({
-  accountId,
-  data: {
-    email: account.email,
-    role: account.role,
-  },
-});
+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;
+};
 ```
 
-Synchronization preserves the existing token and Redis TTL.
+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. |
 
-## Session records contract
+The adapter forwards only the session cookie and the client/origin headers required for session and CSRF validation. 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.
 
-Each consuming application maps `SessionRecords` to its database. The durable record contains:
+Protected API endpoints remain responsible for real authentication. The renewal marker is only a browser scheduling mechanism and never acts as a refresh token.
 
-- Session ID.
-- Account ID and relation owned by the application.
-- SHA-256 token hash.
-- Canonical IP.
-- Platform metadata.
-- Complete User-Agent.
-- Creation, current expiry, update, and revocation timestamps.
+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.
 
-The database never stores the raw browser token.
+## Configuration
 
-## Expiration
+### Password
 
-Defaults:
+Argon2id is the default:
 
 ```ts
-session: {
-  ttl: 7 * 24 * 60 * 60,
-  renewInterval: 24 * 60 * 60,
-  max: 10,
-  validation: ["userAgent"],
+password: {
+    algorithm: "argon2id",
 }
 ```
 
-- Inactive sessions expire after seven days.
-- Active sessions renew at most once every 24 hours.
-- Renewal keeps the same browser token.
-- There is no absolute session lifetime.
-- Every successful `resolve` call counts as HTTP activity and renews the session when due.
+| 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` |
 
-Consumers that cannot deliver `Set-Cookie`, such as WebSocket handshakes, validate without renewing:
+Applications with existing bcrypt hashes must select bcrypt explicitly:
 
 ```ts
-const session = await auth.session.validate({
-  client,
-  token,
-});
+password: {
+    algorithm: "bcrypt",
+}
 ```
 
-`validate` performs the same Redis, expiry, payload, and configured client-field checks as `resolve`. A client mismatch still revokes the backend session. It does not update `touchedAt`, Redis TTL, or the database expiry.
+| bcrypt property | Default | Allowed |
+| --- | ---: | ---: |
+| `maxBytes` | `72` | `1` to `72` |
+| `rounds` | `12` | `4` to `31` |
+| `verifyMaxBytes` | `72` | `maxBytes` to `1,048,576` |
 
-## Client validation
+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.
 
-The default compares only the complete User-Agent:
+### Session
 
 ```ts
 session: {
-  validation: ["userAgent"],
+    maxLifetime: 30 * 24 * 60 * 60,
+    renewInterval: 24 * 60 * 60,
+    ttl: 7 * 24 * 60 * 60,
+    validation: ["agent"],
 }
 ```
 
-Applications can choose any combination of `ip`, `userAgent`, and `platform`:
+Time values are seconds.
+
+| 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)
+```
+
+`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
-session: {
-  validation: ["ip", "userAgent", "platform"],
+cookie: {
+    cacheName: "__cac",
+    domain: undefined,
+    name: "__sec",
+    path: "/",
+    renewName: "__ren",
+    sameSite: "Lax",
+    secure: true,
+}
+```
+
+`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 requires `secure: false`.
+
+### Signed session cache
+
+The cache is disabled by default. Enable it explicitly:
+
+```ts
+secret: process.env.AUTH_SECRET,
+cache: {
+    ttl: 60,
 }
 ```
 
-An empty array disables client-field comparison and validates only the session token. Unknown or duplicate fields are rejected during startup.
+`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.
+
+The cache payload:
+
+- 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.
+
+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.
+
+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
+
+```ts
+getIp: (c) => getTrustedClientIp(c);
+```
+
+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.
+
+The Hono adapter reads:
+
+```ts
+type SessionClientInput = {
+    agent?: string | null;
+    ip?: string | null;
+    platform?: string | null;
+};
+```
+
+- IPv4, IPv4-mapped IPv6, and IPv6 are canonicalized.
+- Invalid or empty IP values become `null`.
+- 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.
+
+## Database adapter
+
+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.
+
+Default Prisma delegate (`account_sessions`):
+
+```ts
+import { createPrismaAdapter } from "@gauts/auth/prisma";
+
+const db = createPrismaAdapter({
+    client: prisma,
+    config: {
+        account: {
+            status: ["ACTIVE"],
+        },
+        user: {
+            status: ["ACTIVE"],
+        },
+    },
+});
+```
+
+Custom compatible Prisma delegate:
+
+```ts
+const db = createPrismaAdapter({
+    client: prisma,
+    config: {
+        account: {
+            status: ["ACTIVE"],
+        },
+        table: "admin_sessions",
+        user: {
+            status: ["ACTIVE"],
+        },
+    },
+});
+```
+
+Access rules:
+
+```ts
+const db = createPrismaAdapter({
+    client: prisma,
+    config: {
+        account: {
+            status: ["ACTIVE", "PENDING"],
+        },
+        user: {
+            role: ["ADMIN"],
+            status: ["ACTIVE", "PENDING"],
+        },
+    },
+});
+```
+
+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.
+
+The configured arrays are access allowlists, not declarations of every enum value that exists in the application.
+
+Custom database adapters implement:
+
+```ts
+import type { DbAdapter } from "@gauts/auth";
+
+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;
+```
+
+`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.
+
+## Core session API
+
+```ts
+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);
+```
+
+- `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.
 
-If a configured field differs, the package deletes the Redis session first and marks its database record as revoked. Clearing the response cookie is client cleanup; Redis deletion is what removes access.
+## Performance and cache policy
 
-Exact IP validation is opt-in because VPN, mobile, and other networks can change a legitimate user's public IP. Platform validation is also opt-in because the client-hint header may be absent. Client-field validation is defense in depth and does not replace TLS, secure cookies, CSRF protection, XSS prevention, or re-authentication for sensitive actions.
+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`.
 
-## Package exports
+Without cache, each `requireSession` performs:
 
 ```text
-@gauts/auth        createAuth and public core types
-@gauts/auth/redis  createRedisStore
-@gauts/auth/hono   createHonoAdapter
+1 Prisma relation lookup by indexed account_sessions.token_hash
 ```
+
+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.
+
+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.
+
+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
+
+```ts
+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.