mcard-js 1.0.0

package/src/core/event-producer.js

@@ -0,0 +1,160 @@
+import { HashAlgorithm as HashAlgorithmEnum } from './hash/enums.js';
+import HashValidator from './hash/validator.js';
+import { GTime as GTimeUtil } from './g_time.js';
+import { HASH_ALGORITHM_HIERARCHY as ALGORITHM_HIERARCHY } from '../config/config_constants.js';
+
+// Use global Buffer if available, otherwise use the polyfill
+const Buffer = global.Buffer || require('buffer').Buffer;
+
+// Destructure the enum values
+const { 
+  MD5, 
+  SHA1, 
+  SHA224, 
+  SHA256, 
+  SHA384, 
+  SHA512, 
+  DEFAULT
+} = HashAlgorithmEnum;
+
+// Event type constants
+const TYPE = 'type';
+const HASH = 'hash';
+const CONTENT_TYPE = 'content_type';
+const TIMESTAMP = 'timestamp';
+const EXISTING_CARD_HASH = 'existing_card_hash';
+const NEW_CARD_HASH = 'new_card_hash';
+const FIRST_G_TIME = 'first_g_time';
+const CONTENT_SIZE = 'content_size';
+const COLLISION_TIME = 'collision_time';
+const UPGRADED_FUNCTION = 'upgraded_function';
+const UPGRADED_HASH = 'upgraded_hash';
+const DUPLICATE_TIME = 'duplicate_time';
+const DUPLICATE_EVENT_TYPE = 'duplicate';
+const COLLISION_EVENT_TYPE = 'collision';
+
+// Predefined hash function progression order
+const HASH_FUNCTION_ORDER = ['md5', 'sha1', 'sha224', 'sha256', 'sha384', 'sha512'];
+
+// Create a new HashValidator instance for use
+let hashValidator;
+
+// Initialize hashValidator in a try-catch to handle potential initialization errors
+try {
+  hashValidator = new HashValidator(Buffer.from(''), 'sha256');
+} catch (error) {
+  console.warn('Failed to initialize hashValidator:', error);
+  // Create a mock hashValidator if initialization fails
+  hashValidator = {
+    validate: () => Promise.resolve(true),
+    computeHash: () => 'mocked-hash'
+  };
+}
+
+// Explicitly define HASH_ALGORITHM_HIERARCHY
+const HASH_ALGORITHM_HIERARCHY = {
+  [MD5]: [SHA1],
+  [SHA1]: [SHA224],
+  [SHA224]: [SHA256],
+  [SHA256]: [SHA384],
+  [SHA384]: [SHA512],
+  [SHA512]: []
+};
+
+// Replace existing nextHashFunction with method from instance
+function nextHashFunction(currentHashFunction) {
+  const algMap = {
+    'md5': MD5,
+    'sha1': SHA1,
+    'sha224': SHA224, 
+    'sha256': SHA256,
+    'sha384': SHA384,
+    'sha512': SHA512
+  };
+  
+  const currFunc = algMap[currentHashFunction] || currentHashFunction;
+  
+  const hashFunctions = Object.values(HashAlgorithmEnum).filter(
+    func => func !== currFunc && typeof func === 'string' 
+  );
+  
+  const strongerFunctions = hashFunctions.filter(func => {
+    const currentStrongerFuncs = HASH_ALGORITHM_HIERARCHY[currFunc] || [];
+    return currentStrongerFuncs.includes(func);
+  });
+  
+  return strongerFunctions.length > 0 
+    ? strongerFunctions[0] 
+    : currFunc; 
+}
+
+// Generate a duplication event for the given card
+// @param {Object} card - The card being duplicated
+// @returns {string} JSON-stringified duplication event
+function generateDuplicationEvent(card) {
+  const event = {
+    [TYPE]: DUPLICATE_EVENT_TYPE,
+    [HASH]: card.hash,
+    [CONTENT_TYPE]: card.contentType,
+    [TIMESTAMP]: GTimeUtil.stampNow(card.hashFunction || HashAlgorithmEnum.DEFAULT),
+    [DUPLICATE_TIME]: card.g_time
+  };
+  return JSON.stringify(event);
+}
+
+// Generate a collision event for the given event data
+// @param {Object} newCard - The new card
+// @param {Object} existingCard - The existing card
+// @returns {string} JSON-stringified collision event
+function generateCollisionEvent(newCard, existingCard = null) {
+  const event = {
+    type: 'collision',
+    original_hash: existingCard ? existingCard.hash : null,
+    new_hash: newCard.hash,
+    timestamp: GTimeUtil.stampNow(
+      newCard.hashFunction || 
+      existingCard?.hashFunction || 
+      HashAlgorithmEnum.DEFAULT
+    ),
+    content_size: typeof newCard.content === 'string' ? 
+      Buffer.from(newCard.content).length : 
+      newCard.content.length
+  };
+
+  if (existingCard) {
+    const upgradedFunction = nextHashFunction(existingCard.hashFunction);
+    event.upgraded_function = upgradedFunction;
+    event.upgraded_hash = existingCard.hash;  
+    event.hash_algorithm = upgradedFunction;  
+  }
+
+  return JSON.stringify(event);
+}
+
+export {
+  MD5,
+  SHA1,
+  SHA224,
+  SHA256,
+  SHA384,
+  SHA512,
+  TYPE,
+  HASH,
+  CONTENT_TYPE,
+  TIMESTAMP,
+  EXISTING_CARD_HASH,
+  NEW_CARD_HASH,
+  FIRST_G_TIME,
+  CONTENT_SIZE,
+  COLLISION_TIME,
+  UPGRADED_FUNCTION,
+  UPGRADED_HASH,
+  DUPLICATE_TIME,
+  DUPLICATE_EVENT_TYPE,
+  COLLISION_EVENT_TYPE,
+  HASH_FUNCTION_ORDER,
+  HASH_ALGORITHM_HIERARCHY,
+  nextHashFunction,
+  generateDuplicationEvent,
+  generateCollisionEvent
+};

