@plyaz/auth 1.0.0

package/src/security/rate-limiting/auth/rate-limiting.interface.ts

@@ -0,0 +1,67 @@
+import { NUMERIX } from "@plyaz/config";
+
+export interface RouteRateLimitConfig {
+  limit: number; // max requests
+  windowMs: number; // time window
+  blockMs?: number; // block duration after limit exceeded
+}
+const thirty = 30;
+const fifteen  = 15;
+export const TIME = {
+  SECOND: 1000,
+  MINUTE: 60_000,
+  FIVE_MIN: NUMERIX.FIVE * NUMERIX.SIXTY_THOUSAND,
+  FIFTEEN_MIN: fifteen * NUMERIX.SIXTY_THOUSAND,
+  THIRTY_MIN: thirty * NUMERIX.SIXTY_THOUSAND,
+} as const;
+
+export const authRateLimits = {
+  signin: {
+    limit: 10,
+    windowMs: TIME.MINUTE,
+    blockMs: TIME.FIFTEEN_MIN,
+  },
+
+  signup: {
+    limit: 5,
+    windowMs: TIME.MINUTE,
+    blockMs: TIME.THIRTY_MIN,
+  },
+
+  refresh: {
+    limit: 30,
+    windowMs: TIME.MINUTE,
+    blockMs: TIME.FIVE_MIN,
+  },
+
+  mfaVerify: {
+    limit: 5,
+    windowMs: TIME.MINUTE,
+    blockMs: TIME.THIRTY_MIN,
+  },
+
+  web3Nonce: {
+    limit: 20,
+    windowMs: TIME.MINUTE,
+    blockMs: TIME.FIVE_MIN,
+  },
+
+  web3Verify: {
+    limit: 10,
+    windowMs: TIME.MINUTE,
+    blockMs: TIME.FIFTEEN_MIN,
+  },
+} as const satisfies Record<string, RouteRateLimitConfig>;
+
+export const rateLimitConfig: Record<string, RouteRateLimitConfig> = {
+  "POST /auth/signin": { limit: 10, windowMs: 60_000, blockMs: fifteen * NUMERIX.SIXTY_THOUSAND },
+  "POST /auth/signup": { limit: 5, windowMs: 60_000, blockMs: thirty * NUMERIX.SIXTY_THOUSAND },
+  "POST /auth/refresh": { limit: 30, windowMs: 60_000, blockMs: NUMERIX.FIVE * NUMERIX.SIXTY_THOUSAND },
+  "POST /auth/mfa/verify": { limit: 5, windowMs: 60_000, blockMs: thirty * NUMERIX.SIXTY_THOUSAND },
+  "GET /auth/web3/nonce": { limit: 20, windowMs: 60_000, blockMs: NUMERIX.FIVE * NUMERIX.SIXTY_THOUSAND },
+  "POST /auth/web3/verify": {
+    limit: 10,
+    windowMs: 60_000,
+    blockMs: fifteen * NUMERIX.SIXTY_THOUSAND,
+  },
+};

package/src/security/rate-limiting/auth.module.ts

@@ -0,0 +1,32 @@
+import { Module } from "@nestjs/common";
+import { ThrottlerModule } from "@nestjs/throttler";
+import { Redis } from "ioredis";
+import { ThrottlerStorageRedisService } from "@nest-lab/throttler-storage-redis";
+import { AuthController } from "./auth/auth.controller";
+import { RateLimiterGuard } from "../../server/guards/custom-throttler.guard";
+import { BruteForceService, RateLimiterService } from "../../server/services";
+
+
+@Module({
+  imports: [
+    ThrottlerModule.forRootAsync({
+      useFactory: () => ({
+        storage: new ThrottlerStorageRedisService(
+          new Redis({
+            host: "localhost",
+            port: 6379,
+          })
+        ),
+        throttlers: [
+          {
+            ttl: 60000,
+            limit: 10,
+          },
+        ],
+      }),
+    }),
+  ],
+  controllers: [AuthController],
+  providers: [RateLimiterGuard, RateLimiterService, BruteForceService],
+})
+export class AuthModule {}

package/src/server/auth.module.ts

