strapi-cms-audit-log 1.1.0

package/dist/server/src/bootstrap.d.ts

@@ -0,0 +1,14 @@
+import { Core } from '@strapi/strapi';
+/**
+ * Wires the plugin up once Strapi is fully loaded.
+ *
+ * Order matters here. The immutability guard is registered *before* the tracker
+ * so that it sits earlier in the Document Service middleware chain: a forbidden
+ * write to the audit table is rejected before the tracker has done any work for
+ * it. Both are registered in `bootstrap` rather than `register` because
+ * `strapi.documents` is not available until the content types have loaded.
+ */
+declare const bootstrap: ({ strapi }: {
+    strapi: Core.Strapi;
+}) => void;
+export default bootstrap;

package/dist/server/src/config/index.d.ts

@@ -0,0 +1,52 @@
+import { AuditUserConfig } from '../types';
+/**
+ * Defaults merged with the consumer's `config/plugins.ts` block.
+ *
+ * ## Why the collection-valued keys default to `null`
+ *
+ * Strapi merges plugin config with lodash's `defaultsDeep`, which merges arrays
+ * *element-wise*. With `ignoredFields: ['password', 'token', 'apiKey', 'secret']`
+ * as a literal default, a consumer writing `ignoredFields: ['internalNote']`
+ * would silently end up with `['internalNote', 'token', 'apiKey', 'secret']` —
+ * their first element replaced, the rest of ours retained. That is a trap, and a
+ * dangerous one for a redaction list.
+ *
+ * So every array/selector option defaults to `null` here, meaning "not set", and
+ * the real defaults are applied in `services/config.ts`. `null` is not an array,
+ * so `defaultsDeep` replaces it wholesale and the consumer gets exactly the list
+ * they wrote. `additionalIgnoredFields` exists for the common case of wanting
+ * ours *plus* a few of their own.
+ */
+declare const _default: {
+    default: {
+        enabled: boolean;
+        actions: null;
+        contentTypes: null;
+        ignoredContentTypes: null;
+        ignoredFields: null;
+        additionalIgnoredFields: null;
+        ignoredChangeFields: null;
+        storeBefore: boolean;
+        storeAfter: boolean;
+        storeChanges: boolean;
+        retentionDays: number;
+        retentionCron: string;
+        failOnAuditError: boolean;
+        writeMode: string;
+        maxPopulateDepth: number;
+        maxSnapshotBytes: number;
+        auditSystemOperations: boolean;
+        securityEvents: null;
+        forwardToLogger: boolean;
+        forwardLogLevel: string;
+    };
+    /**
+     * Runs once at boot, before anything else touches the config. Throwing here
+     * fails startup with a clear message, which is far kinder than a plugin that
+     * silently audits nothing because of a typo.
+     */
+    validator(config: AuditUserConfig & {
+        enabled?: boolean;
+    }): void;
+};
+export default _default;

package/dist/server/src/constants.d.ts

