@h-ai/audit 0.1.0-alpha5

package/dist/index.js

@@ -0,0 +1,594 @@
+import { z } from 'zod';
+import { core, err, ok } from '@h-ai/core';
+import { validateIdentifiers, BaseReldbCrudRepository, reldb } from '@h-ai/reldb';
+
+// src/audit-config.ts
+var AuditInitConfigSchema = z.object({
+  /** 用户表名，用于 list 查询时 LEFT JOIN 获取用户名 */
+  userTable: z.string().default("hai_iam_users"),
+  /** 用户表主键列名，用于 JOIN 条件 */
+  userIdColumn: z.string().default("id"),
+  /** 用户表用户名列名，用于 SELECT 输出 */
+  userNameColumn: z.string().default("username")
+});
+function toVoid(result) {
+  if (!result.success) {
+    return result;
+  }
+  return ok(void 0);
+}
+function createHelper(logFn) {
+  return {
+    async login(userId, ip, ua) {
+      const result = await logFn({ userId, action: "login", resource: "auth", ipAddress: ip, userAgent: ua });
+      return toVoid(result);
+    },
+    async logout(userId, ip, ua) {
+      const result = await logFn({ userId, action: "logout", resource: "auth", ipAddress: ip, userAgent: ua });
+      return toVoid(result);
+    },
+    async register(userId, ip, ua) {
+      const result = await logFn({ userId, action: "register", resource: "auth", resourceId: userId, ipAddress: ip, userAgent: ua });
+      return toVoid(result);
+    },
+    async passwordResetRequest(email, ip, ua) {
+      const result = await logFn({ action: "password_reset_request", resource: "auth", details: { email }, ipAddress: ip, userAgent: ua });
+      return toVoid(result);
+    },
+    async passwordResetComplete(userId, ip, ua) {
+      const result = await logFn({ userId, action: "password_reset", resource: "auth", ipAddress: ip, userAgent: ua });
+      return toVoid(result);
+    },
+    async crud(input) {
+      const result = await logFn({
+        userId: input.userId,
+        action: input.action,
+        resource: input.resource,
+        resourceId: input.resourceId,
+        details: input.details,
+        ipAddress: input.ip,
+        userAgent: input.ua
+      });
+      return toVoid(result);
+    }
+  };
+}
+
+// messages/en-US.json
+var en_US_default = {
+  $schema: "https://inlang.com/schema/inlang-message-format",
+  audit_notInitialized: "Audit module not initialized, call audit.init() first",
+  audit_initFailed: "Audit module initialization failed: {error}",
+  audit_logFailed: "Failed to record audit log: {error}",
+  audit_queryFailed: "Failed to query audit logs: {error}",
+  audit_cleanupFailed: "Failed to cleanup audit logs: {error}",
+  audit_statsFailed: "Failed to query audit statistics: {error}",
+  audit_configError: "Audit config validation failed: {error}",
+  audit_initInProgress: "Audit module initialization is already in progress",
+  audit_invalidInput: "Invalid audit input for {field}: {reason}"
+};
+
+// messages/zh-CN.json
+var zh_CN_default = {
+  $schema: "https://inlang.com/schema/inlang-message-format",
+  audit_notInitialized: "\u5BA1\u8BA1\u6A21\u5757\u5C1A\u672A\u521D\u59CB\u5316\uFF0C\u8BF7\u5148\u8C03\u7528 audit.init()",
+  audit_initFailed: "\u5BA1\u8BA1\u6A21\u5757\u521D\u59CB\u5316\u5931\u8D25\uFF1A{error}",
+  audit_logFailed: "\u5BA1\u8BA1\u65E5\u5FD7\u8BB0\u5F55\u5931\u8D25\uFF1A{error}",
+  audit_queryFailed: "\u5BA1\u8BA1\u65E5\u5FD7\u67E5\u8BE2\u5931\u8D25\uFF1A{error}",
+  audit_cleanupFailed: "\u5BA1\u8BA1\u65E5\u5FD7\u6E05\u7406\u5931\u8D25\uFF1A{error}",
+  audit_statsFailed: "\u5BA1\u8BA1\u7EDF\u8BA1\u67E5\u8BE2\u5931\u8D25\uFF1A{error}",
+  audit_configError: "\u5BA1\u8BA1\u914D\u7F6E\u6821\u9A8C\u5931\u8D25\uFF1A{error}",
+  audit_initInProgress: "\u5BA1\u8BA1\u6A21\u5757\u6B63\u5728\u521D\u59CB\u5316\u4E2D\uFF0C\u8BF7\u52FF\u5E76\u53D1\u8C03\u7528",
+  audit_invalidInput: "\u5BA1\u8BA1\u8F93\u5165\u53C2\u6570\u65E0\u6548\uFF08{field}\uFF09\uFF1A{reason}"
+};
+
+// src/audit-i18n.ts
+var auditM = core.i18n.createMessageGetter({
+  "zh-CN": zh_CN_default,
+  "en-US": en_US_default
+});
+var AuditErrorInfo = {
+  LOG_FAILED: "001:500",
+  QUERY_FAILED: "002:500",
+  CLEANUP_FAILED: "003:500",
+  STATS_FAILED: "004:500",
+  INIT_IN_PROGRESS: "005:409",
+  NOT_INITIALIZED: "010:500",
+  CONFIG_ERROR: "012:500"
+};
+var HaiAuditError = core.error.buildHaiErrorsDef("audit", AuditErrorInfo);
+
+// src/audit-repository-log.ts
+var logger = core.logger.child({ module: "audit", scope: "repository" });
+var AUDIT_TABLE = "hai_audit_logs";
+var AuditLogRepository = class extends BaseReldbCrudRepository {
+  repoConfig;
+  isSqlite;
+  /**
+   * @param config - 仓库配置（用户表映射）
+   */
+  constructor(config) {
+    super(reldb, {
+      table: AUDIT_TABLE,
+      idColumn: "id",
+      generateId: () => core.id.withPrefix("audit_"),
+      fields: [
+        { fieldName: "id", columnName: "id", def: { type: "TEXT", primaryKey: true }, select: true, create: true, update: false },
+        { fieldName: "userId", columnName: "user_id", def: { type: "TEXT" }, select: true, create: true, update: false },
+        { fieldName: "action", columnName: "action", def: { type: "TEXT", notNull: true }, select: true, create: true, update: false },
+        { fieldName: "resource", columnName: "resource", def: { type: "TEXT", notNull: true }, select: true, create: true, update: false },
+        { fieldName: "resourceId", columnName: "resource_id", def: { type: "TEXT" }, select: true, create: true, update: false },
+        { fieldName: "details", columnName: "details", def: { type: "JSON" }, select: true, create: true, update: false },
+        { fieldName: "ipAddress", columnName: "ip_address", def: { type: "TEXT" }, select: true, create: true, update: false },
+        { fieldName: "userAgent", columnName: "user_agent", def: { type: "TEXT" }, select: true, create: true, update: false },
+        { fieldName: "createdAt", columnName: "created_at", def: { type: "TIMESTAMP" }, select: true, create: true, update: false }
+      ]
+    });
+    this.repoConfig = config;
+    this.isSqlite = this.db.config?.type === "sqlite";
+  }
+  /**
+   * 将 Date 转为适合当前数据库类型的 SQL 参数
+   *
+   * SQLite 存储 TIMESTAMP 为毫秒时间戳，其他数据库使用 ISO 字符串。
+   *
+   * @param date - 要转换的日期
+   * @returns SQLite 返回毫秒时间戳（number），其他返回 ISO 字符串
+   */
+  toDateParam(date) {
+    return this.isSqlite ? date.getTime() : date.toISOString();
+  }
+  /**
+   * 记录一条审计日志
+   *
+   * @param input - 日志内容
+   * @param input.userId - 操作用户 ID（系统操作可省略）
+   * @param input.action - 操作类型（如 login / create）
+   * @param input.resource - 资源类型（如 auth / users）
+   * @param input.resourceId - 资源 ID（可选）
+   * @param input.details - 操作详情对象（可选）
+   * @param input.ipAddress - 客户端 IP（可选）
+   * @param input.userAgent - 客户端 User-Agent（可选）
+   * @returns 成功时返回创建的 AuditLog；失败时返回 LOG_FAILED
+   */
+  async log(input) {
+    logger.debug("Recording audit log", { action: input.action, resource: input.resource });
+    const id = core.id.withPrefix("audit_");
+    const now = /* @__PURE__ */ new Date();
+    const data = {
+      id,
+      userId: input.userId ?? null,
+      action: input.action,
+      resource: input.resource,
+      resourceId: input.resourceId ?? null,
+      details: input.details ?? null,
+      ipAddress: input.ipAddress ?? null,
+      userAgent: input.userAgent ?? null,
+      createdAt: now
+    };
+    try {
+      const createResult = await this.create(data);
+      if (!createResult.success) {
+        logger.error("Failed to record audit log", { action: input.action, error: createResult.error.message });
+        return err(
+          HaiAuditError.LOG_FAILED,
+          auditM("audit_logFailed", { params: { error: createResult.error.message } }),
+          createResult.error
+        );
+      }
+      const auditLog = {
+        id,
+        userId: input.userId ?? null,
+        action: input.action,
+        resource: input.resource,
+        resourceId: input.resourceId ?? null,
+        details: input.details ? JSON.stringify(input.details) : null,
+        ipAddress: input.ipAddress ?? null,
+        userAgent: input.userAgent ?? null,
+        createdAt: now
+      };
+      logger.info("Audit log recorded", { id, action: input.action, resource: input.resource });
+      return ok(auditLog);
+    } catch (error) {
+      logger.error("Failed to record audit log", { action: input.action, error });
+      return err(
+        HaiAuditError.LOG_FAILED,
+        auditM("audit_logFailed", { params: { error: error instanceof Error ? error.message : String(error) } }),
+        error
+      );
+    }
+  }
+  /**
+   * 分页查询日志列表（含用户名 LEFT JOIN）
+   *
+   * @param options - 过滤条件与分页参数
+   * @returns 成功时返回 { items, total }；失败时返回 QUERY_FAILED
+   */
+  async listWithUser(options = {}) {
+    logger.debug("Querying audit logs", { userId: options.userId, action: options.action, resource: options.resource });
+    const conditions = [];
+    const params = [];
+    const { userTable, userIdColumn, userNameColumn } = this.repoConfig;
+    if (options.userId) {
+      conditions.push("a.user_id = ?");
+      params.push(options.userId);
+    }
+    if (options.action) {
+      conditions.push("a.action = ?");
+      params.push(options.action);
+    }
+    if (options.resource) {
+      conditions.push("a.resource = ?");
+      params.push(options.resource);
+    }
+    if (options.startDate) {
+      conditions.push("a.created_at >= ?");
+      params.push(this.toDateParam(options.startDate));
+    }
+    if (options.endDate) {
+      conditions.push("a.created_at <= ?");
+      params.push(this.toDateParam(options.endDate));
+    }
+    const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+    try {
+      const result = await this.sql().queryPage({
+        sql: `SELECT a.id, a.user_id AS userId, a.action, a.resource, a.resource_id AS resourceId,
+                a.details, a.ip_address AS ipAddress, a.user_agent AS userAgent,
+                a.created_at AS createdAt, u.${userNameColumn} AS username
+         FROM ${AUDIT_TABLE} a
+         LEFT JOIN ${userTable} u ON a.user_id = u.${userIdColumn}
+         ${whereClause}
+         ORDER BY a.created_at DESC`,
+        params,
+        pagination: { page: options.page, pageSize: options.pageSize },
+        overrides: { defaultPageSize: 20 }
+      });
+      if (!result.success) {
+        logger.error("Failed to query audit logs", { error: result.error.message });
+        return err(
+          HaiAuditError.QUERY_FAILED,
+          auditM("audit_queryFailed", { params: { error: result.error.message } }),
+          result.error
+        );
+      }
+      return ok({ items: result.data.items, total: result.data.total });
+    } catch (error) {
+      logger.error("Failed to query audit logs", { error });
+      return err(
+        HaiAuditError.QUERY_FAILED,
+        auditM("audit_queryFailed", { params: { error: error instanceof Error ? error.message : String(error) } }),
+        error
+      );
+    }
+  }
+  /**
+   * 获取指定用户的最近活动
+   *
+   * @param userId - 用户 ID
+   * @param limit - 最大返回条数，默认 10
+   * @returns 成功时返回 AuditLog 数组（按时间倒序）；失败时返回 QUERY_FAILED
+   */
+  async getUserRecent(userId, limit = 10) {
+    logger.debug("Getting user recent activity", { userId, limit });
+    try {
+      const result = await this.findAll({
+        where: "user_id = ?",
+        params: [userId],
+        orderBy: "created_at DESC",
+        limit
+      });
+      if (!result.success) {
+        return err(
+          HaiAuditError.QUERY_FAILED,
+          auditM("audit_queryFailed", { params: { error: result.error.message } }),
+          result.error
+        );
+      }
+      return ok(result.data);
+    } catch (error) {
+      return err(
+        HaiAuditError.QUERY_FAILED,
+        auditM("audit_queryFailed", { params: { error: error instanceof Error ? error.message : String(error) } }),
+        error
+      );
+    }
+  }
+  /**
+   * 清理指定天数之前的旧日志
+   *
+   * @param olderThanDays - 保留天数，默认 90；清理此天数之前的日志
+   * @returns 成功时返回删除的记录数；失败时返回 CLEANUP_FAILED
+   */
+  async cleanupOld(olderThanDays = 90) {
+    logger.debug("Cleaning up old audit logs", { olderThanDays });
+    const cutoff = /* @__PURE__ */ new Date();
+    cutoff.setDate(cutoff.getDate() - olderThanDays);
+    try {
+      const result = await this.sql().execute(
+        `DELETE FROM ${AUDIT_TABLE} WHERE created_at < ?`,
+        [this.toDateParam(cutoff)]
+      );
+      if (!result.success) {
+        logger.error("Failed to cleanup audit logs", { error: result.error.message });
+        return err(
+          HaiAuditError.CLEANUP_FAILED,
+          auditM("audit_cleanupFailed", { params: { error: result.error.message } }),
+          result.error
+        );
+      }
+      const deleted = result.data.changes;
+      logger.info("Audit logs cleaned up", { olderThanDays, deleted });
+      return ok(deleted);
+    } catch (error) {
+      logger.error("Failed to cleanup audit logs", { error });
+      return err(
+        HaiAuditError.CLEANUP_FAILED,
+        auditM("audit_cleanupFailed", { params: { error: error instanceof Error ? error.message : String(error) } }),
+        error
+      );
+    }
+  }
+  /**
+   * 获取指定天数内的操作统计（按 action 分组计数）
+   *
+   * @param days - 统计天数，默认 7
+   * @returns 成功时返回 AuditStatItem 数组（按 count 倒序）；失败时返回 STATS_FAILED
+   */
+  async getStats(days = 7) {
+    logger.debug("Getting audit statistics", { days });
+    const cutoff = /* @__PURE__ */ new Date();
+    cutoff.setDate(cutoff.getDate() - days);
+    try {
+      const result = await this.sql().query(
+        `SELECT action, COUNT(*) as count
+         FROM ${AUDIT_TABLE}
+         WHERE created_at >= ?
+         GROUP BY action
+         ORDER BY count DESC`,
+        [this.toDateParam(cutoff)]
+      );
+      if (!result.success) {
+        logger.error("Failed to query audit statistics", { error: result.error.message });
+        return err(
+          HaiAuditError.STATS_FAILED,
+          auditM("audit_statsFailed", { params: { error: result.error.message } }),
+          result.error
+        );
+      }
+      return ok(result.data.map((item) => ({ action: item.action, count: Number(item.count) })));
+    } catch (error) {
+      logger.error("Failed to query audit statistics", { error });
+      return err(
+        HaiAuditError.STATS_FAILED,
+        auditM("audit_statsFailed", { params: { error: error instanceof Error ? error.message : String(error) } }),
+        error
+      );
+    }
+  }
+};
+
+// src/audit-main.ts
+var logger2 = core.logger.child({ module: "audit", scope: "main" });
+var MAX_TEXT_LENGTH = 256;
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+function isValidTextLength(value, maxLength = MAX_TEXT_LENGTH) {
+  return value.length <= maxLength;
+}
+var currentRepo = null;
+var currentHelper = null;
+var initInProgress = false;
+var notInitialized = core.module.createNotInitializedKit(
+  HaiAuditError.NOT_INITIALIZED,
+  () => auditM("audit_notInitialized")
+);
+var notInitializedHelper = notInitialized.proxy();
+var audit = {
+  /**
+   * 初始化审计模块
+   *
+   * 会先关闭已有实例（如已初始化），再用新配置重新初始化。
+   * 内部创建 AuditLogRepository 实例（BaseReldbCrudRepository 自动建表）。
+   * 依赖 @h-ai/reldb 已初始化。
+   *
+   * @param config - 初始化配置（可选，所有字段均有默认值）
+   * @returns 成功时返回 ok(undefined)；失败时返回 CONFIG_ERROR
+   *
+   * @example
+   * ```ts
+   * const result = await audit.init()
+   * if (!result.success) {
+   *   logger.error('Audit init failed', { error: result.error.message })
+   * }
+   * ```
+   */
+  async init(config) {
+    if (initInProgress) {
+      logger2.warn("Audit init already in progress, skipping concurrent call");
+      return err(
+        HaiAuditError.INIT_IN_PROGRESS,
+        auditM("audit_initInProgress")
+      );
+    }
+    initInProgress = true;
+    try {
+      if (currentRepo) {
+        logger2.warn("Audit module is already initialized, reinitializing");
+        await audit.close();
+      }
+      logger2.info("Initializing audit module");
+      const parseResult = AuditInitConfigSchema.safeParse(config ?? {});
+      if (!parseResult.success) {
+        logger2.error("Audit config validation failed", { error: parseResult.error.message });
+        return err(
+          HaiAuditError.CONFIG_ERROR,
+          auditM("audit_configError", { params: { error: parseResult.error.message } }),
+          parseResult.error
+        );
+      }
+      const parsed = parseResult.data;
+      const identifierResult = validateIdentifiers([parsed.userTable, parsed.userIdColumn, parsed.userNameColumn]);
+      if (!identifierResult.success) {
+        logger2.error("Audit config contains invalid identifiers", { error: identifierResult.error.message });
+        return err(
+          HaiAuditError.CONFIG_ERROR,
+          auditM("audit_configError", { params: { error: identifierResult.error.message } }),
+          identifierResult.error
+        );
+      }
+      currentRepo = new AuditLogRepository({
+        userTable: parsed.userTable,
+        userIdColumn: parsed.userIdColumn,
+        userNameColumn: parsed.userNameColumn
+      });
+      currentHelper = createHelper((input) => currentRepo.log(input));
+      logger2.info("Audit module initialized");
+      return ok(void 0);
+    } catch (error) {
+      logger2.error("Audit module initialization failed", { error });
+      return err(
+        HaiAuditError.CONFIG_ERROR,
+        auditM("audit_initFailed", { params: { error: error instanceof Error ? error.message : String(error) } }),
+        error
+      );
+    } finally {
+      initInProgress = false;
+    }
+  },
+  /** 当前是否已初始化 */
+  get isInitialized() {
+    return currentRepo !== null;
+  },
+  /**
+   * 记录一条审计日志
+   *
+   * @param input - 日志内容（action 和 resource 为必填）
+   * @returns 成功时返回创建的 AuditLog；未初始化时返回 NOT_INITIALIZED
+   */
+  log(input) {
+    if (!currentRepo) {
+      return Promise.resolve(notInitialized.result());
+    }
+    if (!isNonEmptyString(input.action) || !isNonEmptyString(input.resource)) {
+      return Promise.resolve(err(
+        HaiAuditError.LOG_FAILED,
+        auditM("audit_invalidInput", { params: { field: "action/resource", reason: "must be non-empty string" } })
+      ));
+    }
+    if (!isValidTextLength(input.action) || !isValidTextLength(input.resource)) {
+      return Promise.resolve(err(
+        HaiAuditError.LOG_FAILED,
+        auditM("audit_invalidInput", { params: { field: "action/resource", reason: "exceeds max length" } })
+      ));
+    }
+    return currentRepo.log(input);
+  },
+  /**
+   * 分页查询审计日志列表（含用户名 LEFT JOIN）
+   *
+   * @param options - 过滤条件与分页参数
+   * @returns 成功时返回 { items, total }；未初始化时返回 NOT_INITIALIZED
+   */
+  list(options) {
+    if (!currentRepo) {
+      return Promise.resolve(notInitialized.result());
+    }
+    if (options?.startDate && options?.endDate && options.startDate > options.endDate) {
+      return Promise.resolve(err(
+        HaiAuditError.QUERY_FAILED,
+        auditM("audit_invalidInput", { params: { field: "dateRange", reason: "startDate must be before endDate" } })
+      ));
+    }
+    return currentRepo.listWithUser(options);
+  },
+  /**
+   * 获取指定用户的最近活动记录
+   *
+   * @param userId - 用户 ID
+   * @param limit - 最大返回条数，默认 10
+   * @returns 成功时返回 AuditLog 数组；未初始化时返回 NOT_INITIALIZED
+   */
+  getUserRecent(userId, limit) {
+    if (!currentRepo) {
+      return Promise.resolve(notInitialized.result());
+    }
+    if (!isNonEmptyString(userId)) {
+      return Promise.resolve(err(
+        HaiAuditError.QUERY_FAILED,
+        auditM("audit_invalidInput", { params: { field: "userId", reason: "must be non-empty string" } })
+      ));
+    }
+    if (typeof limit === "number" && (!Number.isInteger(limit) || limit <= 0)) {
+      return Promise.resolve(err(
+        HaiAuditError.QUERY_FAILED,
+        auditM("audit_invalidInput", { params: { field: "limit", reason: "must be a positive integer" } })
+      ));
+    }
+    return currentRepo.getUserRecent(userId, limit);
+  },
+  /**
+   * 清理指定天数之前的旧日志
+   *
+   * @param olderThanDays - 保留天数，默认 90
+   * @returns 成功时返回删除的记录数；未初始化时返回 NOT_INITIALIZED
+   */
+  cleanup(olderThanDays) {
+    if (!currentRepo) {
+      return Promise.resolve(notInitialized.result());
+    }
+    if (typeof olderThanDays === "number" && (!Number.isInteger(olderThanDays) || olderThanDays < 0)) {
+      return Promise.resolve(err(
+        HaiAuditError.CLEANUP_FAILED,
+        auditM("audit_invalidInput", { params: { field: "olderThanDays", reason: "must be a non-negative integer" } })
+      ));
+    }
+    return currentRepo.cleanupOld(olderThanDays);
+  },
+  /**
+   * 获取指定天数内的操作统计（按 action 分组计数）
+   *
+   * @param days - 统计天数，默认 7
+   * @returns 成功时返回 AuditStatItem 数组；未初始化时返回 NOT_INITIALIZED
+   */
+  getStats(days) {
+    if (!currentRepo) {
+      return Promise.resolve(notInitialized.result());
+    }
+    if (typeof days === "number" && (!Number.isInteger(days) || days < 0)) {
+      return Promise.resolve(err(
+        HaiAuditError.STATS_FAILED,
+        auditM("audit_invalidInput", { params: { field: "days", reason: "must be a non-negative integer" } })
+      ));
+    }
+    return currentRepo.getStats(days);
+  },
+  /**
+   * 便捷记录器
+   *
+   * 未初始化时调用任意方法均返回 NOT_INITIALIZED 错误。
+   */
+  get helper() {
+    if (!currentHelper) {
+      return notInitializedHelper;
+    }
+    return currentHelper;
+  },
+  /**
+   * 关闭审计模块，释放内部状态
+   */
+  async close() {
+    if (!currentRepo) {
+      logger2.info("Audit module already closed, skipping");
+      return;
+    }
+    logger2.info("Closing audit module");
+    currentRepo = null;
+    currentHelper = null;
+    logger2.info("Audit module closed");
+  }
+};
+
+export { AuditInitConfigSchema, HaiAuditError, audit, createHelper };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map