@nahisaho/musubix-core 1.0.0

package/dist/types/errors.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Error Type Definitions for MUSUBIX
+ *
+ * @packageDocumentation
+ * @module types/errors
+ *
+ * @see REQ-ERR-001 - Graceful Degradation
+ * @see REQ-MNT-002 - Error Handler
+ * @see DES-MUSUBIX-001 Section 10 - Error Handling Design
+ */
+import type { ID, Timestamp, Location } from './common.js';
+/**
+ * MUSUBIX error codes
+ */
+export declare enum ErrorCode {
+    UNKNOWN = 1000,
+    INTERNAL = 1001,
+    INVALID_ARGUMENT = 1002,
+    NOT_FOUND = 1003,
+    ALREADY_EXISTS = 1004,
+    PERMISSION_DENIED = 1005,
+    CONFIG_NOT_FOUND = 2000,
+    CONFIG_INVALID = 2001,
+    CONFIG_MISSING_FIELD = 2002,
+    LLM_CONNECTION_FAILED = 3000,
+    LLM_RESPONSE_ERROR = 3001,
+    LLM_RATE_LIMIT = 3002,
+    YATA_CONNECTION_FAILED = 3100,
+    YATA_QUERY_ERROR = 3101,
+    YATA_TIMEOUT = 3102,
+    INTEGRATION_MISMATCH = 3200,
+    CONTRADICTION_DETECTED = 3201,
+    VALIDATION_FAILED = 4000,
+    EARS_SYNTAX_ERROR = 4001,
+    DESIGN_VIOLATION = 4002,
+    CODE_QUALITY_ERROR = 4003,
+    TEST_COVERAGE_LOW = 4004,
+    FILE_NOT_FOUND = 5000,
+    FILE_READ_ERROR = 5001,
+    FILE_WRITE_ERROR = 5002,
+    DIRECTORY_NOT_FOUND = 5003,
+    CLI_INVALID_COMMAND = 6000,
+    CLI_MISSING_ARGUMENT = 6001,
+    CLI_INVALID_OPTION = 6002
+}
+/**
+ * Base MUSUBIX error
+ */
+export interface MuSubixErrorData {
+    /** Error code */
+    code: ErrorCode;
+    /** Human-readable message */
+    message: string;
+    /** Detailed description */
+    details?: string;
+    /** Timestamp */
+    timestamp: Timestamp;
+    /** Correlation ID for tracing */
+    correlationId?: ID;
+    /** Original error */
+    cause?: Error;
+    /** Location in source */
+    location?: Location;
+    /** Additional context */
+    context?: Record<string, unknown>;
+    /** Recovery suggestions */
+    recovery?: RecoverySuggestion[];
+}
+/**
+ * Recovery suggestion for errors
+ */
+export interface RecoverySuggestion {
+    /** Suggestion type */
+    type: RecoveryType;
+    /** Description */
+    description: string;
+    /** Automated action available */
+    automatable: boolean;
+    /** Action command if automatable */
+    action?: string;
+}
+/**
+ * Recovery types
+ */
+export type RecoveryType = 'retry' | 'fallback' | 'configure' | 'manual' | 'ignore';
+/**
+ * Configuration error
+ */
+export interface ConfigurationError extends MuSubixErrorData {
+    code: ErrorCode.CONFIG_NOT_FOUND | ErrorCode.CONFIG_INVALID | ErrorCode.CONFIG_MISSING_FIELD;
+    configPath?: string;
+    missingField?: string;
+}
+/**
+ * Integration error
+ */
+export interface IntegrationError extends MuSubixErrorData {
+    code: ErrorCode.LLM_CONNECTION_FAILED | ErrorCode.LLM_RESPONSE_ERROR | ErrorCode.LLM_RATE_LIMIT | ErrorCode.YATA_CONNECTION_FAILED | ErrorCode.YATA_QUERY_ERROR | ErrorCode.YATA_TIMEOUT | ErrorCode.INTEGRATION_MISMATCH | ErrorCode.CONTRADICTION_DETECTED;
+    service: 'llm' | 'yata' | 'integration';
+    endpoint?: string;
+    statusCode?: number;
+}
+/**
+ * Validation error
+ */
+export interface ValidationError extends MuSubixErrorData {
+    code: ErrorCode.VALIDATION_FAILED | ErrorCode.EARS_SYNTAX_ERROR | ErrorCode.DESIGN_VIOLATION | ErrorCode.CODE_QUALITY_ERROR | ErrorCode.TEST_COVERAGE_LOW;
+    validationType: string;
+    violations: ValidationViolation[];
+}
+/**
+ * Validation violation detail
+ */
+export interface ValidationViolation {
+    /** Rule that was violated */
+    rule: string;
+    /** Violation message */
+    message: string;
+    /** Severity */
+    severity: 'error' | 'warning' | 'info';
+    /** Location */
+    location?: Location;
+    /** Suggestion */
+    suggestion?: string;
+}
+/**
+ * File system error
+ */
+export interface FileSystemError extends MuSubixErrorData {
+    code: ErrorCode.FILE_NOT_FOUND | ErrorCode.FILE_READ_ERROR | ErrorCode.FILE_WRITE_ERROR | ErrorCode.DIRECTORY_NOT_FOUND;
+    path: string;
+    operation: 'read' | 'write' | 'delete' | 'create';
+}
+/**
+ * CLI error
+ */
+export interface CLIError extends MuSubixErrorData {
+    code: ErrorCode.CLI_INVALID_COMMAND | ErrorCode.CLI_MISSING_ARGUMENT | ErrorCode.CLI_INVALID_OPTION;
+    command?: string;
+    argument?: string;
+    option?: string;
+    usage?: string;
+}
+/**
+ * Error factory options
+ */
+export interface ErrorOptions {
+    cause?: Error;
+    details?: string;
+    context?: Record<string, unknown>;
+    recovery?: RecoverySuggestion[];
+}
+/**
+ * Error severity levels
+ */
+export type ErrorSeverity = 'fatal' | 'error' | 'warn' | 'warning' | 'info';
+/**
+ * Error classification
+ */
+export interface ErrorClassification {
+    /** Error category */
+    category: ErrorCategory;
+    /** Whether error is recoverable */
+    recoverable: boolean;
+    /** Whether to log error */
+    shouldLog: boolean;
+    /** Log level */
+    logLevel: ErrorSeverity;
+    /** Whether to report to user */
+    userFacing: boolean;
+}
+/**
+ * Error categories
+ */
+export type ErrorCategory = 'configuration' | 'integration' | 'validation' | 'filesystem' | 'cli' | 'internal';
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/types/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,EAAE,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAM3D;;GAEG;AACH,oBAAY,SAAS;IAEnB,OAAO,OAAO;IACd,QAAQ,OAAO;IACf,gBAAgB,OAAO;IACvB,SAAS,OAAO;IAChB,cAAc,OAAO;IACrB,iBAAiB,OAAO;IAGxB,gBAAgB,OAAO;IACvB,cAAc,OAAO;IACrB,oBAAoB,OAAO;IAG3B,qBAAqB,OAAO;IAC5B,kBAAkB,OAAO;IACzB,cAAc,OAAO;IACrB,sBAAsB,OAAO;IAC7B,gBAAgB,OAAO;IACvB,YAAY,OAAO;IACnB,oBAAoB,OAAO;IAC3B,sBAAsB,OAAO;IAG7B,iBAAiB,OAAO;IACxB,iBAAiB,OAAO;IACxB,gBAAgB,OAAO;IACvB,kBAAkB,OAAO;IACzB,iBAAiB,OAAO;IAGxB,cAAc,OAAO;IACrB,eAAe,OAAO;IACtB,gBAAgB,OAAO;IACvB,mBAAmB,OAAO;IAG1B,mBAAmB,OAAO;IAC1B,oBAAoB,OAAO;IAC3B,kBAAkB,OAAO;CAC1B;AAMD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iBAAiB;IACjB,IAAI,EAAE,SAAS,CAAC;IAChB,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,2BAA2B;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gBAAgB;IAChB,SAAS,EAAE,SAAS,CAAC;IACrB,iCAAiC;IACjC,aAAa,CAAC,EAAE,EAAE,CAAC;IACnB,qBAAqB;IACrB,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,yBAAyB;IACzB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,yBAAyB;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,2BAA2B;IAC3B,QAAQ,CAAC,EAAE,kBAAkB,EAAE,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,sBAAsB;IACtB,IAAI,EAAE,YAAY,CAAC;IACnB,kBAAkB;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,iCAAiC;IACjC,WAAW,EAAE,OAAO,CAAC;IACrB,oCAAoC;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,GACpB,OAAO,GACP,UAAU,GACV,WAAW,GACX,QAAQ,GACR,QAAQ,CAAC;AAMb;;GAEG;AACH,MAAM,WAAW,kBAAmB,SAAQ,gBAAgB;IAC1D,IAAI,EAAE,SAAS,CAAC,gBAAgB,GAAG,SAAS,CAAC,cAAc,GAAG,SAAS,CAAC,oBAAoB,CAAC;IAC7F,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAiB,SAAQ,gBAAgB;IACxD,IAAI,EACA,SAAS,CAAC,qBAAqB,GAC/B,SAAS,CAAC,kBAAkB,GAC5B,SAAS,CAAC,cAAc,GACxB,SAAS,CAAC,sBAAsB,GAChC,SAAS,CAAC,gBAAgB,GAC1B,SAAS,CAAC,YAAY,GACtB,SAAS,CAAC,oBAAoB,GAC9B,SAAS,CAAC,sBAAsB,CAAC;IACrC,OAAO,EAAE,KAAK,GAAG,MAAM,GAAG,aAAa,CAAC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,eAAgB,SAAQ,gBAAgB;IACvD,IAAI,EACA,SAAS,CAAC,iBAAiB,GAC3B,SAAS,CAAC,iBAAiB,GAC3B,SAAS,CAAC,gBAAgB,GAC1B,SAAS,CAAC,kBAAkB,GAC5B,SAAS,CAAC,iBAAiB,CAAC;IAChC,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,mBAAmB,EAAE,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,wBAAwB;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe;IACf,QAAQ,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;IACvC,eAAe;IACf,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,iBAAiB;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,eAAgB,SAAQ,gBAAgB;IACvD,IAAI,EACA,SAAS,CAAC,cAAc,GACxB,SAAS,CAAC,eAAe,GACzB,SAAS,CAAC,gBAAgB,GAC1B,SAAS,CAAC,mBAAmB,CAAC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC;CACnD;AAED;;GAEG;AACH,MAAM,WAAW,QAAS,SAAQ,gBAAgB;IAChD,IAAI,EACA,SAAS,CAAC,mBAAmB,GAC7B,SAAS,CAAC,oBAAoB,GAC9B,SAAS,CAAC,kBAAkB,CAAC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAMD;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,QAAQ,CAAC,EAAE,kBAAkB,EAAE,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;AAE5E;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,qBAAqB;IACrB,QAAQ,EAAE,aAAa,CAAC;IACxB,mCAAmC;IACnC,WAAW,EAAE,OAAO,CAAC;IACrB,2BAA2B;IAC3B,SAAS,EAAE,OAAO,CAAC;IACnB,gBAAgB;IAChB,QAAQ,EAAE,aAAa,CAAC;IACxB,gCAAgC;IAChC,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,MAAM,aAAa,GACrB,eAAe,GACf,aAAa,GACb,YAAY,GACZ,YAAY,GACZ,KAAK,GACL,UAAU,CAAC"}

