@crossdyne/security 1.0.0 → 2.0.0

package/README.md

@@ -23,7 +23,6 @@ npm install @crossdyne/security
 - **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
@@ -50,7 +49,7 @@ crossdyne-security/
 │   └── srp-encoding.ts                # BigInt ↔ bytes helpers
 └── utils/
     ├── security-utils.ts              # Base64, BigInt, fixed-time compare
-    └── srp-encoding.ts               # Hash moduli, session key, M1 / M2
+    └── srp-encoding.ts                # Hash moduli, session key, M1 / M2
 ```
 
 ### Quick Start
@@ -62,15 +61,21 @@ 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 rawKey = crypto.generateRandomBytes(32); // AES-256 raw key
+
+// Import the raw key into a non-extractable CryptoKey
+const cryptoKey = await crypto.importKey(rawKey, CryptoVersion.V1, ['encrypt', 'decrypt']);
 
 const encrypted = await crypto.encryptData(
   { message: "Hello, World!" },
-  key,
+  cryptoKey,
   CryptoVersion.V1
 );
 
-const decrypted = await crypto.decryptData<MyData>(encrypted, key);
+const decrypted = await crypto.decryptData<MyData>(encrypted, cryptoKey);
+
+// Best practice: securely wipe the raw key from memory after import
+rawKey.fill(0);
 ```
 
 Encrypted payload format (Base64):
@@ -83,6 +88,7 @@ Encrypted payload format (Base64):
 
 ```typescript
 import { KeyDerivationService } from './crypto/key-derivation-service.js';
+import { CryptoService } from './crypto/crypto-service.js';
 import { CryptoVersion } from './crypto/crypto-version.js';
 
 const kdf = new KeyDerivationService();
@@ -174,11 +180,10 @@ const isValid = await client.verifyServerM2(
 
 ### 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
+- All sensitive buffers (like raw keys) should be explicitly overwritten (`fill(0)`) after being imported into a `CryptoKey`.
+- 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`).
 
 ### License
 
@@ -203,7 +208,6 @@ npm install @crossdyne/security
 - **PBKDF2 + HKDF** — надёжный вывод ключей из пароля
 - **SRP-6a** — протокол аутентификации без передачи пароля на сервер
 - **Zero-memory** — чувствительные буферы явно перезаписываются после использования
