alepha 0.15.3 → 0.15.5

package/src/api/users/services/SessionService.ts

@@ -1,6 +1,5 @@
 import { randomInt } from "node:crypto";
 import { $inject, Alepha } from "alepha";
-import { AuditService } from "alepha/api/audits";
 import type { FileController } from "alepha/api/files";
 import { DateTimeProvider } from "alepha/datetime";
 import { $logger } from "alepha/logger";
@@ -15,6 +14,7 @@ import { $client } from "alepha/server/links";
 import { FileSystemProvider } from "alepha/system";
 import type { UserEntity } from "../entities/users.ts";
 import { RealmProvider } from "../providers/RealmProvider.ts";
+import { UserAudits } from "./UserAudits.ts";
 
 export class SessionService {
   protected readonly alepha = $inject(Alepha);
@@ -24,7 +24,14 @@ export class SessionService {
   protected readonly log = $logger();
   protected readonly realmProvider = $inject(RealmProvider);
   protected readonly fileController = $client<FileController>();
-  protected readonly auditService = $inject(AuditService);
+
+  protected userAudits(realmName?: string) {
+    const realm = this.realmProvider.getRealm(realmName);
+    if (realm.features.audits) {
+      return this.alepha.inject(UserAudits);
+    }
+    return undefined;
+  }
 
   public users(userRealmName?: string) {
     return this.realmProvider.userRepository(userRealmName);
@@ -38,6 +45,55 @@ export class SessionService {
     return this.realmProvider.identityRepository(userRealmName);
   }
 
+  /**
+   * Check if user should be auto-promoted to admin based on adminEmails/adminUsernames settings.
+   * If user matches and doesn't have admin role, promote them.
+   */
+  protected async ensureAdminRole(
+    user: {
+      id: string;
+      email?: string | null;
+      username?: string | null;
+      roles: string[];
+    },
+    userRealmName?: string,
+  ): Promise<boolean> {
+    if (user.roles.includes("admin")) return false;
+
+    const { settings, name } = this.realmProvider.getRealm(userRealmName);
+    const adminEmails = settings.adminEmails ?? [];
+    const adminUsernames = settings.adminUsernames ?? [];
+
+    const isAdminByEmail = user.email && adminEmails.includes(user.email);
+    const isAdminByUsername =
+      user.username && adminUsernames.includes(user.username);
+
+    if (!isAdminByEmail && !isAdminByUsername) return false;
+
+    // Promote to admin
+    user.roles = [...user.roles.filter((r) => r !== "admin"), "admin"];
+    await this.users(userRealmName).updateById(user.id, { roles: user.roles });
+
+    const reason = isAdminByEmail ? "adminEmails" : "adminUsernames";
+    this.log.info(`User auto-promoted to admin via ${reason} setting`, {
+      userId: user.id,
+      email: user.email,
+      username: user.username,
+      realm: name,
+    });
+
+    await this.userAudits(userRealmName)?.recordUser("role_change", {
+      userId: user.id,
+      userEmail: user.email ?? undefined,
+      userRealm: name,
+      resourceId: user.id,
+      description: `User auto-promoted to admin via ${reason} setting`,
+      metadata: { addedRole: "admin", reason },
+    });
+
+    return true;
+  }
+
   /**
    * Random delay to prevent timing attacks (50-200ms)
    * Uses cryptographically secure random number generation
@@ -80,7 +136,7 @@ export class SessionService {
               realm: name,
             });
 
-            await this.auditService.recordAuth("login_failed", {
+            await this.userAudits(userRealmName)?.recordAuth("login_failed", {
               userRealm: name,
               description: "Username does not match required format",
               metadata: { provider, username },
@@ -101,7 +157,7 @@ export class SessionService {
           realm: name,
         });
 
-        await this.auditService.recordAuth("login_failed", {
+        await this.userAudits(userRealmName)?.recordAuth("login_failed", {
           userRealm: name,
           description: "Invalid login identifier format",
           metadata: { provider, username },
@@ -118,7 +174,7 @@ export class SessionService {
           realm: name,
         });
 
-        await this.auditService.recordAuth("login_failed", {
+        await this.userAudits(userRealmName)?.recordAuth("login_failed", {
           userRealm: name,
           description: "User not found",
           metadata: { provider, username },
@@ -157,7 +213,7 @@ export class SessionService {
           realm: name,
         });
 
-        await this.auditService.recordAuth("login_failed", {
+        await this.userAudits(userRealmName)?.recordAuth("login_failed", {
           userRealm: name,
           resourceId: user.id,
           description: "Invalid password",
@@ -167,7 +223,7 @@ export class SessionService {
         throw new InvalidCredentialsError();
       }
 
-      await this.auditService.recordAuth("login", {
+      await this.userAudits(userRealmName)?.recordAuth("login", {
         userId: user.id,
         userEmail: user.email ?? undefined,
         userRealm: name,
@@ -176,6 +232,9 @@ export class SessionService {
         metadata: { provider, username },
       });
 
+      // Auto-promote to admin if configured
+      await this.ensureAdminRole(user, userRealmName);
+
       return user;
     } catch (error) {
       if (error instanceof InvalidCredentialsError) {
@@ -251,6 +310,9 @@ export class SessionService {
       },
     });
 
+    // Auto-promote to admin if configured (handles "I promote you admin" case)
+    await this.ensureAdminRole(user, userRealmName);
+
     this.log.debug("Session refreshed", {
       sessionId: session.id,
       userId: session.userId,
@@ -281,7 +343,7 @@ export class SessionService {
     if (session) {
       const { name } = this.realmProvider.getRealm(userRealmName);
 
-      await this.auditService.recordAuth("logout", {
+      await this.userAudits(userRealmName)?.recordAuth("logout", {
         userId: session.userId,
         userRealm: name,
         sessionId: session.id,
@@ -324,7 +386,7 @@ export class SessionService {
 
       const user = await users.findById(identity.userId);
 
-      await this.auditService.recordAuth("login", {
+      await this.userAudits(userRealmName)?.recordAuth("login", {
         userId: user.id,
         userEmail: user.email ?? undefined,
         userRealm: realm.name,
@@ -333,6 +395,9 @@ export class SessionService {
         metadata: { provider, providerUserId: profile.sub },
       });
 
+      // Auto-promote to admin if configured
+      await this.ensureAdminRole(user, userRealmName);
+
       return user;
     }
 
@@ -368,7 +433,7 @@ export class SessionService {
         userId: existing.id,
       });
 
-      await this.auditService.recordAuth("login", {
+      await this.userAudits(userRealmName)?.recordAuth("login", {
         userId: existing.id,
         userEmail: existing.email ?? undefined,
         userRealm: realm.name,
@@ -377,6 +442,9 @@ export class SessionService {
         metadata: { provider, providerUserId: profile.sub, linked: true },
       });
 
+      // Auto-promote to admin if configured
+      await this.ensureAdminRole(existing, userRealmName);
+
       return existing;
     }
 
@@ -432,7 +500,7 @@ export class SessionService {
     });
 
     // Audit: user created via OAuth
-    await this.auditService.recordUser("create", {
+    await this.userAudits(userRealmName)?.recordUser("create", {
       userId: user.id,
       userEmail: user.email ?? undefined,
       userRealm: realm.name,
@@ -447,7 +515,7 @@ export class SessionService {
     });
 
     // Audit: login event
-    await this.auditService.recordAuth("login", {
+    await this.userAudits(userRealmName)?.recordAuth("login", {
       userId: user.id,
       userEmail: user.email ?? undefined,
       userRealm: realm.name,
@@ -456,6 +524,9 @@ export class SessionService {
       metadata: { provider, providerUserId: profile.sub, firstLogin: true },
     });
 
+    // Auto-promote to admin if configured
+    await this.ensureAdminRole(user, userRealmName);
+
     return user;
   }
 }

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

@@ -0,0 +1,47 @@
+import { $inject } from "alepha";
+import { AuditService, type CreateAudit } from "alepha/api/audits";
+
+type AuditContext = Omit<CreateAudit, "type" | "action">;
+
+/**
+ * User-specific audit wrapper service.
+ *
+ * This service wraps the core AuditService to provide user-related audit logging.
+ * It is lazy-loaded when the `audits` feature is enabled in the realm.
+ */
+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);
+  }
+}

