@qrkit/bc-ur 2.0.0-beta.9-qrkit.1

package/src/encodingMethods/CborEncoding.ts

@@ -0,0 +1,196 @@
+import { URRegistryClass, UrRegistry } from "../registry.js";
+import { RegistryItem, RegistryItemClass, registryItemFactory } from "../classes/RegistryItem.js";
+import { EncodingMethodName } from "../enums/EncodingMethodName.js";
+import { IEncodingMethod } from "../interfaces/IEncodingMethod.js";
+
+import {
+  DecodeOptions,
+  EncodeOptions,
+  decode, encode, Tag
+} from "../wrappers/cbor2.js";
+
+interface inputOptions {
+  registry?: URRegistryClass;
+  cborLibEncoderOptions?: EncodeOptions & {ignoreTopLevelTag?: boolean};
+  cborLibDecoderOptions?: DecodeOptions;
+}
+
+interface decodeOptions {
+  enforceType?: RegistryItemClass | string;
+  cborLibOptions?: DecodeOptions;
+}
+
+export class CborEncoding<T extends RegistryItem>
+  implements IEncodingMethod<T, Uint8Array>
+{
+  private _name: EncodingMethodName = EncodingMethodName.cbor;
+  public registry: URRegistryClass = UrRegistry;
+
+  /** Decoding options for CBOR2 library */
+  cborLibEncoderOptions: EncodeOptions;
+  cborLibDecoderOptions: DecodeOptions;
+
+  constructor(options?: inputOptions) {
+    this.cborLibEncoderOptions = options?.cborLibEncoderOptions;
+    this.cborLibDecoderOptions = options?.cborLibDecoderOptions;
+  }
+
+  get name(): EncodingMethodName {
+    return this._name;
+  }
+
+  /**
+   * Encode the given payload to CBOR
+   *
+   * @param payload @type RegistryItem
+   * @param cborLibOptions @type EncodeOptions
+   * @returns @type Uint8Array
+   */
+  encode(payload: any, cborLibOptions?: EncodeOptions & {ignoreTopLevelTag?: boolean}): Uint8Array {
+    // Combine instance cborLibOptions with the given cborLibOptions
+    const combinedOptions = {
+      ...this.cborLibEncoderOptions,
+      ...cborLibOptions,
+    };
+
+    // By default encode return Uint8Array
+    const encoded = encode(payload, combinedOptions);
+    return encoded;
+  }
+
+  /**
+   * Decode the CBOR encoded payload to the given type
+   * @param payload @type Uint8Array
+   * @param enforceType Forces decoding into given type or throws error if it cannot be decoded @type RegistryItemClass
+   * @param cborLibOptions @type DecodeOptions
+   * @returns @type T
+   */
+  decode(
+    payload: Uint8Array,
+    options?: decodeOptions,
+  ): T {
+    // Combine instance cborLibOptions with the given cborLibOptions
+    const { cborLibOptions, enforceType } = options || {};
+    const combinedOptions = {
+      ...this.cborLibDecoderOptions,
+      ...cborLibOptions,
+    };
+
+    const decoded = decode(payload, combinedOptions);
+
+    // Check if enforce type is given, if so then give the value to the enforced type
+    if (enforceType) {
+      let foundType: RegistryItemClass;
+      // If enforceType is string then find the type from the registry
+      if (typeof enforceType === "string") {
+        foundType = this.registry.queryByURType(enforceType);
+      }
+      else {
+        foundType = enforceType;
+      }
+
+      // If we have a registry item then force the type
+      if (foundType) {
+        return forceType(decoded, foundType) as unknown as T;
+      }
+    }
+
+    // If we still have a cbor tag but not registry item then return try to convert it to registry item
+    if (decoded instanceof Tag) {
+      return tag2registryItem(decoded) as unknown as T;
+    }
+
+    // Otherwise just return the decoded value
+    // TODO: fix as unknown as T;
+    return decoded as unknown as T;
+  }
+}
+
+/**
+ * Force the data to be of the enforced type registry item
+ * @param data 
+ * @param enforceType 
+ * @returns 
+ */
+function forceType(data: any, enforceType: RegistryItemClass): RegistryItem {
+  // If its already the enforced type then return
+  if (data instanceof enforceType) {
+    return data;
+  }
+
+  // If data is CBOR tag item, try to convert it to enforced type
+  if (data instanceof Tag) {
+    if (data.tag !== enforceType.tag) {
+      throw new Error(
+        `Enforced type does not match the tag of ${enforceType.URType}:${enforceType.tag} !== ${data.tag}`
+      );
+    }
+    return enforceType.fromCBORData(data.contents, enforceType.allowKeysNotInMap);
+  }
+
+  // If data is raw then try to convert it to enforced type
+  return enforceType.fromCBORData(data, enforceType.allowKeysNotInMap);
+}
+
+/**
+ * Converts a CBOR tag to a registry item
+ * @param unkownTag 
+ * @returns 
+ */
+function tag2registryItem(unkownTag: Tag): RegistryItem {
+  const tag = toRegistryTagNumber(unkownTag.tag);
+  const data = unkownTag.contents;
+
+  const registryItem = UrRegistry.queryByTag(tag);
+  if (registryItem) {
+    return registryItem.fromCBORData(
+      data,
+      registryItem.allowKeysNotInMap
+    );
+  } 
+
+  // If we dont have the tag in the registry return unknown item
+  const UnknownTag = class extends registryItemFactory({
+    tag: tag,
+    URType: "unknown-tag",
+    CDDL: ``,
+  }) {};
+
+  const unknownItem = new UnknownTag(data);
+
+  // Search through all the children in unknownItem.data if any one of them are tags
+  deepSearchObject(unknownItem.data);
+
+  return unknownItem;
+}
+
+function toRegistryTagNumber(tag: Tag["tag"]): number {
+  if (typeof tag === "bigint") {
+    const converted = Number(tag);
+    if (!Number.isSafeInteger(converted)) {
+      throw new Error(`CBOR tag ${tag.toString()} exceeds JavaScript safe integer range`);
+    }
+    return converted;
+  }
+
+  return Number(tag);
+}
+
+/**
+ * Search through the object and convert tags to registry items
+ * @param obj 
+ * @returns 
+ */
+function deepSearchObject(obj: any) {
+  if (typeof obj !== "object") {
+    return obj;
+  }
+
+  for (const key in obj) {
+    if (obj[key] instanceof Tag) {
+      obj[key] = tag2registryItem(obj[key]);
+    } else if (typeof obj[key] === "object") {
+      deepSearchObject(obj[key]);
+    }
+  }
+}

