neozipkit 0.1.1

package/src/server/platform/servercomponents/ZipKitOTS.ts

@@ -0,0 +1,313 @@
+// ======================================
+//	ZipKitOTS.ts
+//  Copyright (c) 2025 NeoWare, Inc. All rights reserved.
+// ======================================
+// ZipKit OpenTimestamps Routines
+
+"use server";
+"use strict";
+
+import moment from 'moment-timezone';
+
+// Create a singleton instance of OpenTimestamps  
+
+// May need to remove the global._bitcore object to stop the error:
+declare global {
+  var _bitcore: any;
+}
+if (global._bitcore) delete global._bitcore;
+
+let OTSInstance: any = null;
+
+async function getOTS() {
+  if (!OTSInstance) {
+    OTSInstance = (await import('opentimestamps')).default;
+  }
+  return OTSInstance;
+} 
+
+/**
+ * ZipKitOTS - OpenTimestamps utilities for NeoZip
+ * 
+ * This module provides functions for creating and verifying OpenTimestamps
+ * proofs for ZIP archives and their contents. It includes utilities for timestamp
+ * creation, verification, and serialization/deserialization.
+ */
+
+/**
+ * Interface for timestamp verification results
+ * Contains all necessary information about a verified timestamp
+ */
+export interface TimestampResult {
+  merkleRoot: string | null;        // The hash digest used for verification
+  ots: ArrayBuffer | null; // The OpenTimestamps proof data (allow both types)
+  verified: boolean;                // Whether verification was successful
+  results: any | null;              // Results returned from OpenTimestamps verification
+  error: string | null;             // Error message if verification failed
+  attestations: any | null;         // Parsed attestations in JSON string format
+  upgradedOts: ArrayBuffer | null; // Upgraded OTS data if available
+}
+
+// TimestampInfo object for adding to the database
+export interface TimestampInfo {
+  message: string;
+  results: string[];
+  attestDate: Date | null;
+  attestHeight: number | null;
+  submittedUri: string | null;
+  otsUpgraded: boolean;
+}
+
+/**
+ * Verifies a timestamp proof against a file hash
+ * 
+ * @param hashDigest - SHA-256 hash digest of the file or merkle root (hex string)
+ * @param otsData - The OpenTimestamps proof data
+ * @returns Promise with verification result or null on critical failure
+ * 
+ * @example
+ * // Verify a timestamp proof
+ * const hashDigest = "8a9d..."; // SHA-256 digest in hex format
+ * const result = await verifyTimestamp(hashDigest, otsBuffer);
+ * 
+ * if (result) {
+ *   if (result.error) {
+ *     console.error("Verification failed:", result.error);
+ *   } else {
+ *     console.log("Verification succeeded:", result.verified);
+ *     
+ *     if (result.upgradedOts) {
+ *       // Save the upgraded timestamp
+ *     }
+ *   }
+ * }
+ */
+export async function verifyTimestamp(
+  hashDigest: string | null, 
+  ots: ArrayBuffer | null, 
+): Promise<TimestampResult | { error: string } | null> {
+  if (!hashDigest || !ots) {
+    console.error('verifyTimestamp - Invalid parameters');
+    return null;
+  }
+
+  const tsResult: TimestampResult = {
+    merkleRoot: hashDigest,
+    ots: ots,
+    verified: false,
+    results: null,
+    error: null,
+    attestations: null,
+    upgradedOts: null,
+  };
+
+  try {
+    const OpenTimestamps = await getOTS();
+    // Convert the base64 string to a Buffer
+    // const _otsBuffer = Buffer.from(ots, 'base64');
+    const _otsBuffer = Buffer.from(ots);
+    const detachedOts = OpenTimestamps.DetachedTimestampFile.deserialize(_otsBuffer);
+
+    const digest = Buffer.from(hashDigest, 'hex');
+    const hashOts = OpenTimestamps.DetachedTimestampFile.fromHash(
+      new OpenTimestamps.Ops.OpSHA256(),
+      digest
+    );
+
+    // Check if the MetaStamp should be upgraded
+    const upgrade = await OpenTimestamps.upgrade(detachedOts);
+    if (upgrade) {
+      console.log('verifyTimestamp === Timestamp should be upgraded!');
+      tsResult.upgradedOts = detachedOts.serializeToBytes();
+    }
+
+    // Verify the MetaStamp
+    tsResult.results = await OpenTimestamps.verify(detachedOts, hashOts, {
+      ignoreBitcoinNode: true,    // Don't check for local Bitcoin node
+      timeout: 5000
+    });
+
+    var _attest: any = [];
+    detachedOts.timestamp.allAttestations().forEach((attestation: any) => {
+      if (attestation instanceof OpenTimestamps.Notary.UnknownAttestation) {
+        console.log('Unknown attestation type');
+      } else {
+        // console.log(attestation);
+        _attest.push(attestation);
+      }
+    });
+    tsResult.attestations = JSON.stringify(_attest);
+
+    // Check if the results show a verified timestamp
+    if (Object.keys(tsResult.results).length < 1) {
+      tsResult.results = null;
+      tsResult.verified = false;
+    } else {
+      tsResult.verified = true;
+    }
+
+    console.log('verifyTimestamp === tsResult: ', tsResult);    
+    return tsResult;
+  } catch (error: any) {
+    let errMsg = error?.message || 'Timestamp Verification Failed!';
+    if (errMsg.indexOf('ESOCKETTIMEDOUT') != -1) {
+      errMsg = 'Server timed out, Try again in a few minutes.';
+    } else if (errMsg.indexOf('502') != -1) {
+      errMsg = 'Server failed to respond, Try again in a few minutes.';
+    } else if (errMsg.indexOf('ECONNRESET') != -1 ) {
+      errMsg = 'Server connection reset, Try again in a few minutes.';
+    }
+    return { error: errMsg };
+  }
+}
+
+/**
+ * Creates a timestamp proof for a file hash using OpenTimestamps
+ * 
+ * @param hashDigest - SHA-256 hash digest of the file or merkle root (hex string)
+ * @returns Promise containing the OpenTimestamps proof or null on failure
+ * 
+ * @example
+ * // Create a timestamp for a file hash
+ * const hashDigest = "8a9d..."; // SHA-256 digest in hex format
+ * const timestampProof = await createTimestamp(hashDigest);
+ * 
+ * if (timestampProof) {
+ *   // Save the timestamp proof to storage
+ * }
+ */
+export async function createTimestamp(hashDigest: string | null): Promise<Buffer | null> {
+  if (!hashDigest) return null;
+
+  try {
+    const OpenTimestamps = await getOTS();
+        
+    // Convert hex string to Buffer
+    const hashBuffer = Buffer.from(hashDigest, 'hex');
+    
+    // Create detached timestamp file
+    const detached = OpenTimestamps.DetachedTimestampFile.fromHash(
+      new OpenTimestamps.Ops.OpSHA256(),
+      hashBuffer
+    );
+
+    // Create the timestamp
+    await OpenTimestamps.stamp(detached);
+    
+    // Return the serialized timestamp
+    return Buffer.from(detached.serializeToBytes());
+
+  } catch (error) {
+    console.error('Error creating timestamp:', error);
+    throw new Error('Error creating timestamp');
+  }
+}
+
+/**
+ * Result of deserializing an OpenTimestamps proof
+ */
+export interface DeserializeOtsResult {
+  attestStr: string | null;         // Human-readable attestation string
+  needsUpdateMsg: string | null;    // Message if timestamp needs upgrading
+  attestationValues: any[];         // Array of attestation details
+}
+
+/**
+ * Deserializes timestamp metadata to extract attestation information
+ * Used for generating timestamp certificates and displaying verification details
+ * 
+ * @param tsResult - Timestamp verification result to deserialize
+ * @returns JSON string of deserialized data or null on failure
+ */
+export async function deserializeOts(
+  tsResult: TimestampResult, 
+) : Promise< string | null > {
+
+  let result: DeserializeOtsResult = {
+    attestStr: null,
+    needsUpdateMsg: null,
+    attestationValues: [],
+  };
+
+  for (const chain in tsResult.results) {
+    let _results = tsResult.results[chain];
+    const _attestDate = moment(_results.timestamp * 1000).tz(moment.tz.guess()).format('MM-DD-YYYY hh:mma z');
+    const blockchain = chain.charAt(0).toUpperCase() + chain.slice(1);
+    result.attestStr = `<b>${blockchain} block ${_results.height}</b> attests existence as of <b>${_attestDate}</b>`;
+  };
+
+  let timestamp = tsResult.ots;
+  if (tsResult.upgradedOts != null) {
+    result.needsUpdateMsg = "This Zip file requires updated Timestamp Metadata!";
+    // Use the updated timestamp metadata
+    timestamp = tsResult.upgradedOts;
+  }
+
+  // Extract the attestation values from the timestamp metadata
+  if (!timestamp) return null;
+  const OpenTimestamps = await getOTS();  
+  const detached = OpenTimestamps.DetachedTimestampFile.deserialize(Buffer.from(timestamp));
+  const infoResult = OpenTimestamps.info(detached);
+
+  // Extract all transaction IDs using a regular expression
+  const transactionIdMatches = [...infoResult.matchAll(/transaction id ([a-f0-9]+)/gi)];
+  const transactionIds = transactionIdMatches.map(match => match[1]);
+
+  // Extract the value inside the parentheses using a regular expression
+  const blockHeightMatches = [...infoResult.matchAll(/verify BitcoinBlockHeaderAttestation\((\d+)\)/g)];
+  const blockHeights = blockHeightMatches.map(match => match[1]);
+
+  // Extract all values after "block merkle root" using a regular expression
+  const merkleRootMatches = [...infoResult.matchAll(/block merkle root ([a-f0-9]+)/gi)];
+  const merkleRoots = merkleRootMatches.map(match => match[1]);
+
+  // Group the values in a loop
+  result.attestationValues = [];
+  if (transactionIds.length === blockHeights.length && transactionIds.length === merkleRoots.length) {
+    for (let i = 0; i < transactionIds.length; i++) {
+      result.attestationValues.push({
+        blockHeight: blockHeights[i],
+        transactionId: transactionIds[i],
+        merkleRoot: merkleRoots[i]
+      });
+    }
+
+    // Sort the grouped values by blockHeight in ascending order
+    result.attestationValues.sort((a, b) => a.blockHeight - b.blockHeight);
+  }
+
+  return JSON.stringify(result);
+}
+
+// Parse the verifyResult into a TimestampInfo object
+export async function parseVerifyResult(verifyResult: TimestampResult): Promise<TimestampInfo> {
+  let tsInfo: TimestampInfo = {
+    message: '',
+    results: [],
+    attestDate: null,
+    attestHeight: null,
+    submittedUri: null,
+    otsUpgraded: false
+  };
+
+  for (const chain in verifyResult?.results) {
+    let _results = verifyResult.results[chain];
+    const _date = moment(_results.timestamp * 1000)
+      .tz('UTC')
+      .format('MM-DD-YYYY hh:mma z');
+    const _blockchain = chain.charAt(0).toUpperCase() + chain.slice(1);
+    tsInfo.message = 'Validated - ' + _blockchain + ' block ' + _results.height + ' attests existence as of ' + _date;
+    if (tsInfo.attestHeight == null) {
+      tsInfo.attestDate = new Date(_results.timestamp * 1000);
+      tsInfo.attestHeight = _results.height;
+    }
+    tsInfo.results.push(tsInfo.message);
+  };
+
+  if (verifyResult?.upgradedOts) {
+    tsInfo.otsUpgraded = true;
+    tsInfo.results.push('Notice: Please select "Upgrade Timestamp" to save the upgraded timestamp.');
+  }
+  
+  return tsInfo;  
+}

package/src/server/platform/servercomponents/opentimestamps.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Type declarations for OpenTimestamps module
+ */
+declare module 'opentimestamps' {
+  namespace stamp {
+    function create(fileBuffer: Buffer): Promise<Buffer>;
+  }
+
+  namespace verify {
+    function verifyTimestamp(ots: Buffer, fileHash: Buffer): Promise<any>;
+  }
+
+  namespace utils {
+    function hexToBytes(hex: string): number[];
+    function bytesToHex(bytes: number[]): string;
+  }
+
+  export default {
+    stamp,
+    verify,
+    utils
+  };
+}