@abaxxtech/id 0.0.0

package/src/types/records-types.ts

@@ -0,0 +1,184 @@
+import type { EncryptionAlgorithm } from '../utils/encryption.js';
+import type { GeneralJws } from './jws-types.js';
+import type { GenericMessageReply } from '../core/message-reply.js';
+import type { KeyDerivationScheme } from '../utils/hd-key.js';
+import type { PublicJwk } from './jose-types.js';
+import type { RangeFilter } from './message-types.js';
+import type { Readable } from 'readable-stream';
+import type { AuthorizationModel, GenericMessage, GenericSignaturePayload, Pagination } from './message-types.js';
+import type { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
+
+export enum DateSort {
+  CreatedAscending = 'createdAscending',
+  CreatedDescending = 'createdDescending',
+  PublishedAscending = 'publishedAscending',
+  PublishedDescending = 'publishedDescending'
+}
+
+export type RecordsWriteDescriptor = {
+  interface: DwnInterfaceName.Records;
+  method: DwnMethodName.Write;
+  protocol?: string;
+  protocolPath?: string;
+  recipient?: string;
+  schema?: string;
+  parentId?: string;
+  dataCid: string;
+  dataSize: number;
+  dateCreated: string;
+  messageTimestamp: string;
+  published?: boolean;
+  datePublished?: string;
+  dataFormat: string;
+};
+
+export type RecordsWriteReply = GenericMessageReply;
+
+/**
+ * Internal RecordsWrite message representation that can be in an incomplete state.
+ */
+export type InternalRecordsWriteMessage = GenericMessage & {
+  recordId?: string,
+  contextId?: string;
+  descriptor: RecordsWriteDescriptor;
+  attestation?: GeneralJws;
+  encryption?: EncryptionProperty;
+};
+
+export type RecordsWriteMessage = GenericMessage & {
+  authorization: AuthorizationModel; // overriding `GenericMessage` with `authorization` being required
+  recordId: string,
+  contextId?: string;
+  descriptor: RecordsWriteDescriptor;
+  attestation?: GeneralJws;
+  encryption?: EncryptionProperty;
+};
+
+/**
+ * records with a data size below a threshold are stored within MessageStore with their data embedded
+ */
+export type RecordsWriteMessageWithOptionalEncodedData = RecordsWriteMessage & { encodedData?: string };
+
+export type EncryptionProperty = {
+  algorithm: EncryptionAlgorithm;
+  initializationVector: string;
+  keyEncryption: EncryptedKey[]
+};
+
+export type EncryptedKey = {
+  /**
+   * The fully qualified key ID (e.g. did:example:abc#encryption-key-id) of the root public key used to encrypt the symmetric encryption key.
+   */
+  rootKeyId: string;
+
+  /**
+   * The actual derived public key.
+   */
+  derivedPublicKey?: PublicJwk;
+  derivationScheme: KeyDerivationScheme;
+  algorithm: EncryptionAlgorithm;
+  initializationVector: string;
+  ephemeralPublicKey: PublicJwk;
+  messageAuthenticationCode: string;
+  encryptedKey: string;
+};
+
+/**
+ * Data structure returned in a `RecordsQuery` reply entry.
+ * NOTE: the message structure is a modified version of the message received, the most notable differences are:
+ * 1. does not contain `authorization`
+ * 2. may include encoded data
+ */
+export type RecordsQueryReplyEntry = RecordsWriteMessage & {
+  encodedData?: string;
+};
+
+export type RecordsQueryDescriptor = {
+  interface: DwnInterfaceName.Records;
+  method: DwnMethodName.Query;
+  messageTimestamp: string;
+  filter: RecordsFilter;
+  dateSort?: DateSort;
+  pagination?: Pagination;
+};
+
+export type RecordsFilter = {
+  author?: string;
+  attester?: string;
+  recipient?: string;
+  protocol?: string;
+  protocolPath?: string;
+  published?: boolean;
+  contextId?: string;
+  schema?: string;
+  recordId?: string;
+  parentId?: string;
+  dataFormat?: string;
+  dataSize?: RangeFilter;
+  dataCid?: string;
+  dateCreated?: RangeCriterion;
+  datePublished?: RangeCriterion;
+  dateUpdated?: RangeCriterion;
+};
+
+export type RangeCriterion = {
+  /**
+   * Inclusive starting date-time.
+   */
+  from?: string;
+
+  /**
+   * Inclusive end date-time.
+   */
+  to?: string;
+};
+
+export type RecordsWriteAttestationPayload = {
+  descriptorCid: string;
+};
+
+export type RecordsWriteSignaturePayload = GenericSignaturePayload & {
+  recordId: string;
+  contextId?: string;
+  attestationCid?: string;
+  encryptionCid?: string;
+};
+
+export type RecordsQueryMessage = GenericMessage & {
+  descriptor: RecordsQueryDescriptor;
+};
+
+export type RecordsQueryReply = GenericMessageReply & {
+  entries?: RecordsQueryReplyEntry[];
+  cursor?: string;
+};
+
+export type RecordsReadMessage = {
+  authorization?: AuthorizationModel;
+  descriptor: RecordsReadDescriptor;
+};
+
+export type RecordsReadReply = GenericMessageReply & {
+  record?: RecordsWriteMessage & {
+    data: Readable;
+  }
+};
+
+export type RecordsReadDescriptor = {
+  interface: DwnInterfaceName.Records;
+  method: DwnMethodName.Read;
+  filter: RecordsFilter;
+  messageTimestamp: string;
+};
+
+export type RecordsDeleteMessage = GenericMessage & {
+  authorization: AuthorizationModel; // overriding `GenericMessage` with `authorization` being required
+  descriptor: RecordsDeleteDescriptor;
+};
+
+export type RecordsDeleteDescriptor = {
+  interface: DwnInterfaceName.Records;
+  method: DwnMethodName.Delete;
+  recordId: string;
+  messageTimestamp: string;
+};

package/src/types/signer.ts

@@ -0,0 +1,27 @@
+/**
+ * A signer that is capable of generating a digital signature over any given bytes.
+ */
+export interface Signer {
+  /**
+   * The ID of the key used by this signer.
+   * This needs to be a fully-qualified ID (ie. prefixed with DID) so that author can be parsed out for processing such as `recordId` computation.
+   * Example: did:example:alice#key1
+   * This value will be used as the "kid" parameter in JWS produced.
+   * While this property is not a required property per JWS specification, it is required for DWN authentication.
+   */
+  keyId: string
+
+  /**
+   * The name of the signature algorithm used by this signer.
+   * This value will be used as the "alg" parameter in JWS produced.
+   * This parameter is not used by the DWN but is unfortunately a required header property for a JWS as per:
+   * https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.1
+   * Valid signature algorithm values can be found at https://www.iana.org/assignments/jose/jose.xhtml
+   */
+  algorithm: string;
+
+  /**
+   * Signs the given content and returns the signature as bytes.
+   */
+  sign (content: Uint8Array): Promise<Uint8Array>;
+}

package/src/utils/abort.ts

@@ -0,0 +1,31 @@
+/**
+ * Wraps the given `AbortSignal` in a `Promise` that rejects if it is programmatically triggered,
+ * otherwise the promise will remain in await state (will never resolve).
+ */
+function promisifySignal<T>(signal: AbortSignal): Promise<T> {
+  return new Promise((resolve, reject) => {
+    // immediately reject if the given is signal is already aborted
+    if (signal.aborted) {
+      reject(signal.reason);
+      return;
+    }
+
+    signal.addEventListener('abort', () => {
+      reject(signal.reason);
+    });
+  });
+}
+
+/**
+ * Wraps the given `Promise` such that it will reject if the `AbortSignal` is triggered.
+ */
+export async function executeUnlessAborted<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T> {
+  if (!signal) {
+    return promise;
+  }
+
+  return Promise.race([
+    promise,
+    promisifySignal<T>(signal),
+  ]);
+}

package/src/utils/array.ts

@@ -0,0 +1,39 @@
+/**
+ * Array utility methods.
+ */
+export class ArrayUtility {
+  /**
+   * Returns `true` if content of the two given byte arrays are equal; `false` otherwise.
+   */
+  public static byteArraysEqual(array1: Uint8Array, array2:Uint8Array): boolean {
+    const equal = array1.length === array2.length && array1.every((value, index) => value === array2[index]);
+    return equal;
+  }
+
+  /**
+   * Asynchronously iterates an {AsyncGenerator} to return all the values in an array.
+   */
+  public static async fromAsyncGenerator<T>(iterator: AsyncGenerator<T>): Promise<Array<T>> {
+    const array: Array<T> = [ ];
+    for await (const value of iterator) {
+      array.push(value);
+    }
+    return array;
+  }
+
+  /**
+   * Generic asynchronous sort method.
+   */
+  public static async asyncSort<T>(array: T[], asyncComparer: (a: T, b: T) => Promise<number>): Promise<T[]> {
+    // this is a bubble sort implementation
+    for (let i = 0; i < array.length; i++) {
+      for (let j = i + 1; j < array.length; j++) {
+        const comparison = await asyncComparer(array[i], array[j]);
+        if (comparison > 0) {
+          [array[i], array[j]] = [array[j], array[i]]; // Swap
+        }
+      }
+    }
+    return array;
+  }
+}

package/src/utils/cid.ts

@@ -0,0 +1,101 @@
+import * as cbor from '@ipld/dag-cbor';
+
+import type { Readable } from 'readable-stream';
+
+import { CID } from 'multiformats/cid';
+import { importer } from 'ipfs-unixfs-importer';
+import { MemoryBlockstore } from 'blockstore-core';
+import { sha256 } from 'multiformats/hashes/sha2';
+import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
+
+// a map of all supported CID hashing algorithms. This map is used to select the appropriate hasher
+// when generating a CID to compare against a provided CID
+const hashers = {
+  [sha256.code as number]: sha256,
+};
+
+// a map of all support codecs.This map is used to select the appropriate codec
+// when generating a CID to compare against a provided CID
+const codecs = {
+  [cbor.code as number]: cbor
+};
+
+/**
+ * Utility class for creating CIDs. Exported for the convenience of developers.
+ */
+export class Cid {
+
+  /**
+   * Computes a V1 CID for the provided payload
+   * @param codecCode - the codec to use. Defaults to cbor
+   * @param multihashCode - the multihasher to use. Defaults to sha256
+   * @returns payload CID
+   * @throws {Error} codec is not supported
+   * @throws {Error} encoding fails
+   * @throws {Error} if hasher is not supported
+   */
+  public static async computeCid(
+    payload: any,
+    codecCode: number = cbor.code,
+    multihashCode: number = sha256.code
+  ): Promise<string> {
+    const codec = codecs[codecCode];
+    if (!codec) {
+      throw new DwnError(DwnErrorCode.ComputeCidCodecNotSupported, `codec [${codecCode}] not supported`);
+    }
+
+    const hasher = hashers[multihashCode];
+    if (!hasher) {
+      throw new DwnError(DwnErrorCode.ComputeCidMultihashNotSupported, `multihash code [${multihashCode}] not supported`);
+    }
+
+    const payloadBytes = codec.encode(payload);
+    const payloadHash = await hasher.digest(payloadBytes);
+
+    const cid = await CID.createV1(codec.code, payloadHash);
+    return cid.toString();
+  }
+
+  /**
+   * Parses the given CID string into a {CID}.
+   */
+  public static parseCid(str: string): CID {
+    const cid: CID = CID.parse(str).toV1();
+
+    if (!codecs[cid.code]) {
+      throw new DwnError(DwnErrorCode.ParseCidCodecNotSupported, `codec [${cid.code}] not supported`);
+    }
+
+    if (!hashers[cid.multihash.code]) {
+      throw new DwnError(DwnErrorCode.ParseCidMultihashNotSupported, `multihash code [${cid.multihash.code}] not supported`);
+    }
+
+    return cid;
+  }
+
+  /**
+   * @returns V1 CID of the DAG comprised by chunking data into unixfs DAG-PB encoded blocks
+   */
+  public static async computeDagPbCidFromBytes(content: Uint8Array): Promise<string> {
+    const asyncDataBlocks = importer([{ content }], new MemoryBlockstore(), { cidVersion: 1 });
+
+    // NOTE: the last block contains the root CID
+    let block;
+    for await (block of asyncDataBlocks) { ; }
+
+    return block ? block.cid.toString() : '';
+  }
+
+  /**
+   * @returns V1 CID of the DAG comprised by chunking data into unixfs DAG-PB encoded blocks
+   */
+  public static async computeDagPbCidFromStream(dataStream: Readable): Promise<string> {
+    const asyncDataBlocks = importer([{ content: dataStream }], new MemoryBlockstore(), { cidVersion: 1 });
+
+    // NOTE: the last block contains the root CID
+    let block;
+    for await (block of asyncDataBlocks) { ; }
+
+    return block ? block.cid.toString() : '';
+  }
+}

package/src/utils/data-stream.ts

@@ -0,0 +1,85 @@
+import { Encoder } from './encoder.js';
+import { Readable } from 'readable-stream';
+
+/**
+ * Utility class for readable data stream, intentionally named to disambiguate from ReadableStream, readable-stream, Readable etc.
+ */
+export class DataStream {
+  /**
+   * Reads the entire readable stream given into array of bytes.
+   */
+  public static async toBytes(readableStream: Readable): Promise<Uint8Array> {
+    return new Promise((resolve, reject) => {
+      const chunks: any[] = [];
+      readableStream.on('data', chunk => {
+        chunks.push(chunk);
+      });
+
+      readableStream.on('end', () => {
+        const uint8Array = DataStream.concatenateArrayOfBytes(chunks);
+        resolve(uint8Array);
+      });
+
+      readableStream.on('error', reject);
+    });
+  }
+
+  /**
+   * Reads the entire readable stream and JSON parses it into an object.
+   */
+  public static async toObject(readableStream: Readable): Promise<object> {
+    const contentBytes = await DataStream.toBytes(readableStream);
+    const contentObject: any = Encoder.bytesToObject(contentBytes);
+    return contentObject;
+  }
+
+  /**
+   * Concatenates the array of bytes given into one Uint8Array.
+   */
+  private static concatenateArrayOfBytes(arrayOfBytes: Uint8Array[]): Uint8Array {
+    // sum of individual array lengths
+    const totalLength = arrayOfBytes.reduce((accumulatedValue, currentValue) => accumulatedValue + currentValue.length, 0);
+
+    const result = new Uint8Array(totalLength);
+
+    let length = 0;
+    for (const bytes of arrayOfBytes) {
+      result.set(bytes, length);
+      length += bytes.length;
+    }
+
+    return result;
+  }
+
+  /**
+   * Creates a readable stream from the bytes given.
+   */
+  public static fromBytes(bytes: Uint8Array): Readable {
+    // chunk up the bytes to simulate a more real-world like behavior
+    const chunkLength = 100_000;
+    let currentIndex = 0;
+    const readableStream = new Readable({
+      read(_size): void {
+        // if this is the last chunk
+        if (currentIndex + chunkLength > bytes.length) {
+          this.push(bytes.subarray(currentIndex));
+          this.push(null);
+        } else {
+          this.push(bytes.subarray(currentIndex, currentIndex + chunkLength));
+
+          currentIndex = currentIndex + chunkLength;
+        }
+      }
+    });
+
+    return readableStream;
+  }
+
+  /**
+   * Creates a readable stream from the object given.
+   */
+  public static fromObject(object: Record<string, any>): Readable {
+    const bytes = Encoder.objectToBytes(object);
+    return DataStream.fromBytes(bytes);
+  }
+}

package/src/utils/encoder.ts

@@ -0,0 +1,54 @@
+import { base64url } from 'multiformats/bases/base64';
+
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+
+/**
+ * Utility class for encoding/converting data into various formats.
+ */
+export class Encoder {
+
+  public static base64UrlToBytes(base64urlString: string): Uint8Array {
+    const content = base64url.baseDecode(base64urlString);
+    return content;
+  }
+
+  public static base64UrlToObject(base64urlString: string): any {
+    const payloadBytes = base64url.baseDecode(base64urlString);
+    const payloadObject = Encoder.bytesToObject(payloadBytes);
+    return payloadObject;
+  }
+
+  public static bytesToBase64Url(bytes: Uint8Array): string {
+    const base64UrlString = base64url.baseEncode(bytes);
+    return base64UrlString;
+  }
+
+  public static bytesToString(content: Uint8Array): string {
+    const bytes = textDecoder.decode(content);
+    return bytes;
+  }
+
+  public static bytesToObject(content: Uint8Array): object {
+    const contentString = Encoder.bytesToString(content);
+    const contentObject = JSON.parse(contentString);
+    return contentObject;
+  }
+
+  public static objectToBytes(obj: Record<string, any>): Uint8Array {
+    const objectString = JSON.stringify(obj);
+    const objectBytes = textEncoder.encode(objectString);
+    return objectBytes;
+  }
+
+  public static stringToBase64Url(content: string): string {
+    const bytes = textEncoder.encode(content);
+    const base64UrlString = base64url.baseEncode(bytes);
+    return base64UrlString;
+  }
+
+  public static stringToBytes(content: string): Uint8Array {
+    const bytes = textEncoder.encode(content);
+    return bytes;
+  }
+}

package/src/utils/encryption.ts

@@ -0,0 +1,145 @@
+import * as crypto from 'crypto';
+import * as eciesjs from 'eciesjs';
+import { Readable } from 'readable-stream';
+
+// compress publicKey for message encryption
+eciesjs.ECIES_CONFIG.isEphemeralKeyCompressed = true;
+
+/**
+ * Utility class for performing common, non-DWN specific encryption operations.
+ */
+export class Encryption {
+  /**
+   * Encrypts the given plaintext stream using AES-256-CTR algorithm.
+   */
+  public static async aes256CtrEncrypt(key: Uint8Array, initializationVector: Uint8Array, plaintextStream: Readable): Promise<Readable> {
+    const cipher = crypto.createCipheriv('aes-256-ctr', key, initializationVector);
+
+    const cipherStream = new Readable({
+      read(): void { }
+    });
+
+    plaintextStream.on('data', (chunk) => {
+      const encryptedChunk = cipher.update(chunk);
+      cipherStream.push(encryptedChunk);
+    });
+
+    plaintextStream.on('end', () => {
+      const finalChunk = cipher.final();
+      cipherStream.push(finalChunk);
+      cipherStream.push(null);
+    });
+
+    plaintextStream.on('error', (err) => {
+      cipherStream.emit('error', err);
+    });
+
+    return cipherStream;
+  }
+
+  /**
+   * Decrypts the given cipher stream using AES-256-CTR algorithm.
+   */
+  public static async aes256CtrDecrypt(key: Uint8Array, initializationVector: Uint8Array, cipherStream: Readable): Promise<Readable> {
+    const decipher = crypto.createDecipheriv('aes-256-ctr', key, initializationVector);
+
+    const plaintextStream = new Readable({
+      read(): void { }
+    });
+
+    cipherStream.on('data', (chunk) => {
+      const decryptedChunk = decipher.update(chunk);
+      plaintextStream.push(decryptedChunk);
+    });
+
+    cipherStream.on('end', () => {
+      const finalChunk = decipher.final();
+      plaintextStream.push(finalChunk);
+      plaintextStream.push(null);
+    });
+
+    cipherStream.on('error', (err) => {
+      plaintextStream.emit('error', err);
+    });
+
+    return plaintextStream;
+  }
+
+  /**
+   * Encrypts the given plaintext using ECIES (Elliptic Curve Integrated Encryption Scheme)
+   * with SECP256K1 for the asymmetric calculations, HKDF as the key-derivation function,
+   * and AES-GCM for the symmetric encryption and MAC algorithms.
+   */
+  public static async eciesSecp256k1Encrypt(publicKeyBytes: Uint8Array, plaintext: Uint8Array): Promise<EciesEncryptionOutput> {
+    // underlying library requires Buffer as input
+    const publicKey = Buffer.from(publicKeyBytes);
+    const plaintextBuffer = Buffer.from(plaintext);
+
+    const cryptogram = eciesjs.encrypt(publicKey, plaintextBuffer);
+
+    // split cryptogram returned into constituent parts
+    let start = 0;
+    let end = Encryption.isEphemeralKeyCompressed ? 33 : 65;
+    const ephemeralPublicKey = cryptogram.subarray(start, end);
+
+    start = end;
+    end += eciesjs.ECIES_CONFIG.symmetricNonceLength;
+    const initializationVector = cryptogram.subarray(start, end);
+
+    start = end;
+    end += 16; // eciesjs.consts.AEAD_TAG_LENGTH
+    const messageAuthenticationCode = cryptogram.subarray(start, end);
+
+    const ciphertext = cryptogram.subarray(end);
+
+    return {
+      ciphertext,
+      ephemeralPublicKey,
+      initializationVector,
+      messageAuthenticationCode
+    };
+  }
+
+  /**
+   * Decrypt the given plaintext using ECIES (Elliptic Curve Integrated Encryption Scheme)
+   * with SECP256K1 for the asymmetric calculations, HKDF as the key-derivation function,
+   * and AES-GCM for the symmetric encryption and MAC algorithms.
+   */
+  public static async eciesSecp256k1Decrypt(input: EciesEncryptionInput): Promise<Uint8Array> {
+    // underlying library requires Buffer as input
+    const privateKeyBuffer = Buffer.from(input.privateKey);
+    const eciesEncryptionOutput = Buffer.concat([
+      input.ephemeralPublicKey,
+      input.initializationVector,
+      input.messageAuthenticationCode,
+      input.ciphertext
+    ]);
+
+    const plaintext = eciesjs.decrypt(privateKeyBuffer, eciesEncryptionOutput);
+
+    return plaintext;
+  }
+
+  /**
+   * Expose eciesjs library configuration
+   */
+  static get isEphemeralKeyCompressed():boolean {
+    return eciesjs.ECIES_CONFIG.isEphemeralKeyCompressed;
+  }
+}
+
+export type EciesEncryptionOutput = {
+  initializationVector: Uint8Array;
+  ephemeralPublicKey: Uint8Array;
+  ciphertext: Uint8Array;
+  messageAuthenticationCode: Uint8Array;
+};
+
+export type EciesEncryptionInput = EciesEncryptionOutput & {
+  privateKey: Uint8Array;
+};
+
+export enum EncryptionAlgorithm {
+  Aes256Ctr = 'A256CTR',
+  EciesSecp256k1 = 'ECIES-ES256K'
+}