@digitaldefiance/node-express-suite 3.7.5 → 3.8.0

package/src/services/fec.js

@@ -0,0 +1,246 @@
+"use strict";
+/**
+ * @fileoverview Forward Error Correction (FEC) service using Reed-Solomon erasure coding.
+ * Provides parity data creation, file recovery, and integrity verification for distributed storage.
+ * @module services/fec
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FecService = void 0;
+const suite_core_lib_1 = require("@digitaldefiance/suite-core-lib");
+const reed_solomon_erasure_wasm_1 = require("@subspace/reed-solomon-erasure.wasm");
+const constants_1 = require("../constants");
+class FecService {
+    /**
+     * Encodes data using Reed-Solomon erasure coding.
+     * @param data Data buffer to encode
+     * @param shardSize Size of each shard in bytes
+     * @param dataShards Number of data shards
+     * @param parityShards Number of parity shards
+     * @param fecOnly If true, returns only parity shards; otherwise returns all shards
+     * @param fecConstants FEC constants (defaults to FEC)
+     * @returns Encoded buffer containing shards
+     * @throws {FecError} If parameters are invalid or encoding fails
+     */
+    async encode(data, shardSize, dataShards, parityShards, fecOnly, fecConstants = constants_1.FEC) {
+        // Validate parameters
+        if (!data || data.length === 0) {
+            throw new suite_core_lib_1.FecError(suite_core_lib_1.FecErrorType.DataRequired);
+        }
+        if (data.length !== shardSize * dataShards) {
+            throw new suite_core_lib_1.FecError(suite_core_lib_1.FecErrorType.InvalidDataLength, undefined, {
+                LENGTH: data.length.toString(),
+                EXPECTED: (shardSize * dataShards).toString(),
+            });
+        }
+        if (shardSize > fecConstants.MAX_SHARD_SIZE) {
+            throw new suite_core_lib_1.FecError(suite_core_lib_1.FecErrorType.ShardSizeExceedsMaximum, undefined, {
+                SIZE: shardSize.toString(),
+                MAXIMUM: fecConstants.MAX_SHARD_SIZE.toString(),
+            });
+        }
+        if (dataShards <= 0 || parityShards <= 0) {
+            throw new suite_core_lib_1.FecError(suite_core_lib_1.FecErrorType.InvalidShardCounts);
+        }
+        try {
+            const shards = new Uint8Array(shardSize * (dataShards + parityShards));
+            shards.set(new Uint8Array(data));
+            // Encoding
+            const reedSolomonErasure = await reed_solomon_erasure_wasm_1.ReedSolomonErasure.fromCurrentDirectory();
+            reedSolomonErasure.encode(shards, dataShards, parityShards);
+            return fecOnly
+                ? Buffer.from(shards.subarray(shardSize * dataShards))
+                : Buffer.from(shards);
+        }
+        catch (error) {
+            throw new suite_core_lib_1.FecError(suite_core_lib_1.FecErrorType.FecEncodingFailed, undefined, {
+                ERROR: error instanceof Error ? error.message : 'Unknown error',
+            });
+        }
+    }
+    /**
+     * Decodes/reconstructs data using Reed-Solomon erasure coding.
+     * @param data Encoded data buffer containing all shards
+     * @param shardSize Size of each shard in bytes
+     * @param dataShards Number of data shards
+     * @param parityShards Number of parity shards
+     * @param shardsAvailable Boolean array indicating which shards are available
+     * @returns Reconstructed data buffer
+     * @throws {FecError} If parameters are invalid or decoding fails
+     */
+    async decode(data, shardSize, dataShards, parityShards, shardsAvailable) {
+        // Validate parameters
+        if (!data || data.length === 0) {
+            throw new suite_core_lib_1.FecError(suite_core_lib_1.FecErrorType.DataRequired);
+        }
+        if (data.length !== shardSize * (dataShards + parityShards)) {
+            throw new suite_core_lib_1.FecError(suite_core_lib_1.FecErrorType.InvalidDataLength, undefined, {
+                LENGTH: data.length.toString(),
+                EXPECTED: (shardSize * (dataShards + parityShards)).toString(),
+            });
+        }
+        if (!shardsAvailable ||
+            shardsAvailable.length !== dataShards + parityShards) {
+            throw new suite_core_lib_1.FecError(suite_core_lib_1.FecErrorType.InvalidShardsAvailableArray);
+        }
+        const availableCount = shardsAvailable.filter((x) => x).length;
+        if (availableCount < dataShards) {
+            throw new suite_core_lib_1.FecError(suite_core_lib_1.FecErrorType.NotEnoughShardsAvailable, undefined, {
+                AVAILABLE: availableCount.toString(),
+                REQUIRED: dataShards.toString(),
+            });
+        }
+        try {
+            const uint8Data = new Uint8Array(data);
+            const reedSolomonErasure = await reed_solomon_erasure_wasm_1.ReedSolomonErasure.fromCurrentDirectory();
+            reedSolomonErasure.reconstruct(uint8Data, dataShards, parityShards, shardsAvailable);
+            return Buffer.from(uint8Data.subarray(0, shardSize * dataShards));
+        }
+        catch (error) {
+            throw new suite_core_lib_1.FecError(suite_core_lib_1.FecErrorType.FecDecodingFailed, undefined, {
+                ERROR: error instanceof Error ? error.message : 'Unknown error',
+            });
+        }
+    }
+    /**
+     * Creates parity data for a file buffer.
+     * @param fileData File data to create parity for
+     * @param parityCount Number of parity shards to create
+     * @param fecConstants FEC constants (defaults to FEC)
+     * @returns Array of parity data objects
+     * @throws {FecError} If parameters are invalid or encoding fails
+     */
+    async createParityData(fileData, parityCount, fecConstants = constants_1.FEC) {
+        if (!fileData || fileData.length === 0) {
+            throw new suite_core_lib_1.FecError(suite_core_lib_1.FecErrorType.DataRequired);
+        }
+        if (parityCount <= 0) {
+            throw new suite_core_lib_1.FecError(suite_core_lib_1.FecErrorType.ParityDataCountMustBePositive);
+        }
+        const shardSize = Math.min(fileData.length, fecConstants.MAX_SHARD_SIZE);
+        const requiredShards = Math.ceil(fileData.length / shardSize);
+        try {
+            const resultParityData = Array(parityCount)
+                .fill(null)
+                .map(() => Buffer.alloc(0));
+            // Process each chunk
+            for (let i = 0; i < requiredShards; i++) {
+                const start = i * shardSize;
+                const end = Math.min(start + shardSize, fileData.length);
+                const chunk = fileData.subarray(start, end);
+                // Pad chunk if necessary
+                const paddedChunk = Buffer.alloc(shardSize);
+                paddedChunk.set(chunk.subarray(0, shardSize));
+                const chunkParity = await this.encode(paddedChunk, shardSize, 1, parityCount, true, fecConstants);
+                // Distribute parity data
+                for (let j = 0; j < parityCount; j++) {
+                    const parityChunk = chunkParity.subarray(j * shardSize, (j + 1) * shardSize);
+                    const combined = Buffer.alloc(resultParityData[j].length + parityChunk.length);
+                    combined.set(resultParityData[j], 0);
+                    combined.set(parityChunk, resultParityData[j].length);
+                    resultParityData[j] = combined;
+                }
+            }
+            return resultParityData.map((data, index) => ({
+                data,
+                index,
+            }));
+        }
+        catch (error) {
+            throw new suite_core_lib_1.FecError(suite_core_lib_1.FecErrorType.FecEncodingFailed, undefined, {
+                ERROR: error instanceof Error ? error.message : 'Unknown error',
+            });
+        }
+    }
+    /**
+     * Recovers file data using parity data. Pass null for corrupted data.
+     * @param corruptedData Corrupted file data or null if completely lost
+     * @param parityData Array of parity data objects
+     * @param originalSize Original file size in bytes
+     * @param fecConstants FEC constants (defaults to FEC)
+     * @returns Recovery result with data and recovery status
+     * @throws {FecError} If parameters are invalid or recovery fails
+     */
+    async recoverFileData(corruptedData, parityData, originalSize, fecConstants = constants_1.FEC) {
+        if (!parityData || parityData.length === 0) {
+            throw new suite_core_lib_1.FecError(suite_core_lib_1.FecErrorType.ParityDataRequired);
+        }
+        if (originalSize <= 0) {
+            throw new suite_core_lib_1.FecError(suite_core_lib_1.FecErrorType.InvalidDataLength);
+        }
+        try {
+            const shardSize = Math.min(originalSize, fecConstants.MAX_SHARD_SIZE);
+            const requiredShards = Math.ceil(originalSize / shardSize);
+            let recoveredData = Buffer.alloc(0);
+            let parityUsed = false;
+            // Recover each shard
+            for (let i = 0; i < requiredShards; i++) {
+                const start = i * shardSize;
+                const end = Math.min(start + shardSize, originalSize);
+                const chunkSize = end - start;
+                // Use corrupted data if available, otherwise create placeholder
+                const corruptedShard = corruptedData
+                    ? corruptedData.subarray(start, Math.min(end, corruptedData.length))
+                    : Buffer.alloc(0);
+                const parityChunks = parityData.map((parity) => parity.data.subarray(i * shardSize, (i + 1) * shardSize));
+                const hasDataShard = corruptedShard.length > 0;
+                const paddedCorruptedShard = Buffer.alloc(shardSize);
+                if (hasDataShard) {
+                    paddedCorruptedShard.set(corruptedShard.subarray(0, Math.min(shardSize, corruptedShard.length)));
+                }
+                let shardIsHealthy = false;
+                if (hasDataShard) {
+                    const regeneratedParity = await this.encode(paddedCorruptedShard, shardSize, 1, parityData.length, true, fecConstants);
+                    shardIsHealthy = parityChunks.every((parityChunk, index) => parityChunk.equals(Uint8Array.from(regeneratedParity.subarray(index * shardSize, (index + 1) * shardSize))));
+                }
+                if (shardIsHealthy) {
+                    const actualShard = Buffer.from(paddedCorruptedShard.subarray(0, chunkSize));
+                    const combinedRecovered = Buffer.alloc(recoveredData.length + actualShard.length);
+                    combinedRecovered.set(recoveredData, 0);
+                    combinedRecovered.set(actualShard, recoveredData.length);
+                    recoveredData = combinedRecovered;
+                    continue;
+                }
+                // Mark data shard as missing and attempt recovery using parity
+                parityUsed = true;
+                const shardData = Buffer.alloc((1 + parityData.length) * shardSize);
+                shardData.set(paddedCorruptedShard, 0);
+                parityChunks.forEach((chunk, index) => {
+                    shardData.set(chunk, (index + 1) * shardSize);
+                });
+                const availableShards = [false, ...Array(parityData.length).fill(true)];
+                const recoveredShard = await this.decode(shardData, shardSize, 1, parityData.length, availableShards);
+                const actualShard = recoveredShard.subarray(0, chunkSize);
+                const combinedRecovered = Buffer.alloc(recoveredData.length + actualShard.length);
+                combinedRecovered.set(recoveredData, 0);
+                combinedRecovered.set(actualShard, recoveredData.length);
+                recoveredData = combinedRecovered;
+            }
+            return {
+                data: recoveredData,
+                recovered: parityUsed || corruptedData === null,
+            };
+        }
+        catch (error) {
+            throw new suite_core_lib_1.FecError(suite_core_lib_1.FecErrorType.FecDecodingFailed, undefined, {
+                ERROR: error instanceof Error ? error.message : 'Unknown error',
+            });
+        }
+    }
+    /**
+     * Verifies file integrity using parity data.
+     * @param fileData File data to verify
+     * @param parityData Array of parity data objects
+     * @returns True if file integrity is verified, false otherwise
+     */
+    async verifyFileIntegrity(fileData, parityData) {
+        try {
+            const regeneratedParity = await this.createParityData(fileData, parityData.length);
+            return parityData.every((original, index) => Buffer.compare(new Uint8Array(original.data), new Uint8Array(regeneratedParity[index].data)) === 0);
+        }
+        catch {
+            return false;
+        }
+    }
+}
+exports.FecService = FecService;
+//# sourceMappingURL=fec.js.map