@@ -0,0 +1,140 @@
+import { AuditAction, AuditSecurityAction } from './types';
+/** Plugin id. Must match `strapi.name` in package.json — it namespaces routes, permissions and config. */
+export declare const PLUGIN_ID = "audit-log";
+/** UID of the plugin's own collection type. */
+export declare const AUDIT_LOG_UID = "plugin::audit-log.audit-log";
+export declare const ALL_ACTIONS: AuditAction[];
+/** RBAC action uids, as they appear once namespaced by the admin permission provider. */
+export declare const PERMISSIONS: {
+    readonly read: "plugin::audit-log.read";
+    readonly delete: "plugin::audit-log.delete";
+    readonly settings: "plugin::audit-log.settings";
+};
+/**
+ * Fields never written to `before`, `after` or `changes`.
+ *
+ * Matched by leaf name at any depth and case-insensitively, so `*token*` covers
+ * `token`, `accessToken`, `seo.internalToken` and `blocks[0].refreshTokenHash`
+ * alike. Substring patterns rather than an exhaustive list of exact names
+ * because the list can only ever be a guess at what a project calls its secrets:
+ * `internalToken` and `stripeSecretKey` are the names that actually turn up, and
+ * an exact-match list silently stores both.
+ *
+ * The trade is deliberate. `*token*` also redacts a field named `tokenCount`,
+ * which costs one uninteresting value in an audit record. Missing a credential
+ * writes it, in clear, into a table designed to be kept for a year.
+ *
+ * Replaced wholesale (not merged) when a consumer sets `ignoredFields`; use
+ * `additionalIgnoredFields` to extend rather than replace.
+ */
+export declare const DEFAULT_IGNORED_FIELDS: string[];
+/**
+ * Fields excluded from `changes` only.
+ *
+ * They still appear in `before`/`after` — they are real state — but they change
+ * on every single write, so surfacing them as "changes" buries the edit the
+ * editor actually made.
+ */
+export declare const DEFAULT_IGNORED_CHANGE_FIELDS: string[];
+/**
+ * Attributes that carry no auditable content and are stripped from a snapshot.
+ *
+ * `id`, `documentId` and `locale` are recorded as dedicated columns instead, so
+ * repeating them inside the JSON blobs is pure noise. `publishedAt` is fetched —
+ * the tracker needs it to tell a draft row from a published one — but not
+ * stored: the record's own `action` already says whether this was a publish or
+ * an unpublish, and leaving it in makes every single-field update snapshot
+ * contain a field the editor never touched.
+ */
+export declare const SKIPPED_ATTRIBUTES: Set<string>;
+/** Headers checked, in order, for a correlation id. */
+export declare const REQUEST_ID_HEADERS: string[];
+/** Name under which the retention job is registered with `strapi.cron`. */
+export declare const RETENTION_JOB_NAME = "auditLogRetention";
+/**
+ * Alias that says what {@link ALL_ACTIONS} actually is, now that the plugin also
+ * records events which are not content operations.
+ *
+ * `ALL_ACTIONS` keeps its name and its five members because `config.actions`
+ * validates against it. Widening that option to accept security actions would
+ * let a project write `actions: ['login.success']` and then wonder why none of
+ * its content was audited. Security events get their own switch —
+ * `securityEvents` — for the same reason: the two families are produced by
+ * different machinery, fail independently, and are turned on and off
+ * independently.
+ */
+export declare const CONTENT_ACTIONS: AuditAction[];
+/**
+ * Everything the plugin records that is *not* a content write.
+ *
+ * These arrive from `strapi.eventHub` and from a Koa middleware rather than from
+ * the Document Service, which is why they are listed apart. Every one of them is
+ * available in Strapi **Community Edition** — none needs an Enterprise licence.
+ */
+export declare const ALL_SECURITY_ACTIONS: AuditSecurityAction[];
+/**
+ * Pseudo content-type uids for events that are not about a content type.
+ *
+ * `contentType` is `required` on the schema and is what every existing filter,
+ * index and search path is built on, so a security row carries the uid of the
+ * subsystem it concerns rather than a null. `admin::user`, `admin::role` and
+ * `admin::permission` are Strapi's own real uids; `admin::auth` and
+ * `admin::access` are ours, naming the two subsystems Strapi does not model as
+ * content types.
+ */
+export declare const SUBJECTS: {
+    readonly auth: "admin::auth";
+    readonly access: "admin::access";
+    readonly user: "admin::user";
+    readonly role: "admin::role";
+    readonly permission: "admin::permission";
+    readonly file: "plugin::upload.file";
+    readonly folder: "plugin::upload.folder";
+};
+/** Human labels for {@link SUBJECTS}, snapshotted into `contentTypeDisplayName`. */
+export declare const SUBJECT_DISPLAY_NAMES: Record<string, string>;
+/**
+ * `eventHub` event name -> the audit action and subject it becomes.
+ *
+ * Every one of these is emitted by Strapi itself; the plugin adds no
+ * instrumentation to Strapi's own code. Sources, for whoever has to re-verify
+ * this list against a Strapi upgrade:
+ *
+ *   admin.auth.*, admin.logout    @strapi/admin   server/src/controllers/authentication.ts
+ *   user.*, role.*, permission.*  @strapi/admin   server/src/services/{user,role,permission}.ts
+ *   media.*                       @strapi/upload  server/src/services/upload.ts
+ *   media-folder.*                @strapi/upload  server/src/services/folder.ts
+ *
+ * Media and admin-user writes go through `strapi.db.query`, below the Document
+ * Service, so the tracker never sees them and there is no double-recording to
+ * guard against.
+ */
+export declare const SECURITY_EVENT_MAP: Record<string, {
+    action: AuditSecurityAction;
+    subject: string;
+}>;
+/**
+ * Every value the `source` column can hold.
+ *
+ * Listed rather than derived from the rows already written, so the filter can
+ * ask "did anything come in through the content API?" before anything has.
+ */
+export declare const ALL_SOURCES: readonly ["admin", "api", "system", "cron", "migration", "unknown"];
+/**
+ * Response statuses the access middleware records as a denial.
+ *
+ * 401 is "you are not authenticated", 403 is "you are, and you still may not".
+ * Both are what a security review means by an unauthorised access attempt, and
+ * recording only 403 would miss every expired-session and bad-token probe.
+ */
+export declare const DENIED_STATUSES: Set<number>;
+/**
+ * Paths the access middleware never records.
+ *
+ * A failed *login* already produces a `login.failed` record from
+ * `admin.auth.error`, complete with the attempted email; letting the middleware
+ * add an `access.denied` for the same 401 would double every wrong-password
+ * attempt. `/admin/renew-token` 401s routinely whenever a tab is left open past
+ * the session window, which is noise rather than signal.
+ */
+export declare const ACCESS_IGNORED_PATHS: RegExp[];

