@luckystack/login 0.8.3 → 0.8.4

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.4] - 2026-08-17
+
+### Changed
+
+- Corrected password-reset/session documentation for hash-at-rest tokens, one-active-token-per-user invalidation, atomic shared-token consumption, current route paths, and pluggable session storage.
+
 ## [0.8.1] - 2026-07-27
 
 ### Fixed

package/CLAUDE.md

@@ -11,13 +11,13 @@
 
 - **Credentials auth** (email + bcrypt-hashed password) with combined login/register dispatcher.
 - **OAuth 2.0** via a pluggable provider registry. Built-in helpers for Google, GitHub, Discord, Facebook, Microsoft. Custom providers register as raw `OAuthProvider` objects.
-- **Redis-backed sessions** with sliding expiration, CSRF token minting, single-session enforcement, and a swappable `SessionAdapter` (DynamoDB, Postgres, JWT-stateless, etc.).
+- **Redis-backed default sessions** with sliding expiration, CSRF token minting, single-session enforcement, and a swappable `SessionAdapter` (DynamoDB, Postgres, JWT-stateless, etc.).
 - **Lifecycle hooks**: `preLogin` / `postLogin`, `preRegister` / `postRegister`, `preLogout` / `postLogout`, `preSessionCreate` / `postSessionCreate`, `preSessionDelete` / `postSessionDelete`, `passwordResetRequested`, `passwordResetCompleted`, `passwordChanged`. All `pre*` hooks support stop-signals (abort the side-effect with a reason key).
 - **Pluggable user store** via `UserAdapter` — decouples auth from a specific Prisma `User` schema.
 - **Password-reset primitives** (`createPasswordResetToken`, `consumePasswordResetToken`, `updatePasswordHash`, `verifyPassword`) plus the framework-mode `sendPasswordResetEmail` orchestrator (requires the optional `@luckystack/email` peer).
 - **Dynamic post-login redirect** resolver registry (per-user / per-tenant / per-provider OAuth landing pages). Relative resolver results inherit the trusted frontend `defaultUrl` origin, not the backend callback origin.
 
-OAuth state is stored in Redis under `${projectName}-oauth-state:<provider>:<state>` with TTL `auth.oauthStateTtlSeconds`. Sessions live at `${projectName}-session:<token>`. Active-tokens-per-user set lives at `${projectName}-activeUsers:<userId>`. Password-reset and email-change tokens are **hashed at rest** (0.2.0): only `sha256(token)` is stored as the Redis key (`${projectName}-pwreset:<sha256(token)>` / `${projectName}-email-change:<sha256(token)>`) via the `@luckystack/core` one-time-token primitive (`issueOneTimeToken` / `consumeOneTimeToken`). The raw token is returned to the caller exactly once for the emailed URL, so a leaked Redis keyspace can't be replayed to mint a reset or confirm an email change.
+OAuth state is always stored in Redis under `${projectName}-oauth-state:<provider>:<state>` with TTL `auth.oauthStateTtlSeconds`. The default Redis session adapter stores sessions at `${projectName}-session:<token>` and active-tokens-per-user sets at `${projectName}-activeUsers:<userId>`; a custom `SessionAdapter` owns those storage details. Password-reset and email-change tokens are **hashed at rest** (0.2.0): only `sha256(token)` is stored as the Redis key (`${projectName}-pwreset:<sha256(token)>` / `${projectName}-email-change:<sha256(token)>`) via the `@luckystack/core` one-time-token primitive (`issueOneTimeToken` / `consumeOneTimeToken`). The raw token is returned to the caller exactly once for the emailed URL, so a leaked Redis keyspace can't be replayed to mint a reset or confirm an email change.
 
 ---
 
