@ackplus/nest-auth 0.1.51 → 1.1.0

package/src/lib/core/core.module.ts

@@ -0,0 +1,50 @@
+import { Module } from '@nestjs/common';
+import { TypeOrmModule } from '@nestjs/typeorm';
+import { AuthProviderRegistryService } from './services/auth-provider-registry.service';
+import { AppleAuthProvider } from './providers/apple-auth.provider';
+import { JwtAuthProvider } from './providers/jwt-auth.provider';
+import { EmailAuthProvider } from './providers/email-auth.provider';
+import { FacebookAuthProvider } from './providers/facebook-auth.provider';
+import { GoogleAuthProvider } from './providers/google-auth.provider';
+import { GitHubAuthProvider } from './providers/github-auth.provider';
+import { PhoneAuthProvider } from './providers/phone-auth.provider';
+import { JwtService } from './services/jwt.service';
+import { AuthConfigService } from './services/auth-config.service';
+import { InitializationService } from './services/initialization.service';
+import { DebugLoggerService } from './services/debug-logger.service';
+import { TenantModule } from '../tenant/tenant.module';
+import { NestAuthUser } from '../user/entities/user.entity';
+import { NestAuthIdentity } from '../user/entities/identity.entity';
+
+/**
+ * CoreModule provides core authentication services and providers.
+ * Imports TypeOrmModule.forFeature to provide DataSource for auth providers.
+ */
+@Module({
+    imports: [
+        TypeOrmModule.forFeature([NestAuthUser, NestAuthIdentity]),
+        TenantModule
+    ],
+    providers: [
+        AuthConfigService,
+        DebugLoggerService,
+        JwtService,
+        AuthProviderRegistryService,
+        EmailAuthProvider,
+        PhoneAuthProvider,
+        JwtAuthProvider,
+        GoogleAuthProvider,
+        FacebookAuthProvider,
+        AppleAuthProvider,
+        GitHubAuthProvider,
+        InitializationService,
+    ],
+    exports: [
+        JwtService,
+        AuthProviderRegistryService,
+        AuthConfigService,
+        DebugLoggerService,
+        InitializationService,
+    ],
+})
+export class CoreModule { }

package/src/lib/core/decorators/auth.decorator.ts

@@ -0,0 +1,38 @@
+import { UseGuards, applyDecorators, SetMetadata } from '@nestjs/common';
+import { NestAuthAuthGuard, OPTIONAL_AUTH_KEY } from '../../auth/guards/auth.guard';
+
+/**
+ * Flexible Authentication Decorator
+ *
+ * This decorator applies the NestAuthAuthGuard with configurable authentication mode:
+ *
+ * @param optional - If true, authentication becomes optional (no errors thrown for missing/invalid tokens)
+ *
+ * @example Required Authentication (default behavior):
+ * ```typescript
+ * @Get('protected')
+ * @Auth() // or @Auth(false)
+ * async getProtectedData(@Request() req) {
+ *   const user = req.user; // Will always exist or request fails
+ *   return this.getProtectedData(user.id);
+ * }
+ * ```
+ *
+ * @example Optional Authentication:
+ * ```typescript
+ * @Get('posts')
+ * @Auth(true) // Optional authentication
+ * async getPosts(@Request() req) {
+ *   const user = req.user; // Will be null if not authenticated
+ *   if (user) {
+ *     return this.getPersonalizedPosts(user.id);
+ *   } else {
+ *     return this.getPublicPosts();
+ *   }
+ * }
+ * ```
+ */
+export const Auth = (optional: boolean = false) => applyDecorators(
+    SetMetadata(OPTIONAL_AUTH_KEY, optional),
+    UseGuards(NestAuthAuthGuard)
+);

package/src/lib/core/decorators/permissions.decorator.ts

@@ -0,0 +1,17 @@
+import { SetMetadata } from '@nestjs/common';
+
+export const PERMISSIONS_KEY = 'nest_auth_permissions';
+
+/**
+ * Decorator to specify required permissions for a route
+ * @param permissions - Array of permission strings or single permission string
+ * @returns Decorator function
+ */
+export function NestAuthPermissions(permissions: string[] | string) {
+    return (target: any, key?: string, descriptor?: PropertyDescriptor) => {
+        if (descriptor) {
+            Reflect.defineMetadata(PERMISSIONS_KEY, permissions, descriptor.value);
+        }
+        return descriptor;
+    };
+}

package/src/lib/core/decorators/public.decorator.ts

