najm-auth 4.0.6 → 4.0.8

package/dist/index.d.ts

@@ -1227,7 +1227,15 @@ declare class UserService {
     create(data: Record<string, any>, options?: {
         validatePasswordStrength?: boolean;
     }): Promise<SanitizedUser>;
-    update(id: string, data: Record<string, any>): Promise<SanitizedUser>;
+    /**
+     * `options.validatePasswordStrength: false` is for a system-issued temporary
+     * credential the user is durably required to replace — the same opt-out
+     * `create()` already offers provisioning. A user-chosen password never takes
+     * it.
+     */
+    update(id: string, data: Record<string, any>, options?: {
+        validatePasswordStrength?: boolean;
+    }): Promise<SanitizedUser>;
     delete(id: string): Promise<SanitizedUser>;
     deleteAll(): Promise<SanitizedUser[]>;
     getRoleName(id: string): Promise<string | null>;
@@ -1263,6 +1271,16 @@ interface ConsumedSetPasswordToken {
     userId: string;
     type: SetPasswordTokenType;
 }
+/**
+ * A freshly minted one-time set-password token. `jti` identifies this exact
+ * token so a caller that fails to deliver it can discard it again without
+ * touching a newer one.
+ */
+interface SetPasswordToken {
+    token: string;
+    userId: string;
+    jti: string;
+}
 declare class TokenService {
     private tokenRepository;
     private cookieManager;
@@ -1481,19 +1499,24 @@ declare class TokenService {
      * Generate secure password reset token
      * Returns both the plain token (to send via email) and userId for identification
      */
-    generateResetToken(userId: string): Promise<{
-        token: string;
-        userId: string;
-    }>;
+    generateResetToken(userId: string): Promise<SetPasswordToken>;
     /**
      * Generate secure account-invite token.
      * Longer expiry (3d) than reset because an invited user may not check
      * their email immediately. Consumed via the same reset-password endpoint.
      */
-    generateInviteToken(userId: string): Promise<{
-        token: string;
-        userId: string;
-    }>;
+    generateInviteToken(userId: string): Promise<SetPasswordToken>;
+    /**
+     * Discard a set-password token this process just minted, identified by the
+     * `jti` its generator returned. For the caller whose email send failed:
+     * minting already superseded any earlier link for that user, so leaving the
+     * fresh one live would keep a link alive that nobody received.
+     *
+     * Compare-and-delete, never a blind delete — a newer link minted in the
+     * meantime must survive a late failure from an older send. Returns whether
+     * this exact token was still the live one.
+     */
+    discardSetPasswordToken(userId: string, jti: string): Promise<boolean>;
     /**
      * Verify and CONSUME a password reset or invite token.
      *
@@ -1782,6 +1805,27 @@ type ProvisionUserWithPasswordInput = ProvisionUserInput & {
     temporaryCredential?: never;
     requireCredentialSetup?: never;
 };
+/** Outcome of an administrative reset to a system-issued temporary credential. */
+type TemporaryCredentialReset = {
+    userId: string;
+    purpose: typeof PASSWORD_SETUP_PURPOSE;
+    temporaryCredentialKind: string;
+};
+/**
+ * Outcome of an administrative mail-out. `emailSent` is what the provider
+ * actually reported — never an assumption that sending succeeded.
+ *
+ * `undeliveredLinkLive` is the one case a caller cannot infer: the mail did not
+ * leave AND the link minted for it could not be taken out of circulation, so a
+ * usable link exists that no one received. It is false whenever the mail left
+ * — that link is live on purpose — and false when an undelivered one was
+ * successfully discarded.
+ */
+type AdministrativeDelivery = {
+    userId: string;
+    emailSent: boolean;
+    undeliveredLinkLive: boolean;
+};
 /** Login answer: either a complete session, or a pending credential setup. */
 type LoginResult = (TokenPair & {
     nextStep: 'authenticated';
@@ -1820,6 +1864,14 @@ declare class AuthService {
     inviteUser(body: ProvisionUserInput): Promise<SanitizedUser & {
         emailSent: boolean;
     }>;
+    /**
+     * Mint an invite token and send the activation mail. Shared by first-time
+     * invitation and re-invitation, so both rest on one token contract and one
+     * template and neither can drift into an ad hoc message.
+     *
+     * Nothing here logs the token, the link, the message body, or the recipient.
+     */
+    private deliverInvitation;
     /**
      * Create a login for a person record. The branch is intentional and is the
      * single rule callers rely on:
@@ -1910,6 +1962,62 @@ declare class AuthService {
     resetPassword(token: string, newPassword: string): Promise<{
         message: string;
     }>;
+    /**
+     * Replace an existing account's stored credential with a system-issued
+     * temporary one and durably require the holder to replace it at their next
+     * login.
+     *
+     * The hash write and the durable requirement commit together, so no failure
+     * can leave the temporary credential accepted with nothing forcing its
+     * replacement, nor the requirement standing over an unchanged password.
+     * Session revocation runs inside that same transaction: a cache or session
+     * failure rolls the credential back rather than reporting a reset that a
+     * still-live browser could sail past. No session is issued.
+     *
+     * Strength validation is deliberately skipped — the value is issued by the
+     * system, not chosen by the user — but bcrypt's 72-byte boundary is not.
+     */
+    resetToTemporaryCredential(userId: string, credential: TemporaryCredentialInput): Promise<TemporaryCredentialReset>;
+    /**
+     * Send one password-reset link to an account selected by id. The recipient is
+     * read from that account at command time, so neither an administrator nor a
+     * stale client can redirect the link by supplying an address.
+     *
+     * Delivery is reported truthfully: unlike `forgotPassword` there is no email
+     * enumeration to protect against, because the caller already knows the
+     * account exists. Account status and email verification are left exactly as
+     * they were, and requesting the link does not end the user's current session
+     * — `resetPassword` revokes it when the new password is actually saved.
+     *
+     * Minting supersedes any earlier link for this user. A failed send discards
+     * the fresh token too, so a failure never leaves a live link nobody received.
+     */
+    sendPasswordReset(userId: string): Promise<AdministrativeDelivery>;
+    /**
+     * Re-send the activation link for an account that is still pending.
+     *
+     * It creates no second user and no second profile — that is the whole reason
+     * it exists beside `inviteUser`, which does create one. Only a `pending`
+     * account qualifies: an active or inactive account is reset or reactivated,
+     * never re-invited. Whether a given pending account is genuinely an invited
+     * one rather than an application awaiting a decision is the caller's to
+     * decide; this package cannot see an application.
+     */
+    resendInvitation(userId: string): Promise<AdministrativeDelivery>;
+    /**
+     * Take a link that was minted but never delivered out of circulation, and
+     * answer whether it is really gone.
+     *
+     * A `false` from the store is not a failure: compare-and-delete only refuses
+     * when the stored jti is no longer this one, which means a newer mint already
+     * superseded this link and it can no longer be consumed either way. A throw
+     * is the failure — the store was unreachable, the jti it holds is still ours,
+     * and a usable link now exists that nobody received. That does not change
+     * what the caller is told about delivery, but it must not be swallowed: it is
+     * logged as an error and reported up, so the result stays truthful about more
+     * than the mail.
+     */
+    private discardUndeliveredToken;
 }
 
 /**
@@ -3073,4 +3181,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, 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 };
+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 AdministrativeDelivery, 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 SetPasswordToken, type SetPasswordTokenType, TOKEN_STATUS, TOKEN_TYPE, TemporaryCredentialInput, type TemporaryCredentialReset, 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

@@ -1916,12 +1916,22 @@ var UserService = class UserService2 {
     const newUser = await this.userRepository.create(userDetails);
     return this.sanitizeUser(newUser);
   }
-  async update(id, data) {
+  /**
+   * `options.validatePasswordStrength: false` is for a system-issued temporary
+   * credential the user is durably required to replace — the same opt-out
+   * `create()` already offers provisioning. A user-chosen password never takes
+   * it.
+   */
+  async update(id, data, options = {}) {
     const { password, image } = data;
     await this.userValidator.checkEmailUnique(data.email, id);
     let hashedPassword;
     if (password) {
-      this.userValidator.validatePasswordStrength(password);
+      if (options.validatePasswordStrength === false) {
+        this.userValidator.validatePasswordLength(password);
+      } else {
+        this.userValidator.validatePasswordStrength(password);
+      }
       hashedPassword = await this.encryptionService.hashPassword(password);
     }
     const updateData = {
@@ -2711,7 +2721,7 @@ var TokenService = class TokenService2 {
       expiresIn
     });
     await this.cache.set(`${this.resetTokenPrefix}${userId}`, jti, timestring3(expiresIn, "ms"));
-    return { token, userId };
+    return { token, userId, jti };
   }
   /**
    * Generate secure password reset token
@@ -2728,6 +2738,23 @@ var TokenService = class TokenService2 {
   async generateInviteToken(userId) {
     return this.generateSetPasswordToken(userId, "invite", "3d");
   }
+  /**
+   * Discard a set-password token this process just minted, identified by the
+   * `jti` its generator returned. For the caller whose email send failed:
+   * minting already superseded any earlier link for that user, so leaving the
+   * fresh one live would keep a link alive that nobody received.
+   *
+   * Compare-and-delete, never a blind delete — a newer link minted in the
+   * meantime must survive a late failure from an older send. Returns whether
+   * this exact token was still the live one.
+   */
+  async discardSetPasswordToken(userId, jti) {
+    const consume = this.cache.compareAndDelete;
+    if (typeof consume !== "function") {
+      Err7.invalidOperation("Discarding a set-password token requires a cache with atomic compare-and-delete");
+    }
+    return consume.call(this.cache, `${this.resetTokenPrefix}${userId}`, jti);
+  }
   /**
    * Verify and CONSUME a password reset or invite token.
    *
@@ -3444,6 +3471,7 @@ var _h2;
 var _j2;
 var _k;
 var _l;
+var _m;
 var AuthService = class AuthService2 {
   static {
     __name(this, "AuthService");
@@ -3522,16 +3550,27 @@ var AuthService = class AuthService2 {
       status: body.status ?? "active",
       emailVerified: false
     });
-    const { token } = await this.tokenService.generateInviteToken(user.id);
+    const { emailSent } = await this.deliverInvitation(user.id, body.email, user.name, body.role);
+    return { ...user, emailSent };
+  }
+  /**
+   * Mint an invite token and send the activation mail. Shared by first-time
+   * invitation and re-invitation, so both rest on one token contract and one
+   * template and neither can drift into an ad hoc message.
+   *
+   * Nothing here logs the token, the link, the message body, or the recipient.
+   */
+  async deliverInvitation(userId, email2, userName, role) {
+    const { token, jti } = await this.tokenService.generateInviteToken(userId);
     const inviteLink = `${this.config.frontendUrl}/reset-password?token=${token}`;
-    const accountType = body.role?.trim().toLowerCase();
+    const accountType = role?.trim().toLowerCase() || void 0;
     const accountLabel = accountType ? `${accountType} account` : "account";
     let emailSent = false;
     try {
       const logo = this.config.accountInviteLogo;
       const logoCid = logo ? "najm-account-invite-logo" : void 0;
       const result = await this.emailService.send({
-        to: body.email,
+        to: email2,
         subject: this.t("emails.accountInvite.subject", {
           accountLabel,
           appName: this.config.appName
@@ -3542,7 +3581,7 @@ var AuthService = class AuthService2 {
           inviteLink,
           logoAlt: logo?.alt,
           logoSrc: logoCid ? `cid:${logoCid}` : void 0,
-          userName: user.name || body.email
+          userName: userName || email2
         }),
         attachments: logo ? [{
           filename: logo.filename,
@@ -3555,9 +3594,9 @@ var AuthService = class AuthService2 {
       });
       emailSent = result.success;
     } catch (error) {
-      this.logger.warn("Account invite email failed", { email: body.email, error });
+      this.logger.warn("Account invite email failed", { userId, error });
     }
-    return { ...user, emailSent };
+    return { emailSent, jti };
   }
   /**
    * Create a login for a person record. The branch is intentional and is the
@@ -3904,6 +3943,135 @@ var AuthService = class AuthService2 {
     this.cookieManager.clearSessionCookie();
     return { message: this.t("success.passwordReset") };
   }
+  // ==========================================================================
+  // Administrative recovery for an account that already exists
+  //
+  // Three operations an application's own admin surface composes. Each is
+  // bound to a user id, never to a submitted email; none creates a user,
+  // issues a session, or returns a credential, token, or link. Who may call
+  // them, which targets are eligible, how often, and what is audited belong to
+  // the application — this package owns only the credential, token, and
+  // session mechanics underneath.
+  // ==========================================================================
+  /**
+   * Replace an existing account's stored credential with a system-issued
+   * temporary one and durably require the holder to replace it at their next
+   * login.
+   *
+   * The hash write and the durable requirement commit together, so no failure
+   * can leave the temporary credential accepted with nothing forcing its
+   * replacement, nor the requirement standing over an unchanged password.
+   * Session revocation runs inside that same transaction: a cache or session
+   * failure rolls the credential back rather than reporting a reset that a
+   * still-live browser could sail past. No session is issued.
+   *
+   * Strength validation is deliberately skipped — the value is issued by the
+   * system, not chosen by the user — but bcrypt's 72-byte boundary is not.
+   */
+  async resetToTemporaryCredential(userId, credential) {
+    if (!this.credentialSetupRequirements) {
+      Err12.invalidOperation("Credential setup is unavailable: CredentialSetupRequirementService is not registered");
+    }
+    const user = await this.userService.getById(userId);
+    const temporary = toTemporaryCredential(credential);
+    const kind = resolveTemporaryCredentialKind(temporary.kind);
+    if (kind.isTemporaryShape && !kind.isTemporaryShape(temporary.value)) {
+      Err12(`Invalid temporary credential for kind '${kind.name}'`, 400);
+    }
+    const password = kind.normalize(temporary.value);
+    if (!password?.trim()) {
+      Err12("resetToTemporaryCredential requires a non-empty temporaryCredential", 400);
+    }
+    await this.userService.update(user.id, { password }, { validatePasswordStrength: false });
+    await this.credentialSetupRequirements.markRequired(user.id, PASSWORD_SETUP_PURPOSE, {
+      temporaryCredentialKind: kind.name
+    });
+    return {
+      userId: user.id,
+      purpose: PASSWORD_SETUP_PURPOSE,
+      temporaryCredentialKind: kind.name
+    };
+  }
+  /**
+   * Send one password-reset link to an account selected by id. The recipient is
+   * read from that account at command time, so neither an administrator nor a
+   * stale client can redirect the link by supplying an address.
+   *
+   * Delivery is reported truthfully: unlike `forgotPassword` there is no email
+   * enumeration to protect against, because the caller already knows the
+   * account exists. Account status and email verification are left exactly as
+   * they were, and requesting the link does not end the user's current session
+   * — `resetPassword` revokes it when the new password is actually saved.
+   *
+   * Minting supersedes any earlier link for this user. A failed send discards
+   * the fresh token too, so a failure never leaves a live link nobody received.
+   */
+  async sendPasswordReset(userId) {
+    const user = await this.userService.getById(userId);
+    const email2 = typeof user.email === "string" ? user.email.trim() : "";
+    if (!email2) {
+      Err12("This account has no email address to send a password reset to", 409);
+    }
+    const { token, jti } = await this.tokenService.generateResetToken(user.id);
+    const resetLink = `${this.config.frontendUrl}/reset-password?token=${token}`;
+    let emailSent = false;
+    try {
+      const result = await this.emailService.sendHtml(email2, this.t("emails.passwordReset.subject"), passwordResetTemplate({
+        resetLink,
+        userName: user.name || email2
+      }));
+      emailSent = result.success;
+    } catch (error) {
+      this.logger.warn("Administrative password reset email failed", { userId: user.id, error });
+    }
+    const undeliveredLinkLive = emailSent ? false : !await this.discardUndeliveredToken(user.id, jti);
+    return { userId: user.id, emailSent, undeliveredLinkLive };
+  }
+  /**
+   * Re-send the activation link for an account that is still pending.
+   *
+   * It creates no second user and no second profile — that is the whole reason
+   * it exists beside `inviteUser`, which does create one. Only a `pending`
+   * account qualifies: an active or inactive account is reset or reactivated,
+   * never re-invited. Whether a given pending account is genuinely an invited
+   * one rather than an application awaiting a decision is the caller's to
+   * decide; this package cannot see an application.
+   */
+  async resendInvitation(userId) {
+    const user = await this.userService.getById(userId);
+    if (user.status !== "pending") {
+      Err12("Only a pending account can be re-invited", 409);
+    }
+    const email2 = typeof user.email === "string" ? user.email.trim() : "";
+    if (!email2) {
+      Err12("This account has no email address to send an invitation to", 409);
+    }
+    const { emailSent, jti } = await this.deliverInvitation(user.id, email2, user.name, user.role);
+    const undeliveredLinkLive = emailSent ? false : !await this.discardUndeliveredToken(user.id, jti);
+    return { userId: user.id, emailSent, undeliveredLinkLive };
+  }
+  /**
+   * Take a link that was minted but never delivered out of circulation, and
+   * answer whether it is really gone.
+   *
+   * A `false` from the store is not a failure: compare-and-delete only refuses
+   * when the stored jti is no longer this one, which means a newer mint already
+   * superseded this link and it can no longer be consumed either way. A throw
+   * is the failure — the store was unreachable, the jti it holds is still ours,
+   * and a usable link now exists that nobody received. That does not change
+   * what the caller is told about delivery, but it must not be swallowed: it is
+   * logged as an error and reported up, so the result stays truthful about more
+   * than the mail.
+   */
+  async discardUndeliveredToken(userId, jti) {
+    try {
+      await this.tokenService.discardSetPasswordToken(userId, jti);
+      return true;
+    } catch (error) {
+      this.logger.error("Undelivered set-password token is still live", { userId, error });
+      return false;
+    }
+  }
 };
 __decorate18([
   Inject12(AUTH_CONFIG),
@@ -3923,6 +4091,12 @@ __decorate18([
   __metadata18("design:paramtypes", [Object]),
   __metadata18("design:returntype", typeof (_l = typeof Promise !== "undefined" && Promise) === "function" ? _l : Object)
 ], AuthService.prototype, "provisionWithCredentialSetup", null);
+__decorate18([
+  Transaction4(),
+  __metadata18("design:type", Function),
+  __metadata18("design:paramtypes", [String, Object]),
+  __metadata18("design:returntype", typeof (_m = typeof Promise !== "undefined" && Promise) === "function" ? _m : Object)
+], AuthService.prototype, "resetToTemporaryCredential", null);
 AuthService = __decorate18([
   Injectable12(),
   __metadata18("design:paramtypes", [typeof (_a12 = typeof TokenService !== "undefined" && TokenService) === "function" ? _a12 : Object, typeof (_b10 = typeof UserService !== "undefined" && UserService) === "function" ? _b10 : Object, typeof (_c7 = typeof UserValidator !== "undefined" && UserValidator) === "function" ? _c7 : Object, typeof (_d6 = typeof EncryptionService !== "undefined" && EncryptionService) === "function" ? _d6 : Object, typeof (_e5 = typeof CookieManager !== "undefined" && CookieManager) === "function" ? _e5 : Object, typeof (_f4 = typeof I18nService2 !== "undefined" && I18nService2) === "function" ? _f4 : Object, typeof (_g3 = typeof EmailService !== "undefined" && EmailService) === "function" ? _g3 : Object, typeof (_h2 = typeof AuthSessionService !== "undefined" && AuthSessionService) === "function" ? _h2 : Object, typeof (_j2 = typeof CredentialSetupRequirementService !== "undefined" && CredentialSetupRequirementService) === "function" ? _j2 : Object, typeof (_k = typeof PasswordSetupService !== "undefined" && PasswordSetupService) === "function" ? _k : Object])

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "najm-auth",
-  "version": "4.0.6",
+  "version": "4.0.8",
   "description": "Authentication and authorization library for najm framework",
   "type": "module",
   "files": [