@gauts/auth 0.8.2 → 0.10.0

package/README.md

@@ -2,7 +2,7 @@
 
 Database-backed password authentication, opaque browser sessions, and optional social authentication for Node.js applications.
 
-`@gauts/auth` provides password hashing, session lifecycle, secure cookies, database validation, optional short caching, Prisma persistence, Hono integration, and Google/GitHub/X OAuth. The application keeps control of credential lookup, business-specific registration data, authorization, responses, and UI.
+`@gauts/auth` provides password hashing, session lifecycle, secure cookies, database validation, optional short caching, Prisma or Drizzle persistence, Hono/Express/Fastify integration, and Google/GitHub/X OAuth. The application keeps control of credential lookup, business-specific registration data, authorization, responses, and UI.
 
 ## Features
 
@@ -12,14 +12,17 @@ Database-backed password authentication, opaque browser sessions, and optional s
 | bcrypt password hashing        |   ✅    | Opt-in              |
 | Opaque server-side sessions    |   ✅    | Enabled             |
 | Database-backed validation     |   ✅    | Enabled             |
-| Sliding session renewal        |   ✅    | Every 24 hours      |
+| Automatic sliding renewal      |   ✅    | Every 24 hours      |
 | Absolute session lifetime      |   ✅    | 30 days             |
 | Signed browser cache           |   ✅    | Disabled            |
 | Full User-Agent validation     |   ✅    | Enabled             |
 | IP validation                  |   ✅    | Disabled            |
 | Platform validation            |   ✅    | Disabled            |
 | Hono adapter                   |   ✅    | Available           |
+| Express adapter                |   ✅    | Available           |
+| Fastify adapter                |   ✅    | Available           |
 | Prisma adapter                 |   ✅    | Available           |
+| Drizzle MySQL/MariaDB adapter  |   ✅    | Available           |
 | Next.js renewal adapter        |   ✅    | Available           |
 | Google social authentication   |   ✅    | Opt-in              |
 | GitHub social authentication   |   ✅    | Opt-in              |
@@ -32,33 +35,46 @@ Database-backed password authentication, opaque browser sessions, and optional s
 | OTP and transactional email    |   ❌    | Application-owned   |
 | Route roles and permissions    |   ❌    | Application-owned   |
 
-“Session renewal” extends the existing session expiry when activity continues. It is not a refresh-token flow and does not rotate the opaque browser token.
+“Session renewal” extends the existing session expiry when authenticated activity continues. Framework middleware performs it inline when due. It is not a refresh-token flow and does not rotate the opaque browser token.
 
 ## Quick start
 
-The application defines its credential login, renewal, logout, and protected endpoints. Optional addons are configured separately after this base setup.
+The application defines its credential login, logout, protected endpoints, and the optional explicit renewal endpoint used by server-rendered frontends. Optional addons are configured separately after this base setup.
 
 ### 1. Install the package
 
-Run these commands inside the Hono API project:
+Install the package and the framework used by the API. Only one framework adapter is required:
 
 ```bash
-npm install @gauts/auth
-npm install hono @prisma/client
+npm install @gauts/auth hono
+npm install @gauts/auth express
+npm install @gauts/auth fastify
 ```
 
-When the Next.js frontend is a separate project, run these commands inside the frontend project:
+When the Next.js frontend is a separate project, run this command inside the frontend project:
 
 ```bash
-npm install @gauts/auth
-npm install next
+npm install @gauts/auth next
 ```
 
-`hono`, `@prisma/client`, and `next` only need to be installed when the corresponding project does not already provide them. The API imports `@gauts/auth/hono` and `@gauts/auth/prisma`; the frontend imports `@gauts/auth/next`.
+Run only the matching API command. `hono`, `express`, `fastify`, and `next` only need to be installed when the corresponding project does not already provide them.
 
-### 2. Add the Prisma schema
+Express TypeScript projects also install its type declarations:
 
