@ministerjs/auth 2.0.2 → 3.0.1

package/README.md

@@ -1,19 +1,64 @@
 # @ministerjs/auth
 
-Biblioteca de autenticação com dois alvos:
-- **Vue (front)** — helpers reativos para estado de autenticação.
-- **NestJS (back)** — módulo com controllers e drivers plugáveis (inclui driver padrão JWT + Prisma + cookies).
+Biblioteca de autenticacao JWT com dois alvos:
 
-## Sumário
-- [Uso no front (Vue)](./src/vue/README.md)
-- [Uso no backend (NestJS)](./src/nestjs/README.md)
+- **Vue (front)** — classe reativa para estado de autenticacao, login, signup, logout, checkIn e roles.
+- **NestJS (back)** — modulo com controllers, guards, RBAC, drivers plugaveis e driver padrao JWT + Prisma + cookies.
 
-## Instalação
+## Instalacao
 
 ```bash
 pnpm add @ministerjs/auth
 ```
 
-Escolha o subpath conforme o lado da aplicação:
+Escolha o subpath conforme o lado da aplicacao:
+
 - Front: `@ministerjs/auth/vue`
 - Back: `@ministerjs/auth/nestjs`
+
+## Documentacao
+
+- [Vue (front)](./src/vue/README.md)
+- [NestJS (back)](./src/nestjs/README.md)
+
+## Features
+
+### Seguranca
+
+- Cookie `secure` automatico em producao
+- Pinagem de algoritmo HS256 (sign + verify)
+- Re-assinatura de JWT no checkIn (evita reuso de tokens antigos)
+- CSRF double-submit cookie (opcional)
+- Account lockout com janela temporal (plugavel via `LockoutStore`)
+- Rate limiting hook (`onRateLimitCheck`)
+- Audit logging hook (`onAudit`)
+
+### Autenticacao
+
+- Login com credenciais + comparacao de senha obrigatoria (`comparePassword`)
+- CheckIn (valida sessao ativa via cookie/JWT)
+- Logout com limpeza de cookies e revogacao de tokens
+- SignUp (Vue)
+- Refresh token rotation com `jti` e revogacao automatica
+
+### Autorizacao
+
+- `JwtAuthGuard` — extrai JWT de cookie ou header `Authorization: Bearer`
+- `@Roles()` decorator + `RolesGuard` para RBAC
+- `AuthModule.createGuard()` factory para instanciar guards
+
+### Tipagem
+
+- `LoginPayload`, `JwtAccessPayload`, `JwtRefreshPayload` — tipos JWT exportados
+- `AuthenticatedUser` — tipo do `request.user` populado pelo guard
+- `PrismaModelDelegate` / `PrismaClientLike` — tipagem do client Prisma
+- `AuthDriver<User>` — interface para drivers customizados
+
+## Migration v2 → v3
+
+### Breaking changes
+
+1. **`comparePassword` agora e obrigatorio** — nao existe mais fallback para plain-text.
+2. **`AuthPayload` narrowed** — substituido por `LoginPayload` (`Record<string, string>`). O alias `AuthPayload` continua exportado como deprecated.
+3. **Cookie `secure: true` em producao** — `defaultCookieOptions.secure` agora e `process.env.NODE_ENV === "production"`.
+4. **`NestJsAuthenticationController` removido do `@ministerjs/server`** — use `@ministerjs/auth/nestjs` como substituto.

package/dist/nestjs.d.mts

@@ -1,8 +1,14 @@
 import { Request, Response, CookieOptions } from 'express';
-import { Type, DynamicModule } from '@nestjs/common';
+import * as _nestjs_common from '@nestjs/common';
+import { CanActivate, ExecutionContext, Type, DynamicModule } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
 import { SignOptions } from 'jsonwebtoken';
 
