@brightchain/brightchain-lib 0.21.1 → 0.23.0

package/src/lib/blocks/tcbl/tcbl.d.ts

@@ -0,0 +1,190 @@
+/**
+ * @fileoverview TarballConstituentBlockListBlock — a CBL that bundles
+ * multiple file/data entries into a single archive with a manifest.
+ *
+ * The TCBL extends {@link ConstituentBlockListBlock} and adds:
+ * - Structured block header validation (magic prefix + TarballCBL type byte)
+ * - A lazily-deserialized, cached manifest describing all contained entries
+ * - A compression flag indicating whether the payload is bzip2-compressed
+ *
+ * The manifest and compression flag live in the *reconstructed payload*
+ * (the data that the CBL addresses point to). The builder/reader sets
+ * this payload via {@link setPayloadData} after assembling or
+ * reconstructing the constituent blocks.
+ *
+ * Payload format (after reconstruction):
+ *   Byte 0:   compression flag (0x00 = uncompressed, 0x01 = bzip2)
+ *   Bytes 1+: serialized manifest (possibly bzip2-compressed)
+ *
+ * ## Encrypted TCBL Detection (Req 6.6)
+ *
+ * Encrypted TCBLs are stored as {@link EncryptedBlock} instances with
+ * `BlockType.EncryptedTarballConstituentBlockListBlock`. The encrypted
+ * block wraps the TCBL data using the standard ECIES encryption pattern
+ * (same as CBL, ExtendedCBL, and VCBL).
+ *
+ * After decryption, the inner data is a plain TCBL that can be detected
+ * via {@link isTarballCblData} (checks the 0xBC + 0x07 header bytes) and
+ * instantiated as a `TarballConstituentBlockListBlock`. The CBL stores
+ * (`MemoryCBLStore`, `DiskCBLStore`) perform this detection automatically
+ * when retrieving blocks.
+ *
+ * @typeParam TID - Platform ID type for frontend/backend DTO compatibility
+ *
+ * @see Requirement 6 (Transparent Detection and Polymorphic Handling)
+ * @see Requirement 2 (TCBL Manifest Structure)
+ * @see Requirement 7 (Whole-Archive Compression)
+ * @see Requirement 10 (Validation and Error Handling)
+ */
+import { Member, PlatformID } from '@digitaldefiance/ecies-lib';
+import { BlockSize } from '../../enumerations/blockSize';
+import { ICBLServices } from '../../interfaces/services/cblServices';
+import { ITcblEntryDescriptor } from '../../interfaces/tcbl/tcblEntryDescriptor';
+import { ITcblManifest } from '../../interfaces/tcbl/tcblManifest';
+import { ConstituentBlockListBlock } from '../cbl';
+/**
+ * A Tarball Constituent Block List block — an archive container that
+ * bundles multiple file/data entries into a single CBL structure with
+ * a manifest.
+ *
+ * Extends {@link ConstituentBlockListBlock} so that any code accepting
+ * a CBL reference can also accept a TCBL reference (Req 6.3, 6.5).
+ *
+ * @typeParam TID - Platform ID type (defaults to `Uint8Array`)
+ *
+ * @see Requirement 6.3 — extends ConstituentBlockListBlock
+ * @see Requirement 6.1 — header uses magic prefix + TarballCBL type byte
+ * @see Requirement 10.1 — validates structured block header during construction
+ */
+export declare class TarballConstituentBlockListBlock<TID extends PlatformID = Uint8Array> extends ConstituentBlockListBlock<TID> {
+    /** Cached deserialized manifest (lazy, populated on first access). */
+    private _manifest?;
+    /** Cached compression flag (set when payload data is provided). */
+    private _isCompressed?;
+    /** Reconstructed payload data set by the builder/reader. */
+    private _payloadData?;
+    /**
+     * Create a new TCBL block.
+     *
+     * @param data - Raw CBL data (header + addresses, optionally padded)
+     * @param creator - The creator of the CBL
+     * @param blockSize - Optional block size for signature validation
+     * @param services - Optional injected CBL services for dependency injection
+     *
+     * @throws {TcblError} with {@link TcblErrorType.InvalidHeader} if the
+     *   structured block header does not identify this as a TarballCBL
+     *
+     * @see Requirement 6.1, 10.1
+     */
+    constructor(data: Uint8Array, creator: Member<TID>, blockSize?: BlockSize, services?: ICBLServices<TID>);
+    /**
+     * Validate that the structured block header identifies this block as
+     * a TarballCBL (magic prefix 0xBC followed by type byte 0x07).
+     *
+     * @throws {TcblError} with {@link TcblErrorType.InvalidHeader}
+     *
+     * @see Requirement 6.1, 10.1, 10.3
+     */
+    private validateTcblHeader;
+    /**
+     * Set the reconstructed payload data.
+     *
+     * Called by the builder after assembling the archive or by the reader
+     * after reconstructing the payload from the CBL's constituent blocks.
+     *
+     * Payload format:
+     *   Byte 0:   compression flag (0x00 = uncompressed, 0x01 = compressed)
+     *   Bytes 1+: serialized manifest data (possibly bzip2-compressed)
+     *
+     * @param payloadData - The reconstructed payload bytes
+     *
+     * @throws {TcblError} with {@link TcblErrorType.InvalidHeader} if
+     *   the payload is empty or the compression flag is invalid
+     *
+     * @see Requirement 7.3
+     */
+    setPayloadData(payloadData: Uint8Array): void;
+    /**
+     * Whether the archive payload is bzip2-compressed.
+     *
+     * @throws {TcblError} with {@link TcblErrorType.InvalidHeader} if
+     *   payload data has not been set via {@link setPayloadData}
+     *
+     * @see Requirement 7.3
+     */
+    get isCompressed(): boolean;
+    /**
+     * The TCBL manifest — lazily deserialized and cached on first access.
+     *
+     * The manifest is parsed from the payload data (bytes after the
+     * compression flag). The checksum embedded in the manifest is
+     * validated during deserialization by {@link TcblManifestSerializer}.
+     *
+     * @throws {TcblError} with {@link TcblErrorType.InvalidHeader} if
+     *   payload data has not been set
+     * @throws {TcblError} with {@link TcblErrorType.ManifestCorrupted} or
+     *   {@link TcblErrorType.ManifestTruncated} if deserialization fails
+     *
+     * @see Requirement 2, 10.2
+     */
+    get manifest(): ITcblManifest;
+    /**
+     * The entry descriptors from the manifest.
+     *
+     * @see Requirement 5.4
+     */
+    get entries(): ITcblEntryDescriptor[];
+    /**
+     * Synchronous validation including TCBL-specific checks.
+     *
+     * Validates:
+     * 1. Base CBL structure (via `super.validateSync()`)
+     * 2. Structured block header (magic prefix + TarballCBL type byte)
+     * 3. Manifest entry count consistency (if manifest has been loaded)
+     *
+     * @throws {TcblError} with {@link TcblErrorType.ManifestCountMismatch}
+     *   if the manifest's `entryCount` does not match `entries.length`
+     *
+     * @see Requirement 10.4
+     */
+    validateSync(): void;
+    /**
+     * Asynchronous validation including TCBL-specific checks.
+     *
+     * @see Requirement 10.4
+     */
+    validateAsync(): Promise<void>;
+    /**
+     * Validate that the manifest entry count matches the actual number
+     * of entry descriptors. Only runs if the manifest has already been
+     * loaded (avoids forcing deserialization during validation).
+     *
+     * @throws {TcblError} with {@link TcblErrorType.ManifestCountMismatch}
+     *
+     * @see Requirement 10.4
+     */
+    private validateManifestCount;
+}
+/**
+ * Type guard that narrows a {@link ConstituentBlockListBlock} to a
+ * {@link TarballConstituentBlockListBlock}.
+ *
+ * Use this to safely upcast a CBL reference when you need to access
+ * TCBL-specific APIs (manifest, entries, isCompressed).
+ *
+ * @param block - Any CBL instance
+ * @returns `true` if `block` is a `TarballConstituentBlockListBlock`
+ *
+ * @example
+ * ```typescript
+ * const cbl = await cblStore.get(checksum, hydrateGuid);
+ * if (isTcbl(cbl)) {
+ *   // cbl is now typed as TarballConstituentBlockListBlock
+ *   const entries = cbl.entries;
+ * }
+ * ```
+ *
+ * @see Requirement 6.4 — consumer can upcast CBL to TCBL
+ */
+export declare function isTcbl<TID extends PlatformID = Uint8Array>(block: ConstituentBlockListBlock<TID>): block is TarballConstituentBlockListBlock<TID>;
+//# sourceMappingURL=tcbl.d.ts.map