package/dist/server/src/content-types/audit-log/index.d.ts

@@ -0,0 +1,86 @@
+declare const _default: {
+    schema: {
+        kind: string;
+        collectionName: string;
+        info: {
+            singularName: string;
+            pluralName: string;
+            displayName: string;
+            description: string;
+        };
+        options: {
+            draftAndPublish: boolean;
+        };
+        pluginOptions: {
+            'content-manager': {
+                visible: boolean;
+            };
+            'content-type-builder': {
+                visible: boolean;
+            };
+        };
+        attributes: {
+            action: {
+                type: string;
+                required: boolean;
+            };
+            contentType: {
+                type: string;
+                required: boolean;
+            };
+            contentTypeDisplayName: {
+                type: string;
+            };
+            contentDocumentId: {
+                type: string;
+            };
+            contentId: {
+                type: string;
+            };
+            locale: {
+                type: string;
+            };
+            userId: {
+                type: string;
+            };
+            userEmail: {
+                type: string;
+            };
+            userName: {
+                type: string;
+            };
+            changes: {
+                type: string;
+            };
+            before: {
+                type: string;
+            };
+            after: {
+                type: string;
+            };
+            outcome: {
+                type: string;
+            };
+            metadata: {
+                type: string;
+            };
+            ipAddress: {
+                type: string;
+            };
+            userAgent: {
+                type: string;
+            };
+            source: {
+                type: string;
+            };
+            requestId: {
+                type: string;
+            };
+        };
+        indexes: {
+            name: string;
+            columns: string[];
+        }[];
+    };
+};
+export default _default;

package/dist/server/src/content-types/audit-log/schema.d.ts

