@firela/billclaw-core 0.1.3

package/dist/security/audit.js

@@ -0,0 +1,286 @@
+/**
+ * Security audit logging for BillClaw
+ *
+ * Provides audit logging for all credential operations:
+ * - Credential access (read/write/delete)
+ * - Account linking/unlinking
+ * - Sync operations
+ * - Configuration changes
+ *
+ * Audit logs are stored locally and can be exported for compliance.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as os from "node:os";
+/**
+ * Audit event types
+ */
+export var AuditEventType;
+(function (AuditEventType) {
+    // Credential operations
+    AuditEventType["CREDENTIAL_CREATED"] = "credential.created";
+    AuditEventType["CREDENTIAL_READ"] = "credential.read";
+    AuditEventType["CREDENTIAL_WRITE"] = "credential.write";
+    AuditEventType["CREDENTIAL_UPDATED"] = "credential.updated";
+    AuditEventType["CREDENTIAL_DELETED"] = "credential.deleted";
+    AuditEventType["CREDENTIAL_DELETE"] = "credential.delete";
+    AuditEventType["CREDENTIAL_EXPORTED"] = "credential.exported";
+    // Account operations
+    AuditEventType["ACCOUNT_LINKED"] = "account.linked";
+    AuditEventType["ACCOUNT_UNLINKED"] = "account.unlinked";
+    AuditEventType["ACCOUNT_SYNCED"] = "account.synced";
+    AuditEventType["ACCOUNT_SYNC_FAILED"] = "account.sync_failed";
+    // Configuration operations
+    AuditEventType["CONFIG_UPDATED"] = "config.updated";
+    AuditEventType["CONFIG_READ"] = "config.read";
+    // Authentication operations
+    AuditEventType["AUTH_SUCCESS"] = "auth.success";
+    AuditEventType["AUTH_FAILED"] = "auth.failed";
+    AuditEventType["AUTH_REFRESHED"] = "auth.refreshed";
+    // Data operations
+    AuditEventType["DATA_EXPORTED"] = "data.exported";
+    AuditEventType["DATA_IMPORTED"] = "data.imported";
+    AuditEventType["DATA_DELETED"] = "data.deleted";
+    // Legacy aliases for backward compatibility
+    AuditEventType["ACCOUNT_ACCESS"] = "account.access";
+    AuditEventType["SYNC_STARTED"] = "sync.started";
+    AuditEventType["SYNC_COMPLETED"] = "sync.completed";
+    AuditEventType["SYNC_FAILED"] = "sync.failed";
+    AuditEventType["CONFIG_CHANGE"] = "config.change";
+})(AuditEventType || (AuditEventType = {}));
+/**
+ * Audit event severity
+ */
+export var AuditSeverity;
+(function (AuditSeverity) {
+    AuditSeverity["INFO"] = "info";
+    AuditSeverity["LOW"] = "low";
+    AuditSeverity["MEDIUM"] = "medium";
+    AuditSeverity["HIGH"] = "high";
+    AuditSeverity["WARNING"] = "warning";
+    AuditSeverity["ERROR"] = "error";
+    AuditSeverity["CRITICAL"] = "critical";
+})(AuditSeverity || (AuditSeverity = {}));
+/**
+ * Default audit configuration
+ */
+const DEFAULT_AUDIT_CONFIG = {
+    dataDir: "~/.billclaw",
+    maxEntries: 10000,
+    retentionDays: 90,
+};
+/**
+ * Audit logger class
+ */
+export class AuditLogger {
+    config;
+    baseDir;
+    logFilePath;
+    logger;
+    constructor(configOrPath = {}, logger) {
+        // Support both old API (string path) and new API (config object)
+        if (typeof configOrPath === "string") {
+            // Old API: constructor(logFilePath: string, logger?: Logger)
+            this.logFilePath = configOrPath;
+            this.baseDir = path.dirname(configOrPath);
+            this.config = DEFAULT_AUDIT_CONFIG;
+            this.logger = logger;
+        }
+        else {
+            // New API: constructor(config?: AuditConfig, logger?: Logger)
+            this.config = { ...DEFAULT_AUDIT_CONFIG, ...configOrPath };
+            this.baseDir = this.config.dataDir.replace(/^~/, os.homedir());
+            this.logFilePath = path.join(this.baseDir, "audit.log");
+            this.logger = logger;
+        }
+    }
+    /**
+     * Get the audit log file path
+     */
+    getAuditFilePath() {
+        return this.logFilePath;
+    }
+    /**
+     * Ensure audit directory exists
+     */
+    async ensureAuditDir() {
+        await fs.mkdir(this.baseDir, { recursive: true });
+    }
+    /**
+     * Rotate audit logs if they exceed max entries
+     */
+    async rotateIfNeeded() {
+        try {
+            const filePath = this.getAuditFilePath();
+            const content = await fs.readFile(filePath, "utf-8");
+            const lines = content.trim().split("\n");
+            if (lines.length > this.config.maxEntries) {
+                // Keep only the most recent entries
+                const recentLines = lines.slice(-this.config.maxEntries);
+                await fs.writeFile(filePath, recentLines.join("\n"), "utf-8");
+            }
+            // Clean up old entries based on retention
+            const cutoffDate = new Date();
+            cutoffDate.setDate(cutoffDate.getDate() - this.config.retentionDays);
+            const filteredLines = lines.filter((line) => {
+                try {
+                    const event = JSON.parse(line);
+                    const eventDate = new Date(event.timestamp);
+                    return eventDate >= cutoffDate;
+                }
+                catch {
+                    return true; // Keep lines that can't be parsed
+                }
+            });
+            if (filteredLines.length < lines.length) {
+                await fs.writeFile(filePath, filteredLines.join("\n"), "utf-8");
+            }
+        }
+        catch {
+            // File doesn't exist yet, which is fine
+        }
+    }
+    /**
+     * Log an audit event
+     */
+    async log(type, message, details, severity = AuditSeverity.INFO) {
+        await this.ensureAuditDir();
+        const event = {
+            id: this.generateEventId(),
+            timestamp: new Date().toISOString(),
+            type,
+            severity,
+            message,
+            details,
+        };
+        const filePath = this.getAuditFilePath();
+        try {
+            await this.rotateIfNeeded();
+            const logEntry = JSON.stringify(event) + "\n";
+            await fs.appendFile(filePath, logEntry, "utf-8");
+        }
+        catch (error) {
+            this.logger?.error?.("Failed to write audit log:", error);
+        }
+    }
+    /**
+     * Generate a unique event ID
+     */
+    generateEventId() {
+        return `audit_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+    }
+    /**
+     * Read all audit events
+     */
+    async readEvents(limit) {
+        const filePath = this.getAuditFilePath();
+        try {
+            const content = await fs.readFile(filePath, "utf-8");
+            const lines = content.trim().split("\n");
+            const events = [];
+            for (const line of lines) {
+                try {
+                    events.push(JSON.parse(line));
+                }
+                catch {
+                    // Skip malformed lines
+                }
+            }
+            // Return most recent first
+            events.reverse();
+            if (limit) {
+                return events.slice(0, limit);
+            }
+            return events;
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Query audit events by type
+     */
+    async queryByType(type, limit) {
+        const events = await this.readEvents();
+        const filtered = events.filter((e) => e.type === type);
+        return limit ? filtered.slice(0, limit) : filtered;
+    }
+    /**
+     * Query audit events by severity
+     */
+    async queryBySeverity(severity, limit) {
+        const events = await this.readEvents();
+        const filtered = events.filter((e) => e.severity === severity);
+        return limit ? filtered.slice(0, limit) : filtered;
+    }
+    /**
+     * Clear all audit events
+     */
+    async clear() {
+        const filePath = this.getAuditFilePath();
+        try {
+            await fs.unlink(filePath);
+        }
+        catch {
+            // File doesn't exist, which is fine
+        }
+        // Create empty file
+        await this.ensureAuditDir();
+        await fs.writeFile(filePath, "", "utf-8");
+        this.logger?.info?.("Audit log cleared");
+    }
+    /**
+     * Get audit log statistics
+     */
+    async getStats() {
+        const events = await this.readEvents();
+        const byType = {};
+        const bySeverity = {};
+        for (const event of events) {
+            byType[event.type] = (byType[event.type] || 0) + 1;
+            bySeverity[event.severity] = (bySeverity[event.severity] || 0) + 1;
+        }
+        return {
+            totalEvents: events.length,
+            byType,
+            bySeverity,
+        };
+    }
+}
+/**
+ * Create an audit logger with the given configuration
+ */
+export function createAuditLogger(config, logger) {
+    return new AuditLogger(config, logger);
+}
+/**
+ * Convenience functions for common audit events
+ */
+export class AuditHelpers {
+    audit;
+    constructor(audit) {
+        this.audit = audit;
+    }
+    async logCredentialCreated(credentialType, accountId) {
+        await this.audit.log(AuditEventType.CREDENTIAL_CREATED, `Credential created for ${credentialType}`, { credentialType, accountId }, AuditSeverity.INFO);
+    }
+    async logCredentialRead(credentialType, accountId) {
+        await this.audit.log(AuditEventType.CREDENTIAL_READ, `Credential read for ${credentialType}`, { credentialType, accountId }, AuditSeverity.INFO);
+    }
+    async logCredentialDeleted(credentialType, accountId) {
+        await this.audit.log(AuditEventType.CREDENTIAL_DELETED, `Credential deleted for ${credentialType}`, { credentialType, accountId }, AuditSeverity.WARNING);
+    }
+    async logAccountLinked(accountType, accountId) {
+        await this.audit.log(AuditEventType.ACCOUNT_LINKED, `Account linked: ${accountType}`, { accountType, accountId }, AuditSeverity.INFO);
+    }
+    async logAccountUnlinked(accountType, accountId) {
+        await this.audit.log(AuditEventType.ACCOUNT_UNLINKED, `Account unlinked: ${accountType}`, { accountType, accountId }, AuditSeverity.WARNING);
+    }
+    async logAuthFailed(accountType, reason) {
+        await this.audit.log(AuditEventType.AUTH_FAILED, `Authentication failed for ${accountType}`, { accountType, reason }, AuditSeverity.ERROR);
+    }
+    async logDataExported(dataType, count) {
+        await this.audit.log(AuditEventType.DATA_EXPORTED, `Data exported: ${dataType}`, { dataType, count }, AuditSeverity.INFO);
+    }
+}
+//# sourceMappingURL=audit.js.map

package/dist/security/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../src/security/audit.ts"],"names":[],"mappings":"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"}

package/dist/security/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Security utilities for BillClaw
+ *
+ * @packageDocumentation
+ */
+export * from "./audit.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/security/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/security/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,YAAY,CAAA"}

package/dist/security/index.js

@@ -0,0 +1,7 @@
+/**
+ * Security utilities for BillClaw
+ *
+ * @packageDocumentation
+ */
+export * from "./audit.js";
+//# sourceMappingURL=index.js.map

package/dist/security/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/security/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,YAAY,CAAA"}

package/dist/services/event-emitter.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Event emitter for BillClaw webhook events
+ *
+ * This module provides a centralized way to emit and forward webhook events
+ * to configured external webhook endpoints.
+ *
+ * Framework-agnostic: Uses Logger interface instead of framework-specific APIs.
+ */
+import type { Logger } from "../errors/errors.js";
+import type { WebhookEventType, WebhookConfig } from "../models/config.js";
+/**
+ * Base event interface for all BillClaw webhook events
+ */
+export interface BillclawEvent {
+    id: string;
+    event: WebhookEventType;
+    timestamp: string;
+    version: string;
+    data: unknown;
+}
+/**
+ * Transaction event data
+ */
+export interface TransactionEventData {
+    accountId: string;
+    transactionId: string;
+    date: string;
+    amount: number;
+    currency: string;
+    merchantName?: string;
+    category?: string[];
+    source: "plaid" | "gmail" | "gocardless" | "manual";
+}
+/**
+ * Sync event data
+ */
+export interface SyncEventData {
+    accountId: string;
+    syncId: string;
+    status: "started" | "completed" | "failed";
+    transactionsAdded?: number;
+    transactionsUpdated?: number;
+    error?: string;
+    duration?: number;
+}
+/**
+ * Account event data
+ */
+export interface AccountEventData {
+    accountId: string;
+    accountType: "plaid" | "gmail" | "gocardless";
+    status: "connected" | "disconnected" | "error";
+    error?: string;
+}
+/**
+ * Webhook test event data
+ */
+export interface WebhookTestData {
+    message: string;
+    triggeredBy: string;
+}
+/**
+ * Event payload sent to external webhooks
+ */
+export interface WebhookPayload {
+    id: string;
+    event: WebhookEventType;
+    timestamp: string;
+    version: string;
+    data: unknown;
+    signature?: string;
+}
+/**
+ * Options for webhook retry policy
+ */
+export interface RetryPolicy {
+    maxRetries: number;
+    initialDelay: number;
+    maxDelay: number;
+}
+/**
+ * Emit a BillClaw event
+ *
+ * This function creates a standardized event and forwards it to all
+ * configured external webhooks that are subscribed to this event type.
+ *
+ * @param logger - Logger instance for logging
+ * @param webhooks - Array of webhook configurations
+ * @param eventType - Type of event to emit
+ * @param data - Event data
+ */
+export declare function emitEvent(logger: Logger, webhooks: WebhookConfig[], eventType: WebhookEventType, data: unknown): Promise<void>;
+/**
+ * Emit transaction.new event
+ */
+export declare function emitTransactionNew(logger: Logger, webhooks: WebhookConfig[], transaction: TransactionEventData): Promise<void>;
+/**
+ * Emit transaction.updated event
+ */
+export declare function emitTransactionUpdated(logger: Logger, webhooks: WebhookConfig[], transaction: TransactionEventData): Promise<void>;
+/**
+ * Emit transaction.deleted event
+ */
+export declare function emitTransactionDeleted(logger: Logger, webhooks: WebhookConfig[], transactionId: string, accountId: string): Promise<void>;
+/**
+ * Emit sync.started event
+ */
+export declare function emitSyncStarted(logger: Logger, webhooks: WebhookConfig[], accountId: string, syncId: string): Promise<void>;
+/**
+ * Emit sync.completed event
+ */
+export declare function emitSyncCompleted(logger: Logger, webhooks: WebhookConfig[], syncData: SyncEventData): Promise<void>;
+/**
+ * Emit sync.failed event
+ */
+export declare function emitSyncFailed(logger: Logger, webhooks: WebhookConfig[], accountId: string, syncId: string, error: string): Promise<void>;
+/**
+ * Emit account.connected event
+ */
+export declare function emitAccountConnected(logger: Logger, webhooks: WebhookConfig[], accountId: string, accountType: "plaid" | "gmail" | "gocardless"): Promise<void>;
+/**
+ * Emit account.disconnected event
+ */
+export declare function emitAccountDisconnected(logger: Logger, webhooks: WebhookConfig[], accountId: string, accountType: "plaid" | "gmail" | "gocardless"): Promise<void>;
+/**
+ * Emit account.error event
+ */
+export declare function emitAccountError(logger: Logger, webhooks: WebhookConfig[], accountId: string, accountType: "plaid" | "gmail" | "gocardless", error: string): Promise<void>;
+/**
+ * Emit webhook.test event
+ */
+export declare function emitWebhookTest(logger: Logger, webhooks: WebhookConfig[], message?: string): Promise<void>;
+/**
+ * Generate HMAC-SHA256 signature for webhook payload
+ *
+ * @param event - Event to sign
+ * @param secret - Secret key for HMAC
+ * @returns Signature in format "sha256=<hex>"
+ */
+export declare function generateSignature(event: BillclawEvent, secret: string): string;
+/**
+ * Verify webhook signature
+ *
+ * Returns true if the signature matches the computed signature.
+ * Uses timing-safe comparison to prevent timing attacks.
+ *
+ * @param payload - JSON string payload
+ * @param signature - Signature to verify (format: "sha256=<hex>")
+ * @param secret - Secret key for HMAC
+ * @returns True if signature is valid
+ */
+export declare function verifySignature(payload: string, signature: string, secret: string): boolean;
+/**
+ * Type guard to check if an event is a transaction event
+ */
+export declare function isTransactionEvent(event: BillclawEvent): event is BillclawEvent & {
+    data: TransactionEventData;
+};
+/**
+ * Type guard to check if an event is a sync event
+ */
+export declare function isSyncEvent(event: BillclawEvent): event is BillclawEvent & {
+    data: SyncEventData;
+};
+/**
+ * Type guard to check if an event is an account event
+ */
+export declare function isAccountEvent(event: BillclawEvent): event is BillclawEvent & {
+    data: AccountEventData;
+};
+//# sourceMappingURL=event-emitter.d.ts.map

package/dist/services/event-emitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-emitter.d.ts","sourceRoot":"","sources":["../../src/services/event-emitter.ts"],"names":[],"mappings":"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"}