@brightchain/brightchain-lib 0.8.1 → 0.10.0

package/src/lib/utils/dateUtils.js

@@ -0,0 +1,136 @@
+"use strict";
+/**
+ * Date Utilities Module
+ *
+ * Provides robust date handling utilities with timezone support for BrightChain.
+ * All dates are stored internally in UTC to ensure consistency across timezones.
+ *
+ * @module dateUtils
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseDate = parseDate;
+exports.serializeDate = serializeDate;
+exports.isValidDate = isValidDate;
+/**
+ * Parse a date from various formats (ISO 8601, Unix timestamp).
+ *
+ * Supports:
+ * - ISO 8601 strings (e.g., "2024-01-23T10:30:00Z", "2024-01-23T10:30:00.000Z")
+ * - Unix timestamps in milliseconds (number)
+ * - Unix timestamps in seconds (number < 10000000000)
+ *
+ * @param value - Date string or Unix timestamp
+ * @returns Date object in UTC
+ * @throws Error if date is invalid or malformed
+ *
+ * @example
+ * ```typescript
+ * // Parse ISO 8601 string
+ * const date1 = parseDate("2024-01-23T10:30:00Z");
+ *
+ * // Parse Unix timestamp (milliseconds)
+ * const date2 = parseDate(1706008200000);
+ *
+ * // Parse Unix timestamp (seconds)
+ * const date3 = parseDate(1706008200);
+ * ```
+ */
+function parseDate(value) {
+    if (typeof value === 'number') {
+        // Handle Unix timestamps
+        // Strategy: Use the value as-is first, then check if it produces a reasonable date
+        // If the date is before 1980 or after 2200 when interpreted as milliseconds,
+        // and the value is small enough to be seconds, try interpreting as seconds
+        let timestamp = value;
+        let date = new Date(timestamp);
+        // Check if we should try interpreting as seconds instead
+        // This handles the case where small numbers (< 10 billion) might be seconds
+        if (!isNaN(date.getTime())) {
+            const year = date.getFullYear();
+            // If the date is unreasonably early (before 1980) when interpreted as ms,
+            // and the value could be seconds (< 10 billion), try seconds
+            if (year < 1980 && value < 10000000000 && value > 0) {
+                timestamp = value * 1000;
+                date = new Date(timestamp);
+            }
+            // Also handle negative timestamps (before 1970)
+            else if (value < 0 && value > -10000000000) {
+                // Small negative numbers are likely seconds
+                timestamp = value * 1000;
+                date = new Date(timestamp);
+            }
+        }
+        if (isNaN(date.getTime())) {
+            throw new Error(`Invalid Unix timestamp: ${value}`);
+        }
+        return date;
+    }
+    if (typeof value === 'string') {
+        // Try parsing as ISO 8601 string
+        const date = new Date(value);
+        if (isNaN(date.getTime())) {
+            throw new Error(`Invalid date string: "${value}". Expected ISO 8601 format (e.g., "2024-01-23T10:30:00Z") or Unix timestamp.`);
+        }
+        return date;
+    }
+    throw new Error(`Invalid date value type: ${typeof value}. Expected string or number.`);
+}
+/**
+ * Serialize a date to ISO 8601 format with UTC timezone.
+ *
+ * Always returns dates in UTC timezone with 'Z' suffix.
+ * Format: "YYYY-MM-DDTHH:mm:ss.sssZ"
+ *
+ * @param date - Date to serialize
+ * @returns ISO 8601 string in UTC
+ * @throws Error if date is invalid
+ *
+ * @example
+ * ```typescript
+ * const date = new Date("2024-01-23T10:30:00Z");
+ * const serialized = serializeDate(date);
+ * // Returns: "2024-01-23T10:30:00.000Z"
+ * ```
+ */
+function serializeDate(date) {
+    if (!(date instanceof Date)) {
+        throw new Error(`Invalid date object: expected Date instance, got ${typeof date}`);
+    }
+    if (isNaN(date.getTime())) {
+        throw new Error('Invalid date: date object contains NaN timestamp');
+    }
+    return date.toISOString();
+}
+/**
+ * Validate that a date is valid and optionally check if it's not in the future.
+ *
+ * @param date - Date to validate
+ * @param allowFuture - Whether to allow future dates (default: false)
+ * @returns true if valid, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const date = new Date("2024-01-23T10:30:00Z");
+ * const isValid = isValidDate(date); // true if date is in the past
+ * const isValidFuture = isValidDate(date, true); // true regardless of future/past
+ * ```
+ */
+function isValidDate(date, allowFuture = false) {
+    // Check if it's a Date instance
+    if (!(date instanceof Date)) {
+        return false;
+    }
+    // Check if the date is valid (not NaN)
+    if (isNaN(date.getTime())) {
+        return false;
+    }
+    // Check if date is in the future (if not allowed)
+    if (!allowFuture) {
+        const now = new Date();
+        if (date.getTime() > now.getTime()) {
+            return false;
+        }
+    }
+    return true;
+}
+//# sourceMappingURL=dateUtils.js.map

