najm-auth 3.3.1 → 3.4.0

package/README.md

@@ -97,7 +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
+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
@@ -162,8 +166,17 @@ auth({
       errorRedirectPath?: string           // Default: /login
       allowSignup?: boolean                // Default: true
       autoLinkVerifiedEmail?: boolean      // Default: false
-      allowedHostedDomains?: string[]      // Validates the Google hd claim
-    }
+      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
 
@@ -333,8 +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.
+`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()`)
 
@@ -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.
 

package/dist/{NajmAuthClient-ZtXTIUSF.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>;
@@ -110,6 +111,7 @@ declare class NajmAuthClient {
     private _refreshWithCircuit;
     private _doRefresh;
     private handleUnauthorized;
+    private requestServerLogout;
     private applyTokens;
     private scheduleRefresh;
     private clearRefreshTimer;

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-ZtXTIUSF.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(
@@ -364,7 +367,7 @@ var NajmAuthClient = class _NajmAuthClient {
     this.emit("logout", null);
     try {
       await pendingRefresh?.catch(() => void 0);
-      await this.api.post(`${this.prefix}/logout`, { skipAuth: true });
+      await this.requestServerLogout();
     } catch (err) {
       this.emit("logoutError", err);
     }
@@ -549,6 +552,7 @@ var NajmAuthClient = class _NajmAuthClient {
       if (generation !== this.authGeneration) return;
       const shouldOpenCircuit = this.registerRefreshFailure(err);
       if (shouldOpenCircuit) {
+        await this.requestServerLogout().catch(() => void 0);
         this.resetState();
         this.emit("sessionExpired", null);
         if (err instanceof AuthError && err.status === 401) {
@@ -578,6 +582,9 @@ var NajmAuthClient = class _NajmAuthClient {
       return null;
     }
   }
+  async requestServerLogout() {
+    await this.api.post(`${this.prefix}/logout`, { skipAuth: true });
+  }
   applyTokens(tokens) {
     this.resetRefreshFailures();
     const decoded = decodeToken(tokens.accessToken);
@@ -618,7 +625,7 @@ var NajmAuthClient = class _NajmAuthClient {
     this.clearRefreshCircuitTimer();
   }
   registerRefreshFailure(err) {
-    if (err instanceof AuthError && err.status === 401) {
+    if (err instanceof AuthError && [401, 403, 429].includes(err.status)) {
       this.refreshFailures = _NajmAuthClient.MAX_REFRESH_FAILURES;
     } else {
       this.refreshFailures += 1;

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-ZtXTIUSF.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-ZtXTIUSF.js';
+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';
 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';

package/dist/client/server/index.js

@@ -1045,6 +1045,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(
@@ -1075,7 +1078,7 @@ var NajmAuthClient = class _NajmAuthClient {
     this.emit("logout", null);
     try {
       await pendingRefresh?.catch(() => void 0);
-      await this.api.post(`${this.prefix}/logout`, { skipAuth: true });
+      await this.requestServerLogout();
     } catch (err) {
       this.emit("logoutError", err);
     }
@@ -1260,6 +1263,7 @@ var NajmAuthClient = class _NajmAuthClient {
       if (generation !== this.authGeneration) return;
       const shouldOpenCircuit = this.registerRefreshFailure(err);
       if (shouldOpenCircuit) {
+        await this.requestServerLogout().catch(() => void 0);
         this.resetState();
         this.emit("sessionExpired", null);
         if (err instanceof AuthError && err.status === 401) {
@@ -1289,6 +1293,9 @@ var NajmAuthClient = class _NajmAuthClient {
       return null;
     }
   }
+  async requestServerLogout() {
+    await this.api.post(`${this.prefix}/logout`, { skipAuth: true });
+  }
   applyTokens(tokens) {
     this.resetRefreshFailures();
     const decoded = decodeToken(tokens.accessToken);
@@ -1329,7 +1336,7 @@ var NajmAuthClient = class _NajmAuthClient {
     this.clearRefreshCircuitTimer();
   }
   registerRefreshFailure(err) {
-    if (err instanceof AuthError && err.status === 401) {
+    if (err instanceof AuthError && [401, 403, 429].includes(err.status)) {
       this.refreshFailures = _NajmAuthClient.MAX_REFRESH_FAILURES;
     } else {
       this.refreshFailures += 1;

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';
 
 /**

package/dist/{getSession-BthP85UA.d.ts → getSession-DBX8XpsR.d.ts}

@@ -1,4 +1,4 @@
-import { A as AuthUser } from './types-BaSfgxqE.js';
+import { A as AuthUser } from './types-CI2t8wpJ.js';
 import { S as SessionRecoveryFailure } from './sessionRecovery-D5Fa0yZ1.js';
 
 interface ServerSession {

package/dist/index.d.ts

@@ -109,7 +109,7 @@ interface SessionCookieConfig {
     /** HMAC secret. Falls back to NAJM_SESSION_SECRET, then jwt.accessSecret. */
     secret?: string;
 }
-type OAuthProvider = 'google';
+type OAuthProvider = 'google' | 'github';
 interface GoogleOAuthConfig {
     /** Google OAuth web client ID. Falls back to GOOGLE_CLIENT_ID. */
     clientId?: string;
@@ -131,12 +131,33 @@ interface GoogleOAuthConfig {
     /** Optional Google Workspace hosted-domain allowlist. */
     allowedHostedDomains?: string[];
 }
+interface GitHubOAuthConfig {
+    /** GitHub OAuth App client ID. Falls back to GITHUB_CLIENT_ID. */
+    clientId?: string;
+    /** GitHub OAuth App client secret. Falls back to GITHUB_CLIENT_SECRET. */
+    clientSecret?: string;
+    /**
+     * Absolute backend callback URL registered in GitHub. Falls back to
+     * GITHUB_CALLBACK_URL, then `${frontendUrl}/api/auth/oauth/github/callback`.
+     */
+    callbackUrl?: string;
+    /** Frontend route that completes the Najm client session. */
+    frontendCallbackPath?: string;
+    /** Frontend route that receives stable OAuth errors. */
+    errorRedirectPath?: string;
+    /** Create a Najm user for a new GitHub identity (default: true). */
+    allowSignup?: boolean;
+    /** Link an existing user by verified email (default: false). */
+    autoLinkVerifiedEmail?: boolean;
+}
 interface OAuthConfig {
     /**
      * Enable Google with environment defaults (`google: true`), or override
      * individual settings for split-origin deployments and policy changes.
      */
     google?: true | GoogleOAuthConfig;
+    /** Enable GitHub with environment defaults, or override provider settings. */
+    github?: true | GitHubOAuthConfig;
 }
 interface ResolvedGoogleOAuthConfig {
     clientId: string;
@@ -148,8 +169,18 @@ interface ResolvedGoogleOAuthConfig {
     autoLinkVerifiedEmail: boolean;
     allowedHostedDomains: string[];
 }
+interface ResolvedGitHubOAuthConfig {
+    clientId: string;
+    clientSecret: string;
+    callbackUrl: string;
+    frontendCallbackPath: string;
+    errorRedirectPath: string;
+    allowSignup: boolean;
+    autoLinkVerifiedEmail: boolean;
+}
 interface ResolvedOAuthConfig {
     google?: ResolvedGoogleOAuthConfig;
+    github?: ResolvedGitHubOAuthConfig;
 }
 /**
  * Complete auth plugin configuration (internal)
@@ -723,7 +754,6 @@ declare class UserValidator {
      * Check if user exists by email
      */
     checkUserExistsByEmail(email: string): Promise<{
-        password: string;
         id: string;
         name: string;
         createdAt: string;
@@ -732,8 +762,9 @@ declare class UserValidator {
         emailVerified: boolean;
         phone: string;
         phoneVerified: boolean;
+        password: string;
         image: string;
-        status: "active" | "pending" | "inactive";
+        status: "active" | "inactive" | "pending";
         roleId: string;
         lastLogin: string;
         failedLoginAttempts: number;
@@ -745,7 +776,6 @@ declare class UserValidator {
      * Check if email exists in database
      */
     checkEmailExists(email: string): Promise<{
-        password: string;
         id: string;
         name: string;
         createdAt: string;
@@ -754,8 +784,9 @@ declare class UserValidator {
         emailVerified: boolean;
         phone: string;
         phoneVerified: boolean;
+        password: string;
         image: string;
-        status: "active" | "pending" | "inactive";
+        status: "active" | "inactive" | "pending";
         roleId: string;
         lastLogin: string;
         failedLoginAttempts: number;
@@ -1281,8 +1312,8 @@ declare const createUserDto: z.ZodObject<{
     emailVerified: z.ZodDefault<z.ZodBoolean>;
     status: z.ZodOptional<z.ZodEnum<{
         active: "active";
-        pending: "pending";
         inactive: "inactive";
+        pending: "pending";
     }>>;
 }, z.core.$strip>;
 declare const updateUserDto: z.ZodObject<{
@@ -1294,8 +1325,8 @@ declare const updateUserDto: z.ZodObject<{
     emailVerified: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
     status: z.ZodOptional<z.ZodOptional<z.ZodEnum<{
         active: "active";
-        pending: "pending";
         inactive: "inactive";
+        pending: "pending";
     }>>>;
 }, z.core.$strip>;
 declare const registerDto: z.ZodObject<{
@@ -1626,7 +1657,7 @@ declare class AuthService {
     recoverSession(): Promise<{
         recovered: true;
     }>;
-    logoutUser(userId: string, authorization?: string): Promise<{
+    logoutUser(userId: string | undefined, authorization?: string): Promise<{
         data: any;
         message: string;
     }>;
@@ -1678,7 +1709,6 @@ declare class AuthController {
     constructor(authService: AuthService);
     loginUser(body: LoginDto): Promise<LoginResult>;
     inviteUser(body: InviteUserDto): Promise<Omit<{
-        password: string;
         id: string;
         name: string;
         createdAt: string;
@@ -1687,8 +1717,9 @@ declare class AuthController {
         emailVerified: boolean;
         phone: string;
         phoneVerified: boolean;
+        password: string;
         image: string;
-        status: "active" | "pending" | "inactive";
+        status: "active" | "inactive" | "pending";
         roleId: string;
         lastLogin: string;
         failedLoginAttempts: number;
@@ -1703,7 +1734,7 @@ declare class AuthController {
     recoverSession(recoveryRequest: string | undefined, ctx: Context): Promise<{
         recovered: true;
     }>;
-    logoutUser(userId: string, authorization?: string): Promise<{
+    logoutUser(userId: string | undefined, authorization?: string): Promise<{
         data: any;
         message: string;
     }>;
@@ -1711,7 +1742,6 @@ declare class AuthController {
         message: string;
     }>;
     userProfile(authorization?: string): Promise<Omit<{
-        password: string;
         id: string;
         name: string;
         createdAt: string;
@@ -1720,8 +1750,9 @@ declare class AuthController {
         emailVerified: boolean;
         phone: string;
         phoneVerified: boolean;
+        password: string;
         image: string;
-        status: "active" | "pending" | "inactive";
+        status: "active" | "inactive" | "pending";
         roleId: string;
         lastLogin: string;
         failedLoginAttempts: number;
@@ -2802,4 +2833,4 @@ declare const authSeed: (config: AuthSeedConfig) => Record<string, SeedEntry>;
  */
 declare function seedAuthData(config: SeedAuthDataConfig): Promise<SeedAuthDataResult>;
 
-export { AUTH_CONFIG, AUTH_CORE_MODULE, en as AUTH_EN, AUTH_LOCALES, AUTH_LOGIN_RATE_LIMIT_ENV, AUTH_MODULE, AUTH_PERMISSIONS, AUTH_ROLE, AUTH_SCHEMA, AUTH_SUPPORTED_LANGUAGES, AUTH_USER, type AssignPermissionDto, type AssignRoleDto, type AssignRoleParams, type AuthConfig, AuthController, AuthGuard, type AuthLoginRateLimitConfig, type AuthPluginConfig, AuthQueries, type AuthRateLimitEnvironment, AuthResolver, type AuthSchema, type AuthSeedConfig, AuthService, AuthSessionService, type AuthUser, CREDENTIAL_SETUP_CODES, CREDENTIAL_SETUP_MODULE, Can, CanCreate, CanDelete, CanList, CanRead, CanUpdate, type ChainableGuard, type ChangePasswordDto, type CheckPermissionDto, type ConfiguredOwnership, type ConfirmResetPasswordDto, CookieManager, type CreatePermissionDto, type CreateRoleDto, type CreateTokenDto, type CreateUserDto, type CredentialSetupChangeDto, type CredentialSetupCode, type CredentialSetupConfig, CredentialSetupController, type CredentialSetupOptions, type CredentialSetupPasswordOptions, type CredentialSetupPending, CredentialSetupRepository, CredentialSetupRequirementRepository, type CredentialSetupRequirementRow, CredentialSetupRequirementService, CredentialSetupService, type CredentialSetupSessionInfo, type CredentialSetupStarted, DEFAULT_AUTH_LOGIN_RATE_LIMIT, DEFAULT_CREDENTIAL_SETUP_COOKIE_NAME, DEFAULT_CREDENTIAL_SETUP_TTL_MS, type DefineRolesOptions, type EmailParam, EncryptionService, type GoogleOAuthConfig, IdentityConfig, type IdentityResolver, type InviteUserDto, type JwtConfig, type JwtPayload, type LanguageParam, type LoginDto, type LoginResult, NewPermission, NewRoleEntity, NewUser, type OAuthConfig, type OAuthProvider, Owned, type OwnedMethods, type OwnershipConfig, type OwnershipProvider, type OwnershipRule, OwnershipToken, type OwnershipTokenOptions, PASSWORD_SETUP_PURPOSE, PUBLIC_REGISTRATION_MODULE, PasswordSetupService, Permission, PermissionController, PermissionGuard, type PermissionIdParam, PermissionRepository, PermissionService, PermissionValidator, Policy, type ProvisionUserInput, type ProvisionUserWithPasswordInput, type ProvisionUserWithSetupInput, ROLES, ROLE_GROUPS, type RefreshTokenDto, type RegisterDto, RegistrationController, type ResetPasswordDto, type ResolvedCredentialSetupConfig, ResolvedIdentityConfig, type ResourceAccessor, type ResourceGuards, type ResourceGuardsOptions, type RevokeTokenDto, Role, RoleController, RoleEntity, RoleGuard, type RoleIdParam, type RoleInput, RolePermission, RoleRepository, RoleService, type RoleType, RoleValidator, type RunAsUser, type SanitizedUser, ScopeContext, type ScopeResult, type SeedAuthDataConfig, type SeedAuthDataResult, type SeedUserConfig, type SessionCookieData, TOKEN_STATUS, TOKEN_TYPE, TemporaryCredentialInput, type TokenIdParam, type TokenPair, TokenRepository, TokenService, USER_STATUS, type UpdatePermissionDto, type UpdateRoleDto, type UpdateTokenDto, type UpdateUserDto, User, UserController, type UserIdInParam, type UserIdParam, type UserListQuery, UserRepository, UserService, UserValidator, type UserWithPermissions, type VerifyTokenDto, assignPermissionDto, assignRoleDto, assignRoleParams, auth$1 as auth, authIdentityRateLimitKey, authSeed, avatarsPath, calculateAge, calculateYearsOfExperience, changePasswordDto, checkPermissionDto, clean, configureOwnership, confirmResetPasswordDto, createIdentityResolver, createPermissionDto, createRoleDto, createTokenDto, createUserDto, credentialSetupChangeDto, credentialSetupError, defaultCredentialSetupPasswordSchema, defineRoles, emailParam, formatDate, getAuthLocale, getAvatarFile, inviteUserDto, isAdmin, isAdministrator, isAuth, isEmailIdentifier, isEmpty, isFile, isPath, join, languageParam, loginDto, normalizeAuthIdentifier, normalizeSetupPurpose, own, parseSchema, permissionIdParam, pickProps, refreshTokenDto, registerDto, resetPasswordDto, resolveAuthLoginRateLimitConfig, revokeTokenDto, roleIdParam, runAsUser, seedAuthData, tokenIdParam, updatePermissionDto, updateRoleDto, updateTokenDto, updateUserDto, userIdInParam, userIdParam, userListQuery, verifyTokenDto, where };
+export { AUTH_CONFIG, AUTH_CORE_MODULE, en as AUTH_EN, AUTH_LOCALES, AUTH_LOGIN_RATE_LIMIT_ENV, AUTH_MODULE, AUTH_PERMISSIONS, AUTH_ROLE, AUTH_SCHEMA, AUTH_SUPPORTED_LANGUAGES, AUTH_USER, type AssignPermissionDto, type AssignRoleDto, type AssignRoleParams, type AuthConfig, AuthController, AuthGuard, type AuthLoginRateLimitConfig, type AuthPluginConfig, AuthQueries, type AuthRateLimitEnvironment, AuthResolver, type AuthSchema, type AuthSeedConfig, AuthService, AuthSessionService, type AuthUser, CREDENTIAL_SETUP_CODES, CREDENTIAL_SETUP_MODULE, Can, CanCreate, CanDelete, CanList, CanRead, CanUpdate, type ChainableGuard, type ChangePasswordDto, type CheckPermissionDto, type ConfiguredOwnership, type ConfirmResetPasswordDto, CookieManager, type CreatePermissionDto, type CreateRoleDto, type CreateTokenDto, type CreateUserDto, type CredentialSetupChangeDto, type CredentialSetupCode, type CredentialSetupConfig, CredentialSetupController, type CredentialSetupOptions, type CredentialSetupPasswordOptions, type CredentialSetupPending, CredentialSetupRepository, CredentialSetupRequirementRepository, type CredentialSetupRequirementRow, CredentialSetupRequirementService, CredentialSetupService, type CredentialSetupSessionInfo, type CredentialSetupStarted, DEFAULT_AUTH_LOGIN_RATE_LIMIT, DEFAULT_CREDENTIAL_SETUP_COOKIE_NAME, DEFAULT_CREDENTIAL_SETUP_TTL_MS, type DefineRolesOptions, type EmailParam, EncryptionService, type GitHubOAuthConfig, type GoogleOAuthConfig, IdentityConfig, type IdentityResolver, type InviteUserDto, type JwtConfig, type JwtPayload, type LanguageParam, type LoginDto, type LoginResult, NewPermission, NewRoleEntity, NewUser, type OAuthConfig, type OAuthProvider, Owned, type OwnedMethods, type OwnershipConfig, type OwnershipProvider, type OwnershipRule, OwnershipToken, type OwnershipTokenOptions, PASSWORD_SETUP_PURPOSE, PUBLIC_REGISTRATION_MODULE, PasswordSetupService, Permission, PermissionController, PermissionGuard, type PermissionIdParam, PermissionRepository, PermissionService, PermissionValidator, Policy, type ProvisionUserInput, type ProvisionUserWithPasswordInput, type ProvisionUserWithSetupInput, ROLES, ROLE_GROUPS, type RefreshTokenDto, type RegisterDto, RegistrationController, type ResetPasswordDto, type ResolvedCredentialSetupConfig, ResolvedIdentityConfig, type ResourceAccessor, type ResourceGuards, type ResourceGuardsOptions, type RevokeTokenDto, Role, RoleController, RoleEntity, RoleGuard, type RoleIdParam, type RoleInput, RolePermission, RoleRepository, RoleService, type RoleType, RoleValidator, type RunAsUser, type SanitizedUser, ScopeContext, type ScopeResult, type SeedAuthDataConfig, type SeedAuthDataResult, type SeedUserConfig, type SessionCookieData, TOKEN_STATUS, TOKEN_TYPE, TemporaryCredentialInput, type TokenIdParam, type TokenPair, TokenRepository, TokenService, USER_STATUS, type UpdatePermissionDto, type UpdateRoleDto, type UpdateTokenDto, type UpdateUserDto, User, UserController, type UserIdInParam, type UserIdParam, type UserListQuery, UserRepository, UserService, UserValidator, type UserWithPermissions, type VerifyTokenDto, assignPermissionDto, assignRoleDto, assignRoleParams, auth$1 as auth, authIdentityRateLimitKey, authSeed, avatarsPath, calculateAge, calculateYearsOfExperience, changePasswordDto, checkPermissionDto, clean, configureOwnership, confirmResetPasswordDto, createIdentityResolver, createPermissionDto, createRoleDto, createTokenDto, createUserDto, credentialSetupChangeDto, credentialSetupError, defaultCredentialSetupPasswordSchema, defineRoles, emailParam, formatDate, getAuthLocale, getAvatarFile, inviteUserDto, isAdmin, isAdministrator, isAuth, isEmailIdentifier, isEmpty, isFile, isPath, join, languageParam, loginDto, normalizeAuthIdentifier, normalizeSetupPurpose, own, parseSchema, permissionIdParam, pickProps, refreshTokenDto, registerDto, resetPasswordDto, resolveAuthLoginRateLimitConfig, revokeTokenDto, roleIdParam, runAsUser, seedAuthData, tokenIdParam, updatePermissionDto, updateRoleDto, updateTokenDto, updateUserDto, userIdInParam, userIdParam, userListQuery, verifyTokenDto, where };