@korajs/auth 1.0.0-beta.12 → 1.0.0-beta.14

package/src/admin/admin-api.ts

@@ -0,0 +1,327 @@
+import { KoraError } from '@korajs/core'
+import type { AuthUser, StoredUser, UserStore } from '../provider/built-in/user-store'
+import type { Session, SessionStore } from '../session/session'
+import type { AuditAction, AuditLogger } from './audit-log'
+
+// ============================================================================
+// Admin API Types
+// ============================================================================
+
+/**
+ * Configuration for the Admin API.
+ */
+export interface AdminApiConfig {
+	/** User store for managing users */
+	userStore: UserStore
+	/** Session store for managing sessions (optional) */
+	sessionStore?: SessionStore
+	/** Audit logger (optional) */
+	auditLogger?: AuditLogger
+	/**
+	 * Authorization check for the acting admin. When set, every method that
+	 * takes an `adminId` throws {@link AdminUnauthorizedError} unless it returns
+	 * true. Without it, the app must gate access to AdminApi itself.
+	 */
+	isAdmin?: (adminId: string) => boolean | Promise<boolean>
+	/**
+	 * Revoke every credential of a user (defaults to the user store's token
+	 * revocation store). Called by `revokeUserSessions`, `suspend`-style flows
+	 * and `deleteUser`, so JWTs and refresh tokens die with the session rows.
+	 * Pass `authServer.revokeAllForUser` to also end live sync sessions.
+	 */
+	revokeAllForUser?: (userId: string) => Promise<void>
+}
+
+/**
+ * Paginated result set.
+ */
+export interface PaginatedResult<T> {
+	data: T[]
+	total: number
+	limit: number
+	offset: number
+}
+
+/**
+ * User list query parameters.
+ */
+export interface UserListQuery {
+	/** Search by email (substring match) */
+	email?: string
+	/** Filter by email verified status */
+	emailVerified?: boolean
+	/** Maximum number of results */
+	limit?: number
+	/** Offset for pagination */
+	offset?: number
+}
+
+/**
+ * Admin-level user update (different from self-update).
+ */
+export interface AdminUserUpdate {
+	/** Update display name */
+	name?: string
+	/** Set email verified status */
+	emailVerified?: boolean
+	/** Update email (admin override) */
+	email?: string
+}
+
+// ============================================================================
+// Errors
+// ============================================================================
+
+export class AdminApiError extends KoraError {
+	constructor(message: string, code: string, context?: Record<string, unknown>) {
+		super(message, code, context)
+		this.name = 'AdminApiError'
+	}
+}
+
+export class AdminUserNotFoundError extends AdminApiError {
+	constructor(userId: string) {
+		super(`User "${userId}" not found.`, 'ADMIN_USER_NOT_FOUND', { userId })
+	}
+}
+
+export class AdminUnauthorizedError extends AdminApiError {
+	constructor() {
+		super('Admin privileges required.', 'ADMIN_UNAUTHORIZED')
+	}
+}
+
+// ============================================================================
+// AdminApi
+// ============================================================================
+
+/**
+ * Administrative API for managing users, sessions, and system configuration.
+ *
+ * Provides elevated operations that should only be accessible to administrators.
+ * All operations are audit-logged when an AuditLogger is configured.
+ *
+ * @example
+ * ```typescript
+ * const admin = new AdminApi({
+ *   userStore: myUserStore,
+ *   sessionStore: mySessionStore,
+ *   auditLogger: myAuditLogger,
+ * })
+ *
+ * // List users
+ * const { data, total } = await admin.listUsers({ limit: 20 })
+ *
+ * // Suspend a user (revokes all sessions)
+ * await admin.suspendUser('admin-user-id', 'target-user-id', 'Policy violation')
+ * ```
+ */
+export class AdminApi {
+	private readonly userStore: UserStore
+	private readonly sessionStore: SessionStore | null
+	private readonly auditLogger: AuditLogger | null
+	private readonly isAdmin: AdminApiConfig['isAdmin']
+	private readonly revokeAllForUserFn: AdminApiConfig['revokeAllForUser']
+
+	constructor(config: AdminApiConfig) {
+		this.userStore = config.userStore
+		this.sessionStore = config.sessionStore ?? null
+		this.auditLogger = config.auditLogger ?? null
+		this.isAdmin = config.isAdmin
+		this.revokeAllForUserFn = config.revokeAllForUser
+	}
+
+	/** Throws AdminUnauthorizedError unless the configured `isAdmin` accepts the actor. */
+	private async authorize(adminId: string): Promise<void> {
+		if (this.isAdmin && !(await this.isAdmin(adminId))) {
+			throw new AdminUnauthorizedError()
+		}
+	}
+
+	/** Kill every JWT and refresh token of a user, not just session rows (AUTH-7b/AUTH-14). */
+	private async revokeCredentials(userId: string): Promise<void> {
+		if (this.revokeAllForUserFn) {
+			await this.revokeAllForUserFn(userId)
+			return
+		}
+		await this.userStore.getTokenRevocationStore?.()?.revokeAllForUser(userId, Date.now())
+	}
+
+	/**
+	 * Get a user by ID with full details.
+	 */
+	async getUser(adminId: string, userId: string): Promise<AuthUser> {
+		await this.authorize(adminId)
+		const user = await this.userStore.findById(userId)
+		if (!user) {
+			throw new AdminUserNotFoundError(userId)
+		}
+
+		await this.audit('admin.user_lookup', adminId, userId, 'user')
+
+		return toAuthUser(user)
+	}
+
+	/**
+	 * List users with optional filtering and pagination.
+	 */
+	async listUsers(query: UserListQuery = {}): Promise<PaginatedResult<AuthUser>> {
+		const limit = query.limit ?? 50
+		const offset = query.offset ?? 0
+
+		// Get all users (InMemoryUserStore doesn't have a list method, so we use findByEmail with patterns)
+		// For now, we expose a listing helper
+		const allUsers = await this.userStore.listAll()
+
+		let filtered = allUsers
+
+		if (query.email) {
+			const searchEmail = query.email.toLowerCase()
+			filtered = filtered.filter((u) => u.email.toLowerCase().includes(searchEmail))
+		}
+
+		if (query.emailVerified !== undefined) {
+			filtered = filtered.filter((u) => u.emailVerified === query.emailVerified)
+		}
+
+		const total = filtered.length
+		const data = filtered.slice(offset, offset + limit).map(toAuthUser)
+
+		return { data, total, limit, offset }
+	}
+
+	/**
+	 * Update a user's profile (admin-level).
+	 */
+	async updateUser(adminId: string, userId: string, updates: AdminUserUpdate): Promise<AuthUser> {
+		await this.authorize(adminId)
+		const user = await this.userStore.findById(userId)
+		if (!user) {
+			throw new AdminUserNotFoundError(userId)
+		}
+
+		if (updates.name !== undefined) {
+			user.name = updates.name
+		}
+		if (updates.emailVerified !== undefined) {
+			user.emailVerified = updates.emailVerified
+		}
+		if (updates.email !== undefined) {
+			user.email = updates.email.toLowerCase().trim()
+		}
+
+		await this.userStore.update(user)
+
+		await this.audit('user.update', adminId, userId, 'user', { updates })
+
+		return toAuthUser(user)
+	}
+
+	/**
+	 * Delete a user and all associated sessions.
+	 */
+	async deleteUser(adminId: string, userId: string): Promise<void> {
+		await this.authorize(adminId)
+		const user = await this.userStore.findById(userId)
+		if (!user) {
+			throw new AdminUserNotFoundError(userId)
+		}
+
+		// Revoke all sessions and credentials first
+		if (this.sessionStore) {
+			await this.sessionStore.deleteAllForUser(userId)
+		}
+		await this.revokeCredentials(userId)
+
+		await this.userStore.delete(userId)
+
+		await this.audit('user.delete', adminId, userId, 'user')
+	}
+
+	/**
+	 * Get all active sessions for a user.
+	 */
+	async getUserSessions(userId: string): Promise<Session[]> {
+		if (!this.sessionStore) return []
+		return this.sessionStore.listByUserId(userId)
+	}
+
+	/**
+	 * Revoke all sessions for a user.
+	 */
+	async revokeUserSessions(adminId: string, userId: string): Promise<number> {
+		await this.authorize(adminId)
+		await this.revokeCredentials(userId)
+		if (!this.sessionStore) return 0
+
+		const count = await this.sessionStore.deleteAllForUser(userId)
+
+		await this.audit('session.revoke_all', adminId, userId, 'user', { sessionsRevoked: count })
+
+		return count
+	}
+
+	/**
+	 * Revoke a specific session.
+	 */
+	async revokeSession(adminId: string, sessionId: string): Promise<void> {
+		await this.authorize(adminId)
+		if (!this.sessionStore) return
+
+		await this.sessionStore.delete(sessionId)
+
+		await this.audit('session.revoke', adminId, sessionId, 'session')
+	}
+
+	/**
+	 * Get system statistics.
+	 */
+	async getStats(): Promise<{
+		totalUsers: number
+		verifiedUsers: number
+		unverifiedUsers: number
+	}> {
+		const allUsers = await this.userStore.listAll()
+		const verified = allUsers.filter((u) => u.emailVerified).length
+
+		return {
+			totalUsers: allUsers.length,
+			verifiedUsers: verified,
+			unverifiedUsers: allUsers.length - verified,
+		}
+	}
+
+	// --- Private ---
+
+	private async audit(
+		action: AuditAction,
+		actorId: string,
+		targetId: string,
+		targetType: string,
+		metadata?: Record<string, unknown>,
+	): Promise<void> {
+		if (!this.auditLogger) return
+		await this.auditLogger.log({
+			action,
+			actorId,
+			actorType: 'admin',
+			targetId,
+			targetType,
+			metadata,
+		})
+	}
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function toAuthUser(stored: StoredUser): AuthUser {
+	return {
+		id: stored.id,
+		email: stored.email,
+		name: stored.name,
+		emailVerified: stored.emailVerified,
+		createdAt: stored.createdAt,
+	}
+}

package/src/admin/audit-log.ts

@@ -0,0 +1,324 @@
+import { KoraError } from '@korajs/core'
+
+// ============================================================================
+// Audit Log Types
+// ============================================================================
+
+/**
+ * Actions that can be audited.
+ */
+const AUDIT_ACTIONS = [
+	// Auth
+	'user.signup',
+	'user.signin',
+	'user.signout',
+	'user.token_refresh',
+	'user.password_change',
+	'user.password_reset_request',
+	'user.password_reset',
+	'user.email_verify',
+	// MFA
+	'mfa.enable',
+	'mfa.verify_setup',
+	'mfa.verify',
+	'mfa.recovery_used',
+	'mfa.recovery_regenerate',
+	'mfa.disable',
+	// Session
+	'session.create',
+	'session.revoke',
+	'session.revoke_all',
+	'session.expired',
+	// OAuth
+	'oauth.authorize',
+	'oauth.callback',
+	'oauth.link',
+	'oauth.unlink',
+	// User management
+	'user.create',
+	'user.update',
+	'user.delete',
+	'user.suspend',
+	'user.unsuspend',
+	// Org management
+	'org.create',
+	'org.update',
+	'org.delete',
+	'org.member_add',
+	'org.member_remove',
+	'org.member_role_change',
+	'org.ownership_transfer',
+	'org.invitation_create',
+	'org.invitation_accept',
+	'org.invitation_revoke',
+	// Admin
+	'admin.user_lookup',
+	'admin.impersonate',
+	'admin.config_change',
+] as const
+
+export type AuditAction = (typeof AUDIT_ACTIONS)[number]
+
+/**
+ * An audit log entry.
+ */
+export interface AuditEntry {
+	/** Unique entry ID */
+	id: string
+	/** When this event occurred */
+	timestamp: number
+	/** The action that was performed */
+	action: AuditAction
+	/** Who performed the action (user ID, "system", or "anonymous") */
+	actorId: string
+	/** The type of actor */
+	actorType: 'user' | 'admin' | 'system'
+	/** The target of the action (e.g., user ID, org ID, session ID) */
+	targetId: string | null
+	/** The type of target */
+	targetType: string | null
+	/** IP address of the actor */
+	ipAddress: string | null
+	/** User agent */
+	userAgent: string | null
+	/** Whether the action succeeded */
+	success: boolean
+	/** Error message if the action failed */
+	errorMessage: string | null
+	/** Additional structured context */
+	metadata?: Record<string, unknown>
+}
+
+/**
+ * Query parameters for searching audit logs.
+ */
+export interface AuditLogQuery {
+	/** Filter by actor ID */
+	actorId?: string
+	/** Filter by target ID */
+	targetId?: string
+	/** Filter by action(s) */
+	actions?: AuditAction[]
+	/** Filter by success/failure */
+	success?: boolean
+	/** Start time (inclusive) */
+	startTime?: number
+	/** End time (inclusive) */
+	endTime?: number
+	/** Maximum number of entries to return */
+	limit?: number
+	/** Offset for pagination */
+	offset?: number
+}
+
+/**
+ * Store for audit log entries.
+ */
+export interface AuditLogStore {
+	/** Append an audit entry */
+	append(entry: AuditEntry): Promise<void>
+	/** Query audit entries */
+	query(params: AuditLogQuery): Promise<AuditEntry[]>
+	/** Count matching entries */
+	count(params: AuditLogQuery): Promise<number>
+	/** Delete entries older than a given timestamp */
+	purgeOlderThan(timestamp: number): Promise<number>
+}
+
+// ============================================================================
+// Errors
+// ============================================================================
+
+export class AuditLogError extends KoraError {
+	constructor(message: string, code: string, context?: Record<string, unknown>) {
+		super(message, code, context)
+		this.name = 'AuditLogError'
+	}
+}
+
+// ============================================================================
+// InMemoryAuditLogStore
+// ============================================================================
+
+/**
+ * In-memory audit log store for development and testing.
+ */
+export class InMemoryAuditLogStore implements AuditLogStore {
+	private readonly entries: AuditEntry[] = []
+
+	async append(entry: AuditEntry): Promise<void> {
+		this.entries.push({ ...entry })
+	}
+
+	async query(params: AuditLogQuery): Promise<AuditEntry[]> {
+		let results = this.filterEntries(params)
+
+		// Sort by timestamp descending (newest first)
+		results.sort((a, b) => b.timestamp - a.timestamp)
+
+		// Pagination
+		const offset = params.offset ?? 0
+		const limit = params.limit ?? 100
+		results = results.slice(offset, offset + limit)
+
+		return results.map((e) => ({ ...e }))
+	}
+
+	async count(params: AuditLogQuery): Promise<number> {
+		return this.filterEntries(params).length
+	}
+
+	async purgeOlderThan(timestamp: number): Promise<number> {
+		const initialLength = this.entries.length
+		let writeIndex = 0
+		for (let i = 0; i < this.entries.length; i++) {
+			const entry = this.entries[i] as AuditEntry
+			if (entry.timestamp >= timestamp) {
+				this.entries[writeIndex] = entry
+				writeIndex++
+			}
+		}
+		this.entries.length = writeIndex
+		return initialLength - writeIndex
+	}
+
+	private filterEntries(params: AuditLogQuery): AuditEntry[] {
+		return this.entries.filter((e) => {
+			if (params.actorId !== undefined && e.actorId !== params.actorId) return false
+			if (params.targetId !== undefined && e.targetId !== params.targetId) return false
+			if (params.actions !== undefined && !params.actions.includes(e.action)) return false
+			if (params.success !== undefined && e.success !== params.success) return false
+			if (params.startTime !== undefined && e.timestamp < params.startTime) return false
+			if (params.endTime !== undefined && e.timestamp > params.endTime) return false
+			return true
+		})
+	}
+}
+
+// ============================================================================
+// AuditLogger
+// ============================================================================
+
+/**
+ * Structured audit logger for authentication events.
+ *
+ * Records all security-relevant actions for compliance and debugging.
+ * Designed to be plugged into the auth system at key decision points.
+ *
+ * @example
+ * ```typescript
+ * const auditLog = new AuditLogger({
+ *   store: new InMemoryAuditLogStore(),
+ * })
+ *
+ * await auditLog.log({
+ *   action: 'user.signin',
+ *   actorId: 'user-123',
+ *   actorType: 'user',
+ *   success: true,
+ *   ipAddress: '192.168.1.1',
+ * })
+ *
+ * const entries = await auditLog.query({ actorId: 'user-123', limit: 50 })
+ * ```
+ */
+export class AuditLogger {
+	private readonly store: AuditLogStore
+	private readonly retentionMs: number | null
+
+	constructor(config: { store: AuditLogStore; retentionDays?: number }) {
+		this.store = config.store
+		this.retentionMs = config.retentionDays ? config.retentionDays * 24 * 60 * 60 * 1000 : null
+	}
+
+	/**
+	 * Log an audit event.
+	 */
+	async log(params: {
+		action: AuditAction
+		actorId: string
+		actorType?: 'user' | 'admin' | 'system'
+		targetId?: string
+		targetType?: string
+		ipAddress?: string
+		userAgent?: string
+		success?: boolean
+		errorMessage?: string
+		metadata?: Record<string, unknown>
+	}): Promise<AuditEntry> {
+		const entry: AuditEntry = {
+			id: generateAuditId(),
+			timestamp: Date.now(),
+			action: params.action,
+			actorId: params.actorId,
+			actorType: params.actorType ?? 'user',
+			targetId: params.targetId ?? null,
+			targetType: params.targetType ?? null,
+			ipAddress: params.ipAddress ?? null,
+			userAgent: params.userAgent ?? null,
+			success: params.success ?? true,
+			errorMessage: params.errorMessage ?? null,
+			metadata: params.metadata,
+		}
+
+		await this.store.append(entry)
+		return entry
+	}
+
+	/**
+	 * Query audit log entries.
+	 */
+	async query(params: AuditLogQuery): Promise<AuditEntry[]> {
+		return this.store.query(params)
+	}
+
+	/**
+	 * Count matching audit entries.
+	 */
+	async count(params: AuditLogQuery): Promise<number> {
+		return this.store.count(params)
+	}
+
+	/**
+	 * Purge old entries based on retention policy.
+	 * Returns the number of entries purged.
+	 */
+	async purge(): Promise<number> {
+		if (this.retentionMs === null) return 0
+		const cutoff = Date.now() - this.retentionMs
+		return this.store.purgeOlderThan(cutoff)
+	}
+
+	/**
+	 * Get recent activity for a user.
+	 */
+	async getUserActivity(userId: string, limit = 50): Promise<AuditEntry[]> {
+		return this.store.query({ actorId: userId, limit })
+	}
+
+	/**
+	 * Get failed login attempts for a user within a time window.
+	 */
+	async getFailedLogins(userId: string, windowMs: number): Promise<AuditEntry[]> {
+		return this.store.query({
+			targetId: userId,
+			actions: ['user.signin'],
+			success: false,
+			startTime: Date.now() - windowMs,
+		})
+	}
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function generateAuditId(): string {
+	const bytes = new Uint8Array(16)
+	globalThis.crypto.getRandomValues(bytes)
+	let hex = ''
+	for (let i = 0; i < bytes.length; i++) {
+		hex += bytes[i]?.toString(16).padStart(2, '0')
+	}
+	return hex
+}