@brightchain/brightchain-lib 0.8.1 → 0.10.0

package/src/lib/services/cblService.js

@@ -13,7 +13,8 @@ const cblError_1 = require("../errors/cblError");
 const extendedCblError_1 = require("../errors/extendedCblError");
 const checksum_1 = require("../types/checksum");
 const validator_1 = require("../utils/validator");
-const blockCapacity_service_1 = require("./blockCapacity.service");
+const blockFormatService_1 = require("./blockFormatService");
+const globalServiceProvider_1 = require("./globalServiceProvider");
 /**
  * Service for creating and verifying CBL blocks.
  *
@@ -40,8 +41,7 @@ class CBLService {
     constructor(checksumService, eciesService, enhancedProvider) {
         this.checksumService = checksumService;
         this.eciesService = eciesService;
-        // Use the enhanced provider which should now use the same global configuration
-        this.enhancedProvider = enhancedProvider ?? (0, ecies_lib_1.getEnhancedIdProvider)();
+        this.enhancedProvider = enhancedProvider;
     }
     /** Create safe buffers for common operations */
     createArrays() {
@@ -62,18 +62,24 @@ class CBLService {
     get creatorLength() {
         return this.enhancedProvider.byteLength;
     }
+    /**
+     * Offset of the creator ID field in the header (after structured prefix)
+     */
+    get creatorIdOffset() {
+        return CBLService.StructuredPrefixSize;
+    }
     /**
      * Offset of the date field in the header (instance method for dynamic provider support)
      */
     get dateCreatedOffset() {
-        return this.creatorLength;
+        return this.creatorIdOffset + this.creatorLength;
     }
     /**
      * Offset of the date field in the header (static for backward compatibility)
      * @deprecated Use instance method dateCreatedOffset instead
      */
     static get DateCreatedOffset() {
-        return CBLService.CreatorIdLength;
+        return CBLService.StructuredPrefixSize + CBLService.CreatorIdLength;
     }
     /**
      * Offset of the address count field in the header (instance method)
@@ -180,12 +186,72 @@ class CBLService {
     static get FileNameLengthOffset() {
         return CBLService.BaseHeaderCreatorSignatureOffset;
     }
+    /**
+     * Offset of the sub-CBL count field in SuperCBL header (after date)
+     */
+    get superCblSubCblCountOffset() {
+        return this.dateCreatedOffset + CBLService.DateSize;
+    }
+    /**
+     * Offset of the total block count field in SuperCBL header
+     */
+    get superCblTotalBlockCountOffset() {
+        return this.superCblSubCblCountOffset + CBLService.SuperCblSubCblCountSize;
+    }
+    /**
+     * Offset of the depth field in SuperCBL header
+     */
+    get superCblDepthOffset() {
+        return (this.superCblTotalBlockCountOffset +
+            CBLService.SuperCblTotalBlockCountSize);
+    }
+    /**
+     * Offset of the original data length field in SuperCBL header
+     */
+    get superCblOriginalDataLengthOffset() {
+        return this.superCblDepthOffset + CBLService.SuperCblDepthSize;
+    }
+    /**
+     * Offset of the original checksum field in SuperCBL header
+     */
+    get superCblOriginalChecksumOffset() {
+        return this.superCblOriginalDataLengthOffset + CBLService.DataLengthSize;
+    }
+    /**
+     * Offset of the creator signature field in SuperCBL header
+     */
+    get superCblCreatorSignatureOffset() {
+        return this.superCblOriginalChecksumOffset + CBLService.DataChecksumSize;
+    }
+    /**
+     * Length of the SuperCBL header (without address data)
+     */
+    get superCblHeaderSize() {
+        return (this.superCblCreatorSignatureOffset + CBLService.CreatorSignatureSize);
+    }
+    /**
+     * Get SuperCBL header offsets
+     */
+    get superCblHeaderOffsets() {
+        return {
+            StructuredPrefix: 0,
+            CreatorId: this.creatorIdOffset,
+            DateCreated: this.dateCreatedOffset,
+            SubCblCount: this.superCblSubCblCountOffset,
+            TotalBlockCount: this.superCblTotalBlockCountOffset,
+            Depth: this.superCblDepthOffset,
+            OriginalDataLength: this.superCblOriginalDataLengthOffset,
+            OriginalDataChecksum: this.superCblOriginalChecksumOffset,
+            CreatorSignature: this.superCblCreatorSignatureOffset,
+        };
+    }
     /**
      * Instance offsets for dynamic provider support
      */
     get headerOffsets() {
         return {
-            CreatorId: 0,
+            StructuredPrefix: 0,
+            CreatorId: this.creatorIdOffset,
             DateCreated: this.dateCreatedOffset,
             CblAddressCount: this.cblAddressCountOffset,
             TupleSize: this.tupleSizeOffset,
@@ -202,7 +268,8 @@ class CBLService {
      */
     static get HeaderOffsets() {
         return {
-            CreatorId: 0,
+            StructuredPrefix: 0,
+            CreatorId: CBLService.StructuredPrefixSize,
             DateCreated: CBLService.DateCreatedOffset,
             CblAddressCount: CBLService.CblAddressCountOffset,
             TupleSize: CBLService.TupleSizeOffset,
@@ -219,6 +286,11 @@ class CBLService {
      * @returns True if the data is encrypted, false otherwise
      */
     isEncrypted(data) {
+        // Check for structured block prefix first
+        if (data[0] === constants_1.BLOCK_HEADER.MAGIC_PREFIX) {
+            return false; // Structured blocks are not encrypted
+        }
+        // Check for ECIES magic byte
         return data[0] === ecies_lib_1.ECIES.PUBLIC_KEY_MAGIC;
     }
     /**
@@ -514,7 +586,7 @@ class CBLService {
         if (this.isEncrypted(data)) {
             throw new cblError_1.CblError(cblErrorType_1.CblErrorType.CblEncrypted);
         }
-        if (!creator || !creator.privateKey) {
+        if (!creator || !creator.publicKey) {
             return false;
         }
         // Check if the creator ID in the header matches the provided creator
@@ -523,7 +595,8 @@ class CBLService {
             return false;
         }
         const headerLength = this.getHeaderLength(data);
-        const headerWithoutSignature = data.subarray(0, headerLength - CBLService.CreatorSignatureSize);
+        // Skip the 4-byte structured prefix when getting header for signature validation
+        const headerWithoutPrefixAndSignature = data.subarray(CBLService.StructuredPrefixSize, headerLength - CBLService.CreatorSignatureSize);
         // Get the block size from the parameter or calculate it from the data length
         const blockSizeBuffer = new Uint8Array(constants_1.default['UINT32_SIZE']);
         (0, bufferUtils_1.writeUInt32BE)(blockSize ?? (0, blockSize_1.lengthToBlockSize)(data.length), blockSizeBuffer);
@@ -532,7 +605,7 @@ class CBLService {
             this.getCblAddressCount(data) * ecies_lib_1.CHECKSUM.SHA3_BUFFER_LENGTH);
         // Combine arrays for signing
         const toSign = (0, bufferUtils_1.concatenateUint8Arrays)([
-            headerWithoutSignature,
+            headerWithoutPrefixAndSignature,
             blockSizeBuffer,
             addressList,
         ]);
@@ -724,7 +797,7 @@ class CBLService {
      * @throws {EnhancedValidationError} If block size or encryption type is invalid
      * @throws {CblError} If CBL-specific validation fails
      *
-     * @see Requirements 5.1, 5.2, 5.3, 12.1, 12.2, 12.7
+     * @see Requirements 5.1, 5.2, 5.3, 12.1, 12.2, 12.7, 9.1, 9.2, 9.4, 9.5, 10.1, 10.2, 12.4
      */
     makeCblHeader(creator, dateCreated, cblAddressCount, fileDataLength, addressList, blockSize, encryptionType, extendedCBL, tupleSize = constants_1.TUPLE.SIZE) {
         // Validate inputs using Validator
@@ -749,6 +822,10 @@ class CBLService {
             this.calculateCBLAddressCapacity(blockSize, encryptionType)) {
             throw new cblError_1.CblError(cblErrorType_1.CblErrorType.AddressCountExceedsCapacity);
         }
+        // Determine structured block type
+        const structuredBlockType = extendedCBL
+            ? constants_1.StructuredBlockType.ExtendedCBL
+            : constants_1.StructuredBlockType.CBL;
         // Create buffers for header fields
         const buffers = this.createArrays();
         const timestamp = dateCreated.getTime();
@@ -766,14 +843,15 @@ class CBLService {
         // Calculate a checksum for the original data (empty for now, will be filled in later)
         const dataChecksum = new Uint8Array(constants_1.default['CHECKSUM'].SHA3_BUFFER_LENGTH);
         buffers.dataChecksum.set(dataChecksum);
-        // Use the provider to convert creator ID to bytes
-        const creatorIdBytes = this.enhancedProvider.toBytes(creator.id);
+        // Use the member's idBytes directly - it's already in the correct format
+        // The Member class stores both the native ID type and the raw bytes
+        const creatorIdBytes = creator.idBytes;
         // Validate that the provider returns the expected length
         if (creatorIdBytes.length !== this.creatorLength) {
             throw new cblError_1.CblError(cblErrorType_1.CblErrorType.InvalidStructure, `Creator ID provider returned ${creatorIdBytes.length} bytes, expected ${this.creatorLength}`);
         }
         const creatorId = creatorIdBytes;
-        // Create base header
+        // Create base header (without structured prefix yet)
         const baseHeaderSize = creatorId.length +
             buffers.dateCreated.length +
             buffers.addressCount.length +
@@ -801,7 +879,7 @@ class CBLService {
         const extendedHeaderData = extendedCBL
             ? this.makeExtendedHeader(extendedCBL.fileName, extendedCBL.mimeType)
             : new Uint8Array(0);
-        // Calculate checksum
+        // Calculate checksum for signing
         const toSignSize = baseHeader.length +
             extendedHeaderData.length +
             buffers.blockSize.length +
@@ -823,9 +901,29 @@ class CBLService {
         if (signatureBytes.length !== ecies_lib_1.ECIES.SIGNATURE_SIZE) {
             throw new cblError_1.CblError(cblErrorType_1.CblErrorType.InvalidSignature, `Signature length mismatch: got ${signatureBytes.length}, expected ${ecies_lib_1.ECIES.SIGNATURE_SIZE}`);
         }
-        // Construct final header
-        const headerData = new Uint8Array(baseHeader.length + extendedHeaderData.length + signatureBytes.length);
+        // Compute CRC8 over header content (after CRC8 field, before signature)
+        // This includes: baseHeader + extendedHeaderData (but not signature)
+        const crcDataSize = baseHeader.length + extendedHeaderData.length;
+        const crcData = new Uint8Array(crcDataSize);
+        crcData.set(baseHeader, 0);
+        crcData.set(extendedHeaderData, baseHeader.length);
+        const crcService = new ecies_lib_1.CrcService();
+        const crc8Buffer = crcService.crc8(crcData);
+        const crc8 = crc8Buffer[0];
+        // Create structured prefix: [MagicPrefix(1)][BlockType(1)][Version(1)][CRC8(1)]
+        const structuredPrefix = new Uint8Array(4);
+        structuredPrefix[0] = constants_1.BLOCK_HEADER.MAGIC_PREFIX;
+        structuredPrefix[1] = structuredBlockType;
+        structuredPrefix[2] = constants_1.BLOCK_HEADER.VERSION;
+        structuredPrefix[3] = crc8;
+        // Construct final header with structured prefix
+        const headerData = new Uint8Array(structuredPrefix.length +
+            baseHeader.length +
+            extendedHeaderData.length +
+            signatureBytes.length);
         let headerOffset = 0;
+        headerData.set(structuredPrefix, headerOffset);
+        headerOffset += structuredPrefix.length;
         headerData.set(baseHeader, headerOffset);
         headerOffset += baseHeader.length;
         headerData.set(extendedHeaderData, headerOffset);
@@ -840,9 +938,21 @@ class CBLService {
      * @returns The parsed header
      */
     parseBaseHeader(data, creatorForValidation) {
-        if (this.isEncrypted(data)) {
+        // First, detect and validate the block format
+        const formatResult = (0, blockFormatService_1.detectBlockFormat)(data);
+        if (formatResult.isEncrypted) {
             throw new cblError_1.CblError(cblErrorType_1.CblErrorType.CblEncrypted);
         }
+        if (!formatResult.isValid) {
+            if (formatResult.error?.includes('encrypted')) {
+                throw new cblError_1.CblError(cblErrorType_1.CblErrorType.CblEncrypted);
+            }
+            if (formatResult.error?.includes('raw data')) {
+                throw new cblError_1.CblError(cblErrorType_1.CblErrorType.InvalidStructure, 'Data appears to be raw data without structured header');
+            }
+            throw new cblError_1.CblError(cblErrorType_1.CblErrorType.InvalidStructure, formatResult.error || 'Invalid block format');
+        }
+        // Validate signature if creator provided
         if (creatorForValidation &&
             !this.validateSignature(data, creatorForValidation)) {
             throw new cblError_1.CblError(cblErrorType_1.CblErrorType.InvalidSignature);
@@ -897,7 +1007,10 @@ class CBLService {
      * @param mimeType The mime type
      * @returns number of addresses that can fit in the block
      */
-    calculateCBLAddressCapacity(blockSize, encryptedBlockType, cbl) {
+    calculateCBLAddressCapacity(blockSize, encryptedBlockType, cbl, blockCapacityCalculator) {
+        // Use provided calculator or fall back to global service provider
+        const calculator = blockCapacityCalculator ??
+            (0, globalServiceProvider_1.getGlobalServiceProvider)().blockCapacityCalculator;
         let blockType;
         if (cbl) {
             blockType =
@@ -911,8 +1024,7 @@ class CBLService {
                     ? blockType_1.default.EncryptedConstituentBlockListBlock
                     : blockType_1.default.ConstituentBlockList;
         }
-        const blockCapacityCalculator = new blockCapacity_service_1.BlockCapacityCalculator(this, this.eciesService);
-        const result = blockCapacityCalculator.calculateCapacity({
+        const result = calculator.calculateCapacity({
             blockSize,
             blockType,
             encryptionType: encryptedBlockType,
@@ -932,8 +1044,362 @@ class CBLService {
         // Ensure enough space for at least four addresses
         return addressCapacity < 4 ? 0 : Math.max(0, tupleAlignedCapacity);
     }
+    // ============================================================================
+    // SuperCBL Methods
+    // ============================================================================
+    /**
+     * Check if the data is a SuperCBL
+     * @param data The data to check
+     * @returns True if the data is a SuperCBL, false otherwise
+     */
+    isSuperCbl(data) {
+        if (data.length < CBLService.StructuredPrefixSize) {
+            return false;
+        }
+        return (data[0] === constants_1.BLOCK_HEADER.MAGIC_PREFIX &&
+            data[1] === constants_1.StructuredBlockType.SuperCBL);
+    }
+    /**
+     * Get the sub-CBL count from a SuperCBL header
+     * @param header The SuperCBL header data
+     * @returns The number of sub-CBL references
+     */
+    getSuperCblSubCblCount(header) {
+        if (this.isEncrypted(header)) {
+            throw new cblError_1.CblError(cblErrorType_1.CblErrorType.CblEncrypted);
+        }
+        if (!this.isSuperCbl(header)) {
+            throw new cblError_1.CblError(cblErrorType_1.CblErrorType.InvalidStructure, 'Not a SuperCBL');
+        }
+        const view = new DataView(header.buffer, header.byteOffset, header.byteLength);
+        return view.getUint32(this.superCblHeaderOffsets.SubCblCount, false);
+    }
+    /**
+     * Get the total block count from a SuperCBL header
+     * @param header The SuperCBL header data
+     * @returns The total number of blocks across all sub-CBLs
+     */
+    getSuperCblTotalBlockCount(header) {
+        if (this.isEncrypted(header)) {
+            throw new cblError_1.CblError(cblErrorType_1.CblErrorType.CblEncrypted);
+        }
+        if (!this.isSuperCbl(header)) {
+            throw new cblError_1.CblError(cblErrorType_1.CblErrorType.InvalidStructure, 'Not a SuperCBL');
+        }
+        const view = new DataView(header.buffer, header.byteOffset, header.byteLength);
+        return view.getUint32(this.superCblHeaderOffsets.TotalBlockCount, false);
+    }
+    /**
+     * Get the depth from a SuperCBL header
+     * @param header The SuperCBL header data
+     * @returns The hierarchy depth
+     */
+    getSuperCblDepth(header) {
+        if (this.isEncrypted(header)) {
+            throw new cblError_1.CblError(cblErrorType_1.CblErrorType.CblEncrypted);
+        }
+        if (!this.isSuperCbl(header)) {
+            throw new cblError_1.CblError(cblErrorType_1.CblErrorType.InvalidStructure, 'Not a SuperCBL');
+        }
+        const view = new DataView(header.buffer, header.byteOffset, header.byteLength);
+        return view.getUint16(this.superCblHeaderOffsets.Depth, false);
+    }
+    /**
+     * Get the original data length from a SuperCBL header
+     * @param header The SuperCBL header data
+     * @returns The original file size
+     */
+    getSuperCblOriginalDataLength(header) {
+        if (this.isEncrypted(header)) {
+            throw new cblError_1.CblError(cblErrorType_1.CblErrorType.CblEncrypted);
+        }
+        if (!this.isSuperCbl(header)) {
+            throw new cblError_1.CblError(cblErrorType_1.CblErrorType.InvalidStructure, 'Not a SuperCBL');
+        }
+        const view = new DataView(header.buffer, header.byteOffset, header.byteLength);
+        const bigIntValue = view.getBigUint64(this.superCblHeaderOffsets.OriginalDataLength, false);
+        return Number(bigIntValue);
+    }
+    /**
+     * Get the original data checksum from a SuperCBL header
+     * @param header The SuperCBL header data
+     * @returns The SHA3-512 checksum of the original data
+     */
+    getSuperCblOriginalDataChecksum(header) {
+        if (this.isEncrypted(header)) {
+            throw new cblError_1.CblError(cblErrorType_1.CblErrorType.CblEncrypted);
+        }
+        if (!this.isSuperCbl(header)) {
+            throw new cblError_1.CblError(cblErrorType_1.CblErrorType.InvalidStructure, 'Not a SuperCBL');
+        }
+        const checksumData = header.subarray(this.superCblHeaderOffsets.OriginalDataChecksum, this.superCblHeaderOffsets.OriginalDataChecksum +
+            CBLService.DataChecksumSize);
+        return checksum_1.Checksum.fromUint8Array(checksumData);
+    }
+    /**
+     * Get the creator signature from a SuperCBL header
+     * @param header The SuperCBL header data
+     * @returns The ECDSA signature
+     */
+    getSuperCblSignature(header) {
+        if (this.isEncrypted(header)) {
+            throw new cblError_1.CblError(cblErrorType_1.CblErrorType.CblEncrypted);
+        }
+        if (!this.isSuperCbl(header)) {
+            throw new cblError_1.CblError(cblErrorType_1.CblErrorType.InvalidStructure, 'Not a SuperCBL');
+        }
+        return header.subarray(this.superCblHeaderOffsets.CreatorSignature, this.superCblHeaderOffsets.CreatorSignature +
+            CBLService.CreatorSignatureSize);
+    }
+    /**
+     * Get the sub-CBL checksums from a SuperCBL
+     * @param data The SuperCBL data (header + address data)
+     * @returns Array of sub-CBL checksums
+     */
+    getSuperCblSubCblChecksums(data) {
+        if (this.isEncrypted(data)) {
+            throw new cblError_1.CblError(cblErrorType_1.CblErrorType.CblEncrypted);
+        }
+        if (!this.isSuperCbl(data)) {
+            throw new cblError_1.CblError(cblErrorType_1.CblErrorType.InvalidStructure, 'Not a SuperCBL');
+        }
+        const subCblCount = this.getSuperCblSubCblCount(data);
+        const addressDataStart = this.superCblHeaderSize;
+        const checksums = new Array(subCblCount);
+        for (let i = 0; i < subCblCount; i++) {
+            const offset = addressDataStart + i * ecies_lib_1.CHECKSUM.SHA3_BUFFER_LENGTH;
+            const checksumData = data.subarray(offset, offset + ecies_lib_1.CHECKSUM.SHA3_BUFFER_LENGTH);
+            checksums[i] = checksum_1.Checksum.fromUint8Array(checksumData);
+        }
+        return checksums;
+    }
+    /**
+     * Create a SuperCBL header.
+     *
+     * @param creator - The member creating the SuperCBL
+     * @param dateCreated - The creation date
+     * @param subCblCount - Number of sub-CBL references
+     * @param totalBlockCount - Total blocks across all sub-CBLs
+     * @param depth - Hierarchy depth
+     * @param originalDataLength - Original file size
+     * @param originalDataChecksum - SHA3-512 checksum of original data
+     * @param subCblChecksums - Array of sub-CBL checksums
+     * @param blockSize - The block size
+     * @returns Object containing headerData and signature
+     * @throws {CblError} If validation fails
+     *
+     * @see Requirements 11.1, 11.2, 11.3, 11.4, 11.5
+     */
+    makeSuperCblHeader(creator, dateCreated, subCblCount, totalBlockCount, depth, originalDataLength, originalDataChecksum, subCblChecksums, blockSize) {
+        // Validate inputs
+        validator_1.Validator.validateRequired(creator, 'creator', 'makeSuperCblHeader');
+        validator_1.Validator.validateRequired(dateCreated, 'dateCreated', 'makeSuperCblHeader');
+        validator_1.Validator.validateRequired(originalDataChecksum, 'originalDataChecksum', 'makeSuperCblHeader');
+        validator_1.Validator.validateRequired(subCblChecksums, 'subCblChecksums', 'makeSuperCblHeader');
+        validator_1.Validator.validateBlockSize(blockSize, 'makeSuperCblHeader');
+        if (subCblCount !== subCblChecksums.length) {
+            throw new cblError_1.CblError(cblErrorType_1.CblErrorType.InvalidStructure, `SubCblCount (${subCblCount}) does not match subCblChecksums length (${subCblChecksums.length})`);
+        }
+        if (depth < 1 || depth > 65535) {
+            throw new cblError_1.CblError(cblErrorType_1.CblErrorType.InvalidStructure, `Depth must be between 1 and 65535, got ${depth}`);
+        }
+        // Create buffers for header fields
+        const dateBuffer = new Uint8Array(CBLService.DateSize);
+        const subCblCountBuffer = new Uint8Array(CBLService.SuperCblSubCblCountSize);
+        const totalBlockCountBuffer = new Uint8Array(CBLService.SuperCblTotalBlockCountSize);
+        const depthBuffer = new Uint8Array(CBLService.SuperCblDepthSize);
+        const dataLengthBuffer = new Uint8Array(CBLService.DataLengthSize);
+        const blockSizeBuffer = new Uint8Array(constants_1.default['UINT32_SIZE']);
+        const timestamp = dateCreated.getTime();
+        // Write timestamp using DataView
+        const dateView = new DataView(dateBuffer.buffer);
+        dateView.setUint32(0, Math.floor(timestamp / 0x100000000), false);
+        dateView.setUint32(constants_1.default['UINT32_SIZE'], timestamp % 0x100000000, false);
+        // Write sub-CBL count
+        const subCblCountView = new DataView(subCblCountBuffer.buffer);
+        subCblCountView.setUint32(0, subCblCount, false);
+        // Write total block count
+        const totalBlockCountView = new DataView(totalBlockCountBuffer.buffer);
+        totalBlockCountView.setUint32(0, totalBlockCount, false);
+        // Write depth
+        const depthView = new DataView(depthBuffer.buffer);
+        depthView.setUint16(0, depth, false);
+        // Write original data length
+        const dataLengthView = new DataView(dataLengthBuffer.buffer);
+        dataLengthView.setBigUint64(0, BigInt(originalDataLength), false);
+        // Write block size
+        (0, bufferUtils_1.writeUInt32BE)(blockSize, blockSizeBuffer);
+        // Get creator ID bytes
+        const creatorIdBytes = creator.idBytes;
+        if (creatorIdBytes.length !== this.creatorLength) {
+            throw new cblError_1.CblError(cblErrorType_1.CblErrorType.InvalidStructure, `Creator ID provider returned ${creatorIdBytes.length} bytes, expected ${this.creatorLength}`);
+        }
+        // Create address list from sub-CBL checksums
+        const addressList = new Uint8Array(subCblCount * ecies_lib_1.CHECKSUM.SHA3_BUFFER_LENGTH);
+        for (let i = 0; i < subCblCount; i++) {
+            addressList.set(subCblChecksums[i].toUint8Array(), i * ecies_lib_1.CHECKSUM.SHA3_BUFFER_LENGTH);
+        }
+        // Create base header (without structured prefix)
+        const baseHeaderSize = creatorIdBytes.length +
+            dateBuffer.length +
+            subCblCountBuffer.length +
+            totalBlockCountBuffer.length +
+            depthBuffer.length +
+            dataLengthBuffer.length +
+            CBLService.DataChecksumSize;
+        const baseHeader = new Uint8Array(baseHeaderSize);
+        let offset = 0;
+        // Copy base header fields
+        baseHeader.set(creatorIdBytes, offset);
+        offset += creatorIdBytes.length;
+        baseHeader.set(dateBuffer, offset);
+        offset += dateBuffer.length;
+        baseHeader.set(subCblCountBuffer, offset);
+        offset += subCblCountBuffer.length;
+        baseHeader.set(totalBlockCountBuffer, offset);
+        offset += totalBlockCountBuffer.length;
+        baseHeader.set(depthBuffer, offset);
+        offset += depthBuffer.length;
+        baseHeader.set(dataLengthBuffer, offset);
+        offset += dataLengthBuffer.length;
+        baseHeader.set(originalDataChecksum.toUint8Array(), offset);
+        // Calculate checksum for signing
+        const toSignSize = baseHeader.length + blockSizeBuffer.length + addressList.length;
+        const toSign = new Uint8Array(toSignSize);
+        let signOffset = 0;
+        toSign.set(baseHeader, signOffset);
+        signOffset += baseHeader.length;
+        toSign.set(blockSizeBuffer, signOffset);
+        signOffset += blockSizeBuffer.length;
+        toSign.set(addressList, signOffset);
+        const checksum = this.checksumService.calculateChecksum(toSign);
+        const signatureBytes = (creator instanceof ecies_lib_1.Member && creator.privateKey
+            ? new Uint8Array(this.eciesService.signMessage(creator.privateKey.value, checksum.toUint8Array()))
+            : new Uint8Array(ecies_lib_1.ECIES.SIGNATURE_SIZE));
+        // Validate signature length
+        if (signatureBytes.length !== ecies_lib_1.ECIES.SIGNATURE_SIZE) {
+            throw new cblError_1.CblError(cblErrorType_1.CblErrorType.InvalidSignature, `Signature length mismatch: got ${signatureBytes.length}, expected ${ecies_lib_1.ECIES.SIGNATURE_SIZE}`);
+        }
+        // Compute CRC8 over header content (after CRC8 field, before signature)
+        const crcService = new ecies_lib_1.CrcService();
+        const crc8Buffer = crcService.crc8(baseHeader);
+        const crc8 = crc8Buffer[0];
+        // Create structured prefix: [MagicPrefix(1)][BlockType(1)][Version(1)][CRC8(1)]
+        const structuredPrefix = new Uint8Array(4);
+        structuredPrefix[0] = constants_1.BLOCK_HEADER.MAGIC_PREFIX;
+        structuredPrefix[1] = constants_1.StructuredBlockType.SuperCBL;
+        structuredPrefix[2] = constants_1.BLOCK_HEADER.VERSION;
+        structuredPrefix[3] = crc8;
+        // Construct final header with structured prefix
+        const headerData = new Uint8Array(structuredPrefix.length + baseHeader.length + signatureBytes.length);
+        let headerOffset = 0;
+        headerData.set(structuredPrefix, headerOffset);
+        headerOffset += structuredPrefix.length;
+        headerData.set(baseHeader, headerOffset);
+        headerOffset += baseHeader.length;
+        headerData.set(signatureBytes, headerOffset);
+        return { headerData, signature: signatureBytes };
+    }
+    /**
+     * Validate the signature of a SuperCBL.
+     *
+     * @param data - The SuperCBL data (header + address data)
+     * @param creator - The creator of the SuperCBL
+     * @param blockSize - The block size (optional, defaults to calculated from data length)
+     * @returns True if the signature is valid, false otherwise
+     * @throws {CblError} If the data is encrypted or not a SuperCBL
+     *
+     * @see Requirements 11.4, 11.6
+     */
+    validateSuperCblSignature(data, creator, blockSize) {
+        if (this.isEncrypted(data)) {
+            throw new cblError_1.CblError(cblErrorType_1.CblErrorType.CblEncrypted);
+        }
+        if (!this.isSuperCbl(data)) {
+            throw new cblError_1.CblError(cblErrorType_1.CblErrorType.InvalidStructure, 'Not a SuperCBL');
+        }
+        if (!creator || !creator.publicKey) {
+            return false;
+        }
+        // Check if the creator ID in the header matches the provided creator
+        const headerCreatorId = this.getCreatorId(data);
+        if (!this.enhancedProvider.equals(headerCreatorId, creator.id)) {
+            return false;
+        }
+        // Get header without prefix and signature for verification
+        const headerWithoutPrefixAndSignature = data.subarray(CBLService.StructuredPrefixSize, this.superCblHeaderSize - CBLService.CreatorSignatureSize);
+        // Get the block size from the parameter or calculate it from the data length
+        const blockSizeBuffer = new Uint8Array(constants_1.default['UINT32_SIZE']);
+        (0, bufferUtils_1.writeUInt32BE)(blockSize ?? (0, blockSize_1.lengthToBlockSize)(data.length), blockSizeBuffer);
+        // Get address list (sub-CBL checksums)
+        const subCblCount = this.getSuperCblSubCblCount(data);
+        const addressList = data.subarray(this.superCblHeaderSize, this.superCblHeaderSize + subCblCount * ecies_lib_1.CHECKSUM.SHA3_BUFFER_LENGTH);
+        // Combine arrays for signing
+        const toSign = (0, bufferUtils_1.concatenateUint8Arrays)([
+            headerWithoutPrefixAndSignature,
+            blockSizeBuffer,
+            addressList,
+        ]);
+        const checksum = this.checksumService.calculateChecksum(toSign);
+        const signature = this.getSuperCblSignature(data);
+        return this.eciesService.verifyMessage(creator.publicKey, checksum.toUint8Array(), signature);
+    }
+    /**
+     * Parse a SuperCBL header from data.
+     *
+     * @param data - The SuperCBL data (header + address data)
+     * @param creatorForValidation - Optional creator to validate signature against
+     * @param blockSize - Optional block size for signature validation (required if validating signature)
+     * @returns The parsed SuperCBL header
+     * @throws {CblError} If the data is encrypted, not a SuperCBL, or validation fails
+     *
+     * @see Requirements 11.1, 11.2
+     */
+    parseSuperCblHeader(data, creatorForValidation, blockSize) {
+        // First, detect and validate the block format
+        const formatResult = (0, blockFormatService_1.detectBlockFormat)(data);
+        if (formatResult.isEncrypted) {
+            throw new cblError_1.CblError(cblErrorType_1.CblErrorType.CblEncrypted);
+        }
+        if (!formatResult.isValid) {
+            if (formatResult.error?.includes('encrypted')) {
+                throw new cblError_1.CblError(cblErrorType_1.CblErrorType.CblEncrypted);
+            }
+            if (formatResult.error?.includes('raw data')) {
+                throw new cblError_1.CblError(cblErrorType_1.CblErrorType.InvalidStructure, 'Data appears to be raw data without structured header');
+            }
+            throw new cblError_1.CblError(cblErrorType_1.CblErrorType.InvalidStructure, formatResult.error || 'Invalid block format');
+        }
+        // Validate that this is a SuperCBL
+        if (!this.isSuperCbl(data)) {
+            throw new cblError_1.CblError(cblErrorType_1.CblErrorType.InvalidStructure, `Expected SuperCBL (block type 0x03), got block type 0x${data[1].toString(16).padStart(2, '0')}`);
+        }
+        // Validate signature if creator provided
+        if (creatorForValidation &&
+            !this.validateSuperCblSignature(data, creatorForValidation, blockSize)) {
+            throw new cblError_1.CblError(cblErrorType_1.CblErrorType.InvalidSignature);
+        }
+        // Extract sub-CBL checksums
+        const subCblCount = this.getSuperCblSubCblCount(data);
+        const subCblChecksums = this.getSuperCblSubCblChecksums(data);
+        return {
+            creatorId: this.getCreatorId(data),
+            dateCreated: this.getDateCreated(data),
+            subCblCount,
+            totalBlockCount: this.getSuperCblTotalBlockCount(data),
+            depth: this.getSuperCblDepth(data),
+            originalDataLength: this.getSuperCblOriginalDataLength(data),
+            originalDataChecksum: this.getSuperCblOriginalDataChecksum(data),
+            creatorSignature: this.getSuperCblSignature(data),
+            subCblChecksums,
+        };
+    }
 }
 exports.CBLService = CBLService;
+/**
+ * Length of the structured block header prefix (magic, type, version, CRC8)
+ */
+CBLService.StructuredPrefixSize = 4;
 /**
  * Length of the date field in the header
  * Date consists of two 32-bit unsigned integers (high/low)
@@ -976,4 +1442,19 @@ CBLService.FileNameLengthSize = constants_1.default['UINT16_SIZE'];
  * Length of the mime type length field in the header
  */
 CBLService.MimeTypeLengthSize = constants_1.default['UINT8_SIZE'];
+// ============================================================================
+// SuperCBL Header Constants
+// ============================================================================
+/**
+ * Length of the sub-CBL count field in SuperCBL header
+ */
+CBLService.SuperCblSubCblCountSize = constants_1.default['UINT32_SIZE'];
+/**
+ * Length of the total block count field in SuperCBL header
+ */
+CBLService.SuperCblTotalBlockCountSize = constants_1.default['UINT32_SIZE'];
+/**
+ * Length of the depth field in SuperCBL header
+ */
+CBLService.SuperCblDepthSize = constants_1.default['UINT16_SIZE'];
 //# sourceMappingURL=cblService.js.map