package/src/services/fec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fec.js","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite/src/services/fec.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAEH,oEAAyE;AACzE,mFAAyE;AACzE,4CAAmC;AAoCnC,MAAa,UAAU;IACrB;;;;;;;;;;OAUG;IACI,KAAK,CAAC,MAAM,CACjB,IAAY,EACZ,SAAiB,EACjB,UAAkB,EAClB,YAAoB,EACpB,OAAgB,EAChB,eAA2B,eAAG;QAE9B,sBAAsB;QACtB,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC/B,MAAM,IAAI,yBAAQ,CAAC,6BAAY,CAAC,YAAY,CAAC,CAAC;QAChD,CAAC;QAED,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,GAAG,UAAU,EAAE,CAAC;YAC3C,MAAM,IAAI,yBAAQ,CAAC,6BAAY,CAAC,iBAAiB,EAAE,SAAS,EAAE;gBAC5D,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE;gBAC9B,QAAQ,EAAE,CAAC,SAAS,GAAG,UAAU,CAAC,CAAC,QAAQ,EAAE;aAC9C,CAAC,CAAC;QACL,CAAC;QAED,IAAI,SAAS,GAAG,YAAY,CAAC,cAAc,EAAE,CAAC;YAC5C,MAAM,IAAI,yBAAQ,CAAC,6BAAY,CAAC,uBAAuB,EAAE,SAAS,EAAE;gBAClE,IAAI,EAAE,SAAS,CAAC,QAAQ,EAAE;gBAC1B,OAAO,EAAE,YAAY,CAAC,cAAc,CAAC,QAAQ,EAAE;aAChD,CAAC,CAAC;QACL,CAAC;QAED,IAAI,UAAU,IAAI,CAAC,IAAI,YAAY,IAAI,CAAC,EAAE,CAAC;YACzC,MAAM,IAAI,yBAAQ,CAAC,6BAAY,CAAC,kBAAkB,CAAC,CAAC;QACtD,CAAC;QAED,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,SAAS,GAAG,CAAC,UAAU,GAAG,YAAY,CAAC,CAAC,CAAC;YACvE,MAAM,CAAC,GAAG,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;YAEjC,WAAW;YACX,MAAM,kBAAkB,GACtB,MAAM,8CAAkB,CAAC,oBAAoB,EAAE,CAAC;YAClD,kBAAkB,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,YAAY,CAAC,CAAC;YAE5D,OAAO,OAAO;gBACZ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,GAAG,UAAU,CAAC,CAAC;gBACtD,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC1B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,yBAAQ,CAAC,6BAAY,CAAC,iBAAiB,EAAE,SAAS,EAAE;gBAC5D,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe;aAChE,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED;;;;;;;;;OASG;IACI,KAAK,CAAC,MAAM,CACjB,IAAY,EACZ,SAAiB,EACjB,UAAkB,EAClB,YAAoB,EACpB,eAA0B;QAE1B,sBAAsB;QACtB,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC/B,MAAM,IAAI,yBAAQ,CAAC,6BAAY,CAAC,YAAY,CAAC,CAAC;QAChD,CAAC;QAED,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,GAAG,CAAC,UAAU,GAAG,YAAY,CAAC,EAAE,CAAC;YAC5D,MAAM,IAAI,yBAAQ,CAAC,6BAAY,CAAC,iBAAiB,EAAE,SAAS,EAAE;gBAC5D,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE;gBAC9B,QAAQ,EAAE,CAAC,SAAS,GAAG,CAAC,UAAU,GAAG,YAAY,CAAC,CAAC,CAAC,QAAQ,EAAE;aAC/D,CAAC,CAAC;QACL,CAAC;QAED,IACE,CAAC,eAAe;YAChB,eAAe,CAAC,MAAM,KAAK,UAAU,GAAG,YAAY,EACpD,CAAC;YACD,MAAM,IAAI,yBAAQ,CAAC,6BAAY,CAAC,2BAA2B,CAAC,CAAC;QAC/D,CAAC;QAED,MAAM,cAAc,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;QAC/D,IAAI,cAAc,GAAG,UAAU,EAAE,CAAC;YAChC,MAAM,IAAI,yBAAQ,CAAC,6BAAY,CAAC,wBAAwB,EAAE,SAAS,EAAE;gBACnE,SAAS,EAAE,cAAc,CAAC,QAAQ,EAAE;gBACpC,QAAQ,EAAE,UAAU,CAAC,QAAQ,EAAE;aAChC,CAAC,CAAC;QACL,CAAC;QAED,IAAI,CAAC;YACH,MAAM,SAAS,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC;YACvC,MAAM,kBAAkB,GACtB,MAAM,8CAAkB,CAAC,oBAAoB,EAAE,CAAC;YAClD,kBAAkB,CAAC,WAAW,CAC5B,SAAS,EACT,UAAU,EACV,YAAY,EACZ,eAAe,CAChB,CAAC;YACF,OAAO,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,EAAE,SAAS,GAAG,UAAU,CAAC,CAAC,CAAC;QACpE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,yBAAQ,CAAC,6BAAY,CAAC,iBAAiB,EAAE,SAAS,EAAE;gBAC5D,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe;aAChE,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED;;;;;;;OAOG;IACI,KAAK,CAAC,gBAAgB,CAC3B,QAAgB,EAChB,WAAmB,EACnB,eAA2B,eAAG;QAE9B,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvC,MAAM,IAAI,yBAAQ,CAAC,6BAAY,CAAC,YAAY,CAAC,CAAC;QAChD,CAAC;QAED,IAAI,WAAW,IAAI,CAAC,EAAE,CAAC;YACrB,MAAM,IAAI,yBAAQ,CAAC,6BAAY,CAAC,6BAA6B,CAAC,CAAC;QACjE,CAAC;QAED,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC,cAAc,CAAC,CAAC;QACzE,MAAM,cAAc,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;QAE9D,IAAI,CAAC;YACH,MAAM,gBAAgB,GAAa,KAAK,CAAC,WAAW,CAAC;iBAClD,IAAI,CAAC,IAAI,CAAC;iBACV,GAAG,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;YAE9B,qBAAqB;YACrB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,cAAc,EAAE,CAAC,EAAE,EAAE,CAAC;gBACxC,MAAM,KAAK,GAAG,CAAC,GAAG,SAAS,CAAC;gBAC5B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;gBACzD,MAAM,KAAK,GAAG,QAAQ,CAAC,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;gBAE5C,yBAAyB;gBACzB,MAAM,WAAW,GAAG,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;gBAC5C,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC;gBAE9C,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,MAAM,CACnC,WAAW,EACX,SAAS,EACT,CAAC,EACD,WAAW,EACX,IAAI,EACJ,YAAY,CACb,CAAC;gBAEF,yBAAyB;gBACzB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,WAAW,EAAE,CAAC,EAAE,EAAE,CAAC;oBACrC,MAAM,WAAW,GAAG,WAAW,CAAC,QAAQ,CACtC,CAAC,GAAG,SAAS,EACb,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,SAAS,CACpB,CAAC;oBACF,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,CAC3B,gBAAgB,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,WAAW,CAAC,MAAM,CAChD,CAAC;oBACF,QAAQ,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;oBACrC,QAAQ,CAAC,GAAG,CAAC,WAAW,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;oBACtD,gBAAgB,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC;gBACjC,CAAC;YACH,CAAC;YAED,OAAO,gBAAgB,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;gBAC5C,IAAI;gBACJ,KAAK;aACN,CAAC,CAAC,CAAC;QACN,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,yBAAQ,CAAC,6BAAY,CAAC,iBAAiB,EAAE,SAAS,EAAE;gBAC5D,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe;aAChE,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED;;;;;;;;OAQG;IACI,KAAK,CAAC,eAAe,CAC1B,aAA4B,EAC5B,UAAwB,EACxB,YAAoB,EACpB,eAA2B,eAAG;QAE9B,IAAI,CAAC,UAAU,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3C,MAAM,IAAI,yBAAQ,CAAC,6BAAY,CAAC,kBAAkB,CAAC,CAAC;QACtD,CAAC;QAED,IAAI,YAAY,IAAI,CAAC,EAAE,CAAC;YACtB,MAAM,IAAI,yBAAQ,CAAC,6BAAY,CAAC,iBAAiB,CAAC,CAAC;QACrD,CAAC;QAED,IAAI,CAAC;YACH,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,YAAY,CAAC,cAAc,CAAC,CAAC;YACtE,MAAM,cAAc,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,GAAG,SAAS,CAAC,CAAC;YAC3D,IAAI,aAAa,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACpC,IAAI,UAAU,GAAG,KAAK,CAAC;YAEvB,qBAAqB;YACrB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,cAAc,EAAE,CAAC,EAAE,EAAE,CAAC;gBACxC,MAAM,KAAK,GAAG,CAAC,GAAG,SAAS,CAAC;gBAC5B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,SAAS,EAAE,YAAY,CAAC,CAAC;gBACtD,MAAM,SAAS,GAAG,GAAG,GAAG,KAAK,CAAC;gBAE9B,gEAAgE;gBAChE,MAAM,cAAc,GAAG,aAAa;oBAClC,CAAC,CAAC,aAAa,CAAC,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;oBACpE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;gBAEpB,MAAM,YAAY,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAC7C,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,GAAG,SAAS,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,SAAS,CAAC,CACzD,CAAC;gBAEF,MAAM,YAAY,GAAG,cAAc,CAAC,MAAM,GAAG,CAAC,CAAC;gBAC/C,MAAM,oBAAoB,GAAG,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;gBACrD,IAAI,YAAY,EAAE,CAAC;oBACjB,oBAAoB,CAAC,GAAG,CACtB,cAAc,CAAC,QAAQ,CACrB,CAAC,EACD,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,cAAc,CAAC,MAAM,CAAC,CAC3C,CACF,CAAC;gBACJ,CAAC;gBAED,IAAI,cAAc,GAAG,KAAK,CAAC;gBAC3B,IAAI,YAAY,EAAE,CAAC;oBACjB,MAAM,iBAAiB,GAAG,MAAM,IAAI,CAAC,MAAM,CACzC,oBAAoB,EACpB,SAAS,EACT,CAAC,EACD,UAAU,CAAC,MAAM,EACjB,IAAI,EACJ,YAAY,CACb,CAAC;oBAEF,cAAc,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,KAAK,EAAE,EAAE,CACzD,WAAW,CAAC,MAAM,CAChB,UAAU,CAAC,IAAI,CACb,iBAAiB,CAAC,QAAQ,CACxB,KAAK,GAAG,SAAS,EACjB,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,SAAS,CACxB,CACF,CACF,CACF,CAAC;gBACJ,CAAC;gBAED,IAAI,cAAc,EAAE,CAAC;oBACnB,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAC7B,oBAAoB,CAAC,QAAQ,CAAC,CAAC,EAAE,SAAS,CAAC,CAC5C,CAAC;oBACF,MAAM,iBAAiB,GAAG,MAAM,CAAC,KAAK,CACpC,aAAa,CAAC,MAAM,GAAG,WAAW,CAAC,MAAM,CAC1C,CAAC;oBACF,iBAAiB,CAAC,GAAG,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC;oBACxC,iBAAiB,CAAC,GAAG,CAAC,WAAW,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;oBACzD,aAAa,GAAG,iBAAiB,CAAC;oBAClC,SAAS;gBACX,CAAC;gBAED,+DAA+D;gBAC/D,UAAU,GAAG,IAAI,CAAC;gBAClB,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC,CAAC;gBACpE,SAAS,CAAC,GAAG,CAAC,oBAAoB,EAAE,CAAC,CAAC,CAAC;gBACvC,YAAY,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;oBACpC,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;gBAChD,CAAC,CAAC,CAAC;gBAEH,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,GAAG,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;gBAExE,MAAM,cAAc,GAAG,MAAM,IAAI,CAAC,MAAM,CACtC,SAAS,EACT,SAAS,EACT,CAAC,EACD,UAAU,CAAC,MAAM,EACjB,eAAe,CAChB,CAAC;gBAEF,MAAM,WAAW,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;gBAC1D,MAAM,iBAAiB,GAAG,MAAM,CAAC,KAAK,CACpC,aAAa,CAAC,MAAM,GAAG,WAAW,CAAC,MAAM,CAC1C,CAAC;gBACF,iBAAiB,CAAC,GAAG,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC;gBACxC,iBAAiB,CAAC,GAAG,CAAC,WAAW,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;gBACzD,aAAa,GAAG,iBAAiB,CAAC;YACpC,CAAC;YAED,OAAO;gBACL,IAAI,EAAE,aAAa;gBACnB,SAAS,EAAE,UAAU,IAAI,aAAa,KAAK,IAAI;aAChD,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,yBAAQ,CAAC,6BAAY,CAAC,iBAAiB,EAAE,SAAS,EAAE;gBAC5D,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe;aAChE,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACI,KAAK,CAAC,mBAAmB,CAC9B,QAAgB,EAChB,UAAwB;QAExB,IAAI,CAAC;YACH,MAAM,iBAAiB,GAAG,MAAM,IAAI,CAAC,gBAAgB,CACnD,QAAQ,EACR,UAAU,CAAC,MAAM,CAClB,CAAC;YAEF,OAAO,UAAU,CAAC,KAAK,CACrB,CAAC,QAAQ,EAAE,KAAK,EAAE,EAAE,CAClB,MAAM,CAAC,OAAO,CACZ,IAAI,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,EAC7B,IAAI,UAAU,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAC9C,KAAK,CAAC,CACV,CAAC;QACJ,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;CACF;AAlWD,gCAkWC"}