package/src/lib/utils/dateUtils.js.map

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

package/src/lib/utils/index.d.ts

@@ -55,4 +55,61 @@ export * from './checksumUtils';
  * @see {@link xorUtils}
  */
 export * from './xorUtils';
+/**
+ * Constant-time comparison utilities for security-sensitive operations.
+ *
+ * Provides functions for:
+ * - Constant-time equality comparison (Uint8Array, hex strings, numbers)
+ * - Constant-time conditional selection
+ * - Constant-time zero checking
+ *
+ * These utilities prevent timing-based side-channel attacks by ensuring
+ * operations take the same amount of time regardless of input values.
+ *
+ * @see {@link constantTime}
+ */
+export * from './constantTime';
+/**
+ * Constant-time XOR operations for security-sensitive operations.
+ *
+ * Provides functions for:
+ * - Constant-time XOR of two arrays
+ * - Constant-time XOR of multiple arrays
+ *
+ * These utilities prevent timing-based side-channel attacks by ensuring
+ * XOR operations take the same amount of time regardless of input byte values.
+ * Critical for whitening/brightening operations in the Owner-Free Filesystem.
+ *
+ * @see {@link constantTimeXor}
+ */
+export * from './constantTimeXor';
+/**
+ * Type guard utilities for JSON deserialization.
+ *
+ * Provides functions for:
+ * - Runtime type checking of JSON data
+ * - Validating BlockMetadataJson structure
+ * - Validating EphemeralBlockMetadataJson structure
+ * - Parsing JSON with type safety
+ *
+ * These utilities ensure that JSON data conforms to expected TypeScript
+ * interfaces before constructing objects, maintaining type safety at runtime.
+ *
+ * @see {@link typeGuards}
+ */
+export * from './typeGuards';
+/**
+ * Date handling utilities with timezone support.
+ *
+ * Provides functions for:
+ * - Parsing dates from ISO 8601 strings and Unix timestamps
+ * - Serializing dates to ISO 8601 format in UTC
+ * - Validating dates (including future date checks)
+ *
+ * All dates are stored internally in UTC to ensure consistency across timezones.
+ * These utilities provide robust date handling for block metadata timestamps.
+ *
+ * @see {@link dateUtils}
+ */
+export * from './dateUtils';
 //# sourceMappingURL=index.d.ts.map

