The Audit Log: Schema, Retention, Export, and Tamper-Evidence

interface AuditEvent {
  id: string;          // application-assigned, opaque
  at: number;          // epoch ms
  actor: string;       // a user id, `service:<id>`, `system`, or an import/merge source
  action: string;      // e.g. "grant.create", "role.update", "directory.import"
  target: string;      // the entity acted on: row id, group id, request id, …
  detail?: unknown;    // action-specific payload (subject, scope, reason, …)
  prevHash?: string;   // present when the hash chain is on, see below
  hash?: string;
}

// An admin page: the last 50 entries touching one grant.
await app.listAuditEvents({ target: grantId, limit: 50 });

// Filters compose: one actor's deletions in a time range.
await app.listAuditEvents({
  actor: "admin-42",
  action: "grant.delete",
  from: quarterStart, // inclusive
  to: quarterEnd,     // exclusive
});

// An export: page the whole log forward with the (at, id) cursor.
let cursor: { at: number; id: string } | undefined;
for (;;) {
  const page = await app.listAuditEvents({ ...(cursor && { cursor }), limit: 1_000 });
  ship(page);
  if (page.length < 1_000) break;
  const last = page[page.length - 1]!;
  cursor = { at: last.at, id: last.id };
}

const app = createApplication({
  catalog,
  storage,
  audit: { hashChain: true },
});

import { verifyAuditChain } from "@alfiz/application";

// Full-log verification: the first hashed entry must be a chain genesis.
const events = await app.listAuditEvents();
const result = verifyAuditChain(events);
// { ok: true, hashed: n }, or { ok: false, index, reason }

// Export-window verification: carry one hash between windows.
verifyAuditChain(page, { priorHash: lastHashOfPreviousWindow });