@bcts/provenance-mark 1.0.0-alpha.10

package/src/error.ts

@@ -0,0 +1,141 @@
+// Ported from provenance-mark-rust/src/error.rs
+
+/**
+ * Error types for Provenance Mark operations.
+ */
+export enum ProvenanceMarkErrorType {
+  /** Invalid Seed length */
+  InvalidSeedLength = "InvalidSeedLength",
+  /** Duplicate key */
+  DuplicateKey = "DuplicateKey",
+  /** Missing key */
+  MissingKey = "MissingKey",
+  /** Invalid key */
+  InvalidKey = "InvalidKey",
+  /** Extra keys */
+  ExtraKeys = "ExtraKeys",
+  /** Invalid key length for the given resolution */
+  InvalidKeyLength = "InvalidKeyLength",
+  /** Invalid next key length for the given resolution */
+  InvalidNextKeyLength = "InvalidNextKeyLength",
+  /** Invalid chain ID length for the given resolution */
+  InvalidChainIdLength = "InvalidChainIdLength",
+  /** Invalid message length for the given resolution */
+  InvalidMessageLength = "InvalidMessageLength",
+  /** Invalid CBOR data in info field */
+  InvalidInfoCbor = "InvalidInfoCbor",
+  /** Date out of range for serialization */
+  DateOutOfRange = "DateOutOfRange",
+  /** Invalid date components */
+  InvalidDate = "InvalidDate",
+  /** Missing required URL parameter */
+  MissingUrlParameter = "MissingUrlParameter",
+  /** Year out of range for 2-byte serialization */
+  YearOutOfRange = "YearOutOfRange",
+  /** Invalid month or day */
+  InvalidMonthOrDay = "InvalidMonthOrDay",
+  /** Resolution serialization error */
+  ResolutionError = "ResolutionError",
+  /** Bytewords encoding/decoding error */
+  BytewordsError = "BytewordsError",
+  /** CBOR encoding/decoding error */
+  CborError = "CborError",
+  /** URL parsing error */
+  UrlError = "UrlError",
+  /** Base64 decoding error */
+  Base64Error = "Base64Error",
+  /** JSON serialization error */
+  JsonError = "JsonError",
+  /** Integer conversion error */
+  IntegerConversionError = "IntegerConversionError",
+  /** Validation error */
+  ValidationError = "ValidationError",
+}
+
+/**
+ * Error class for Provenance Mark operations.
+ */
+export class ProvenanceMarkError extends Error {
+  readonly type: ProvenanceMarkErrorType;
+  readonly details?: Record<string, unknown> | undefined;
+
+  constructor(type: ProvenanceMarkErrorType, message?: string, details?: Record<string, unknown>) {
+    const fullMessage =
+      message !== undefined && message !== ""
+        ? `${type}: ${message}`
+        : ProvenanceMarkError.defaultMessage(type, details);
+    super(fullMessage);
+    this.name = "ProvenanceMarkError";
+    this.type = type;
+    this.details = details;
+  }
+
+  private static defaultMessage(
+    type: ProvenanceMarkErrorType,
+    details?: Record<string, unknown>,
+  ): string {
+    const d = (key: string): string => {
+      const value = details?.[key];
+      if (value === undefined || value === null) return "?";
+      if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+        return String(value);
+      }
+      return JSON.stringify(value);
+    };
+    switch (type) {
+      case ProvenanceMarkErrorType.InvalidSeedLength:
+        return `invalid seed length: expected 32 bytes, got ${d("actual")} bytes`;
+      case ProvenanceMarkErrorType.DuplicateKey:
+        return `duplicate key: ${d("key")}`;
+      case ProvenanceMarkErrorType.MissingKey:
+        return `missing key: ${d("key")}`;
+      case ProvenanceMarkErrorType.InvalidKey:
+        return `invalid key: ${d("key")}`;
+      case ProvenanceMarkErrorType.ExtraKeys:
+        return `wrong number of keys: expected ${d("expected")}, got ${d("actual")}`;
+      case ProvenanceMarkErrorType.InvalidKeyLength:
+        return `invalid key length: expected ${d("expected")}, got ${d("actual")}`;
+      case ProvenanceMarkErrorType.InvalidNextKeyLength:
+        return `invalid next key length: expected ${d("expected")}, got ${d("actual")}`;
+      case ProvenanceMarkErrorType.InvalidChainIdLength:
+        return `invalid chain ID length: expected ${d("expected")}, got ${d("actual")}`;
+      case ProvenanceMarkErrorType.InvalidMessageLength:
+        return `invalid message length: expected at least ${d("expected")}, got ${d("actual")}`;
+      case ProvenanceMarkErrorType.InvalidInfoCbor:
+        return "invalid CBOR data in info field";
+      case ProvenanceMarkErrorType.DateOutOfRange:
+        return `date out of range: ${d("details")}`;
+      case ProvenanceMarkErrorType.InvalidDate:
+        return `invalid date: ${d("details")}`;
+      case ProvenanceMarkErrorType.MissingUrlParameter:
+        return `missing required URL parameter: ${d("parameter")}`;
+      case ProvenanceMarkErrorType.YearOutOfRange:
+        return `year out of range for 2-byte serialization: must be between 2023-2150, got ${d("year")}`;
+      case ProvenanceMarkErrorType.InvalidMonthOrDay:
+        return `invalid month (${d("month")}) or day (${d("day")}) for year ${d("year")}`;
+      case ProvenanceMarkErrorType.ResolutionError:
+        return `resolution serialization error: ${d("details")}`;
+      case ProvenanceMarkErrorType.BytewordsError:
+        return `bytewords error: ${d("message")}`;
+      case ProvenanceMarkErrorType.CborError:
+        return `CBOR error: ${d("message")}`;
+      case ProvenanceMarkErrorType.UrlError:
+        return `URL parsing error: ${d("message")}`;
+      case ProvenanceMarkErrorType.Base64Error:
+        return `base64 decoding error: ${d("message")}`;
+      case ProvenanceMarkErrorType.JsonError:
+        return `JSON error: ${d("message")}`;
+      case ProvenanceMarkErrorType.IntegerConversionError:
+        return `integer conversion error: ${d("message")}`;
+      case ProvenanceMarkErrorType.ValidationError:
+        return `validation error: ${d("message")}`;
+      default:
+        return type;
+    }
+  }
+}
+
+/**
+ * Result type for Provenance Mark operations.
+ */
+export type ProvenanceMarkResult<T> = T;

