strapi-cms-audit-log 1.1.0

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

@@ -0,0 +1,328 @@
+/**
+ * Server half of the plugin, loaded by Strapi through the `./strapi-server`
+ * export in package.json.
+ */
+declare const _default: {
+    register: ({ strapi }: {
+        strapi: import('@strapi/types/dist/core').Strapi;
+    }) => Promise<void>;
+    bootstrap: ({ strapi }: {
+        strapi: import('@strapi/types/dist/core').Strapi;
+    }) => void;
+    destroy: ({ strapi }: {
+        strapi: import('@strapi/types/dist/core').Strapi;
+    }) => Promise<void>;
+    config: {
+        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;
+        };
+        validator(config: import('./types').AuditUserConfig & {
+            enabled?: boolean;
+        }): void;
+    };
+    contentTypes: {
+        '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[];
+                }[];
+            };
+        };
+    };
+    controllers: {
+        '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>;
+        };
+    };
+    routes: {
+        admin: {
+            type: string;
+            routes: {
+                method: string;
+                path: string;
+                handler: string;
+                config: {
+                    policies: (string | {
+                        name: string;
+                        config: {
+                            actions: string[];
+                        };
+                    })[];
+                };
+            }[];
+        };
+    };
+    services: {
+        access: ({ strapi }: {
+            strapi: import('@strapi/types/dist/core').Strapi;
+        }) => {
+            createMiddleware: () => (ctx: {
+                [x: string]: any;
+            }, next: () => Promise<unknown>) => Promise<void>;
+            register: () => void;
+            recordDenial: (ctx: {
+                [x: string]: any;
+            }) => Promise<void>;
+            sourceOf: (ctx: {
+                [x: string]: any;
+            }) => "admin" | "api" | "unknown";
+            isIgnoredPath: (path: string) => boolean;
+        };
+        audit: ({ strapi }: {
+            strapi: import('@strapi/types/dist/core').Strapi;
+        }) => {
+            record: (entry: import('./types').AuditEntryInput) => Promise<void>;
+            write: (entry: import('./types').AuditEntryInput) => Promise<void>;
+            flush: () => Promise<void>;
+            find: (query?: import('./types').AuditLogQuery) => Promise<import('./types').AuditLogListResult>;
+            findOne: (id: number) => Promise<import('./types').AuditLog | null>;
+            deleteOne: (id: number) => Promise<import('./types').AuditLog | null>;
+            deleteOlderThan: (date: Date) => Promise<number>;
+            getFilterOptions: () => Promise<import('./types').AuditFilterOptions>;
+            buildWhere: (query: import('./types').AuditLogQuery) => Record<string, unknown>;
+            parseSort: (sort: string | undefined) => Record<string, "asc" | "desc">;
+        };
+        config: ({ strapi }: {
+            strapi: import('@strapi/types/dist/core').Strapi;
+        }) => {
+            resolve: () => import('./services/config').ResolvedConfig;
+            isAuditedContentType: (uid: string) => boolean;
+            isAuditedAction: (action: import('./types').AuditAction) => boolean;
+            isAuditedSecurityAction: (action: import('./types').AuditSecurityAction) => boolean;
+            hasSecurityEvents: () => boolean;
+            enabledSecurityActions: () => import('./types').AuditSecurityAction[];
+            getPublicConfig: () => import('./types').AuditConfig;
+            clearCache: () => void;
+        };
+        context: ({ strapi }: {
+            strapi: import('@strapi/types/dist/core').Strapi;
+        }) => {
+            resolve: () => import('./types').AuditContext;
+            runAs: <T>(override: import('./services/context').SourceOverride, callback: () => T) => T;
+        };
+        diff: ({ strapi }: {
+            strapi: import('@strapi/types/dist/core').Strapi;
+        }) => {
+            buildDiff: (before: unknown, after: unknown, options?: import('./services/diff').DiffOptions) => import('./types').AuditChangeSet;
+        };
+        immutability: ({ strapi }: {
+            strapi: import('@strapi/types/dist/core').Strapi;
+        }) => {
+            createMiddleware: () => (ctx: {
+                uid: string;
+                action: string;
+            }, next: () => Promise<unknown>) => Promise<unknown>;
+            register: () => void;
+        };
+        retention: ({ strapi }: {
+            strapi: import('@strapi/types/dist/core').Strapi;
+        }) => {
+            cleanup: () => Promise<number>;
+            cutoffDate: (retentionDays: number, now?: Date) => Date;
+            register: () => void;
+            unregister: () => void;
+        };
+        security: ({ strapi }: {
+            strapi: import('@strapi/types/dist/core').Strapi;
+        }) => {
+            register: () => void;
+            unregister: () => void;
+            record: (action: import('./types').AuditSecurityAction, subject: string, fields?: {
+                contentDocumentId?: string | null;
+                contentId?: string | null;
+                user?: {
+                    [x: string]: any;
+                } | null;
+                before?: Record<string, unknown> | null;
+                after?: Record<string, unknown> | null;
+                metadata?: import('./types').AuditMetadata | null;
+                outcome?: import('./types').AuditOutcome;
+            }) => Promise<void>;
+            identify: (entity: {
+                [x: string]: any;
+            } | null | undefined) => Record<string, unknown> | null;
+            subjectOf: (payload: {
+                [x: string]: any;
+            }) => {
+                [x: string]: any;
+            } | null;
+            sourceOf: () => "admin" | "system";
+            entityHandler: (action: import('./types').AuditSecurityAction, subject: string) => (payload: {
+                [x: string]: any;
+            }) => Promise<void>;
+            handlers: Record<string, (payload: {
+                [x: string]: any;
+            }) => Promise<void>>;
+        };
+        snapshot: ({ strapi }: {
+            strapi: import('@strapi/types/dist/core').Strapi;
+        }) => {
+            buildSnapshotQuery: (uid: string, keys: string[] | null, options: {
+                depth: number;
+                isIgnored?: (path: string) => boolean;
+            }) => import('./services/snapshot').SnapshotQuery;
+            buildComponentPopulate: (componentUid: string, depth: number) => Record<string, unknown> | true;
+            buildWhere: (uid: string, lookup: import('./services/snapshot').SnapshotLookup) => Record<string, unknown>;
+            fetchRows: (uid: string, lookup: import('./services/snapshot').SnapshotLookup, query: import('./services/snapshot').SnapshotQuery, depth: number) => Promise<{
+                [x: string]: any;
+            }[]>;
+            refineDynamicZones: (uid: string, rows: {
+                [x: string]: any;
+            }[], query: import('./services/snapshot').SnapshotQuery, depth: number) => Promise<{
+                [x: string]: any;
+            }[]>;
+            toSnapshot: (row: {
+                [x: string]: any;
+            } | null | undefined) => Record<string, unknown> | null;
+            hasDraftAndPublish: (uid: string) => boolean;
+            isLocalized: (uid: string) => boolean;
+        };
+        tracker: ({ strapi }: {
+            strapi: import('@strapi/types/dist/core').Strapi;
+        }) => {
+            createMiddleware: () => (ctx: import('./services/tracker').DocumentMiddlewareContext, next: () => Promise<unknown>) => Promise<unknown>;
+            register: () => void;
+            changedKeys: (uid: string, params: Record<string, any>) => string[] | null;
+            resultRows: (result: unknown) => {
+                [x: string]: any;
+            }[];
+        };
+    };
+};
+export default _default;
+/** Public type surface — see `server/src/types`. */
+export type { AuditAction, AuditActor, AuditAnyAction, AuditChange, AuditChangeSet, AuditConfig, AuditContext, AuditEntryInput, AuditFilterOptions, AuditLog, AuditLogListResult, AuditLogQuery, AuditLogLevel, AuditMetadata, AuditOutcome, AuditRequestContext, AuditSecurityAction, AuditSource, AuditUserConfig, AuditWriteMode, ContentTypeSelector, SecurityEventSelector, } from './types';
+export { PLUGIN_ID, AUDIT_LOG_UID, PERMISSIONS, DEFAULT_IGNORED_FIELDS, CONTENT_ACTIONS, ALL_SECURITY_ACTIONS, SECURITY_EVENT_MAP, SUBJECTS, } from './constants';

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