package/dist/types/errors.js

@@ -0,0 +1,55 @@
+/**
+ * Error Type Definitions for MUSUBIX
+ *
+ * @packageDocumentation
+ * @module types/errors
+ *
+ * @see REQ-ERR-001 - Graceful Degradation
+ * @see REQ-MNT-002 - Error Handler
+ * @see DES-MUSUBIX-001 Section 10 - Error Handling Design
+ */
+// ============================================================================
+// Error Codes
+// ============================================================================
+/**
+ * MUSUBIX error codes
+ */
+export var ErrorCode;
+(function (ErrorCode) {
+    // General errors (1xxx)
+    ErrorCode[ErrorCode["UNKNOWN"] = 1000] = "UNKNOWN";
+    ErrorCode[ErrorCode["INTERNAL"] = 1001] = "INTERNAL";
+    ErrorCode[ErrorCode["INVALID_ARGUMENT"] = 1002] = "INVALID_ARGUMENT";
+    ErrorCode[ErrorCode["NOT_FOUND"] = 1003] = "NOT_FOUND";
+    ErrorCode[ErrorCode["ALREADY_EXISTS"] = 1004] = "ALREADY_EXISTS";
+    ErrorCode[ErrorCode["PERMISSION_DENIED"] = 1005] = "PERMISSION_DENIED";
+    // Configuration errors (2xxx)
+    ErrorCode[ErrorCode["CONFIG_NOT_FOUND"] = 2000] = "CONFIG_NOT_FOUND";
+    ErrorCode[ErrorCode["CONFIG_INVALID"] = 2001] = "CONFIG_INVALID";
+    ErrorCode[ErrorCode["CONFIG_MISSING_FIELD"] = 2002] = "CONFIG_MISSING_FIELD";
+    // Integration errors (3xxx)
+    ErrorCode[ErrorCode["LLM_CONNECTION_FAILED"] = 3000] = "LLM_CONNECTION_FAILED";
+    ErrorCode[ErrorCode["LLM_RESPONSE_ERROR"] = 3001] = "LLM_RESPONSE_ERROR";
+    ErrorCode[ErrorCode["LLM_RATE_LIMIT"] = 3002] = "LLM_RATE_LIMIT";
+    ErrorCode[ErrorCode["YATA_CONNECTION_FAILED"] = 3100] = "YATA_CONNECTION_FAILED";
+    ErrorCode[ErrorCode["YATA_QUERY_ERROR"] = 3101] = "YATA_QUERY_ERROR";
+    ErrorCode[ErrorCode["YATA_TIMEOUT"] = 3102] = "YATA_TIMEOUT";
+    ErrorCode[ErrorCode["INTEGRATION_MISMATCH"] = 3200] = "INTEGRATION_MISMATCH";
+    ErrorCode[ErrorCode["CONTRADICTION_DETECTED"] = 3201] = "CONTRADICTION_DETECTED";
+    // Validation errors (4xxx)
+    ErrorCode[ErrorCode["VALIDATION_FAILED"] = 4000] = "VALIDATION_FAILED";
+    ErrorCode[ErrorCode["EARS_SYNTAX_ERROR"] = 4001] = "EARS_SYNTAX_ERROR";
+    ErrorCode[ErrorCode["DESIGN_VIOLATION"] = 4002] = "DESIGN_VIOLATION";
+    ErrorCode[ErrorCode["CODE_QUALITY_ERROR"] = 4003] = "CODE_QUALITY_ERROR";
+    ErrorCode[ErrorCode["TEST_COVERAGE_LOW"] = 4004] = "TEST_COVERAGE_LOW";
+    // File system errors (5xxx)
+    ErrorCode[ErrorCode["FILE_NOT_FOUND"] = 5000] = "FILE_NOT_FOUND";
+    ErrorCode[ErrorCode["FILE_READ_ERROR"] = 5001] = "FILE_READ_ERROR";
+    ErrorCode[ErrorCode["FILE_WRITE_ERROR"] = 5002] = "FILE_WRITE_ERROR";
+    ErrorCode[ErrorCode["DIRECTORY_NOT_FOUND"] = 5003] = "DIRECTORY_NOT_FOUND";
+    // CLI errors (6xxx)
+    ErrorCode[ErrorCode["CLI_INVALID_COMMAND"] = 6000] = "CLI_INVALID_COMMAND";
+    ErrorCode[ErrorCode["CLI_MISSING_ARGUMENT"] = 6001] = "CLI_MISSING_ARGUMENT";
+    ErrorCode[ErrorCode["CLI_INVALID_OPTION"] = 6002] = "CLI_INVALID_OPTION";
+})(ErrorCode || (ErrorCode = {}));
+//# sourceMappingURL=errors.js.map

