alepha 0.14.3 → 0.15.0

package/src/api/users/index.ts

@@ -7,10 +7,10 @@ import { AlephaServerHelmet } from "alepha/server/helmet";
 import { AdminIdentityController } from "./controllers/AdminIdentityController.ts";
 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 { UserRealmController } from "./controllers/UserRealmController.ts";
 import { UserNotifications } from "./notifications/UserNotifications.ts";
-import { UserRealmProvider } from "./providers/UserRealmProvider.ts";
+import { RealmProvider } from "./providers/RealmProvider.ts";
 import { CredentialService } from "./services/CredentialService.ts";
 import { IdentityService } from "./services/IdentityService.ts";
 import { RegistrationService } from "./services/RegistrationService.ts";
@@ -24,13 +24,13 @@ export * from "./atoms/realmAuthSettingsAtom.ts";
 export * from "./controllers/AdminIdentityController.ts";
 export * from "./controllers/AdminSessionController.ts";
 export * from "./controllers/AdminUserController.ts";
+export * from "./controllers/RealmController.ts";
 export * from "./controllers/UserController.ts";
-export * from "./controllers/UserRealmController.ts";
 export * from "./entities/identities.ts";
 export * from "./entities/sessions.ts";
 export * from "./entities/users.ts";
-export * from "./primitives/$userRealm.ts";
-export * from "./providers/UserRealmProvider.ts";
+export * from "./primitives/$realm.ts";
+export * from "./providers/RealmProvider.ts";
 export * from "./schemas/completePasswordResetRequestSchema.ts";
 export * from "./schemas/completeRegistrationRequestSchema.ts";
 export * from "./schemas/createUserSchema.ts";
@@ -38,6 +38,7 @@ export * from "./schemas/identityQuerySchema.ts";
 export * from "./schemas/identityResourceSchema.ts";
 export * from "./schemas/loginSchema.ts";
 export * from "./schemas/passwordResetIntentResponseSchema.ts";
+export * from "./schemas/realmConfigSchema.ts";
 export * from "./schemas/registerSchema.ts";
 export * from "./schemas/registrationIntentResponseSchema.ts";
 export * from "./schemas/resetPasswordSchema.ts";
@@ -45,7 +46,6 @@ export * from "./schemas/sessionQuerySchema.ts";
 export * from "./schemas/sessionResourceSchema.ts";
 export * from "./schemas/updateUserSchema.ts";
 export * from "./schemas/userQuerySchema.ts";
-export * from "./schemas/userRealmConfigSchema.ts";
 export * from "./schemas/userResourceSchema.ts";
 export * from "./services/CredentialService.ts";
 export * from "./services/IdentityService.ts";