@@ -0,0 +1,33 @@
+import { SetMetadata } from '@nestjs/common';
+
+/**
+ * Key for public route metadata
+ * Used to mark routes that should skip authentication when global guard is enabled
+ */
+export const IS_PUBLIC_KEY = 'isPublic';
+
+/**
+ * @Public decorator
+ *
+ * Use this decorator to skip authentication on specific routes when enableGlobalGuard is true.
+ *
+ * @example
+ * ```typescript
+ * @Controller('users')
+ * export class UsersController {
+ *   // This route is public - no authentication required
+ *   @Public()
+ *   @Get('info')
+ *   getPublicInfo() {
+ *     return { info: 'public data' };
+ *   }
+ *
+ *   // This route requires authentication (protected by global guard)
+ *   @Get('profile')
+ *   getProfile(@Request() req) {
+ *     return req.user;
+ *   }
+ * }
+ * ```
+ */
+export const Public = () => SetMetadata(IS_PUBLIC_KEY, true);

package/src/lib/core/decorators/role.decorator.ts

@@ -0,0 +1,12 @@
+
+export const ROLES_KEY = 'nest_auth_roles';
+export const GUARD_KEY = 'nest_auth_guard';
+
+
+export function NestAuthRoles(roles: string[] | string, guard?: string) {
+    return (target: any, key: string, descriptor: PropertyDescriptor) => {
+        Reflect.defineMetadata(ROLES_KEY, roles, descriptor.value);
+        Reflect.defineMetadata(GUARD_KEY, guard, descriptor.value);
+        return descriptor;
+    };
+}

package/src/lib/core/decorators/skip-mfa.decorator.ts

@@ -0,0 +1,4 @@
+import { SetMetadata } from '@nestjs/common';
+
+export const SKIP_MFA_KEY = 'skipMfa';
+export const SkipMfa = () => SetMetadata(SKIP_MFA_KEY, true);

package/src/lib/core/dto/message.response.dto.ts

@@ -0,0 +1,6 @@
+import { ApiProperty } from '@nestjs/swagger';
+
+export class MessageResponseDto {
+    @ApiProperty({ description: 'Response message' })
+    message: string;
+}

package/src/lib/core/{entities.d.ts → entities.ts}

@@ -6,6 +6,9 @@ import { NestAuthRole } from '../role/entities/role.entity';
 import { NestAuthMFASecret } from '../auth/entities/mfa-secret.entity';
 import { NestAuthOTP } from '../auth/entities/otp.entity';
 import { NestAuthSession } from '../session/entities/session.entity';
+import { NestAuthPermission } from '../permission/entities/permission.entity';
+import { AdminUser as NestAuthAdminUser } from '../admin-console/entities/admin-user.entity';
+
 export * from '../user/entities/user.entity';
 export * from '../user/entities/identity.entity';
 export * from '../user/entities/access-key.entity';
@@ -14,4 +17,18 @@ export * from '../role/entities/role.entity';
 export * from '../auth/entities/mfa-secret.entity';
 export * from '../auth/entities/otp.entity';
 export * from '../session/entities/session.entity';
-export declare const NestAuthEntities: (typeof NestAuthTenant | typeof NestAuthIdentity | typeof NestAuthUser | typeof NestAuthSession | typeof NestAuthOTP | typeof NestAuthMFASecret | typeof NestAuthRole | typeof NestAuthAccessKey)[];
+export * from '../permission/entities/permission.entity';
+export { AdminUser as NestAuthAdminUser } from '../admin-console/entities/admin-user.entity';
+
+export const NestAuthEntities = [
+    NestAuthUser,
+    NestAuthIdentity,
+    NestAuthRole,
+    NestAuthTenant,
+    NestAuthMFASecret,
+    NestAuthSession,
+    NestAuthOTP,
+    NestAuthAccessKey,
+    NestAuthPermission,
+    NestAuthAdminUser,
+];

package/src/lib/core/{index.d.ts → index.ts}

@@ -1,23 +1,40 @@
+// Decorators
 export * from './decorators/role.decorator';
 export * from './decorators/permissions.decorator';
 export * from './decorators/skip-mfa.decorator';
 export * from './decorators/auth.decorator';
+
+// Interfaces
 export * from './interfaces/auth-module-options.interface';
 export * from './interfaces/mfa-options.interface';
 export * from './interfaces/session-options.interface';
 export * from './interfaces/token-payload.interface';
+
+// Entities
 export * from './entities';
+
+// DTOs
 export * from './dto/message.response.dto';
+
+
+// Interface
 export * from './interfaces/auth-module-options.interface';
 export * from './interfaces/mfa-options.interface';
 export * from './interfaces/session-options.interface';
 export * from './interfaces/token-payload.interface';
 export * from './interfaces/otp.interface';