package/src/services/{index.ts → index.d.ts}

@@ -16,3 +16,4 @@ export * from './symmetric';
 export * from './system-user';
 export * from './user';
 export * from './xor';
+//# sourceMappingURL=index.d.ts.map

package/src/services/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite/src/services/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,QAAQ,CAAC;AACvB,cAAc,YAAY,CAAC;AAC3B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,OAAO,CAAC;AACtB,cAAc,qBAAqB,CAAC;AACpC,cAAc,OAAO,CAAC;AACtB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,QAAQ,CAAC;AACvB,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,QAAQ,CAAC;AACvB,cAAc,OAAO,CAAC"}

package/src/services/index.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./backup-code"), exports);
+tslib_1.__exportStar(require("./base"), exports);
+tslib_1.__exportStar(require("./checksum"), exports);
+tslib_1.__exportStar(require("./database-initialization"), exports);
+tslib_1.__exportStar(require("./db-init-cache"), exports);
+tslib_1.__exportStar(require("./direct-login-token"), exports);
+tslib_1.__exportStar(require("./dummy-email-service"), exports);
+tslib_1.__exportStar(require("./fec"), exports);
+tslib_1.__exportStar(require("./fec-usage-example"), exports);
+tslib_1.__exportStar(require("./jwt"), exports);
+tslib_1.__exportStar(require("./key-wrapping"), exports);
+tslib_1.__exportStar(require("./mnemonic"), exports);
+tslib_1.__exportStar(require("./request-user"), exports);
+tslib_1.__exportStar(require("./role"), exports);
+tslib_1.__exportStar(require("./symmetric"), exports);
+tslib_1.__exportStar(require("./system-user"), exports);
+tslib_1.__exportStar(require("./user"), exports);
+tslib_1.__exportStar(require("./xor"), exports);
+//# sourceMappingURL=index.js.map

