alepha 0.21.2 → 0.22.0

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

@@ -0,0 +1,17 @@
+import { $audit } from "alepha/api/audits";
+
+/**
+ * Runtime parameter (config) audit events.
+ *
+ * Holds the `parameter` audit type. Using `$audit` pulls in the audits module
+ * automatically — the parameters module does not need to import it. Register
+ * as a variant and log via `parameterAudits.parameter.log("rollback", …)`.
+ */
+export class ParameterAudits {
+  public readonly parameter = $audit({
+    type: "parameter",
+    description:
+      "Runtime parameter changes (create, rollback, activate, delete).",
+    actions: ["create", "rollback", "activate", "delete"],
+  });
+}

package/src/api/parameters/controllers/AdminParameterController.ts

@@ -1,6 +1,7 @@
-import { $inject, AlephaError, t } from "alepha";
+import { $inject, Alepha, AlephaError, t } from "alepha";
 import { $secure } from "alepha/security";
 import { $action, okSchema } from "alepha/server";
+import { ParameterAudits } from "../audits/ParameterAudits.ts";
 import { activateParameterBodySchema } from "../schemas/activateParameterBodySchema.ts";
 import { createParameterVersionBodySchema } from "../schemas/createParameterVersionBodySchema.ts";
 import { parameterCurrentResponseSchema } from "../schemas/parameterCurrentResponseSchema.ts";
@@ -29,6 +30,7 @@ export class AdminParameterController {
   protected readonly url = "/parameters";
   protected readonly group = "admin:parameters";
   protected readonly provider = $inject(ParameterProvider);
+  protected readonly alepha = $inject(Alepha);
 
   /**
    * Get tree structure of all parameter names.
@@ -162,16 +164,26 @@ export class AdminParameterController {
       body: createParameterVersionBodySchema,
       response: parameterResponseSchema,
     },
-    handler: async ({ params, body }) => {
-      return this.provider.save(params.name, body.content, body.schemaHash, {
-        activationDate: body.activationDate
-          ? new Date(body.activationDate)
-          : undefined,
-        changeDescription: body.changeDescription,
-        tags: body.tags,
-        creatorId: body.creatorId,
-        creatorName: body.creatorName,
+    handler: async ({ params, body, user }) => {
+      const result = await this.provider.save(
+        params.name,
+        body.content,
+        body.schemaHash,
+        {
+          activationDate: body.activationDate
+            ? new Date(body.activationDate)
+            : undefined,
+          changeDescription: body.changeDescription,
+          tags: body.tags,
+          creatorId: user?.id,
+          creatorName: this.creatorNameOf(user),
+        },
+      );
+      await this.audit("create", params.name, {
+        version: result.version,
+        scheduled: result.status !== "current",
       });
+      return result;
     },
   });
 
@@ -190,12 +202,21 @@ export class AdminParameterController {
       body: rollbackParameterBodySchema,
       response: parameterResponseSchema,
     },
-    handler: async ({ params, body }) => {
-      return this.provider.rollback(params.name, body.targetVersion, {
-        changeDescription: body.changeDescription,
-        creatorId: body.creatorId,
-        creatorName: body.creatorName,
+    handler: async ({ params, body, user }) => {
+      const result = await this.provider.rollback(
+        params.name,
+        body.targetVersion,
+        {
+          changeDescription: body.changeDescription,
+          creatorId: user?.id,
+          creatorName: this.creatorNameOf(user),
+        },
+      );
+      await this.audit("rollback", params.name, {
+        version: result.version,
+        targetVersion: body.targetVersion,
       });
+      return result;
     },
   });
 
@@ -214,7 +235,7 @@ export class AdminParameterController {
       body: activateParameterBodySchema,
       response: parameterResponseSchema,
     },
-    handler: async ({ params, body }) => {
+    handler: async ({ params, body, user }) => {
       const allVersions = await this.provider.getHistory(params.name);
       const withStatuses = this.provider.calculateStatuses(allVersions);
       const target = withStatuses.find((v) => v.version === body.version);
@@ -236,16 +257,21 @@ export class AdminParameterController {
       }
 
       // Create new version with same content but immediate activation
-      return this.provider.save(
+      const result = await this.provider.save(
         params.name,
         target.content,
         target.schemaHash,
         {
           changeDescription: `Early activation of version ${body.version}`,
-          creatorId: body.creatorId,
-          creatorName: body.creatorName,
+          creatorId: user?.id,
+          creatorName: this.creatorNameOf(user),
         },
       );
+      await this.audit("activate", params.name, {
+        version: result.version,
+        activatedFrom: body.version,
+      });
+      return result;
     },
   });
 
@@ -264,6 +290,7 @@ export class AdminParameterController {
     },
     handler: async ({ params }) => {
       await this.provider.delete(params.name);
+      await this.audit("delete", params.name);
       return { ok: true };
     },
   });
@@ -290,7 +317,56 @@ export class AdminParameterController {
     },
     handler: async ({ body }) => {
       const deleted = await this.provider.deleteMany(body.names);
+      for (const name of deleted) {
+        await this.audit("delete", name);
+      }
       return { deleted };
     },
   });
+
+  /**
+   * Derive a human-readable creator name from the authenticated session token.
+   *
+   * The name is snapshotted onto the version at write time rather than joined
+   * from the users table on read: this keeps the parameters module free of any
+   * dependency on the users module (no import, no circular-import risk). The
+   * trade-off is that the stored name does not follow later user renames.
+   *
+   * Precedence: `username` → `email`. The token's `name` is intentionally
+   * skipped: the security layer fills it with a placeholder ("Anonymous User")
+   * when the issuer supplies no name, which would otherwise be snapshotted.
+   */
+  protected creatorNameOf(user?: {
+    username?: string;
+    email?: string;
+  }): string | undefined {
+    return user?.username ?? user?.email;
+  }
+
+  /**
+   * Record a parameter mutation via the `ParameterAudits` holder — best-effort.
+   *
+   * `ParameterAudits` is resolved lazily from the container; when it is not
+   * registered, auditing is silently skipped. Actor (userId / email / realm),
+   * IP, and request id are auto-filled by `AuditService` from the request
+   * context. Failures never break the underlying operation.
+   */
+  protected async audit(
+    action: "create" | "rollback" | "activate" | "delete",
+    name: string,
+    metadata?: Record<string, unknown>,
+  ): Promise<void> {
+    if (!this.alepha.has(ParameterAudits)) {
+      return;
+    }
+    try {
+      await this.alepha.inject(ParameterAudits).parameter.log(action, {
+        resourceType: "parameter",
+        resourceId: name,
+        metadata,
+      });
+    } catch {
+      // Auditing is best-effort; never fail the operation because of it.
+    }
+  }
 }

