@brightchain/brightchain-lib 0.21.0 → 0.22.0

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

@@ -0,0 +1,180 @@
+"use strict";
+/**
+ * @fileoverview TCBL Archive Builder.
+ *
+ * Constructs a TCBL (Tarball CBL) archive from a set of input entries.
+ * Each entry's data is stored as a raw block in the block store, and a
+ * manifest is built from the entry metadata. The final TCBL is assembled
+ * as a CBL with a `StructuredBlockType.TarballCBL` header.
+ *
+ * Optional bzip2 compression can be applied to the entire payload.
+ *
+ * @typeParam TID - Platform ID type for frontend/backend DTO compatibility
+ *
+ * @see Requirement 4 (TCBL Construction)
+ * @see Requirement 7 (Whole-Archive Compression)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TcblBuilder = void 0;
+const ecies_lib_1 = require("@digitaldefiance/ecies-lib");
+const constants_1 = require("../../constants");
+const blockEncryptionType_1 = require("../../enumerations/blockEncryptionType");
+const blockSize_1 = require("../../enumerations/blockSize");
+const globalServiceProvider_1 = require("../../services/globalServiceProvider");
+const checksum_1 = require("../../types/checksum");
+const rawData_1 = require("../rawData");
+const manifestSerializer_1 = require("./manifestSerializer");
+const tcbl_1 = require("./tcbl");
+const tcblValidator_1 = require("./tcblValidator");
+/**
+ * Builder for constructing TCBL (Tarball CBL) archives.
+ *
+ * Usage:
+ * ```typescript
+ * const builder = new TcblBuilder(creator, blockSize, blockStore);
+ * await builder.addEntry({ fileName: 'file.txt', mimeType: 'text/plain', data });
+ * const tcbl = await builder.build();
+ * ```
+ *
+ * @typeParam TID - Platform ID type (defaults to `Uint8Array`)
+ *
+ * @see Requirement 4
+ */
+class TcblBuilder {
+    /**
+     * Create a new TCBL builder.
+     *
+     * @param creator - The member creating the archive
+     * @param blockSize - Block size for storing entry data
+     * @param blockStore - Block store for persisting blocks
+     * @param services - Optional CBL services for dependency injection
+     * @param options - Optional archive options (compression)
+     *
+     * @see Requirement 4.8, 4.9
+     */
+    constructor(creator, blockSize, blockStore, services, options) {
+        /** Collected entry descriptors (populated by addEntry). */
+        this.entryDescriptors = [];
+        this.creator = creator;
+        this.blockSize = blockSize;
+        this.blockStore = blockStore;
+        this.services = services;
+        this.compress = options?.compress ?? false;
+    }
+    /**
+     * Add an entry to the archive.
+     *
+     * Validates the input, stores the entry data as a raw block in the
+     * block store, and records the entry descriptor for the manifest.
+     *
+     * @param input - The entry input (fileName, mimeType, data)
+     *
+     * @throws {TcblError} if validation fails (file name too long,
+     *   path traversal, MIME type too long)
+     *
+     * @see Requirement 4.1, 4.2
+     */
+    async addEntry(input) {
+        // Validate the entry input
+        tcblValidator_1.TcblValidator.validateFileName(input.fileName);
+        tcblValidator_1.TcblValidator.validateMimeType(input.mimeType);
+        // Store entry data as a raw block
+        const checksumService = this.services?.checksumService ??
+            (0, globalServiceProvider_1.getGlobalServiceProvider)().checksumService;
+        const checksum = checksumService.calculateChecksum(input.data);
+        const rawBlock = new rawData_1.RawDataBlock(this.blockSize, input.data, undefined, checksum);
+        await this.blockStore.setData(rawBlock);
+        // Record the entry descriptor
+        this.entryDescriptors.push({
+            fileName: input.fileName,
+            mimeType: input.mimeType,
+            originalDataLength: input.data.length,
+            cblAddress: checksum,
+        });
+    }
+    /**
+     * Build the TCBL archive.
+     *
+     * Constructs the manifest from collected entries, serializes it,
+     * optionally compresses the payload, creates a CBL header with
+     * `StructuredBlockType.TarballCBL`, and returns the final TCBL block.
+     *
+     * @returns The constructed TCBL block
+     *
+     * @see Requirement 4.3, 4.4, 4.5, 4.7, 4.10, 7.1, 7.3
+     */
+    async build() {
+        const checksumService = this.services?.checksumService ??
+            (0, globalServiceProvider_1.getGlobalServiceProvider)().checksumService;
+        const cblService = this.services?.cblService ?? (0, globalServiceProvider_1.getGlobalServiceProvider)().cblService;
+        // Build the manifest
+        const manifest = {
+            version: 1,
+            entryCount: this.entryDescriptors.length,
+            entries: [...this.entryDescriptors],
+            checksum: checksum_1.Checksum.fromUint8Array(new Uint8Array(ecies_lib_1.CHECKSUM.SHA3_BUFFER_LENGTH)),
+        };
+        // Serialize the manifest
+        const serializedManifest = manifestSerializer_1.TcblManifestSerializer.serialize(manifest);
+        // Assemble the TCBL payload: [compressionFlag(1)][manifestData]
+        let manifestData;
+        if (this.compress) {
+            // Dynamic import to avoid ESM/CJS issues at module load time
+            const BZip2Module = await Promise.resolve().then(() => require('bzip2-wasm'));
+            const BZip2 = BZip2Module.default;
+            const bzip2 = new BZip2();
+            await bzip2.init();
+            const compressed = bzip2.compress(serializedManifest);
+            // Store uncompressed length as uint32 BE so decompressor knows buffer size
+            const withLength = new Uint8Array(4 + compressed.length);
+            const view = new DataView(withLength.buffer, withLength.byteOffset, withLength.byteLength);
+            view.setUint32(0, serializedManifest.length, false);
+            withLength.set(compressed, 4);
+            manifestData = withLength;
+        }
+        else {
+            manifestData = serializedManifest;
+        }
+        // Full payload: [compressionFlag(1 byte)][manifestData]
+        const payload = new Uint8Array(1 + manifestData.length);
+        payload[0] = this.compress ? 0x01 : 0x00;
+        payload.set(manifestData, 1);
+        // Store the payload as a raw block so we have an address for it
+        const payloadChecksum = checksumService.calculateChecksum(payload);
+        const payloadBlock = new rawData_1.RawDataBlock(this.blockSize, payload, undefined, payloadChecksum);
+        await this.blockStore.setData(payloadBlock);
+        // Build the address list: entry data checksums + payload checksum
+        const allAddresses = [
+            ...this.entryDescriptors.map((e) => e.cblAddress),
+            payloadChecksum,
+        ];
+        const addressBytes = ecies_lib_1.CHECKSUM.SHA3_BUFFER_LENGTH;
+        const addressList = new Uint8Array(allAddresses.length * addressBytes);
+        for (let i = 0; i < allAddresses.length; i++) {
+            addressList.set(allAddresses[i].toUint8Array(), i * addressBytes);
+        }
+        // Create CBL header via cblService.makeCblHeader
+        // Use Small block size to ensure enough capacity for addresses
+        const cblBlockSize = blockSize_1.BlockSize.Small;
+        const { headerData } = cblService.makeCblHeader(this.creator, new Date(), allAddresses.length, payload.length, addressList, cblBlockSize, blockEncryptionType_1.BlockEncryptionType.None, undefined, constants_1.TUPLE.SIZE);
+        // Patch the structured block type byte from CBL to TarballCBL.
+        // The CRC8 is computed over baseHeader + extendedHeaderData (not the
+        // structured prefix), and the signature is computed over
+        // baseHeader + extendedHeaderData + blockSize + addressList.
+        // Neither includes byte[1], so patching is safe.
+        const patchedHeader = new Uint8Array(headerData);
+        patchedHeader[1] = constants_1.StructuredBlockType.TarballCBL;
+        // Assemble the full block data: header + addresses, padded to block size
+        const blockSizeBytes = cblBlockSize;
+        const data = new Uint8Array(blockSizeBytes);
+        data.set(patchedHeader, 0);
+        data.set(addressList, patchedHeader.length);
+        // Create the TarballConstituentBlockListBlock
+        const tcblBlock = new tcbl_1.TarballConstituentBlockListBlock(data, this.creator, cblBlockSize, this.services);
+        // Set the payload data so the manifest can be accessed
+        tcblBlock.setPayloadData(payload);
+        return tcblBlock;
+    }
+}
+exports.TcblBuilder = TcblBuilder;
+//# sourceMappingURL=tcblBuilder.js.map

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

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

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

