95 lines
9.5 KiB
Markdown
95 lines
9.5 KiB
Markdown
# @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.
|
|
|
|
<!-- begin:auto-docs -->
|
|
## Documentation tree
|
|
|
|
- [memory](./src/adapters/memory/memory.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [memory](./src/adapters/memory/memory.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [storage](./src/adapters/storage/storage.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [storage](./src/adapters/storage/storage.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [audit-logger](./src/core/audit-logger/audit-logger.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [audit-logger](./src/core/audit-logger/audit-logger.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [chain-integrity](./src/core/chain-integrity/chain-integrity.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [chain-integrity](./src/core/chain-integrity/chain-integrity.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [errors](./src/errors/audit-error.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [audit-error](./src/errors/audit-error.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [schemas](./src/schemas/audit-logging.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [audit-logging.schemas](./src/schemas/audit-logging.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
<!-- end:auto-docs --> - [memory](./src/adapters/memory/memory.md) — <!-- begin:auto-docs --> _(no submodules)_- [storage](./src/adapters/storage/storage.md) — <!-- begin:auto-docs --> _(no submodules)_- [storage](./src/adapters/storage/storage.md) — <!-- begin:auto-docs --> _(no submodules)_- [audit-logger](./src/core/audit-logger/audit-logger.md) — <!-- begin:auto-docs --> _(no submodules)_- [audit-logger](./src/core/audit-logger/audit-logger.md) — <!-- begin:auto-docs --> _(no submodules)_- [chain-integrity](./src/core/chain-integrity/chain-integrity.md) — <!-- begin:auto-docs --> _(no submodules)_- [chain-integrity](./src/core/chain-integrity/chain-integrity.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/audit-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [audit-error](./src/errors/audit-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [schemas](./src/schemas/audit-logging.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [audit-logging.schemas](./src/schemas/audit-logging.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [memory](./src/adapters/memory/memory.md) — <!-- begin:auto-docs --> _(no submodules)_- [storage](./src/adapters/storage/storage.md) — <!-- begin:auto-docs --> _(no submodules)_- [storage](./src/adapters/storage/storage.md) — <!-- begin:auto-docs --> _(no submodules)_- [audit-logger](./src/core/audit-logger/audit-logger.md) — <!-- begin:auto-docs --> _(no submodules)_- [audit-logger](./src/core/audit-logger/audit-logger.md) — <!-- begin:auto-docs --> _(no submodules)_- [chain-integrity](./src/core/chain-integrity/chain-integrity.md) — <!-- begin:auto-docs --> _(no submodules)_- [chain-integrity](./src/core/chain-integrity/chain-integrity.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/audit-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [audit-error](./src/errors/audit-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [schemas](./src/schemas/audit-logging.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [audit-logging.schemas](./src/schemas/audit-logging.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [memory](./src/adapters/memory/memory.md) — <!-- begin:auto-docs --> _(no submodules)_- [storage](./src/adapters/storage/storage.md) — <!-- begin:auto-docs --> _(no submodules)_- [storage](./src/adapters/storage/storage.md) — <!-- begin:auto-docs --> _(no submodules)_- [audit-logger](./src/core/audit-logger/audit-logger.md) — <!-- begin:auto-docs --> _(no submodules)_- [audit-logger](./src/core/audit-logger/audit-logger.md) — <!-- begin:auto-docs --> _(no submodules)_- [chain-integrity](./src/core/chain-integrity/chain-integrity.md) — <!-- begin:auto-docs --> _(no submodules)_- [chain-integrity](./src/core/chain-integrity/chain-integrity.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/audit-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [audit-error](./src/errors/audit-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [schemas](./src/schemas/audit-logging.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [audit-logging.schemas](./src/schemas/audit-logging.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [memory](./src/adapters/memory/memory.md) — <!-- begin:auto-docs --> _(no submodules)_- [storage](./src/adapters/storage/storage.md) — <!-- begin:auto-docs --> _(no submodules)_ - [storage](./src/adapters/storage/storage.md) — <!-- begin:auto-docs --> _(no submodules)_- [audit-logger](./src/core/audit-logger/audit-logger.md) — <!-- begin:auto-docs --> _(no submodules)_ - [audit-logger](./src/core/audit-logger/audit-logger.md) — <!-- begin:auto-docs --> _(no submodules)_- [chain-integrity](./src/core/chain-integrity/chain-integrity.md) — <!-- begin:auto-docs --> _(no submodules)_ - [chain-integrity](./src/core/chain-integrity/chain-integrity.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/audit-error.md) — <!-- begin:auto-docs --> _(no submodules)_ - [audit-error](./src/errors/audit-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [schemas](./src/schemas/audit-logging.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_ - [audit-logging.schemas](./src/schemas/audit-logging.schemas.md) — <!-- begin:auto-docs --> _(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_total` with `event_type` and `severity` labels
|
|
- **Event bus integration** — emits `audit:event:logged` after each successful log
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
bun add @suaveplan/audit-logging
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```ts
|
|
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`](src/core/audit-logger/audit-logger.md) | Main logger class |
|
|
| [`src/core/chain-integrity/chain-integrity.md`](src/core/chain-integrity/chain-integrity.md) | HMAC chain signing and verification |
|
|
| [`src/adapters/memory-adapter/memory-adapter.md`](src/adapters/memory-adapter/memory-adapter.md) | In-memory storage adapter |
|
|
| [`src/adapters/storage-adapter/storage-adapter.md`](src/adapters/storage-adapter/storage-adapter.md) | Storage adapter interface |
|
|
| [`src/schemas/audit-logging.schemas.md`](src/schemas/audit-logging.schemas.md) | Zod validation schemas |
|
|
| [`src/errors/audit-error.md`](src/errors/audit-error.md) | Error codes and AuditError class |
|
|
| [`src/types/audit-logging.types.md`](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
|