package/src/api/users/services/UserFiles.ts

@@ -0,0 +1,19 @@
+import { $bucket } from "alepha/bucket";
+
+/**
+ * User-specific file storage wrapper service.
+ *
+ * This service provides file storage for user-related files such as:
+ * - User avatars/profile pictures
+ *
+ * It is lazy-loaded when the `files` feature is enabled in the realm.
+ */
+export class UserFiles {
+  /**
+   * Bucket for user avatar storage.
+   */
+  public readonly avatars = $bucket({
+    maxSize: 5 * 1024 * 1024, // 5 MB
+    mimeTypes: ["image/jpeg", "image/png", "image/gif", "image/webp"],
+  });
+}

package/src/api/users/services/UserJobs.spec.ts

@@ -0,0 +1,107 @@
+import { Alepha } from "alepha";
+import { AlephaApiJobs } from "alepha/api/jobs";
+import { $repository, AlephaOrm } from "alepha/orm";
+import { describe, test } from "vitest";
+import { sessions } from "../entities/sessions.ts";
+import { users } from "../entities/users.ts";
+import { UserJobs } from "./UserJobs.ts";
+
+describe("UserJobs", () => {
+  describe("purgeExpiredSessions", () => {
+    test("should delete expired sessions", async ({ expect }) => {
+      const alepha = Alepha.create().with(AlephaOrm).with(AlephaApiJobs);
+
+      class TestRepositories {
+        userRepository = $repository(users);
+        sessionRepository = $repository(sessions);
+      }
+
+      const userJobs = alepha.inject(UserJobs);
+      const repos = alepha.inject(TestRepositories);
+      await alepha.start();
+
+      // Create a test user
+      const user = await repos.userRepository.create({
+        email: "test@example.com",
+      });
+
+      // Create expired sessions (expiresAt in the past)
+      const pastDate = new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString(); // 1 day ago
+      await repos.sessionRepository.create({
+        userId: user.id,
+        refreshToken: crypto.randomUUID(),
+        expiresAt: pastDate,
+      });
+      await repos.sessionRepository.create({
+        userId: user.id,
+        refreshToken: crypto.randomUUID(),
+        expiresAt: pastDate,
+      });
+
+      // Create a valid session (expiresAt in the future)
+      const futureDate = new Date(
+        Date.now() + 24 * 60 * 60 * 1000,
+      ).toISOString(); // 1 day from now
+      await repos.sessionRepository.create({
+        userId: user.id,
+        refreshToken: crypto.randomUUID(),
+        expiresAt: futureDate,
+      });
+
+      // Verify we have 3 sessions
+      const sessionsBefore = await repos.sessionRepository.findMany();
+      expect(sessionsBefore).toHaveLength(3);
+
+      // Trigger the job
+      await userJobs.purgeExpiredSessions.trigger();
+
+      // Verify only the valid session remains
+      const sessionsAfter = await repos.sessionRepository.findMany();
+      expect(sessionsAfter).toHaveLength(1);
+      expect(new Date(sessionsAfter[0].expiresAt).getTime()).toBeGreaterThan(
+        Date.now(),
+      );
+    });
+
+    test("should handle case when no expired sessions exist", async ({
+      expect,
+    }) => {
+      const alepha = Alepha.create().with(AlephaOrm).with(AlephaApiJobs);
+
+      class TestRepositories {
+        userRepository = $repository(users);
+        sessionRepository = $repository(sessions);
+      }
+
+      const userJobs = alepha.inject(UserJobs);
+      const repos = alepha.inject(TestRepositories);
+      await alepha.start();
+
+      // Create a test user
+      const user = await repos.userRepository.create({
+        email: "test2@example.com",
+      });
+
+      // Create only valid sessions
+      const futureDate = new Date(
+        Date.now() + 24 * 60 * 60 * 1000,
+      ).toISOString();
+      await repos.sessionRepository.create({
+        userId: user.id,
+        refreshToken: crypto.randomUUID(),
+        expiresAt: futureDate,
+      });
+
+      // Verify we have 1 session
+      const sessionsBefore = await repos.sessionRepository.findMany();
+      expect(sessionsBefore).toHaveLength(1);
+
+      // Trigger the job - should not throw
+      await userJobs.purgeExpiredSessions.trigger();
+
+      // Session should still exist
+      const sessionsAfter = await repos.sessionRepository.findMany();
+      expect(sessionsAfter).toHaveLength(1);
+    });
+  });
+});

