@h-ai/audit 0.1.0-alpha.66 → 0.1.0-alpha.67

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.en.md +18 -8
  2. package/README.ja.md +19 -9
  3. package/README.md +19 -9
  4. package/package.json +3 -3
package/README.en.md CHANGED
@@ -4,20 +4,30 @@
4
4
 
5
5
  [Framework home](../../README.en.md) · Related modules: [@h-ai/core](../core/README.en.md) · [@h-ai/reldb](../reldb/README.en.md)
6
6
 
7
+ ## Introduction
8
+
7
9
  A unified audit logging module. The `audit` object records, queries, cleans up, and aggregates audit logs, with persistence provided by `@h-ai/reldb`.
8
10
 
9
- ## Dependencies
11
+ ## Core features
12
+
13
+ - Record user actions and security events; filter by user, date and action.
14
+ - Query paginated logs and statistics, and clean up by retention period.
15
+ - Persist through the relational database and redact credential fields before writing.
16
+
17
+ ## Getting started
18
+
19
+ ### Dependencies
10
20
 
11
21
  - `@h-ai/reldb`: database for audit log persistence; **initialize it before audit.init()**.
12
22
 
13
- ## Use cases
23
+ ### Use cases
14
24
 
15
25
  - User activity auditing (login, logout, registration, password reset, etc.)
16
26
  - CRUD auditing (resource creation, reads, updates, and deletion)
17
27
  - Security event tracking and compliance auditing
18
28
  - Operational statistics (operation frequency, active users, etc.)
19
29
 
20
- ## Quick start
30
+ ### Quick start
21
31
 
22
32
  ```ts
23
33
  import { audit } from '@h-ai/audit'
@@ -60,7 +70,7 @@ if (!closeResult.success) {
60
70
  }
61
71
  ```
62
72
 
63
- ## Initialization options
73
+ ### Initialization options
64
74
 
65
75
  ```ts
66
76
  // 默认配置（无需传参）
@@ -76,7 +86,7 @@ await audit.init({
76
86
 
77
87
  Audit logs are stored in the fixed `hai_audit_logs` table and require an initialized `@h-ai/reldb`.
78
88
 
79
- ## API overview
89
+ ### API overview
80
90
 
81
91
  - `audit.init(config)`: initialize the audit module.
82
92
  - `audit.log(input)`: record an audit log.
@@ -87,7 +97,7 @@ Audit logs are stored in the fixed `hai_audit_logs` table and require an initial
87
97
  - `audit.helper.login/logout/register/...`: convenient log helpers.
88
98
  - `audit.close()`: close the module.
89
99
 
90
- ### Input constraints
100
+ #### Input constraints
91
101
 
92
102
  - `audit.log(input)`: `action` / `resource` must be nonempty strings of at most 256 characters.
93
103
  - `audit.log(input)`: credential fields in `details` (such as `password` / `token` / `secret`) are redacted automatically before persistence; email addresses and phone numbers retain their original values by default.
@@ -96,7 +106,7 @@ Audit logs are stored in the fixed `hai_audit_logs` table and require an initial
96
106
  - `audit.cleanup(days)`: `days`, if provided, must be a nonnegative integer.
97
107
  - `audit.getStats(days)`: `days`, if provided, must be a nonnegative integer.
98
108
 
99
- ## Error codes
109
+ ### Error codes
100
110
 
101
111
  All operations return `HaiResult<T>`. Common error codes:
102
112
 
@@ -112,7 +122,7 @@ All operations return `HaiResult<T>`. Common error codes:
112
122
 
113
123
  > Note: `audit.close()` also returns `HaiResult<void>`. `audit.helper.passwordResetRequest()` records the original email address without additional masking by default.
114
124
 
115
- ## Tests
125
+ ## Development and testing
116
126
 
117
127
  ```bash
118
128
  pnpm --filter @h-ai/audit test
package/README.ja.md CHANGED
@@ -4,20 +4,30 @@
4
4
 
5
5
  [フレームワークのホーム](../../README.ja.md) · 関連モジュール：[@h-ai/core](../core/README.ja.md) · [@h-ai/reldb](../reldb/README.ja.md)
