@digitaldefiance/ecies-lib 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Digital Defiance
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,237 @@
+# @digitaldefiance/ecies-lib
+
+A production-ready, browser-friendly implementation of Elliptic Curve Integrated Encryption Scheme (ECIES) and related primitives for modern TypeScript runtimes. The library ships with end-to-end test coverage, high-level services for common workflows, and low-level utilities you can compose to build secure storage, file sharing, and password-login flows.
+
+## Highlights
+
+- **Web & Node compatible** – built around the Web Crypto API (`crypto.subtle`) and `secp256k1` from `@noble/curves`, tested against Node 18+ and headless browser environments.
+- **Multiple ECIES modes** – "simple" (no length metadata), "single" (length-prefixed payloads), and a dedicated `EciesMultiRecipient` helper for wrapping symmetric keys across large recipient sets.
+- **Typed safety net** – exhaustive error/enum catalog (e.g., `ECIESErrorTypeEnum`, `Pbkdf2ErrorType`, `InvalidEmailErrorType`) backed by strongly typed error classes.
+- **Ancillary crypto services** – AES-GCM helpers, PBKDF2 profiles, secure buffers/strings, mnemonic-based key derivation, and password-login tooling.
+- **Rock-solid tests** – 380+ Jest specs, including multi-recipient integration, file encryption round-trips, and e2e login flows.
+
+## Installation
+
+```bash
+pnpm add @digitaldefiance/ecies-lib
+# or
+yarn add @digitaldefiance/ecies-lib
+# or
+npm install @digitaldefiance/ecies-lib
+```
+
+> **Runtime requirements**
+>
+> - Node.js 18+ (ships with the Web Crypto API). For earlier Node versions, polyfill `globalThis.crypto` before importing the library.
+> - Browsers with Web Crypto + `BigInt` support (Chromium, Firefox, Safari >= 14).
+
+## Quick start
+
+```ts
+import { ECIESService } from '@digitaldefiance/ecies-lib';
+
+const ecies = new ECIESService();
+
+// 1. Generate deterministic recipient keys from a mnemonic
+const recipientMnemonic = ecies.generateNewMnemonic();
+const recipientKeys = ecies.mnemonicToSimpleKeyPair(recipientMnemonic);
+
+// 2. Encrypt in "single" mode (length metadata included)
+const message = new TextEncoder().encode('Sign the blocks.');
+const encrypted = await ecies.encryptSimpleOrSingle(
+  false, // false => EciesEncryptionTypeEnum.Single
+  recipientKeys.publicKey,
+  message,
+);
+
+// 3. Decrypt by honoring the header
+const decrypted = await ecies.decryptSimpleOrSingleWithHeader(
+  false,
+  recipientKeys.privateKey,
+  encrypted,
+);
+
+console.log(new TextDecoder().decode(decrypted)); // "Sign the blocks."
+```
+
+## Multi-recipient encryption
+
+The high-level `ECIESService.encrypt` method intentionally throws for `EciesEncryptionTypeEnum.Multiple` until the orchestration layer is finalized. The lower-level `EciesMultiRecipient` helper is fully functional and end-to-end tested.
+
+```ts
+import {
+  ECIES,
+  EciesMultiRecipient,
+  EciesCryptoCore,
+  concatUint8Arrays,
+} from '@digitaldefiance/ecies-lib';
+
+const config = {
+  curveName: ECIES.CURVE_NAME,
+  primaryKeyDerivationPath: ECIES.PRIMARY_KEY_DERIVATION_PATH,
+  mnemonicStrength: ECIES.MNEMONIC_STRENGTH,
+  symmetricAlgorithm: ECIES.SYMMETRIC.ALGORITHM,
+  symmetricKeyBits: ECIES.SYMMETRIC.KEY_BITS,
+  symmetricKeyMode: ECIES.SYMMETRIC.MODE,
+};
+
+const multi = new EciesMultiRecipient(config);
+const core = new EciesCryptoCore(config);
+
+const recipients = await Promise.all(
+  [...Array(3)].map(async () => {
+    const { privateKey, publicKey } = await core.generateEphemeralKeyPair();
+    return {
+      id: crypto.getRandomValues(new Uint8Array(ECIES.MULTIPLE.RECIPIENT_ID_SIZE)),
+      privateKey,
+      publicKey,
+    };
+  }),
+);
+
+const payload = new TextEncoder().encode('Broadcast to the ops team');
+const encrypted = await multi.encryptMultiple(
+  recipients.map(({ id, publicKey }) => ({ id, publicKey })),
+  payload,
+);
+
+const transportFrame = concatUint8Arrays(
+  multi.buildHeader(encrypted),
+  encrypted.encryptedMessage,
+);
+
+// Recipient 0 decrypts
+const cleartext = await multi.decryptMultipleForRecipient(
+  multi.parseMessage(transportFrame),
+  recipients[0].id,
+  recipients[0].privateKey,
+);
+```
+
+## File encryption service
+
+`EciesFileService` wraps `ECIESService` to provide authenticated file encryption/decryption in the browser. It streams large files, supports zero-length payloads, and handles download flows.
+
+```ts
+import { ECIESService, EciesFileService } from '@digitaldefiance/ecies-lib';
+
+const ecies = new ECIESService();
+const { privateKey, publicKey } = ecies.mnemonicToSimpleKeyPair(ecies.generateNewMnemonic());
+const fileService = new EciesFileService(ecies, privateKey);
+
+const encryptedBytes = await fileService.encryptFile(fileInput.files![0], publicKey);
+const plainBytes = await fileService.decryptFile(encryptedBytes);
+fileService.downloadEncryptedFile(encryptedBytes, `${Date.now()}.enc`);
+```
+
+See `src/services/ecies/file.ts` and `tests/services/ecies/file.spec.ts` for stream management details.
+
+## Password login + PBKDF2 helpers
+
+The library also addresses user authentication workflows. `PasswordLoginService` manages PBKDF2 hashing, login challenges, and secure storage, while `Pbkdf2Service` exposes low-level derivation utilities and hardened presets.
+
+```ts
+import { PasswordLoginService, Pbkdf2Service } from '@digitaldefiance/ecies-lib';
+
+const passwordService = new PasswordLoginService();
+
+// Derive a login hash with a hardened profile
+const passwordBytes = new TextEncoder().encode('xX_password_Xx!');
+const pbkdf2 = await Pbkdf2Service.deriveKeyFromPasswordWithProfileAsync(
+  passwordBytes,
+  'BROWSER_PASSWORD',
+);
+
+const loginPayload = await passwordService.generateLoginPayload({
+  email: 'alice@example.org',
+  password: passwordBytes,
+});
+```
+
+Check `src/services/password-login.ts` and the comprehensive spec files in `tests/password-login*.spec.ts` and `tests/pbkdf2*.spec.ts` for concrete edge cases.
+
+## Secure primitives & value objects
+
+- `SecureString` / `SecureBuffer`: auto-zero, opt-in disposal, and helper methods for dealing with sensitive material.
+- `BackupCodeString` / `EmailString`: validated wrappers around critical data, catching malformed inputs early.
+- `Guid` utilities: strong typing via `ts-brand`, plus brand-aware error classes.
+
+These primitives are exported via `src/index.ts` and come with targeted tests in `tests/backup-code-string.spec.ts`, `tests/email-string.spec.ts`, `src/guid.spec.ts`, etc.
+
+## Error handling
+
+Every failure path maps to a typed error, so consumers can branch without string comparisons. Example:
+
+```ts
+import { ECIESError, ECIESErrorTypeEnum } from '@digitaldefiance/ecies-lib';
+
+try {
+  await ecies.decryptSimpleOrSingleWithHeader(false, privateKey, tamperedData);
+} catch (error) {
+  if (error instanceof ECIESError) {
+    if (error.type === ECIESErrorTypeEnum.DecryptionFailed) {
+      // attempt recovery or alert the user
+    }
+  }
+}
+```
+
+## Project structure
+
+```
+packages/digitaldefiance-ecies-lib/
+├─ src/
+│  ├─ services/          # ECIES, AES-GCM, PBKDF2, password login
+│  ├─ errors/            # Typed error classes
+│  ├─ enumerations/      # Public enums exported via the barrel
+│  ├─ interfaces/        # Shared type definitions
+│  ├─ secure-*.ts        # SecureString / SecureBuffer implementations
+│  └─ utils.ts           # Buffer/string helpers, CRC, etc.
+├─ tests/
+│  ├─ services/          # Service-level unit + integration suites
+│  ├─ *.spec.ts          # Domain-specific validators and helpers
+│  ├─ *.e2e.spec.ts      # Password login, PBKDF2, AES-GCM end-to-end coverage
+│  └─ support/           # LocalStorage mocks, custom Jest matchers
+└─ jest.config.js
+```
+
+## Quality gates
+
+The project ships with mandatory linting, formatting, and testing commands:
+
+```bash
+yarn lint           # ESLint across src/**/*.ts
+yarn prettier:check # Enforce formatting
+yarn test           # Jest unit + e2e suites
+yarn build          # Compile TypeScript into dist/
+```
+
+Continuous integration mirrors these gates, and the repository currently passes 389 Jest specs (unit + e2e).
+
+## Browser vs. Node tips
+
+- **Node**: Node 18+ exposes `globalThis.crypto`. If you target older runtimes, polyfill before importing the library:
+  ```ts
+  import { webcrypto } from 'crypto';
+  globalThis.crypto = webcrypto as unknown as Crypto;
+  ```
+- **Browser bundlers**: the package ships TypeScript sources; rely on your bundler (Vite, Webpack, Next.js) to tree-shake unused exports. All external dependencies are ESM-friendly.
+- **Memory hygiene**: many helpers (e.g., `SecureBuffer`) provide `.dispose()` to zero sensitive data. Call them when you’re done.
+
+## Contributing
+
+1. Fork & clone the repo.
+2. Install dependencies with `yarn install` (Yarn 4 is already configured via `.yarnrc`).
+3. Create a feature branch (`git checkout -b feature/awesome`).
+4. Make changes and run `yarn format && yarn lint && yarn test`.
+5. Submit a PR with a clear description and test evidence.
+
+Bug reports and feature requests are welcome—open an issue with reproduction steps and expected behavior.
+
+## Security
+
+If you discover a vulnerability, please **do not** open a public issue. Email security@digitaldefiance.io with details so we can coordinate a fix and responsible disclosure timeline.
+
+## License
+
+MIT © Digital Defiance