@@ -0,0 +1,126 @@
+/**
+ * @fileoverview TCBL Archive Reader.
+ *
+ * Reads and extracts entries from a TCBL (Tarball CBL) archive.
+ * The reader receives an already-constructed {@link TarballConstituentBlockListBlock}
+ * and a block store. Decryption of any `EncryptedBlock` wrapper is the
+ * caller's responsibility.
+ *
+ * Usage:
+ * ```typescript
+ * const reader = new TcblReader(tcblBlock, blockStore);
+ * await reader.open();
+ * const entries = reader.listEntries();
+ * const data = await reader.getEntryByName('file.txt');
+ * ```
+ *
+ * @typeParam TID - Platform ID type for frontend/backend DTO compatibility
+ *
+ * @see Requirement 5 (TCBL Reading and Extraction)
+ */
+import { PlatformID } from '@digitaldefiance/ecies-lib';
+import { IBlockStore } from '../../interfaces/storage/blockStore';
+import { ITcblEntryDescriptor } from '../../interfaces/tcbl/tcblEntryDescriptor';
+import { TarballConstituentBlockListBlock } from './tcbl';
+/**
+ * Reader for TCBL (Tarball CBL) archives.
+ *
+ * Provides methods to enumerate manifest entries and extract individual
+ * entry data from the block store. The {@link open} method must be called
+ * before any other operations.
+ *
+ * @typeParam TID - Platform ID type (defaults to `Uint8Array`)
+ *
+ * @see Requirement 5
+ */
+export declare class TcblReader<TID extends PlatformID = Uint8Array> {
+    /** The TCBL block being read. */
+    private readonly tcblBlock;
+    /** Block store for retrieving entry data. */
+    private readonly blockStore;
+    /** Whether {@link open} has been called successfully. */
+    private _isOpen;
+    /** Cached manifest entries after open(). */
+    private _entries;
+    /**
+     * Create a new TCBL reader.
+     *
+     * @param tcblBlock - The TCBL block to read (must be already decrypted)
+     * @param blockStore - Block store for retrieving entry data blocks
+     *
+     * @see Requirement 5.7 — decryption is the caller's responsibility
+     */
+    constructor(tcblBlock: TarballConstituentBlockListBlock<TID>, blockStore: IBlockStore);
+    /**
+     * Open the archive for reading.
+     *
+     * Retrieves the payload block from the block store (last address in
+     * the CBL's address list), handles decompression if the payload is
+     * bzip2-compressed, sets the payload data on the TCBL block, and
+     * validates the manifest checksum.
+     *
+     * Must be called before {@link listEntries}, {@link getEntryByIndex},
+     * or {@link getEntryByName}.
+     *
+     * @throws {TcblError} with {@link TcblErrorType.DecompressionFailed}
+     *   if bzip2 decompression fails
+     * @throws {TcblError} with {@link TcblErrorType.ManifestChecksumMismatch}
+     *   if the manifest checksum does not match
+     * @throws {TcblError} with {@link TcblErrorType.ManifestCorrupted}
+     *   if the manifest is structurally invalid
+     *
+     * @see Requirement 5.1, 5.2, 5.5
+     */
+    open(): Promise<void>;
+    /**
+     * Ensure the archive has been opened.
+     *
+     * @throws {TcblError} with {@link TcblErrorType.InvalidHeader} if
+     *   {@link open} has not been called
+     */
+    private ensureOpen;
+    /**
+     * List all entry descriptors from the manifest without extracting data.
+     *
+     * @returns Array of entry descriptors
+     * @throws {TcblError} if the archive has not been opened
+     *
+     * @see Requirement 5.3
+     */
+    listEntries(): ITcblEntryDescriptor[];
+    /**
+     * Retrieve entry data by index.
+     *
+     * @param index - Zero-based index into the manifest entries
+     * @returns The entry's original data (trimmed to originalDataLength)
+     *
+     * @throws {TcblError} with {@link TcblErrorType.EntryNotFound} if
+     *   the index is out of range
+     *
+     * @see Requirement 5.4, 5.6
+     */
+    getEntryByIndex(index: number): Promise<Uint8Array>;
+    /**
+     * Retrieve entry data by file name.
+     *
+     * @param fileName - The file name to search for in the manifest
+     * @returns The entry's original data (trimmed to originalDataLength)
+     *
+     * @throws {TcblError} with {@link TcblErrorType.EntryNotFound} if
+     *   no entry with the given file name exists
+     *
+     * @see Requirement 5.4, 5.6
+     */
+    getEntryByName(fileName: string): Promise<Uint8Array>;
+    /**
+     * Retrieve the raw data for a manifest entry from the block store.
+     *
+     * The block store returns a {@link RawDataBlock} padded to block size,
+     * so we trim to `originalDataLength` to get the actual data.
+     *
+     * @param entry - The entry descriptor from the manifest
+     * @returns The entry's original data bytes
+     */
+    private retrieveEntryData;
+}
+//# sourceMappingURL=tcblReader.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tcblReader.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/blocks/tcbl/tcblReader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAGxD,OAAO,EAAE,WAAW,EAAE,MAAM,qCAAqC,CAAC;AAClE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,gCAAgC,EAAE,MAAM,QAAQ,CAAC;AAE1D;;;;;;;;;;GAUG;AACH,qBAAa,UAAU,CAAC,GAAG,SAAS,UAAU,GAAG,UAAU;IACzD,iCAAiC;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwC;IAElE,6CAA6C;IAC7C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAc;IAEzC,yDAAyD;IACzD,OAAO,CAAC,OAAO,CAAS;IAExB,4CAA4C;IAC5C,OAAO,CAAC,QAAQ,CAA8B;IAE9C;;;;;;;OAOG;gBAED,SAAS,EAAE,gCAAgC,CAAC,GAAG,CAAC,EAChD,UAAU,EAAE,WAAW;IAMzB;;;;;;;;;;;;;;;;;;;OAmBG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAoF3B;;;;;OAKG;IACH,OAAO,CAAC,UAAU;IASlB;;;;;;;OAOG;IACH,WAAW,IAAI,oBAAoB,EAAE;IAKrC;;;;;;;;;;OAUG;IACG,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAiBzD;;;;;;;;;;OAUG;IACG,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAc3D;;;;;;;;OAQG;YACW,iBAAiB;CAMhC"}

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

