alepha 0.20.4 → 0.20.6

package/src/api/users/__tests__/Registration-emailMode.spec.ts

@@ -0,0 +1,203 @@
+import { Alepha } from "alepha";
+import { AlephaApiVerification } from "alepha/api/verifications";
+import { AlephaEmail, MemoryEmailProvider } from "alepha/email";
+import { AlephaOrmPostgres } from "alepha/orm/postgres";
+import { AlephaSecurity } from "alepha/security";
+import { BadRequestError } from "alepha/server";
+import { describe, expect, it } from "vitest";
+import {
+  AlephaApiUsers,
+  RealmProvider,
+  RegistrationService,
+  UserNotifications,
+  UserService,
+} from "../index.ts";
+
+const setup = async (
+  realmName: string,
+  realmSettings?: Record<string, unknown>,
+) => {
+  const alepha = Alepha.create();
+  alepha.with(AlephaOrmPostgres);
+  alepha.with(AlephaSecurity);
+  alepha.with(AlephaEmail);
+  alepha.with(AlephaApiVerification);
+  alepha.with(AlephaApiUsers);
+  alepha.with(UserNotifications);
+  await alepha.start();
+
+  const realmProvider = alepha.inject(RealmProvider);
+  if (realmSettings) {
+    realmProvider.register(realmName, {
+      settings: realmSettings as never,
+    });
+  }
+
+  // Wipe between cases.
+  await realmProvider.userRepository(realmName).deleteMany({});
+  alepha.inject(MemoryEmailProvider).records = [];
+
+  return {
+    alepha,
+    registrationService: alepha.inject(RegistrationService),
+    userService: alepha.inject(UserService),
+    realmProvider,
+  };
+};
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+describe("RegistrationService — username: 'email' mode", () => {
+  it("derives the username from the email and ignores any client-sent value", async () => {
+    const { registrationService, userService } = await setup("email-mode-1", {
+      username: "email",
+    });
+
+    const intent = await registrationService.createRegistrationIntent(
+      {
+        email: "ni.foures+testkv@gmail.com",
+        password: "SecurePassword123!",
+        // The client sneaks a custom username into the request — server
+        // must drop it on the floor and use the slugger.
+        username: "i-am-the-admin" as never,
+      },
+      "email-mode-1",
+    );
+
+    const user = await registrationService.completeRegistration({
+      intentId: intent.intentId,
+    });
+
+    // Slug rule: gmail "+suffix" preserved, dots → "-".
+    expect(user.username).toBe("ni-foures-testkv");
+
+    const reloaded = await userService
+      .users("email-mode-1")
+      .findOne({ where: { email: { eq: "ni.foures+testkv@gmail.com" } } });
+    expect(reloaded?.username).toBe("ni-foures-testkv");
+  });
+
+  it("appends a 4-char random suffix on collision instead of failing", async () => {
+    const { registrationService, userService } = await setup("email-mode-2", {
+      username: "email",
+    });
+
+    // First user takes the slug.
+    await userService.users("email-mode-2").create({
+      realm: "email-mode-2",
+      username: "alice",
+      email: "preexisting@example.com",
+      roles: ["user"],
+    });
+
+    const intent = await registrationService.createRegistrationIntent(
+      {
+        email: "alice@example.com",
+        password: "SecurePassword123!",
+      },
+      "email-mode-2",
+    );
+    const created = await registrationService.completeRegistration({
+      intentId: intent.intentId,
+    });
+
+    expect(created.username).toMatch(/^alice-[a-z0-9]{4}$/);
+  });
+
+  it("rejects email-mode when no email is provided", async () => {
+    const { registrationService } = await setup("email-mode-3", {
+      username: "email",
+      email: "optional",
+    });
+
+    await expect(
+      registrationService.createRegistrationIntent(
+        {
+          password: "SecurePassword123!",
+        },
+        "email-mode-3",
+      ),
+    ).rejects.toThrowError(BadRequestError);
+  });
+
+  it("blocklist applies even though the client never sees the field", async () => {
+    const { registrationService } = await setup("email-mode-blocklist", {
+      username: "email",
+      usernameBlocklist: ["admin"],
+    });
+
+    const intent = await registrationService.createRegistrationIntent(
+      {
+        email: "admin@example.com",
+        password: "SecurePassword123!",
+      },
+      "email-mode-blocklist",
+    );
+    const user = await registrationService.completeRegistration({
+      intentId: intent.intentId,
+    });
+
+    // Slug "admin" is blocked → falls through to the suffix path.
+    expect(user.username).not.toBe("admin");
+    expect(user.username).toMatch(/^admin-[a-z0-9]{4}$/);
+  });
+});
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+describe("RegistrationService — blocklist applies in 'required' mode too", () => {
+  it("rejects a manual username that hits the blocklist", async () => {
+    const { registrationService } = await setup("manual-mode", {
+      username: "required",
+      usernameBlocklist: ["admin"],
+    });
+
+    await expect(
+      registrationService.createRegistrationIntent(
+        {
+          username: "admin",
+          email: "someone@example.com",
+          password: "SecurePassword123!",
+        },
+        "manual-mode",
+      ),
+    ).rejects.toThrowError(BadRequestError);
+  });
+
+  it("blocklist match is case-insensitive in manual mode", async () => {
+    const { registrationService } = await setup("manual-case", {
+      username: "required",
+      usernameBlocklist: ["Admin"],
+    });
+
+    await expect(
+      registrationService.createRegistrationIntent(
+        {
+          username: "ADMIN",
+          email: "someone@example.com",
+          password: "SecurePassword123!",
+        },
+        "manual-case",
+      ),
+    ).rejects.toThrowError(BadRequestError);
+  });
+
+  it("default (empty) blocklist does not reject special names", async () => {
+    const { registrationService } = await setup("manual-empty", {
+      username: "required",
+    });
+
+    const intent = await registrationService.createRegistrationIntent(
+      {
+        username: "admin",
+        email: "admin-empty@example.com",
+        password: "SecurePassword123!",
+      },
+      "manual-empty",
+    );
+    const created = await registrationService.completeRegistration({
+      intentId: intent.intentId,
+    });
+    expect(created.username).toBe("admin");
+  });
+});

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