@@ -0,0 +1,158 @@
+/**
+ * @fileoverview NestJS authentication module for @plyaz/auth
+ * @module @plyaz/auth/server/auth-module
+ * 
+ * @description
+ * Main NestJS module that provides all authentication and authorization services,
+ * guards, decorators, and middleware. Configures dependency injection for the
+ * entire auth system including session management, token validation, RBAC,
+ * and security features.
+ * 
+ * @example
+ * ```typescript
+ * import { AuthModule } from '@plyaz/auth';
+ * 
+ * @Module({
+ *   imports: [AuthModule],
+ * })
+ * export class AppModule {}
+ * ```
+ */
+
+import { Module } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+import { JwtModule } from '@nestjs/jwt';
+
+// Services
+import { AuthService } from './services/auth.service';
+import { SessionService } from './services/session.service';
+import { TokenService } from './services/token.service';
+import { AccountService } from './services/account.service';
+
+// Guards
+import { AuthGuard } from './guards/auth.guard';
+import { RolesGuard } from './guards/roles.guard';
+import { PermissionsGuard } from './guards/permissions.guard';
+
+// Core Components
+import { SessionManager } from '../core/session/session.manager';
+import { EnhancedSessionManager } from '../session/enhanced-session-manager';
+import { RoleManager } from '../rbac/role.manager';
+import { PermissionChecker } from '../rbac/permission-checker';
+
+// Strategies
+import { TraditionalAuthStrategy } from '../strategies/traditional-auth.strategy';
+import { OAuthStrategy } from '../strategies/oauth.strategy';
+
+// Token Management
+import { TokenValidator } from '../tokens/token-validator';
+import { RefreshTokenManager } from '../tokens/refresh-token-manager';
+import { TokenBlacklist } from '../core/blacklist/token.blacklist';
+
+// Security
+
+import { CSRFProtection } from '../security/csrf/csrf.protection';
+
+// Repositories
+import { UserRepository } from '../db/repositories/user.repository';
+import { SessionRepository } from '../db/repositories/session.repository';
+import { ConnectedAccountRepository } from '../db/repositories/connected-account.repository';
+
+// Session Stores
+import { MemoryStore } from '../session/memory-store';
+import { RateLimiterService } from './services';
+
+@Module({
+  imports: [
+    ConfigModule,
+    JwtModule.register({
+      secret: globalThis.process.env.JWT_SECRET ?? 'default-secret',
+      signOptions: { expiresIn: '15m' },
+    }),
+  ],
+  providers: [
+    // Services
+    AuthService,
+    SessionService,
+    TokenService,
+    AccountService,
+    
+    // Guards
+    AuthGuard,
+    RolesGuard,
+    PermissionsGuard,
+    
+    // Core Components
+    SessionManager,
+    EnhancedSessionManager,
+    RoleManager,
+    PermissionChecker,
+    
+    // Strategies
+    TraditionalAuthStrategy,
+    OAuthStrategy,
+    
+    // Token Management
+    TokenValidator,
+    RefreshTokenManager,
+    TokenBlacklist,
+    
+    // Security
+    RateLimiterService,
+    CSRFProtection,
+    
+    // Repositories
+    UserRepository,
+    SessionRepository,
+    ConnectedAccountRepository,
+
+    
+    // Session Store
+    {
+      provide: 'SessionStore',
+      useClass: MemoryStore,
+    },
+    
+    // Configuration Providers
+    {
+      provide: 'JWT_CONFIG',
+      useValue: {
+        privateKey: globalThis.process.env.JWT_PRIVATE_KEY ?? 'default-private-key',
+        publicKey: globalThis.process.env.JWT_PUBLIC_KEY ?? 'default-public-key',
+        issuer: globalThis.process.env.JWT_ISSUER ?? 'plyaz.com',
+        audience: globalThis.process.env.JWT_AUDIENCE ?? 'plyaz-api',
+        accessTokenTTL: globalThis.parseInt(globalThis.process.env.ACCESS_TOKEN_TTL ?? '900'), // 15 minutes
+        refreshTokenTTL:globalThis.parseInt(globalThis.process.env.REFRESH_TOKEN_TTL ?? '604800'), // 7 days
+      },
+    },
+  ],
+  exports: [
+    // Services
+    AuthService,
+    SessionService,
+    TokenService,
+    AccountService,
+    
+    // Guards
+    AuthGuard,
+    RolesGuard,
+    PermissionsGuard,
+    
+
+    SessionManager,
+    EnhancedSessionManager,
+    RoleManager,
+    PermissionChecker,
+    
+    // Token Management
+    TokenValidator,
+    RefreshTokenManager,
+    
+    // Repositories
+    UserRepository,
+    SessionRepository,
+    ConnectedAccountRepository,
+
+  ],
+})
+export class AuthModule {}

package/src/server/decorators/auth.decorator.ts