@@ -0,0 +1,141 @@
+/**
+ * The audit-log collection type.
+ *
+ * Deliberately invisible to both the Content Manager and the Content-Type
+ * Builder. That is not cosmetic: the Content Manager only registers
+ * create/update/delete/publish RBAC actions for content types it *displays*
+ * (`services/permission.ts` in `@strapi/content-manager` filters by
+ * `isDisplayed`), so with `visible: false` there is no permission any admin
+ * role could be granted that would let it write these rows through the normal
+ * content APIs. Immutability is enforced by the absence of a permission rather
+ * than by a check that could be forgotten. `services/immutability.ts` adds a
+ * second, belt-and-braces guard at the Document Service layer.
+ */
+declare const schema: {
+    kind: string;
+    collectionName: string;
+    info: {
+        singularName: string;
+        pluralName: string;
+        displayName: string;
+        description: string;
+    };
+    options: {
+        draftAndPublish: boolean;
+    };
+    pluginOptions: {
+        'content-manager': {
+            visible: boolean;
+        };
+        'content-type-builder': {
+            visible: boolean;
+        };
+    };
+    attributes: {
+        action: {
+            type: string;
+            required: boolean;
+        };
+        /** UID of the audited content type, e.g. `api::page.page`. */
+        contentType: {
+            type: string;
+            required: boolean;
+        };
+        /** Display name at write time, so the log stays readable if the type is renamed or removed. */
+        contentTypeDisplayName: {
+            type: string;
+        };
+        /**
+         * The audited document's Strapi v5 document id.
+         *
+         * NOT named `documentId`. Strapi reserves that attribute name on every
+         * content type — `transformContentTypesToModels` throws
+         * "The attribute "documentId" is reserved" at boot — because it injects its
+         * own `documentId` column into every collection type. Each audit row
+         * therefore still *has* a framework `documentId` (its own identity); this
+         * column is the id of the document the row is *about*.
+         */
+        contentDocumentId: {
+            type: string;
+        };
+        /** The audited entry's numeric database id, stored as a string. */
+        contentId: {
+            type: string;
+        };
+        locale: {
+            type: string;
+        };
+        /** Actor identity, snapshotted so the record survives the user being renamed or deleted. */
+        userId: {
+            type: string;
+        };
+        userEmail: {
+            type: string;
+        };
+        userName: {
+            type: string;
+        };
+        /** Field-level diff, keyed by dotted path. */
+        changes: {
+            type: string;
+        };
+        before: {
+            type: string;
+        };
+        after: {
+            type: string;
+        };
+        /**
+         * Whether the recorded attempt succeeded.
+         *
+         * Always `success` for a content write — the tracker runs after the
+         * operation resolved, so a save that threw produces no row at all. The
+         * column earns its place on the security side, where `login.failed` and
+         * `access.denied` are exactly the rows a reviewer opens the log to find, and
+         * where "show me every failure" has to be an indexed query rather than a
+         * scan against a hard-coded list of action names.
+         */
+        outcome: {
+            type: string;
+        };
+        /**
+         * Action-specific detail: the reason a login was refused, the method and
+         * path of a denied request, the filename of an upload.
+         *
+         * A loose JSON bag rather than a column each, because the useful fields
+         * differ per action and none of them is ever filtered or sorted on. Anything
+         * that needs to be queryable gets a real column instead.
+         */
+        metadata: {
+            type: string;
+        };
+        ipAddress: {
+            type: string;
+        };
+        userAgent: {
+            type: string;
+        };
+        source: {
+            type: string;
+        };
+        requestId: {
+            type: string;
+        };
+    };
+    /**
+     * Secondary indexes, declared here so Strapi's schema sync owns them and they
+     * are created on every supported database without hand-written DDL.
+     *
+     * Columns are DB column names (snake_cased attribute names), and names are
+     * kept short enough for PostgreSQL's 63-character identifier limit.
+     *
+     * `audit_logs_ct_created_idx` is composite and leading-column ordered for the
+     * admin list's default query — filter by content type, sort by date — which is
+     * the only query that runs on every page load.
+     */
+    indexes: {
+        name: string;
+        columns: string[];
+    }[];
+};
+export default schema;

package/dist/server/src/content-types/index.d.ts

@@ -0,0 +1,88 @@
+declare const _default: {
+    'audit-log': {
+        schema: {
+            kind: string;
+            collectionName: string;
+            info: {
+                singularName: string;
+                pluralName: string;
+                displayName: string;
+                description: string;
+            };
+            options: {
+                draftAndPublish: boolean;
+            };
+            pluginOptions: {
+                'content-manager': {
+                    visible: boolean;
+                };
+                'content-type-builder': {
+                    visible: boolean;
+                };
+            };
+            attributes: {
+                action: {
+                    type: string;
+                    required: boolean;
+                };
+                contentType: {
+                    type: string;
+                    required: boolean;
+                };
+                contentTypeDisplayName: {
+                    type: string;
+                };
+                contentDocumentId: {
+                    type: string;
+                };
+                contentId: {
+                    type: string;
+                };
+                locale: {
+                    type: string;
+                };
+                userId: {
+                    type: string;
+                };
+                userEmail: {
+                    type: string;
+                };
+                userName: {
+                    type: string;
+                };
+                changes: {
+                    type: string;
+                };
+                before: {
+                    type: string;
+                };
+                after: {
+                    type: string;
+                };
+                outcome: {
+                    type: string;
+                };
+                metadata: {
+                    type: string;
+                };
+                ipAddress: {
+                    type: string;
+                };
+                userAgent: {
+                    type: string;
+                };
+                source: {
+                    type: string;
+                };
+                requestId: {
+                    type: string;
+                };
+            };
+            indexes: {
+                name: string;
+                columns: string[];
+            }[];
+        };
+    };
+};
+export default _default;

