alepha 0.23.0 → 0.24.0

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

@@ -1,4 +1,4 @@
-import { $inject, t } from "alepha";
+import { $inject, z } from "alepha";
 import { $repository } from "alepha/orm";
 import { $secure } from "alepha/security";
 import { $action } from "alepha/server";
@@ -33,7 +33,7 @@ export class AdminAuditController {
     description: "Find audit entries with filtering and pagination",
     schema: {
       query: auditQuerySchema,
-      response: t.page(auditResourceSchema),
+      response: z.page(auditResourceSchema),
     },
     handler: ({ query }) => this.auditService.find(query),
   });
@@ -47,8 +47,8 @@ export class AdminAuditController {
     use: [$secure({ permissions: ["admin:audit:read"] })],
     description: "Get a single audit entry by ID",
     schema: {
-      params: t.object({
-        id: t.text(),
+      params: z.object({
+        id: z.text(),
       }),
       response: auditResourceSchema,
     },
@@ -66,11 +66,11 @@ export class AdminAuditController {
     use: [$secure({ permissions: ["admin:audit:delete"] })],
     description: "Delete many audit entries",
     schema: {
-      body: t.object({
-        ids: t.array(t.text(), { minItems: 1, maxItems: 1000 }),
+      body: z.object({
+        ids: z.array(z.text()).min(1).max(1000),
       }),
-      response: t.object({
-        deleted: t.array(t.text()),
+      response: z.object({
+        deleted: z.array(z.text()),
       }),
     },
     handler: async ({ body }) => {
@@ -107,11 +107,11 @@ export class AdminAuditController {
     use: [$secure({ permissions: ["admin:audit:read"] })],
     description: "Get audit entries for a specific user",
     schema: {
-      params: t.object({
-        userId: t.uuid(),
+      params: z.object({
+        userId: z.uuid(),
       }),
-      query: t.omit(auditQuerySchema, ["userId"]),
-      response: t.page(auditResourceSchema),
+      query: auditQuerySchema.omit({ userId: true }),
+      response: z.page(auditResourceSchema),
     },
     handler: ({ params, query }) =>
       this.auditService.findByUser(params.userId, query),
@@ -126,12 +126,12 @@ export class AdminAuditController {
     use: [$secure({ permissions: ["admin:audit:read"] })],
     description: "Get audit entries for a specific resource",
     schema: {
-      params: t.object({
-        resourceType: t.text(),
-        resourceId: t.text(),
+      params: z.object({
+        resourceType: z.text(),
+        resourceId: z.text(),
       }),
-      query: t.omit(auditQuerySchema, ["resourceType", "resourceId"]),
-      response: t.page(auditResourceSchema),
+      query: auditQuerySchema.omit({ resourceType: true, resourceId: true }),
+      response: z.page(auditResourceSchema),
     },
     handler: ({ params, query }) =>
       this.auditService.findByResource(
@@ -150,21 +150,21 @@ export class AdminAuditController {
     use: [$secure({ permissions: ["admin:audit:read"] })],
     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()),
+      query: z.object({
+        from: z.datetime().optional(),
+        to: z.datetime().optional(),
+        userRealm: z.text().optional(),
       }),
-      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(),
+      response: z.object({
+        total: z.integer(),
+        byType: z.record(z.text(), z.integer()),
+        bySeverity: z.object({
+          info: z.integer(),
+          warning: z.integer(),
+          critical: z.integer(),
         }),
-        successRate: t.number(),
-        recentFailures: t.array(auditResourceSchema),
+        successRate: z.number(),
+        recentFailures: z.array(auditResourceSchema),
       }),
     },
     handler: ({ query }) =>
@@ -184,7 +184,7 @@ export class AdminAuditController {
     use: [$secure({ permissions: ["admin:audit:read"] })],
     description: "List distinct action names present in the audit log",
     schema: {
-      response: t.array(t.text()),
+      response: z.array(z.text()),
     },
     handler: () => this.auditService.getDistinctActions(),
   });
@@ -198,11 +198,11 @@ export class AdminAuditController {
     use: [$secure({ permissions: ["admin:audit:read"] })],
     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()),
+      response: z.array(
+        z.object({
+          type: z.text(),
+          description: z.text().optional(),
+          actions: z.array(z.text()),
         }),
       ),
     },
@@ -218,11 +218,11 @@ export class AdminAuditController {
     use: [$secure({ permissions: ["admin:audit:read"] })],
     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()),
+      response: z.object({
+        types: z.array(z.text()),
+        actions: z.array(z.text()),
+        resourceTypes: z.array(z.text()),
+        userRealms: z.array(z.text()),
       }),
     },
     handler: async () => {

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

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

package/src/api/audits/index.ts

@@ -1,11 +1,15 @@
 import { $module } from "alepha";
 import { AdminAuditController } from "./controllers/AdminAuditController.ts";
+import { AuditJobs } from "./jobs/AuditJobs.ts";
+import { AuditParameters } from "./parameters/AuditParameters.ts";
 import { AuditService } from "./services/AuditService.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
 export * from "./controllers/AdminAuditController.ts";
 export * from "./entities/audits.ts";
+export * from "./jobs/AuditJobs.ts";
+export * from "./parameters/AuditParameters.ts";
 export * from "./primitives/$audit.ts";
 export * from "./schemas/auditQuerySchema.ts";
 export * from "./schemas/auditResourceSchema.ts";
@@ -22,10 +26,11 @@ export * from "./services/AuditService.ts";
  * - Audit event logging
  * - Filtering and searching
  * - User action tracking
+ * - Retention policy with a default + per-type TTL ({@link AuditParameters}, {@link AuditJobs})
  *
  * @module alepha.api.audits
  */
 export const AlephaApiAudits = $module({
   name: "alepha.api.audits",
-  services: [AuditService, AdminAuditController],
+  services: [AuditService, AdminAuditController, AuditParameters, AuditJobs],
 });

package/src/api/audits/jobs/AuditJobs.ts

@@ -0,0 +1,29 @@
+import { $inject } from "alepha";
+import { $scheduler } from "alepha/scheduler";
+import { AuditParameters } from "../parameters/AuditParameters.ts";
+import { AuditService } from "../services/AuditService.ts";
+
+/**
+ * Scheduled enforcement of the audit retention policy.
+ */
+export class AuditJobs {
+  protected readonly auditService = $inject(AuditService);
+  protected readonly auditParameters = $inject(AuditParameters);
+
+  /**
+   * Delete audit entries that have outlived their retention window.
+   *
+   * Runs daily and applies each audit type's dedicated `retentionDays` plus the
+   * global default (`auditOptions.retentionDays`). A default of `0` disables
+   * cleanup for types without a dedicated retention.
+   */
+  public readonly cleanExpired = $scheduler({
+    name: "api:audits:cleanExpired",
+    cron: "0 3 * * *", // Daily at 03:00
+    description: "Delete expired audit entries (retention policy)",
+    handler: async ({ now }) => {
+      const defaultRetentionDays = this.auditParameters.get("retentionDays");
+      await this.auditService.deleteExpired(now.toDate(), defaultRetentionDays);
+    },
+  });
+}

package/src/api/audits/parameters/AuditParameters.ts

@@ -0,0 +1,51 @@
+import { $atom, $state, type Static, z } from "alepha";
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Audit module configuration atom.
+ */
+export const auditOptions = $atom({
+  name: "alepha.api.audits.options",
+  schema: z.object({
+    /**
+     * Default number of days audit entries are retained before the periodic
+     * cleanup job ({@link AuditJobs}) deletes them.
+     *
+     * Applies to every audit type that does not declare its own
+     * `retentionDays`. Set to `0` to disable automatic cleanup of those types
+     * entirely (keep them forever).
+     */
+    retentionDays: z
+      .integer()
+      .min(0)
+      .describe(
+        "Default days to retain audit entries before cleanup. 0 disables cleanup.",
+      )
+      .default(90),
+  }),
+  default: {
+    retentionDays: 90,
+  },
+});
+
+export type AuditOptions = Static<typeof auditOptions.schema>;
+
+declare module "alepha" {
+  interface State {
+    [auditOptions.key]: AuditOptions;
+  }
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Typed accessor for audit module configuration ({@link auditOptions}).
+ */
+export class AuditParameters {
+  protected readonly options = $state(auditOptions);
+
+  public get<K extends keyof AuditOptions>(key: K): AuditOptions[K] {
+    return this.options[key];
+  }
+}

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

@@ -22,6 +22,22 @@ export interface AuditPrimitiveOptions {
    * List of allowed actions for this audit type.
    */
   actions: string[];
+
+  /**
+   * Number of days entries of this audit type are retained before the periodic
+   * cleanup job deletes them.
+   *
+   * Overrides the global default retention (see `auditOptions.retentionDays` in
+   * `AuditParameters`). Set to `0` to keep this type's entries forever,
+   * regardless of the global default. When omitted, the global default applies.
+   *
+   * @example
+   * ```ts
+   * // Keep security audits for two years, ignoring the global default.
+   * $audit({ type: "security", actions: ["login"], retentionDays: 730 });
+   * ```
+   */
+  retentionDays?: number;
 }
 
 /**
@@ -74,6 +90,13 @@ export class AuditPrimitive extends Primitive<AuditPrimitiveOptions> {
     return this.options.actions;
   }
 
+  /**
+   * The dedicated retention (in days) for this audit type, if set.
+   */
+  public get retentionDays(): number | undefined {
+    return this.options.retentionDays;
+  }
+
   /**
    * Log an audit event for this type.
    */
@@ -113,6 +136,7 @@ export class AuditPrimitive extends Primitive<AuditPrimitiveOptions> {
       type: this.options.type,
       description: this.options.description,
       actions: this.options.actions,
+      retentionDays: this.options.retentionDays,
     };
     this.auditService.registerType(definition);
   }

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

@@ -1,23 +1,23 @@
 import type { Static } from "alepha";
-import { t } from "alepha";
+import { z } 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 const auditQuerySchema = pageQuerySchema.extend({
+  type: z.text({ description: "Filter by audit type" }).optional(),
+  action: z.text({ description: "Filter by action" }).optional(),
+  severity: auditSeveritySchema.optional(),
+  userId: z.uuid().describe("Filter by user ID").optional(),
+  userRealm: z.text({ description: "Filter by user realm" }).optional(),
+  resourceType: z.text({ description: "Filter by resource type" }).optional(),
+  resourceId: z.text({ description: "Filter by resource ID" }).optional(),
+  success: z.boolean().describe("Filter by success status").optional(),
+  from: z.datetime().describe("Start date filter").optional(),
+  to: z.datetime().describe("End date filter").optional(),
+  search: z.text({ description: "Search in description" }).optional(),
 });
 
 export type AuditQuery = Static<typeof auditQuerySchema>;

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

@@ -1,27 +1,27 @@
 import type { Static } from "alepha";
-import { t } from "alepha";
+import { z } 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 const createAuditSchema = z.object({
+  type: z.text({ description: "Audit event type" }),
+  action: z.text({ description: "Specific action performed" }),
+  severity: auditSeveritySchema.optional(),
+  userId: z.uuid().optional(),
+  userRealm: z.text().optional(),
+  userEmail: z.email().optional(),
+  resourceType: z.text().optional(),
+  resourceId: z.text().optional(),
+  description: z.text().optional(),
+  metadata: z.json().optional(),
+  ipAddress: z.text().optional(),
+  userAgent: z.text().optional(),
+  sessionId: z.uuid().optional(),
+  requestId: z.text().optional(),
+  success: z.boolean().optional(),
+  errorMessage: z.text().optional(),
 });
 
 export type CreateAudit = Static<typeof createAuditSchema>;

package/src/api/audits/services/AuditService.ts

@@ -17,6 +17,14 @@ export interface AuditTypeDefinition {
   type: string;
   description?: string;
   actions: string[];
+
+  /**
+   * Dedicated retention (in days) for this audit type.
+   *
+   * Overrides the global default applied by the cleanup job. `0` keeps entries
+   * forever. When `undefined`, the global default retention applies.
+   */
+  retentionDays?: number;
 }
 
 /**
@@ -314,22 +322,86 @@ export class AuditService {
   }
 
   /**
-   * Delete old audit entries (for retention policy).
+   * Delete audit entries created before the given date (retention policy).
+   *
+   * @returns number of deleted entries.
    */
   public async deleteOlderThan(date: Date): Promise<number> {
     this.log.info("Deleting old audit entries", { olderThan: date });
 
-    const old = await this.repo.findMany({
-      where: { createdAt: { lt: date.toISOString() } },
+    const deleted = await this.repo.deleteMany({
+      createdAt: { lt: date.toISOString() },
     });
 
-    for (const entry of old) {
-      await this.repo.deleteById(entry.id);
+    this.log.info("Old audit entries deleted", { count: deleted.length });
+
+    return deleted.length;
+  }
+
+  /**
+   * Delete audit entries that have outlived their retention window.
+   *
+   * Each registered audit type that declares a dedicated `retentionDays` is
+   * pruned using its own window; every other type — including unregistered or
+   * legacy types — falls back to `defaultRetentionDays`. A retention of `0`
+   * (per-type or default) keeps that scope forever.
+   *
+   * `now` is injected rather than read from the clock so the policy is
+   * deterministic and testable.
+   *
+   * @param now - reference "now" used to compute cutoff dates.
+   * @param defaultRetentionDays - global default for types without an override.
+   * @returns total number of deleted entries.
+   */
+  public async deleteExpired(
+    now: Date,
+    defaultRetentionDays: number,
+  ): Promise<number> {
+    const dayMs = 24 * 60 * 60 * 1000;
+    const cutoff = (days: number): string =>
+      new Date(now.getTime() - days * dayMs).toISOString();
+
+    // Audit types carrying their own retention window.
+    const overrides = this.getRegisteredTypes().filter(
+      (type) => type.retentionDays !== undefined,
+    );
+
+    let deleted = 0;
+
+    // 1) Per-type dedicated retention.
+    for (const type of overrides) {
+      const days = type.retentionDays as number;
+      if (days <= 0) {
+        continue; // keep this type forever
+      }
+      const ids = await this.repo.deleteMany({
+        type: { eq: type.type },
+        createdAt: { lt: cutoff(days) },
+      });
+      deleted += ids.length;
+    }
+
+    // 2) Global default for every other type.
+    if (defaultRetentionDays > 0) {
+      const overriddenTypes = overrides.map((type) => type.type);
+      const ids =
+        overriddenTypes.length > 0
+          ? await this.repo.deleteMany({
+              type: { notInArray: overriddenTypes },
+              createdAt: { lt: cutoff(defaultRetentionDays) },
+            })
+          : await this.repo.deleteMany({
+              createdAt: { lt: cutoff(defaultRetentionDays) },
+            });
+      deleted += ids.length;
     }
 
-    this.log.info("Old audit entries deleted", { count: old.length });
+    this.log.info("Expired audit entries deleted", {
+      count: deleted,
+      defaultRetentionDays,
+    });
 
-    return old.length;
+    return deleted;
   }
 }
 

package/src/api/files/__tests__/FileController.spec.ts

@@ -476,13 +476,13 @@ describe("FileController", () => {
       expect(results.content.every((f) => f.creator === user1Id)).toBe(true);
     });
 
-    it("should filter by date range", { retry: 3 }, async () => {
+    it("should filter by date range", async () => {
       const { service, ctrl, dtp } = await setup();
 
-      const startTime = dtp.nowISOString();
-
-      // ensure time difference
-      await new Promise((resolve) => setTimeout(resolve, 1));
+      // createdAfter is exclusive, so sampling "now" here races the first
+      // upload: at millisecond precision both can land on the same tick and
+      // the file gets filtered out. Take a bound strictly below all uploads.
+      const startTime = dtp.now().subtract(1, "second").toISOString();
 
       await service.uploadFile(createFile("content", { name: "file1.txt" }));
       await service.uploadFile(createFile("content", { name: "file2.txt" }));

package/src/api/files/__tests__/FileJobs.spec.ts

@@ -54,6 +54,12 @@ describe("FileJobRegistry", () => {
     expect(await list()).toHaveLength(3);
 
     await dtp.travel(2, "hours");
+
+    // Time-travel fires the hourly cron, whose purge handler runs asynchronously
+    // (CronProvider dispatches handlers fire-and-forget) and holds the scheduler
+    // lock while in flight. Let that settle so the manual trigger below isn't
+    // (correctly) deduped by the still-running travel-fired run.
+    await new Promise((resolve) => setTimeout(resolve, 50));
     await jobs.purgeFiles.trigger();
 
     expect(await list()).toHaveLength(2);