package/src/generator.ts

@@ -0,0 +1,182 @@
+// Ported from provenance-mark-rust/src/generator.rs
+
+import { toBase64, fromBase64, bytesToHex } from "./utils.js";
+import { type Cbor } from "@bcts/dcbor";
+
+import { ProvenanceMarkError, ProvenanceMarkErrorType } from "./error.js";
+import { type ProvenanceMarkResolution, linkLength } from "./resolution.js";
+import { ProvenanceSeed } from "./seed.js";
+import { RngState } from "./rng-state.js";
+import { sha256 } from "./crypto-utils.js";
+import { Xoshiro256StarStar } from "./xoshiro256starstar.js";
+import { ProvenanceMark } from "./mark.js";
+
+/**
+ * Generator for creating provenance mark chains.
+ */
+export class ProvenanceMarkGenerator {
+  private readonly _res: ProvenanceMarkResolution;
+  private readonly _seed: ProvenanceSeed;
+  private readonly _chainId: Uint8Array;
+  private _nextSeq: number;
+  private _rngState: RngState;
+
+  private constructor(
+    res: ProvenanceMarkResolution,
+    seed: ProvenanceSeed,
+    chainId: Uint8Array,
+    nextSeq: number,
+    rngState: RngState,
+  ) {
+    this._res = res;
+    this._seed = seed;
+    this._chainId = chainId;
+    this._nextSeq = nextSeq;
+    this._rngState = rngState;
+  }
+
+  res(): ProvenanceMarkResolution {
+    return this._res;
+  }
+
+  seed(): ProvenanceSeed {
+    return this._seed;
+  }
+
+  chainId(): Uint8Array {
+    return new Uint8Array(this._chainId);
+  }
+
+  nextSeq(): number {
+    return this._nextSeq;
+  }
+
+  rngState(): RngState {
+    return this._rngState;
+  }
+
+  /**
+   * Create a new generator with a seed.
+   */
+  static newWithSeed(res: ProvenanceMarkResolution, seed: ProvenanceSeed): ProvenanceMarkGenerator {
+    // Definitely don't use the bare seed as the chain ID!
+    const digest1 = sha256(seed.toBytes());
+    const chainId = digest1.slice(0, linkLength(res));
+    const digest2 = sha256(digest1);
+    return ProvenanceMarkGenerator.new(res, seed, chainId, 0, RngState.fromBytes(digest2));
+  }
+
+  /**
+   * Create a new generator with a passphrase.
+   */
+  static newWithPassphrase(
+    res: ProvenanceMarkResolution,
+    passphrase: string,
+  ): ProvenanceMarkGenerator {
+    const seed = ProvenanceSeed.newWithPassphrase(passphrase);
+    return ProvenanceMarkGenerator.newWithSeed(res, seed);
+  }
+
+  /**
+   * Create a new generator with custom random data.
+   */
+  static newUsing(res: ProvenanceMarkResolution, randomData: Uint8Array): ProvenanceMarkGenerator {
+    const seed = ProvenanceSeed.newUsing(randomData);
+    return ProvenanceMarkGenerator.newWithSeed(res, seed);
+  }
+
+  /**
+   * Create a new generator with random seed.
+   */
+  static newRandom(res: ProvenanceMarkResolution): ProvenanceMarkGenerator {
+    const seed = ProvenanceSeed.new();
+    return ProvenanceMarkGenerator.newWithSeed(res, seed);
+  }
+
+  /**
+   * Create a new generator with all parameters.
+   */
+  static new(
+    res: ProvenanceMarkResolution,
+    seed: ProvenanceSeed,
+    chainId: Uint8Array,
+    nextSeq: number,
+    rngState: RngState,
+  ): ProvenanceMarkGenerator {
+    const linkLen = linkLength(res);
+    if (chainId.length !== linkLen) {
+      throw new ProvenanceMarkError(ProvenanceMarkErrorType.InvalidChainIdLength, undefined, {
+        expected: linkLen,
+        actual: chainId.length,
+      });
+    }
+    return new ProvenanceMarkGenerator(res, seed, chainId, nextSeq, rngState);
+  }
+
+  /**
+   * Generate the next provenance mark in the chain.
+   */
+  next(date: Date, info?: Cbor): ProvenanceMark {
+    const data = this._rngState.toBytes();
+    const rng = Xoshiro256StarStar.fromData(data);
+
+    const seq = this._nextSeq;
+    this._nextSeq += 1;
+
+    let key: Uint8Array;
+    if (seq === 0) {
+      key = new Uint8Array(this._chainId);
+    } else {
+      // The randomness generated by the PRNG should be portable across implementations
+      key = rng.nextBytes(linkLength(this._res));
+      this._rngState = RngState.fromBytes(rng.toData());
+    }
+
+    // Clone the RNG for generating next_key
+    const nextRngData = rng.toData();
+    const nextRng = Xoshiro256StarStar.fromData(nextRngData);
+    const nextKey = nextRng.nextBytes(linkLength(this._res));
+
+    return ProvenanceMark.new(
+      this._res,
+      key,
+      nextKey,
+      new Uint8Array(this._chainId),
+      seq,
+      date,
+      info,
+    );
+  }
+
+  /**
+   * String representation.
+   */
+  toString(): string {
+    return `ProvenanceMarkGenerator(chainID: ${bytesToHex(this._chainId)}, res: ${this._res}, seed: ${this._seed.hex()}, nextSeq: ${this._nextSeq})`;
+  }
+
+  /**
+   * JSON serialization.
+   */
+  toJSON(): Record<string, unknown> {
+    return {
+      res: this._res,
+      seed: toBase64(this._seed.toBytes()),
+      chainID: toBase64(this._chainId),
+      nextSeq: this._nextSeq,
+      rngState: toBase64(this._rngState.toBytes()),
+    };
+  }
+
+  /**
+   * Create from JSON object.
+   */
+  static fromJSON(json: Record<string, unknown>): ProvenanceMarkGenerator {
+    const res = json["res"] as ProvenanceMarkResolution;
+    const seed = ProvenanceSeed.fromBytes(fromBase64(json["seed"] as string));
+    const chainId = fromBase64(json["chainID"] as string);
+    const nextSeq = json["nextSeq"] as number;
+    const rngState = RngState.fromBytes(fromBase64(json["rngState"] as string));
+    return ProvenanceMarkGenerator.new(res, seed, chainId, nextSeq, rngState);
+  }
+}

