najm-auth 4.0.0 → 4.0.2

package/README.md

@@ -138,8 +138,9 @@ auth({
   publicRegistration?: boolean             // Default: true; mounts POST /auth/register
   bcryptRounds?: number                    // Default: 10 (valid: 4-31)
 
-  // Frontend
-  frontendUrl?: string                     // Password reset link base URL
+  // Frontend
+  frontendUrl?: string                     // Password reset link base URL
+  appName?: string                         // Security email brand (default: 'Your app')
 
   // Login identifier normalization (see "Identity presets")
   identity?: {
@@ -1119,15 +1120,28 @@ errors cannot change the authentication result.
 ### Password Reset 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.
+cache with the same expiry. `consumeSetPasswordToken()` atomically compares and
+deletes that value while preserving whether the token was a reset or invite;
+the backward-compatible `verifyResetToken()` returns only the user id. Exactly
+one concurrent caller can consume a link, and a stale link cannot delete the
+value for a newer one.
 
 `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.
 
+Accepting an account invitation also marks the destination email verified and
+activates the account when its status is `pending`. An ordinary password reset
+changes neither verification nor lifecycle status, and an explicitly inactive
+invited account remains inactive.
+
+Set `appName` on `auth()` to brand the invitation subject and email card. The
+provisioned role is presented as the account type, so a sponsor invitation can
+say “Activate your sponsor account” without application-owned HTML. The shared
+template uses inline critical styles for Gmail and keeps the raw token URL out
+of visible fallback copy.
+
 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

package/dist/index.d.ts

@@ -198,6 +198,8 @@ interface AuthConfig {
     defaultRole: string | null;
     /** Frontend URL for password reset links (default: 'http://localhost:3000') */
     frontendUrl: string;
+    /** Product name used in security email subjects and templates. */
+    appName: string;
     /** Registration mode: 'active' auto-activates, 'pending' requires admin approval (default: 'active') */
     registrationMode: 'active' | 'pending';
     /** Whether the unauthenticated POST /auth/register route is mounted. */
@@ -265,6 +267,8 @@ type AuthPluginConfig = {
     defaultRole?: string | null;
     /** Frontend URL for password reset links. Falls back to FRONTEND_URL env var, then 'http://localhost:3000' */
     frontendUrl?: string;
+    /** Product name used in account invitation emails (default: 'Your app'). */
+    appName?: string;
     /** Registration mode: 'active' auto-activates new users, 'pending' requires admin approval (default: 'active') */
     registrationMode?: 'active' | 'pending';
     /**
@@ -432,7 +436,7 @@ var auth = {
 			subject: "Reset your password"
 		},
 		accountInvite: {
-			subject: "You've been invited — set up your account"
+			subject: "{{appName}}: activate your {{accountLabel}}"
 		}
 	}
 };
@@ -1233,6 +1237,11 @@ declare class CredentialSetupRequirementRepository {
     complete(userId: string, purpose: string): Promise<CredentialSetupRequirementRow | undefined>;
 }
 
+type SetPasswordTokenType = 'reset' | 'invite';
+interface ConsumedSetPasswordToken {
+    userId: string;
+    type: SetPasswordTokenType;
+}
 declare class TokenService {
     private tokenRepository;
     private cookieManager;
@@ -1480,6 +1489,12 @@ declare class TokenService {
      * request that then failed validation would cost the user their link for
      * nothing.
      */
+    consumeSetPasswordToken(token: string): Promise<ConsumedSetPasswordToken>;
+    /**
+     * Backward-compatible user-id-only reset/invite token consumption.
+     * Prefer `consumeSetPasswordToken()` when the caller must distinguish an
+     * account invitation from an ordinary password reset.
+     */
     verifyResetToken(token: string): Promise<string>;
     private getUserSessionVersion;
 }
@@ -3037,4 +3052,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 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, SessionInvalidationService, 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, authEmailRateLimitKey, 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, type ConsumedSetPasswordToken, 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, SessionInvalidationService, type SetPasswordTokenType, 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, authEmailRateLimitKey, 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 };

package/dist/index.js

@@ -2708,7 +2708,7 @@ var TokenService = class TokenService2 {
    * request that then failed validation would cost the user their link for
    * nothing.
    */
-  async verifyResetToken(token) {
+  async consumeSetPasswordToken(token) {
     let decoded;
     try {
       decoded = jwt.verify(token, this.config.jwt.refreshSecret);
@@ -2726,7 +2726,18 @@ var TokenService = class TokenService2 {
     if (!await consume.call(this.cache, key, decoded.jti)) {
       Err7(this.t("errors.invalidResetToken"));
     }
-    return decoded.userId;
+    return {
+      userId: decoded.userId,
+      type: decoded.type
+    };
+  }
+  /**
+   * Backward-compatible user-id-only reset/invite token consumption.
+   * Prefer `consumeSetPasswordToken()` when the caller must distinguish an
+   * account invitation from an ordinary password reset.
+   */
+  async verifyResetToken(token) {
+    return (await this.consumeSetPasswordToken(token)).userId;
   }
   async getUserSessionVersion(userId) {
     return this.invalidation.getSessionVersion(userId);
@@ -3477,9 +3488,16 @@ var AuthService = class AuthService2 {
     });
     const { token } = await this.tokenService.generateInviteToken(user.id);
     const inviteLink = `${this.config.frontendUrl}/reset-password?token=${token}`;
+    const accountType = body.role?.trim().toLowerCase();
+    const accountLabel = accountType ? `${accountType} account` : "account";
     let emailSent = false;
     try {
-      await this.emailService.sendHtml(body.email, this.t("emails.accountInvite.subject"), accountInviteTemplate({
+      await this.emailService.sendHtml(body.email, this.t("emails.accountInvite.subject", {
+        accountLabel,
+        appName: this.config.appName
+      }), accountInviteTemplate({
+        accountType,
+        appName: this.config.appName,
         inviteLink,
         userName: user.name || body.email
       }));
@@ -3818,10 +3836,18 @@ var AuthService = class AuthService2 {
   }
   async resetPassword(token, newPassword) {
     this.userValidator.validatePasswordStrength(newPassword);
-    const userId = await this.tokenService.verifyResetToken(token);
-    await this.userService.update(userId, { password: newPassword });
-    await this.tokenService.invalidateUserAccessTokens(userId);
-    await this.tokenService.revokeAllForUser(userId);
+    const consumed = await this.tokenService.consumeSetPasswordToken(token);
+    const user = await this.userService.getById(consumed.userId);
+    const acceptsInvitation = consumed.type === "invite";
+    await this.userService.update(consumed.userId, {
+      password: newPassword,
+      ...acceptsInvitation ? {
+        emailVerified: true,
+        ...user.status === "pending" ? { status: "active" } : {}
+      } : {}
+    });
+    await this.tokenService.invalidateUserAccessTokens(consumed.userId);
+    await this.tokenService.revokeAllForUser(consumed.userId);
     this.cookieManager.clearRefreshToken();
     this.cookieManager.clearSessionCookie();
     return { message: this.t("success.passwordReset") };
@@ -6327,7 +6353,7 @@ var en_default = {
         subject: "Reset your password"
       },
       accountInvite: {
-        subject: "You've been invited \u2014 set up your account"
+        subject: "{{appName}}: activate your {{accountLabel}}"
       }
     }
   },
@@ -7459,6 +7485,13 @@ var validateCallbackUrl = /* @__PURE__ */ __name((value, name) => {
   }
   return callback.toString();
 }, "validateCallbackUrl");
+var resolveAppName = /* @__PURE__ */ __name((value) => {
+  const appName = value?.trim() || "Your app";
+  if (appName.length > 80 || /[\u0000-\u001f\u007f]/.test(appName)) {
+    throw new Error("auth.appName must be at most 80 characters without control characters");
+  }
+  return appName;
+}, "resolveAppName");
 var resolveGoogleConfig = /* @__PURE__ */ __name((config) => {
   const configuredGoogle = config?.oauth?.google;
   if (!configuredGoogle)
@@ -7535,6 +7568,7 @@ var resolveAuthConfig = /* @__PURE__ */ __name((config) => {
     blacklistPrefix: config?.blacklistPrefix ?? "auth:blacklist:",
     defaultRole: config?.defaultRole ?? null,
     frontendUrl: config?.frontendUrl ?? process.env.FRONTEND_URL ?? "http://localhost:3000",
+    appName: resolveAppName(config?.appName),
     registrationMode: config?.registrationMode ?? "active",
     publicRegistration: config?.publicRegistration ?? true,
     requireVerifiedEmail: config?.requireVerifiedEmail ?? false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "najm-auth",
-  "version": "4.0.0",
+  "version": "4.0.2",
   "description": "Authentication and authorization library for najm framework",
   "type": "module",
   "files": [
@@ -97,7 +97,7 @@
     "najm-guard": "^2.0.2",
     "najm-i18n": "^2.1.2",
     "najm-cache": "^2.2.0",
-    "najm-email": "^2.0.3",
+    "najm-email": "^2.0.4",
     "najm-rate": "^2.1.1",
     "najm-validation": "^2.0.2",
     "jsonwebtoken": "^9.0.3",