@bajustone/fortress 1.0.0-rc.1

package/dist/plugins/audit-log.cjs

@@ -0,0 +1,493 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/plugins/audit-log/index.ts
+var audit_log_exports = {};
+__export(audit_log_exports, {
+  auditLog: () => auditLog
+});
+module.exports = __toCommonJS(audit_log_exports);
+async function sha256Hex(input) {
+  const data = new TextEncoder().encode(input);
+  const buffer = await crypto.subtle.digest("SHA-256", data);
+  return Array.from(new Uint8Array(buffer)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+var auditWriteChains = /* @__PURE__ */ new WeakMap();
+function withAuditChainLock(db, fn) {
+  const run = () => db.transaction(async (tx) => {
+    if (tx.dialect === "pg") {
+      if (!tx.rawQuery)
+        throw new Error("PostgreSQL audit hash chains require rawQuery advisory-lock support");
+      await tx.rawQuery("SELECT pg_advisory_xact_lock(117993, 1)");
+    }
+    return fn(tx);
+  });
+  if (db.dialect === "pg")
+    return run();
+  const previous = auditWriteChains.get(db) ?? Promise.resolve();
+  const result = previous.then(run, run);
+  auditWriteChains.set(db, result.then(() => void 0, () => void 0));
+  return result;
+}
+var AUDIT_EXPORT_COLUMNS = [
+  "id",
+  "timestamp",
+  "eventType",
+  "actorId",
+  "actorType",
+  "targetId",
+  "targetType",
+  "ipAddress",
+  "userAgent",
+  "outcome",
+  "metadata",
+  "previousHash",
+  "createdAt"
+];
+var CSV_SPECIAL_RE = /[",\n\r]/;
+var CSV_FORMULA_PREFIX_RE = /^[=+\-@\t\r]/;
+function toCsvCell(value) {
+  if (value == null)
+    return "";
+  const raw = value instanceof Date ? value.toISOString() : String(value);
+  const str = CSV_FORMULA_PREFIX_RE.test(raw) ? `'${raw}` : raw;
+  if (CSV_SPECIAL_RE.test(str))
+    return `"${str.replace(/"/g, '""')}"`;
+  return str;
+}
+function entriesToCsv(entries) {
+  const header = AUDIT_EXPORT_COLUMNS.join(",");
+  const rows = entries.map((entry) => {
+    const record = entry;
+    return AUDIT_EXPORT_COLUMNS.map((column) => toCsvCell(record[column])).join(",");
+  });
+  return [header, ...rows].join("\n");
+}
+async function computeEntryHash(entry) {
+  const values = AUDIT_EXPORT_COLUMNS.map((column) => {
+    const value = entry[column];
+    return value instanceof Date ? value.toISOString() : value;
+  });
+  return sha256Hex(JSON.stringify(values));
+}
+async function inspectChain(entries, anchor) {
+  if (entries.length === 0) {
+    const brokenLinks2 = [];
+    if (!anchor) {
+      brokenLinks2.push({
+        entryId: "anchor",
+        expected: "persistent zero-entry audit-chain anchor",
+        actual: null
+      });
+    } else if (anchor.entryCount !== 0 || anchor.lastHash !== null) {
+      brokenLinks2.push({
+        entryId: "anchor",
+        expected: "entry_count=0 and last_hash=null",
+        actual: `${anchor.entryCount}:${anchor.lastHash ?? "null"}`
+      });
+    }
+    return { tail: null, brokenLinks: brokenLinks2 };
+  }
+  const hashes = /* @__PURE__ */ new Map();
+  const duplicateHashes = /* @__PURE__ */ new Set();
+  for (const entry of entries) {
+    const hash = await computeEntryHash(entry);
+    if (hashes.has(hash))
+      duplicateHashes.add(hash);
+    hashes.set(hash, entry);
+  }
+  const brokenLinks = [];
+  const roots = entries.filter((entry) => entry.previousHash == null);
+  for (const entry of entries) {
+    if (entry.previousHash != null && !hashes.has(entry.previousHash)) {
+      brokenLinks.push({
+        entryId: entry.id,
+        expected: "hash of an existing predecessor",
+        actual: entry.previousHash
+      });
+    }
+  }
+  for (const hash of duplicateHashes) {
+    brokenLinks.push({
+      entryId: hashes.get(hash).id,
+      expected: "unique entry hash",
+      actual: hash
+    });
+  }
+  if (roots.length !== 1) {
+    for (const root of roots.slice(1)) {
+      brokenLinks.push({
+        entryId: root.id,
+        expected: "exactly one chain root",
+        actual: null
+      });
+    }
+    if (roots.length === 0) {
+      brokenLinks.push({
+        entryId: entries[0].id,
+        expected: "one entry with previousHash=null",
+        actual: entries[0].previousHash
+      });
+    }
+  }
+  const byPreviousHash = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    if (entry.previousHash == null)
+      continue;
+    const successors = byPreviousHash.get(entry.previousHash) ?? [];
+    successors.push(entry);
+    byPreviousHash.set(entry.previousHash, successors);
+  }
+  const visited = /* @__PURE__ */ new Set();
+  let current = roots.length === 1 ? roots[0] : null;
+  let tail = null;
+  while (current && !visited.has(current)) {
+    visited.add(current);
+    tail = current;
+    const hash = await computeEntryHash(current);
+    const successors = byPreviousHash.get(hash) ?? [];
+    if (successors.length > 1) {
+      for (const successor of successors.slice(1)) {
+        brokenLinks.push({
+          entryId: successor.id,
+          expected: "a predecessor with only one successor",
+          actual: successor.previousHash
+        });
+      }
+    }
+    current = successors.length === 1 ? successors[0] : null;
+  }
+  for (const entry of entries) {
+    if (!visited.has(entry)) {
+      brokenLinks.push({
+        entryId: entry.id,
+        expected: "entry reachable from the chain root",
+        actual: entry.previousHash
+      });
+    }
+  }
+  if (!anchor) {
+    brokenLinks.push({
+      entryId: tail?.id ?? entries[0].id,
+      expected: "persisted terminal audit-chain anchor",
+      actual: null
+    });
+  } else {
+    if (anchor.entryCount !== entries.length) {
+      brokenLinks.push({
+        entryId: tail?.id ?? entries[0].id,
+        expected: `anchor entry count ${anchor.entryCount}`,
+        actual: String(entries.length)
+      });
+    }
+    if (tail) {
+      const tailHash = await computeEntryHash(tail);
+      if (anchor.lastHash !== tailHash) {
+        brokenLinks.push({
+          entryId: tail.id,
+          expected: anchor.lastHash ?? "non-null terminal hash",
+          actual: tailHash
+        });
+      }
+    }
+  }
+  return { tail, brokenLinks };
+}
+async function queryAuditLog(db, options) {
+  const where = [];
+  if (options?.userId != null)
+    where.push({ field: "actorId", operator: "=", value: options.userId });
+  if (options?.eventType)
+    where.push({ field: "eventType", operator: "=", value: options.eventType });
+  if (options?.from)
+    where.push({ field: "timestamp", operator: ">=", value: options.from });
+  if (options?.to)
+    where.push({ field: "timestamp", operator: "<=", value: options.to });
+  return db.findMany({
+    model: "audit_log",
+    where: where.length > 0 ? where : void 0,
+    limit: options?.limit,
+    offset: options?.offset,
+    sortBy: { field: "timestamp", direction: "desc" }
+  });
+}
+function auditLog(config = {}) {
+  const allowedEvents = config.events ?? null;
+  const hashChain = config.hashChain ?? false;
+  function shouldLog(eventType) {
+    if (!allowedEvents)
+      return true;
+    return allowedEvents.includes(eventType);
+  }
+  async function readChainAnchor(db) {
+    return db.findOne({
+      model: "audit_chain_state",
+      where: [{ field: "id", operator: "=", value: "1" }]
+    });
+  }
+  async function writeEntry(db, entry) {
+    if (!hashChain) {
+      await db.create({ model: "audit_log", data: { ...entry, previousHash: null } });
+      return;
+    }
+    await withAuditChainLock(db, async (tx) => {
+      const anchor = await readChainAnchor(tx);
+      if (!anchor || !Number.isInteger(anchor.entryCount) || anchor.entryCount < 0 || anchor.entryCount === 0 !== (anchor.lastHash === null)) {
+        throw new Error("Cannot append without a valid audit hash-chain anchor");
+      }
+      if (anchor.entryCount === 0) {
+        const existing = await tx.findMany({
+          model: "audit_log",
+          limit: 1
+        });
+        if (existing.length > 0) {
+          throw new Error(
+            "Cannot append to an unchained legacy audit log; call rebaselineChain() first"
+          );
+        }
+      }
+      const created = await tx.create({
+        model: "audit_log",
+        data: { ...entry, previousHash: anchor.lastHash }
+      });
+      const lastHash = await computeEntryHash(created);
+      const updated = await tx.update({
+        model: "audit_chain_state",
+        where: [{ field: "id", operator: "=", value: anchor.id }],
+        data: { lastHash, entryCount: anchor.entryCount + 1, updatedAt: /* @__PURE__ */ new Date() }
+      });
+      if (!updated)
+        throw new Error("Audit hash-chain anchor disappeared during append");
+    });
+  }
+  async function writeAuthEntry(db, entry, logger) {
+    try {
+      await writeEntry(db, entry);
+    } catch (error) {
+      try {
+        logger?.error({ plugin: "audit-log", error }, "audit log write failed");
+      } catch {
+      }
+    }
+  }
+  return {
+    name: "audit-log",
+    models: [{
+      name: "audit_log",
+      fields: {
+        id: { type: "string", required: true },
+        timestamp: { type: "date", required: true },
+        eventType: { type: "string", required: true },
+        actorId: { type: "string" },
+        actorType: { type: "string", required: true },
+        targetId: { type: "string" },
+        targetType: { type: "string" },
+        ipAddress: { type: "string" },
+        userAgent: { type: "string" },
+        outcome: { type: "string", required: true },
+        metadata: { type: "string" },
+        previousHash: { type: "string" },
+        createdAt: { type: "date", required: true }
+      }
+    }, {
+      name: "audit_chain_state",
+      fields: {
+        id: { type: "string", required: true },
+        lastHash: { type: "string" },
+        entryCount: { type: "number", required: true },
+        updatedAt: { type: "date", required: true }
+      }
+    }],
+    hooks: {
+      async afterLogin(ctx, result) {
+        if (!shouldLog("LOGIN_SUCCESS"))
+          return result;
+        await writeAuthEntry(ctx.db, {
+          timestamp: /* @__PURE__ */ new Date(),
+          eventType: "LOGIN_SUCCESS",
+          actorId: result.user.id,
+          actorType: "user",
+          targetId: null,
+          targetType: null,
+          ipAddress: ctx.meta?.ipAddress ?? null,
+          userAgent: ctx.meta?.userAgent ?? null,
+          outcome: "success",
+          metadata: null
+        }, ctx.config.logger);
+        return result;
+      },
+      async onLoginFailure(ctx) {
+        if (!shouldLog("LOGIN_FAILURE"))
+          return;
+        await writeAuthEntry(ctx.db, {
+          timestamp: /* @__PURE__ */ new Date(),
+          eventType: "LOGIN_FAILURE",
+          actorId: null,
+          actorType: "anonymous",
+          targetId: null,
+          targetType: null,
+          ipAddress: null,
+          userAgent: null,
+          outcome: "failure",
+          metadata: JSON.stringify({ identifier: ctx.identifier, error: ctx.error.message })
+        }, ctx.config.logger);
+      },
+      async beforeLogout(ctx) {
+        if (!shouldLog("LOGOUT"))
+          return;
+        await writeAuthEntry(ctx.db, {
+          timestamp: /* @__PURE__ */ new Date(),
+          eventType: "LOGOUT",
+          actorId: null,
+          actorType: "user",
+          targetId: null,
+          targetType: null,
+          ipAddress: ctx.meta?.ipAddress ?? null,
+          userAgent: ctx.meta?.userAgent ?? null,
+          outcome: "success",
+          metadata: null
+        }, ctx.config.logger);
+      },
+      async afterRegister(ctx, user) {
+        if (!shouldLog("REGISTER"))
+          return;
+        await writeAuthEntry(ctx.db, {
+          timestamp: /* @__PURE__ */ new Date(),
+          eventType: "REGISTER",
+          actorId: user.id,
+          actorType: "user",
+          targetId: user.id,
+          targetType: "user",
+          ipAddress: ctx.meta?.ipAddress ?? null,
+          userAgent: ctx.meta?.userAgent ?? null,
+          outcome: "success",
+          metadata: null
+        }, ctx.config.logger);
+      },
+      async afterTokenRefresh(ctx, result) {
+        if (!shouldLog("TOKEN_REFRESH"))
+          return result;
+        await writeAuthEntry(ctx.db, {
+          timestamp: /* @__PURE__ */ new Date(),
+          eventType: "TOKEN_REFRESH",
+          actorId: null,
+          actorType: "user",
+          targetId: null,
+          targetType: null,
+          ipAddress: ctx.meta?.ipAddress ?? null,
+          userAgent: ctx.meta?.userAgent ?? null,
+          outcome: "success",
+          metadata: null
+        }, ctx.config.logger);
+        return result;
+      }
+    },
+    methods: (ctx) => ({
+      async getAuditLog(options) {
+        return queryAuditLog(ctx.db, options);
+      },
+      async logCustomEvent(event) {
+        const eventType = event.eventType;
+        if (allowedEvents && !allowedEvents.includes(eventType))
+          return;
+        await writeEntry(ctx.db, {
+          timestamp: /* @__PURE__ */ new Date(),
+          eventType,
+          actorId: event.actorId ?? null,
+          actorType: event.actorType ?? "system",
+          targetId: event.targetId ?? null,
+          targetType: event.targetType ?? null,
+          ipAddress: event.ipAddress ?? null,
+          userAgent: event.userAgent ?? null,
+          outcome: event.outcome ?? "success",
+          metadata: event.metadata ? JSON.stringify(event.metadata) : null
+        });
+      },
+      async rebaselineChain() {
+        if (!hashChain)
+          throw new Error("Enable hashChain before rebaselining the audit log");
+        return withAuditChainLock(ctx.db, async (tx) => {
+          const anchor = await readChainAnchor(tx);
+          if (!anchor)
+            throw new Error("Cannot rebaseline without the persistent audit hash-chain anchor");
+          if (anchor.entryCount !== 0 || anchor.lastHash !== null) {
+            throw new Error("Cannot rebaseline an audit hash chain that has already been initialized");
+          }
+          const entries = await tx.findMany({ model: "audit_log" });
+          if (entries.some((entry) => entry.previousHash !== null)) {
+            throw new Error("Cannot rebaseline a partially or previously chained audit log");
+          }
+          entries.sort((left, right) => {
+            const timeDifference = left.createdAt.getTime() - right.createdAt.getTime();
+            if (timeDifference !== 0)
+              return timeDifference;
+            return left.id < right.id ? -1 : left.id > right.id ? 1 : 0;
+          });
+          let previousHash = null;
+          const rebaselined = [];
+          for (const entry of entries) {
+            const updated = await tx.update({
+              model: "audit_log",
+              where: [{ field: "id", operator: "=", value: entry.id }],
+              data: { previousHash }
+            });
+            if (!updated)
+              throw new Error(`Audit entry ${entry.id} disappeared during rebaseline`);
+            rebaselined.push(updated);
+            previousHash = await computeEntryHash(updated);
+          }
+          const updatedAt = /* @__PURE__ */ new Date();
+          const updatedAnchor = await tx.update({
+            model: "audit_chain_state",
+            where: [{ field: "id", operator: "=", value: anchor.id }],
+            data: { lastHash: previousHash, entryCount: entries.length, updatedAt }
+          });
+          if (!updatedAnchor)
+            throw new Error("Audit hash-chain anchor disappeared during rebaseline");
+          const { brokenLinks } = await inspectChain(rebaselined, updatedAnchor);
+          if (brokenLinks.length > 0)
+            throw new Error("Rebaselined audit hash chain failed verification");
+          return { valid: true, totalEntries: entries.length, brokenLinks: [] };
+        });
+      },
+      async exportEntries(format = "json", options) {
+        const entries = await queryAuditLog(ctx.db, options);
+        if (format === "csv")
+          return entriesToCsv(entries);
+        return JSON.stringify(entries, null, 2);
+      },
+      async verifyChain() {
+        return withAuditChainLock(ctx.db, async (tx) => {
+          const entries = await tx.findMany({ model: "audit_log" });
+          const anchor = await readChainAnchor(tx);
+          const { brokenLinks } = await inspectChain(entries, anchor);
+          return {
+            valid: brokenLinks.length === 0,
+            totalEntries: entries.length,
+            brokenLinks
+          };
+        });
+      }
+    })
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  auditLog
+});

package/dist/plugins/audit-log.d.cts

@@ -0,0 +1,86 @@
+import { F as FortressPlugin } from '../config-GtlVt6ZD.cjs';
+import '../index-CxEkfCA0.cjs';
+import '../jwt.cjs';
+import '../types-et0R8tsC.cjs';
+import '../auth-service-BcyQ2PuZ.cjs';
+
+/**
+ * Append-only audit log plugin for fortress.
+ *
+ * Captures auth and IAM lifecycle events into the `fortress_audit_log` table
+ * with a tamper-evident hash chain (each entry links to the previous entry's
+ * hash). Configurable event filtering and a query API for compliance reads.
+ *
+ * @module
+ */
+
+interface AuditLogConfig {
+    /** Events to capture. Default: all. */
+    events?: AuditEventType[];
+    /** Enable hash chain for tamper detection. Default: false. */
+    hashChain?: boolean;
+}
+type AuditEventType = 'LOGIN_SUCCESS' | 'LOGIN_FAILURE' | 'LOGIN_PENDING' | 'MFA_VERIFY_SUCCESS' | 'MFA_VERIFY_FAILURE' | 'LOGOUT' | 'REGISTER' | 'TOKEN_REFRESH' | 'TOKEN_REUSE' | 'ROLE_CREATED' | 'ROLE_DELETED' | 'ROLE_UPDATED' | 'ROLE_BOUND' | 'ROLE_UNBOUND' | 'ROLE_PERMISSION_ADDED' | 'ROLE_PERMISSION_REMOVED' | 'PERMISSION_CHANGED' | 'PERMISSION_CREATED' | 'PERMISSION_DELETED' | 'GROUP_CREATED' | 'GROUP_UPDATED' | 'GROUP_DELETED' | 'GROUP_MEMBER_ADDED' | 'GROUP_MEMBER_REMOVED' | 'SERVICE_ACCOUNT_CREATED' | 'SERVICE_ACCOUNT_UPDATED' | 'SERVICE_ACCOUNT_DELETED';
+interface AuditLogEntry {
+    id: string;
+    timestamp: Date;
+    eventType: AuditEventType;
+    actorId: string | null;
+    actorType: string;
+    targetId: string | null;
+    targetType: string | null;
+    ipAddress: string | null;
+    userAgent: string | null;
+    outcome: string;
+    metadata: string | null;
+    previousHash: string | null;
+    createdAt: Date;
+}
+interface AuditLogQueryOptions {
+    userId?: string;
+    eventType?: AuditEventType;
+    from?: Date;
+    to?: Date;
+    limit?: number;
+    offset?: number;
+}
+interface CustomAuditEvent {
+    eventType: string;
+    actorId?: string | null;
+    actorType?: string;
+    targetId?: string | null;
+    targetType?: string | null;
+    outcome?: string;
+    metadata?: Record<string, unknown> | null;
+    ipAddress?: string | null;
+    userAgent?: string | null;
+}
+interface ChainVerificationResult {
+    valid: boolean;
+    totalEntries: number;
+    brokenLinks: {
+        entryId: string;
+        expected: string;
+        actual: string | null;
+    }[];
+}
+/** Serialization formats supported by {@link AuditLogMethods.exportEntries}. */
+type AuditLogExportFormat = 'json' | 'csv';
+interface AuditLogMethods {
+    getAuditLog: (options?: AuditLogQueryOptions) => Promise<AuditLogEntry[]>;
+    logCustomEvent: (event: CustomAuditEvent) => Promise<void>;
+    verifyChain: () => Promise<ChainVerificationResult>;
+    /** Transactionally convert an unchained legacy log into a hash chain. */
+    rebaselineChain: () => Promise<ChainVerificationResult>;
+    exportEntries: (format?: AuditLogExportFormat, options?: AuditLogQueryOptions) => Promise<string>;
+}
+/**
+ * Audit log plugin factory. Returns a {@link FortressPlugin} that records
+ * auth and IAM lifecycle events into an append-only table with a
+ * tamper-evident hash chain, plus a query API for compliance reads.
+ */
+declare function auditLog(config?: AuditLogConfig): FortressPlugin & {
+    readonly name: 'audit-log';
+};
+
+export { type AuditEventType, type AuditLogConfig, type AuditLogEntry, type AuditLogExportFormat, type AuditLogMethods, type AuditLogQueryOptions, type ChainVerificationResult, type CustomAuditEvent, auditLog };

package/dist/plugins/audit-log.d.ts

@@ -0,0 +1,86 @@
+import { F as FortressPlugin } from '../config-B2366s_G.js';
+import '../index-CxEkfCA0.js';
+import '../jwt.js';
+import '../types-et0R8tsC.js';
+import '../auth-service-BkzZkWfH.js';
+
+/**
+ * Append-only audit log plugin for fortress.
+ *
+ * Captures auth and IAM lifecycle events into the `fortress_audit_log` table
+ * with a tamper-evident hash chain (each entry links to the previous entry's
+ * hash). Configurable event filtering and a query API for compliance reads.
+ *
+ * @module
+ */
+
+interface AuditLogConfig {
+    /** Events to capture. Default: all. */
+    events?: AuditEventType[];
+    /** Enable hash chain for tamper detection. Default: false. */
+    hashChain?: boolean;
+}
+type AuditEventType = 'LOGIN_SUCCESS' | 'LOGIN_FAILURE' | 'LOGIN_PENDING' | 'MFA_VERIFY_SUCCESS' | 'MFA_VERIFY_FAILURE' | 'LOGOUT' | 'REGISTER' | 'TOKEN_REFRESH' | 'TOKEN_REUSE' | 'ROLE_CREATED' | 'ROLE_DELETED' | 'ROLE_UPDATED' | 'ROLE_BOUND' | 'ROLE_UNBOUND' | 'ROLE_PERMISSION_ADDED' | 'ROLE_PERMISSION_REMOVED' | 'PERMISSION_CHANGED' | 'PERMISSION_CREATED' | 'PERMISSION_DELETED' | 'GROUP_CREATED' | 'GROUP_UPDATED' | 'GROUP_DELETED' | 'GROUP_MEMBER_ADDED' | 'GROUP_MEMBER_REMOVED' | 'SERVICE_ACCOUNT_CREATED' | 'SERVICE_ACCOUNT_UPDATED' | 'SERVICE_ACCOUNT_DELETED';
+interface AuditLogEntry {
+    id: string;
+    timestamp: Date;
+    eventType: AuditEventType;
+    actorId: string | null;
+    actorType: string;
+    targetId: string | null;
+    targetType: string | null;
+    ipAddress: string | null;
+    userAgent: string | null;
+    outcome: string;
+    metadata: string | null;
+    previousHash: string | null;
+    createdAt: Date;
+}
+interface AuditLogQueryOptions {
+    userId?: string;
+    eventType?: AuditEventType;
+    from?: Date;
+    to?: Date;
+    limit?: number;
+    offset?: number;
+}
+interface CustomAuditEvent {
+    eventType: string;
+    actorId?: string | null;
+    actorType?: string;
+    targetId?: string | null;
+    targetType?: string | null;
+    outcome?: string;
+    metadata?: Record<string, unknown> | null;
+    ipAddress?: string | null;
+    userAgent?: string | null;
+}
+interface ChainVerificationResult {
+    valid: boolean;
+    totalEntries: number;
+    brokenLinks: {
+        entryId: string;
+        expected: string;
+        actual: string | null;
+    }[];
+}
+/** Serialization formats supported by {@link AuditLogMethods.exportEntries}. */
+type AuditLogExportFormat = 'json' | 'csv';
+interface AuditLogMethods {
+    getAuditLog: (options?: AuditLogQueryOptions) => Promise<AuditLogEntry[]>;
+    logCustomEvent: (event: CustomAuditEvent) => Promise<void>;
+    verifyChain: () => Promise<ChainVerificationResult>;
+    /** Transactionally convert an unchained legacy log into a hash chain. */
+    rebaselineChain: () => Promise<ChainVerificationResult>;
+    exportEntries: (format?: AuditLogExportFormat, options?: AuditLogQueryOptions) => Promise<string>;
+}
+/**
+ * Audit log plugin factory. Returns a {@link FortressPlugin} that records
+ * auth and IAM lifecycle events into an append-only table with a
+ * tamper-evident hash chain, plus a query API for compliance reads.
+ */
+declare function auditLog(config?: AuditLogConfig): FortressPlugin & {
+    readonly name: 'audit-log';
+};
+
+export { type AuditEventType, type AuditLogConfig, type AuditLogEntry, type AuditLogExportFormat, type AuditLogMethods, type AuditLogQueryOptions, type ChainVerificationResult, type CustomAuditEvent, auditLog };