@crossdyne/security 0.5.0-beta.1 → 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;
 };
 
@@ -31,7 +38,6 @@ declare class CryptoService {
     * Encrypts a serializable object to a Base64 string.
     * @param dataModel - Object or Uint8Array to encrypt.
     * @param key - AES-256 key (32 bytes).
-    * @param options - AES-GCM configuration; uses default if omitted.
     * @returns Base64-encoded ciphertext with prepended nonce.
     */
     encryptData<T>(dataModel: T, key: Uint8Array, version?: CryptoVersion): Promise<string>;
@@ -39,7 +45,6 @@ declare class CryptoService {
     * Decrypts a Base64-encoded ciphertext back to the original object.
     * @param encryptedBase64 - The encrypted data.
     * @param key - AES-256 key (32 bytes).
-    * @param options - AES-GCM configuration; uses default if omitted.
     * @returns Deserialized object, or null if input is empty.
     * @throws If authentication tag mismatch or corrupted data.
     */
@@ -57,86 +62,62 @@ declare class CryptoService {
  */
 declare class KeyDerivationService {
     /**
-    * Derives KEK and Base64 AuthHash. Identity is hashed as-is — caller must
-    * normalize (trim, lowercase, etc.) before calling.
-    * @param identity - User identity (pre-normalized by caller).
-    * @param identity - User identity (email, username).
-    * @param password - User password.
-    * @param salt - Random salt.
-    * @param options - KDF configuration; uses default if omitted.
-    * @returns Object with `kek` (Uint8Array) and `authHash` (Base64 string).
-    */
+     * Derives KEK and Base64 AuthHash. Identity is used as-is in the
+     * combined salt string — caller must normalize (trim, lowercase, etc.) before calling.
+     * @param identity - User identity (email, username). Must be pre-normalized by caller.
+     * @param password - User password.
+     * @param salt - Random salt (minimum 16 bytes).
+     * @param version - Crypto version for profile selection.
+     * @returns Object with `kek` (Uint8Array) and `authHash` (Base64 string).
+     */
     deriveKeysFromPassword(identity: string, password: string, salt: Uint8Array, version: CryptoVersion): Promise<{
         kek: Uint8Array;
         authHash: string;
     }>;
-    /**
-    * Derives an SRP-compatible authentication hash (output size = hash output length).
-    * Identity is hashed as-is — caller must normalize (trim, lowercase, etc.) before calling.
-    * @param identity - User identity (pre-normalized by caller).
-    * @param identity - User identity.
-    * @param password - User password.
-    * @param salt - Random salt.
-    * @param srpHashAlgorithm - SRP hash algorithm (SHA-256/384/512).
-    * @param options - KDF configuration; uses default if omitted.
-    * @returns Raw hash bytes for use as SRP verifier input (x).
-    */
-    deriveAuthHashForSrp(identity: string, password: string, salt: Uint8Array, srpHashAlgorithm: HashAlgorithm, version: CryptoVersion): Promise<Uint8Array>;
 }
 
 /**
- * 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;
 }
 
 /**
@@ -172,45 +153,51 @@ declare class CryptoProfileRegistry {
 }
 
 /**
- * Immutable SRP cryptographic context: modulus, generator, multiplier k, hash algorithm, and sizes.
+ * SRP-6a Diffie-Hellman groups (RFC 5054).
+ * 1024 (~80) deprecated, 1536 (~90) legacy, 2048 (~112) baseline,
+ * 3072+ (≥128) preferred. g=2 for ≤2048, g=5 for 3072-6144, g=19 for 8192.
+ * Always use {@link SrpGroupParams} to get N and g.
  */
-interface SrpContext {
-    /** Prime modulus N. */
-    readonly N: bigint;
-    /** Generator g. */
-    readonly g: bigint;
-    /** Multiplier k = H(PAD(N) || PAD(g)) (RFC 5054, 2.5.3) */
-    readonly k: bigint;
-    /** Modulus size in bytes (ceil(bit length / 8)). */
-    readonly modulusSize: number;
-    /** Hash algorithm used for SRP computations. */
-    readonly hashAlgorithmName: HashAlgorithm;
-    /** Hash output size in bytes (e.g., 32 for SHA-256). */
-    readonly hashSize: number;
+declare enum SrpGroup {
+    /** 1024-bit, g=2, ~80-bit security. Deprecated, legacy only. */
+    Rfc5054_1024 = 1,
+    /** 1536-bit, g=2, ~90-bit security. Minimum for legacy systems. */
+    Rfc5054_1536 = 2,
+    /** 2048-bit, g=2, ~112-bit security. Recommended baseline. */
+    Rfc5054_2048 = 3,
+    /** 3072-bit, g=5, ~128-bit security. Preferred for long-term. */
+    Rfc5054_3072 = 4,
+    /** 4096-bit, g=5, ~156-bit security. High-security environments. */
+    Rfc5054_4096 = 5,
+    /** 6144-bit, g=5, ~192-bit security. Specialized high-assurance. */
+    Rfc5054_6144 = 6,
+    /** 8192-bit, g=19, ~256-bit security. Experimental, extremely slow. */
+    Rfc5054_8192 = 7,
+    /** User-supplied N and g. Validate safe prime and generator. */
+    Custom = 99
 }
 
 /**
  * Client-side SRP-6a implementation: proof generation, verifier creation, server M2 verification.
  */
 declare class SrpClientService {
-    private readonly keyDerivation;
     /**
     * Computes SRP verifier v = g^x mod N from the authentication hash.
     * @param authHash - Auth hash (Base64).
-    * @param ctx - SRP context (N, g, hash algorithm, etc.).
+    * @param group - SRP group (determines modulus N, generator g, hash).
     * @returns Verifier as Base64 string.
     */
-    generateSrpVerifier(authHash: string, ctx: SrpContext): Promise<string>;
+    generateSrpVerifier(authHash: string, group: SrpGroup): Promise<string>;
     /**
      * Generates client proof (A, M1, session key S) from server challenge.
      * @param login - User login.
-     * @param password - Plaintext password.
+     * @param authHashBytes - SRP private exponent x as raw bytes (derived from auth hash).
      * @param saltBase64 - Server salt (standard Base64).
      * @param B_base64 - Server public ephemeral B (standard Base64).
-     * @param ctx - SRP context.
+     * @param group - SRP group (determines modulus N, generator g, hash).
      * @returns Object with A and M1 as standard Base64; SessionKeyK as raw bytes.
      */
-    generateSrpProof(login: string, password: string, saltBase64: string, B_base64: string, ctx: SrpContext, version: CryptoVersion): Promise<{
+    generateSrpProof(login: string, authHashBytes: Uint8Array<ArrayBufferLike>, saltBase64: string, B_base64: string, group: SrpGroup): Promise<{
         A: string;
         M1: string;
         SessionKeyK: Uint8Array;
@@ -219,12 +206,12 @@ declare class SrpClientService {
      * Validates the server proof M2 to authenticate the server.
      * @param A_b64 - Client public A (Base64).
      * @param M1_b64 - Client proof M1 (Base64).
-     * @param S_b64 - Session key S (Base64).
+     * @param sessionKeyK - Session key K as raw bytes.
      * @param serverM2_b64 - Server proof M2 (Base64).
-     * @param ctx - SRP context.
+     * @param group - SRP group (determines modulus N, generator g, hash).
      * @returns True if the server proof is valid.
      */
-    verifyServerM2(A_b64: string, M1_b64: string, sessionKeyK: Uint8Array, serverM2_b64: string, ctx: SrpContext): Promise<boolean>;
+    verifyServerM2(A_b64: string, M1_b64: string, sessionKeyK: Uint8Array, serverM2_b64: string, group: SrpGroup): Promise<boolean>;
 }
 
 /**
@@ -233,13 +220,13 @@ declare class SrpClientService {
 interface SrpSessionState {
     /** User login identifier. */
     login: string;
-    /** Server private ephemeral key (Base64). */
+    /** Server private ephemeral key (raw bytes). */
     privateKeyB: Uint8Array;
-    /** Password verifier (Base64). */
+    /** Password verifier v (raw bytes). */
     verifier: Uint8Array;
-    /** Server public ephemeral key B (Base64). */
+    /** Server public ephemeral key B (raw bytes). */
     publicKeyB: Uint8Array;
-    /** User salt s (needed for RFC 5054 M1). */
+    /** User salt s (raw bytes). */
     salt: Uint8Array;
 }
 /**
@@ -250,45 +237,39 @@ declare class SrpServerService {
      * Generates server challenge B and session state from verifier.
      * @param login - User login.
      * @param verifierBytes - Stored verifier v as byte array.
-     * @param ctx - SRP context (hash, N, g, etc.).
-     * @returns Session state with private b, verifier, and public B.
+     * @param salt - User salt (raw bytes).
+     * @param group - SRP group (determines modulus N, generator g, hash).
+     * @returns Session state with private b, verifier, public B, and salt.
      */
-    getSrpChallenge(login: string, verifierBytes: Uint8Array, salt: Uint8Array, ctx: SrpContext): Promise<SrpSessionState>;
+    getSrpChallenge(login: string, verifierBytes: Uint8Array, salt: Uint8Array, group: SrpGroup): Promise<SrpSessionState>;
     /**
      * Verifies client M1 proof and returns server M2 proof.
      * @param sessionState - Server session state.
      * @param a - Client public A (Base64).
      * @param m1 - Client proof M1 (Base64).
-     * @param ctx - SRP context.
+     * @param group - SRP group (determines modulus N, generator g, hash).
      * @returns Server proof M2 as Base64 string.
      * @throws If verification fails or input is invalid.
      */
-    verifySrpProof(sessionState: SrpSessionState, a: string, m1: string, ctx: SrpContext): Promise<string>;
+    verifySrpProof(sessionState: SrpSessionState, a: string, m1: string, group: SrpGroup): Promise<string>;
 }
 
 /**
- * SRP-6a Diffie-Hellman groups (RFC 5054).
- * 1024 (~80) deprecated, 1536 (~90) legacy, 2048 (~112) baseline,
- * 3072+ (≥128) preferred. g=2 for ≤2048, g=5 for 3072-6144, g=19 for 8192.
- * Always use {@link SrpGroupParams} to get N and g.
+ * Service for deriving SRP authentication hashes via PBKDF2 → HKDF.
  */
-declare enum SrpGroup {
-    /** 1024-bit, g=2, ~80-bit security. Deprecated, legacy only. */
-    Rfc5054_1024 = 1,
-    /** 1536-bit, g=2, ~90-bit security. Minimum for legacy systems. */
-    Rfc5054_1536 = 2,
-    /** 2048-bit, g=2, ~112-bit security. Recommended baseline. */
-    Rfc5054_2048 = 3,
-    /** 3072-bit, g=5, ~128-bit security. Preferred for long-term. */
-    Rfc5054_3072 = 4,
-    /** 4096-bit, g=5, ~156-bit security. High-security environments. */
-    Rfc5054_4096 = 5,
-    /** 6144-bit, g=5, ~192-bit security. Specialized high-assurance. */
-    Rfc5054_6144 = 6,
-    /** 8192-bit, g=19, ~256-bit security. Experimental, extremely slow. */
-    Rfc5054_8192 = 7,
-    /** User-supplied N and g. Validate safe prime and generator. */
-    Custom = 99
+declare class SrpKeyDerivationService {
+    /**
+     * Derives an SRP-compatible authentication hash (output size = hash output length).
+     * Identity is used as-is in the combined string — caller must normalize
+     * (trim, lowercase, etc.) before calling.
+     * @param identity - User identity (email, username). Must be pre-normalized by caller.
+     * @param password - User password.
+     * @param salt - Random salt (minimum 16 bytes).
+     * @param srpGroup - SRP group (determines hash algorithm and modulus).
+     * @param version - Crypto version for KDF profile selection.
+     * @returns Raw hash bytes for use as SRP verifier input (x).
+     */
+    deriveAuthHashForSrp(identity: string, password: string, salt: Uint8Array, srpGroup: SrpGroup, version: CryptoVersion): Promise<Uint8Array>;
 }
 
 /**
@@ -333,6 +314,24 @@ declare class SrpGroupParams {
     static getG(group: SrpGroup): bigint;
 }
 
+/**
+ * Immutable SRP cryptographic context: modulus, generator, multiplier k, hash algorithm, and sizes.
+ */
+interface SrpContext {
+    /** Prime modulus N. */
+    readonly N: bigint;
+    /** Generator g. */
+    readonly g: bigint;
+    /** Multiplier k = H(PAD(N) || PAD(g)) (RFC 5054, 2.5.3) */
+    readonly k: bigint;
+    /** Modulus size in bytes (ceil(bit length / 8)). */
+    readonly modulusSize: number;
+    /** Hash algorithm used for SRP computations. */
+    readonly hashAlgorithmName: HashAlgorithm;
+    /** Hash output size in bytes (e.g., 32 for SHA-256). */
+    readonly hashSize: number;
+}
+
 /**
  * Factory for creating an {@link SrpContext} from an SRP group.
  * Automatically selects the hash algorithm (SHA-256 for ≤3072-bit, SHA-384 for 4096+).
@@ -360,8 +359,15 @@ declare class SecurityUtils {
     static bigIntToFixedBytes(bn: bigint, length: number): Uint8Array;
     /** Constant-time comparison of two Uint8Arrays. */
     static fixedTimeEquals(a: Uint8Array, b: Uint8Array): boolean;
-    /** Modular exponentiation (base^exp mod mod) using binary exponentiation. */
-    static expMod(base: bigint, exp: bigint, mod: bigint): bigint;
+    /**
+     * Async modular exponentiation with event-loop yielding.
+     * @param base - The base value.
+     * @param exp - The exponent.
+     * @param mod - The modulus.
+     * @param yieldEvery - Number of iterations before yielding (default 64).
+     */
+    static expModAsync(base: bigint, exp: bigint, mod: bigint, yieldEvery?: number): Promise<bigint>;
+    /** Converts bigint to minimal-length big-endian bytes (no padding). */
     static bigIntToRawBytes(bn: bigint): Uint8Array;
 }
 
@@ -381,7 +387,7 @@ declare class SrpEncoding {
     * Follows RFC 5054 / SRP-6a:
     * - H(N) and H(g) are hashed as modulus-sized values.
     * - Identity (I) is hashed as raw UTF-8 bytes.
-    * - A and B are padded to the modulus size before hashing.
+    * - A and B are zero-padded to the modulus size before hashing.
     * - K is the session key (H(S) without padding).
     *
     * @param ctx - SRP context containing N, g, hash algorithm, and modulus size.
@@ -393,14 +399,17 @@ declare class SrpEncoding {
     * @returns The M1 proof as raw hash bytes.
     */
     static computeM1(ctx: SrpContext, A: bigint, B: bigint, sessionKeyK: Uint8Array, identity: string, salt: Uint8Array): Promise<Uint8Array>;
-    /** Computes M2 = H(A || M1 || sessionKeyK). */
+    /**
+    * Computes M2 = H( PAD(A) || M1 || sessionKeyK ).
+    * A is zero-padded to the modulus size before hashing.
+    */
     static computeM2(ctx: SrpContext, A: bigint, m1Bytes: Uint8Array, sessionKeyK: Uint8Array): Promise<Uint8Array>;
     /** Computes session key K = H(S). */
     static computeSessionKey(ctx: SrpContext, S: bigint): Promise<Uint8Array>;
-    /** Hashes bytes and returns raw Uint8Array (для M1/M2). */
+    /** Hashes concatenated byte arrays and returns raw Uint8Array. */
     private static computeHash;
     /** Concatenates byte arrays and returns the hash as bigint. */
     private static hash;
 }
 
-export { AesGcmOptions, CryptoProfile, CryptoProfileRegistry, CryptoService, CryptoVersion, type HashAlgorithm, KdfOptions, KeyDerivationService, SecurityConstants, SecurityUtils, SrpClientService, type SrpContext, SrpContextFactory, SrpEncoding, SrpGroup, SrpGroupParams, SrpOptions, SrpServerService, type SrpSessionState, SupportedHashAlgorithms };
+export { AesGcmOptions, CryptoProfile, CryptoProfileRegistry, CryptoService, CryptoVersion, type HashAlgorithm, KdfOptions, KeyDerivationService, SecurityConstants, SecurityUtils, SrpClientService, type SrpContext, SrpContextFactory, SrpEncoding, SrpGroup, SrpGroupParams, SrpKeyDerivationService, SrpOptions, SrpServerService, type SrpSessionState, SupportedHashAlgorithms };