package/src/index.ts

@@ -0,0 +1,90 @@
+// Ported from provenance-mark-rust
+
+// Error types
+export {
+  ProvenanceMarkError,
+  ProvenanceMarkErrorType,
+  type ProvenanceMarkResult,
+} from "./error.js";
+
+// Resolution types and utilities
+export {
+  ProvenanceMarkResolution,
+  resolutionToNumber,
+  resolutionFromNumber,
+  linkLength,
+  seqBytesLength,
+  dateBytesLength,
+  fixedLength,
+  keyRange,
+  chainIdRange,
+  hashRange,
+  seqBytesRange,
+  dateBytesRange,
+  infoRangeStart,
+  serializeDate,
+  deserializeDate,
+  serializeSeq,
+  deserializeSeq,
+  resolutionToString,
+  resolutionToCbor,
+  resolutionFromCbor,
+} from "./resolution.js";
+
+// Date utilities
+export {
+  type SerializableDate,
+  serialize2Bytes,
+  deserialize2Bytes,
+  serialize4Bytes,
+  deserialize4Bytes,
+  serialize6Bytes,
+  deserialize6Bytes,
+  rangeOfDaysInMonth,
+  dateToIso8601,
+  dateFromIso8601,
+  dateToDateString,
+} from "./date.js";
+
+// Crypto utilities
+export {
+  SHA256_SIZE,
+  sha256,
+  sha256Prefix,
+  extendKey,
+  hkdfHmacSha256,
+  obfuscate,
+} from "./crypto-utils.js";
+
+// PRNG
+export { Xoshiro256StarStar } from "./xoshiro256starstar.js";
+
+// RNG State
+export { RngState, RNG_STATE_LENGTH } from "./rng-state.js";
+
+// Seed
+export { ProvenanceSeed, PROVENANCE_SEED_LENGTH } from "./seed.js";
+
+// Mark
+export { ProvenanceMark } from "./mark.js";
+
+// Generator
+export { ProvenanceMarkGenerator } from "./generator.js";
+
+// Validation
+export {
+  ValidationReportFormat,
+  type ValidationIssue,
+  type FlaggedMark,
+  type SequenceReport,
+  type ChainReport,
+  type ValidationReport,
+  formatValidationIssue,
+  chainIdHex,
+  hasIssues,
+  formatReport,
+  validate,
+} from "./validate.js";
+
+// Mark Info
+export { ProvenanceMarkInfo } from "./mark-info.js";