@@ -0,0 +1,138 @@
+import { Alepha } from "alepha";
+import { AlephaOrmPostgres } from "alepha/orm/postgres";
+import { AlephaSecurity } from "alepha/security";
+import { describe, expect, it } from "vitest";
+import { realmAuthSettingsAtom } from "../atoms/realmAuthSettingsAtom.ts";
+import { AlephaApiUsers, RealmProvider, UsernameSlugger } from "../index.ts";
+
+const setup = async (realmSettings?: Record<string, unknown>) => {
+  const alepha = Alepha.create();
+  alepha.with(AlephaOrmPostgres);
+  alepha.with(AlephaSecurity);
+  alepha.with(AlephaApiUsers);
+
+  await alepha.start();
+
+  if (realmSettings) {
+    alepha.inject(RealmProvider).register("default", {
+      settings: realmSettings as never,
+    });
+  }
+
+  // Wipe users table between cases so collision tests don't interfere.
+  const users = alepha.inject(RealmProvider).userRepository();
+  await users.deleteMany({});
+
+  return {
+    alepha,
+    slugger: alepha.inject(UsernameSlugger),
+    users,
+  };
+};
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+describe("UsernameSlugger.slug — pure rule", () => {
+  it("strips the domain and the gmail '+suffix' is kept verbatim", async () => {
+    const { slugger } = await setup();
+    expect(slugger.slug("ni.foures+testkv@gmail.com")).toBe("ni-foures-testkv");
+  });
+
+  it("collapses runs of non-alphanumeric chars and trims edges", async () => {
+    const { slugger } = await setup();
+    expect(slugger.slug("john...doe@example.com")).toBe("john-doe");
+    expect(slugger.slug("---weird---name---@x.io")).toBe("weird-name");
+  });
+
+  it("lowercases the result", async () => {
+    const { slugger } = await setup();
+    expect(slugger.slug("Alice.SMITH@Example.com")).toBe("alice-smith");
+  });
+
+  it("drops every non-[a-z0-9] char (no NFD normalize)", async () => {
+    // `é` is dropped, so `josé` becomes `jos` — and then padded to MIN_LENGTH.
+    const { slugger } = await setup();
+    const result = slugger.slug("josé@example.com");
+    expect(result.startsWith("jos")).toBe(true);
+    expect(result.length).toBeGreaterThanOrEqual(UsernameSlugger.MIN_LENGTH);
+  });
+
+  it("pads short slugs with random alphanumerics", async () => {
+    const { slugger } = await setup();
+    const result = slugger.slug("a@example.com");
+    expect(result.startsWith("a")).toBe(true);
+    expect(result.length).toBeGreaterThanOrEqual(UsernameSlugger.MIN_LENGTH);
+    expect(result).toMatch(/^[a-z0-9-]+$/);
+  });
+
+  it("falls back to the EMPTY_LOCAL_FALLBACK when the local part has no [a-z0-9]", async () => {
+    const { slugger } = await setup();
+    expect(slugger.slug("é@example.com")).toBe(
+      UsernameSlugger.EMPTY_LOCAL_FALLBACK,
+    );
+  });
+
+  it("clamps to MAX_LENGTH", async () => {
+    const { slugger } = await setup();
+    const long = `${"a".repeat(60)}@example.com`;
+    expect(slugger.slug(long).length).toBe(UsernameSlugger.MAX_LENGTH);
+  });
+
+  it("treats null/empty input by returning the fallback", async () => {
+    const { slugger } = await setup();
+    expect(slugger.slug(null)).toBe(UsernameSlugger.EMPTY_LOCAL_FALLBACK);
+    expect(slugger.slug("")).toBe(UsernameSlugger.EMPTY_LOCAL_FALLBACK);
+    expect(slugger.slug(undefined)).toBe(UsernameSlugger.EMPTY_LOCAL_FALLBACK);
+  });
+});
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+describe("UsernameSlugger.pickAvailable — DB-backed availability + retry", () => {
+  it("returns the base when nothing collides", async () => {
+    const { slugger } = await setup();
+    const picked = await slugger.pickAvailable("default", "alice");
+    expect(picked).toBe("alice");
+  });
+
+  it("appends a 4-char random suffix when the base is taken", async () => {
+    const { slugger, users } = await setup();
+    await users.create({ realm: "default", username: "alice", email: "a@x" });
+
+    const picked = await slugger.pickAvailable("default", "alice");
+    expect(picked).toMatch(/^alice-[a-z0-9]{4}$/);
+  });
+
+  it("treats blocklisted candidates as collisions and falls through to the suffix path", async () => {
+    const { slugger } = await setup({ usernameBlocklist: ["admin", "root"] });
+
+    const picked = await slugger.pickAvailable("default", "admin");
+    expect(picked).toMatch(/^admin-[a-z0-9]{4}$/);
+  });
+
+  it("trims the base before adding the suffix when MAX_LENGTH would be exceeded", async () => {
+    const { slugger, users } = await setup();
+    const long = "a".repeat(UsernameSlugger.MAX_LENGTH);
+    await users.create({ realm: "default", username: long, email: "a@x" });
+
+    const picked = await slugger.pickAvailable("default", long);
+    expect(picked.length).toBeLessThanOrEqual(UsernameSlugger.MAX_LENGTH);
+    expect(picked).toMatch(/-[a-z0-9]{4}$/);
+  });
+
+  it("blocklist match is case-insensitive", async () => {
+    const { slugger } = await setup({ usernameBlocklist: ["Admin"] });
+    expect(await slugger.isBlocked("default", "admin")).toBe(true);
+    expect(await slugger.isBlocked("default", "ADMIN")).toBe(true);
+    expect(await slugger.isBlocked("default", "user")).toBe(false);
+  });
+
+  it("default blocklist is empty — no name is implicitly reserved", async () => {
+    const { alepha, slugger } = await setup();
+    const settings = alepha.get(realmAuthSettingsAtom);
+    expect(settings.usernameBlocklist).toEqual([]);
+
+    const picked = await slugger.pickAvailable("default", "admin");
+    expect(picked).toBe("admin");
+  });
+});

