alepha 0.15.0 → 0.15.2

package/src/api/keys/services/ApiKeyService.ts

@@ -0,0 +1,306 @@
+import { createHash, randomBytes } from "node:crypto";
+import { $inject, Alepha } from "alepha";
+import { $cache } from "alepha/cache";
+import { DateTimeProvider } from "alepha/datetime";
+import { $logger } from "alepha/logger";
+import { $repository, sql } from "alepha/orm";
+import type { IssuerResolver, UserInfo } from "alepha/security";
+import {
+  ForbiddenError,
+  NotFoundError,
+  type ServerRequest,
+} from "alepha/server";
+import { type ApiKeyEntity, apiKeyEntity } from "../entities/apiKeyEntity.ts";
+
+export class ApiKeyService {
+  protected readonly alepha = $inject(Alepha);
+  protected readonly dateTimeProvider = $inject(DateTimeProvider);
+  protected readonly log = $logger();
+  protected readonly repo = $repository(apiKeyEntity);
+
+  /**
+   * Cache validated API keys for 15 minutes.
+   */
+  protected readonly validationCache = $cache<ApiKeyEntity | null, [string]>({
+    name: "api-key-validation",
+    ttl: [15, "minutes"],
+  });
+
+  // -------------------------------------------------------------------------
+  // Resolver
+  // -------------------------------------------------------------------------
+
+  /**
+   * Create an issuer resolver for API key authentication.
+   * Lower priority means it runs before JWT resolver.
+   *
+   * @param options.priority - Priority of this resolver (default: 50, JWT is 100)
+   * @param options.prefix - API key prefix to match in Bearer header (default: "ak")
+   */
+  public createResolver(
+    options: { priority?: number; prefix?: string } = {},
+  ): IssuerResolver {
+    const { priority = 50, prefix = "ak" } = options;
+    const prefixPattern = `${prefix}_`;
+
+    return {
+      priority,
+      onRequest: async (req: ServerRequest) => {
+        // Try query param first
+        const url = typeof req.url === "string" ? new URL(req.url) : req.url;
+        let token = url.searchParams.get("api_key");
+
+        // Try Bearer header - only if token starts with expected prefix
+        if (!token) {
+          const auth = req.headers.authorization;
+          if (auth?.startsWith("Bearer ")) {
+            const bearerToken = auth.slice(7);
+            if (bearerToken.startsWith(prefixPattern)) {
+              token = bearerToken;
+            }
+          }
+        }
+
+        if (!token) {
+          return null;
+        }
+
+        return this.validate(token);
+      },
+    };
+  }
+
+  // -------------------------------------------------------------------------
+  // CRUD
+  // -------------------------------------------------------------------------
+
+  /**
+   * Create a new API key for a user.
+   * Returns both the API key entity and the plain token (which is only available once).
+   */
+  public async create(options: {
+    userId: string;
+    name: string;
+    roles: string[];
+    description?: string;
+    expiresAt?: Date;
+    prefix?: string;
+  }): Promise<{ apiKey: ApiKeyEntity; token: string }> {
+    const prefix = options.prefix ?? "ak";
+    const random = randomBytes(24).toString("base64url");
+    const token = `${prefix}_${random}`;
+    const hash = this.hashToken(token);
+    const suffix = token.slice(-8);
+
+    const apiKey = await this.repo.create({
+      userId: options.userId,
+      name: options.name,
+      description: options.description,
+      tokenHash: hash,
+      tokenPrefix: prefix,
+      tokenSuffix: suffix,
+      roles: options.roles,
+      expiresAt: options.expiresAt?.toISOString(),
+    });
+
+    this.log.info("API key created", {
+      apiKeyId: apiKey.id,
+      userId: options.userId,
+      name: options.name,
+    });
+
+    return { apiKey, token };
+  }
+
+  /**
+   * List all non-revoked API keys for a user.
+   */
+  public async list(userId: string): Promise<ApiKeyEntity[]> {
+    return this.repo.findMany({
+      where: {
+        userId: { eq: userId },
+        revokedAt: { isNull: true },
+      },
+      orderBy: { column: "createdAt", direction: "desc" },
+    });
+  }
+
+  // -------------------------------------------------------------------------
+  // Admin Operations
+  // -------------------------------------------------------------------------
+
+  /**
+   * Find all API keys with optional filtering (admin only).
+   */
+  public async findAll(query: {
+    userId?: string;
+    includeRevoked?: boolean;
+    page?: number;
+    size?: number;
+    sort?: string;
+  }) {
+    query.sort ??= "-createdAt";
+
+    const where = this.repo.createQueryWhere();
+
+    if (query.userId) {
+      where.userId = { eq: query.userId };
+    }
+
+    if (!query.includeRevoked) {
+      where.revokedAt = { isNull: true };
+    }
+
+    return this.repo.paginate(query, { where }, { count: true });
+  }
+
+  /**
+   * Get an API key by ID (admin only).
+   */
+  public async getById(id: string): Promise<ApiKeyEntity> {
+    const apiKey = await this.repo.findById(id).catch(() => null);
+
+    if (!apiKey) {
+      throw new NotFoundError("API key not found");
+    }
+
+    return apiKey;
+  }
+
+  /**
+   * Revoke any API key (admin only).
+   */
+  public async revokeByAdmin(id: string): Promise<void> {
+    const apiKey = await this.repo.findById(id).catch(() => null);
+
+    if (!apiKey) {
+      throw new NotFoundError("API key not found");
+    }
+
+    if (apiKey.revokedAt) {
+      return; // Already revoked
+    }
+
+    // Invalidate cache
+    await this.validationCache.invalidate(apiKey.tokenHash);
+
+    await this.repo.updateById(id, {
+      revokedAt: this.dateTimeProvider.now().toISOString(),
+    });
+
+    this.log.info("API key revoked by admin", {
+      apiKeyId: id,
+      userId: apiKey.userId,
+    });
+  }
+
+  // -------------------------------------------------------------------------
+  // User Operations
+  // -------------------------------------------------------------------------
+
+  /**
+   * Revoke an API key. Only the owner can revoke their own keys.
+   */
+  public async revoke(id: string, userId: string): Promise<void> {
+    const apiKey = await this.repo.findById(id).catch(() => null);
+
+    if (!apiKey) {
+      throw new NotFoundError("API key not found");
+    }
+
+    if (apiKey.userId !== userId) {
+      throw new ForbiddenError("Not your API key");
+    }
+
+    await this.validationCache.invalidate(apiKey.tokenHash);
+
+    await this.repo.updateById(id, {
+      revokedAt: this.dateTimeProvider.now().toISOString(),
+    });
+
+    this.log.info("API key revoked", {
+      apiKeyId: id,
+      userId,
+    });
+  }
+
+  // -------------------------------------------------------------------------
+  // Validation
+  // -------------------------------------------------------------------------
+
+  /**
+   * Validate an API key token and return user info if valid.
+   */
+  public async validate(token: string): Promise<UserInfo | null> {
+    // Quick check for API key format
+    if (!token.includes("_")) {
+      return null;
+    }
+
+    const hash = this.hashToken(token);
+
+    // Try cache first
+    let apiKey = await this.validationCache.get(hash);
+
+    // If not in cache, look up in database
+    if (apiKey === undefined) {
+      apiKey = await this.repo
+        .findOne({
+          where: { tokenHash: { eq: hash } },
+        })
+        .catch(() => null);
+
+      // Store in cache (even if null, to prevent repeated lookups)
+      if (apiKey) {
+        await this.validationCache.set(hash, apiKey);
+      }
+    }
+
+    if (!apiKey) {
+      return null;
+    }
+
+    // Check revocation
+    if (apiKey.revokedAt) {
+      return null;
+    }
+
+    // Check expiration
+    if (
+      apiKey.expiresAt &&
+      this.dateTimeProvider.now().isAfter(apiKey.expiresAt)
+    ) {
+      return null;
+    }
+
+    // Update usage stats (fire and forget)
+    this.updateUsage(apiKey.id).catch((error) => {
+      this.log.warn("Failed to update API key usage", { error });
+    });
+
+    return {
+      id: apiKey.userId,
+      roles: apiKey.roles,
+    };
+  }
+
+  /**
+   * Update usage statistics for an API key.
+   */
+  protected async updateUsage(id: string): Promise<void> {
+    const request = this.alepha.context.get<ServerRequest>("request");
+
+    await this.repo.updateById(id, {
+      lastUsedAt: this.dateTimeProvider.now().toISOString(),
+      lastUsedIp: request?.ip,
+      usageCount: sql`${this.repo.table.usageCount} + 1`,
+    });
+  }
+
+  /**
+   * Hash a token using SHA-256.
+   */
+  protected hashToken(token: string): string {
+    return createHash("sha256").update(token).digest("hex");
+  }
+}

