alepha 0.15.1 → 0.15.3

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

@@ -0,0 +1,401 @@
+import { Alepha } from "alepha";
+import { ApiKeyService } from "alepha/api/keys";
+import { DateTimeProvider } from "alepha/datetime";
+import { AlephaEmail } from "alepha/email";
+import { AlephaSecurity } from "alepha/security";
+import { AlephaServer, ForbiddenError } from "alepha/server";
+import { describe, it } from "vitest";
+import { $realm, AlephaApiUsers, SessionService } from "../index.ts";
+
+const setup = async () => {
+  const alepha = Alepha.create({
+    env: { LOG_LEVEL: "error" },
+  });
+
+  alepha.with(AlephaServer);
+  alepha.with(AlephaSecurity);
+  alepha.with(AlephaEmail);
+  alepha.with(AlephaApiUsers);
+
+  // Create a realm with API keys enabled
+  class TestApp {
+    realm = $realm({
+      apiKeys: true,
+    });
+  }
+
+  alepha.inject(TestApp);
+  await alepha.start();
+
+  const sessionService = alepha.inject(SessionService);
+  const apiKeyService = alepha.inject(ApiKeyService);
+  const dateTimeProvider = alepha.inject(DateTimeProvider);
+
+  return {
+    alepha,
+    sessionService,
+    apiKeyService,
+    dateTimeProvider,
+  };
+};
+
+describe("alepha/api/users - API Keys Integration", () => {
+  it("should create an API key for a user", async ({ expect }) => {
+    const { sessionService, apiKeyService } = await setup();
+
+    // Create a user
+    const user = await sessionService.users().create({
+      username: "testuser",
+      email: "test@example.com",
+      roles: ["user"],
+    });
+
+    // Create an API key
+    const { apiKey, token } = await apiKeyService.create({
+      userId: user.id,
+      name: "My API Key",
+      roles: ["user"],
+    });
+
+    expect(apiKey.name).toBe("My API Key");
+    expect(apiKey.userId).toBe(user.id);
+    expect(apiKey.roles).toEqual(["user"]);
+    expect(token).toMatch(/^ak_/);
+  });
+
+  it("should validate API key and return user info", async ({ expect }) => {
+    const { sessionService, apiKeyService } = await setup();
+
+    // Create a user
+    const user = await sessionService.users().create({
+      username: "testuser",
+      email: "test@example.com",
+      roles: ["user"],
+    });
+
+    // Create an API key
+    const { token } = await apiKeyService.create({
+      userId: user.id,
+      name: "My API Key",
+      roles: ["user"],
+    });
+
+    // Validate the API key
+    const userInfo = await apiKeyService.validate(token);
+
+    expect(userInfo).not.toBeNull();
+    expect(userInfo?.id).toBe(user.id);
+    expect(userInfo?.roles).toEqual(["user"]);
+  });
+
+  it("should resolve user from API key in query param via resolver", async ({
+    expect,
+  }) => {
+    const { sessionService, apiKeyService } = await setup();
+
+    // Create a user
+    const user = await sessionService.users().create({
+      username: "testuser",
+      email: "test@example.com",
+      roles: ["user"],
+    });
+
+    // Create an API key
+    const { token } = await apiKeyService.create({
+      userId: user.id,
+      name: "My API Key",
+      roles: ["user"],
+    });
+
+    // Create resolver and test with query param
+    const resolver = apiKeyService.createResolver();
+    const userInfo = await resolver.onRequest({
+      url: new URL(`http://localhost/profile?api_key=${token}`),
+      headers: {},
+    } as any);
+
+    expect(userInfo).not.toBeNull();
+    expect(userInfo?.id).toBe(user.id);
+    expect(userInfo?.roles).toEqual(["user"]);
+  });
+
+  it("should resolve user from API key in Bearer header via resolver", async ({
+    expect,
+  }) => {
+    const { sessionService, apiKeyService } = await setup();
+
+    // Create a user
+    const user = await sessionService.users().create({
+      username: "testuser",
+      email: "test@example.com",
+      roles: ["user"],
+    });
+
+    // Create an API key
+    const { token } = await apiKeyService.create({
+      userId: user.id,
+      name: "My API Key",
+      roles: ["user"],
+    });
+
+    // Create resolver and test with Bearer header
+    const resolver = apiKeyService.createResolver();
+    const userInfo = await resolver.onRequest({
+      url: new URL("http://localhost/profile"),
+      headers: { authorization: `Bearer ${token}` },
+    } as any);
+
+    expect(userInfo).not.toBeNull();
+    expect(userInfo?.id).toBe(user.id);
+    expect(userInfo?.roles).toEqual(["user"]);
+  });
+
+  it("should not resolve JWT tokens as API keys", async ({ expect }) => {
+    const { apiKeyService } = await setup();
+
+    // Create resolver and test with a JWT-like token (contains dots)
+    const resolver = apiKeyService.createResolver();
+    const userInfo = await resolver.onRequest({
+      url: new URL("http://localhost/profile"),
+      headers: {
+        authorization:
+          "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.test.signature",
+      },
+    } as any);
+
+    // Should return null because JWT tokens should be handled by JWT resolver
+    expect(userInfo).toBeNull();
+  });
+
+  it("should reject revoked API key", async ({ expect }) => {
+    const { sessionService, apiKeyService } = await setup();
+
+    // Create a user
+    const user = await sessionService.users().create({
+      username: "testuser",
+      email: "test@example.com",
+      roles: ["user"],
+    });
+
+    // Create an API key
+    const { apiKey, token } = await apiKeyService.create({
+      userId: user.id,
+      name: "My API Key",
+      roles: ["user"],
+    });
+
+    // Verify key is valid
+    const beforeRevoke = await apiKeyService.validate(token);
+    expect(beforeRevoke).not.toBeNull();
+
+    // Revoke the key
+    await apiKeyService.revoke(apiKey.id, user.id);
+
+    // Verify key is now invalid
+    const afterRevoke = await apiKeyService.validate(token);
+    expect(afterRevoke).toBeNull();
+  });
+
+  it("should reject expired API key", async ({ expect }) => {
+    const { sessionService, apiKeyService, dateTimeProvider } = await setup();
+
+    // Create a user
+    const user = await sessionService.users().create({
+      username: "testuser",
+      email: "test@example.com",
+      roles: ["user"],
+    });
+
+    // Create an API key that expires in 1 hour
+    const expiresAt = dateTimeProvider.now().add(1, "hour").toDate();
+    const { token } = await apiKeyService.create({
+      userId: user.id,
+      name: "Expiring Key",
+      roles: ["user"],
+      expiresAt,
+    });
+
+    // Verify key is valid
+    const beforeExpiry = await apiKeyService.validate(token);
+    expect(beforeExpiry).not.toBeNull();
+
+    // Travel forward in time past expiry
+    dateTimeProvider.travel(2, "hours");
+
+    // Verify key is now invalid
+    const afterExpiry = await apiKeyService.validate(token);
+    expect(afterExpiry).toBeNull();
+  });
+
+  it("should reject invalid API key", async ({ expect }) => {
+    await setup();
+
+    const { apiKeyService } = await setup();
+
+    // Try to validate an invalid token
+    const result = await apiKeyService.validate("ak_invalid_token_12345678");
+    expect(result).toBeNull();
+  });
+
+  it("should list user's API keys", async ({ expect }) => {
+    const { sessionService, apiKeyService } = await setup();
+
+    // Create a user
+    const user = await sessionService.users().create({
+      username: "testuser",
+      email: "test@example.com",
+      roles: ["user"],
+    });
+
+    // Create multiple API keys
+    await apiKeyService.create({
+      userId: user.id,
+      name: "Key 1",
+      roles: ["user"],
+    });
+    await apiKeyService.create({
+      userId: user.id,
+      name: "Key 2",
+      roles: ["user"],
+    });
+
+    // List keys
+    const keys = await apiKeyService.list(user.id);
+
+    expect(keys).toHaveLength(2);
+    expect(keys.map((k) => k.name).sort()).toEqual(["Key 1", "Key 2"]);
+  });
+
+  it("should not allow revoking another user's API key", async ({ expect }) => {
+    const { sessionService, apiKeyService } = await setup();
+
+    // Create two users
+    const user1 = await sessionService.users().create({
+      username: "user1",
+      email: "user1@example.com",
+      roles: ["user"],
+    });
+    const user2 = await sessionService.users().create({
+      username: "user2",
+      email: "user2@example.com",
+      roles: ["user"],
+    });
+
+    // Create an API key for user1
+    const { apiKey } = await apiKeyService.create({
+      userId: user1.id,
+      name: "User1 Key",
+      roles: ["user"],
+    });
+
+    // Try to revoke user1's key as user2
+    await expect(
+      apiKeyService.revoke(apiKey.id, user2.id),
+    ).rejects.toThrowError(ForbiddenError);
+  });
+
+  it("should create API key with description", async ({ expect }) => {
+    const { sessionService, apiKeyService } = await setup();
+
+    // Create a user
+    const user = await sessionService.users().create({
+      username: "testuser",
+      email: "test@example.com",
+      roles: ["user", "admin"],
+    });
+
+    // Create API key with description
+    const { apiKey, token } = await apiKeyService.create({
+      userId: user.id,
+      name: "My Key",
+      description: "Used for CI/CD pipeline",
+      roles: ["user", "admin"],
+    });
+
+    expect(apiKey.name).toBe("My Key");
+    expect(apiKey.description).toBe("Used for CI/CD pipeline");
+    expect(apiKey.roles).toEqual(["user", "admin"]);
+    expect(token).toMatch(/^ak_/);
+
+    // Validate works
+    const userInfo = await apiKeyService.validate(token);
+    expect(userInfo?.id).toBe(user.id);
+    expect(userInfo?.roles).toEqual(["user", "admin"]);
+  });
+
+  it("should support API key with admin role", async ({ expect }) => {
+    const { sessionService, apiKeyService } = await setup();
+
+    // Create an admin user
+    const adminUser = await sessionService.users().create({
+      username: "admin",
+      email: "admin@example.com",
+      roles: ["admin"],
+    });
+
+    // Create an API key with admin role
+    const { token } = await apiKeyService.create({
+      userId: adminUser.id,
+      name: "Admin API Key",
+      roles: ["admin"],
+    });
+
+    // Validate API key returns admin role
+    const userInfo = await apiKeyService.validate(token);
+    expect(userInfo).not.toBeNull();
+    expect(userInfo?.id).toBe(adminUser.id);
+    expect(userInfo?.roles).toEqual(["admin"]);
+  });
+
+  it("should not revoke already revoked keys twice", async ({ expect }) => {
+    const { sessionService, apiKeyService } = await setup();
+
+    // Create a user
+    const user = await sessionService.users().create({
+      username: "testuser",
+      email: "test@example.com",
+      roles: ["user"],
+    });
+
+    // Create and revoke an API key
+    const { apiKey, token } = await apiKeyService.create({
+      userId: user.id,
+      name: "My Key",
+      roles: ["user"],
+    });
+
+    await apiKeyService.revoke(apiKey.id, user.id);
+
+    // Verify key is revoked
+    const result = await apiKeyService.validate(token);
+    expect(result).toBeNull();
+
+    // Admin revoke should not fail on already revoked key
+    await apiKeyService.revokeByAdmin(apiKey.id);
+  });
+
+  it("should create API key with custom prefix", async ({ expect }) => {
+    const { sessionService, apiKeyService } = await setup();
+
+    // Create a user
+    const user = await sessionService.users().create({
+      username: "testuser",
+      email: "test@example.com",
+      roles: ["user"],
+    });
+
+    // Create an API key with custom prefix
+    const { token } = await apiKeyService.create({
+      userId: user.id,
+      name: "Custom Key",
+      roles: ["user"],
+      prefix: "prod",
+    });
+
+    expect(token).toMatch(/^prod_/);
+
+    // Should still validate
+    const userInfo = await apiKeyService.validate(token);
+    expect(userInfo).not.toBeNull();
+  });
+});

