@plyaz/auth 1.0.0

package/src/common/types/auth.types.ts

@@ -0,0 +1,641 @@
+/**
+ * @fileoverview Core authentication types and interfaces for @plyaz/auth
+ * @module @plyaz/auth/types
+ * 
+ * @description
+ * Defines all TypeScript interfaces, enums, and types for the authentication system.
+ * Includes B2C (public) and B2B (backoffice) user types, sessions, RBAC, and provider adapters.
+ * All types match database schema exactly (snake_case in DB, camelCase in TS).
+ */
+
+// ============================================
+// ENUMS
+// ============================================
+
+/**
+ * User role assignment status
+ * @enum {string}
+ */
+export enum USER_ROLE_STATUS {
+  /** Role is active and grants permissions */
+  ACTIVE = 'ACTIVE',
+  /** Role is inactive (temporarily disabled) */
+  INACTIVE = 'INACTIVE',
+  /** Role is suspended (user violation) */
+  SUSPENDED = 'SUSPENDED'
+}
+
+/**
+ * Authentication provider types
+ * @enum {string}
+ */
+export enum AUTHPROVIDER {
+  /** Email/password authentication */
+  EMAIL = 'EMAIL',
+  /** Clerk authentication */
+  CLERK = 'CLERK',
+  /** Google OAuth */
+  GOOGLE = 'GOOGLE',
+  /** Facebook OAuth */
+  FACEBOOK = 'FACEBOOK',
+  /** Apple Sign In */
+  APPLE = 'APPLE',
+  /** Web3 wallet authentication */
+  WEB3 = 'WEB3'
+}
+
+/**
+ * Token type for authentication
+ * @enum {string}
+ */
+export enum TOKENTYPE {
+  /** Bearer token */
+  BEARER = 'Bearer',
+  /** JSON Web Token */
+  JWT = 'JWT'
+}
+
+// ============================================
+// CORE USER TYPES
+// ============================================
+
+/**
+ * B2C User (public schema)
+ * Represents platform users: fans, athletes, clubs, scouts, agents
+ * 
+ * @interface User
+ * @property {string} id - Unique user identifier (UUID)
+ * @property {string} email - User email address (unique)
+ * @property {string} [clerkUserId] - Clerk provider user ID
+ * @property {string} authProvider - Authentication provider used
+ * @property {string} [firstName] - User first name
+ * @property {string} [lastName] - User last name
+ * @property {string} displayName - Display name (required)
+ * @property {string} [avatarUrl] - Avatar image URL
+ * @property {string} [phoneNumber] - Phone number
+ * @property {boolean} isActive - Account active status
+ * @property {boolean} isVerified - Email verification status
+ * @property {Date} createdAt - Account creation timestamp
+ * @property {Date} updatedAt - Last update timestamp
+ * @property {Date} [lastLoginAt] - Last login timestamp
+ */
+export interface User {
+  id: string;
+  email: string;
+  clerkUserId?: string;
+  authProvider: string;
+  firstName?: string;
+  lastName?: string;
+  displayName: string;
+  avatarUrl?: string;
+  phoneNumber?: string;
+  isActive: boolean;
+  isVerified: boolean;
+  createdAt: Date;
+  updatedAt: Date;
+  lastLoginAt?: Date;
+  roles?: string[];
+  passwordHash?: string;
+  isSuspended?: boolean;
+}
+
+/**
+ * B2B User (backoffice schema)
+ * Represents internal staff: admins, moderators, support, finance, compliance
+ * 
+ * @interface BackofficeUser
+ * @property {string} id - Unique user identifier (UUID)
+ * @property {string} email - User email address (unique)
+ * @property {string} passwordHash - Hashed password
+ * @property {string} [clerkUserId] - Clerk provider user ID
+ * @property {string} authProvider - Authentication provider used
+ * @property {string} [firstName] - User first name
+ * @property {string} [lastName] - User last name
+ * @property {string} displayName - Display name (required)
+ * @property {string} [avatarMediaId] - Avatar media UUID reference
+ * @property {string} [phoneNumber] - Phone number
+ * @property {boolean} isActive - Account active status
+ * @property {boolean} isVerified - Email verification status
+ * @property {boolean} isSuspended - Account suspension status
+ * @property {string} [suspensionReason] - Reason for suspension
+ * @property {Date} [suspendedAt] - Suspension timestamp
+ * @property {Date} createdAt - Account creation timestamp
+ * @property {Date} updatedAt - Last update timestamp
+ * @property {Date} [lastLoginAt] - Last login timestamp
+ */
+export interface BackofficeUser {
+  id: string;
+  email: string;
+  passwordHash: string;
+  clerkUserId?: string;
+  authProvider: string;
+  firstName?: string;
+  lastName?: string;
+  displayName: string;
+  avatarMediaId?: string;
+  phoneNumber?: string;
+  isActive: boolean;
+  isVerified: boolean;
+  isSuspended: boolean;
+  suspensionReason?: string;
+  suspendedAt?: Date;
+  createdAt: Date;
+  updatedAt: Date;
+  lastLoginAt?: Date;
+}
+
+// ============================================
+// SESSION TYPES
+// ============================================
+
+/**
+ * B2C Session (public schema)
+ * Tracks authenticated user sessions with device and activity info
+ * 
+ * @interface Session
+ */
+export interface Session {
+  id: string;
+  userId: string;
+  provider: string;
+  providerSessionId?: string;
+  expiresAt: Date;
+  createdAt: Date;
+  lastActivityAt: Date;
+  ipAddress?: string;
+  userAgent?: string;
+  metadata?: Record<string, string>;
+}
+
+/**
+ * B2B Session (backoffice schema)
+ * Tracks authenticated backoffice user sessions
+ * 
+ * @interface BackofficeSession
+ */
+export interface BackofficeSession {
+  id: string;
+  backofficeUserId: string;
+  provider: string;
+  providerSessionId?: string;
+  expiresAt: Date;
+  createdAt: Date;
+  lastActivityAt: Date;
+  ipAddress?: string;
+  userAgent?: string;
+  metadata?: Record<string, string>;
+}
+
+// ============================================
+// CONNECTED ACCOUNT TYPES
+// ============================================
+
+/**
+ * Connected Account (provider linking)
+ * Links external OAuth/Web3 provider accounts to users
+ * Supports OAuth providers (Clerk, Google, etc.) and Web3 wallets
+ * 
+ * @interface ConnectedAccount
+ */
+export interface ConnectedAccount {
+  id: string;
+  userId: string;
+  providerType: string;
+  provider: string;
+  providerAccountId: string;
+  providerEmail?: string;
+  providerUsername?: string;
+  providerDisplayName?: string;
+  providerAvatarUrl?: string;
+  providerProfileUrl?: string;
+  providerMetadata?: Record<string, unknown>;
+  walletAddress?: string;
+  chainId?: string;
+  accessTokenEncrypted?: string;
+  refreshTokenEncrypted?: string;
+  tokenExpiresAt?: Date;
+  tokenScope?: string;
+  isPrimary: boolean;
+  isVerified: boolean;
+  isActive: boolean;
+  linkedAt: Date;
+  linkedIpAddress?: string;
+  linkedUserAgent?: string;
+  lastUsedAt?: Date;
+  lastUsedIpAddress?: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+// ============================================
+// AUTH TOKENS
+// ============================================
+
+/**
+ * Authentication tokens returned after successful login
+ * 
+ * @interface AuthTokens
+ */
+export interface AuthTokens {
+  accessToken: string;
+  refreshToken: string;
+}
+
+// ============================================
+// RBAC TYPES
+// ============================================
+
+/**
+ * B2C Role (public schema)
+ * Defines user roles: FAN, ATHLETE, SCOUT, AGENT, CLUB, DEVELOPER, ADMIN
+ * 
+ * @interface Role
+ */
+export interface Role {
+  id: string;
+  code: string;
+  name: string;
+  description?: string;
+  hierarchy: number;
+  canCreateCampaigns?: boolean;
+  canContribute?: boolean;
+  requiresKyc?: boolean;
+  isActive: boolean;
+  isSystem: boolean;
+  metadata?: Record<string, string>;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/**
+ * B2B Role (backoffice schema)
+ * Defines staff roles: SUPER_ADMIN, ADMIN, MODERATOR, FINANCE, COMPLIANCE, SUPPORT
+ * 
+ * @interface BackofficeRole
+ */
+export interface BackofficeRole {
+  id: string;
+  code: string;
+  name: string;
+  description?: string;
+  hierarchy: number;
+  canApproveCampaigns: boolean;
+  canApproveKyc: boolean;
+  canApprovePayouts: boolean;
+  canManageUsers: boolean;
+  canManageRoles: boolean;
+  canViewAllData: boolean;
+  isActive: boolean;
+  isSystem: boolean;
+  metadata?: Record<string, string>;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/**
+ * Permission (backoffice only)
+ * Fine-grained permissions for backoffice users
+ * 
+ * @interface Permission
+ */
+export interface Permission {
+  id: string;
+  code: string;
+  name: string;
+  description?: string;
+  resource: string;
+  action: string;
+  isActive: boolean;
+  isSystem: boolean;
+  metadata?: Record<string, string>;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/**
+ * Role-Permission mapping (backoffice only)
+ * Links permissions to roles
+ * 
+ * @interface RolePermission
+ */
+export interface RolePermission {
+  id: string;
+  roleId: string;
+  role: string;
+  permissionId: string;
+  grantedAt: Date;
+  grantedBy?: string;
+}
+
+/**
+ * User-Permission mapping (backoffice only)
+ * Grants/revokes specific permissions to users
+ * 
+ * @interface UserPermission
+ */
+export interface UserPermission {
+  id: string;
+  backofficeUserId: string;
+  permissionId: string;
+  isGranted: boolean;
+  expiresAt?: Date;
+  grantedAt: Date;
+  grantedBy?: string;
+  reason?: string;
+}
+
+/**
+ * B2C User-Role assignment
+ * Links users to roles with status tracking
+ * 
+ * @interface UserRole
+ */
+export interface UserRole {
+  id: string;
+  userId: string;
+  roleId: string;
+  role: string;
+  isPrimary: boolean;
+  status: USER_ROLE_STATUS;
+  assignedBy?: string;
+  assignedReason?: string;
+  expiresAt?: Date;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/**
+ * B2B User-Role assignment
+ * Links backoffice users to roles
+ * 
+ * @interface BackofficeUserRole
+ */
+export interface BackofficeUserRole {
+  id: string;
+  backofficeUserId: string;
+  roleId: string;
+  role: string;
+  isPrimary: boolean;
+  status: USER_ROLE_STATUS;
+  assignedBy?: string;
+  assignedReason?: string;
+  expiresAt?: Date;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+// ============================================
+// AUTH PROVIDER ADAPTER INTERFACE
+// ============================================
+
+/**
+ * Authentication provider adapter interface
+ * Defines contract for provider-agnostic authentication
+ * 
+ * @interface AuthProviderAdapter
+ * @example
+ * ```typescript
+ * class ClerkAdapter implements AuthProviderAdapter {
+ *   name = 'clerk';
+ *   async verifyToken(token: string) { ... }
+ *   async getUserInfo(token: string) { ... }
+ * }
+ * ```
+ */
+export interface AuthProviderAdapter {
+  name: string;
+  
+  verifyToken(token: string): Promise<VerifiedToken>;
+  
+  getUserInfo(token: string): Promise<ProviderUserInfo>;
+  
+  refreshToken?(refreshToken: string): Promise<AuthTokens>;
+  
+  revokeToken?(token: string): Promise<void>;
+}
+
+/**
+ * Verified token result
+ * Returned after successful token verification
+ * 
+ * @interface VerifiedToken
+ */
+export interface VerifiedToken {
+  userId: string;
+  provider: string;
+  providerAccountId: string;
+  email?: string;
+  expiresAt?: Date;
+  metadata?: Record<string, string>;
+}
+
+/**
+ * Provider user information
+ * User profile data from external provider
+ * 
+ * @interface ProviderUserInfo
+ */
+export interface ProviderUserInfo {
+  providerAccountId: string;
+  email?: string;
+  displayName?: string;
+  firstName?: string;
+  lastName?: string;
+  avatarUrl?: string;
+  phoneNumber?: string;
+  metadata?: Record<string, string>;
+}
+
+// ============================================
+// REPOSITORY INTERFACES
+// ============================================
+
+/**
+ * User repository interface
+ * Defines data access methods for user management
+ * 
+ * @interface UserRepository
+ */
+export interface UserRepository {
+  findById(id: string): Promise<User | null>;
+  findByEmail(email: string): Promise<User | null>;
+  findByProviderAccount(provider: string, providerAccountId: string): Promise<User | null>;
+  findByCredentials(email: string, passwordHash: string): Promise<User | null>;
+  create(data: CreateUserData): Promise<User>;
+  update(id: string, data: UpdateUserData): Promise<User>;
+  delete(id: string): Promise<void>;
+}
+
+/**
+ * Session repository interface
+ * Defines data access methods for session management
+ * 
+ * @interface SessionRepository
+ */
+export interface SessionRepository {
+  create(data: CreateSessionData): Promise<Session>;
+  findById(id: string): Promise<Session | null>;
+  findByUserId(userId: string): Promise<Session[]>;
+  validate(sessionId: string): Promise<Session | null>;
+  invalidate(sessionId: string): Promise<void>;
+  invalidateAllForUser(userId: string): Promise<void>;
+  updateActivity(sessionId: string): Promise<void>;
+}
+
+/**
+ * Connected account repository interface
+ * Defines data access methods for provider account linking
+ * 
+ * @interface ConnectedAccountRepository
+ */
+export interface ConnectedAccountRepository {
+  create(data: CreateConnectedAccountData): Promise<ConnectedAccount>;
+  findById(id: string): Promise<ConnectedAccount | null>;
+  findByUserId(userId: string): Promise<ConnectedAccount[]>;
+  findByProvider(provider: string, providerAccountId: string): Promise<ConnectedAccount | null>;
+  update(id: string, data: UpdateConnectedAccountData): Promise<ConnectedAccount>;
+  delete(id: string): Promise<void>;
+}
+
+// ============================================
+// DATA TRANSFER OBJECTS
+// ============================================
+
+/**
+ * DTO for creating B2C users
+ * @interface CreateUserData
+ */
+export interface CreateUserData {
+  email: string;
+  clerkUserId?: string;
+  authProvider?: string;
+  firstName?: string;
+  lastName?: string;
+  displayName: string;
+  avatarUrl?: string;
+  phoneNumber?: string;
+  isVerified?: boolean;
+  passwordHash?: string;
+  isActive?: boolean;
+}
+
+/**
+ * DTO for creating B2B users
+ * @interface CreateBackofficeUserData
+ */
+export interface CreateBackofficeUserData {
+  email: string;
+  passwordHash: string;
+  clerkUserId?: string;
+  authProvider?: string;
+  firstName?: string;
+  lastName?: string;
+  displayName: string;
+  avatarMediaId?: string;
+  phoneNumber?: string;
+  isVerified?: boolean;
+}
+
+/**
+ * DTO for updating B2C users
+ * @interface UpdateUserData
+ */
+export interface UpdateUserData {
+  email?: string;
+  clerkUserId?: string;
+  authProvider?: string;
+  firstName?: string;
+  lastName?: string;
+  displayName?: string;
+  avatarUrl?: string;
+  phoneNumber?: string;
+  isActive?: boolean;
+  isVerified?: boolean;
+  lastLoginAt?: Date;
+}
+
+/**
+ * DTO for updating B2B users
+ * @interface UpdateBackofficeUserData
+ */
+export interface UpdateBackofficeUserData {
+  email?: string;
+  passwordHash?: string;
+  clerkUserId?: string;
+  authProvider?: string;
+  firstName?: string;
+  lastName?: string;
+  displayName?: string;
+  avatarMediaId?: string;
+  phoneNumber?: string;
+  isActive?: boolean;
+  isVerified?: boolean;
+  isSuspended?: boolean;
+  suspensionReason?: string;
+  suspendedAt?: Date;
+  lastLoginAt?: Date;
+}
+
+/**
+ * DTO for creating sessions
+ * @interface CreateSessionData
+ */
+export interface CreateSessionData {
+  userId: string;
+  provider: string;
+  providerSessionId?: string;
+  expiresAt: Date;
+  ipAddress?: string;
+  userAgent?: string;
+  metadata?: Record<string, string>;
+}
+
+/**
+ * DTO for creating connected accounts
+ * @interface CreateConnectedAccountData
+ */
+export interface CreateConnectedAccountData {
+  userId: string;
+  providerType: string;
+  provider: string;
+  providerAccountId: string;
+  providerEmail?: string;
+  providerUsername?: string;
+  providerDisplayName?: string;
+  providerAvatarUrl?: string;
+  providerProfileUrl?: string;
+  providerMetadata?: Record<string, unknown>;
+  walletAddress?: string;
+  chainId?: string;
+  accessTokenEncrypted?: string;
+  refreshTokenEncrypted?: string;
+  tokenExpiresAt?: Date;
+  tokenScope?: string;
+  isPrimary?: boolean;
+  isVerified?: boolean;
+  isActive?: boolean;
+  linkedIpAddress?: string;
+  linkedUserAgent?: string;
+}
+
+/**
+ * DTO for updating connected accounts
+ * @interface UpdateConnectedAccountData
+ */
+export interface UpdateConnectedAccountData {
+  providerEmail?: string;
+  providerUsername?: string;
+  providerDisplayName?: string;
+  providerAvatarUrl?: string;
+  providerProfileUrl?: string;
+  providerMetadata?: Record<string, string>;
+  accessTokenEncrypted?: string;
+  refreshTokenEncrypted?: string;
+  tokenExpiresAt?: Date;
+  tokenScope?: string;
+  isPrimary?: boolean;
+  isVerified?: boolean;
+  isActive?: boolean;
+  lastUsedAt?: Date;
+  lastUsedIpAddress?: string;
+}