@digitaldefiance/ecies-lib 1.1.23 → 1.1.24

package/src/member.ts

@@ -0,0 +1,429 @@
+import { Wallet } from '@ethereumjs/wallet';
+import { ECIES } from './constants';
+import { EmailString } from './email-string';
+import MemberErrorType from './enumerations/member-error-type';
+import MemberType from './enumerations/member-type';
+import { MemberError } from './errors/member';
+import { GuidV4 } from './guid';
+import { getEciesI18nEngine } from './i18n-setup';
+import { IMemberOperational } from './interfaces/member-operational';
+import { IMemberStorageData } from './interfaces/member-storage';
+import { IMemberWithMnemonic } from './interfaces/member-with-mnemonic';
+import { SecureBuffer } from './secure-buffer';
+import { SecureString } from './secure-string';
+import { ECIESService } from './services/ecies/service';
+import { SignatureUint8Array } from './types';
+import {
+  base64ToUint8Array,
+  uint8ArrayToBase64,
+  uint8ArrayToHex,
+} from './utils';
+import { IECIESConstants } from './interfaces/ecies-consts';
+
+/**
+ * Represents a member with cryptographic capabilities.
+ * This class provides methods for signing, verifying, encrypting, and decrypting data.
+ * It also manages the member's keys and wallet.
+ */
+export class Member implements IMemberOperational {
+  private readonly _eciesService: ECIESService;
+  private readonly _id: GuidV4;
+  private readonly _type: MemberType;
+  private readonly _name: string;
+  private readonly _email: EmailString;
+  private readonly _publicKey: Uint8Array;
+  private readonly _creatorId: GuidV4;
+  private readonly _dateCreated: Date;
+  private readonly _dateUpdated: Date;
+  private _privateKey?: SecureBuffer;
+  private _wallet?: Wallet;
+
+  constructor(
+    // Add injected services as parameters
+    eciesService: ECIESService,
+    // Original parameters
+    type: MemberType,
+    name: string,
+    email: EmailString,
+    publicKey: Uint8Array,
+    privateKey?: SecureBuffer,
+    wallet?: Wallet,
+    id?: GuidV4,
+    dateCreated?: Date,
+    dateUpdated?: Date,
+    creatorId?: GuidV4,
+  ) {
+    // Assign injected services
+    this._eciesService = eciesService;
+    // Assign original parameters
+    this._type = type;
+    this._id = id ?? GuidV4.new();
+    this._name = name;
+    if (!this._name || this._name.length == 0) {
+      throw new MemberError(
+        MemberErrorType.MissingMemberName,
+        getEciesI18nEngine() as any,
+      );
+    }
+    if (this._name.trim() != this._name) {
+      throw new MemberError(
+        MemberErrorType.InvalidMemberNameWhitespace,
+        getEciesI18nEngine() as any,
+      );
+    }
+    this._email = email;
+    this._publicKey = publicKey;
+    this._privateKey = privateKey;
+    this._wallet = wallet;
+
+    // don't create a new date object with nearly identical values to the existing one
+    let _now: null | Date = null;
+    const now = function () {
+      if (!_now) {
+        _now = new Date();
+      }
+      return _now;
+    };
+    this._dateCreated = dateCreated ?? now();
+    this._dateUpdated = dateUpdated ?? now();
+    this._creatorId = creatorId ?? this._id;
+  }
+
+  // Required getters
+  public get id(): GuidV4 {
+    return this._id;
+  }
+  public get type(): MemberType {
+    return this._type;
+  }
+  public get name(): string {
+    return this._name;
+  }
+  public get email(): EmailString {
+    return this._email;
+  }
+  public get publicKey(): Uint8Array {
+    return this._publicKey;
+  }
+  public get creatorId(): GuidV4 {
+    return this._creatorId;
+  }
+  public get dateCreated(): Date {
+    return this._dateCreated;
+  }
+  public get dateUpdated(): Date {
+    return this._dateUpdated;
+  }
+
+  // Optional private data getters
+  public get privateKey(): SecureBuffer | undefined {
+    return this._privateKey;
+  }
+  public get wallet(): Wallet {
+    if (!this._wallet) {
+      throw new MemberError(
+        MemberErrorType.NoWallet,
+        getEciesI18nEngine() as any,
+      );
+    }
+    return this._wallet;
+  }
+
+  // State getters
+  public get hasPrivateKey(): boolean {
+    return this._privateKey !== undefined;
+  }
+
+  public unloadPrivateKey(): void {
+    // Do not dispose here; tests expect the same SecureBuffer instance to remain usable
+    // when reloaded into another member in the same process.
+    this._privateKey = undefined;
+  }
+
+  public unloadWallet(): void {
+    this._wallet = undefined;
+  }
+
+  public unloadWalletAndPrivateKey(): void {
+    this.unloadWallet();
+    this.unloadPrivateKey();
+  }
+
+  public loadWallet(mnemonic: SecureString, eciesParams?: IECIESConstants): void {
+    if (this._wallet) {
+      throw new MemberError(
+        MemberErrorType.WalletAlreadyLoaded,
+        getEciesI18nEngine() as any,
+      );
+    }
+    const eciesConsts = eciesParams ?? ECIES;
+    const { wallet } = this._eciesService.walletAndSeedFromMnemonic(mnemonic);
+    const privateKey = wallet.getPrivateKey();
+    const publicKey = wallet.getPublicKey();
+    const publicKeyWithPrefix = new Uint8Array(publicKey.length + 1);
+    publicKeyWithPrefix[0] = eciesConsts.PUBLIC_KEY_MAGIC;
+    publicKeyWithPrefix.set(publicKey, 1);
+
+    if (
+      uint8ArrayToHex(publicKeyWithPrefix) !== uint8ArrayToHex(this._publicKey)
+    ) {
+      throw new MemberError(
+        MemberErrorType.InvalidMnemonic,
+        getEciesI18nEngine() as any,
+      );
+    }
+    this._wallet = wallet;
+    this._privateKey?.dispose();
+    this._privateKey = new SecureBuffer(privateKey);
+  }
+
+  /**
+   * Loads the private key and optionally the voting private key.
+   *
+   * @param privateKey The private key to load.
+   * @param votingPrivateKey The voting private key to load.
+   */
+  public loadPrivateKey(privateKey: SecureBuffer): void {
+    this._privateKey = privateKey;
+  }
+
+  public sign(data: Uint8Array): SignatureUint8Array {
+    if (!this._privateKey) {
+      throw new MemberError(
+        MemberErrorType.MissingPrivateKey,
+        getEciesI18nEngine() as any,
+      );
+    }
+    return this._eciesService.signMessage(this._privateKey.value, data);
+  }
+
+  public signData(data: Uint8Array): SignatureUint8Array {
+    if (!this._privateKey) {
+      throw new MemberError(
+        MemberErrorType.MissingPrivateKey,
+        getEciesI18nEngine() as any,
+      );
+    }
+    return this._eciesService.signMessage(
+      new Uint8Array(this._privateKey.value),
+      data,
+    );
+  }
+
+  public verify(signature: SignatureUint8Array, data: Uint8Array): boolean {
+    return this._eciesService.verifyMessage(this._publicKey, data, signature);
+  }
+
+  public verifySignature(
+    data: Uint8Array,
+    signature: Uint8Array,
+    publicKey: Uint8Array,
+  ): boolean {
+    return this._eciesService.verifyMessage(
+      publicKey,
+      data,
+      signature as SignatureUint8Array,
+    );
+  }
+
+  private static readonly MAX_ENCRYPTION_SIZE = 1024 * 1024 * 10; // 10MB limit
+  private static readonly VALID_STRING_REGEX = /^[\x20-\x7E\n\r\t]*$/; // Printable ASCII + common whitespace
+
+  public async encryptData(
+    data: string | Uint8Array,
+    recipientPublicKey?: Uint8Array,
+  ): Promise<Uint8Array> {
+    // Validate input
+    if (!data) {
+      throw new MemberError(
+        MemberErrorType.MissingEncryptionData,
+        getEciesI18nEngine() as any,
+      );
+    }
+
+    // Check size limit
+    const arr: Uint8Array =
+      data instanceof Uint8Array ? data : new TextEncoder().encode(data);
+    if (arr.length > Member.MAX_ENCRYPTION_SIZE) {
+      throw new MemberError(
+        MemberErrorType.EncryptionDataTooLarge,
+        getEciesI18nEngine() as any,
+      );
+    }
+
+    // Use recipient public key or self public key
+    const targetPublicKey = recipientPublicKey || this._publicKey;
+
+    return await this._eciesService.encryptSimpleOrSingle(
+      false,
+      targetPublicKey,
+      arr,
+    );
+  }
+
+  public async decryptData(encryptedData: Uint8Array): Promise<Uint8Array> {
+    if (!this._privateKey) {
+      throw new MemberError(
+        MemberErrorType.MissingPrivateKey,
+        getEciesI18nEngine() as any,
+      );
+    }
+    // decryptSingleWithHeader now returns the Uint8Array directly
+    return await this._eciesService.decryptSimpleOrSingleWithHeader(
+      false,
+      new Uint8Array(this._privateKey.value),
+      encryptedData,
+    );
+  }
+
+  public toJson(): string {
+    const storage: IMemberStorageData = {
+      id: this._id.toString(),
+      type: this._type,
+      name: this._name,
+      email: this._email.toString(),
+      publicKey: uint8ArrayToBase64(this._publicKey),
+      creatorId: this._creatorId.toString(),
+      dateCreated: this._dateCreated.toISOString(),
+      dateUpdated: this._dateUpdated.toISOString(),
+    };
+    return JSON.stringify(storage);
+  }
+
+  public dispose(): void {
+    // Ensure secret material is zeroized when disposing
+    try {
+      this._privateKey?.dispose();
+    } finally {
+      this.unloadWalletAndPrivateKey();
+    }
+  }
+
+  public static fromJson(
+    json: string,
+    // Add injected services as parameters
+    eciesService: ECIESService,
+  ): Member {
+    let storage: IMemberStorageData;
+    try {
+      storage = JSON.parse(json);
+    } catch (error) {
+      throw new MemberError(
+        MemberErrorType.InvalidMemberData,
+        getEciesI18nEngine() as any,
+      );
+    }
+    const email = new EmailString(storage.email);
+
+    // Pass injected services to constructor
+    const dateCreated = new Date(storage.dateCreated);
+    return new Member(
+      eciesService,
+      storage.type,
+      storage.name,
+      email,
+      base64ToUint8Array(storage.publicKey),
+      undefined,
+      undefined,
+      new GuidV4(storage.id),
+      dateCreated,
+      new Date(storage.dateUpdated),
+      new GuidV4(storage.creatorId),
+    );
+  }
+
+  public static fromMnemonic(
+    mnemonic: SecureString,
+    eciesService: ECIESService,
+    eciesParams?: IECIESConstants,
+  ): Member {
+    const eciesConsts = eciesParams ?? ECIES;
+    const { wallet } = eciesService.walletAndSeedFromMnemonic(mnemonic);
+    const privateKey = wallet.getPrivateKey();
+    const publicKey = wallet.getPublicKey();
+    const publicKeyWithPrefix = new Uint8Array(publicKey.length + 1);
+    publicKeyWithPrefix[0] = eciesConsts.PUBLIC_KEY_MAGIC;
+    publicKeyWithPrefix.set(publicKey, 1);
+
+    return new Member(
+      eciesService,
+      MemberType.User,
+      'Test User',
+      new EmailString('test@example.com'),
+      publicKeyWithPrefix,
+      new SecureBuffer(privateKey),
+      wallet,
+    );
+  }
+
+  public static newMember(
+    // Add injected services as parameters
+    eciesService: ECIESService,
+    // Original parameters
+    type: MemberType,
+    name: string,
+    email: EmailString,
+    forceMnemonic?: SecureString,
+    createdBy?: GuidV4,
+    eciesParams?: IECIESConstants,
+  ): IMemberWithMnemonic {
+    // Validate inputs first
+    if (!name || name.length == 0) {
+      throw new MemberError(
+        MemberErrorType.MissingMemberName,
+        getEciesI18nEngine() as any,
+      );
+    }
+    if (name.trim() != name) {
+      throw new MemberError(
+        MemberErrorType.InvalidMemberNameWhitespace,
+        getEciesI18nEngine() as any,
+      );
+    }
+    if (!email || email.toString().length == 0) {
+      throw new MemberError(
+        MemberErrorType.MissingEmail,
+        getEciesI18nEngine() as any,
+      );
+    }
+    if (email.toString().trim() != email.toString()) {
+      throw new MemberError(
+        MemberErrorType.InvalidEmailWhitespace,
+        getEciesI18nEngine() as any,
+      );
+    }
+
+    const eciesConsts = eciesParams ?? ECIES;
+    // Use injected services
+    const mnemonic = forceMnemonic ?? eciesService.generateNewMnemonic();
+    const { wallet } = eciesService.walletAndSeedFromMnemonic(mnemonic);
+
+    // Get private key from wallet
+    const privateKey = wallet.getPrivateKey();
+    // Get public key with 0x04 prefix
+    const publicKey = wallet.getPublicKey();
+    const publicKeyWithPrefix = new Uint8Array(publicKey.length + 1);
+    publicKeyWithPrefix[0] = eciesConsts.PUBLIC_KEY_MAGIC;
+    publicKeyWithPrefix.set(publicKey, 1);
+
+    const newId = GuidV4.new();
+    const dateCreated = new Date();
+    return {
+      // Pass injected services to constructor
+      member: new Member(
+        eciesService,
+        type,
+        name,
+        email,
+        publicKeyWithPrefix,
+        new SecureBuffer(privateKey),
+        wallet,
+        newId,
+        dateCreated,
+        dateCreated,
+        createdBy ?? newId,
+      ),
+      mnemonic,
+    };
+  }
+}

