@luckystack/login 0.1.0

package/docs/session-management.md

@@ -0,0 +1,286 @@
+# Session management
+
+Deep-dive on `saveSession` / `getSession` / `deleteSession`, sliding expiration, single-session enforcement, and the swappable `SessionAdapter`. Canonical sources: [`./src/session.ts`](../src/session.ts) and [`./src/sessionAdapter.ts`](../src/sessionAdapter.ts).
+
+---
+
+## Storage layout (defaults — Redis adapter)
+
+| Key                                                | Type       | Contents                                                                          |
+| -------------------------------------------------- | ---------- | --------------------------------------------------------------------------------- |
+| `${projectName}-session:<token>`                   | string     | JSON-encoded `BaseSessionLayout` (id, email, name, csrfToken, custom fields).     |
+| `${projectName}-activeUsers:<userId>`              | set        | Tokens currently associated with this user. Read by single-session enforcement.   |
+| `${projectName}-oauth-state:<provider>:<state>`    | string     | `'1'` sentinel + TTL. Consumed atomically on OAuth callback. (See `login.ts`.)    |
+| `${projectName}-pwreset:<token>`                   | string     | `userId` bound to the reset token. (See [`./password-reset.md`](./password-reset.md).) |
+
+`projectName` comes from `getProjectName()` in `@luckystack/core` — a single source of truth so the namespace is identical across sessions, activeUsers, OAuth state, password reset, and rate-limit.
+
+The keys are exported as helpers for downstream admin tooling that reads Redis directly:
+
+```ts
+import { sessionKeyFor, activeUsersKeyFor } from '@luckystack/login';
+
+// In an admin script:
+const raw = await redis.get(sessionKeyFor(token));
+const tokens = await redis.smembers(activeUsersKeyFor(userId));
+```
+
+For new code, prefer `getSessionAdapter()` so the keys stay encapsulated and a non-Redis adapter doesn't break the tooling.
+
+## API surface
+
+```ts
+saveSession(token: string, data: SessionLayout, newUser?: boolean): Promise<void>;
+getSession(token: string | null): Promise<SessionLayout | null>;
+deleteSession(token: string): Promise<boolean>;
+getAllSessions(): Promise<SessionLayout[]>;
+revokeUserSessions(userId: string, exceptToken?: string | null): Promise<number>;
+sessionKeyFor(token: string): string;
+activeUsersKeyFor(userId: string): string;
+```
+
+`SessionLayout` is the framework's `BaseSessionLayout` from `@luckystack/core`, augmentable via module declaration — see [`./oauth-providers.md`](./oauth-providers.md) for the `extraSessionFields` pattern.
+
+## `saveSession` — write path
+
+The full sequence on a `newUser: true` save:
+
+1. **`preSessionCreate` dispatch** — `{ token, user, persistent: !session.basedToken }`. A handler can return a stop signal; the warn-log surfaces the `errorCode` and the function returns without writing.
+2. **CSRF token mint** — if `data.csrfToken` is not present, mint a fresh 32-byte hex token and write it onto the data. Subsequent writes preserve it so the client doesn't need to re-fetch on every session update. Rotated on logout (via `deleteSession`).
+3. **Adapter write** — `adapter.setRaw(token, JSON.stringify(data), ttl)`. TTL = `session.expiryDays * 86400`.
+4. **`trackActive`** — `adapter.trackActive(userId, token, ttl)` so the active-tokens set is in sync.
+5. **Single-session enforcement** — see the next section.
+6. **Broadcast** — if a socket is in the token room (`io.sockets.adapter.rooms.has(token)`), emit `socketEventNames.updateSession` with the new JSON. Drives client-side session refresh without a round-trip.
+7. **`postSessionCreate` dispatch** — same payload as the pre-version.
+
+On a `newUser: false` save (used for in-place session edits — admin promoting a user, settings update, etc.), steps 1 / 5 / 7 are skipped. Steps 2, 3, 4, 6 still run.
+
+`saveSession` is wrapped in `tryCatch` end-to-end; errors are logged but never thrown out of the function. A failed save does not block the request that triggered it — but does mean the session is stale, so the next `getSession` will re-read from Redis if it can.
+
+## Sliding expiration — `getSession`
+
+```
+preSessionRefresh (can stop the TTL extend) → adapter.expire(token, newTtl) → postSessionRefresh
+```
+
+Each authenticated `getSession` call extends the TTL by `session.expiryDays`. That means an active user is never logged out by the framework — only an idle one whose sliding window expires.
+
+The hook gate exists for use cases like:
+
+- **Admin freezing a session** — `preSessionRefresh` returns a stop signal while the admin reviews the account; the session keeps its current TTL but is not extended further, so it expires naturally even while the user keeps refreshing the page.
+- **Sliding-window analytics** — `postSessionRefresh` receives `{ token, userId, oldTtl, newTtl, applied }` and is the canonical place to track "user is active right now" without re-reading the session.
+
+`applied` reflects whether `adapter.expire` actually extended the TTL (true) or was skipped (false — either because the record was already gone, or because `preSessionRefresh` stopped the extend). Audit handlers should branch on `applied` to distinguish "user is active" from "user has a hold on their session".
+
+Return value: the parsed `SessionLayout` with the `token` re-injected, or `null` when the token is missing / record is gone / the JSON failed to parse.
+
+## `deleteSession` — write path with visible stacktrace
+
+```ts
+getLogger().warn('[session] deleteSession invoked', {
+  tokenPrefix: token.slice(0, 8),
+  stack: new Error('deleteSession invoked').stack,
+});
+```
+
+The function intentionally warn-logs with a stacktrace BEFORE doing anything — same reasoning as the `logout` warn-log: spurious deletes silently kick users, and the stacktrace is the smoking gun.
+
+After the warn-log:
+
+1. **Read raw** — `adapter.getRaw(token)` to extract `userId` from the JSON. Used as the hook payload's `userId` and to clean up the active-users set.
+2. **`preSessionDelete` dispatch** — `{ token, userId: resolvedUserId | null }`. Stop signal warn-logs and returns `false`.
+3. **Logout connected sockets** — if `getIoInstance()` is up and there are sockets in the token room, call `logout(...)` for each one with `skipSessionDelete: true` (we're already inside the delete; don't recurse). See [`./logout-flow.md`](./logout-flow.md).
+4. **`adapter.untrackActive`** — removes the token from the active-users set.
+5. **`adapter.delete`** — removes the session record itself.
+6. **`postSessionDelete` dispatch** — same payload as pre.
+7. **Return** `true` on success, `false` when stopped or when an error bubbled.
+
+When `getRaw` returned null (the record was already gone), the function still dispatches the pre/post hooks (with `userId: null`) and calls `adapter.delete` for idempotency, but skips the socket-walk and `untrackActive` because there's nothing to clean up.
+
+## `getAllSessions` — graceful degradation
+
+```ts
+if (!adapter.listAll) {
+  getLogger().warn(`[session] getAllSessions: adapter '${adapter.name}' does not implement listAll — returning empty`);
+  return [];
+}
+```
+
+Some adapters can't enumerate by design — signed-JWT-stateless adapters have no storage to walk; log-only / audit-only adapters might shed reads. Rather than throw, the function warn-logs once and returns `[]`. Admin code should treat the empty result as "this adapter is not scannable" rather than "this user has no sessions".
+
+The Redis adapter implements `listAll` via `SCAN` over `${projectName}-session:*`, collecting `{ token, raw }` pairs. The walk paginates with `COUNT 100` so it doesn't block the event loop on large stores.
+
+## `revokeUserSessions(userId, exceptToken?)`
+
+Pure orchestration on top of `deleteSession`:
+
+```ts
+const tokens = await adapter.listActive(userId);
+const targets = exceptToken ? tokens.filter((t) => t !== exceptToken) : tokens;
+await Promise.all(targets.map((token) => deleteSession(token)));
+return targets.length;
+```
+
+`exceptToken` is the "keep me signed in" escape hatch:
+
+- After a password change: call with the current request's token so the user stays signed in on the device they just changed it on.
+- After account deletion / "sign out everywhere": omit `exceptToken` to revoke every session including the caller's.
+
+The return value is the number of sessions revoked, which lets the caller surface "Signed out of N other devices" in the UI.
+
+## Single-session enforcement
+
+When a `newUser: true` `saveSession` runs, the function decides which (if any) previous sessions to kick. The decision tree:
+
+```
+let effectivePerUser = sessionCfg.allowMultiple ? 'multiple' : sessionCfg.perUser;
+const cap = sessionCfg.maxConcurrentPerUser;
+const previousTokens = (await adapter.listActive(userId)).filter(t => t !== token);
+
+if (effectivePerUser === 'single') {
+  tokensToKick = previousTokens;                              // kick all
+} else if (
+  effectivePerUser === 'multiple' &&
+  cap !== null &&
+  previousTokens.length + 1 > cap &&
+  sessionCfg.onConflict === 'revokeOld'
+) {
+  const excess = previousTokens.length + 1 - cap;
+  tokensToKick = previousTokens.slice(0, excess);             // kick oldest until under cap
+}
+// else (multiple, no cap; or multiple + 'rejectNew') — nothing to kick here
+```
+
+Reading the config:
+
+| Slot                                  | Possible values                | Behavior                                                                                                |
+| ------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------- |
+| `session.perUser`                     | `'single'` / `'multiple'`      | `'single'` (default) — only one session at a time. `'multiple'` — pair with `maxConcurrentPerUser`.     |
+| `session.allowMultiple` (legacy)      | `boolean`                      | When `false`, collapses to `'single'` regardless of `perUser`. Backward-compat shim.                    |
+| `session.maxConcurrentPerUser`        | `number \| null`               | Cap on simultaneous sessions when `perUser === 'multiple'`. `null` = unlimited.                          |
+| `session.onConflict`                  | `'revokeOld'` / `'rejectNew'`  | What to do when the cap is reached. `'revokeOld'` kicks oldest; `'rejectNew'` refuses the new login.    |
+| `session.notifyOldDeviceOnRevoke`     | `boolean`                      | Emit `socketEventNames.sessionReplaced` to the kicked socket before the disconnect.                     |
+| `session.basedToken`                  | `boolean`                      | Used to compute `persistent: !basedToken` for `preSessionCreate` / `postSessionCreate`.                 |
+| `session.expiryDays`                  | `number`                       | Multiplied by 86400 to get the TTL in seconds.                                                          |
+
+`onConflict === 'rejectNew'` is enforced at the API layer (the login endpoint refuses the request), not inside `saveSession` — by the time we reach `saveSession` the decision to allow the login has already been made.
+
+For each token in `tokensToKick`:
+
+```ts
+const sockets = io.sockets.adapter.rooms.get(previousToken);
+if (sockets) {
+  if (sessionCfg.notifyOldDeviceOnRevoke) {
+    io.to(previousToken).emit(socketEventNames.sessionReplaced, JSON.stringify({
+      reason: 'session-replaced',
+      userId,
+    }));
+  }
+  for (const socketId of sockets) {
+    const socket = io.sockets.sockets.get(socketId);
+    if (socket) {
+      await logout({ token: previousToken, socket, userId });
+    }
+  }
+} else {
+  // No active sockets — just clean up the adapter state.
+  await adapter.delete(previousToken);
+  await adapter.untrackActive(userId, previousToken);
+}
+```
+
+The two branches matter: with sockets, the disconnect-flow runs end-to-end. Without sockets (the user was offline), only the storage cleanup runs — there's no socket to emit to and no presence state to tear down.
+
+### Ordering caveat
+
+The single-session-enforcement logic kicks "the oldest" tokens by dropping the head of `previousTokens.slice(0, excess)`. There is no LRU metadata in the adapter contract — adapters return insertion-order for set-like structures, which is good enough for the common case but not a strict guarantee.
+
+If you need precise LRU semantics (e.g. a "kick the device the user hasn't used the most recently" UX), implement a custom `SessionAdapter` that tracks per-token last-touch timestamps in a sorted structure (Redis `ZSET`, Postgres `last_seen DESC`, DynamoDB GSI on `lastSeenAt`).
+
+## `SessionAdapter` contract
+
+```ts
+interface SessionAdapter {
+  name: string;
+  getRaw(token: string): Promise<string | null>;
+  setRaw(token: string, value: string, ttlSeconds: number): Promise<void>;
+  delete(token: string): Promise<void>;
+  expire(token: string, ttlSeconds: number): Promise<boolean>;
+  ttl(token: string): Promise<number | null>;
+  trackActive(userId: string, token: string, ttlSeconds: number): Promise<void>;
+  untrackActive(userId: string, token: string): Promise<void>;
+  listActive(userId: string): Promise<string[]>;
+  listAll?(): Promise<{ token: string; raw: string }[]>;
+}
+```
+
+Semantics:
+
+| Method          | Required behavior                                                                                                          |
+| --------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `getRaw`        | Return the stored string for the token, or `null` when missing.                                                            |
+| `setRaw`        | Persist the value with the given TTL. Implementations MUST honour the TTL — sessions without one would never expire.        |
+| `delete`        | Idempotent removal. No-op when the record is already gone.                                                                 |
+| `expire`        | Refresh the TTL only if the record exists. Return `true` when refreshed, `false` otherwise. MUST NOT create on miss.        |
+| `ttl`           | Remaining TTL in seconds, or `null` when the record is missing.                                                            |
+| `trackActive`   | Add `token` to the per-user set. Set itself MUST have the same TTL (the longest active session keeps the set alive).        |
+| `untrackActive` | Remove `token` from the per-user set. Idempotent.                                                                          |
+| `listActive`    | Return the current per-user set. Empty array (never throw) when missing.                                                   |
+| `listAll`       | Optional admin walk. Omit when the backend cannot enumerate.                                                               |
+
+`name` is a human-readable identifier surfaced in logs. The default Redis adapter is `'redis'`.
+
+## Writing a custom adapter
+
+```ts
+import { registerSessionAdapter, type SessionAdapter } from '@luckystack/login';
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+
+const dynamoAdapter: SessionAdapter = {
+  name: 'dynamodb',
+  async getRaw(token) { /* GetItem */ },
+  async setRaw(token, value, ttlSeconds) { /* PutItem with TTL attribute */ },
+  async delete(token) { /* DeleteItem */ },
+  async expire(token, ttlSeconds) { /* UpdateItem with condition exists */ },
+  async ttl(token) { /* GetItem read TTL attribute */ },
+  async trackActive(userId, token, ttlSeconds) { /* UpdateItem ADD to a SS attribute */ },
+  async untrackActive(userId, token) { /* UpdateItem DELETE from SS */ },
+  async listActive(userId) { /* GetItem read SS */ },
+  // listAll omitted — DynamoDB Scan is too expensive in production
+};
+
+registerSessionAdapter(dynamoAdapter);
+```
+
+Common adapter shapes consumers have shipped:
+
+- **DynamoDB / Cosmos DB** — serverless / edge deployments where Redis is operationally inconvenient.
+- **Postgres `sessions` table** — when you already operate Postgres and don't want a second datastore. Per-token row with `userId`, `data` (JSON column), `expiresAt`.
+- **Signed-JWT-stateless** — `getRaw` decodes the JWT, `setRaw` is a no-op (the JWT IS the storage), `trackActive` writes to a small Redis hash so single-session enforcement still works. `listAll` is omitted.
+- **In-memory mock** — for integration tests. A `Map<string, { value, expiresAt }>` with a setInterval-based expiration sweep.
+
+Call `registerSessionAdapter(...)` once at boot from `luckystack/server/index.ts`, BEFORE the first login request. Last-write-wins on subsequent calls (you can swap adapters in tests this way).
+
+## `getSessionAdapter`
+
+Reads the currently-active adapter. Defaults to `redisSessionAdapter` when no `registerSessionAdapter` call has happened. The default adapter is exported as `redisSessionAdapter` for cases where consumer code wants to compose around it (e.g. a wrapper adapter that delegates to Redis but also writes to an audit log).
+
+## Why a separate broadcast on `updateSession`
+
+When `saveSession` writes a `newUser: false` update — for instance an admin granting a user the `admin` flag from a settings page — the broadcast pushes the new session JSON to every socket already in the token room. The client-side `SessionProvider` listens for `socketEventNames.updateSession` and merges the payload into its in-memory session state.
+
+This means:
+
+- Permission changes apply instantly across all the user's open tabs.
+- Profile updates (name, avatar) reflect in the navbar without a refresh.
+- Custom session fields (e.g. `googleCalendarToken` set via `extraSessionFields`) flow to the client the same way.
+
+The broadcast is gated on `io.sockets.adapter.rooms.has(token)` so a save targeting an offline user doesn't waste an emit.
+
+## Related
+
+- [`./logout-flow.md`](./logout-flow.md) — `logout` and `deleteSession`'s socket-walk.
+- [`./hooks.md`](./hooks.md) — `preSessionCreate` / `postSessionCreate` / `preSessionDelete` / `postSessionDelete` / `preSessionRefresh` / `postSessionRefresh`.
+- [`./credentials-auth.md`](./credentials-auth.md) — what calls `saveSession(token, user, true)`.
+- [`./oauth-providers.md`](./oauth-providers.md) — `extraSessionFields` and module-augmentation of `BaseSessionLayout`.
+- Architecture: [`/docs/ARCHITECTURE_SESSION.md`](../../../docs/ARCHITECTURE_SESSION.md).