package/src/api/users/index.ts

@@ -57,10 +57,21 @@ export * from "./services/UserService.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * Provides user management API endpoints for Alepha applications.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | epic | stable |
  *
- * This module includes user CRUD operations, authentication endpoints,
- * password reset functionality, and user profile management capabilities.
+ * Complete user management with multi-realm support for multi-tenant applications.
+ *
+ * **Features:**
+ * - User registration, login, and profile management
+ * - Password reset workflows
+ * - Email verification
+ * - Session management with multiple devices
+ * - Identity management (social logins, SSO)
+ * - Multi-realm support for tenant isolation
+ * - Credential management
+ * - Entities: `users`, `identities`, `sessions`
  *
  * @module alepha.api.users
  */

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

@@ -1,11 +1,14 @@
 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 type { Repository } from "alepha/orm";
 import {
   $issuer,
   type IssuerPrimitive,
   type IssuerPrimitiveOptions,
+  type IssuerResolver,
   SecurityProvider,
 } from "alepha/security";
 import {
@@ -65,13 +68,29 @@ export const $realm = (options: RealmOptions = {}): RealmPrimitive => {
 
   const realmRegistration = realmProvider.register(name, options);
 
+  // For now, all modules are enabled
   alepha.with(AlephaApiFiles);
   alepha.with(AlephaApiAudits);
+  alepha.with(AlephaApiJobs);
+
+  // 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)
+  const customResolvers: IssuerResolver[] = [
+    ...(options.issuer?.resolvers ?? []),
+  ];
+
+  // Enable API key authentication - must be added to customResolvers before $issuer() call
+  if (options.apiKeys) {
+    alepha.with(AlephaApiKeys);
+    const apiKeyService = alepha.inject(ApiKeyService);
+    customResolvers.push(apiKeyService.createResolver());
+  }
 
   const realm: RealmPrimitive = $issuer({
     ...options.issuer,
     name,
     secret: options.secret ?? securityProvider.secretKey,
+    resolvers: customResolvers,
     roles: options.issuer?.roles ?? [
       {
         name: "admin",
@@ -189,9 +208,18 @@ export interface RealmOptions {
     github?: true;
   };
 
-  modules?: {
-    files?: boolean;
-    audits?: boolean;
-    jobs?: boolean;
-  };
+  /**
+   * 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
+   *
+   * API keys can be passed via:
+   * - Query parameter: `?api_key=ak_xxx`
+   * - Bearer header: `Authorization: Bearer ak_xxx`
+   */
+  apiKeys?: boolean;
 }

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

@@ -1,4 +1,4 @@
-import { $hook, $inject, Alepha, AlephaError } from "alepha";
+import { $inject, Alepha, AlephaError } from "alepha";
 import { $bucket } from "alepha/bucket";
 import { $repository, type Repository } from "alepha/orm";
 import {
@@ -36,17 +36,6 @@ export class RealmProvider {
     mimeTypes: ["image/jpeg", "image/png", "image/gif", "image/webp"],
   });
 
-  protected readonly onConfigure = $hook({
-    on: "configure",
-    handler: () => {
-      this.alepha.store.set("alepha.server.security.system.user", {
-        id: "00000000-0000-0000-0000-000000000000",
-        name: "system",
-        roles: ["admin"], // TODO: use realm config
-      });
-    },
-  });
-
   public register(realmName: string, realmOptions: RealmOptions = {}) {
     this.realms.set(realmName, {
       name: realmName,

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

@@ -3,7 +3,6 @@ import { $inject, Alepha } from "alepha";
 import { AuditService } from "alepha/api/audits";
 import type { FileController } from "alepha/api/files";
 import { DateTimeProvider } from "alepha/datetime";
-import { FileSystemProvider } from "alepha/file";
 import { $logger } from "alepha/logger";
 import {
   CryptoProvider,
@@ -13,6 +12,7 @@ import {
 import { type ServerRequest, UnauthorizedError } from "alepha/server";
 import type { OAuth2Profile } from "alepha/server/auth";
 import { $client } from "alepha/server/links";
+import { FileSystemProvider } from "alepha/system";
 import type { UserEntity } from "../entities/users.ts";
 import { RealmProvider } from "../providers/RealmProvider.ts";
 

package/src/api/verifications/controllers/VerificationController.ts

@@ -15,6 +15,7 @@ export class VerificationController {
     path: `${this.url}/:type`,
     group: this.group,
     method: "POST",
+    secure: false,
     schema: {
       params: t.object({
         type: verificationTypeEnumSchema,
@@ -36,6 +37,7 @@ export class VerificationController {
     path: `${this.url}/:type/validate`,
     group: this.group,
     method: "POST",
+    secure: false,
     schema: {
       params: t.object({
         type: verificationTypeEnumSchema,

package/src/api/verifications/index.ts

@@ -18,11 +18,17 @@ export * from "./services/VerificationService.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * Provides email/phone verification management API endpoints for Alepha applications.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | standard | stable |
  *
- * This module includes verification code generation, validation,
- * and related functionalities. Notifications are handled by the consuming module
- * (e.g., api-users) for context-specific messaging.
+ * Email and phone verification workflows.
+ *
+ * **Features:**
+ * - Verification token generation
+ * - Verification code sending
+ * - Verification completion tracking
+ * - Resend functionality
  *
  * @module alepha.api.verifications
  */

package/src/batch/index.ts

@@ -10,45 +10,18 @@ export * from "./providers/BatchProvider.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * This module allows you to group multiple asynchronous operations into a single "batch," which is then processed together.
- * This is an essential pattern for improving performance, reducing I/O, and interacting efficiently with rate-limited APIs or databases.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | standard | stable |
  *
- * ```ts
- * import { Alepha, $hook, run, t } from "alepha";
- * import { $batch } from "alepha/batch";
+ * Batch accumulation and processing.
  *
- * class LoggingService {
- *   // define the batch processor
- *   logBatch = $batch({
- *     schema: t.text(),
- *     maxSize: 10,
- *     maxDuration: [5, "seconds"],
- *     handler: async (items) => {
- *       console.log(`[BATCH LOG] Processing ${items.length} events:`, items);
- *     },
- *   });
+ * **Features:**
+ * - Batch accumulator with handler
+ * - Configurable batch size
+ * - Time-based triggers
+ * - Status tracking
  *
- *   // example of how to use it
- *   onReady = $hook({
- *     on: "ready",
- *     handler: async () => {
- *       // push() returns an ID immediately
- *       const id1 = await this.logBatch.push("Application started.");
- *       const id2 = await this.logBatch.push("User authenticated.");
- *
- *       // optionally wait for processing to complete
- *       await this.logBatch.wait(id1);
- *
- *       // or check the status
- *       const status = this.logBatch.status(id2);
- *       console.log(status?.status); // "pending" | "processing" | "completed" | "failed"
- *     },
- *   });
- * }
- * ```
- *
- * @see {@link $batch}
- * @see {@link BatchProvider}
  * @module alepha.batch
  */
 export const AlephaBatch = $module({

package/src/batch/primitives/$batch.ts

@@ -159,14 +159,6 @@ export class BatchPrimitive<
       await this.batchProvider.markReady(this.context);
     },
   });
-
-  protected readonly dispose = $hook({
-    on: "stop",
-    priority: "first",
-    handler: async () => {
-      await this.batchProvider.shutdown(this.context);
-    },
-  });
 }
 
 $batch[KIND] = BatchPrimitive;