@unchainedshop/events 4.5.0 → 4.6.0

package/lib/EventDirector.js

@@ -31,7 +31,7 @@ export const EventDirector = {
         HistoryAdapter?.publish(eventName, {
             payload,
         });
-        logger.debug(`EventDirector -> Emitted ${eventName} with ${JSON.stringify(data)}`);
+        logger.debug(`EventDirector -> Emitted ${eventName}`);
     },
     subscribe: (eventName, callback) => {
         const currentSubscription = `${eventName}${callback?.toString()}`;

package/lib/audit/audit-integration.d.ts

@@ -0,0 +1,3 @@
+import type { AuditLog } from './index.ts';
+export declare function configureAuditIntegration(auditLog: AuditLog): void;
+export declare const AUDITED_EVENTS: readonly ["API_LOGIN_TOKEN_CREATED", "API_LOGOUT", "USER_CREATE", "USER_REMOVE", "USER_UPDATE_PASSWORD", "USER_ADD_ROLES", "USER_UPDATE_ROLE", "USER_ACCOUNT_ACTION", "ORDER_CREATE", "ORDER_CHECKOUT", "ORDER_CONFIRMED", "ORDER_FULFILLED", "ORDER_REJECTED", "ORDER_ADD_PRODUCT", "ORDER_REMOVE_CART_ITEM", "ORDER_PAY", "ORDER_UPDATE_PAYMENT"];

package/lib/audit/audit-integration.js

@@ -0,0 +1,200 @@
+import { createLogger } from '@unchainedshop/logger';
+import { EventDirector } from "../EventDirector.js";
+import { OCSF_AUTH_ACTIVITY, OCSF_ACCOUNT_ACTIVITY, OCSF_API_ACTIVITY } from "./ocsf-types.js";
+const logger = createLogger('unchained:audit-integration');
+function extractContext(payload) {
+    return {
+        userId: payload.userId || payload.user?._id || payload.user?.id,
+        userName: payload.userName || payload.user?.username || payload.user?.emails?.[0]?.address,
+        remoteAddress: payload.remoteAddress || payload.ip,
+        sessionId: payload.sessionId,
+    };
+}
+const ACCOUNT_ACTION_MAP = {
+    'reset-password': {
+        activity: OCSF_ACCOUNT_ACTIVITY.PASSWORD_RESET,
+        message: 'Password reset requested',
+    },
+    'verify-email': { activity: OCSF_ACCOUNT_ACTIVITY.ENABLE, message: 'Email verified' },
+    'enroll-account': { activity: OCSF_ACCOUNT_ACTIVITY.ENABLE, message: 'Account enrolled' },
+};
+export function configureAuditIntegration(auditLog) {
+    const sub = (event, handler) => {
+        try {
+            EventDirector.subscribe(event, async ({ payload }) => {
+                try {
+                    await handler(payload);
+                }
+                catch (error) {
+                    logger.error(`Audit log error for ${event}: ${error}`);
+                }
+            });
+        }
+        catch {
+        }
+    };
+    sub('API_LOGIN_TOKEN_CREATED', async (p) => {
+        const ctx = extractContext(p);
+        await auditLog.logAuthentication({ activity: OCSF_AUTH_ACTIVITY.LOGON, ...ctx, success: true });
+    });
+    sub('API_LOGOUT', async (p) => {
+        const ctx = extractContext(p);
+        await auditLog.logAuthentication({ activity: OCSF_AUTH_ACTIVITY.LOGOFF, ...ctx, success: true });
+    });
+    sub('USER_CREATE', async (p) => {
+        const ctx = extractContext(p);
+        await auditLog.logAccountChange({ activity: OCSF_ACCOUNT_ACTIVITY.CREATE, ...ctx, success: true });
+    });
+    sub('USER_REMOVE', async (p) => {
+        const ctx = extractContext(p);
+        await auditLog.logAccountChange({ activity: OCSF_ACCOUNT_ACTIVITY.DELETE, ...ctx, success: true });
+    });
+    sub('USER_UPDATE_PASSWORD', async (p) => {
+        const ctx = extractContext(p);
+        await auditLog.logAccountChange({
+            activity: OCSF_ACCOUNT_ACTIVITY.PASSWORD_CHANGE,
+            ...ctx,
+            success: true,
+        });
+    });
+    sub('USER_ADD_ROLES', async (p) => {
+        const ctx = extractContext(p);
+        await auditLog.logAccountChange({
+            activity: OCSF_ACCOUNT_ACTIVITY.ATTACH_POLICY,
+            ...ctx,
+            success: true,
+            message: `Roles added: ${p.roles?.join(', ') || 'unknown'}`,
+        });
+    });
+    sub('USER_UPDATE_ROLE', async (p) => {
+        const ctx = extractContext(p);
+        await auditLog.logAccountChange({
+            activity: OCSF_ACCOUNT_ACTIVITY.ATTACH_POLICY,
+            ...ctx,
+            success: true,
+            message: 'User roles updated',
+        });
+    });
+    sub('USER_ACCOUNT_ACTION', async (p) => {
+        const ctx = extractContext(p);
+        const mapped = ACCOUNT_ACTION_MAP[p.action] || {
+            activity: OCSF_ACCOUNT_ACTIVITY.OTHER,
+            message: 'Account action',
+        };
+        await auditLog.logAccountChange({ ...mapped, ...ctx, success: true });
+    });
+    sub('ORDER_CREATE', async (p) => {
+        const ctx = extractContext(p);
+        await auditLog.logApiActivity({
+            activity: OCSF_API_ACTIVITY.CREATE,
+            ...ctx,
+            userId: p.order?.userId || ctx.userId,
+            success: true,
+            operation: 'createOrder',
+            message: `Order created: ${p.order?._id || 'unknown'}`,
+        });
+    });
+    sub('ORDER_CHECKOUT', async (p) => {
+        const ctx = extractContext(p);
+        await auditLog.logApiActivity({
+            activity: OCSF_API_ACTIVITY.CHECKOUT,
+            ...ctx,
+            userId: p.order?.userId || ctx.userId,
+            success: true,
+            operation: 'checkoutOrder',
+            message: `Order checkout: ${p.order?._id || 'unknown'}`,
+        });
+    });
+    sub('ORDER_CONFIRMED', async (p) => {
+        const ctx = extractContext(p);
+        await auditLog.logApiActivity({
+            activity: OCSF_API_ACTIVITY.UPDATE,
+            ...ctx,
+            userId: p.order?.userId || ctx.userId,
+            success: true,
+            operation: 'confirmOrder',
+            message: `Order confirmed: ${p.order?._id || 'unknown'}`,
+        });
+    });
+    sub('ORDER_FULFILLED', async (p) => {
+        const ctx = extractContext(p);
+        await auditLog.logApiActivity({
+            activity: OCSF_API_ACTIVITY.UPDATE,
+            ...ctx,
+            userId: p.order?.userId || ctx.userId,
+            success: true,
+            operation: 'fulfillOrder',
+            message: `Order fulfilled: ${p.order?._id || 'unknown'}`,
+        });
+    });
+    sub('ORDER_REJECTED', async (p) => {
+        const ctx = extractContext(p);
+        await auditLog.logApiActivity({
+            activity: OCSF_API_ACTIVITY.UPDATE,
+            ...ctx,
+            userId: p.order?.userId || ctx.userId,
+            success: false,
+            operation: 'rejectOrder',
+            message: `Order rejected: ${p.order?._id || 'unknown'}`,
+        });
+    });
+    sub('ORDER_ADD_PRODUCT', async (p) => {
+        const ctx = extractContext(p);
+        await auditLog.logApiActivity({
+            activity: OCSF_API_ACTIVITY.UPDATE,
+            ...ctx,
+            success: true,
+            operation: 'addToCart',
+            message: `Product added to cart: ${p.orderPosition?.productId || 'unknown'}`,
+        });
+    });
+    sub('ORDER_REMOVE_CART_ITEM', async (p) => {
+        const ctx = extractContext(p);
+        await auditLog.logApiActivity({
+            activity: OCSF_API_ACTIVITY.DELETE,
+            ...ctx,
+            success: true,
+            operation: 'removeFromCart',
+            message: 'Product removed from cart',
+        });
+    });
+    sub('ORDER_PAY', async (p) => {
+        const ctx = extractContext(p);
+        await auditLog.logApiActivity({
+            activity: OCSF_API_ACTIVITY.PAYMENT,
+            ...ctx,
+            success: true,
+            operation: 'processPayment',
+            message: 'Payment processed for order',
+        });
+    });
+    sub('ORDER_UPDATE_PAYMENT', async (p) => {
+        const ctx = extractContext(p);
+        await auditLog.logApiActivity({
+            activity: OCSF_API_ACTIVITY.PAYMENT,
+            ...ctx,
+            success: true,
+            operation: 'updatePayment',
+            message: 'Payment updated',
+        });
+    });
+}
+export const AUDITED_EVENTS = [
+    'API_LOGIN_TOKEN_CREATED',
+    'API_LOGOUT',
+    'USER_CREATE',
+    'USER_REMOVE',
+    'USER_UPDATE_PASSWORD',
+    'USER_ADD_ROLES',
+    'USER_UPDATE_ROLE',
+    'USER_ACCOUNT_ACTION',
+    'ORDER_CREATE',
+    'ORDER_CHECKOUT',
+    'ORDER_CONFIRMED',
+    'ORDER_FULFILLED',
+    'ORDER_REJECTED',
+    'ORDER_ADD_PRODUCT',
+    'ORDER_REMOVE_CART_ITEM',
+    'ORDER_PAY',
+    'ORDER_UPDATE_PAYMENT',
+];

package/lib/audit/index.d.ts

@@ -0,0 +1,95 @@
+import { type OCSFEvent, OCSF_AUTH_ACTIVITY, OCSF_ACCOUNT_ACTIVITY, OCSF_API_ACTIVITY } from './ocsf-types.ts';
+export * from './ocsf-types.ts';
+export interface AuditLogConfig {
+    directory?: string;
+    collectorUrl?: string;
+    collectorHeaders?: Record<string, string>;
+    batchSize?: number;
+    flushIntervalMs?: number;
+}
+export interface AuthenticationInput {
+    activity: (typeof OCSF_AUTH_ACTIVITY)[keyof typeof OCSF_AUTH_ACTIVITY];
+    userId?: string;
+    userName?: string;
+    success?: boolean;
+    remoteAddress?: string;
+    sessionId?: string;
+    message?: string;
+    isMfa?: boolean;
+    authProtocol?: string;
+}
+export interface AccountChangeInput {
+    activity: (typeof OCSF_ACCOUNT_ACTIVITY)[keyof typeof OCSF_ACCOUNT_ACTIVITY];
+    userId?: string;
+    userName?: string;
+    success?: boolean;
+    remoteAddress?: string;
+    sessionId?: string;
+    message?: string;
+    actorUserId?: string;
+    actorUserName?: string;
+}
+export interface ApiActivityInput {
+    activity: (typeof OCSF_API_ACTIVITY)[keyof typeof OCSF_API_ACTIVITY];
+    userId?: string;
+    userName?: string;
+    success?: boolean;
+    remoteAddress?: string;
+    sessionId?: string;
+    message?: string;
+    operation?: string;
+    httpMethod?: string;
+    path?: string;
+    responseCode?: number;
+}
+export interface AuditLogQuery {
+    classUids?: number[];
+    activityIds?: number[];
+    userId?: string;
+    success?: boolean;
+    startTime?: Date;
+    endTime?: Date;
+    limit?: number;
+    offset?: number;
+}
+export interface VerifyResult {
+    valid: boolean;
+    entries: number;
+    verified: number;
+    error?: string;
+}
+export declare class AuditLog {
+    private readonly dir;
+    private readonly collectorUrl?;
+    private readonly collectorHeaders;
+    private readonly batchSize;
+    private readonly flushIntervalMs;
+    private lastEvent;
+    private writeLock;
+    private initialized;
+    private pendingEvents;
+    private flushTimer?;
+    constructor(config?: AuditLogConfig);
+    private getFilePath;
+    private init;
+    private computeHash;
+    private createMetadata;
+    private createUser;
+    private createEndpoint;
+    private writeEvent;
+    private flushToCollector;
+    private matches;
+    logAuthentication(input: AuthenticationInput): Promise<string>;
+    logAccountChange(input: AccountChangeInput): Promise<string>;
+    logApiActivity(input: ApiActivityInput): Promise<string>;
+    find(query?: AuditLogQuery): Promise<OCSFEvent[]>;
+    count(query?: AuditLogQuery): Promise<number>;
+    getFailedLogins(params: {
+        userId?: string;
+        remoteAddress?: string;
+        since?: Date;
+    }): Promise<number>;
+    verify(): Promise<VerifyResult>;
+    close(): Promise<void>;
+}
+export declare function createAuditLog(config?: AuditLogConfig | string): AuditLog;

package/lib/audit/index.js

@@ -0,0 +1,416 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, appendFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createLogger } from '@unchainedshop/logger';
+import { OCSF_CLASS, OCSF_CATEGORY, OCSF_SEVERITY, OCSF_STATUS, OCSF_AUTH_ACTIVITY, OCSF_ACCOUNT_ACTIVITY, OCSF_API_ACTIVITY, } from "./ocsf-types.js";
+export * from "./ocsf-types.js";
+const logger = createLogger('unchained:audit');
+const OCSF_VERSION = '1.4.0';
+const PRODUCT_NAME = 'Unchained Engine';
+const PRODUCT_VERSION = '4.5';
+const PRODUCT_VENDOR = 'Unchained';
+const GENESIS_HASH = '0'.repeat(64);
+export class AuditLog {
+    dir;
+    collectorUrl;
+    collectorHeaders;
+    batchSize;
+    flushIntervalMs;
+    lastEvent = null;
+    writeLock = Promise.resolve();
+    initialized = false;
+    pendingEvents = [];
+    flushTimer;
+    constructor(config = {}) {
+        this.dir = config.directory || './audit-logs';
+        this.collectorUrl = config.collectorUrl;
+        this.collectorHeaders = config.collectorHeaders || {};
+        this.batchSize = config.batchSize || 10;
+        this.flushIntervalMs = config.flushIntervalMs || 5000;
+    }
+    getFilePath() {
+        const date = new Date().toISOString().slice(0, 10);
+        return join(this.dir, `audit-${date}.jsonl`);
+    }
+    async init() {
+        if (this.initialized)
+            return;
+        await mkdir(this.dir, { recursive: true });
+        try {
+            const files = (await readdir(this.dir)).filter((f) => f.endsWith('.jsonl')).sort();
+            for (let i = files.length - 1; i >= 0; i--) {
+                const content = await readFile(join(this.dir, files[i]), 'utf-8');
+                const lines = content.trim().split('\n').filter(Boolean);
+                if (lines.length > 0) {
+                    const parsed = JSON.parse(lines[lines.length - 1]);
+                    if (parsed.unmapped?.hash) {
+                        this.lastEvent = parsed;
+                        break;
+                    }
+                }
+            }
+        }
+        catch {
+        }
+        if (this.collectorUrl && !this.flushTimer) {
+            this.flushTimer = setInterval(() => this.flushToCollector(), this.flushIntervalMs);
+        }
+        this.initialized = true;
+    }
+    computeHash(event) {
+        const { unmapped, ...rest } = event;
+        const toHash = {
+            ...rest,
+            unmapped: unmapped ? { seq: unmapped.seq, prev_hash: unmapped.prev_hash } : undefined,
+        };
+        const data = JSON.stringify(toHash, Object.keys(toHash).sort());
+        return createHash('sha256').update(data, 'utf8').digest('hex');
+    }
+    createMetadata(uid) {
+        return {
+            version: OCSF_VERSION,
+            product: {
+                name: PRODUCT_NAME,
+                version: PRODUCT_VERSION,
+                vendor_name: PRODUCT_VENDOR,
+            },
+            uid,
+        };
+    }
+    createUser(userId, userName) {
+        return {
+            uid: userId,
+            name: userName,
+            email_addr: userName?.includes('@') ? userName : undefined,
+        };
+    }
+    createEndpoint(ip) {
+        if (!ip)
+            return undefined;
+        return { ip };
+    }
+    async writeEvent(event) {
+        const result = this.writeLock.then(async () => {
+            await this.init();
+            const prevHash = this.lastEvent?.unmapped?.hash || GENESIS_HASH;
+            const seq = (this.lastEvent?.unmapped?.seq || 0) + 1;
+            const eventWithChain = {
+                ...event,
+                unmapped: {
+                    seq,
+                    prev_hash: prevHash,
+                    hash: '',
+                },
+            };
+            const hash = this.computeHash(eventWithChain);
+            eventWithChain.unmapped.hash = hash;
+            const line = JSON.stringify(eventWithChain);
+            await appendFile(this.getFilePath(), line + '\n', 'utf-8');
+            this.lastEvent = eventWithChain;
+            if (this.collectorUrl) {
+                this.pendingEvents.push(eventWithChain);
+                if (this.pendingEvents.length >= this.batchSize) {
+                    this.flushToCollector().catch((err) => logger.error(`Failed to flush to collector: ${err.message}`));
+                }
+            }
+            logger.debug(`Audit: ${event.message || 'Event'} [class=${event.class_uid}] seq=${seq}`);
+            return eventWithChain.metadata.uid;
+        });
+        this.writeLock = result;
+        return result;
+    }
+    async flushToCollector() {
+        if (!this.collectorUrl || this.pendingEvents.length === 0)
+            return;
+        const events = [...this.pendingEvents];
+        this.pendingEvents = [];
+        try {
+            const response = await fetch(this.collectorUrl, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...this.collectorHeaders,
+                },
+                body: JSON.stringify({ events }),
+            });
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+            }
+            logger.debug(`Flushed ${events.length} events to collector`);
+        }
+        catch (err) {
+            this.pendingEvents = [...events, ...this.pendingEvents];
+            throw err;
+        }
+    }
+    matches(event, query) {
+        if (query.classUids?.length && !query.classUids.includes(event.class_uid))
+            return false;
+        if (query.activityIds?.length && !query.activityIds.includes(event.activity_id))
+            return false;
+        const userId = 'user' in event ? event.user?.uid : undefined;
+        const actorId = 'actor' in event ? event.actor?.user?.uid : undefined;
+        if (query.userId && userId !== query.userId && actorId !== query.userId)
+            return false;
+        if (query.success !== undefined) {
+            const isSuccess = event.status_id === OCSF_STATUS.SUCCESS;
+            if (query.success !== isSuccess)
+                return false;
+        }
+        if (query.startTime || query.endTime) {
+            const ts = new Date(event.time);
+            if (query.startTime && ts < query.startTime)
+                return false;
+            if (query.endTime && ts > query.endTime)
+                return false;
+        }
+        return true;
+    }
+    async logAuthentication(input) {
+        const activityId = input.activity;
+        const activityMessages = {
+            [OCSF_AUTH_ACTIVITY.LOGON]: 'User Login',
+            [OCSF_AUTH_ACTIVITY.LOGOFF]: 'User Logout',
+        };
+        const event = {
+            category_uid: OCSF_CATEGORY.IDENTITY_ACCESS_MGMT,
+            class_uid: OCSF_CLASS.AUTHENTICATION,
+            type_uid: OCSF_CLASS.AUTHENTICATION * 100 + activityId,
+            activity_id: activityId,
+            severity_id: input.success === false ? OCSF_SEVERITY.HIGH : OCSF_SEVERITY.INFORMATIONAL,
+            status_id: input.success === false ? OCSF_STATUS.FAILURE : OCSF_STATUS.SUCCESS,
+            time: Date.now(),
+            message: input.message || activityMessages[activityId] || 'Authentication Event',
+            metadata: this.createMetadata(crypto.randomUUID()),
+            user: this.createUser(input.userId, input.userName),
+            src_endpoint: this.createEndpoint(input.remoteAddress),
+            is_mfa: input.isMfa,
+            auth_protocol: input.authProtocol,
+            session: input.sessionId ? { uid: input.sessionId } : undefined,
+        };
+        return this.writeEvent(event);
+    }
+    async logAccountChange(input) {
+        const activityId = input.activity;
+        const activityMessages = {
+            [OCSF_ACCOUNT_ACTIVITY.CREATE]: 'User Created',
+            [OCSF_ACCOUNT_ACTIVITY.DELETE]: 'User Deleted',
+            [OCSF_ACCOUNT_ACTIVITY.PASSWORD_CHANGE]: 'Password Changed',
+            [OCSF_ACCOUNT_ACTIVITY.PASSWORD_RESET]: 'Password Reset',
+            [OCSF_ACCOUNT_ACTIVITY.ATTACH_POLICY]: 'User Roles Changed',
+            [OCSF_ACCOUNT_ACTIVITY.MFA_ENABLE]: 'MFA Enabled',
+            [OCSF_ACCOUNT_ACTIVITY.MFA_DISABLE]: 'MFA Disabled',
+        };
+        const event = {
+            category_uid: OCSF_CATEGORY.IDENTITY_ACCESS_MGMT,
+            class_uid: OCSF_CLASS.ACCOUNT_CHANGE,
+            type_uid: OCSF_CLASS.ACCOUNT_CHANGE * 100 + activityId,
+            activity_id: activityId,
+            severity_id: input.success === false ? OCSF_SEVERITY.HIGH : OCSF_SEVERITY.INFORMATIONAL,
+            status_id: input.success === false ? OCSF_STATUS.FAILURE : OCSF_STATUS.SUCCESS,
+            time: Date.now(),
+            message: input.message || activityMessages[activityId] || 'Account Change',
+            metadata: this.createMetadata(crypto.randomUUID()),
+            user: this.createUser(input.userId, input.userName),
+            actor: input.actorUserId
+                ? {
+                    user: this.createUser(input.actorUserId, input.actorUserName),
+                    session: input.sessionId ? { uid: input.sessionId } : undefined,
+                }
+                : undefined,
+            src_endpoint: this.createEndpoint(input.remoteAddress),
+        };
+        return this.writeEvent(event);
+    }
+    async logApiActivity(input) {
+        const activityId = input.activity;
+        const activityMessages = {
+            [OCSF_API_ACTIVITY.CREATE]: 'Resource Created',
+            [OCSF_API_ACTIVITY.READ]: 'Resource Read',
+            [OCSF_API_ACTIVITY.UPDATE]: 'Resource Updated',
+            [OCSF_API_ACTIVITY.DELETE]: 'Resource Deleted',
+            [OCSF_API_ACTIVITY.CHECKOUT]: 'Order Checkout',
+            [OCSF_API_ACTIVITY.PAYMENT]: 'Payment Processed',
+            [OCSF_API_ACTIVITY.REFUND]: 'Refund Processed',
+            [OCSF_API_ACTIVITY.EXPORT]: 'Data Exported',
+            [OCSF_API_ACTIVITY.IMPORT]: 'Data Imported',
+            [OCSF_API_ACTIVITY.ACCESS_DENIED]: 'Access Denied',
+        };
+        const isAccessDenied = activityId === OCSF_API_ACTIVITY.ACCESS_DENIED;
+        const severity = isAccessDenied || input.success === false ? OCSF_SEVERITY.HIGH : OCSF_SEVERITY.INFORMATIONAL;
+        const event = {
+            category_uid: OCSF_CATEGORY.APPLICATION_ACTIVITY,
+            class_uid: OCSF_CLASS.API_ACTIVITY,
+            type_uid: OCSF_CLASS.API_ACTIVITY * 100 + activityId,
+            activity_id: activityId,
+            severity_id: severity,
+            status_id: input.success === false ? OCSF_STATUS.FAILURE : OCSF_STATUS.SUCCESS,
+            time: Date.now(),
+            message: input.message || activityMessages[activityId] || 'API Activity',
+            metadata: this.createMetadata(crypto.randomUUID()),
+            actor: {
+                user: this.createUser(input.userId, input.userName),
+                session: input.sessionId ? { uid: input.sessionId } : undefined,
+            },
+            api: {
+                operation: input.operation,
+                response: input.responseCode ? { code: input.responseCode } : undefined,
+            },
+            src_endpoint: this.createEndpoint(input.remoteAddress),
+            http_request: input.httpMethod || input.path
+                ? {
+                    http_method: input.httpMethod,
+                    url: input.path ? { path: input.path } : undefined,
+                }
+                : undefined,
+        };
+        return this.writeEvent(event);
+    }
+    async find(query = {}) {
+        await this.init();
+        const results = [];
+        const limit = query.limit || 100;
+        const offset = query.offset || 0;
+        let skipped = 0;
+        try {
+            const files = (await readdir(this.dir)).filter((f) => f.endsWith('.jsonl')).sort();
+            for (let i = files.length - 1; i >= 0 && results.length < limit; i--) {
+                const content = await readFile(join(this.dir, files[i]), 'utf-8');
+                const lines = content.trim().split('\n').filter(Boolean);
+                for (let j = lines.length - 1; j >= 0 && results.length < limit; j--) {
+                    try {
+                        const event = JSON.parse(lines[j]);
+                        if (!this.matches(event, query))
+                            continue;
+                        if (skipped < offset) {
+                            skipped++;
+                            continue;
+                        }
+                        results.push(event);
+                    }
+                    catch {
+                    }
+                }
+            }
+        }
+        catch {
+        }
+        return results;
+    }
+    async count(query = {}) {
+        await this.init();
+        let count = 0;
+        try {
+            const files = (await readdir(this.dir)).filter((f) => f.endsWith('.jsonl')).sort();
+            for (const file of files) {
+                const content = await readFile(join(this.dir, file), 'utf-8');
+                const lines = content.trim().split('\n').filter(Boolean);
+                for (const line of lines) {
+                    try {
+                        const event = JSON.parse(line);
+                        if (this.matches(event, query))
+                            count++;
+                    }
+                    catch {
+                    }
+                }
+            }
+        }
+        catch {
+        }
+        return count;
+    }
+    async getFailedLogins(params) {
+        const events = await this.find({
+            classUids: [OCSF_CLASS.AUTHENTICATION],
+            activityIds: [OCSF_AUTH_ACTIVITY.LOGON],
+            userId: params.userId,
+            success: false,
+            startTime: params.since,
+        });
+        if (params.remoteAddress) {
+            return events.filter((e) => {
+                const authEvent = e;
+                return authEvent.src_endpoint?.ip === params.remoteAddress;
+            }).length;
+        }
+        return events.length;
+    }
+    async verify() {
+        await this.init();
+        let entries = 0;
+        let verified = 0;
+        let prevHash = GENESIS_HASH;
+        let prevSeq = 0;
+        try {
+            const files = (await readdir(this.dir)).filter((f) => f.endsWith('.jsonl')).sort();
+            for (const file of files) {
+                const content = await readFile(join(this.dir, file), 'utf-8');
+                const lines = content.trim().split('\n').filter(Boolean);
+                for (const line of lines) {
+                    entries++;
+                    let event;
+                    try {
+                        event = JSON.parse(line);
+                    }
+                    catch {
+                        return { valid: false, entries, verified, error: `Parse error at entry ${entries}` };
+                    }
+                    if (!event.unmapped) {
+                        return { valid: false, entries, verified, error: `Missing hash chain at entry ${entries}` };
+                    }
+                    if (event.unmapped.seq !== prevSeq + 1) {
+                        return { valid: false, entries, verified, error: `Sequence gap at ${event.unmapped.seq}` };
+                    }
+                    if (event.unmapped.prev_hash !== prevHash) {
+                        return {
+                            valid: false,
+                            entries,
+                            verified,
+                            error: `Chain broken at seq ${event.unmapped.seq}`,
+                        };
+                    }
+                    const computedHash = this.computeHash(event);
+                    if (computedHash !== event.unmapped.hash) {
+                        return {
+                            valid: false,
+                            entries,
+                            verified,
+                            error: `Hash mismatch at seq ${event.unmapped.seq}`,
+                        };
+                    }
+                    verified++;
+                    prevHash = event.unmapped.hash;
+                    prevSeq = event.unmapped.seq;
+                }
+            }
+        }
+        catch (e) {
+            return { valid: false, entries, verified, error: `Read error: ${e}` };
+        }
+        return { valid: true, entries, verified };
+    }
+    async close() {
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = undefined;
+        }
+        if (this.collectorUrl && this.pendingEvents.length > 0) {
+            try {
+                await this.flushToCollector();
+            }
+            catch (err) {
+                logger.error(`Failed to flush pending events on close: ${err.message}`);
+            }
+        }
+        await this.writeLock;
+        this.initialized = false;
+        this.lastEvent = null;
+    }
+}
+export function createAuditLog(config) {
+    if (typeof config === 'string') {
+        return new AuditLog({ directory: config });
+    }
+    return new AuditLog(config);
+}

