@contractspec/module.audit-trail 1.44.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chaman Ventures, SASU
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,113 @@
+# @contractspec/module.audit-trail
+
+Website: https://contractspec.io/
+
+
+Audit trail module for tracking and querying system events in ContractSpec applications.
+
+## Purpose
+
+Provides a complete audit logging solution that captures, stores, and queries audit events. Integrates with the event bus to automatically capture domain events and exposes a query API for compliance and debugging.
+
+## Features
+
+- **Event Capture**: Automatic capture of events from the event bus
+- **Persistent Storage**: Multiple storage adapters (Prisma, append-only log)
+- **Rich Querying**: Filter by actor, target, organization, time range
+- **Retention Policies**: Configurable retention and archival
+- **Export**: Export audit logs for compliance reporting
+
+## Installation
+
+```bash
+bun add @contractspec/module.audit-trail
+```
+
+## Usage
+
+### Entity Specs (for schema generation)
+
+```typescript
+import { auditTrailSchemaContribution } from '@contractspec/module.audit-trail/entities';
+
+// Use in schema composition
+const config = {
+  modules: [auditTrailSchemaContribution],
+};
+```
+
+### Set Up Audit Capture
+
+```typescript
+import { createAuditCapture, PrismaAuditStorage } from '@contractspec/module.audit-trail';
+import { prisma } from './db';
+
+// Create storage adapter
+const storage = new PrismaAuditStorage(prisma);
+
+// Create audit capture (connects to event bus)
+const auditCapture = createAuditCapture({
+  bus: eventBus,
+  storage,
+  filters: {
+    // Only audit events with audit:true tag or from specific domains
+    domains: ['identity', 'billing', 'security'],
+  },
+});
+
+// Start capturing
+auditCapture.start();
+```
+
+### Query Audit Logs
+
+```typescript
+import { AuditLogService } from '@contractspec/module.audit-trail';
+
+const service = new AuditLogService(storage);
+
+// Query by actor
+const userActions = await service.query({
+  actorId: 'user-123',
+  from: new Date('2024-01-01'),
+  to: new Date(),
+  limit: 100,
+});
+
+// Query by target
+const resourceChanges = await service.query({
+  targetId: 'project-456',
+  eventName: 'project.*',
+});
+
+// Export for compliance
+const report = await service.export({
+  orgId: 'org-789',
+  from: new Date('2024-01-01'),
+  to: new Date('2024-12-31'),
+  format: 'csv',
+});
+```
+
+## Entity Overview
+
+| Entity | Description |
+|--------|-------------|
+| AuditLog | Main audit log entry |
+| AuditLogArchive | Archived logs for retention |
+
+## Retention
+
+Configure retention policies:
+
+```typescript
+const retention = new RetentionPolicy({
+  // Keep detailed logs for 90 days
+  hotRetentionDays: 90,
+  // Archive for 7 years (compliance)
+  archiveRetentionDays: 2555,
+  // Run cleanup daily at 3 AM
+  cleanupSchedule: '0 3 * * *',
+});
+```
+

package/dist/audit-trail.feature.d.ts

@@ -0,0 +1,12 @@
+import { FeatureModuleSpec } from "@contractspec/lib.contracts";
+
+//#region src/audit-trail.feature.d.ts
+
+/**
+ * Audit Trail feature module that bundles audit log querying,
+ * export, and statistics capabilities.
+ */
+declare const AuditTrailFeature: FeatureModuleSpec;
+//#endregion
+export { AuditTrailFeature };
+//# sourceMappingURL=audit-trail.feature.d.ts.map

package/dist/audit-trail.feature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-trail.feature.d.ts","names":[],"sources":["../src/audit-trail.feature.ts"],"sourcesContent":[],"mappings":";;;;;;;;cAWa,mBAAmB"}

package/dist/audit-trail.feature.js

