@firela/billclaw-core 0.1.3

package/dist/credentials/keychain.js

@@ -0,0 +1,172 @@
+/**
+ * Platform keychain credential storage for BillClaw
+ *
+ * Uses keytar to securely store sensitive tokens in the platform keychain:
+ * - macOS: Keychain
+ * - Windows: Credential Manager
+ * - Linux: Secret Service API / KWallet
+ *
+ * This provides P0 security for:
+ * - Plaid access tokens
+ * - Gmail refresh tokens
+ * - GoCardless access tokens
+ */
+// Keytar is an optional dependency - will be installed by adapter
+let keytarModule = null;
+/**
+ * Initialize keytar module
+ * Call this before using keychain functions
+ */
+export async function initKeytar() {
+    if (!keytarModule) {
+        try {
+            keytarModule = await import("keytar");
+        }
+        catch (error) {
+            throw new Error("keytar is not installed. Install it with: npm install keytar");
+        }
+    }
+}
+/**
+ * Service name for BillClaw in keychain
+ */
+const KEYCHAIN_SERVICE = "billclaw";
+/**
+ * Store a credential in the platform keychain
+ *
+ * @param key - Credential identifier (e.g., "plaid_access_token:account123")
+ * @param value - Sensitive value to store (e.g., access token)
+ * @param logger - Optional logger for audit logging
+ */
+export async function setCredential(key, value, logger) {
+    await initKeytar();
+    const keytar = keytarModule;
+    try {
+        await keytar.setPassword(KEYCHAIN_SERVICE, key, value);
+        logger?.debug?.(`Stored credential in keychain: ${key}`);
+    }
+    catch (error) {
+        logger?.error?.(`Failed to store credential in keychain: ${key}`, error);
+        throw new Error(`Failed to store credential in keychain: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Retrieve a credential from the platform keychain
+ *
+ * @param key - Credential identifier
+ * @param logger - Optional logger for audit logging
+ * @returns The credential value, or null if not found
+ */
+export async function getCredential(key, logger) {
+    await initKeytar();
+    const keytar = keytarModule;
+    try {
+        const value = await keytar.getPassword(KEYCHAIN_SERVICE, key);
+        if (value !== null) {
+            logger?.debug?.(`Retrieved credential from keychain: ${key}`);
+        }
+        else {
+            logger?.debug?.(`Credential not found in keychain: ${key}`);
+        }
+        return value;
+    }
+    catch (error) {
+        logger?.error?.(`Failed to retrieve credential from keychain: ${key}`, error);
+        throw new Error(`Failed to retrieve credential from keychain: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Delete a credential from the platform keychain
+ *
+ * @param key - Credential identifier
+ * @param logger - Optional logger for audit logging
+ * @returns true if the credential was deleted, false if it didn't exist
+ */
+export async function deleteCredential(key, logger) {
+    await initKeytar();
+    const keytar = keytarModule;
+    try {
+        const result = await keytar.deletePassword(KEYCHAIN_SERVICE, key);
+        if (result) {
+            logger?.debug?.(`Deleted credential from keychain: ${key}`);
+        }
+        else {
+            logger?.debug?.(`Credential not found in keychain (could not delete): ${key}`);
+        }
+        return result;
+    }
+    catch (error) {
+        logger?.error?.(`Failed to delete credential from keychain: ${key}`, error);
+        throw new Error(`Failed to delete credential from keychain: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Check if a credential exists in the keychain
+ *
+ * @param key - Credential identifier
+ * @param logger - Optional logger for audit logging
+ * @returns true if the credential exists
+ */
+export async function hasCredential(key, logger) {
+    const value = await getCredential(key, logger);
+    return value !== null;
+}
+/**
+ * List all credential keys for BillClaw
+ *
+ * Note: keytar doesn't provide a direct way to list all keys,
+ * so this returns empty array. Applications should track
+ * their own credential keys separately.
+ *
+ * @returns Empty array (keytar limitation)
+ */
+export async function listCredentialKeys() {
+    // keytar doesn't support listing keys
+    // Applications should maintain their own registry
+    return [];
+}
+/**
+ * Clear all BillClaw credentials from the keychain
+ *
+ * WARNING: This is a destructive operation. Use with caution.
+ *
+ * @param keys - List of credential keys to delete
+ * @param logger - Optional logger for audit logging
+ */
+export async function clearAllCredentials(keys, logger) {
+    logger?.warn?.(`Clearing ${keys.length} credentials from keychain`);
+    for (const key of keys) {
+        await deleteCredential(key, logger);
+    }
+    logger?.info?.(`Cleared all credentials from keychain`);
+}
+/**
+ * Keychain utility functions for building credential keys
+ */
+export const KeychainKeys = {
+    /**
+     * Build a Plaid access token key
+     */
+    plaidAccessToken(accountId) {
+        return `plaid_access_token:${accountId}`;
+    },
+    /**
+     * Build a Gmail refresh token key
+     */
+    gmailRefreshToken(accountId) {
+        return `gmail_refresh_token:${accountId}`;
+    },
+    /**
+     * Build a GoCardless access token key
+     */
+    gocardlessAccessToken(accountId) {
+        return `gocardless_access_token:${accountId}`;
+    },
+    /**
+     * Build a GoCardless requisition ID key
+     */
+    gocardlessRequisitionId(accountId) {
+        return `gocardless_requisition_id:${accountId}`;
+    },
+};
+//# sourceMappingURL=keychain.js.map

package/dist/credentials/keychain.js.map

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

package/dist/credentials/store.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Unified credential store interface for BillClaw
+ *
+ * Provides a consistent API for storing and retrieving credentials,
+ * with support for both keychain storage (secure) and in-memory
+ * fallback for development/testing.
+ */
+import type { Logger } from "../errors/errors.js";
+/**
+ * Credential storage strategy
+ */
+export declare enum CredentialStrategy {
+    /** Store in platform keychain (recommended for production) */
+    KEYCHAIN = "keychain",
+    /** Store in memory only (for testing/development, NOT secure) */
+    MEMORY = "memory"
+}
+/**
+ * Credential store configuration
+ */
+export interface CredentialStoreConfig {
+    strategy: CredentialStrategy;
+    logger?: Logger;
+}
+/**
+ * Unified credential store
+ */
+export declare class CredentialStore {
+    private memoryStore;
+    private config;
+    constructor(config: CredentialStoreConfig);
+    /**
+     * Store a credential
+     *
+     * @param key - Credential identifier
+     * @param value - Sensitive value to store
+     */
+    set(key: string, value: string): Promise<void>;
+    /**
+     * Retrieve a credential
+     *
+     * @param key - Credential identifier
+     * @returns The credential value, or null if not found
+     */
+    get(key: string): Promise<string | null>;
+    /**
+     * Delete a credential
+     *
+     * @param key - Credential identifier
+     * @returns true if the credential was deleted
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Check if a credential exists
+     *
+     * @param key - Credential identifier
+     * @returns true if the credential exists
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * List all credential keys
+     *
+     * @returns Array of credential keys
+     */
+    list(): Promise<string[]>;
+    /**
+     * Clear all credentials
+     */
+    clear(): Promise<void>;
+}
+/**
+ * Create a credential store with the given configuration
+ */
+export declare function createCredentialStore(config: CredentialStoreConfig): CredentialStore;
+export * from "./keychain.js";
+//# sourceMappingURL=store.d.ts.map

package/dist/credentials/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/credentials/store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAGjD;;GAEG;AACH,oBAAY,kBAAkB;IAC5B,8DAA8D;IAC9D,QAAQ,aAAa;IAErB,iEAAiE;IACjE,MAAM,WAAW;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,kBAAkB,CAAA;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAiCD;;GAEG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,MAAM,CAAuB;gBAEzB,MAAM,EAAE,qBAAqB;IAKzC;;;;;OAKG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWpD;;;;;OAKG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAQ9C;;;;;OAKG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAQ3C;;;;;OAKG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAQxC;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAQ/B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAS7B;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,qBAAqB,GAC5B,eAAe,CAEjB;AAGD,cAAc,eAAe,CAAA"}

package/dist/credentials/store.js

@@ -0,0 +1,144 @@
+/**
+ * Unified credential store interface for BillClaw
+ *
+ * Provides a consistent API for storing and retrieving credentials,
+ * with support for both keychain storage (secure) and in-memory
+ * fallback for development/testing.
+ */
+import * as keychain from "./keychain.js";
+/**
+ * Credential storage strategy
+ */
+export var CredentialStrategy;
+(function (CredentialStrategy) {
+    /** Store in platform keychain (recommended for production) */
+    CredentialStrategy["KEYCHAIN"] = "keychain";
+    /** Store in memory only (for testing/development, NOT secure) */
+    CredentialStrategy["MEMORY"] = "memory";
+})(CredentialStrategy || (CredentialStrategy = {}));
+/**
+ * In-memory credential storage (NOT secure - for testing only)
+ */
+class MemoryCredentialStore {
+    credentials = new Map();
+    async set(key, value) {
+        this.credentials.set(key, value);
+    }
+    async get(key) {
+        return this.credentials.get(key) || null;
+    }
+    async delete(key) {
+        return this.credentials.delete(key);
+    }
+    async has(key) {
+        return this.credentials.has(key);
+    }
+    async list() {
+        return Array.from(this.credentials.keys());
+    }
+    async clear() {
+        this.credentials.clear();
+    }
+}
+/**
+ * Unified credential store
+ */
+export class CredentialStore {
+    memoryStore;
+    config;
+    constructor(config) {
+        this.config = config;
+        this.memoryStore = new MemoryCredentialStore();
+    }
+    /**
+     * Store a credential
+     *
+     * @param key - Credential identifier
+     * @param value - Sensitive value to store
+     */
+    async set(key, value) {
+        if (this.config.strategy === CredentialStrategy.KEYCHAIN) {
+            await keychain.setCredential(key, value, this.config.logger);
+        }
+        else {
+            await this.memoryStore.set(key, value);
+            this.config.logger?.warn?.(`Stored credential in memory (NOT SECURE): ${key}`);
+        }
+    }
+    /**
+     * Retrieve a credential
+     *
+     * @param key - Credential identifier
+     * @returns The credential value, or null if not found
+     */
+    async get(key) {
+        if (this.config.strategy === CredentialStrategy.KEYCHAIN) {
+            return keychain.getCredential(key, this.config.logger);
+        }
+        else {
+            return this.memoryStore.get(key);
+        }
+    }
+    /**
+     * Delete a credential
+     *
+     * @param key - Credential identifier
+     * @returns true if the credential was deleted
+     */
+    async delete(key) {
+        if (this.config.strategy === CredentialStrategy.KEYCHAIN) {
+            return keychain.deleteCredential(key, this.config.logger);
+        }
+        else {
+            return this.memoryStore.delete(key);
+        }
+    }
+    /**
+     * Check if a credential exists
+     *
+     * @param key - Credential identifier
+     * @returns true if the credential exists
+     */
+    async has(key) {
+        if (this.config.strategy === CredentialStrategy.KEYCHAIN) {
+            return keychain.hasCredential(key, this.config.logger);
+        }
+        else {
+            return this.memoryStore.has(key);
+        }
+    }
+    /**
+     * List all credential keys
+     *
+     * @returns Array of credential keys
+     */
+    async list() {
+        if (this.config.strategy === CredentialStrategy.KEYCHAIN) {
+            return keychain.listCredentialKeys();
+        }
+        else {
+            return this.memoryStore.list();
+        }
+    }
+    /**
+     * Clear all credentials
+     */
+    async clear() {
+        const keys = await this.list();
+        if (this.config.strategy === CredentialStrategy.KEYCHAIN) {
+            await keychain.clearAllCredentials(keys, this.config.logger);
+        }
+        else {
+            await this.memoryStore.clear();
+        }
+    }
+}
+/**
+ * Create a credential store with the given configuration
+ */
+export function createCredentialStore(config) {
+    return new CredentialStore(config);
+}
+// Re-export keychain utilities for convenience
+export * from "./keychain.js";
+//# sourceMappingURL=store.js.map

package/dist/credentials/store.js.map

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

package/dist/errors/errors.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Error handling utilities for BillClaw
+ *
+ * Provides user-friendly error messages, recovery suggestions,
+ * and troubleshooting guides.
+ *
+ * Framework-agnostic: Logger is provided via runtime abstraction.
+ */
+/**
+ * Error categories for better user messaging
+ */
+export declare enum ErrorCategory {
+    CONFIG = "configuration",
+    CREDENTIALS = "credentials",
+    NETWORK = "network",
+    PLAID_API = "plaid_api",
+    PLAID_AUTH = "plaid_auth",
+    PLAID_ITEM = "plaid_item",
+    GMAIL_API = "gmail_api",
+    GMAIL_AUTH = "gmail_auth",
+    STORAGE = "storage",
+    FILE_SYSTEM = "file_system",
+    UNKNOWN = "unknown"
+}
+/**
+ * User-friendly error with recovery suggestions
+ */
+export interface UserError {
+    type: "UserError";
+    category: ErrorCategory;
+    title: string;
+    message: string;
+    suggestions: string[];
+    docsLink?: string;
+    error?: Error;
+}
+/**
+ * Logger interface for framework-agnostic logging
+ */
+export interface Logger {
+    info(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    debug(...args: unknown[]): void;
+}
+/**
+ * Create a user-friendly error
+ */
+export declare function createUserError(category: ErrorCategory, title: string, message: string, suggestions: string[], docsLink?: string, originalError?: Error): UserError;
+/**
+ * Format error for display to user
+ */
+export declare function formatError(error: UserError): string;
+/**
+ * Parse Plaid error codes and create user-friendly errors
+ */
+export declare function parsePlaidError(error: {
+    error_code?: string;
+    error_message?: string;
+    error_type?: string;
+    display_message?: string;
+    request_id?: string;
+}): UserError;
+/**
+ * Parse Gmail API errors and create user-friendly errors
+ */
+export declare function parseGmailError(error: {
+    code?: number;
+    message?: string;
+    status?: number;
+}): UserError;
+/**
+ * Parse network errors
+ */
+export declare function parseNetworkError(error: Error): UserError;
+/**
+ * Parse file system errors
+ */
+export declare function parseFileSystemError(error: Error, filePath?: string): UserError;
+/**
+ * Type guard to check if error is a UserError
+ */
+export declare function isUserError(error: unknown): error is UserError;
+/**
+ * Log error with context for debugging
+ */
+export declare function logError(logger: Logger | undefined, error: UserError | Error, context?: Record<string, unknown>): void;
+/**
+ * Get troubleshooting guide URL for error category
+ */
+export declare function getTroubleshootingUrl(category: ErrorCategory): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;GAEG;AACH,oBAAY,aAAa;IAEvB,MAAM,kBAAkB;IACxB,WAAW,gBAAgB;IAC3B,OAAO,YAAY;IAGnB,SAAS,cAAc;IACvB,UAAU,eAAe;IACzB,UAAU,eAAe;IAGzB,SAAS,cAAc;IACvB,UAAU,eAAe;IAGzB,OAAO,YAAY;IACnB,WAAW,gBAAgB;IAG3B,OAAO,YAAY;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,WAAW,CAAA;IACjB,QAAQ,EAAE,aAAa,CAAA;IACvB,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAE,KAAK,CAAA;CACd;AAED;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;IAC9B,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;IAC/B,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;IAC9B,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;CAChC;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,aAAa,EACvB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EAAE,EACrB,QAAQ,CAAC,EAAE,MAAM,EACjB,aAAa,CAAC,EAAE,KAAK,GACpB,SAAS,CAUX;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CA2BpD;AAsBD;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE;IACrC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB,GAAG,SAAS,CA8GZ;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE;IACrC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,GAAG,SAAS,CA4EZ;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,CAiEzD;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,KAAK,EACZ,QAAQ,CAAC,EAAE,MAAM,GAChB,SAAS,CA0DX;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAO9D;AAED;;GAEG;AACH,wBAAgB,QAAQ,CACtB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,KAAK,EAAE,SAAS,GAAG,KAAK,EACxB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,IAAI,CAiBN;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,CAiBrE"}