@@ -0,0 +1,43 @@
+/**
+ * @fileoverview @Auth() and @Public() decorators
+ * @module @plyaz/auth/server/decorators
+ */
+
+import { applyDecorators, SetMetadata, UseGuards } from '@nestjs/common';
+import { AuthGuard } from '../guards/auth.guard';
+
+export const IS_PUBLIC_KEY = 'isPublic';
+
+/**
+ * Decorator to require authentication for endpoint
+ * Combines @UseGuards(AuthGuard) for convenience
+ * 
+ * @example
+ * ```typescript
+ * @Get('protected')
+ * @Auth()
+ * getProtectedData(@CurrentUser() user: User) {
+ *   return { message: 'This is protected data' };
+ * }
+ * ```
+ */
+export const Auth = (): MethodDecorator & ClassDecorator => 
+  applyDecorators(
+    UseGuards(AuthGuard),
+  );
+
+/**
+ * Decorator to mark endpoint as public (skip authentication)
+ * 
+ * @example
+ * ```typescript
+ * @Get('health')
+ * @Public()
+ * getHealth() {
+ *   return { status: 'ok' };
+ * }
+ * ```
+ */
+
+export const Public = (): MethodDecorator & ClassDecorator => 
+  SetMetadata(IS_PUBLIC_KEY, true);

package/src/server/decorators/auth.decorators.ts

@@ -0,0 +1,31 @@
+import type { ExecutionContext } from '@nestjs/common';
+import { SetMetadata, createParamDecorator } from '@nestjs/common';
+
+// Public decorator
+export const Public = (): MethodDecorator & ClassDecorator =>
+  SetMetadata('isPublic', true);
+
+// Roles decorator
+export const Roles = (...roles: string[]): MethodDecorator & ClassDecorator =>
+  SetMetadata('roles', roles);
+
+// Permissions decorator
+export const Permissions = (...permissions: string[]): MethodDecorator & ClassDecorator =>
+  SetMetadata('permissions', permissions);
+export const CurrentUser = createParamDecorator(
+  (data: unknown, ctx: ExecutionContext) => {
+    const request = ctx.switchToHttp().getRequest();
+    return request.user;
+  },
+);
+
+export const CurrentSession = createParamDecorator(
+  (data: unknown, ctx: ExecutionContext) => {
+    const request = ctx.switchToHttp().getRequest();
+    return request.session;
+  },
+);
+
+export const Auth = ():void => {
+ 
+};

package/src/server/decorators/current-user.decorator.ts

@@ -0,0 +1,49 @@
+/**
+ * @fileoverview @CurrentUser() parameter decorator
+ * @module @plyaz/auth/server/decorators
+ */
+
+import type { ExecutionContext } from '@nestjs/common';
+import { createParamDecorator } from '@nestjs/common';
+import type { User } from '@/common/types/auth.types';
+
+/**
+ * Parameter decorator to inject authenticated user into controller methods
+ * 
+ * @example
+ * ```typescript
+ * @Get('profile')
+ * @Auth()
+ * getProfile(@CurrentUser() user: User) {
+ *   return { id: user.id, email: user.email };
+ * }
+ * ```
+ */
+export const CurrentUser = createParamDecorator(
+  (data: keyof User | undefined, ctx: ExecutionContext): User => {
+    const request = ctx.switchToHttp().getRequest();
+    const user = request.user;
+
+    // Return specific property if requested
+    return data ? user?.[data] : user;
+  },
+);
+
+/**
+ * Get access token from request
+ * 
+ * @example
+ * ```typescript
+ * @Post('logout')
+ * @Auth()
+ * async logout(@CurrentToken() token: string) {
+ *   await this.authService.signOut(token);
+ * }
+ * ```
+ */
+export const CurrentToken = createParamDecorator(
+  (data: unknown, ctx: ExecutionContext): string => {
+    const request = ctx.switchToHttp().getRequest();
+    return request.accessToken;
+  },
+);

package/src/server/decorators/permission.decorator.ts