package/src/core/g_time.js

@@ -0,0 +1,215 @@
+import { HashAlgorithm } from '../config/config_constants.js';
+
+export class GTime {
+  /**
+   * Get current timestamp in ISO format with hash function and region code
+   * @param {string|HashAlgorithm} hashFunction - Hash function to use
+   * @returns {string} Formatted timestamp string
+   */
+  static stampNow(hashFunction) {
+    // Use default hash algorithm if no function is provided
+    if (hashFunction === null || hashFunction === undefined) {
+      hashFunction = HashAlgorithm.DEFAULT;
+    }
+
+    // Convert string to HashAlgorithm if needed
+    let normalizedHashFunction = hashFunction;
+    if (typeof hashFunction === 'string') {
+      const trimmedFunc = hashFunction.toLowerCase().trim();
+      if (!Object.values(HashAlgorithm).filter(func => typeof func === 'string').map(func => func.toLowerCase()).includes(trimmedFunc)) {
+        throw new Error(`Invalid hash function: ${hashFunction}`);
+      }
+      try {
+        normalizedHashFunction = HashAlgorithm[trimmedFunc.toUpperCase()];
+      } catch (error) {
+        throw new Error(`Invalid hash function: ${hashFunction}`);
+      }
+    }
+
+    const now = new Date();
+    const year = now.getFullYear();
+    const month = String(now.getMonth() + 1).padStart(2, '0');
+    const day = String(now.getDate()).padStart(2, '0');
+    const hours = String(now.getHours()).padStart(2, '0');
+    const minutes = String(now.getMinutes()).padStart(2, '0');
+    const seconds = String(now.getSeconds()).padStart(2, '0');
+    
+    // Ensure 6 decimal places for microseconds
+    const microseconds = String(Math.floor(performance.now() % 1 * 1000000)).padStart(6, '0').slice(0, 6);
+
+    const timestamp = `${year}-${month}-${day}T${hours}:${minutes}:${seconds}.${microseconds}Z`;
+    const regionCode = Intl.DateTimeFormat().resolvedOptions().timeZone.split('/')[0].toUpperCase();
+
+    return `${normalizedHashFunction}|${timestamp}|${regionCode}`;
+  }
+
+  /**
+   * Alias for stampNow to maintain backwards compatibility
+   * @param {string|HashAlgorithm} hashFunction - Hash function to use
+   * @returns {string} Formatted timestamp string
+   */
+  static stamp_now(hashFunction) {
+    return this.stampNow(hashFunction);
+  }
+
+  /**
+   * Get the hash function from the formatted string
+   * @param {string} stringValue - Formatted timestamp string
+   * @returns {string} Hash function
+   */
+  static get_hash_function(stringValue) {
+    // Validate input is a non-empty string
+    if (!stringValue || typeof stringValue !== 'string' || stringValue.trim() === '') {
+      throw new Error('Invalid hash function: Empty or non-string input');
+    }
+
+    // Validate exact number of parts
+    const parts = stringValue.split('|');
+    if (parts.length !== 3) {
+      throw new Error('Invalid hash function: Incorrect number of components');
+    }
+
+    // Validate each part is non-empty and has no extra whitespace
+    const [hashFunctionStr, timestamp, regionCode] = parts;
+    if (!hashFunctionStr || !timestamp || !regionCode) {
+      throw new Error('Invalid hash function: Missing components');
+    }
+
+    // Validate hash function format (must be exactly lowercase, no extra whitespace)
+    const trimmedHashFunc = hashFunctionStr.trim();
+    const validLowercaseHashes = Object.values(HashAlgorithm).filter(func => typeof func === 'string').map(func => func.toLowerCase());
+    
+    if (!validLowercaseHashes.includes(trimmedHashFunc) || 
+        trimmedHashFunc !== hashFunctionStr) {
+      throw new Error(`Invalid hash function: ${hashFunctionStr}`);
+    }
+
+    // Validate timestamp format (strict ISO 8601 with exactly 6 decimal places)
+    const timestampRegex = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{6}Z$/;
+    const trimmedTimestamp = timestamp.trim();
+    
+    if (!timestampRegex.test(trimmedTimestamp) || 
+        trimmedTimestamp !== timestamp) {
+      throw new Error('Invalid hash function: Incorrect timestamp format');
+    }
+
+    // Validate region code format (must be all uppercase letters, no extra whitespace)
+    const trimmedRegionCode = regionCode.trim();
+    if (!/^[A-Z]+$/.test(trimmedRegionCode) || 
+        trimmedRegionCode !== regionCode) {
+      throw new Error('Invalid hash function: Incorrect region code format');
+    }
+
+    try {
+      return HashAlgorithm[trimmedHashFunc.toUpperCase()];
+    } catch (error) {
+      throw new Error(`Invalid hash function: ${trimmedHashFunc}`);
+    }
+  }
+
+  /**
+   * Get the timestamp from the formatted string
+   * @param {string} stringValue - Formatted timestamp string
+   * @returns {string} Timestamp in ISO format
+   */
+  static get_timestamp(stringValue) {
+    return stringValue.split('|')[1];
+  }
+
+  /**
+   * Get the region code from the formatted string
+   * @param {string} stringValue - Formatted timestamp string
+   * @returns {string} Region code
+   */
+  static get_region_code(stringValue) {
+    return stringValue.split('|')[2];
+  }
+
+  /**
+   * Check if the provided hash function is valid
+   * @param {string|HashAlgorithm} hashFunction - Hash function to validate
+   * @returns {boolean} Whether the hash function is valid
+   */
+  static is_valid_hash_function(hashFunction) {
+    // Strict validation for null or undefined
+    if (hashFunction === null || hashFunction === undefined) {
+      return false;
+    }
+
+    // Reject any non-string, non-object inputs
+    if (typeof hashFunction !== 'string' && 
+        typeof hashFunction !== 'object' && 
+        typeof hashFunction !== 'boolean') {
+      return false;
+    }
+
+    // Reject non-string objects
+    if (typeof hashFunction === 'object' && 
+        !(hashFunction instanceof String)) {
+      return false;
+    }
+
+    // Reject empty strings or whitespace
+    if (typeof hashFunction === 'string' && 
+        (hashFunction.trim() === '' || hashFunction !== hashFunction.trim())) {
+      return false;
+    }
+
+    // For string inputs, be extremely strict
+    if (typeof hashFunction === 'string' || hashFunction instanceof String) {
+      // Convert to string 
+      const strFunc = String(hashFunction);
+      
+      // All valid hash functions, lowercase
+      const validLowercaseHashes = Object.values(HashAlgorithm).filter(func => typeof func === 'string').map(func => func.toLowerCase());
+      
+      // Reject any input that doesn't match exactly
+      const isValid = validLowercaseHashes.includes(strFunc) && 
+                      strFunc === strFunc.toLowerCase() && 
+                      strFunc.trim() === strFunc;
+
+      // Extra checks to reject inputs like 'md 5', 'md5 hash', 'SHA-256', 'MD5', etc.
+      if (!isValid || strFunc.includes(' ')) {
+        return false;
+      }
+
+      return true;
+    }
+    
+    // If we reach here, it means the input is a valid HashAlgorithm value
+    return Object.values(HashAlgorithm).includes(hashFunction);
+  }
+
+  /**
+   * Check if the provided region code is valid
+   * @param {string} regionCode - Region code to validate
+   * @returns {boolean} Whether the region code is valid
+   */
+  static is_valid_region_code(regionCode) {
+    if (regionCode === null || regionCode === undefined) {
+      return false;
+    }
+
+    return typeof regionCode === 'string' && 
+           regionCode.trim().length > 0 && 
+           regionCode.trim() === regionCode.trim().toUpperCase() &&
+           regionCode.trim() === regionCode; // No extra whitespace
+  }
+
+  /**
+   * Check if the provided timestamp is in ISO format
+   * @param {string} timestamp - Timestamp to validate
+   * @returns {boolean} Whether the timestamp is in ISO format
+   */
+  /**
+   * Validate ISO 8601 format with 6 decimal places
+   * @param {string} timestamp
+   * @returns {boolean}
+   */
+  static is_iso_format(timestamp) {
+    const isoRegex = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{6}Z$/;
+    return isoRegex.test(timestamp);
+  }
+}
+
+export default GTime;