+
+// Providers
+export * from './providers/base-auth.provider';
 export * from './providers/email-auth.provider';
 export * from './providers/phone-auth.provider';
 export * from './providers/jwt-auth.provider';
 export * from './providers/google-auth.provider';
 export * from './providers/facebook-auth.provider';
 export * from './providers/apple-auth.provider';
+export * from './providers/github-auth.provider';
+
+
+// Services
 export * from './services/auth-provider-registry.service';
 export * from './services/jwt.service';

package/src/lib/core/interfaces/auth-module-options.interface.ts

@@ -0,0 +1,211 @@
+import { Type } from '@nestjs/common';
+import { MFAOptions } from './mfa-options.interface';
+import { CookieOptions, SessionOptions } from './session-options.interface';
+import { BaseAuthProvider } from '../providers/base-auth.provider';
+import { DebugLogOptions } from '../services/debug-logger.service';
+
+/**
+ * Default Tenant Options
+ *
+ * When configured, a default tenant will be automatically created on module initialization
+ * and used for all authentication operations when no tenantId is explicitly provided.
+ *
+ * This enables single-tenant mode where users don't need to pass tenantId in signup/login requests.
+ */
+export interface DefaultTenantOptions {
+    /** Name of the default tenant */
+    name: string;
+
+    /**
+     * Unique identifier/slug for the tenant
+     * Must be lowercase, no spaces, only letters, numbers, hyphens (-) and underscores (_)
+     * Examples: 'my-app', 'acme_corp', 'tenant123'
+     */
+    slug: string;
+
+    /**
+     * @deprecated Use 'slug' instead. Will be removed in v2.0.0
+     * Unique domain identifier for the tenant (legacy field)
+     */
+    domain?: string;
+
+    /** Optional description */
+    description?: string;
+
+    /** Optional metadata */
+    metadata?: Record<string, any>;
+}
+
+export interface RegistrationCollectProfileField {
+    id: string;
+    label: string;
+    required: boolean;
+    type: 'text' | 'email' | 'phone' | 'select' | 'checkbox' | 'password';
+    placeholder?: string;
+    options?: Array<{ label: string; value: string }>;
+}
+
+export interface AuthModuleOptions {
+    isGlobal?: boolean;
+    appName: string;
+    /**
+     * Enable automatic token refresh via global interceptor.
+     * When enabled, expired access tokens are automatically refreshed using refresh tokens.
+     *
+     * Default: true (automatic refresh enabled)
+     */
+    enableAutoRefresh?: boolean;
+    accessTokenType?: 'header' | 'cookie';
+    cookieOptions?: CookieOptions;
+    jwt: {
+        secret: string;
+        accessTokenExpiresIn?: number | string; // expressed in seconds or a string describing a time span [zeit/ms](https://github.com/zeit/ms.js).  Eg: 60, "2 days", "10h", "7d"
+        refreshTokenExpiresIn?: number | string; // expressed in seconds or a string describing a time span [zeit/ms](https://github.com/zeit/ms.js).  Eg: 60, "2 days", "10h", "7d"
+    };
+    google?: {
+        clientId: string;
+        clientSecret: string;
+        redirectUri: string;
+    };
+    facebook?: {
+        appId: string;
+        appSecret: string;
+        redirectUri: string;
+    };
+    apple?: {
+        clientId: string;
+        teamId: string;
+        keyId: string;
+        privateKey: string;
+        privateKeyMethod?: string;
+        redirectUri: string;
+    };
+    github?: {
+        clientId: string;
+        clientSecret: string;
+        redirectUri: string;
+    };
+    phoneAuth?: {
+        enabled: boolean;
+    };
+    emailAuth?: {
+        enabled: boolean;
+    };
+    /**
+     * Registration configuration
+     * Controls user registration/signup behavior and profile fields
+     */
+    registration?: {
+        enabled?: boolean;
+        requireInvitation?: boolean;
+        collectProfileFields?: Array<RegistrationCollectProfileField>;
+    };
+    /**
+     * Client configuration customization
+     * Allows extending/modifying the client-config endpoint response
+     */
+    clientConfig?: {
+        /**
+         * Factory function to customize the client config response
+         * Receives the default config and can modify/return it
+         */
+        factory?: (defaultConfig: any, context: { configService: any; tenantService: any }) => Promise<any> | any;
+    };
+    mfa?: MFAOptions;
+    session?: SessionOptions;
+    customAuthProviders?: BaseAuthProvider[];
+    passwordResetOtpExpiresIn?: number | string; // expressed in seconds or a string describing a time span [zeit/ms](https://github.com/zeit/ms.js).  Eg: 60, "2 days", "10h", "7d"
+    passwordResetTokenExpiresIn?: number | string; // expressed in seconds or a string describing a time span [zeit/ms](https://github.com/zeit/ms.js).  Eg: 60, "2 days", "10h", "7d"
+    /**
+     * Configure a default tenant for single-tenant applications.
+     * When set, tenantId becomes optional in all authentication requests.
+     * The default tenant is automatically created on module initialization.
+     *
+     * Example:
+     * ```typescript
+     * defaultTenant: {
+     *   name: 'My App',
+     *   slug: 'my-app'  // lowercase, no spaces, only a-z0-9_-
+     * }
+     * ```
+     *
+     * Legacy (deprecated):
+     * ```typescript
+     * defaultTenant: {
+     *   name: 'My App',
+     *   domain: 'myapp'  // Still supported but use 'slug' instead
+     * }
+     * ```
+     */
+    defaultTenant?: DefaultTenantOptions;
+    /**
+     * Embedded admin console configuration.
+     * Provides a password-protected dashboard for managing users, roles, tenants, and system settings.
+     *
+     * The admin console secretKey is also used for admin signup via the /signup endpoint.
+     */
+    adminConsole?: AdminConsoleOptions;
+    debug?: DebugLogOptions;
+}
+
+export interface AdminConsoleOptions {
+    /** Enable or disable the embedded admin console (default: true) */
+    enabled?: boolean;
+    /** Base path where the console is served (default: /auth/admin) */
+    basePath?: string;
+    /**
+     * Nest Auth Admin Console Secret Key used for security operations.
+     * This key is used for:
+     * - Signing admin dashboard sessions
+     * - Admin signup via /signup endpoint
+     * - Password reset operations
+     *
+     * You can set this to any value you prefer:
+     * - Hardcode: secretKey: 'your-secret-key-here'
+     * - Environment variable: secretKey: process.env.MY_SECRET_KEY (use any variable name)
+     */
+    secretKey?: string;
+    /** Cookie name for admin dashboard sessions (default: nest_auth_admin) */
+    sessionCookieName?: string;
+    /** Session duration expressed in seconds or ms string (default: 2h) */
+    sessionDuration?: string | number;
+    /**
+     * @deprecated This option is no longer used. Admin users are created directly without role assignment.
+     * Role name for super admin created via /initialize endpoint (default: 'super-admin')
+     */
+    superAdminRole?: string;
+    /**
+     * @deprecated This option is no longer used. The /signup endpoint is always available when secretKey is configured.
+     * Whether the /initialize endpoint is enabled for super admin creation (default: true if secretKey is available)
+     */
+    initializeEnabled?: boolean;
+    /**
+     * Cookie options applied to the admin session cookie.
+     * httpOnly and sameSite default to true/'lax' respectively.
+     */
+    cookie?: CookieOptions;
+    /**
+     * Allow managing other dashboard admins through the console UI (default: true).
+     */
+    allowAdminManagement?: boolean;
+}
+
+export interface AuthModuleAsyncOptions {
+    isGlobal?: boolean;
+    /**
+     * Enable automatic token refresh via global interceptor.
+     * When enabled, expired access tokens are automatically refreshed using refresh tokens.
+     *
+     * Default: true (automatic refresh enabled)
+     */
+    enableAutoRefresh?: boolean;
+    imports?: any[];
+    useFactory?: (...args: any[]) => Promise<AuthModuleOptions> | AuthModuleOptions;
+    inject?: any[];
+    useClass?: Type<AuthModuleOptionsFactory>;
+    useExisting?: Type<AuthModuleOptionsFactory>;
+}
+
+export interface AuthModuleOptionsFactory {
+    createAuthModuleOptions(): Promise<AuthModuleOptions> | AuthModuleOptions;
+}