package/src/lib/blocks/tcbl/tcbl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tcbl.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/blocks/tcbl/tcbl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAEhE,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAGzD,OAAO,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAC;AACrE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AACnE,OAAO,EAAE,yBAAyB,EAAE,MAAM,QAAQ,CAAC;AAGnD;;;;;;;;;;;;;GAaG;AACH,qBAAa,gCAAgC,CAC3C,GAAG,SAAS,UAAU,GAAG,UAAU,CACnC,SAAQ,yBAAyB,CAAC,GAAG,CAAC;IACtC,sEAAsE;IACtE,OAAO,CAAC,SAAS,CAAC,CAAgB;IAElC,mEAAmE;IACnE,OAAO,CAAC,aAAa,CAAC,CAAU;IAEhC,4DAA4D;IAC5D,OAAO,CAAC,YAAY,CAAC,CAAa;IAElC;;;;;;;;;;;;OAYG;gBAED,IAAI,EAAE,UAAU,EAChB,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC,EACpB,SAAS,CAAC,EAAE,SAAS,EACrB,QAAQ,CAAC,EAAE,YAAY,CAAC,GAAG,CAAC;IAM9B;;;;;;;OAOG;IACH,OAAO,CAAC,kBAAkB;IA6B1B;;;;;;;;;;;;;;;;OAgBG;IACI,cAAc,CAAC,WAAW,EAAE,UAAU,GAAG,IAAI;IA0BpD;;;;;;;OAOG;IACH,IAAW,YAAY,IAAI,OAAO,CAQjC;IAED;;;;;;;;;;;;;OAaG;IACH,IAAW,QAAQ,IAAI,aAAa,CAenC;IAED;;;;OAIG;IACH,IAAW,OAAO,IAAI,oBAAoB,EAAE,CAE3C;IAED;;;;;;;;;;;;OAYG;IACa,YAAY,IAAI,IAAI;IAMpC;;;;OAIG;IACmB,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAMpD;;;;;;;;OAQG;IACH,OAAO,CAAC,qBAAqB;CAa9B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,MAAM,CAAC,GAAG,SAAS,UAAU,GAAG,UAAU,EACxD,KAAK,EAAE,yBAAyB,CAAC,GAAG,CAAC,GACpC,KAAK,IAAI,gCAAgC,CAAC,GAAG,CAAC,CAEhD"}

