@contractspec/module.audit-trail 1.56.1 → 1.58.0

package/dist/browser/index.js

@@ -0,0 +1,474 @@
+// src/audit-trail.feature.ts
+import { defineFeature } from "@contractspec/lib.contracts";
+var AuditTrailFeature = defineFeature({
+  meta: {
+    key: "audit-trail",
+    title: "Audit Trail",
+    description: "Audit logging, querying, export, and compliance reporting",
+    domain: "platform",
+    version: "1.0.0",
+    owners: ["@platform.audit-trail"],
+    tags: ["audit", "compliance", "logging", "security"],
+    stability: "stable"
+  },
+  operations: [
+    { key: "audit.logs.export", version: "1.0.0" },
+    { key: "audit.logs.query", version: "1.0.0" },
+    { key: "audit.logs.get", version: "1.0.0" },
+    { key: "audit.trace.get", version: "1.0.0" },
+    { key: "audit.stats", version: "1.0.0" }
+  ],
+  events: [],
+  presentations: [],
+  opToPresentation: [],
+  presentationsTargets: [],
+  capabilities: {
+    provides: [{ key: "audit-trail", version: "1.0.0" }],
+    requires: []
+  }
+});
+
+// src/contracts/index.ts
+import {
+  defineCommand,
+  defineQuery,
+  defineSchemaModel
+} from "@contractspec/lib.contracts";
+import { ScalarTypeEnum, defineEnum } from "@contractspec/lib.schema";
+var OWNERS = ["platform.audit-trail"];
+var AuditLogModel = defineSchemaModel({
+  name: "AuditLog",
+  description: "Detailed audit log entry",
+  fields: {
+    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    eventName: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    eventVersion: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    payload: { type: ScalarTypeEnum.JSONObject(), isOptional: false },
+    actorId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    actorType: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    actorEmail: { type: ScalarTypeEnum.EmailAddress(), isOptional: true },
+    targetId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    targetType: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    orgId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    traceId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    clientIp: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    occurredAt: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+    recordedAt: { type: ScalarTypeEnum.DateTime(), isOptional: false }
+  }
+});
+var AuditQueryInputModel = defineSchemaModel({
+  name: "AuditQueryInput",
+  description: "Input for querying audit logs",
+  fields: {
+    eventName: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    actorId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    targetId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    targetType: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    orgId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    traceId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    from: { type: ScalarTypeEnum.DateTime(), isOptional: true },
+    to: { type: ScalarTypeEnum.DateTime(), isOptional: true },
+    limit: {
+      type: ScalarTypeEnum.Int_unsecure(),
+      isOptional: true,
+      defaultValue: 100
+    },
+    offset: {
+      type: ScalarTypeEnum.Int_unsecure(),
+      isOptional: true,
+      defaultValue: 0
+    }
+  }
+});
+var AuditQueryOutputModel = defineSchemaModel({
+  name: "AuditQueryOutput",
+  description: "Output from querying audit logs",
+  fields: {
+    logs: { type: AuditLogModel, isArray: true, isOptional: false },
+    total: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    hasMore: { type: ScalarTypeEnum.Boolean(), isOptional: false }
+  }
+});
+var ExportFormatEnum = defineEnum("ExportFormat", [
+  "json",
+  "csv",
+  "parquet"
+]);
+var AuditExportInputModel = defineSchemaModel({
+  name: "AuditExportInput",
+  description: "Input for exporting audit logs",
+  fields: {
+    orgId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    from: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+    to: { type: ScalarTypeEnum.DateTime(), isOptional: false },
+    format: { type: ExportFormatEnum, isOptional: true, defaultValue: "json" },
+    eventNames: {
+      type: ScalarTypeEnum.String_unsecure(),
+      isArray: true,
+      isOptional: true
+    }
+  }
+});
+var ExportStatusEnum = defineEnum("ExportStatus", [
+  "pending",
+  "processing",
+  "completed",
+  "failed"
+]);
+var AuditExportOutputModel = defineSchemaModel({
+  name: "AuditExportOutput",
+  description: "Output from initiating an audit export",
+  fields: {
+    exportId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    status: { type: ExportStatusEnum, isOptional: false },
+    downloadUrl: { type: ScalarTypeEnum.URL(), isOptional: true }
+  }
+});
+var AuditStatsInputModel = defineSchemaModel({
+  name: "AuditStatsInput",
+  description: "Input for getting audit statistics",
+  fields: {
+    orgId: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    from: { type: ScalarTypeEnum.DateTime(), isOptional: true },
+    to: { type: ScalarTypeEnum.DateTime(), isOptional: true }
+  }
+});
+var AuditStatsOutputModel = defineSchemaModel({
+  name: "AuditStatsOutput",
+  description: "Audit log statistics",
+  fields: {
+    totalLogs: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    uniqueActors: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    uniqueTargets: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    eventCounts: { type: ScalarTypeEnum.JSONObject(), isOptional: false }
+  }
+});
+var QueryAuditLogsContract = defineQuery({
+  meta: {
+    key: "audit.logs.query",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["audit", "logs", "query"],
+    description: "Query audit logs with filters.",
+    goal: "Enable searching and filtering of audit history.",
+    context: "Admin dashboard, compliance reporting, debugging."
+  },
+  io: {
+    input: AuditQueryInputModel,
+    output: AuditQueryOutputModel
+  },
+  policy: {
+    auth: "admin"
+  }
+});
+var GetAuditLogContract = defineQuery({
+  meta: {
+    key: "audit.logs.get",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["audit", "logs", "get"],
+    description: "Get a specific audit log by ID.",
+    goal: "View detailed audit log entry.",
+    context: "Log detail view."
+  },
+  io: {
+    input: defineSchemaModel({
+      name: "GetAuditLogInput",
+      fields: {
+        logId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false }
+      }
+    }),
+    output: AuditLogModel
+  },
+  policy: {
+    auth: "admin"
+  }
+});
+var GetAuditTraceContract = defineQuery({
+  meta: {
+    key: "audit.trace.get",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["audit", "trace", "get"],
+    description: "Get all audit logs for a trace.",
+    goal: "View complete request trace for debugging.",
+    context: "Request tracing, debugging."
+  },
+  io: {
+    input: defineSchemaModel({
+      name: "GetAuditTraceInput",
+      fields: {
+        traceId: { type: ScalarTypeEnum.String_unsecure(), isOptional: false }
+      }
+    }),
+    output: defineSchemaModel({
+      name: "GetAuditTraceOutput",
+      fields: {
+        logs: { type: AuditLogModel, isArray: true, isOptional: false }
+      }
+    })
+  },
+  policy: {
+    auth: "admin"
+  }
+});
+var ExportAuditLogsContract = defineCommand({
+  meta: {
+    key: "audit.logs.export",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["audit", "logs", "export"],
+    description: "Export audit logs for compliance reporting.",
+    goal: "Generate audit reports for compliance.",
+    context: "Compliance reporting, external audits."
+  },
+  io: {
+    input: AuditExportInputModel,
+    output: AuditExportOutputModel
+  },
+  policy: {
+    auth: "admin"
+  }
+});
+var GetAuditStatsContract = defineQuery({
+  meta: {
+    key: "audit.stats",
+    version: "1.0.0",
+    stability: "stable",
+    owners: [...OWNERS],
+    tags: ["audit", "stats"],
+    description: "Get audit log statistics.",
+    goal: "Monitor audit activity levels.",
+    context: "Admin dashboard, monitoring."
+  },
+  io: {
+    input: AuditStatsInputModel,
+    output: AuditStatsOutputModel
+  },
+  policy: {
+    auth: "admin"
+  }
+});
+
+// src/entities/index.ts
+import { defineEntity, field, index } from "@contractspec/lib.schema";
+var AuditLogEntity = defineEntity({
+  name: "AuditLog",
+  description: "Audit log entry for tracking system events.",
+  schema: "lssm_audit",
+  map: "audit_log",
+  fields: {
+    id: field.id({ description: "Unique audit log ID" }),
+    eventName: field.string({ description: "Event name/type" }),
+    eventVersion: field.int({ description: "Event version" }),
+    payload: field.json({ description: "Event payload (may be redacted)" }),
+    actorId: field.string({
+      isOptional: true,
+      description: "User/service that triggered the event"
+    }),
+    actorType: field.string({
+      isOptional: true,
+      description: "Actor type (user, system, service)"
+    }),
+    actorEmail: field.string({
+      isOptional: true,
+      description: "Actor email (for searchability)"
+    }),
+    targetId: field.string({
+      isOptional: true,
+      description: "Resource affected by the event"
+    }),
+    targetType: field.string({
+      isOptional: true,
+      description: "Resource type"
+    }),
+    orgId: field.string({
+      isOptional: true,
+      description: "Organization context"
+    }),
+    tenantId: field.string({ isOptional: true, description: "Tenant context" }),
+    traceId: field.string({
+      isOptional: true,
+      description: "Distributed trace ID"
+    }),
+    spanId: field.string({ isOptional: true, description: "Span ID" }),
+    requestId: field.string({ isOptional: true, description: "Request ID" }),
+    sessionId: field.string({ isOptional: true, description: "Session ID" }),
+    clientIp: field.string({
+      isOptional: true,
+      description: "Client IP address"
+    }),
+    userAgent: field.string({
+      isOptional: true,
+      description: "User agent string"
+    }),
+    tags: field.json({
+      isOptional: true,
+      description: "Custom tags for filtering"
+    }),
+    metadata: field.json({
+      isOptional: true,
+      description: "Additional metadata"
+    }),
+    occurredAt: field.dateTime({ description: "When the event occurred" }),
+    recordedAt: field.createdAt({ description: "When the log was recorded" })
+  },
+  indexes: [
+    index.on(["actorId", "occurredAt"]),
+    index.on(["targetId", "occurredAt"]),
+    index.on(["orgId", "occurredAt"]),
+    index.on(["eventName", "occurredAt"]),
+    index.on(["traceId"]),
+    index.on(["occurredAt"])
+  ]
+});
+var AuditLogArchiveEntity = defineEntity({
+  name: "AuditLogArchive",
+  description: "Archived audit logs for long-term retention.",
+  schema: "lssm_audit",
+  map: "audit_log_archive",
+  fields: {
+    id: field.id(),
+    batchId: field.string({ description: "Archive batch ID" }),
+    logCount: field.int({ description: "Number of logs in batch" }),
+    fromDate: field.dateTime({ description: "Earliest log in batch" }),
+    toDate: field.dateTime({ description: "Latest log in batch" }),
+    storagePath: field.string({ description: "Path to archived data" }),
+    storageType: field.string({ description: "Storage type (s3, gcs, file)" }),
+    compressedSize: field.int({ description: "Compressed size in bytes" }),
+    checksum: field.string({ description: "SHA-256 checksum" }),
+    retainUntil: field.dateTime({ description: "When archive can be deleted" }),
+    createdAt: field.createdAt()
+  },
+  indexes: [index.on(["fromDate", "toDate"]), index.on(["retainUntil"])]
+});
+var auditTrailEntities = [AuditLogEntity, AuditLogArchiveEntity];
+var auditTrailSchemaContribution = {
+  moduleId: "@contractspec/module.audit-trail",
+  entities: auditTrailEntities
+};
+
+// src/storage/index.ts
+class InMemoryAuditStorage {
+  records = [];
+  async store(record) {
+    this.records.push(record);
+  }
+  async query(options) {
+    let results = [...this.records];
+    if (options.eventKey) {
+      const pattern = options.eventKey.replace(/\*/g, ".*");
+      const regex = new RegExp(`^${pattern}$`);
+      results = results.filter((r) => regex.test(r.eventKey));
+    }
+    if (options.actorId) {
+      results = results.filter((r) => r.metadata?.actorId === options.actorId);
+    }
+    if (options.targetId) {
+      results = results.filter((r) => r.metadata?.targetId === options.targetId);
+    }
+    if (options.targetType) {
+      results = results.filter((r) => r.metadata?.targetType === options.targetType);
+    }
+    if (options.orgId) {
+      results = results.filter((r) => r.metadata?.orgId === options.orgId);
+    }
+    if (options.traceId) {
+      results = results.filter((r) => r.traceId === options.traceId);
+    }
+    if (options.from) {
+      const fromDate = options.from;
+      results = results.filter((r) => new Date(r.occurredAt) >= fromDate);
+    }
+    if (options.to) {
+      const toDate = options.to;
+      results = results.filter((r) => new Date(r.occurredAt) <= toDate);
+    }
+    const orderBy = options.orderBy ?? "occurredAt";
+    const orderDir = options.orderDir ?? "desc";
+    results.sort((a, b) => {
+      const aTime = orderBy === "occurredAt" ? new Date(a.occurredAt).getTime() : a.recordedAt.getTime();
+      const bTime = orderBy === "occurredAt" ? new Date(b.occurredAt).getTime() : b.recordedAt.getTime();
+      return orderDir === "desc" ? bTime - aTime : aTime - bTime;
+    });
+    const offset = options.offset ?? 0;
+    const limit = options.limit ?? 100;
+    return results.slice(offset, offset + limit);
+  }
+  async count(options) {
+    const results = await this.query({ ...options, limit: Infinity });
+    return results.length;
+  }
+  async getById(id) {
+    return this.records.find((r) => r.id === id) ?? null;
+  }
+  async getByTraceId(traceId) {
+    return this.query({ traceId });
+  }
+  async deleteOlderThan(date) {
+    const before = this.records.length;
+    this.records = this.records.filter((r) => new Date(r.occurredAt) >= date);
+    return before - this.records.length;
+  }
+  getAll() {
+    return [...this.records];
+  }
+  clear() {
+    this.records = [];
+  }
+}
+
+class RetentionPolicy {
+  config;
+  constructor(config) {
+    this.config = config;
+  }
+  getHotCutoff() {
+    const cutoff = new Date;
+    cutoff.setDate(cutoff.getDate() - this.config.hotRetentionDays);
+    return cutoff;
+  }
+  getArchiveCutoff() {
+    if (!this.config.archiveRetentionDays)
+      return null;
+    const cutoff = new Date;
+    cutoff.setDate(cutoff.getDate() - this.config.archiveRetentionDays);
+    return cutoff;
+  }
+  async apply(storage) {
+    const cutoff = this.getHotCutoff();
+    const deletedCount = await storage.deleteOlderThan(cutoff);
+    return { deletedCount };
+  }
+}
+function createInMemoryAuditStorage() {
+  return new InMemoryAuditStorage;
+}
+export {
+  createInMemoryAuditStorage,
+  auditTrailSchemaContribution,
+  auditTrailEntities,
+  RetentionPolicy,
+  QueryAuditLogsContract,
+  InMemoryAuditStorage,
+  GetAuditTraceContract,
+  GetAuditStatsContract,
+  GetAuditLogContract,
+  ExportStatusEnum,
+  ExportFormatEnum,
+  ExportAuditLogsContract,
+  AuditTrailFeature,
+  AuditStatsOutputModel,
+  AuditStatsInputModel,
+  AuditQueryOutputModel,
+  AuditQueryInputModel,
+  AuditLogModel,
+  AuditLogEntity,
+  AuditLogArchiveEntity,
+  AuditExportOutputModel,
+  AuditExportInputModel
+};