package/dist/backup-code-string.d.ts

@@ -0,0 +1,26 @@
+import { SecureString } from './secure-string';
+export declare class BackupCodeString extends SecureString {
+    private readonly _normalizedCode;
+    constructor(code: string);
+    get value(): string;
+    get notNullValue(): string;
+    get valueAsHexString(): string;
+    get valueAsBase64String(): string;
+    get valueAsUint8Array(): Uint8Array;
+    /**
+     * Format a 32-char normalized code into display form (8 groups of 4).
+     * Does not restrict characters beyond grouping.
+     */
+    static formatBackupCode(code: string): string;
+    /**
+     * Normalize user-entered code: remove spaces and hyphens, lowercase, and trim.
+     */
+    static normalizeCode(input: string): string;
+    static generateBackupCode(): string;
+    /**
+     * Generate the configured number of backup codes.
+     * Note: If generation alphabet/length is controlled elsewhere, prefer that path.
+     */
+    static generateBackupCodes(): Array<BackupCodeString>;
+}
+//# sourceMappingURL=backup-code-string.d.ts.map

package/dist/backup-code-string.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup-code-string.d.ts","sourceRoot":"","sources":["../src/backup-code-string.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/C,qBAAa,gBAAiB,SAAQ,YAAY;IAChD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;gBAE7B,IAAI,EAAE,MAAM;IASxB,IAAoB,KAAK,IAAI,MAAM,CAElC;IAED,IAAoB,YAAY,IAAI,MAAM,CAEzC;IAED,IAAoB,gBAAgB,IAAI,MAAM,CAO7C;IAED,IAAoB,mBAAmB,IAAI,MAAM,CAKhD;IAED,IAAoB,iBAAiB,IAAI,UAAU,CAKlD;IAED;;;OAGG;WACW,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAIpD;;OAEG;WACW,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;WAIpC,kBAAkB,IAAI,MAAM;IAU1C;;;OAGG;WACW,mBAAmB,IAAI,KAAK,CAAC,gBAAgB,CAAC;CAO7D"}