package/dist/server/src/controllers/audit-log.d.ts

@@ -0,0 +1,31 @@
+import { Core } from '@strapi/strapi';
+type KoaContext = {
+    query: Record<string, unknown>;
+    params: Record<string, string>;
+    body: unknown;
+    badRequest: (message: string) => unknown;
+    notFound: (message?: string) => unknown;
+};
+/**
+ * Admin-only HTTP surface.
+ *
+ * Every route is registered with `type: 'admin'` and guarded by
+ * `admin::isAuthenticatedAdmin` plus an explicit `admin::hasPermissions` check —
+ * see `routes/admin.ts`. Nothing here re-implements authentication or
+ * authorisation; the controller runs only once Strapi's own RBAC has said yes.
+ *
+ * There is deliberately no create or update handler. Audit records are written
+ * by the plugin and read by humans; nothing in between.
+ */
+declare const auditLogController: ({ strapi }: {
+    strapi: Core.Strapi;
+}) => {
+    find(ctx: KoaContext): Promise<void>;
+    findOne(ctx: KoaContext): Promise<unknown>;
+    delete(ctx: KoaContext): Promise<unknown>;
+    /** Filter dropdown options, derived from the rows that actually exist. */
+    filters(ctx: KoaContext): Promise<void>;
+    /** The effective configuration, so the UI can hide controls for disabled features. */
+    config(ctx: KoaContext): Promise<void>;
+};
+export default auditLogController;

package/dist/server/src/controllers/index.d.ts

@@ -0,0 +1,42 @@
+declare const _default: {
+    'audit-log': ({ strapi }: {
+        strapi: import('@strapi/types/dist/core').Strapi;
+    }) => {
+        find(ctx: {
+            query: Record<string, unknown>;
+            params: Record<string, string>;
+            body: unknown;
+            badRequest: (message: string) => unknown;
+            notFound: (message?: string) => unknown;
+        }): Promise<void>;
+        findOne(ctx: {
+            query: Record<string, unknown>;
+            params: Record<string, string>;
+            body: unknown;
+            badRequest: (message: string) => unknown;
+            notFound: (message?: string) => unknown;
+        }): Promise<unknown>;
+        delete(ctx: {
+            query: Record<string, unknown>;
+            params: Record<string, string>;
+            body: unknown;
+            badRequest: (message: string) => unknown;
+            notFound: (message?: string) => unknown;
+        }): Promise<unknown>;
+        filters(ctx: {
+            query: Record<string, unknown>;
+            params: Record<string, string>;
+            body: unknown;
+            badRequest: (message: string) => unknown;
+            notFound: (message?: string) => unknown;
+        }): Promise<void>;
+        config(ctx: {
+            query: Record<string, unknown>;
+            params: Record<string, string>;
+            body: unknown;
+            badRequest: (message: string) => unknown;
+            notFound: (message?: string) => unknown;
+        }): Promise<void>;
+    };
+};
+export default _default;

package/dist/server/src/destroy.d.ts

@@ -0,0 +1,19 @@
+import { Core } from '@strapi/strapi';
+/**
+ * Shuts the plugin down cleanly.
+ *
+ * Flushing pending writes is the part that matters. In `writeMode: 'async'` the
+ * audit inserts are in flight when the process is asked to stop, and an audit
+ * trail that silently drops its last few records on every deploy is worse than
+ * useless — it is misleading. Draining here turns "async loses data on restart"
+ * into "async loses data only on a hard kill", which is a trade-off a reader of
+ * the README can actually reason about.
+ *
+ * The cron job is removed too, so a `strapi.destroy()` followed by a fresh boot
+ * in the same process (which is what the test harness and `strapi console` do)
+ * does not end up with two retention jobs scheduled.
+ */
+declare const destroy: ({ strapi }: {
+    strapi: Core.Strapi;
+}) => Promise<void>;
+export default destroy;