@aranzatech/aranza-auth 0.2.1 → 0.2.2

package/dist/index.d.ts

@@ -1,6 +1,6 @@
+import { A as AuthFeatures, a as AuthModuleOptions, b as AuthModuleAsyncOptions, c as AuthHooks, B as BaseAuthAccount, R as RegisterInput, d as AuthTokens, I as IAuthRepository } from './auth-repository.interface--1rv0RCD.js';
+export { e as AuthAccountWithSecrets, f as AuthHooksConstructor, g as AuthIdentifierField, h as AuthJwtConfig, C as CreateAccountData } from './auth-repository.interface--1rv0RCD.js';
 import { DynamicModule } from '@nestjs/common';
-import { A as AuthModuleOptions, a as AuthModuleAsyncOptions, b as AuthHooks, B as BaseAuthAccount, R as RegisterInput, c as AuthTokens, I as IAuthRepository } from './auth-repository.interface-9PpDVOs8.js';
-export { d as AuthAccountWithSecrets, e as AuthFeatures, f as AuthIdentifierField, g as AuthJwtConfig, C as CreateAccountData } from './auth-repository.interface-9PpDVOs8.js';
 import * as _nestjs_passport from '@nestjs/passport';
 import { JwtService } from '@nestjs/jwt';
 
@@ -38,20 +38,116 @@ declare const AUTH_RATE_LIMIT_PRESETS: {
 };
 type AuthRateLimitPreset = (typeof AUTH_RATE_LIMIT_PRESETS)[keyof typeof AUTH_RATE_LIMIT_PRESETS];
 
-/** Machine-readable auth error codes returned in HTTP responses. */
+/**
+ * Maps auth routes to recommended `@nestjs/throttler` presets.
+ * Apply per-route with `@Throttle()` in a wrapping controller or global guard.
+ *
+ * @example
+ * ```typescript
+ * import { Throttle } from "@nestjs/throttler";
+ * import { AUTH_RATE_LIMIT_ROUTES } from "@aranzatech/aranza-auth";
+ *
+ * @Throttle({ default: AUTH_RATE_LIMIT_ROUTES.login })
+ * @Post("login")
+ * login() { ... }
+ * ```
+ */
+declare const AUTH_RATE_LIMIT_ROUTES: {
+    readonly login: {
+        readonly name: "auth-credentials";
+        readonly ttl: 60000;
+        readonly limit: 5;
+    };
+    readonly register: {
+        readonly name: "auth-credentials";
+        readonly ttl: 60000;
+        readonly limit: 5;
+    };
+    readonly refresh: {
+        readonly name: "auth-credentials";
+        readonly ttl: 60000;
+        readonly limit: 5;
+    };
+    readonly "forgot-password": {
+        readonly name: "auth-password-reset";
+        readonly ttl: 60000;
+        readonly limit: 3;
+    };
+    readonly "reset-password": {
+        readonly name: "auth-password-reset";
+        readonly ttl: 60000;
+        readonly limit: 3;
+    };
+    readonly "resend-verification": {
+        readonly name: "auth-password-reset";
+        readonly ttl: 60000;
+        readonly limit: 3;
+    };
+    readonly default: {
+        readonly name: "auth-default";
+        readonly ttl: 60000;
+        readonly limit: 10;
+    };
+};
+type AuthRateLimitRoute = keyof typeof AUTH_RATE_LIMIT_ROUTES;
+
+/** Machine-readable auth error codes returned in HTTP `message` field. */
 declare const AuthErrorCode: {
-    readonly INVALID_CREDENTIALS: "Invalid credentials";
-    readonly INVALID_REFRESH_TOKEN: "Invalid refresh token";
+    readonly INVALID_CREDENTIALS: "INVALID_CREDENTIALS";
+    readonly INVALID_REFRESH_TOKEN: "INVALID_REFRESH_TOKEN";
     readonly REFRESH_TOKEN_REUSE: "REFRESH_TOKEN_REUSE";
     readonly ACCOUNT_DISABLED: "ACCOUNT_DISABLED";
+    readonly ACCOUNT_NOT_FOUND: "ACCOUNT_NOT_FOUND";
     readonly EMAIL_NOT_VERIFIED: "EMAIL_NOT_VERIFIED";
     readonly TOKEN_INVALID_OR_EXPIRED: "TOKEN_INVALID_OR_EXPIRED";
     readonly ACCOUNT_LOCKED: "ACCOUNT_LOCKED";
     readonly INVALID_CURRENT_PASSWORD: "INVALID_CURRENT_PASSWORD";
     readonly PASSWORD_UNCHANGED: "PASSWORD_UNCHANGED";
+    readonly PASSWORD_CHANGED: "PASSWORD_CHANGED";
+    /** Missing or invalid Bearer token on a protected route. */
+    readonly UNAUTHORIZED: "UNAUTHORIZED";
 };
 type AuthErrorCodeValue = (typeof AuthErrorCode)[keyof typeof AuthErrorCode];
 
