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

package/dist/index.d.cts

@@ -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
 }
 
 /**
@@ -54,7 +34,7 @@ declare class CryptoService {
     * @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.
@@ -63,7 +43,7 @@ declare class CryptoService {
     * @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,49 +52,28 @@ declare class CryptoService {
     generateRandomBytes: (length?: number) => Uint8Array;
 }
 
-/**
- * PBKDF2 key derivation options: iterations count and hash algorithm.
- * Mutable builder-style; call {@link build} to validate.
- */
-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);
-    /** 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;
-}
-
 /**
  * Two-stage key derivation: PBKDF2 (master key) → HKDF (sub-keys).
  */
 declare class KeyDerivationService {
     /**
-    * Derives KEK and Base64 AuthHash. Identity is normalized (trimmed, lowercase).
+    * 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).
     */
-    deriveKeysFromPassword(identity: string, password: string, salt: Uint8Array, options?: KdfOptions): Promise<{
+    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.
@@ -122,17 +81,62 @@ declare class KeyDerivationService {
     * @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>;
+    deriveAuthHashForSrp(identity: string, password: string, salt: Uint8Array, srpHashAlgorithm: HashAlgorithm, version: CryptoVersion): 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.
+ * AES-GCM encryption options: nonce size, tag size, and optional AAD.
+ * Mutable builder-style; call {@link build} to validate.
  */
-declare enum CryptoVersion {
-    /** Version 1 — initial profile. */
-    V1 = 1
+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.
+ */
+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);
+    /** 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;
 }
 
 /**
@@ -201,12 +205,12 @@ declare class SrpClientService {
      * 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 saltBase64 - Server salt (standard Base64).
+     * @param B_base64 - Server public ephemeral B (standard Base64).
      * @param ctx - SRP context.
-     * @returns Object with A, M1, S as Base64 strings.
+     * @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, password: string, saltBase64: string, B_base64: string, ctx: SrpContext, version: CryptoVersion): Promise<{
         A: string;
         M1: string;
         SessionKeyK: Uint8Array;
@@ -352,12 +356,13 @@ 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;
+    static bigIntToRawBytes(bn: bigint): Uint8Array;
 }
 
 /**
@@ -383,7 +388,7 @@ declare class SrpEncoding {
     * @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.
     */

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
 }
 
 /**
@@ -54,7 +34,7 @@ declare class CryptoService {
     * @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.
@@ -63,7 +43,7 @@ declare class CryptoService {
     * @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,49 +52,28 @@ declare class CryptoService {
     generateRandomBytes: (length?: number) => Uint8Array;
 }
 
-/**
- * PBKDF2 key derivation options: iterations count and hash algorithm.
- * Mutable builder-style; call {@link build} to validate.
- */
-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);
-    /** 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;
-}
-
 /**
  * Two-stage key derivation: PBKDF2 (master key) → HKDF (sub-keys).
  */
 declare class KeyDerivationService {
     /**
-    * Derives KEK and Base64 AuthHash. Identity is normalized (trimmed, lowercase).
+    * 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).
     */
-    deriveKeysFromPassword(identity: string, password: string, salt: Uint8Array, options?: KdfOptions): Promise<{
+    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.
@@ -122,17 +81,62 @@ declare class KeyDerivationService {
     * @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>;
+    deriveAuthHashForSrp(identity: string, password: string, salt: Uint8Array, srpHashAlgorithm: HashAlgorithm, version: CryptoVersion): 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.
+ * AES-GCM encryption options: nonce size, tag size, and optional AAD.
+ * Mutable builder-style; call {@link build} to validate.
  */
-declare enum CryptoVersion {
-    /** Version 1 — initial profile. */
-    V1 = 1
+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.
+ */
+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);
+    /** 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;
 }
 
 /**
@@ -201,12 +205,12 @@ declare class SrpClientService {
      * 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 saltBase64 - Server salt (standard Base64).
+     * @param B_base64 - Server public ephemeral B (standard Base64).
      * @param ctx - SRP context.
-     * @returns Object with A, M1, S as Base64 strings.
+     * @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, password: string, saltBase64: string, B_base64: string, ctx: SrpContext, version: CryptoVersion): Promise<{
         A: string;
         M1: string;
         SessionKeyK: Uint8Array;
@@ -352,12 +356,13 @@ 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;
+    static bigIntToRawBytes(bn: bigint): Uint8Array;
 }
 
 /**
@@ -383,7 +388,7 @@ declare class SrpEncoding {
     * @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.
     */