package/dist/browser/storage/index.js

@@ -0,0 +1,101 @@
+// src/storage/index.ts
+class InMemoryAuditStorage {
+  records = [];
+  async store(record) {
+    this.records.push(record);
+  }
+  async query(options) {
+    let results = [...this.records];
+    if (options.eventKey) {
+      const pattern = options.eventKey.replace(/\*/g, ".*");
+      const regex = new RegExp(`^${pattern}$`);
+      results = results.filter((r) => regex.test(r.eventKey));
+    }
+    if (options.actorId) {
+      results = results.filter((r) => r.metadata?.actorId === options.actorId);
+    }
+    if (options.targetId) {
+      results = results.filter((r) => r.metadata?.targetId === options.targetId);
+    }
+    if (options.targetType) {
+      results = results.filter((r) => r.metadata?.targetType === options.targetType);
+    }
+    if (options.orgId) {
+      results = results.filter((r) => r.metadata?.orgId === options.orgId);
+    }
+    if (options.traceId) {
+      results = results.filter((r) => r.traceId === options.traceId);
+    }
+    if (options.from) {
+      const fromDate = options.from;
+      results = results.filter((r) => new Date(r.occurredAt) >= fromDate);
+    }
+    if (options.to) {
+      const toDate = options.to;
+      results = results.filter((r) => new Date(r.occurredAt) <= toDate);
+    }
+    const orderBy = options.orderBy ?? "occurredAt";
+    const orderDir = options.orderDir ?? "desc";
+    results.sort((a, b) => {
+      const aTime = orderBy === "occurredAt" ? new Date(a.occurredAt).getTime() : a.recordedAt.getTime();
+      const bTime = orderBy === "occurredAt" ? new Date(b.occurredAt).getTime() : b.recordedAt.getTime();
+      return orderDir === "desc" ? bTime - aTime : aTime - bTime;
+    });
+    const offset = options.offset ?? 0;
+    const limit = options.limit ?? 100;
+    return results.slice(offset, offset + limit);
+  }
+  async count(options) {
+    const results = await this.query({ ...options, limit: Infinity });
+    return results.length;
+  }
+  async getById(id) {
+    return this.records.find((r) => r.id === id) ?? null;
+  }
+  async getByTraceId(traceId) {
+    return this.query({ traceId });
+  }
+  async deleteOlderThan(date) {
+    const before = this.records.length;
+    this.records = this.records.filter((r) => new Date(r.occurredAt) >= date);
+    return before - this.records.length;
+  }
+  getAll() {
+    return [...this.records];
+  }
+  clear() {
+    this.records = [];
+  }
+}
+
+class RetentionPolicy {
+  config;
+  constructor(config) {
+    this.config = config;
+  }
+  getHotCutoff() {
+    const cutoff = new Date;
+    cutoff.setDate(cutoff.getDate() - this.config.hotRetentionDays);
+    return cutoff;
+  }
+  getArchiveCutoff() {
+    if (!this.config.archiveRetentionDays)
+      return null;
+    const cutoff = new Date;
+    cutoff.setDate(cutoff.getDate() - this.config.archiveRetentionDays);
+    return cutoff;
+  }
+  async apply(storage) {
+    const cutoff = this.getHotCutoff();
+    const deletedCount = await storage.deleteOlderThan(cutoff);
+    return { deletedCount };
+  }
+}
+function createInMemoryAuditStorage() {
+  return new InMemoryAuditStorage;
+}
+export {
+  createInMemoryAuditStorage,
+  RetentionPolicy,
+  InMemoryAuditStorage
+};