package/dist/types/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/types/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,+EAA+E;AAC/E,cAAc;AACd,+EAA+E;AAE/E;;GAEG;AACH,MAAM,CAAN,IAAY,SAyCX;AAzCD,WAAY,SAAS;IACnB,wBAAwB;IACxB,kDAAc,CAAA;IACd,oDAAe,CAAA;IACf,oEAAuB,CAAA;IACvB,sDAAgB,CAAA;IAChB,gEAAqB,CAAA;IACrB,sEAAwB,CAAA;IAExB,8BAA8B;IAC9B,oEAAuB,CAAA;IACvB,gEAAqB,CAAA;IACrB,4EAA2B,CAAA;IAE3B,4BAA4B;IAC5B,8EAA4B,CAAA;IAC5B,wEAAyB,CAAA;IACzB,gEAAqB,CAAA;IACrB,gFAA6B,CAAA;IAC7B,oEAAuB,CAAA;IACvB,4DAAmB,CAAA;IACnB,4EAA2B,CAAA;IAC3B,gFAA6B,CAAA;IAE7B,2BAA2B;IAC3B,sEAAwB,CAAA;IACxB,sEAAwB,CAAA;IACxB,oEAAuB,CAAA;IACvB,wEAAyB,CAAA;IACzB,sEAAwB,CAAA;IAExB,4BAA4B;IAC5B,gEAAqB,CAAA;IACrB,kEAAsB,CAAA;IACtB,oEAAuB,CAAA;IACvB,0EAA0B,CAAA;IAE1B,oBAAoB;IACpB,0EAA0B,CAAA;IAC1B,4EAA2B,CAAA;IAC3B,wEAAyB,CAAA;AAC3B,CAAC,EAzCW,SAAS,KAAT,SAAS,QAyCpB"}