package/src/api/users/services/UserJobs.ts

@@ -0,0 +1,62 @@
+import { $inject } from "alepha";
+import { $job } from "alepha/api/jobs";
+import { DateTimeProvider } from "alepha/datetime";
+import { $logger } from "alepha/logger";
+import { $repository } from "alepha/orm";
+import { sessions } from "../entities/sessions.ts";
+
+/**
+ * User-specific jobs wrapper service.
+ *
+ * This service handles user-related scheduled jobs such as:
+ * - Session purge (cleaning up expired sessions)
+ * - Verification code cleanup
+ * - Inactive user notifications
+ *
+ * It is lazy-loaded when the `jobs` feature is enabled in the realm.
+ */
+export class UserJobs {
+  protected readonly log = $logger();
+  protected readonly dateTimeProvider = $inject(DateTimeProvider);
+  protected readonly sessionRepository = $repository(sessions);
+
+  /**
+   * Purge expired sessions from the database.
+   *
+   * This job runs daily at 3:00 AM and removes all sessions
+   * where the `expiresAt` timestamp has passed.
+   */
+  public readonly purgeExpiredSessions = $job({
+    name: "users.purgeExpiredSessions",
+    description: "Remove expired user sessions from the database",
+    cron: "0 3 * * *", // Daily at 3:00 AM
+    handler: async () => {
+      const now = this.dateTimeProvider.nowISOString();
+
+      this.log.info("Starting expired sessions purge", { cutoffTime: now });
+
+      const expiredSessions = await this.sessionRepository.findMany({
+        where: {
+          expiresAt: { lt: now },
+        },
+      });
+
+      if (expiredSessions.length === 0) {
+        this.log.info("No expired sessions found");
+        return;
+      }
+
+      this.log.info("Found expired sessions", {
+        count: expiredSessions.length,
+      });
+
+      const deletedIds = await this.sessionRepository.deleteMany({
+        expiresAt: { lt: now },
+      });
+
+      this.log.info("Expired sessions purged successfully", {
+        deletedCount: deletedIds.length,
+      });
+    },
+  });
+}