@@ -0,0 +1,31 @@
+import { Core } from '@strapi/strapi';
+/**
+ * RBAC actions this plugin contributes.
+ *
+ * `section: 'plugins'` puts them in the Plugins tab of the role editor, next to
+ * the other plugins, and the provider namespaces each `uid` with the plugin name
+ * — `read` becomes `plugin::audit-log.read`.
+ *
+ * Read and delete are separate on purpose: an auditor needs to see the trail, an
+ * auditor must not be able to erase it, and collapsing the two into one
+ * permission would make that distinction unexpressible.
+ */
+declare const ACTIONS: {
+    section: string;
+    displayName: string;
+    uid: string;
+    pluginName: string;
+}[];
+/**
+ * Runs before content types are loaded and before `bootstrap`.
+ *
+ * Permissions are registered here rather than in `bootstrap` so the actions
+ * exist by the time the admin builds its permission sections — registering them
+ * later leaves the role editor with nothing to tick on the first boot after
+ * install.
+ */
+declare const register: ({ strapi }: {
+    strapi: Core.Strapi;
+}) => Promise<void>;
+export default register;
+export { ACTIONS };

package/dist/server/src/routes/admin.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Admin API for the plugin.
+ *
+ * `type: 'admin'` mounts these under the admin server and prefixes them with the
+ * plugin id, so the paths below become `/audit-log/logs`, `/audit-log/logs/:id`
+ * and so on. There is no `type: 'content-api'` route file, and that is the
+ * point: audit records are never reachable from the public content API, with or
+ * without an API token, because no public route exists to reach them.
+ */
+declare const _default: {
+    type: string;
+    routes: {
+        method: string;
+        path: string;
+        handler: string;
+        config: {
+            policies: (string | {
+                name: string;
+                config: {
+                    actions: string[];
+                };
+            })[];
+        };
+    }[];
+};
+export default _default;

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

