najm-auth 3.4.0 → 4.0.0

package/README.md

@@ -97,11 +97,11 @@ FRONTEND_URL=https://app.example.com
 GOOGLE_CLIENT_ID=<google-web-client-id>
 GOOGLE_CLIENT_SECRET=<google-web-client-secret>
 # Optional for a split frontend/API deployment. Otherwise FRONTEND_URL is used.
-GOOGLE_CALLBACK_URL=https://app.example.com/api/auth/oauth/google/callback
-# Optional GitHub sign-in
-GITHUB_CLIENT_ID=<github-oauth-app-client-id>
-GITHUB_CLIENT_SECRET=<github-oauth-app-client-secret>
-GITHUB_CALLBACK_URL=https://app.example.com/api/auth/oauth/github/callback
+GOOGLE_CALLBACK_URL=https://app.example.com/api/auth/oauth/google/callback
+# Optional GitHub sign-in
+GITHUB_CLIENT_ID=<github-oauth-app-client-id>
+GITHUB_CLIENT_SECRET=<github-oauth-app-client-secret>
+GITHUB_CALLBACK_URL=https://app.example.com/api/auth/oauth/github/callback
 ```
 
 > ⚠️ **Security:** Generate secrets with `openssl rand -base64 32`
@@ -156,7 +156,7 @@ auth({
     }
   }
 
-  // Optional external identity providers
+  // Optional external identity providers
   oauth?: {
     google?: true | {
       clientId?: string                    // Or GOOGLE_CLIENT_ID
@@ -166,17 +166,17 @@ auth({
       errorRedirectPath?: string           // Default: /login
       allowSignup?: boolean                // Default: true
       autoLinkVerifiedEmail?: boolean      // Default: false
-      allowedHostedDomains?: string[]      // Validates the Google hd claim
-    }
-    github?: true | {
-      clientId?: string                    // Or GITHUB_CLIENT_ID
-      clientSecret?: string                // Or GITHUB_CLIENT_SECRET
-      callbackUrl?: string                 // Or GITHUB_CALLBACK_URL
-      frontendCallbackPath?: string        // Default: /auth/oauth/callback
-      errorRedirectPath?: string           // Default: /login
-      allowSignup?: boolean                // Default: true
-      autoLinkVerifiedEmail?: boolean      // Default: false
-    }
+      allowedHostedDomains?: string[]      // Validates the Google hd claim
+    }
+    github?: true | {
+      clientId?: string                    // Or GITHUB_CLIENT_ID
+      clientSecret?: string                // Or GITHUB_CLIENT_SECRET
+      callbackUrl?: string                 // Or GITHUB_CALLBACK_URL
+      frontendCallbackPath?: string        // Default: /auth/oauth/callback
+      errorRedirectPath?: string           // Default: /login
+      allowSignup?: boolean                // Default: true
+      autoLinkVerifiedEmail?: boolean      // Default: false
+    }
   }
 
   // Dependencies (forwarded to plugins)
@@ -346,22 +346,22 @@ import { GoogleLoginButton } from 'najm-auth/client/react';
 Google accounts are keyed by Google's stable `sub` claim. If an existing Najm
 user has the same email but is not linked, sign-in fails with
 `oauth_account_link_required` by default. After password login, call
-`client.linkOAuthAccount('google')` to prove control of both accounts. Setting
-`autoLinkVerifiedEmail: true` opts into verified-email linking.
-
-### GitHub Sign-In
-
-Enable GitHub with `oauth: { github: true }`. Credentials come from
-`GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET`; the callback defaults to
-`${FRONTEND_URL}/api/auth/oauth/github/callback`. Register that exact callback
-on the GitHub OAuth App, and set `GITHUB_CALLBACK_URL` only for a split-origin
-deployment. GitHub login uses authorization code plus PKCE, requests
-`user:email`, requires a verified primary email, and keys the durable provider
-link by GitHub's numeric user ID.
-
-The client exposes `loginWithGitHub()`, `useGitHubLogin()`, and the headless
-`GitHubLoginButton`; the generic `linkOAuthAccount('github')` method links an
-authenticated Najm user.
+`client.linkOAuthAccount('google')` to prove control of both accounts. Setting
+`autoLinkVerifiedEmail: true` opts into verified-email linking.
+
+### GitHub Sign-In
+
+Enable GitHub with `oauth: { github: true }`. Credentials come from
+`GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET`; the callback defaults to
+`${FRONTEND_URL}/api/auth/oauth/github/callback`. Register that exact callback
+on the GitHub OAuth App, and set `GITHUB_CALLBACK_URL` only for a split-origin
+deployment. GitHub login uses authorization code plus PKCE, requests
+`user:email`, requires a verified primary email, and keys the durable provider
+link by GitHub's numeric user ID.
+
+The client exposes `loginWithGitHub()`, `useGitHubLogin()`, and the headless
+`GitHubLoginButton`; the generic `linkOAuthAccount('github')` method links an
+authenticated Najm user.
 
 ### Admin Routes (all require `@isAdmin()`)
 
@@ -664,7 +664,7 @@ credential_setup_requirements
 Existing databases must generate and run a migration after upgrading so the
 new `oauth_accounts`, `credential_setup_sessions`, and
 `credential_setup_requirements` tables exist. Custom `AuthSchema` objects may
-omit `oauthAccounts` while OAuth is disabled, but provider configuration fails
+omit `oauthAccounts` while OAuth is disabled, but provider configuration fails
 fast unless the custom schema supplies it. Both credential-setup tables are
 required of a custom schema, because the setup flow is always mounted.
 
@@ -849,6 +849,31 @@ Next.js 16 requires the exported Proxy `config` to be a statically analyzable
 object literal. Turbopack rejects `export const config = auth.config`, so the
 matcher is the one integration value that cannot be composed at runtime.
 
+When a Proxy generates request-scoped headers for the downstream render, pass
+only the overrides as the optional second argument. Najm merges them over the
+incoming request and preserves them when session recovery replaces the cookie.
+The application still owns any matching response header:
+
+```typescript
+export default async function proxy(request: Request) {
+  const nonce = btoa(globalThis.crypto.randomUUID());
+  const policy = `script-src 'self' 'nonce-${nonce}' 'strict-dynamic'`;
+  const response = await auth.proxy(request, {
+    requestHeaders: {
+      'content-security-policy': policy,
+      'x-nonce': nonce,
+    },
+  });
+  response.headers.set('Content-Security-Policy', policy);
+  return response;
+}
+```
+
+Authentication reads the original request. `requestHeaders` controls only what
+the successful Next.js render receives. Attempts to override `cookie` or
+`authorization` fail closed; only Najm's validated recovery path may replace
+the cookie after it authorizes the recovered session.
+
 ```typescript
 // src/app/api/[...route]/route.ts
 import { handle } from 'najm-core';
