alepha 0.15.4 → 0.15.5

package/src/api/jobs/services/JobAudits.ts

@@ -0,0 +1,101 @@
+import { $audit, type AuditLogOptions } from "alepha/api/audits";
+
+/**
+ * Job-specific audit service.
+ *
+ * Provides type-safe audit logging for job-related events.
+ * This service is lazy-loaded when the audits feature is enabled.
+ *
+ * @example
+ * ```ts
+ * const jobAudits = alepha.inject(JobAudits);
+ * await jobAudits.logTrigger("my-job", { description: "Manually triggered" });
+ * ```
+ */
+export class JobAudits {
+  protected readonly audit = $audit({
+    type: "job",
+    description: "Background job execution events",
+    actions: ["trigger", "pause", "resume", "cancel", "schedule_change"],
+  });
+
+  /**
+   * Log a manual job trigger event.
+   */
+  public async logTrigger(
+    jobName: string,
+    options: Omit<AuditLogOptions, "resourceType" | "resourceId"> = {},
+  ) {
+    await this.audit.log("trigger", {
+      ...options,
+      resourceType: "job",
+      resourceId: jobName,
+      description: options.description ?? `Manually triggered job: ${jobName}`,
+    });
+  }
+
+  /**
+   * Log a job pause event.
+   */
+  public async logPause(
+    jobName: string,
+    options: Omit<AuditLogOptions, "resourceType" | "resourceId"> = {},
+  ) {
+    await this.audit.log("pause", {
+      ...options,
+      resourceType: "job",
+      resourceId: jobName,
+      description: options.description ?? `Paused job: ${jobName}`,
+    });
+  }
+
+  /**
+   * Log a job resume event.
+   */
+  public async logResume(
+    jobName: string,
+    options: Omit<AuditLogOptions, "resourceType" | "resourceId"> = {},
+  ) {
+    await this.audit.log("resume", {
+      ...options,
+      resourceType: "job",
+      resourceId: jobName,
+      description: options.description ?? `Resumed job: ${jobName}`,
+    });
+  }
+
+  /**
+   * Log a job cancellation event.
+   */
+  public async logCancel(
+    jobName: string,
+    options: Omit<AuditLogOptions, "resourceType" | "resourceId"> = {},
+  ) {
+    await this.audit.log("cancel", {
+      ...options,
+      resourceType: "job",
+      resourceId: jobName,
+      description: options.description ?? `Cancelled job: ${jobName}`,
+    });
+  }
+
+  /**
+   * Log a job schedule change event.
+   */
+  public async logScheduleChange(
+    jobName: string,
+    options: Omit<AuditLogOptions, "resourceType" | "resourceId"> & {
+      oldCron?: string;
+      newCron?: string;
+    } = {},
+  ) {
+    const { oldCron, newCron, ...rest } = options;
+    await this.audit.log("schedule_change", {
+      ...rest,
+      resourceType: "job",
+      resourceId: jobName,
+      description: rest.description ?? `Changed schedule for job: ${jobName}`,
+      metadata: { oldCron, newCron, ...rest.metadata },
+    });
+  }
+}

package/src/api/keys/index.ts

@@ -16,9 +16,9 @@ export * from "./schemas/revokeApiKeyResponseSchema.ts";
 export * from "./services/ApiKeyService.ts";
 
 /**
- * | type | quality | stability |
- * |------|---------|--------------|
- * | backend | good | experimental |
+ * | Stability | Since | Runtime |
+ * |-----------|-------|---------|
+ * | 3 - stable | 0.11.0 | node, bun, workerd|
  *
  * API key management module for programmatic access.
  *

package/src/api/notifications/index.ts

@@ -25,9 +25,9 @@ export * from "./services/NotificationService.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * | type | quality | stability |
- * |------|---------|-----------|
- * | backend | standard | stable |
+ * | Stability | Since | Runtime |
+ * |-----------|-------|---------|
+ * | 3 - stable | 0.10.0 | node, bun, workerd|
  *
  * User notification management.
  *

package/src/api/parameters/index.ts

@@ -1,5 +1,6 @@
 import { $module } from "alepha";
 import { AdminConfigController } from "./controllers/AdminConfigController.ts";
+import { $config } from "./primitives/$config.ts";
 import { ConfigActivationScheduler } from "./schedulers/ConfigActivationScheduler.ts";
 import { ConfigStore } from "./services/ConfigStore.ts";
 
@@ -19,9 +20,9 @@ export * from "./services/ConfigStore.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * | type | quality | stability |
- * |------|---------|-----------|
- * | backend | standard | stable |
+ * | Stability | Since | Runtime |
+ * |-----------|-------|---------|
+ * | 3 - stable | 0.9.0 | node, bun, workerd|
  *
  * Application configuration management.
  *
@@ -35,5 +36,6 @@ export * from "./services/ConfigStore.ts";
  */
 export const AlephaApiParameters = $module({
   name: "alepha.api.parameters",
+  primitives: [$config],
   services: [ConfigStore, AdminConfigController, ConfigActivationScheduler],
 });