package/lib/audit/ocsf-types.d.ts

@@ -0,0 +1,165 @@
+export declare const OCSF_CATEGORY: {
+    readonly IDENTITY_ACCESS_MGMT: 3;
+    readonly APPLICATION_ACTIVITY: 6;
+};
+export declare const OCSF_CLASS: {
+    readonly ACCOUNT_CHANGE: 3001;
+    readonly AUTHENTICATION: 3002;
+    readonly AUTHORIZE_SESSION: 3003;
+    readonly API_ACTIVITY: 6003;
+};
+export declare const OCSF_SEVERITY: {
+    readonly UNKNOWN: 0;
+    readonly INFORMATIONAL: 1;
+    readonly LOW: 2;
+    readonly MEDIUM: 3;
+    readonly HIGH: 4;
+    readonly CRITICAL: 5;
+    readonly FATAL: 6;
+};
+export declare const OCSF_STATUS: {
+    readonly UNKNOWN: 0;
+    readonly SUCCESS: 1;
+    readonly FAILURE: 2;
+    readonly OTHER: 99;
+};
+export declare const OCSF_AUTH_ACTIVITY: {
+    readonly UNKNOWN: 0;
+    readonly LOGON: 1;
+    readonly LOGOFF: 2;
+    readonly AUTHENTICATION_TICKET: 3;
+    readonly SERVICE_TICKET_REQUEST: 4;
+    readonly SERVICE_TICKET_RENEW: 5;
+    readonly PREAUTH: 6;
+    readonly OTHER: 99;
+};
+export declare const OCSF_ACCOUNT_ACTIVITY: {
+    readonly UNKNOWN: 0;
+    readonly CREATE: 1;
+    readonly ENABLE: 2;
+    readonly PASSWORD_CHANGE: 3;
+    readonly PASSWORD_RESET: 4;
+    readonly DISABLE: 5;
+    readonly DELETE: 6;
+    readonly ATTACH_POLICY: 7;
+    readonly DETACH_POLICY: 8;
+    readonly LOCK: 9;
+    readonly MFA_ENABLE: 10;
+    readonly MFA_DISABLE: 11;
+    readonly OTHER: 99;
+};
+export declare const OCSF_API_ACTIVITY: {
+    readonly UNKNOWN: 0;
+    readonly CREATE: 1;
+    readonly READ: 2;
+    readonly UPDATE: 3;
+    readonly DELETE: 4;
+    readonly CHECKOUT: 90;
+    readonly PAYMENT: 91;
+    readonly REFUND: 92;
+    readonly EXPORT: 93;
+    readonly IMPORT: 94;
+    readonly ACCESS_DENIED: 95;
+    readonly OTHER: 99;
+};
+export interface OCSFMetadata {
+    version: string;
+    product: {
+        name: string;
+        version: string;
+        vendor_name?: string;
+    };
+    uid?: string;
+    original_time?: number;
+    sequence?: number;
+}
+export interface OCSFUser {
+    uid?: string;
+    name?: string;
+    email_addr?: string;
+    type?: string;
+    type_id?: number;
+}
+export interface OCSFActor {
+    user?: OCSFUser;
+    session?: OCSFSession;
+    invoked_by?: string;
+}
+export interface OCSFSession {
+    uid?: string;
+    created_time?: number;
+    is_mfa?: boolean;
+}
+export interface OCSFEndpoint {
+    ip?: string;
+    port?: number;
+    hostname?: string;
+    agent_list?: {
+        name?: string;
+        version?: string;
+    }[];
+}
+export interface OCSFApi {
+    operation?: string;
+    service?: {
+        name?: string;
+    };
+    request?: {
+        uid?: string;
+    };
+    response?: {
+        code?: number;
+        message?: string;
+    };
+}
+export interface OCSFBaseEvent {
+    category_uid: number;
+    class_uid: number;
+    type_uid: number;
+    activity_id: number;
+    severity_id: number;
+    time: number;
+    message?: string;
+    metadata: OCSFMetadata;
+    status_id?: number;
+    status_detail?: string;
+    unmapped?: {
+        seq: number;
+        prev_hash: string;
+        hash: string;
+    };
+}
+export interface OCSFAuthenticationEvent extends OCSFBaseEvent {
+    category_uid: 3;
+    class_uid: 3002;
+    user: OCSFUser;
+    src_endpoint?: OCSFEndpoint;
+    dst_endpoint?: OCSFEndpoint;
+    auth_protocol_id?: number;
+    auth_protocol?: string;
+    is_mfa?: boolean;
+    logon_type_id?: number;
+    session?: OCSFSession;
+}
+export interface OCSFAccountChangeEvent extends OCSFBaseEvent {
+    category_uid: 3;
+    class_uid: 3001;
+    user: OCSFUser;
+    actor?: OCSFActor;
+    src_endpoint?: OCSFEndpoint;
+}
+export interface OCSFApiActivityEvent extends OCSFBaseEvent {
+    category_uid: 6;
+    class_uid: 6003;
+    actor: OCSFActor;
+    api: OCSFApi;
+    src_endpoint?: OCSFEndpoint;
+    dst_endpoint?: OCSFEndpoint;
+    http_request?: {
+        http_method?: string;
+        url?: {
+            path?: string;
+        };
+    };
+}
+export type OCSFEvent = OCSFAuthenticationEvent | OCSFAccountChangeEvent | OCSFApiActivityEvent;