package/src/encodingMethods/HexEncoding.ts

@@ -0,0 +1,23 @@
+import { hexToUint8Array, uint8ArrayToHex } from "../helpers/uintArrayHelper.js";
+import { EncodingMethodName } from "../enums/EncodingMethodName.js";
+import { IEncodingMethod } from "../interfaces/IEncodingMethod.js";
+
+export class HexEncoding implements IEncodingMethod<Uint8Array, string> {
+  private _name: EncodingMethodName = EncodingMethodName.hex;
+
+  get name(): EncodingMethodName {
+    return this._name;
+  }
+
+  encode(payload: Uint8Array): string {
+    // return payload.toString("hex");
+    return uint8ArrayToHex(payload);
+  }
+  decode(payload: string): Uint8Array {
+    const hexRegex = /^[0-9a-fA-F]+$/;
+    if (!hexRegex.test(payload)) {
+      throw new Error("Invalid hex string");
+    }
+    return hexToUint8Array(payload);
+  }
+}

package/src/encodingMethods/UrEncoding.ts

@@ -0,0 +1,19 @@
+import { EncodingMethodName } from "../enums/EncodingMethodName.js";
+import { IEncodingMethod } from "../interfaces/IEncodingMethod.js";
+import { UR } from "../classes/UR.js";
+import { RegistryItem } from "../classes/RegistryItem.js";
+
+export class UrEncoding implements IEncodingMethod<RegistryItem, UR> {
+  private _name: EncodingMethodName = EncodingMethodName.ur;
+
+  get name(): EncodingMethodName {
+    return this._name;
+  }
+
+  encode(payload: RegistryItem): UR {
+    return UR.fromRegistryItem(payload);
+  }
+  decode(payload: UR): RegistryItem {
+    return payload.toRegistryItem();
+  }
+}