package/src/lib/core/interfaces/mfa-options.interface.ts

@@ -0,0 +1,46 @@
+
+export interface MFAOptions {
+    // Whether MFA is enabled for the application
+    enabled?: boolean;
+
+    // Whether MFA is required for all users
+    required?: boolean;
+
+    // Default enabled MFA methods
+    methods?: MFAMethodEnum[];
+
+    // OTP length
+    otpLength?: number;
+
+    // Default TOTP settings
+    totp?: {
+        issuer: string;
+        period: number;
+    };
+
+    // Default SMS settings
+    sms?: {
+        provider: string;
+        template: string;
+    };
+
+    // Default Email settings
+    email?: {
+        template: string;
+    };
+
+    // Whether users can enable/disable MFA
+    allowUserToggle?: boolean;
+
+    // Whether users can choose their MFA methods
+    allowMethodSelection?: boolean;
+
+    // OTP expiry time
+    otpExpiresIn?: string | number;
+}
+
+export enum MFAMethodEnum {
+    TOTP = 'totp',
+    SMS = 'sms',
+    EMAIL = 'email',
+}

package/src/lib/core/interfaces/otp.interface.ts

@@ -0,0 +1,6 @@
+
+export enum OTPTypeEnum {
+    PASSWORD_RESET = 'password_reset',
+    VERIFICATION = 'verification',
+    MFA = 'mfa',
+}