@@ -139,7 +139,7 @@ All config keys live on `ProjectConfig` (from `@luckystack/core`). Resolved at c
 | `FACEBOOK_CLIENT_ID` / `FACEBOOK_CLIENT_SECRET` | `facebookProvider` | OAuth app credentials. |
 | `MICROSOFT_CLIENT_ID` / `MICROSOFT_CLIENT_SECRET` | `microsoftProvider` | OAuth app credentials. |
 | `MICROSOFT_TENANT_ID` | `microsoftProvider` (optional) | Single-tenant Azure AD. Defaults to `'common'`. |
-| (callback origin) | All OAuth `callbackUrl` builders | The `callbackUrl` is the BACKEND origin + `/auth/callback/<provider>`. The scaffold derives it in `config.ts` (`oauthCallbackBase`: dev `http://localhost:80`, prod the public domain). No `DNS` env var — that was removed in 0.1.5. |
+| (callback origin) | All OAuth `callbackUrl` builders | The `callbackUrl` is the BACKEND origin + `/auth/callback/<provider>`. The scaffold derives dev from `config.ports.ts` (or the explicit CLI port) and production from `PUBLIC_URL`; generic consumers still fall back to `app.publicUrl`. No `DNS` env var is required by the framework OAuth contract. |
 | `BCRYPT_ROUNDS` | `auth.bcryptRounds` | Surfaced through project config; salt rounds for credentials hashing. |
 | `TOTP_ENCRYPTION_KEY` | TOTP at-rest encryption | Current primary write key; new rows are `enc:v2:<key-id>:...`. |
 | `TOTP_ENCRYPTION_LEGACY_KEYS` | TOTP key rotation | JSON array of decrypt-only previous keys. Successful TOTP proofs lazily rewrite legacy/plaintext rows under the primary. |
@@ -180,7 +180,7 @@ All config keys live on `ProjectConfig` (from `@luckystack/core`). Resolved at c
 | `bcryptjs` | hard runtime dep | Password hashing + comparison. |
 | `validator` | hard runtime dep | Email validation + name escaping. |
 | `dotenv` | hard runtime dep | Env loading at boot. |
-| `@prisma/client` | **required peer** | Default `UserAdapter` talks to `prisma.user`. Register a custom `UserAdapter` if you cannot ship Prisma. |
+| `@prisma/client` | **optional peer** | The default `UserAdapter` talks to `prisma.user`; register a custom `UserAdapter` when Prisma is not used. |
 | `socket.io` | **required peer** | `logout` and session enforcement broadcast through the live `io` instance from `getIoInstance()`. |
 | `@luckystack/email` | **optional peer** | Only required when `auth.forgotPassword === 'framework'`. Lazy-imported by `sendPasswordResetEmail` — every other API works without it. |
 
@@ -188,7 +188,7 @@ All config keys live on `ProjectConfig` (from `@luckystack/core`). Resolved at c
 
 ## Related links
 
-- Repo root contract: [`/.claude/CLAUDE.md`](../../.claude/CLAUDE.md)
+- Repository-root contract: [`CLAUDE.md`](../../CLAUDE.md)
 - Package README: [`./README.md`](./README.md)
 - Architecture — auth lifecycle: [`/docs/ARCHITECTURE_AUTH.md`](../../docs/ARCHITECTURE_AUTH.md)
 - Architecture — sessions (Redis layout, sliding expiration, single-session enforcement): [`/docs/ARCHITECTURE_SESSION.md`](../../docs/ARCHITECTURE_SESSION.md)

package/README.md

@@ -1,13 +1,15 @@
 # @luckystack/login
 
