@bcts/provenance-mark 1.0.0-alpha.5

package/dist/index.d.mts

@@ -0,0 +1,711 @@
+import { Cbor } from "@bcts/dcbor";
+import { BytewordsStyle, UR } from "@bcts/uniform-resources";
+
+//#region src/error.d.ts
+/**
+ * Error types for Provenance Mark operations.
+ */
+declare 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.
+ */
+declare class ProvenanceMarkError extends Error {
+  readonly type: ProvenanceMarkErrorType;
+  readonly details?: Record<string, unknown> | undefined;
+  constructor(type: ProvenanceMarkErrorType, message?: string, details?: Record<string, unknown>);
+  private static defaultMessage;
+}
+/**
+ * Result type for Provenance Mark operations.
+ */
+type ProvenanceMarkResult<T> = T;
+//#endregion
+//#region src/resolution.d.ts
+/**
+ * Resolution levels for provenance marks.
+ * Higher resolution provides more security but larger mark sizes.
+ */
+declare enum ProvenanceMarkResolution {
+  Low = 0,
+  Medium = 1,
+  Quartile = 2,
+  High = 3,
+}
+/**
+ * Convert a resolution to its numeric value.
+ */
+declare function resolutionToNumber(res: ProvenanceMarkResolution): number;
+/**
+ * Create a resolution from a numeric value.
+ */
+declare function resolutionFromNumber(value: number): ProvenanceMarkResolution;
+/**
+ * Get the link length (key/hash/chainID length) for a resolution.
+ */
+declare function linkLength(res: ProvenanceMarkResolution): number;
+/**
+ * Get the sequence bytes length for a resolution.
+ */
+declare function seqBytesLength(res: ProvenanceMarkResolution): number;
+/**
+ * Get the date bytes length for a resolution.
+ */
+declare function dateBytesLength(res: ProvenanceMarkResolution): number;
+/**
+ * Get the fixed-length portion size for a resolution.
+ */
+declare function fixedLength(res: ProvenanceMarkResolution): number;
+/**
+ * Get the key range for a resolution.
+ */
+declare function keyRange(res: ProvenanceMarkResolution): {
+  start: number;
+  end: number;
+};
+/**
+ * Get the chain ID range for a resolution.
+ */
+declare function chainIdRange(res: ProvenanceMarkResolution): {
+  start: number;
+  end: number;
+};
+/**
+ * Get the hash range for a resolution.
+ */
+declare function hashRange(res: ProvenanceMarkResolution): {
+  start: number;
+  end: number;
+};
+/**
+ * Get the sequence bytes range for a resolution.
+ */
+declare function seqBytesRange(res: ProvenanceMarkResolution): {
+  start: number;
+  end: number;
+};
+/**
+ * Get the date bytes range for a resolution.
+ */
+declare function dateBytesRange(res: ProvenanceMarkResolution): {
+  start: number;
+  end: number;
+};
+/**
+ * Get the info range start for a resolution.
+ */
+declare function infoRangeStart(res: ProvenanceMarkResolution): number;
+/**
+ * Serialize a Date into bytes based on the resolution.
+ */
+declare function serializeDate(res: ProvenanceMarkResolution, date: Date): Uint8Array;
+/**
+ * Deserialize bytes into a Date based on the resolution.
+ */
+declare function deserializeDate(res: ProvenanceMarkResolution, data: Uint8Array): Date;
+/**
+ * Serialize a sequence number into bytes based on the resolution.
+ */
+declare function serializeSeq(res: ProvenanceMarkResolution, seq: number): Uint8Array;
+/**
+ * Deserialize bytes into a sequence number based on the resolution.
+ */
+declare function deserializeSeq(res: ProvenanceMarkResolution, data: Uint8Array): number;
+/**
+ * Get the string representation of a resolution.
+ */
+declare function resolutionToString(res: ProvenanceMarkResolution): string;
+/**
+ * Convert a resolution to CBOR.
+ */
+declare function resolutionToCbor(res: ProvenanceMarkResolution): Cbor;
+/**
+ * Create a resolution from CBOR.
+ */
+declare function resolutionFromCbor(cborValue: Cbor): ProvenanceMarkResolution;
+//#endregion
+//#region src/date.d.ts
+/**
+ * Interface for serializable date operations.
+ */
+interface SerializableDate {
+  serialize2Bytes(): Uint8Array;
+  serialize4Bytes(): Uint8Array;
+  serialize6Bytes(): Uint8Array;
+}
+/**
+ * Serialize a date to 2 bytes (year + month + day only, day precision).
+ * Year range: 2023-2150 (128 years)
+ * Format: YYYYYYY MMMM DDDDD (7 bits year offset, 4 bits month, 5 bits day)
+ */
+declare function serialize2Bytes(date: Date): Uint8Array;
+/**
+ * Deserialize 2 bytes to a date.
+ */
+declare function deserialize2Bytes(bytes: Uint8Array): Date;
+/**
+ * Serialize a date to 4 bytes (seconds since 2001-01-01).
+ */
+declare function serialize4Bytes(date: Date): Uint8Array;
+/**
+ * Deserialize 4 bytes to a date.
+ */
+declare function deserialize4Bytes(bytes: Uint8Array): Date;
+/**
+ * Serialize a date to 6 bytes (milliseconds since 2001-01-01).
+ */
+declare function serialize6Bytes(date: Date): Uint8Array;
+/**
+ * Deserialize 6 bytes to a date.
+ */
+declare function deserialize6Bytes(bytes: Uint8Array): Date;
+/**
+ * Get the range of valid days in a month.
+ */
+declare function rangeOfDaysInMonth(year: number, month: number): {
+  min: number;
+  max: number;
+};
+/**
+ * Format a date as ISO8601 string.
+ */
+declare function dateToIso8601(date: Date): string;
+/**
+ * Parse an ISO8601 string to a Date.
+ */
+declare function dateFromIso8601(str: string): Date;
+/**
+ * Format a date as a simple date string (YYYY-MM-DD).
+ */
+declare function dateToDateString(date: Date): string;
+//#endregion
+//#region src/crypto-utils.d.ts
+declare const SHA256_SIZE = 32;
+/**
+ * Compute SHA-256 hash of data.
+ */
+declare function sha256(data: Uint8Array): Uint8Array;
+/**
+ * Compute SHA-256 hash and return a prefix of the given length.
+ */
+declare function sha256Prefix(data: Uint8Array, prefix: number): Uint8Array;
+/**
+ * Extend a key to 32 bytes using HKDF-HMAC-SHA-256.
+ */
+declare function extendKey(data: Uint8Array): Uint8Array;
+/**
+ * Compute HKDF-HMAC-SHA-256 for the given key material.
+ */
+declare function hkdfHmacSha256(keyMaterial: Uint8Array, salt: Uint8Array, keyLen: number): Uint8Array;
+/**
+ * Obfuscate (or deobfuscate) a message using ChaCha20.
+ * The function is symmetric - applying it twice returns the original message.
+ */
+declare function obfuscate(key: Uint8Array, message: Uint8Array): Uint8Array;
+//#endregion
+//#region src/xoshiro256starstar.d.ts
+/**
+ * Xoshiro256** PRNG implementation.
+ * A fast, high-quality pseudorandom number generator.
+ */
+declare class Xoshiro256StarStar {
+  private s;
+  private constructor();
+  /**
+   * Get the internal state as an array of 4 u64 values.
+   */
+  toState(): [bigint, bigint, bigint, bigint];
+  /**
+   * Create a new PRNG from a state array.
+   */
+  static fromState(state: [bigint, bigint, bigint, bigint]): Xoshiro256StarStar;
+  /**
+   * Serialize the state to 32 bytes (little-endian).
+   */
+  toData(): Uint8Array;
+  /**
+   * Create a new PRNG from 32 bytes of seed data (little-endian).
+   */
+  static fromData(data: Uint8Array): Xoshiro256StarStar;
+  /**
+   * Generate the next u64 value.
+   */
+  nextU64(): bigint;
+  /**
+   * Generate the next u32 value (upper bits of u64 for better quality).
+   */
+  nextU32(): number;
+  /**
+   * Generate the next byte.
+   */
+  nextByte(): number;
+  /**
+   * Generate the next n bytes.
+   */
+  nextBytes(len: number): Uint8Array;
+  /**
+   * Fill a buffer with random bytes.
+   */
+  fillBytes(dest: Uint8Array): void;
+  /**
+   * The starstar transformation: x * 5, rotate left 7, * 9
+   */
+  private starstarU64;
+  /**
+   * Rotate a 64-bit value left by n bits.
+   */
+  private rotateLeft64;
+  /**
+   * Advance the PRNG state.
+   */
+  private advance;
+}
+//#endregion
+//#region src/rng-state.d.ts
+declare const RNG_STATE_LENGTH = 32;
+/**
+ * RNG state for provenance marks (32 bytes).
+ */
+declare class RngState {
+  private readonly data;
+  private constructor();
+  /**
+   * Get the raw bytes.
+   */
+  toBytes(): Uint8Array;
+  /**
+   * Create from a 32-byte array.
+   */
+  static fromBytes(bytes: Uint8Array): RngState;
+  /**
+   * Create from a slice (validates length).
+   */
+  static fromSlice(bytes: Uint8Array): RngState;
+  /**
+   * Get the hex representation.
+   */
+  hex(): string;
+  /**
+   * Convert to CBOR (byte string).
+   */
+  toCbor(): Cbor;
+  /**
+   * Create from CBOR (byte string).
+   */
+  static fromCbor(cborValue: Cbor): RngState;
+}
+//#endregion
+//#region src/seed.d.ts
+declare const PROVENANCE_SEED_LENGTH = 32;
+/**
+ * A seed for generating provenance marks.
+ */
+declare class ProvenanceSeed {
+  private readonly data;
+  private constructor();
+  /**
+   * Create a new random seed using secure random number generation.
+   */
+  static new(): ProvenanceSeed;
+  /**
+   * Create a new seed using custom random data.
+   */
+  static newUsing(randomData: Uint8Array): ProvenanceSeed;
+  /**
+   * Create a new seed from a passphrase.
+   */
+  static newWithPassphrase(passphrase: string): ProvenanceSeed;
+  /**
+   * Get the raw bytes.
+   */
+  toBytes(): Uint8Array;
+  /**
+   * Create from a 32-byte array.
+   */
+  static fromBytes(bytes: Uint8Array): ProvenanceSeed;
+  /**
+   * Create from a slice (validates length).
+   */
+  static fromSlice(bytes: Uint8Array): ProvenanceSeed;
+  /**
+   * Get the hex representation.
+   */
+  hex(): string;
+  /**
+   * Convert to CBOR (byte string).
+   */
+  toCbor(): Cbor;
+  /**
+   * Create from CBOR (byte string).
+   */
+  static fromCbor(cborValue: Cbor): ProvenanceSeed;
+}
+//#endregion
+//#region src/mark.d.ts
+/**
+ * A cryptographically-secured provenance mark.
+ */
+declare class ProvenanceMark {
+  private readonly _res;
+  private readonly _key;
+  private readonly _hash;
+  private readonly _chainId;
+  private readonly _seqBytes;
+  private readonly _dateBytes;
+  private readonly _infoBytes;
+  private readonly _seq;
+  private readonly _date;
+  private constructor();
+  res(): ProvenanceMarkResolution;
+  key(): Uint8Array;
+  hash(): Uint8Array;
+  chainId(): Uint8Array;
+  seqBytes(): Uint8Array;
+  dateBytes(): Uint8Array;
+  seq(): number;
+  date(): Date;
+  /**
+   * Get the message (serialized bytes) of this mark.
+   */
+  message(): Uint8Array;
+  /**
+   * Get the info field as CBOR, if present.
+   */
+  info(): Cbor | undefined;
+  /**
+   * Create a new provenance mark.
+   */
+  static new(res: ProvenanceMarkResolution, key: Uint8Array, nextKey: Uint8Array, chainId: Uint8Array, seq: number, date: Date, info?: Cbor): ProvenanceMark;
+  /**
+   * Create a provenance mark from a serialized message.
+   */
+  static fromMessage(res: ProvenanceMarkResolution, message: Uint8Array): ProvenanceMark;
+  private static makeHash;
+  /**
+   * Get the first four bytes of the hash as a hex string identifier.
+   */
+  identifier(): string;
+  /**
+   * Get the first four bytes of the hash as upper-case ByteWords.
+   */
+  bytewordsIdentifier(prefix: boolean): string;
+  /**
+   * Get the first four bytes of the hash as Bytemoji.
+   */
+  bytemojiIdentifier(prefix: boolean): string;
+  /**
+   * Check if this mark precedes another mark in the chain.
+   */
+  precedes(next: ProvenanceMark): boolean;
+  /**
+   * Check if this mark precedes another mark, throwing on validation errors.
+   */
+  precedesOpt(next: ProvenanceMark): void;
+  /**
+   * Check if a sequence of marks is valid.
+   */
+  static isSequenceValid(marks: ProvenanceMark[]): boolean;
+  /**
+   * Check if this is a genesis mark (seq 0 and key equals chain_id).
+   */
+  isGenesis(): boolean;
+  /**
+   * Encode as bytewords with the given style.
+   */
+  toBytewordsWithStyle(style: BytewordsStyle): string;
+  /**
+   * Encode as standard bytewords.
+   */
+  toBytewords(): string;
+  /**
+   * Decode from bytewords.
+   */
+  static fromBytewords(res: ProvenanceMarkResolution, bytewords: string): ProvenanceMark;
+  /**
+   * Encode for URL (minimal bytewords of CBOR).
+   */
+  toUrlEncoding(): string;
+  /**
+   * Decode from URL encoding.
+   */
+  static fromUrlEncoding(urlEncoding: string): ProvenanceMark;
+  /**
+   * Build a URL with this mark as a query parameter.
+   */
+  toUrl(base: string): URL;
+  /**
+   * Parse a provenance mark from a URL.
+   */
+  static fromUrl(url: URL): ProvenanceMark;
+  /**
+   * Get the untagged CBOR representation.
+   */
+  untaggedCbor(): Cbor;
+  /**
+   * Get the tagged CBOR representation.
+   */
+  taggedCbor(): Cbor;
+  /**
+   * Serialize to CBOR bytes (tagged).
+   */
+  toCborData(): Uint8Array;
+  /**
+   * Create from untagged CBOR.
+   */
+  static fromUntaggedCbor(cborValue: Cbor): ProvenanceMark;
+  /**
+   * Create from tagged CBOR.
+   */
+  static fromTaggedCbor(cborValue: Cbor): ProvenanceMark;
+  /**
+   * Create from CBOR bytes.
+   */
+  static fromCborData(data: Uint8Array): ProvenanceMark;
+  /**
+   * Get the fingerprint (SHA-256 of CBOR data).
+   */
+  fingerprint(): Uint8Array;
+  /**
+   * Debug string representation.
+   */
+  toString(): string;
+  /**
+   * Detailed debug representation.
+   */
+  toDebugString(): string;
+  /**
+   * Check equality with another mark.
+   */
+  equals(other: ProvenanceMark): boolean;
+  /**
+   * JSON serialization.
+   */
+  toJSON(): Record<string, unknown>;
+  /**
+   * Create from JSON object.
+   */
+  static fromJSON(json: Record<string, unknown>): ProvenanceMark;
+}
+//#endregion
+//#region src/generator.d.ts
+/**
+ * Generator for creating provenance mark chains.
+ */
+declare class ProvenanceMarkGenerator {
+  private readonly _res;
+  private readonly _seed;
+  private readonly _chainId;
+  private _nextSeq;
+  private _rngState;
+  private constructor();
+  res(): ProvenanceMarkResolution;
+  seed(): ProvenanceSeed;
+  chainId(): Uint8Array;
+  nextSeq(): number;
+  rngState(): RngState;
+  /**
+   * Create a new generator with a seed.
+   */
+  static newWithSeed(res: ProvenanceMarkResolution, seed: ProvenanceSeed): ProvenanceMarkGenerator;
+  /**
+   * Create a new generator with a passphrase.
+   */
+  static newWithPassphrase(res: ProvenanceMarkResolution, passphrase: string): ProvenanceMarkGenerator;
+  /**
+   * Create a new generator with custom random data.
+   */
+  static newUsing(res: ProvenanceMarkResolution, randomData: Uint8Array): ProvenanceMarkGenerator;
+  /**
+   * Create a new generator with random seed.
+   */
+  static newRandom(res: ProvenanceMarkResolution): ProvenanceMarkGenerator;
+  /**
+   * Create a new generator with all parameters.
+   */
+  static new(res: ProvenanceMarkResolution, seed: ProvenanceSeed, chainId: Uint8Array, nextSeq: number, rngState: RngState): ProvenanceMarkGenerator;
+  /**
+   * Generate the next provenance mark in the chain.
+   */
+  next(date: Date, info?: Cbor): ProvenanceMark;
+  /**
+   * String representation.
+   */
+  toString(): string;
+  /**
+   * JSON serialization.
+   */
+  toJSON(): Record<string, unknown>;
+  /**
+   * Create from JSON object.
+   */
+  static fromJSON(json: Record<string, unknown>): ProvenanceMarkGenerator;
+}
+//#endregion
+//#region src/validate.d.ts
+/**
+ * Format for validation report output.
+ */
+declare enum ValidationReportFormat {
+  /** Human-readable text format */
+  Text = "text",
+  /** Compact JSON format (no whitespace) */
+  JsonCompact = "json-compact",
+  /** Pretty-printed JSON format (with indentation) */
+  JsonPretty = "json-pretty",
+}
+/**
+ * Issue flagged during validation.
+ */
+type ValidationIssue = {
+  type: "HashMismatch";
+  expected: string;
+  actual: string;
+} | {
+  type: "KeyMismatch";
+} | {
+  type: "SequenceGap";
+  expected: number;
+  actual: number;
+} | {
+  type: "DateOrdering";
+  previous: string;
+  next: string;
+} | {
+  type: "NonGenesisAtZero";
+} | {
+  type: "InvalidGenesisKey";
+};
+/**
+ * Format a validation issue as a string.
+ */
+declare function formatValidationIssue(issue: ValidationIssue): string;
+/**
+ * A mark with any issues flagged during validation.
+ */
+interface FlaggedMark {
+  mark: ProvenanceMark;
+  issues: ValidationIssue[];
+}
+/**
+ * Report for a contiguous sequence of marks within a chain.
+ */
+interface SequenceReport {
+  startSeq: number;
+  endSeq: number;
+  marks: FlaggedMark[];
+}
+/**
+ * Report for a chain of marks with the same chain ID.
+ */
+interface ChainReport {
+  chainId: Uint8Array;
+  hasGenesis: boolean;
+  marks: ProvenanceMark[];
+  sequences: SequenceReport[];
+}
+/**
+ * Get the chain ID as a hex string for display.
+ */
+declare function chainIdHex(report: ChainReport): string;
+/**
+ * Complete validation report.
+ */
+interface ValidationReport {
+  marks: ProvenanceMark[];
+  chains: ChainReport[];
+}
+/**
+ * Check if the validation report has any issues.
+ */
+declare function hasIssues(report: ValidationReport): boolean;
+/**
+ * Format the validation report.
+ */
+declare function formatReport(report: ValidationReport, format: ValidationReportFormat): string;
+/**
+ * Validate a collection of provenance marks.
+ */
+declare function validate(marks: ProvenanceMark[]): ValidationReport;
+//#endregion
+//#region src/mark-info.d.ts
+/**
+ * Wrapper for a provenance mark with additional display information.
+ */
+declare class ProvenanceMarkInfo {
+  private readonly _mark;
+  private readonly _ur;
+  private readonly _bytewords;
+  private readonly _bytemoji;
+  private readonly _comment;
+  private constructor();
+  /**
+   * Create a new ProvenanceMarkInfo from a mark.
+   */
+  static new(mark: ProvenanceMark, comment?: string): ProvenanceMarkInfo;
+  mark(): ProvenanceMark;
+  ur(): UR;
+  bytewords(): string;
+  bytemoji(): string;
+  comment(): string;
+  /**
+   * Generate a markdown summary of the mark.
+   */
+  markdownSummary(): string;
+  /**
+   * JSON serialization.
+   */
+  toJSON(): Record<string, unknown>;
+  /**
+   * Create from JSON object.
+   */
+  static fromJSON(json: Record<string, unknown>): ProvenanceMarkInfo;
+}
+//#endregion
+export { type ChainReport, type FlaggedMark, PROVENANCE_SEED_LENGTH, ProvenanceMark, ProvenanceMarkError, ProvenanceMarkErrorType, ProvenanceMarkGenerator, ProvenanceMarkInfo, ProvenanceMarkResolution, type ProvenanceMarkResult, ProvenanceSeed, RNG_STATE_LENGTH, RngState, SHA256_SIZE, type SequenceReport, type SerializableDate, type ValidationIssue, type ValidationReport, ValidationReportFormat, Xoshiro256StarStar, chainIdHex, chainIdRange, dateBytesLength, dateBytesRange, dateFromIso8601, dateToDateString, dateToIso8601, deserialize2Bytes, deserialize4Bytes, deserialize6Bytes, deserializeDate, deserializeSeq, extendKey, fixedLength, formatReport, formatValidationIssue, hasIssues, hashRange, hkdfHmacSha256, infoRangeStart, keyRange, linkLength, obfuscate, rangeOfDaysInMonth, resolutionFromCbor, resolutionFromNumber, resolutionToCbor, resolutionToNumber, resolutionToString, seqBytesLength, seqBytesRange, serialize2Bytes, serialize4Bytes, serialize6Bytes, serializeDate, serializeSeq, sha256, sha256Prefix, validate };
+//# sourceMappingURL=index.d.mts.map