@@ -72,7 +72,7 @@ export const AlephaApiUsers = $module({
     AlephaServerHelmet,
     AlephaServerCompress,
     AlephaEmail,
-    UserRealmProvider,
+    RealmProvider,
     SessionService,
     SessionCrudService,
     CredentialService,
@@ -83,7 +83,7 @@ export const AlephaApiUsers = $module({
     AdminUserController,
     AdminSessionController,
     AdminIdentityController,
-    UserRealmController,
+    RealmController,
     UserNotifications,
   ],
 });

package/src/api/users/primitives/{$userRealm.ts → $realm.ts}

@@ -3,9 +3,9 @@ import { AlephaApiAudits } from "alepha/api/audits";
 import { AlephaApiFiles } from "alepha/api/files";
 import type { Repository } from "alepha/orm";
 import {
-  $realm,
-  type RealmPrimitive,
-  type RealmPrimitiveOptions,
+  $issuer,
+  type IssuerPrimitive,
+  type IssuerPrimitiveOptions,
   SecurityProvider,
 } from "alepha/security";
 import {
@@ -22,10 +22,10 @@ import type { RealmAuthSettings } from "../atoms/realmAuthSettingsAtom.ts";
 import type { identities } from "../entities/identities.ts";
 import type { sessions } from "../entities/sessions.ts";
 import { DEFAULT_USER_REALM_NAME, type users } from "../entities/users.ts";
-import { UserRealmProvider } from "../providers/UserRealmProvider.ts";
+import { RealmProvider } from "../providers/RealmProvider.ts";
 import { SessionService } from "../services/SessionService.ts";
 
-export type UserRealmPrimitive = RealmPrimitive & WithLinkFn & WithLoginFn;
+export type RealmPrimitive = IssuerPrimitive & WithLinkFn & WithLoginFn;
 
 /**
  * Already configured realm for user management.
@@ -41,15 +41,13 @@ export type UserRealmPrimitive = RealmPrimitive & WithLinkFn & WithLoginFn;
  * - `APP_SECRET`: Secret key for signing tokens (if not provided in options).
  */
 
-export const $userRealm = (
-  options: UserRealmOptions = {},
-): UserRealmPrimitive => {
+export const $realm = (options: RealmOptions = {}): RealmPrimitive => {
   const { alepha } = $context();
   const sessionService = alepha.inject(SessionService);
   const securityProvider = alepha.inject(SecurityProvider);
-  const userRealmProvider = alepha.inject(UserRealmProvider);
+  const realmProvider = alepha.inject(RealmProvider);
 
-  const name = options.realm?.name ?? DEFAULT_USER_REALM_NAME;
+  const name = options.issuer?.name ?? DEFAULT_USER_REALM_NAME;
 
   options.settings ??= {};
 
@@ -65,16 +63,16 @@ export const $userRealm = (
     options.settings.phoneEnabled = true;
   }
 
-  const userRealm = userRealmProvider.register(name, options);
+  const realmRegistration = realmProvider.register(name, options);
 
   alepha.with(AlephaApiFiles);
   alepha.with(AlephaApiAudits);
 
-  const realm: UserRealmPrimitive = $realm({
-    ...options.realm,
+  const realm: RealmPrimitive = $issuer({
+    ...options.issuer,
     name,
     secret: options.secret ?? securityProvider.secretKey,
-    roles: options.realm?.roles ?? [
+    roles: options.issuer?.roles ?? [
       {
         name: "admin",
         permissions: [
@@ -110,7 +108,7 @@ export const $userRealm = (
       onDeleteSession: async (refreshToken) => {
         await sessionService.deleteSession(refreshToken);
       },
-      ...options.realm?.settings,
+      ...options.issuer?.settings,
     },
   });
 
@@ -140,7 +138,7 @@ export const $userRealm = (
       auth.credentials = $authCredentials(realm);
     } else {
       // if credentials auth is disabled, disable registration as well
-      userRealm.settings.registrationAllowed = false;
+      realmRegistration.settings.registrationAllowed = false;
     }
 
     if (identities.google) {
@@ -159,7 +157,7 @@ export const $userRealm = (
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-export interface UserRealmOptions {
+export interface RealmOptions {
   /**
    * Secret key for signing tokens.
    *
@@ -168,11 +166,11 @@ export interface UserRealmOptions {
   secret?: string;
 
   /**
-   * Realm configuration options.
+   * Issuer configuration options.
    *
    * It's already pre-configured for user management with admin and user roles.
    */
-  realm?: Partial<RealmPrimitiveOptions>;
+  issuer?: Partial<IssuerPrimitiveOptions>;
 
   /**
    * Override entities.

package/src/api/users/providers/{UserRealmProvider.ts → RealmProvider.ts}

@@ -8,28 +8,28 @@ 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 { UserRealmOptions } from "../primitives/$userRealm.ts";
+import type { RealmOptions } from "../primitives/$realm.ts";
 
-export interface UserRealmRepositories {
+export interface RealmRepositories {
   identities: Repository<typeof identities.schema>;
   sessions: Repository<typeof sessions.schema>;
   users: Repository<typeof users.schema>;
 }
 
-export interface UserRealm {
+export interface Realm {
   name: string;
-  repositories: UserRealmRepositories;
+  repositories: RealmRepositories;
   settings: RealmAuthSettings;
 }
 
-export class UserRealmProvider {
+export class RealmProvider {
   protected readonly alepha = $inject(Alepha);
   // Default repositories using $repository() for eager initialization
   protected readonly defaultIdentities = $repository(identities);
   protected readonly defaultSessions = $repository(sessions);
   protected readonly defaultUsers = $repository(users);
 
-  protected realms = new Map<string, UserRealm>();
+  protected realms = new Map<string, Realm>();
 
   public avatars = $bucket({
     maxSize: 5 * 1024 * 1024, // 5 MB
@@ -47,48 +47,44 @@ export class UserRealmProvider {
     },
   });
 
-  public register(
-    userRealmName: string,
-    userRealmOptions: UserRealmOptions = {},
-  ) {
-    this.realms.set(userRealmName, {
-      name: userRealmName,
+  public register(realmName: string, realmOptions: RealmOptions = {}) {
+    this.realms.set(realmName, {
+      name: realmName,
       repositories: {
-        identities:
-          userRealmOptions.entities?.identities ?? this.defaultIdentities,
-        sessions: userRealmOptions.entities?.sessions ?? this.defaultSessions,
-        users: userRealmOptions.entities?.users ?? this.defaultUsers,
+        identities: realmOptions.entities?.identities ?? this.defaultIdentities,
+        sessions: realmOptions.entities?.sessions ?? this.defaultSessions,
+        users: realmOptions.entities?.users ?? this.defaultUsers,
       },
       // TODO: Remove deep merge when alepha supports it natively
       settings: {
         ...realmAuthSettingsAtom.options.default,
-        ...userRealmOptions.settings,
+        ...realmOptions.settings,
         passwordPolicy: {
           ...realmAuthSettingsAtom.options.default.passwordPolicy,
-          ...userRealmOptions.settings?.passwordPolicy,
+          ...realmOptions.settings?.passwordPolicy,
         },
       },
     });
-    return this.getRealm(userRealmName);
+    return this.getRealm(realmName);
   }
 
   /**
    * Gets a registered realm by name, auto-creating default if needed.
    */
-  public getRealm(userRealmName = DEFAULT_USER_REALM_NAME): UserRealm {
-    let realm = this.realms.get(userRealmName);
+  public getRealm(realmName = DEFAULT_USER_REALM_NAME): Realm {
+    let realm = this.realms.get(realmName);
 
     if (!realm) {
       // Auto-register default realm for backward compatibility
       const realms = Array.from(this.realms.values());
       const firstRealm = realms[0];
-      if (userRealmName === DEFAULT_USER_REALM_NAME && firstRealm) {
+      if (realmName === DEFAULT_USER_REALM_NAME && firstRealm) {
         realm = firstRealm;
       } else if (this.alepha.isTest()) {
-        realm = this.register(userRealmName); // Auto-create default realm in tests
+        realm = this.register(realmName); // Auto-create default realm in tests
       } else {
         throw new AlephaError(
-          `Missing user realm '${userRealmName}', please declare $userRealm in your application.`,
+          `Missing realm '${realmName}', please declare $realm in your application.`,
         );
       }
     }
@@ -97,20 +93,20 @@ export class UserRealmProvider {
   }
 
   public identityRepository(
-    userRealmName = DEFAULT_USER_REALM_NAME,
+    realmName = DEFAULT_USER_REALM_NAME,
   ): Repository<typeof identities.schema> {
-    return this.getRealm(userRealmName).repositories.identities;
+    return this.getRealm(realmName).repositories.identities;
   }
 
   public sessionRepository(
-    userRealmName = DEFAULT_USER_REALM_NAME,
+    realmName = DEFAULT_USER_REALM_NAME,
   ): Repository<typeof sessions.schema> {
-    return this.getRealm(userRealmName).repositories.sessions;
+    return this.getRealm(realmName).repositories.sessions;
   }
 
   public userRepository(
-    userRealmName = DEFAULT_USER_REALM_NAME,
+    realmName = DEFAULT_USER_REALM_NAME,
   ): Repository<typeof users.schema> {
-    return this.getRealm(userRealmName).repositories.users;
+    return this.getRealm(realmName).repositories.users;
   }
 }

package/src/api/users/schemas/{userRealmConfigSchema.ts → realmConfigSchema.ts}

@@ -2,10 +2,10 @@ import { type Static, t } from "alepha";
 import { authenticationProviderSchema } from "alepha/server/auth";
 import { realmAuthSettingsAtom } from "../atoms/realmAuthSettingsAtom.ts";
 
-export const userRealmConfigSchema = t.object({
+export const realmConfigSchema = t.object({
   settings: realmAuthSettingsAtom.schema,
   realmName: t.string(),
   authenticationMethods: t.array(authenticationProviderSchema),
 });
 
-export type UserRealmConfig = Static<typeof userRealmConfigSchema>;
+export type RealmConfig = Static<typeof realmConfigSchema>;

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

@@ -9,7 +9,7 @@ import { CryptoProvider } from "alepha/security";
 import { BadRequestError, HttpError } from "alepha/server";
 import { $client } from "alepha/server/links";
 import { UserNotifications } from "../notifications/UserNotifications.ts";
-import { UserRealmProvider } from "../providers/UserRealmProvider.ts";
+import { RealmProvider } from "../providers/RealmProvider.ts";
 import type { CompletePasswordResetRequest } from "../schemas/completePasswordResetRequestSchema.ts";
 import type { PasswordResetIntentResponse } from "../schemas/passwordResetIntentResponseSchema.ts";
 
@@ -32,7 +32,7 @@ export class CredentialService {
   protected readonly dateTimeProvider = $inject(DateTimeProvider);
   protected readonly verificationController = $client<VerificationController>();
   protected readonly userNotifications = $inject(UserNotifications);
-  protected readonly userRealmProvider = $inject(UserRealmProvider);
+  protected readonly realmProvider = $inject(RealmProvider);
   protected readonly auditService = $inject(AuditService);
 
   protected readonly intentCache = $cache<PasswordResetIntent>({
@@ -41,15 +41,15 @@ export class CredentialService {
   });
 
   public users(userRealmName?: string) {
-    return this.userRealmProvider.userRepository(userRealmName);
+    return this.realmProvider.userRepository(userRealmName);
   }
 
   public sessions(userRealmName?: string) {
-    return this.userRealmProvider.sessionRepository(userRealmName);
+    return this.realmProvider.sessionRepository(userRealmName);
   }
 
   public identities(userRealmName?: string) {
-    return this.userRealmProvider.identityRepository(userRealmName);
+    return this.realmProvider.identityRepository(userRealmName);
   }
 
   /**
@@ -222,7 +222,7 @@ export class CredentialService {
       email: intent.email,
     });
 
-    const realm = this.userRealmProvider.getRealm(intent.realmName);
+    const realm = this.realmProvider.getRealm(intent.realmName);
 
     // Audit: password reset
     await this.auditService.recordUser("update", {
@@ -330,7 +330,7 @@ export class CredentialService {
       userId: { eq: user.id },
     });
 
-    const realm = this.userRealmProvider.getRealm(userRealmName);
+    const realm = this.realmProvider.getRealm(userRealmName);
 
     // Audit: password reset (legacy method)
     await this.auditService.recordUser("update", {

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

@@ -3,16 +3,16 @@ import { AuditService } from "alepha/api/audits";
 import { $logger } from "alepha/logger";
 import type { Page } from "alepha/orm";
 import type { IdentityEntity } from "../entities/identities.ts";
-import { UserRealmProvider } from "../providers/UserRealmProvider.ts";
+import { RealmProvider } from "../providers/RealmProvider.ts";
 import type { IdentityQuery } from "../schemas/identityQuerySchema.ts";
 
 export class IdentityService {
   protected readonly log = $logger();
-  protected readonly userRealmProvider = $inject(UserRealmProvider);
+  protected readonly realmProvider = $inject(RealmProvider);
   protected readonly auditService = $inject(AuditService);
 
   public identities(userRealmName?: string) {
-    return this.userRealmProvider.identityRepository(userRealmName);
+    return this.realmProvider.identityRepository(userRealmName);
   }
 
   /**
@@ -85,7 +85,7 @@ export class IdentityService {
       userId: identity.userId,
     });
 
-    const realm = this.userRealmProvider.getRealm(userRealmName);
+    const realm = this.realmProvider.getRealm(userRealmName);
 
     await this.auditService.recordUser("update", {
       userRealm: realm.name,

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

@@ -7,9 +7,9 @@ import { BadRequestError, ConflictError, HttpError } from "alepha/server";
 import { describe, it } from "vitest";
 import {
   AlephaApiUsers,
+  RealmProvider,
   RegistrationService,
   SessionService,
-  UserRealmProvider,
   UserService,
 } from "../index.ts";
 
@@ -26,11 +26,11 @@ const setup = async (realmSettings?: Record<string, unknown>) => {
   const emailProvider = alepha.inject(MemoryEmailProvider);
   emailProvider.records = [];
 
-  const userRealmProvider = alepha.inject(UserRealmProvider);
+  const realmProvider = alepha.inject(RealmProvider);
 
   // Configure realm settings if provided (applies to default realm)
   if (realmSettings) {
-    userRealmProvider.register("default", {
+    realmProvider.register("default", {
       settings: realmSettings as never,
     });
   }
@@ -43,7 +43,7 @@ const setup = async (realmSettings?: Record<string, unknown>) => {
     cryptoProvider: alepha.inject(CryptoProvider),
     dateTimeProvider: alepha.inject(DateTimeProvider),
     emailProvider,
-    userRealmProvider,
+    realmProvider,
   };
 };
 
@@ -79,11 +79,11 @@ describe("alepha/api/users - RegistrationService", () => {
     it("should create intent with email verification required when configured", async ({
       expect,
     }) => {
-      const { registrationService, emailProvider, userRealmProvider } =
+      const { registrationService, emailProvider, realmProvider } =
         await setup();
 
       // Register realm with email verification required
-      userRealmProvider.register("verify-email-realm", {
+      realmProvider.register("verify-email-realm", {
         settings: {
           verifyEmailRequired: true,
         } as never,
@@ -113,9 +113,9 @@ describe("alepha/api/users - RegistrationService", () => {
     it("should reject registration when disabled in realm settings", async ({
       expect,
     }) => {
-      const { registrationService, userRealmProvider } = await setup();
+      const { registrationService, realmProvider } = await setup();
 
-      userRealmProvider.register("no-registration-realm", {
+      realmProvider.register("no-registration-realm", {
         settings: {
           registrationAllowed: false,
         } as never,
@@ -135,9 +135,9 @@ describe("alepha/api/users - RegistrationService", () => {
     it("should reject when required username is missing", async ({
       expect,
     }) => {
-      const { registrationService, userRealmProvider } = await setup();
+      const { registrationService, realmProvider } = await setup();
 
-      userRealmProvider.register("username-required-realm", {
+      realmProvider.register("username-required-realm", {
         settings: {
           usernameRequired: true,
         } as never,
@@ -169,9 +169,9 @@ describe("alepha/api/users - RegistrationService", () => {
     });
 
     it("should reject when required phone is missing", async ({ expect }) => {
-      const { registrationService, userRealmProvider } = await setup();
+      const { registrationService, realmProvider } = await setup();
 
-      userRealmProvider.register("phone-required-realm", {
+      realmProvider.register("phone-required-realm", {
         settings: {
           phoneRequired: true,
           emailRequired: false,
@@ -229,10 +229,9 @@ describe("alepha/api/users - RegistrationService", () => {
     });
 
     it("should reject duplicate phone number", async ({ expect }) => {
-      const { registrationService, userService, userRealmProvider } =
-        await setup();
+      const { registrationService, userService, realmProvider } = await setup();
 
-      userRealmProvider.register("phone-realm", {
+      realmProvider.register("phone-realm", {
         settings: {
           phoneEnabled: true,
           emailRequired: false,
@@ -312,10 +311,10 @@ describe("alepha/api/users - RegistrationService", () => {
     it("should complete registration with valid email verification code", async ({
       expect,
     }) => {
-      const { registrationService, emailProvider, userRealmProvider } =
+      const { registrationService, emailProvider, realmProvider } =
         await setup();
 
-      userRealmProvider.register("email-verify-realm", {
+      realmProvider.register("email-verify-realm", {
         settings: {
           verifyEmailRequired: true,
         } as never,
@@ -379,9 +378,9 @@ describe("alepha/api/users - RegistrationService", () => {
     it("should reject when email code is required but not provided", async ({
       expect,
     }) => {
-      const { registrationService, userRealmProvider } = await setup();
+      const { registrationService, realmProvider } = await setup();
 
-      userRealmProvider.register("email-required-realm", {
+      realmProvider.register("email-required-realm", {
         settings: {
           verifyEmailRequired: true,
         } as never,
@@ -404,9 +403,9 @@ describe("alepha/api/users - RegistrationService", () => {
     });
 
     it("should reject invalid email verification code", async ({ expect }) => {
-      const { registrationService, userRealmProvider } = await setup();
+      const { registrationService, realmProvider } = await setup();
 
-      userRealmProvider.register("email-verify-realm", {
+      realmProvider.register("email-verify-realm", {
         settings: {
           verifyEmailRequired: true,
         } as never,
@@ -454,10 +453,9 @@ describe("alepha/api/users - RegistrationService", () => {
     it("should detect race condition when email is taken during verification", async ({
       expect,
     }) => {
-      const { registrationService, userService, userRealmProvider } =
-        await setup();
+      const { registrationService, userService, realmProvider } = await setup();
 
-      userRealmProvider.register("race-realm", {
+      realmProvider.register("race-realm", {
         settings: {
           verifyEmailRequired: false,
         } as never,
@@ -490,7 +488,7 @@ describe("alepha/api/users - RegistrationService", () => {
     it("should create credentials identity with hashed password", async ({
       expect,
     }) => {
-      const { registrationService, sessionService, userRealmProvider } =
+      const { registrationService, sessionService, realmProvider } =
         await setup();
 
       const intent = await registrationService.createRegistrationIntent({
@@ -584,10 +582,10 @@ describe("alepha/api/users - RegistrationService", () => {
         registrationService,
         sessionService,
         emailProvider,
-        userRealmProvider,
+        realmProvider,
       } = await setup();
 
-      userRealmProvider.register("full-verify-realm", {
+      realmProvider.register("full-verify-realm", {
         settings: {
           verifyEmailRequired: true,
         } as never,