package/src/lib/blocks/tcbl/tcbl.js

@@ -0,0 +1,263 @@
+"use strict";
+/**
+ * @fileoverview TarballConstituentBlockListBlock — a CBL that bundles
+ * multiple file/data entries into a single archive with a manifest.
+ *
+ * The TCBL extends {@link ConstituentBlockListBlock} and adds:
+ * - Structured block header validation (magic prefix + TarballCBL type byte)
+ * - A lazily-deserialized, cached manifest describing all contained entries
+ * - A compression flag indicating whether the payload is bzip2-compressed
+ *
+ * The manifest and compression flag live in the *reconstructed payload*
+ * (the data that the CBL addresses point to). The builder/reader sets
+ * this payload via {@link setPayloadData} after assembling or
+ * reconstructing the constituent blocks.
+ *
+ * Payload format (after reconstruction):
+ *   Byte 0:   compression flag (0x00 = uncompressed, 0x01 = bzip2)
+ *   Bytes 1+: serialized manifest (possibly bzip2-compressed)
+ *
+ * ## Encrypted TCBL Detection (Req 6.6)
+ *
+ * Encrypted TCBLs are stored as {@link EncryptedBlock} instances with
+ * `BlockType.EncryptedTarballConstituentBlockListBlock`. The encrypted
+ * block wraps the TCBL data using the standard ECIES encryption pattern
+ * (same as CBL, ExtendedCBL, and VCBL).
+ *
+ * After decryption, the inner data is a plain TCBL that can be detected
+ * via {@link isTarballCblData} (checks the 0xBC + 0x07 header bytes) and
+ * instantiated as a `TarballConstituentBlockListBlock`. The CBL stores
+ * (`MemoryCBLStore`, `DiskCBLStore`) perform this detection automatically
+ * when retrieving blocks.
+ *
+ * @typeParam TID - Platform ID type for frontend/backend DTO compatibility
+ *
+ * @see Requirement 6 (Transparent Detection and Polymorphic Handling)
+ * @see Requirement 2 (TCBL Manifest Structure)
+ * @see Requirement 7 (Whole-Archive Compression)
+ * @see Requirement 10 (Validation and Error Handling)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TarballConstituentBlockListBlock = void 0;
+exports.isTcbl = isTcbl;
+const constants_1 = require("../../constants");
+const tcblErrorType_1 = require("../../enumerations/tcblErrorType");
+const tcblError_1 = require("../../errors/tcblError");
+const cbl_1 = require("../cbl");
+const manifestSerializer_1 = require("./manifestSerializer");
+/**
+ * A Tarball Constituent Block List block — an archive container that
+ * bundles multiple file/data entries into a single CBL structure with
+ * a manifest.
+ *
+ * Extends {@link ConstituentBlockListBlock} so that any code accepting
+ * a CBL reference can also accept a TCBL reference (Req 6.3, 6.5).
+ *
+ * @typeParam TID - Platform ID type (defaults to `Uint8Array`)
+ *
+ * @see Requirement 6.3 — extends ConstituentBlockListBlock
+ * @see Requirement 6.1 — header uses magic prefix + TarballCBL type byte
+ * @see Requirement 10.1 — validates structured block header during construction
+ */
+class TarballConstituentBlockListBlock extends cbl_1.ConstituentBlockListBlock {
+    /**
+     * Create a new TCBL block.
+     *
+     * @param data - Raw CBL data (header + addresses, optionally padded)
+     * @param creator - The creator of the CBL
+     * @param blockSize - Optional block size for signature validation
+     * @param services - Optional injected CBL services for dependency injection
+     *
+     * @throws {TcblError} with {@link TcblErrorType.InvalidHeader} if the
+     *   structured block header does not identify this as a TarballCBL
+     *
+     * @see Requirement 6.1, 10.1
+     */
+    constructor(data, creator, blockSize, services) {
+        super(data, creator, blockSize, services);
+        this.validateTcblHeader();
+    }
+    /**
+     * Validate that the structured block header identifies this block as
+     * a TarballCBL (magic prefix 0xBC followed by type byte 0x07).
+     *
+     * @throws {TcblError} with {@link TcblErrorType.InvalidHeader}
+     *
+     * @see Requirement 6.1, 10.1, 10.3
+     */
+    validateTcblHeader() {
+        if (this._data.length < 2) {
+            throw new tcblError_1.TcblError(tcblErrorType_1.TcblErrorType.InvalidHeader, new Map([['reason', 'data too short for structured block header']]));
+        }
+        if (this._data[0] !== constants_1.BLOCK_HEADER.MAGIC_PREFIX) {
+            throw new tcblError_1.TcblError(tcblErrorType_1.TcblErrorType.InvalidHeader, new Map([
+                ['reason', 'missing magic prefix'],
+                ['expected', `0x${constants_1.BLOCK_HEADER.MAGIC_PREFIX.toString(16)}`],
+                ['actual', `0x${this._data[0].toString(16)}`],
+            ]));
+        }
+        if (this._data[1] !== constants_1.StructuredBlockType.TarballCBL) {
+            throw new tcblError_1.TcblError(tcblErrorType_1.TcblErrorType.InvalidHeader, new Map([
+                ['reason', 'wrong structured block type'],
+                ['expected', `0x${constants_1.StructuredBlockType.TarballCBL.toString(16)}`],
+                ['actual', `0x${this._data[1].toString(16)}`],
+            ]));
+        }
+    }
+    /**
+     * Set the reconstructed payload data.
+     *
+     * Called by the builder after assembling the archive or by the reader
+     * after reconstructing the payload from the CBL's constituent blocks.
+     *
+     * Payload format:
+     *   Byte 0:   compression flag (0x00 = uncompressed, 0x01 = compressed)
+     *   Bytes 1+: serialized manifest data (possibly bzip2-compressed)
+     *
+     * @param payloadData - The reconstructed payload bytes
+     *
+     * @throws {TcblError} with {@link TcblErrorType.InvalidHeader} if
+     *   the payload is empty or the compression flag is invalid
+     *
+     * @see Requirement 7.3
+     */
+    setPayloadData(payloadData) {
+        if (payloadData.length < 1) {
+            throw new tcblError_1.TcblError(tcblErrorType_1.TcblErrorType.InvalidHeader, new Map([['reason', 'payload data is empty']]));
+        }
+        const compressionByte = payloadData[0];
+        if (compressionByte !== 0x00 && compressionByte !== 0x01) {
+            throw new tcblError_1.TcblError(tcblErrorType_1.TcblErrorType.InvalidHeader, new Map([
+                ['reason', 'invalid compression flag'],
+                ['expected', '0x00 or 0x01'],
+                ['actual', `0x${compressionByte.toString(16)}`],
+            ]));
+        }
+        this._isCompressed = compressionByte === 0x01;
+        this._payloadData = payloadData;
+        // Invalidate cached manifest so it is re-parsed from the new payload
+        this._manifest = undefined;
+    }
+    /**
+     * Whether the archive payload is bzip2-compressed.
+     *
+     * @throws {TcblError} with {@link TcblErrorType.InvalidHeader} if
+     *   payload data has not been set via {@link setPayloadData}
+     *
+     * @see Requirement 7.3
+     */
+    get isCompressed() {
+        if (this._isCompressed === undefined) {
+            throw new tcblError_1.TcblError(tcblErrorType_1.TcblErrorType.InvalidHeader, new Map([['reason', 'payload data not loaded; call setPayloadData()']]));
+        }
+        return this._isCompressed;
+    }
+    /**
+     * The TCBL manifest — lazily deserialized and cached on first access.
+     *
+     * The manifest is parsed from the payload data (bytes after the
+     * compression flag). The checksum embedded in the manifest is
+     * validated during deserialization by {@link TcblManifestSerializer}.
+     *
+     * @throws {TcblError} with {@link TcblErrorType.InvalidHeader} if
+     *   payload data has not been set
+     * @throws {TcblError} with {@link TcblErrorType.ManifestCorrupted} or
+     *   {@link TcblErrorType.ManifestTruncated} if deserialization fails
+     *
+     * @see Requirement 2, 10.2
+     */
+    get manifest() {
+        if (!this._manifest) {
+            if (!this._payloadData) {
+                throw new tcblError_1.TcblError(tcblErrorType_1.TcblErrorType.InvalidHeader, new Map([
+                    ['reason', 'payload data not loaded; call setPayloadData()'],
+                ]));
+            }
+            // Skip the compression flag byte, deserialize the manifest
+            const manifestData = this._payloadData.subarray(1);
+            this._manifest = manifestSerializer_1.TcblManifestSerializer.deserialize(manifestData);
+        }
+        return this._manifest;
+    }
+    /**
+     * The entry descriptors from the manifest.
+     *
+     * @see Requirement 5.4
+     */
+    get entries() {
+        return this.manifest.entries;
+    }
+    /**
+     * Synchronous validation including TCBL-specific checks.
+     *
+     * Validates:
+     * 1. Base CBL structure (via `super.validateSync()`)
+     * 2. Structured block header (magic prefix + TarballCBL type byte)
+     * 3. Manifest entry count consistency (if manifest has been loaded)
+     *
+     * @throws {TcblError} with {@link TcblErrorType.ManifestCountMismatch}
+     *   if the manifest's `entryCount` does not match `entries.length`
+     *
+     * @see Requirement 10.4
+     */
+    validateSync() {
+        super.validateSync();
+        this.validateTcblHeader();
+        this.validateManifestCount();
+    }
+    /**
+     * Asynchronous validation including TCBL-specific checks.
+     *
+     * @see Requirement 10.4
+     */
+    async validateAsync() {
+        await super.validateAsync();
+        this.validateTcblHeader();
+        this.validateManifestCount();
+    }
+    /**
+     * Validate that the manifest entry count matches the actual number
+     * of entry descriptors. Only runs if the manifest has already been
+     * loaded (avoids forcing deserialization during validation).
+     *
+     * @throws {TcblError} with {@link TcblErrorType.ManifestCountMismatch}
+     *
+     * @see Requirement 10.4
+     */
+    validateManifestCount() {
+        if (this._manifest) {
+            if (this._manifest.entryCount !== this._manifest.entries.length) {
+                throw new tcblError_1.TcblError(tcblErrorType_1.TcblErrorType.ManifestCountMismatch, new Map([
+                    ['entryCount', String(this._manifest.entryCount)],
+                    ['actualEntries', String(this._manifest.entries.length)],
+                ]));
+            }
+        }
+    }
+}
+exports.TarballConstituentBlockListBlock = TarballConstituentBlockListBlock;
+/**
+ * Type guard that narrows a {@link ConstituentBlockListBlock} to a
+ * {@link TarballConstituentBlockListBlock}.
+ *
+ * Use this to safely upcast a CBL reference when you need to access
+ * TCBL-specific APIs (manifest, entries, isCompressed).
+ *
+ * @param block - Any CBL instance
+ * @returns `true` if `block` is a `TarballConstituentBlockListBlock`
+ *
+ * @example
+ * ```typescript
+ * const cbl = await cblStore.get(checksum, hydrateGuid);
+ * if (isTcbl(cbl)) {
+ *   // cbl is now typed as TarballConstituentBlockListBlock
+ *   const entries = cbl.entries;
+ * }
+ * ```
+ *
+ * @see Requirement 6.4 — consumer can upcast CBL to TCBL
+ */
+function isTcbl(block) {
+    return block instanceof TarballConstituentBlockListBlock;
+}
+//# sourceMappingURL=tcbl.js.map

