alepha 0.15.3 → 0.15.5

package/src/api/users/primitives/$realm.ts

@@ -1,8 +1,6 @@
 import { $context } from "alepha";
-import { AlephaApiAudits } from "alepha/api/audits";
-import { AlephaApiFiles } from "alepha/api/files";
-import { AlephaApiJobs } from "alepha/api/jobs";
 import { AlephaApiKeys, ApiKeyService } from "alepha/api/keys";
+import { AlephaApiVerification } from "alepha/api/verifications";
 import type { Repository } from "alepha/orm";
 import {
   $issuer,
@@ -27,6 +25,11 @@ import type { sessions } from "../entities/sessions.ts";
 import { DEFAULT_USER_REALM_NAME, type users } from "../entities/users.ts";
 import { RealmProvider } from "../providers/RealmProvider.ts";
 import { SessionService } from "../services/SessionService.ts";
+import { UserAudits } from "../services/UserAudits.ts";
+import { UserFiles } from "../services/UserFiles.ts";
+import { UserJobs } from "../services/UserJobs.ts";
+import { UserNotifications } from "../services/UserNotifications.ts";
+import { UserParameters } from "../services/UserParameters.ts";
 
 export type RealmPrimitive = IssuerPrimitive & WithLinkFn & WithLoginFn;
 
@@ -66,12 +69,50 @@ export const $realm = (options: RealmOptions = {}): RealmPrimitive => {
     options.settings.phoneEnabled = true;
   }
 
+  // Merge features with defaults
+  const features: RealmFeatures = {
+    jobs: false,
+    notifications: false,
+    apiKeys: false,
+    parameters: false,
+    files: false,
+    audits: false,
+    organizations: false,
+    ...options.features,
+  };
+
+  // When notifications are disabled, force verification-dependent settings to false
+  // These features require sending codes via email/SMS which won't work without notifications
+  if (!features.notifications) {
+    options.settings.verifyEmailRequired = false;
+    options.settings.verifyPhoneRequired = false;
+    options.settings.resetPasswordAllowed = false;
+  }
+
   const realmRegistration = realmProvider.register(name, options);
 
-  // For now, all modules are enabled
-  alepha.with(AlephaApiFiles);
-  alepha.with(AlephaApiAudits);
-  alepha.with(AlephaApiJobs);
+  // Enable features based on configuration
+  // Each feature registers its wrapper service which internally uses the module primitives
+  if (features.files) {
+    alepha.with(UserFiles);
+  }
+
+  if (features.audits) {
+    alepha.with(UserAudits);
+  }
+
+  if (features.jobs) {
+    alepha.with(UserJobs);
+  }
+
+  if (features.notifications) {
+    alepha.with(AlephaApiVerification);
+    alepha.with(UserNotifications);
+  }
+
+  if (features.parameters) {
+    alepha.with(UserParameters);
+  }
 
   // Collect custom resolvers that will be registered during $issuer.onInit()
   // This ensures they are registered AFTER the realm is created (not on the default test realm)
@@ -80,7 +121,7 @@ export const $realm = (options: RealmOptions = {}): RealmPrimitive => {
   ];
 
   // Enable API key authentication - must be added to customResolvers before $issuer() call
-  if (options.apiKeys) {
+  if (features.apiKeys) {
     alepha.with(AlephaApiKeys);
     const apiKeyService = alepha.inject(ApiKeyService);
     customResolvers.push(apiKeyService.createResolver());
@@ -176,6 +217,71 @@ export const $realm = (options: RealmOptions = {}): RealmPrimitive => {
 
 // ---------------------------------------------------------------------------------------------------------------------
 
+export interface RealmFeatures {
+  /**
+   * Enable job execution tracking and purge functionality.
+   *
+   * @default false
+   */
+  jobs?: boolean;
+
+  /**
+   * Enable notification system for password reset, verification emails, etc.
+   *
+   * @default false
+   */
+  notifications?: boolean;
+
+  /**
+   * Enable API key authentication for programmatic access.
+   *
+   * When enabled, users can create API keys to access protected endpoints
+   * without using JWT tokens. API keys are useful for:
+   * - Programmatic access (CLI tools, scripts)
+   * - Long-lived authentication tokens
+   * - Third-party integrations (MCP servers)
+   *
+   * API keys can be passed via:
+   * - Query parameter: `?api_key=ak_xxx`
+   * - Bearer header: `Authorization: Bearer ak_xxx`
+   *
+   * @default false
+   */
+  apiKeys?: boolean;
+
+  /**
+   * Enable runtime configuration management.
+   *
+   * Allows configuring realm settings at runtime with versioning and scheduled activation.
+   *
+   * @default false
+   */
+  parameters?: boolean;
+
+  /**
+   * Enable file management for avatar uploads and attachments.
+   *
+   * @default false
+   */
+  files?: boolean;
+
+  /**
+   * Enable audit trail for compliance and event logging.
+   *
+   * @default false
+   */
+  audits?: boolean;
+
+  /**
+   * Enable organization management to group users.
+   *
+   * @default false
+   */
+  organizations?: boolean;
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+
 export interface RealmOptions {
   /**
    * Secret key for signing tokens.
@@ -209,17 +315,9 @@ export interface RealmOptions {
   };
 
   /**
-   * Enable API key authentication.
-   *
-   * When enabled, users can create API keys to access protected endpoints
-   * without using JWT tokens. API keys are useful for:
-   * - Programmatic access (CLI tools, scripts)
-   * - Long-lived authentication tokens
-   * - Third-party integrations
+   * Enable or disable realm features.
    *
-   * API keys can be passed via:
-   * - Query parameter: `?api_key=ak_xxx`
-   * - Bearer header: `Authorization: Bearer ak_xxx`
+   * Features control which modules are loaded with the realm.
    */
-  apiKeys?: boolean;
+  features?: Partial<RealmFeatures>;
 }

package/src/api/users/providers/RealmProvider.ts

@@ -1,5 +1,4 @@
 import { $inject, Alepha, AlephaError } from "alepha";
-import { $bucket } from "alepha/bucket";
 import { $repository, type Repository } from "alepha/orm";
 import {
   type RealmAuthSettings,
@@ -8,7 +7,7 @@ import {
 import { identities } from "../entities/identities.ts";
 import { sessions } from "../entities/sessions.ts";
 import { DEFAULT_USER_REALM_NAME, users } from "../entities/users.ts";
-import type { RealmOptions } from "../primitives/$realm.ts";
+import type { RealmFeatures, RealmOptions } from "../primitives/$realm.ts";
 
 export interface RealmRepositories {
   identities: Repository<typeof identities.schema>;
@@ -20,6 +19,7 @@ export interface Realm {
   name: string;
   repositories: RealmRepositories;
   settings: RealmAuthSettings;
+  features: RealmFeatures;
 }
 
 export class RealmProvider {
@@ -31,12 +31,19 @@ export class RealmProvider {
 
   protected realms = new Map<string, Realm>();
 
-  public avatars = $bucket({
-    maxSize: 5 * 1024 * 1024, // 5 MB
-    mimeTypes: ["image/jpeg", "image/png", "image/gif", "image/webp"],
-  });
-
   public register(realmName: string, realmOptions: RealmOptions = {}) {
+    // Merge features with defaults
+    const features: RealmFeatures = {
+      jobs: false,
+      notifications: false,
+      apiKeys: false,
+      parameters: false,
+      files: false,
+      audits: false,
+      organizations: false,
+      ...realmOptions.features,
+    };
+
     this.realms.set(realmName, {
       name: realmName,
       repositories: {
@@ -53,6 +60,7 @@ export class RealmProvider {
           ...realmOptions.settings?.passwordPolicy,
         },
       },
+      features,
     });
     return this.getRealm(realmName);
   }

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

@@ -8,7 +8,9 @@ import { describe, it } from "vitest";
 import {
   AlephaApiUsers,
   CredentialService,
+  RealmProvider,
   SessionService,
+  UserNotifications,
   UserService,
 } from "../index.ts";
 
@@ -21,9 +23,18 @@ const setup = async () => {
   alepha.with(AlephaEmail);
   alepha.with(AlephaApiVerification);
   alepha.with(AlephaApiUsers);
+  alepha.with(UserNotifications);
 
   await alepha.start();
 
+  // Enable notifications for the default realm
+  const realmProvider = alepha.inject(RealmProvider);
+  realmProvider.register("default", {
+    features: {
+      notifications: true,
+    },
+  });
+
   const emailProvider = alepha.inject(MemoryEmailProvider);
   emailProvider.records = [];
 

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,