@@ -1052,8 +1077,9 @@ throw new HttpError(403, 'Insufficient permissions for this action');
 - Login uses a dummy password hash for missing users to reduce timing leaks.
 - Forgot-password responses avoid email enumeration.
 - Auth routes register `najm-rate` and ship route-level brute-force limits.
-- Session cookies are signed and short-lived; server auth resolution checks
-  their session version.
+- Session cookies are signed, short-lived, and bound to their refresh-token
+  family; server auth resolution checks both the session version and positive
+  family liveness.
 - Expired signed sessions recover through authoritative, non-rotating refresh
   validation; middleware verifies the reissued HMAC before using its claims.
 - Server-side recovery sends only the configured refresh cookie and accepts
@@ -1092,17 +1118,20 @@ errors cannot change the authentication result.
 
 ### Password Reset Tokens
 
-⚠️ **Current behavior:** Reset tokens use JWT expiry (default 1h) for single-use validation. To add database-backed single-use tokens:
+Reset and invite links are signed JWTs whose `jti` is stored in the configured
+cache with the same expiry. `verifyResetToken()` atomically compares and
+deletes that value, so exactly one concurrent caller can consume a link and a
+stale link cannot delete the value for a newer one.
 
-```typescript
-// In AuthService.resetPassword():
-async resetPassword(token: string, newPassword: string) {
-  const userId = this.tokenService.verifyResetToken(token);
-  // ... update password ...
-  // Blacklist the reset token to prevent reuse
-  await this.tokenService.blacklistCurrentToken(token);
-}
-```
+`AuthService.resetPassword()` validates the replacement password before
+consumption. Once consumed, a token stays consumed even if the later user
+mutation fails; restoring it would make the link replayable, so the user must
+request a new one.
+
+The built-in memory and Redis drivers implement the required atomic primitive.
+A custom cache driver may omit `compareAndDelete()` for compatibility with
+unrelated cache usage, but reset and invite consumption then fails closed. Do
+not emulate this operation with separate `get()` and `del()` calls.
 
 ### Purpose-Bound Credential Setup
 
