@crossdyne/security 0.5.0-beta.2 → 1.0.0

package/dist/index.d.ts

@@ -1,12 +1,19 @@
 type HashAlgorithm = 'SHA-256' | 'SHA-384' | 'SHA-512';
 
+/**
+ * Algorithmic constraints that are physically immutable.
+ * These do not change between crypto versions.
+ */
 declare const SecurityConstants: {
+    /** Standard nonce size for AES-GCM (96 bits). Fixed by NIST SP 800-38D. */
     readonly AesGcmNonceSize: 12;
-    readonly AesGcmTagSize: 16;
+    /** Minimum allowed authentication tag size (96 bits). */
     readonly AesGcmTagSizeMin: 12;
+    /** Maximum allowed authentication tag size (128 bits). */
     readonly AesGcmTagSizeMax: 16;
+    /** Key size for AES-256 (256 bits). */
     readonly KeySizeBytes: 32;
-    readonly Pbkdf2IterationsDefault: 600000;
+    /** Absolute minimum PBKDF2 iterations for any profile version. */
     readonly Pbkdf2IterationsMinimum: 100000;
 };
 
@@ -70,58 +77,47 @@ declare class KeyDerivationService {
 }
 
 /**
- * AES-GCM encryption options: nonce size, tag size, and optional AAD.
- * Mutable builder-style; call {@link build} to validate.
+ * Immutable AES-GCM configuration. All parameters are validated at creation.
+ *
+ * @remarks
+ * Do not construct manually. Use versioned presets such as {@link AesGcmOptions.V1}
+ * or the {@link AesGcmOptions.create} factory for custom (non-standard) configurations.
  */
 declare class AesGcmOptions {
-    private _nonceSize;
-    private _tagSize;
-    /** Optional Additional Authenticated Data (not encrypted). */
-    associatedData?: Uint8Array;
-    /** Nonce size in bytes (must be 12). */
-    get nonceSize(): number;
-    set nonceSize(v: number);
-    /** Tag size in bytes (12–16, default 16). */
-    get tagSize(): number;
-    set tagSize(v: number);
+    /** Nonce size in bytes. Must equal 12 (NIST SP 800-38D). */
+    readonly nonceSize: number;
+    /** Authentication tag size in bytes. Allowed range: 12–16. */
+    readonly tagSize: number;
+    private constructor();
     /** Validates that {@link tagSize} is in the allowed range. */
     validate(): void;
-    /** Default preset: nonce=12, tag=16, no AAD. */
-    static get default(): AesGcmOptions;
-    /** Fluent setter for {@link tagSize}. */
-    withTagSize(s: number): this;
     /**
-     * Fluent setter for {@link associatedData}.
-     * Accepts a byte array or a UTF-8 string (encoded internally).
+     * V1 preset: nonce=12, tag=16, no AAD.
+     * These exact values are frozen for all V1-encrypted payloads.
      */
-    withAssociatedData(aad: Uint8Array | string | undefined): this;
-    /** Validates and returns this instance. */
-    build(): AesGcmOptions;
+    static readonly V1: AesGcmOptions;
 }
 
 /**
- * PBKDF2 key derivation options: iterations count and hash algorithm.
- * Mutable builder-style; call {@link build} to validate.
+ * Immutable PBKDF2/HKDF configuration. All parameters are validated at creation.
+ *
+ * @remarks
+ * Do not construct manually. Use versioned presets such as {@link KdfOptions.V1}
+ * or the {@link KdfOptions.create} factory for custom (non-standard) configurations.
  */
 declare class KdfOptions {
-    private _pbkdf2Iterations;
-    private _hashAlgorithm;
-    /** PBKDF2 iteration count (minimum 100_000). */
-    get pbkdf2Iterations(): number;
-    set pbkdf2Iterations(v: number);
-    /** Hash algorithm used by PBKDF2. Must be one of {@link SupportedHashAlgorithms}. */
-    get hashAlgorithm(): HashAlgorithm;
-    set hashAlgorithm(v: HashAlgorithm);
+    /** PBKDF2 iteration count. Must be at least 100_000. */
+    readonly pbkdf2Iterations: number;
+    /** Hash algorithm used by PBKDF2 and HKDF. Supported: SHA-256, SHA-384, SHA-512. */
+    readonly hashAlgorithm: HashAlgorithm;
+    private constructor();
     /** Validates iterations and hash algorithm. */
     validate(): void;
-    /** Default preset: SHA-256, 600_000 iterations. */
-    static get default(): KdfOptions;
-    /** Fluent setter for {@link pbkdf2Iterations}. */
-    withPbkdf2Iterations(i: number): this;
-    /** Fluent setter for {@link hashAlgorithm}. */
-    withHashAlgorithm(h: HashAlgorithm): this;
-    /** Validates and returns this instance. */
-    build(): KdfOptions;
+    /**
+     * V1 preset: SHA-256, 600_000 iterations.
+     * These exact values are frozen for all V1-derived keys.
+     */
+    static readonly V1: KdfOptions;
 }
 
 /**

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 {
@@ -177,28 +161,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,26 +184,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 {
@@ -235,8 +201,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}`);
@@ -284,16 +250,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
@@ -332,15 +293,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