package/src/services/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite/src/services/index.ts"],"names":[],"mappings":";;;AAAA,wDAA8B;AAC9B,iDAAuB;AACvB,qDAA2B;AAC3B,oEAA0C;AAC1C,0DAAgC;AAChC,+DAAqC;AACrC,gEAAsC;AACtC,gDAAsB;AACtB,8DAAoC;AACpC,gDAAsB;AACtB,yDAA+B;AAC/B,qDAA2B;AAC3B,yDAA+B;AAC/B,iDAAuB;AACvB,sDAA4B;AAC5B,wDAA8B;AAC9B,iDAAuB;AACvB,gDAAsB"}

package/src/services/jwt.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @fileoverview JWT token service for authentication and authorization.
+ * Handles JWT token generation, signing, and verification with role-based access control.
+ * @module services/jwt
+ */
+import { ITokenRole, ITokenUser } from '@digitaldefiance/suite-core-lib';
+import { IUserDocument } from '../documents/user';
+import { IApplication } from '../interfaces/application';
+import { IJwtSignResponse } from '../interfaces/jwt-sign-response';
+import { BaseService } from './base';
+import type { PlatformID } from '@digitaldefiance/node-ecies-lib';
+/**
+ * Service for JWT token operations including generation, signing, and verification.
+ * Integrates with role service to embed user roles in JWT tokens.
+ * @template TID - Platform ID type (defaults to Buffer)
+ * @template TDate - Date type (defaults to Date)
+ * @template TTokenRole - Token role interface type
+ * @template TTokenUser - Token user interface type
+ * @template TApplication - Application interface type
+ * @extends {BaseService<TID, TApplication>}
+ */
+export declare class JwtService<TID extends PlatformID = Buffer, TDate extends Date = Date, TTokenRole extends ITokenRole<TID, TDate> = ITokenRole<TID, TDate>, TTokenUser extends ITokenUser = ITokenUser, TApplication extends IApplication<TID> = IApplication<TID>> extends BaseService<TID, TApplication> {
+    private readonly roleService;
+    /**
+     * Constructor for the JWT service
+     * @param application The application object
+     */
+    constructor(application: TApplication);
+    /**
+     * Sign a JWT token for a user
+     * @param userDoc The user document to sign the token for
+     * @param jwtSecret The secret to sign the token with
+     * @param overrideLanguage Optional language to use for role translations
+     * @returns The signed token
+     */
+    signToken(userDoc: IUserDocument<string, TID>, jwtSecret: string, overrideLanguage?: string): Promise<IJwtSignResponse<TID, TDate, TTokenRole>>;
+    /**
+     * Verify a JWT token and return the user data
+     * @param token The token to verify
+     * @returns The user data
+     * @throws InvalidTokenError
+     */
+    verifyToken(token: string): Promise<TTokenUser | null>;
+}
+//# sourceMappingURL=jwt.d.ts.map