@@ -0,0 +1,224 @@
+"use strict";
+/**
+ * @fileoverview TCBL Archive Reader.
+ *
+ * Reads and extracts entries from a TCBL (Tarball CBL) archive.
+ * The reader receives an already-constructed {@link TarballConstituentBlockListBlock}
+ * and a block store. Decryption of any `EncryptedBlock` wrapper is the
+ * caller's responsibility.
+ *
+ * Usage:
+ * ```typescript
+ * const reader = new TcblReader(tcblBlock, blockStore);
+ * await reader.open();
+ * const entries = reader.listEntries();
+ * const data = await reader.getEntryByName('file.txt');
+ * ```
+ *
+ * @typeParam TID - Platform ID type for frontend/backend DTO compatibility
+ *
+ * @see Requirement 5 (TCBL Reading and Extraction)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TcblReader = void 0;
+const tcblErrorType_1 = require("../../enumerations/tcblErrorType");
+const tcblError_1 = require("../../errors/tcblError");
+/**
+ * Reader for TCBL (Tarball CBL) archives.
+ *
+ * Provides methods to enumerate manifest entries and extract individual
+ * entry data from the block store. The {@link open} method must be called
+ * before any other operations.
+ *
+ * @typeParam TID - Platform ID type (defaults to `Uint8Array`)
+ *
+ * @see Requirement 5
+ */
+class TcblReader {
+    /**
+     * Create a new TCBL reader.
+     *
+     * @param tcblBlock - The TCBL block to read (must be already decrypted)
+     * @param blockStore - Block store for retrieving entry data blocks
+     *
+     * @see Requirement 5.7 — decryption is the caller's responsibility
+     */
+    constructor(tcblBlock, blockStore) {
+        /** Whether {@link open} has been called successfully. */
+        this._isOpen = false;
+        /** Cached manifest entries after open(). */
+        this._entries = [];
+        this.tcblBlock = tcblBlock;
+        this.blockStore = blockStore;
+    }
+    /**
+     * Open the archive for reading.
+     *
+     * Retrieves the payload block from the block store (last address in
+     * the CBL's address list), handles decompression if the payload is
+     * bzip2-compressed, sets the payload data on the TCBL block, and
+     * validates the manifest checksum.
+     *
+     * Must be called before {@link listEntries}, {@link getEntryByIndex},
+     * or {@link getEntryByName}.
+     *
+     * @throws {TcblError} with {@link TcblErrorType.DecompressionFailed}
+     *   if bzip2 decompression fails
+     * @throws {TcblError} with {@link TcblErrorType.ManifestChecksumMismatch}
+     *   if the manifest checksum does not match
+     * @throws {TcblError} with {@link TcblErrorType.ManifestCorrupted}
+     *   if the manifest is structurally invalid
+     *
+     * @see Requirement 5.1, 5.2, 5.5
+     */
+    async open() {
+        // Retrieve the payload block — it's the last address in the CBL
+        const addresses = this.tcblBlock.addresses;
+        const payloadAddress = addresses[addresses.length - 1];
+        const payloadBlock = await this.blockStore.getData(payloadAddress);
+        const rawPayload = payloadBlock.data;
+        // Check the compression flag (byte 0)
+        const compressionFlag = rawPayload[0];
+        let decompressedPayload;
+        if (compressionFlag === 0x01) {
+            // Compressed: [0x01][uncompressedLength(4 bytes BE)][bzip2 data]
+            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('bzip2-wasm'));
+                const BZip2 = BZip2Module.default;
+                const bzip2 = new BZip2();
+                await bzip2.init();
+                const decompressedManifest = bzip2.decompress(compressedData, uncompressedLength);
+                // Build a new uncompressed payload: [0x00][decompressedManifest]
+                decompressedPayload = new Uint8Array(1 + decompressedManifest.length);
+                decompressedPayload[0] = 0x00;
+                decompressedPayload.set(decompressedManifest, 1);
+            }
+            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: use as-is
+            decompressedPayload = rawPayload;
+        }
+        // Set the (decompressed) payload on the TCBL block.
+        // This will parse the manifest via the block's manifest getter.
+        // The deserializer validates the manifest checksum internally,
+        // throwing ManifestCorrupted if it doesn't match.
+        try {
+            this.tcblBlock.setPayloadData(decompressedPayload);
+        }
+        catch (e) {
+            if (e instanceof tcblError_1.TcblError) {
+                // Re-map ManifestCorrupted to ManifestChecksumMismatch if it's
+                // a checksum issue (the deserializer throws ManifestCorrupted
+                // for checksum failures)
+                if (e.errorType === tcblErrorType_1.TcblErrorType.ManifestCorrupted) {
+                    throw new tcblError_1.TcblError(tcblErrorType_1.TcblErrorType.ManifestChecksumMismatch);
+                }
+                throw e;
+            }
+            throw e;
+        }
+        // Access the manifest to trigger deserialization and checksum validation.
+        // The manifest getter calls TcblManifestSerializer.deserialize() which
+        // validates the checksum internally.
+        try {
+            this._entries = [...this.tcblBlock.manifest.entries];
+        }
+        catch (e) {
+            if (e instanceof tcblError_1.TcblError) {
+                if (e.errorType === tcblErrorType_1.TcblErrorType.ManifestCorrupted) {
+                    throw new tcblError_1.TcblError(tcblErrorType_1.TcblErrorType.ManifestChecksumMismatch);
+                }
+                throw e;
+            }
+            throw e;
+        }
+        this._isOpen = true;
+    }
+    /**
+     * Ensure the archive has been opened.
+     *
+     * @throws {TcblError} with {@link TcblErrorType.InvalidHeader} if
+     *   {@link open} has not been called
+     */
+    ensureOpen() {
+        if (!this._isOpen) {
+            throw new tcblError_1.TcblError(tcblErrorType_1.TcblErrorType.InvalidHeader, new Map([['reason', 'archive not opened; call open() first']]));
+        }
+    }
+    /**
+     * List all entry descriptors from the manifest without extracting data.
+     *
+     * @returns Array of entry descriptors
+     * @throws {TcblError} if the archive has not been opened
+     *
+     * @see Requirement 5.3
+     */
+    listEntries() {
+        this.ensureOpen();
+        return [...this._entries];
+    }
+    /**
+     * Retrieve entry data by index.
+     *
+     * @param index - Zero-based index into the manifest entries
+     * @returns The entry's original data (trimmed to originalDataLength)
+     *
+     * @throws {TcblError} with {@link TcblErrorType.EntryNotFound} if
+     *   the index is out of range
+     *
+     * @see Requirement 5.4, 5.6
+     */
+    async getEntryByIndex(index) {
+        this.ensureOpen();
+        if (index < 0 || index >= this._entries.length) {
+            throw new tcblError_1.TcblError(tcblErrorType_1.TcblErrorType.EntryNotFound, new Map([
+                ['index', String(index)],
+                ['entryCount', String(this._entries.length)],
+            ]));
+        }
+        const entry = this._entries[index];
+        return this.retrieveEntryData(entry);
+    }
+    /**
+     * Retrieve entry data by file name.
+     *
+     * @param fileName - The file name to search for in the manifest
+     * @returns The entry's original data (trimmed to originalDataLength)
+     *
+     * @throws {TcblError} with {@link TcblErrorType.EntryNotFound} if
+     *   no entry with the given file name exists
+     *
+     * @see Requirement 5.4, 5.6
+     */
+    async getEntryByName(fileName) {
+        this.ensureOpen();
+        const entry = this._entries.find((e) => e.fileName === fileName);
+        if (!entry) {
+            throw new tcblError_1.TcblError(tcblErrorType_1.TcblErrorType.EntryNotFound, new Map([['fileName', fileName]]));
+        }
+        return this.retrieveEntryData(entry);
+    }
+    /**
+     * Retrieve the raw data for a manifest entry from the block store.
+     *
+     * The block store returns a {@link RawDataBlock} padded to block size,
+     * so we trim to `originalDataLength` to get the actual data.
+     *
+     * @param entry - The entry descriptor from the manifest
+     * @returns The entry's original data bytes
+     */
+    async retrieveEntryData(entry) {
+        const rawBlock = await this.blockStore.getData(entry.cblAddress);
+        return rawBlock.data.subarray(0, entry.originalDataLength);
+    }
+}
+exports.TcblReader = TcblReader;
+//# sourceMappingURL=tcblReader.js.map

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

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

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