@@ -1152,8 +1181,9 @@ consuming it; `cancel()` revokes it and clears the cookie.
 ### Session Management
 
 - Sessions are multi-device: the token table stores one refresh row per login session (keyed by a unique `tokenFamily`), so a user can stay logged in on several devices at once. Logout and rotation are scoped to the current session; password change/reset revoke every session
+- Revocation changes the refresh row to a durable `revoked` tombstone until its original expiry. Active-session reads and rotations require `status = active`, so losing Redis cannot revive a logged-out database session; expired tombstones are removed by normal session cleanup
 - A stale refresh token presented after the 120-second rotation grace window revokes only that session's family as reuse protection
-- The signed session cookie is accepted for up to its configured TTL (5 minutes by default) without a database or revocation-cache read
+- The signed session cookie is accepted on the fast path only while Redis positively identifies its family as live and owned by the same user; an unknown cache state falls back to authoritative refresh-row recovery
 - Use `@RateLimit` on logout for DDoS protection
 
 ### Token Blacklist
@@ -1177,8 +1207,24 @@ consuming it; `cancel()` revokes it and clears the cookie.
 ```bash
 bun run test      # Run all tests
 bun run test:auth # Run auth tests only
+bun run --cwd packages/najm-auth test:real-infra # Opt-in PostgreSQL + Redis races
+bun packages/najm-auth/integration/mailpit-forgot-password/run.ts # Loopback Redis + Mailpit HTTP acceptance
 ```
 
+The real-infrastructure suite runs only with `NAJM_AUTH_REAL_INFRA=1`. Supply
+loopback-only `NAJM_AUTH_REAL_POSTGRES_URL` and `NAJM_AUTH_REAL_REDIS_URL` (or
+the conventional `DATABASE_URL` and `REDIS_URL`). It creates and drops its own
+randomly named PostgreSQL database and cleans only its unique Redis key prefix;
+remote endpoints fail before either service is touched.
+
+The Mailpit acceptance runner requires Redis on `127.0.0.1:6399`, Mailpit SMTP
+on `127.0.0.1:1025`, and the Mailpit API on `127.0.0.1:8025` by default. It
+boots the real auth plugin over HTTP with an ephemeral SQLite fixture, proves
+ignored fields and spoofed forwarding headers cannot buy more reset emails,
+and removes only its run-specific messages and Redis keys. The three endpoints
+can be changed with the `NAJM_AUTH_MAILPIT_*` variables, but non-loopback
+values fail before the fixture is created.
+
 Test files include:
 - `schema.test.ts` — Schema exports validation
 - `auth.test.ts` — Authentication flow

package/dist/client/edge.d.ts

@@ -3,6 +3,19 @@ import { S as SessionRecoveryFailure } from '../sessionRecovery-D5Fa0yZ1.js';
 export { a as SessionRecoveryErrorDetails, b as SessionRecoveryFailureReason } from '../sessionRecovery-D5Fa0yZ1.js';
 
 type ProxySessionMode = 'optimistic' | 'authoritative';