package/dist/backup-code-string.js

@@ -0,0 +1,69 @@
+import { Constants } from './constants';
+import { InvalidBackupCodeError } from './errors/invalid-backup-code';
+import { SecureString } from './secure-string';
+export class BackupCodeString extends SecureString {
+    _normalizedCode;
+    constructor(code) {
+        const normalizedCode = BackupCodeString.normalizeCode(code);
+        if (!Constants.BACKUP_CODES.NormalizedHexRegex.test(normalizedCode)) {
+            throw new InvalidBackupCodeError();
+        }
+        super(normalizedCode);
+        this._normalizedCode = normalizedCode;
+    }
+    get value() {
+        return this.notNullValue;
+    }
+    get notNullValue() {
+        return BackupCodeString.formatBackupCode(this._normalizedCode);
+    }
+    get valueAsHexString() {
+        const formattedValue = BackupCodeString.formatBackupCode(this._normalizedCode);
+        return new TextEncoder().encode(formattedValue).reduce((str, byte) => {
+            return str + byte.toString(16).padStart(2, '0');
+        }, '');
+    }
+    get valueAsBase64String() {
+        const formattedValue = BackupCodeString.formatBackupCode(this._normalizedCode);
+        return btoa(formattedValue);
+    }
+    get valueAsUint8Array() {
+        const formattedValue = BackupCodeString.formatBackupCode(this._normalizedCode);
+        return new TextEncoder().encode(formattedValue);
+    }
+    /**
+     * Format a 32-char normalized code into display form (8 groups of 4).
+     * Does not restrict characters beyond grouping.
+     */
+    static formatBackupCode(code) {
+        const groups = code.match(/.{1,4}/g) ?? [code];
+        return groups.join('-');
+    }
+    /**
+     * Normalize user-entered code: remove spaces and hyphens, lowercase, and trim.
+     */
+    static normalizeCode(input) {
+        return input.replace(/[\s-]/g, '').toLowerCase().trim();
+    }
+    static generateBackupCode() {
+        const alphabet = 'abcdefghijklmnopqrstuvwxyz0123456789';
+        const rnd = crypto.getRandomValues(new Uint8Array(32));
+        let raw = '';
+        for (let j = 0; j < 32; j++) {
+            raw += alphabet[rnd[j] % alphabet.length];
+        }
+        return raw;
+    }
+    /**
+     * Generate the configured number of backup codes.
+     * Note: If generation alphabet/length is controlled elsewhere, prefer that path.
+     */
+    static generateBackupCodes() {
+        const codes = [];
+        for (let i = 0; i < Constants.BACKUP_CODES.Count; i++) {
+            codes.push(new BackupCodeString(BackupCodeString.generateBackupCode()));
+        }
+        return codes;
+    }
+}
+//# sourceMappingURL=backup-code-string.js.map

