@geekmidas/审计
类型安全审计记录与数据库整合,以跟踪应用程序事件和用户行动
概览
@geekmidas/audit 为在应用程序中记录和持续审计线索提供了一个全面的解决办法。 它支持类型安全的审计动作,交易写作,以及灵活的存储后端.
特征
- 安全审计行动: 为编译时间安全定义审计类型
- 交易支持: 在数据库交易中进行断层审计
- 弹性存储:可插件存储接口(Kysely, Knex, in- memory, 缓存)
- 演员跟踪: 记录执行每项行动的人(用户、服务、系统)
- 丰富的元数据: 附加请求上下文、实体引用和自定义数据
- 查询支持: 查询带有过滤器、页码和排序的审计日志
安装
npm install @geekmidas/audit
# or
pnpm add @geekmidas/audit
快速启动
1. 界定你的审计行动
import type { AuditableAction } from '@geekmidas/audit';
// Define type-safe audit actions
type AppAuditAction =
| AuditableAction<'user.created', { userId: string; email: string }>
| AuditableAction<'user.updated', { userId: string; changes: string[] }>
| AuditableAction<'order.placed', { orderId: string; total: number }>;
2. 设置存储
促进发展/试验(记忆审计):
import { InMemoryAuditStorage } from '@geekmidas/audit/memory';
const storage = new InMemoryAuditStorage<AppAuditAction>();
// Query stored records
const records = await storage.query({ type: 'user.created' });
// Clear all records (useful in tests)
storage.clear();
用于生产(Kysely AuditStorage):
import { KyselyAuditStorage } from '@geekmidas/audit/kysely';
// Define your database schema
interface Database {
audit_logs: AuditLogTable;
// ... other tables
}
const storage = new KyselyAuditStorage<Database>({
db: kyselyDb,
tableName: 'audit_logs',
});
用于生产(KnexAuditStorage):
import { KnexAuditStorage } from '@geekmidas/audit/knex';
const storage = new KnexAuditStorage({
db: knexDb,
tableName: 'audit_logs',
});
3. 设立审计人
import { DefaultAuditor } from '@geekmidas/audit';
const auditor = new DefaultAuditor<AppAuditAction>({
actor: { id: 'user-123', type: 'user' },
storage,
metadata: {
requestId: 'req-456',
endpoint: '/api/users',
},
});
4. 记录审计
// Type-safe audit calls - TypeScript enforces correct payload shapes
auditor.audit('user.created', {
userId: '789',
email: '[email protected]',
}); // OK
auditor.audit('user.created', {
orderId: '123', // Type error - wrong payload shape
});
// Flush to storage
await auditor.flush();
交易审计
使用 withAuditableTransaction 以确保审计与数据库操作具有原子性:
import { withAuditableTransaction } from '@geekmidas/audit/kysely';
const result = await withAuditableTransaction(
db,
auditor,
async (trx) => {
// Database operations
const user = await trx
.insertInto('users')
.values({ name: 'John', email: '[email protected]' })
.returningAll()
.executeTakeFirstOrThrow();
// Audit is recorded
auditor.audit('user.created', {
userId: user.id,
email: user.email,
});
return user;
},
);
// Audits are automatically flushed before transaction commits
// If flush fails, the entire transaction rolls back
API 参考
核心类型
AuditableAction<TType, TPayload>
定义具有类型和有效载荷的可审计动作:
type UserAction = AuditableAction<'user.created', { userId: string }>;
AuditRecord
完成所有元数据的审计记录:
interface AuditRecord<TPayload = unknown> {
id: string;
type: string;
operation: AuditOperation;
table?: string;
entityId?: string | Record<string, unknown>;
oldValues?: Record<string, unknown>;
newValues?: Record<string, unknown>;
payload?: TPayload;
timestamp: Date;
actor?: AuditActor;
metadata?: AuditMetadata;
}
AuditActor
代表执行行动的人:
interface AuditActor {
id?: string;
type?: string;
[key: string]: unknown;
}
AuditMetadata
请求上下文和补充数据:
interface AuditMetadata {
requestId?: string;
endpoint?: string;
method?: string;
ip?: string;
userAgent?: string;
[key: string]: unknown;
}
Auditor 接口
interface Auditor<TAuditAction, TTransaction> {
readonly actor: AuditActor;
// Type-safe audit recording
audit<TType extends ExtractAuditType<TAuditAction>>(
type: TType,
payload: ExtractAuditPayload<TAuditAction, TType>,
options?: AuditOptions,
): void;
// Raw record insertion
record(record: Omit<AuditRecord, 'id' | 'timestamp' | 'actor'>): void;
// Get collected records
getRecords(): AuditRecord[];
// Flush to storage
flush(trx?: TTransaction): Promise<void>;
// Clear without flushing
clear(): void;
// Add metadata to future records
addMetadata(metadata: AuditMetadata): void;
// Transaction management
setTransaction(trx: TTransaction): void;
getTransaction(): TTransaction | undefined;
}
AuditStorage 接口
为自定义存储后端执行此接口 :
interface AuditStorage<TAuditAction> {
// Required: Write records
write(records: AuditRecord[], trx?: unknown): Promise<void>;
// Optional: Query records
query?(options: AuditQueryOptions): Promise<AuditRecord[]>;
// Optional: Count records
count?(options: Omit<AuditQueryOptions, 'limit' | 'offset'>): Promise<number>;
// Optional: Get database for transactions
getDatabase?(): unknown;
}
KyselyAuditStorage
已建 Kysely 存储执行 :
const storage = new KyselyAuditStorage({
db: kyselyDb,
tableName: 'audit_logs',
databaseServiceName: 'database', // Optional: for automatic transaction injection
autoId: false, // Optional: let database generate IDs
});
// Query audits
const audits = await storage.query({
type: 'user.created',
actorId: 'user-123',
from: new Date('2024-01-01'),
limit: 100,
orderBy: 'timestamp',
orderDirection: 'desc',
});
// Count audits
const count = await storage.count({
type: ['user.created', 'user.updated'],
actorId: 'user-123',
});
KnexAuditStorage
已建成的克能斯仓储实施. 镜子 KyselyAuditStorage - 一样
配置, 不变 query()编号 :count() 过滤器, 相同的交易语义 :
import { KnexAuditStorage } from '@geekmidas/audit/knex';
const storage = new KnexAuditStorage({
db: knexDb,
tableName: 'audit_logs',
databaseServiceName: 'database', // Optional: for automatic transaction injection
autoId: false, // Optional: let database generate IDs
});
const audits = await storage.query({
type: 'user.created',
actorId: 'user-123',
from: new Date('2024-01-01'),
limit: 100,
orderBy: 'timestamp',
orderDirection: 'desc',
});
const count = await storage.count({
type: ['user.created', 'user.updated'],
actorId: 'user-123',
});
列名为骆驼Case,匹配克赛利存储. 如果您的数据库使用 蛇行 case 列, 用大小写映射器配置 Knex :
import { knexSnakeCaseMappers } from 'objection';
const knexDb = knex({
client: 'pg',
connection: process.env.DATABASE_URL,
...knexSnakeCaseMappers(),
});
交易与Kysely存储相同:
import { withAuditableTransaction } from '@geekmidas/audit/knex';
const user = await withAuditableTransaction(knexDb, auditor, async (trx) => {
const [user] = await trx('users').insert(data).returning('*');
auditor.audit('user.created', { userId: user.id, email: user.email });
return user;
});
// Audits are flushed inside the transaction, before it commits
通过交易作为第一个参数 重用它而不是打开一个 保存点,所以审计会随着外部交易而回滚.
InMemoryAuditStorage
方便包装 CacheAuditStorage 与 InMemoryCache用于测试和开发:
import { InMemoryAuditStorage } from '@geekmidas/audit/memory';
const storage = new InMemoryAuditStorage<AppAuditAction>();
// Query audits (same API as other storages)
const audits = await storage.query({
type: 'user.created',
limit: 10,
});
// Get all records (for assertions in tests)
const allRecords = await storage.getRecords();
// Clear all records (reset for next test)
await storage.clear();
CacheAuditStorage
基于缓存的存储使用任意 @geekmidas/cache 执行:
import { CacheAuditStorage } from '@geekmidas/audit/cache';
import { InMemoryCache } from '@geekmidas/cache/memory';
import { UpstashCache } from '@geekmidas/cache/upstash';
// With in-memory cache (development/testing)
const storage = new CacheAuditStorage({
cache: new InMemoryCache(),
ttl: 86400, // 24 hours
});
// With Upstash Redis (production - distributed systems)
const storage = new CacheAuditStorage({
cache: new UpstashCache({
url: process.env.UPSTASH_REDIS_URL,
token: process.env.UPSTASH_REDIS_TOKEN,
}),
prefix: 'audit', // Optional key prefix
ttl: 604800, // 7 days
});
// Query and count work the same as other storages
const audits = await storage.query({ type: 'user.created' });
const count = await storage.count({ actorId: 'user-123' });
// Clear all records
await storage.clear();
数据库Schema
创建一个 audit_logs 表格显示 KyselyAuditStorage 或者说 KnexAuditStorage数字 :
CREATE TABLE audit_logs (
id VARCHAR(21) PRIMARY KEY, -- or use gen_random_uuid() with autoId: true
type VARCHAR(255) NOT NULL,
operation VARCHAR(20) NOT NULL,
"table" VARCHAR(255),
"entityId" VARCHAR(255),
"oldValues" JSONB,
"newValues" JSONB,
payload JSONB,
timestamp TIMESTAMPTZ NOT NULL DEFAULT NOW(),
"actorId" VARCHAR(255),
"actorType" VARCHAR(50),
"actorData" JSONB,
metadata JSONB
);
-- Recommended indexes
CREATE INDEX idx_audit_logs_type ON audit_logs(type);
CREATE INDEX idx_audit_logs_timestamp ON audit_logs(timestamp);
CREATE INDEX idx_audit_logs_actor_id ON audit_logs("actorId");
CREATE INDEX idx_audit_logs_entity_id ON audit_logs("entityId");
与 @geekmidas/ 构建
审计包与 @geekmidas/constructs 结束点 :
import { e } from '@geekmidas/constructs/endpoints';
const endpoint = e
.post('/users')
.body(UserSchema)
.output(UserResponseSchema)
.audit([
{
type: 'user.created',
payload: (response) => ({
userId: response.id,
email: response.email,
}),
},
])
.handle(async ({ body, auditor }) => {
// Audits are automatically recorded and flushed
return { id: '123', ...body };
});
最佳做法
- 预先界定所有审计行动: 为您的应用程序创建所有可能的审计行动的联盟类型
- 使用交易: 汇总数据库操作和交易审计,以确保一致性
- 包含实体引用: 使用
entityId财务报告和审定财务报表table选项以方便查询 - 添加请求上下文: 在元数据中包含请求的ID,端点和IP
- 使用有意义的类型: 名称具有域名背景的审计类型(例如,
order.shipped没有update(中文(简体) )
许可证
麻省理工学院