alepha 0.13.6 → 0.13.7

package/dist/api-audits/index.js

@@ -0,0 +1,674 @@
+import { $inject, $module, Alepha, KIND, Primitive, createPrimitive, t } from "alepha";
+import { $entity, $repository, pageQuerySchema, pg } from "alepha/orm";
+import { $action } from "alepha/server";
+import { $logger } from "alepha/logger";
+
+//#region ../../src/api-audits/entities/audits.ts
+/**
+* Audit severity levels for categorizing events.
+*/
+const auditSeveritySchema = t.enum([
+	"info",
+	"warning",
+	"critical"
+], {
+	default: "info",
+	description: "Severity level of the audit event"
+});
+/**
+* Audit log entity for tracking important system events.
+*
+* Stores comprehensive audit information including:
+* - Who performed the action (userId, userRealm)
+* - What happened (type, action, resource)
+* - When it happened (createdAt)
+* - Context and details (metadata, ipAddress, userAgent)
+*/
+const audits = $entity({
+	name: "audits",
+	schema: t.object({
+		id: pg.primaryKey(t.bigint()),
+		createdAt: pg.createdAt(),
+		type: t.text({ description: "Audit event type (e.g., auth, user, payment, system)" }),
+		action: t.text({ description: "Specific action performed (e.g., login, create, update)" }),
+		severity: pg.default(auditSeveritySchema, "info"),
+		userId: t.optional(t.uuid()),
+		userRealm: t.optional(t.text()),
+		userEmail: t.optional(t.email()),
+		resourceType: t.optional(t.text()),
+		resourceId: t.optional(t.text()),
+		description: t.optional(t.text()),
+		metadata: t.optional(t.json()),
+		ipAddress: t.optional(t.text()),
+		userAgent: t.optional(t.text()),
+		sessionId: t.optional(t.uuid()),
+		requestId: t.optional(t.text()),
+		success: pg.default(t.boolean(), true),
+		errorMessage: t.optional(t.text())
+	}),
+	indexes: [
+		"createdAt",
+		"type",
+		"action",
+		"userId",
+		"userRealm",
+		"resourceType",
+		"resourceId",
+		"severity",
+		{ columns: ["type", "action"] },
+		{ columns: ["userId", "createdAt"] },
+		{ columns: ["userRealm", "createdAt"] }
+	]
+});
+const auditEntitySchema = audits.schema;
+const auditEntityInsertSchema = audits.insertSchema;
+
+//#endregion
+//#region ../../src/api-audits/schemas/auditQuerySchema.ts
+/**
+* Query schema for searching and filtering audit logs.
+*/
+const auditQuerySchema = t.extend(pageQuerySchema, {
+	type: t.optional(t.text({ description: "Filter by audit type" })),
+	action: t.optional(t.text({ description: "Filter by action" })),
+	severity: t.optional(auditSeveritySchema),
+	userId: t.optional(t.uuid({ description: "Filter by user ID" })),
+	userRealm: t.optional(t.text({ description: "Filter by user realm" })),
+	resourceType: t.optional(t.text({ description: "Filter by resource type" })),
+	resourceId: t.optional(t.text({ description: "Filter by resource ID" })),
+	success: t.optional(t.boolean({ description: "Filter by success status" })),
+	from: t.optional(t.datetime({ description: "Start date filter" })),
+	to: t.optional(t.datetime({ description: "End date filter" })),
+	search: t.optional(t.text({ description: "Search in description" }))
+});
+
+//#endregion
+//#region ../../src/api-audits/schemas/auditResourceSchema.ts
+/**
+* Resource schema for audit log responses.
+*/
+const auditResourceSchema = audits.schema;
+
+//#endregion
+//#region ../../src/api-audits/schemas/createAuditSchema.ts
+/**
+* Schema for creating a new audit log entry.
+*/
+const createAuditSchema = t.object({
+	type: t.text({ description: "Audit event type" }),
+	action: t.text({ description: "Specific action performed" }),
+	severity: t.optional(auditSeveritySchema),
+	userId: t.optional(t.uuid()),
+	userRealm: t.optional(t.text()),
+	userEmail: t.optional(t.email()),
+	resourceType: t.optional(t.text()),
+	resourceId: t.optional(t.text()),
+	description: t.optional(t.text()),
+	metadata: t.optional(t.json()),
+	ipAddress: t.optional(t.text()),
+	userAgent: t.optional(t.text()),
+	sessionId: t.optional(t.uuid()),
+	requestId: t.optional(t.text()),
+	success: t.optional(t.boolean()),
+	errorMessage: t.optional(t.text())
+});
+
+//#endregion
+//#region ../../src/api-audits/services/AuditService.ts
+/**
+* Service for managing audit logs.
+*
+* Provides methods for:
+* - Creating audit entries
+* - Querying audit history
+* - Aggregating audit statistics
+* - Managing registered audit types
+*/
+var AuditService = class {
+	alepha = $inject(Alepha);
+	log = $logger();
+	repo = $repository(audits);
+	/**
+	* Registry of audit types and their allowed actions.
+	*/
+	auditTypes = /* @__PURE__ */ new Map();
+	/**
+	* Register an audit type with its allowed actions.
+	*/
+	registerType(definition) {
+		this.auditTypes.set(definition.type, definition);
+		this.log.debug("Audit type registered", {
+			type: definition.type,
+			actions: definition.actions
+		});
+	}
+	/**
+	* Get all registered audit types.
+	*/
+	getRegisteredTypes() {
+		return Array.from(this.auditTypes.values());
+	}
+	/**
+	* Get current request context if available.
+	*/
+	getRequestContext() {
+		return this.alepha.context.get("request");
+	}
+	/**
+	* Create a new audit log entry.
+	* Automatically populates ipAddress, userAgent, and requestId from the current request context.
+	*/
+	async create(data) {
+		const request = this.getRequestContext();
+		const contextData = {};
+		if (request) {
+			if (!data.ipAddress && request.ip) contextData.ipAddress = request.ip;
+			if (!data.userAgent && request.headers["user-agent"]) contextData.userAgent = request.headers["user-agent"];
+			if (!data.requestId && request.requestId) contextData.requestId = request.requestId;
+			if (!data.sessionId && request.metadata?.sessionId) contextData.sessionId = request.metadata.sessionId;
+			const user = request.user;
+			if (user) {
+				if (!data.userId && user.id) contextData.userId = user.id;
+				if (!data.userEmail && user.email) contextData.userEmail = user.email;
+				if (!data.userRealm && user.realm) contextData.userRealm = user.realm;
+			}
+		}
+		this.log.trace("Creating audit entry", {
+			type: data.type,
+			action: data.action,
+			userId: data.userId ?? contextData.userId
+		});
+		const entry = await this.repo.create({
+			...contextData,
+			...data,
+			severity: data.severity ?? "info",
+			success: data.success ?? true
+		});
+		this.log.debug("Audit entry created", {
+			id: entry.id,
+			type: data.type,
+			action: data.action
+		});
+		return entry;
+	}
+	/**
+	* Record an audit event (convenience method).
+	*/
+	async record(type, action, options = {}) {
+		return this.create({
+			type,
+			action,
+			...options
+		});
+	}
+	/**
+	* Record an authentication event.
+	*/
+	async recordAuth(action, options = {}) {
+		return this.create({
+			type: "auth",
+			action,
+			severity: action === "login_failed" ? "warning" : "info",
+			...options
+		});
+	}
+	/**
+	* Record a user management event.
+	*/
+	async recordUser(action, options = {}) {
+		return this.create({
+			type: "user",
+			action,
+			resourceType: "user",
+			...options
+		});
+	}
+	/**
+	* Record a data access event.
+	*/
+	async recordAccess(action, options = {}) {
+		return this.create({
+			type: "access",
+			action,
+			...options
+		});
+	}
+	/**
+	* Record a security event.
+	*/
+	async recordSecurity(action, options = {}) {
+		return this.create({
+			type: "security",
+			action,
+			severity: "warning",
+			...options
+		});
+	}
+	/**
+	* Record a system event.
+	*/
+	async recordSystem(action, options = {}) {
+		return this.create({
+			type: "system",
+			action,
+			severity: action === "error" ? "critical" : "info",
+			...options
+		});
+	}
+	/**
+	* Find audit entries with filtering and pagination.
+	*/
+	async find(query = {}) {
+		this.log.trace("Finding audit entries", { query });
+		query.sort ??= "-createdAt";
+		const where = this.repo.createQueryWhere();
+		if (query.type) where.type = { eq: query.type };
+		if (query.action) where.action = { eq: query.action };
+		if (query.severity) where.severity = { eq: query.severity };
+		if (query.userId) where.userId = { eq: query.userId };
+		if (query.userRealm) where.userRealm = { eq: query.userRealm };
+		if (query.resourceType) where.resourceType = { eq: query.resourceType };
+		if (query.resourceId) where.resourceId = { eq: query.resourceId };
+		if (query.success !== void 0) where.success = { eq: query.success };
+		if (query.from) where.createdAt = {
+			...where.createdAt,
+			gte: query.from
+		};
+		if (query.to) where.createdAt = {
+			...where.createdAt,
+			lte: query.to
+		};
+		if (query.search) where.description = { like: `%${query.search}%` };
+		const result = await this.repo.paginate(query, { where }, { count: true });
+		this.log.debug("Audit entries found", {
+			count: result.content.length,
+			total: result.page.totalElements
+		});
+		return result;
+	}
+	/**
+	* Get audit entry by ID.
+	*/
+	async getById(id) {
+		return this.repo.findById(id);
+	}
+	/**
+	* Get audit entries for a specific user.
+	*/
+	async findByUser(userId, query = {}) {
+		return this.find({
+			...query,
+			userId
+		});
+	}
+	/**
+	* Get audit entries for a specific resource.
+	*/
+	async findByResource(resourceType, resourceId, query = {}) {
+		return this.find({
+			...query,
+			resourceType,
+			resourceId
+		});
+	}
+	/**
+	* Get audit statistics for a time period.
+	*/
+	async getStats(options = {}) {
+		this.log.trace("Getting audit stats", options);
+		const where = this.repo.createQueryWhere();
+		if (options.from) where.createdAt = { gte: options.from.toISOString() };
+		if (options.to) where.createdAt = {
+			...where.createdAt,
+			lte: options.to.toISOString()
+		};
+		if (options.userRealm) where.userRealm = { eq: options.userRealm };
+		const all = await this.repo.findMany({ where });
+		const stats = {
+			total: all.length,
+			byType: {},
+			bySeverity: {
+				info: 0,
+				warning: 0,
+				critical: 0
+			},
+			successRate: 0,
+			recentFailures: []
+		};
+		let successCount = 0;
+		for (const entry of all) {
+			stats.byType[entry.type] = (stats.byType[entry.type] || 0) + 1;
+			const severity = entry.severity;
+			stats.bySeverity[severity]++;
+			if (entry.success) successCount++;
+		}
+		stats.successRate = stats.total > 0 ? successCount / stats.total : 1;
+		stats.recentFailures = all.filter((e) => !e.success).sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime()).slice(0, 10);
+		return stats;
+	}
+	/**
+	* Delete old audit entries (for retention policy).
+	*/
+	async deleteOlderThan(date) {
+		this.log.info("Deleting old audit entries", { olderThan: date });
+		const old = await this.repo.findMany({ where: { createdAt: { lt: date.toISOString() } } });
+		for (const entry of old) await this.repo.deleteById(entry.id);
+		this.log.info("Old audit entries deleted", { count: old.length });
+		return old.length;
+	}
+};
+
+//#endregion
+//#region ../../src/api-audits/controllers/AuditController.ts
+/**
+* REST API controller for audit log management.
+*
+* Provides endpoints for:
+* - Querying audit logs with filtering
+* - Creating audit entries
+* - Getting audit statistics
+* - Viewing registered audit types
+*/
+var AuditController = class {
+	url = "/audits";
+	group = "audits";
+	auditService = $inject(AuditService);
+	/**
+	* Find audit entries with filtering and pagination.
+	*/
+	findAudits = $action({
+		path: this.url,
+		group: this.group,
+		description: "Find audit entries with filtering and pagination",
+		schema: {
+			query: auditQuerySchema,
+			response: pg.page(auditResourceSchema)
+		},
+		handler: ({ query }) => this.auditService.find(query)
+	});
+	/**
+	* Get a single audit entry by ID.
+	*/
+	getAudit = $action({
+		path: `${this.url}/:id`,
+		group: this.group,
+		description: "Get a single audit entry by ID",
+		schema: {
+			params: t.object({ id: t.text() }),
+			response: auditResourceSchema
+		},
+		handler: ({ params }) => this.auditService.getById(params.id)
+	});
+	/**
+	* Create a new audit entry.
+	*/
+	createAudit = $action({
+		method: "POST",
+		path: this.url,
+		group: this.group,
+		description: "Create a new audit entry",
+		schema: {
+			body: createAuditSchema,
+			response: auditResourceSchema
+		},
+		handler: ({ body }) => this.auditService.create(body)
+	});
+	/**
+	* Get audit entries for a specific user.
+	*/
+	findByUser = $action({
+		path: `${this.url}/user/:userId`,
+		group: this.group,
+		description: "Get audit entries for a specific user",
+		schema: {
+			params: t.object({ userId: t.uuid() }),
+			query: t.omit(auditQuerySchema, ["userId"]),
+			response: pg.page(auditResourceSchema)
+		},
+		handler: ({ params, query }) => this.auditService.findByUser(params.userId, query)
+	});
+	/**
+	* Get audit entries for a specific resource.
+	*/
+	findByResource = $action({
+		path: `${this.url}/resource/:resourceType/:resourceId`,
+		group: this.group,
+		description: "Get audit entries for a specific resource",
+		schema: {
+			params: t.object({
+				resourceType: t.text(),
+				resourceId: t.text()
+			}),
+			query: t.omit(auditQuerySchema, ["resourceType", "resourceId"]),
+			response: pg.page(auditResourceSchema)
+		},
+		handler: ({ params, query }) => this.auditService.findByResource(params.resourceType, params.resourceId, query)
+	});
+	/**
+	* Get audit statistics.
+	*/
+	getStats = $action({
+		path: `${this.url}/stats`,
+		group: this.group,
+		description: "Get audit statistics for a time period",
+		schema: {
+			query: t.object({
+				from: t.optional(t.datetime()),
+				to: t.optional(t.datetime()),
+				userRealm: t.optional(t.text())
+			}),
+			response: t.object({
+				total: t.integer(),
+				byType: t.record(t.text(), t.integer()),
+				bySeverity: t.object({
+					info: t.integer(),
+					warning: t.integer(),
+					critical: t.integer()
+				}),
+				successRate: t.number(),
+				recentFailures: t.array(auditResourceSchema)
+			})
+		},
+		handler: ({ query }) => this.auditService.getStats({
+			from: query.from ? new Date(query.from) : void 0,
+			to: query.to ? new Date(query.to) : void 0,
+			userRealm: query.userRealm
+		})
+	});
+	/**
+	* Get registered audit types.
+	*/
+	getTypes = $action({
+		path: `${this.url}/types`,
+		group: this.group,
+		description: "Get all registered audit types",
+		schema: { response: t.array(t.object({
+			type: t.text(),
+			description: t.optional(t.text()),
+			actions: t.array(t.text())
+		})) },
+		handler: () => this.auditService.getRegisteredTypes()
+	});
+	/**
+	* Get distinct values for filters.
+	*/
+	getFilterOptions = $action({
+		path: `${this.url}/filters`,
+		group: this.group,
+		description: "Get distinct values for audit filters",
+		schema: { response: t.object({
+			types: t.array(t.text()),
+			actions: t.array(t.text()),
+			resourceTypes: t.array(t.text()),
+			userRealms: t.array(t.text())
+		}) },
+		handler: async () => {
+			const types = this.auditService.getRegisteredTypes();
+			return {
+				types: types.map((t$1) => t$1.type),
+				actions: types.flatMap((t$1) => t$1.actions),
+				resourceTypes: [
+					"user",
+					"session",
+					"file",
+					"order",
+					"payment"
+				],
+				userRealms: ["default"]
+			};
+		}
+	});
+};
+
+//#endregion
+//#region ../../src/api-audits/primitives/$audit.ts
+/**
+* Audit type primitive for registering domain-specific audit events.
+*
+* Provides a type-safe way to define and log audit events within a specific domain.
+*
+* @example
+* ```ts
+* class PaymentAudits {
+*   audit = $audit({
+*     type: "payment",
+*     description: "Payment-related audit events",
+*     actions: ["create", "refund", "cancel", "dispute"],
+*   });
+*
+*   async logPaymentCreated(paymentId: string, userId: string, amount: number) {
+*     await this.audit.log("create", {
+*       userId,
+*       resourceType: "payment",
+*       resourceId: paymentId,
+*       description: `Payment of ${amount} created`,
+*       metadata: { amount },
+*     });
+*   }
+* }
+* ```
+*/
+var AuditPrimitive = class extends Primitive {
+	auditService = $inject(AuditService);
+	/**
+	* The audit type identifier.
+	*/
+	get type() {
+		return this.options.type;
+	}
+	/**
+	* The audit type description.
+	*/
+	get description() {
+		return this.options.description;
+	}
+	/**
+	* The allowed actions for this audit type.
+	*/
+	get actions() {
+		return this.options.actions;
+	}
+	/**
+	* Log an audit event for this type.
+	*/
+	async log(action, options = {}) {
+		await this.auditService.record(this.options.type, action, options);
+	}
+	/**
+	* Log a successful audit event.
+	*/
+	async logSuccess(action, options = {}) {
+		await this.log(action, {
+			...options,
+			success: true
+		});
+	}
+	/**
+	* Log a failed audit event.
+	*/
+	async logFailure(action, errorMessage, options = {}) {
+		await this.log(action, {
+			...options,
+			success: false,
+			errorMessage
+		});
+	}
+	/**
+	* Called during initialization to register this audit type.
+	*/
+	onInit() {
+		const definition = {
+			type: this.options.type,
+			description: this.options.description,
+			actions: this.options.actions
+		};
+		this.auditService.registerType(definition);
+	}
+};
+/**
+* Create an audit type primitive.
+*
+* @example
+* ```ts
+* class OrderAudits {
+*   audit = $audit({
+*     type: "order",
+*     description: "Order management events",
+*     actions: ["create", "update", "cancel", "fulfill", "ship"],
+*   });
+* }
+* ```
+*/
+const $audit = (options) => {
+	return createPrimitive(AuditPrimitive, options);
+};
+$audit[KIND] = AuditPrimitive;
+
+//#endregion
+//#region ../../src/api-audits/index.ts
+/**
+* Provides audit logging API endpoints for Alepha applications.
+*
+* This module includes:
+* - Audit log CRUD operations
+* - Filtering and searching audit events
+* - Audit statistics and analytics
+* - `$audit` primitive for domain-specific audit types
+*
+* @module alepha.api.audits
+*
+* @example
+* ```ts
+* // In your app module
+* import { AlephaApiAudits } from "alepha/api/audits";
+*
+* const App = $module({
+*   name: "app",
+*   services: [AlephaApiAudits, ...],
+* });
+*
+* // Create domain-specific audit types
+* class PaymentAudits {
+*   audit = $audit({
+*     type: "payment",
+*     actions: ["create", "refund", "cancel"],
+*   });
+*
+*   async onPaymentCreated(paymentId: string, userId: string) {
+*     await this.audit.log("create", {
+*       userId,
+*       resourceType: "payment",
+*       resourceId: paymentId,
+*     });
+*   }
+* }
+* ```
+*/
+const AlephaApiAudits = $module({
+	name: "alepha.api.audits",
+	services: [AuditService, AuditController]
+});
+
+//#endregion
+export { $audit, AlephaApiAudits, AuditController, AuditPrimitive, AuditService, auditEntityInsertSchema, auditEntitySchema, auditQuerySchema, auditResourceSchema, auditSeveritySchema, audits, createAuditSchema };
+//# sourceMappingURL=index.js.map