alepha 0.20.5 → 0.20.7

package/src/api/subscriptions/services/UsageService.ts

@@ -0,0 +1,118 @@
+import { $inject } from "alepha";
+import { CacheProvider } from "alepha/cache";
+import { DateTimeProvider } from "alepha/datetime";
+import { SubscriptionService } from "./SubscriptionService.ts";
+
+// -----------------------------------------------------------------------------------------------------------------
+
+/**
+ * The result of a usage check or increment operation.
+ */
+export interface UsageResult {
+  /**
+   * Whether the operation is allowed given the current usage and limit.
+   */
+  allowed: boolean;
+
+  /**
+   * Current usage count for the period.
+   */
+  current: number;
+
+  /**
+   * The plan limit for the resource. -1 means unlimited.
+   */
+  limit: number;
+
+  /**
+   * Remaining capacity. -1 means unlimited.
+   */
+  remaining: number;
+}
+
+// -----------------------------------------------------------------------------------------------------------------
+
+/**
+ * Tracks and enforces per-organization resource usage limits.
+ *
+ * Usage counters are keyed by `organizationId:resource:YYYY-MM` and stored in the cache.
+ * Limits are resolved from the organization's current subscription plan.
+ */
+export class UsageService {
+  protected readonly cache = $inject(CacheProvider);
+  protected readonly dateTime = $inject(DateTimeProvider);
+  protected readonly subscriptionService = $inject(SubscriptionService);
+
+  /**
+   * Increment a resource counter for the current period and return the usage result.
+   *
+   * @param organizationId The organization to track usage for.
+   * @param resource The resource identifier (e.g., "api_calls", "seats").
+   * @param amount Amount to increment by (default: 1).
+   */
+  public async increment(
+    organizationId: string,
+    resource: string,
+    amount = 1,
+  ): Promise<UsageResult> {
+    const limit = await this.subscriptionService.limit(
+      organizationId,
+      resource,
+    );
+    const key = this.buildKey(organizationId, resource);
+    const current = await this.cache.incr("subscriptions:usage", key, amount);
+    const allowed = limit === -1 || current <= limit;
+    return {
+      allowed,
+      current,
+      limit,
+      remaining: limit === -1 ? -1 : Math.max(0, limit - current),
+    };
+  }
+
+  /**
+   * Get the current usage for a resource without incrementing.
+   *
+   * @param organizationId The organization to query usage for.
+   * @param resource The resource identifier.
+   */
+  public async getUsage(
+    organizationId: string,
+    resource: string,
+  ): Promise<UsageResult> {
+    const limit = await this.subscriptionService.limit(
+      organizationId,
+      resource,
+    );
+    const key = this.buildKey(organizationId, resource);
+    const current = await this.cache.incr("subscriptions:usage", key, 0);
+    return {
+      allowed: limit === -1 || current <= limit,
+      current,
+      limit,
+      remaining: limit === -1 ? -1 : Math.max(0, limit - current),
+    };
+  }
+
+  /**
+   * Reset all usage counters for an organization.
+   *
+   * Used at the start of a new billing period.
+   *
+   * @param organizationId The organization whose counters to reset.
+   */
+  public async resetForPeriod(organizationId: string): Promise<void> {
+    const pattern = this.buildKey(organizationId, "*");
+    await this.cache.invalidateKeys("subscriptions:usage", [pattern]);
+  }
+
+  /**
+   * Build the cache key for a usage counter.
+   *
+   * Format: `organizationId:resource:YYYY-MM`
+   */
+  protected buildKey(organizationId: string, resource: string): string {
+    const period = this.dateTime.now().format("YYYY-MM");
+    return `${organizationId}:${resource}:${period}`;
+  }
+}

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