package/dist/types/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Type Definitions Index
+ *
+ * @packageDocumentation
+ * @module types
+ */
+export * from './common.js';
+export * from './ears.js';
+export * from './errors.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC"}

package/dist/types/index.js

@@ -0,0 +1,10 @@
+/**
+ * Type Definitions Index
+ *
+ * @packageDocumentation
+ * @module types
+ */
+export * from './common.js';
+export * from './ears.js';
+export * from './errors.js';
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC"}

package/dist/utils/data-protector.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Data Protector Utility
+ *
+ * Provides data protection, encryption, and security features
+ *
+ * @packageDocumentation
+ * @module utils/data-protector
+ *
+ * @see REQ-SEC-001 - Data Protector
+ * @see REQ-ERR-002 - Data Persistence
+ * @see DES-MUSUBIX-001 Section 14.1 - Data Protector Design
+ */
+/**
+ * Data protection options
+ */
+export interface ProtectionOptions {
+    /** Enable encryption */
+    encrypt: boolean;
+    /** Encryption key or password */
+    key?: string;
+    /** Enable integrity verification */
+    verify: boolean;
+    /** Enable backup */
+    backup: boolean;
+    /** Backup path */
+    backupPath?: string;
+}
+/**
+ * Protected data structure
+ */
+export interface ProtectedData {
+    /** Data version */
+    version: number;
+    /** Encrypted flag */
+    encrypted: boolean;
+    /** Encryption salt (hex) */
+    salt?: string;
+    /** Initialization vector (hex) */
+    iv?: string;
+    /** Authentication tag (hex) */
+    authTag?: string;
+    /** Data payload (encrypted or plain) */
+    payload: string;
+    /** Integrity hash */
+    hash: string;
+    /** Timestamp */
+    timestamp: string;
+}
+/**
+ * Data Protector class
+ */
+export declare class DataProtector {
+    private options;
+    constructor(options?: Partial<ProtectionOptions>);
+    /**
+     * Update options
+     */
+    configure(options: Partial<ProtectionOptions>): void;
+    /**
+     * Protect and save data to file
+     */
+    save<T>(filePath: string, data: T, options?: Partial<ProtectionOptions>): Promise<void>;
+    /**
+     * Load and verify data from file
+     */
+    load<T>(filePath: string, options?: Partial<ProtectionOptions>): Promise<T>;
+    /**
+     * Check if file exists
+     */
+    exists(filePath: string): Promise<boolean>;
+    /**
+     * Delete protected file
+     */
+    delete(filePath: string, options?: {
+        deleteBackups?: boolean;
+    }): Promise<void>;
+    /**
+     * Calculate hash of data
+     */
+    hash(data: string): string;
+    /**
+     * Verify data integrity
+     */
+    verifyIntegrity(protected_: ProtectedData): boolean;
+    /**
+     * Create plain protected data structure
+     */
+    private createPlainProtected;
+    /**
+     * Encrypt data
+     */
+    private encrypt;
+    /**
+     * Decrypt data
+     */
+    private decrypt;
+    /**
+     * Create backup of file
+     */
+    private createBackup;
+    /**
+     * Get backup file path
+     */
+    private getBackupPath;
+}
+/**
+ * Check if key might contain sensitive data
+ */
+export declare function isSensitiveKey(key: string): boolean;
+/**
+ * Mask sensitive value for logging
+ */
+export declare function maskValue(value: string): string;
+/**
+ * Redact sensitive data from object for logging
+ */
+export declare function redactSensitive<T extends Record<string, unknown>>(obj: T): T;
+/**
+ * Global data protector instance
+ */
+export declare const dataProtector: DataProtector;
+//# sourceMappingURL=data-protector.d.ts.map