package/src/services/jwt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwt.d.ts","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite/src/services/jwt.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,UAAU,EAEV,UAAU,EACX,MAAM,iCAAiC,CAAC;AAUzC,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAGlD,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAErC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AASlE;;;;;;;;;GASG;AACH,qBAAa,UAAU,CACrB,GAAG,SAAS,UAAU,GAAG,MAAM,EAC/B,KAAK,SAAS,IAAI,GAAG,IAAI,EACzB,UAAU,SAAS,UAAU,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,UAAU,CAAC,GAAG,EAAE,KAAK,CAAC,EAClE,UAAU,SAAS,UAAU,GAAG,UAAU,EAC1C,YAAY,SAAS,YAAY,CAAC,GAAG,CAAC,GAAG,YAAY,CAAC,GAAG,CAAC,CAC1D,SAAQ,WAAW,CAAC,GAAG,EAAE,YAAY,CAAC;IACtC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAsC;IAElE;;;OAGG;gBACS,WAAW,EAAE,YAAY;IAKrC;;;;;;OAMG;IACU,SAAS,CACpB,OAAO,EAAE,aAAa,CAAC,MAAM,EAAE,GAAG,CAAC,EACnC,SAAS,EAAE,MAAM,EACjB,gBAAgB,CAAC,EAAE,MAAM,GACxB,OAAO,CAAC,gBAAgB,CAAC,GAAG,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC;IAgCpD;;;;;OAKG;IACU,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;CAgCpE"}