package/src/api/users/services/UserParameters.ts

@@ -0,0 +1,23 @@
+import { $config } from "alepha/api/parameters";
+import { realmAuthSettingsAtom } from "../atoms/realmAuthSettingsAtom.ts";
+
+/**
+ * User-specific configuration service.
+ *
+ * This service wraps the core ConfigStore to provide realm settings management.
+ * It is lazy-loaded when the `parameters` feature is enabled in the realm.
+ */
+export class UserParameters {
+  /**
+   * Realm authentication settings configuration.
+   *
+   * Controls user registration, login methods, verification requirements,
+   * and password policies for the realm.
+   */
+  public readonly realmSettings = $config({
+    name: "alepha.api.users.realmSettings",
+    description: "Realm authentication and registration settings",
+    schema: realmAuthSettingsAtom.schema,
+    default: realmAuthSettingsAtom.options.default,
+  });
+}

package/src/api/users/services/UserService.ts

@@ -1,23 +1,38 @@
-import { $inject } from "alepha";
-import { AuditService } from "alepha/api/audits";
+import { $inject, Alepha } from "alepha";
 import type { VerificationController } from "alepha/api/verifications";
 import { $logger } from "alepha/logger";
 import { type Page, parseQueryString } from "alepha/orm";
 import { BadRequestError } from "alepha/server";
 import { $client } from "alepha/server/links";
 import type { UserEntity } from "../entities/users.ts";
-import { UserNotifications } from "../notifications/UserNotifications.ts";
 import { RealmProvider } from "../providers/RealmProvider.ts";
 import type { CreateUser } from "../schemas/createUserSchema.ts";
 import type { UpdateUser } from "../schemas/updateUserSchema.ts";
 import type { UserQuery } from "../schemas/userQuerySchema.ts";
