@h-ai/audit 0.1.0-alpha.55 → 0.1.0-alpha.57

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 +123 -0
  2. package/README.ja.md +123 -0
  3. package/README.md +4 -0
  4. package/package.json +3 -3
package/README.en.md ADDED
@@ -0,0 +1,123 @@
1
+ # @h-ai/audit
2
+
3
+ [简体中文](./README.md) | [English](./README.en.md) | [日本語](./README.ja.md)
4
+
5
+ [Framework home](../../README.en.md) · Related modules: [@h-ai/core](../core/README.en.md) · [@h-ai/reldb](../reldb/README.en.md)
6
+
7
+ A unified audit logging module. The `audit` object records, queries, cleans up, and aggregates audit logs, with persistence provided by `@h-ai/reldb`.
8
+
9
+ ## Dependencies
10
+
11
+ - `@h-ai/reldb`: database for audit log persistence; **initialize it before audit.init()**.
12
+
13
+ ## Use cases
14
+
15
+ - User activity auditing (login, logout, registration, password reset, etc.)
16
+ - CRUD auditing (resource creation, reads, updates, and deletion)
17
+ - Security event tracking and compliance auditing
18
+ - Operational statistics (operation frequency, active users, etc.)
19
+
20
+ ## Quick start
21
+
22
+ ```ts
23
+ import { audit } from '@h-ai/audit'
24
+ import { reldb } from '@h-ai/reldb'
25
+
26
+ // 1. 初始化依赖
27
+ await reldb.init({ type: 'sqlite', database: './data.db' })
28
+
29
+ // 2. 初始化审计模块（自动使用已初始化的 reldb 单例）
30
+ const result = await audit.init()
31
+ if (!result.success) {
32
+ throw new Error(result.error.message)
33
+ }
34
+
35
+ // 3. 记录审计日志
36
+ await audit.log({
37
+ userId: 'user_1',
38
+ action: 'login',
39
+ resource: 'auth',
40
+ ipAddress: '127.0.0.1',
41
+ })
42
+
43
+ // 4. 使用便捷方法
44
+ await audit.helper.login('user_1', '127.0.0.1')
45
+ await audit.helper.crud({ userId: 'user_1', action: 'create', resource: 'users', resourceId: 'user_2', details: { name: '张三' } })
46
+
47
+ // 5. 查询日志
48
+ const logs = await audit.list({ pageSize: 20, action: 'login' })
49
+
50
+ // 6. 获取统计
51
+ const stats = await audit.getStats(7) // 最近 7 天
52
+
53
+ // 7. 清理旧日志
54
+ await audit.cleanup(90) // 清理 90 天前的日志
55
+
56
+ // 8. 关闭
57
+ const closeResult = await audit.close()
58
+ if (!closeResult.success) {
59
+ throw new Error(closeResult.error.message)
60
+ }
61
+ ```
62
+
63
+ ## Initialization options
64
+
65
+ ```ts
66
+ // 默认配置（无需传参）
67
+ await audit.init()
68
+
69
+ // 自定义用户表映射
70
+ await audit.init({
71
+ userTable: 'hai_iam_users', // 用户表名（默认 'hai_iam_users'）
72
+ userIdColumn: 'id', // 用户表主键列名（默认 'id'）
73
+ userNameColumn: 'username', // 用户表用户名列名（默认 'username'）
74
+ })
75
+ ```
76
+
77
+ Audit logs are stored in the fixed `hai_audit_logs` table and require an initialized `@h-ai/reldb`.
78
+
79
+ ## API overview
80
+
81
+ - `audit.init(config)`: initialize the audit module.
82
+ - `audit.log(input)`: record an audit log.
83
+ - `audit.list(options)`: query paginated audit logs, including a JOIN for usernames.
84
+ - `audit.getUserRecent(userId, limit)`: get recent user activity.
85
+ - `audit.cleanup(days)`: delete old logs.
86
+ - `audit.getStats(days)`: get operation statistics.
87
+ - `audit.helper.login/logout/register/...`: convenient log helpers.
88
+ - `audit.close()`: close the module.
89
+
90
+ ### Input constraints
91
+
92
+ - `audit.log(input)`: `action` / `resource` must be nonempty strings of at most 256 characters.
93
+ - `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.
94
+ - `audit.list(options)`: when both `startDate` and `endDate` are provided, `startDate <= endDate` is required.
95
+ - `audit.getUserRecent(userId, limit)`: `userId` must be nonempty; `limit`, if provided, must be a positive integer.
96
+ - `audit.cleanup(days)`: `days`, if provided, must be a nonnegative integer.
97
+ - `audit.getStats(days)`: `days`, if provided, must be a nonnegative integer.
98
+
99
+ ## Error codes
100
+
101
+ All operations return `HaiResult<T>`. Common error codes:
102
+
103
+ | Error code | code | Description |
104
+ | -------------------------------- | --------------- | -------------------------- |
105
+ | `HaiAuditError.LOG_FAILED` | `hai:audit:001` | Recording failed |
106
+ | `HaiAuditError.QUERY_FAILED` | `hai:audit:002` | Query failed |
107
+ | `HaiAuditError.CLEANUP_FAILED` | `hai:audit:003` | Cleanup failed |
108
+ | `HaiAuditError.STATS_FAILED` | `hai:audit:004` | Aggregation failed |
109
+ | `HaiAuditError.INIT_IN_PROGRESS` | `hai:audit:005` | Initialization in progress |
110
+ | `HaiAuditError.NOT_INITIALIZED` | `hai:audit:010` | Module not initialized |
111
+ | `HaiAuditError.CONFIG_ERROR` | `hai:audit:012` | Invalid configuration |
112
+
113
+ > Note: `audit.close()` also returns `HaiResult<void>`. `audit.helper.passwordResetRequest()` records the original email address without additional masking by default.
114
+
115
+ ## Tests
116
+
117
+ ```bash
118
+ pnpm --filter @h-ai/audit test
119
+ ```
120
+
121
+ ## License
122
+
123
+ Apache-2.0
package/README.ja.md ADDED
@@ -0,0 +1,123 @@
1
+ # @h-ai/audit
2
+
3
+ [简体中文](./README.md) | [English](./README.en.md) | [日本語](./README.ja.md)
4
+
5
+ [フレームワークのホーム](../../README.ja.md) · 関連モジュール：[@h-ai/core](../core/README.ja.md) · [@h-ai/reldb](../reldb/README.ja.md)
6
+
7
+ 統一された監査ログモジュールです。`audit` オブジェクトで記録、検索、削除、集計を行い、`@h-ai/reldb` で永続化します。
8
+
9
+ ## 依存関係
10
+
11
+ - `@h-ai/reldb`：監査ログを永続化するデータベース。**audit.init() より先に初期化してください**。
12
+
13
+ ## 用途
14
+
15
+ - ユーザー操作の監査（ログイン、ログアウト、登録、パスワードリセットなど）
16
+ - CRUD 操作の監査（リソースの作成、参照、更新、削除）
17
+ - セキュリティイベントの追跡とコンプライアンス監査
18
+ - 運用統計（操作頻度、アクティブユーザーなど）
19
+
20
+ ## クイックスタート
21
+
22
+ ```ts
23
+ import { audit } from '@h-ai/audit'
24
+ import { reldb } from '@h-ai/reldb'
25
+
26
+ // 1. 初始化依赖
27
+ await reldb.init({ type: 'sqlite', database: './data.db' })
28
+
29
+ // 2. 初始化审计模块（自动使用已初始化的 reldb 单例）
30
+ const result = await audit.init()
31
+ if (!result.success) {
32
+ throw new Error(result.error.message)
33
+ }
34
+
35
+ // 3. 记录审计日志
36
+ await audit.log({
37
+ userId: 'user_1',
38
+ action: 'login',
39
+ resource: 'auth',
40
+ ipAddress: '127.0.0.1',
41
+ })
42
+
43
+ // 4. 使用便捷方法
44
+ await audit.helper.login('user_1', '127.0.0.1')
45
+ await audit.helper.crud({ userId: 'user_1', action: 'create', resource: 'users', resourceId: 'user_2', details: { name: '张三' } })
46
+
47
+ // 5. 查询日志
48
+ const logs = await audit.list({ pageSize: 20, action: 'login' })
49
+
50
+ // 6. 获取统计
51
+ const stats = await audit.getStats(7) // 最近 7 天
52
+
53
+ // 7. 清理旧日志
54
+ await audit.cleanup(90) // 清理 90 天前的日志
55
+
56
+ // 8. 关闭
57
+ const closeResult = await audit.close()
58
+ if (!closeResult.success) {
59
+ throw new Error(closeResult.error.message)
60
+ }
61
+ ```
62
+
63
+ ## 初期化設定
64
+
65
+ ```ts
66
+ // 默认配置（无需传参）
67
+ await audit.init()
68
+
69
+ // 自定义用户表映射
70
+ await audit.init({
71
+ userTable: 'hai_iam_users', // 用户表名（默认 'hai_iam_users'）
72
+ userIdColumn: 'id', // 用户表主键列名（默认 'id'）
73
+ userNameColumn: 'username', // 用户表用户名列名（默认 'username'）
74
+ })
75
+ ```
76
+
77
+ 監査ログは固定の `hai_audit_logs` テーブルに保存され、初期化済みの `@h-ai/reldb` が必要です。
78
+
79
+ ## API 一覧
80
+
81
+ - `audit.init(config)`：監査モジュールを初期化。
82
+ - `audit.log(input)`：監査ログを記録。
83
+ - `audit.list(options)`：ユーザー名の JOIN を含む監査ログのページ検索。
84
+ - `audit.getUserRecent(userId, limit)`：ユーザーの最近の操作を取得。
85
+ - `audit.cleanup(days)`：古いログを削除。
86
+ - `audit.getStats(days)`：操作統計を取得。
87
+ - `audit.helper.login/logout/register/...`：記録用ヘルパー。
88
+ - `audit.close()`：モジュールを終了。
89
+
90
+ ### 入力制約
91
+
92
+ - `audit.log(input)`：`action` / `resource` は空でない文字列で、長さは 256 文字以内。
93
+ - `audit.log(input)`：`details` 内の認証情報（`password` / `token` / `secret` など）は永続化前に自動的にマスクされます。メールアドレスと電話番号は既定で元の値を保持します。
94
+ - `audit.list(options)`：`startDate` と `endDate` を両方指定する場合は `startDate <= endDate` が必要です。
95
+ - `audit.getUserRecent(userId, limit)`：`userId` は空でない文字列。`limit` を指定する場合は正の整数。
96
+ - `audit.cleanup(days)`：`days` を指定する場合は 0 以上の整数。
97
+ - `audit.getStats(days)`：`days` を指定する場合は 0 以上の整数。
98
+
99
+ ## エラーコード
100
+
101
+ すべての操作は `HaiResult<T>` を返します。主なエラーコード：
102
+
103
+ | エラーコード | code | 説明 |
104
+ | -------------------------------- | --------------- | -------------------- |
105
+ | `HaiAuditError.LOG_FAILED` | `hai:audit:001` | 記録に失敗 |
106
+ | `HaiAuditError.QUERY_FAILED` | `hai:audit:002` | 検索に失敗 |
107
+ | `HaiAuditError.CLEANUP_FAILED` | `hai:audit:003` | 削除に失敗 |
108
+ | `HaiAuditError.STATS_FAILED` | `hai:audit:004` | 集計に失敗 |
109
+ | `HaiAuditError.INIT_IN_PROGRESS` | `hai:audit:005` | 初期化中 |
110
+ | `HaiAuditError.NOT_INITIALIZED` | `hai:audit:010` | モジュールが未初期化 |
111
+ | `HaiAuditError.CONFIG_ERROR` | `hai:audit:012` | 設定エラー |
112
+
113
+ > 注：`audit.close()` も `HaiResult<void>` を返します。`audit.helper.passwordResetRequest()` は既定でメールアドレスを追加マスクせず、そのまま記録します。
114
+
115
+ ## テスト
116
+
117
+ ```bash
118
+ pnpm --filter @h-ai/audit test
119
+ ```
120
+
121
+ ## License
122
+
123
+ Apache-2.0
package/README.md CHANGED
@@ -1,5 +1,9 @@
1
1
  # @h-ai/audit
2
2
 
3
+ [简体中文](./README.md) | [English](./README.en.md) | [日本語](./README.ja.md)
4
+
5
+ [框架首页](../../README.md) · 相关模块：[@h-ai/core](../core/README.md) · [@h-ai/reldb](../reldb/README.md)
6
+
3
7
  统一审计日志模块，通过 `audit` 对象提供审计日志的记录、查询、清理与统计功能，基于 `@h-ai/reldb` 实现持久化。
4
8
 
5
9
  ## 依赖
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.55",
4
+ "version": "0.1.0-alpha.57",
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.12.0"
24
24
  },
25
25
  "dependencies": {
26
- "@h-ai/core": "0.1.0-alpha.55",
27
- "@h-ai/reldb": "0.1.0-alpha.55"
26
+ "@h-ai/core": "0.1.0-alpha.57",
27
+ "@h-ai/reldb": "0.1.0-alpha.57"
28
28
  },
29
29
  "devDependencies": {
30
30
  "@types/node": "^25.9.1",