package/src/api/users/atoms/realmAuthSettingsAtom.ts

@@ -14,6 +14,31 @@ const fieldRequirement = (description: string) =>
     description,
   });
 
+/**
+ * Username-specific field requirement, extending {@link FieldRequirement}
+ * with an additional auto-derivation mode.
+ *
+ * - `"none"` / `"optional"` / `"required"`: same as {@link FieldRequirement}.
+ * - `"email"`: Field is hidden in the registration UI and the value is
+ *   auto-derived from the user's email at signup. Same handling on
+ *   credentials and OAuth flows. See `UsernameSlugger` for the rule and
+ *   collision behavior.
+ */
+export type UsernameFieldRequirement = FieldRequirement | "email";
+
+const usernameFieldRequirement = (description: string) =>
+  t.union(
+    [
+      t.const("none"),
+      t.const("optional"),
+      t.const("required"),
+      t.const("email"),
+    ],
+    {
+      description,
+    },
+  );
+
 export const realmAuthSettingsAtom = $atom({
   name: "alepha.api.users.realmAuthSettings",
   schema: t.object({
@@ -42,11 +67,20 @@ export const realmAuthSettingsAtom = $atom({
     email: fieldRequirement(
       "Email address field requirement for user accounts",
     ),
-    username: fieldRequirement("Username field requirement for user accounts"),
+    username: usernameFieldRequirement(
+      "Username field requirement for user accounts",
+    ),
     usernameRegExp: t.string({
       description:
         "Regular expression that usernames must match (if username is enabled)",
     }),
+    usernameBlocklist: t.array(t.text(), {
+      description:
+        "Usernames that the slugger / manual registration must reject. " +
+        "Default empty so apps can register `admin`/`root`/`me`/etc. if " +
+        "they want; populate it explicitly for handles you want to keep " +
+        "off-limits.",
+    }),
     phoneNumber: fieldRequirement(
       "Phone number field requirement for user accounts",
     ),
@@ -138,8 +172,12 @@ export const realmAuthSettingsAtom = $atom({
     // for a fresh hello world setup, we accept registration and email login
     registrationAllowed: true,
     email: "required" as FieldRequirement,
-    username: "none" as FieldRequirement,
-    usernameRegExp: "^[a-zA-Z0-9_]{3,30}$",
+    username: "none" as UsernameFieldRequirement,
+    // Allow hyphens by default so the UsernameSlugger output (`ni-foures-testkv`)
+    // matches without app overrides. Existing `[a-zA-Z0-9_]` usernames remain
+    // valid because the new pattern is a strict superset.
+    usernameRegExp: "^[a-zA-Z0-9_-]{3,30}$",
+    usernameBlocklist: [] as string[],
     phoneNumber: "none" as FieldRequirement,
     verifyEmailRequired: false,
     verifyPhoneRequired: false,

package/src/api/users/controllers/AdminSessionController.ts

@@ -74,4 +74,33 @@ export class AdminSessionController {
       return { ok: true, id: params.id };
     },
   });
+
+  /**
+   * Delete many sessions in one repository call.
+   */
+  public readonly deleteSessions = $action({
+    method: "POST",
+    path: `${this.url}/delete`,
+    group: this.group,
+    use: [$secure({ permissions: ["admin:session:delete"] })],
+    description: "Delete many sessions",
+    schema: {
+      query: t.object({
+        userRealmName: t.optional(t.string()),
+      }),
+      body: t.object({
+        ids: t.array(t.uuid(), { minItems: 1, maxItems: 1000 }),
+      }),
+      response: t.object({
+        deleted: t.array(t.string()),
+      }),
+    },
+    handler: async ({ body, query }) => {
+      const deleted = await this.sessionService.deleteSessions(
+        body.ids,
+        query.userRealmName,
+      );
+      return { deleted };
+    },
+  });
 }

package/src/api/users/controllers/AdminUserController.ts

@@ -119,4 +119,36 @@ export class AdminUserController {
       return { ok: true, id: params.id };
     },
   });
+
+  /**
+   * Delete many users in one request. Each id is processed sequentially so
+   * cascades and side-effects run as if called one-by-one. Errors on a single
+   * id surface with that id in the response.
+   */
+  public readonly deleteUsers = $action({
+    method: "POST",
+    path: `${this.url}/delete`,
+    group: this.group,
+    use: [$secure({ permissions: ["admin:user:delete"] })],
+    description: "Delete many users",
+    schema: {
+      query: t.object({
+        userRealmName: t.optional(t.string()),
+      }),
+      body: t.object({
+        ids: t.array(t.uuid(), { minItems: 1, maxItems: 1000 }),
+      }),
+      response: t.object({
+        deleted: t.array(t.uuid()),
+      }),
+    },
+    handler: async ({ body, query }) => {
+      const deleted: string[] = [];
+      for (const id of body.ids) {
+        await this.userService.deleteUser(id, query.userRealmName);
+        deleted.push(id);
+      }
+      return { deleted };
+    },
+  });
 }

package/src/api/users/index.ts

@@ -14,6 +14,7 @@ import { IdentityService } from "./services/IdentityService.ts";
 import { RegistrationService } from "./services/RegistrationService.ts";
 import { SessionCrudService } from "./services/SessionCrudService.ts";
 import { SessionService } from "./services/SessionService.ts";
+import { UsernameSlugger } from "./services/UsernameSlugger.ts";
 import { UserService } from "./services/UserService.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
@@ -54,6 +55,7 @@ export * from "./services/IdentityService.ts";
 export * from "./services/RegistrationService.ts";
 export * from "./services/SessionCrudService.ts";
 export * from "./services/SessionService.ts";
+export * from "./services/UsernameSlugger.ts";
 export * from "./services/UserService.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
@@ -82,6 +84,7 @@ export const AlephaApiUsers = $module({
     CredentialService,
     RegistrationService,
     UserService,
+    UsernameSlugger,
     IdentityService,
     UserController,
     AdminUserController,

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

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import { $inject, Alepha } from "alepha";
 import type { VerificationController } from "alepha/api/verifications";
 import { $cache } from "alepha/cache";
+import { DatabaseCacheProvider } from "alepha/cache/database";
 import { DateTimeProvider } from "alepha/datetime";
 import { $logger } from "alepha/logger";
 import { CryptoProvider } from "alepha/security";
@@ -52,6 +53,10 @@ export class CredentialService {
   }
 
   protected readonly intentCache = $cache<PasswordResetIntent>({
+    // Use the SQL-backed cache so phase-2 reads what phase-1 wrote with
+    // strong consistency, and so bare deployments don't need a distributed
+    // KV resource just to support password reset.
+    provider: DatabaseCacheProvider,
     name: "api:users:password-reset-intents",
     ttl: [INTENT_TTL_MINUTES, "minutes"],
   });

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

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import { $inject, Alepha, AlephaError } from "alepha";
 import type { VerificationController } from "alepha/api/verifications";
 import { $cache } from "alepha/cache";
+import { DatabaseCacheProvider } from "alepha/cache/database";
 import { CaptchaProvider } from "alepha/captcha";
 import { DateTimeProvider } from "alepha/datetime";
 import { $logger } from "alepha/logger";
@@ -16,6 +17,7 @@ import type { CompleteRegistrationRequest } from "../schemas/completeRegistratio
 import type { RegisterRequest } from "../schemas/registerRequestSchema.ts";
 import type { RegistrationIntentResponse } from "../schemas/registrationIntentResponseSchema.ts";
 import { CredentialService } from "./CredentialService.ts";
+import { UsernameSlugger } from "./UsernameSlugger.ts";
 
 /**
  * Intent stored in cache during the registration flow.
@@ -50,13 +52,24 @@ export class RegistrationService {
   protected readonly realmProvider = $inject(RealmProvider);
   protected readonly credentialService = $inject(CredentialService);
   protected readonly captchaProvider = $inject(CaptchaProvider);
+  protected readonly usernameSlugger = $inject(UsernameSlugger);
 
   protected readonly intentCache = $cache<RegistrationIntent>({
+    // Pinned to the SQL-backed cache so:
+    // - phase 2 reliably reads the partial-registration payload phase 1 wrote;
+    // - the password hash held in the intent never lives in a distributed
+    //   K/V outside the user's own DB unless they explicitly opt in.
+    provider: DatabaseCacheProvider,
     name: "api:users:registrations",
     ttl: [INTENT_TTL_MINUTES, "minutes"],
   });
 
   protected readonly rateLimitCache = $cache<number>({
+    // Use the SQL-backed cache so `incr()` is atomic (`INSERT ... ON CONFLICT
+    // DO UPDATE SET count = count + 1`). Cloudflare KV silently coalesces
+    // concurrent writes to the same key, which makes the limiter useless
+    // against bursts.
+    provider: DatabaseCacheProvider,
     name: "api:users:registration-rate-limit",
     ttl: [15, "minutes"],
   });
@@ -128,9 +141,16 @@ export class RegistrationService {
       throw new BadRequestError("Username is required");
     }
 
+    // In "email" mode the server is authoritative — any username sent in
+    // the request is dropped on the floor and replaced by the slugger
+    // output below.
+    if (realmSettings?.username === "email") {
+      body.username = undefined;
+    }
+
     if (body.username) {
       // Security note: usernameRegExp is admin-controlled (from realmAuthSettingsAtom),
-      // not user input. Default is ^[a-zA-Z0-9_]{3,30}$ which is ReDoS-safe.
+      // not user input. Default is ^[a-zA-Z0-9_-]{3,30}$ which is ReDoS-safe.
       // No need for regex timeout or safe-regex validation here.
       const usernameRegExp = realmSettings?.usernameRegExp;
       if (usernameRegExp) {
@@ -145,6 +165,17 @@ export class RegistrationService {
           );
         }
       }
+
+      // Manual usernames must also clear the realm blocklist — same set
+      // that the slugger uses, so apps can't be sidestepped by clients
+      // POSTing the reserved name directly.
+      if (await this.usernameSlugger.isBlocked(userRealmName, body.username)) {
+        this.log.debug("Registration rejected: username is blocked", {
+          userRealmName,
+          username: body.username,
+        });
+        throw new BadRequestError("This username is not available");
+      }
     }
 
     if (realmSettings?.email === "required" && !body.email) {
@@ -161,6 +192,23 @@ export class RegistrationService {
       throw new BadRequestError("Phone number is required");
     }
 
+    // In "email" mode, derive the username from the email *now* so that
+    // checkUserAvailability picks it up too, the DB unique index sees a
+    // concrete value, and the persisted intent already carries the final
+    // username.
+    if (realmSettings?.username === "email") {
+      if (!body.email) {
+        throw new BadRequestError(
+          "Email is required to derive a username from email",
+        );
+      }
+      const base = this.usernameSlugger.slug(body.email);
+      body.username = await this.usernameSlugger.pickAvailable(
+        userRealmName,
+        base,
+      );
+    }
+
     // Check for existing users (username, email, phone)
     await this.checkUserAvailability(body, userRealmName);
 

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

@@ -71,4 +71,20 @@ export class SessionCrudService {
     await this.sessions(userRealmName).deleteById(id);
     this.log.info("Session deleted", { id });
   }
+
+  /**
+   * Delete many sessions by ID in one repository call.
+   */
+  public async deleteSessions(
+    ids: string[],
+    userRealmName?: string,
+  ): Promise<string[]> {
+    if (ids.length === 0) return [];
+    this.log.trace("Deleting sessions", { count: ids.length, userRealmName });
+    const deleted = await this.sessions(userRealmName).deleteMany({
+      id: { inArray: ids },
+    });
+    this.log.info("Sessions deleted", { count: deleted.length });
+    return deleted.map(String);
+  }
 }