package/src/lib/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../brightchain-lib/src/lib/utils/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAKH;;;;;;;;;;;;GAYG;AACH,cAAc,aAAa,CAAC;AAK5B;;;;;;;;;GASG;AACH,cAAc,iBAAiB,CAAC;AAKhC;;;;;;;;;GASG;AACH,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../brightchain-lib/src/lib/utils/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAKH;;;;;;;;;;;;GAYG;AACH,cAAc,aAAa,CAAC;AAK5B;;;;;;;;;GASG;AACH,cAAc,iBAAiB,CAAC;AAKhC;;;;;;;;;GASG;AACH,cAAc,YAAY,CAAC;AAK3B;;;;;;;;;;;;GAYG;AACH,cAAc,gBAAgB,CAAC;AAK/B;;;;;;;;;;;;GAYG;AACH,cAAc,mBAAmB,CAAC;AAKlC;;;;;;;;;;;;;GAaG;AACH,cAAc,cAAc,CAAC;AAK7B;;;;;;;;;;;;GAYG;AACH,cAAc,aAAa,CAAC"}

package/src/lib/utils/index.js

@@ -67,4 +67,73 @@ tslib_1.__exportStar(require("./checksumUtils"), exports);
  * @see {@link xorUtils}
  */
 tslib_1.__exportStar(require("./xorUtils"), exports);
+// ============================================================================
+// Constant-Time Utilities
+// ============================================================================
+/**
+ * Constant-time comparison utilities for security-sensitive operations.
+ *
+ * Provides functions for:
+ * - Constant-time equality comparison (Uint8Array, hex strings, numbers)
+ * - Constant-time conditional selection
+ * - Constant-time zero checking
+ *
+ * These utilities prevent timing-based side-channel attacks by ensuring
+ * operations take the same amount of time regardless of input values.
+ *
+ * @see {@link constantTime}
+ */
+tslib_1.__exportStar(require("./constantTime"), exports);
+// ============================================================================
+// Constant-Time XOR Utilities
+// ============================================================================
+/**
+ * Constant-time XOR operations for security-sensitive operations.
+ *
+ * Provides functions for:
+ * - Constant-time XOR of two arrays
+ * - Constant-time XOR of multiple arrays
+ *
+ * These utilities prevent timing-based side-channel attacks by ensuring
+ * XOR operations take the same amount of time regardless of input byte values.
+ * Critical for whitening/brightening operations in the Owner-Free Filesystem.
+ *
+ * @see {@link constantTimeXor}
+ */
+tslib_1.__exportStar(require("./constantTimeXor"), exports);
+// ============================================================================
+// Type Guard Utilities
+// ============================================================================
+/**
+ * Type guard utilities for JSON deserialization.
+ *
+ * Provides functions for:
+ * - Runtime type checking of JSON data
+ * - Validating BlockMetadataJson structure
+ * - Validating EphemeralBlockMetadataJson structure
+ * - Parsing JSON with type safety
+ *
+ * These utilities ensure that JSON data conforms to expected TypeScript
+ * interfaces before constructing objects, maintaining type safety at runtime.
+ *
+ * @see {@link typeGuards}
+ */
+tslib_1.__exportStar(require("./typeGuards"), exports);
+// ============================================================================
+// Date Utilities
+// ============================================================================
+/**
+ * Date handling utilities with timezone support.
+ *
+ * Provides functions for:
+ * - Parsing dates from ISO 8601 strings and Unix timestamps
+ * - Serializing dates to ISO 8601 format in UTC
+ * - Validating dates (including future date checks)
+ *
+ * All dates are stored internally in UTC to ensure consistency across timezones.
+ * These utilities provide robust date handling for block metadata timestamps.
+ *
+ * @see {@link dateUtils}
+ */
+tslib_1.__exportStar(require("./dateUtils"), exports);
 //# sourceMappingURL=index.js.map

