alepha 0.13.6 → 0.13.8

package/src/api/audits/controllers/AuditController.ts

@@ -0,0 +1,186 @@
+import { $inject, t } from "alepha";
+import { pg } from "alepha/orm";
+import { $action } from "alepha/server";
+import { auditQuerySchema } from "../schemas/auditQuerySchema.ts";
+import { auditResourceSchema } from "../schemas/auditResourceSchema.ts";
+import { createAuditSchema } from "../schemas/createAuditSchema.ts";
+import { AuditService } from "../services/AuditService.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
+ */
+export class AuditController {
+  protected readonly url = "/audits";
+  protected readonly group = "audits";
+  protected readonly auditService = $inject(AuditService);
+
+  /**
+   * Find audit entries with filtering and pagination.
+   */
+  public readonly 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.
+   */
+  public readonly 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.
+   */
+  public readonly 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.
+   */
+  public readonly 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.
+   */
+  public readonly 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.
+   */
+  public readonly 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) : undefined,
+        to: query.to ? new Date(query.to) : undefined,
+        userRealm: query.userRealm,
+      }),
+  });
+
+  /**
+   * Get registered audit types.
+   */
+  public readonly 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.
+   */
+  public readonly 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) => t.type),
+        actions: types.flatMap((t) => t.actions),
+        resourceTypes: ["user", "session", "file", "order", "payment"],
+        userRealms: ["default"],
+      };
+    },
+  });
+}

package/src/api/audits/entities/audits.ts

@@ -0,0 +1,132 @@
+import type { Static } from "alepha";
+import { t } from "alepha";
+import { $entity, pg } from "alepha/orm";
+
+/**
+ * Audit severity levels for categorizing events.
+ */
+export const auditSeveritySchema = t.enum(["info", "warning", "critical"], {
+  default: "info",
+  description: "Severity level of the audit event",
+});
+
+export type AuditSeverity = Static<typeof auditSeveritySchema>;
+
+/**
+ * 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)
+ */
+export const audits = $entity({
+  name: "audits",
+  schema: t.object({
+    id: pg.primaryKey(t.bigint()),
+    createdAt: pg.createdAt(),
+
+    /**
+     * Audit event type (e.g., "auth", "user", "payment", "system").
+     * Used for categorizing and filtering audit events.
+     */
+    type: t.text({
+      description: "Audit event type (e.g., auth, user, payment, system)",
+    }),
+
+    /**
+     * Specific action performed (e.g., "login", "logout", "create", "update", "delete").
+     */
+    action: t.text({
+      description: "Specific action performed (e.g., login, create, update)",
+    }),
+
+    /**
+     * Severity level of the event.
+     */
+    severity: pg.default(auditSeveritySchema, "info"),
+
+    /**
+     * User ID who performed the action (null for system events).
+     */
+    userId: t.optional(t.uuid()),
+
+    /**
+     * User realm for multi-tenant support.
+     */
+    userRealm: t.optional(t.text()),
+
+    /**
+     * User email at the time of the event (denormalized for history).
+     */
+    userEmail: t.optional(t.email()),
+
+    /**
+     * Resource type affected (e.g., "user", "order", "file").
+     */
+    resourceType: t.optional(t.text()),
+
+    /**
+     * Resource ID affected.
+     */
+    resourceId: t.optional(t.text()),
+
+    /**
+     * Human-readable description of the event.
+     */
+    description: t.optional(t.text()),
+
+    /**
+     * Additional metadata/context as JSON.
+     */
+    metadata: t.optional(t.json()),
+
+    /**
+     * Client IP address.
+     */
+    ipAddress: t.optional(t.text()),
+
+    /**
+     * Client user agent.
+     */
+    userAgent: t.optional(t.text()),
+
+    /**
+     * Session ID if applicable.
+     */
+    sessionId: t.optional(t.uuid()),
+
+    /**
+     * Request ID for correlation.
+     */
+    requestId: t.optional(t.text()),
+
+    /**
+     * Whether the action was successful.
+     */
+    success: pg.default(t.boolean(), true),
+
+    /**
+     * Error message if the action failed.
+     */
+    errorMessage: t.optional(t.text()),
+  }),
+  indexes: [
+    "createdAt",
+    "type",
+    "action",
+    "userId",
+    "userRealm",
+    "resourceType",
+    "resourceId",
+    "severity",
+    { columns: ["type", "action"] },
+    { columns: ["userId", "createdAt"] },
+    { columns: ["userRealm", "createdAt"] },
+  ],
+});
+
+export const auditEntitySchema = audits.schema;
+export const auditEntityInsertSchema = audits.insertSchema;
+export type AuditEntity = Static<typeof audits.schema>;

package/src/api/audits/index.browser.ts

@@ -0,0 +1,18 @@
+// Browser exports for api-audits module
+// Only exports types and schemas that are safe for browser usage
+
+export type { AuditController } from "./controllers/AuditController.ts";
+export * from "./entities/audits.ts";
+export type {
+  AuditLogOptions,
+  AuditPrimitive,
+  AuditPrimitiveOptions,
+} from "./primitives/$audit.ts";
+export * from "./schemas/auditQuerySchema.ts";
+export * from "./schemas/auditResourceSchema.ts";
+export * from "./schemas/createAuditSchema.ts";
+export type {
+  AuditService,
+  AuditStats,
+  AuditTypeDefinition,
+} from "./services/AuditService.ts";

package/src/api/audits/index.ts