package/src/mark-info.ts

@@ -0,0 +1,126 @@
+// Ported from provenance-mark-rust/src/mark_info.rs
+
+import { UR } from "@bcts/uniform-resources";
+import { decodeCbor, cborData } from "@bcts/dcbor";
+import { PROVENANCE_MARK } from "@bcts/tags";
+
+import { ProvenanceMark } from "./mark.js";
+
+/**
+ * Wrapper for a provenance mark with additional display information.
+ */
+export class ProvenanceMarkInfo {
+  private readonly _mark: ProvenanceMark;
+  private readonly _ur: UR;
+  private readonly _bytewords: string;
+  private readonly _bytemoji: string;
+  private readonly _comment: string;
+
+  private constructor(
+    mark: ProvenanceMark,
+    ur: UR,
+    bytewords: string,
+    bytemoji: string,
+    comment: string,
+  ) {
+    this._mark = mark;
+    this._ur = ur;
+    this._bytewords = bytewords;
+    this._bytemoji = bytemoji;
+    this._comment = comment;
+  }
+
+  /**
+   * Create a new ProvenanceMarkInfo from a mark.
+   */
+  static new(mark: ProvenanceMark, comment = ""): ProvenanceMarkInfo {
+    const tagName = PROVENANCE_MARK.name;
+    if (tagName === undefined) {
+      throw new Error("PROVENANCE_MARK tag has no name");
+    }
+    const cborValue = decodeCbor(mark.toCborData());
+    const ur = UR.new(tagName, cborValue);
+    const bytewords = mark.bytewordsIdentifier(true);
+    const bytemoji = mark.bytemojiIdentifier(true);
+    return new ProvenanceMarkInfo(mark, ur, bytewords, bytemoji, comment);
+  }
+
+  mark(): ProvenanceMark {
+    return this._mark;
+  }
+
+  ur(): UR {
+    return this._ur;
+  }
+
+  bytewords(): string {
+    return this._bytewords;
+  }
+
+  bytemoji(): string {
+    return this._bytemoji;
+  }
+
+  comment(): string {
+    return this._comment;
+  }
+
+  /**
+   * Generate a markdown summary of the mark.
+   */
+  markdownSummary(): string {
+    const lines: string[] = [];
+
+    lines.push("---");
+
+    lines.push("");
+    lines.push(this._mark.date().toISOString());
+
+    lines.push("");
+    lines.push(`#### ${this._ur.toString()}`);
+
+    lines.push("");
+    lines.push(`#### \`${this._bytewords}\``);
+
+    lines.push("");
+    lines.push(this._bytemoji);
+
+    lines.push("");
+    if (this._comment.length > 0) {
+      lines.push(this._comment);
+      lines.push("");
+    }
+
+    return lines.join("\n");
+  }
+
+  /**
+   * JSON serialization.
+   */
+  toJSON(): Record<string, unknown> {
+    const result: Record<string, unknown> = {
+      ur: this._ur.toString(),
+      bytewords: this._bytewords,
+      bytemoji: this._bytemoji,
+      mark: this._mark.toJSON(),
+    };
+    if (this._comment.length > 0) {
+      result["comment"] = this._comment;
+    }
+    return result;
+  }
+
+  /**
+   * Create from JSON object.
+   */
+  static fromJSON(json: Record<string, unknown>): ProvenanceMarkInfo {
+    const urString = json["ur"] as string;
+    const ur = UR.fromURString(urString);
+    const cborBytes = cborData(ur.cbor());
+    const mark = ProvenanceMark.fromCborData(cborBytes);
+    const bytewords = json["bytewords"] as string;
+    const bytemoji = json["bytemoji"] as string;
+    const comment = typeof json["comment"] === "string" ? json["comment"] : "";
+    return new ProvenanceMarkInfo(mark, ur, bytewords, bytemoji, comment);
+  }
+}