+/**
+ * Per-request headers an application proxy needs to expose to the downstream
+ * Next.js render. This is primarily useful for request-scoped values such as a
+ * Content Security Policy nonce.
+ *
+ * Values are merged over the incoming request headers. Authentication always
+ * evaluates the original request, so these overrides cannot change which
+ * principal or cookie Najm authorizes. `authorization` and `cookie` are
+ * rejected here; only Najm's validated recovery path may replace the cookie.
+ */
+interface AuthProxyOptions {
+    requestHeaders?: HeadersInit;
+}
 interface AuthMiddlewareConfig {
     /** Routes that require authentication (glob patterns) */
     protectedRoutes?: string[];
@@ -73,6 +86,6 @@ interface AuthMiddlewareConfig {
  * };
  * ```
  */
-declare function withAuthMiddleware(config: AuthMiddlewareConfig): (request: Request) => Promise<next_server.NextResponse<unknown>>;
+declare function withAuthMiddleware(config: AuthMiddlewareConfig): (request: Request, options?: AuthProxyOptions) => Promise<next_server.NextResponse<unknown>>;
 
-export { type AuthMiddlewareConfig, type ProxySessionMode, SessionRecoveryFailure, withAuthMiddleware };
+export { type AuthMiddlewareConfig, type AuthProxyOptions, type ProxySessionMode, SessionRecoveryFailure, withAuthMiddleware };

package/dist/client/edge.js

@@ -19,6 +19,7 @@ function parseSessionCookiePayload(payload, maxAgeSeconds = DEFAULT_SESSION_MAX_
     if (!isRecord(data) || !isValidUser(data.user)) return null;
     if (!isStringArray(data.roles) || !isStringArray(data.permissions)) return null;
     if (!Number.isInteger(data.sessionVersion) || data.sessionVersion < 0) return null;
+    if (typeof data.tokenFamily !== "string" || !data.tokenFamily) return null;
     if (!Number.isFinite(data.iat) || !Number.isInteger(data.iat) || data.iat <= 0) return null;
     const issuedAt = data.iat;
     if (issuedAt > now + MAX_CLOCK_SKEW_MS) return null;
@@ -28,6 +29,7 @@ function parseSessionCookiePayload(payload, maxAgeSeconds = DEFAULT_SESSION_MAX_
       roles: [...data.roles],
       permissions: [...data.permissions],
       sessionVersion: data.sessionVersion,
+      tokenFamily: data.tokenFamily,
       iat: issuedAt
     };
   } catch {
@@ -353,8 +355,25 @@ function withAuthMiddleware(config) {
   } = config;
   const verifyAlways = proxySessionMode === void 0 ? legacyVerifyAlways : proxySessionMode === "authoritative";
   const resolvedInternalRecoveryURL = resolveInternalRecoveryURL(internalRecoveryURL);
-  return /* @__PURE__ */ __name(async function middleware(request) {
+  return /* @__PURE__ */ __name(async function middleware(request, options = {}) {
     const { NextResponse } = await import("next/server");
+    const downstreamHeaders = new Headers(request.headers);
+    if (options.requestHeaders) {
+      const overrides = new Headers(options.requestHeaders);
+      for (const identityHeader of ["authorization", "cookie"]) {
+        if (overrides.has(identityHeader)) {
+          throw new TypeError(
+            `Auth proxy requestHeaders cannot override ${identityHeader}`
+          );
+        }
+      }
+      overrides.forEach((value, key) => {
+        downstreamHeaders.set(key, value);
+      });
+    }
+    const continueRequest = /* @__PURE__ */ __name(() => NextResponse.next({
+      request: { headers: downstreamHeaders }
+    }), "continueRequest");
     const redirectToLogin = /* @__PURE__ */ __name((returnPath2, clearCookies) => {
       const loginUrl = new URL(loginRoute, request.url);
       loginUrl.searchParams.set("from", returnPath2);
@@ -371,10 +390,10 @@ function withAuthMiddleware(config) {
     const pathname = url.pathname;
     const returnPath = `${url.pathname}${url.search}`;
     if (matchesAny(pathname, publicRoutes)) {
-      return NextResponse.next();
+      return continueRequest();
     }
     const isProtected = protectedRoutes.length === 0 || matchesAny(pathname, protectedRoutes);
-    if (!isProtected) return NextResponse.next();
+    if (!isProtected) return continueRequest();
     const cookie = request.headers.get("cookie") ?? "";
     const sessionCookie = readCookieValue(cookie, sessionCookieName);
     const secret = resolveSessionSecret(sessionSecret);
@@ -420,16 +439,15 @@ function withAuthMiddleware(config) {
       return forbidden;
     }
     if (recovery?.status === "recovered") {
-      const requestHeaders = new Headers(request.headers);
-      requestHeaders.set(
+      downstreamHeaders.set(
         "cookie",
         replaceCookieValue(cookie, sessionCookieName, recovery.sessionCookieValue)
       );
-      const response = NextResponse.next({ request: { headers: requestHeaders } });
+      const response = continueRequest();
       response.headers.append("Set-Cookie", recovery.setCookie);
       return response;
     }
-    return NextResponse.next();
+    return continueRequest();
   }, "middleware");
 }
 __name(withAuthMiddleware, "withAuthMiddleware");

package/dist/client/server/index.d.ts

@@ -1,6 +1,6 @@
 import { A as AuthUser, R as RetryConfig } from '../../types-CI2t8wpJ.js';
 import { F as FetchClient, N as NajmAuthClient } from '../../NajmAuthClient-BygfBCpF.js';
-import { ProxySessionMode } from '../edge.js';
+import { AuthProxyOptions, ProxySessionMode } from '../edge.js';
 export { withAuthMiddleware } from '../edge.js';
 import { G as GetSessionConfig, S as ServerSession$1 } from '../../getSession-DBX8XpsR.js';
 export { A as AuthConfigError, a as AuthTransportError, N as NoSessionError, g as getSession } from '../../getSession-DBX8XpsR.js';
@@ -244,9 +244,9 @@ interface AuthKit {
      */
     requireRole: (roles: string[]) => Promise<ServerSession$1>;
     /** Generated Next.js 16 Proxy function. */
-    proxy: (request: Request) => Promise<Response>;
+    proxy: (request: Request, options?: AuthProxyOptions) => Promise<Response>;
     /** @deprecated Next.js 16 renamed Middleware to Proxy. Use `proxy`. */
-    middleware: (request: Request) => Promise<Response>;
+    middleware: (request: Request, options?: AuthProxyOptions) => Promise<Response>;
     /** @deprecated Next.js 16 requires a static config literal in `proxy.ts`. */
     config: {
         matcher: string[];
@@ -298,4 +298,4 @@ interface SafeRedirectOptions {
  */
 declare function getSafeRedirectPath(value: string | string[] | undefined | null, options?: SafeRedirectOptions | string): string;
 
-export { type AuthCookiePersistenceOptions, type AuthKit, type AuthRouteHandler, type DefineAuthConfig, GetSessionConfig, type NextAuthRouteHandlers, ProxySessionMode, type SafeRedirectOptions, ServerSession$1 as ServerSession, SessionRecoveryFailure, type WithAuthOptions, type WithAuthProps, createServerClient, defineAuth, getSafeRedirectPath, getServerSession, makeSessionCookie, withAuth, withAuthCookiePersistence };
+export { type AuthCookiePersistenceOptions, type AuthKit, AuthProxyOptions, type AuthRouteHandler, type DefineAuthConfig, GetSessionConfig, type NextAuthRouteHandlers, ProxySessionMode, type SafeRedirectOptions, ServerSession$1 as ServerSession, SessionRecoveryFailure, type WithAuthOptions, type WithAuthProps, createServerClient, defineAuth, getSafeRedirectPath, getServerSession, makeSessionCookie, withAuth, withAuthCookiePersistence };

package/dist/client/server/index.js

@@ -22,6 +22,7 @@ function parseSessionCookiePayload(payload, maxAgeSeconds = DEFAULT_SESSION_MAX_
     if (!isRecord(data) || !isValidUser(data.user)) return null;
     if (!isStringArray(data.roles) || !isStringArray(data.permissions)) return null;
     if (!Number.isInteger(data.sessionVersion) || data.sessionVersion < 0) return null;
+    if (typeof data.tokenFamily !== "string" || !data.tokenFamily) return null;
     if (!Number.isFinite(data.iat) || !Number.isInteger(data.iat) || data.iat <= 0) return null;
     const issuedAt = data.iat;
     if (issuedAt > now + MAX_CLOCK_SKEW_MS) return null;
@@ -31,6 +32,7 @@ function parseSessionCookiePayload(payload, maxAgeSeconds = DEFAULT_SESSION_MAX_
       roles: [...data.roles],
       permissions: [...data.permissions],
       sessionVersion: data.sessionVersion,
+      tokenFamily: data.tokenFamily,
       iat: issuedAt
     };
   } catch {
@@ -764,8 +766,25 @@ function withAuthMiddleware(config) {
   } = config;
   const verifyAlways = proxySessionMode === void 0 ? legacyVerifyAlways : proxySessionMode === "authoritative";
   const resolvedInternalRecoveryURL = resolveInternalRecoveryURL(internalRecoveryURL);
-  return /* @__PURE__ */ __name(async function middleware(request) {
+  return /* @__PURE__ */ __name(async function middleware(request, options = {}) {
     const { NextResponse } = await import("next/server");
+    const downstreamHeaders = new Headers(request.headers);
+    if (options.requestHeaders) {
+      const overrides = new Headers(options.requestHeaders);
+      for (const identityHeader of ["authorization", "cookie"]) {
+        if (overrides.has(identityHeader)) {
+          throw new TypeError(
+            `Auth proxy requestHeaders cannot override ${identityHeader}`
+          );
+        }
+      }
+      overrides.forEach((value, key) => {
+        downstreamHeaders.set(key, value);
+      });
+    }
+    const continueRequest = /* @__PURE__ */ __name(() => NextResponse.next({
+      request: { headers: downstreamHeaders }
+    }), "continueRequest");
     const redirectToLogin = /* @__PURE__ */ __name((returnPath2, clearCookies) => {
       const loginUrl = new URL(loginRoute, request.url);
       loginUrl.searchParams.set("from", returnPath2);
@@ -782,10 +801,10 @@ function withAuthMiddleware(config) {
     const pathname = url.pathname;
     const returnPath = `${url.pathname}${url.search}`;
     if (matchesAny(pathname, publicRoutes)) {
-      return NextResponse.next();
+      return continueRequest();
     }
     const isProtected = protectedRoutes.length === 0 || matchesAny(pathname, protectedRoutes);
-    if (!isProtected) return NextResponse.next();
+    if (!isProtected) return continueRequest();
     const cookie = request.headers.get("cookie") ?? "";
     const sessionCookie = readCookieValue(cookie, sessionCookieName);
     const secret = resolveSessionSecret(sessionSecret);
@@ -831,16 +850,15 @@ function withAuthMiddleware(config) {
       return forbidden;
     }
     if (recovery?.status === "recovered") {
-      const requestHeaders = new Headers(request.headers);
-      requestHeaders.set(
+      downstreamHeaders.set(
         "cookie",
         replaceCookieValue(cookie, sessionCookieName, recovery.sessionCookieValue)
       );
-      const response = NextResponse.next({ request: { headers: requestHeaders } });
+      const response = continueRequest();
       response.headers.append("Set-Cookie", recovery.setCookie);
       return response;
     }
-    return NextResponse.next();
+    return continueRequest();
   }, "middleware");
 }
 __name(withAuthMiddleware, "withAuthMiddleware");