package/src/lib/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../brightchain-lib/src/lib/utils/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AAEH,+EAA+E;AAC/E,uBAAuB;AACvB,+EAA+E;AAC/E;;;;;;;;;;;;GAYG;AACH,sDAA4B;AAE5B,+EAA+E;AAC/E,qBAAqB;AACrB,+EAA+E;AAC/E;;;;;;;;;GASG;AACH,0DAAgC;AAEhC,+EAA+E;AAC/E,gBAAgB;AAChB,+EAA+E;AAC/E;;;;;;;;;GASG;AACH,qDAA2B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../brightchain-lib/src/lib/utils/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AAEH,+EAA+E;AAC/E,uBAAuB;AACvB,+EAA+E;AAC/E;;;;;;;;;;;;GAYG;AACH,sDAA4B;AAE5B,+EAA+E;AAC/E,qBAAqB;AACrB,+EAA+E;AAC/E;;;;;;;;;GASG;AACH,0DAAgC;AAEhC,+EAA+E;AAC/E,gBAAgB;AAChB,+EAA+E;AAC/E;;;;;;;;;GASG;AACH,qDAA2B;AAE3B,+EAA+E;AAC/E,0BAA0B;AAC1B,+EAA+E;AAC/E;;;;;;;;;;;;GAYG;AACH,yDAA+B;AAE/B,+EAA+E;AAC/E,8BAA8B;AAC9B,+EAA+E;AAC/E;;;;;;;;;;;;GAYG;AACH,4DAAkC;AAElC,+EAA+E;AAC/E,uBAAuB;AACvB,+EAA+E;AAC/E;;;;;;;;;;;;;GAaG;AACH,uDAA6B;AAE7B,+EAA+E;AAC/E,iBAAiB;AACjB,+EAA+E;AAC/E;;;;;;;;;;;;GAYG;AACH,sDAA4B"}

package/src/lib/utils/typeGuards.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Type Guards for JSON Deserialization
+ *
+ * This module provides runtime type checking for JSON deserialization of block metadata.
+ * Type guards ensure that JSON data conforms to expected TypeScript interfaces before
+ * constructing objects, maintaining type safety at runtime.
+ *
+ * @module typeGuards
+ *
+ * @example
+ * ```typescript
+ * import { isBlockMetadataJson, parseBlockMetadataJson } from 'brightchain-lib';
+ *
+ * // Validate JSON data structure
+ * if (isBlockMetadataJson(data)) {
+ *   // TypeScript knows data is BlockMetadataJson
+ *   const metadata = new BlockMetadata(data.size, data.type, ...);
+ * }
+ *
+ * // Parse and validate JSON string
+ * try {
+ *   const data = parseBlockMetadataJson(jsonString);
+ *   // data is guaranteed to be BlockMetadataJson
+ * } catch (error) {
+ *   // Handle validation error with descriptive message
+ * }
+ * ```
+ */
+/**
+ * JSON representation of BlockMetadata.
+ * This interface defines the expected structure of JSON data
+ * when deserializing BlockMetadata objects.
+ */
+export interface BlockMetadataJson {
+    /** Block size in bytes (must be a valid BlockSize enum value) */
+    size: number;
+    /** Block type (must be a valid BlockType enum value) */
+    type: number;
+    /** Data type (must be a valid BlockDataType enum value) */
+    dataType: number;
+    /** Length of data without padding (must be non-negative) */
+    lengthWithoutPadding: number;
+    /** Date created (ISO 8601 string or Unix timestamp) */
+    dateCreated: string | number;
+}
+/**
+ * JSON representation of EphemeralBlockMetadata.
+ * Extends BlockMetadataJson with creator information.
+ */
+export interface EphemeralBlockMetadataJson extends BlockMetadataJson {
+    /** Creator ID (serialized as string) */
+    creator: string;
+}
+/**
+ * Error thrown when JSON validation fails.
+ * Provides descriptive information about which field failed validation.
+ */
+export declare class JsonValidationError extends Error {
+    readonly field: string;
+    readonly reason: string;
+    readonly value?: unknown | undefined;
+    constructor(field: string, reason: string, value?: unknown | undefined);
+}
+/**
+ * Type guard for BlockMetadataJson.
+ * Validates that an unknown value conforms to the BlockMetadataJson interface.
+ *
+ * @param data - Data to validate
+ * @returns True if data is BlockMetadataJson
+ * @throws JsonValidationError if validation fails with descriptive error
+ */
+export declare function isBlockMetadataJson(data: unknown): data is BlockMetadataJson;
+/**
+ * Type guard for EphemeralBlockMetadataJson.
+ * Validates that an unknown value conforms to the EphemeralBlockMetadataJson interface.
+ *
+ * @param data - Data to validate
+ * @returns True if data is EphemeralBlockMetadataJson
+ * @throws JsonValidationError if validation fails with descriptive error
+ */
+export declare function isEphemeralBlockMetadataJson(data: unknown): data is EphemeralBlockMetadataJson;
+/**
+ * Parse and validate a JSON string as BlockMetadataJson.
+ * Combines JSON parsing with type guard validation.
+ *
+ * @param json - JSON string to parse
+ * @returns Validated BlockMetadataJson object
+ * @throws JsonValidationError if validation fails
+ * @throws SyntaxError if JSON parsing fails
+ */
+export declare function parseBlockMetadataJson(json: string): BlockMetadataJson;
+/**
+ * Parse and validate a JSON string as EphemeralBlockMetadataJson.
+ * Combines JSON parsing with type guard validation.
+ *
+ * @param json - JSON string to parse
+ * @returns Validated EphemeralBlockMetadataJson object
+ * @throws JsonValidationError if validation fails
+ * @throws SyntaxError if JSON parsing fails
+ */
+export declare function parseEphemeralBlockMetadataJson(json: string): EphemeralBlockMetadataJson;
+//# sourceMappingURL=typeGuards.d.ts.map