@@ -0,0 +1,58 @@
+import { $module } from "alepha";
+import { AuditController } from "./controllers/AuditController.ts";
+import { AuditService } from "./services/AuditService.ts";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export * from "./controllers/AuditController.ts";
+export * from "./entities/audits.ts";
+export * from "./primitives/$audit.ts";
+export * from "./schemas/auditQuerySchema.ts";
+export * from "./schemas/auditResourceSchema.ts";
+export * from "./schemas/createAuditSchema.ts";
+export * from "./services/AuditService.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,
+ *     });
+ *   }
+ * }
+ * ```
+ */
+export const AlephaApiAudits = $module({
+  name: "alepha.api.audits",
+  services: [AuditService, AuditController],
+});

package/src/api/audits/primitives/$audit.ts

@@ -0,0 +1,159 @@
+import { $inject, createPrimitive, KIND, Primitive } from "alepha";
+import {
+  AuditService,
+  type AuditTypeDefinition,
+} from "../services/AuditService.ts";
+
+/**
+ * Options for creating an audit type primitive.
+ */
+export interface AuditPrimitiveOptions {
+  /**
+   * Unique audit type identifier (e.g., "auth", "payment", "order").
+   */
+  type: string;
+
+  /**
+   * Human-readable description of this audit type.
+   */
+  description?: string;
+
+  /**
+   * List of allowed actions for this audit type.
+   */
+  actions: string[];
+}
+
+/**
+ * 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 },
+ *     });
+ *   }
+ * }
+ * ```
+ */
+export class AuditPrimitive extends Primitive<AuditPrimitiveOptions> {
+  protected readonly auditService = $inject(AuditService);
+
+  /**
+   * The audit type identifier.
+   */
+  public get type(): string {
+    return this.options.type;
+  }
+
+  /**
+   * The audit type description.
+   */
+  public get description(): string | undefined {
+    return this.options.description;
+  }
+
+  /**
+   * The allowed actions for this audit type.
+   */
+  public get actions(): string[] {
+    return this.options.actions;
+  }
+
+  /**
+   * Log an audit event for this type.
+   */
+  public async log(
+    action: string,
+    options: AuditLogOptions = {},
+  ): Promise<void> {
+    await this.auditService.record(this.options.type, action, options);
+  }
+
+  /**
+   * Log a successful audit event.
+   */
+  public async logSuccess(
+    action: string,
+    options: Omit<AuditLogOptions, "success"> = {},
+  ): Promise<void> {
+    await this.log(action, { ...options, success: true });
+  }
+
+  /**
+   * Log a failed audit event.
+   */
+  public async logFailure(
+    action: string,
+    errorMessage: string,
+    options: Omit<AuditLogOptions, "success" | "errorMessage"> = {},
+  ): Promise<void> {
+    await this.log(action, { ...options, success: false, errorMessage });
+  }
+
+  /**
+   * Called during initialization to register this audit type.
+   */
+  protected onInit(): void {
+    const definition: AuditTypeDefinition = {
+      type: this.options.type,
+      description: this.options.description,
+      actions: this.options.actions,
+    };
+    this.auditService.registerType(definition);
+  }
+}
+
+/**
+ * Options for logging an audit event.
+ */
+export interface AuditLogOptions {
+  severity?: "info" | "warning" | "critical";
+  userId?: string;
+  userRealm?: string;
+  userEmail?: string;
+  resourceType?: string;
+  resourceId?: string;
+  description?: string;
+  metadata?: Record<string, unknown>;
+  ipAddress?: string;
+  userAgent?: string;
+  sessionId?: string;
+  requestId?: string;
+  success?: boolean;
+  errorMessage?: string;
+}
+
+/**
+ * Create an audit type primitive.
+ *
+ * @example
+ * ```ts
+ * class OrderAudits {
+ *   audit = $audit({
+ *     type: "order",
+ *     description: "Order management events",
+ *     actions: ["create", "update", "cancel", "fulfill", "ship"],
+ *   });
+ * }
+ * ```
+ */
+export const $audit = (options: AuditPrimitiveOptions) => {
+  return createPrimitive(AuditPrimitive, options);
+};
+
+$audit[KIND] = AuditPrimitive;

package/src/api/audits/schemas/auditQuerySchema.ts

@@ -0,0 +1,23 @@
+import type { Static } from "alepha";
+import { t } from "alepha";
+import { pageQuerySchema } from "alepha/orm";
+import { auditSeveritySchema } from "../entities/audits.ts";
+
+/**
+ * Query schema for searching and filtering audit logs.
+ */
+export 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" })),
+});
+
+export type AuditQuery = Static<typeof auditQuerySchema>;

package/src/api/audits/schemas/auditResourceSchema.ts

@@ -0,0 +1,9 @@
+import type { Static } from "alepha";
+import { audits } from "../entities/audits.ts";
+
+/**
+ * Resource schema for audit log responses.
+ */
+export const auditResourceSchema = audits.schema;
+
+export type AuditResource = Static<typeof auditResourceSchema>;

package/src/api/audits/schemas/createAuditSchema.ts

@@ -0,0 +1,27 @@
+import type { Static } from "alepha";
+import { t } from "alepha";
+import { auditSeveritySchema } from "../entities/audits.ts";
+
+/**
+ * Schema for creating a new audit log entry.
+ */
+export 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()),
+});
+
+export type CreateAudit = Static<typeof createAuditSchema>;