package/lib/audit/ocsf-types.js

@@ -0,0 +1,64 @@
+export const OCSF_CATEGORY = {
+    IDENTITY_ACCESS_MGMT: 3,
+    APPLICATION_ACTIVITY: 6,
+};
+export const OCSF_CLASS = {
+    ACCOUNT_CHANGE: 3001,
+    AUTHENTICATION: 3002,
+    AUTHORIZE_SESSION: 3003,
+    API_ACTIVITY: 6003,
+};
+export const OCSF_SEVERITY = {
+    UNKNOWN: 0,
+    INFORMATIONAL: 1,
+    LOW: 2,
+    MEDIUM: 3,
+    HIGH: 4,
+    CRITICAL: 5,
+    FATAL: 6,
+};
+export const OCSF_STATUS = {
+    UNKNOWN: 0,
+    SUCCESS: 1,
+    FAILURE: 2,
+    OTHER: 99,
+};
+export const OCSF_AUTH_ACTIVITY = {
+    UNKNOWN: 0,
+    LOGON: 1,
+    LOGOFF: 2,
+    AUTHENTICATION_TICKET: 3,
+    SERVICE_TICKET_REQUEST: 4,
+    SERVICE_TICKET_RENEW: 5,
+    PREAUTH: 6,
+    OTHER: 99,
+};
+export const OCSF_ACCOUNT_ACTIVITY = {
+    UNKNOWN: 0,
+    CREATE: 1,
+    ENABLE: 2,
+    PASSWORD_CHANGE: 3,
+    PASSWORD_RESET: 4,
+    DISABLE: 5,
+    DELETE: 6,
+    ATTACH_POLICY: 7,
+    DETACH_POLICY: 8,
+    LOCK: 9,
+    MFA_ENABLE: 10,
+    MFA_DISABLE: 11,
+    OTHER: 99,
+};
+export const OCSF_API_ACTIVITY = {
+    UNKNOWN: 0,
+    CREATE: 1,
+    READ: 2,
+    UPDATE: 3,
+    DELETE: 4,
+    CHECKOUT: 90,
+    PAYMENT: 91,
+    REFUND: 92,
+    EXPORT: 93,
+    IMPORT: 94,
+    ACCESS_DENIED: 95,
+    OTHER: 99,
+};