@@ -0,0 +1,49 @@
+import { SetMetadata } from '@nestjs/common';
+
+/**
+ * Permission decorator metadata key
+ */
+export const PERMISSION_KEY = 'permission';
+
+/**
+ * Permission decorator for setting required permissions
+ * @param resource - Resource name (e.g., 'campaigns', 'users', 'organizations')
+ * @param action - Action name (e.g., 'create', 'read', 'update', 'delete')
+ * @param conditions - Optional conditions for the permission
+ * @returns Method & Class decorator
+ */
+export const Permission = (
+  resource: string,
+  action: string,
+  conditions?: Record<string, string>
+): MethodDecorator & ClassDecorator => {
+  const permissionData = conditions 
+    ? { resource, action, conditions }
+    : [resource, action];
+    
+  return SetMetadata(PERMISSION_KEY, permissionData);
+};
+
+/**
+ * Permissions decorator for setting multiple required permissions
+ * User must have ALL specified permissions
+ * @param permissions - Array of permission objects
+ * @returns Method & Class decorator
+ */
+export const Permissions = (
+  permissions: Array<{ resource: string; action: string; conditions?: Record<string, string> }>
+): MethodDecorator & ClassDecorator => {
+  return SetMetadata('permissions', permissions);
+};
+
+/**
+ * AnyPermission decorator for setting alternative permissions
+ * User must have ANY of the specified permissions
+ * @param permissions - Array of permission objects
+ * @returns Method & Class decorator
+ */
+export const AnyPermission = (
+  permissions: Array<{ resource: string; action: string; conditions?: Record<string, string> }>
+): MethodDecorator & ClassDecorator => {
+  return SetMetadata('anyPermission', permissions);
+};

package/src/server/guards/auth.guard.ts

@@ -0,0 +1,56 @@
+import type { CanActivate, ExecutionContext } from '@nestjs/common';
+import { Injectable } from '@nestjs/common';
+import type { Reflector } from '@nestjs/core';
+
+import type { SessionManager } from '../../core/session/session.manager';
+import { AuthenticationError } from '@plyaz/errors';
+import type { JwtManager } from '@/core';
+
+@Injectable()
+export class AuthGuard implements CanActivate {
+  constructor(
+    private jwtManager: JwtManager,
+    private sessionManager: SessionManager,
+    private reflector: Reflector
+  ) {}
+
+  // Explicit return type for canActivate
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    const isPublic: boolean | undefined = this.reflector.get<boolean>('isPublic', context.getHandler());
+    if (isPublic) return true;
+
+    const request = context.switchToHttp().getRequest();
+    const token: string | null = this.extractToken(request);
+    if (!token) throw new AuthenticationError('AUTH_TOKEN_INVALID');
+
+    try {
+      const payload = this.jwtManager.verifyAccessToken(token);
+      const session = await this.sessionManager.getSession(payload.sessionId);
+
+      if (!session) throw new AuthenticationError('AUTH_SESSION_EXPIRED');
+
+      await this.sessionManager.updateLastActive(session.id);
+
+      // Attach user and session to request
+      request.user = payload;
+      request.session = session;
+
+      return true;
+    } catch (error: unknown) {
+      if (error instanceof Error) {
+        if (error.name === 'TokenExpiredError') {
+          throw new AuthenticationError('AUTH_TOKEN_EXPIRED');
+        }
+      }
+      throw new AuthenticationError('AUTH_TOKEN_INVALID');
+    }
+  }
+
+  // Explicit return type for private helper
+  private extractToken(request: { headers: { authorization?: string } }): string | null {
+    const authHeader = request.headers.authorization;
+    if (!authHeader?.startsWith('Bearer ')) return null;
+    const seven  = 7;
+    return authHeader.substring(seven);
+  }
+}

package/src/server/guards/custom-throttler.guard.ts

@@ -0,0 +1,46 @@
+import type {
+  CanActivate,
+  ExecutionContext} from "@nestjs/common";
+import {
+  Injectable,
+  BadRequestException,
+} from "@nestjs/common";
+import type { RateLimiterService } from "../services/rate-limiter.service";
+
+@Injectable()
+export class RateLimiterGuard implements CanActivate {
+  constructor(private readonly rateLimiterService: RateLimiterService) {}
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    const req = context.switchToHttp().getRequest();
+
+    // Get IP address from headers or socket
+    const ip =
+      req.headers["x-forwarded-for"]?.split(",")[0] ??
+      req.ip ??
+      req.socket?.remoteAddress;
+    const identifier = `${ip}`;
+
+    // Construct route key, e.g., "POST /auth/signin"
+    const routeKey = `${req.method} ${req.route.path}`;
+
+    // Get rate limit options for this route
+    const options = this.rateLimiterService.getOption(routeKey);
+
+    // If no rate limit configured, allow request
+    if (options === undefined) return true;
+
+    // Check if the request is rate limited
+    const isLimited = await this.rateLimiterService.isRateLimited(
+      identifier,
+      options
+    );
+
+    if (isLimited)
+      throw new BadRequestException(
+        "Too many requests, please try again later"
+      );
+
+    return true;
+  }
+}