6
6
 
7
+ ## 概要
8
+
7
9
  統一された監査ログモジュールです。`audit` オブジェクトで記録、検索、削除、集計を行い、`@h-ai/reldb` で永続化します。
8
10
 
9
- ## 依存関係
11
+ ## 主な機能
12
+
13
+ - ユーザー操作やセキュリティイベントを記録し、ユーザー・日時・操作で検索。
14
+ - ログのページ取得、統計、保存期間に応じた削除。
15
+ - 関係データベースに保存し、認証情報を記録前にマスク。
16
+
17
+ ## 使い始める
18
+
19
+ ### 依存関係
10
20
 
11
21
  - `@h-ai/reldb`：監査ログを永続化するデータベース。**audit.init() より先に初期化してください**。
12
22
 
13
- ## 用途
23
+ ### 用途
14
24
 
15
25
  - ユーザー操作の監査（ログイン、ログアウト、登録、パスワードリセットなど）
16
26
  - CRUD 操作の監査（リソースの作成、参照、更新、削除）
17
27
  - セキュリティイベントの追跡とコンプライアンス監査
18
28
  - 運用統計（操作頻度、アクティブユーザーなど）
19
29
 
20
- ## クイックスタート
30
+ ### クイックスタート
21
31
 
22
32
  ```ts
23
33
  import { audit } from '@h-ai/audit'
@@ -60,7 +70,7 @@ if (!closeResult.success) {
60
70
  }
61
71
  ```
62
72
 
63
- ## 初期化設定
73
+ ### 初期化設定
64
74
 
65
75
  ```ts
66
76
  // 默认配置（无需传参）
@@ -76,7 +86,7 @@ await audit.init({
76
86
 
77
87
  監査ログは固定の `hai_audit_logs` テーブルに保存され、初期化済みの `@h-ai/reldb` が必要です。
78
88
 
79
- ## API 一覧
89
+ ### API 一覧
80
90
 
81
91
  - `audit.init(config)`：監査モジュールを初期化。
82
92
  - `audit.log(input)`：監査ログを記録。
@@ -87,7 +97,7 @@ await audit.init({
87
97
  - `audit.helper.login/logout/register/...`：記録用ヘルパー。
88
98
  - `audit.close()`：モジュールを終了。
89
99
 
90
- ### 入力制約
100
+ #### 入力制約
91
101
 
92
102
  - `audit.log(input)`：`action` / `resource` は空でない文字列で、長さは 256 文字以内。
93
103
  - `audit.log(input)`：`details` 内の認証情報（`password` / `token` / `secret` など）は永続化前に自動的にマスクされます。メールアドレスと電話番号は既定で元の値を保持します。
@@ -96,7 +106,7 @@ await audit.init({
96
106
  - `audit.cleanup(days)`：`days` を指定する場合は 0 以上の整数。
97
107
  - `audit.getStats(days)`：`days` を指定する場合は 0 以上の整数。
98
108
 
99
- ## エラーコード
109
+ ### エラーコード
100
110
 
101
111
  すべての操作は `HaiResult<T>` を返します。主なエラーコード：
102
112
 
@@ -112,12 +122,12 @@ await audit.init({
112
122
 
113
123
  > 注：`audit.close()` も `HaiResult<void>` を返します。`audit.helper.passwordResetRequest()` は既定でメールアドレスを追加マスクせず、そのまま記録します。
114
124
 
115
- ## テスト
125
+ ## 開発とテスト
116
126
 
117
127
  ```bash
118
128
  pnpm --filter @h-ai/audit test