package/src/lib/utils/typeGuards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typeGuards.d.ts","sourceRoot":"","sources":["../../../../../brightchain-lib/src/lib/utils/typeGuards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAMH;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,oBAAoB,EAAE,MAAM,CAAC;IAC7B,uDAAuD;IACvD,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,0BAA2B,SAAQ,iBAAiB;IACnE,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;aAE1B,KAAK,EAAE,MAAM;aACb,MAAM,EAAE,MAAM;aACd,KAAK,CAAC,EAAE,OAAO;gBAFf,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,KAAK,CAAC,EAAE,OAAO,YAAA;CAKlC;AAkED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,iBAAiB,CAmF5E;AAED;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,OAAO,GACZ,IAAI,IAAI,0BAA0B,CA4BpC;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,CAmBtE;AAED;;;;;;;;GAQG;AACH,wBAAgB,+BAA+B,CAC7C,IAAI,EAAE,MAAM,GACX,0BAA0B,CAmB5B"}

package/src/lib/utils/typeGuards.js

@@ -0,0 +1,244 @@
+"use strict";
+/**
+ * Type Guards for JSON Deserialization
+ *
+ * This module provides runtime type checking for JSON deserialization of block metadata.
+ * Type guards ensure that JSON data conforms to expected TypeScript interfaces before
+ * constructing objects, maintaining type safety at runtime.
+ *
+ * @module typeGuards
+ *
+ * @example
+ * ```typescript
+ * import { isBlockMetadataJson, parseBlockMetadataJson } from 'brightchain-lib';
+ *
+ * // Validate JSON data structure
+ * if (isBlockMetadataJson(data)) {
+ *   // TypeScript knows data is BlockMetadataJson
+ *   const metadata = new BlockMetadata(data.size, data.type, ...);
+ * }
+ *
+ * // Parse and validate JSON string
+ * try {
+ *   const data = parseBlockMetadataJson(jsonString);
+ *   // data is guaranteed to be BlockMetadataJson
+ * } catch (error) {
+ *   // Handle validation error with descriptive message
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JsonValidationError = void 0;
+exports.isBlockMetadataJson = isBlockMetadataJson;
+exports.isEphemeralBlockMetadataJson = isEphemeralBlockMetadataJson;
+exports.parseBlockMetadataJson = parseBlockMetadataJson;
+exports.parseEphemeralBlockMetadataJson = parseEphemeralBlockMetadataJson;
+const blockDataType_1 = require("../enumerations/blockDataType");
+const blockSize_1 = require("../enumerations/blockSize");
+const blockType_1 = require("../enumerations/blockType");
+/**
+ * Error thrown when JSON validation fails.
+ * Provides descriptive information about which field failed validation.
+ */
+class JsonValidationError extends Error {
+    constructor(field, reason, value) {
+        super(`JSON validation failed for field '${field}': ${reason}`);
+        this.field = field;
+        this.reason = reason;
+        this.value = value;
+        this.name = 'JsonValidationError';
+    }
+}
+exports.JsonValidationError = JsonValidationError;
+/**
+ * Check if a value is a valid BlockSize enum value.
+ * @param value - Value to check
+ * @returns True if value is a valid BlockSize
+ */
+function isValidBlockSize(value) {
+    if (typeof value !== 'number') {
+        return false;
+    }
+    return blockSize_1.validBlockSizes.includes(value);
+}
+/**
+ * Check if a value is a valid BlockType enum value.
+ * BlockType.Unknown (-1) is explicitly rejected as it represents
+ * uninitialized or invalid blocks and should not be used in metadata.
+ *
+ * @param value - Value to check
+ * @returns True if value is a valid BlockType (excluding Unknown)
+ */
+function isValidBlockType(value) {
+    if (typeof value !== 'number') {
+        return false;
+    }
+    // Explicitly reject BlockType.Unknown (-1)
+    if (value === blockType_1.default.Unknown) {
+        return false;
+    }
+    // Check if the value exists in the BlockType enum
+    return Object.values(blockType_1.default).includes(value);
+}
+/**
+ * Check if a value is a valid BlockDataType enum value.
+ * @param value - Value to check
+ * @returns True if value is a valid BlockDataType
+ */
+function isValidBlockDataType(value) {
+    if (typeof value !== 'number') {
+        return false;
+    }
+    // Check if the value exists in the BlockDataType enum
+    return Object.values(blockDataType_1.default).includes(value);
+}
+/**
+ * Check if a value is a valid date representation (ISO 8601 string or Unix timestamp).
+ * @param value - Value to check
+ * @returns True if value can be parsed as a date
+ */
+function isValidDateValue(value) {
+    if (typeof value === 'string') {
+        // Check if it's a valid ISO 8601 string
+        const date = new Date(value);
+        return !isNaN(date.getTime());
+    }
+    if (typeof value === 'number') {
+        // Check if it's a valid Unix timestamp
+        const date = new Date(value);
+        return !isNaN(date.getTime());
+    }
+    return false;
+}
+/**
+ * Type guard for BlockMetadataJson.
+ * Validates that an unknown value conforms to the BlockMetadataJson interface.
+ *
+ * @param data - Data to validate
+ * @returns True if data is BlockMetadataJson
+ * @throws JsonValidationError if validation fails with descriptive error
+ */
+function isBlockMetadataJson(data) {
+    // Check if data is an object
+    if (typeof data !== 'object' || data === null) {
+        throw new JsonValidationError('data', 'must be a non-null object', data);
+    }
+    const obj = data;
+    // Validate size field
+    if (!('size' in obj)) {
+        throw new JsonValidationError('size', 'field is required');
+    }
+    if (!isValidBlockSize(obj['size'])) {
+        throw new JsonValidationError('size', 'must be a valid BlockSize enum value', obj['size']);
+    }
+    // Validate type field
+    if (!('type' in obj)) {
+        throw new JsonValidationError('type', 'field is required');
+    }
+    if (!isValidBlockType(obj['type'])) {
+        throw new JsonValidationError('type', 'must be a valid BlockType enum value', obj['type']);
+    }
+    // Validate dataType field
+    if (!('dataType' in obj)) {
+        throw new JsonValidationError('dataType', 'field is required');
+    }
+    if (!isValidBlockDataType(obj['dataType'])) {
+        throw new JsonValidationError('dataType', 'must be a valid BlockDataType enum value', obj['dataType']);
+    }
+    // Validate lengthWithoutPadding field
+    if (!('lengthWithoutPadding' in obj)) {
+        throw new JsonValidationError('lengthWithoutPadding', 'field is required');
+    }
+    if (typeof obj['lengthWithoutPadding'] !== 'number') {
+        throw new JsonValidationError('lengthWithoutPadding', 'must be a number', obj['lengthWithoutPadding']);
+    }
+    if (obj['lengthWithoutPadding'] < 0) {
+        throw new JsonValidationError('lengthWithoutPadding', 'must be non-negative', obj['lengthWithoutPadding']);
+    }
+    if (!Number.isInteger(obj['lengthWithoutPadding'])) {
+        throw new JsonValidationError('lengthWithoutPadding', 'must be an integer', obj['lengthWithoutPadding']);
+    }
+    // Validate dateCreated field
+    if (!('dateCreated' in obj)) {
+        throw new JsonValidationError('dateCreated', 'field is required');
+    }
+    if (!isValidDateValue(obj['dateCreated'])) {
+        throw new JsonValidationError('dateCreated', 'must be a valid ISO 8601 string or Unix timestamp', obj['dateCreated']);
+    }
+    return true;
+}
+/**
+ * Type guard for EphemeralBlockMetadataJson.
+ * Validates that an unknown value conforms to the EphemeralBlockMetadataJson interface.
+ *
+ * @param data - Data to validate
+ * @returns True if data is EphemeralBlockMetadataJson
+ * @throws JsonValidationError if validation fails with descriptive error
+ */
+function isEphemeralBlockMetadataJson(data) {
+    // First validate as BlockMetadataJson
+    if (!isBlockMetadataJson(data)) {
+        return false;
+    }
+    const obj = data;
+    // Validate creator field
+    if (!('creator' in obj)) {
+        throw new JsonValidationError('creator', 'field is required');
+    }
+    if (typeof obj['creator'] !== 'string') {
+        throw new JsonValidationError('creator', 'must be a string', obj['creator']);
+    }
+    if (obj['creator'].length === 0) {
+        throw new JsonValidationError('creator', 'must not be empty', obj['creator']);
+    }
+    return true;
+}
+/**
+ * Parse and validate a JSON string as BlockMetadataJson.
+ * Combines JSON parsing with type guard validation.
+ *
+ * @param json - JSON string to parse
+ * @returns Validated BlockMetadataJson object
+ * @throws JsonValidationError if validation fails
+ * @throws SyntaxError if JSON parsing fails
+ */
+function parseBlockMetadataJson(json) {
+    let data;
+    try {
+        data = JSON.parse(json);
+    }
+    catch (error) {
+        throw new JsonValidationError('json', `JSON parsing failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+    // Validate using type guard
+    if (isBlockMetadataJson(data)) {
+        return data;
+    }
+    // This should never be reached since isBlockMetadataJson throws on failure
+    throw new JsonValidationError('json', 'validation failed');
+}
+/**
+ * Parse and validate a JSON string as EphemeralBlockMetadataJson.
+ * Combines JSON parsing with type guard validation.
+ *
+ * @param json - JSON string to parse
+ * @returns Validated EphemeralBlockMetadataJson object
+ * @throws JsonValidationError if validation fails
+ * @throws SyntaxError if JSON parsing fails
+ */
+function parseEphemeralBlockMetadataJson(json) {
+    let data;
+    try {
+        data = JSON.parse(json);
+    }
+    catch (error) {
+        throw new JsonValidationError('json', `JSON parsing failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+    // Validate using type guard
+    if (isEphemeralBlockMetadataJson(data)) {
+        return data;
+    }
+    // This should never be reached since isEphemeralBlockMetadataJson throws on failure
+    throw new JsonValidationError('json', 'validation failed');
+}
+//# sourceMappingURL=typeGuards.js.map

package/src/lib/utils/typeGuards.js.map

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