nesthub 1.0.3 → 1.2.0-alpha.2

package/README.md

@@ -8,15 +8,16 @@ A collection of modular NestJS utility packages. Each module can be imported ind
 npm install nesthub
 ```
 
-## Available modules
+Each sub-package has its own peer dependencies. Install only the modules you need:
 
-| Import path | Description | README |
-|---|---|---|
-| `nesthub/typeorm` | TypeORM configuration helpers (RDS PostgreSQL, MySQL) | [README](src/typeorm/README.md) |
-| `nesthub/cache` | Global cache module with Valkey / Redis backend | [README](src/cache/README.md) |
-| `nesthub/queue` | BullMQ config factory for Valkey / Redis backend | [README](src/queue/README.md) |
-| `nesthub/notification` | Multi-channel notification module (email, SMS, Firebase, Telegram) with templates, queue, TypeORM persistence | [README](src/notification/README.md) |
-| `nesthub/excel` | Export JSON data to Excel (.xlsx) — fast, zero boilerplate | [README](src/excel/README.md) |
+| Import path | Install command | Description | README |
+|---|---|---|---|
+| `nesthub/typeorm` | `npm install nesthub @nestjs/typeorm @nestjs/config pg` | TypeORM configuration helpers (RDS PostgreSQL, MySQL) | [README](src/typeorm/README.md) |
+| `nesthub/cache` | `npm install nesthub keyv cacheable` + `@keyv/valkey` or `@keyv/redis` | Global cache module with Valkey / Redis backend | [README](src/cache/README.md) |
+| `nesthub/queue` | `npm install nesthub @nestjs/bullmq bullmq` | BullMQ config factory for Valkey / Redis backend | [README](src/queue/README.md) |
+| `nesthub/notification` | `npm install nesthub` + optional peers (see [README](src/notification/README.md)) | Multi-channel notification module (email, SMS, Firebase, Telegram) with templates, queue, TypeORM persistence | [README](src/notification/README.md) |
+| `nesthub/auth` | `npm install nesthub @nestjs/jwt @nestjs/passport passport passport-jwt bcrypt otplib` | Feature-rich Auth module — JWT, OAuth, SSO, 2FA, Passkeys, magic link, OTP, session management, GDPR account deletion | [README](src/auth/README.md) |
+| `nesthub/excel` | `npm install nesthub exceljs` | Export JSON data to Excel (.xlsx) — fast, zero boilerplate | [README](src/excel/README.md) |
 
 Click each README link above for detailed usage, environment variables, and options specific to that module.
 
@@ -24,6 +25,10 @@ Click each README link above for detailed usage, environment variables, and opti
 
 ### TypeORM
 
+```bash
+npm install nesthub @nestjs/typeorm @nestjs/config pg
+```
+
 ```typescript
 import { TypeOrmModule } from '@nestjs/typeorm'
 import { ConfigService } from '@nestjs/config'