package/{dist/pbkdf2-profiles.d.ts → src/pbkdf2-profiles.ts}

@@ -1,6 +1,6 @@
 import { Pbkdf2ProfileEnum } from './enumerations/pbkdf2-profile';
 import { IPbkdf2Config } from './interfaces/pbkdf2-config';
+
 export type Pbkdf2Profiles = {
-    [key in Pbkdf2ProfileEnum]: IPbkdf2Config;
+  [key in Pbkdf2ProfileEnum]: IPbkdf2Config;
 };
-//# sourceMappingURL=pbkdf2-profiles.d.ts.map

package/src/phone-number.ts

@@ -0,0 +1,18 @@
+import { EciesStringKey } from './enumerations';
+import { EciesComponentId, getEciesI18nEngine } from './i18n-setup';
+import { PhoneNumberRegex } from './regexes';
+
+export class PhoneNumber {
+  private readonly _number: string;
+  constructor(number: string) {
+    // make sure the phone number fits the regex
+    if (!PhoneNumberRegex.test(number)) {
+      const engine = getEciesI18nEngine();
+      throw new Error(engine.translate(EciesComponentId, EciesStringKey.Error_PhoneNumber_InvalidTemplate, { phoneNumber: number }));
+    }
+    this._number = number;
+  }
+  public get number(): string {
+    return this._number;
+  }
+}