package/src/api/parameters/index.ts

@@ -1,4 +1,5 @@
 import { $module } from "alepha";
+import { ParameterAudits } from "./audits/ParameterAudits.ts";
 import { AdminParameterController } from "./controllers/AdminParameterController.ts";
 import { $parameter } from "./primitives/$parameter.ts";
 import { ParameterProvider } from "./services/ParameterProvider.ts";
@@ -6,6 +7,7 @@ import { ParameterProvider } from "./services/ParameterProvider.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 // Controller exports
+export * from "./audits/ParameterAudits.ts";
 export * from "./controllers/AdminParameterController.ts";
 // Entity exports
 export * from "./entities/parameters.ts";
@@ -45,4 +47,5 @@ export const AlephaApiParameters = $module({
   name: "alepha.api.parameters",
   primitives: [$parameter],
   services: [ParameterProvider, AdminParameterController],
+  variants: [ParameterAudits],
 });

package/src/api/parameters/schemas/activateParameterBodySchema.ts

@@ -3,12 +3,12 @@ import { parameters } from "../entities/parameters.ts";
 
 /**
  * Activate parameter body schema.
- * Uses t.pick for version and creator fields.
+ *
+ * Creator fields are omitted; the controller captures the authenticated user
+ * server-side.
  */
 export const activateParameterBodySchema = t.pick(parameters.schema, [
   "version",
-  "creatorId",
-  "creatorName",
 ]);
 
 export type ActivateParameterBody = Static<typeof activateParameterBodySchema>;

package/src/api/parameters/schemas/createParameterVersionBodySchema.ts