package/dist/backup-code-string.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup-code-string.js","sourceRoot":"","sources":["../src/backup-code-string.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AACtE,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/C,MAAM,OAAO,gBAAiB,SAAQ,YAAY;IAC/B,eAAe,CAAS;IAEzC,YAAY,IAAY;QACtB,MAAM,cAAc,GAAG,gBAAgB,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;QAC5D,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,kBAAkB,CAAC,IAAI,CAAC,cAAc,CAAC,EAAE,CAAC;YACpE,MAAM,IAAI,sBAAsB,EAAE,CAAC;QACrC,CAAC;QACD,KAAK,CAAC,cAAc,CAAC,CAAC;QACtB,IAAI,CAAC,eAAe,GAAG,cAAc,CAAC;IACxC,CAAC;IAED,IAAoB,KAAK;QACvB,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;IAED,IAAoB,YAAY;QAC9B,OAAO,gBAAgB,CAAC,gBAAgB,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;IACjE,CAAC;IAED,IAAoB,gBAAgB;QAClC,MAAM,cAAc,GAAG,gBAAgB,CAAC,gBAAgB,CACtD,IAAI,CAAC,eAAe,CACrB,CAAC;QACF,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE;YACnE,OAAO,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QAClD,CAAC,EAAE,EAAE,CAAC,CAAC;IACT,CAAC;IAED,IAAoB,mBAAmB;QACrC,MAAM,cAAc,GAAG,gBAAgB,CAAC,gBAAgB,CACtD,IAAI,CAAC,eAAe,CACrB,CAAC;QACF,OAAO,IAAI,CAAC,cAAc,CAAC,CAAC;IAC9B,CAAC;IAED,IAAoB,iBAAiB;QACnC,MAAM,cAAc,GAAG,gBAAgB,CAAC,gBAAgB,CACtD,IAAI,CAAC,eAAe,CACrB,CAAC;QACF,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;IAClD,CAAC;IAED;;;OAGG;IACI,MAAM,CAAC,gBAAgB,CAAC,IAAY;QACzC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC/C,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;IACD;;OAEG;IACI,MAAM,CAAC,aAAa,CAAC,KAAa;QACvC,OAAO,KAAK,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC;IAC1D,CAAC;IAEM,MAAM,CAAC,kBAAkB;QAC9B,MAAM,QAAQ,GAAG,sCAAsC,CAAC;QACxD,MAAM,GAAG,GAAG,MAAM,CAAC,eAAe,CAAC,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC;QACvD,IAAI,GAAG,GAAG,EAAE,CAAC;QACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;YAC5B,GAAG,IAAI,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;QAC5C,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED;;;OAGG;IACI,MAAM,CAAC,mBAAmB;QAC/B,MAAM,KAAK,GAA4B,EAAE,CAAC;QAC1C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;YACtD,KAAK,CAAC,IAAI,CAAC,IAAI,gBAAgB,CAAC,gBAAgB,CAAC,kBAAkB,EAAE,CAAC,CAAC,CAAC;QAC1E,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;CACF"}