+interface AuthSwaggerOptions {
+    /** OpenAPI document title. Default: `API`. */
+    title?: string;
+    /** API description shown in Swagger UI. */
+    description?: string;
+    /** Swagger UI path. Default: `api`. */
+    path?: string;
+    /** API version string. Default: `1.0`. */
+    version?: string;
+    /** Enabled auth features — appended to the OpenAPI description. */
+    features?: Partial<AuthFeatures>;
+    /** Write `openapi.json` to this path when set (relative to process cwd). */
+    exportPath?: string;
+}
+/**
+ * Configures Swagger UI with JWT Bearer auth for apps using `@aranzatech/aranza-auth`.
+ * Requires `@nestjs/swagger` installed in the host application.
+ */
+declare function setupAuthSwagger(app: unknown, options?: AuthSwaggerOptions): void;
+
+interface RefreshTokenCookieOptions {
+    /** Cookie name. Default: `refresh_token`. */
+    name?: string;
+    /** Cookie path. Default: `/auth/refresh`. */
+    path?: string;
+    /** `Secure` flag — use `true` in production (HTTPS). Default: `true`. */
+    secure?: boolean;
+    /** `SameSite` attribute. Default: `strict`. */
+    sameSite?: "strict" | "lax" | "none";
+    /** Max-Age in seconds. Default: 7 days. */
+    maxAgeSeconds?: number;
+    /** `HttpOnly` flag. Default: `true`. */
+    httpOnly?: boolean;
+}
+/** Builds a `Set-Cookie` header value for storing the refresh token. */
+declare function buildRefreshTokenCookie(refreshToken: string, options?: RefreshTokenCookieOptions): string;
+/** Builds a `Set-Cookie` header value that clears the refresh token cookie. */
+declare function buildClearRefreshTokenCookie(options?: RefreshTokenCookieOptions): string;
+
 declare class AuthModule {
     static forRoot(options: AuthModuleOptions): DynamicModule;
     static forRootAsync(options: AuthModuleAsyncOptions): DynamicModule;
@@ -107,6 +203,20 @@ declare class VerifyEmailDto {
     token: string;
 }
 
+declare class ResendVerificationDto {
+    email: string;
+}
+
+declare class MeResponseDto {
+    id: string;
+    email?: string;
+    username?: string;
+    emailVerified: boolean;
+    disabled: boolean;
+    lastLoginAt?: Date;
+    passwordChangedAt?: Date;
+}
+
 declare const JwtAuthGuard_base: _nestjs_passport.Type<_nestjs_passport.IAuthGuard>;
 declare class JwtAuthGuard extends JwtAuthGuard_base {
     handleRequest<TUser>(err: Error | null, user: TUser, _info: unknown): TUser;
@@ -120,21 +230,40 @@ declare class DefaultAuthHooks implements AuthHooks {
     onAfterLogin(_account: BaseAuthAccount): Promise<void>;
 }
 
-/** JWT access/refresh payload. Extend via `AuthHooks.buildJwtPayload`. */
+/** JWT access token payload. Extend via `AuthHooks.buildJwtPayload`. */
 interface AuthJwtPayload {
     sub: string;
+    /** `access` — rejected by Passport if a refresh token is presented. */
+    typ?: "access" | "refresh";
+    /** Unix ms when password last changed — invalidates older access tokens. */
+    pwdAt?: number;
+    iss?: string;
+    aud?: string;
     [claim: string]: unknown;
 }
 /** @deprecated Use `AuthJwtPayload`. */
 type JwtPayload = AuthJwtPayload;
 
+declare const JWT_TOKEN_TYPE: {
+    readonly ACCESS: "access";
+    readonly REFRESH: "refresh";
+};
+interface RefreshJwtPayload {
+    sub: string;
+    typ: typeof JWT_TOKEN_TYPE.REFRESH;
+    pwdAt?: number;
+    jti: string;
+    iss?: string;
+    aud?: string;
+}
+
 declare class TokenService {
     private readonly jwtService;
     private readonly options;
     constructor(jwtService: JwtService, options: AuthModuleOptions);
-    private get bcryptRounds();
-    signTokens(payload: AuthJwtPayload): Promise<AuthTokens>;
-    verifyRefreshToken(refreshToken: string): Promise<AuthJwtPayload>;
+    private signOptions;
+    signTokens(accessClaims: Record<string, unknown>, refreshClaims: RefreshJwtPayload): Promise<AuthTokens>;
+    verifyRefreshToken(refreshToken: string): Promise<RefreshJwtPayload>;
     hashRefreshToken(refreshToken: string): Promise<string>;
     compareRefreshToken(refreshToken: string, hash: string): Promise<boolean>;
 }
@@ -171,10 +300,12 @@ declare class AuthService {
     resetPassword(token: string, newPassword: string): Promise<{
         reset: true;
     }>;
+    resendVerification(email: string): Promise<{
+        sent: true;
+    }>;
     changePassword(authId: string, currentPassword: string, newPassword: string): Promise<{
         changed: true;
     }>;
-    private assertAccountNotLocked;
     private assertAccountActive;
     private assertPasswordPolicy;
     private issueTokens;
@@ -188,4 +319,4 @@ declare class AuthService {
     getIdentifierForAccount(account: BaseAuthAccount): string | undefined;
 }
 
-export { AUTH_HOOKS, AUTH_MODULE_OPTIONS, AUTH_RATE_LIMIT_PRESETS, AUTH_REPOSITORY, AuthErrorCode, type AuthErrorCodeValue, AuthHooks, type AuthJwtPayload, AuthModule, AuthModuleAsyncOptions, AuthModuleOptions, type AuthRateLimitPreset, AuthService, AuthTokens, AuthTokensDto, BaseAuthAccount, ChangePasswordDto, CurrentUser, DefaultAuthHooks, ForgotPasswordDto, IAuthRepository, JwtAuthGuard, type JwtPayload, LoginDto, RefreshTokenDto, RegisterAckDto, RegisterDto, RegisterInput, ResetPasswordDto, TokenService, VerifyEmailDto };
+export { AUTH_HOOKS, AUTH_MODULE_OPTIONS, AUTH_RATE_LIMIT_PRESETS, AUTH_RATE_LIMIT_ROUTES, AUTH_REPOSITORY, AuthErrorCode, type AuthErrorCodeValue, AuthFeatures, AuthHooks, type AuthJwtPayload, AuthModule, AuthModuleAsyncOptions, AuthModuleOptions, type AuthRateLimitPreset, type AuthRateLimitRoute, AuthService, type AuthSwaggerOptions, AuthTokens, AuthTokensDto, BaseAuthAccount, ChangePasswordDto, CurrentUser, DefaultAuthHooks, ForgotPasswordDto, IAuthRepository, JwtAuthGuard, type JwtPayload, LoginDto, MeResponseDto, type RefreshTokenCookieOptions, RefreshTokenDto, RegisterAckDto, RegisterDto, RegisterInput, ResendVerificationDto, ResetPasswordDto, TokenService, VerifyEmailDto, buildClearRefreshTokenCookie, buildRefreshTokenCookie, setupAuthSwagger };