alepha 0.15.4 → 0.15.5

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

@@ -1,6 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { $inject } from "alepha";
-import { AuditService } from "alepha/api/audits";
+import { $inject, Alepha } from "alepha";
 import type { VerificationController } from "alepha/api/verifications";
 import { $cache } from "alepha/cache";
 import { DateTimeProvider } from "alepha/datetime";
@@ -8,10 +7,11 @@ import { $logger } from "alepha/logger";
 import { CryptoProvider } from "alepha/security";
 import { BadRequestError, HttpError } from "alepha/server";
 import { $client } from "alepha/server/links";
-import { UserNotifications } from "../notifications/UserNotifications.ts";
 import { RealmProvider } from "../providers/RealmProvider.ts";
 import type { CompletePasswordResetRequest } from "../schemas/completePasswordResetRequestSchema.ts";
 import type { PasswordResetIntentResponse } from "../schemas/passwordResetIntentResponseSchema.ts";
+import { UserAudits } from "./UserAudits.ts";
+import { UserNotifications } from "./UserNotifications.ts";
 
 /**
  * Intent stored in cache during the password reset flow.
@@ -27,13 +27,28 @@ interface PasswordResetIntent {
 const INTENT_TTL_MINUTES = 10;
 
 export class CredentialService {
+  protected readonly alepha = $inject(Alepha);
   protected readonly log = $logger();
   protected readonly cryptoProvider = $inject(CryptoProvider);
   protected readonly dateTimeProvider = $inject(DateTimeProvider);
   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;
+  }
 
   protected readonly intentCache = $cache<PasswordResetIntent>({
     name: "password-reset-intents",
@@ -118,7 +133,7 @@ export class CredentialService {
         });
 
       // Send password reset notification with the code
-      await this.userNotifications.passwordReset.push({
+      await this.userNotifications(userRealmName)?.passwordReset.push({
         contact: email,
         variables: {
           email,
@@ -225,7 +240,7 @@ export class CredentialService {
     const realm = this.realmProvider.getRealm(intent.realmName);
 
     // Audit: password reset
-    await this.auditService.recordUser("update", {
+    await this.userAudits(intent.realmName)?.recordUser("update", {
       userId: intent.userId,
       userEmail: intent.email,
       userRealm: realm.name,
@@ -235,14 +250,18 @@ export class CredentialService {
     });
 
     // Audit: sessions invalidated (security event)
-    await this.auditService.record("security", "sessions_invalidated", {
-      userId: intent.userId,
-      userEmail: intent.email,
-      userRealm: realm.name,
-      resourceId: intent.userId,
-      severity: "warning",
-      description: "All sessions invalidated after password reset",
-    });
+    await this.userAudits(intent.realmName)?.record(
+      "security",
+      "sessions_invalidated",
+      {
+        userId: intent.userId,
+        userEmail: intent.email,
+        userRealm: realm.name,
+        resourceId: intent.userId,
+        severity: "warning",
+        description: "All sessions invalidated after password reset",
+      },
+    );
   }
 
   // Legacy methods kept for backward compatibility
@@ -333,7 +352,7 @@ export class CredentialService {
     const realm = this.realmProvider.getRealm(userRealmName);
 
     // Audit: password reset (legacy method)
-    await this.auditService.recordUser("update", {
+    await this.userAudits(userRealmName)?.recordUser("update", {
       userId: user.id,
       userEmail: email,
       userRealm: realm.name,
@@ -343,13 +362,17 @@ export class CredentialService {
     });
 
     // Audit: sessions invalidated
-    await this.auditService.record("security", "sessions_invalidated", {
-      userId: user.id,
-      userEmail: email,
-      userRealm: realm.name,
-      resourceId: user.id,
-      severity: "warning",
-      description: "All sessions invalidated after password reset",
-    });
+    await this.userAudits(userRealmName)?.record(
+      "security",
+      "sessions_invalidated",
+      {
+        userId: user.id,
+        userEmail: email,
+        userRealm: realm.name,
+        resourceId: user.id,
+        severity: "warning",
+        description: "All sessions invalidated after password reset",
+      },
+    );
   }
 }

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

@@ -1,15 +1,23 @@
-import { $inject } from "alepha";
-import { AuditService } from "alepha/api/audits";
+import { $inject, Alepha } from "alepha";
 import { $logger } from "alepha/logger";
 import type { Page } from "alepha/orm";
 import type { IdentityEntity } from "../entities/identities.ts";
 import { RealmProvider } from "../providers/RealmProvider.ts";
 import type { IdentityQuery } from "../schemas/identityQuerySchema.ts";
+import { UserAudits } from "./UserAudits.ts";
 
 export class IdentityService {
+  protected readonly alepha = $inject(Alepha);
   protected readonly log = $logger();
   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;
+  }
 
   public identities(userRealmName?: string) {
     return this.realmProvider.identityRepository(userRealmName);
@@ -87,7 +95,7 @@ export class IdentityService {
 
     const realm = this.realmProvider.getRealm(userRealmName);
 
-    await this.auditService.recordUser("update", {
+    await this.userAudits(userRealmName)?.recordUser("update", {
       userRealm: realm.name,
       resourceId: identity.userId,
       description: `Identity provider disconnected: ${identity.provider}`,

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

@@ -10,6 +10,7 @@ import {
   RealmProvider,
   RegistrationService,
   SessionService,
+  UserNotifications,
   UserService,
 } from "../index.ts";
 
@@ -20,6 +21,7 @@ const setup = async (realmSettings?: Record<string, unknown>) => {
   alepha.with(AlephaEmail);
   alepha.with(AlephaApiVerification);
   alepha.with(AlephaApiUsers);
+  alepha.with(UserNotifications);
 
   await alepha.start();
 
@@ -84,6 +86,9 @@ describe("alepha/api/users - RegistrationService", () => {
 
       // Register realm with email verification required
       realmProvider.register("verify-email-realm", {
+        features: {
+          notifications: true,
+        },
         settings: {
           verifyEmailRequired: true,
         } as never,
@@ -315,6 +320,9 @@ describe("alepha/api/users - RegistrationService", () => {
         await setup();
 
       realmProvider.register("email-verify-realm", {
+        features: {
+          notifications: true,
+        },
         settings: {
           verifyEmailRequired: true,
         } as never,
@@ -586,6 +594,9 @@ describe("alepha/api/users - RegistrationService", () => {
       } = await setup();
 
       realmProvider.register("full-verify-realm", {
+        features: {
+          notifications: true,
+        },
         settings: {
           verifyEmailRequired: true,
         } as never,

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

@@ -1,6 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { $inject } from "alepha";
-import { AuditService } from "alepha/api/audits";
+import { $inject, Alepha } from "alepha";
 import type { VerificationController } from "alepha/api/verifications";
 import { $cache } from "alepha/cache";
 import { DateTimeProvider } from "alepha/datetime";
@@ -9,11 +8,12 @@ import { CryptoProvider } from "alepha/security";
 import { BadRequestError, ConflictError, HttpError } 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 { CompleteRegistrationRequest } from "../schemas/completeRegistrationRequestSchema.ts";
 import type { RegisterRequest } from "../schemas/registerRequestSchema.ts";
 import type { RegistrationIntentResponse } from "../schemas/registrationIntentResponseSchema.ts";
+import { UserAudits } from "./UserAudits.ts";
+import { UserNotifications } from "./UserNotifications.ts";
 
 /**
  * Intent stored in cache during the registration flow.
@@ -40,19 +40,34 @@ interface RegistrationIntent {
 const INTENT_TTL_MINUTES = 10;
 
 export class RegistrationService {
+  protected readonly alepha = $inject(Alepha);
   protected readonly log = $logger();
   protected readonly dateTimeProvider = $inject(DateTimeProvider);
   protected readonly cryptoProvider = $inject(CryptoProvider);
   protected readonly verificationController = $client<VerificationController>();
-  protected readonly userNotifications = $inject(UserNotifications);
   protected readonly realmProvider = $inject(RealmProvider);
-  protected readonly auditService = $inject(AuditService);
 
   protected readonly intentCache = $cache<RegistrationIntent>({
     name: "registration-intents",
     ttl: [INTENT_TTL_MINUTES, "minutes"],
   });
 
+  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;
+  }
+
   /**
    * Phase 1: Create a registration intent.
    *
@@ -130,11 +145,11 @@ export class RegistrationService {
 
     // Create verification sessions and send codes
     if (requirements.email && body.email) {
-      await this.sendEmailVerification(body.email);
+      await this.sendEmailVerification(body.email, userRealmName);
     }
 
     if (requirements.phone && body.phoneNumber) {
-      await this.sendPhoneVerification(body.phoneNumber);
+      await this.sendPhoneVerification(body.phoneNumber, userRealmName);
     }
 
     // Generate intent ID and expiration
@@ -291,7 +306,7 @@ export class RegistrationService {
 
     const realm = this.realmProvider.getRealm(userRealmName);
 
-    await this.auditService.recordUser("create", {
+    await this.userAudits(userRealmName)?.recordUser("create", {
       userId: user.id,
       userEmail: user.email ?? undefined,
       userRealm: realm.name,
@@ -353,7 +368,10 @@ export class RegistrationService {
   /**
    * Send email verification code.
    */
-  protected async sendEmailVerification(email: string): Promise<void> {
+  protected async sendEmailVerification(
+    email: string,
+    realmName?: string,
+  ): Promise<void> {
     this.log.debug("Sending email verification code", { email });
 
     const verification =
@@ -362,7 +380,7 @@ export class RegistrationService {
         body: { target: email },
       });
 
-    await this.userNotifications.emailVerification.push({
+    await this.userNotifications(realmName)?.emailVerification.push({
       contact: email,
       variables: {
         email,
@@ -377,7 +395,10 @@ export class RegistrationService {
   /**
    * Send phone verification code.
    */
-  protected async sendPhoneVerification(phoneNumber: string): Promise<void> {
+  protected async sendPhoneVerification(
+    phoneNumber: string,
+    realmName?: string,
+  ): Promise<void> {
     this.log.debug("Sending phone verification code", { phoneNumber });
     try {
       const verification =
@@ -386,7 +407,7 @@ export class RegistrationService {
           body: { target: phoneNumber },
         });
 
-      await this.userNotifications.phoneVerification.push({
+      await this.userNotifications(realmName)?.phoneVerification.push({
         contact: phoneNumber,
         variables: {
           phoneNumber,

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"],
+  });
+}