package/src/services/jwt.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * @fileoverview JWT token service for authentication and authorization.
+ * Handles JWT token generation, signing, and verification with role-based access control.
+ * @module services/jwt
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JwtService = void 0;
+const jsonwebtoken_1 = require("jsonwebtoken");
+const util_1 = require("util");
+const invalid_jwt_token_1 = require("../errors/invalid-jwt-token");
+const token_expired_1 = require("../errors/token-expired");
+const base_1 = require("./base");
+const role_1 = require("./role");
+const verifyAsync = (0, util_1.promisify)(jsonwebtoken_1.verify);
+/**
+ * Service for JWT token operations including generation, signing, and verification.
+ * Integrates with role service to embed user roles in JWT tokens.
+ * @template TID - Platform ID type (defaults to Buffer)
+ * @template TDate - Date type (defaults to Date)
+ * @template TTokenRole - Token role interface type
+ * @template TTokenUser - Token user interface type
+ * @template TApplication - Application interface type
+ * @extends {BaseService<TID, TApplication>}
+ */
+class JwtService extends base_1.BaseService {
+    roleService;
+    /**
+     * Constructor for the JWT service
+     * @param application The application object
+     */
+    constructor(application) {
+        super(application);
+        this.roleService = new role_1.RoleService(application);
+    }
+    /**
+     * Sign a JWT token for a user
+     * @param userDoc The user document to sign the token for
+     * @param jwtSecret The secret to sign the token with
+     * @param overrideLanguage Optional language to use for role translations
+     * @returns The signed token
+     */
+    async signToken(userDoc, jwtSecret, overrideLanguage) {
+        // look for roles the user is a member of (the role contains the user id in the user's roles array)
+        const roles = await this.roleService.getUserRoles(userDoc._id);
+        const tokenRoles = this.roleService.rolesToTokenRoles(roles, overrideLanguage);
+        const tokenRoleDTOs = tokenRoles.map((role) => role_1.RoleService.roleToRoleDTO(role));
+        const roleTranslatedNames = tokenRoles.map((role) => role.translatedName);
+        const roleNames = tokenRoles.map((role) => role.name);
+        const tokenUser = {
+            userId: userDoc._id.toString(),
+            roles: tokenRoleDTOs,
+        };
+        // amazonq-ignore-next-line false positive
+        const token = (0, jsonwebtoken_1.sign)(tokenUser, jwtSecret, {
+            algorithm: this.application.constants.JWT.ALGORITHM,
+            allowInsecureKeySizes: false,
+            expiresIn: this.application.constants.JWT.EXPIRATION_SEC,
+        });
+        return {
+            token,
+            tokenUser,
+            roleNames,
+            roleTranslatedNames,
+            roles: tokenRoles,
+            roleDTOs: tokenRoleDTOs,
+        };
+    }
+    /**
+     * Verify a JWT token and return the user data
+     * @param token The token to verify
+     * @returns The user data
+     * @throws InvalidTokenError
+     */
+    async verifyToken(token) {
+        try {
+            const decoded = (await verifyAsync(token, this.application.environment.jwtSecret, {
+                algorithms: [this.application.constants.JWT.ALGORITHM],
+            }));
+            if (typeof decoded === 'object' &&
+                decoded !== null &&
+                'userId' in decoded &&
+                'roles' in decoded) {
+                return {
+                    userId: decoded['userId'],
+                    roles: decoded['roles'],
+                };
+            }
+            else {
+                return null;
+            }
+        }
+        catch (err) {
+            if (err instanceof jsonwebtoken_1.TokenExpiredError) {
+                throw new token_expired_1.TokenExpiredError();
+            }
+            else if (err instanceof jsonwebtoken_1.JsonWebTokenError) {
+                throw err;
+            }
+            throw new invalid_jwt_token_1.InvalidJwtTokenError();
+        }
+    }
+}
+exports.JwtService = JwtService;
+//# sourceMappingURL=jwt.js.map

