@crossdyne/security 0.5.0-beta.2 → 1.0.0

package/README.md

@@ -1,15 +1,365 @@
-# @quantropic/security
+# Crossdyne.Security
 
-Security library with SRP authentication and cryptography utilities.
+> Cross-platform cryptographic library — [.NET](https://github.com/crossdyne/dotnet-security) | [TypeScript](https://github.com/crossdyne/typescript-security)
+>
+> [English](#english) | [Русский](#русский)
 
-## Features
+---
 
-- SRP (Secure Remote Password) protocol implementation
-- Cryptographic utilities
-- Key derivation functions
+<a name="english"></a>
+## English
+
+TypeScript / JavaScript implementation of the Crossdyne.Security cryptographic library via the native **Web Crypto API**.
 
 ## Installation
 
 ```bash
-npm install @quantropic/security
-```
+npm install @crossdyne/security
+```
+
+### Features
+
+- **AES-256-GCM** — authenticated symmetric encryption via `crypto.subtle`
+- **PBKDF2 + HKDF** — secure key derivation from passwords
+- **SRP-6a** — password-authenticated key exchange without sending the password to the server
+- **Zero-memory** — sensitive buffers are explicitly overwritten after use
+- **No custom crypto primitives** — relies entirely on the browser / Node.js Web Crypto API
+- **Cross-platform** — compatible with the [.NET implementation](https://github.com/crossdyne/dotnet-security). Encrypted payloads and SRP messages are interchangeable between TS and .NET.
+
+### Requirements
+
+- TypeScript 5.3+
+- Web Crypto API (`crypto.subtle`) — modern browsers and Node.js 18+
+
+### Project Structure
+
+```
+crossdyne-security/
+├── crypto/
+│   ├── crypto-service.ts              # AES-GCM encrypt / decrypt
+│   ├── key-derivation-service.ts      # Derive KEK and AuthHash (PBKDF2 → HKDF)
+│   ├── crypto-profile-registry.ts     # Versioned crypto profiles
+│   ├── crypto-version.ts              # Enum: V1, V2, ...
+│   └── kdf-options.ts                 # PBKDF2 / HKDF parameters
+├── srp/
+│   ├── srp-server-service.ts          # SRP server (challenge, verify)
+│   ├── srp-client-service.ts          # SRP client (proof, verifier)
+│   ├── srp-key-derivation-service.ts  # Derive auth-hash for SRP
+│   ├── srp-context-factory.ts         # Creates SRP context (N, g, k, hash)
+│   ├── srp-group.ts                   # Enum: Group2048, Group4096, ...
+│   └── srp-encoding.ts                # BigInt ↔ bytes helpers
+└── utils/
+    ├── security-utils.ts              # Base64, BigInt, fixed-time compare
+    └── srp-encoding.ts               # Hash moduli, session key, M1 / M2
+```
+
+### Quick Start
+
+#### Encrypt / Decrypt
+
+```typescript
+import { CryptoService } from './crypto/crypto-service.js';
+import { CryptoVersion } from './crypto/crypto-version.js';
+
+const crypto = new CryptoService();
+const key = crypto.generateRandomBytes(32); // AES-256
+
+const encrypted = await crypto.encryptData(
+  { message: "Hello, World!" },
+  key,
+  CryptoVersion.V1
+);
+
+const decrypted = await crypto.decryptData<MyData>(encrypted, key);
+```
+
+Encrypted payload format (Base64):
+
+```
+[Version (1 byte)][Nonce (N bytes)][Ciphertext + Tag]
+```
+
+#### Key Derivation from Password
+
+```typescript
+import { KeyDerivationService } from './crypto/key-derivation-service.js';
+import { CryptoVersion } from './crypto/crypto-version.js';
+
+const kdf = new KeyDerivationService();
+const salt = crypto.getRandomValues(new Uint8Array(16));
+
+const { kek, authHash } = await kdf.deriveKeysFromPassword(
+  "user@example.com",
+  "SuperSecret123!",
+  salt,
+  CryptoVersion.V1
+);
+```
+
+- `kek` — `Uint8Array` key for AES-GCM
+- `authHash` — Base64 string for SRP authentication
+
+#### SRP Authentication Flow
+
+**Server — generate challenge**
+
+```typescript
+import { SrpServerService } from './srp/srp-server-service.js';
+import { SrpGroup } from './srp/srp-group.js';
+
+const server = new SrpServerService();
+
+const session = await server.getSrpChallenge(
+  "user@example.com",
+  verifierBytes,
+  salt,
+  SrpGroup.Group2048
+);
+
+// Send to client: salt + session.publicKeyB (B)
+```
+
+**Client — generate proof**
+
+```typescript
+import { SrpClientService } from './srp/srp-client-service.js';
+import { SrpKeyDerivationService } from './srp/srp-key-derivation-service.js';
+import { SrpGroup } from './srp/srp-group.js';
+import { CryptoVersion } from './crypto/crypto-version.js';
+
+const client = new SrpClientService();
+const kdf = new SrpKeyDerivationService();
+
+// 1. Derive auth-hash from password
+const authHash = await kdf.deriveAuthHashForSrp(
+  identity, password, salt, SrpGroup.Group2048, CryptoVersion.V1
+);
+
+// 2. Generate proof
+const { A, M1, SessionKeyK } = await client.generateSrpProof(
+  identity,
+  authHash,
+  btoa(String.fromCharCode(...salt)),
+  btoa(String.fromCharCode(...session.publicKeyB)),
+  SrpGroup.Group2048
+);
+
+// Send to server: A + M1
+```
+
+**Server — verify proof**
+
+```typescript
+const serverM2 = await server.verifySrpProof(
+  session,
+  A,
+  M1,
+  SrpGroup.Group2048
+);
+
+// Send to client: serverM2
+```
+
+**Client — verify server proof**
+
+```typescript
+const isValid = await client.verifyServerM2(
+  A,
+  M1,
+  SessionKeyK,
+  serverM2,
+  SrpGroup.Group2048
+);
+```
+
+### Security Notes
+
+- All sensitive buffers are explicitly overwritten after use
+- Salt must be **at least 16 bytes**
+- AES-256 key must be **exactly 32 bytes**
+- SRP groups are protected against small-subgroup attacks (checks `A % N != 0`, `B != 0`)
+- Relies entirely on the native Web Crypto API — no custom crypto primitives
+
+### License
+
+MIT
+
+---
+
+<a name="русский"></a>
+## Русский
+
+Реализация криптографической библиотеки Crossdyne.Security для TypeScript / JavaScript через нативный **Web Crypto API**.
+
+## Установка
+
+```bash
+npm install @crossdyne/security
+```
+
+### Возможности
+
+- **AES-256-GCM** — симметричное шифрование с аутентификацией через `crypto.subtle`
+- **PBKDF2 + HKDF** — надёжный вывод ключей из пароля
+- **SRP-6a** — протокол аутентификации без передачи пароля на сервер
+- **Zero-memory** — чувствительные буферы явно перезаписываются после использования
+- **Никаких самописных криптопримитивов** — только нативный Web Crypto API браузера / Node.js
+- **Кроссплатформенность** — совместима с [.NET-реализацией](https://github.com/crossdyne/dotnet-security). Зашифрованные данные и SRP-сообщения взаимозаменяемы между TS и .NET.
+
+### Требования
+
+- TypeScript 5.3+
+- Web Crypto API (`crypto.subtle`) — современные браузеры и Node.js 18+
+
+### Структура проекта
+
+```
+crossdyne-security/
+├── crypto/
+│   ├── crypto-service.ts              # AES-GCM шифрование / дешифрование
+│   ├── key-derivation-service.ts      # Вывод KEK и AuthHash (PBKDF2 → HKDF)
+│   ├── crypto-profile-registry.ts     # Версионированные криптопрофили
+│   ├── crypto-version.ts              # Enum: V1, V2, ...
+│   └── kdf-options.ts                 # Параметры PBKDF2 / HKDF
+├── srp/
+│   ├── srp-server-service.ts          # SRP сервер (challenge, проверка)
+│   ├── srp-client-service.ts          # SRP клиент (proof, верификатор)
+│   ├── srp-key-derivation-service.ts  # Вывод auth-hash для SRP
+│   ├── srp-context-factory.ts         # Создание SRP-контекста (N, g, k, hash)
+│   ├── srp-group.ts                   # Enum: Group2048, Group4096, ...
+│   └── srp-encoding.ts                # BigInt ↔ bytes хелперы
+└── utils/
+    ├── security-utils.ts              # Base64, BigInt, сравнение в постоянное время
+    └── srp-encoding.ts               # Хеш модулей, сессионный ключ, M1 / M2
+```
+
+### Быстрый старт
+
+#### Шифрование / дешифрование
+
+```typescript
+import { CryptoService } from './crypto/crypto-service.js';
+import { CryptoVersion } from './crypto/crypto-version.js';
+
+const crypto = new CryptoService();
+const key = crypto.generateRandomBytes(32); // AES-256
+
+const encrypted = await crypto.encryptData(
+  { message: "Hello, World!" },
+  key,
+  CryptoVersion.V1
+);
+
+const decrypted = await crypto.decryptData<MyData>(encrypted, key);
+```
+
+Формат зашифрованных данных (Base64):
+
+```
+[Version (1 byte)][Nonce (N bytes)][Ciphertext + Tag]
+```
+
+#### Вывод ключей из пароля
+
+```typescript
+import { KeyDerivationService } from './crypto/key-derivation-service.js';
+import { CryptoVersion } from './crypto/crypto-version.js';
+
+const kdf = new KeyDerivationService();
+const salt = crypto.getRandomValues(new Uint8Array(16));
+
+const { kek, authHash } = await kdf.deriveKeysFromPassword(
+  "user@example.com",
+  "SuperSecret123!",
+  salt,
+  CryptoVersion.V1
+);
+```
+
+- `kek` — `Uint8Array` ключ для AES-GCM
+- `authHash` — Base64-строка для SRP-аутентификации
+
+#### SRP-аутентификация
+
+**Сервер — генерация challenge**
+
+```typescript
+import { SrpServerService } from './srp/srp-server-service.js';
+import { SrpGroup } from './srp/srp-group.js';
+
+const server = new SrpServerService();
+
+const session = await server.getSrpChallenge(
+  "user@example.com",
+  verifierBytes,
+  salt,
+  SrpGroup.Group2048
+);
+
+// Отправить клиенту: salt + session.publicKeyB (B)
+```
+
+**Клиент — генерация proof**
+
+```typescript
+import { SrpClientService } from './srp/srp-client-service.js';
+import { SrpKeyDerivationService } from './srp/srp-key-derivation-service.js';
+import { SrpGroup } from './srp/srp-group.js';
+import { CryptoVersion } from './crypto/crypto-version.js';
+
+const client = new SrpClientService();
+const kdf = new SrpKeyDerivationService();
+
+// 1. Вывести auth-hash из пароля
+const authHash = await kdf.deriveAuthHashForSrp(
+  identity, password, salt, SrpGroup.Group2048, CryptoVersion.V1
+);
+
+// 2. Сгенерировать proof
+const { A, M1, SessionKeyK } = await client.generateSrpProof(
+  identity,
+  authHash,
+  btoa(String.fromCharCode(...salt)),
+  btoa(String.fromCharCode(...session.publicKeyB)),
+  SrpGroup.Group2048
+);
+
+// Отправить серверу: A + M1
+```
+
+**Сервер — проверка proof**
+
+```typescript
+const serverM2 = await server.verifySrpProof(
+  session,
+  A,
+  M1,
+  SrpGroup.Group2048
+);
+
+// Отправить клиенту: serverM2
+```
+
+**Клиент — проверка server proof**
+
+```typescript
+const isValid = await client.verifyServerM2(
+  A,
+  M1,
+  SessionKeyK,
+  serverM2,
+  SrpGroup.Group2048
+);
+```
+
+### Безопасность
+
+- Все чувствительные буферы явно перезаписываются после использования
+- Соль должна быть **минимум 16 байт**
+- Ключ AES-256 — **строго 32 байта**
+- SRP-группы защищены от атак на малые подгруппы (проверки `A % N != 0`, `B != 0`)
+- Полностью опирается на нативный Web Crypto API — никаких самописных криптопримитивов
+
+### Лицензия
+
+MIT

package/dist/index.cjs

@@ -2,13 +2,15 @@
 
 // src/configurations/security-constants.ts
 var SecurityConstants = {
+  /** Standard nonce size for AES-GCM (96 bits). Fixed by NIST SP 800-38D. */
   AesGcmNonceSize: 12,
-  AesGcmTagSize: 16,
+  /** Minimum allowed authentication tag size (96 bits). */
   AesGcmTagSizeMin: 12,
+  /** Maximum allowed authentication tag size (128 bits). */
   AesGcmTagSizeMax: 16,
+  /** Key size for AES-256 (256 bits). */
   KeySizeBytes: 32,
-  // 256 bits
-  Pbkdf2IterationsDefault: 6e5,
+  /** Absolute minimum PBKDF2 iterations for any profile version. */
   Pbkdf2IterationsMinimum: 1e5
 };
 var HashSizes = {
@@ -110,54 +112,36 @@ var SecurityUtils = class {
 };
 
 // src/crypto/aes-gcm-options.ts
-var AesGcmOptions = class _AesGcmOptions {
-  constructor() {
-    this._nonceSize = SecurityConstants.AesGcmNonceSize;
-    this._tagSize = SecurityConstants.AesGcmTagSize;
-  }
-  /** Nonce size in bytes (must be 12). */
-  get nonceSize() {
-    return this._nonceSize;
-  }
-  set nonceSize(v) {
-    if (v !== SecurityConstants.AesGcmNonceSize) throw new RangeError(`AES-GCM requires ${SecurityConstants.AesGcmNonceSize}-byte nonce`);
-    this._nonceSize = v;
-  }
-  /** Tag size in bytes (12–16, default 16). */
-  get tagSize() {
-    return this._tagSize;
-  }
-  set tagSize(v) {
-    if (v < SecurityConstants.AesGcmTagSizeMin || v > SecurityConstants.AesGcmTagSizeMax) throw new RangeError(`Tag size must be between ${SecurityConstants.AesGcmTagSizeMin} and ${SecurityConstants.AesGcmTagSizeMax}`);
-    this._tagSize = v;
+var _AesGcmOptions = class _AesGcmOptions {
+  constructor(nonceSize, tagSize) {
+    if (nonceSize !== SecurityConstants.AesGcmNonceSize) {
+      throw new RangeError(
+        `AES-GCM requires exactly ${SecurityConstants.AesGcmNonceSize}-byte nonce per NIST SP 800-38D.`
+      );
+    }
+    if (tagSize < SecurityConstants.AesGcmTagSizeMin || tagSize > SecurityConstants.AesGcmTagSizeMax) {
+      throw new RangeError(
+        `Tag size must be between ${SecurityConstants.AesGcmTagSizeMin} and ${SecurityConstants.AesGcmTagSizeMax} bytes.`
+      );
+    }
+    this.nonceSize = nonceSize;
+    this.tagSize = tagSize;
+    Object.freeze(this);
   }
   /** Validates that {@link tagSize} is in the allowed range. */
   validate() {
-    if (this.tagSize < SecurityConstants.AesGcmTagSizeMin || this.tagSize > SecurityConstants.AesGcmTagSizeMax) throw new Error(`Invalid Tag Size: ${this.tagSize}`);
-  }
-  /** Default preset: nonce=12, tag=16, no AAD. */
-  static get default() {
-    return new _AesGcmOptions();
-  }
-  /** Fluent setter for {@link tagSize}. */
-  withTagSize(s) {
-    this.tagSize = s;
-    return this;
-  }
-  /**
-   * Fluent setter for {@link associatedData}.
-   * Accepts a byte array or a UTF-8 string (encoded internally).
-   */
-  withAssociatedData(aad) {
-    this.associatedData = typeof aad === "string" ? new TextEncoder().encode(aad) : aad;
-    return this;
-  }
-  /** Validates and returns this instance. */
-  build() {
-    this.validate();
-    return this;
+    if (this.tagSize < SecurityConstants.AesGcmTagSizeMin || this.tagSize > SecurityConstants.AesGcmTagSizeMax)
+      throw new Error(`Invalid Tag Size: ${this.tagSize}`);
   }
 };
+/**
+ * V1 preset: nonce=12, tag=16, no AAD.
+ * These exact values are frozen for all V1-encrypted payloads.
+ */
+_AesGcmOptions.V1 = Object.freeze(
+  new _AesGcmOptions(12, 16)
+);
+var AesGcmOptions = _AesGcmOptions;
 
 // src/crypto/crypto-profile.ts
 var CryptoProfile = class {
@@ -179,28 +163,21 @@ var CryptoVersion = /* @__PURE__ */ ((CryptoVersion2) => {
 })(CryptoVersion || {});
 
 // src/crypto/kdf-options.ts
-var KdfOptions = class _KdfOptions {
-  constructor() {
-    this._pbkdf2Iterations = SecurityConstants.Pbkdf2IterationsDefault;
-    this._hashAlgorithm = "SHA-256";
-  }
-  /** PBKDF2 iteration count (minimum 100_000). */
-  get pbkdf2Iterations() {
-    return this._pbkdf2Iterations;
-  }
-  set pbkdf2Iterations(v) {
-    if (v < SecurityConstants.Pbkdf2IterationsMinimum)
-      throw new RangeError(`PBKDF2 iterations must be \u2265 ${SecurityConstants.Pbkdf2IterationsMinimum}`);
-    this._pbkdf2Iterations = v;
-  }
-  /** Hash algorithm used by PBKDF2. Must be one of {@link SupportedHashAlgorithms}. */
-  get hashAlgorithm() {
-    return this._hashAlgorithm;
-  }
-  set hashAlgorithm(v) {
-    if (!SupportedHashAlgorithms.includes(v))
-      throw new RangeError(`Unsupported hash: ${v}`);
-    this._hashAlgorithm = v;
+var _KdfOptions = class _KdfOptions {
+  constructor(pbkdf2Iterations, hashAlgorithm) {
+    if (pbkdf2Iterations < SecurityConstants.Pbkdf2IterationsMinimum) {
+      throw new RangeError(
+        `PBKDF2 iterations must be at least ${SecurityConstants.Pbkdf2IterationsMinimum}.`
+      );
+    }
+    if (!SupportedHashAlgorithms.includes(hashAlgorithm)) {
+      throw new RangeError(
+        `Unsupported hash algorithm: ${hashAlgorithm}. Supported: ${SupportedHashAlgorithms.join(", ")}.`
+      );
+    }
+    this.pbkdf2Iterations = pbkdf2Iterations;
+    this.hashAlgorithm = hashAlgorithm;
+    Object.freeze(this);
   }
   /** Validates iterations and hash algorithm. */
   validate() {
@@ -209,26 +186,15 @@ var KdfOptions = class _KdfOptions {
     if (!SupportedHashAlgorithms.includes(this.hashAlgorithm))
       throw new Error(`Invalid hash algorithm: ${this.hashAlgorithm}`);
   }
-  /** Default preset: SHA-256, 600_000 iterations. */
-  static get default() {
-    return new _KdfOptions();
-  }
-  /** Fluent setter for {@link pbkdf2Iterations}. */
-  withPbkdf2Iterations(i) {
-    this.pbkdf2Iterations = i;
-    return this;
-  }
-  /** Fluent setter for {@link hashAlgorithm}. */
-  withHashAlgorithm(h) {
-    this.hashAlgorithm = h;
-    return this;
-  }
-  /** Validates and returns this instance. */
-  build() {
-    this.validate();
-    return this;
-  }
 };
+/**
+ * V1 preset: SHA-256, 600_000 iterations.
+ * These exact values are frozen for all V1-derived keys.
+ */
+_KdfOptions.V1 = Object.freeze(
+  new _KdfOptions(6e5, "SHA-256")
+);
+var KdfOptions = _KdfOptions;
 
 // src/crypto/crypto-profile-registry.ts
 var CryptoProfileRegistry = class {
@@ -237,8 +203,8 @@ var CryptoProfileRegistry = class {
       case 1 /* V1 */:
         return new CryptoProfile({
           version: 1 /* V1 */,
-          kdfOptions: KdfOptions.default,
-          aesGcmOptions: AesGcmOptions.default
+          kdfOptions: KdfOptions.V1,
+          aesGcmOptions: AesGcmOptions.V1
         });
       default:
         throw new Error(`Unsupported crypto version: ${version}`);
@@ -286,16 +252,11 @@ var CryptoService = class {
       false,
       ["encrypt"]
     );
-    let associatedData = new Uint8Array(0);
-    if (opts.associatedData != null) {
-      associatedData = opts.associatedData;
-    }
     const encryptedContent = await crypto.subtle.encrypt(
       {
         name: "AES-GCM",
         iv: nonce,
-        tagLength: opts.tagSize * 8,
-        additionalData: associatedData
+        tagLength: opts.tagSize * 8
       },
       cryptoKey,
       plainBytes
@@ -334,15 +295,11 @@ var CryptoService = class {
       ["decrypt"]
     );
     try {
-      let associatedData = new Uint8Array(0);
-      if (opts.associatedData != null)
-        associatedData = opts.associatedData;
       const decryptedBuffer = await crypto.subtle.decrypt(
         {
           name: "AES-GCM",
           iv: nonce,
-          tagLength: opts.tagSize * 8,
-          additionalData: associatedData
+          tagLength: opts.tagSize * 8
         },
         cryptoKey,
         ciphertextWithTag