package/lib/events-index.d.ts

@@ -2,3 +2,5 @@ import { type EmitAdapter, type RawPayloadType } from './EventDirector.ts';
 declare const emit: (eventName: string, data?: Record<string, any>) => Promise<void>, getEmitAdapter: () => EmitAdapter, getEmitHistoryAdapter: () => EmitAdapter, getRegisteredEvents: () => string[], registerEvents: (events: string[]) => void, setEmitAdapter: (adapter: EmitAdapter) => void, setEmitHistoryAdapter: (adapter: EmitAdapter) => void, subscribe: <T extends Record<string, any>>(eventName: string, callback: (payload: RawPayloadType<T>) => void) => void;
 export { emit, getEmitAdapter, getEmitHistoryAdapter, getRegisteredEvents, registerEvents, setEmitAdapter, setEmitHistoryAdapter, subscribe, };
 export type { EmitAdapter, RawPayloadType };
+export { AuditLog, createAuditLog, OCSF_CLASS, OCSF_CATEGORY, OCSF_SEVERITY, OCSF_STATUS, OCSF_AUTH_ACTIVITY, OCSF_ACCOUNT_ACTIVITY, OCSF_API_ACTIVITY, type AuditLogConfig, type AuthenticationInput, type AccountChangeInput, type ApiActivityInput, type AuditLogQuery, type VerifyResult, type OCSFBaseEvent, type OCSFAuthenticationEvent, type OCSFAccountChangeEvent, type OCSFApiActivityEvent, type OCSFEvent, type OCSFMetadata, type OCSFUser, type OCSFActor, type OCSFEndpoint, type OCSFApi, type OCSFSession, } from './audit/index.ts';
+export { configureAuditIntegration, AUDITED_EVENTS } from './audit/audit-integration.ts';