package/src/server/guards/permissions.guard.ts

@@ -0,0 +1,115 @@
+import  { Injectable, type CanActivate, type ExecutionContext } from '@nestjs/common';
+
+import type { Reflector } from '@nestjs/core';
+import type { PermissionChecker } from '../../rbac/permission-checker';
+import { AuthenticationError } from '@plyaz/errors';
+
+/**
+ * Typed request interface including user and request data
+ */
+interface TypedRequest {
+  user?: {
+    sub?: string;
+    userId?: string;
+  };
+  params?: Record<string, string>;
+  query?: Record<string, string>;
+  body?: Record<string, string>;
+  permissionResult?: unknown;
+}
+
+/**
+ * Permission metadata interface
+ */
+interface PermissionMetadata {
+  resource: string;
+  action: string;
+  conditions?: Record<string, string>;
+}
+
+@Injectable()
+export class PermissionsGuard implements CanActivate {
+  constructor(
+    private readonly reflector: Reflector,
+    private readonly permissionChecker: PermissionChecker
+  ) {}
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    const request: TypedRequest = context.switchToHttp().getRequest();
+    const permissionMetadata = this.getPermissionMetadata(context);
+
+    if (!permissionMetadata) return true; // no permission required
+
+    const user = request.user;
+    if (!user) {
+      throw new AuthenticationError(
+        'AUTH_INVALID_CREDENTIALS'
+      );
+    }
+
+    const permissionContext = this.buildPermissionContext(request, permissionMetadata);
+
+    const result = await this.permissionChecker.checkPermission(
+      user.sub ?? user.userId ?? '',
+      permissionMetadata.resource,
+      permissionMetadata.action,
+      permissionContext
+    );
+
+    if (!result.granted) {
+      throw new AuthenticationError(
+        'AUTH_INSUFFICIENT_PERMISSIONS'
+      );
+    }
+
+    request.permissionResult = result; // attach for handler usage
+
+    return true;
+  }
+
+  private getPermissionMetadata(context: ExecutionContext): PermissionMetadata | null {
+    const permissionData = this.reflector.get<[string, string] | PermissionMetadata>(
+      'permission',
+      context.getHandler()
+    );
+
+    if (!permissionData) return null;
+
+    if (Array.isArray(permissionData)) {
+      return { resource: permissionData[0], action: permissionData[1] };
+    }
+
+    return permissionData;
+  }
+
+  private buildPermissionContext(
+    request: TypedRequest,
+    metadata: PermissionMetadata
+  ): Record<string, string> {
+    const context: Record<string, string> = {};
+
+    if (request.user) {
+      context.ownerId = request.user.sub ?? request.user.userId ?? '';
+    }
+
+    if (request.params) Object.assign(context, request.params);
+
+    if (request.query) {
+      const relevantQueryParams = ['organizationId', 'teamId', 'projectId'];
+      for (const param of relevantQueryParams) {
+        if (request.query[param]) context[param] = request.query[param];
+      }
+    }
+
+    if (request.body) {
+      const relevantBodyFields = ['ownerId', 'organizationId', 'teamId', 'projectId'];
+      for (const field of relevantBodyFields) {
+        if (request.body[field]) context[field] = request.body[field];
+      }
+    }
+
+    if (metadata.conditions) Object.assign(context, metadata.conditions);
+
+    return context;
+  }
+}

package/src/server/guards/roles.guard.ts

@@ -0,0 +1,31 @@
+import type { CanActivate, ExecutionContext } from '@nestjs/common';
+import { Injectable } from '@nestjs/common';
+import type { Reflector } from '@nestjs/core';
+import type { RoleManager } from '../../rbac/role.manager';
+import { AuthenticationError } from '@plyaz/errors';
+
+
+@Injectable()
+export class RolesGuard implements CanActivate {
+  constructor(
+    private roleManager: RoleManager,
+    private reflector: Reflector
+  ) {}
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    const requiredRoles = this.reflector.get<string[]>('roles', context.getHandler());
+    if (!requiredRoles) return true;
+
+    const request = context.switchToHttp().getRequest();
+    const user = request.user;
+    
+    if (!user) throw new AuthenticationError('AUTH_INVALID_CREDENTIALS');
+
+    const hasRole = await this.roleManager.hasAnyRole(user.sub, requiredRoles);
+    if (!hasRole) {
+      throw new AuthenticationError('AUTH_ROLE_REQUIRED');
+    }
+
+    return true;
+  }
+}