package/src/services/jwt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwt.js","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite/src/services/jwt.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAOH,+CAOsB;AACtB,+BAAiC;AAEjC,mEAAmE;AACnE,2DAA4D;AAG5D,iCAAqC;AACrC,iCAAqC;AAGrC,MAAM,WAAW,GAAG,IAAA,gBAAS,EAK3B,qBAAM,CAAC,CAAC;AAEV;;;;;;;;;GASG;AACH,MAAa,UAMX,SAAQ,kBAA8B;IACrB,WAAW,CAAsC;IAElE;;;OAGG;IACH,YAAY,WAAyB;QACnC,KAAK,CAAC,WAAW,CAAC,CAAC;QACnB,IAAI,CAAC,WAAW,GAAG,IAAI,kBAAW,CAAyB,WAAW,CAAC,CAAC;IAC1E,CAAC;IAED;;;;;;OAMG;IACI,KAAK,CAAC,SAAS,CACpB,OAAmC,EACnC,SAAiB,EACjB,gBAAyB;QAEzB,mGAAmG;QACnG,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,YAAY,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC/D,MAAM,UAAU,GAAsB,IAAI,CAAC,WAAW,CAAC,iBAAiB,CACtE,KAAK,EACL,gBAAgB,CACjB,CAAC;QACF,MAAM,aAAa,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAC5C,kBAAW,CAAC,aAAa,CAAa,IAAI,CAAC,CAC5C,CAAC;QACF,MAAM,mBAAmB,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QAC1E,MAAM,SAAS,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtD,MAAM,SAAS,GAAG;YAChB,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE;YAC9B,KAAK,EAAE,aAAa;SACP,CAAC;QAChB,0CAA0C;QAC1C,MAAM,KAAK,GAAG,IAAA,mBAAI,EAAC,SAAS,EAAE,SAAS,EAAE;YACvC,SAAS,EAAE,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS;YACnD,qBAAqB,EAAE,KAAK;YAC5B,SAAS,EAAE,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,GAAG,CAAC,cAAc;SACzD,CAAC,CAAC;QACH,OAAO;YACL,KAAK;YACL,SAAS;YACT,SAAS;YACT,mBAAmB;YACnB,KAAK,EAAE,UAAU;YACjB,QAAQ,EAAE,aAAa;SACxB,CAAC;IACJ,CAAC;IAED;;;;;OAKG;IACI,KAAK,CAAC,WAAW,CAAC,KAAa;QACpC,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,CAAC,MAAM,WAAW,CAChC,KAAK,EACL,IAAI,CAAC,WAAW,CAAC,WAAW,CAAC,SAAS,EACtC;gBACE,UAAU,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC;aACvD,CACF,CAAe,CAAC;YAEjB,IACE,OAAO,OAAO,KAAK,QAAQ;gBAC3B,OAAO,KAAK,IAAI;gBAChB,QAAQ,IAAI,OAAO;gBACnB,OAAO,IAAI,OAAO,EAClB,CAAC;gBACD,OAAO;oBACL,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAW;oBACnC,KAAK,EAAE,OAAO,CAAC,OAAO,CAAoB;iBAC7B,CAAC;YAClB,CAAC;iBAAM,CAAC;gBACN,OAAO,IAAI,CAAC;YACd,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,gCAAoB,EAAE,CAAC;gBACxC,MAAM,IAAI,iCAAiB,EAAE,CAAC;YAChC,CAAC;iBAAM,IAAI,GAAG,YAAY,gCAAiB,EAAE,CAAC;gBAC5C,MAAM,GAAG,CAAC;YACZ,CAAC;YACD,MAAM,IAAI,wCAAoB,EAAE,CAAC;QACnC,CAAC;IACH,CAAC;CACF;AAnGD,gCAmGC"}

package/src/services/key-wrapping.d.ts

@@ -0,0 +1,139 @@
+/**
+ * @fileoverview Service for password-based key wrapping and unwrapping using AES-256-GCM.
+ * Provides secure master key management, password changes, and generic secret wrapping.
+ * @module services/key-wrapping
+ */
+import { SecureBuffer, SecureString } from '@digitaldefiance/ecies-lib';
+import { IConstants } from '@digitaldefiance/node-ecies-lib';
+/**
+ * Represents a password-wrapped master key with all encryption metadata.
+ */
+export interface WrappedKey {
+    /** Hex-encoded salt for PBKDF2 key derivation */
+    salt: string;
+    /** Hex-encoded initialization vector for AES-GCM */
+    iv: string;
+    /** Hex-encoded authentication tag for AES-GCM */
+    authTag: string;
+    /** Hex-encoded encrypted master key */
+    encryptedMasterKey: string;
+    /** Number of PBKDF2 iterations used */
+    iterations: number;
+}
+/**
+ * Generic password-wrapped secret payload with encryption metadata.
+ */
+export interface PasswordWrappedSecret {
+    /** Hex-encoded salt for PBKDF2 key derivation */
+    salt: string;
+    /** Hex-encoded initialization vector for AES-GCM */
+    iv: string;
+    /** Hex-encoded authentication tag for AES-GCM */
+    authTag: string;
+    /** Hex-encoded encrypted secret data */
+    ciphertext: string;
+    /** Number of PBKDF2 iterations used */
+    iterations: number;
+}
+/**
+ * Service for password-based key wrapping and unwrapping operations.
+ * Provides secure master key management with AES-256-GCM encryption and PBKDF2 key derivation.
+ * Supports both synchronous and asynchronous operations with deduplication for concurrent requests.
+ */
+export declare class KeyWrappingService {
+    /**
+     * In-flight de-duplication map to share PBKDF2 work across concurrent identical requests.
+     * Stores promises of base64-encoded master key bytes for sharing across callers.
+     * @private
+     */
+    private static inFlightUnwraps;
+    /**
+     * Generates a new random master key and wraps it with the user's password.
+     * @param password User's password for wrapping
+     * @param constants Configuration constants (defaults to Constants)
+     * @returns Object containing the master key and wrapped key metadata
+     * @throws {InvalidNewPasswordError} If password doesn't meet requirements
+     */
+    wrapNewMasterKey(password: SecureString, constants?: IConstants): {
+        masterKey: SecureBuffer;
+        wrappedKey: WrappedKey;
+    };
+    /**
+     * Wraps an existing master key with a password-derived key using AES-256-GCM.
+     * @param masterKey Master key to wrap
+     * @param password User's password for wrapping
+     * @param constants Configuration constants (defaults to Constants)
+     * @returns Wrapped key metadata including salt, IV, auth tag, and encrypted key
+     * @throws {InvalidNewPasswordError} If password doesn't meet requirements
+     */
+    wrapMasterKey(masterKey: SecureBuffer, password: SecureString, constants?: IConstants): WrappedKey;
+    /**
+     * Unwraps a master key using the user's password (synchronous).
+     * @param wrappedKey Wrapped key metadata
+     * @param password User's password for unwrapping
+     * @param constants Configuration constants (defaults to Constants)
+     * @returns Unwrapped master key in a SecureBuffer
+     * @throws {InvalidPasswordError} If password is incorrect or decryption fails
+     */
+    unwrapMasterKey(wrappedKey: WrappedKey, password: SecureString, constants?: IConstants): SecureBuffer;
+    /**
+     * Async version of unwrapMasterKey that uses libuv threadpool via crypto.pbkdf2
+     * to avoid blocking the event loop during password verification.
+     * @param wrappedKey Wrapped key metadata
+     * @param password User's password (SecureString or raw string)
+     * @param constants Configuration constants (defaults to Constants)
+     * @returns Promise resolving to unwrapped master key in a SecureBuffer
+     * @throws {InvalidPasswordError} If password is incorrect or decryption fails
+     */
+    unwrapMasterKeyAsync(wrappedKey: WrappedKey, password: SecureString | string, constants?: IConstants): Promise<SecureBuffer>;
+    /**
+     * Deduplicated async unwrap that coalesces concurrent identical PBKDF2 operations.
+     * Keyed by salt + iterations + password hash to avoid redundant computation.
+     * @param wrappedKey Wrapped key metadata
+     * @param password User's password as string
+     * @param constants Configuration constants (defaults to Constants)
+     * @returns Promise resolving to unwrapped master key in a SecureBuffer
+     * @throws {InvalidPasswordError} If password is incorrect or decryption fails
+     */
+    unwrapMasterKeyAsyncDedup(wrappedKey: WrappedKey, password: string, constants?: IConstants): Promise<SecureBuffer>;
+    /**
+     * Changes password by re-wrapping the master key with a new password.
+     * @param wrappedKey Current wrapped key metadata
+     * @param oldPassword Current password
+     * @param newPassword New password
+     * @param constants Configuration constants (defaults to Constants)
+     * @returns New wrapped key metadata
+     * @throws {InvalidPasswordError} If old password is incorrect
+     * @throws {InvalidNewPasswordError} If new password doesn't meet requirements
+     */
+    changePassword(wrappedKey: WrappedKey, oldPassword: SecureString, newPassword: SecureString, constants?: IConstants): WrappedKey;
+    /**
+     * Wraps arbitrary secret bytes with a password-derived key using AES-256-GCM.
+     * @param secret Secret data to wrap
+     * @param password User's password for wrapping
+     * @param constants Configuration constants (defaults to Constants)
+     * @returns Password-wrapped secret metadata
+     * @throws {InvalidNewPasswordError} If password doesn't meet requirements
+     */
+    wrapSecret(secret: SecureBuffer, password: SecureString, constants?: IConstants): PasswordWrappedSecret;
+    /**
+     * Unwraps a password-wrapped secret (synchronous).
+     * @param wrapped Password-wrapped secret metadata
+     * @param password User's password for unwrapping
+     * @param constants Configuration constants (defaults to Constants)
+     * @returns Unwrapped secret in a SecureBuffer
+     * @throws {InvalidPasswordError} If password is incorrect or decryption fails
+     */
+    unwrapSecret(wrapped: PasswordWrappedSecret, password: SecureString, constants?: IConstants): SecureBuffer;
+    /**
+     * Unwraps a password-wrapped secret using async PBKDF2 to avoid blocking.
+     * @param wrapped Password-wrapped secret metadata
+     * @param password User's password (SecureString or raw string)
+     * @param constants Configuration constants (defaults to Constants)
+     * @returns Promise resolving to unwrapped secret in a SecureBuffer
+     * @throws {InvalidPasswordError} If password is incorrect or decryption fails
+     * @throws {Error} If password is undefined, null, or invalid type
+     */
+    unwrapSecretAsync(wrapped: PasswordWrappedSecret, password: SecureString | string, constants?: IConstants): Promise<SecureBuffer>;
+}
+//# sourceMappingURL=key-wrapping.d.ts.map