package/src/encodingMethods/bytewords.ts

@@ -0,0 +1,215 @@
+import { assert, getCRCHex, partition, split } from "../helpers/utils.js";
+import { uint8ArrayToHex, hexToUint8Array } from "../helpers/uintArrayHelper.js";
+
+const bytewords =
+  "ableacidalsoapexaquaarchatomauntawayaxisbackbaldbarnbeltbetabiasbluebodybragbrewbulbbuzzcalmcashcatschefcityclawcodecolacookcostcruxcurlcuspcyandarkdatadaysdelidicedietdoordowndrawdropdrumdulldutyeacheasyechoedgeepicevenexamexiteyesfactfairfernfigsfilmfishfizzflapflewfluxfoxyfreefrogfuelfundgalagamegeargemsgiftgirlglowgoodgraygrimgurugushgyrohalfhanghardhawkheathelphighhillholyhopehornhutsicedideaidleinchinkyintoirisironitemjadejazzjoinjoltjowljudojugsjumpjunkjurykeepkenokeptkeyskickkilnkingkitekiwiknoblamblavalazyleaflegsliarlimplionlistlogoloudloveluaulucklungmainmanymathmazememomenumeowmildmintmissmonknailnavyneednewsnextnoonnotenumbobeyoboeomitonyxopenovalowlspaidpartpeckplaypluspoempoolposepuffpumapurrquadquizraceramprealredorichroadrockroofrubyruinrunsrustsafesagascarsetssilkskewslotsoapsolosongstubsurfswantacotasktaxitenttiedtimetinytoiltombtoystriptunatwinuglyundouniturgeuservastveryvetovialvibeviewvisavoidvowswallwandwarmwaspwavewaxywebswhatwhenwhizwolfworkyankyawnyellyogayurtzapszerozestzinczonezoom";
+let bytewordsLookUpTable: number[] = [];
+const BYTEWORDS_NUM = 256;
+const BYTEWORD_LENGTH = 4;
+const MINIMAL_BYTEWORD_LENGTH = 2;
+
+export enum STYLES {
+  STANDARD = "standard",
+  URI = "uri",
+  MINIMAL = "minimal",
+}
+
+const getWord = (index: number): string => {
+  return bytewords.slice(
+    index * BYTEWORD_LENGTH,
+    index * BYTEWORD_LENGTH + BYTEWORD_LENGTH
+  );
+};
+
+const getMinimalWord = (index: number): string => {
+  const byteword = getWord(index);
+
+  return `${byteword[0]}${byteword[BYTEWORD_LENGTH - 1]}`;
+};
+
+const addCRC = (string: string): string => {
+  const crc = getCRCHex(hexToUint8Array(string));
+
+  return `${string}${crc}`;
+};
+
+const encodeWithSeparator = (word: string, separator: string, includeChecksum: boolean): string => {
+  const crcAppendedWord = includeChecksum ? addCRC(word) : word;
+  const crcWordArray = hexToUint8Array(crcAppendedWord);
+  const result = crcWordArray.reduce(
+    (result: string[], w) => [...result, getWord(w)],
+    []
+  );
+
+  return result.join(separator);
+};
+
+const encodeMinimal = (word: string, includeChecksum: boolean): string => {
+  const crcAppendedWord = includeChecksum ? addCRC(word) : word;
+  const crcWordArray = hexToUint8Array(crcAppendedWord);
+  const result = crcWordArray.reduce(
+    (result, w) => result + getMinimalWord(w),
+    ""
+  );
+
+  return result;
+};
+
+const decodeWord = (word: string, wordLength: number): string => {
+  assert(
+    word.length === wordLength,
+    "Invalid Bytewords: word.length does not match wordLength provided"
+  );
+
+  const dim = 26;
+
+  // Since the first and last letters of each Byteword are unique,
+  // we can use them as indexes into a two-dimensional lookup table.
+  // This table is generated lazily.
+  if (bytewordsLookUpTable.length === 0) {
+    const array_len = dim * dim;
+    bytewordsLookUpTable = [...new Array(array_len)].map(() => -1);
+
+    for (let i = 0; i < BYTEWORDS_NUM; i++) {
+      const byteword = getWord(i);
+      let x = byteword[0].charCodeAt(0) - "a".charCodeAt(0);
+      let y = byteword[3].charCodeAt(0) - "a".charCodeAt(0);
+      let offset = y * dim + x;
+      bytewordsLookUpTable[offset] = i;
+    }
+  }
+
+  // If the coordinates generated by the first and last letters are out of bounds,
+  // or the lookup table contains -1 at the coordinates, then the word is not valid.
+  let x = word[0].toLowerCase().charCodeAt(0) - "a".charCodeAt(0);
+  let y =
+    word[wordLength == 4 ? 3 : 1].toLowerCase().charCodeAt(0) -
+    "a".charCodeAt(0);
+
+  assert(
+    0 <= x && x < dim && 0 <= y && y < dim,
+    "Invalid Bytewords: invalid word"
+  );
+
+  let offset = y * dim + x;
+  let value = bytewordsLookUpTable[offset];
+
+  assert(value !== -1, "Invalid Bytewords: value not in lookup table");
+
+  // If we're decoding a full four-letter word, verify that the two middle letters are correct.
+  if (wordLength == BYTEWORD_LENGTH) {
+    const byteword = getWord(value);
+    let c1 = word[1].toLowerCase();
+    let c2 = word[2].toLowerCase();
+
+    assert(
+      c1 === byteword[1] && c2 === byteword[2],
+      "Invalid Bytewords: invalid middle letters of word"
+    );
+  }
+
+  // Successful decode.
+  return value.toString(16).padStart(2, "0");
+};
+
+/**
+ * Decode a string of Bytewords into a hex string.
+ * @param string string of Bytewords. e.g. "lpamchcfatttcyclehgsdphdhgehfghkkkdl..."
+ * @param separator e.g. " " or "-" or "" or any other separator
+ * @param wordLength e.g. 4 or 2 or any other length
+ * @param includeChecksum whether to include checksum in the decoding.
+ * @returns hex string
+ */
+const _decode = (
+  string: string,
+  separator: string,
+  wordLength: number,
+  includeChecksum: boolean
+): string => {
+  // Split the string into words. e.g. ["lp", "am", "ch", "cf", "at", "tt", "cy", "cl", "eh", "gs", "dp", "hd", "hg", "eh", "fg", "hk", "kk", "dl", ...]
+  const words =
+    wordLength == BYTEWORD_LENGTH
+      ? string.split(separator)
+      : partition(string, 2);
+
+  // Decode each word. e.g. ["85", "06", "17", "19", "07", "d1", "1a", "21", "31", "4c", "2d", "58", "57", "31", "46", "59", "79", "2f", ...]
+  const decodedWords = words.map((word: string) =>
+    decodeWord(word, wordLength)
+  );
+
+  // e.g. "8506171907d11a21314c2d5857314659792f..."
+  const decodedString = decodedWords.join("");
+
+  if (includeChecksum) {
+    // 4 bytes for checksum, at least 1 byte for body
+    assert(
+      decodedString.length >= 5,
+      "Invalid Bytewords: invalid decoded string length"
+    );
+
+    // decoded string consists of `body` and `checksum`
+    const decodedArray = hexToUint8Array(decodedString);
+    const [body, bodyChecksum] = split(decodedArray, 4);
+    const checksum = getCRCHex(body); // convert to hex
+
+    assert(checksum === uint8ArrayToHex(bodyChecksum), "Invalid Checksum");
+
+    return uint8ArrayToHex(body);
+  } else {
+    return decodedString;
+  }
+};
+
+/**
+ * Decode a string of bytewords into a hex string.
+ * @param string string of Bytewords
+ * @param style style of Bytewords
+ * @param includeChecksum whether to include checksum in the decoding.
+ * @returns hex string
+ */
+export const decode = (
+  string: string,
+  style: STYLES = STYLES.MINIMAL,
+  includeChecksum: boolean = true
+): string => {
+  switch (style) {
+    case STYLES.STANDARD:
+      return _decode(string, " ", BYTEWORD_LENGTH, includeChecksum);
+    case STYLES.URI:
+      return _decode(string, "-", BYTEWORD_LENGTH, includeChecksum);
+    case STYLES.MINIMAL:
+      return _decode(string, "", MINIMAL_BYTEWORD_LENGTH, includeChecksum);
+    default:
+      throw new Error(`Invalid style ${style}`);
+  }
+};
+
+/**
+ * Encodes a string (hex representation of a buffer) into bytewords.
+ * @param string string to encode.
+ * @param style style to use for the encoding.
+ * @param includeChecksum whether to include checksum in the encoding.
+ * @returns the byteword encoded string
+ */
+export const encode = (
+  string: string,
+  style: STYLES = STYLES.MINIMAL,
+  includeChecksum: boolean = true
+): string => {
+  switch (style) {
+    case STYLES.STANDARD:
+      return encodeWithSeparator(string, " ", includeChecksum);
+    case STYLES.URI:
+      return encodeWithSeparator(string, "-", includeChecksum);
+    case STYLES.MINIMAL:
+      return encodeMinimal(string, includeChecksum);
+    default:
+      throw new Error(`Invalid style ${style}`);
+  }
+};
+
+export default {
+  decode,
+  encode,
+  STYLES,
+};