package/src/lib/blocks/tcbl/tcbl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tcbl.js","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/blocks/tcbl/tcbl.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;;;AAmRH,wBAIC;AApRD,+CAAoE;AAEpE,oEAAiE;AACjE,sDAAmD;AAInD,gCAAmD;AACnD,6DAA8D;AAE9D;;;;;;;;;;;;;GAaG;AACH,MAAa,gCAEX,SAAQ,+BAA8B;IAUtC;;;;;;;;;;;;OAYG;IACH,YACE,IAAgB,EAChB,OAAoB,EACpB,SAAqB,EACrB,QAA4B;QAE5B,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;QAC1C,IAAI,CAAC,kBAAkB,EAAE,CAAC;IAC5B,CAAC;IAED;;;;;;;OAOG;IACK,kBAAkB;QACxB,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,qBAAS,CACjB,6BAAa,CAAC,aAAa,EAC3B,IAAI,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,4CAA4C,CAAC,CAAC,CAAC,CACpE,CAAC;QACJ,CAAC;QACD,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,wBAAY,CAAC,YAAY,EAAE,CAAC;YAChD,MAAM,IAAI,qBAAS,CACjB,6BAAa,CAAC,aAAa,EAC3B,IAAI,GAAG,CAAC;gBACN,CAAC,QAAQ,EAAE,sBAAsB,CAAC;gBAClC,CAAC,UAAU,EAAE,KAAK,wBAAY,CAAC,YAAY,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;gBAC3D,CAAC,QAAQ,EAAE,KAAK,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;aAC9C,CAAC,CACH,CAAC;QACJ,CAAC;QACD,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,+BAAmB,CAAC,UAAU,EAAE,CAAC;YACrD,MAAM,IAAI,qBAAS,CACjB,6BAAa,CAAC,aAAa,EAC3B,IAAI,GAAG,CAAC;gBACN,CAAC,QAAQ,EAAE,6BAA6B,CAAC;gBACzC,CAAC,UAAU,EAAE,KAAK,+BAAmB,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;gBAChE,CAAC,QAAQ,EAAE,KAAK,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;aAC9C,CAAC,CACH,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACI,cAAc,CAAC,WAAuB;QAC3C,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,qBAAS,CACjB,6BAAa,CAAC,aAAa,EAC3B,IAAI,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,uBAAuB,CAAC,CAAC,CAAC,CAC/C,CAAC;QACJ,CAAC;QAED,MAAM,eAAe,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;QACvC,IAAI,eAAe,KAAK,IAAI,IAAI,eAAe,KAAK,IAAI,EAAE,CAAC;YACzD,MAAM,IAAI,qBAAS,CACjB,6BAAa,CAAC,aAAa,EAC3B,IAAI,GAAG,CAAC;gBACN,CAAC,QAAQ,EAAE,0BAA0B,CAAC;gBACtC,CAAC,UAAU,EAAE,cAAc,CAAC;gBAC5B,CAAC,QAAQ,EAAE,KAAK,eAAe,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;aAChD,CAAC,CACH,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,aAAa,GAAG,eAAe,KAAK,IAAI,CAAC;QAC9C,IAAI,CAAC,YAAY,GAAG,WAAW,CAAC;QAChC,qEAAqE;QACrE,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;IAED;;;;;;;OAOG;IACH,IAAW,YAAY;QACrB,IAAI,IAAI,CAAC,aAAa,KAAK,SAAS,EAAE,CAAC;YACrC,MAAM,IAAI,qBAAS,CACjB,6BAAa,CAAC,aAAa,EAC3B,IAAI,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,gDAAgD,CAAC,CAAC,CAAC,CACxE,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,CAAC,aAAa,CAAC;IAC5B,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,IAAW,QAAQ;QACjB,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YACpB,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;gBACvB,MAAM,IAAI,qBAAS,CACjB,6BAAa,CAAC,aAAa,EAC3B,IAAI,GAAG,CAAC;oBACN,CAAC,QAAQ,EAAE,gDAAgD,CAAC;iBAC7D,CAAC,CACH,CAAC;YACJ,CAAC;YACD,2DAA2D;YAC3D,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;YACnD,IAAI,CAAC,SAAS,GAAG,2CAAsB,CAAC,WAAW,CAAC,YAAY,CAAC,CAAC;QACpE,CAAC;QACD,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED;;;;OAIG;IACH,IAAW,OAAO;QAChB,OAAO,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;IAC/B,CAAC;IAED;;;;;;;;;;;;OAYG;IACa,YAAY;QAC1B,KAAK,CAAC,YAAY,EAAE,CAAC;QACrB,IAAI,CAAC,kBAAkB,EAAE,CAAC;QAC1B,IAAI,CAAC,qBAAqB,EAAE,CAAC;IAC/B,CAAC;IAED;;;;OAIG;IACa,KAAK,CAAC,aAAa;QACjC,MAAM,KAAK,CAAC,aAAa,EAAE,CAAC;QAC5B,IAAI,CAAC,kBAAkB,EAAE,CAAC;QAC1B,IAAI,CAAC,qBAAqB,EAAE,CAAC;IAC/B,CAAC;IAED;;;;;;;;OAQG;IACK,qBAAqB;QAC3B,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,IAAI,IAAI,CAAC,SAAS,CAAC,UAAU,KAAK,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;gBAChE,MAAM,IAAI,qBAAS,CACjB,6BAAa,CAAC,qBAAqB,EACnC,IAAI,GAAG,CAAC;oBACN,CAAC,YAAY,EAAE,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;oBACjD,CAAC,eAAe,EAAE,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;iBACzD,CAAC,CACH,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;CACF;AAjOD,4EAiOC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,SAAgB,MAAM,CACpB,KAAqC;IAErC,OAAO,KAAK,YAAY,gCAAgC,CAAC;AAC3D,CAAC"}