package/src/regexes.ts

@@ -0,0 +1,10 @@
+export const PASSWORD_REGEX =
+  /^(?=.*[A-Za-z])(?=.*\d)(?=.*[!@#$%^&*()_+\-=[\]{};':"\\|,.<>/?])[A-Za-z\d!@#$%^&*()_+\-=[\]{};':"\\|,.<>/?]{8,}$/;
+
+export const MNEMONIC_REGEX =
+  /^(?:\w+\s){11}\w+$|^(?:\w+\s){14}\w+$|^(?:\w+\s){17}\w+$|^(?:\w+\s){20}\w+$|^(?:\w+\s){23}\w+$/i;
+
+/**
+ * Phone number regex to validate phone numbers
+ */
+export const PhoneNumberRegex = /^(\+\d{1,3}[- ]?)?\d{10}$/; // Matches international phone numbers with optional country code

package/src/secure-buffer.ts

@@ -0,0 +1,183 @@
+import { SecureStorageErrorType } from './enumerations/secure-storage-error-type';
+import { DisposedError } from './errors/disposed';
+import { SecureStorageError } from './errors/secure-storage';
+import { GuidV4 } from './guid';
+import { getEciesI18nEngine } from './i18n-setup';
+import { XorService } from './services/xor';
+import { FullHexGuid, RawGuidUint8Array } from './types';
+import { uint8ArrayToHex } from './utils';
+
+/**
+ * A secure string buffer is a buffer whose intent is to prevent the raw password from being stored in memory.
+ * The buffer is encrypted with a key derived from a GUID.
+ * The GUID is stored in the clear, but the buffer is encrypted with a key derived from the GUID.
+ * This allows the buffer to be decrypted, but only if the GUID and salt are known.
+ */
+export class SecureBuffer {
+  private _disposed: boolean = false;
+  private readonly _id: GuidV4;
+  private readonly _length: number;
+  private readonly _obfuscatedValue: Uint8Array;
+  private readonly _key: Uint8Array;
+  private readonly _obfuscatedChecksum: Uint8Array;
+  private _disposedAt?: string;
+  constructor(data?: Uint8Array) {
+    this._id = GuidV4.new();
+    // don't bother encrypting an empty buffer
+    if (data === undefined || data.length === 0) {
+      this._length = 0;
+      this._obfuscatedValue = new Uint8Array(0);
+      this._key = new Uint8Array(0);
+      this._obfuscatedChecksum = new Uint8Array(0);
+      return;
+    }
+    this._length = data.length;
+    this._key = this.idUint8Array;
+    this._obfuscatedValue = this.obfuscateData(data);
+    // Create a simple checksum without crypto for synchronous operation
+    this._obfuscatedChecksum = this.createSimpleObfuscatedChecksum(data);
+  }
+  public dispose(): void {
+    const err = new DisposedError();
+    if (typeof (Error as any).captureStackTrace === 'function') {
+      (Error as any).captureStackTrace(err, this.dispose);
+    }
+    this._disposedAt = err.stack ?? 'stack unavailable';
+    this._obfuscatedValue.fill(0);
+    this._key.fill(0);
+    this._obfuscatedChecksum.fill(0);
+    this._disposed = true;
+  }
+  private assertNotDisposed(): void {
+    if (this._disposed) {
+      const e = new DisposedError();
+      try {
+        (e as any).disposedAt = this._disposedAt;
+      } catch {
+        // ignore if Error object is sealed/frozen
+      }
+      throw e;
+    }
+  }
+  public static fromString(data: string): SecureBuffer {
+    return new SecureBuffer(new TextEncoder().encode(data));
+  }
+  public get disposedAtStack(): string | undefined {
+    return this._disposedAt;
+  }
+  public get id(): FullHexGuid {
+    this.assertNotDisposed();
+    return this._id.asFullHexGuid;
+  }
+  public get idUint8Array(): RawGuidUint8Array {
+    this.assertNotDisposed();
+    return this._id.asRawGuidUint8Array;
+  }
+  public get originalLength(): number {
+    this.assertNotDisposed();
+    return this._length;
+  }
+  public get value(): Uint8Array {
+    this.assertNotDisposed();
+    if (this._length === 0) {
+      return new Uint8Array(0);
+    }
+    try {
+      const deobfuscatedResult = this.deobfuscateData(this._obfuscatedValue);
+      if (deobfuscatedResult.length !== this._length) {
+        throw new SecureStorageError(
+          SecureStorageErrorType.DecryptedValueLengthMismatch,
+          getEciesI18nEngine() as any,
+        );
+      }
+      if (!this.validateObfuscatedChecksum(deobfuscatedResult)) {
+        throw new SecureStorageError(
+          SecureStorageErrorType.DecryptedValueChecksumMismatch,
+          getEciesI18nEngine() as any,
+        );
+      }
+      return deobfuscatedResult;
+    } catch (error) {
+      // If it's already a SecureStorageError, re-throw it
+      if (error instanceof SecureStorageError) {
+        throw error;
+      }
+      // Convert any other error (including AES-GCM authentication errors) to SecureStorageError
+      throw new SecureStorageError(
+        SecureStorageErrorType.DecryptedValueChecksumMismatch,
+        getEciesI18nEngine() as any,
+      );
+    }
+  }
+  public get valueAsString(): string {
+    this.assertNotDisposed();
+    return new TextDecoder().decode(this.value);
+  }
+  public get valueAsHexString(): string {
+    this.assertNotDisposed();
+    return uint8ArrayToHex(this.value);
+  }
+  public get valueAsBase64String(): string {
+    this.assertNotDisposed();
+    return btoa(String.fromCharCode(...this.value));
+  }
+  public get checksum(): string {
+    this.assertNotDisposed();
+    const deobfuscatedChecksum = new TextDecoder().decode(
+      this.deobfuscateData(this._obfuscatedChecksum),
+    );
+    return deobfuscatedChecksum;
+  }
+  private generateSimpleChecksum(data: string | Uint8Array): string {
+    const dataBytes =
+      typeof data === 'string' ? new TextEncoder().encode(data) : data;
+    let hash = 0;
+    for (let i = 0; i < dataBytes.length; i++) {
+      hash = ((hash << 5) - hash + dataBytes[i]) & 0xffffffff;
+    }
+    return hash.toString(16);
+  }
+  private createSimpleObfuscatedChecksum(
+    data: string | Uint8Array,
+  ): Uint8Array {
+    const checksum = this.generateSimpleChecksum(data);
+    const result = this.obfuscateData(new TextEncoder().encode(checksum));
+    return result;
+  }
+  private validateSimpleChecksum(
+    data: string | Uint8Array,
+    checksum: string,
+  ): boolean {
+    const generatedChecksum = this.generateSimpleChecksum(data);
+    const a = new TextEncoder().encode(generatedChecksum);
+    const b = new TextEncoder().encode(checksum);
+    return this.timingSafeEqual(a, b);
+  }
+
+  private timingSafeEqual(a: Uint8Array, b: Uint8Array): boolean {
+    if (a.length !== b.length) {
+      return false;
+    }
+    let result = 0;
+    for (let i = 0; i < a.length; i++) {
+      result |= a[i] ^ b[i];
+    }
+    return result === 0;
+  }
+  private validateObfuscatedChecksum(data: string | Uint8Array): boolean {
+    const deobfuscatedChecksum = new TextDecoder().decode(
+      this.deobfuscateData(this._obfuscatedChecksum),
+    );
+    return this.validateSimpleChecksum(data, deobfuscatedChecksum);
+  }
+  private obfuscateData(data: Uint8Array): Uint8Array {
+    return XorService.xor(data, this._key);
+  }
+  private deobfuscateData(data: Uint8Array): Uint8Array {
+    return XorService.xor(data, this._key);
+  }
+  public get length(): number {
+    this.assertNotDisposed();
+    return this._length;
+  }
+}