@crossdyne/security 0.4.0-beta.1 → 0.5.0-beta.2

package/dist/index.d.ts

@@ -13,33 +13,13 @@ declare const SecurityConstants: {
 declare const SupportedHashAlgorithms: ReadonlyArray<HashAlgorithm>;
 
 /**
- * AES-GCM encryption options: nonce size, tag size, and optional AAD.
- * Mutable builder-style; call {@link build} to validate.
+ * Supported cryptographic profile versions.
+ * V1: baseline (PBKDF2-HMAC-SHA256, AES-256-GCM, 12-byte nonce, 16-byte tag).
+ * Append new members sequentially; never change existing values.
  */
-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);
-    /** 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).
-     */
-    withAssociatedData(aad: Uint8Array | string | undefined): this;
-    /** Validates and returns this instance. */
-    build(): AesGcmOptions;
+declare enum CryptoVersion {
+    /** Version 1 — initial profile. */
+    V1 = 1
 }
 
 /**
@@ -51,19 +31,17 @@ 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, options?: AesGcmOptions): Promise<string>;
+    encryptData<T>(dataModel: T, key: Uint8Array, version?: CryptoVersion): Promise<string>;
     /**
     * 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.
     */
-    decryptData<T>(encryptedBase64: string, key: Uint8Array, options?: AesGcmOptions, isBytes?: boolean): Promise<T | null>;
+    decryptData<T>(encryptedBase64: string, key: Uint8Array, isBytes?: boolean): Promise<T | null>;
     /**
     * Generates cryptographically secure random bytes.
     * @param length - Number of bytes (default 32).
@@ -72,6 +50,55 @@ declare class CryptoService {
     generateRandomBytes: (length?: number) => Uint8Array;
 }
 
+/**
+ * Two-stage key derivation: PBKDF2 (master key) → HKDF (sub-keys).
+ */
+declare class KeyDerivationService {
+    /**
+     * 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;
+    }>;
+}
+
+/**
+ * AES-GCM encryption options: nonce size, tag size, and optional AAD.
+ * Mutable builder-style; call {@link build} to validate.
+ */
+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);
+    /** 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).
+     */
+    withAssociatedData(aad: Uint8Array | string | undefined): this;
+    /** Validates and returns this instance. */
+    build(): AesGcmOptions;
+}
+
 /**
  * PBKDF2 key derivation options: iterations count and hash algorithm.
  * Mutable builder-style; call {@link build} to validate.
@@ -97,44 +124,6 @@ declare class KdfOptions {
     build(): KdfOptions;
 }
 
-/**
- * Two-stage key derivation: PBKDF2 (master key) → HKDF (sub-keys).
- */
-declare class KeyDerivationService {
-    /**
-    * Derives KEK and Base64 AuthHash. Identity is normalized (trimmed, lowercase).
-    * @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).
-    */
-    deriveKeysFromPassword(identity: string, password: string, salt: Uint8Array, options?: KdfOptions): Promise<{
-        kek: Uint8Array;
-        authHash: string;
-    }>;
-    /**
-    * Derives an SRP-compatible authentication hash (output size = hash output length).
-    * @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, options?: KdfOptions): Promise<Uint8Array>;
-}
-
-/**
- * Supported cryptographic profile versions.
- * V1: baseline (PBKDF2-HMAC-SHA256, AES-256-GCM, 12-byte nonce, 16-byte tag).
- * Append new members sequentially; never change existing values.
- */
-declare enum CryptoVersion {
-    /** Version 1 — initial profile. */
-    V1 = 1
-}
-
 /**
  * Immutable cryptographic profile bundling version, KDF, and AES-GCM settings.
  * Thread-safe after construction.
@@ -168,45 +157,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 saltBase64 - Server salt (URL-safe Base64).
-     * @param B_base64 - Server public ephemeral B (URL-safe Base64).
-     * @param ctx - SRP context.
-     * @returns Object with A, M1, S as Base64 strings.
+     * @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 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): Promise<{
+    generateSrpProof(login: string, authHashBytes: Uint8Array<ArrayBufferLike>, saltBase64: string, B_base64: string, group: SrpGroup): Promise<{
         A: string;
         M1: string;
         SessionKeyK: Uint8Array;
@@ -215,12 +210,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>;
 }
 
 /**
@@ -229,13 +224,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;
 }
 /**
@@ -246,45 +241,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>;
 }
 
 /**
@@ -329,6 +318,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+).
@@ -352,12 +359,20 @@ declare class SecurityUtils {
     static fromBase64(base64: string): Uint8Array;
     /** Converts big-endian bytes to bigint. */
     static bytesToBigInt(bytes: Uint8Array): bigint;
-    /** Converts bigint to fixed-length big-endian bytes (pads/truncates). */
+    /** Converts bigint to fixed-length big-endian bytes (pads only; never truncates). */
     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;
 }
 
 /**
@@ -376,26 +391,29 @@ 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.
     * @param A - Client ephemeral public key.
     * @param B - Server ephemeral public key.
     * @param sessionKeyK - Session key K as raw bytes.
-    * @param identity - User identity (login). Should already be normalized (trimmed / lowercased) by the caller.
+    * @param identity - User identity (login). Must be pre-normalized by the caller.
     * @param salt - User-specific salt bytes.
     * @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 };