@aranzatech/aranza-auth 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-03
+
+First public release.
+
+### Added
+
+- **`AuthModule.forRoot` / `forRootAsync`** — módulo dinámico global con configuración JWT.
+- **Endpoints REST** bajo `/auth`:
+  - `POST /auth/register` — alta de cuenta
+  - `POST /auth/login` — login con access + refresh token
+  - `POST /auth/refresh` — renovación de tokens
+  - `POST /auth/logout` — invalidar refresh token (Bearer)
+  - `GET /auth/me` — usuario autenticado (Bearer)
+  - `POST /auth/verify-email` — verificación de email (opt-in)
+  - `POST /auth/forgot-password` — solicitar reset (opt-in)
+  - `POST /auth/reset-password` — nueva contraseña con token (opt-in)
+- **`AuthService`**, **`TokenService`**, **`JwtStrategy`**, **`JwtAuthGuard`**, decorador **`@CurrentUser()`**.
+- **Feature flags** (`features`) — todo desactivado por defecto, ideal para POCs:
+  - `emailVerification` — bloquea login hasta verificar email
+  - `passwordReset` — habilita forgot/reset password
+  - `refreshTokenRotation` — rota hash del refresh token en DB (default: `true`)
+- **`AuthHooks`** — extiende JWT payload, `/auth/me`, lifecycle y envío de emails.
+- **`DefaultAuthHooks`** — implementación mínima incluida.
+- **Adapter MongoDB** (`@aranzatech/aranza-auth/mongo`):
+  - `BaseAuthAccountSchema` — schema base extensible
+  - `MongoAuthRepository` — implementación de `IAuthRepository`
+  - `MongoAuthModule.forFeature()` — registro de schema + repository
+- Tokens de verificación/reset hasheados (SHA-256) con TTL configurable.
+- Build dual ESM/CJS con types (`tsup`), tests (`vitest`), CI GitHub Actions.
+
+[Unreleased]: https://github.com/aapa96/aranza-auth/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/aapa96/aranza-auth/releases/tag/v0.1.0

package/README.md

