najm-auth 1.1.44 → 2.0.2

package/dist/index.d.ts

@@ -2,11 +2,11 @@ import * as najm_core from 'najm-core';
 import { Container } from 'najm-core';
 import { ValidationPluginConfig } from 'najm-validation';
 import { RateLimitPluginConfig } from 'najm-rate';
+import { EmailPluginConfig, EmailService } from 'najm-email';
 import { I18nService } from 'najm-i18n';
-import { EmailService } from 'najm-email';
 import { TDb, SeedEntry } from 'najm-database';
 import { User, NewUser, RoleEntity, NewRoleEntity, Permission, NewPermission, RolePermission } from './schema/pg.js';
-export { NewRolePermission, NewToken, Token, authSchema, baseFields, permissionsTable, rolePermissionsTable, rolesTable, tokenStatusEnum, tokenTypeEnum, tokensTable, userStatusEnum, usersTable } from './schema/pg.js';
+export { NewOAuthAccount, NewRolePermission, NewToken, OAuthAccount, Token, authSchema, baseFields, oauthAccountsTable, permissionsTable, rolePermissionsTable, rolesTable, tokenStatusEnum, tokenTypeEnum, tokensTable, userStatusEnum, usersTable } from './schema/pg.js';
 import { CacheService } from 'najm-cache';
 import { z } from 'zod';
 import { GuardResult } from 'najm-guard';
@@ -45,6 +45,48 @@ interface SessionCookieConfig {
     /** Secret used to HMAC-sign the cookie. Defaults to jwt.accessSecret. */
     secret?: string;
 }
+type OAuthProvider = 'google';
+interface GoogleOAuthConfig {
+    /** Google OAuth web client ID. Falls back to GOOGLE_CLIENT_ID. */
+    clientId?: string;
+    /** Google OAuth web client secret. Falls back to GOOGLE_CLIENT_SECRET. */
+    clientSecret?: string;
+    /**
+     * Absolute backend callback URL registered in Google Cloud. Falls back to
+     * GOOGLE_CALLBACK_URL, then `${frontendUrl}/api/auth/oauth/google/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 Google identity (default: true). */
+    allowSignup?: boolean;
+    /** Link an existing user by verified email (default: false). */
+    autoLinkVerifiedEmail?: boolean;
+    /** Optional Google Workspace hosted-domain allowlist. */
+    allowedHostedDomains?: string[];
+}
+interface OAuthConfig {
+    /**
+     * Enable Google with environment defaults (`google: true`), or override
+     * individual settings for split-origin deployments and policy changes.
+     */
+    google?: true | GoogleOAuthConfig;
+}
+interface ResolvedGoogleOAuthConfig {
+    clientId: string;
+    clientSecret: string;
+    callbackUrl: string;
+    frontendCallbackPath: string;
+    errorRedirectPath: string;
+    allowSignup: boolean;
+    autoLinkVerifiedEmail: boolean;
+    allowedHostedDomains: string[];
+}
+interface ResolvedOAuthConfig {
+    google?: ResolvedGoogleOAuthConfig;
+}
 /**
  * Complete auth plugin configuration (internal)
  */