@@ -0,0 +1,19 @@
+declare const _default: {
+    admin: {
+        type: string;
+        routes: {
+            method: string;
+            path: string;
+            handler: string;
+            config: {
+                policies: (string | {
+                    name: string;
+                    config: {
+                        actions: string[];
+                    };
+                })[];
+            };
+        }[];
+    };
+};
+export default _default;

package/dist/server/src/services/access.d.ts

@@ -0,0 +1,51 @@
+import { Core } from '@strapi/strapi';
+type KoaContext = Record<string, any>;
+/**
+ * Records requests Strapi refused: `401 Unauthorized` and `403 Forbidden`.
+ *
+ * This is the "unauthorized access / permission failures" line of a security
+ * review, and it is the one part of the audit trail that cannot come from an
+ * event, because Strapi emits none for a refusal. A denial is not a write, has
+ * no entity and touches no content type — it exists only as an HTTP status.
+ *
+ * ## Why this middleware sits outermost, and how it gets there
+ *
+ * `strapi.server.use()` appends to the Koa stack, and Strapi's boot order is:
+ *
+ * ```
+ *   register()            <- plugin register lifecycles run here
+ *   bootstrap()
+ *     server.initMiddlewares()   <- config/middlewares.ts is applied
+ *     server.initRouting()       <- routes and their policies are mounted
+ *     bootstrap lifecycles       <- plugin bootstrap runs here
+ * ```
+ *
+ * Registered from the plugin's `register`, this lands ahead of every configured
+ * middleware and ahead of the router — so by the time `await next()` returns,
+ * `strapi::errors` has already turned any thrown `ForbiddenError` into a status
+ * and `ctx.status` is final. Registered from `bootstrap` it would land *after*
+ * the router, see nothing, and fail silently. That ordering is the entire reason
+ * this service is wired up in `register.ts` rather than alongside the others in
+ * `bootstrap.ts`.
+ *
+ * ## What is deliberately not recorded
+ *
+ * A failed login is a 401, and it already produces a far better record from
+ * `admin.auth.error` — one that names the account that was tried. Recording the
+ * status too would double every wrong-password attempt, so the login and
+ * token-refresh paths are excluded by {@link ACCESS_IGNORED_PATHS}. 404s are
+ * excluded as well: Strapi answers an unauthorised *content API* read with a
+ * 404 rather than a 403 to avoid confirming that a document exists, and
+ * recording every 404 to catch those would bury the log in typos and favicon
+ * requests.
+ */
+declare const accessService: ({ strapi }: {
+    strapi: Core.Strapi;
+}) => {
+    createMiddleware: () => (ctx: KoaContext, next: () => Promise<unknown>) => Promise<void>;
+    register: () => void;
+    recordDenial: (ctx: KoaContext) => Promise<void>;
+    sourceOf: (ctx: KoaContext) => "admin" | "api" | "unknown";
+    isIgnoredPath: (path: string) => boolean;
+};
+export default accessService;