119
129
  ```
120
130
 
121
- ## License
131
+ ## ライセンス
122
132
 
123
133
  Apache-2.0
package/README.md CHANGED
@@ -4,20 +4,30 @@
4
4
 
5
5
  [框架首页](../../README.md) · 相关模块：[@h-ai/core](../core/README.md) · [@h-ai/reldb](../reldb/README.md)
6
6
 
7
+ ## 简介
8
+
7
9
  统一审计日志模块，通过 `audit` 对象提供审计日志的记录、查询、清理与统计功能，基于 `@h-ai/reldb` 实现持久化。
8
10
 
9
- ## 依赖
11
+ ## 核心功能清单
12
+
13
+ - 记录用户操作与安全事件，支持按用户、时间和操作筛选。
14
+ - 查询分页日志与操作统计，并按保留天数清理。
15
+ - 使用关系数据库持久化，写入前隐藏凭证类字段。
16
+
17
+ ## 使用入门
18
+
19
+ ### 依赖
10
20
 
11
21
  - `@h-ai/reldb` — 数据库（审计日志持久化），**需在 audit.init() 前初始化**
12
22
 
13
- ## 适用场景
23
+ ### 适用场景
14
24
 
15
25
  - 用户操作审计（登录、登出、注册、密码重置等）
16
26
  - CRUD 操作审计（创建、读取、更新、删除资源）
17
27
  - 安全事件追踪与合规审计
18
28
  - 运营数据统计（操作频次、活跃用户等）
19
29
 
20
- ## 快速开始
30
+ ### 快速开始
21
31
 
22
32
  ```ts
23
33
  import { audit } from '@h-ai/audit'
@@ -60,7 +70,7 @@ if (!closeResult.success) {
60
70
  }
61
71
  ```
62
72
 
63
- ## 初始化配置
73
+ ### 初始化配置
64
74
 
65
75
  ```ts
66
76
  // 默认配置（无需传参）
@@ -76,7 +86,7 @@ await audit.init({
76
86
 
77
87
  审计日志固定存储在 `hai_audit_logs` 表中，依赖 `@h-ai/reldb` 已初始化。
78
88
 
79
- ## API 概览
89
+ ### API 概览
80
90
 
81
91
  - `audit.init(config)` - 初始化审计模块
82
92
  - `audit.log(input)` - 记录审计日志
@@ -87,7 +97,7 @@ await audit.init({
87
97
  - `audit.helper.login/logout/register/...` - 便捷记录器
88
98
  - `audit.close()` - 关闭模块
89
99
 
90
- ### 输入约束
100
+ #### 输入约束
91
101
 
92
102
  - `audit.log(input)`：`action` / `resource` 必须为非空字符串，且长度不超过 256。
93
103
  - `audit.log(input)`：`details` 中的凭证类敏感字段（如 `password` / `token` / `secret`）会在持久化前自动脱敏；邮箱、手机号默认保留原值。
@@ -96,7 +106,7 @@ await audit.init({
96
106
  - `audit.cleanup(days)`：`days`（如传入）必须为非负整数。
97
107
  - `audit.getStats(days)`：`days`（如传入）必须为非负整数。
98
108
 
99
- ## 错误码
109
+ ### 错误码
100
110
 
101
111
  所有操作返回 `HaiResult<T>`，常用错误码如下：
102
112
 
@@ -112,12 +122,12 @@ await audit.init({
112
122
 
113
123
  > 说明：`audit.close()` 也返回 `HaiResult<void>`；`audit.helper.passwordResetRequest()` 会记录原始邮箱，默认不会额外掩码。
114
124
 
115
- ## 测试
125
+ ## 开发测试
116
126
 
117
127
  ```bash
118
128
  pnpm --filter @h-ai/audit test
119
129
  ```
120
130
 
121
- ## License
131
+ ## 许可证
122
132
 
123
133
  Apache-2.0
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@h-ai/audit",
3
3
  "type": "module",
4
- "version": "0.1.0-alpha.66",
4
+ "version": "0.1.0-alpha.67",
5
5
  "description": "Hai Framework audit logging module.",
6
6
  "license": "Apache-2.0",
7
7
  "exports": {
@@ -23,8 +23,8 @@
23
23
  "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
24
24
  },
25
25
  "dependencies": {
26
- "@h-ai/core": "0.1.0-alpha.66",
27
- "@h-ai/reldb": "0.1.0-alpha.66"
26
+ "@h-ai/core": "0.1.0-alpha.67",
27
+ "@h-ai/reldb": "0.1.0-alpha.67"
28
28
  },
29
29
  "devDependencies": {
30
30
  "@types/node": "^26.6.5",