@bcts/provenance-mark 1.0.0-alpha.8 → 1.0.0-beta.0

package/src/utils.ts

@@ -1,13 +1,14 @@
 /**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ *
  * Utility functions for byte array conversions.
  *
  * These functions provide cross-platform support for common byte manipulation
  * operations needed in provenance mark encoding.
  */
 
-// Declare Node.js types for environments where they might not be available
-declare const require: ((module: string) => unknown) | undefined;
-
 /**
  * Convert a Uint8Array to a lowercase hexadecimal string.
  *
@@ -50,26 +51,13 @@ export function hexToBytes(hex: string): Uint8Array {
  * @returns A base64-encoded string
  */
 export function toBase64(data: Uint8Array): string {
-  // Use globalThis.btoa for browser/modern Node.js compatibility
-  const globalBtoa = globalThis.btoa as ((data: string) => string) | undefined;
-  if (typeof globalBtoa === "function") {
-    // Convert bytes to binary string without spread operator to avoid
-    // call stack limits for large arrays
-    let binary = "";
-    for (const byte of data) {
-      binary += String.fromCharCode(byte);
-    }
-    return globalBtoa(binary);
+  // Convert bytes to binary string without spread operator to avoid
+  // call stack limits for large arrays
+  let binary = "";
+  for (const byte of data) {
+    binary += String.fromCharCode(byte);
   }
-  // Node.js environment (fallback for Node < 18)
-  const requireFn = require;
-  if (typeof requireFn === "function") {
-    const { Buffer: NodeBuffer } = requireFn("buffer") as {
-      Buffer: { from: (data: Uint8Array) => { toString: (encoding: string) => string } };
-    };
-    return NodeBuffer.from(data).toString("base64");
-  }
-  throw new Error("btoa not available and require is not defined");
+  return btoa(binary);
 }
 
 /**
@@ -81,23 +69,64 @@ export function toBase64(data: Uint8Array): string {
  * @returns The decoded byte array
  */
 export function fromBase64(base64: string): Uint8Array {
-  // Use globalThis.atob for browser/modern Node.js compatibility
-  const globalAtob = globalThis.atob as ((data: string) => string) | undefined;
-  if (typeof globalAtob === "function") {
-    const binary = globalAtob(base64);
-    const bytes = new Uint8Array(binary.length);
-    for (let i = 0; i < binary.length; i++) {
-      bytes[i] = binary.charCodeAt(i);
-    }
-    return bytes;
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
   }
-  // Node.js environment (fallback for Node < 18)
-  const requireFn = require;
-  if (typeof requireFn === "function") {
-    const { Buffer: NodeBuffer } = requireFn("buffer") as {
-      Buffer: { from: (data: string, encoding: string) => Uint8Array };
-    };
-    return new Uint8Array(NodeBuffer.from(base64, "base64"));
+  return bytes;
+}
+
+/**
+ * Parse a base64-encoded provenance seed.
+ *
+ * Mirrors Rust's `parse_seed` user helper
+ * (`provenance-mark-rust/src/util.rs:34-38`), which round-trips the
+ * input through serde JSON / `deserialize_block` and so requires the
+ * decoded bytes to be exactly {@link PROVENANCE_SEED_LENGTH} (32) long.
+ * The TS equivalent decodes the base64 directly and delegates to
+ * {@link ProvenanceSeed.fromBytes} for the length check.
+ *
+ * @param s - Base64-encoded 32-byte seed string.
+ * @returns The decoded {@link ProvenanceSeed}.
+ * @throws {ProvenanceMarkError} If the input is not valid base64 or the
+ *   decoded length is not exactly 32 bytes.
+ */
+export function parseSeed(s: string): ProvenanceSeed {
+  let bytes: Uint8Array;
+  try {
+    bytes = fromBase64(s);
+  } catch (e) {
+    throw new ProvenanceMarkError(
+      ProvenanceMarkErrorType.Base64Error,
+      "invalid base64 encoding for provenance seed",
+      { details: e instanceof Error ? e.message : String(e) },
+    );
   }
-  throw new Error("atob not available and require is not defined");
+  return ProvenanceSeed.fromBytes(bytes);
 }
+
+/**
+ * Parse a date string (`YYYY-MM-DD` or full RFC 3339) into a `Date`.
+ *
+ * Mirrors Rust's `parse_date` user helper
+ * (`provenance-mark-rust/src/util.rs:40-42`), which delegates to
+ * `Date::from_string` (the same parser the JSON deserializer uses).
+ * Accepts the same shapes the Rust parser does:
+ *
+ * - `YYYY-MM-DD` (interpreted as UTC midnight, matching JS spec).
+ * - Full RFC 3339, e.g. `2023-06-20T15:30:45Z` or
+ *   `2023-06-20T15:30:45.123Z`.
+ *
+ * @throws {ProvenanceMarkError} If the input fails to parse.
+ */
+export function parseDate(s: string): Date {
+  const date = new Date(s);
+  if (Number.isNaN(date.getTime())) {
+    throw new ProvenanceMarkError(ProvenanceMarkErrorType.InvalidDate, `cannot parse date: ${s}`);
+  }
+  return date;
+}
+
+import { ProvenanceSeed } from "./seed.js";
+import { ProvenanceMarkError, ProvenanceMarkErrorType } from "./error.js";

package/src/validate.ts

@@ -1,6 +1,13 @@
+/**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ */
+
 // Ported from provenance-mark-rust/src/validate.rs
 
 import type { ProvenanceMark } from "./mark.js";
+import { ProvenanceMarkError } from "./error.js";
 
 /**
  * Format for validation report output.
@@ -186,7 +193,7 @@ function formatText(report: ValidationReport): string {
       // Report each mark in the sequence
       for (const flaggedMark of seq.marks) {
         const mark = flaggedMark.mark;
-        const shortId = mark.identifier();
+        const shortId = mark.idHex().slice(0, 8);
         const seqNum = mark.seq();
 
         // Build the mark line with annotations
@@ -257,23 +264,47 @@ export function formatReport(report: ValidationReport, format: ValidationReportF
  */
 function reportToJSON(report: ValidationReport): unknown {
   return {
-    marks: report.marks.map((m) => m.toUrlEncoding()),
+    marks: report.marks.map((m) => m.urString()),
     chains: report.chains.map((chain) => ({
       chain_id: hexEncode(chain.chainId),
       has_genesis: chain.hasGenesis,
-      marks: chain.marks.map((m) => m.toUrlEncoding()),
+      marks: chain.marks.map((m) => m.urString()),
       sequences: chain.sequences.map((seq) => ({
         start_seq: seq.startSeq,
         end_seq: seq.endSeq,
         marks: seq.marks.map((fm) => ({
-          mark: fm.mark.toUrlEncoding(),
-          issues: fm.issues,
+          mark: fm.mark.urString(),
+          issues: fm.issues.map(issueToJSON),
         })),
       })),
     })),
   };
 }
 
+/**
+ * Convert a ValidationIssue to JSON matching Rust's serde format.
+ *
+ * Rust uses `#[serde(tag = "type", content = "data")]` which wraps
+ * struct variant data in a `"data"` field. Unit variants have no
+ * `"data"` field.
+ */
+function issueToJSON(issue: ValidationIssue): unknown {
+  switch (issue.type) {
+    case "HashMismatch":
+      return { type: "HashMismatch", data: { expected: issue.expected, actual: issue.actual } };
+    case "SequenceGap":
+      return { type: "SequenceGap", data: { expected: issue.expected, actual: issue.actual } };
+    case "DateOrdering":
+      return { type: "DateOrdering", data: { previous: issue.previous, next: issue.next } };
+    case "KeyMismatch":
+      return { type: "KeyMismatch" };
+    case "NonGenesisAtZero":
+      return { type: "NonGenesisAtZero" };
+    case "InvalidGenesisKey":
+      return { type: "InvalidGenesisKey" };
+  }
+}
+
 /**
  * Build sequence bins for a chain.
  */
@@ -301,8 +332,14 @@ function buildSequenceBins(marks: ProvenanceMark[]): SequenceReport[] {
           sequences.push(createSequenceReport(currentSequence));
         }
 
-        // Parse the error to determine the issue type
-        const issue = parseValidationError(e, prev, mark);
+        // Extract structured issue directly from the error
+        // Matches Rust: Error::Validation(v) => v, _ => ValidationIssue::KeyMismatch
+        let issue: ValidationIssue;
+        if (e instanceof ProvenanceMarkError && e.details?.["validationIssue"] !== undefined) {
+          issue = e.details["validationIssue"] as ValidationIssue;
+        } else {
+          issue = { type: "KeyMismatch" }; // Fallback
+        }
 
         // Start new sequence with this mark, flagged with the issue
         currentSequence = [{ mark, issues: [issue] }];
@@ -318,53 +355,6 @@ function buildSequenceBins(marks: ProvenanceMark[]): SequenceReport[] {
   return sequences;
 }
 
-/**
- * Parse a validation error into a ValidationIssue.
- */
-function parseValidationError(
-  e: unknown,
-  prev: ProvenanceMark,
-  next: ProvenanceMark,
-): ValidationIssue {
-  const message = e instanceof Error ? e.message : "";
-
-  if (message !== "" && message.includes("non-genesis mark at sequence 0")) {
-    return { type: "NonGenesisAtZero" };
-  }
-  if (message !== "" && message.includes("genesis mark must have key equal to chain_id")) {
-    return { type: "InvalidGenesisKey" };
-  }
-  if (message !== "" && message.includes("sequence gap")) {
-    const seqGapRegex = /expected (\d+), got (\d+)/;
-    const match = seqGapRegex.exec(message);
-    if (match !== null) {
-      return {
-        type: "SequenceGap",
-        expected: parseInt(match[1], 10),
-        actual: parseInt(match[2], 10),
-      };
-    }
-  }
-  if (message !== "" && message.includes("date ordering")) {
-    return {
-      type: "DateOrdering",
-      previous: prev.date().toISOString(),
-      next: next.date().toISOString(),
-    };
-  }
-  if (message !== "" && message.includes("hash mismatch")) {
-    const hashRegex = /expected: (\w+), actual: (\w+)/;
-    const match = hashRegex.exec(message);
-    if (match !== null) {
-      return { type: "HashMismatch", expected: match[1], actual: match[2] };
-    }
-    return { type: "HashMismatch", expected: "", actual: "" };
-  }
-
-  // Fallback
-  return { type: "KeyMismatch" };
-}
-
 /**
  * Create a sequence report from flagged marks.
  */
@@ -379,10 +369,11 @@ function createSequenceReport(marks: FlaggedMark[]): SequenceReport {
  */
 export function validate(marks: ProvenanceMark[]): ValidationReport {
   // Deduplicate exact duplicates
+  // Matches Rust semantics: PartialEq compares (res, message())
   const seen = new Set<string>();
   const deduplicatedMarks: ProvenanceMark[] = [];
   for (const mark of marks) {
-    const key = mark.toUrlEncoding();
+    const key = `${mark.res()}:${hexEncode(mark.message())}`;
     if (!seen.has(key)) {
       seen.add(key);
       deduplicatedMarks.push(mark);
@@ -422,8 +413,23 @@ export function validate(marks: ProvenanceMark[]): ValidationReport {
     });
   }
 
-  // Sort chains by chain ID for consistent output
-  chains.sort((a, b) => hexEncode(a.chainId).localeCompare(hexEncode(b.chainId)));
+  // Sort chains by chain ID for consistent output.
+  //
+  // Mirrors Rust `chains.sort_by_key(|c| c.chain_id.clone())` which
+  // uses `Vec<u8>::cmp` (lexicographic byte comparison). We compare
+  // hex-encoded chain IDs with raw `<`/`>` rather than `localeCompare`,
+  // because hex-digit ordering is locale-independent under JS `<`/`>`
+  // (UTF-16 code-unit compare) but `localeCompare` is locale-aware and
+  // could in principle drift on a non-default locale. Using a pure
+  // bytewise compare here keeps the chain order byte-identical to Rust
+  // regardless of locale.
+  chains.sort((a, b) => {
+    const aHex = hexEncode(a.chainId);
+    const bHex = hexEncode(b.chainId);
+    if (aHex < bHex) return -1;
+    if (aHex > bHex) return 1;
+    return 0;
+  });
 
   return { marks: deduplicatedMarks, chains };
 }

package/src/xoshiro256starstar.ts

@@ -1,3 +1,9 @@
+/**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ */
+
 // Ported from provenance-mark-rust/src/xoshiro256starstar.rs
 
 /**