package/docs/user-adapter.md

@@ -0,0 +1,353 @@
+# User adapter
+
+Deep-dive on the `UserAdapter` extension point — the abstraction between auth flows and the consumer's user data store. Canonical source: [`./src/userAdapter.ts`](../src/userAdapter.ts).
+
+---
+
+## Why a User Adapter
+
+`@luckystack/login` ships a default that reads and writes the framework's recommended Prisma `User` model:
+
+```prisma
+model User {
+  id              String   @id @default(cuid())
+  email           String   @unique
+  provider        String   // enum: PROVIDERS in your schema
+  password        String?
+  name            String?
+  avatar          String?
+  avatarFallback  String?
+  language        String?
+  // lastLogin?    DateTime?   // optional — best-effort updated on each login
+}
+```
+
+That default covers single-tenant apps with the canonical schema. The adapter exists for everything else:
+
+- **Multi-tenant** — every query should be scoped by `tenantId` read from `AsyncLocalStorage`.
+- **Soft delete** — `findByEmail` / `findById` should filter `deletedAt: null`.
+- **Renamed columns** — your schema calls it `displayName` instead of `name`, or `emailAddress` instead of `email`.
+- **Additional required columns** — your `User` model has a non-nullable `organizationId` that the framework can't supply.
+- **Non-Prisma data layer** — Drizzle, Kysely, raw `pg`, a REST microservice, a GraphQL gateway.
+- **Read-replica routing** — `findByEmail` hits the replica, `create` / `update` hit the primary.
+
+The adapter has exactly four methods. Implement them and call `registerUserAdapter(adapter)` at boot.
+
+## API surface
+
+```ts
+interface UserAdapter {
+  findByEmail: (params: { email: string; provider: string }) => Promise<UserRecord | null>;
+  findById:    (id: string) => Promise<UserRecord | null>;
+  create:      (input: UserAdapterCreateInput) => Promise<UserRecord>;
+  update:      (id: string, patch: Partial<UserRecord>) => Promise<UserRecord>;
+}
+
+registerUserAdapter(adapter: UserAdapter): UserAdapter;
+getUserAdapter(): UserAdapter;
+isUserAdapterRegistered(): boolean;
+defaultPrismaUserAdapter(): UserAdapter;
+```
+
+`registerUserAdapter` is last-write-wins. `getUserAdapter` returns the registered adapter, or falls back to `defaultPrismaUserAdapter()` lazily on first call. `isUserAdapterRegistered()` returns `true` iff a custom adapter has been registered — useful when an integration package wants to bail with a helpful error if the consumer hasn't yet swapped the default.
+
+## Required methods
+
+### `findByEmail({ email, provider })`
+
+Lookup a user by their (email, provider) pair. The pair is the unique identity in the framework — the same email registered via `'credentials'` and via `'google'` are two different `UserRecord`s. Return `null` when no row matches.
+
+Called from:
+
+- `registerWithCredentials` — duplicate-email guard.
+- `loginWithCredentialsCore` — find-the-user-to-authenticate.
+- `loginCallback` (OAuth) — find-or-create branch.
+- `sendPasswordResetEmail` — locate the credentials user behind a reset request.
+
+### `findById(id)`
+
+Lookup a user by id. Returns `null` when missing. Called by consumer-side code that needs a fresh user read by id; the framework itself uses `findByEmail` everywhere except for hooks that pass `userId` and want the live record.
+
+### `create(input)`
+
+Insert a new user. `UserAdapterCreateInput` is intentionally loose (string-typed fields) because the framework cannot statically know consumer-side Prisma enums for `provider` / `language`:
+
+```ts
+interface UserAdapterCreateInput {
+  email: string;
+  provider: string;
+  name?: string | null;
+  password?: string | null;       // bcrypt hash for credentials; null for OAuth
+  avatar?: string | null;
+  avatarFallback?: string | null; // hex color string '#aabbcc' for the avatar initials fallback
+  language?: string | null;
+}
+```
+
+Return the freshly-inserted `UserRecord`. The framework wraps the call in `tryCatch` and surfaces a `login.createUserFailed` reason key when the call resolves to a falsy value (or `api.internalServerError` when it throws).
+
+### `update(id, patch)`
+
+Patch an existing user. The framework calls this for:
+
+- `lastLogin: new Date()` on every successful login (best-effort, wrapped in `tryCatch`).
+- `password: hashedNew` on `updatePasswordHash` from the password-reset / password-change flows.
+- `avatar` after image upload (consumer-side).
+
+`patch` is typed as `Partial<UserRecord>`. The framework casts to `never` at the call site for the `lastLogin` and `password` updates so a schema missing those fields doesn't break compilation — the adapter is responsible for accepting (or ignoring) unknown keys gracefully.
+
+## `UserRecord` shape
+
+```ts
+interface UserRecord extends BaseSessionLayout {
+  password?: string | null;
+  provider?: string | null;
+  lastLogin?: Date | null;
+}
+```
+
+`BaseSessionLayout` (from `@luckystack/core`) covers the standard fields: `id`, `email`, `name`, `avatar`, `avatarFallback`, `admin`, `language`. `UserRecord` adds three things the session layout deliberately doesn't expose:
+
+- `password` — the bcrypt hash. Stripped before the session is built (`sanitizeUserForSession`).
+- `provider` — the auth provider. The session knows this only when the consumer needs it; some apps don't.
+- `lastLogin` — best-effort timestamp. Mirrored on the session as both `lastLogin` (the just-written value) and `previousLogin` (the value before the update).
+
+Consumers who add columns can either:
+
+1. **Augment `BaseSessionLayout`** via module declaration so the new field flows to the session, OR
+2. **Keep the field internal** to the adapter implementation and not expose it on `UserRecord`.
+
+The first option is right for "data the UI should see" (preferences, role, organization id). The second is right for "data the auth layer doesn't care about" (audit fields, internal flags).
+
+## `defaultPrismaUserAdapter`
+
+The framework default. Implementation:
+
+```ts
+export const defaultPrismaUserAdapter = (): UserAdapter => {
+  const user = (): PrismaUserDelegate => prisma.user as unknown as PrismaUserDelegate;
+
+  return {
+    findByEmail: async ({ email, provider }) =>
+      user().findFirst({ where: { email, provider } }),
+    findById: async (id) =>
+      user().findUnique({ where: { id } }),
+    create: async (input) =>
+      user().create({
+        data: {
+          email: input.email,
+          provider: input.provider,
+          name: input.name,
+          password: input.password ?? null,
+          avatar: input.avatar ?? '',
+          avatarFallback: input.avatarFallback,
+          language: input.language,
+        },
+      }),
+    update: async (id, patch) =>
+      user().update({ where: { id }, data: patch }),
+  };
+};
+```
+
+The single `as unknown as PrismaUserDelegate` cast is the only one of its kind in `@luckystack/login` and is intentional + load-bearing. It is the abstraction boundary between the framework's loose `UserAdapterCreateInput` (string-typed fields) and the consumer's strict Prisma model (which may declare enums for `provider` / `language`). The framework cannot know those enum types statically, so it type-erases once at this seam and trusts the runtime `prisma.user` to satisfy the documented `PrismaUserDelegate` shape:
+
+```ts
+interface PrismaUserDelegate {
+  findFirst: (args: { where: { email: string; provider: string } }) => Promise<UserRecord | null>;
+  findUnique: (args: { where: { id: string } }) => Promise<UserRecord | null>;
+  create: (args: { data: Record<string, unknown> }) => Promise<UserRecord>;
+  update: (args: { where: { id: string }; data: Record<string, unknown> }) => Promise<UserRecord>;
+}
+```
+
+Consumers whose schema diverges should NOT widen this cast further — register their own `UserAdapter` instead.
+
+## Lazy initialization
+
+`getUserAdapter` defers default construction until first use:
+
+```ts
+let registeredAdapter: UserAdapter | null = null;
+let cachedDefaultAdapter: UserAdapter | null = null;
+
+export const getUserAdapter = (): UserAdapter => {
+  if (registeredAdapter) return registeredAdapter;
+  if (!cachedDefaultAdapter) {
+    cachedDefaultAdapter = defaultPrismaUserAdapter();
+  }
+  return cachedDefaultAdapter;
+};
+```
+
+This matters because `defaultPrismaUserAdapter` calls `prisma.user` — which is a Prisma proxy that connects on first read. If we instantiated eagerly, modules that just import `@luckystack/login` (without ever logging anyone in) would open a database connection at import time.
+
+Lazy + cached means:
+
+- Pure imports never connect to the DB.
+- The first login attempt creates one adapter and reuses it forever.
+- Custom adapters bypass the cache entirely.
+
+## Recipes
+
+### Multi-tenant scoping
+
+```ts
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+export const tenantContext = new AsyncLocalStorage<{ tenantId: string }>();
+
+const tenantedAdapter: UserAdapter = {
+  findByEmail: async ({ email, provider }) => {
+    const ctx = tenantContext.getStore();
+    if (!ctx) throw new Error('No tenant context');
+    return prisma.user.findFirst({
+      where: { email, provider, tenantId: ctx.tenantId },
+    });
+  },
+  // ... same for findById, create, update
+};
+
+registerUserAdapter(tenantedAdapter);
+```
+
+The HTTP middleware that resolves `tenantId` from the host header runs `tenantContext.run({ tenantId }, next)` so the adapter reads it without an explicit parameter.
+
+### Soft delete
+
+```ts
+const softDeleteAdapter: UserAdapter = {
+  ...defaultPrismaUserAdapter(),
+  findByEmail: async ({ email, provider }) =>
+    prisma.user.findFirst({
+      where: { email, provider, deletedAt: null },
+    }),
+  findById: async (id) =>
+    prisma.user.findFirst({
+      where: { id, deletedAt: null },
+    }),
+};
+
+registerUserAdapter(softDeleteAdapter);
+```
+
+The spread keeps `create` and `update` identical to the default — only the read methods get the `deletedAt: null` filter.
+
+### Alternative ORM (Drizzle)
+
+```ts
+import { db } from './db';
+import { users } from './schema';
+import { and, eq } from 'drizzle-orm';
+
+const drizzleAdapter: UserAdapter = {
+  findByEmail: async ({ email, provider }) => {
+    const rows = await db.select().from(users)
+      .where(and(eq(users.email, email), eq(users.provider, provider)));
+    return rows[0] ?? null;
+  },
+  findById: async (id) => {
+    const rows = await db.select().from(users).where(eq(users.id, id));
+    return rows[0] ?? null;
+  },
+  create: async (input) => {
+    const [row] = await db.insert(users).values(input).returning();
+    return row;
+  },
+  update: async (id, patch) => {
+    const [row] = await db.update(users).set(patch).where(eq(users.id, id)).returning();
+    return row;
+  },
+};
+
+registerUserAdapter(drizzleAdapter);
+```
+
+### Additional required column
+
+If your schema requires `organizationId` on create, override only the `create` method:
+
+```ts
+const orgScopedAdapter: UserAdapter = {
+  ...defaultPrismaUserAdapter(),
+  create: async (input) => {
+    const orgId = tenantContext.getStore()?.tenantId;
+    if (!orgId) throw new Error('No org context for create');
+    return prisma.user.create({
+      data: { ...input, organizationId: orgId },
+    });
+  },
+};
+
+registerUserAdapter(orgScopedAdapter);
+```
+
+### Read-replica routing
+
+```ts
+const replicaAdapter: UserAdapter = {
+  findByEmail: async (args) => prismaReplica.user.findFirst({ where: args }),
+  findById:    async (id)   => prismaReplica.user.findUnique({ where: { id } }),
+  create:      async (input) => prismaPrimary.user.create({ data: { ...input } }),
+  update:      async (id, patch) => prismaPrimary.user.update({ where: { id }, data: patch }),
+};
+
+registerUserAdapter(replicaAdapter);
+```
+
+The framework reads via `findByEmail` on every login, so routing reads to a replica is a meaningful production optimization. Reads after a write (e.g. `findByEmail` immediately after `create` during register) should still hit the primary — handle that with a read-your-writes timestamp or a per-request "stick to primary for N ms" flag inside your adapter.
+
+## `lastLogin` semantics
+
+The default adapter accepts `lastLogin` in `update` because it casts to `Record<string, unknown>` for the `data` field. The framework writes `{ lastLogin: new Date() }` after a successful credentials or OAuth login, wrapped in `tryCatch`:
+
+```ts
+await tryCatch(() => userAdapter.update(findUserResponse.id, { lastLogin: nowLogin } as never));
+```
+
+The cast to `never` is intentional — it tells TypeScript "we know `lastLogin` may not be in `UserRecord`, accept it anyway". If your schema doesn't have a `lastLogin` column, the call either:
+
+- Fails inside Prisma's runtime field validation → `tryCatch` swallows the error, the login succeeds.
+- Succeeds silently if your adapter ignores unknown keys (recommended).
+
+The session's `lastLogin` and `previousLogin` are populated from this update — if it fails, both fields will be `undefined` on the session and the UI should treat them as optional.
+
+For audit-grade tracking, register a `postLogin` hook instead of relying on the column:
+
+```ts
+registerHook('postLogin', async ({ userId, provider }) => {
+  await prisma.loginEvent.create({
+    data: { userId, provider, timestamp: new Date() },
+  });
+});
+```
+
+The hook gives you a row-per-login with full context, vs. the column which is a single mutating timestamp.
+
+## Composing on top of the default
+
+A common pattern is "the default but with one method overridden":
+
+```ts
+const base = defaultPrismaUserAdapter();
+
+registerUserAdapter({
+  ...base,
+  findByEmail: async ({ email, provider }) => {
+    const user = await base.findByEmail({ email, provider });
+    if (!user) return null;
+    if (user.disabledAt) return null; // app-level "disabled" flag
+    return user;
+  },
+});
+```
+
+This avoids re-implementing the other three methods just to add a single filter.
+
+## Related
+
+- [`./credentials-auth.md`](./credentials-auth.md) — what calls `findByEmail` / `create` for credentials flows.
+- [`./oauth-providers.md`](./oauth-providers.md) — `loginCallback` uses the same adapter surface.
+- [`./password-reset.md`](./password-reset.md) — `updatePasswordHash` calls `update` with `{ password }`.
+- [`./session-management.md`](./session-management.md) — the adapter does NOT touch sessions; sessions are a separate adapter.
+- Architecture: [`/docs/ARCHITECTURE_AUTH.md`](../../../docs/ARCHITECTURE_AUTH.md).