package/lib/events-index.js

@@ -3,3 +3,5 @@ const { emit, getEmitAdapter, getEmitHistoryAdapter, getRegisteredEvents, regist
 const GLOBAL_EVENTS = ['PAGE_VIEW'];
 registerEvents(GLOBAL_EVENTS);
 export { emit, getEmitAdapter, getEmitHistoryAdapter, getRegisteredEvents, registerEvents, setEmitAdapter, setEmitHistoryAdapter, subscribe, };
+export { AuditLog, createAuditLog, OCSF_CLASS, OCSF_CATEGORY, OCSF_SEVERITY, OCSF_STATUS, OCSF_AUTH_ACTIVITY, OCSF_ACCOUNT_ACTIVITY, OCSF_API_ACTIVITY, } from "./audit/index.js";
+export { configureAuditIntegration, AUDITED_EVENTS } from "./audit/audit-integration.js";

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@unchainedshop/events",
-  "version": "4.5.0",
+  "description": "Event emitter abstraction layer for the Unchained Engine",
+  "version": "4.6.0",
   "main": "lib/events-index.js",
   "types": "lib/events-index.d.ts",
   "type": "module",
@@ -33,7 +34,7 @@
   },
   "homepage": "https://github.com/unchainedshop/unchained#readme",
   "dependencies": {
-    "@unchainedshop/logger": "^4.5.0"
+    "@unchainedshop/logger": "^4.6.0"
   },
   "devDependencies": {
     "@types/node": "^25.0.0",