@crossdyne/security 0.5.0-beta.2 → 2.0.0

package/dist/index.js

@@ -1,12 +1,14 @@
 // 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 = {
@@ -108,54 +110,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 {
@@ -165,6 +149,7 @@ var CryptoProfile = class {
    */
   constructor(params) {
     this.version = params.version;
+    this.algorithmName = params.algorithmName;
     this.kdfOptions = params.kdfOptions;
     this.aesGcmOptions = params.aesGcmOptions;
   }
@@ -177,28 +162,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() {
@@ -207,46 +185,33 @@ 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 {
   static getProfile(version) {
     switch (version) {
       case 1 /* V1 */:
-        return new CryptoProfile({
-          version: 1 /* V1 */,
-          kdfOptions: KdfOptions.default,
-          aesGcmOptions: AesGcmOptions.default
-        });
+        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 {
@@ -261,7 +226,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 */) {
@@ -277,25 +242,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"]
-    );
-    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,
+      key,
       plainBytes
     );
     const result = new Uint8Array(1 + opts.nonceSize + encryptedContent.byteLength);
@@ -307,7 +260,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.
   */
@@ -324,25 +277,14 @@ 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 {
-      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,
+        key,
         ciphertextWithTag
       );
       const decoder = new TextDecoder();
@@ -357,6 +299,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