package/dist/constants.d.ts

@@ -0,0 +1,22 @@
+import { IBackupCodeConstants } from './interfaces';
+import { IConstants } from './interfaces/constants';
+import { IECIESConstants } from './interfaces/ecies-consts';
+import { IPBkdf2Consts } from './interfaces/pbkdf2-consts';
+import { Pbkdf2Profiles } from './pbkdf2-profiles';
+export declare const UINT8_SIZE: number;
+export declare const UINT16_SIZE: number;
+export declare const UINT16_MAX: number;
+export declare const UINT32_SIZE: number;
+export declare const UINT32_MAX: number;
+export declare const UINT64_SIZE: number;
+export declare const UINT64_MAX: bigint;
+/**
+ * Standard size of a UUID v4 in bytes.
+ */
+export declare const GUID_SIZE: number;
+export declare const BACKUP_CODES: IBackupCodeConstants;
+export declare const PBKDF2: IPBkdf2Consts;
+export declare const PBKDF2_PROFILES: Pbkdf2Profiles;
+export declare const ECIES: IECIESConstants;
+export declare const Constants: IConstants;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD,eAAO,MAAM,UAAU,EAAE,MAAmB,CAAC;AAC7C,eAAO,MAAM,WAAW,EAAE,MAAmB,CAAC;AAC9C,eAAO,MAAM,UAAU,EAAE,MAAuB,CAAC;AACjD,eAAO,MAAM,WAAW,EAAE,MAAmB,CAAC;AAC9C,eAAO,MAAM,UAAU,EAAE,MAA4B,CAAC;AACtD,eAAO,MAAM,WAAW,EAAE,MAAmB,CAAC;AAC9C,eAAO,MAAM,UAAU,EAAE,MAAuC,CAAC;AACjE;;GAEG;AACH,eAAO,MAAM,SAAS,EAAE,MAAoB,CAAC;AAE7C,eAAO,MAAM,YAAY,EAAE,oBAOjB,CAAC;AAEX,eAAO,MAAM,MAAM,EAAE,aAQX,CAAC;AAEX,eAAO,MAAM,eAAe,EAAE,cAa7B,CAAC;AAyBF,eAAO,MAAM,KAAK,EAAE,eAoEnB,CAAC;AAGF,eAAO,MAAM,SAAS,EAAE,UA8Cd,CAAC"}

