@jwilleke/ngdpbase-types 5.41.1 → 5.43.0

package/lib/src/managers/AuditManager.d.ts

@@ -0,0 +1,477 @@
+/**
+ * The caller may not query the audit log (#1116, #1165).
+ *
+ * A distinct type rather than a bare Error so a route can tell an
+ * authorization refusal from a genuine fault. #1165 was hard to diagnose
+ * precisely because it could not: the route's catch-all turned this refusal
+ * into `500 Error loading audit logs`, so "you may not read this" and
+ * "auditing is broken" were the same plain-text page.
+ *
+ * Matching on the message string would work today and break the first time
+ * somebody rewords it, which is why this is a type.
+ */
+export declare class AuditQueryForbiddenError extends Error {
+    constructor(message: string);
+}
+/**
+ * AuditManager - Comprehensive audit trail system for access control and security monitoring
+ *
+ * Extends BaseManager following the JSPWiki modular manager pattern with provider architecture.
+ * Follows the provider pattern established in CacheManager, AttachmentManager, PageManager.
+ * Supports pluggable audit storage backends (file, database, cloud logging).
+ *
+ * @class AuditManager
+ * @extends BaseManager
+ *
+ * @property {BaseAuditProvider|null} provider - The active audit provider
+ * @property {string|null} providerClass - The class name of the loaded provider
+ *
+ * @see {@link BaseManager} for base functionality
+ * @see {@link FileAuditProvider} for default provider implementation
+ *
+ * @example
+ * const auditManager = engine.getManager('AuditManager');
+ * await auditManager.logAccess('admin', 'Main', 'view', 'granted');
+ */
+import BaseManager, { type BackupData, type ManagerBackupOptions, type ManagerRestoreOptions } from './BaseManager.js';
+import { type ActorContext } from '../context/ActorContext.js';
+import type { PermissionSubject } from './UserManager.js';
+import { type AuditEventName } from '../utils/auditEventNames.js';
+import { WikiEngine } from '../types/WikiEngine.js';
+import type { ReportedValues } from './AuthManager.js';
+import type { AuditReport } from '../providers/BaseAuditProvider.js';
+import { type AuditRecordOutcome } from '../utils/auditEvents.js';
+/**
+ * Base audit event structure
+ */
+interface AuditEvent {
+    eventType: AuditEventName;
+    user: string;
+    userId?: string;
+    sessionId?: string;
+    ipAddress?: string;
+    userAgent?: string;
+    resource?: string;
+    resourceType?: string;
+    action?: string;
+    result?: string;
+    reason?: string;
+    policyId?: string;
+    policyName?: string;
+    severity?: 'low' | 'medium' | 'high' | 'critical';
+    duration?: number;
+    context?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    timestamp?: string;
+}
+/**
+ * User information for audit events
+ */
+interface AuditUser {
+    username?: string;
+    id?: string;
+    roles?: string[];
+    attributes?: Record<string, unknown>;
+}
+/**
+ * Context for access control decisions
+ */
+interface AccessContext {
+    user?: AuditUser;
+    sessionId?: string;
+    ipAddress?: string;
+    userAgent?: string;
+    resource?: string;
+    resourceType?: string;
+    action?: string;
+    requestMethod?: string;
+    requestPath?: string;
+    timestamp?: string;
+}
+/**
+ * Policy information
+ */
+interface PolicyInfo {
+    id: string;
+    name: string;
+    priority?: number;
+}
+/**
+ * Context for authentication events
+ */
+interface AuthenticationContext {
+    username?: string;
+    ipAddress?: string;
+    userAgent?: string;
+    loginMethod?: string;
+    attemptedUsername?: string;
+    /** #1633: an outside provider's reported `amr` / `acr`, and whether it is trusted; never a token. */
+    reported?: ReportedValues;
+    /** #1523 slice 1c: the second-factor prompt was skipped on a remembered browser. Not a factor. */
+    knownDevice?: boolean;
+    /** #1523: the RFC 8176 methods of a completed sign-in, so a remembered browser's row can be checked against it. */
+    amr?: string[];
+}
+/**
+ * What a remembered browser's row is checked against (#1523): the fields of
+ * one `authentication-success` record, never the rest of it.
+ */
+export interface AuthenticationRecordSummary {
+    id: string;
+    user: string;
+    loginMethod?: string;
+    amr?: string[];
+}
+/**
+ * Context for security events
+ */
+interface SecurityContext {
+    /**
+     * The context the event happened in (#1762 slice 4): the row's "who" is
+     * built from it (`actorOf`), so under a proxy grant it names both people.
+     * Mandatory: null only for a caller with no context (a sign-in throttle,
+     * before anyone is signed in). Never stored on the row itself.
+     */
+    subject: ActorContext | null;
+    /** The named user, for a caller with no context (a sign-in throttle, before anyone is signed in). */
+    user?: AuditUser;
+    ipAddress?: string;
+    userAgent?: string;
+    [key: string]: unknown;
+}
+/**
+ * Filters for searching audit logs
+ */
+interface AuditFilters {
+    user?: string;
+    /** The person who actually acted, under a proxy grant (#1762). */
+    actor?: string;
+    eventType?: string;
+    result?: string;
+    severity?: 'low' | 'medium' | 'high' | 'critical';
+    startDate?: string | Date;
+    endDate?: string | Date;
+    resource?: string;
+    action?: string;
+}
+/**
+ * Options for searching audit logs
+ */
+interface AuditSearchOptions {
+    limit?: number;
+    offset?: number;
+    sortBy?: string;
+    sortOrder?: 'asc' | 'desc';
+}
+/**
+ * Search results structure
+ */
+interface AuditSearchResults {
+    results: AuditEvent[];
+    total: number;
+    limit: number;
+    offset: number;
+    hasMore: boolean;
+}
+/**
+ * Audit statistics structure
+ */
+interface AuditStats {
+    totalEvents: number;
+    eventsByType: Record<string, number>;
+    eventsByResult: Record<string, number>;
+    eventsBySeverity: Record<string, number>;
+    eventsByUser: Record<string, number>;
+    recentActivity: AuditEvent[];
+    securityIncidents: number;
+}
+/**
+ * Who is asking for audit records (#1116): the request's subject (#1762
+ * slice 4), so the decision is the PDP's for the subject as it is — under a
+ * proxy grant, bounded by the grant and the actor — and the export row names
+ * both people. The permission decision is derived inside AuditManager, never
+ * passed in.
+ */
+export type AuditQueryCaller = PermissionSubject;
+declare class AuditManager extends BaseManager {
+    private provider;
+    private providerClass;
+    /**
+     * Creates a new AuditManager instance
+     *
+     * @constructor
+     * @param {WikiEngine} engine - The wiki engine instance
+     */
+    constructor(engine: WikiEngine);
+    /**
+     * Initialize the AuditManager and load the configured provider
+     *
+     * @async
+     * @param {Record<string, unknown>} [config={}] - Configuration object (unused, reads from ConfigurationManager)
+     * @returns {Promise<void>}
+     * @throws {Error} If ConfigurationManager is not available or provider fails to load
+     */
+    initialize(config?: Record<string, unknown>): Promise<void>;
+    /**
+     * Load the audit provider dynamically
+     *
+     * @private
+     * @returns {Promise<void>}
+     */
+    /**
+     * Whether auditing is running degraded — configured but not actually working
+     * (#1118).
+     *
+     * Distinct from auditing being OFF. An operator who selects
+     * `nullauditprovider`, or sets `ngdpbase.audit.enabled: false`, has made a
+     * decision that is on the record. An instance whose configured provider
+     * failed has not, and until this existed it had no way to say so: the server
+     * booted healthy, the audit page rendered empty, and the only thing that
+     * would have recorded the problem was the thing that failed.
+     */
+    private degraded;
+    /** True when audit is configured but not working. */
+    isDegraded(): boolean;
+    /** Why audit is degraded, or null. */
+    degradedReason(): string | null;
+    /**
+     * What this instance's auditing actually does right now (#1118).
+     *
+     * Reportable rather than inferable: a security property that has to be
+     * deduced from configuration is not one an instance can be assessed on.
+     */
+    getAuditPosture(): {
+        provider: string;
+        configured: string;
+        degraded: boolean;
+        reason: string | null;
+        guarantees: AuditReport | null;
+    };
+    /**
+     * Begin a new audit chain, recording that the old one was abandoned (#1124).
+     *
+     * Exposed so the operator command can reach it. Never called automatically —
+     * a system that silently repairs its own audit chain is worse than one that
+     * stays visibly broken.
+     */
+    restartAuditChain(reason: string, ctx: ActorContext): Promise<string>;
+    /**
+     * Fall back to the inert provider, recording that we did (#1118).
+     *
+     * @private
+     */
+    private degradeToNull;
+    private loadProvider;
+    /**
+     * Normalize provider name to PascalCase class name
+     *
+     * @param {string} providerName - Lowercase provider name (e.g., 'fileauditprovider')
+     * @returns {string} PascalCase class name (e.g., 'FileAuditProvider')
+     * @private
+     */
+    private normalizeProviderName;
+    /**
+     * Log an audit event
+     *
+     * @param {AuditEvent} auditEvent - Audit event data
+     * @returns {Promise<string>} Event ID
+     */
+    logAuditEvent(auditEvent: AuditEvent): Promise<string>;
+    /**
+     * The one door for the helpers below (#1205): through `recordAuditEvent`,
+     * so the `enabled` switch, the on-failure rule, and the outcome are the same as for
+     * every other emitter. Calling `logAuditEvent` directly skipped all three.
+     */
+    private record;
+    /** {@link record}, and the stored record's id when it was recorded (#1523). */
+    private recordWithId;
+    /**
+     * Log access control decision
+     *
+     * @param {AccessContext} context - Access context
+     * @param {string} result - 'allow', 'deny', 'error'
+     * @param {string} reason - Reason for the decision
+     * @param {PolicyInfo | null} policy - Policy that made the decision
+     * @returns What became of the record (#1205)
+     */
+    logAccessDecision(context: AccessContext, result: string, reason: string, policy?: PolicyInfo | null): Promise<AuditRecordOutcome>;
+    /**
+     * Log policy evaluation
+     *
+     * @param {AccessContext} context - Evaluation context
+     * @param {PolicyInfo[]} policies - Policies evaluated
+     * @param {string} finalResult - Final result
+     * @param {number} duration - Evaluation duration in ms
+     * @returns What became of the record (#1205)
+     */
+    logPolicyEvaluation(context: AccessContext, policies: PolicyInfo[], finalResult: string, duration: number): Promise<AuditRecordOutcome>;
+    /**
+     * Log authentication event
+     *
+     * @param {AuthenticationContext} context - Authentication context
+     * @param {string} result - 'success', 'failure', 'logout'
+     * @param {string} reason - Reason for result
+     * @returns What became of the record (#1205), and its id when it was
+     *   recorded: a remembered browser's row names its sign-in's record (#1523)
+     */
+    logAuthentication(context: AuthenticationContext, result: string, reason: string): Promise<{
+        outcome: AuditRecordOutcome;
+        id?: string;
+    }>;
+    /**
+     * The `authentication-success` record with this id, or null (#1523): a
+     * remembered browser counts only while the record of the sign-in that
+     * remembered it says the same as its row. Only the fields that check needs
+     * leave this method, so it is not an audit query and asks no caller; a
+     * record of any other kind is null. Null too when the provider cannot look
+     * a record up by id.
+     */
+    authenticationRecord(id: string): Promise<AuthenticationRecordSummary | null>;
+    /**
+     * Log security event
+     *
+     * @param {SecurityContext} context - Security context
+     * @param {string} eventType - Type of security event
+     * @param {string} severity - 'low', 'medium', 'high', 'critical'
+     * @param {string} description - Event description
+     * @returns What became of the record (#1205)
+     */
+    logSecurityEvent(context: SecurityContext, eventType: string, severity: 'low' | 'medium' | 'high' | 'critical', description: string): Promise<AuditRecordOutcome>;
+    /**
+     * #1116: the gate on every audit query, inside the door.
+     *
+     * The audit list was the counterexample to the list-gate rule: this manager
+     * applied no authorization of its own, safe only because one admin-system
+     * check gated the whole page at the route — exactly the reasoning that
+     * stops working the moment a second caller appears. The caller supplies its
+     * subject; the decision is derived here, by the PDP (#1762 slice 4: the
+     * subject as it is, so a person acting for someone is bounded by the grant
+     * and by what they hold themselves, never by the represented person's roles
+     * alone). Fail closed: no caller, no username, no PDP, or no permission all
+     * refuse. The audit log has no per-record narrowing, and a list that
+     * cannot be narrowed refuses rather than returning everything.
+     */
+    private assertQueryCallerAllowed;
+    /**
+     * Search audit logs
+     *
+     * @param {AuditFilters} filters - Search filters
+     * @param {AuditSearchOptions} options - Search options
+     * @param {AuditQueryCaller} caller - Who is asking: the request's subject (the decision is made here)
+     * @returns {Promise<AuditSearchResults>} Search results
+     */
+    searchAuditLogs(filters?: AuditFilters, options?: AuditSearchOptions, caller?: AuditQueryCaller): Promise<AuditSearchResults>;
+    /**
+     * The audit entries about one person, newest first, a page at a time
+     * (#1537): the one audit log, filtered to the rows where the person is the
+     * `user` (the account acted on, or the person represented under a proxy
+     * grant), the `actor` (who actually did it under a proxy grant), or the
+     * owner of the resource the row names (`metadata.owner`: the user's
+     * identity `@id` on rows from #2041 on, their username on older rows).
+     * Nothing is removed from the log by reading it.
+     *
+     * Decided by the PDP with the caller's subject: a person asking about
+     * themselves needs `profile-manage` (granted to every account); asking about
+     * anyone else is reading the audit log, `admin-system`. Under a proxy grant
+     * the subject's username is the person represented, and the PDP bounds the
+     * answer by the grant. Refused with {@link AuditQueryForbiddenError}.
+     *
+     * @param person - The username whose entries are listed
+     * @param options - `limit` (capped by the provider) and `offset`
+     * @param caller - Who is asking: the request's subject
+     */
+    searchEntriesAbout(person: string, options?: {
+        limit?: number;
+        offset?: number;
+    }, caller?: AuditQueryCaller): Promise<AuditSearchResults>;
+    /**
+     * Get audit statistics
+     *
+     * @param {AuditFilters} filters - Optional filters
+     * @returns {Promise<AuditStats>} Audit statistics
+     */
+    getAuditStats(filters?: AuditFilters, caller?: AuditQueryCaller): Promise<AuditStats>;
+    /**
+     * Export audit logs
+     *
+     * @param {AuditFilters} filters - Export filters
+     * @param {string} format - Export format ('json', 'csv')
+     * @param {AuditQueryCaller} caller - Who is asking (#1116)
+     * @returns {Promise<string>} Exported data
+     */
+    exportAuditLogs(filters?: AuditFilters, format?: string, caller?: AuditQueryCaller): Promise<string>;
+    /**
+     * Flush audit queue to disk
+     *
+     * @returns {Promise<void>}
+     */
+    flushAuditQueue(): Promise<void>;
+    /**
+     * Clean up old audit logs based on retention policy
+     *
+     * @returns {Promise<void>}
+     */
+    cleanupOldLogs(): Promise<void>;
+    /**
+     * The most recent record of a lifecycle phase, or null (#1149).
+     *
+     * A provider that cannot be searched returns null rather than throwing: an
+     * instance must still boot when its audit history is unreadable, and
+     * `assessPreviousRun` already treats missing evidence as `none` or `unknown`
+     * rather than inventing a verdict.
+     */
+    private lastLifecycleRecord;
+    /**
+     * Record that this process started, and what became of the previous one
+     * (#1149).
+     *
+     * The assessment is read BEFORE the new start is written, or the record
+     * being written would be the one it found.
+     */
+    private recordStart;
+    /**
+     * Record the security posture, and compare it against the previous start
+     * (#1156, D19).
+     *
+     * `config-change` audits what goes through `setProperty()`. This closes the
+     * two holes that leaves: an `app-custom-config.json` edited directly on disk
+     * emits nothing, and the state an instance STARTED in was never stated.
+     * Comparing consecutive boots surfaces an edit nothing observed.
+     *
+     * Emitted after `system-start`, deliberately: the start record establishes
+     * that this run began, and the posture record says what it began with.
+     */
+    private recordPosture;
+    /** Record that this process is stopping (#1149). */
+    private recordShutdown;
+    private emitLifecycle;
+    /** The active provider's file backup and staged restore, when it keeps files (FileAuditProvider, #1876). */
+    private fileProvider;
+    /**
+     * The audit log in a backup (#1876): the provider's own files beside the
+     * document, with the hash chain they carry (`FileAuditProvider.backupFiles`).
+     * A provider that keeps no files is not in the file backup: the database
+     * provider's records are in the application database, which DatabaseManager
+     * backs up after writing the audit queue (#1537).
+     */
+    backup(options?: ManagerBackupOptions): Promise<BackupData>;
+    /**
+     * Staged for the next start with the rest of a site restore (#1876); the
+     * live log keeps recording until then.
+     *
+     * A site whose audit provider keeps no files (the database provider, #1537)
+     * stages nothing from a backup's audit files and does not fail the restore:
+     * its audit records are restored with the databases, and the file part is
+     * left out, so BackupManager reports "the audit log" as not restored. The
+     * files stay in the backup.
+     */
+    restore(backupData: BackupData, options?: ManagerRestoreOptions): Promise<void>;
+    restoreIsStaged(): boolean;
+    /**
+     * Shutdown the audit manager
+     *
+     * @returns {Promise<void>}
+     */
+    shutdown(): Promise<void>;
+}
+export default AuditManager;