package/src/core/hash/enums.js

@@ -0,0 +1,13 @@
+// Hash algorithm enums
+export const HashAlgorithm = {
+  MD5: 'md5',
+  SHA1: 'sha1',
+  SHA224: 'sha224',
+  SHA256: 'sha256',
+  SHA384: 'sha384',
+  SHA512: 'sha512'
+};
+
+export default {
+  HashAlgorithm
+};

package/src/core/hash/validator.js

@@ -0,0 +1,271 @@
+// Replace direct crypto import with environment-aware implementation
+import { encodeText } from '../../utils/textEncoderPolyfill.js';
+import { SafeBuffer } from '../../utils/bufferPolyfill.js';
+import { createHash } from '../../utils/cryptoPolyfill.js';
+import { 
+  HashAlgorithm, 
+  HASH_ALGORITHM_HIERARCHY, 
+  VALID_HASH_FUNCTIONS 
+} from '../../config/config_constants.js';
+
+// Check if we're in a browser environment
+const isBrowser = typeof window !== 'undefined';
+
+export default class HashValidator {
+  /**
+   * Constructor for HashValidator
+   */
+  constructor(content, hashAlgorithm = HashAlgorithm.DEFAULT) {
+    // Convert content to Buffer/Uint8Array if it's a string
+    this.content = SafeBuffer.isBuffer(content) 
+      ? content 
+      : encodeText(content);
+    
+    this.hashAlgorithm = this.normalizeHashAlgorithm(hashAlgorithm);
+    
+    // In browser environments, we can't synchronously compute crypto hashes
+    if (isBrowser) {
+      this.hashValue = "computing...";
+      this._computeHashAsync().then(hash => {
+        this.hashValue = hash;
+      });
+    } else {
+      this.hashValue = this.computeHash();
+    }
+  }
+  
+  /**
+   * Async computation of hash for browser environments
+   * @private
+   */
+  async _computeHashAsync() {
+    const hash = createHash(this.hashAlgorithm);
+    hash.update(this.content);
+    return await hash.digest('hex');
+  }
+
+  /**
+   * Normalizes the hash algorithm input
+   * @param {string|Object} hashAlgorithm - The hash algorithm to normalize
+   * @returns {string} Normalized hash algorithm
+   */
+  normalizeHashAlgorithm(hashAlgorithm) {
+    // Handle undefined or null input
+    if (hashAlgorithm === undefined || hashAlgorithm === null) {
+      return HashAlgorithm.DEFAULT || 'sha256';
+    }
+    
+    // If input is an object, try to extract the type
+    if (typeof hashAlgorithm === 'object') {
+      hashAlgorithm = hashAlgorithm.type || hashAlgorithm.value || HashAlgorithm.DEFAULT || 'sha256';
+    }
+    
+    // Convert to lowercase string and remove dashes for consistency
+    const normalizedAlgo = String(hashAlgorithm).toLowerCase().replace(/-/g, '');
+    
+    // Validate the hash algorithm
+    if (!HashValidator.isValidHashFunction(normalizedAlgo)) {
+      console.warn(`Invalid hash algorithm: ${normalizedAlgo}, using default instead`);
+      return HashAlgorithm.DEFAULT || 'sha256';
+    }
+    
+    return normalizedAlgo;
+  }
+
+  /**
+   * Validates a hash function
+   * @param {string} hashFunction - Hash function to validate
+   * @returns {boolean} Whether the hash function is valid
+   */
+  static isValidHashFunction(hashFunction) {
+    if (!hashFunction) return false;
+    
+    const normalizedFunc = String(hashFunction).toLowerCase().trim();
+    
+    // Accept both formats: with dashes (Web Crypto format) and without dashes (Node.js format)
+    const validAlgorithms = [
+      // Node.js format
+      'md5', 'sha1', 'sha224', 'sha256', 'sha384', 'sha512',
+      // Web Crypto format
+      'sha-1', 'sha-256', 'sha-384', 'sha-512'
+    ];
+    
+    return validAlgorithms.includes(normalizedFunc) || 
+           validAlgorithms.includes(normalizedFunc.replace(/-/g, ''));
+  }
+
+  /**
+   * Compute hash from content
+   * @returns {string|Promise<string>} Computed hash or promise to hash
+   */
+  computeHash() {
+    try {
+      const hash = createHash(this.hashAlgorithm);
+      hash.update(this.content);
+      const result = hash.digest('hex');
+      
+      // Handle the case where result is a Promise
+      if (result instanceof Promise) {
+        return "computing...";
+      }
+      
+      return result;
+    } catch (e) {
+      console.error('Error computing hash:', e);
+      return '';
+    }
+  }
+
+  /**
+   * Getter for hash value
+   * @returns {string} Hash value
+   */
+  getHashValue() {
+    return this.hashValue;
+  }
+
+  /**
+   * Getter for hash algorithm
+   * @returns {string} Hash algorithm
+   */
+  getHashAlgorithm() {
+    return this.hashAlgorithm;
+  }
+
+  /**
+   * Static method to compute hash
+   * @param {string|Buffer} content - Content to hash
+   * @param {string} hashAlgorithm - Algorithm to use
+   * @returns {string|Promise<string>} Computed hash or Promise of hash in browser
+   */
+  static computeHash(content, hashAlgorithm = HashAlgorithm.DEFAULT) {
+    const buffer = SafeBuffer.isBuffer(content) 
+      ? content 
+      : encodeText(content);
+    
+    const hash = createHash(hashAlgorithm);
+    hash.update(buffer);
+    return hash.digest('hex');
+  }
+
+  /**
+   * Validate hash against an expected hash
+   * @param {string} [expectedHash] - Expected hash value
+   * @returns {boolean|Promise<boolean>} True if hash matches, false otherwise
+   */
+  validate(expectedHash) {
+    if (!expectedHash) return false;
+    
+    if (isBrowser) {
+      // In browser, we need to handle async validation
+      return this._computeHashAsync().then(computedHash => {
+        return computedHash === expectedHash;
+      });
+    }
+    
+    return this.hashValue === expectedHash;
+  }
+
+  /**
+   * Return string representation
+   * @returns {string} String representation
+   */
+  toString() {
+    return `HashValidator(alg=${this.hashAlgorithm}, hash=${this.hashValue})`;
+  }
+
+  /**
+   * Gets the strength order of hash algorithms
+   * @returns {string[]} Ordered list of hash algorithms by strength
+   */
+  getHashAlgorithmStrengthOrder() {
+    return [
+      HashAlgorithm.MD5,
+      HashAlgorithm.SHA1,
+      HashAlgorithm.SHA224,
+      HashAlgorithm.SHA256,
+      HashAlgorithm.SHA384,
+      HashAlgorithm.SHA512
+    ];
+  }
+
+  /**
+   * Gets the strength index of a hash algorithm
+   * @param {string} algorithm - Hash algorithm
+   * @returns {number} Strength index
+   */
+  getHashAlgorithmStrength(algorithm) {
+    return this.getHashAlgorithmStrengthOrder().indexOf(algorithm);
+  }
+
+  /**
+   * Checks if one hash algorithm is stronger than another
+   * @param {string} current - Current hash algorithm
+   * @param {string} upgrade - Potential upgrade hash algorithm
+   * @returns {boolean} Whether the upgrade is stronger
+   */
+  isStrongerHashAlgorithm(current, upgrade) {
+    return this.getHashAlgorithmStrength(upgrade) > this.getHashAlgorithmStrength(current);
+  }
+
+  /**
+   * Determines the next hash algorithm in the upgrade path
+   * @param {string|Object} currentHashFunction - Current hash function
+   * @returns {string} Next hash algorithm
+   */
+  nextHashFunction(currentHashFunction) {
+    const strengthOrder = this.getHashAlgorithmStrengthOrder();
+
+    // Handle undefined or null input
+    if (currentHashFunction === undefined || currentHashFunction === null) {
+      return HashAlgorithm.MD5;
+    }
+
+    // Extract hash function value if it's an object
+    const currentHash = typeof currentHashFunction === 'object' 
+      ? currentHashFunction.value || currentHashFunction.type 
+      : currentHashFunction;
+
+    // Normalize to lowercase
+    const normalizedHash = (currentHash || '').toLowerCase();
+
+    // Find current index
+    const currentIndex = strengthOrder.indexOf(normalizedHash);
+
+    // Special case for SHA512 - wrap around to SHA1
+    if (normalizedHash === HashAlgorithm.SHA512) {
+      return HashAlgorithm.SHA1;
+    }
+
+    // If not found or last in order, return default (first hash function)
+    if (currentIndex === -1 || currentIndex === strengthOrder.length - 1) {
+      return HashAlgorithm[strengthOrder[0].toUpperCase()];
+    }
+
+    // Return the next hash function in the order as an enum
+    return HashAlgorithm[strengthOrder[currentIndex + 1].toUpperCase()];
+  }
+
+  /**
+   * Static method to get supported hash algorithms
+   * @returns {string[]} List of supported hash algorithms
+   */
+  static getSupportedAlgorithms() {
+    return [
+      HashAlgorithm.MD5,
+      HashAlgorithm.SHA1,
+      HashAlgorithm.SHA256,
+      HashAlgorithm.SHA512
+    ];
+  }
+
+  static compute_hash(content, hashAlgorithm = HashAlgorithm.DEFAULT) {
+    return HashValidator.computeHash(content, hashAlgorithm);
+  }
+
+  static HashAlgorithm = HashAlgorithm;
+  static HASH_ALGORITHM_HIERARCHY = HASH_ALGORITHM_HIERARCHY;
+  static VALID_HASH_FUNCTIONS = VALID_HASH_FUNCTIONS;
+}
+
+export { HashAlgorithm, HASH_ALGORITHM_HIERARCHY, VALID_HASH_FUNCTIONS };