+import { UserAudits } from "./UserAudits.ts";
+import { UserNotifications } from "./UserNotifications.ts";
 
 export class UserService {
+  protected readonly alepha = $inject(Alepha);
   protected readonly log = $logger();
   protected readonly verificationController = $client<VerificationController>();
-  protected readonly userNotifications = $inject(UserNotifications);
   protected readonly realmProvider = $inject(RealmProvider);
-  protected readonly auditService = $inject(AuditService);
+
+  protected userAudits(realmName?: string) {
+    const realm = this.realmProvider.getRealm(realmName);
+    if (realm.features.audits) {
+      return this.alepha.inject(UserAudits);
+    }
+    return undefined;
+  }
+
+  protected userNotifications(realmName?: string) {
+    const realm = this.realmProvider.getRealm(realmName);
+    if (realm.features.notifications) {
+      return this.alepha.inject(UserNotifications);
+    }
+    return undefined;
+  }
 
   public users(userRealmName?: string) {
     return this.realmProvider.userRepository(userRealmName);
@@ -79,21 +94,23 @@ export class UserService {
           ? `${verifyUrl}${url.search}`
           : url.pathname + url.search;
 
-        await this.userNotifications.emailVerificationLink.push({
-          contact: email,
-          variables: {
-            email,
-            verifyUrl: fullVerifyUrl,
-            expiresInMinutes: Math.floor(verification.codeExpiration / 60),
+        await this.userNotifications(userRealmName)?.emailVerificationLink.push(
+          {
+            contact: email,
+            variables: {
+              email,
+              verifyUrl: fullVerifyUrl,
+              expiresInMinutes: Math.floor(verification.codeExpiration / 60),
+            },
           },
-        });
+        );
 
         this.log.debug("Email verification link sent", {
           email,
           userId: user.id,
         });
       } else {
-        await this.userNotifications.emailVerification.push({
+        await this.userNotifications(userRealmName)?.emailVerification.push({
           contact: email,
           variables: {
             email,
@@ -158,7 +175,7 @@ export class UserService {
 
     const realm = this.realmProvider.getRealm(userRealmName);
 
-    await this.auditService.recordUser("update", {
+    await this.userAudits(userRealmName)?.recordUser("update", {
       userId: user.id,
       userEmail: email,
       userRealm: realm.name,
@@ -314,7 +331,7 @@ export class UserService {
       email: user.email,
     });
 
-    await this.auditService.recordUser("create", {
+    await this.userAudits(userRealmName)?.recordUser("create", {
       userRealm: realm.name,
       resourceId: user.id,
       description: "User created",
@@ -357,7 +374,7 @@ export class UserService {
       data.roles !== undefined &&
       JSON.stringify(before.roles) !== JSON.stringify(data.roles);
 
-    await this.auditService.recordUser(
+    await this.userAudits(userRealmName)?.recordUser(
       isRoleChange ? "role_change" : "update",
       {
         userRealm: realm.name,
@@ -384,7 +401,7 @@ export class UserService {
 
     const realm = this.realmProvider.getRealm(userRealmName);
 
-    await this.auditService.recordUser("delete", {
+    await this.userAudits(userRealmName)?.recordUser("delete", {
       userRealm: realm.name,
       resourceId: id,
       severity: "warning",

package/src/api/verifications/index.ts

@@ -18,9 +18,9 @@ export * from "./services/VerificationService.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * | type | quality | stability |
- * |------|---------|-----------|
- * | backend | standard | stable |
+ * | Stability | Since | Runtime |
+ * |-----------|-------|---------|
+ * | 3 - stable | 0.13.0 | node, bun, workerd|
  *
  * Email and phone verification workflows.
  *

package/src/batch/index.ts

@@ -10,9 +10,9 @@ export * from "./providers/BatchProvider.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * | type | quality | stability |
- * |------|---------|-----------|
- * | backend | standard | stable |
+ * | Stability | Since | Runtime |
+ * |-----------|-------|---------|
+ * | 3 - stable | 0.8.0 | node, bun|
  *
  * Batch accumulation and processing.
  *

package/src/bucket/index.ts

@@ -43,9 +43,9 @@ declare module "alepha" {
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * | type | quality | stability |
- * |------|---------|-----------|
- * | backend | rare | stable |
+ * | Stability | Since | Runtime |
+ * |-----------|-------|---------|
+ * | 3 - stable | 0.9.0 | node, bun, workerd|
  *
  * Unified file storage abstraction across multiple backends.
  *

package/src/cache/core/index.ts

@@ -12,9 +12,9 @@ export * from "./providers/MemoryCacheProvider.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * | type | quality | stability |
- * |------|---------|-----------|
- * | backend | rare | stable |
+ * | Stability | Since | Runtime |
+ * |-----------|-------|---------|
+ * | 3 - stable | 0.9.0 | node, bun, workerd|
  *
  * Type-safe caching with TTL support.
  *

package/src/cli/commands/build.ts

@@ -269,6 +269,7 @@ export class BuildCommand {
             generateCloudflare({
               distDir,
               config: options.cloudflare?.config,
+              alepha: alepha!,
             }),
         });
       }