-type AuthPayload = Record<string, any>;
+interface LoginPayload {
+    [key: string]: string;
+}
+/** @deprecated Use LoginPayload */
+type AuthPayload = LoginPayload;
 interface AuthResponse<User> {
     message: string;
     data: User;
@@ -10,11 +16,37 @@ interface AuthResponse<User> {
 interface LogoutResponse {
     message: string;
 }
+interface JwtAccessPayload {
+    sub: string;
+    roles?: string[];
+    iat?: number;
+    exp?: number;
+}
+interface JwtRefreshPayload {
+    sub: string;
+    jti: string;
+    iat?: number;
+    exp?: number;
+}
+interface AuthenticatedUser {
+    id: string;
+    roles: string[];
+    [key: string]: unknown;
+}
+interface AuditEvent {
+    action: "login" | "logout" | "checkin" | "refresh" | "lockout";
+    userId?: string;
+    ip?: string;
+    userAgent?: string;
+    timestamp: Date;
+    success: boolean;
+    metadata?: Record<string, unknown>;
+}
 interface AuthDriver<User = any> {
     /**
      * Deve validar o payload recebido e retornar o usuário autenticado.
      */
-    login(payload: AuthPayload, request: Request, response: Response): Promise<User> | User;
+    login(payload: LoginPayload, request: Request, response: Response): Promise<User> | User;
     /**
      * Deve recuperar o usuário a partir do contexto (cookies, headers, sessão, etc.).
      * Retorne `null` ou `undefined` quando não houver sessão ativa.
@@ -24,15 +56,80 @@ interface AuthDriver<User = any> {
      * Deve encerrar a sessão/tokens do usuário.
      */
     logout(request: Request, response: Response): Promise<void> | void;
+    /**
+     * Renova os tokens usando um refresh token.
+     * Opcional — drivers que não implementam retornam undefined.
+     */
+    refresh?(request: Request, response: Response): Promise<User | null | undefined> | User | null | undefined;
 }
 
 declare const AUTH_DRIVER: unique symbol;
 
+interface LockoutStore {
+    recordFailure(key: string): Promise<void>;
+    getFailures(key: string): Promise<number>;
+    reset(key: string): Promise<void>;
+}
+declare class InMemoryLockoutStore implements LockoutStore {
+    private readonly windowMs;
+    private entries;
+    constructor(windowMs: number);
+    recordFailure(key: string): Promise<void>;
+    getFailures(key: string): Promise<number>;
+    reset(key: string): Promise<void>;
+}
+interface RefreshTokenStore {
+    save(jti: string, userId: string, expiresAt: Date): Promise<void>;
+    find(jti: string): Promise<{
+        userId: string;
+        expiresAt: Date;
+    } | null>;
+    revoke(jti: string): Promise<void>;
+    revokeAll(userId: string): Promise<void>;
+}
+interface RefreshTokenEntry {
+    userId: string;
+    expiresAt: Date;
+}
+declare class InMemoryRefreshTokenStore implements RefreshTokenStore {
+    private tokens;
+    private userJtis;
+    save(jti: string, userId: string, expiresAt: Date): Promise<void>;
+    find(jti: string): Promise<RefreshTokenEntry | null>;
+    revoke(jti: string): Promise<void>;
+    revokeAll(userId: string): Promise<void>;
+}
+
+declare const ROLES_KEY = "ministerjs:roles";
+declare const Roles: (...roles: string[]) => _nestjs_common.CustomDecorator<string>;
+
+interface JwtAuthGuardOptions {
+    jwtSecret: string;
+    cookieName?: string;
+    csrfEnabled?: boolean;
+}
+declare class JwtAuthGuard implements CanActivate {
+    private readonly jwtSecret;
+    private readonly cookieName;
+    private readonly csrfEnabled;
+    constructor(options: JwtAuthGuardOptions);
+    canActivate(context: ExecutionContext): boolean;
+    private extractToken;
+    private validateCsrf;
+}
+
+declare class RolesGuard implements CanActivate {
+    private readonly reflector;
+    constructor(reflector: Reflector);
+    canActivate(context: ExecutionContext): boolean;
+}
+
 declare class AuthController<User extends Record<string, any> = Record<string, any>> {
     private readonly driver;
     constructor(driver: AuthDriver<User>);
     login(body: AuthPayload, request: Request, response: Response): Promise<AuthResponse<User>>;
     checkIn(request: Request, response: Response): Promise<AuthResponse<User>>;
+    refresh(request: Request, response: Response): Promise<AuthResponse<User>>;
     logout(request: Request, response: Response): Promise<LogoutResponse>;
 }
 
@@ -62,10 +159,16 @@ interface AuthModuleAsyncOptions<User = any> {
 declare class AuthModule {
     static register<User = any>(options: AuthModuleOptions<User>): DynamicModule;
     static registerAsync<User = any>(options: AuthModuleAsyncOptions<User>): DynamicModule;
+    static createGuard(options: JwtAuthGuardOptions): JwtAuthGuard;
     private static normalizeDriverProvider;
 }
 
-type PrismaClientLike = Record<string, any>;
+interface PrismaModelDelegate {
+    findUnique(args: {
+        where: Record<string, unknown>;
+    }): Promise<any>;
+}
+type PrismaClientLike = Record<string, PrismaModelDelegate | undefined>;
 interface JwtPrismaDriverOptions {
     prisma: PrismaClientLike;
     /**
@@ -102,12 +205,52 @@ interface JwtPrismaDriverOptions {
     cookieOptions?: Partial<CookieOptions>;
     /**
      * Função de comparação de senha (p.ex. bcrypt.compare).
+     * Obrigatório — não há fallback para comparação em plain-text.
      */
-    comparePassword?: (provided: string, stored: unknown) => Promise<boolean> | boolean;
+    comparePassword: (provided: string, stored: unknown) => Promise<boolean> | boolean;
     /**
      * Permite alterar a shape do usuário retornado.
      */
     transformUser?: <T extends Record<string, any>>(user: T) => any;
+    /**
+     * Habilita proteção CSRF via double-submit cookie.
+     * No login, emite um cookie `csrf_token` (não-httpOnly) que o cliente
+     * deve enviar no header `x-csrf-token` em requisições autenticadas.
+     */
+    csrf?: boolean;
+    /**
+     * Callback de auditoria chamado em cada evento de autenticação.
+     */
+    onAudit?: (event: AuditEvent) => void | Promise<void>;
+    /**
+     * Callback de rate limiting chamado antes de cada tentativa de login.
+     * Retorne `false` para bloquear a tentativa.
+     */
+    onRateLimitCheck?: (ip: string, identifier: string) => Promise<boolean> | boolean;
+    /**
+     * Configuração de account lockout.
+     */
+    lockout?: {
+        /** Número máximo de tentativas antes de bloquear (default: 5). */
+        maxAttempts?: number;
+        /** Janela de tempo em ms para contar falhas (default: 15 min). */
+        windowMs?: number;
+        /** Store customizado para persistir falhas (default: InMemoryLockoutStore). */
+        store?: LockoutStore;
+    };
+    /**
+     * Configuração de refresh token rotation.
+     * Quando habilitado, login emite um par access + refresh token.
+     */
+    refreshToken?: {
+        enabled: boolean;
+        /** Nome do cookie do refresh token (default: "refresh_token"). */
+        cookieName?: string;
+        /** Tempo de expiração do refresh token (default: "30d"). */
+        expiresIn?: SignOptions["expiresIn"];
+        /** Store para persistir refresh tokens (default: InMemoryRefreshTokenStore). */
+        store?: RefreshTokenStore;
+    };
 }
 declare class JwtPrismaCookieAuthDriver<User extends Record<string, any>> implements AuthDriver<User> {
     private readonly prismaModel;
@@ -120,10 +263,22 @@ declare class JwtPrismaCookieAuthDriver<User extends Record<string, any>> implem
     private readonly cookieOptions;
     private readonly comparePassword;
     private readonly transformUser;
+    private readonly csrf;
+    private readonly onAudit?;
+    private readonly onRateLimitCheck?;
+    private readonly lockoutStore?;
+    private readonly lockoutMaxAttempts;
+    private readonly refreshTokenEnabled;
+    private readonly refreshTokenCookieName;
+    private readonly refreshTokenExpiresIn;
+    private readonly refreshTokenStore?;
     constructor(options: JwtPrismaDriverOptions);
-    login(payload: AuthPayload, _req: Request, res: Response): Promise<User>;
+    login(payload: LoginPayload, req: Request, res: Response): Promise<User>;
     checkIn(req: Request, res: Response): Promise<User | null>;
-    logout(_req: Request, res: Response): Promise<void>;
+    logout(req: Request, res: Response): Promise<void>;
+    refresh(req: Request, res: Response): Promise<User | null>;
+    private issueRefreshToken;
+    private emitAudit;
 }
 
-export { AUTH_DRIVER, AuthController, type AuthDriver, AuthModule, type AuthModuleAsyncOptions, type AuthModuleOptions, type AuthPayload, type AuthResponse, type DriverProvider, JwtPrismaCookieAuthDriver, type JwtPrismaDriverOptions, type LogoutResponse };
+export { AUTH_DRIVER, type AuditEvent, AuthController, type AuthDriver, AuthModule, type AuthModuleAsyncOptions, type AuthModuleOptions, type AuthPayload, type AuthResponse, type AuthenticatedUser, type DriverProvider, InMemoryLockoutStore, InMemoryRefreshTokenStore, type JwtAccessPayload, JwtAuthGuard, type JwtAuthGuardOptions, JwtPrismaCookieAuthDriver, type JwtPrismaDriverOptions, type JwtRefreshPayload, type LockoutStore, type LoginPayload, type LogoutResponse, type PrismaClientLike, type PrismaModelDelegate, ROLES_KEY, type RefreshTokenStore, Roles, RolesGuard };

package/dist/nestjs.d.ts

@@ -1,8 +1,14 @@
 import { Request, Response, CookieOptions } from 'express';
-import { Type, DynamicModule } from '@nestjs/common';
+import * as _nestjs_common from '@nestjs/common';
+import { CanActivate, ExecutionContext, Type, DynamicModule } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
 import { SignOptions } from 'jsonwebtoken';
 
-type AuthPayload = Record<string, any>;
+interface LoginPayload {
+    [key: string]: string;
+}
+/** @deprecated Use LoginPayload */
+type AuthPayload = LoginPayload;
 interface AuthResponse<User> {
     message: string;
     data: User;
@@ -10,11 +16,37 @@ interface AuthResponse<User> {
 interface LogoutResponse {
     message: string;
 }
+interface JwtAccessPayload {
+    sub: string;
+    roles?: string[];
+    iat?: number;
+    exp?: number;
+}
+interface JwtRefreshPayload {
+    sub: string;
+    jti: string;
+    iat?: number;
+    exp?: number;
+}
+interface AuthenticatedUser {
+    id: string;
+    roles: string[];
+    [key: string]: unknown;
+}
+interface AuditEvent {
+    action: "login" | "logout" | "checkin" | "refresh" | "lockout";
+    userId?: string;
+    ip?: string;
+    userAgent?: string;
+    timestamp: Date;
+    success: boolean;
+    metadata?: Record<string, unknown>;
+}
 interface AuthDriver<User = any> {
     /**
      * Deve validar o payload recebido e retornar o usuário autenticado.
      */
-    login(payload: AuthPayload, request: Request, response: Response): Promise<User> | User;
+    login(payload: LoginPayload, request: Request, response: Response): Promise<User> | User;
     /**
      * Deve recuperar o usuário a partir do contexto (cookies, headers, sessão, etc.).
      * Retorne `null` ou `undefined` quando não houver sessão ativa.
@@ -24,15 +56,80 @@ interface AuthDriver<User = any> {
      * Deve encerrar a sessão/tokens do usuário.
      */
     logout(request: Request, response: Response): Promise<void> | void;
+    /**
+     * Renova os tokens usando um refresh token.
+     * Opcional — drivers que não implementam retornam undefined.
+     */
+    refresh?(request: Request, response: Response): Promise<User | null | undefined> | User | null | undefined;
 }
 
 declare const AUTH_DRIVER: unique symbol;
 
+interface LockoutStore {
+    recordFailure(key: string): Promise<void>;
+    getFailures(key: string): Promise<number>;
+    reset(key: string): Promise<void>;
+}
+declare class InMemoryLockoutStore implements LockoutStore {
+    private readonly windowMs;
+    private entries;
+    constructor(windowMs: number);
+    recordFailure(key: string): Promise<void>;
+    getFailures(key: string): Promise<number>;
+    reset(key: string): Promise<void>;
+}
+interface RefreshTokenStore {
+    save(jti: string, userId: string, expiresAt: Date): Promise<void>;
+    find(jti: string): Promise<{
+        userId: string;
+        expiresAt: Date;
+    } | null>;
+    revoke(jti: string): Promise<void>;
+    revokeAll(userId: string): Promise<void>;
+}
+interface RefreshTokenEntry {
+    userId: string;
+    expiresAt: Date;
+}
+declare class InMemoryRefreshTokenStore implements RefreshTokenStore {
+    private tokens;
+    private userJtis;
+    save(jti: string, userId: string, expiresAt: Date): Promise<void>;
+    find(jti: string): Promise<RefreshTokenEntry | null>;
+    revoke(jti: string): Promise<void>;
+    revokeAll(userId: string): Promise<void>;
+}
+
+declare const ROLES_KEY = "ministerjs:roles";
+declare const Roles: (...roles: string[]) => _nestjs_common.CustomDecorator<string>;
+
+interface JwtAuthGuardOptions {
+    jwtSecret: string;
+    cookieName?: string;
+    csrfEnabled?: boolean;
+}
+declare class JwtAuthGuard implements CanActivate {
+    private readonly jwtSecret;
+    private readonly cookieName;
+    private readonly csrfEnabled;
+    constructor(options: JwtAuthGuardOptions);
+    canActivate(context: ExecutionContext): boolean;
+    private extractToken;
+    private validateCsrf;
+}
+
+declare class RolesGuard implements CanActivate {
+    private readonly reflector;
+    constructor(reflector: Reflector);
+    canActivate(context: ExecutionContext): boolean;
+}
+
 declare class AuthController<User extends Record<string, any> = Record<string, any>> {
     private readonly driver;
     constructor(driver: AuthDriver<User>);
     login(body: AuthPayload, request: Request, response: Response): Promise<AuthResponse<User>>;
     checkIn(request: Request, response: Response): Promise<AuthResponse<User>>;
+    refresh(request: Request, response: Response): Promise<AuthResponse<User>>;
     logout(request: Request, response: Response): Promise<LogoutResponse>;
 }
 
@@ -62,10 +159,16 @@ interface AuthModuleAsyncOptions<User = any> {
 declare class AuthModule {
     static register<User = any>(options: AuthModuleOptions<User>): DynamicModule;
     static registerAsync<User = any>(options: AuthModuleAsyncOptions<User>): DynamicModule;
+    static createGuard(options: JwtAuthGuardOptions): JwtAuthGuard;
     private static normalizeDriverProvider;
 }
 
-type PrismaClientLike = Record<string, any>;
+interface PrismaModelDelegate {
+    findUnique(args: {
+        where: Record<string, unknown>;
+    }): Promise<any>;
+}
+type PrismaClientLike = Record<string, PrismaModelDelegate | undefined>;
 interface JwtPrismaDriverOptions {
     prisma: PrismaClientLike;
     /**
@@ -102,12 +205,52 @@ interface JwtPrismaDriverOptions {
     cookieOptions?: Partial<CookieOptions>;
     /**
      * Função de comparação de senha (p.ex. bcrypt.compare).
+     * Obrigatório — não há fallback para comparação em plain-text.
      */
-    comparePassword?: (provided: string, stored: unknown) => Promise<boolean> | boolean;
+    comparePassword: (provided: string, stored: unknown) => Promise<boolean> | boolean;
     /**
      * Permite alterar a shape do usuário retornado.
      */
     transformUser?: <T extends Record<string, any>>(user: T) => any;
+    /**
+     * Habilita proteção CSRF via double-submit cookie.
+     * No login, emite um cookie `csrf_token` (não-httpOnly) que o cliente
+     * deve enviar no header `x-csrf-token` em requisições autenticadas.
+     */
+    csrf?: boolean;
+    /**
+     * Callback de auditoria chamado em cada evento de autenticação.
+     */
+    onAudit?: (event: AuditEvent) => void | Promise<void>;
+    /**
+     * Callback de rate limiting chamado antes de cada tentativa de login.
+     * Retorne `false` para bloquear a tentativa.
+     */
+    onRateLimitCheck?: (ip: string, identifier: string) => Promise<boolean> | boolean;
+    /**
+     * Configuração de account lockout.
+     */
+    lockout?: {
+        /** Número máximo de tentativas antes de bloquear (default: 5). */
+        maxAttempts?: number;
+        /** Janela de tempo em ms para contar falhas (default: 15 min). */
+        windowMs?: number;
+        /** Store customizado para persistir falhas (default: InMemoryLockoutStore). */
+        store?: LockoutStore;
+    };
+    /**
+     * Configuração de refresh token rotation.
+     * Quando habilitado, login emite um par access + refresh token.
+     */
+    refreshToken?: {
+        enabled: boolean;
+        /** Nome do cookie do refresh token (default: "refresh_token"). */
+        cookieName?: string;
+        /** Tempo de expiração do refresh token (default: "30d"). */
+        expiresIn?: SignOptions["expiresIn"];
+        /** Store para persistir refresh tokens (default: InMemoryRefreshTokenStore). */
+        store?: RefreshTokenStore;
+    };
 }
 declare class JwtPrismaCookieAuthDriver<User extends Record<string, any>> implements AuthDriver<User> {
     private readonly prismaModel;
@@ -120,10 +263,22 @@ declare class JwtPrismaCookieAuthDriver<User extends Record<string, any>> implem
     private readonly cookieOptions;
     private readonly comparePassword;
     private readonly transformUser;
+    private readonly csrf;
+    private readonly onAudit?;
+    private readonly onRateLimitCheck?;
+    private readonly lockoutStore?;
+    private readonly lockoutMaxAttempts;
+    private readonly refreshTokenEnabled;
+    private readonly refreshTokenCookieName;
+    private readonly refreshTokenExpiresIn;
+    private readonly refreshTokenStore?;
     constructor(options: JwtPrismaDriverOptions);
-    login(payload: AuthPayload, _req: Request, res: Response): Promise<User>;
+    login(payload: LoginPayload, req: Request, res: Response): Promise<User>;
     checkIn(req: Request, res: Response): Promise<User | null>;
-    logout(_req: Request, res: Response): Promise<void>;
+    logout(req: Request, res: Response): Promise<void>;
+    refresh(req: Request, res: Response): Promise<User | null>;
+    private issueRefreshToken;
+    private emitAudit;
 }
 
-export { AUTH_DRIVER, AuthController, type AuthDriver, AuthModule, type AuthModuleAsyncOptions, type AuthModuleOptions, type AuthPayload, type AuthResponse, type DriverProvider, JwtPrismaCookieAuthDriver, type JwtPrismaDriverOptions, type LogoutResponse };
+export { AUTH_DRIVER, type AuditEvent, AuthController, type AuthDriver, AuthModule, type AuthModuleAsyncOptions, type AuthModuleOptions, type AuthPayload, type AuthResponse, type AuthenticatedUser, type DriverProvider, InMemoryLockoutStore, InMemoryRefreshTokenStore, type JwtAccessPayload, JwtAuthGuard, type JwtAuthGuardOptions, JwtPrismaCookieAuthDriver, type JwtPrismaDriverOptions, type JwtRefreshPayload, type LockoutStore, type LoginPayload, type LogoutResponse, type PrismaClientLike, type PrismaModelDelegate, ROLES_KEY, type RefreshTokenStore, Roles, RolesGuard };