@@ -38,6 +43,10 @@ TypeOrmModule.forRootAsync({
 
 ### Cache
 
+```bash
+npm install nesthub keyv cacheable @keyv/valkey
+```
+
 ```typescript
 import { CacheModule } from 'nesthub/cache'
 
@@ -49,6 +58,10 @@ export class AppModule {}
 
 ### Queue
 
+```bash
+npm install nesthub @nestjs/bullmq bullmq
+```
+
 ```typescript
 import { BullModule } from '@nestjs/bullmq'
 import { configBullMQ } from 'nesthub/queue'
@@ -61,6 +74,11 @@ BullModule.forRootAsync({
 
 ### Notification
 
+```bash
+npm install nesthub
+# Optional: npm install nodemailer twilio firebase-admin handlebars @nestjs/bullmq bullmq @nestjs/typeorm typeorm
+```
+
 ```typescript
 import { Module } from '@nestjs/common'
 import { NotificationModule } from 'nesthub/notification'
@@ -81,8 +99,40 @@ import { NotificationModule } from 'nesthub/notification'
 export class AppModule {}
 ```
 
+### Auth
+
+```bash
+npm install @nestjs/jwt @nestjs/passport passport passport-jwt bcrypt otplib
+```
+
+```typescript
+import { Module } from '@nestjs/common'
+import { AuthModule } from 'nesthub/auth'
+
+@Module({
+  imports: [
+    AuthModule.forRoot({
+      security: { jwtSecret: process.env.JWT_SECRET },
+      oauth: {
+        google: {
+          clientId: process.env.GOOGLE_CLIENT_ID!,
+          clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+        },
+      },
+      twoFactor: { enabled: true, methods: ['totp', 'email'] },
+      passkey: { enabled: true, relyingPartyId: 'example.com', origin: 'https://example.com' },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
 ### Excel
 
+```bash
+npm install nesthub exceljs
+```
+
 ```typescript
 import { exportToBuffer, exportToFile, exportToResponse } from 'nesthub/excel'
 

package/dist/auth/README.md

@@ -0,0 +1,346 @@
+# NestHub Auth Module
+
+All-in-one authentication module for NestJS, inspired by Better Auth. Supports multiple authentication mechanisms with enterprise-grade security.
+
+## Features
+
+- **Credentials**: Email/username + password login
+- **OAuth**: Google, GitHub, Facebook, Apple, Microsoft, Discord, and custom providers
+- **Two-Factor Auth (2FA)**: TOTP-based with backup codes
+- **Anonymous**: Anonymous sessions convertible to permanent accounts
+- **Magic Link**: Passwordless email login
+- **OTP**: One-time password via email/phone
+- **Passkey**: WebAuthn/FIDO2 passkey authentication
+- **OneTap**: Google & Apple OneTap sign-in
+- **SSO**: SAML & OpenID Connect support
+- **Session Management**: Stateless JWT with refresh tokens, multi-device tracking, per-device logout (like Telegram)
+- **Security**: Password hashing (bcrypt), rate limiting, token versioning, token blacklist via Redis/Valkey
+
+## Installation
+
+```bash
+npm install @nestjs/jwt @nestjs/passport passport passport-jwt bcrypt otplib
+```
+
+## Quick Start
+
+```typescript
+import { Module } from '@nestjs/common';
+import { TypeOrmModule } from '@nestjs/typeorm';
+import { AuthModule } from 'nesthub/auth';
+
+@Module({
+  imports: [
+    TypeOrmModule.forRoot({ ... }),
+    AuthModule.forRoot({
+      credentials: { enabled: true, allowRegistration: true },
+      security: {
+        jwtSecret: process.env.JWT_SECRET,
+        passwordHashRounds: 12,
+        maxSessions: { enabled: true, maxPerUser: 5 },
+      },
+      oauth: {
+        google: {
+          enabled: true,
+          clientId: process.env.GOOGLE_CLIENT_ID,
+          clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+        },
+        github: {
+          enabled: false,
+          clientId: process.env.GITHUB_CLIENT_ID,
+          clientSecret: process.env.GITHUB_CLIENT_SECRET,
+        },
+      },
+      twoFactor: {
+        enabled: true,
+        issuer: 'MyApp',
+      },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+## Configuration via .env
+
+```env
+# JWT
+JWT_SECRET=your-jwt-secret
+JWT_EXPIRES_IN=15m
+
+# OAuth Providers
+GOOGLE_CLIENT_ID=xxx
+GOOGLE_CLIENT_SECRET=xxx
+GITHUB_CLIENT_ID=xxx
+GITHUB_CLIENT_SECRET=xxx
+FACEBOOK_CLIENT_ID=xxx
+FACEBOOK_CLIENT_SECRET=xxx
+APPLE_CLIENT_ID=xxx
+APPLE_CLIENT_SECRET=xxx
+MICROSOFT_CLIENT_ID=xxx
+MICROSOFT_CLIENT_SECRET=xxx
+DISCORD_CLIENT_ID=xxx
+DISCORD_CLIENT_SECRET=xxx
+
+# App
+APP_URL=http://localhost:3000
+```
+
+## Usage
+
+### Register
+
+```typescript
+POST /auth/register
+{ "email": "user@example.com", "password": "secure123", "name": "User", "deviceName": "iPhone 15" }
+```
+
+### Login
+
+```typescript
+POST /auth/login
+{ "identifier": "user@example.com", "password": "secure123", "deviceName": "Chrome on Mac" }
+```
+
+### Response Structure
+
+All endpoints return a consistent response format:
+
+```typescript
+// Successful login/register
+{
+  "user": {
+    "id": "uuid",
+    "email": "user@example.com",
+    "emailVerified": false,
+    "phone": null,
+    "name": "User",
+    "image": null,
+    "roles": ["user"],
+    "isAnonymous": false,
+    "twoFactorEnabled": false,
+    "twoFactorVerified": false
+  },
+  "accessToken": "eyJhbGci...",
+  "refreshToken": "eyJhbGci..."
+}
+
+// When 2FA is required
+{
+  "user": { ... },
+  "requiresTwoFactor": true,
+  "accessToken": ""
+}
+```
+
+### Session Management (like Telegram)
+
+List all active devices/sessions:
+
+```typescript
+GET /auth/sessions
+Authorization: Bearer <accessToken>
+
+// Response
+[
+  {
+    "id": "uuid",
+    "userId": "uuid",
+    "jti": "hex-token-id",
+    "ipAddress": "192.168.1.1",
+    "userAgent": "Mozilla/5.0 ...",
+    "deviceName": "Chrome on Mac",
+    "expiresAt": "2026-07-20T00:00:00Z",
+    "createdAt": "2026-06-20T00:00:00Z"
+  }
+]
+```
+
+Revoke a specific session (logout that device without affecting others):
+
+```typescript
+DELETE /auth/sessions/:id
+Authorization: Bearer <accessToken>
+
+// Response
+{ "message": "Session revoked" }
+```
+
+Logout current session:
+
+```typescript
+POST /auth/logout
+Authorization: Bearer <accessToken>
+
+// Optional: pass jti to revoke a specific token
+{ "jti": "hex-token-id" }
+```
+
+Logout all sessions (increments tokenVersion, invalidating all existing tokens):
+
+```typescript
+POST /auth/logout-all
+Authorization: Bearer <accessToken>
+```
+
+### Magic Link
+
+```typescript
+POST /auth/magic-link/send
+{ "email": "user@example.com" }
+
+POST /auth/magic-link/verify
+{ "token": "..." }
+```
+
+### OTP
+
+```typescript
+POST /auth/otp/send
+{ "identifier": "user@example.com", "purpose": "login" }
+
+POST /auth/otp/verify
+{ "identifier": "user@example.com", "code": "123456", "purpose": "login" }
+```
+
+### 2FA
+
+```typescript
+GET /auth/2fa/setup          # Get TOTP secret + QR code URL
+POST /auth/2fa/enable        # { "secret": "...", "code": "123456" }
+POST /auth/2fa/verify        # { "code": "123456" }
+POST /auth/2fa/disable
+POST /auth/2fa/backup-codes  # Generate new backup codes
+```
+
+### Passkey (WebAuthn)
+
+```typescript
+POST /auth/passkeys/register/initiate
+POST /auth/passkeys/register/complete
+POST /auth/passkeys/authenticate/initiate
+POST /auth/passkeys/authenticate/complete
+GET  /auth/passkeys
+DELETE /auth/passkeys/:id
+```
+
+### Anonymous
+
+```typescript
+POST /auth/anonymous
+POST /auth/anonymous/convert
+{ "email": "user@example.com", "password": "secure123", "name": "User" }
+```
+
+### OAuth
+
+```typescript
+GET  /auth/oauth/providers
+POST /auth/oauth/:provider/callback
+{ "code": "...", "redirectUri": "..." }
+```
+
+### OneTap
+
+```typescript
+POST /auth/onetap/google  { "idToken": "..." }
+POST /auth/onetap/apple   { "idToken": "..." }
+```
+
+### SSO
+
+```typescript
+GET  /auth/sso/providers
+POST /auth/sso/:provider/callback
+{ "attributes": { "email": "...", "name": "..." } }
+```
+
+### Profile & Account
+
+```typescript
+GET    /auth/profile
+POST   /auth/profile       { "name": "...", "image": "..." }
+POST   /auth/change-password  { "currentPassword": "...", "newPassword": "..." }
+DELETE /auth/account           # GDPR-compliant account deletion (anonymizes PII)
+```
+
+## API Reference
+
+### AuthModule.forRoot(options)
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `credentials` | `CredentialsConfig` | `{ enabled: true, allowRegistration: true }` | Email/phone + password login & registration |
+| `oauth` | `ProviderConfig` | - | OAuth provider configs (each provider has `enabled` flag) |
+| `sso` | `SSOProviderConfig[]` | - | SSO provider configs (each provider has `enabled` flag) |
+| `twoFactor` | `TwoFactorConfig` | `{ enabled: true }` | 2FA configuration |
+| `passkey` | `PasskeyConfig` | `{ enabled: false }` | WebAuthn config |
+| `anonymous` | `AnonymousConfig` | `{ enabled: true }` | Anonymous auth config |
+| `magicLink` | `MagicLinkConfig` | `{ enabled: false }` | Magic link config |
+| `otp` | `OtpConfig` | `{ enabled: false }` | OTP config |
+| `onelink` | `OnelinkConfig` | `{ enabled: false }` | Google & Apple OneTap sign-in |
+| `security` | `SecurityConfig` | (see below) | Security settings |
+| `email` | `EmailChannelConfig` | - | Email notification config |
+| `override` | `OverrideConfig` | - | Override entities/services/controllers |
+
+### Security Defaults
+
+```typescript
+{
+  passwordHashRounds: 12,
+  jwtExpiresIn: '15m',
+  refreshTokenExpiresIn: '7d',
+  rateLimit: { enabled: true, maxAttempts: 5, windowMs: 900000 },
+  requireEmailVerification: false,
+  maxSessions: { enabled: false, maxPerUser: 5 },
+}
+```
+
+### Override Custom Classes
+
+You can extend and override any entity, service, or controller:
+
+```typescript
+import { AuthService, AuthController, User } from 'nesthub/auth';
+
+class CustomUser extends User { /* extra columns */ }
+class CustomAuthService extends AuthService { /* overridden methods */ }
+class CustomAuthController extends AuthController { /* overridden endpoints */ }
+
+AuthModule.forRoot({
+  override: {
+    entities: { user: CustomUser },
+    services: { auth: CustomAuthService },
+    controllers: { auth: CustomAuthController },
+  },
+})
+```
+
+## Guards & Decorators
+
+```typescript
+import { AuthGuard, RolesGuard } from 'nesthub/auth';
+import { Public, CurrentUser, Roles } from 'nesthub/auth';
+
+@UseGuards(AuthGuard)
+@Get('profile')
+getProfile(@CurrentUser() user: AuthenticatedUser) {}
+
+@Public()
+@Get('public-route')
+publicEndpoint() {}
+
+@UseGuards(AuthGuard, RolesGuard)
+@Roles('admin')
+@Get('admin')
+adminOnly() {}
+```
+
+## Dependencies
+
+Optional peer dependencies:
+- `@nestjs/jwt` - JWT token handling
+- `@nestjs/passport` + `passport` + `passport-jwt` - Passport strategies
+- `bcrypt` - Password hashing
+- `otplib` - TOTP for 2FA
+- `@nestjs/cache-manager` or `nesthub/cache` (Redis/Valkey) - Token blacklist (recommended for production)

package/dist/auth/auth.constants.d.ts

@@ -0,0 +1,13 @@
+export declare const AUTH_OPTIONS = "AUTH_OPTIONS";
+export declare const AUTH_PREFIX = "auth";
+export declare const AUTH_USER_SERVICE = "AUTH_USER_SERVICE";
+export declare const AUTH_SESSION_SERVICE = "AUTH_SESSION_SERVICE";
+export declare const AUTH_OAUTH_PROVIDERS = "AUTH_OAUTH_PROVIDERS";
+export declare const AUTH_SSO_PROVIDERS = "AUTH_SSO_PROVIDERS";
+export declare const AUTH_PASSKEY_SERVICE = "AUTH_PASSKEY_SERVICE";
+export declare const AUTH_EMAIL_SERVICE = "AUTH_EMAIL_SERVICE";
+export declare const PASSWORD_RESET_PREFIX = "auth:pwdreset:";
+export declare const MAGIC_LINK_PREFIX = "auth:magiclink:";
+export declare const OTP_PREFIX = "auth:otp:";
+export declare const VERIFY_EMAIL_PREFIX = "auth:verify:";
+export declare const AUTH_CACHE_NAMESPACE = "nesthub:auth";

package/dist/auth/auth.constants.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AUTH_CACHE_NAMESPACE = exports.VERIFY_EMAIL_PREFIX = exports.OTP_PREFIX = exports.MAGIC_LINK_PREFIX = exports.PASSWORD_RESET_PREFIX = exports.AUTH_EMAIL_SERVICE = exports.AUTH_PASSKEY_SERVICE = exports.AUTH_SSO_PROVIDERS = exports.AUTH_OAUTH_PROVIDERS = exports.AUTH_SESSION_SERVICE = exports.AUTH_USER_SERVICE = exports.AUTH_PREFIX = exports.AUTH_OPTIONS = void 0;
+exports.AUTH_OPTIONS = 'AUTH_OPTIONS';
+exports.AUTH_PREFIX = 'auth';
+exports.AUTH_USER_SERVICE = 'AUTH_USER_SERVICE';
+exports.AUTH_SESSION_SERVICE = 'AUTH_SESSION_SERVICE';
+exports.AUTH_OAUTH_PROVIDERS = 'AUTH_OAUTH_PROVIDERS';
+exports.AUTH_SSO_PROVIDERS = 'AUTH_SSO_PROVIDERS';
+exports.AUTH_PASSKEY_SERVICE = 'AUTH_PASSKEY_SERVICE';
+exports.AUTH_EMAIL_SERVICE = 'AUTH_EMAIL_SERVICE';
+exports.PASSWORD_RESET_PREFIX = 'auth:pwdreset:';
+exports.MAGIC_LINK_PREFIX = 'auth:magiclink:';
+exports.OTP_PREFIX = 'auth:otp:';
+exports.VERIFY_EMAIL_PREFIX = 'auth:verify:';
+exports.AUTH_CACHE_NAMESPACE = 'nesthub:auth';
+//# sourceMappingURL=auth.constants.js.map

package/dist/auth/auth.constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.constants.js","sourceRoot":"","sources":["../../src/auth/auth.constants.ts"],"names":[],"mappings":";;;AAAa,QAAA,YAAY,GAAG,cAAc,CAAC;AAC9B,QAAA,WAAW,GAAG,MAAM,CAAC;AAErB,QAAA,iBAAiB,GAAG,mBAAmB,CAAC;AAExC,QAAA,oBAAoB,GAAG,sBAAsB,CAAC;AAE9C,QAAA,oBAAoB,GAAG,sBAAsB,CAAC;AAE9C,QAAA,kBAAkB,GAAG,oBAAoB,CAAC;AAE1C,QAAA,oBAAoB,GAAG,sBAAsB,CAAC;AAE9C,QAAA,kBAAkB,GAAG,oBAAoB,CAAC;AAE1C,QAAA,qBAAqB,GAAG,gBAAgB,CAAC;AACzC,QAAA,iBAAiB,GAAG,iBAAiB,CAAC;AACtC,QAAA,UAAU,GAAG,WAAW,CAAC;AACzB,QAAA,mBAAmB,GAAG,cAAc,CAAC;AAErC,QAAA,oBAAoB,GAAG,cAAc,CAAC"}

package/dist/auth/auth.module.d.ts

@@ -0,0 +1,10 @@
+import { DynamicModule, Type, ForwardReference } from '@nestjs/common';
+import type { AuthModuleOptions } from './interfaces';
+export declare class AuthModule {
+    static forRoot(options?: AuthModuleOptions): DynamicModule;
+    static forRootAsync(options: {
+        useFactory: (...args: any[]) => AuthModuleOptions | Promise<AuthModuleOptions>;
+        inject?: (string | symbol | Type<any>)[];
+        imports?: (DynamicModule | Type<any> | Promise<DynamicModule> | ForwardReference)[];
+    }): DynamicModule;
+}