@@ -0,0 +1,56 @@
+/**
+ * @fileoverview TCBL input validation utilities.
+ *
+ * Provides static validation methods for TCBL entry inputs including
+ * file name length/traversal checks and MIME type length checks.
+ *
+ * @see Requirement 10 (Validation and Error Handling)
+ */
+import { ITcblEntryInput } from '../../interfaces/tcbl/tcblEntryInput';
+/**
+ * Static validation utilities for TCBL archive entry inputs.
+ *
+ * All methods throw {@link TcblError} with the appropriate
+ * {@link TcblErrorType} on validation failure.
+ */
+export declare class TcblValidator {
+    /**
+     * Validate a file name for TCBL entry use.
+     *
+     * Rejects names that:
+     * - Exceed {@link CBL.MAX_FILE_NAME_LENGTH} (255) characters
+     * - Contain path traversal sequences (`../`, `..\\`)
+     * - Start with `/` or `\\` (absolute paths)
+     *
+     * @param name - The file name to validate
+     * @throws {TcblError} with {@link TcblErrorType.FileNameTooLong} if name exceeds 255 chars
+     * @throws {TcblError} with {@link TcblErrorType.PathTraversal} if name contains traversal or absolute path
+     *
+     * @see Requirement 10.5, 10.7
+     */
+    static validateFileName(name: string): void;
+    /**
+     * Validate a MIME type for TCBL entry use.
+     *
+     * Rejects MIME types that exceed {@link CBL.MAX_MIME_TYPE_LENGTH} (127) characters.
+     *
+     * @param mimeType - The MIME type string to validate
+     * @throws {TcblError} with {@link TcblErrorType.MimeTypeTooLong} if mimeType exceeds 127 chars
+     *
+     * @see Requirement 10.6
+     */
+    static validateMimeType(mimeType: string): void;
+    /**
+     * Validate all entries in an array of TCBL entry inputs.
+     *
+     * Validates each entry's file name and MIME type, throwing a
+     * {@link TcblError} on the first violation encountered.
+     *
+     * @param entries - The array of entry inputs to validate
+     * @throws {TcblError} on the first validation failure
+     *
+     * @see Requirement 10.5, 10.6, 10.7
+     */
+    static validateEntryInputs(entries: ITcblEntryInput[]): void;
+}
+//# sourceMappingURL=tcblValidator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tcblValidator.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/blocks/tcbl/tcblValidator.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,EAAE,eAAe,EAAE,MAAM,sCAAsC,CAAC;AAEvE;;;;;GAKG;AACH,qBAAa,aAAa;IACxB;;;;;;;;;;;;;OAaG;WACW,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAmClD;;;;;;;;;OASG;WACW,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAgBtD;;;;;;;;;;OAUG;WACW,mBAAmB,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,IAAI;CAMpE"}