package/dist/constants.js

@@ -0,0 +1,177 @@
+import { ObjectId } from 'bson';
+import { ECIESErrorTypeEnum } from './enumerations';
+import { ECIESError } from './errors/ecies';
+export const UINT8_SIZE = 1;
+export const UINT16_SIZE = 2;
+export const UINT16_MAX = 65535;
+export const UINT32_SIZE = 4;
+export const UINT32_MAX = 4294967295;
+export const UINT64_SIZE = 8;
+export const UINT64_MAX = 18446744073709551615n;
+/**
+ * Standard size of a UUID v4 in bytes.
+ */
+export const GUID_SIZE = 16;
+export const BACKUP_CODES = {
+    /**
+     * How many backup codes to generate for users
+     */
+    Count: 10,
+    NormalizedHexRegex: /^[a-z0-9]{32}$/, // exactly 32 lowercase alphanumeric chars
+    DisplayRegex: /^([a-z0-9]{4}-){7}[a-z0-9]{4}$/, // xxxx-xxxx-xxxx-xxxx-xxxx-xxxx-xxxx-xxxx
+};
+export const PBKDF2 = {
+    ALGORITHM: 'SHA-256',
+    SALT_BYTES: 32,
+    /**
+     * Number of pbkdf2 iterations per second when hashing a password.
+     * This is the high-security default for user login operations.
+     */
+    ITERATIONS_PER_SECOND: 1304000,
+};
+export const PBKDF2_PROFILES = {
+    BACKUP_CODES: {
+        hashBytes: 32,
+        saltBytes: 16,
+        iterations: 100000,
+        algorithm: 'SHA-256',
+    },
+    BROWSER_PASSWORD: {
+        hashBytes: 32,
+        saltBytes: 64,
+        iterations: 2000000,
+        algorithm: 'SHA-512',
+    },
+};
+const ECIES_SYMMETRIC_KEY_SIZE = 32;
+const ECIES_PUBLIC_KEY_LENGTH = 65;
+const ECIES_RAW_PUBLIC_KEY_LENGTH = 64;
+const ECIES_IV_SIZE = 16;
+const ECIES_AUTH_TAG_SIZE = 16;
+const ECIES_MULTIPLE_RECIPIENT_ID_SIZE = 16;
+// Define the expected value for SIMPLE.FIXED_OVERHEAD_SIZE
+const expectedSimpleOverhead = UINT8_SIZE + ECIES_PUBLIC_KEY_LENGTH + ECIES_IV_SIZE + ECIES_AUTH_TAG_SIZE;
+// Define the expected value for MULTIPLE.FIXED_OVERHEAD_SIZE
+// Includes: type (1) + IV (16) + auth tag (16) = 33 (no CRC, AES-GCM provides authentication)
+const expectedMultipleOverhead = UINT8_SIZE + ECIES_IV_SIZE + ECIES_AUTH_TAG_SIZE;
+// Update ENCRYPTED_KEY_SIZE to match Simple encryption (no CRC)
+const expectedMultipleEncryptedKeySize = ECIES_PUBLIC_KEY_LENGTH +
+    ECIES_IV_SIZE +
+    ECIES_AUTH_TAG_SIZE +
+    ECIES_SYMMETRIC_KEY_SIZE;
+export const ECIES = {
+    /** The elliptic curve to use for all ECDSA operations */
+    CURVE_NAME: 'secp256k1',
+    /** The primary key derivation path for HD wallets */
+    PRIMARY_KEY_DERIVATION_PATH: "m/44'/60'/0'/0/0",
+    SYMMETRIC_ALGORITHM_CONFIGURATION: 'aes-256-gcm',
+    /** Length of ECDSA signatures in bytes */
+    SIGNATURE_SIZE: 64,
+    /** Length of raw public keys in bytes (without 0x04 prefix) */
+    RAW_PUBLIC_KEY_LENGTH: ECIES_RAW_PUBLIC_KEY_LENGTH,
+    /** Length of public keys in bytes (with 0x04 prefix) */
+    PUBLIC_KEY_LENGTH: ECIES_PUBLIC_KEY_LENGTH,
+    PUBLIC_KEY_MAGIC: 0x04,
+    /** Mnemonic strength in bits. This will produce a 32-bit key for ECDSA */
+    MNEMONIC_STRENGTH: 256,
+    /** Symmetric encryption algorithm configuration */
+    SYMMETRIC: {
+        ALGORITHM: 'aes',
+        MODE: 'gcm',
+        KEY_BITS: 256,
+        KEY_SIZE: ECIES_SYMMETRIC_KEY_SIZE, // KEY_BITS / 8
+    },
+    IV_SIZE: ECIES_IV_SIZE,
+    AUTH_TAG_SIZE: ECIES_AUTH_TAG_SIZE,
+    MAX_RAW_DATA_SIZE: 9007199254740991, // 2^53 - 1 (max safe integer for JS)
+    /**
+     * Message encrypts without data length or crc
+     */
+    SIMPLE: {
+        FIXED_OVERHEAD_SIZE: expectedSimpleOverhead, // type (1) + public key (65) + IV (16) + auth tag (16)
+        DATA_LENGTH_SIZE: 0,
+    },
+    /**
+     * Message encrypts with data length but no CRC (AES-GCM provides authentication)
+     */
+    SINGLE: {
+        FIXED_OVERHEAD_SIZE: 106, // type (1) + public key (65) + IV (16) + auth tag (16) + data length (8)
+        DATA_LENGTH_SIZE: 8,
+    },
+    /**
+     * Message encrypts for multiple recipients
+     */
+    MULTIPLE: {
+        FIXED_OVERHEAD_SIZE: expectedMultipleOverhead, // type (1) + IV (16) + auth tag (16), no CRC
+        ENCRYPTED_KEY_SIZE: expectedMultipleEncryptedKeySize, // 129
+        MAX_RECIPIENTS: 65535,
+        RECIPIENT_ID_SIZE: ECIES_MULTIPLE_RECIPIENT_ID_SIZE,
+        RECIPIENT_COUNT_SIZE: 2,
+        DATA_LENGTH_SIZE: 8,
+    },
+    ENCRYPTION_TYPE: {
+        SIMPLE: 33,
+        SINGLE: 66,
+        MULTIPLE: 99,
+    },
+};
+const objectIdLength = new ObjectId().toHexString().length / 2;
+export const Constants = {
+    /**
+     * The length of a raw object ID (not the hex string representation)
+     */
+    OBJECT_ID_LENGTH: objectIdLength,
+    UINT8_SIZE: UINT8_SIZE,
+    UINT16_SIZE: UINT16_SIZE,
+    UINT16_MAX: UINT16_MAX,
+    UINT32_SIZE: UINT32_SIZE,
+    UINT32_MAX: UINT32_MAX,
+    UINT64_SIZE: UINT64_SIZE,
+    UINT64_MAX: UINT64_MAX,
+    HEX_RADIX: 16,
+    GUID_SIZE: GUID_SIZE,
+    BACKUP_CODES: BACKUP_CODES,
+    ECIES: ECIES,
+    PBKDF2: PBKDF2,
+    PBKDF2_PROFILES: PBKDF2_PROFILES,
+    /**
+     * Number of rounds for bcrypt hashing. Higher values increase security but also consume more CPU resources.
+     */
+    BcryptRounds: 10,
+    /**
+     * Minimum password length
+     */
+    PasswordMinLength: 8,
+    /**
+     * The regular expression for valid passwords.
+     */
+    PasswordRegex: /^(?=.*[A-Za-z])(?=.*\d)(?=.*[!@#$%^&*()_+\-=[\]{};':"\\|,.<>/?])[A-Za-z\d!@#$%^&*()_+\-=[\]{};':"\\|,.<>/?]{8,}$/,
+    /**
+     * The regular expression for valid mnemonic phrases.
+     * BIP39 - supports 12, 15, 18, 21, or 24 word mnemonics
+     */
+    MnemonicRegex: /^(?:\w+\s){11}\w+$|^(?:\w+\s){14}\w+$|^(?:\w+\s){17}\w+$|^(?:\w+\s){20}\w+$|^(?:\w+\s){23}\w+$/i,
+    /**
+     * Matches a 64-character hexadecimal string (SHA-256).
+     */
+    HmacRegex: /^[a-f0-9]{64}$/,
+};
+if (objectIdLength !== 12) {
+    console.warn('ObjectID length may have changed, breaking encryption', objectIdLength);
+}
+if (ECIES.MULTIPLE.ENCRYPTED_KEY_SIZE !== 129) {
+    throw new ECIESError(ECIESErrorTypeEnum.InvalidECIESMultipleEncryptedKeySize);
+}
+if (ECIES.PUBLIC_KEY_LENGTH !== ECIES.RAW_PUBLIC_KEY_LENGTH + 1) {
+    throw new ECIESError(ECIESErrorTypeEnum.InvalidECIESPublicKeyLength);
+}
+if (ECIES.MULTIPLE.RECIPIENT_COUNT_SIZE !== UINT16_SIZE) {
+    throw new ECIESError(ECIESErrorTypeEnum.InvalidECIESMultipleRecipientCountSize);
+}
+if (ECIES.MULTIPLE.DATA_LENGTH_SIZE !== UINT64_SIZE) {
+    throw new ECIESError(ECIESErrorTypeEnum.InvalidECIESMultipleDataLengthSize);
+}
+if (ECIES.MULTIPLE.RECIPIENT_ID_SIZE !== GUID_SIZE) {
+    throw new ECIESError(ECIESErrorTypeEnum.InvalidECIESMultipleRecipientIdSize);
+}
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"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"}

package/dist/email-string.d.ts

@@ -0,0 +1,42 @@
+/**
+ * EmailString represents a validated email address.
+ * It ensures that the email is not empty, does not have leading or trailing spaces,
+ * and is a valid email format.
+ */
+export declare class EmailString {
+    readonly email: string;
+    /**
+     * Creates an instance of EmailString.
+     * @param email - The email address to validate and store.
+     * @throws Will throw an error if the email is invalid.
+     */
+    constructor(email: string);
+    /**
+     * Returns the email address as a string.
+     * @returns The email address.
+     */
+    toString(): string;
+    /**
+     * Checks if this email address is equal to another email address.
+     * @param other - The other email address to compare.
+     * @returns True if the email addresses are equal, false otherwise.
+     */
+    equals(other: EmailString): boolean;
+    /**
+     * Converts the email address to a JSON string.
+     * @returns The email address as a JSON string.
+     */
+    toJson(): string;
+    /**
+     * Creates an EmailString instance from a JSON string.
+     * @param email - The JSON string representing the email address.
+     * @returns The EmailString instance.
+     */
+    static fromJson(email: string): EmailString;
+    /**
+     * Gets the length of the email address.
+     * @returns The length of the email address.
+     */
+    get length(): number;
+}
+//# sourceMappingURL=email-string.d.ts.map

package/dist/email-string.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-string.d.ts","sourceRoot":"","sources":["../src/email-string.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,qBAAa,WAAW;IACtB,SAAgB,KAAK,EAAE,MAAM,CAAC;IAE9B;;;;OAIG;gBACS,KAAK,EAAE,MAAM;IAczB;;;OAGG;IACI,QAAQ,IAAI,MAAM;IAIzB;;;;OAIG;IACI,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO;IAI1C;;;OAGG;IACI,MAAM,IAAI,MAAM;IAIvB;;;;OAIG;WACW,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW;IAIlD;;;OAGG;IACH,IAAW,MAAM,IAAI,MAAM,CAE1B;CACF"}