najm-auth 3.3.2 → 4.0.0

package/README.md

@@ -98,6 +98,10 @@ 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
 ```
 
 > ⚠️ **Security:** Generate secrets with `openssl rand -base64 32`
@@ -129,10 +133,10 @@ auth({
   database?: string                        // Default: 'default'
   blacklistPrefix?: string                 // Default: 'auth:blacklist:'
 
-  // Registration
-  defaultRole?: string | null              // Auto-assign role to new users
-  publicRegistration?: boolean             // Default: true; mounts POST /auth/register
-  bcryptRounds?: number                    // Default: 10 (valid: 4-31)
+  // Registration
+  defaultRole?: string | null              // Auto-assign role to new users
+  publicRegistration?: boolean             // Default: true; mounts POST /auth/register
+  bcryptRounds?: number                    // Default: 10 (valid: 4-31)
 
   // Frontend
   frontendUrl?: string                     // Password reset link base URL
@@ -152,7 +156,7 @@ auth({
     }
   }
 
-  // Optional Google OpenID Connect
+  // Optional external identity providers
   oauth?: {
     google?: true | {
       clientId?: string                    // Or GOOGLE_CLIENT_ID
@@ -164,6 +168,15 @@ auth({
       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)
@@ -182,7 +195,7 @@ All routes are prefixed with `/auth` and auto-registered by the plugin.
 
 | Method | Path | Description | Auth |
 |--------|------|-------------|------|
-| `POST` | `/auth/register` | Register new user (omitted when `publicRegistration: false`) | None |
+| `POST` | `/auth/register` | Register new user (omitted when `publicRegistration: false`) | None |
 | `POST` | `/auth/login` | Login with email/password | None |
 | `POST` | `/auth/refresh` | Refresh access token (cookie) | None (uses refresh cookie) |
 | `POST` | `/auth/session/recover` | Reissue signed session without token rotation | Refresh cookie + recovery header |
@@ -195,12 +208,12 @@ All routes are prefixed with `/auth` and auto-registered by the plugin.
 | `POST` | `/auth/oauth/google/link` | Link Google to the current user | ✅ Required |
 | `GET` | `/auth/credential-setup/setup` | Read the pending setup session | Setup cookie |
 | `POST` | `/auth/credential-setup/change` | Replace the temporary credential | Setup cookie |
-| `POST` | `/auth/credential-setup/cancel` | Abandon the setup session | Setup cookie |
-
-Applications with an approval-owned onboarding flow should set
-`publicRegistration: false`. This removes the unauthenticated route while
-retaining `AuthService.registerUser()`, `provisionUser()`, and other internal
-account-management APIs for trusted application services.
+| `POST` | `/auth/credential-setup/cancel` | Abandon the setup session | Setup cookie |
+
+Applications with an approval-owned onboarding flow should set
+`publicRegistration: false`. This removes the unauthenticated route while
+retaining `AuthService.registerUser()`, `provisionUser()`, and other internal
+account-management APIs for trusted application services.
 
 ### Identity presets
 
@@ -336,6 +349,20 @@ user has the same email but is not linked, sign-in fails with
 `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()`)
 
 | Method | Path | Description |
@@ -637,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 Google 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.
 
@@ -822,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';
@@ -1025,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
@@ -1065,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
 
@@ -1125,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
@@ -1150,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/{NajmAuthClient-BBl-GRis.d.ts → NajmAuthClient-BygfBCpF.d.ts}

@@ -1,4 +1,4 @@
-import { R as RetryConfig, a as RequestOptions, A as AuthUser, b as AuthClientConfig, L as LoginCredentials, c as LoginResult, O as OAuthProvider, d as OAuthLoginOptions, e as AuthState, f as AuthEvent, g as AuthEventHandler } from './types-BaSfgxqE.js';
+import { R as RetryConfig, a as RequestOptions, A as AuthUser, b as AuthClientConfig, L as LoginCredentials, c as LoginResult, O as OAuthProvider, d as OAuthLoginOptions, e as AuthState, f as AuthEvent, g as AuthEventHandler } from './types-CI2t8wpJ.js';
 
 interface FetchClientConfig {
     baseURL: string;
@@ -63,6 +63,7 @@ declare class NajmAuthClient {
     getOAuthLoginUrl(provider: OAuthProvider, options?: OAuthLoginOptions): string;
     loginWithOAuth(provider: OAuthProvider, options?: OAuthLoginOptions): void;
     loginWithGoogle(options?: OAuthLoginOptions): void;
+    loginWithGitHub(options?: OAuthLoginOptions): void;
     linkOAuthAccount(provider: OAuthProvider, options?: OAuthLoginOptions): Promise<void>;
     completeOAuthLogin(): Promise<AuthUser>;
     logout(): Promise<void>;

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/index.d.ts

@@ -1,6 +1,6 @@
-export { F as FetchClient, H as HydrateSession, N as NajmAuthClient, c as createAuthClient } from '../NajmAuthClient-BBl-GRis.js';
-import { D as DecodedToken, T as TabSyncMessage, S as SyncPayload } from '../types-BaSfgxqE.js';
-export { b as AuthClientConfig, h as AuthError, f as AuthEvent, g as AuthEventHandler, i as AuthEventMap, e as AuthState, A as AuthUser, j as AuthenticatedLogin, C as CredentialSetupPending, L as LoginCredentials, c as LoginResult, d as OAuthLoginOptions, O as OAuthProvider, a as RequestOptions, R as RetryConfig, k as ServerResponse, l as TokenPair } from '../types-BaSfgxqE.js';
+export { F as FetchClient, H as HydrateSession, N as NajmAuthClient, c as createAuthClient } from '../NajmAuthClient-BygfBCpF.js';
+import { D as DecodedToken, T as TabSyncMessage, S as SyncPayload } from '../types-CI2t8wpJ.js';
+export { b as AuthClientConfig, h as AuthError, f as AuthEvent, g as AuthEventHandler, i as AuthEventMap, e as AuthState, A as AuthUser, j as AuthenticatedLogin, C as CredentialSetupPending, L as LoginCredentials, c as LoginResult, d as OAuthLoginOptions, O as OAuthProvider, a as RequestOptions, R as RetryConfig, k as ServerResponse, l as TokenPair } from '../types-CI2t8wpJ.js';
 
 /**
  * Decode a JWT token payload without verification.

package/dist/client/index.js

@@ -334,6 +334,9 @@ var NajmAuthClient = class _NajmAuthClient {
   loginWithGoogle(options) {
     this.loginWithOAuth("google", options);
   }
+  loginWithGitHub(options) {
+    this.loginWithOAuth("github", options);
+  }
   async linkOAuthAccount(provider, options = {}) {
     const query = options.returnTo ? `?${new URLSearchParams({ returnTo: this.validateReturnTo(options.returnTo) })}` : "";
     const res = await this.api.post(

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

@@ -1,7 +1,7 @@
 import * as react from 'react';
 import { ReactNode, CSSProperties, ReactElement } from 'react';
-import { N as NajmAuthClient, H as HydrateSession } from '../../NajmAuthClient-BBl-GRis.js';
-import { e as AuthState, A as AuthUser, c as LoginResult, h as AuthError, L as LoginCredentials, d as OAuthLoginOptions, f as AuthEvent, i as AuthEventMap } from '../../types-BaSfgxqE.js';
+import { N as NajmAuthClient, H as HydrateSession } from '../../NajmAuthClient-BygfBCpF.js';
+import { e as AuthState, A as AuthUser, c as LoginResult, h as AuthError, L as LoginCredentials, d as OAuthLoginOptions, f as AuthEvent, i as AuthEventMap } from '../../types-CI2t8wpJ.js';
 
 interface AuthProviderProps {
     client: NajmAuthClient;
@@ -177,6 +177,17 @@ interface UseGoogleLoginReturn {
 }
 declare function useGoogleLogin(options?: UseGoogleLoginOptions): UseGoogleLoginReturn;
 
+interface UseGitHubLoginOptions {
+    onError?: (error: AuthError | Error) => void;
+}
+interface UseGitHubLoginReturn {
+    loginWithGitHub: (options?: OAuthLoginOptions) => void;
+    linkGitHub: (options?: OAuthLoginOptions) => Promise<void>;
+    isRedirecting: boolean;
+    error: AuthError | Error | null;
+}
+declare function useGitHubLogin(options?: UseGitHubLoginOptions): UseGitHubLoginReturn;
+
 interface UseOAuthCallbackOptions {
     onSuccess?: (user: AuthUser) => void;
     onError?: (error: AuthError | Error) => void;
@@ -571,6 +582,15 @@ declare function GoogleLoginButton({ children, returnTo, onError }: GoogleLoginB
     disabled?: boolean;
 }, string | react.JSXElementConstructor<any>>;
 
+interface GitHubLoginButtonProps extends OAuthLoginOptions {
+    children: ReactNode;
+    onError?: (error: Error) => void;
+}
+declare function GitHubLoginButton({ children, returnTo, onError }: GitHubLoginButtonProps): ReactElement<{
+    onClick?: (event: unknown) => void;
+    disabled?: boolean;
+}, string | react.JSXElementConstructor<any>>;
+
 interface OAuthCallbackProps {
     fallback?: ReactNode;
     errorFallback?: ReactNode | ((props: {
@@ -580,4 +600,4 @@ interface OAuthCallbackProps {
 }
 declare function OAuthCallback({ fallback, errorFallback, defaultRedirect, }: OAuthCallbackProps): react.JSX.Element;
 
-export { AuthBoundary, type AuthEventEntry, AuthGate, AuthLoading, AuthProvider, Can, GoogleLoginButton, IfAuth, LoginButton, OAuthCallback, PermissionList, Protected, RedirectToLogin, Role, type SessionStatus, SignOutButton, SignedIn, SignedOut, UserAvatar, UserEmail, UserName, UserRole, useAuth, useAuthClient, useAuthEvent, useAuthEvents, useChangePassword, useForgotPassword, useGoogleLogin, useLogin, useLogout, useOAuthCallback, usePermissions, useRegister, useResetPassword, useSession, useUser };
+export { AuthBoundary, type AuthEventEntry, AuthGate, AuthLoading, AuthProvider, Can, GitHubLoginButton, GoogleLoginButton, IfAuth, LoginButton, OAuthCallback, PermissionList, Protected, RedirectToLogin, Role, type SessionStatus, SignOutButton, SignedIn, SignedOut, UserAvatar, UserEmail, UserName, UserRole, useAuth, useAuthClient, useAuthEvent, useAuthEvents, useChangePassword, useForgotPassword, useGitHubLogin, useGoogleLogin, useLogin, useLogout, useOAuthCallback, usePermissions, useRegister, useResetPassword, useSession, useUser };

package/dist/client/react/index.js

@@ -354,14 +354,48 @@ function useGoogleLogin(options) {
 }
 __name(useGoogleLogin, "useGoogleLogin");
 
+// src/client/react/useGitHubLogin.ts
+import { useCallback as useCallback8, useState as useState10 } from "react";
+function useGitHubLogin(options) {
+  const client = useAuthClient();
+  const [isRedirecting, setIsRedirecting] = useState10(false);
+  const [error, setError] = useState10(null);
+  const fail = useCallback8((value) => {
+    const next = value instanceof Error ? value : new Error(String(value));
+    setIsRedirecting(false);
+    setError(next);
+    options?.onError?.(next);
+  }, [options?.onError]);
+  const loginWithGitHub = useCallback8((loginOptions) => {
+    setError(null);
+    setIsRedirecting(true);
+    try {
+      client.loginWithGitHub(loginOptions);
+    } catch (value) {
+      fail(value);
+    }
+  }, [client, fail]);
+  const linkGitHub = useCallback8(async (loginOptions) => {
+    setError(null);
+    setIsRedirecting(true);
+    try {
+      await client.linkOAuthAccount("github", loginOptions);
+    } catch (value) {
+      fail(value);
+    }
+  }, [client, fail]);
+  return { loginWithGitHub, linkGitHub, isRedirecting, error };
+}
+__name(useGitHubLogin, "useGitHubLogin");
+
 // src/client/react/useOAuthCallback.ts
-import { useCallback as useCallback8, useRef as useRef3, useState as useState10 } from "react";
+import { useCallback as useCallback9, useRef as useRef3, useState as useState11 } from "react";
 function useOAuthCallback(options) {
   const client = useAuthClient();
   const promise = useRef3(null);
-  const [isLoading, setIsLoading] = useState10(false);
-  const [error, setError] = useState10(null);
-  const complete = useCallback8(async () => {
+  const [isLoading, setIsLoading] = useState11(false);
+  const [error, setError] = useState11(null);
+  const complete = useCallback9(async () => {
     if (promise.current) return promise.current;
     setIsLoading(true);
     setError(null);
@@ -398,7 +432,7 @@ function useAuthEvent(event, handler) {
 __name(useAuthEvent, "useAuthEvent");
 
 // src/client/react/useAuthEvents.ts
-import { useEffect as useEffect4, useRef as useRef5, useState as useState11 } from "react";
+import { useEffect as useEffect4, useRef as useRef5, useState as useState12 } from "react";
 var ALL_EVENTS = [
   "login",
   "logout",
@@ -411,7 +445,7 @@ var ALL_EVENTS = [
 function useAuthEvents(opts) {
   const client = useAuthClient();
   const max = opts?.maxEntries ?? 100;
-  const [entries, setEntries] = useState11([]);
+  const [entries, setEntries] = useState12([]);
   const maxRef = useRef5(max);
   maxRef.current = max;
   useEffect4(() => {
@@ -714,6 +748,27 @@ function GoogleLoginButton({ children, returnTo, onError }) {
 }
 __name(GoogleLoginButton, "GoogleLoginButton");
 
+// src/client/react/GitHubLoginButton.tsx
+import { Children as Children4, cloneElement as cloneElement4, isValidElement as isValidElement4 } from "react";
+function GitHubLoginButton({ children, returnTo, onError }) {
+  const { loginWithGitHub, isRedirecting } = useGitHubLogin({ onError });
+  const child = Children4.only(children);
+  if (!isValidElement4(child)) {
+    throw new Error("<GitHubLoginButton> expects a single React element as its child");
+  }
+  const element = child;
+  return cloneElement4(element, {
+    onClick: /* @__PURE__ */ __name((event) => {
+      element.props.onClick?.(event);
+      if (!event?.defaultPrevented) {
+        loginWithGitHub({ returnTo });
+      }
+    }, "onClick"),
+    disabled: Boolean(element.props.disabled || isRedirecting)
+  });
+}
+__name(GitHubLoginButton, "GitHubLoginButton");
+
 // src/client/react/OAuthCallback.tsx
 import { useEffect as useEffect7 } from "react";
 import { Fragment as Fragment14, jsx as jsx16 } from "react/jsx-runtime";
@@ -755,6 +810,7 @@ export {
   AuthLoading,
   AuthProvider,
   Can,
+  GitHubLoginButton,
   GoogleLoginButton,
   IfAuth,
   LoginButton,
@@ -776,6 +832,7 @@ export {
   useAuthEvents,
   useChangePassword,
   useForgotPassword,
+  useGitHubLogin,
   useGoogleLogin,
   useLogin,
   useLogout,

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

@@ -1,9 +1,9 @@
-import { A as AuthUser, R as RetryConfig } from '../../types-BaSfgxqE.js';
-import { F as FetchClient, N as NajmAuthClient } from '../../NajmAuthClient-BBl-GRis.js';
-import { ProxySessionMode } from '../edge.js';
+import { A as AuthUser, R as RetryConfig } from '../../types-CI2t8wpJ.js';
+import { F as FetchClient, N as NajmAuthClient } from '../../NajmAuthClient-BygfBCpF.js';
+import { AuthProxyOptions, ProxySessionMode } from '../edge.js';
 export { withAuthMiddleware } from '../edge.js';
-import { G as GetSessionConfig, S as ServerSession$1 } from '../../getSession-BthP85UA.js';
-export { A as AuthConfigError, a as AuthTransportError, N as NoSessionError, g as getSession } from '../../getSession-BthP85UA.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';
 import { S as SessionRecoveryFailure } from '../../sessionRecovery-D5Fa0yZ1.js';
 export { a as SessionRecoveryErrorDetails, b as SessionRecoveryFailureReason } from '../../sessionRecovery-D5Fa0yZ1.js';
 import 'next/server';
@@ -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");
@@ -1045,6 +1063,9 @@ var NajmAuthClient = class _NajmAuthClient {
   loginWithGoogle(options) {
     this.loginWithOAuth("google", options);
   }
+  loginWithGitHub(options) {
+    this.loginWithOAuth("github", options);
+  }
   async linkOAuthAccount(provider, options = {}) {
     const query = options.returnTo ? `?${new URLSearchParams({ returnTo: this.validateReturnTo(options.returnTo) })}` : "";
     const res = await this.api.post(

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

@@ -1,5 +1,5 @@
-import { S as ServerSession } from '../../getSession-BthP85UA.js';
-import '../../types-BaSfgxqE.js';
+import { S as ServerSession } from '../../getSession-DBX8XpsR.js';
+import '../../types-CI2t8wpJ.js';
 import '../../sessionRecovery-D5Fa0yZ1.js';
 
 /**