-> Authentication for [LuckyStack](https://github.com/ItsLucky23/LuckyStack-v2). Credentials + OAuth (Google, GitHub, Facebook, Discord, Microsoft), Redis-backed sessions, single-session enforcement, and lifecycle hooks (`preLogin`, `preRegister`, `preLogout`, `preSessionCreate`, `preSessionDelete` and their `post*` counterparts).
+> Authentication for [LuckyStack](https://github.com/ItsLucky23/LuckyStack-v2). Credentials + OAuth (Google, GitHub, Facebook, Discord, Microsoft), Redis-backed default sessions with a swappable session adapter, single-session enforcement, and lifecycle hooks (`preLogin`, `preRegister`, `preLogout`, `preSessionCreate`, `preSessionDelete` and their `post*` counterparts).
 
 ## Install
 
 ```bash
-npm install @luckystack/login @luckystack/core @prisma/client socket.io
+npm install @luckystack/login socket.io
 ```
 
+The default user adapter uses Prisma; install optional peer `@prisma/client` when you use it. Framework-mode email flows additionally need optional peer `@luckystack/email`. Projects with custom `UserAdapter` and `SessionAdapter` implementations can use another data layer and session store.
+
 ## Quickstart
 
 ```ts
@@ -28,7 +30,7 @@ const result = await loginWithCredentials({ email, password });
 // → { status: false, reason } on failure (including hook-stop with the hook's errorCode)
 ```
 
-Sessions are stored in Redis under `${PROJECT_NAME}-session:<token>` and are sliding (every authenticated read extends the TTL by `ProjectConfig.session.expiryDays`).
+The default `redisSessionAdapter` stores sessions under `${PROJECT_NAME}-session:<token>` and applies sliding expiration (every authenticated read extends the TTL by `ProjectConfig.session.expiryDays`). Register a custom `SessionAdapter` when sessions should live in another store.
 
 ## Hooks
 
@@ -195,8 +197,8 @@ import {
 | `loginCallback(pathname, req, res)` | OAuth state-exchange handler — wired to `/auth/callback/<provider>` by `@luckystack/server`. |
 | `createOAuthState(providerName)` | Issue a CSRF state token (Redis, NX, TTL from project config). |
 | `logout({ token, socket, userId })` | End a single socket's session. |
-| `saveSession(token, user, newUser?)` | Write to Redis + broadcast to existing connections. |
-| `getSession(token)` | Read + slide expiration. Dispatches `preSessionRefresh` / `postSessionRefresh` around the Redis EXPIRE call. |
+| `saveSession(token, user, newUser?)` | Write through the active `SessionAdapter` + broadcast to existing connections. |
+| `getSession(token)` | Read + slide expiration through the active adapter. Dispatches `preSessionRefresh` / `postSessionRefresh` around the adapter TTL refresh. |
 | `deleteSession(token)` | Hard delete + clean up active-tokens set. |
 | `getAllSessions()` | Admin utility — scans all sessions. |
 | `revokeUserSessions(userId)` | Force-logout every active session for a user. |
@@ -204,6 +206,7 @@ import {
 | `registerOAuthProviders(list)` / `getOAuthProviders()` / `isFullOAuthProvider(p)` | OAuth registry. |
 | `googleProvider`, `githubProvider`, `discordProvider`, `facebookProvider`, `microsoftProvider`, `credentialsProvider` | Built-in provider factories. |
 | `registerUserAdapter(adapter)` / `getUserAdapter()` / `isUserAdapterRegistered()` / `defaultPrismaUserAdapter` | Pluggable user store. |
+| `registerSessionAdapter(adapter)` / `getSessionAdapter()` / `redisSessionAdapter` | Pluggable session storage; Redis is the default. |
 | `registerPostLoginRedirect(resolver)` / `getPostLoginRedirect()` | Dynamic redirect resolution. |
 | `createPasswordResetToken`, `consumePasswordResetToken`, `updatePasswordHash`, `verifyPassword`, `sendPasswordResetEmail` | Password-reset primitives. |
 
@@ -221,18 +224,16 @@ If your project has no such surfaces this is informational. The framework intent
 ## Related architecture docs
 
 - [`docs/ARCHITECTURE_AUTH.md`](../../docs/ARCHITECTURE_AUTH.md) — OAuth + credentials lifecycle, allowed-origin checks, role guards.
-- [`docs/ARCHITECTURE_SESSION.md`](../../docs/ARCHITECTURE_SESSION.md) — Redis layout, sliding expiration, single-session enforcement.
+- [`docs/ARCHITECTURE_SESSION.md`](../../docs/ARCHITECTURE_SESSION.md) — session adapters, default Redis layout, sliding expiration, and single-session enforcement.
 - [`docs/ARCHITECTURE_EMAIL.md`](../../docs/ARCHITECTURE_EMAIL.md) — forgot-password modes (`framework` / `custom` / `disabled`).
 
 ## Dependencies
 
 - Runtime: `@luckystack/core`, `bcryptjs`, `validator`, `dotenv`
-- Peer (canonical ranges, standardized 2026-05-07):
-  - `@prisma/client@^6.19.0`
-  - `socket.io@^4.8.0`
-- Optional peer: `@luckystack/email` — only required when `forgotPassword: 'framework'`. The package lazy-imports it; without it, the framework-mode flow is disabled but every other API works.
+- Required peer: `socket.io@^4.8.0`
+- Optional peers: `@prisma/client@^6.19.0` (default user adapter) and `@luckystack/email` (only when `forgotPassword: 'framework'`). The package lazy-imports optional peers; every other API works without them.
 
-Your Prisma schema must include a `User` model with at least: `id`, `email`, `provider` (enum `PROVIDERS`), `password` (nullable), `name`, `avatar`, `avatarFallback`, `admin`, `language`. See [`prisma/schema.prisma`](../../prisma/schema.prisma) for the canonical shape, or register a `UserAdapter` to talk to a different schema.
+When using the default Prisma `UserAdapter`, your schema must include a `User` model with at least: `id`, `email`, `provider` (enum `PROVIDERS`), `password` (nullable), `name`, `avatar`, `avatarFallback`, `admin`, `language`. See [`prisma/schema.prisma`](../../prisma/schema.prisma) for the canonical shape. A custom `UserAdapter` and `SessionAdapter` can bind auth to another data layer and session store.
 
 ## License
 

package/docs/hooks.md

@@ -166,7 +166,7 @@ registerHook('postLogout', async ({ userId, token }) => {
 { token: string; user: BaseSessionLayout; persistent: boolean }
 ```
 
-`persistent` is the inverse of `projectConfig.session.basedToken` — `true` means "this session survives a browser restart" (the default), `false` means "session-cookie only". Audit handlers can use this to differentiate a "remember me" login from a one-shot one.
+`persistent` is the inverse of `projectConfig.session.basedToken` — `true` means cookie mode (the credential can survive a browser restart according to cookie expiry, and is shared across tabs); `false` means tab-scoped `sessionStorage` bearer mode. Audit handlers can use this to differentiate a "remember me" login from a one-shot one.
 
 `user` is the freshly-sanitized session layout — password already stripped, avatar already resolved. Hooks should treat it as read-only; mutating it does NOT affect the saved session (the framework writes the original reference, but other hooks expect immutability).
 

package/docs/password-reset.md

@@ -18,18 +18,23 @@ This is the password lifecycle from "user clicks Forgot password" through "new p
 
 The mode is read at call time via `getProjectConfig()`, so consumers can toggle it through `registerProjectConfig` without restarting. In practice, switching modes mid-process is uncommon — pick a mode at boot and stick with it.
 
-## Token layout
+## Token layout and hash-at-rest contract
 
 ```ts
-const token = randomBytes(32).toString('hex'); // 64 char URL-safe string
-const key = `${getProjectName()}-pwreset:${token}`;
-await redis.set(key, userId, 'EX', auth.passwordResetTtlSeconds);
+const handle = issueOneTimeToken('-pwreset', auth.passwordResetTtlSeconds, userId);
+await handle.store();
+
+// Redis stores only the hash-derived key:
+// <projectName>-pwreset:<sha256(handle.token)> -> userId
+return handle.token; // raw 64-character token, returned only for delivery
 ```
 
-- **Entropy** — 256 bits via `randomBytes(32)`. Hex-encoded so it can be passed in a URL query string without any escaping.
-- **Storage** — Redis. Single key holds the `userId`; one-time use means the redemption deletes the key.
-- **Namespace** — `${projectName}-pwreset:<token>`. Shared `getProjectName()` helper means the namespace matches sessions, activeUsers, OAuth state, and rate-limit (no drift between Redis keys).
-- **TTL** — `auth.passwordResetTtlSeconds`. Default 3600 (1 hour). Tighten for high-security deployments; loosen if your users frequently check email on a different device than they reset on.
+- **Entropy** — 256 bits via `randomBytes(32)`, hex-encoded as a 64-character URL-safe token.
+- **Hash at rest** — the raw token is never persisted. `issueOneTimeToken` derives a SHA-256 key suffix, so a Redis keyspace/backup leak does not yield a redeemable reset link.
+- **Namespace** — `formatKey('-pwreset', sha256(token))`; the active project/tenant key formatter remains authoritative.
+- **Single active token per user** — `${projectName}-pwreset-user:<userId>` points to the current hash key. Issuing a replacement deletes the previous outstanding token before storing the new one.
+- **TTL** — both the hash record and per-user pointer use `auth.passwordResetTtlSeconds` (default 3600 seconds).
+- **Storage boundary** — password-reset tokens intentionally use the core one-time-token Redis primitive; this is independent of the pluggable session-storage adapter.
 
 ## Primitives
 
@@ -39,9 +44,9 @@ await redis.set(key, userId, 'EX', auth.passwordResetTtlSeconds);
 createPasswordResetToken(userId: string): Promise<string>;
 ```
 
-Mint + store + return. Caller is responsible for getting the token to the user — typically embedded in a `${appPublicUrl}/reset-password?token=<token>` URL inside an email, but custom modes might send it via SMS, push notification, or an in-app banner.
+Invalidate the user's previous outstanding reset token, mint/store a new hash-at-rest token, persist the per-user pointer, and return the raw token. The caller is responsible for delivering it—normally in an `${appPublicUrl}/reset-password?token=<token>` URL.
 
-Always succeeds (returns the token string). If Redis is down, the underlying `redis.set` throws and propagates — wrap in `tryCatch` at the call site if you want to surface "email service degraded" rather than 500.
+The promise rejects when Redis cannot read/delete/store the token records. Framework-mode callers normalize that failure; custom callers should use the standard `tryCatch` helper when they need a typed degradation path.
 
 ### `consumePasswordResetToken(token)`
 
@@ -49,23 +54,9 @@ Always succeeds (returns the token string). If Redis is down, the underlying `re
 consumePasswordResetToken(token: string): Promise<string | null>;
 ```
 
-Atomic `GET` + `DEL` in a Redis transaction:
-
-```ts
-const txResult = await redis.multi().get(key).del(key).exec();
-const [getErr, value] = txResult[0];
-if (getErr) return null;
-return typeof value === 'string' && value.length > 0 ? value : null;
-```
-
-Returns the bound `userId` on success, `null` on:
-
-- Empty or non-string `token` argument.
-- Token expired (Redis returns null for the GET).
-- Token already consumed (the DEL on a prior call already removed it).
-- The transaction failed entirely (Redis network blip).
+Delegates to `consumeOneTimeToken('-pwreset', token)`. The shared primitive hashes the supplied raw token to derive the Redis key and performs one `MULTI` containing `GET` + `DEL`. It returns the bound `userId` only when both commands succeed.
 
-One-time-use is enforced by the atomic DEL — a second call with the same token returns `null` because the key is already gone. Replay attacks defeated.
+Returns `null` for an empty/malformed token, missing or expired hash record, an already-consumed token, or any transaction/DEL failure. A concurrent second redemption sees no value and fails closed, providing at-most-once consumption.
 
 ### `updatePasswordHash(userId, plaintext)`
 
@@ -80,10 +71,11 @@ const reason = validatePassword(plaintext);
 if (reason) throw new PasswordPolicyError(reason);
 const salt = await bcrypt.genSalt(getProjectConfig().auth.bcryptRounds);
 const hashedPassword = await bcrypt.hash(plaintext, salt);
-await getUserAdapter().update(userId, { password: hashedPassword } as never);
+const patch: Record<string, unknown> = { password: hashedPassword };
+await getUserAdapter().update(userId, patch);
 ```
 
-Throws `PasswordPolicyError` on policy violation. The cast to `never` on the patch tells TypeScript "we know `password` may not be a typed field on `UserRecord`, trust me" — the framework's `UserAdapter` interface is intentionally loose for this kind of optional column.
+Throws `PasswordPolicyError` on policy violation. `UserAdapter.update` accepts a loose patch because custom user stores may expose different optional credential fields; no transport-typing cast is needed.
 
 Note this primitive deliberately does NOT consume a reset token. The reset-password completion API is responsible for the sequence:
 
@@ -209,9 +201,9 @@ const { sendEmail, renderEmailLayout } = await (
 The framework-mode flow has two HTTP endpoints (wired by `@luckystack/server` via the file-based router):
 
 ```
-1. POST /api/login/sendReset/v1     → sendPasswordResetEmail({ email })
-                                       └ token now in Redis, email on its way
-2. POST /api/login/completeReset/v1 → consumePasswordResetToken(token)
+1. POST /api/reset-password/sendReset/v1   → sendPasswordResetEmail({ email })
+                                             └ token hash now in Redis; raw token is emailed
+2. POST /api/reset-password/confirmReset/v1 → consumePasswordResetToken(token)
                                        └ updatePasswordHash(userId, newPassword)
                                        └ revokeUserSessions(userId, currentToken?)
                                        └ dispatchHook('passwordResetCompleted', { userId, revokedOtherSessions })

package/docs/session-management.md

@@ -11,7 +11,8 @@ Deep-dive on `saveSession` / `getSession` / `deleteSession`, sliding expiration,
 | `${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}-pwreset:<sha256(token)>`           | string     | `userId` bound to the hash-at-rest one-time token; raw token is never persisted. |
+| `${projectName}-pwreset-user:<userId>`             | string     | Hash-key pointer for the user's only active reset token; replacement issuance invalidates the prior key. |
 
 `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.
 

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@luckystack/login",
-  "version": "0.8.3",
+  "version": "0.8.4",
   "private": false,
   "publishConfig": {
     "access": "public",
     "provenance": true
   },
   "type": "module",
-  "description": "Authentication for LuckyStack: credentials + OAuth (Google/GitHub/Facebook/Discord), Redis-backed sessions, single-session enforcement, lifecycle hooks. Pairs with @luckystack/core.",
+  "description": "Authentication for LuckyStack: credentials + OAuth (Google/GitHub/Facebook/Discord/Microsoft/custom), Redis-backed sessions, single-session enforcement, password reset, 2FA, lifecycle hooks, and pluggable user/session adapters. Pairs with @luckystack/core.",
   "license": "MIT",
   "author": "Mathijs van Melick <mathijsvanmelick3@gmail.com>",
   "repository": {
@@ -59,7 +59,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@luckystack/core": "^0.8.3",
+    "@luckystack/core": "^0.8.4",
     "bcryptjs": "^3.0.0",
     "dotenv": "^17.0.0",
     "validator": "^13.15.35"
@@ -67,7 +67,7 @@
   "peerDependencies": {
     "@prisma/client": "^6.19.0",
     "socket.io": "^4.8.0",
-    "@luckystack/email": "^0.8.3"
+    "@luckystack/email": "^0.8.4"
   },
   "peerDependenciesMeta": {
     "@prisma/client": {