@aranzatech/aranza-auth 0.2.0 → 0.2.2

package/dist/index.js

@@ -1,13 +1,14 @@
 import { __decorateClass, __decorateParam, AUTH_MODULE_OPTIONS, AUTH_REPOSITORY, AUTH_HOOKS, normalizeIdentifier, resolveRegisterIdentifier, readAccountIdentifier } from './chunk-QNEFN5ES.js';
 export { AUTH_HOOKS, AUTH_MODULE_OPTIONS, AUTH_REPOSITORY } from './chunk-QNEFN5ES.js';
-import { createParamDecorator, UnauthorizedException, Injectable, Inject, Post, Body, HttpCode, HttpStatus, UseGuards, Get, Controller, Module, BadRequestException, NotFoundException } from '@nestjs/common';
-import { ModuleRef } from '@nestjs/core';
+import { ApiProperty, ApiPropertyOptional, ApiOperation, ApiResponse, ApiBearerAuth, ApiTags, ApiUnauthorizedResponse, DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
+import { IsString, IsNotEmpty, Length, IsEmail, IsOptional, ValidateIf, Matches } from 'class-validator';
+import { createParamDecorator, UnauthorizedException, Injectable, Inject, Post, Body, HttpCode, HttpStatus, UseGuards, Get, Module, BadRequestException, NotFoundException, applyDecorators, Controller } from '@nestjs/common';
 import { JwtService, JwtModule } from '@nestjs/jwt';
 import { AuthGuard, PassportStrategy, PassportModule } from '@nestjs/passport';
-import * as bcrypt2 from 'bcryptjs';
-import { createHash, randomBytes } from 'crypto';
+import * as bcrypt from 'bcryptjs';
+import { createHmac, timingSafeEqual, createHash, randomBytes, randomUUID } from 'crypto';
 import { Strategy, ExtractJwt } from 'passport-jwt';
-import { IsString, IsNotEmpty, Length, IsEmail, IsOptional, ValidateIf, Matches } from 'class-validator';
+import { ModuleRef } from '@nestjs/core';
 
 // src/constants/rate-limit.presets.ts
 var AUTH_RATE_LIMIT_PRESETS = {
@@ -19,18 +20,258 @@ var AUTH_RATE_LIMIT_PRESETS = {
   passwordReset: { name: "auth-password-reset", ttl: 6e4, limit: 3 }
 };
 
+// src/constants/rate-limit.routes.ts
+var AUTH_RATE_LIMIT_ROUTES = {
+  login: AUTH_RATE_LIMIT_PRESETS.credentials,
+  register: AUTH_RATE_LIMIT_PRESETS.credentials,
+  refresh: AUTH_RATE_LIMIT_PRESETS.credentials,
+  "forgot-password": AUTH_RATE_LIMIT_PRESETS.passwordReset,
+  "reset-password": AUTH_RATE_LIMIT_PRESETS.passwordReset,
+  "resend-verification": AUTH_RATE_LIMIT_PRESETS.passwordReset,
+  default: AUTH_RATE_LIMIT_PRESETS.default
+};
+
 // src/constants/auth-errors.ts
 var AuthErrorCode = {
-  INVALID_CREDENTIALS: "Invalid credentials",
-  INVALID_REFRESH_TOKEN: "Invalid refresh token",
+  INVALID_CREDENTIALS: "INVALID_CREDENTIALS",
+  INVALID_REFRESH_TOKEN: "INVALID_REFRESH_TOKEN",
   REFRESH_TOKEN_REUSE: "REFRESH_TOKEN_REUSE",
   ACCOUNT_DISABLED: "ACCOUNT_DISABLED",
+  ACCOUNT_NOT_FOUND: "ACCOUNT_NOT_FOUND",
   EMAIL_NOT_VERIFIED: "EMAIL_NOT_VERIFIED",
   TOKEN_INVALID_OR_EXPIRED: "TOKEN_INVALID_OR_EXPIRED",
   ACCOUNT_LOCKED: "ACCOUNT_LOCKED",
   INVALID_CURRENT_PASSWORD: "INVALID_CURRENT_PASSWORD",
-  PASSWORD_UNCHANGED: "PASSWORD_UNCHANGED"
+  PASSWORD_UNCHANGED: "PASSWORD_UNCHANGED",
+  PASSWORD_CHANGED: "PASSWORD_CHANGED",
+  /** Missing or invalid Bearer token on a protected route. */
+  UNAUTHORIZED: "UNAUTHORIZED"
+};
+var AuthTokensDto = class {
+};
+__decorateClass([
+  ApiProperty({ example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." })
+], AuthTokensDto.prototype, "accessToken", 2);
+__decorateClass([
+  ApiProperty({ example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." })
+], AuthTokensDto.prototype, "refreshToken", 2);
+var ChangePasswordDto = class {
+};
+__decorateClass([
+  ApiProperty({ example: "CurrentPassword1", minLength: 1, maxLength: 128 }),
+  IsString(),
+  IsNotEmpty(),
+  Length(1, 128)
+], ChangePasswordDto.prototype, "currentPassword", 2);
+__decorateClass([
+  ApiProperty({ example: "NewPassword1", minLength: 8, maxLength: 128 }),
+  IsString(),
+  IsNotEmpty(),
+  Length(8, 128)
+], ChangePasswordDto.prototype, "newPassword", 2);
+var ForgotPasswordDto = class {
+};
+__decorateClass([
+  ApiProperty({ example: "user@example.com" }),
+  IsEmail()
+], ForgotPasswordDto.prototype, "email", 2);
+var LoginDto = class {
+};
+__decorateClass([
+  ApiPropertyOptional({ example: "user@example.com" }),
+  IsOptional(),
+  ValidateIf((dto) => dto.email != null && dto.email.trim() !== ""),
+  IsEmail(),
+  Length(3, 255)
+], LoginDto.prototype, "email", 2);
+__decorateClass([
+  ApiPropertyOptional({ example: "johndoe" }),
+  IsOptional(),
+  IsString(),
+  Length(3, 50)
+], LoginDto.prototype, "username", 2);
+__decorateClass([
+  ApiProperty({ example: "Password1", minLength: 8, maxLength: 128 }),
+  IsString(),
+  IsNotEmpty(),
+  Length(8, 128)
+], LoginDto.prototype, "password", 2);
+var MeResponseDto = class {
+};
+__decorateClass([
+  ApiProperty({ example: "507f1f77bcf86cd799439011" })
+], MeResponseDto.prototype, "id", 2);
+__decorateClass([
+  ApiPropertyOptional({ example: "user@example.com" })
+], MeResponseDto.prototype, "email", 2);
+__decorateClass([
+  ApiPropertyOptional({ example: "johndoe" })
+], MeResponseDto.prototype, "username", 2);
+__decorateClass([
+  ApiProperty({ example: true })
+], MeResponseDto.prototype, "emailVerified", 2);
+__decorateClass([
+  ApiProperty({ example: false })
+], MeResponseDto.prototype, "disabled", 2);
+__decorateClass([
+  ApiPropertyOptional({ type: String, format: "date-time" })
+], MeResponseDto.prototype, "lastLoginAt", 2);
+__decorateClass([
+  ApiPropertyOptional({ type: String, format: "date-time" })
+], MeResponseDto.prototype, "passwordChangedAt", 2);
+var RefreshTokenDto = class {
+};
+__decorateClass([
+  ApiProperty({ example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }),
+  IsString(),
+  IsNotEmpty()
+], RefreshTokenDto.prototype, "refreshToken", 2);
+var RegisterAckDto = class {
+};
+__decorateClass([
+  ApiProperty({ example: true, enum: [true] })
+], RegisterAckDto.prototype, "registered", 2);
+var RegisterDto = class {
+};
+__decorateClass([
+  ApiPropertyOptional({ example: "user@example.com" }),
+  IsOptional(),
+  ValidateIf((dto) => dto.email != null && dto.email.trim() !== ""),
+  IsEmail(),
+  Length(3, 255)
+], RegisterDto.prototype, "email", 2);
+__decorateClass([
+  ApiPropertyOptional({ example: "johndoe" }),
+  IsOptional(),
+  IsString(),
+  Length(3, 50),
+  Matches(/^[a-zA-Z0-9._-]+$/)
+], RegisterDto.prototype, "username", 2);
+__decorateClass([
+  ApiProperty({ example: "Password1", minLength: 8, maxLength: 128 }),
+  IsString(),
+  IsNotEmpty(),
+  Length(8, 128)
+], RegisterDto.prototype, "password", 2);
+var ResendVerificationDto = class {
+};
+__decorateClass([
+  ApiProperty({ example: "user@example.com" }),
+  IsEmail()
+], ResendVerificationDto.prototype, "email", 2);
+var ResetPasswordDto = class {
+};
+__decorateClass([
+  ApiProperty({ example: "reset-token-from-email" }),
+  IsString(),
+  IsNotEmpty()
+], ResetPasswordDto.prototype, "token", 2);
+__decorateClass([
+  ApiProperty({ example: "NewPassword1", minLength: 8, maxLength: 128 }),
+  IsString(),
+  IsNotEmpty(),
+  Length(8, 128)
+], ResetPasswordDto.prototype, "newPassword", 2);
+var VerifyEmailDto = class {
 };
+__decorateClass([
+  ApiProperty({ example: "verification-token-from-email" }),
+  IsString(),
+  IsNotEmpty()
+], VerifyEmailDto.prototype, "token", 2);
+
+// src/swagger/setup-swagger.util.ts
+var AUTH_SWAGGER_MODELS = [
+  AuthTokensDto,
+  ChangePasswordDto,
+  ForgotPasswordDto,
+  LoginDto,
+  MeResponseDto,
+  RefreshTokenDto,
+  RegisterAckDto,
+  RegisterDto,
+  ResendVerificationDto,
+  ResetPasswordDto,
+  VerifyEmailDto
+];
+function describeEnabledFeatures(features) {
+  const lines = [];
+  if (features.emailVerification === true) {
+    lines.push("- Email verification (`POST /auth/verify-email`, `POST /auth/resend-verification`)");
+  }
+  if (features.passwordReset === true) {
+    lines.push("- Password reset (`POST /auth/forgot-password`, `POST /auth/reset-password`)");
+  }
+  if (features.refreshTokenRotation === false) {
+    lines.push("- Refresh token rotation **disabled** (stateless refresh until JWT expiry)");
+  }
+  if (features.accountLockout === true) {
+    lines.push("- Account lockout after failed logins");
+  }
+  if (lines.length === 0) {
+    return "";
+  }
+  return `
+
+## Auth features enabled
+${lines.join("\n")}`;
+}
+function setupAuthSwagger(app, options = {}) {
+  const nestApp = app;
+  const baseDescription = options.description ?? "REST API with JWT authentication via @aranzatech/aranza-auth";
+  const config = new DocumentBuilder().setTitle(options.title ?? "API").setDescription(
+    `${baseDescription}${describeEnabledFeatures(options.features ?? {})}`
+  ).setVersion(options.version ?? "1.0").addBearerAuth(
+    {
+      type: "http",
+      scheme: "bearer",
+      bearerFormat: "JWT",
+      description: "Access token from POST /auth/login"
+    },
+    "access-token"
+  ).build();
+  const document = SwaggerModule.createDocument(nestApp, config, {
+    extraModels: [...AUTH_SWAGGER_MODELS]
+  });
+  if (options.exportPath != null) {
+    void import('fs/promises').then(
+      ({ writeFile }) => writeFile(options.exportPath, JSON.stringify(document, null, 2), "utf8")
+    );
+  }
+  SwaggerModule.setup(options.path ?? "api", nestApp, document);
+}
+
+// src/utils/refresh-token-cookie.util.ts
+var DEFAULT_COOKIE_NAME = "refresh_token";
+var DEFAULT_MAX_AGE_SECONDS = 7 * 24 * 60 * 60;
+function resolveCookieOptions(options = {}) {
+  return {
+    name: options.name ?? DEFAULT_COOKIE_NAME,
+    path: options.path ?? "/auth/refresh",
+    secure: options.secure ?? true,
+    sameSite: options.sameSite ?? "strict",
+    maxAgeSeconds: options.maxAgeSeconds ?? DEFAULT_MAX_AGE_SECONDS,
+    httpOnly: options.httpOnly ?? true
+  };
+}
+function formatCookieAttributes(options) {
+  const parts = [
+    `Path=${options.path}`,
+    `Max-Age=${options.maxAgeSeconds}`,
+    `SameSite=${options.sameSite}`
+  ];
+  if (options.secure) parts.push("Secure");
+  if (options.httpOnly) parts.push("HttpOnly");
+  return parts.join("; ");
+}
+function buildRefreshTokenCookie(refreshToken, options = {}) {
+  const resolved = resolveCookieOptions(options);
+  return `${resolved.name}=${encodeURIComponent(refreshToken)}; ${formatCookieAttributes(resolved)}`;
+}
+function buildClearRefreshTokenCookie(options = {}) {
+  const resolved = resolveCookieOptions(options);
+  return `${resolved.name}=; Path=${resolved.path}; Max-Age=0; HttpOnly`;
+}
 var CurrentUser = createParamDecorator(
   (_data, ctx) => {
     const request = ctx.switchToHttp().getRequest();
@@ -39,8 +280,11 @@ var CurrentUser = createParamDecorator(
 );
 var JwtAuthGuard = class extends AuthGuard("jwt") {
   handleRequest(err, user, _info) {
-    if (err != null || !user) {
-      throw err ?? new UnauthorizedException();
+    if (err != null) {
+      throw err;
+    }
+    if (!user) {
+      throw new UnauthorizedException(AuthErrorCode.UNAUTHORIZED);
     }
     return user;
   }
@@ -54,7 +298,6 @@ var DUMMY_PASSWORD_HASH = "$2a$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZd
 var DefaultAuthHooks = class {
   async buildJwtPayload(account) {
     return {
-      sub: account.id,
       ...account.email != null ? { email: account.email } : {},
       ...account.username != null ? { username: account.username } : {}
     };
@@ -107,49 +350,133 @@ function expiresAtFromTtlMs(ttlMs) {
 }
 var DEFAULT_EMAIL_VERIFICATION_TTL_MS = 24 * 60 * 60 * 1e3;
 var DEFAULT_PASSWORD_RESET_TTL_MS = 15 * 60 * 1e3;
+var JWT_TOKEN_TYPE = {
+  ACCESS: "access",
+  REFRESH: "refresh"
+};
+function issuerAudienceClaims(options) {
+  return {
+    ...options.jwtIssuer != null ? { iss: options.jwtIssuer } : {},
+    ...options.jwtAudience != null ? { aud: options.jwtAudience } : {}
+  };
+}
+function buildAccessClaims(hookClaims, sub, pwdAt, options) {
+  return {
+    ...hookClaims,
+    sub,
+    typ: JWT_TOKEN_TYPE.ACCESS,
+    ...pwdAt != null ? { pwdAt } : {},
+    ...issuerAudienceClaims(options)
+  };
+}
+function buildRefreshClaims(sub, pwdAt, options) {
+  return {
+    sub,
+    typ: JWT_TOKEN_TYPE.REFRESH,
+    jti: randomUUID(),
+    ...pwdAt != null ? { pwdAt } : {},
+    ...issuerAudienceClaims(options)
+  };
+}
+function assertIssuerAudience(payload, options, errorCode) {
+  if (options.jwtIssuer != null && payload.iss != null && payload.iss !== options.jwtIssuer) {
+    throw new UnauthorizedException(errorCode);
+  }
+  if (options.jwtAudience != null && payload.aud != null && payload.aud !== options.jwtAudience) {
+    throw new UnauthorizedException(errorCode);
+  }
+}
+function assertAccessTokenClaims(payload, options) {
+  if (payload.typ != null && payload.typ !== JWT_TOKEN_TYPE.ACCESS) {
+    throw new UnauthorizedException(AuthErrorCode.INVALID_CREDENTIALS);
+  }
+  assertIssuerAudience(payload, options, AuthErrorCode.INVALID_CREDENTIALS);
+}
+function assertRefreshTokenClaims(payload, options) {
+  if (payload.typ !== JWT_TOKEN_TYPE.REFRESH) {
+    throw new UnauthorizedException(AuthErrorCode.INVALID_REFRESH_TOKEN);
+  }
+  if (typeof payload.sub !== "string" || payload.sub.length === 0) {
+    throw new UnauthorizedException(AuthErrorCode.INVALID_REFRESH_TOKEN);
+  }
+  assertIssuerAudience(payload, options, AuthErrorCode.INVALID_REFRESH_TOKEN);
+  return payload;
+}
+var HMAC_ALGORITHM = "sha256";
+function hashRefreshTokenValue(refreshToken, secret) {
+  return createHmac(HMAC_ALGORITHM, secret).update(refreshToken).digest("hex");
+}
+function compareRefreshTokenValue(refreshToken, storedHash, secret) {
+  const computed = hashRefreshTokenValue(refreshToken, secret);
+  try {
+    const a = Buffer.from(computed, "hex");
+    const b = Buffer.from(storedHash, "hex");
+    if (a.length !== b.length) return false;
+    return timingSafeEqual(a, b);
+  } catch {
+    return false;
+  }
+}
+
+// src/services/token.service.ts
 var JWT_ALGORITHM = "HS256";
 var TokenService = class {
   constructor(jwtService, options) {
     this.jwtService = jwtService;
     this.options = options;
   }
-  get bcryptRounds() {
-    return this.options.bcryptRounds ?? 10;
+  signOptions(secret, expiresIn) {
+    return {
+      secret,
+      expiresIn,
+      algorithm: JWT_ALGORITHM,
+      ...this.options.jwtIssuer != null ? { issuer: this.options.jwtIssuer } : {},
+      ...this.options.jwtAudience != null ? { audience: this.options.jwtAudience } : {}
+    };
   }
-  async signTokens(payload) {
+  async signTokens(accessClaims, refreshClaims) {
     const accessExpiresIn = this.options.expiresIn ?? "1h";
     const refreshExpiresIn = this.options.refreshExpiresIn ?? "7d";
     const [accessToken, refreshToken] = await Promise.all([
       this.jwtService.signAsync(
-        payload,
-        {
-          secret: this.options.secret,
-          expiresIn: accessExpiresIn,
-          algorithm: JWT_ALGORITHM
-        }
+        accessClaims,
+        this.signOptions(this.options.secret, accessExpiresIn)
       ),
       this.jwtService.signAsync(
-        payload,
-        {
-          secret: this.options.refreshSecret,
-          expiresIn: refreshExpiresIn,
-          algorithm: JWT_ALGORITHM
-        }
+        refreshClaims,
+        this.signOptions(this.options.refreshSecret, refreshExpiresIn)
       )
     ]);
     return { accessToken, refreshToken };
   }
   async verifyRefreshToken(refreshToken) {
-    return this.jwtService.verifyAsync(refreshToken, {
-      secret: this.options.refreshSecret,
-      algorithms: [JWT_ALGORITHM]
-    });
+    try {
+      const payload = await this.jwtService.verifyAsync(
+        refreshToken,
+        {
+          secret: this.options.refreshSecret,
+          algorithms: [JWT_ALGORITHM],
+          ...this.options.jwtIssuer != null ? { issuer: this.options.jwtIssuer } : {},
+          ...this.options.jwtAudience != null ? { audience: this.options.jwtAudience } : {}
+        }
+      );
+      return assertRefreshTokenClaims(payload, this.options);
+    } catch (error) {
+      if (error instanceof UnauthorizedException) {
+        throw error;
+      }
+      throw new UnauthorizedException(AuthErrorCode.INVALID_REFRESH_TOKEN);
+    }
   }
   async hashRefreshToken(refreshToken) {
-    return bcrypt2.hash(refreshToken, this.bcryptRounds);
+    return hashRefreshTokenValue(refreshToken, this.options.refreshSecret);
   }
-  async compareRefreshToken(refreshToken, hash3) {
-    return bcrypt2.compare(refreshToken, hash3);
+  async compareRefreshToken(refreshToken, hash2) {
+    return compareRefreshTokenValue(
+      refreshToken,
+      hash2,
+      this.options.refreshSecret
+    );
   }
 };
 TokenService = __decorateClass([
@@ -157,6 +484,32 @@ TokenService = __decorateClass([
   __decorateParam(0, Inject(JwtService)),
   __decorateParam(1, Inject(AUTH_MODULE_OPTIONS))
 ], TokenService);
+function passwordChangedAtMs(account) {
+  return account.passwordChangedAt?.getTime();
+}
+function buildPwdAtClaim(account) {
+  return passwordChangedAtMs(account);
+}
+function isAccountLocked(account, lockoutEnabled) {
+  if (!lockoutEnabled) return false;
+  const lockedUntil = "lockedUntil" in account ? account.lockedUntil : void 0;
+  if (lockedUntil == null) return false;
+  return lockedUntil > /* @__PURE__ */ new Date();
+}
+function assertAccountNotLocked(account, options) {
+  if (!isAccountLocked(account, options.features?.accountLockout === true)) {
+    return;
+  }
+  throw new UnauthorizedException(AuthErrorCode.ACCOUNT_LOCKED);
+}
+function assertPasswordNotStale(payload, account) {
+  const changedAt = passwordChangedAtMs(account);
+  if (changedAt == null) return;
+  const tokenPwdAt = typeof payload.pwdAt === "number" ? payload.pwdAt : void 0;
+  if (tokenPwdAt == null || tokenPwdAt < changedAt) {
+    throw new UnauthorizedException(AuthErrorCode.PASSWORD_CHANGED);
+  }
+}
 
 // src/services/auth.service.ts
 var AuthService = class {
@@ -205,7 +558,7 @@ var AuthService = class {
     resolveRegisterIdentifier(input, this.identifierField);
     this.assertRegisterEmailWhenVerificationEnabled(input);
     this.assertPasswordPolicy(dto.password);
-    const passwordHash = await bcrypt2.hash(dto.password, this.bcryptRounds);
+    const passwordHash = await bcrypt.hash(dto.password, this.bcryptRounds);
     try {
       const account = await this.authRepository.create({
         ...input,
@@ -229,11 +582,8 @@ var AuthService = class {
     const account = await this.authRepository.findByIdentifierWithSecrets(
       identifier
     );
-    if (account != null) {
-      this.assertAccountNotLocked(account);
-    }
     const passwordHash = account?.passwordHash ?? DUMMY_PASSWORD_HASH;
-    const passwordMatches = await bcrypt2.compare(dto.password, passwordHash);
+    const passwordMatches = await bcrypt.compare(dto.password, passwordHash);
     if (account?.passwordHash == null || !passwordMatches) {
       if (account != null && this.accountLockoutEnabled) {
         await this.authRepository.recordLoginFailure(
@@ -243,6 +593,7 @@ var AuthService = class {
       }
       throw new UnauthorizedException(AuthErrorCode.INVALID_CREDENTIALS);
     }
+    assertAccountNotLocked(account, this.options);
     this.assertAccountActive(account);
     await this.authRepository.recordLoginSuccess(account.id);
     return this.issueTokens(account);
@@ -251,14 +602,25 @@ var AuthService = class {
     let payload;
     try {
       payload = await this.tokenService.verifyRefreshToken(refreshToken);
-    } catch {
+    } catch (error) {
+      if (error instanceof UnauthorizedException) {
+        throw error;
+      }
       throw new UnauthorizedException(AuthErrorCode.INVALID_REFRESH_TOKEN);
     }
     const account = await this.authRepository.findByIdWithSecrets(payload.sub);
     if (account == null) {
       throw new UnauthorizedException(AuthErrorCode.INVALID_REFRESH_TOKEN);
     }
+    assertPasswordNotStale(
+      {
+        sub: payload.sub,
+        ...payload.pwdAt != null ? { pwdAt: payload.pwdAt } : {}
+      },
+      account
+    );
     this.assertAccountActive(account);
+    assertAccountNotLocked(account, this.options);
     if (this.rotateRefreshToken) {
       if (account.refreshTokenHash == null) {
         throw new UnauthorizedException(AuthErrorCode.INVALID_REFRESH_TOKEN);
@@ -271,6 +633,9 @@ var AuthService = class {
         await this.authRepository.updateRefreshTokenHash(account.id, null);
         throw new UnauthorizedException(AuthErrorCode.REFRESH_TOKEN_REUSE);
       }
+      return this.issueTokens(account, {
+        expectedRefreshHash: account.refreshTokenHash
+      });
     }
     return this.issueTokens(account);
   }
@@ -281,7 +646,7 @@ var AuthService = class {
   async me(authId) {
     const account = await this.authRepository.findById(authId);
     if (account == null) {
-      throw new UnauthorizedException("Account not found");
+      throw new UnauthorizedException(AuthErrorCode.ACCOUNT_NOT_FOUND);
     }
     if (this.hooks.enrichMe != null) {
       return this.hooks.enrichMe(account);
@@ -322,18 +687,37 @@ var AuthService = class {
       throw new BadRequestException(AuthErrorCode.TOKEN_INVALID_OR_EXPIRED);
     }
     this.assertPasswordPolicy(newPassword);
-    const passwordHash = await bcrypt2.hash(newPassword, this.bcryptRounds);
+    const samePassword = await bcrypt.compare(
+      newPassword,
+      account.passwordHash
+    );
+    if (samePassword) {
+      throw new BadRequestException(AuthErrorCode.PASSWORD_UNCHANGED);
+    }
+    const passwordHash = await bcrypt.hash(newPassword, this.bcryptRounds);
     await this.authRepository.updatePasswordHash(account.id, passwordHash);
     await this.authRepository.clearResetToken(account.id);
     await this.authRepository.updateRefreshTokenHash(account.id, null);
     return { reset: true };
   }
+  async resendVerification(email) {
+    this.assertEmailVerificationEnabled();
+    this.assertEmailHookWhenVerificationEnabled();
+    const normalizedEmail = normalizeIdentifier(email);
+    const account = await this.authRepository.findUnverifiedByEmail(
+      normalizedEmail
+    );
+    if (account != null && !account.disabled) {
+      await this.sendVerificationEmail(account);
+    }
+    return { sent: true };
+  }
   async changePassword(authId, currentPassword, newPassword) {
     const account = await this.authRepository.findByIdWithSecrets(authId);
     if (account?.passwordHash == null) {
       throw new UnauthorizedException(AuthErrorCode.INVALID_CURRENT_PASSWORD);
     }
-    const currentMatches = await bcrypt2.compare(
+    const currentMatches = await bcrypt.compare(
       currentPassword,
       account.passwordHash
     );
@@ -344,19 +728,11 @@ var AuthService = class {
       throw new BadRequestException(AuthErrorCode.PASSWORD_UNCHANGED);
     }
     this.assertPasswordPolicy(newPassword);
-    const passwordHash = await bcrypt2.hash(newPassword, this.bcryptRounds);
+    const passwordHash = await bcrypt.hash(newPassword, this.bcryptRounds);
     await this.authRepository.updatePasswordHash(account.id, passwordHash);
     await this.authRepository.updateRefreshTokenHash(account.id, null);
     return { changed: true };
   }
-  assertAccountNotLocked(account) {
-    if (!this.accountLockoutEnabled || account.lockedUntil == null) {
-      return;
-    }
-    if (account.lockedUntil > /* @__PURE__ */ new Date()) {
-      throw new UnauthorizedException(AuthErrorCode.ACCOUNT_LOCKED);
-    }
-  }
   assertAccountActive(account) {
     if (account.disabled) {
       throw new UnauthorizedException(AuthErrorCode.ACCOUNT_DISABLED);
@@ -370,20 +746,33 @@ var AuthService = class {
       assertPasswordComplexity(password);
     }
   }
-  async issueTokens(account) {
-    const payload = await this.hooks.buildJwtPayload(account);
-    const tokens = await this.tokenService.signTokens({
-      ...payload,
-      sub: account.id
-    });
+  async issueTokens(account, rotation) {
+    const hookPayload = await this.hooks.buildJwtPayload(account);
+    const pwdAt = buildPwdAtClaim(account);
+    const tokens = await this.tokenService.signTokens(
+      buildAccessClaims(hookPayload, account.id, pwdAt, this.options),
+      buildRefreshClaims(account.id, pwdAt, this.options)
+    );
     if (this.rotateRefreshToken) {
       const refreshTokenHash = await this.tokenService.hashRefreshToken(
         tokens.refreshToken
       );
-      await this.authRepository.updateRefreshTokenHash(
-        account.id,
-        refreshTokenHash
-      );
+      if (rotation?.expectedRefreshHash != null) {
+        const swapped = await this.authRepository.rotateRefreshTokenHashIfMatch(
+          account.id,
+          rotation.expectedRefreshHash,
+          refreshTokenHash
+        );
+        if (!swapped) {
+          await this.authRepository.updateRefreshTokenHash(account.id, null);
+          throw new UnauthorizedException(AuthErrorCode.REFRESH_TOKEN_REUSE);
+        }
+      } else {
+        await this.authRepository.updateRefreshTokenHash(
+          account.id,
+          refreshTokenHash
+        );
+      }
     }
     await this.hooks.onAfterLogin?.(account);
     return tokens;
@@ -453,6 +842,21 @@ AuthService = __decorateClass([
   __decorateParam(2, Inject(AUTH_HOOKS)),
   __decorateParam(3, Inject(TokenService))
 ], AuthService);
+function ApiAuthUnauthorizedResponse(...codes) {
+  const messageEnum = codes.length > 0 ? codes : Object.values(AuthErrorCode);
+  return applyDecorators(
+    ApiUnauthorizedResponse({
+      description: "Unauthorized \u2014 `message` is an `AuthErrorCode` value",
+      schema: {
+        type: "object",
+        properties: {
+          statusCode: { type: "number", example: 401 },
+          message: { type: "string", enum: messageEnum }
+        }
+      }
+    })
+  );
+}
 
 // src/controllers/auth.controller.ts
 var AuthController = class {
@@ -477,6 +881,9 @@ var AuthController = class {
   verifyEmail(dto) {
     return this.authService.verifyEmail(dto.token);
   }
+  resendVerification(dto) {
+    return this.authService.resendVerification(dto.email);
+  }
   forgotPassword(dto) {
     return this.authService.forgotPassword(dto.email);
   }
@@ -493,52 +900,118 @@ var AuthController = class {
 };
 __decorateClass([
   Post("register"),
+  ApiOperation({ summary: "Register a new account" }),
+  ApiResponse({ status: 201, type: RegisterAckDto }),
   __decorateParam(0, Body())
 ], AuthController.prototype, "register", 1);
 __decorateClass([
   Post("login"),
+  HttpCode(HttpStatus.OK),
+  ApiOperation({ summary: "Login and receive JWT tokens" }),
+  ApiResponse({ status: 200, type: AuthTokensDto }),
+  ApiAuthUnauthorizedResponse(
+    AuthErrorCode.INVALID_CREDENTIALS,
+    AuthErrorCode.ACCOUNT_LOCKED,
+    AuthErrorCode.EMAIL_NOT_VERIFIED,
+    AuthErrorCode.ACCOUNT_DISABLED
+  ),
   __decorateParam(0, Body())
 ], AuthController.prototype, "login", 1);
 __decorateClass([
   Post("refresh"),
   HttpCode(HttpStatus.OK),
+  ApiOperation({ summary: "Refresh access token using refresh token" }),
+  ApiResponse({ status: 200, type: AuthTokensDto }),
+  ApiAuthUnauthorizedResponse(
+    AuthErrorCode.INVALID_REFRESH_TOKEN,
+    AuthErrorCode.REFRESH_TOKEN_REUSE,
+    AuthErrorCode.PASSWORD_CHANGED,
+    AuthErrorCode.EMAIL_NOT_VERIFIED,
+    AuthErrorCode.ACCOUNT_LOCKED
+  ),
   __decorateParam(0, Body())
 ], AuthController.prototype, "refresh", 1);
 __decorateClass([
   Post("logout"),
   UseGuards(JwtAuthGuard),
+  ApiBearerAuth("access-token"),
   HttpCode(HttpStatus.OK),
+  ApiOperation({ summary: "Logout and revoke refresh token" }),
+  ApiResponse({ status: 200, schema: { example: { loggedOut: true } } }),
+  ApiAuthUnauthorizedResponse(AuthErrorCode.UNAUTHORIZED),
   __decorateParam(0, CurrentUser())
 ], AuthController.prototype, "logout", 1);
 __decorateClass([
   Get("me"),
   UseGuards(JwtAuthGuard),
+  ApiBearerAuth("access-token"),
+  ApiOperation({ summary: "Get current authenticated user profile" }),
+  ApiResponse({ status: 200, type: MeResponseDto }),
+  ApiAuthUnauthorizedResponse(
+    AuthErrorCode.UNAUTHORIZED,
+    AuthErrorCode.ACCOUNT_NOT_FOUND,
+    AuthErrorCode.PASSWORD_CHANGED,
+    AuthErrorCode.EMAIL_NOT_VERIFIED,
+    AuthErrorCode.ACCOUNT_LOCKED
+  ),
   __decorateParam(0, CurrentUser())
 ], AuthController.prototype, "me", 1);
 __decorateClass([
   Post("verify-email"),
   HttpCode(HttpStatus.OK),
+  ApiOperation({
+    summary: "Verify email with token (requires emailVerification feature)"
+  }),
+  ApiResponse({ status: 200, schema: { example: { verified: true } } }),
+  ApiResponse({ status: 404, description: "Feature disabled" }),
   __decorateParam(0, Body())
 ], AuthController.prototype, "verifyEmail", 1);
+__decorateClass([
+  Post("resend-verification"),
+  HttpCode(HttpStatus.OK),
+  ApiOperation({
+    summary: "Resend verification email (requires emailVerification feature)"
+  }),
+  ApiResponse({ status: 200, schema: { example: { sent: true } } }),
+  ApiResponse({ status: 404, description: "Feature disabled" }),
+  __decorateParam(0, Body())
+], AuthController.prototype, "resendVerification", 1);
 __decorateClass([
   Post("forgot-password"),
   HttpCode(HttpStatus.OK),
+  ApiOperation({
+    summary: "Request password reset email (requires passwordReset feature)"
+  }),
+  ApiResponse({ status: 200, schema: { example: { sent: true } } }),
+  ApiResponse({ status: 404, description: "Feature disabled" }),
   __decorateParam(0, Body())
 ], AuthController.prototype, "forgotPassword", 1);
 __decorateClass([
   Post("reset-password"),
   HttpCode(HttpStatus.OK),
+  ApiOperation({
+    summary: "Reset password with token (requires passwordReset feature)"
+  }),
+  ApiResponse({ status: 200, schema: { example: { reset: true } } }),
+  ApiResponse({ status: 404, description: "Feature disabled" }),
   __decorateParam(0, Body())
 ], AuthController.prototype, "resetPassword", 1);
 __decorateClass([
   Post("change-password"),
   UseGuards(JwtAuthGuard),
+  ApiBearerAuth("access-token"),
   HttpCode(HttpStatus.OK),
+  ApiOperation({ summary: "Change password for authenticated user" }),
+  ApiResponse({ status: 200, schema: { example: { changed: true } } }),
+  ApiAuthUnauthorizedResponse(
+    AuthErrorCode.UNAUTHORIZED,
+    AuthErrorCode.INVALID_CURRENT_PASSWORD
+  ),
   __decorateParam(0, CurrentUser()),
   __decorateParam(1, Body())
 ], AuthController.prototype, "changePassword", 1);
 AuthController = __decorateClass([
-  Controller("auth"),
+  ApiTags("auth"),
   __decorateParam(0, Inject(AuthService))
 ], AuthController);
 
@@ -560,19 +1033,55 @@ var JwtStrategy = class extends PassportStrategy(Strategy) {
       jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
       ignoreExpiration: false,
       secretOrKey: options.secret,
-      algorithms: ["HS256"]
+      algorithms: ["HS256"],
+      ...options.jwtIssuer != null ? { issuer: options.jwtIssuer } : {},
+      ...options.jwtAudience != null ? { audience: options.jwtAudience } : {}
     });
     this.options = options;
     this.authRepository = authRepository;
+    this.validationCache = /* @__PURE__ */ new Map();
   }
-  async validate(payload) {
-    const account = await this.authRepository.findById(payload.sub);
-    if (account == null || account.disabled) {
-      throw new UnauthorizedException("Account not found or inactive");
+  get cacheTtlMs() {
+    return this.options.jwtValidationCacheTtlMs ?? 0;
+  }
+  getCachedAccount(sub) {
+    const cached = this.validationCache.get(sub);
+    if (cached == null || cached.expiresAt <= Date.now()) {
+      if (cached != null) this.validationCache.delete(sub);
+      return null;
+    }
+    return cached.account;
+  }
+  cacheAccount(sub, account) {
+    if (this.cacheTtlMs <= 0) return;
+    this.validationCache.set(sub, {
+      account,
+      expiresAt: Date.now() + this.cacheTtlMs
+    });
+  }
+  assertAccountActive(account, payload) {
+    if (account.disabled) {
+      throw new UnauthorizedException(AuthErrorCode.ACCOUNT_DISABLED);
     }
+    assertAccountNotLocked(account, this.options);
     if (this.options.features?.emailVerification === true && !account.emailVerified) {
       throw new UnauthorizedException(AuthErrorCode.EMAIL_NOT_VERIFIED);
     }
+    assertPasswordNotStale(payload, account);
+  }
+  async validate(payload) {
+    assertAccessTokenClaims(payload, this.options);
+    const cached = this.getCachedAccount(payload.sub);
+    if (cached != null) {
+      this.assertAccountActive(cached, payload);
+      return payload;
+    }
+    const account = await this.authRepository.findById(payload.sub);
+    if (account == null) {
+      throw new UnauthorizedException(AuthErrorCode.ACCOUNT_NOT_FOUND);
+    }
+    this.assertAccountActive(account, payload);
+    this.cacheAccount(payload.sub, account);
     return payload;
   }
 };
@@ -581,8 +1090,6 @@ JwtStrategy = __decorateClass([
   __decorateParam(0, Inject(AUTH_MODULE_OPTIONS)),
   __decorateParam(1, Inject(AUTH_REPOSITORY))
 ], JwtStrategy);
-
-// src/utils/hooks-provider.util.ts
 function createHooksProvider(options) {
   if (options.hooksProvider != null) {
     return options.hooksProvider;
@@ -590,7 +1097,8 @@ function createHooksProvider(options) {
   const HooksClass = options.hooks ?? DefaultAuthHooks;
   return {
     provide: AUTH_HOOKS,
-    useClass: HooksClass
+    inject: [ModuleRef],
+    useFactory: (moduleRef) => moduleRef.create(HooksClass)
   };
 }
 
@@ -630,6 +1138,17 @@ function validateAuthModuleOptions(options) {
       "AuthModule: passwordResetTokenTtlMs must be at least 60000 (1 minute)"
     );
   }
+  if (options.features?.refreshTokenRotation === false) {
+    console.warn(
+      "[aranza-auth] features.refreshTokenRotation is false \u2014 refresh tokens are stateless until JWT expiry; stolen tokens cannot be revoked server-side."
+    );
+  }
+  const cacheTtl = options.jwtValidationCacheTtlMs ?? 0;
+  if (cacheTtl < 0 || cacheTtl > 3e5) {
+    throw new Error(
+      "AuthModule: jwtValidationCacheTtlMs must be between 0 and 300000 (5 minutes)"
+    );
+  }
 }
 
 // src/auth.module.ts
@@ -647,15 +1166,33 @@ function createCoreProviders(options) {
     JwtAuthGuard
   ];
 }
-function createAsyncHooksProvider(options) {
-  if (options.hooksProvider != null) {
-    return options.hooksProvider;
-  }
-  const HooksClass = options.hooks ?? DefaultAuthHooks;
+function createAsyncProviders(options) {
+  return [
+    {
+      provide: AUTH_MODULE_OPTIONS,
+      inject: options.inject ?? [],
+      useFactory: async (...args) => {
+        const config = await options.useFactory(...args);
+        validateAuthModuleOptions(config);
+        return config;
+      }
+    },
+    createHooksProvider(options),
+    AuthService,
+    TokenService,
+    JwtStrategy,
+    JwtAuthGuard
+  ];
+}
+function jwtModuleOptions(opts) {
   return {
-    provide: AUTH_HOOKS,
-    inject: [ModuleRef],
-    useFactory: (moduleRef) => moduleRef.create(HooksClass)
+    secret: opts.secret,
+    signOptions: {
+      expiresIn: opts.expiresIn ?? "1h",
+      algorithm: "HS256",
+      ...opts.jwtIssuer != null ? { issuer: opts.jwtIssuer } : {},
+      ...opts.jwtAudience != null ? { audience: opts.jwtAudience } : {}
+    }
   };
 }
 function createAuthImports() {
@@ -663,13 +1200,7 @@ function createAuthImports() {
     PassportModule.register({ defaultStrategy: "jwt" }),
     JwtModule.registerAsync({
       inject: [AUTH_MODULE_OPTIONS],
-      useFactory: (opts) => ({
-        secret: opts.secret,
-        signOptions: {
-          expiresIn: opts.expiresIn ?? "1h",
-          algorithm: "HS256"
-        }
-      })
+      useFactory: (opts) => jwtModuleOptions(opts)
     })
   ];
 }
@@ -680,24 +1211,6 @@ function mergeImports(userImports) {
   }
   return merged;
 }
-function createAsyncProviders(options) {
-  return [
-    {
-      provide: AUTH_MODULE_OPTIONS,
-      inject: options.inject ?? [],
-      useFactory: async (...args) => {
-        const config = await options.useFactory(...args);
-        validateAuthModuleOptions(config);
-        return config;
-      }
-    },
-    createAsyncHooksProvider(options),
-    AuthService,
-    TokenService,
-    JwtStrategy,
-    JwtAuthGuard
-  ];
-}
 var AuthModule = class {
   static forRoot(options) {
     const routePrefix = options.routePrefix ?? "auth";
@@ -742,90 +1255,6 @@ AuthModule = __decorateClass([
   Module({})
 ], AuthModule);
 
-// src/dto/auth-tokens.dto.ts
-var AuthTokensDto = class {
-};
-var ChangePasswordDto = class {
-};
-__decorateClass([
-  IsString(),
-  IsNotEmpty()
-], ChangePasswordDto.prototype, "currentPassword", 2);
-__decorateClass([
-  IsString(),
-  IsNotEmpty(),
-  Length(8, 128)
-], ChangePasswordDto.prototype, "newPassword", 2);
-var ForgotPasswordDto = class {
-};
-__decorateClass([
-  IsEmail()
-], ForgotPasswordDto.prototype, "email", 2);
-var LoginDto = class {
-};
-__decorateClass([
-  IsOptional(),
-  ValidateIf((dto) => dto.email != null && dto.email.trim() !== ""),
-  IsEmail(),
-  Length(3, 255)
-], LoginDto.prototype, "email", 2);
-__decorateClass([
-  IsOptional(),
-  IsString(),
-  Length(3, 50)
-], LoginDto.prototype, "username", 2);
-__decorateClass([
-  IsString(),
-  IsNotEmpty(),
-  Length(8, 128)
-], LoginDto.prototype, "password", 2);
-var RefreshTokenDto = class {
-};
-__decorateClass([
-  IsString(),
-  IsNotEmpty()
-], RefreshTokenDto.prototype, "refreshToken", 2);
-
-// src/dto/register-ack.dto.ts
-var RegisterAckDto = class {
-};
-var RegisterDto = class {
-};
-__decorateClass([
-  IsOptional(),
-  ValidateIf((dto) => dto.email != null && dto.email.trim() !== ""),
-  IsEmail(),
-  Length(3, 255)
-], RegisterDto.prototype, "email", 2);
-__decorateClass([
-  IsOptional(),
-  IsString(),
-  Length(3, 50),
-  Matches(/^[a-zA-Z0-9._-]+$/)
-], RegisterDto.prototype, "username", 2);
-__decorateClass([
-  IsString(),
-  IsNotEmpty(),
-  Length(8, 128)
-], RegisterDto.prototype, "password", 2);
-var ResetPasswordDto = class {
-};
-__decorateClass([
-  IsString(),
-  IsNotEmpty()
-], ResetPasswordDto.prototype, "token", 2);
-__decorateClass([
-  IsString(),
-  IsNotEmpty(),
-  Length(8, 128)
-], ResetPasswordDto.prototype, "newPassword", 2);
-var VerifyEmailDto = class {
-};
-__decorateClass([
-  IsString(),
-  IsNotEmpty()
-], VerifyEmailDto.prototype, "token", 2);
-
-export { AUTH_RATE_LIMIT_PRESETS, AuthErrorCode, AuthModule, AuthService, AuthTokensDto, ChangePasswordDto, CurrentUser, DefaultAuthHooks, ForgotPasswordDto, JwtAuthGuard, LoginDto, RefreshTokenDto, RegisterAckDto, RegisterDto, ResetPasswordDto, TokenService, VerifyEmailDto };
+export { AUTH_RATE_LIMIT_PRESETS, AUTH_RATE_LIMIT_ROUTES, AuthErrorCode, AuthModule, AuthService, AuthTokensDto, ChangePasswordDto, CurrentUser, DefaultAuthHooks, ForgotPasswordDto, JwtAuthGuard, LoginDto, MeResponseDto, RefreshTokenDto, RegisterAckDto, RegisterDto, ResendVerificationDto, ResetPasswordDto, TokenService, VerifyEmailDto, buildClearRefreshTokenCookie, buildRefreshTokenCookie, setupAuthSwagger };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map