package/dist/utils/data-protector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-protector.d.ts","sourceRoot":"","sources":["../../src/utils/data-protector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAiBH;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,wBAAwB;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,iCAAiC;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,MAAM,EAAE,OAAO,CAAC;IAChB,oBAAoB;IACpB,MAAM,EAAE,OAAO,CAAC;IAChB,kBAAkB;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,mBAAmB;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,qBAAqB;IACrB,SAAS,EAAE,OAAO,CAAC;IACnB,4BAA4B;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kCAAkC;IAClC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,+BAA+B;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAWD;;GAEG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,OAAO,CAAoB;gBAEvB,OAAO,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC;IAIhD;;OAEG;IACH,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAAG,IAAI;IAIpD;;OAEG;IACG,IAAI,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAuB7F;;OAEG;IACG,IAAI,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IA6BjF;;OAEG;IACG,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAShD;;OAEG;IACG,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAapF;;OAEG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAI1B;;OAEG;IACH,eAAe,CAAC,UAAU,EAAE,aAAa,GAAG,OAAO;IAKnD;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAU5B;;OAEG;YACW,OAAO;IA4BrB;;OAEG;YACW,OAAO;IA0BrB;;OAEG;YACW,YAAY;IAiB1B;;OAEG;IACH,OAAO,CAAC,aAAa;CAWtB;AAeD;;GAEG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAK/C;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAc5E;AAED;;GAEG;AACH,eAAO,MAAM,aAAa,eAAsB,CAAC"}

