@digitaldefiance/ecies-lib 4.12.7 → 4.13.0

package/src/secure-buffer.d.ts

@@ -1,13 +1,26 @@
 /**
- * A secure string buffer is a buffer whose intent is to prevent the raw password from being stored in memory.
- * The buffer is encrypted with a key derived from a random ID.
- * The ID is stored in the clear, but the buffer is encrypted with a key derived from the ID.
- * This allows the buffer to be decrypted, but only if the ID and salt are known.
+ * A secure buffer that prevents raw sensitive data from being stored in memory.
+ * The buffer is obfuscated with a key derived from a random ID.
  *
- * Supports explicit resource management (TC39 proposal) for automatic disposal:
+ * Features:
+ * - XOR obfuscation of sensitive data
+ * - Automatic disposal support (TC39 explicit resource management)
+ * - Checksum validation for data integrity
+ * - Stack trace capture for debugging disposed access
+ *
+ * @example
  * ```typescript
+ * // Using explicit resource management
  * using buffer = new SecureBuffer(sensitiveData);
  * // buffer automatically disposed when leaving scope
+ *
+ * // Manual disposal
+ * const buffer = new SecureBuffer(sensitiveData);
+ * try {
+ *   const data = buffer.value;
+ * } finally {
+ *   buffer.dispose();
+ * }
  * ```
  */
 export declare class SecureBuffer implements Disposable {
@@ -19,7 +32,15 @@ export declare class SecureBuffer implements Disposable {
     private readonly _key;
     private readonly _obfuscatedChecksum;
     private _disposedAt?;
+    /**
+     * Creates a new SecureBuffer instance.
+     * @param data Optional data to secure. If undefined or empty, creates an empty buffer.
+     */
     constructor(data?: Uint8Array);
+    /**
+     * Disposes the secure buffer, zeroing out all sensitive data.
+     * Captures a stack trace for debugging if the buffer is accessed after disposal.
+     */
     dispose(): void;
     /**
      * Symbol.dispose implementation for explicit resource management
@@ -27,34 +48,124 @@ export declare class SecureBuffer implements Disposable {
      */
     [Symbol.dispose](): void;
     /**
-     * Factory method for backward compatibility that uses the default ObjectIdProvider
+     * Factory method for backward compatibility that uses the default ObjectIdProvider.
      * @param data Optional data to secure
      * @returns A new SecureBuffer instance using the default ID provider
      */
     static create(data?: Uint8Array): SecureBuffer;
     /**
-     * Static factory method that creates a SecureBuffer for a symmetric key
-     * Useful for managing encryption keys securely
+     * Static factory method that creates a SecureBuffer for a symmetric key.
+     * Useful for managing encryption keys securely.
+     * @param sizeBytes Size of the key in bytes (default: 32)
+     * @returns A new SecureBuffer instance for the key
      */
     static allocateKey(sizeBytes?: number): SecureBuffer;
+    /**
+     * Asserts that the buffer has not been disposed.
+     * @throws {DisposedError} If the buffer has been disposed
+     */
     private assertNotDisposed;
+    /**
+     * Creates a SecureBuffer from a string.
+     * @param data The string to secure
+     * @returns A new SecureBuffer containing the UTF-8 encoded string
+     */
     static fromString(data: string): SecureBuffer;
+    /**
+     * Gets the stack trace from when the buffer was disposed.
+     * Useful for debugging access-after-dispose errors.
+     */
     get disposedAtStack(): string | undefined;
+    /**
+     * Gets the buffer's unique ID as a string.
+     * @throws {DisposedError} If the buffer has been disposed
+     */
     get id(): string;
+    /**
+     * Gets the buffer's unique ID as a Uint8Array.
+     * @throws {DisposedError} If the buffer has been disposed
+     */
     get idUint8Array(): Uint8Array;
+    /**
+     * Gets the original length of the secured data in bytes.
+     * @throws {DisposedError} If the buffer has been disposed
+     */
     get originalLength(): number;
+    /**
+     * Gets the decrypted value as a Uint8Array.
+     * Validates the checksum to ensure data integrity.
+     * @throws {DisposedError} If the buffer has been disposed
+     * @throws {SecureStorageError} If decryption fails or checksum is invalid
+     */
     get value(): Uint8Array;
+    /**
+     * Gets the decrypted value as a UTF-8 string.
+     * @throws {DisposedError} If the buffer has been disposed
+     */
     get valueAsString(): string;
+    /**
+     * Gets the decrypted value as a hexadecimal string.
+     * @throws {DisposedError} If the buffer has been disposed
+     */
     get valueAsHexString(): string;
+    /**
+     * Gets the decrypted value as a Base64 string.
+     * @throws {DisposedError} If the buffer has been disposed
+     */
     get valueAsBase64String(): string;
+    /**
+     * Gets the checksum of the secured data.
+     * @throws {DisposedError} If the buffer has been disposed
+     */
     get checksum(): string;
+    /**
+     * Generates a simple checksum for data validation.
+     * @param data The data to checksum (string or Uint8Array)
+     * @returns Hexadecimal checksum string
+     */
     private generateSimpleChecksum;
+    /**
+     * Creates an obfuscated checksum for the data.
+     * @param data The data to checksum
+     * @returns Obfuscated checksum as Uint8Array
+     */
     private createSimpleObfuscatedChecksum;
+    /**
+     * Validates a checksum against data using timing-safe comparison.
+     * @param data The data to validate
+     * @param checksum The expected checksum
+     * @returns True if checksum is valid
+     */
     private validateSimpleChecksum;
+    /**
+     * Performs timing-safe equality comparison of two byte arrays.
+     * @param a First array
+     * @param b Second array
+     * @returns True if arrays are equal
+     */
     private timingSafeEqual;
+    /**
+     * Validates the obfuscated checksum against data.
+     * @param data The data to validate
+     * @returns True if checksum is valid
+     */
     private validateObfuscatedChecksum;
+    /**
+     * Obfuscates data using XOR with the key.
+     * @param data The data to obfuscate
+     * @returns Obfuscated data
+     */
     private obfuscateData;
+    /**
+     * Deobfuscates data using XOR with the key.
+     * @param data The data to deobfuscate
+     * @returns Deobfuscated data
+     */
     private deobfuscateData;
+    /**
+     * Gets the length of the secured data in bytes.
+     * @throws {DisposedError} If the buffer has been disposed
+     */
     get length(): number;
 }
 //# sourceMappingURL=secure-buffer.d.ts.map

package/src/secure-buffer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"secure-buffer.d.ts","sourceRoot":"","sources":["../../../../packages/digitaldefiance-ecies-lib/src/secure-buffer.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;GAWG;AACH,qBAAa,YAAa,YAAW,UAAU;IAC7C,OAAO,CAAC,SAAS,CAAkB;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAa;IACjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAmB;IAC/C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAa;IAC9C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;IAClC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAa;IACjD,OAAO,CAAC,WAAW,CAAC,CAAS;gBAEjB,IAAI,CAAC,EAAE,UAAU;IAiBtB,OAAO,IAAI,IAAI;IAYtB;;;OAGG;IACH,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;IAIxB;;;;OAIG;IACH,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,UAAU,GAAG,YAAY;IAI9C;;;OAGG;IACH,MAAM,CAAC,WAAW,CAAC,SAAS,GAAE,MAAW,GAAG,YAAY;IAMxD,OAAO,CAAC,iBAAiB;WAWX,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY;IAGpD,IAAW,eAAe,IAAI,MAAM,GAAG,SAAS,CAE/C;IACD,IAAW,EAAE,IAAI,MAAM,CAGtB;IACD,IAAW,YAAY,IAAI,UAAU,CAGpC;IACD,IAAW,cAAc,IAAI,MAAM,CAGlC;IACD,IAAW,KAAK,IAAI,UAAU,CA4B7B;IACD,IAAW,aAAa,IAAI,MAAM,CAGjC;IACD,IAAW,gBAAgB,IAAI,MAAM,CAGpC;IACD,IAAW,mBAAmB,IAAI,MAAM,CAGvC;IACD,IAAW,QAAQ,IAAI,MAAM,CAM5B;IACD,OAAO,CAAC,sBAAsB;IAS9B,OAAO,CAAC,8BAA8B;IAOtC,OAAO,CAAC,sBAAsB;IAU9B,OAAO,CAAC,eAAe;IAUvB,OAAO,CAAC,0BAA0B;IAMlC,OAAO,CAAC,aAAa;IAGrB,OAAO,CAAC,eAAe;IAGvB,IAAW,MAAM,IAAI,MAAM,CAG1B;CACF"}
+{"version":3,"file":"secure-buffer.d.ts","sourceRoot":"","sources":["../../../../packages/digitaldefiance-ecies-lib/src/secure-buffer.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,YAAa,YAAW,UAAU;IAC7C,OAAO,CAAC,SAAS,CAAkB;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAa;IACjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAmB;IAC/C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAa;IAC9C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;IAClC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAa;IACjD,OAAO,CAAC,WAAW,CAAC,CAAS;IAE7B;;;OAGG;gBACS,IAAI,CAAC,EAAE,UAAU;IAiB7B;;;OAGG;IACI,OAAO,IAAI,IAAI;IAYtB;;;OAGG;IACH,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;IAIxB;;;;OAIG;IACH,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,UAAU,GAAG,YAAY;IAI9C;;;;;OAKG;IACH,MAAM,CAAC,WAAW,CAAC,SAAS,GAAE,MAAW,GAAG,YAAY;IAMxD;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAWzB;;;;OAIG;WACW,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY;IAGpD;;;OAGG;IACH,IAAW,eAAe,IAAI,MAAM,GAAG,SAAS,CAE/C;IACD;;;OAGG;IACH,IAAW,EAAE,IAAI,MAAM,CAGtB;IACD;;;OAGG;IACH,IAAW,YAAY,IAAI,UAAU,CAGpC;IACD;;;OAGG;IACH,IAAW,cAAc,IAAI,MAAM,CAGlC;IACD;;;;;OAKG;IACH,IAAW,KAAK,IAAI,UAAU,CA4B7B;IACD;;;OAGG;IACH,IAAW,aAAa,IAAI,MAAM,CAGjC;IACD;;;OAGG;IACH,IAAW,gBAAgB,IAAI,MAAM,CAGpC;IACD;;;OAGG;IACH,IAAW,mBAAmB,IAAI,MAAM,CAGvC;IACD;;;OAGG;IACH,IAAW,QAAQ,IAAI,MAAM,CAM5B;IACD;;;;OAIG;IACH,OAAO,CAAC,sBAAsB;IAS9B;;;;OAIG;IACH,OAAO,CAAC,8BAA8B;IAOtC;;;;;OAKG;IACH,OAAO,CAAC,sBAAsB;IAU9B;;;;;OAKG;IACH,OAAO,CAAC,eAAe;IAUvB;;;;OAIG;IACH,OAAO,CAAC,0BAA0B;IAMlC;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAGrB;;;;OAIG;IACH,OAAO,CAAC,eAAe;IAGvB;;;OAGG;IACH,IAAW,MAAM,IAAI,MAAM,CAG1B;CACF"}

package/src/secure-buffer.js

@@ -8,15 +8,28 @@ const objectid_provider_1 = require("./lib/id-providers/objectid-provider");
 const xor_1 = require("./services/xor");
 const utils_1 = require("./utils");
 /**
- * A secure string buffer is a buffer whose intent is to prevent the raw password from being stored in memory.
- * The buffer is encrypted with a key derived from a random ID.
- * The ID is stored in the clear, but the buffer is encrypted with a key derived from the ID.
- * This allows the buffer to be decrypted, but only if the ID and salt are known.
+ * A secure buffer that prevents raw sensitive data from being stored in memory.
+ * The buffer is obfuscated with a key derived from a random ID.
  *
- * Supports explicit resource management (TC39 proposal) for automatic disposal:
+ * Features:
+ * - XOR obfuscation of sensitive data
+ * - Automatic disposal support (TC39 explicit resource management)
+ * - Checksum validation for data integrity
+ * - Stack trace capture for debugging disposed access
+ *
+ * @example
  * ```typescript
+ * // Using explicit resource management
  * using buffer = new SecureBuffer(sensitiveData);
  * // buffer automatically disposed when leaving scope
+ *
+ * // Manual disposal
+ * const buffer = new SecureBuffer(sensitiveData);
+ * try {
+ *   const data = buffer.value;
+ * } finally {
+ *   buffer.dispose();
+ * }
  * ```
  */
 class SecureBuffer {
@@ -28,6 +41,10 @@ class SecureBuffer {
     _key;
     _obfuscatedChecksum;
     _disposedAt;
+    /**
+     * Creates a new SecureBuffer instance.
+     * @param data Optional data to secure. If undefined or empty, creates an empty buffer.
+     */
     constructor(data) {
         this._idProvider = new objectid_provider_1.ObjectIdProvider();
         this._id = this._idProvider.generate();
@@ -45,6 +62,10 @@ class SecureBuffer {
         // Create a simple checksum without crypto for synchronous operation
         this._obfuscatedChecksum = this.createSimpleObfuscatedChecksum(data);
     }
+    /**
+     * Disposes the secure buffer, zeroing out all sensitive data.
+     * Captures a stack trace for debugging if the buffer is accessed after disposal.
+     */
     dispose() {
         const err = new disposed_1.DisposedError();
         if (typeof Error.captureStackTrace === 'function') {
@@ -64,7 +85,7 @@ class SecureBuffer {
         this.dispose();
     }
     /**
-     * Factory method for backward compatibility that uses the default ObjectIdProvider
+     * Factory method for backward compatibility that uses the default ObjectIdProvider.
      * @param data Optional data to secure
      * @returns A new SecureBuffer instance using the default ID provider
      */
@@ -72,14 +93,20 @@ class SecureBuffer {
         return new SecureBuffer(data);
     }
     /**
-     * Static factory method that creates a SecureBuffer for a symmetric key
-     * Useful for managing encryption keys securely
+     * Static factory method that creates a SecureBuffer for a symmetric key.
+     * Useful for managing encryption keys securely.
+     * @param sizeBytes Size of the key in bytes (default: 32)
+     * @returns A new SecureBuffer instance for the key
      */
     static allocateKey(sizeBytes = 32) {
         const keyData = new Uint8Array(sizeBytes);
         // Will be filled by crypto.getRandomValues by caller
         return new SecureBuffer(keyData);
     }
+    /**
+     * Asserts that the buffer has not been disposed.
+     * @throws {DisposedError} If the buffer has been disposed
+     */
     assertNotDisposed() {
         if (this._disposed) {
             const e = new disposed_1.DisposedError();
@@ -92,24 +119,51 @@ class SecureBuffer {
             throw e;
         }
     }
+    /**
+     * Creates a SecureBuffer from a string.
+     * @param data The string to secure
+     * @returns A new SecureBuffer containing the UTF-8 encoded string
+     */
     static fromString(data) {
         return new SecureBuffer(new TextEncoder().encode(data));
     }
+    /**
+     * Gets the stack trace from when the buffer was disposed.
+     * Useful for debugging access-after-dispose errors.
+     */
     get disposedAtStack() {
         return this._disposedAt;
     }
+    /**
+     * Gets the buffer's unique ID as a string.
+     * @throws {DisposedError} If the buffer has been disposed
+     */
     get id() {
         this.assertNotDisposed();
         return this._idProvider.serialize(this._id);
     }
+    /**
+     * Gets the buffer's unique ID as a Uint8Array.
+     * @throws {DisposedError} If the buffer has been disposed
+     */
     get idUint8Array() {
         this.assertNotDisposed();
         return this._id;
     }
+    /**
+     * Gets the original length of the secured data in bytes.
+     * @throws {DisposedError} If the buffer has been disposed
+     */
     get originalLength() {
         this.assertNotDisposed();
         return this._length;
     }
+    /**
+     * Gets the decrypted value as a Uint8Array.
+     * Validates the checksum to ensure data integrity.
+     * @throws {DisposedError} If the buffer has been disposed
+     * @throws {SecureStorageError} If decryption fails or checksum is invalid
+     */
     get value() {
         this.assertNotDisposed();
         if (this._length === 0) {
@@ -134,23 +188,44 @@ class SecureBuffer {
             throw new secure_storage_1.SecureStorageError(secure_storage_error_type_1.SecureStorageErrorType.DecryptedValueChecksumMismatch);
         }
     }
+    /**
+     * Gets the decrypted value as a UTF-8 string.
+     * @throws {DisposedError} If the buffer has been disposed
+     */
     get valueAsString() {
         this.assertNotDisposed();
         return new TextDecoder().decode(this.value);
     }
+    /**
+     * Gets the decrypted value as a hexadecimal string.
+     * @throws {DisposedError} If the buffer has been disposed
+     */
     get valueAsHexString() {
         this.assertNotDisposed();
         return (0, utils_1.uint8ArrayToHex)(this.value);
     }
+    /**
+     * Gets the decrypted value as a Base64 string.
+     * @throws {DisposedError} If the buffer has been disposed
+     */
     get valueAsBase64String() {
         this.assertNotDisposed();
         return btoa(String.fromCharCode(...this.value));
     }
+    /**
+     * Gets the checksum of the secured data.
+     * @throws {DisposedError} If the buffer has been disposed
+     */
     get checksum() {
         this.assertNotDisposed();
         const deobfuscatedChecksum = new TextDecoder().decode(this.deobfuscateData(this._obfuscatedChecksum));
         return deobfuscatedChecksum;
     }
+    /**
+     * Generates a simple checksum for data validation.
+     * @param data The data to checksum (string or Uint8Array)
+     * @returns Hexadecimal checksum string
+     */
     generateSimpleChecksum(data) {
         const dataBytes = typeof data === 'string' ? new TextEncoder().encode(data) : data;
         let hash = 0;
@@ -159,17 +234,34 @@ class SecureBuffer {
         }
         return hash.toString(16);
     }
+    /**
+     * Creates an obfuscated checksum for the data.
+     * @param data The data to checksum
+     * @returns Obfuscated checksum as Uint8Array
+     */
     createSimpleObfuscatedChecksum(data) {
         const checksum = this.generateSimpleChecksum(data);
         const result = this.obfuscateData(new TextEncoder().encode(checksum));
         return result;
     }
+    /**
+     * Validates a checksum against data using timing-safe comparison.
+     * @param data The data to validate
+     * @param checksum The expected checksum
+     * @returns True if checksum is valid
+     */
     validateSimpleChecksum(data, checksum) {
         const generatedChecksum = this.generateSimpleChecksum(data);
         const a = new TextEncoder().encode(generatedChecksum);
         const b = new TextEncoder().encode(checksum);
         return this.timingSafeEqual(a, b);
     }
+    /**
+     * Performs timing-safe equality comparison of two byte arrays.
+     * @param a First array
+     * @param b Second array
+     * @returns True if arrays are equal
+     */
     timingSafeEqual(a, b) {
         if (a.length !== b.length) {
             return false;
@@ -180,16 +272,35 @@ class SecureBuffer {
         }
         return result === 0;
     }
+    /**
+     * Validates the obfuscated checksum against data.
+     * @param data The data to validate
+     * @returns True if checksum is valid
+     */
     validateObfuscatedChecksum(data) {
         const deobfuscatedChecksum = new TextDecoder().decode(this.deobfuscateData(this._obfuscatedChecksum));
         return this.validateSimpleChecksum(data, deobfuscatedChecksum);
     }
+    /**
+     * Obfuscates data using XOR with the key.
+     * @param data The data to obfuscate
+     * @returns Obfuscated data
+     */
     obfuscateData(data) {
         return xor_1.XorService.xor(data, this._key);
     }
+    /**
+     * Deobfuscates data using XOR with the key.
+     * @param data The data to deobfuscate
+     * @returns Deobfuscated data
+     */
     deobfuscateData(data) {
         return xor_1.XorService.xor(data, this._key);
     }
+    /**
+     * Gets the length of the secured data in bytes.
+     * @throws {DisposedError} If the buffer has been disposed
+     */
     get length() {
         this.assertNotDisposed();
         return this._length;

package/src/secure-buffer.js.map

@@ -1 +1 @@
-{"version":3,"file":"secure-buffer.js","sourceRoot":"","sources":["../../../../packages/digitaldefiance-ecies-lib/src/secure-buffer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"secure-buffer.js","sourceRoot":"","sources":["../../../../packages/digitaldefiance-ecies-lib/src/secure-buffer.ts"],"names":[],"mappings":"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"}

package/src/secure-string.d.ts

@@ -1,7 +1,22 @@
 import type { ObjectId } from 'bson';
 import type { IIdProvider } from './interfaces/id-provider';
 /**
- * A secure string buffer is a buffer whose intent is to prevent the raw password from being stored in memory.
+ * A secure string buffer that prevents raw sensitive data from being stored in memory.
+ * Similar to SecureBuffer but specifically designed for string data.
+ *
+ * Features:
+ * - XOR obfuscation of sensitive string data
+ * - Null value support
+ * - Checksum validation for data integrity
+ * - Stack trace capture for debugging disposed access
+ * - Configurable ID provider
+ *
+ * @example
+ * ```typescript
+ * const securePassword = new SecureString('myPassword123');
+ * const password = securePassword.value; // Retrieves the original string
+ * securePassword.dispose(); // Zeroes out sensitive data
+ * ```
  */
 export declare class SecureString {
     private _disposed;
@@ -13,6 +28,11 @@ export declare class SecureString {
     private readonly _key;
     private readonly _obfuscatedChecksum;
     private _disposedAt?;
+    /**
+     * Creates a new SecureString instance.
+     * @param data Optional data to secure (string, Uint8Array, or null)
+     * @param idProvider ID provider for generating unique IDs (defaults to ObjectIdProvider)
+     */
     constructor(data?: string | Uint8Array | null, idProvider?: IIdProvider<ObjectId>);
     /**
      * Factory method for backward compatibility that uses the default ObjectIdProvider
@@ -20,28 +40,125 @@ export declare class SecureString {
      * @returns A new SecureString instance using the default ID provider
      */
     static create(data?: string | Uint8Array | null): SecureString;
+    /**
+     * Asserts that the string has not been disposed.
+     * @throws {DisposedError} If the string has been disposed
+     */
     private assertNotDisposed;
+    /**
+     * Disposes the secure string, zeroing out all sensitive data.
+     * Captures a stack trace for debugging if the string is accessed after disposal.
+     */
     dispose(): void;
+    /**
+     * Gets the stack trace from when the string was disposed.
+     * Useful for debugging access-after-dispose errors.
+     */
     get disposedAtStack(): string | undefined;
+    /**
+     * Gets the string's unique ID as a string.
+     * @throws {DisposedError} If the string has been disposed
+     */
     get id(): string;
+    /**
+     * Gets the string's unique ID as a Uint8Array.
+     * @throws {DisposedError} If the string has been disposed
+     */
     get idUint8Array(): Uint8Array;
+    /**
+     * Gets the original length of the secured data in bytes.
+     * @throws {DisposedError} If the string has been disposed
+     */
     get originalLength(): number;
+    /**
+     * Gets the decrypted value as a Uint8Array.
+     * Validates the checksum to ensure data integrity.
+     * @throws {DisposedError} If the string has been disposed
+     * @throws {SecureStorageError} If decryption fails or checksum is invalid
+     */
     get valueAsUint8Array(): Uint8Array;
+    /**
+     * Gets the decrypted value as a string, or null if the value is null.
+     * @throws {DisposedError} If the string has been disposed
+     */
     get value(): string | null;
+    /**
+     * Gets the decrypted value as a string, throwing if the value is null.
+     * @throws {DisposedError} If the string has been disposed
+     * @throws {SecureStorageError} If the value is null
+     */
     get notNullValue(): string;
+    /**
+     * Gets the decrypted value as a hexadecimal string.
+     * @throws {DisposedError} If the string has been disposed
+     */
     get valueAsHexString(): string;
+    /**
+     * Gets the decrypted value as a Base64 string.
+     * @throws {DisposedError} If the string has been disposed
+     */
     get valueAsBase64String(): string;
+    /**
+     * Checks if the string has a non-null, non-empty value.
+     * @throws {DisposedError} If the string has been disposed
+     */
     get hasValue(): boolean;
+    /**
+     * Gets the checksum of the secured data.
+     * @throws {DisposedError} If the string has been disposed
+     */
     get checksum(): string;
+    /**
+     * Gets the length of the secured data in bytes.
+     * @throws {DisposedError} If the string has been disposed
+     */
     get length(): number;
+    /**
+     * Generates a SHA-256 checksum for data validation (async).
+     * @param data The data to checksum (string or Uint8Array)
+     * @returns Promise resolving to hexadecimal checksum string
+     */
     private generateChecksum;
+    /**
+     * Creates a simple checksum for data validation (synchronous).
+     * @param data The data to checksum
+     * @returns Hexadecimal checksum string
+     */
     private createSimpleChecksum;
+    /**
+     * Creates an obfuscated checksum for the data (synchronous).
+     * @param data The data to checksum
+     * @returns Obfuscated checksum as Uint8Array
+     */
     private createSimpleObfuscatedChecksum;
     private __createObfuscatedChecksum;
+    /**
+     * Validates a checksum against data using timing-safe comparison (async).
+     * @param data The data to validate
+     * @param checksum The expected checksum
+     * @returns Promise resolving to true if checksum is valid
+     */
     private validateChecksum;
+    /**
+     * Performs timing-safe equality comparison of two byte arrays.
+     * Prevents timing attacks by always comparing all bytes.
+     * @param a First array
+     * @param b Second array
+     * @returns True if arrays are equal
+     */
     private timingSafeEqual;
     private __validateObfuscatedChecksum;
+    /**
+     * Obfuscates data using XOR with the key.
+     * @param data The data to obfuscate
+     * @returns Obfuscated data
+     */
     private obfuscateData;
+    /**
+     * Deobfuscates data using XOR with the key.
+     * @param data The data to deobfuscate
+     * @returns Deobfuscated data
+     */
     private deobfuscateData;
 }
 //# sourceMappingURL=secure-string.d.ts.map

package/src/secure-string.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"secure-string.d.ts","sourceRoot":"","sources":["../../../../packages/digitaldefiance-ecies-lib/src/secure-string.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,MAAM,CAAC;AAIrC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAU5D;;GAEG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,SAAS,CAAkB;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAa;IACjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAwB;IACpD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAa;IAC9C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;IAClC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAa;IACjD,OAAO,CAAC,WAAW,CAAC,CAAS;gBAE3B,IAAI,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,EACjC,UAAU,GAAE,WAAW,CAAC,QAAQ,CAAuB;IA0BzD;;;;OAIG;IACH,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,GAAG,YAAY;IAI9D,OAAO,CAAC,iBAAiB;IAWlB,OAAO,IAAI,IAAI;IAWtB,IAAW,eAAe,IAAI,MAAM,GAAG,SAAS,CAE/C;IACD,IAAW,EAAE,IAAI,MAAM,CAGtB;IACD,IAAW,YAAY,IAAI,UAAU,CAGpC;IACD,IAAW,cAAc,IAAI,MAAM,CAGlC;IACD,IAAW,iBAAiB,IAAI,UAAU,CAsCzC;IACD,IAAW,KAAK,IAAI,MAAM,GAAG,IAAI,CAMhC;IACD,IAAW,YAAY,IAAI,MAAM,CAMhC;IACD,IAAW,gBAAgB,IAAI,MAAM,CAGpC;IACD,IAAW,mBAAmB,IAAI,MAAM,CAGvC;IACD,IAAW,QAAQ,IAAI,OAAO,CAG7B;IACD,IAAW,QAAQ,IAAI,MAAM,CAM5B;IACD,IAAW,MAAM,IAAI,MAAM,CAG1B;YACa,gBAAgB;IAS9B,OAAO,CAAC,oBAAoB;IAQ5B,OAAO,CAAC,8BAA8B;YASxB,0BAA0B;YAO1B,gBAAgB;IAQ9B,OAAO,CAAC,eAAe;YAUT,4BAA4B;IAQ1C,OAAO,CAAC,aAAa;IAGrB,OAAO,CAAC,eAAe;CAGxB"}
+{"version":3,"file":"secure-string.d.ts","sourceRoot":"","sources":["../../../../packages/digitaldefiance-ecies-lib/src/secure-string.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,MAAM,CAAC;AAIrC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAU5D;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,SAAS,CAAkB;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAa;IACjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAwB;IACpD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAa;IAC9C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;IAClC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAa;IACjD,OAAO,CAAC,WAAW,CAAC,CAAS;IAC7B;;;;OAIG;gBAED,IAAI,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,EACjC,UAAU,GAAE,WAAW,CAAC,QAAQ,CAAuB;IA0BzD;;;;OAIG;IACH,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,GAAG,YAAY;IAI9D;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAWzB;;;OAGG;IACI,OAAO,IAAI,IAAI;IAWtB;;;OAGG;IACH,IAAW,eAAe,IAAI,MAAM,GAAG,SAAS,CAE/C;IACD;;;OAGG;IACH,IAAW,EAAE,IAAI,MAAM,CAGtB;IACD;;;OAGG;IACH,IAAW,YAAY,IAAI,UAAU,CAGpC;IACD;;;OAGG;IACH,IAAW,cAAc,IAAI,MAAM,CAGlC;IACD;;;;;OAKG;IACH,IAAW,iBAAiB,IAAI,UAAU,CAsCzC;IACD;;;OAGG;IACH,IAAW,KAAK,IAAI,MAAM,GAAG,IAAI,CAMhC;IACD;;;;OAIG;IACH,IAAW,YAAY,IAAI,MAAM,CAMhC;IACD;;;OAGG;IACH,IAAW,gBAAgB,IAAI,MAAM,CAGpC;IACD;;;OAGG;IACH,IAAW,mBAAmB,IAAI,MAAM,CAGvC;IACD;;;OAGG;IACH,IAAW,QAAQ,IAAI,OAAO,CAG7B;IACD;;;OAGG;IACH,IAAW,QAAQ,IAAI,MAAM,CAM5B;IACD;;;OAGG;IACH,IAAW,MAAM,IAAI,MAAM,CAG1B;IACD;;;;OAIG;YACW,gBAAgB;IAS9B;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAQ5B;;;;OAIG;IACH,OAAO,CAAC,8BAA8B;YASxB,0BAA0B;IAOxC;;;;;OAKG;YACW,gBAAgB;IAQ9B;;;;;;OAMG;IACH,OAAO,CAAC,eAAe;YAUT,4BAA4B;IAQ1C;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAGrB;;;;OAIG;IACH,OAAO,CAAC,eAAe;CAGxB"}