package/dist/server/src/services/audit.d.ts

@@ -0,0 +1,25 @@
+import { Core } from '@strapi/strapi';
+import { AuditEntryInput, AuditFilterOptions, AuditLog, AuditLogListResult, AuditLogQuery } from '../types';
+/**
+ * Persistence and retrieval of audit records.
+ *
+ * Every database call goes through `strapi.db.query`, never the Document
+ * Service. That is deliberate on both ends: writes must not re-enter the
+ * middleware that produced them, and reads must not be reshaped by document
+ * middlewares a consuming application has registered for its own content.
+ */
+declare const auditService: ({ strapi }: {
+    strapi: Core.Strapi;
+}) => {
+    record: (entry: AuditEntryInput) => Promise<void>;
+    write: (entry: AuditEntryInput) => Promise<void>;
+    flush: () => Promise<void>;
+    find: (query?: AuditLogQuery) => Promise<AuditLogListResult>;
+    findOne: (id: number) => Promise<AuditLog | null>;
+    deleteOne: (id: number) => Promise<AuditLog | null>;
+    deleteOlderThan: (date: Date) => Promise<number>;
+    getFilterOptions: () => Promise<AuditFilterOptions>;
+    buildWhere: (query: AuditLogQuery) => Record<string, unknown>;
+    parseSort: (sort: string | undefined) => Record<string, "asc" | "desc">;
+};
+export default auditService;

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

@@ -0,0 +1,30 @@
+import { Core } from '@strapi/strapi';
+import { PathMatcher } from '../utils/sanitize';
+import { AuditAction, AuditConfig, AuditSecurityAction } from '../types';
+export interface ResolvedConfig extends AuditConfig {
+    /** True when `changes` is excluded from a path as well as `before`/`after`. */
+    isIgnoredForChanges: PathMatcher;
+    /** True when a path must never be persisted anywhere. */
+    isIgnoredForSnapshot: PathMatcher;
+}
+/**
+ * Resolves and caches the effective configuration.
+ *
+ * Cached because it is read on the hot path — once per audited write — and
+ * because `createPathMatcher` compiles the ignore patterns. Nothing invalidates
+ * it: Strapi's plugin config is fixed at boot, so a cache miss can only happen
+ * once per process.
+ */
+declare const configService: ({ strapi }: {
+    strapi: Core.Strapi;
+}) => {
+    resolve: () => ResolvedConfig;
+    isAuditedContentType: (uid: string) => boolean;
+    isAuditedAction: (action: AuditAction) => boolean;
+    isAuditedSecurityAction: (action: AuditSecurityAction) => boolean;
+    hasSecurityEvents: () => boolean;
+    enabledSecurityActions: () => AuditSecurityAction[];
+    getPublicConfig: () => AuditConfig;
+    clearCache: () => void;
+};
+export default configService;

package/dist/server/src/services/context.d.ts

@@ -0,0 +1,33 @@
+import { Core } from '@strapi/strapi';
+import { AuditContext, AuditSource } from '../types';
+/**
+ * Overrides for code that runs outside a request.
+ *
+ * A migration script or a cron task has no Koa context, so without this every
+ * such write would land as `source: "system"` with no actor. `runAs` lets the
+ * consuming application label its own background work without the plugin having
+ * to guess, and without any caller-supplied value ever reaching an HTTP request
+ * — this store is process-local and can only be written from server code.
+ */
+export interface SourceOverride {
+    source: AuditSource;
+    userId?: string | null;
+    userEmail?: string | null;
+    userName?: string | null;
+}
+/**
+ * Derives who did what, from where.
+ *
+ * Everything comes from the server-side Koa context that Strapi keeps in
+ * AsyncLocalStorage (`strapi.requestContext`). Nothing is read from the request
+ * body or from a client-settable header other than the correlation id, which is
+ * treated as an opaque label and never used for authorisation — a client that
+ * lies about it can only confuse its own trace.
+ */
+declare const contextService: ({ strapi }: {
+    strapi: Core.Strapi;
+}) => {
+    resolve: () => AuditContext;
+    runAs: <T>(override: SourceOverride, callback: () => T) => T;
+};
+export default contextService;