package/src/services/key-wrapping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-wrapping.d.ts","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite/src/services/key-wrapping.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AACxE,OAAO,EAEL,UAAU,EAEX,MAAM,iCAAiC,CAAC;AAkBzC;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,EAAE,EAAE,MAAM,CAAC;IACX,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,EAAE,EAAE,MAAM,CAAC;IACX,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,qBAAa,kBAAkB;IAC7B;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,eAAe,CAA2C;IAEzE;;;;;;OAMG;IACI,gBAAgB,CACrB,QAAQ,EAAE,YAAY,EACtB,SAAS,GAAE,UAAsB,GAChC;QACD,SAAS,EAAE,YAAY,CAAC;QACxB,UAAU,EAAE,UAAU,CAAC;KACxB;IAQD;;;;;;;OAOG;IACI,aAAa,CAClB,SAAS,EAAE,YAAY,EACvB,QAAQ,EAAE,YAAY,EACtB,SAAS,GAAE,UAAsB,GAChC,UAAU;IAyCb;;;;;;;OAOG;IACI,eAAe,CACpB,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,YAAY,EACtB,SAAS,GAAE,UAAsB,GAChC,YAAY;IAuCf;;;;;;;;OAQG;IACU,oBAAoB,CAC/B,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,YAAY,GAAG,MAAM,EAC/B,SAAS,GAAE,UAAsB,GAChC,OAAO,CAAC,YAAY,CAAC;IA6DxB;;;;;;;;OAQG;IACU,yBAAyB,CACpC,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,MAAM,EAChB,SAAS,GAAE,UAAsB,GAChC,OAAO,CAAC,YAAY,CAAC;IAuCxB;;;;;;;;;OASG;IACI,cAAc,CACnB,UAAU,EAAE,UAAU,EACtB,WAAW,EAAE,YAAY,EACzB,WAAW,EAAE,YAAY,EACzB,SAAS,GAAE,UAAsB,GAChC,UAAU;IAYb;;;;;;;OAOG;IACI,UAAU,CACf,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,YAAY,EACtB,SAAS,GAAE,UAAsB,GAChC,qBAAqB;IAuCxB;;;;;;;OAOG;IACI,YAAY,CACjB,OAAO,EAAE,qBAAqB,EAC9B,QAAQ,EAAE,YAAY,EACtB,SAAS,GAAE,UAAsB,GAChC,YAAY;IAoCf;;;;;;;;OAQG;IACU,iBAAiB,CAC5B,OAAO,EAAE,qBAAqB,EAC9B,QAAQ,EAAE,YAAY,GAAG,MAAM,EAC/B,SAAS,GAAE,UAAsB,GAChC,OAAO,CAAC,YAAY,CAAC;CA+DzB"}