package/src/api/logs/TODO.md

@@ -0,0 +1,52 @@
+
+
+
+
+2 modules:
+
+AlephaApiLogs - Module for handling logs collected from various sources.
+
+- 1-2 days retention policy for logs. (more can be configured)
+- Independent Sqlite storage for logs with querying capabilities.
+- Output can be sent to Postgres (TimeScaleDB) if big data storage is needed.
+
+AlephaApiLogsClient - Client module for interacting with the AlephaApiLogs module automatically.
+
+- use Alepha micro-services features to collect logs from different services.
+- Keyless Codec, Batching, ...
+
+1 external module: (@alepha/ui)
+
+- UI of current devtools
+
+AlephaApiLogsUI - UI components for displaying and managing logs within the Alepha framework.
+
+--- CLIENT ----
+
+class LogCollectorClient {
+  collector = $remote({
+    url: "http://localhost:5000/",
+  });
+
+  client = $client<LogController>();
+
+  batchLog = $batch({
+    maxDuration: [10, "seconds"],
+    maxItems: 50,
+    handler: (logs: Logs[]) => {
+      return this.client.collect({ body: logs });
+    }
+  })
+
+  onLog = $hook({
+    on: "log",
+    handler: (log) => {
+      if (log.level === "trace") return;
+      return this.batchLog.push(log);
+    }
+  })
+}
+
+const $collector = (opts: {url}) => $context().alepha.with(LogCollectorClient).set(logCollectorOptions, {url})
+
+---- SERVER ----