package/src/encodingMethods/index.ts

@@ -0,0 +1,26 @@
+import { BytewordEncoding } from "./BytewordEncoding.js";
+import { CborEncoding } from "./CborEncoding.js";
+import { HexEncoding } from "./HexEncoding.js";
+import { EncodingPipeline } from "./pipeline.js";
+
+/**
+ * Pipeline that encodes registry registryItem | any -> cbor -> hex -> bytewords
+ * 
+ * Uses default encoding options for each encoding method
+ * 1. Cbor: CBOR2 library
+ * 2. Hex: Uint8Array -> hex string
+ * 3. Bytewords: Uint8Array -> bytewords string with checksum and minimal style
+ * 
+ */
+
+export const defaultEncoders = {
+  cbor: new CborEncoding(),
+  hex: new HexEncoding(),
+  bytewords: new BytewordEncoding(),
+}
+
+export const dataPipeline = new EncodingPipeline<any, string>([
+  defaultEncoders.cbor,
+  defaultEncoders.hex,
+  defaultEncoders.bytewords,
+]);

package/src/encodingMethods/pipeline.ts

@@ -0,0 +1,103 @@
+import { EncodingMethodName } from "../enums/EncodingMethodName.js";
+import { IEncodingMethod } from "../interfaces/IEncodingMethod.js";
+
+interface pipelineConfig {
+  from?: EncodingMethodName;
+  until?: EncodingMethodName;
+  [key: string]: any;
+}
+
+export class EncodingPipeline<T, U> implements IEncodingMethod<T, U> {
+  private _name: EncodingMethodName = EncodingMethodName.pipe;
+  private _encodingMethods: IEncodingMethod<any, any>[];
+
+  constructor(encodingMethods: IEncodingMethod<any, any>[]) {
+    this._encodingMethods = encodingMethods;
+  }
+
+  get name(): EncodingMethodName {
+    return this._name;
+  }  
+
+  get encodingMethods() {
+    return this._encodingMethods;
+  }
+
+  get decodingMethods() {
+    return this._encodingMethods.slice().reverse();
+  }
+  
+
+  // TODO: change until to "to"
+  encode<O = U>(payload: T, config: pipelineConfig = {from:undefined, until:undefined}): O {
+    let encodedValue: any = payload;
+    let fromIndex = 0;
+    let untilIndex = this.encodingMethods.length;
+
+    const { from, until, ...rest } = config;
+
+    // Find the index of the specified start and until encoding methods
+    if(from) {
+      fromIndex = this.encodingMethods.findIndex((method) => method.name === from);
+      if(fromIndex === -1) {
+        throw new Error(`Encoding method ${from} not found`);
+      }
+    }
+
+    if(until) {
+      untilIndex = this.encodingMethods.findIndex((method) => method.name === until);
+      if(untilIndex === -1) {
+        throw new Error(`Encoding method ${until} not found`);
+      }
+    }
+
+    if(fromIndex > untilIndex) {
+      throw new Error("Invalid encoding method range");
+    }
+
+    // Apply each encoding method in sequence until the specified encoding method or the end
+    for (let i = fromIndex; i < untilIndex; i++) {
+      encodedValue = this.encodingMethods[i].encode(encodedValue, rest);
+    }
+    return encodedValue;
+  }  
+
+  decode<O = T>(payload: U, config: pipelineConfig = {from:undefined, until:undefined}): O {
+    let decodedValue: any = payload;
+    let fromIndex = 0;
+    let untilIndex = this.decodingMethods.length;
+
+    const { from, until, ...rest } = config;
+
+    // Find the index of the specified start and until encoding methods
+    if(from) {
+      fromIndex = this.decodingMethods.findIndex((method) => method.name === from);
+      if(fromIndex === -1) {
+        throw new Error(`Encoding method ${from} not found`);
+      }
+    }
+
+    if(until) {
+      untilIndex = this.decodingMethods.findIndex((method) => method.name === until);
+      if(untilIndex === -1) {
+        throw new Error(`Encoding method ${until} not found`);
+      }
+    }
+
+    if(fromIndex > untilIndex) {
+      throw new Error("Invalid encoding method range");
+    }
+
+    // Apply each encoding method in sequence until the specified encoding method or the end
+    for (let i = fromIndex; i < untilIndex; i++) {
+      decodedValue = this.decodingMethods[i].decode(decodedValue, rest);
+    }
+
+    return decodedValue;
+  }
+
+  getMethod(methodName: EncodingMethodName): IEncodingMethod<any, any> {
+    return this.encodingMethods.find((method) => method.name === methodName);
+  }
+
+}

package/src/enums/EncodingMethodName.ts

@@ -0,0 +1,10 @@
+/**
+ * Defaultly used encoding methods.
+ */
+export enum EncodingMethodName {
+  bytewords = "bytewords",
+  cbor = "cbor",
+  hex = "hex",
+  pipe = "pipe",
+  ur = "ur",
+}

package/src/errors.ts

@@ -0,0 +1,34 @@
+export class InvalidSchemeError extends Error {
+  constructor() {
+    super("Invalid Scheme");
+    this.name = "InvalidSchemeError";
+  }
+}
+
+export class InvalidPathLengthError extends Error {
+  constructor() {
+    super("Invalid Path");
+    this.name = "InvalidPathLengthError";
+  }
+}
+
+export class InvalidTypeError extends Error {
+  constructor() {
+    super("Invalid Type");
+    this.name = "InvalidTypeError";
+  }
+}
+
+export class InvalidSequenceComponentError extends Error {
+  constructor() {
+    super("Invalid Sequence Component");
+    this.name = "InvalidSequenceComponentError";
+  }
+}
+
+export class InvalidChecksumError extends Error {
+  constructor() {
+    super("Invalid Checksum");
+    this.name = "InvalidChecksumError";
+  }
+}