package/src/lib/blocks/tcbl/tcblAttachmentUtils.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @fileoverview Utility functions for working with TCBL attachments
+ * in the context of quorum proposals.
+ *
+ * Provides a unified way to enumerate entries from an attachment
+ * that may be either a plain CBL or a TCBL archive. This allows
+ * proposal consumers to handle both formats transparently.
+ *
+ * @see Requirement 9.2 — enumerate entries from TCBL attachments
+ * @see Requirement 9.3 — handle plain CBL attachments as single-entry
+ */
+import { PlatformID } from '@digitaldefiance/ecies-lib';
+import { ICBLServices } from '../../interfaces/services/cblServices';
+import { IBlockStore } from '../../interfaces/storage/blockStore';
+import { ITcblEntryDescriptor } from '../../interfaces/tcbl/tcblEntryDescriptor';
+import { Checksum } from '../../types/checksum';
+/**
+ * Enumerate the entries contained in a proposal attachment.
+ *
+ * If the attachment is a TCBL archive, this function retrieves the
+ * payload, parses the manifest, and returns all entry descriptors.
+ *
+ * If the attachment is a plain CBL, this function returns a single-entry
+ * list with a generic descriptor (fileName: 'attachment', mimeType:
+ * 'application/octet-stream').
+ *
+ * @typeParam TID - Platform ID type for frontend/backend DTO compatibility
+ * @param attachmentCblId - The CBL/TCBL checksum identifying the attachment
+ * @param blockStore - The block store to retrieve block data from
+ * @param services - Optional CBL services for dependency injection
+ * @returns Array of entry descriptors for the attachment contents
+ *
+ * @example
+ * ```typescript
+ * const entries = await enumerateAttachmentEntries(
+ *   proposal.attachmentCblId,
+ *   blockStore,
+ * );
+ * for (const entry of entries) {
+ *   console.log(`${entry.fileName} (${entry.mimeType}, ${entry.originalDataLength} bytes)`);
+ * }
+ * ```
+ *
+ * @see Requirement 9.1 — attachmentCblId accepts both CBL and TCBL
+ * @see Requirement 9.2 — TCBL attachments enumerate all entries
+ * @see Requirement 9.3 — plain CBL attachments return single entry
+ */
+export declare function enumerateAttachmentEntries<TID extends PlatformID = Uint8Array>(attachmentCblId: Checksum, blockStore: IBlockStore, services?: ICBLServices<TID>): Promise<ITcblEntryDescriptor[]>;
+//# sourceMappingURL=tcblAttachmentUtils.d.ts.map

