authentication.tsā¢11.4 kB
/**
* EuConquisto Composer MCP Server - Authentication Interface
*
* @version 0.1.0
* @created 2025-06-08
* @updated 2025-06-08
* @author EuConquisto Development Team
*
* @description TypeScript interfaces for authentication and authorization
* management, including user management, session handling, and security.
*
* @testStatus PENDING
* @coverage 0%
*
* @dependencies
* - TypeScript 5.0+
* - Node.js types
* - mcp-server.ts
*
* @supersedes N/A
* @supersededBy N/A
*/
// Core Authentication Interfaces
export interface AuthenticationManager {
authenticate(credentials: AuthCredentials): Promise<AuthResult>;
authorize(token: string, resource: string, action: string): Promise<AuthorizationResult>;
refreshToken(refreshToken: string): Promise<TokenRefreshResult>;
logout(sessionId: string): Promise<boolean>;
validateToken(token: string): Promise<TokenValidationResult>;
revokeToken(token: string): Promise<boolean>;
}
export interface AuthCredentials {
type: 'password' | 'token' | 'oauth' | 'apikey' | 'certificate';
identifier: string; // username, email, client_id, etc.
secret?: string; // password, client_secret, api_key, etc.
provider?: string; // oauth provider name
additionalData?: Record<string, any>;
}
export interface AuthResult {
success: boolean;
user?: User;
session?: UserSession;
tokens?: AuthTokens;
error?: AuthError;
metadata?: AuthMetadata;
}
export interface AuthTokens {
accessToken: string;
refreshToken?: string;
tokenType: 'Bearer' | 'API-Key' | 'Custom';
expiresIn: number;
scope?: string[];
}
export interface AuthError {
code: string;
message: string;
details?: Record<string, any>;
retryAfter?: number;
}
export interface AuthMetadata {
provider: string;
method: string;
timestamp: string;
ipAddress?: string;
userAgent?: string;
location?: string;
}
// User Management Interfaces
export interface User {
id: string;
username: string;
email: string;
firstName?: string;
lastName?: string;
displayName?: string;
avatar?: string;
status: 'active' | 'inactive' | 'suspended' | 'pending';
roles: Role[];
permissions: Permission[];
profile: UserProfile;
preferences: UserPreferences;
metadata: UserMetadata;
}
export interface Role {
id: string;
name: string;
description?: string;
permissions: Permission[];
isSystem: boolean;
hierarchy: number;
}
export interface Permission {
id: string;
resource: string;
action: string;
conditions?: PermissionCondition[];
effect: 'allow' | 'deny';
}
export interface PermissionCondition {
field: string;
operator: 'eq' | 'ne' | 'in' | 'nin' | 'gt' | 'gte' | 'lt' | 'lte' | 'contains' | 'startsWith';
value: any;
}
export interface UserProfile {
bio?: string;
organization?: string;
department?: string;
title?: string;
phone?: string;
timezone?: string;
locale?: string;
socialLinks?: Record<string, string>;
}
export interface UserPreferences {
language: string;
theme: 'light' | 'dark' | 'auto';
notifications: NotificationPreferences;
privacy: PrivacySettings;
accessibility: AccessibilitySettings;
}
export interface NotificationPreferences {
email: boolean;
push: boolean;
sms: boolean;
inApp: boolean;
frequency: 'immediate' | 'hourly' | 'daily' | 'weekly';
types: string[];
}
export interface PrivacySettings {
profileVisibility: 'public' | 'restricted' | 'private';
activityTracking: boolean;
dataSharing: boolean;
analyticsOptOut: boolean;
}
export interface AccessibilitySettings {
screenReader: boolean;
highContrast: boolean;
largeText: boolean;
keyboardNavigation: boolean;
reducedMotion: boolean;
}
export interface UserMetadata {
created: string;
updated: string;
lastLogin?: string;
loginCount: number;
emailVerified: boolean;
phoneVerified: boolean;
twoFactorEnabled: boolean;
passwordLastChanged?: string;
accountLocked?: boolean;
lockReason?: string;
tags: string[];
}
// Session Management Interfaces
export interface UserSession {
id: string;
userId: string;
status: 'active' | 'expired' | 'terminated';
created: string;
lastActivity: string;
expiresAt: string;
ipAddress?: string;
userAgent?: string;
location?: SessionLocation;
devices: SessionDevice[];
metadata: SessionMetadata;
}
export interface SessionLocation {
country?: string;
region?: string;
city?: string;
latitude?: number;
longitude?: number;
timezone?: string;
}
export interface SessionDevice {
id: string;
type: 'desktop' | 'mobile' | 'tablet' | 'other';
os?: string;
browser?: string;
version?: string;
trusted: boolean;
}
export interface SessionMetadata {
loginMethod: string;
provider?: string;
riskScore?: number;
flags: string[];
data: Record<string, any>;
}
export interface SessionManager {
createSession(userId: string, metadata: Partial<SessionMetadata>): Promise<UserSession>;
getSession(sessionId: string): Promise<UserSession | null>;
updateSession(sessionId: string, updates: Partial<UserSession>): Promise<UserSession>;
terminateSession(sessionId: string): Promise<boolean>;
getUserSessions(userId: string): Promise<UserSession[]>;
cleanupExpiredSessions(): Promise<number>;
}
// Authentication Provider Interfaces
export interface AuthProvider {
name: string;
type: 'local' | 'oauth' | 'saml' | 'ldap' | 'api';
config: AuthProviderConfig;
initialize(): Promise<void>;
authenticate(credentials: AuthCredentials): Promise<AuthResult>;
authorize(token: string, resource: string, action: string): Promise<AuthorizationResult>;
getUserInfo(token: string): Promise<User | null>;
refreshToken(refreshToken: string): Promise<TokenRefreshResult>;
revokeToken(token: string): Promise<boolean>;
}
export interface AuthProviderConfig {
enabled: boolean;
priority: number;
settings: Record<string, any>;
endpoints?: ProviderEndpoints;
clientCredentials?: ClientCredentials;
validation?: ValidationSettings;
}
export interface ProviderEndpoints {
authorize?: string;
token?: string;
userInfo?: string;
revoke?: string;
logout?: string;
}
export interface ClientCredentials {
clientId: string;
clientSecret: string;
scope?: string[];
audience?: string;
}
export interface ValidationSettings {
validateCertificates: boolean;
allowedIssuers?: string[];
requiredClaims?: string[];
clockSkew?: number;
}
// OAuth Specific Interfaces
export interface OAuthProvider extends AuthProvider {
type: 'oauth';
getAuthorizationUrl(state: string, redirectUri: string): string;
exchangeCodeForToken(code: string, redirectUri: string): Promise<AuthTokens>;
validateState(state: string): boolean;
}
export interface OAuthConfig extends AuthProviderConfig {
authorizationEndpoint: string;
tokenEndpoint: string;
userInfoEndpoint: string;
scope: string[];
responseType: 'code' | 'token' | 'id_token';
redirectUri: string;
pkceEnabled: boolean;
}
// Authorization Interfaces
export interface AuthorizationResult {
allowed: boolean;
reason?: string;
conditions?: Record<string, any>;
metadata?: Record<string, any>;
}
export interface TokenValidationResult {
valid: boolean;
expired: boolean;
user?: User;
permissions?: Permission[];
claims?: Record<string, any>;
error?: string;
}
export interface TokenRefreshResult {
success: boolean;
tokens?: AuthTokens;
error?: AuthError;
}
// Security Interfaces
export interface SecurityConfig {
passwordPolicy: PasswordPolicy;
sessionSecurity: SessionSecurity;
rateLimiting: RateLimitingConfig;
fraudDetection: FraudDetectionConfig;
encryption: EncryptionConfig;
}
export interface PasswordPolicy {
minLength: number;
requireUppercase: boolean;
requireLowercase: boolean;
requireNumbers: boolean;
requireSpecialChars: boolean;
preventReuse: number;
expiration: number;
complexityScore: number;
}
export interface SessionSecurity {
httpOnly: boolean;
secure: boolean;
sameSite: 'strict' | 'lax' | 'none';
maxAge: number;
inactivityTimeout: number;
concurrentSessions: number;
ipValidation: boolean;
userAgentValidation: boolean;
}
export interface RateLimitingConfig {
login: RateLimit;
tokenRefresh: RateLimit;
passwordReset: RateLimit;
apiRequests: RateLimit;
}
export interface RateLimit {
windowMs: number;
maxAttempts: number;
blockDuration: number;
skipSuccessful: boolean;
}
export interface FraudDetectionConfig {
enabled: boolean;
riskScoring: boolean;
deviceFingerprinting: boolean;
velocityChecks: boolean;
geoLocationChecks: boolean;
suspiciousActivityDetection: boolean;
}
export interface EncryptionConfig {
algorithm: string;
keySize: number;
saltLength: number;
iterations: number;
tokenEncryption: boolean;
databaseEncryption: boolean;
}
// Audit and Logging Interfaces
export interface AuthAuditLog {
id: string;
timestamp: string;
userId?: string;
sessionId?: string;
action: string;
resource?: string;
result: 'success' | 'failure' | 'warning';
ipAddress?: string;
userAgent?: string;
location?: string;
details: Record<string, any>;
riskScore?: number;
}
export interface AuthAuditor {
logEvent(event: Partial<AuthAuditLog>): Promise<void>;
getAuditLogs(filters: AuditLogFilters): Promise<AuthAuditLog[]>;
analyzeRisk(userId: string, action: string, context: Record<string, any>): Promise<number>;
detectAnomalies(userId: string, timeWindow: number): Promise<AnomalyReport>;
}
export interface AuditLogFilters {
userId?: string;
sessionId?: string;
action?: string;
result?: string;
dateRange?: {
start: string;
end: string;
};
ipAddress?: string;
riskScore?: {
min: number;
max: number;
};
limit?: number;
offset?: number;
}
export interface AnomalyReport {
userId: string;
timeWindow: number;
anomalies: DetectedAnomaly[];
riskScore: number;
recommendations: string[];
}
export interface DetectedAnomaly {
type: string;
description: string;
severity: 'low' | 'medium' | 'high' | 'critical';
confidence: number;
details: Record<string, any>;
}
// Two-Factor Authentication Interfaces
export interface TwoFactorAuth {
generateSecret(userId: string): Promise<TwoFactorSecret>;
verifyCode(userId: string, code: string): Promise<boolean>;
generateBackupCodes(userId: string): Promise<string[]>;
verifyBackupCode(userId: string, code: string): Promise<boolean>;
disable(userId: string): Promise<boolean>;
getStatus(userId: string): Promise<TwoFactorStatus>;
}
export interface TwoFactorSecret {
secret: string;
qrCode: string;
backupCodes: string[];
issuer: string;
accountName: string;
}
export interface TwoFactorStatus {
enabled: boolean;
backupCodesRemaining: number;
lastUsed?: string;
method: 'totp' | 'sms' | 'email' | 'app';
}
// Utility Types
export type AuthMethod = 'password' | 'oauth' | 'apikey' | 'certificate' | 'biometric';
export type UserStatus = 'active' | 'inactive' | 'suspended' | 'pending';
export type SessionStatus = 'active' | 'expired' | 'terminated';
export type AuthAction = 'login' | 'logout' | 'refresh' | 'authorize' | 'revoke';
export type PermissionEffect = 'allow' | 'deny';
export type RoleType = 'system' | 'custom';
export type AuthEventType = 'login' | 'logout' | 'token_refresh' | 'permission_check' |
'password_change' | 'profile_update' | 'suspicious_activity';