@@ -0,0 +1,59 @@
+//#region src/audit-trail.feature.ts
+/**
+* Audit Trail feature module that bundles audit log querying,
+* export, and statistics capabilities.
+*/
+const AuditTrailFeature = {
+	meta: {
+		key: "audit-trail",
+		title: "Audit Trail",
+		description: "Audit logging, querying, export, and compliance reporting",
+		domain: "platform",
+		version: 1,
+		owners: ["@platform.audit-trail"],
+		tags: [
+			"audit",
+			"compliance",
+			"logging",
+			"security"
+		],
+		stability: "stable"
+	},
+	operations: [
+		{
+			key: "audit.logs.export",
+			version: 1
+		},
+		{
+			key: "audit.logs.query",
+			version: 1
+		},
+		{
+			key: "audit.logs.get",
+			version: 1
+		},
+		{
+			key: "audit.trace.get",
+			version: 1
+		},
+		{
+			key: "audit.stats",
+			version: 1
+		}
+	],
+	events: [],
+	presentations: [],
+	opToPresentation: [],
+	presentationsTargets: [],
+	capabilities: {
+		provides: [{
+			key: "audit-trail",
+			version: 1
+		}],
+		requires: []
+	}
+};
+
+//#endregion
+export { AuditTrailFeature };
+//# sourceMappingURL=audit-trail.feature.js.map

package/dist/audit-trail.feature.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-trail.feature.js","names":["AuditTrailFeature: FeatureModuleSpec"],"sources":["../src/audit-trail.feature.ts"],"sourcesContent":["/**\n * Audit Trail Feature Module Specification\n *\n * Defines the feature module for audit logging and compliance.\n */\nimport type { FeatureModuleSpec } from '@contractspec/lib.contracts';\n\n/**\n * Audit Trail feature module that bundles audit log querying,\n * export, and statistics capabilities.\n */\nexport const AuditTrailFeature: FeatureModuleSpec = {\n  meta: {\n    key: 'audit-trail',\n    title: 'Audit Trail',\n    description: 'Audit logging, querying, export, and compliance reporting',\n    domain: 'platform',\n    version: 1,\n    owners: ['@platform.audit-trail'],\n    tags: ['audit', 'compliance', 'logging', 'security'],\n    stability: 'stable',\n  },\n\n  // All contract operations included in this feature\n  operations: [\n    { key: 'audit.logs.export', version: 1 },\n    { key: 'audit.logs.query', version: 1 },\n    { key: 'audit.logs.get', version: 1 },\n    { key: 'audit.trace.get', version: 1 },\n    { key: 'audit.stats', version: 1 },\n  ],\n\n  // No events for this feature - it consumes events, doesn't emit them\n  events: [],\n\n  // No presentations for this module feature\n  presentations: [],\n  opToPresentation: [],\n  presentationsTargets: [],\n\n  // Capability definitions\n  capabilities: {\n    provides: [{ key: 'audit-trail', version: 1 }],\n    requires: [],\n  },\n};\n"],"mappings":";;;;;AAWA,MAAaA,oBAAuC;CAClD,MAAM;EACJ,KAAK;EACL,OAAO;EACP,aAAa;EACb,QAAQ;EACR,SAAS;EACT,QAAQ,CAAC,wBAAwB;EACjC,MAAM;GAAC;GAAS;GAAc;GAAW;GAAW;EACpD,WAAW;EACZ;CAGD,YAAY;EACV;GAAE,KAAK;GAAqB,SAAS;GAAG;EACxC;GAAE,KAAK;GAAoB,SAAS;GAAG;EACvC;GAAE,KAAK;GAAkB,SAAS;GAAG;EACrC;GAAE,KAAK;GAAmB,SAAS;GAAG;EACtC;GAAE,KAAK;GAAe,SAAS;GAAG;EACnC;CAGD,QAAQ,EAAE;CAGV,eAAe,EAAE;CACjB,kBAAkB,EAAE;CACpB,sBAAsB,EAAE;CAGxB,cAAc;EACZ,UAAU,CAAC;GAAE,KAAK;GAAe,SAAS;GAAG,CAAC;EAC9C,UAAU,EAAE;EACb;CACF"}