package/src/lib/blocks/tcbl/tcblAttachmentUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tcblAttachmentUtils.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/blocks/tcbl/tcblAttachmentUtils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAGxD,OAAO,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAC;AACrE,OAAO,EAAE,WAAW,EAAE,MAAM,qCAAqC,CAAC;AAClE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAGjF,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAGhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAsB,0BAA0B,CAC9C,GAAG,SAAS,UAAU,GAAG,UAAU,EAEnC,eAAe,EAAE,QAAQ,EACzB,UAAU,EAAE,WAAW,EACvB,QAAQ,CAAC,EAAE,YAAY,CAAC,GAAG,CAAC,GAC3B,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAmBjC"}

package/src/lib/blocks/tcbl/tcblAttachmentUtils.js

@@ -0,0 +1,126 @@
+"use strict";
+/**
+ * @fileoverview Utility functions for working with TCBL attachments
+ * in the context of quorum proposals.
+ *
+ * Provides a unified way to enumerate entries from an attachment
+ * that may be either a plain CBL or a TCBL archive. This allows
+ * proposal consumers to handle both formats transparently.
+ *
+ * @see Requirement 9.2 — enumerate entries from TCBL attachments
+ * @see Requirement 9.3 — handle plain CBL attachments as single-entry
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.enumerateAttachmentEntries = enumerateAttachmentEntries;
+const tcblErrorType_1 = require("../../enumerations/tcblErrorType");
+const tcblError_1 = require("../../errors/tcblError");
+const blockFormatService_1 = require("../../services/blockFormatService");
+const globalServiceProvider_1 = require("../../services/globalServiceProvider");
+const manifestSerializer_1 = require("./manifestSerializer");
+/**
+ * Enumerate the entries contained in a proposal attachment.
+ *
+ * If the attachment is a TCBL archive, this function retrieves the
+ * payload, parses the manifest, and returns all entry descriptors.
+ *
+ * If the attachment is a plain CBL, this function returns a single-entry
+ * list with a generic descriptor (fileName: 'attachment', mimeType:
+ * 'application/octet-stream').
+ *
+ * @typeParam TID - Platform ID type for frontend/backend DTO compatibility
+ * @param attachmentCblId - The CBL/TCBL checksum identifying the attachment
+ * @param blockStore - The block store to retrieve block data from
+ * @param services - Optional CBL services for dependency injection
+ * @returns Array of entry descriptors for the attachment contents
+ *
+ * @example
+ * ```typescript
+ * const entries = await enumerateAttachmentEntries(
+ *   proposal.attachmentCblId,
+ *   blockStore,
+ * );
+ * for (const entry of entries) {
+ *   console.log(`${entry.fileName} (${entry.mimeType}, ${entry.originalDataLength} bytes)`);
+ * }
+ * ```
+ *
+ * @see Requirement 9.1 — attachmentCblId accepts both CBL and TCBL
+ * @see Requirement 9.2 — TCBL attachments enumerate all entries
+ * @see Requirement 9.3 — plain CBL attachments return single entry
+ */
+async function enumerateAttachmentEntries(attachmentCblId, blockStore, services) {
+    // Retrieve the raw block data for the attachment
+    const rawBlock = await blockStore.getData(attachmentCblId);
+    const data = rawBlock.data;
+    // Check if the data has a TCBL header (0xBC + TarballCBL type byte)
+    if ((0, blockFormatService_1.isTarballCblData)(data)) {
+        return enumerateTcblEntries(data, blockStore, services);
+    }
+    // Plain CBL — return a single-entry descriptor with generic metadata
+    return [
+        {
+            fileName: 'attachment',
+            mimeType: 'application/octet-stream',
+            originalDataLength: data.length,
+            cblAddress: attachmentCblId,
+        },
+    ];
+}
+/**
+ * Parse a TCBL block's addresses and extract manifest entries.
+ *
+ * Uses the CBL service to parse addresses from the raw TCBL data,
+ * retrieves the payload block (last address), handles decompression,
+ * and parses the manifest.
+ *
+ * @param data - Raw TCBL block data (header + addresses)
+ * @param blockStore - Block store for retrieving the payload block
+ * @param services - Optional CBL services for dependency injection
+ * @returns Array of entry descriptors from the TCBL manifest
+ */
+async function enumerateTcblEntries(data, blockStore, services) {
+    const cblService = services?.cblService ?? (0, globalServiceProvider_1.getGlobalServiceProvider)().cblService;
+    // Parse addresses from the CBL data
+    const addresses = cblService.addressDataToAddresses(data);
+    if (addresses.length === 0) {
+        return [];
+    }
+    // The payload block is the last address in the CBL
+    const payloadAddress = addresses[addresses.length - 1];
+    const payloadBlock = await blockStore.getData(payloadAddress);
+    const rawPayload = payloadBlock.data;
+    if (rawPayload.length < 1) {
+        throw new tcblError_1.TcblError(tcblErrorType_1.TcblErrorType.InvalidHeader, new Map([['reason', 'payload block is empty']]));
+    }
+    // Check compression flag (byte 0)
+    const compressionFlag = rawPayload[0];
+    let manifestData;
+    if (compressionFlag === 0x01) {
+        // Compressed payload: [0x01][uncompressedLength(4 bytes BE)][bzip2 data]
+        if (rawPayload.length < 5) {
+            throw new tcblError_1.TcblError(tcblErrorType_1.TcblErrorType.DecompressionFailed, new Map([['reason', 'compressed payload too short']]));
+        }
+        try {
+            const view = new DataView(rawPayload.buffer, rawPayload.byteOffset, rawPayload.byteLength);
+            const uncompressedLength = view.getUint32(1, false);
+            const compressedData = rawPayload.subarray(5);
+            const BZip2Module = await Promise.resolve().then(() => require('@digitaldefiance/bzip2-wasm'));
+            const BZip2 = BZip2Module.default;
+            const bzip2 = new BZip2();
+            await bzip2.init();
+            manifestData = bzip2.decompress(compressedData, uncompressedLength);
+        }
+        catch (e) {
+            if (e instanceof tcblError_1.TcblError)
+                throw e;
+            throw new tcblError_1.TcblError(tcblErrorType_1.TcblErrorType.DecompressionFailed, new Map([['reason', String(e)]]));
+        }
+    }
+    else {
+        // Uncompressed: skip the compression flag byte
+        manifestData = rawPayload.subarray(1);
+    }
+    const manifest = manifestSerializer_1.TcblManifestSerializer.deserialize(manifestData);
+    return manifest.entries;
+}
+//# sourceMappingURL=tcblAttachmentUtils.js.map