-The default adapter uses this fixed relationship tree:
+```bash
+npm install --save-dev @types/express
+```
+
+### 2. Choose the database adapter and schema
+
+One database adapter is required. Prisma and Drizzle are equivalent persistence choices; install and configure only one.
+
+| Adapter | Database support           | Setup                                          |
+| ------- | -------------------------- | ---------------------------------------------- |
+| Prisma  | Prisma-supported databases | [Use Prisma](#option-a--prisma)                |
+| Drizzle | MySQL and MariaDB          | [Use Drizzle](#option-b--drizzle-mysqlmariadb) |
+
+Both schemas use the same relationship tree:
 
 ```text
 users
@@ -66,70 +82,87 @@ users
     └── account_sessions
 ```
 
-Add the three required models to the API schema. Social authentication is an optional addon with its own schema instructions later in this README.
+Social authentication is an optional addon with separate schema instructions later in this README.
 
-```prisma
-model users {
-  id   String @id @default(uuid()) @db.VarChar(255)
-  name String @db.VarChar(255)
+#### Option A — Prisma
 
-  accounts user_accounts[]
-}
+Install Prisma inside the API project:
 
-model user_accounts {
-  id            String  @id @default(uuid()) @db.VarChar(255)
-  user_id       String  @db.VarChar(255)
-  email         String  @unique @db.VarChar(255)
-  password_hash String? @db.VarChar(255)
+```bash
+npm install @prisma/client
+npm install --save-dev prisma
+```
 
-  user     users             @relation(fields: [user_id], references: [id], onDelete: Cascade)
-  sessions account_sessions[]
+[View and copy the Prisma schema](./src/adapters/prisma/schema.prisma) into the application's Prisma schema.
 
-  @@index([user_id])
-}
+Create the migration through the application's Prisma workflow, then regenerate its client:
+
+```bash
+npx prisma migrate dev --name add_auth
+npx prisma generate
+```
 
-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)
-  country     String?   @db.VarChar(2)
-  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)
+Create the database adapter:
 
-  account user_accounts @relation(fields: [account_id], references: [id], onDelete: Cascade)
+```ts
+import { createPrismaAdapter } from "@gauts/auth/prisma";
 
-  @@index([account_id])
-  @@index([expires_at])
-  @@index([revoked_at])
-}
+import { prisma } from "./db.js";
+
+export const authDb = createPrismaAdapter({
+    client: prisma,
+});
 ```
 
-Create the migration through the application's Prisma workflow, then regenerate its client:
+#### Option B — Drizzle MySQL/MariaDB
+
+Install Drizzle and the application's MySQL driver inside the API project:
 
 ```bash
-npx prisma migrate dev --name add_auth
-npx prisma generate
+npm install drizzle-orm mysql2
+npm install --save-dev drizzle-kit
+```
+
+[View and copy the Drizzle MySQL/MariaDB schema](./src/adapters/drizzle/schema.ts) into the application.
+
+Create and apply the migration through the application's Drizzle workflow, then create the database adapter:
+
+```ts
+import { createDrizzleAdapter } from "@gauts/auth/drizzle";
+
+import { db } from "./db.js";
+import { accountSessions, userAccounts, users } from "./schema.js";
+
+export const authDb = createDrizzleAdapter({
+    client: db,
+    models: {
+        accounts: { table: userAccounts },
+        sessions: { table: accountSessions },
+        users: { table: users },
+    },
+});
 ```
 
 ### 3. Create the auth instance and routes
 
-Create the API auth instance:
+This Hono example is identical for Prisma and Drizzle:
+
+Generate one high-entropy API secret and keep it server-side:
+
+```bash
+openssl rand -base64 48
+```
+
+Store the result as `AUTH_SECRET` in the API environment. Do not expose it through a public frontend variable.
 
 ```ts
 import { createHonoAuth } from "@gauts/auth/hono";
-import { createPrismaAdapter } from "@gauts/auth/prisma";
 
-import { prisma } from "./db.js";
+import { authDb } from "./authDb.js";
 
 export const auth = createHonoAuth({
-    db: createPrismaAdapter({
-        client: prisma,
-    }),
+    db: authDb,
+    secret: process.env.AUTH_SECRET!,
 });
 ```
 
@@ -142,7 +175,7 @@ renewal        every 24 hours
 max lifetime   30 days
 validation     User-Agent
 cache          disabled
-cookies        __ses, __cac, __ren
+cookies        __ses, __ctx
 ```
 
 Mount the application-owned login routes and the package middleware:
@@ -202,6 +235,16 @@ app.get("/account", auth.requireSession, (c) => {
 });
 ```
 
+The equivalent framework examples are available here:
+
+| Framework | Simple example                                                  | Advanced example                                                    |
+| --------- | --------------------------------------------------------------- | ------------------------------------------------------------------- |
+| Hono      | [`examples/hono/simple`](./examples/hono/simple/index.ts)       | [`examples/hono/advanced`](./examples/hono/advanced/index.ts)       |
+| Express   | [`examples/express/simple`](./examples/express/simple/index.ts) | [`examples/express/advanced`](./examples/express/advanced/index.ts) |
+| Fastify   | [`examples/fastify/simple`](./examples/fastify/simple/index.ts) | [`examples/fastify/advanced`](./examples/fastify/advanced/index.ts) |
+
+Express exposes authenticated values through `response.locals`. Fastify exposes them through request decorators and requires one `auth.decorate(app)` call before routes are registered. All routes remain application-owned.
+
 When `storedHash` is missing, the package performs password work with the configured algorithm and always returns `false`. Applications do not need a dummy hash. Keep the response identical for unknown accounts and incorrect passwords.
 
 ### 4. Connect the Next.js frontend
@@ -221,7 +264,6 @@ Call it from the Next.js middleware (proxy.ts) on protected routes:
 ```ts
 import type { NextRequest } from "next/server";
 import { NextResponse } from "next/server";
-
 import { nextAuth } from "./lib/auth.js";
 
 export const proxy = async (request: NextRequest) => {
@@ -241,22 +283,28 @@ export const proxy = async (request: NextRequest) => {
 };
 ```
 
-The application owns the redirect URL. When `unauthorizedUrl` is provided, the adapter creates the redirect and copies every API `Set-Cookie` header to it before returning the final response. The frontend does not receive `AUTH_SECRET`; the API remains responsible for session validation.
+The application owns the redirect URL. When `unauthorizedUrl` is provided, the adapter creates the redirect and copies every API `Set-Cookie` header to it before returning the final response. The frontend does not receive `AUTH_SECRET`; it reads only untrusted scheduling dates from `__ctx`. The API verifies the signature and remains responsible for session validation.
 
 ## Requirements and package entry points
 
 - Node.js 22 or newer.
 - A database adapter.
+- Drizzle ORM 0.45.2 or newer when using the Drizzle adapter.
 - Hono 4 when using the Hono adapter.
+- Express 5 when using the Express adapter.
+- Fastify 5 when using the Fastify adapter.
 - Next.js 15 or newer when using the Next.js adapter.
 
-`hono` and `next` are optional peer dependencies. The Prisma adapter receives the application's generated Prisma client and does not import Prisma at runtime.
+`drizzle-orm`, `hono`, `express`, `fastify`, and `next` are optional peer dependencies. Installing or importing one adapter does not load the others. The Prisma adapter receives the application's generated Prisma client and does not import Prisma at runtime. The Drizzle adapter imports `drizzle-orm`, while the application owns the MySQL/MariaDB driver.
 
 | Import                  | Purpose                                                   |
 | ----------------------- | --------------------------------------------------------- |
 | `@gauts/auth`           | Password service, session core, errors, and public types. |
+| `@gauts/auth/drizzle`   | Drizzle database adapter for MySQL and MariaDB.           |
 | `@gauts/auth/prisma`    | Prisma database adapter.                                  |
 | `@gauts/auth/hono`      | Hono cookies, methods, and middleware.                    |
+| `@gauts/auth/express`   | Express cookies, methods, and middleware.                 |
+| `@gauts/auth/fastify`   | Fastify cookies, methods, decorators, and hooks.          |
 | `@gauts/auth/next`      | Next.js renewal scheduling and `Set-Cookie` forwarding.   |
 | `@gauts/auth/providers` | Google, GitHub, and X OAuth providers.                    |
 
@@ -272,7 +320,7 @@ The application owns the redirect URL. When `unauthorizedUrl` is provided, the a
 | `session`  | `SessionConfig`       |            ❌            | Session defaults  | Expiry, renewal, and client validation configuration.                                               |
 | `cookie`   | `HonoCookieConfig`    |            ❌            | Cookie defaults   | Names, domain, path, SameSite, and Secure settings.                                                 |
 | `cache`    | `{ ttl: number }`     |            ❌            | Disabled          | Enables the short signed browser cache.                                                             |
-| `secret`   | `string`              | With `cache` or `social` | —                 | HMAC secret for signed authentication data. Minimum 32 UTF-8 bytes.                                 |
+| `secret`   | `string`              |            ✅            | —                 | HMAC secret for signed session context and optional social data. Minimum 32 UTF-8 bytes.             |
 | `social`   | `SocialConfig`        |            ❌            | Disabled          | Enables configured social providers, redirects, and optional registration.                          |
 
 ```ts
@@ -281,6 +329,8 @@ type HonoGetIp = (c: Context) => Promise<string | null | undefined> | string | n
 
 When `getIp` is omitted, the adapter stores `ip: null` and does not read IP headers automatically. Configuring `session.validation` with `"ip"` requires `getIp` and fails during initialization when it is missing.
 
+`createExpressAuth()` and `createFastifyAuth()` accept the same configuration. Their `getIp` callback receives the native Express or Fastify request instead of a Hono context.
+
 ### Password
 
 #### Argon2id
@@ -363,17 +413,16 @@ renew_at     = min((updated_at ?? created_at) + renewInterval, maxExpiresAt)
 
 ### Cookies
 
-| Property      | Type / allowed values         | Default           | Description                                                               |
-| ------------- | ----------------------------- | ----------------- | ------------------------------------------------------------------------- |
-| `sessionName` | Valid cookie name             | `"__ses"`         | Contains the opaque token. This is the only authenticating cookie.        |
-| `cacheName`   | Valid cookie name             | `"__cac"`         | Contains the optional signed short cache.                                 |
-| `renewName`   | Valid cookie name             | `"__ren"`         | Contains the untrusted `renew_at` Unix timestamp.                         |
-| `domain`      | `string`                      | Browser host only | Optional cookie domain.                                                   |
-| `path`        | String beginning with `/`     | `"/"`             | Cookie path.                                                              |
-| `sameSite`    | `"Strict" \| "Lax" \| "None"` | `"Lax"`           | Browser SameSite policy.                                                  |
-| `secure`      | `boolean`                     | `true`            | Requires HTTPS when enabled. Set `false` only for local HTTP development. |
+| Property      | Type / allowed values         | Default           | Description                                                                                   |
+| ------------- | ----------------------------- | ----------------- | --------------------------------------------------------------------------------------------- |
+| `sessionName` | Valid cookie name             | `"__ses"`         | Contains the opaque token. This is the only authenticating cookie.                            |
+| `contextName` | Valid cookie name             | `"__ctx"`         | Contains signed renewal scheduling and the optional short cache. It never authenticates alone. |
+| `domain`      | `string`                      | Browser host only | Optional cookie domain.                                                                       |
+| `path`        | String beginning with `/`     | `"/"`             | Cookie path.                                                                                  |
+| `sameSite`    | `"Strict" \| "Lax" \| "None"` | `"Lax"`           | Browser SameSite policy.                                                                      |
+| `secure`      | `boolean`                     | `true`            | Requires HTTPS when enabled. Set `false` only for local HTTP development.                     |
 
-All three cookies are always `HttpOnly` and expire with their respective server-side purpose. Their names must be unique.
+Both cookies are always `HttpOnly`, expire with the authoritative session, and must use unique names. Deleting `__ctx` does not log the user out: the next authenticated API request validates `__ses` through the database and rebuilds the signed context. Deleting `__ses` ends browser authentication because `__ctx` is never accepted on its own.
 
 Cookie prefix rules are enforced:
 
@@ -393,53 +442,50 @@ The resolved names are available through:
 
 ```ts
 auth.cookie.sessionName; // "__ses"
-auth.cookie.cacheName; // "__cac"
-auth.cookie.renewName; // "__ren"
+auth.cookie.contextName; // "__ctx"
 ```
 
-### Signed cache
+### Signed session context
 
-| Property    | Type / allowed values               | Default  | Description                                               |
-| ----------- | ----------------------------------- | -------- | --------------------------------------------------------- |
-| `cache.ttl` | Integer `1` to `session.ttl`        | Disabled | Maximum cache lifetime in seconds.                        |
-| `secret`    | String with at least 32 UTF-8 bytes | —        | Signs the cache with HMAC-SHA-256. Required with `cache`. |
+| Property    | Type / allowed values               | Default  | Description                                                        |
+| ----------- | ----------------------------------- | -------- | ------------------------------------------------------------------ |
+| `secret`    | String with at least 32 UTF-8 bytes | Required | Signs `__ctx` with HMAC-SHA-256 and binds it to the opaque token.  |
+| `cache.ttl` | Integer `1` to `session.ttl`        | Disabled | Enables cached account/session data for at most this many seconds. |
 
-The cache:
+The signed context always contains the session expiry and next renewal time. When caching is configured, it may also contain the selected account and session data. The context:
 
-- is cryptographically bound to the opaque token and client identity;
-- is accepted only for `GET` and `HEAD`;
-- never extends the authoritative database session;
-- is bypassed for unsafe methods, renewal, logout, WebSockets, and core calls;
-- falls back to normal database authentication when absent, expired, malformed, or altered.
+- is cryptographically bound to `__ses` and cannot authenticate without it;
+- is verified by the API before any cached data is trusted;
+- exposes untrusted `renew` and `exp` scheduling values to the Next.js adapter without exposing `AUTH_SECRET`;
+- uses cached data only for `GET` and `HEAD`;
+- never extends the authoritative database session by itself;
+- bypasses cached data for unsafe methods, renewal, logout, WebSockets, and core calls;
+- triggers normal database authentication and a fresh signed context when absent, expired, malformed, altered, or bound to another token.
 
-The cache is signed but not encrypted. Do not place passwords, password hashes, raw session tokens, or application secrets in account/session data.
+The context is signed but not encrypted. Do not place passwords, password hashes, raw session tokens, or application secrets in selected account/session data.
 
 <details>
-<summary>Internal compact cache payload</summary>
+<summary>Internal signed context payload</summary>
 
 ```ts
 {
-    exp: cacheExpiresAt,
-    acc: {
-        id,
-        email,
-        name,
-        role,
-        status,
-        timezone,
-        user: { id, role, status },
-    },
-    ses: {
-        id,
-        client: { ip, agent, platform },
-        created_at,
-        exp: expiresAt,
-        ren: renewAt,
-    },
+    cache: {
+        data: {
+            account,
+            session: {
+                client,
+                created,
+                id,
+            },
+        },
+        exp: cacheExpiresAt,
+    } | null,
+    exp: sessionExpiresAt,
+    renew: renewAt,
 }
 ```
 
-`session.account_id` is reconstructed from `acc.id` after signature validation.
+The payload is encoded as `base64url(payload).signature`. The Next.js adapter may decode `exp` and `renew` only as scheduling hints. The API verifies the signature against the current opaque token before using any value. `session.account_id` is reconstructed from `account.id` after verification.
 
 </details>
 
@@ -453,6 +499,8 @@ users
     └── account_sessions
 ```
 
+[View and copy the required Prisma schema](./src/adapters/prisma/schema.prisma).
+
 The required default delegate names are `prisma.users`, `prisma.user_accounts`, and `prisma.account_sessions`. The fixed Prisma relation fields are:
 
 - `user_accounts.user`;
@@ -555,6 +603,77 @@ access: {
 
 Every configured account and user condition must match. Omitting `access` applies no application-specific account restriction.
 
+### Drizzle MySQL/MariaDB adapter
+
+The Drizzle adapter supports MySQL and MariaDB. Install it inside the API project with the driver used by the application:
+
+```bash
+npm install @gauts/auth drizzle-orm mysql2
+```
+
+Unlike Prisma, Drizzle does not expose model delegates that can be discovered by name. Pass the application's table objects explicitly:
+
+```ts
+import { createDrizzleAdapter } from "@gauts/auth/drizzle";
+import { createHonoAuth } from "@gauts/auth/hono";
+import { db } from "./db.js";
+import { accountSessions, userAccounts, users } from "./schema.js";
+
+export const auth = createHonoAuth({
+    db: createDrizzleAdapter({
+        client: db,
+        models: {
+            accounts: { table: userAccounts },
+            sessions: { table: accountSessions },
+            users: { table: users },
+        },
+    }),
+    secret: process.env.AUTH_SECRET!,
+});
+```
+
+The minimum Drizzle schema uses the same relationship tree and canonical TypeScript field names as the Prisma adapter. [View and copy the required Drizzle MySQL/MariaDB schema](./src/adapters/drizzle/schema.ts).
+
+The adapter queries these tables through explicit SQL joins, so Drizzle `relations()` declarations are not required. Physical SQL column names may use aliases, but the TypeScript keys shown above are part of the adapter contract. Date columns must use `{ mode: "date" }`.
+
+`select` and `access` work exactly like the Prisma adapter and are inferred from the supplied table:
+
+```ts
+const database = createDrizzleAdapter({
+    client: db,
+    models: {
+        accounts: {
+            access: {
+                role: ["OWNER", "ADMIN"],
+                status: ["ACTIVE"],
+            },
+            select: ["role", "status", "timezone"],
+            table: userAccounts,
+        },
+        sessions: { table: accountSessions },
+        users: {
+            access: { status: ["ACTIVE", "PENDING"] },
+            select: ["status"],
+            table: users,
+        },
+    },
+});
+```
+
+| Property                 | Required | Description                                                            |
+| ------------------------ | :------: | ---------------------------------------------------------------------- |
+| `client`                 |    ✅    | Drizzle MySQL client created by the application.                       |
+| `models.users.table`     |    ✅    | Table with `id` and `name` columns.                                    |
+| `models.users.select`    |    ❌    | Additional public scalar fields; `id` and `name` are always included.  |
+| `models.users.access`    |    ❌    | Required values for the owning user/entity.                            |
+| `models.accounts.table`  |    ✅    | Table with `id`, `email`, and `user_id` columns.                       |
+| `models.accounts.select` |    ❌    | Additional public scalar fields; `id` and `email` are always included. |
+| `models.accounts.access` |    ❌    | Required values for the authenticating account.                        |
+| `models.sessions.table`  |    ✅    | Table implementing the complete documented session column contract.    |
+| `models.socials.table`   |    ❌    | Enables social persistence when the optional social table is supplied. |
+
+Private password fields are rejected from `select` and `access` by both TypeScript and runtime validation. The adapter does not load or execute the Prisma adapter, and Prisma is not required in a Drizzle application.
+
 ### Next.js adapter
 
 ```ts
@@ -565,11 +684,11 @@ export const nextAuth = createNextAuth({
 });
 ```
 
-| Property             | Type / allowed values            | Required | Default   | Description                                   |
-| -------------------- | -------------------------------- | :------: | --------- | --------------------------------------------- |
-| `renewUrl`           | Absolute `http:` or `https:` URL |    ✅    | —         | Trusted private API renewal endpoint.         |
-| `cookie.sessionName` | Valid cookie name                |    ❌    | `"__ses"` | Session cookie read and forwarded to the API. |
-| `cookie.renewName`   | Valid cookie name                |    ❌    | `"__ren"` | Renewal scheduling cookie read by Next.js.    |
+| Property             | Type / allowed values            | Required | Default   | Description                                              |
+| -------------------- | -------------------------------- | :------: | --------- | -------------------------------------------------------- |
+| `renewUrl`           | Absolute `http:` or `https:` URL |    ✅    | —         | Trusted private API renewal endpoint.                    |
+| `cookie.sessionName` | Valid cookie name                |    ❌    | `"__ses"` | Session cookie read and forwarded to the API.            |
+| `cookie.contextName` | Valid cookie name                |    ❌    | `"__ctx"` | Signed context decoded only to schedule SSR renewal.     |
 
 ## Session flow
 
@@ -582,8 +701,8 @@ credentials accepted
     -> load current account and owning user
     -> apply configured account/user access rules
     -> write __ses
-    -> write __ren
-    -> optionally write __cac
+    -> write signed __ctx with renewal schedule
+    -> optionally include short cached data inside __ctx
 ```
 
 Only the raw browser token authenticates. The database stores only its SHA-256 hash.
@@ -591,12 +710,16 @@ Only the raw browser token authenticates. The database stores only its SHA-256 h
 ### Protected `GET` or `HEAD`
 
 ```text
-session token
-    -> valid signed cache?
-        -> yes: expose cached account and session
-        -> no: validate through DB and create a fresh cache
+__ses + __ctx
+    -> renewal due?
+        -> yes: validate and renew through DB, then write both cookies
+        -> no: valid signed cache?
+            -> yes: expose cached account and session
+            -> no: validate through DB and write a fresh signed context
 ```
 
+Renewal happens inside the same protected API request. A client-side fetch does not need a second renewal request.
+
 ### Unsafe request
 
 ```text
@@ -604,22 +727,22 @@ session token
     -> SHA-256 hash
     -> indexed DB lookup
     -> validate expiry, revocation, account/user access, and client
-    -> clear short cache
+    -> write signed context without cached account data
     -> continue
 ```
 
-### Renewal
+### Next.js SSR renewal
 
 ```text
-Next reads __ren
-    -> future timestamp: no API request
+Next decodes renew and exp from __ctx as untrusted hints
+    -> future timestamps: no renewal request
     -> missing, invalid, or due: POST /auth/renew
     -> API validates through DB
     -> update expires_at when renewal is due
-    -> Set-Cookie with the same token, new renewAt, and fresh cache
+    -> Set-Cookie with the same token and fresh signed context
 ```
 
-`auth.session.resolve()` is always DB-backed and read-only. Only explicit renewal updates database expiry.
+`auth.session.resolve()` is always DB-backed and read-only. `auth.session.renew()` performs the authoritative renewal. Framework `requireSession` calls it automatically when the verified context says renewal is due; the explicit endpoint gives Next.js the same behavior during SSR navigation.
 
 ## Hono adapter
 
@@ -657,7 +780,7 @@ type Session = {
 };
 ```
 
-The Prisma adapter refines `account` and `user` with the exact additional scalar fields declared in their respective `select` arrays.
+The Prisma and Drizzle adapters refine `account` and `user` with the exact additional scalar fields declared in their respective `select` arrays.
 
 Only `account_id` is copied into the session row. Current account/user data is loaded through the fixed database relations and is never duplicated in the session table.
 
@@ -673,14 +796,14 @@ await auth.createSession({
 });
 ```
 
-`country` is normalized to uppercase and is never used for authentication or client matching. It is not resolved by the package and does not trigger GeoIP work during normal requests. When supplied, the configured session model must provide a nullable `country` column. When omitted, the Prisma adapter does not send the field.
+`country` is normalized to uppercase and is never used for authentication or client matching. It is not resolved by the package and does not trigger GeoIP work during normal requests. When supplied, the configured session model must provide a nullable `country` column. When omitted, the database adapter does not send the field.
 
 ### Methods
 
 | Method                                                  | Purpose                                                                                           |
 | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
 | `auth.createSession({ account_id, context, country? })` | Creates the DB session and writes the browser cookies. `country` is optional login-time metadata. |
-| `auth.resolveSession(context)`                          | Resolves a request and returns the selected account and session.                                  |
+| `auth.resolveSession(context)`                          | Resolves a request, renews inline when due, and returns the selected account and session.          |
 | `auth.renewSession(context)`                            | Performs DB validation, renews when due, and writes authoritative cookies.                        |
 | `auth.revokeSession(context)`                           | Revokes the current DB session and clears cookies.                                                |
 | `auth.clearSession(context)`                            | Clears browser cookies without revoking the DB session.                                           |
@@ -689,11 +812,69 @@ await auth.createSession({
 
 `requireSession` authenticates only. Application-specific route permissions remain the application's responsibility.
 
+## Express adapter
+
+```ts
+import { createExpressAuth, type ExpressAuthLocals } from "@gauts/auth/express";
+
+const auth = createExpressAuth({ db, secret: process.env.AUTH_SECRET! });
+
+app.get("/account", auth.requireSession, (_request, response) => {
+    const { account, session, user } = response.locals as ExpressAuthLocals;
+    response.json({ account, session, user });
+});
+```
+
+| Method                                                            | Purpose                                              |
+| ----------------------------------------------------------------- | ---------------------------------------------------- |
+| `auth.createSession({ account_id, request, response, country? })` | Creates the DB session and writes cookies.           |
+| `auth.resolveSession({ request, response })`                      | Resolves and automatically renews when due.           |
+| `auth.renewSession({ request, response })`                        | Renews when due and writes authoritative cookies.    |
+| `auth.revokeSession({ request, response })`                       | Revokes the current session and clears cookies.      |
+| `auth.clearSession(response)`                                     | Clears cookies without revoking the DB session.      |
+| `auth.getToken(request)`                                          | Reads and validates the opaque session token.        |
+| `auth.requireSession`                                             | Express middleware that populates `response.locals`. |
+
+Express 5 forwards rejected async middleware promises to the application's error handler. The adapter does not install routes or an error handler.
+
+## Fastify adapter
+
+Register the request decorators once before declaring routes:
+
+```ts
+import { createFastifyAuth } from "@gauts/auth/fastify";
+
+const auth = createFastifyAuth({ db, secret: process.env.AUTH_SECRET! });
+
+auth.decorate(app);
+
+app.get("/account", { preHandler: auth.requireSession }, (request) => ({
+    account: request.getDecorator("account"),
+    session: request.getDecorator("session"),
+    user: request.getDecorator("user"),
+}));
+```
+
+| Method                                                         | Purpose                                                        |
+| -------------------------------------------------------------- | -------------------------------------------------------------- |
+| `auth.decorate(app)`                                           | Declares the native request decorators once at startup.        |
+| `auth.createSession({ account_id, request, reply, country? })` | Creates the DB session and writes cookies.                     |
+| `auth.resolveSession({ request, reply })`                      | Resolves and automatically renews when due.                     |
+| `auth.renewSession({ request, reply })`                        | Renews when due and writes authoritative cookies.              |
+| `auth.revokeSession({ request, reply })`                       | Revokes the current session and clears cookies.                |
+| `auth.clearSession(reply)`                                     | Clears cookies without revoking the DB session.                |
+| `auth.getToken(request)`                                       | Reads and validates the opaque session token.                  |
+| `auth.requireSession`                                          | Fastify `preHandler` that populates native request decorators. |
+
+When social authentication is enabled, `auth.decorate(app)` also declares `social`. The adapter does not register a Fastify plugin or create routes.
+
 ## Social authentication
 
 Social authentication is an optional addon and remains disabled unless `social` is configured. Complete these steps only in applications that need Google, GitHub, or X authentication.
 
-### 1. Add the social Prisma schema
+### 1. Add social persistence
+
+#### Prisma
 
 Add the social relation inside the existing `user_accounts` model in the API schema:
 
@@ -745,6 +926,49 @@ const db = createPrismaAdapter({
 });
 ```
 
+#### Drizzle MySQL/MariaDB
+
+Add the provider table to the API schema:
+
+```ts
+export const socialAccounts = mysqlTable(
+    "social_accounts",
+    {
+        account_id: varchar("account_id", { length: 255 })
+            .notNull()
+            .references(() => userAccounts.id, { onDelete: "cascade" }),
+        created_at: timestamp("created_at", { mode: "date" }).defaultNow().notNull(),
+        id: varchar("id", { length: 255 }).primaryKey(),
+        provider: varchar("provider", { length: 32 }).notNull(),
+        provider_id: varchar("provider_id", { length: 255 }).notNull(),
+    },
+    (table) => [
+        index("social_accounts_account_id_idx").on(table.account_id),
+        uniqueIndex("social_accounts_provider_provider_id_key").on(
+            table.provider,
+            table.provider_id,
+        ),
+        uniqueIndex("social_accounts_account_id_provider_key").on(table.account_id, table.provider),
+    ],
+);
+```
+
+Then supply it to the adapter:
+
+```ts
+const db = createDrizzleAdapter({
+    client,
+    models: {
+        accounts: { table: userAccounts },
+        sessions: { table: accountSessions },
+        socials: { table: socialAccounts },
+        users: { table: users },
+    },
+});
+```
+
+Omitting `models.socials` keeps the Drizzle adapter session-only. The adapter creates the owning user and account in one transaction during default social registration, so that path requires a Drizzle MySQL driver with transaction support. Additional required user/account columns must have database defaults; otherwise the application must provide `registration.createAccount`.
+
 ### 2. Configure the providers
 
 Import only the providers used by the API:
@@ -783,7 +1007,7 @@ Register every `callbackUrl` shown above in the corresponding provider dashboard
 
 ### 3. Add the API route and frontend start
 
-Declare one dynamic API route covering every configured provider. `social.handle` is Hono middleware: it completes `start` and expected error responses itself, then calls the application handler only after a successful callback.
+Declare one dynamic API route covering every configured provider. `social.handle` completes `start` and expected error responses itself, then continues to the application handler only after a successful callback.
 
 ```ts
 app.get("/auth/social/:provider/:action", auth.social.handle, async (c) => {
@@ -827,16 +1051,28 @@ social.registered;
 social.returnTo;
 ```
 
+The native equivalents are:
+
+```ts
+// Express
+const social = (response.locals as ExpressSocialLocals).social;
+
+// Fastify
+const social = request.getDecorator<SocialAuthenticated>("social");
+```
+
+See the advanced framework examples for complete social routes and custom registration.
+
 The package does not create the application route, session, notifications, logs, or final success response. Those remain explicit in the route handler.
 
 ### Social configuration
 
-| Property                     | Type / allowed values                |  Required   | Default   | Description                                                                |
-| ---------------------------- | ------------------------------------ | :---------: | --------- | -------------------------------------------------------------------------- |
-| `social.providers`           | `SocialProvider[]`                   |     ✅      | —         | Configured Google, GitHub, or X providers.                                 |
-| `social.cookieName`          | Valid cookie name                    |     ❌      | `"__soc"` | Signed temporary OAuth/registration transaction cookie.                    |
-| `social.registration`        | `SocialRegistrationConfig`           |     ❌      | Disabled  | Enables default or application-specific social registration.               |
-| `registration.createAccount` | Async callback returning `accountId` |     ❌      | Built-in  | Creates required business data when the default structure is insufficient. |
+| Property                     | Type / allowed values                | Required | Default   | Description                                                                |
+| ---------------------------- | ------------------------------------ | :------: | --------- | -------------------------------------------------------------------------- |
+| `social.providers`           | `SocialProvider[]`                   |    ✅    | —         | Configured Google, GitHub, or X providers.                                 |
+| `social.cookieName`          | Valid cookie name                    |    ❌    | `"__soc"` | Signed temporary OAuth/registration transaction cookie.                    |
+| `social.registration`        | `SocialRegistrationConfig`           |    ❌    | Disabled  | Enables default or application-specific social registration.               |
+| `registration.createAccount` | Async callback returning `accountId` |    ❌    | Built-in  | Creates required business data when the default structure is insufficient. |
 
 Provider configuration:
 
@@ -952,7 +1188,7 @@ app.post("/auth/register/social", async (c) => {
 
 ### Core and adapter composition
 
-`createHonoAuth()` is the normal entry point. Use separate composition only when the same core instance is required outside Hono:
+Use the entry point matching the application framework: `createHonoAuth()`, `createExpressAuth()`, or `createFastifyAuth()`. Use separate composition only when the same core instance is required outside the framework adapter:
 
 ```ts
 import { createAuth } from "@gauts/auth";
@@ -961,12 +1197,13 @@ import { createHonoAdapter } from "@gauts/auth/hono";
 const core = createAuth({ db });
 const hono = createHonoAdapter({
     auth: core,
+    secret: process.env.AUTH_SECRET!,
 });
 ```
 
 ## Next.js adapter
 
-The Next.js adapter schedules renewal; it does not authenticate pages or API requests.
+The Next.js adapter schedules SSR renewal; it does not authenticate pages or API requests. Normal API middleware independently verifies `__ctx` and renews inline, including requests made directly by client-side SWR or `fetch`.
 
 ```ts
 import type { NextRequest } from "next/server";
@@ -992,13 +1229,13 @@ Result values:
 
 | `attempted` |    `status` | Meaning                                                         |
 | :---------: | ----------: | --------------------------------------------------------------- |
-|   `false`   |      `null` | Session token exists and renewal is not due.                    |
+|   `false`   |      `null` | Session token and context schedule exist; renewal is not due.   |
 |   `false`   |       `401` | Session token is missing or malformed; no API request occurred. |
 |   `true`    | HTTP status | The renewal endpoint was called and returned this status.       |
 
 `unauthorizedUrl` is optional. When provided, the adapter redirects a `401` to that relative or absolute URL and transfers every returned `Set-Cookie` header to the redirect. Without it, the original response is returned with `status: 401` as before.
 
-The adapter forwards only the session cookie and controlled client/origin headers required by the private API. Other cookies, authorization headers, and arbitrary headers are not forwarded.
+The adapter forwards only the session cookie and controlled client/origin headers required by the private API. `__ctx` is not forwarded because the API renewal endpoint always validates the opaque token through the database and returns a new signed context. Other cookies, authorization headers, and arbitrary headers are not forwarded.
 
 `buildForwardHeaders()` and `FORWARD_HEADERS` are exported from `@gauts/auth/next` for application fetchers that need the same controlled forwarding rules:
 
@@ -1015,7 +1252,7 @@ Safe client and proxy metadata is copied by default. Credentials such as `cookie
 
 When `Origin` is absent and trusted `X-Forwarded-Proto` and `X-Forwarded-Host` headers exist, the adapter reconstructs the public origin from them. It never derives a public origin from the internal Next.js request URL. The deployment proxy must overwrite forwarded headers received from untrusted clients.
 
-Apply renewal only to protected routes or skip public routes before calling `nextAuth.renew()`.
+Apply renewal only to protected routes or skip public routes before calling `nextAuth.renew()`. The adapter calls the API only when `__ctx` is missing, malformed, expired, or its decoded renewal time is due. Those decoded dates are untrusted scheduling hints; they never authenticate the request.
 
 ## Core session API
 
@@ -1074,15 +1311,15 @@ const socialDb = {
 } satisfies SocialDbAdapter;
 ```
 
-The Prisma adapter already implements both `DbAdapter` and `SocialDbAdapter`.
+The Prisma and Drizzle adapters implement both `DbAdapter` and `SocialDbAdapter` when their optional social model is available.
 
 ## Performance
 
 The package contains no Redis or in-process cache.
 
-Without the optional browser cache, each `requireSession` performs an indexed database lookup through `account_sessions.token_hash`.
+Without the optional browser cache, each `requireSession` performs an indexed database lookup through `account_sessions.token_hash`. When renewal is due, that same request also updates the authoritative expiry and returns refreshed cookies; there is no additional client-side API call.
 
-With a valid cache, `GET` and `HEAD` skip the lookup until `cache.ttl` expires. Unsafe methods always use current database state.
+With valid cached data inside `__ctx`, `GET` and `HEAD` skip the lookup until `cache.ttl` expires. Unsafe methods always use current database state. Renewal still validates through the database even if cached data is present.
 
 The tradeoff is explicit: revocation and selected account or relation changes made elsewhere may remain visible to safe cached requests until the short TTL expires. A 60-second TTL limits this stale-read window to one minute. Disable cache when immediate read revocation is required.
 
@@ -1134,7 +1371,6 @@ The package provides authentication primitives, not a complete application secur
 - TLS and trusted-proxy configuration;
 - CSRF, CORS, host, and origin validation;
 - login and renewal rate limiting;
-- equivalent password verification work for unknown accounts;
 - route roles and authorization;
 - re-authentication for sensitive operations;
 - database migrations and session cleanup;