@@ -4,6 +4,9 @@ import { parameters } from "../entities/parameters.ts";
 /**
  * Create parameter version body schema.
  * Uses t.pick to derive from entity, with required fields made non-optional.
+ *
+ * Creator fields are intentionally omitted: the controller captures the
+ * authenticated user server-side, so they cannot be spoofed by the client.
  */
 export const createParameterVersionBodySchema = t.extend(
   t.pick(parameters.schema, [
@@ -11,8 +14,6 @@ export const createParameterVersionBodySchema = t.extend(
     "schemaHash",
     "changeDescription",
     "tags",
-    "creatorId",
-    "creatorName",
   ]),
   {
     activationDate: t.optional(

package/src/api/parameters/schemas/parameterCreatorSummarySchema.ts

@@ -0,0 +1,25 @@
+import { type Static, t } from "alepha";
+
+/**
+ * Slim view of a parameter version's creator, embedded by the admin history
+ * endpoint via a best-effort left join (`parameters.creatorId` → `users.id`)
+ * so the UI can render a human-readable identifier (and link) instead of a
+ * bare UUID.
+ *
+ * Optional end-to-end: the join only runs when the `users` entity is
+ * registered in the running app (see `ParameterProvider.resolveCreatorJoin`),
+ * and a version whose creator was deleted — or who lives in a non-default
+ * realm — comes back with `creator` undefined. Callers fall back to the raw
+ * `creatorId`.
+ */
+export const parameterCreatorSummarySchema = t.object({
+  id: t.uuid(),
+  email: t.optional(t.string({ format: "email" })),
+  username: t.optional(t.shortText({ minLength: 3, maxLength: 30 })),
+  firstName: t.optional(t.string()),
+  lastName: t.optional(t.string()),
+});
+
+export type ParameterCreatorSummary = Static<
+  typeof parameterCreatorSummarySchema
+>;

package/src/api/parameters/schemas/parameterResponseSchema.ts

@@ -1,14 +1,19 @@
 import { type Static, t } from "alepha";
 import { parameters } from "../entities/parameters.ts";
+import { parameterCreatorSummarySchema } from "./parameterCreatorSummarySchema.ts";
 import { parameterStatusSchema } from "./parameterStatusSchema.ts";
 
 /**
  * Parameter response schema for API responses.
  * Extends the entity schema with a calculated status field.
  * Status is derived from activationDate at query time, not stored.
+ *
+ * `creator` is embedded on read via a best-effort left join on `creatorId`
+ * (see `parameterCreatorSummarySchema`); it is not a stored column.
  */
 export const parameterResponseSchema = t.extend(parameters.schema, {
   status: parameterStatusSchema,
+  creator: t.optional(parameterCreatorSummarySchema),
 });
 
 export type ParameterResponse = Static<typeof parameterResponseSchema>;

package/src/api/parameters/schemas/rollbackParameterBodySchema.ts

@@ -3,10 +3,12 @@ import { parameters } from "../entities/parameters.ts";
 
 /**
  * Rollback parameter body schema.
- * Uses t.pick for creator fields, adds targetVersion.
+ *
+ * Creator fields are omitted; the controller captures the authenticated user
+ * server-side.
  */
 export const rollbackParameterBodySchema = t.extend(
-  t.pick(parameters.schema, ["changeDescription", "creatorId", "creatorName"]),
+  t.pick(parameters.schema, ["changeDescription"]),
   {
     targetVersion: t.integer({
       description: "Version number to rollback to",

package/src/api/parameters/services/ParameterProvider.ts

@@ -12,7 +12,7 @@ import { CryptoProvider } from "alepha/crypto";
 import { DateTimeProvider } from "alepha/datetime";
 import { LockProvider } from "alepha/lock";
 import { $logger } from "alepha/logger";
-import { $repository } from "alepha/orm";
+import { $repository, RepositoryProvider } from "alepha/orm";
 import { $topic } from "alepha/topic";
 import { type Parameter, parameters } from "../entities/parameters.ts";
 import type { ParameterPrimitive } from "../primitives/$parameter.ts";
@@ -50,6 +50,7 @@ export class ParameterProvider {
   protected readonly crypto = $inject(CryptoProvider);
   protected readonly lockProvider = $inject(LockProvider);
   protected readonly schemaValidator = $inject(SchemaValidator);
+  protected readonly repositoryProvider = $inject(RepositoryProvider);
   protected readonly repo = $repository(parameters);
 
   /**
@@ -326,10 +327,10 @@ export class ParameterProvider {
    * - Other future versions are "future"
    * - Other past versions are "expired"
    */
-  public calculateStatuses(
-    versions: Parameter[],
+  public calculateStatuses<T extends Parameter>(
+    versions: T[],
     now?: Date,
-  ): ParameterWithStatus[] {
+  ): Array<T & { status: ParameterStatus }> {
     const effectiveNow = now ?? this.dateTimeProvider.now().toDate();
 
     // Sort by activationDate ascending, then version ascending for ties
@@ -458,17 +459,49 @@ export class ParameterProvider {
   }
 
   /**
-   * Get all versions of a parameter.
+   * Best-effort left join embedding the creating user on each version, so the
+   * admin UI can render a human-readable identifier (live, not snapshotted)
+   * instead of the bare `creatorId`. Joins `parameters.creatorId` → `users.id`.
+   *
+   * The `users` entity is resolved from the repository registry at runtime
+   * rather than imported: that keeps the parameters module free of any
+   * dependency on the users module (no import, no circular-import risk). When
+   * the users module is not registered the join is skipped and `creator` comes
+   * back undefined.
+   */
+  protected resolveCreatorJoin() {
+    const usersEntity = this.repositoryProvider
+      .getRepositories()
+      .find((repo) => repo.entity.name === "users")?.entity;
+    if (!usersEntity) {
+      return undefined;
+    }
+    return {
+      creator: {
+        join: usersEntity,
+        on: ["creatorId", usersEntity.cols.id] as [
+          "creatorId",
+          { name: string },
+        ],
+      },
+    };
+  }
+
+  /**
+   * Get all versions of a parameter, each with the creating user embedded
+   * (best-effort, see {@link resolveCreatorJoin}).
    */
   public async getHistory(
     name: string,
     options?: { limit?: number; offset?: number },
   ): Promise<Parameter[]> {
+    const withCreator = this.resolveCreatorJoin();
     return this.repo.findMany({
       where: { name },
       orderBy: { column: "version", direction: "desc" },
       limit: options?.limit,
       offset: options?.offset,
+      ...(withCreator ? { with: withCreator } : {}),
     });
   }
 
@@ -563,6 +596,12 @@ export class ParameterProvider {
 
   /**
    * Get parameter info including current value with default fallback.
+   *
+   * When no version exists in the DB yet but a primitive is registered, this
+   * lazily materializes v1 from the primitive's `default`. After this call,
+   * the parameter has a concrete current row admins can edit / roll back /
+   * compare against, instead of running on phantom defaults-from-code state.
+   * Idempotent: subsequent calls return the same row without re-creating.
    */
   public async getCurrentWithDefault(name: string): Promise<{
     current: ParameterWithStatus | null;
@@ -571,10 +610,34 @@ export class ParameterProvider {
     currentValue: unknown | null;
     schema: TObject | null;
   }> {
-    const { current, next } = await this.loadCurrentAndNext(name);
+    let { current, next } = await this.loadCurrentAndNext(name);
 
     // Get default and current from registered primitive
     const param = this.primitives.get(name);
+
+    // No version in DB yet but the primitive is registered: seed v1 from
+    // the compiled defaults. Always-on parameters are then a tangible row
+    // the admin UI can edit (and that history can grow from). Unregistered
+    // names (orphans from a removed `$parameter`) are not seeded.
+    if (!current && param) {
+      try {
+        current = await this.save(
+          name,
+          param.options.default as Static<TObject>,
+          this.schemaHashes.get(name) ?? "",
+          { changeDescription: "Auto-seeded from compiled defaults" },
+        );
+      } catch (err) {
+        // A concurrent caller may have raced us to insert v1; fall back to
+        // re-reading instead of bubbling up a unique-constraint error.
+        this.log.warn("Auto-seed of parameter failed, retrying read", {
+          name,
+          error: (err as Error).message,
+        });
+        ({ current, next } = await this.loadCurrentAndNext(name));
+      }
+    }
+
     const defaultValue = param?.options.default ?? null;
     const currentValue = this.getCachedCurrentContent(name) ?? null;
     const schema = param?.schema ?? null;

package/src/api/subscriptions/jobs/SubscriptionJobs.ts

@@ -301,7 +301,7 @@ export class SubscriptionJobs {
    * Runs daily at 2 AM.
    */
   public readonly gracePeriodSweep = $job({
-    cron: "0 2 * * *",
+    cron: "0 3 * * *",
     lock: true,
     handler: async ({ now }) => {
       const settings = await this.config.getSettings();

package/src/api/users/__tests__/AdminSessionController.spec.ts

@@ -75,6 +75,43 @@ describe("alepha/api/users - AdminSessionController", () => {
     expect(result.userAgent?.browser).toBe("Chrome");
   });
 
+  it("should embed the slim user summary on findSessions + getSession", async ({
+    expect,
+  }) => {
+    const { sessionService, userService, controller, dateTimeProvider } =
+      await setup();
+
+    const user = await userService.users().create({
+      username: "withuser",
+      email: "withuser@example.com",
+      firstName: "With",
+      lastName: "User",
+      roles: ["user"],
+    });
+
+    const session = await sessionService.sessions().create({
+      userId: user.id,
+      refreshToken: crypto.randomUUID(),
+      expiresAt: dateTimeProvider.now().add(7, "days").toISOString(),
+    });
+
+    const listed = await controller.findSessions(
+      { query: { userId: user.id } },
+      { user: adminUser },
+    );
+    const found = listed.content.find((s) => s.id === session.id);
+    expect(found?.user?.id).toBe(user.id);
+    expect(found?.user?.email).toBe("withuser@example.com");
+    expect(found?.user?.username).toBe("withuser");
+    expect(found?.user?.firstName).toBe("With");
+
+    const fetched = await controller.getSession(
+      { params: { id: session.id } },
+      { user: adminUser },
+    );
+    expect(fetched.user?.email).toBe("withuser@example.com");
+  });
+
   it("should throw error for non-existent session", async ({ expect }) => {
     const { controller } = await setup();
 

package/src/api/users/audits/SessionAudits.ts

@@ -0,0 +1,33 @@
+import { $audit } from "alepha/api/audits";
+
+/**
+ * Authentication & session-security audit events.
+ *
+ * Holds two audit types:
+ * - `auth` — login / logout / token refresh / MFA.
+ * - `security` — rate limiting, session invalidation, and related guards.
+ *
+ * Failed events are logged with `success: false`; severity (`warning`) is
+ * derived centrally in `AuditService.create`. Register as a module variant
+ * and log via the exposed primitives:
+ * `sessionAudits(realm)?.auth.log("login", { success: false, … })`.
+ */
+export class SessionAudits {
+  public readonly auth = $audit({
+    type: "auth",
+    description: "Authentication events (login, logout, token refresh, MFA).",
+    actions: ["login", "logout", "token_refresh", "mfa_setup", "mfa_verify"],
+  });
+
+  public readonly security = $audit({
+    type: "security",
+    description:
+      "Security events (rate limiting, session invalidation, blocked access).",
+    actions: [
+      "rate_limited",
+      "sessions_invalidated",
+      "permission_denied",
+      "blocked",
+    ],
+  });
+}

package/src/api/users/audits/UserAudits.ts

@@ -1,49 +1,25 @@
-import { $inject } from "alepha";
-import { AuditService, type CreateAudit } from "alepha/api/audits";
-
-type AuditContext = Omit<CreateAudit, "type" | "action">;
+import { $audit } from "alepha/api/audits";
 
 /**
- * User-specific audit wrapper service.
- *
- * This service wraps the core AuditService to provide user-related audit logging.
+ * User-management audit events.
  *
- * Declared as a module variant — not auto-injected. It is instantiated
- * lazily the first time something calls `alepha.inject(UserAudits)`.
+ * Holds the `user` audit type. Mirrors the `$notification`/`$job` holder
+ * pattern (see {@link UserNotifications}) — register as a module variant and
+ * log via the exposed primitive: `userAudits(realm)?.user.log("create", …)`.
  */
 export class UserAudits {
-  protected readonly auditService = $inject(AuditService);
-
-  /**
-   * Record a user-related audit event.
-   */
-  public recordUser(
-    action:
-      | "create"
-      | "update"
-      | "delete"
-      | "role_change"
-      | "enable"
-      | "disable",
-    context: AuditContext,
-  ) {
-    return this.auditService.recordUser(action, context);
-  }
-
-  /**
-   * Record an authentication-related audit event.
-   */
-  public recordAuth(
-    action: "login" | "logout" | "login_failed" | "token_refresh",
-    context: AuditContext,
-  ) {
-    return this.auditService.recordAuth(action, context);
-  }
-
-  /**
-   * Record a generic audit event.
-   */
-  public record(category: string, action: string, context: AuditContext) {
-    return this.auditService.record(category, action, context);
-  }
+  public readonly user = $audit({
+    type: "user",
+    description:
+      "User management events (create, update, delete, role/password changes).",
+    actions: [
+      "create",
+      "update",
+      "delete",
+      "role_change",
+      "password_change",
+      "enable",
+      "disable",
+    ],
+  });
 }