package/src/lib/blocks/tcbl/tcblAttachmentUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tcblAttachmentUtils.js","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/blocks/tcbl/tcblAttachmentUtils.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;AA4CH,gEAyBC;AAlED,oEAAiE;AACjE,sDAAmD;AAInD,0EAAqE;AACrE,gFAAgF;AAEhF,6DAA8D;AAE9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACI,KAAK,UAAU,0BAA0B,CAG9C,eAAyB,EACzB,UAAuB,EACvB,QAA4B;IAE5B,iDAAiD;IACjD,MAAM,QAAQ,GAAG,MAAM,UAAU,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;IAC3D,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC;IAE3B,oEAAoE;IACpE,IAAI,IAAA,qCAAgB,EAAC,IAAI,CAAC,EAAE,CAAC;QAC3B,OAAO,oBAAoB,CAAM,IAAI,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC;IAC/D,CAAC;IAED,qEAAqE;IACrE,OAAO;QACL;YACE,QAAQ,EAAE,YAAY;YACtB,QAAQ,EAAE,0BAA0B;YACpC,kBAAkB,EAAE,IAAI,CAAC,MAAM;YAC/B,UAAU,EAAE,eAAe;SAC5B;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;GAWG;AACH,KAAK,UAAU,oBAAoB,CACjC,IAAgB,EAChB,UAAuB,EACvB,QAA4B;IAE5B,MAAM,UAAU,GACd,QAAQ,EAAE,UAAU,IAAI,IAAA,gDAAwB,GAAO,CAAC,UAAU,CAAC;IAErE,oCAAoC;IACpC,MAAM,SAAS,GAAG,UAAU,CAAC,sBAAsB,CAAC,IAAI,CAAC,CAAC;IAC1D,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3B,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,mDAAmD;IACnD,MAAM,cAAc,GAAG,SAAS,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACvD,MAAM,YAAY,GAAG,MAAM,UAAU,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;IAC9D,MAAM,UAAU,GAAG,YAAY,CAAC,IAAI,CAAC;IAErC,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,qBAAS,CACjB,6BAAa,CAAC,aAAa,EAC3B,IAAI,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,wBAAwB,CAAC,CAAC,CAAC,CAChD,CAAC;IACJ,CAAC;IAED,kCAAkC;IAClC,MAAM,eAAe,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;IACtC,IAAI,YAAwB,CAAC;IAE7B,IAAI,eAAe,KAAK,IAAI,EAAE,CAAC;QAC7B,yEAAyE;QACzE,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,qBAAS,CACjB,6BAAa,CAAC,mBAAmB,EACjC,IAAI,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,8BAA8B,CAAC,CAAC,CAAC,CACtD,CAAC;QACJ,CAAC;QACD,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,IAAI,QAAQ,CACvB,UAAU,CAAC,MAAM,EACjB,UAAU,CAAC,UAAU,EACrB,UAAU,CAAC,UAAU,CACtB,CAAC;YACF,MAAM,kBAAkB,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;YACpD,MAAM,cAAc,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;YAE9C,MAAM,WAAW,GAAG,2CAAa,6BAA6B,EAAC,CAAC;YAChE,MAAM,KAAK,GAAG,WAAW,CAAC,OAAO,CAAC;YAClC,MAAM,KAAK,GAAG,IAAI,KAAK,EAAE,CAAC;YAC1B,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC;YACnB,YAAY,GAAG,KAAK,CAAC,UAAU,CAAC,cAAc,EAAE,kBAAkB,CAAC,CAAC;QACtE,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,CAAC,YAAY,qBAAS;gBAAE,MAAM,CAAC,CAAC;YACpC,MAAM,IAAI,qBAAS,CACjB,6BAAa,CAAC,mBAAmB,EACjC,IAAI,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CACjC,CAAC;QACJ,CAAC;IACH,CAAC;SAAM,CAAC;QACN,+CAA+C;QAC/C,YAAY,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IACxC,CAAC;IAED,MAAM,QAAQ,GAAG,2CAAsB,CAAC,WAAW,CAAC,YAAY,CAAC,CAAC;IAClE,OAAO,QAAQ,CAAC,OAAO,CAAC;AAC1B,CAAC"}