alepha 0.15.1 → 0.15.3

package/src/api/files/index.ts

@@ -49,10 +49,17 @@ declare module "alepha/bucket" {
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * Provides file management API endpoints for Alepha applications.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | standard | stable |
  *
- * This module includes file upload, download, storage management,
- * and file metadata operations.
+ * File management endpoints.
+ *
+ * **Features:**
+ * - Upload/download endpoints
+ * - File metadata storage
+ * - TTL-based expiration
+ * - Storage statistics
  *
  * @module alepha.api.files
  */

package/src/api/files/jobs/FileJobs.spec.ts

@@ -1,6 +1,6 @@
 import { Alepha } from "alepha";
 import { DateTimeProvider } from "alepha/datetime";
-import { FileSystemProvider } from "alepha/file";
+import { FileSystemProvider } from "alepha/system";
 import { describe, expect, it } from "vitest";
 import { FileJobs, FileService } from "../index.ts";
 

package/src/api/files/services/FileService.spec.ts

@@ -6,7 +6,7 @@ import {
   LocalFileStorageProvider,
   MemoryFileStorageProvider,
 } from "alepha/bucket";
-import { FileSystemProvider } from "alepha/file";
+import { FileSystemProvider } from "alepha/system";
 import { describe, expect, it } from "vitest";
 import { AlephaApiFiles, FileController } from "../index.ts";
 

package/src/api/jobs/index.ts

@@ -17,10 +17,17 @@ export * from "./services/JobService.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * Provides job management API endpoints for Alepha applications.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | standard | stable |
  *
- * This module includes job queue operations, job status monitoring,
- * and background task management capabilities.
+ * Job execution monitoring.
+ *
+ * **Features:**
+ * - Job definitions for tracking
+ * - Job status tracking
+ * - Execution history
+ * - Retry management
  *
  * @module alepha.api.jobs
  */

package/src/api/keys/controllers/AdminApiKeyController.ts

@@ -0,0 +1,75 @@
+import { $inject, t } from "alepha";
+import { $action, okSchema } from "alepha/server";
+import { adminApiKeyQuerySchema } from "../schemas/adminApiKeyQuerySchema.ts";
+import { adminApiKeyResourceSchema } from "../schemas/adminApiKeyResourceSchema.ts";
+import { ApiKeyService } from "../services/ApiKeyService.ts";
+
+/**
+ * REST API controller for admin API key management.
+ * Admins can list, view, and revoke any API key.
+ */
+export class AdminApiKeyController {
+  protected readonly url = "/admin/api-keys";
+  protected readonly group = "admin:api-keys";
+  protected readonly apiKeyService = $inject(ApiKeyService);
+
+  /**
+   * Find all API keys with optional filtering.
+   */
+  public readonly findApiKeys = $action({
+    path: this.url,
+    group: this.group,
+    secure: true,
+    description: "Find API keys with pagination and filtering",
+    schema: {
+      query: adminApiKeyQuerySchema,
+      response: t.page(adminApiKeyResourceSchema),
+    },
+    handler: ({ query }) => {
+      const { userId, includeRevoked, ...pagination } = query;
+      return this.apiKeyService.findAll({
+        userId,
+        includeRevoked,
+        ...pagination,
+      });
+    },
+  });
+
+  /**
+   * Get an API key by ID.
+   */
+  public readonly getApiKey = $action({
+    path: `${this.url}/:id`,
+    group: this.group,
+    secure: true,
+    description: "Get an API key by ID",
+    schema: {
+      params: t.object({
+        id: t.uuid(),
+      }),
+      response: adminApiKeyResourceSchema,
+    },
+    handler: ({ params }) => this.apiKeyService.getById(params.id),
+  });
+
+  /**
+   * Revoke any API key.
+   */
+  public readonly revokeApiKey = $action({
+    method: "DELETE",
+    path: `${this.url}/:id`,
+    group: this.group,
+    secure: true,
+    description: "Revoke an API key",
+    schema: {
+      params: t.object({
+        id: t.uuid(),
+      }),
+      response: okSchema,
+    },
+    handler: async ({ params }) => {
+      await this.apiKeyService.revokeByAdmin(params.id);
+      return { ok: true, id: params.id };
+    },
+  });
+}

package/src/api/keys/controllers/ApiKeyController.ts

@@ -0,0 +1,103 @@
+import { $inject } from "alepha";
+import { $action } from "alepha/server";
+import { createApiKeyBodySchema } from "../schemas/createApiKeyBodySchema.ts";
+import { createApiKeyResponseSchema } from "../schemas/createApiKeyResponseSchema.ts";
+import { listApiKeyResponseSchema } from "../schemas/listApiKeyResponseSchema.ts";
+import { revokeApiKeyParamsSchema } from "../schemas/revokeApiKeyParamsSchema.ts";
+import { revokeApiKeyResponseSchema } from "../schemas/revokeApiKeyResponseSchema.ts";
+import { ApiKeyService } from "../services/ApiKeyService.ts";
+
+/**
+ * REST API controller for user's own API key management.
+ * Users can create, list, and revoke their own API keys.
+ */
+export class ApiKeyController {
+  protected readonly url = "/api-keys";
+  protected readonly group = "api-keys";
+  protected readonly apiKeyService = $inject(ApiKeyService);
+
+  /**
+   * Create a new API key for the authenticated user.
+   * The token is only returned once upon creation.
+   */
+  public readonly createApiKey = $action({
+    method: "POST",
+    path: this.url,
+    group: this.group,
+    description: "Create a new API key",
+    secure: true,
+    schema: {
+      body: createApiKeyBodySchema,
+      response: createApiKeyResponseSchema,
+    },
+    handler: async (request) => {
+      const { apiKey, token } = await this.apiKeyService.create({
+        userId: request.user.id,
+        name: request.body.name,
+        description: request.body.description,
+        roles: request.user.roles ?? [],
+        expiresAt: request.body.expiresAt
+          ? new Date(request.body.expiresAt)
+          : undefined,
+      });
+
+      return {
+        id: apiKey.id,
+        name: apiKey.name,
+        token,
+        tokenSuffix: apiKey.tokenSuffix,
+        roles: apiKey.roles,
+        createdAt: apiKey.createdAt,
+        expiresAt: apiKey.expiresAt,
+      };
+    },
+  });
+
+  /**
+   * List all active API keys for the authenticated user.
+   * Does not return the actual tokens.
+   */
+  public readonly listApiKeys = $action({
+    path: this.url,
+    group: this.group,
+    description: "List your API keys",
+    secure: true,
+    schema: {
+      response: listApiKeyResponseSchema,
+    },
+    handler: async (request) => {
+      const apiKeys = await this.apiKeyService.list(request.user.id);
+
+      return apiKeys.map((apiKey) => ({
+        id: apiKey.id,
+        name: apiKey.name,
+        tokenPrefix: apiKey.tokenPrefix,
+        tokenSuffix: apiKey.tokenSuffix,
+        roles: apiKey.roles,
+        createdAt: apiKey.createdAt,
+        lastUsedAt: apiKey.lastUsedAt,
+        expiresAt: apiKey.expiresAt,
+        usageCount: apiKey.usageCount,
+      }));
+    },
+  });
+
+  /**
+   * Revoke an API key. Only the owner can revoke their own keys.
+   */
+  public readonly revokeApiKey = $action({
+    method: "DELETE",
+    path: `${this.url}/:id`,
+    group: this.group,
+    description: "Revoke an API key",
+    secure: true,
+    schema: {
+      params: revokeApiKeyParamsSchema,
+      response: revokeApiKeyResponseSchema,
+    },
+    handler: async (request) => {
+      await this.apiKeyService.revoke(request.params.id, request.user.id);
+      return { ok: true };
+    },
+  });
+}

package/src/api/keys/entities/apiKeyEntity.ts

@@ -0,0 +1,41 @@
+import { type Static, t } from "alepha";
+import { $entity, db } from "alepha/orm";
+
+export const apiKeyEntity = $entity({
+  name: "api_keys",
+  schema: t.object({
+    id: db.primaryKey(t.uuid()),
+    createdAt: db.createdAt(),
+    updatedAt: db.updatedAt(),
+
+    // Owner
+    userId: t.uuid(),
+
+    // Key metadata
+    name: t.text({ maxLength: 100 }),
+    description: t.optional(t.text({ maxLength: 500 })),
+
+    // Token (hashed) - internal, not user input
+    tokenHash: t.string({ maxLength: 256 }),
+    tokenPrefix: t.string({ maxLength: 10 }),
+    tokenSuffix: t.string({ maxLength: 8 }),
+
+    // Roles (snapshot from user at creation)
+    roles: db.default(t.array(t.string()), []),
+
+    // Tracking
+    lastUsedAt: t.optional(t.datetime()),
+    lastUsedIp: t.optional(t.string({ maxLength: 45 })),
+    usageCount: db.default(t.integer(), 0),
+
+    // Lifecycle
+    expiresAt: t.optional(t.datetime()),
+    revokedAt: t.optional(t.datetime()),
+  }),
+  indexes: [
+    { columns: ["userId", "name"], unique: true },
+    { columns: ["tokenHash"], unique: true },
+  ],
+});
+
+export type ApiKeyEntity = Static<typeof apiKeyEntity.schema>;

package/src/api/keys/index.ts

@@ -0,0 +1,49 @@
+import { $module } from "alepha";
+import { AdminApiKeyController } from "./controllers/AdminApiKeyController.ts";
+import { ApiKeyController } from "./controllers/ApiKeyController.ts";
+import { ApiKeyService } from "./services/ApiKeyService.ts";
+
+export * from "./controllers/AdminApiKeyController.ts";
+export * from "./controllers/ApiKeyController.ts";
+export * from "./entities/apiKeyEntity.ts";
+export * from "./schemas/adminApiKeyQuerySchema.ts";
+export * from "./schemas/adminApiKeyResourceSchema.ts";
+export * from "./schemas/createApiKeyBodySchema.ts";
+export * from "./schemas/createApiKeyResponseSchema.ts";
+export * from "./schemas/listApiKeyResponseSchema.ts";
+export * from "./schemas/revokeApiKeyParamsSchema.ts";
+export * from "./schemas/revokeApiKeyResponseSchema.ts";
+export * from "./services/ApiKeyService.ts";
+
+/**
+ * | type | quality | stability |
+ * |------|---------|--------------|
+ * | backend | good | experimental |
+ *
+ * API key management module for programmatic access.
+ *
+ * **Features:**
+ * - Create API keys with role snapshots
+ * - List and revoke API keys
+ * - 15-minute validation caching
+ * - Query param (?api_key=) and Bearer header support
+ *
+ * **Integration:**
+ * To enable API key authentication for an issuer, register the resolver:
+ *
+ * ```ts
+ * class MyApp {
+ *   apiKeyService = $inject(ApiKeyService);
+ *   issuer = $issuer({
+ *     secret: env.APP_SECRET,
+ *     resolvers: [this.apiKeyService.createResolver()],
+ *   });
+ * }
+ * ```
+ *
+ * @module alepha.api.keys
+ */
+export const AlephaApiKeys = $module({
+  name: "alepha.api.keys",
+  services: [ApiKeyService, ApiKeyController, AdminApiKeyController],
+});

package/src/api/keys/schemas/adminApiKeyQuerySchema.ts

@@ -0,0 +1,7 @@
+import { t } from "alepha";
+import { pageQuerySchema } from "alepha/orm";
+
+export const adminApiKeyQuerySchema = t.extend(pageQuerySchema, {
+  userId: t.optional(t.uuid()),
+  includeRevoked: t.optional(t.boolean()),
+});

package/src/api/keys/schemas/adminApiKeyResourceSchema.ts

@@ -0,0 +1,17 @@
+import { t } from "alepha";
+
+export const adminApiKeyResourceSchema = t.object({
+  id: t.uuid(),
+  userId: t.uuid(),
+  name: t.string(),
+  description: t.optional(t.string()),
+  tokenPrefix: t.string(),
+  tokenSuffix: t.string(),
+  roles: t.array(t.string()),
+  createdAt: t.datetime(),
+  lastUsedAt: t.optional(t.datetime()),
+  lastUsedIp: t.optional(t.string()),
+  expiresAt: t.optional(t.datetime()),
+  revokedAt: t.optional(t.datetime()),
+  usageCount: t.integer(),
+});

package/src/api/keys/schemas/createApiKeyBodySchema.ts

@@ -0,0 +1,7 @@
+import { t } from "alepha";
+
+export const createApiKeyBodySchema = t.object({
+  name: t.text({ minLength: 1, maxLength: 100 }),
+  description: t.optional(t.text({ maxLength: 500 })),
+  expiresAt: t.optional(t.datetime()),
+});

package/src/api/keys/schemas/createApiKeyResponseSchema.ts

@@ -0,0 +1,11 @@
+import { t } from "alepha";
+
+export const createApiKeyResponseSchema = t.object({
+  id: t.uuid(),
+  name: t.string(),
+  token: t.string(),
+  tokenSuffix: t.string(),
+  roles: t.array(t.string()),
+  createdAt: t.datetime(),
+  expiresAt: t.optional(t.datetime()),
+});

package/src/api/keys/schemas/listApiKeyResponseSchema.ts

@@ -0,0 +1,15 @@
+import { t } from "alepha";
+
+export const listApiKeyItemSchema = t.object({
+  id: t.uuid(),
+  name: t.string(),
+  tokenPrefix: t.string(),
+  tokenSuffix: t.string(),
+  roles: t.array(t.string()),
+  createdAt: t.datetime(),
+  lastUsedAt: t.optional(t.datetime()),
+  expiresAt: t.optional(t.datetime()),
+  usageCount: t.integer(),
+});
+
+export const listApiKeyResponseSchema = t.array(listApiKeyItemSchema);

package/src/api/keys/schemas/revokeApiKeyParamsSchema.ts

@@ -0,0 +1,5 @@
+import { t } from "alepha";
+
+export const revokeApiKeyParamsSchema = t.object({
+  id: t.uuid(),
+});

package/src/api/keys/schemas/revokeApiKeyResponseSchema.ts

@@ -0,0 +1,5 @@
+import { t } from "alepha";
+
+export const revokeApiKeyResponseSchema = t.object({
+  ok: t.boolean(),
+});