package/src/api/notifications/index.ts

@@ -25,12 +25,18 @@ export * from "./services/NotificationService.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * Provides notification management API endpoints for Alepha applications.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | standard | stable |
  *
- * This module includes notification sending, retrieval, status tracking,
- * and user notification preferences management.
+ * User notification management.
  *
- * Requires `AlephaSms` module to be loaded for SMS notifications.
+ * **Features:**
+ * - Notification definitions
+ * - Email/SMS notification sending
+ * - Status tracking
+ * - User preferences
+ * - Queue integration
  *
  * @module alepha.api.notifications
  */

package/src/api/parameters/index.ts

@@ -19,38 +19,17 @@ export * from "./services/ConfigStore.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * Provides versioned configuration management for Alepha applications.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | standard | stable |
  *
- * Features:
- * - Type-safe, versioned configuration with `$config` primitive
- * - Schema validation with auto-migration detection
- * - Scheduled activation (FUTURE, NEXT, CURRENT, EXPIRED statuses)
- * - PostgreSQL persistence with full version history
- * - Cross-instance synchronization via topic
- * - Tree view support via dot-notation naming
- * - REST API for configuration management
- * - Automatic activation scheduler
+ * Application configuration management.
  *
- * @example
- * ```ts
- * import { Alepha } from "alepha";
- * import { AlephaApiParameters } from "alepha/api/parameters";
- *
- * const alepha = Alepha.create();
- * alepha.with(AlephaApiParameters);
- *
- * // Then use $config in your services:
- * class AppConfig {
- *   features = $config({
- *     name: "app.features.flags",
- *     schema: t.object({
- *       enableBeta: t.boolean(),
- *       maxUploadSize: t.number()
- *     }),
- *     default: { enableBeta: false, maxUploadSize: 10485760 }
- *   });
- * }
- * ```
+ * **Features:**
+ * - Versioned configuration definitions
+ * - Scheduled activation (FUTURE, NEXT, CURRENT, EXPIRED)
+ * - Schema validation with migration detection
+ * - Cross-instance sync via pub/sub
  *
  * @module alepha.api.parameters
  */

package/src/api/parameters/primitives/$config.ts

@@ -84,16 +84,24 @@ export class ConfigPrimitive<T extends TObject> extends Primitive<
   protected readonly log = $logger();
   protected readonly store = $inject(ConfigStore);
 
-  /** Internal atom key for state management */
+  /**
+   * Internal atom key for state management.
+   */
   protected atomKey!: string;
 
-  /** Schema hash for migration detection */
+  /**
+   * Schema hash for migration detection.
+   */
   protected schemaHash!: string;
 
-  /** Whether we're currently syncing (to avoid loops) */
+  /**
+   * Whether we're currently syncing (to avoid loops).
+   */
   protected syncing = false;
 
-  /** Whether initial load has completed */
+  /**
+   * Whether initial load has completed.
+   */
   protected loaded = false;
 
   /**

package/src/api/parameters/services/ConfigStore.ts

@@ -36,13 +36,19 @@ export class ConfigStore {
   protected readonly dateTimeProvider = $inject(DateTimeProvider);
   protected readonly repo = $repository(parameters);
 
-  /** Unique identifier for this instance (to avoid self-updates) */
+  /**
+   * Unique identifier for this instance (to avoid self-updates).
+   */
   protected readonly instanceId = crypto.randomUUID();
 
-  /** In-memory cache of registered configs */
+  /**
+   * In-memory cache of registered configs.
+   */
   protected readonly configs = new Map<string, ConfigPrimitive<any>>();
 
-  /** Topic for cross-instance synchronization */
+  /**
+   * Topic for cross-instance synchronization.
+   */
   public readonly syncTopic = $topic({
     name: "config:sync",
     schema: {