9.5 KiB
9.5 KiB
@suaveplan/audit-logging - Tamper-proof, GDPR-compliant audit logging: cryptographic chain-integrity, pluggable storage, retention policy, GDPR export, and a rich event taxonomy
Summary
Tamper-proof, GDPR-compliant audit logging for Suaveplan. Provides a cryptographic chain-integrity engine, pluggable storage adapters, GDPR data export, configurable retention policies, and a rich event taxonomy spanning auth, authorization, data access, system, and GDPR events.
Documentation tree
- memory — (no submodules)
- memory — (no submodules)
- storage — (no submodules)
- storage — (no submodules)
- audit-logger — (no submodules)
- audit-logger — (no submodules)
- chain-integrity — (no submodules)
- chain-integrity — (no submodules)
- errors — (no submodules)
- audit-error — (no submodules)
- schemas — (no submodules)
- audit-logging.schemas — (no submodules)
Features
- AuditLogger — orchestrates log, query, verify, export, and retention with injectable dependencies
- Chain integrity — HMAC-SHA256 signed events linked in a tamper-evident chain via
previousHash - MemoryAuditAdapter — full in-memory storage with rich query filtering for tests and development
- GDPR export — Article 15/20 compliant
exportGDPRData()with event summary statistics - Retention policy — archive-before-delete with configurable TTL and location
- Zod schemas — runtime validation for all public types
- OTel instrumentation — counter
audit.events_logged_totalwithevent_typeandseveritylabels - Event bus integration — emits
audit:event:loggedafter each successful log
Installation
bun add @suaveplan/audit-logging
Quick Start
import { AuditLogger, MemoryAuditAdapter, AuditEventType, AuditSeverity } from "@suaveplan/audit-logging";
const logger = new AuditLogger({
storage: new MemoryAuditAdapter(),
secretKey: process.env.AUDIT_SECRET_KEY!,
enableChainIntegrity: true,
});
const event = await logger.log({
type: AuditEventType.AUTH_LOGIN,
severity: AuditSeverity.INFO,
actor: { userId: "user-123", ipAddress: "203.0.113.1" },
target: { type: "session", id: "sess-456" },
});
console.log(event.hash); // hex HMAC-SHA256
// Verify chain integrity
const events = await logger.query({ order: "asc" });
const result = await logger.verifyChainIntegrity(events);
console.log(result.valid); // true
// GDPR export
const gdprExport = await logger.exportGDPRData("user-123");
console.log(gdprExport.summary.totalEvents);
Modules
| Module | Description |
|---|---|
src/core/audit-logger/audit-logger.md |
Main logger class |
src/core/chain-integrity/chain-integrity.md |
HMAC chain signing and verification |
src/adapters/memory-adapter/memory-adapter.md |
In-memory storage adapter |
src/adapters/storage-adapter/storage-adapter.md |
Storage adapter interface |
src/schemas/audit-logging.schemas.md |
Zod validation schemas |
src/errors/audit-error.md |
Error codes and AuditError class |
src/types/audit-logging.types.md |
TypeScript type definitions |
Event Taxonomy
| Category | Events |
|---|---|
| Authentication | auth_login, auth_logout, auth_register, auth_password_change, auth_password_reset, auth_mfa_enable, auth_mfa_disable, auth_session_create, auth_session_revoke, auth_api_key_create, auth_api_key_revoke |
| Authorization | authz_permission_check, authz_permission_grant, authz_permission_revoke, authz_role_assign, authz_role_unassign |
| Data Access | data_create, data_read, data_update, data_delete, data_export, data_import |
| System | system_config_change, system_security_alert, system_rate_limit, system_error |
| GDPR | gdpr_data_export, gdpr_data_delete, gdpr_consent_change |
License
MIT