davepi-plugin-audit 0.1.0

package/README.md

@@ -0,0 +1,179 @@
+# davepi-plugin-audit
+
+Immutable, append-only audit log for [dAvePi][davepi]. Subscribes to the in-process record event bus and writes one document per CRUD mutation into an auto-registered `audit` collection — with `before` / `after` snapshots, an RFC 6902 [JSON-Patch][rfc6902] `diff`, the actor's `userId`, request `ip` / `userAgent` / `reqId`, and the resource + action. Queryable through the standard REST + GraphQL surface, admin-only cross-tenant list, no API-level writes or deletes.
+
+[davepi]: https://docs.davepi.dev
+[rfc6902]: https://www.rfc-editor.org/rfc/rfc6902
+
+## Install
+
+```bash
+npm install davepi-plugin-audit
+```
+
+Add it to your project's `package.json` under `davepi.plugins`:
+
+```json
+{
+  "davepi": {
+    "plugins": ["davepi-plugin-audit"]
+  }
+}
+```
+
+That's it — on boot, the plugin auto-registers the `audit` schema, attaches a `bus.on('record', ...)` listener, and creates the TTL index on `at`. Your existing schemas need **no changes**: every mutation through REST or GraphQL becomes one audit row.
+
+## Configure
+
+All config is env-driven:
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `AUDIT_ENABLED`         | no | `true` | Master switch. Setting `false` leaves the plugin dormant — no schema registered, no events captured. |
+| `AUDIT_RETENTION_DAYS`  | no | `365` | TTL index on the `at` field. `0` disables retention (audit rows are kept forever) and drops any existing TTL index. |
+| `AUDIT_BULK_BYPASS`     | no | `false` | When `true`, bulk events (`PUT /api/{v}/{path}`, GraphQL `updateMany` / `removeMany`) are NOT audited. See *Storage and bulk events* below. |
+| `AUDIT_INCLUDE`         | no | *(all)* | Comma-separated allowlist of resource names. Empty / unset means "all resources". |
+| `AUDIT_EXCLUDE`         | no | — | Comma-separated denylist. Wins over `AUDIT_INCLUDE` on conflict. |
+| `AUDIT_REDACT`          | no | `password,token,secret` | Comma-separated field names whose values are replaced with `[REDACTED]` in `before` and `after`, recursively. Independent of the `pino` redaction set in the framework's logger. |
+
+Setting `AUDIT_INCLUDE=order,invoice` audits only those two resources. Setting `AUDIT_EXCLUDE=otp` skips the `otp` resource even if it's in the allowlist (denylist wins). Setting `AUDIT_REDACT=ssn,taxId` *replaces* the default redaction list — if you also want `password` redacted, add it back: `AUDIT_REDACT=password,token,secret,ssn,taxId`.
+
+## What gets written
+
+Each row carries these fields (schema declared at boot):
+
+| Field | Description |
+|-------|-------------|
+| `userId`      | The actor's user_id from the mutation's JWT. The tenant the row "belongs to" for read scoping. |
+| `accountId`   | The actor's accountId, when the mutated record had one. |
+| `action`      | One of `created`, `updated`, `deleted`, `transitioned`, or any custom string supplied to `plugin.record({...})`. |
+| `resource`    | The schema `path` (e.g. `order`, `invoice`). |
+| `resourceId`  | The single-record `_id`, or `null` for bulk events. |
+| `before`      | The pre-mutation snapshot (post-redaction). `null` for `created`, populated for `updated` / `deleted`, also populated for `transitioned`. May be `null` on GraphQL paths where the framework doesn't fetch a `before`. |
+| `after`       | The post-mutation snapshot (post-redaction). Populated for `created` / `updated` / `transitioned`, `null` for `deleted` on the hard-delete path. |
+| `diff`        | An RFC 6902 JSON-Patch from `before` to `after`. Stable shape regardless of which side is `null`. |
+| `filter`      | Mongo filter for bulk events (`updateMany`). |
+| `numAffected` | Number of records changed by a bulk event. |
+| `ip`, `userAgent`, `reqId` | Request metadata captured at the producing handler. May be `null` for non-HTTP producers (the MCP tools, internal jobs). |
+| `at`          | Timestamp the row was written (also drives the TTL index). |
+
+The standard `createdAt` / `updatedAt` are also there from the framework's mongoose-timestamp plugin, but `at` is the canonical time-of-event field — it's what the TTL is keyed on, and it's what you sort by when reconstructing a history.
+
+## Reading the audit log
+
+The plugin's `audit` schema is registered like any other dAvePi schema, so every standard surface works:
+
+### REST
+
+```bash
+# All events for one record
+GET /api/v1/audit?resource=order&resourceId=<oid>&__sort=at:desc
+
+# All deletes for the last 30 days
+GET /api/v1/audit?action=deleted&at__gte=2026-04-25T00:00:00Z
+
+# Per-resource view
+GET /api/v1/audit?resource=invoice&__sort=at:desc
+```
+
+### GraphQL
+
+```graphql
+query {
+  auditMany(
+    filter: { resource: "order" }
+    sort: AT_DESC
+    limit: 50
+  ) {
+    _id
+    action
+    resourceId
+    userId
+    before
+    after
+    diff
+    at
+  }
+}
+```
+
+### Tenant scope
+
+A regular caller sees only audit rows whose `userId` equals their own — the standard dAvePi owner-scope rule, applied to the audit collection like every other resource. The `audit` schema declares `acl.list = ['admin']`, so callers carrying the `admin` role bypass the owner predicate and see cross-tenant rows. Promote a compliance reviewer's user with `db.users.updateOne({_id}, {$set: {roles: ['admin', 'user']}})` (or your own admin management UI) to grant them the bypass.
+
+## Append-only enforcement (and its limits)
+
+The plugin enforces append-only at the **API layer**:
+
+- Every field declares an ACL whose only allowed role is a sentinel value no real user holds, so `filterWritable` (the framework's pre-persist strip pass) drops every key from `POST` / `PUT` / bulk-PUT request bodies — the resulting `$set` is empty, the write is a no-op.
+- The schema declares `beforeCreate` / `beforeUpdate` / `beforeDelete` hooks that throw `ForbiddenError`, so the REST single-record `POST` / `PUT /:id` / `DELETE /:id` paths (and their GraphQL `createOne` / `updateById` / `removeById` counterparts) return HTTP **403** with code `FORBIDDEN`.
+- `acl.delete` is intentionally absent — admins don't get a tenant-bypass on delete either, and even an admin's owner-scoped delete is rejected by the hook above.
+
+What this **doesn't** stop:
+
+- A direct `db.audit.updateOne(...)` / `db.audit.deleteMany(...)` from someone who has Mongo shell access. Database-level immutability is the consumer's call: replica-set + RBAC, periodic archival to S3 with object-lock, or both. The plugin is the wire-side guarantee; the DBA owns the file-system side.
+- GraphQL `auditRemoveMany` will go through `wrapFilter` for tenant scoping but does not currently invoke the `beforeDelete` hook (which is REST-only). A regular user can still delete their **own** audit rows via that mutation. If this matters in your deployment, either rebuild your admin UI to fence the mutation off, or run with `AUDIT_RETENTION_DAYS=0` and a separate replicated copy.
+
+## Storage and bulk events
+
+Audit rows carry full `before` + `after` snapshots, which means **the audit collection grows in proportion to your mutation rate × your record size**. A schema whose typical record is 4 KB and that sees 100 mutations/sec produces roughly 8 KB × 100 = 800 KB/s of audit data, or about 70 GB/day before redaction overhead. The defaults are tuned for typical CRUD apps (a few mutations per second per tenant); high-throughput workloads should:
+
+1. Set `AUDIT_RETENTION_DAYS` to the regulatory minimum you can defend (e.g. 90 instead of 365).
+2. Set `AUDIT_BULK_BYPASS=true` so a `updateMany({status: 'pending'}, ...)` doesn't explode into N audit rows — bulk events without bypass already write **one** row carrying `filter` + `numAffected`, but on a hot bulk path even that one row per call adds up.
+3. Use `AUDIT_INCLUDE` to narrow the surface to compliance-relevant resources only. Most apps don't need `cache.*` or `session.*` events audited.
+
+## Calling `record()` from a hook
+
+The plugin also exports `record(entry)` for ad-hoc audit writes — handy when a non-CRUD event happens that you still want trailed:
+
+```js
+// schema/versions/v1/contract.js
+const audit = require('davepi-plugin-audit');
+
+module.exports = {
+  path: 'contract',
+  collection: 'contract',
+  fields: [/* ... */],
+  hooks: {
+    afterUpdate: async ({ record, previous, user, req }) => {
+      // A signature event isn't a normal CRUD verb — record it
+      // under a custom action so it shows up alongside the
+      // automatic updated/deleted/created rows.
+      if (previous && !previous.signedAt && record.signedAt) {
+        await audit.record({
+          userId: user.user_id,
+          action: 'contract_signed',
+          resource: 'contract',
+          resourceId: record._id,
+          before: previous,
+          after: record,
+          ip: req && req.ip,
+          userAgent: req && req.get && req.get('user-agent'),
+          reqId: req && req.id,
+        });
+      }
+    },
+  },
+};
+```
+
+`record()` is best-effort like the bus subscriber — a thrown Mongo error logs and is swallowed. The function returns `true` when the row was written and `false` otherwise (dormant plugin, failed write).
+
+## Differences from the framework's in-tree audit
+
+dAvePi already writes to a separate `audit_log` collection via `utils/audit.js`. That trail captures the same per-mutation before/after as this plugin's `audit` collection but isn't exposed through the schema-driven surface — there are no REST routes, no GraphQL types, no admin UI integration. For v1, both coexist:
+
+- `audit_log` (in-tree): existing behaviour, no API surface, written by the persist sites in `utils/schemaLoader.js`.
+- `audit` (this plugin): new collection, full REST + GraphQL + admin SPA + MCP surface, written by the bus listener.
+
+Future versions may deprecate the in-tree path once the plugin is the canonical answer; for now, leave both running and query whichever one your tooling expects.
+
+## Failure handling
+
+- **Bus subscriber**: every audit write is wrapped in `try/catch`. A Mongo outage logs an `error` row via the framework's pino instance and is otherwise silent — the request loop is never blocked, and the user-facing response is committed even if the audit row is lost. Same posture as every other plugin bus subscriber.
+- **TTL index management**: at boot the plugin tries to align the TTL on `at` with `AUDIT_RETENTION_DAYS`. A failure (Mongo not yet connected, missing permissions) logs a warning and continues — the index can be created manually later, or on the next process restart.
+- **Boot**: a missing dependency (`mongoose`, `davepi/utils/errors`) logs an error and leaves the plugin dormant rather than failing boot. The framework continues to serve traffic without an audit trail; this is intentional for CI / staging without the package fully wired.
+
+## License
+
+ISC

package/index.js

@@ -0,0 +1,419 @@
+'use strict';
+
+/**
+ * davepi-plugin-audit
+ *
+ * Immutable, append-only audit log for dAvePi. Loaded by listing the
+ * package under the consumer project's `package.json -> davepi.plugins`:
+ *
+ *   {
+ *     "davepi": { "plugins": ["davepi-plugin-audit"] }
+ *   }
+ *
+ * Behaviour:
+ *   - On boot, auto-registers an `audit` schema (one per process) and
+ *     subscribes to the in-process `record` event bus. Every CRUD
+ *     event lands as one document in the `audit` collection with
+ *     `userId`, `accountId?`, `action`, `resource`, `resourceId`,
+ *     `before`, `after`, `diff` (a JSON-Patch from before to after),
+ *     `filter` / `numAffected` for bulk events, plus request metadata
+ *     (`ip`, `userAgent`, `reqId`) when the producing event carried a
+ *     `req` snapshot.
+ *   - The `audit` collection is read-only via the standard API:
+ *     every field declares an ACL that no role overlaps, and the
+ *     schema declares `beforeCreate` / `beforeUpdate` / `beforeDelete`
+ *     hooks that throw `ForbiddenError`. The plugin itself writes
+ *     directly through Mongoose, which doesn't go through hooks.
+ *   - `acl.list = ['admin']` gives admins a cross-tenant view; regular
+ *     users see only audit rows for actions they performed (the
+ *     standard tenant invariant).
+ *   - Retention via TTL index on `at`, controlled by
+ *     `AUDIT_RETENTION_DAYS` (default 365; `0` keeps forever and drops
+ *     any existing TTL index).
+ *
+ * Failure isolation: the bus subscriber wraps every Mongo write in
+ * try/catch and logs through the framework's pino instance handed in
+ * at setup. A misbehaving Mongo or a transient connection blip
+ * never blocks the request loop or surfaces as an unhandled
+ * rejection — same posture as the slack / postmark plugins.
+ *
+ * Storage growth: every mutation lands one row carrying `before` +
+ * `after` snapshots. Schemas with many large fields and many writes
+ * fill Mongo fast — the TTL index is the safety valve. The README
+ * carries the sizing math.
+ */
+
+const { compare } = require('./lib/diff');
+const { redact } = require('./lib/redact');
+const { buildAuditSchema } = require('./lib/schema');
+const {
+  shouldAuditResource,
+  parseEventType,
+  parseList,
+} = require('./lib/matcher');
+
+const ENV_KEYS = {
+  enabled:       'AUDIT_ENABLED',
+  retentionDays: 'AUDIT_RETENTION_DAYS',
+  bulkBypass:    'AUDIT_BULK_BYPASS',
+  include:       'AUDIT_INCLUDE',
+  exclude:       'AUDIT_EXCLUDE',
+  redact:        'AUDIT_REDACT',
+};
+
+const DEFAULT_REDACT_FIELDS = ['password', 'token', 'secret'];
+const DEFAULT_RETENTION_DAYS = 365;
+const TTL_INDEX_NAME = 'audit_at_ttl';
+// The plugin's own collection. Events whose resource matches this are
+// short-circuited so an audit-of-the-audit-log isn't possible — that
+// would only fire if the plugin's own writes somehow re-entered the
+// bus (they don't today, but the guard makes the contract explicit).
+const SELF_RESOURCE = 'audit';
+
+function parseBool(raw, fallback) {
+  if (raw === undefined || raw === null || raw === '') return fallback;
+  const v = String(raw).trim().toLowerCase();
+  if (['1', 'true', 'yes', 'on'].includes(v)) return true;
+  if (['0', 'false', 'no', 'off'].includes(v)) return false;
+  return fallback;
+}
+
+function parseRetentionDays(raw) {
+  if (raw === undefined || raw === null || raw === '') return DEFAULT_RETENTION_DAYS;
+  const n = parseInt(raw, 10);
+  if (Number.isNaN(n) || n < 0) return DEFAULT_RETENTION_DAYS;
+  return n;
+}
+
+function readConfigFromEnv(env) {
+  return {
+    enabled:       parseBool(env[ENV_KEYS.enabled], true),
+    retentionDays: parseRetentionDays(env[ENV_KEYS.retentionDays]),
+    bulkBypass:    parseBool(env[ENV_KEYS.bulkBypass], false),
+    include:       parseList(env[ENV_KEYS.include]),
+    exclude:       parseList(env[ENV_KEYS.exclude]),
+    redact:        env[ENV_KEYS.redact] === undefined
+      ? DEFAULT_REDACT_FIELDS
+      : parseList(env[ENV_KEYS.redact]),
+  };
+}
+
+/**
+ * Build a fresh plugin instance. Most consumers don't call this
+ * directly — `require('davepi-plugin-audit')` returns a default
+ * instance configured from `process.env`. Use this factory in tests
+ * (so you can inject `env`, `mongoose`, and `errors` stubs without a
+ * live framework install) or to override the schema version.
+ */
+function createPlugin(opts = {}) {
+  const env = opts.env || process.env;
+  const injectedMongoose = opts.mongoose || null;
+  const injectedErrors = opts.errors || null;
+  const schemaVersion = opts.schemaVersion || 'v1';
+  const config = readConfigFromEnv(env);
+
+  const state = {
+    enabled: false,
+    AuditModel: null,
+    log: null,
+  };
+
+  /**
+   * Hand-fire a write into the audit collection. Exposed so consumer
+   * code (or a hook) can record a non-CRUD event — "user manually
+   * approved waiver", "background job ran" — through the same surface.
+   * Best-effort: errors are logged and swallowed, mirroring the bus
+   * subscriber's posture.
+   */
+  async function record(entry) {
+    if (!state.enabled || !state.AuditModel) {
+      // No-throw on the public API — callers from `after*` hooks
+      // shouldn't have to gate on whether the plugin happened to be
+      // configured. The slack/postmark plugins DO throw on dormant
+      // `postMessage` / `sendEmail` because those are explicit
+      // outbound calls; here, "audit a thing" is meant to be
+      // ergonomic. A dormant plugin just no-ops.
+      return false;
+    }
+    try {
+      await state.AuditModel.create(buildRow(entry));
+      return true;
+    } catch (err) {
+      state.log.error(
+        { err, plugin: 'audit' },
+        'davepi-plugin-audit: manual record() failed'
+      );
+      return false;
+    }
+  }
+
+  function buildRow(input) {
+    const now = input && input.at ? new Date(input.at) : new Date();
+    const before = redact(input.before == null ? null : input.before, config.redact);
+    const after = redact(input.after == null ? null : input.after, config.redact);
+    return {
+      userId:      input.userId ? String(input.userId) : null,
+      accountId:   input.accountId ? String(input.accountId) : null,
+      action:      input.action || null,
+      resource:    input.resource || null,
+      resourceId:  input.resourceId ? String(input.resourceId) : null,
+      before,
+      after,
+      diff:        compare(before, after),
+      filter:      input.filter || null,
+      numAffected: typeof input.numAffected === 'number' ? input.numAffected : null,
+      ip:          input.ip || null,
+      userAgent:   input.userAgent || null,
+      reqId:       input.reqId || null,
+      at:          now,
+    };
+  }
+
+  /**
+   * Translate one bus event into the audit row arguments. Returns
+   * `null` to indicate the event should be skipped (resource is the
+   * plugin's own collection, type is malformed, or the resource fell
+   * out of the include/exclude policy).
+   */
+  function buildRowFromEvent(event) {
+    if (!event || !event.type) return null;
+    const parsed = parseEventType(event.type);
+    if (!parsed) return null;
+    const { resource, action } = parsed;
+    if (resource === SELF_RESOURCE) return null;
+    if (!shouldAuditResource(resource, config)) return null;
+    const isBulk = typeof event.numAffected === 'number' && !event.recordId;
+    if (isBulk && config.bulkBypass) return null;
+
+    // For bulk events we lose `before` / `after` per the framework's
+    // event contract — emit a single row with the filter + count.
+    // Single-record events carry `record` (after), and the framework's
+    // REST layer also carries `before` for updates/deletes when
+    // available. Some producers (GraphQL, MCP) don't carry `before`
+    // yet — those rows show `before: null`, and the diff is the
+    // equivalent of "every field added at this snapshot".
+    const reqMeta = event.req && typeof event.req === 'object' ? event.req : null;
+    if (isBulk) {
+      return {
+        userId:      event.userId,
+        accountId:   event.accountId,
+        action,
+        resource,
+        resourceId:  null,
+        before:      null,
+        after:       null,
+        filter:      event.filter || null,
+        numAffected: event.numAffected,
+        ip:          reqMeta && reqMeta.ip,
+        userAgent:   reqMeta && reqMeta.userAgent,
+        reqId:       reqMeta && reqMeta.reqId,
+      };
+    }
+    return {
+      userId:     event.userId,
+      accountId:  event.accountId || (event.record && event.record.accountId),
+      action,
+      resource,
+      resourceId: event.recordId,
+      before:     event.before === undefined ? null : event.before,
+      // `record` is the standard payload key from the framework's
+      // single-record events; `after` is the (newer) explicit name.
+      // Prefer `after` when both are set so a producer can opt into
+      // the explicit shape without breaking older consumers.
+      after:      event.after !== undefined
+        ? event.after
+        : (event.record !== undefined ? event.record : null),
+      ip:         reqMeta && reqMeta.ip,
+      userAgent:  reqMeta && reqMeta.userAgent,
+      reqId:      reqMeta && reqMeta.reqId,
+    };
+  }
+
+  async function ensureTtlIndex(collection) {
+    // `0` (or any non-positive) disables retention. We try to drop an
+    // existing TTL index if present so flipping the env from "365 →
+    // 0" actually frees the index. dropIndex throws when the index
+    // doesn't exist; that's fine — we want the no-op path to be
+    // silent.
+    if (config.retentionDays <= 0) {
+      try {
+        await collection.dropIndex(TTL_INDEX_NAME);
+      } catch (_e) {
+        // not present — nothing to drop
+      }
+      return;
+    }
+    const seconds = config.retentionDays * 86400;
+    try {
+      const existing = await collection.indexes();
+      const ttl = existing.find((idx) => idx.name === TTL_INDEX_NAME);
+      if (ttl && ttl.expireAfterSeconds !== seconds) {
+        // Mongo allows modifying TTL via collMod, but dropping and
+        // recreating is simpler and the plugin's setup runs once per
+        // process anyway. The brief window without a TTL index can't
+        // grow the collection meaningfully.
+        await collection.dropIndex(TTL_INDEX_NAME);
+      }
+      if (!ttl || ttl.expireAfterSeconds !== seconds) {
+        await collection.createIndex(
+          { at: 1 },
+          { name: TTL_INDEX_NAME, expireAfterSeconds: seconds }
+        );
+      }
+    } catch (err) {
+      state.log.warn(
+        { err, plugin: 'audit' },
+        'davepi-plugin-audit: TTL index management failed; continuing without TTL'
+      );
+    }
+  }
+
+  async function setup({ app, schemaLoader, bus, log, appName }) {
+    state.log = log;
+
+    if (!config.enabled) {
+      log.warn(
+        { plugin: 'audit' },
+        'AUDIT_ENABLED=false; davepi-plugin-audit is dormant'
+      );
+      return;
+    }
+    if (!schemaLoader || typeof schemaLoader.loadSchema !== 'function') {
+      log.error(
+        { plugin: 'audit' },
+        'davepi-plugin-audit setup({ schemaLoader }) is required; staying dormant'
+      );
+      return;
+    }
+    if (!bus || typeof bus.on !== 'function') {
+      log.error(
+        { plugin: 'audit' },
+        'davepi-plugin-audit setup({ bus }) is required; staying dormant'
+      );
+      return;
+    }
+
+    // Resolve framework dependencies lazily so the package's own unit
+    // tests (which don't install `davepi` or any of its deps) can run
+    // standalone. Production callers will have these on the require
+    // path because the framework itself uses them.
+    let mongoose = injectedMongoose;
+    if (!mongoose) {
+      try {
+        mongoose = require('mongoose');
+      } catch (err) {
+        log.error(
+          { err, plugin: 'audit' },
+          "could not require 'mongoose' to register audit schema; staying dormant"
+        );
+        return;
+      }
+    }
+    let errors = injectedErrors;
+    if (!errors) {
+      try {
+        errors = require('davepi/utils/errors');
+      } catch (err) {
+        log.error(
+          { err, plugin: 'audit' },
+          "could not require 'davepi/utils/errors' to define audit schema hooks; staying dormant"
+        );
+        return;
+      }
+    }
+
+    // Register the audit schema. The loader hot-mounts it onto the
+    // existing Express app and rebuilds the GraphQL surface — exactly
+    // what the consumer would have done by dropping a file under
+    // schema/versions/v1/, just without requiring them to.
+    const schema = buildAuditSchema({ mongoose, version: schemaVersion, errors });
+    try {
+      await schemaLoader.loadSchema(schema);
+    } catch (err) {
+      log.error(
+        { err, plugin: 'audit' },
+        'davepi-plugin-audit: failed to register audit schema; staying dormant'
+      );
+      return;
+    }
+    const entry = schemaLoader.getEntry(`${schemaVersion}/audit`);
+    if (!entry || !entry.model) {
+      log.error(
+        { plugin: 'audit' },
+        'davepi-plugin-audit: audit schema registered but model is missing; staying dormant'
+      );
+      return;
+    }
+    state.AuditModel = entry.model;
+
+    // TTL index. Best-effort: if Mongo isn't reachable yet we log and
+    // continue — the next setup-cycle (or operator's manual
+    // `collection.createIndex(...)`) will catch up.
+    if (
+      state.AuditModel.collection &&
+      typeof state.AuditModel.collection.createIndex === 'function'
+    ) {
+      await ensureTtlIndex(state.AuditModel.collection);
+    }
+
+    state.enabled = true;
+
+    bus.on('record', async (event) => {
+      if (!state.enabled || !state.AuditModel) return;
+      let row;
+      try {
+        row = buildRowFromEvent(event);
+      } catch (err) {
+        // Defensive: a malformed event shouldn't take down the bus
+        // listener. Log and move on.
+        log.error(
+          { err, plugin: 'audit', eventType: event && event.type },
+          'davepi-plugin-audit: row build failed'
+        );
+        return;
+      }
+      if (!row) return;
+      try {
+        await state.AuditModel.create(buildRow(row));
+      } catch (err) {
+        log.error(
+          { err, plugin: 'audit', eventType: event && event.type },
+          'davepi-plugin-audit: write failed (audit row lost)'
+        );
+      }
+    });
+
+    log.info(
+      {
+        plugin: 'audit',
+        retentionDays: config.retentionDays,
+        include:       config.include,
+        exclude:       config.exclude,
+        bulkBypass:    config.bulkBypass,
+      },
+      'davepi-plugin-audit ready'
+    );
+    // Reference `appName` so a future formatter can use it (parity
+    // with the slack/postmark plugin signatures); kept here so the
+    // contract documented in pluginLoader stays exercised.
+    void appName;
+    void app;
+  }
+
+  return {
+    name: 'audit',
+    setup,
+    record,
+    // Exposed for tests + ad-hoc debugging — not part of the
+    // documented plugin API but harmless to leave on the object.
+    _buildRowFromEvent: buildRowFromEvent,
+    _buildRow: buildRow,
+    _config: config,
+  };
+}
+
+const defaultPlugin = createPlugin();
+module.exports = defaultPlugin;
+module.exports.createPlugin = createPlugin;
+module.exports.compare = compare;
+module.exports.redact = redact;

package/lib/diff.js

@@ -0,0 +1,32 @@
+'use strict';
+
+/**
+ * RFC 6902 JSON-Patch `compare(before, after)`. Returns an array of
+ * `{ op, path, value? }` ops describing how `before` would be
+ * transformed into `after`.
+ *
+ * Delegates to `fast-json-patch.compare` for the actual diff — it's
+ * the reference implementation of RFC 6902, has zero runtime deps of
+ * its own, and gives us round-trip applicability for free (a consumer
+ * can `applyPatch({}, diff)` to reconstruct `after` from `before`).
+ * Issue #116 explicitly named `fast-json-patch` as the implementation
+ * choice; a homegrown compare would diverge over time on edge cases
+ * (array LCS, escape-sequence corners, no-op detection).
+ *
+ * Inputs may be `null` / `undefined`: the framework's bus emits
+ * `before: null` on create and `after: null` on hard-delete, and
+ * we coerce both sides to `{}` so the resulting patch is a per-key
+ * `add` / `remove` series at the top level rather than a root-replace
+ * — easier to render in an audit UI and easier to apply back through
+ * `applyPatch({}, diff)`.
+ */
+
+const jsonpatch = require('fast-json-patch');
+
+function compare(before, after) {
+  const b = before === null || before === undefined ? {} : before;
+  const a = after === null || after === undefined ? {} : after;
+  return jsonpatch.compare(b, a);
+}
+
+module.exports = { compare };

package/lib/matcher.js

@@ -0,0 +1,59 @@
+'use strict';
+
+/**
+ * Resource allow/deny matcher.
+ *
+ * `include` is an allowlist of resource names ('order', 'invoice'); an
+ * empty / unset list means "all resources are eligible". `exclude` is
+ * a denylist that wins on a conflict — if `audit` is in `exclude`, the
+ * plugin never writes a row for it, even when also in `include`. That
+ * ordering is documented in the issue and lets an operator turn off
+ * audit for a specific high-cardinality resource without rebuilding
+ * their allowlist.
+ *
+ * The plugin's own `audit` resource is filtered out by the caller
+ * before this matcher runs (any row produced from an `audit.*` event
+ * would create a feedback loop), so we don't special-case it here.
+ */
+function shouldAuditResource(resource, { include, exclude }) {
+  if (!resource) return false;
+  if (Array.isArray(exclude) && exclude.length && exclude.includes(resource)) {
+    return false;
+  }
+  if (Array.isArray(include) && include.length) {
+    return include.includes(resource);
+  }
+  return true;
+}
+
+/**
+ * Parse a record-event `type` into `{ resource, action }`. Events are
+ * shaped as `<resource>.<verb>` where verb is one of
+ * `created` / `updated` / `deleted` / `transitioned`. We split on the
+ * LAST `.` so a resource name with a `.` in it (none today, but the
+ * framework doesn't forbid it) still routes correctly.
+ *
+ * `action` is normalised to the past-tense form the audit row stores
+ * (matching the spec). Unknown verbs fall through as-is so the row
+ * isn't silently dropped — operators can investigate via the audit
+ * row's stored action.
+ */
+function parseEventType(type) {
+  if (typeof type !== 'string' || !type.length) return null;
+  const lastDot = type.lastIndexOf('.');
+  if (lastDot <= 0 || lastDot === type.length - 1) return null;
+  return {
+    resource: type.slice(0, lastDot),
+    action: type.slice(lastDot + 1),
+  };
+}
+
+function parseList(raw) {
+  if (!raw || typeof raw !== 'string') return [];
+  return raw
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+module.exports = { shouldAuditResource, parseEventType, parseList };

package/lib/redact.js

@@ -0,0 +1,55 @@
+'use strict';
+
+/**
+ * Recursively scrub fields whose name appears in `fields`, replacing
+ * the value with the literal string `[REDACTED]`. Operates on a fresh
+ * copy — the input is never mutated, so the same snapshot can also be
+ * passed to non-redacting consumers (the framework's in-tree audit,
+ * future analytics consumers) without surprise.
+ *
+ * The match is case-insensitive on the *field name*. Values are
+ * untouched apart from the redaction marker; we deliberately do NOT
+ * try to redact things like "looks-like-a-credit-card" — that's pino
+ * redaction's job and a different posture entirely.
+ *
+ * Arrays are walked element-by-element. Dates, Buffers, ObjectIds,
+ * and other non-plain-object values pass through unchanged so the
+ * audit row still serialises faithfully.
+ */
+function redact(value, fields) {
+  if (!Array.isArray(fields) || fields.length === 0) return value;
+  const set = new Set(fields.map((f) => String(f).toLowerCase()));
+  return walk(value, set);
+}
+
+function walk(value, set) {
+  if (value === null || value === undefined) return value;
+  if (Array.isArray(value)) {
+    return value.map((item) => walk(item, set));
+  }
+  if (typeof value !== 'object') return value;
+  // Preserve non-plain-object types — Date, Buffer, BSON ObjectId, etc.
+  // Walking their properties would either produce nonsense or mutate
+  // semantics (e.g., replacing Date.prototype.toISOString output with
+  // a redacted string).
+  if (
+    value instanceof Date ||
+    (typeof Buffer !== 'undefined' && Buffer.isBuffer && Buffer.isBuffer(value)) ||
+    Object.getPrototypeOf(value) !== Object.prototype
+  ) {
+    return value;
+  }
+  const out = {};
+  for (const [k, v] of Object.entries(value)) {
+    if (set.has(k.toLowerCase())) {
+      out[k] = '[REDACTED]';
+    } else if (v && typeof v === 'object') {
+      out[k] = walk(v, set);
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+module.exports = { redact };

package/lib/schema.js

@@ -0,0 +1,99 @@
+'use strict';
+
+/**
+ * Build the audit-collection schema the plugin registers with the
+ * framework's schemaLoader. The shape matches dAvePi's schema-driven
+ * vocabulary (see AGENTS.md) so every standard surface — REST,
+ * GraphQL, swagger, the `_describe` manifest — picks it up
+ * automatically.
+ *
+ * Read-only-via-API is enforced at two layers:
+ *
+ *   1. Every field declares `acl.create` / `acl.update` whose value is
+ *      a sentinel role no real user holds. `filterWritable` strips
+ *      every key from inbound payloads, so an authenticated `POST` /
+ *      `PUT` / bulk `PUT` lands an empty `$set` and writes nothing.
+ *   2. `beforeCreate` / `beforeUpdate` / `beforeDelete` hooks throw
+ *      `ForbiddenError`, surfacing a 403 on the REST single-record
+ *      paths (and the equivalent GraphQL mutations, which route
+ *      through the same hook runner).
+ *
+ * `acl.list = ['admin']` gives admins a cross-tenant bypass on read.
+ * `acl.delete` is intentionally absent — combined with the
+ * `beforeDelete` hook above, no caller (including admins, since the
+ * bypass would only let them widen the owner predicate) can remove a
+ * row through the standard CRUD surface.
+ *
+ * `audit: false` opts this schema OUT of the framework's in-tree
+ * audit pipeline (`utils/audit.js`). The plugin's own bus subscriber
+ * is what writes rows here; the in-tree pipeline writes to a separate
+ * `audit_log` collection. Leaving the framework audit on would let
+ * the (blocked) hook throws still leak audit_log rows.
+ *
+ * `softDelete: false` keeps this collection literal — no `deletedAt`
+ * tombstone, no `/restore` route. The acceptance contract is
+ * "append-only at the API layer", and a soft-deletable row still
+ * presents as deletable to clients even when the underlying document
+ * sticks around.
+ */
+function buildAuditSchema({ mongoose, version = 'v1', errors }) {
+  const Mixed = mongoose.Schema.Types.Mixed;
+  // A sentinel role no real user holds. `filterWritable` keeps fields
+  // whose acl-allowed roles overlap the caller's roles; an opaque
+  // marker guarantees the overlap check fails for every persona,
+  // including admin.
+  const NO_ONE = ['__davepi_audit_plugin_only__'];
+  const withWriteLock = (field) => ({
+    ...field,
+    acl: { ...(field.acl || {}), create: NO_ONE, update: NO_ONE },
+  });
+
+  const { ForbiddenError } = errors;
+  const blockWrite = (op) => async () => {
+    throw new ForbiddenError(
+      `audit log is append-only; ${op} not permitted via API ` +
+        '(entries are written by davepi-plugin-audit only)'
+    );
+  };
+
+  return {
+    path: 'audit',
+    collection: 'audit',
+    version,
+    softDelete: false,
+    audit: false,
+    fields: [
+      withWriteLock({ name: 'userId',      type: String, required: true }),
+      withWriteLock({ name: 'accountId',   type: String }),
+      withWriteLock({ name: 'action',      type: String, required: true }),
+      withWriteLock({ name: 'resource',    type: String, required: true }),
+      withWriteLock({ name: 'resourceId',  type: String }),
+      withWriteLock({ name: 'before',      type: Mixed }),
+      withWriteLock({ name: 'after',       type: Mixed }),
+      withWriteLock({ name: 'diff',        type: Mixed }),
+      withWriteLock({ name: 'filter',      type: Mixed }),
+      withWriteLock({ name: 'numAffected', type: Number }),
+      withWriteLock({ name: 'ip',          type: String }),
+      withWriteLock({ name: 'userAgent',   type: String }),
+      withWriteLock({ name: 'reqId',       type: String }),
+      withWriteLock({ name: 'at',          type: Date,   required: true }),
+    ],
+    acl: {
+      // Admin role bypasses the owner-scoped read filter so compliance
+      // reviewers see cross-tenant rows. Regular users see only the
+      // rows whose `userId` matches their own — the standard tenant
+      // invariant.
+      list: ['admin'],
+      // `delete` is deliberately omitted (no bypass). The hook below
+      // is the actual block; the missing entry just keeps the bypass
+      // story unambiguous.
+    },
+    hooks: {
+      beforeCreate: blockWrite('create'),
+      beforeUpdate: blockWrite('update'),
+      beforeDelete: blockWrite('delete'),
+    },
+  };
+}
+
+module.exports = { buildAuditSchema };

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "davepi-plugin-audit",
+  "version": "0.1.0",
+  "description": "Immutable append-only audit log for dAvePi. Subscribes to the in-process record event bus and writes one row per CRUD mutation (with before/after, JSON-patch diff, actor, IP, user-agent, and request ID) into an auto-registered `audit` collection that's queryable through the standard REST + GraphQL surface. Admin-only list bypass, no API-level writes, optional TTL retention, redaction, and per-resource allow/deny lists.",
+  "license": "ISC",
+  "homepage": "https://docs.davepi.dev/features/plugins/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/projik/davepi.git",
+    "directory": "packages/davepi-plugin-audit"
+  },
+  "keywords": [
+    "davepi",
+    "davepi-plugin",
+    "audit",
+    "audit-log",
+    "compliance",
+    "events"
+  ],
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "lib",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "fast-json-patch": "^3.1.1"
+  },
+  "peerDependencies": {
+    "davepi": ">=1.0.5"
+  },
+  "peerDependenciesMeta": {
+    "davepi": {
+      "optional": false
+    }
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  }
+}