@@ -63,12 +105,18 @@ interface AuthConfig {
     frontendUrl: string;
     /** Registration mode: 'active' auto-activates, 'pending' requires admin approval (default: 'active') */
     registrationMode: 'active' | 'pending';
+    /** When true, users with emailVerified=false are blocked from logging in (default: false) */
+    requireVerifiedEmail: boolean;
+    /** Cookie path for the refresh token. Scope to the refresh endpoint to limit exposure (default: '/') */
+    refreshCookiePath: string;
     /** Per-account lockout settings */
     lockout: LockoutConfig;
     /** Bcrypt work factor (default: 10) */
     bcryptRounds: number;
     /** Session cookie cache settings */
     session: SessionCookieConfig;
+    /** Resolved external identity-provider configuration. */
+    oauth?: ResolvedOAuthConfig;
 }
 /**
  * Auth plugin configuration options
@@ -84,6 +132,8 @@ interface AuthSchema {
     roles: any;
     permissions: any;
     rolePermissions: any;
+    /** Required when an OAuth provider is enabled. */
+    oauthAccounts?: any;
 }
 type AuthPluginConfig = {
     /**
@@ -112,6 +162,10 @@ type AuthPluginConfig = {
     frontendUrl?: string;
     /** Registration mode: 'active' auto-activates new users, 'pending' requires admin approval (default: 'active') */
     registrationMode?: 'active' | 'pending';
+    /** Block login for users whose email is not verified (default: false) */
+    requireVerifiedEmail?: boolean;
+    /** Cookie path for the refresh token (default: '/'). Set e.g. '/auth' to keep it off unrelated routes. */
+    refreshCookiePath?: string;
     /** Per-account lockout settings */
     lockout?: Partial<LockoutConfig>;
     /** Bcrypt work factor (default: 10, valid range: 4-31) */
@@ -122,8 +176,12 @@ type AuthPluginConfig = {
     validation?: ValidationPluginConfig;
     /** Optional config forwarded to rateLimit() dependency */
     rateLimit?: RateLimitPluginConfig;
+    /** Email transport used by password reset and verification flows. */
+    email?: EmailPluginConfig;
     /** AES-256-GCM key for reversible encryption (e.g. API keys). Falls back to NAJM_ENCRYPTION_KEY env var. */
     encryptionKey?: string;
+    /** External identity providers. */
+    oauth?: OAuthConfig;
 };
 /**
  * JWT payload structure
@@ -199,7 +257,18 @@ var auth = {
 		unauthorized: "Unauthorized access",
 		sessionExpired: "Session has expired",
 		accountLocked: "Account is temporarily locked. Please try again later.",
-		accountInactive: "Account is inactive. Please contact support."
+		accountInactive: "Account is inactive. Please contact support.",
+		emailNotVerified: "Please verify your email address before signing in.",
+		oauthProviderDisabled: "Google sign-in is not configured.",
+		oauthStateInvalid: "The Google sign-in attempt is invalid or expired.",
+		oauthAccessDenied: "Google sign-in was cancelled.",
+		oauthProviderError: "Google sign-in could not be completed.",
+		oauthVerifiedEmailRequired: "Google must provide a verified email address.",
+		oauthAccountLinkRequired: "Sign in with your password and link Google from your account.",
+		oauthProviderAccountLinked: "This Google account is already linked.",
+		oauthSignupDisabled: "Registration with Google is disabled.",
+		oauthHostedDomainDenied: "This Google Workspace domain is not allowed.",
+		oauthLinkSessionExpired: "Your session changed before Google could be linked. Please try again."
 	},
 	success: {
 		login: "Login successful",
@@ -209,7 +278,9 @@ var auth = {
 		passwordResetSent: "If that email exists, a reset link has been sent",
 		passwordReset: "Password has been reset successfully",
 		accountInviteSent: "Invitation sent successfully",
-		tokenRefreshed: "Token refreshed successfully"
+		tokenRefreshed: "Token refreshed successfully",
+		oauthLogin: "Google sign-in successful",
+		oauthLinked: "Google account linked successfully"
 	},
 	emails: {
 		passwordReset: {
@@ -242,7 +313,9 @@ var roles = {
 		notFound: "Role not found",
 		exists: "Role already exists",
 		nameRequired: "Role name is required",
-		cannotDeleteSystem: "Cannot delete system role"
+		cannotDeleteSystem: "Cannot delete system role",
+		cannotRenameSystem: "Cannot rename the system admin role",
+		roleInUse: "Cannot delete a role that is assigned to users"
 	},
 	success: {
 		created: "Role created successfully",
@@ -302,6 +375,17 @@ declare const AUTH_LOCALES: {
                 sessionExpired: string;
                 accountLocked: string;
                 accountInactive: string;
+                emailNotVerified: string;
+                oauthProviderDisabled: string;
+                oauthStateInvalid: string;
+                oauthAccessDenied: string;
+                oauthProviderError: string;
+                oauthVerifiedEmailRequired: string;
+                oauthAccountLinkRequired: string;
+                oauthProviderAccountLinked: string;
+                oauthSignupDisabled: string;
+                oauthHostedDomainDenied: string;
+                oauthLinkSessionExpired: string;
             };
             success: {
                 login: string;
@@ -312,6 +396,8 @@ declare const AUTH_LOCALES: {
                 passwordReset: string;
                 accountInviteSent: string;
                 tokenRefreshed: string;
+                oauthLogin: string;
+                oauthLinked: string;
             };
             emails: {
                 passwordReset: {
@@ -345,6 +431,8 @@ declare const AUTH_LOCALES: {
                 exists: string;
                 nameRequired: string;
                 cannotDeleteSystem: string;
+                cannotRenameSystem: string;
+                roleInUse: string;
             };
             success: {
                 created: string;
@@ -406,6 +494,12 @@ interface SessionCookieData {
     };
     roles: string[];
     permissions: string[];
+    /**
+     * Per-user session version captured when the cookie was written. Lets the
+     * fast-path reader reject a cookie whose session has since been invalidated
+     * (password change/reset, logout-all) without hitting the database.
+     */
+    sessionVersion: number;
     /** Epoch ms when the cookie was written */
     iat: number;
 }