@@ -0,0 +1,468 @@
+# @aranzatech/aranza-auth
+
+Módulo de autenticación **extensible** para NestJS. JWT, refresh tokens, register/login y adapter MongoDB — sin acoplar tu dominio (org, roles, users, etc.).
+
+Ideal para reutilizar auth en todos tus proyectos AranzaTech: instalas, configuras, extiendes el modelo y listo.
+
+---
+
+## Tabla de contenidos
+
+- [Instalación](#instalación)
+- [Inicio rápido (5 minutos)](#inicio-rápido-5-minutos)
+- [Variables de entorno](#variables-de-entorno)
+- [Configuración del módulo](#configuración-del-módulo)
+- [Feature flags](#feature-flags)
+- [Endpoints](#endpoints)
+- [Proteger rutas propias](#proteger-rutas-propias)
+- [Extender con AuthHooks](#extender-con-authhooks)
+- [Extender el schema MongoDB](#extender-el-schema-mongodb)
+- [Flujos opcionales (email y password)](#flujos-opcionales-email-y-password)
+- [Exports públicos](#exports-públicos)
+- [Requisitos del proyecto consumidor](#requisitos-del-proyecto-consumidor)
+- [Limitaciones conocidas (v0.1.0)](#limitaciones-conocidas-v010)
+- [Roadmap](#roadmap)
+- [Licencia](#licencia)
+
+---
+
+## Instalación
+
+```bash
+npm install @aranzatech/aranza-auth
+```
+
+**Peer dependencies** (instalar en tu app Nest):
+
+```bash
+npm install @nestjs/common @nestjs/core @nestjs/jwt @nestjs/passport \
+  @nestjs/mongoose mongoose passport passport-jwt bcryptjs \
+  class-validator class-transformer reflect-metadata
+```
+
+> NestJS **11+** recomendado.
+
+---
+
+## Inicio rápido (5 minutos)
+
+### 1. Variables de entorno
+
+```env
+MONGODB_URI=mongodb://localhost:27017/myapp
+JWT_SECRET=your-access-secret-min-32-chars
+JWT_REFRESH_SECRET=your-refresh-secret-min-32-chars
+```
+
+### 2. Conectar el módulo
+
+```typescript
+// app.module.ts
+import { Module } from "@nestjs/common";
+import { ConfigModule, ConfigService } from "@nestjs/config";
+import { MongooseModule } from "@nestjs/mongoose";
+import { AuthModule } from "@aranzatech/aranza-auth";
+import { MongoAuthModule } from "@aranzatech/aranza-auth/mongo";
+
+@Module({
+  imports: [
+    ConfigModule.forRoot({ isGlobal: true }),
+    MongooseModule.forRoot(process.env.MONGODB_URI!),
+    MongoAuthModule.forFeature(),
+    AuthModule.forRootAsync({
+      imports: [ConfigModule],
+      inject: [ConfigService],
+      useFactory: (config: ConfigService) => ({
+        secret: config.getOrThrow("JWT_SECRET"),
+        refreshSecret: config.getOrThrow("JWT_REFRESH_SECRET"),
+        expiresIn: "1h",
+        refreshExpiresIn: "7d",
+        identifierField: "email",
+      }),
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### 3. Habilitar validación global (requerido)
+
+Los DTOs usan `class-validator`. Activa el pipe global en `main.ts`:
+
+```typescript
+import { ValidationPipe } from "@nestjs/common";
+
+app.useGlobalPipes(
+  new ValidationPipe({ whitelist: true, transform: true }),
+);
+```
+
+### 4. Probar
+
+```bash
+# Register
+curl -X POST http://localhost:3000/auth/register \
+  -H "Content-Type: application/json" \
+  -d '{"email":"user@example.com","password":"SecurePass123!"}'
+
+# Login
+curl -X POST http://localhost:3000/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"email":"user@example.com","password":"SecurePass123!"}'
+
+# Me (usa el accessToken del login)
+curl http://localhost:3000/auth/me \
+  -H "Authorization: Bearer <accessToken>"
+```
+
+Con eso ya tienes auth funcional para un POC.
+
+---
+
+## Variables de entorno
+
+| Variable | Requerida | Descripción |
+|----------|-----------|-------------|
+| `MONGODB_URI` | Sí | Connection string de MongoDB |
+| `JWT_SECRET` | Sí | Secret para access tokens |
+| `JWT_REFRESH_SECRET` | Sí | Secret para refresh tokens (distinto al anterior) |
+| `FRONTEND_URL` | No | Base URL para links en emails (verify/reset) |
+
+---
+
+## Configuración del módulo
+
+`AuthModule.forRootAsync()` acepta un objeto `AuthModuleOptions`:
+
+```typescript
+AuthModule.forRootAsync({
+  imports: [ConfigModule],
+  inject: [ConfigService],
+  useFactory: (config: ConfigService) => ({
+    // ── JWT (requerido) ──────────────────────────────────
+    secret: config.getOrThrow("JWT_SECRET"),
+    refreshSecret: config.getOrThrow("JWT_REFRESH_SECRET"),
+    expiresIn: "1h",           // access token  (default: "1h")
+    refreshExpiresIn: "7d",    // refresh token (default: "7d")
+
+    // ── Identificador de login ───────────────────────────
+    identifierField: "email",  // "email" | "username" (default: "email")
+
+    // ── Features opcionales ──────────────────────────────
+    features: {
+      emailVerification: false,   // default: false
+      passwordReset: false,       // default: false
+      refreshTokenRotation: true,   // default: true
+    },
+
+    // ── TTL de tokens de email/reset ─────────────────────
+    emailVerificationTokenTtlMs: 24 * 60 * 60 * 1000,  // 24h
+    passwordResetTokenTtlMs: 15 * 60 * 1000,           // 15min
+
+    // ── Hooks personalizados ─────────────────────────────
+    hooks: AppAuthHooks,  // default: DefaultAuthHooks
+  }),
+}),
+```
+
+### Orden de imports
+
+`MongoAuthModule.forFeature()` debe importarse **junto** con `AuthModule`. El orden recomendado:
+
+```typescript
+imports: [
+  MongooseModule.forRoot(...),
+  MongoAuthModule.forFeature(...),  // provee AUTH_REPOSITORY
+  AuthModule.forRootAsync(...),       // consume AUTH_REPOSITORY
+]
+```
+
+---
+
+## Feature flags
+
+Todo está **desactivado por defecto**. Sin declarar `features`, obtienes el mínimo para POCs.
+
+| Flag | Default | Qué hace |
+|------|---------|----------|
+| `emailVerification` | `false` | Envía email al register, bloquea login hasta verificar |
+| `passwordReset` | `false` | Habilita `forgot-password` y `reset-password` |
+| `refreshTokenRotation` | `true` | Guarda hash del refresh token en DB y lo rota |
+
+### Modo POC (solo login/register)
+
+```typescript
+// No declares features — o déjalo vacío:
+AuthModule.forRootAsync({
+  useFactory: () => ({
+    secret: "...",
+    refreshSecret: "...",
+  }),
+}),
+```
+
+- Register crea cuenta con `emailVerified: true` → login inmediato.
+- Endpoints `verify-email`, `forgot-password`, `reset-password` responden **404**.
+
+### Modo producción
+
+```typescript
+features: {
+  emailVerification: true,
+  passwordReset: true,
+  refreshTokenRotation: true,
+},
+hooks: AppAuthHooks,  // debe implementar sendEmail
+```
+
+> Si activas `emailVerification` o `passwordReset`, **debes** implementar `AuthHooks.sendEmail`. Si no, register/forgot fallará con un error claro.
+
+---
+
+## Endpoints
+
+| Método | Ruta | Auth | Feature | Body | Respuesta |
+|--------|------|------|---------|------|-----------|
+| `POST` | `/auth/register` | — | — | `{ email?, username?, password }` | `{ registered: true }` |
+| `POST` | `/auth/login` | — | — | `{ email?, username?, password }` | `{ accessToken, refreshToken }` |
+| `POST` | `/auth/refresh` | — | — | `{ refreshToken }` | `{ accessToken, refreshToken }` |
+| `POST` | `/auth/logout` | Bearer | — | — | `{ loggedOut: true }` |
+| `GET` | `/auth/me` | Bearer | — | — | objeto enriquecido via hooks |
+| `POST` | `/auth/verify-email` | — | `emailVerification` | `{ token }` | `{ verified: true }` |
+| `POST` | `/auth/forgot-password` | — | `passwordReset` | `{ email }` | `{ sent: true }` |
+| `POST` | `/auth/reset-password` | — | `passwordReset` | `{ token, newPassword }` | `{ reset: true }` |
+
+### Errores comunes
+
+| Código | Mensaje | Causa |
+|--------|---------|-------|
+| `401` | `Invalid credentials` | Email/username o password incorrectos |
+| `401` | `EMAIL_NOT_VERIFIED` | Feature `emailVerification` activa y email sin verificar |
+| `401` | `ACCOUNT_DISABLED` | Cuenta desactivada |
+| `401` | `Invalid refresh token` | Refresh expirado, revocado o inválido |
+| `404` | — | Feature desactivada (endpoint no disponible) |
+| `400` | `TOKEN_INVALID_OR_EXPIRED` | Token de verify/reset inválido o expirado |
+
+---
+
+## Proteger rutas propias
+
+Usa el guard y el decorador exportados por la lib:
+
+```typescript
+import { Controller, Get, UseGuards } from "@nestjs/common";
+import {
+  JwtAuthGuard,
+  CurrentUser,
+  type AuthJwtPayload,
+} from "@aranzatech/aranza-auth";
+
+@Controller("projects")
+export class ProjectsController {
+  @Get()
+  @UseGuards(JwtAuthGuard)
+  list(@CurrentUser() user: AuthJwtPayload) {
+    // user.sub  → ID de la cuenta auth
+    // user.email, user.orgId, etc. → lo que agregues en buildJwtPayload
+    return { ownerId: user.sub };
+  }
+}
+```
+
+También puedes registrar `JwtAuthGuard` como guard global:
+
+```typescript
+{ provide: APP_GUARD, useClass: JwtAuthGuard }
+```
+
+---
+
+## Extender con AuthHooks
+
+La lib maneja auth genérico. Tu dominio (org, roles, users) va en **hooks**:
+
+```typescript
+// app-auth.hooks.ts
+import { Injectable } from "@nestjs/common";
+import type { AuthHooks, BaseAuthAccount } from "@aranzatech/aranza-auth";
+
+interface MyAuthAccount extends BaseAuthAccount {
+  orgId: string;
+  roleId: string;
+}
+
+@Injectable()
+export class AppAuthHooks implements AuthHooks<MyAuthAccount> {
+  constructor(private readonly orgService: OrgService) {}
+
+  /** Campos extra en el JWT */
+  async buildJwtPayload(account: MyAuthAccount) {
+    return {
+      orgId: account.orgId,
+      roleId: account.roleId,
+    };
+  }
+
+  /** Respuesta de GET /auth/me */
+  async enrichMe(account: MyAuthAccount) {
+    const org = await this.orgService.findById(account.orgId);
+    return {
+      id: account.id,
+      email: account.email,
+      org: { id: org.id, name: org.name },
+    };
+  }
+
+  /** Validaciones antes de crear cuenta */
+  async onBeforeRegister(input) {
+    // ej: verificar invitación, orgId, etc.
+  }
+
+  /** Envío de emails (requerido si activas emailVerification o passwordReset) */
+  async sendEmail(type: "verify" | "reset", to: string, token: string) {
+    const base = process.env.FRONTEND_URL ?? "http://localhost:3001";
+    const path = type === "verify" ? "verify-email" : "reset-password";
+    const url = `${base}/auth/${path}?token=${token}`;
+    // await this.mailer.send({ to, subject: "...", html: url });
+  }
+}
+```
+
+Registra los hooks en la config:
+
+```typescript
+AuthModule.forRootAsync({
+  useFactory: () => ({
+    secret: "...",
+    refreshSecret: "...",
+    hooks: AppAuthHooks,
+  }),
+}),
+```
+
+### Métodos disponibles en AuthHooks
+
+| Método | Cuándo se ejecuta | Requerido |
+|--------|-------------------|-----------|
+| `buildJwtPayload` | Login, refresh | Sí |
+| `enrichMe` | GET /auth/me | No (usa default) |
+| `onBeforeRegister` | Antes de crear cuenta | No |
+| `onAfterRegister` | Después de crear cuenta | No |
+| `onAfterLogin` | Después de login exitoso | No |
+| `sendEmail` | Register (verify) o forgot (reset) | Sí si features de email activas |
+
+---
+
+## Extender el schema MongoDB
+
+El schema base incluye: `email`, `username`, `passwordHash`, `refreshTokenHash`, `emailVerified`, `disabled` y campos de tokens.
+
+### Agregar campos de dominio
+
+```typescript
+import { Prop, Schema, SchemaFactory } from "@nestjs/mongoose";
+import { Types } from "mongoose";
+import { baseAuthAccountSchema } from "@aranzatech/aranza-auth/mongo";
+
+@Schema()
+export class AuthAccount {
+  @Prop({ type: Types.ObjectId, ref: "Organization", required: true })
+  orgId!: Types.ObjectId;
+
+  @Prop({ type: Types.ObjectId, ref: "Role", required: true })
+  roleId!: Types.ObjectId;
+}
+
+export const AuthAccountSchema = SchemaFactory.createForClass(AuthAccount);
+AuthAccountSchema.add(baseAuthAccountSchema);
+```
+
+### Registrar schema extendido
+
+```typescript
+import { AuthAccount, AuthAccountSchema } from "./schemas/auth-account.schema";
+
+MongoAuthModule.forFeature({
+  name: AuthAccount.name,
+  schema: AuthAccountSchema,
+  identifierField: "username",  // si login es por username
+}),
+```
+
+> `identifierField` en `MongoAuthModule.forFeature()` debe coincidir con el de `AuthModule`.
+
+---
+
+## Flujos opcionales (email y password)
+
+### Verificación de email
+
+1. Activa `features.emailVerification: true`
+2. Implementa `sendEmail` en hooks
+3. Register envía email con token → usuario visita link → `POST /auth/verify-email` con `{ token }`
+4. Login bloqueado hasta `emailVerified: true`
+
+Si usas `identifierField: "username"`, el register **debe incluir `email`** además del username.
+
+### Forgot / Reset password
+
+1. Activa `features.passwordReset: true`
+2. Implementa `sendEmail` en hooks
+3. `POST /auth/forgot-password` con `{ email }` → siempre responde `{ sent: true }` (no revela si el email existe)
+4. Usuario recibe link → `POST /auth/reset-password` con `{ token, newPassword }`
+5. Reset invalida refresh tokens activos
+
+---
+
+## Exports públicos
+
+| Import | Contenido |
+|--------|-----------|
+| `@aranzatech/aranza-auth` | `AuthModule`, `AuthService`, guards, DTOs, interfaces, tokens |
+| `@aranzatech/aranza-auth/mongo` | `MongoAuthModule`, `MongoAuthRepository`, schemas |
+
+### Tokens de inyección
+
+```typescript
+import { AUTH_MODULE_OPTIONS, AUTH_HOOKS, AUTH_REPOSITORY } from "@aranzatech/aranza-auth";
+```
+
+Útiles si necesitas acceder a config o reemplazar el repository manualmente.
+
+---
+
+## Requisitos del proyecto consumidor
+
+- [ ] NestJS 11+
+- [ ] `ValidationPipe` global activo
+- [ ] `reflect-metadata` importado al inicio de `main.ts`
+- [ ] MongoDB conectado via `@nestjs/mongoose`
+- [ ] `MongoAuthModule.forFeature()` importado antes o junto a `AuthModule`
+- [ ] Secrets JWT distintos para access y refresh
+- [ ] Si usas features de email: implementar `AuthHooks.sendEmail`
+
+---
+
+## Limitaciones conocidas (v0.1.0)
+
+| Limitación | Workaround / versión futura |
+|------------|----------------------------|
+| Hooks se instancian con `new HooksClass()` sin DI de Nest | Registrar servicios manualmente o v0.2.0 con DI |
+| Ruta fija `/auth` (routePrefix en config aún no aplicado) | Usar global prefix de Nest o v0.2.0 |
+| Solo adapter MongoDB | Prisma en v0.3.0 |
+| Sin OAuth (Google, GitHub, etc.) | v0.2.0 |
+| Sin `change-password` autenticado | v0.2.0 |
+
+---
+
+## Roadmap
+
+- [ ] **0.2.0** — OAuth (Google, GitHub), `change-password`, hooks con DI
+- [ ] **0.3.0** — Adapter Prisma
+- [ ] **0.4.0** — Migración de AranzaFlow como caso de referencia
+
+---
+
+## Licencia
+
+MIT © [AranzaTech](https://github.com/aapa96)

package/dist/auth-repository.interface-BMlJc-98.d.cts

@@ -0,0 +1,90 @@
+interface BaseAuthAccount {
+    id: string;
+    email?: string;
+    username?: string;
+    emailVerified: boolean;
+    disabled: boolean;
+    createdAt?: Date;
+    updatedAt?: Date;
+}
+/** Internal shape returned by repository secret lookups. */
+interface AuthAccountWithSecrets extends BaseAuthAccount {
+    passwordHash?: string;
+    refreshTokenHash?: string | null;
+}
+interface RegisterInput {
+    email?: string;
+    username?: string;
+    password: string;
+}
+interface AuthTokens {
+    accessToken: string;
+    refreshToken: string;
+}
+interface AuthHooks<TAccount extends BaseAuthAccount = BaseAuthAccount> {
+    buildJwtPayload(account: TAccount): Promise<Record<string, unknown>>;
+    onBeforeRegister?(input: RegisterInput): Promise<void>;
+    onAfterRegister?(account: TAccount): Promise<void>;
+    onAfterLogin?(account: TAccount): Promise<void>;
+    enrichMe?(account: TAccount): Promise<Record<string, unknown>>;
+    sendEmail?(type: "verify" | "reset", to: string, token: string): Promise<void>;
+}
+
+type AuthIdentifierField = "email" | "username";
+interface AuthFeatures {
+    /** Require verified email before login. Sends verification email on register. Default: `false`. */
+    emailVerification?: boolean;
+    /** Enable forgot/reset password endpoints. Default: `false`. */
+    passwordReset?: boolean;
+    /** Rotate refresh token hash on login/refresh. Default: `true`. */
+    refreshTokenRotation?: boolean;
+}
+interface AuthJwtConfig {
+    secret: string;
+    expiresIn?: string;
+    refreshSecret: string;
+    refreshExpiresIn?: string;
+}
+interface AuthModuleOptions extends AuthJwtConfig {
+    /** Field used for login/register lookup. Default: `email`. */
+    identifierField?: AuthIdentifierField;
+    /** Optional feature flags — all off by default (POC-friendly). */
+    features?: AuthFeatures;
+    /** Email verification token TTL in ms. Default: 24h. */
+    emailVerificationTokenTtlMs?: number;
+    /** Password reset token TTL in ms. Default: 15min. */
+    passwordResetTokenTtlMs?: number;
+    /** Route prefix for auth controller. Default: `auth`. */
+    routePrefix?: string;
+    /** Custom hooks class. Defaults to built-in minimal payload. */
+    hooks?: new (...args: any[]) => AuthHooks;
+}
+interface AuthModuleAsyncOptions {
+    imports?: unknown[];
+    inject?: unknown[];
+    useFactory: (...args: unknown[]) => AuthModuleOptions | Promise<AuthModuleOptions>;
+}
+
+interface CreateAccountData extends RegisterInput {
+    passwordHash: string;
+    /** When `false`, account can login immediately. Default decided by AuthService. */
+    emailVerified?: boolean;
+}
+interface IAuthRepository<TAccount extends BaseAuthAccount = BaseAuthAccount> {
+    create(data: CreateAccountData): Promise<TAccount>;
+    findByIdentifier(identifier: string): Promise<TAccount | null>;
+    findByEmail(email: string): Promise<BaseAuthAccount | null>;
+    findByIdentifierWithSecrets(identifier: string): Promise<AuthAccountWithSecrets | null>;
+    findById(id: string): Promise<BaseAuthAccount | null>;
+    findByIdWithSecrets(id: string): Promise<AuthAccountWithSecrets | null>;
+    updateRefreshTokenHash(id: string, hash: string | null): Promise<void>;
+    updatePasswordHash(id: string, passwordHash: string): Promise<void>;
+    setEmailVerificationToken(id: string, tokenHash: string, expiresAt: Date): Promise<void>;
+    findByEmailVerificationTokenHash(tokenHash: string): Promise<BaseAuthAccount | null>;
+    markEmailVerified(id: string): Promise<void>;
+    setResetToken(id: string, tokenHash: string, expiresAt: Date): Promise<void>;
+    findByResetTokenHash(tokenHash: string): Promise<AuthAccountWithSecrets | null>;
+    clearResetToken(id: string): Promise<void>;
+}
+
+export type { AuthModuleOptions as A, BaseAuthAccount as B, CreateAccountData as C, IAuthRepository as I, RegisterInput as R, AuthModuleAsyncOptions as a, AuthHooks as b, AuthTokens as c, AuthAccountWithSecrets as d, AuthFeatures as e, AuthIdentifierField as f, AuthJwtConfig as g };

package/dist/auth-repository.interface-BMlJc-98.d.ts

@@ -0,0 +1,90 @@
+interface BaseAuthAccount {
+    id: string;
+    email?: string;
+    username?: string;
+    emailVerified: boolean;
+    disabled: boolean;
+    createdAt?: Date;
+    updatedAt?: Date;
+}
+/** Internal shape returned by repository secret lookups. */
+interface AuthAccountWithSecrets extends BaseAuthAccount {
+    passwordHash?: string;
+    refreshTokenHash?: string | null;
+}
+interface RegisterInput {
+    email?: string;
+    username?: string;
+    password: string;
+}
+interface AuthTokens {
+    accessToken: string;
+    refreshToken: string;
+}
+interface AuthHooks<TAccount extends BaseAuthAccount = BaseAuthAccount> {
+    buildJwtPayload(account: TAccount): Promise<Record<string, unknown>>;
+    onBeforeRegister?(input: RegisterInput): Promise<void>;
+    onAfterRegister?(account: TAccount): Promise<void>;
+    onAfterLogin?(account: TAccount): Promise<void>;
+    enrichMe?(account: TAccount): Promise<Record<string, unknown>>;
+    sendEmail?(type: "verify" | "reset", to: string, token: string): Promise<void>;
+}
+
+type AuthIdentifierField = "email" | "username";
+interface AuthFeatures {
+    /** Require verified email before login. Sends verification email on register. Default: `false`. */
+    emailVerification?: boolean;
+    /** Enable forgot/reset password endpoints. Default: `false`. */
+    passwordReset?: boolean;
+    /** Rotate refresh token hash on login/refresh. Default: `true`. */
+    refreshTokenRotation?: boolean;
+}
+interface AuthJwtConfig {
+    secret: string;
+    expiresIn?: string;
+    refreshSecret: string;
+    refreshExpiresIn?: string;
+}
+interface AuthModuleOptions extends AuthJwtConfig {
+    /** Field used for login/register lookup. Default: `email`. */
+    identifierField?: AuthIdentifierField;
+    /** Optional feature flags — all off by default (POC-friendly). */
+    features?: AuthFeatures;
+    /** Email verification token TTL in ms. Default: 24h. */
+    emailVerificationTokenTtlMs?: number;
+    /** Password reset token TTL in ms. Default: 15min. */
+    passwordResetTokenTtlMs?: number;
+    /** Route prefix for auth controller. Default: `auth`. */
+    routePrefix?: string;
+    /** Custom hooks class. Defaults to built-in minimal payload. */
+    hooks?: new (...args: any[]) => AuthHooks;
+}
+interface AuthModuleAsyncOptions {
+    imports?: unknown[];
+    inject?: unknown[];
+    useFactory: (...args: unknown[]) => AuthModuleOptions | Promise<AuthModuleOptions>;
+}
+
+interface CreateAccountData extends RegisterInput {
+    passwordHash: string;
+    /** When `false`, account can login immediately. Default decided by AuthService. */
+    emailVerified?: boolean;
+}
+interface IAuthRepository<TAccount extends BaseAuthAccount = BaseAuthAccount> {
+    create(data: CreateAccountData): Promise<TAccount>;
+    findByIdentifier(identifier: string): Promise<TAccount | null>;
+    findByEmail(email: string): Promise<BaseAuthAccount | null>;
+    findByIdentifierWithSecrets(identifier: string): Promise<AuthAccountWithSecrets | null>;
+    findById(id: string): Promise<BaseAuthAccount | null>;
+    findByIdWithSecrets(id: string): Promise<AuthAccountWithSecrets | null>;
+    updateRefreshTokenHash(id: string, hash: string | null): Promise<void>;
+    updatePasswordHash(id: string, passwordHash: string): Promise<void>;
+    setEmailVerificationToken(id: string, tokenHash: string, expiresAt: Date): Promise<void>;
+    findByEmailVerificationTokenHash(tokenHash: string): Promise<BaseAuthAccount | null>;
+    markEmailVerified(id: string): Promise<void>;
+    setResetToken(id: string, tokenHash: string, expiresAt: Date): Promise<void>;
+    findByResetTokenHash(tokenHash: string): Promise<AuthAccountWithSecrets | null>;
+    clearResetToken(id: string): Promise<void>;
+}
+
+export type { AuthModuleOptions as A, BaseAuthAccount as B, CreateAccountData as C, IAuthRepository as I, RegisterInput as R, AuthModuleAsyncOptions as a, AuthHooks as b, AuthTokens as c, AuthAccountWithSecrets as d, AuthFeatures as e, AuthIdentifierField as f, AuthJwtConfig as g };