package/dist/server/src/services/diff.d.ts

@@ -0,0 +1,48 @@
+import { Core } from '@strapi/strapi';
+import { PathMatcher } from '../utils/sanitize';
+import { AuditChangeSet } from '../types';
+export interface DiffOptions {
+    /** Paths excluded from the result. Already applied to `before`/`after` for the sensitive list; this one also carries `ignoredChangeFields`. */
+    isIgnored?: PathMatcher;
+    /**
+     * Restricts the diff to these top-level keys.
+     *
+     * For an update this is the set of attributes the caller actually sent, which
+     * is what makes the diff both meaningful and cheap: comparing keys the write
+     * never touched can only produce noise, and `before`/`after` were only
+     * populated for these keys in the first place.
+     */
+    keys?: string[] | null;
+    /**
+     * Longest path, in segments, before a whole subtree is recorded as one change.
+     *
+     * `maxDepth: 2` produces `seo.metaTitle` but collapses `a.b.c.d` into a single
+     * `a.b` entry holding both subtrees. A dynamic zone nested three components
+     * deep is still legible as `blocks[2].rows[0].label`; past that, a reader is
+     * better served by the raw JSON of the subtree than by a hundred leaf paths.
+     */
+    maxDepth?: number;
+    /** Ceiling on entries, so one pathological write cannot produce a megabyte of diff. */
+    maxChanges?: number;
+}
+/**
+ * Field-level diff between two snapshots.
+ *
+ * Entirely generic: it knows nothing about content types, components or dynamic
+ * zones, and works purely off the shape of the two values. That is deliberate —
+ * anything schema-aware would have to walk every component definition a type
+ * *could* hold, which for a page with 173 registered widgets is exactly the
+ * work this plugin exists to avoid.
+ *
+ * Arrays — repeatable components, dynamic zones, multi-relations, media lists —
+ * are compared by index and addressed as `blocks[2].heading`. Index comparison
+ * reports a reorder as a change to every moved element, which is honest: the
+ * stored order *is* the content, and a reader looking at "why did this page
+ * change" wants to see that the blocks moved.
+ */
+declare const diffService: ({ strapi }: {
+    strapi: Core.Strapi;
+}) => {
+    buildDiff: (before: unknown, after: unknown, options?: DiffOptions) => AuditChangeSet;
+};
+export default diffService;

package/dist/server/src/services/immutability.d.ts

@@ -0,0 +1,30 @@
+import { Core } from '@strapi/strapi';
+/**
+ * Second line of defence for audit-record immutability.
+ *
+ * The first line is structural: `content-manager: { visible: false }` on the
+ * schema means the Content Manager never registers create/update/delete RBAC
+ * actions for this content type, so there is no permission an administrator
+ * could grant that would let a role write these rows through the normal content
+ * APIs. That covers the panel and the content API.
+ *
+ * It does not cover *server* code. A plugin, a migration or a stray
+ * `strapi.documents('plugin::audit-log.audit-log').update(...)` in a bootstrap
+ * would otherwise succeed silently. This middleware makes that a loud failure.
+ *
+ * Deletion is not blocked here. It is a legitimate operation — retention runs on
+ * it — and it is gated where it belongs: the only HTTP route that deletes
+ * requires `plugin::audit-log.delete`. The plugin's own writes and deletes go
+ * through `strapi.db.query`, below the Document Service, so this guard never
+ * needs an escape hatch that an attacker could reach for.
+ */
+declare const immutabilityService: ({ strapi }: {
+    strapi: Core.Strapi;
+}) => {
+    createMiddleware: () => (ctx: {
+        uid: string;
+        action: string;
+    }, next: () => Promise<unknown>) => Promise<unknown>;
+    register: () => void;
+};
+export default immutabilityService;