@@ -413,6 +507,7 @@ declare class CookieManager {
     private config;
     private cookieService;
     private get cookieName();
+    private get refreshCookiePath();
     private get sessionCookieName();
     private get sessionMaxAge();
     private get sessionSecret();
@@ -457,6 +552,9 @@ declare class UserRepository {
     getByEmail(email: string): Promise<(User & {
         role?: string | null;
     }) | undefined>;
+    getByEmailInsensitive(email: string): Promise<(User & {
+        role?: string | null;
+    }) | undefined>;
     create(data: NewUser): Promise<User>;
     update(id: string, data: Partial<NewUser>): Promise<User | undefined>;
     updateLastLogin(id: string): Promise<User>;
@@ -565,6 +663,9 @@ declare class RoleRepository {
     db: TDb;
     private schema;
     private get roles();
+    private get users();
+    /** True if any user currently references this role (blocks deletion). */
+    hasUsers(roleId: string): Promise<boolean>;
     getAll(): Promise<RoleEntity[]>;
     getById(id: string): Promise<RoleEntity | undefined>;
     getByName(name: string): Promise<RoleEntity | undefined>;
@@ -625,6 +726,7 @@ declare class RoleValidator {
 declare class RoleService {
     private roleRepository;
     private roleValidator;
+    private t;
     constructor(roleRepository: RoleRepository, roleValidator: RoleValidator);
     getAll(): Promise<{
         id: string;
@@ -654,14 +756,17 @@ declare class RoleService {
         createdAt: string;
         updatedAt: string;
     }>;
-    update(id: any, data: any): Promise<{
+    update(id: string, data: {
+        name?: string;
+        description?: string;
+    }): Promise<{
         id: string;
         name: string;
         description: string;
         createdAt: string;
         updatedAt: string;
     }>;
-    delete(id: any): Promise<{
+    delete(id: string): Promise<{
         id: string;
         name: string;
         description: string;
@@ -709,6 +814,9 @@ declare class UserService {
     findByEmail(email: string): Promise<(User & {
         role?: string | null;
     }) | undefined>;
+    findByEmailInsensitive(email: string): Promise<(User & {
+        role?: string | null;
+    }) | undefined>;
     getAuthRecordById(id: string): Promise<User | undefined>;
     create(data: Record<string, any>): Promise<SanitizedUser>;
     update(id: string, data: Record<string, any>): Promise<SanitizedUser>;
@@ -831,6 +939,12 @@ declare class TokenService {
     getTokenExpire(token: string): number | undefined;
     decodeAccessToken(token: string): JwtPayload | null;
     private signAccessToken;
+    /**
+     * Current per-user session version (0 when never invalidated). The signed
+     * session cookie stamps this so a fast-path reader can reject a cookie whose
+     * session was invalidated after it was written.
+     */
+    getSessionVersion(userId: string): Promise<number>;
     /**
      * Generate access token with unique jti for blacklist support.
      * Includes roles/permissions for client-side RBAC/PBAC.
@@ -855,6 +969,7 @@ declare class TokenService {
         tokenFamily: string;
         roles: string[];
         permissions: string[];
+        sessionVersion: number;
         accessToken: string;
         refreshToken: string;
         accessTokenExpiresAt: number;
@@ -888,6 +1003,7 @@ declare class TokenService {
         tokenFamily: string;
         roles: string[];
         permissions: string[];
+        sessionVersion: number;
         accessToken: string;
         refreshToken: string;
         accessTokenExpiresAt: number;
@@ -995,6 +1111,12 @@ declare const updateUserDto: z.ZodObject<{
         inactive: "inactive";
     }>>>;
 }, z.core.$strip>;
+declare const registerDto: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    email: z.ZodString;
+    password: z.ZodString;
+    image: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
 declare const inviteUserDto: z.ZodObject<{
     name: z.ZodOptional<z.ZodString>;
     email: z.ZodString;
@@ -1038,6 +1160,7 @@ declare const userListQuery: z.ZodObject<{
 }, z.core.$strip>;
 type CreateUserDto = z.infer<typeof createUserDto>;
 type UpdateUserDto = z.infer<typeof updateUserDto>;
+type RegisterDto = z.infer<typeof registerDto>;
 type InviteUserDto = z.infer<typeof inviteUserDto>;
 type UserIdParam = z.infer<typeof userIdParam>;
 type LoginDto = z.infer<typeof loginDto>;
@@ -1050,6 +1173,16 @@ type UserIdInParam = z.infer<typeof userIdInParam>;
 type AssignRoleParams = z.infer<typeof assignRoleParams>;
 type UserListQuery = z.infer<typeof userListQuery>;
 
+declare class AuthSessionService {
+    private tokenService;
+    private userService;
+    private cookieManager;
+    constructor(tokenService: TokenService, userService: UserService, cookieManager: CookieManager);
+    establish(user: SanitizedUser): Promise<TokenPair & {
+        user: SanitizedUser;
+    }>;
+}
+
 /**
  * Identity fields for creating a user behind a person record (parent, student,
  * teacher, staff…). Role can be given by name (`role`) or id (`roleId`).
@@ -1071,16 +1204,17 @@ declare class AuthService {
     private cookieManager;
     private i18nService;
     private emailService;
+    private authSessionService?;
     private config;
     private t;
     private logger;
     private dummyHash?;
-    constructor(tokenService: TokenService, userService: UserService, userValidator: UserValidator, encryptionService: EncryptionService, cookieManager: CookieManager, i18nService: I18nService, emailService: EmailService);
+    constructor(tokenService: TokenService, userService: UserService, userValidator: UserValidator, encryptionService: EncryptionService, cookieManager: CookieManager, i18nService: I18nService, emailService: EmailService, authSessionService?: AuthSessionService);
     private isLockoutActive;
     private nextLockoutUntil;
     private getDummyHash;
     warmupPasswordHash(): Promise<void>;
-    registerUser(body: CreateUserDto): Promise<SanitizedUser>;
+    registerUser(body: RegisterDto): Promise<SanitizedUser>;
     /**
      * Admin-initiated account creation. The user is created with a random,
      * unusable password (the schema requires one) and then emailed a one-time
@@ -1090,7 +1224,9 @@ declare class AuthService {
      * Email is best-effort: a send failure logs a warning but never rolls back
      * account creation (and with the console provider, nothing is actually sent).
      */
-    inviteUser(body: ProvisionUserInput): Promise<SanitizedUser>;
+    inviteUser(body: ProvisionUserInput): Promise<SanitizedUser & {
+        emailSent: boolean;
+    }>;
     /**
      * Create a login for a person record. The branch is intentional and is the
      * single rule callers rely on:
@@ -1147,11 +1283,32 @@ declare class AuthService {
 declare class AuthController {
     private authService;
     constructor(authService: AuthService);
-    registerUser(body: CreateUserDto): Promise<SanitizedUser>;
+    registerUser(body: RegisterDto): Promise<SanitizedUser>;
     loginUser(body: LoginDto): Promise<TokenPair & {
         user: SanitizedUser;
     }>;
-    inviteUser(body: InviteUserDto): Promise<SanitizedUser>;
+    inviteUser(body: InviteUserDto): Promise<Omit<{
+        id: string;
+        name: string;
+        createdAt: string;
+        updatedAt: string;
+        email: string;
+        emailVerified: boolean;
+        phone: string;
+        phoneVerified: boolean;
+        password: string;
+        image: string;
+        status: "active" | "pending" | "inactive";
+        roleId: string;
+        lastLogin: string;
+        failedLoginAttempts: number;
+        lockoutUntil: string;
+    }, "password" | "failedLoginAttempts" | "lockoutUntil"> & {
+        role?: string | null;
+        permissions?: string[];
+    } & {
+        emailSent: boolean;
+    }>;
     refreshTokens(): Promise<TokenPair>;
     logoutUser(userId: string, authorization?: string): Promise<{
         data: any;
@@ -1240,7 +1397,7 @@ interface RunAsUser {
 }
 declare function runAsUser<T>(container: Container, user: RunAsUser, fn: () => Promise<T> | T): Promise<T>;
 
-declare const AUTH_MODULE: readonly [typeof AuthService, typeof CookieManager, typeof EncryptionService, typeof AuthGuard, typeof AuthController, typeof AuthResolver];
+declare const AUTH_MODULE: readonly [typeof AuthService, typeof AuthSessionService, typeof CookieManager, typeof EncryptionService, typeof AuthGuard, typeof AuthController, typeof AuthResolver];
 
 declare class PermissionRepository {
     db: TDb;
@@ -2131,4 +2288,4 @@ declare const authSeed: (config: AuthSeedConfig) => Record<string, SeedEntry>;
  */
 declare function seedAuthData(config: SeedAuthDataConfig): Promise<SeedAuthDataResult>;
 
-export { AUTH_CONFIG, en as AUTH_EN, AUTH_LOCALES, AUTH_MODULE, AUTH_PERMISSIONS, AUTH_ROLE, AUTH_SCHEMA, AUTH_SUPPORTED_LANGUAGES, AUTH_USER, type AssignPermissionDto, type AssignRoleDto, type AssignRoleParams, type AuthConfig, AuthController, AuthGuard, type AuthPluginConfig, AuthQueries, AuthResolver, type AuthSchema, type AuthSeedConfig, AuthService, type AuthUser, 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 DefineRolesOptions, type EmailParam, EncryptionService, type InviteUserDto, type JwtConfig, type JwtPayload, type LanguageParam, type LoginDto, NewPermission, NewRoleEntity, NewUser, Owned, type OwnedMethods, type OwnershipConfig, type OwnershipProvider, type OwnershipRule, OwnershipToken, type OwnershipTokenOptions, Permission, PermissionController, PermissionGuard, type PermissionIdParam, PermissionRepository, PermissionService, PermissionValidator, Policy, type ProvisionUserInput, ROLES, ROLE_GROUPS, type RefreshTokenDto, type ResetPasswordDto, 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, 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, authSeed, avatarsPath, calculateAge, calculateYearsOfExperience, changePasswordDto, checkPermissionDto, clean, configureOwnership, confirmResetPasswordDto, createPermissionDto, createRoleDto, createTokenDto, createUserDto, defineRoles, emailParam, formatDate, getAuthLocale, getAvatarFile, inviteUserDto, isAdmin, isAdministrator, isAuth, isEmpty, isFile, isPath, join, languageParam, loginDto, own, parseSchema, permissionIdParam, pickProps, refreshTokenDto, resetPasswordDto, revokeTokenDto, roleIdParam, runAsUser, seedAuthData, tokenIdParam, updatePermissionDto, updateRoleDto, updateTokenDto, updateUserDto, userIdInParam, userIdParam, userListQuery, verifyTokenDto, where };
+export { AUTH_CONFIG, en as AUTH_EN, AUTH_LOCALES, AUTH_MODULE, AUTH_PERMISSIONS, AUTH_ROLE, AUTH_SCHEMA, AUTH_SUPPORTED_LANGUAGES, AUTH_USER, type AssignPermissionDto, type AssignRoleDto, type AssignRoleParams, type AuthConfig, AuthController, AuthGuard, type AuthPluginConfig, AuthQueries, AuthResolver, type AuthSchema, type AuthSeedConfig, AuthService, AuthSessionService, type AuthUser, 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 DefineRolesOptions, type EmailParam, EncryptionService, type GoogleOAuthConfig, type InviteUserDto, type JwtConfig, type JwtPayload, type LanguageParam, type LoginDto, NewPermission, NewRoleEntity, NewUser, type OAuthConfig, type OAuthProvider, Owned, type OwnedMethods, type OwnershipConfig, type OwnershipProvider, type OwnershipRule, OwnershipToken, type OwnershipTokenOptions, Permission, PermissionController, PermissionGuard, type PermissionIdParam, PermissionRepository, PermissionService, PermissionValidator, Policy, type ProvisionUserInput, ROLES, ROLE_GROUPS, type RefreshTokenDto, type RegisterDto, type ResetPasswordDto, 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, 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, authSeed, avatarsPath, calculateAge, calculateYearsOfExperience, changePasswordDto, checkPermissionDto, clean, configureOwnership, confirmResetPasswordDto, createPermissionDto, createRoleDto, createTokenDto, createUserDto, defineRoles, emailParam, formatDate, getAuthLocale, getAvatarFile, inviteUserDto, isAdmin, isAdministrator, isAuth, isEmpty, isFile, isPath, join, languageParam, loginDto, own, parseSchema, permissionIdParam, pickProps, refreshTokenDto, registerDto, resetPasswordDto, revokeTokenDto, roleIdParam, runAsUser, seedAuthData, tokenIdParam, updatePermissionDto, updateRoleDto, updateTokenDto, updateUserDto, userIdInParam, userIdParam, userListQuery, verifyTokenDto, where };