-- **Никаких самописных криптопримитивов** — только нативный Web Crypto API браузера / Node.js
 - **Кроссплатформенность** — совместима с [.NET-реализацией](https://github.com/crossdyne/dotnet-security). Зашифрованные данные и SRP-сообщения взаимозаменяемы между TS и .NET.
 
 ### Требования
@@ -230,7 +234,7 @@ crossdyne-security/
 │   └── srp-encoding.ts                # BigInt ↔ bytes хелперы
 └── utils/
     ├── security-utils.ts              # Base64, BigInt, сравнение в постоянное время
-    └── srp-encoding.ts               # Хеш модулей, сессионный ключ, M1 / M2
+    └── srp-encoding.ts                # Хеш модулей, сессионный ключ, M1 / M2
 ```
 
 ### Быстрый старт
@@ -242,15 +246,21 @@ 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 rawKey = crypto.generateRandomBytes(32); // Сырой ключ AES-256
+
+// Импортируем сырой ключ в неизвлекаемый CryptoKey
+const cryptoKey = await crypto.importKey(rawKey, CryptoVersion.V1, ['encrypt', 'decrypt']);
 
 const encrypted = await crypto.encryptData(
   { message: "Hello, World!" },
-  key,
+  cryptoKey,
   CryptoVersion.V1
 );
 
-const decrypted = await crypto.decryptData<MyData>(encrypted, key);
+const decrypted = await crypto.decryptData<MyData>(encrypted, cryptoKey);
+
+// Рекомендуемая практика: безопасно очистить сырой ключ из памяти сразу после импорта
+rawKey.fill(0);
 ```
 
 Формат зашифрованных данных (Base64):
@@ -354,11 +364,10 @@ const isValid = await client.verifyServerM2(
 
 ### Безопасность
 
-- Все чувствительные буферы явно перезаписываются после использования
-- Соль должна быть **минимум 16 байт**
-- Ключ AES-256 — **строго 32 байта**
-- SRP-группы защищены от атак на малые подгруппы (проверки `A % N != 0`, `B != 0`)
-- Полностью опирается на нативный Web Crypto API — никаких самописных криптопримитивов
+- Все чувствительные буферы (сырые ключи и тд) должны быть явно перезаписаны (`fill(0)`) после их импорта в `CryptoKey`.
+- Соль должна быть **минимум 16 байт**.
+- Ключ AES-256 — **строго 32 байта**.
+- SRP-группы защищены от атак на малые подгруппы (проверки `A % N != 0`, `B != 0`).
 
 ### Лицензия
 

package/dist/index.cjs

@@ -151,6 +151,7 @@ var CryptoProfile = class {
    */
   constructor(params) {
     this.version = params.version;
+    this.algorithmName = params.algorithmName;
     this.kdfOptions = params.kdfOptions;
     this.aesGcmOptions = params.aesGcmOptions;
   }
@@ -201,20 +202,18 @@ var CryptoProfileRegistry = class {
   static getProfile(version) {
     switch (version) {
       case 1 /* V1 */:
-        return new CryptoProfile({
-          version: 1 /* V1 */,
-          kdfOptions: KdfOptions.V1,
-          aesGcmOptions: AesGcmOptions.V1
-        });
+        return this.V1_PROFILE;
       default:
         throw new Error(`Unsupported crypto version: ${version}`);
     }
   }
-  /** Latest supported profile (currently V1). */
-  static get latest() {
-    return this.getProfile(1 /* V1 */);
-  }
 };
+CryptoProfileRegistry.V1_PROFILE = new CryptoProfile({
+  version: 1 /* V1 */,
+  algorithmName: "AES-GCM",
+  kdfOptions: KdfOptions.V1,
+  aesGcmOptions: AesGcmOptions.V1
+});
 
 // src/crypto/crypto.service.ts
 var CryptoService = class {
@@ -229,7 +228,7 @@ var CryptoService = class {
   /**
   * Encrypts a serializable object to a Base64 string.
   * @param dataModel - Object or Uint8Array to encrypt.
-  * @param key - AES-256 key (32 bytes).
+  * @param key - A non-extractable CryptoKey obtained via {@link CryptoService.importKey}.
   * @returns Base64-encoded ciphertext with prepended nonce.
   */
   async encryptData(dataModel, key, version = 1 /* V1 */) {
@@ -245,20 +244,13 @@ var CryptoService = class {
     }
     const plainBytes = encoder.encode(jsonString);
     const nonce = crypto.getRandomValues(new Uint8Array(opts.nonceSize));
-    const cryptoKey = await crypto.subtle.importKey(
-      "raw",
-      key,
-      "AES-GCM",
-      false,
-      ["encrypt"]
-    );
     const encryptedContent = await crypto.subtle.encrypt(
       {
         name: "AES-GCM",
         iv: nonce,
         tagLength: opts.tagSize * 8
       },
-      cryptoKey,
+      key,
       plainBytes
     );
     const result = new Uint8Array(1 + opts.nonceSize + encryptedContent.byteLength);
@@ -270,7 +262,7 @@ var CryptoService = class {
   /**
   * Decrypts a Base64-encoded ciphertext back to the original object.
   * @param encryptedBase64 - The encrypted data.
-  * @param key - AES-256 key (32 bytes).
+  * @param key - A non-extractable CryptoKey obtained via {@link CryptoService.importKey}.
   * @returns Deserialized object, or null if input is empty.
   * @throws If authentication tag mismatch or corrupted data.
   */
@@ -287,13 +279,6 @@ var CryptoService = class {
       throw new Error(`Invalid format: minimum expected ${opts.nonceSize + opts.tagSize} byte.`);
     const nonce = payload.slice(0, opts.nonceSize);
     const ciphertextWithTag = payload.slice(opts.nonceSize);
-    const cryptoKey = await crypto.subtle.importKey(
-      "raw",
-      key,
-      "AES-GCM",
-      false,
-      ["decrypt"]
-    );
     try {
       const decryptedBuffer = await crypto.subtle.decrypt(
         {
@@ -301,7 +286,7 @@ var CryptoService = class {
           iv: nonce,
           tagLength: opts.tagSize * 8
         },
-        cryptoKey,
+        key,
         ciphertextWithTag
       );
       const decoder = new TextDecoder();
@@ -316,6 +301,28 @@ var CryptoService = class {
       throw new Error("Decryption failed: authentication tag mismatch or corrupted data.");
     }
   }
+  /**
+   * Imports raw key bytes into a non-extractable CryptoKey based on the crypto profile version.
+   *
+   * The resulting key cannot be exported back to raw bytes (extractable: false),
+   * ensuring that sensitive key material does not persist in JavaScript-accessible memory.
+   * Callers should securely wipe the original raw key buffer immediately after import.
+   *
+   * @param rawKey - Raw key bytes (e.g. a Data Encryption Key).
+   * @param version - Crypto profile version that determines the algorithm and parameters.
+   * @param usages - Allowed key operations (e.g. ['encrypt', 'decrypt']).
+   * @returns A non-extractable CryptoKey bound to the algorithm defined by the profile.
+   */
+  async importKey(rawKey, version, usages) {
+    const profile = CryptoProfileRegistry.getProfile(version);
+    return await crypto.subtle.importKey(
+      "raw",
+      rawKey,
+      profile.algorithmName,
+      false,
+      usages
+    );
+  }
 };
 
 // src/crypto/key-derivation.service.ts