package/src/api/users/__tests__/ApiKeys-integration.spec.ts

@@ -33,7 +33,7 @@ const setup = async () => {
   // Create a realm with API keys enabled
   class TestApp {
     realm = $realm({
-      apiKeys: true,
+      features: { apiKeys: true },
     });
 
     // A protected action to test API key authentication (any authenticated user)

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

@@ -20,7 +20,7 @@ const setup = async () => {
   // Create a realm with API keys enabled
   class TestApp {
     realm = $realm({
-      apiKeys: true,
+      features: { apiKeys: true },
     });
   }
 

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

@@ -5,7 +5,13 @@ import { AlephaEmail, MemoryEmailProvider } from "alepha/email";
 import { AlephaSecurity } from "alepha/security";
 import { BadRequestError } from "alepha/server";
 import { describe, it } from "vitest";
-import { AlephaApiUsers, UserController, UserService } from "../index.ts";
+import {
+  AlephaApiUsers,
+  RealmProvider,
+  UserController,
+  UserNotifications,
+  UserService,
+} from "../index.ts";
 
 const setup = async () => {
   const alepha = Alepha.create({
@@ -16,9 +22,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/__tests__/PasswordReset.spec.ts

@@ -8,8 +8,10 @@ import { describe, it } from "vitest";
 import {
   AlephaApiUsers,
   CredentialService,
+  RealmProvider,
   SessionService,
   UserController,
+  UserNotifications,
 } from "../index.ts";
 
 const setup = async () => {
@@ -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/atoms/realmAuthSettingsAtom.ts

@@ -62,6 +62,14 @@ export const realmAuthSettingsAtom = $atom({
     resetPasswordAllowed: t.boolean({
       description: "Enable forgot password functionality",
     }),
+    adminEmails: t.array(t.email(), {
+      description:
+        "List of email addresses that are automatically promoted to admin role on login",
+    }),
+    adminUsernames: t.array(t.text(), {
+      description:
+        "List of usernames that are automatically promoted to admin role on login",
+    }),
     passwordPolicy: t.object({
       minLength: t.integer({
         description: "Minimum password length",
@@ -97,6 +105,8 @@ export const realmAuthSettingsAtom = $atom({
     resetPasswordAllowed: false,
     firstNameLastNameEnabled: false,
     firstNameLastNameRequired: false,
+    adminEmails: [],
+    adminUsernames: [],
     // TODO: not implemented yet
     passwordPolicy: {
       minLength: 8,

package/src/api/users/index.ts

@@ -1,6 +1,4 @@
 import { $module } from "alepha";
-import { AlephaApiNotifications } from "alepha/api/notifications";
-import { AlephaApiVerification } from "alepha/api/verifications";
 import { AlephaEmail } from "alepha/email";
 import { AlephaServerCompress } from "alepha/server/compress";
 import { AlephaServerHelmet } from "alepha/server/helmet";
@@ -9,7 +7,6 @@ import { AdminSessionController } from "./controllers/AdminSessionController.ts"
 import { AdminUserController } from "./controllers/AdminUserController.ts";
 import { RealmController } from "./controllers/RealmController.ts";
 import { UserController } from "./controllers/UserController.ts";
-import { UserNotifications } from "./notifications/UserNotifications.ts";
 import { RealmProvider } from "./providers/RealmProvider.ts";
 import { CredentialService } from "./services/CredentialService.ts";
 import { IdentityService } from "./services/IdentityService.ts";
@@ -52,14 +49,19 @@ export * from "./services/IdentityService.ts";
 export * from "./services/RegistrationService.ts";
 export * from "./services/SessionCrudService.ts";
 export * from "./services/SessionService.ts";
+export * from "./services/UserAudits.ts";
+export * from "./services/UserFiles.ts";
+export * from "./services/UserJobs.ts";
+export * from "./services/UserNotifications.ts";
+export * from "./services/UserParameters.ts";
 export * from "./services/UserService.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * | type | quality | stability |
- * |------|---------|-----------|
- * | backend | epic | stable |
+ * | Stability | Since | Runtime |
+ * |-----------|-------|---------|
+ * | 3 - stable | 0.5.0 | node, bun, workerd|
  *
  * Complete user management with multi-realm support for multi-tenant applications.
  *
@@ -78,8 +80,6 @@ export * from "./services/UserService.ts";
 export const AlephaApiUsers = $module({
   name: "alepha.api.users",
   services: [
-    AlephaApiVerification,
-    AlephaApiNotifications,
     AlephaServerHelmet,
     AlephaServerCompress,
     AlephaEmail,
@@ -95,6 +95,5 @@ export const AlephaApiUsers = $module({
     AdminSessionController,
     AdminIdentityController,
     RealmController,
-    UserNotifications,
   ],
 });

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 = [];