package/src/lib/core/interfaces/session-options.interface.ts

@@ -0,0 +1,19 @@
+import { CookieOptions as ExpressCookieOptions } from 'express';
+
+export enum SessionStorageType {
+    REDIS = 'redis',
+    DATABASE = 'database',
+    MEMORY = 'memory'
+}
+
+export interface SessionOptions {
+    storageType: SessionStorageType;
+    redisUrl?: string;
+    sessionExpiry?: number | string; // expressed in seconds or a string describing a time span [zeit/ms](https://github.com/zeit/ms.js).  Eg: 60, "2 days", "10h", "7d"
+    refreshTokenExpiry?: number | string; // expressed in seconds or a string describing a time span [zeit/ms](https://github.com/zeit/ms.js).  Eg: 60, "2 days", "10h", "7d"
+    maxSessionsPerUser?: number; // Maximum number of active sessions per user (default: 10)
+    slidingExpiration?: boolean; // Whether to extend session on activity (default: true)
+}
+
+
+export type CookieOptions = Omit<ExpressCookieOptions, 'maxAge'>

package/src/lib/core/interfaces/{token-payload.interface.d.ts → token-payload.interface.ts}

@@ -1,8 +1,9 @@
 import { NestAuthRole } from '../../role/entities/role.entity';
 import { NestAuthUser } from '../../user/entities/user.entity';
+
 export interface JWTTokenPayload {
     id?: string;
-    sub?: string;
+    sub?: string; // user id
     email?: string;
     phone?: string;
     isVerified?: boolean;
@@ -15,6 +16,7 @@ export interface JWTTokenPayload {
     exp?: number;
     iat?: number;
 }
+
 export interface SessionPayload {
     id?: string;
     userId?: string;
@@ -33,6 +35,7 @@ export interface SessionPayload {
     createdAt?: Date;
     updatedAt?: Date;
 }
+
 export interface TokenGenerationResponse {
     accessToken: string;
     refreshToken: string;

package/src/lib/core/providers/apple-auth.provider.ts

@@ -0,0 +1,61 @@
+import AppleAuth from 'apple-auth';
+import { Injectable, UnauthorizedException } from '@nestjs/common';
+import { DataSource } from 'typeorm';
+import { BaseAuthProvider } from './base-auth.provider';
+import { APPLE_AUTH_PROVIDER } from '../../auth.constants';
+import { NestAuthUser } from '../../user/entities/user.entity';
+import { NestAuthIdentity } from '../../user/entities/identity.entity';
+import { JwtService } from '../services/jwt.service';
+
+@Injectable()
+export class AppleAuthProvider extends BaseAuthProvider {
+    providerName = APPLE_AUTH_PROVIDER;
+
+    private appleAuth: AppleAuth;
+
+    constructor(
+        readonly dataSource: DataSource,
+        private readonly jwtService: JwtService,
+    ) {
+        const userRepository = dataSource.getRepository(NestAuthUser);
+        const authIdentityRepository = dataSource.getRepository(NestAuthIdentity);
+
+        super(userRepository, authIdentityRepository);
+
+        const appleConfig = this.options.apple;
+
+        this.enabled = Boolean(this.options.apple);
+
+        if (this.enabled) {
+            this.appleAuth = new AppleAuth(
+                {
+                    scope: 'email name',
+                    redirect_uri: appleConfig.redirectUri,
+                    team_id: appleConfig.teamId,
+                    key_id: appleConfig.keyId,
+                    client_id: appleConfig.clientId,
+                },
+                appleConfig.privateKey,
+                appleConfig.privateKeyMethod || 'text',
+            );
+        }
+    }
+
+    async validate(credentials: { accessToken: string }) {
+        try {
+            const response = await this.appleAuth.accessToken(credentials.accessToken);
+            const user = this.jwtService.decodeToken(response.id_token);
+            return {
+                userId: user.id,
+                email: user.email || '',
+                metadata: user,
+            };
+        } catch (error) {
+            throw new UnauthorizedException('Invalid Apple token');
+        }
+    }
+
+    getRequiredFields(): string[] {
+        return ['accessToken'];
+    }
+}