package/dist/utils/data-protector.js

@@ -0,0 +1,275 @@
+/**
+ * Data Protector Utility
+ *
+ * Provides data protection, encryption, and security features
+ *
+ * @packageDocumentation
+ * @module utils/data-protector
+ *
+ * @see REQ-SEC-001 - Data Protector
+ * @see REQ-ERR-002 - Data Persistence
+ * @see DES-MUSUBIX-001 Section 14.1 - Data Protector Design
+ */
+import { createHash, createCipheriv, createDecipheriv, randomBytes, scrypt } from 'crypto';
+import { promisify } from 'util';
+import { readFile, writeFile, mkdir, access, unlink } from 'fs/promises';
+import { join, dirname } from 'path';
+const scryptAsync = promisify(scrypt);
+/**
+ * Encryption algorithm
+ */
+const ALGORITHM = 'aes-256-gcm';
+const KEY_LENGTH = 32;
+const IV_LENGTH = 16;
+const SALT_LENGTH = 32;
+/**
+ * Default protection options
+ */
+const DEFAULT_OPTIONS = {
+    encrypt: false,
+    verify: true,
+    backup: true,
+};
+/**
+ * Data Protector class
+ */
+export class DataProtector {
+    options;
+    constructor(options) {
+        this.options = { ...DEFAULT_OPTIONS, ...options };
+    }
+    /**
+     * Update options
+     */
+    configure(options) {
+        this.options = { ...this.options, ...options };
+    }
+    /**
+     * Protect and save data to file
+     */
+    async save(filePath, data, options) {
+        const opts = { ...this.options, ...options };
+        // Create backup if enabled
+        if (opts.backup) {
+            await this.createBackup(filePath, opts.backupPath);
+        }
+        // Serialize data
+        const serialized = JSON.stringify(data, null, 2);
+        // Create protected structure
+        const protected_ = opts.encrypt && opts.key
+            ? await this.encrypt(serialized, opts.key)
+            : this.createPlainProtected(serialized);
+        // Ensure directory exists
+        await mkdir(dirname(filePath), { recursive: true });
+        // Write to file
+        await writeFile(filePath, JSON.stringify(protected_, null, 2));
+    }
+    /**
+     * Load and verify data from file
+     */
+    async load(filePath, options) {
+        const opts = { ...this.options, ...options };
+        // Read file
+        const content = await readFile(filePath, 'utf-8');
+        const protected_ = JSON.parse(content);
+        // Verify integrity if enabled
+        if (opts.verify) {
+            const isValid = this.verifyIntegrity(protected_);
+            if (!isValid) {
+                throw new Error('Data integrity verification failed');
+            }
+        }
+        // Decrypt if encrypted
+        let payload;
+        if (protected_.encrypted) {
+            if (!opts.key) {
+                throw new Error('Encryption key required to load encrypted data');
+            }
+            payload = await this.decrypt(protected_, opts.key);
+        }
+        else {
+            payload = protected_.payload;
+        }
+        return JSON.parse(payload);
+    }
+    /**
+     * Check if file exists
+     */
+    async exists(filePath) {
+        try {
+            await access(filePath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Delete protected file
+     */
+    async delete(filePath, options) {
+        await unlink(filePath);
+        if (options?.deleteBackups && this.options.backupPath) {
+            const backupPath = this.getBackupPath(filePath, this.options.backupPath);
+            try {
+                await unlink(backupPath);
+            }
+            catch {
+                // Backup may not exist
+            }
+        }
+    }
+    /**
+     * Calculate hash of data
+     */
+    hash(data) {
+        return createHash('sha256').update(data).digest('hex');
+    }
+    /**
+     * Verify data integrity
+     */
+    verifyIntegrity(protected_) {
+        const calculatedHash = this.hash(protected_.payload);
+        return calculatedHash === protected_.hash;
+    }
+    /**
+     * Create plain protected data structure
+     */
+    createPlainProtected(data) {
+        return {
+            version: 1,
+            encrypted: false,
+            payload: data,
+            hash: this.hash(data),
+            timestamp: new Date().toISOString(),
+        };
+    }
+    /**
+     * Encrypt data
+     */
+    async encrypt(data, password) {
+        // Generate salt and derive key
+        const salt = randomBytes(SALT_LENGTH);
+        const key = await scryptAsync(password, salt, KEY_LENGTH);
+        // Generate IV
+        const iv = randomBytes(IV_LENGTH);
+        // Encrypt
+        const cipher = createCipheriv(ALGORITHM, key, iv);
+        const encrypted = Buffer.concat([
+            cipher.update(data, 'utf8'),
+            cipher.final(),
+        ]);
+        const authTag = cipher.getAuthTag();
+        return {
+            version: 1,
+            encrypted: true,
+            salt: salt.toString('hex'),
+            iv: iv.toString('hex'),
+            authTag: authTag.toString('hex'),
+            payload: encrypted.toString('hex'),
+            hash: this.hash(encrypted.toString('hex')),
+            timestamp: new Date().toISOString(),
+        };
+    }
+    /**
+     * Decrypt data
+     */
+    async decrypt(protected_, password) {
+        if (!protected_.salt || !protected_.iv || !protected_.authTag) {
+            throw new Error('Invalid encrypted data structure');
+        }
+        // Derive key from password
+        const salt = Buffer.from(protected_.salt, 'hex');
+        const key = await scryptAsync(password, salt, KEY_LENGTH);
+        // Get IV and auth tag
+        const iv = Buffer.from(protected_.iv, 'hex');
+        const authTag = Buffer.from(protected_.authTag, 'hex');
+        const encrypted = Buffer.from(protected_.payload, 'hex');
+        // Decrypt
+        const decipher = createDecipheriv(ALGORITHM, key, iv);
+        decipher.setAuthTag(authTag);
+        const decrypted = Buffer.concat([
+            decipher.update(encrypted),
+            decipher.final(),
+        ]);
+        return decrypted.toString('utf8');
+    }
+    /**
+     * Create backup of file
+     */
+    async createBackup(filePath, backupDir) {
+        try {
+            const exists = await this.exists(filePath);
+            if (!exists) {
+                return;
+            }
+            const content = await readFile(filePath, 'utf-8');
+            const backupPath = this.getBackupPath(filePath, backupDir);
+            await mkdir(dirname(backupPath), { recursive: true });
+            await writeFile(backupPath, content);
+        }
+        catch {
+            // Silently fail backup - don't block main operation
+        }
+    }
+    /**
+     * Get backup file path
+     */
+    getBackupPath(filePath, backupDir) {
+        const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+        const fileName = filePath.split('/').pop() ?? 'backup';
+        const backupFileName = `${fileName}.${timestamp}.bak`;
+        if (backupDir) {
+            return join(backupDir, backupFileName);
+        }
+        return join(dirname(filePath), '.backups', backupFileName);
+    }
+}
+/**
+ * Sensitive data patterns for detection
+ */
+const SENSITIVE_PATTERNS = [
+    /api[_-]?key/i,
+    /secret/i,
+    /password/i,
+    /token/i,
+    /credential/i,
+    /private[_-]?key/i,
+    /auth/i,
+];
+/**
+ * Check if key might contain sensitive data
+ */
+export function isSensitiveKey(key) {
+    return SENSITIVE_PATTERNS.some(pattern => pattern.test(key));
+}
+/**
+ * Mask sensitive value for logging
+ */
+export function maskValue(value) {
+    if (value.length <= 4) {
+        return '****';
+    }
+    return value.slice(0, 2) + '*'.repeat(value.length - 4) + value.slice(-2);
+}
+/**
+ * Redact sensitive data from object for logging
+ */
+export function redactSensitive(obj) {
+    const result = { ...obj };
+    for (const key of Object.keys(result)) {
+        const value = result[key];
+        if (isSensitiveKey(key) && typeof value === 'string') {
+            result[key] = maskValue(value);
+        }
+        else if (value && typeof value === 'object' && !Array.isArray(value)) {
+            result[key] = redactSensitive(value);
+        }
+    }
+    return result;
+}
+/**
+ * Global data protector instance
+ */
+export const dataProtector = new DataProtector();
+//# sourceMappingURL=data-protector.js.map