@crossdyne/security 0.2.0-beta.1 → 0.3.1-beta.1

package/dist/index.d.cts

@@ -1,47 +1,381 @@
+declare const SecurityConstants: {
+    readonly AesGcmNonceSize: 12;
+    readonly AesGcmTagSize: 16;
+    readonly AesGcmTagSizeMin: 12;
+    readonly AesGcmTagSizeMax: 16;
+    readonly KeySizeBytes: 32;
+    readonly Pbkdf2IterationsDefault: 600000;
+    readonly Pbkdf2IterationsMinimum: 100000;
+};
+
+type HashAlgorithm = 'SHA-256' | 'SHA-384' | 'SHA-512';
+
+declare const SupportedHashAlgorithms: ReadonlyArray<HashAlgorithm>;
+
+/**
+ * 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;
+}
+
+/**
+ * AES-GCM encryption/decryption service with JSON serialization.
+ * Encrypted output format (Base64): [Nonce][Ciphertext+Tag].
+ */
 declare class CryptoService {
-    encryptData<T>(dataModel: T, key: Uint8Array): Promise<string>;
-    decryptedData<T>(encryptedBase64: string, key: Uint8Array): Promise<T | null>;
+    /**
+    * 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>;
+    /**
+    * 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>;
+    /**
+    * Generates cryptographically secure random bytes.
+    * @param length - Number of bytes (default 32).
+    * @returns Uint8Array of random bytes.
+    */
     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 {
-    readonly ITERATIONS = 600000;
-    readonly KEY_SIZE = 32;
-    deriveKeysFromPassword(login: string, password: string, salt: Uint8Array): Promise<{
+    /**
+    * 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>;
 }
 
-declare class SecurityUtils {
-    static readonly MODULUS_SIZE: number;
-    static readonly NONCE_SIZE: number;
-    static readonly TAG_SIZE: number;
-    static readonly KEY_SIZE: number;
-    static readonly N: bigint;
-    static readonly g: bigint;
-    static readonly k: bigint;
-    static toBase64(bytes: Uint8Array): string;
-    static fromBase64(base64: string): Uint8Array;
-    static bytesToBigInt: (bytes: Uint8Array) => bigint;
-    static bigIntToFixedBytes(bn: bigint, length: number): Uint8Array;
-    private static fromHex;
-    static expMod(base: bigint, exp: bigint, mod: bigint): bigint;
-    static hashAsPerSrp6a(items: {
-        value: bigint;
-        length: number;
-    }[]): Promise<bigint>;
+/**
+ * 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
 }
 
-declare class SrpService {
+/**
+ * Immutable cryptographic profile bundling version, KDF, and AES-GCM settings.
+ * Thread-safe after construction.
+ */
+declare class CryptoProfile {
+    /** Protocol version, influencing KDF defaults, cipher modes, and serialization. */
+    readonly version: CryptoVersion;
+    /** Key derivation parameters (iterations, hash algorithm). */
+    readonly kdfOptions: KdfOptions;
+    /** AES-GCM encryption parameters (nonce size, tag size, AAD). */
+    readonly aesGcmOptions: AesGcmOptions;
+    /**
+     * Creates a new CryptoProfile.
+     * @param params - Object containing version, kdfOptions, aesGcmOptions.
+     */
+    constructor(params: {
+        version: CryptoVersion;
+        kdfOptions: KdfOptions;
+        aesGcmOptions: AesGcmOptions;
+    });
+}
+
+/**
+ * Registry of predefined {@link CryptoProfile} instances by version.
+ * Returns a fresh profile per call.
+ */
+declare class CryptoProfileRegistry {
+    static getProfile(version: CryptoVersion): CryptoProfile;
+    /** Latest supported profile (currently V1). */
+    static get latest(): CryptoProfile;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * Client-side SRP-6a implementation: proof generation, verifier creation, server M2 verification.
+ */
+declare class SrpClientService {
     private readonly keyDerivation;
-    generateSrpVerifier(authHash: string): Promise<string>;
-    generateSrpProof(login: string, password: string, saltBase64: string, B_base64: string): Promise<{
+    /**
+    * 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.).
+    * @returns Verifier as Base64 string.
+    */
+    generateSrpVerifier(authHash: string, ctx: SrpContext): 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.
+     */
+    generateSrpProof(login: string, password: string, saltBase64: string, B_base64: string, ctx: SrpContext): Promise<{
         A: string;
         M1: string;
         S: string;
     }>;
-    verifyServerM2(A_b64: string, M1_b64: string, S_b64: string, serverM2_b64: string): Promise<boolean>;
+    /**
+     * 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 serverM2_b64 - Server proof M2 (Base64).
+     * @param ctx - SRP context.
+     * @returns True if the server proof is valid.
+     */
+    verifyServerM2(A_b64: string, M1_b64: string, S_b64: string, serverM2_b64: string, ctx: SrpContext): Promise<boolean>;
+}
+
+/**
+ * Server-side SRP session state containing ephemeral keys and verifier.
+ */
+interface SrpSessionState {
+    /** User login identifier. */
+    login: string;
+    /** Server private ephemeral key (Base64). */
+    privateKeyB: string;
+    /** Password verifier (Base64). */
+    verifier: string;
+    /** Server public ephemeral key B (Base64). */
+    publicKeyB: string;
+}
+/**
+ * Server-side SRP-6a: challenge generation, client proof verification, server proof creation.
+ */
+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.
+     */
+    getSrpChallenge(login: string, verifierBytes: Uint8Array, ctx: SrpContext): 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.
+     * @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>;
+}
+
+/**
+ * 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.
+ */
+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
+}
+
+/**
+ * Immutable-style SRP-6a configuration. Parameters aligned with RFC 5054.
+ * Compute `k` via {@link computeK}.
+ */
+declare class SrpOptions {
+    /** Diffie-Hellman group. Default Rfc5054_3072 (g=5). */
+    group: SrpGroup;
+    /** Hash algorithm for SRP computations. Default SHA-256. */
+    hashAlgorithmName: HashAlgorithm;
+    /** Salt size in bytes. Default 32. */
+    saltSize: number;
+    /** Prime modulus N for the selected group. */
+    get N(): bigint;
+    /** Generator g for the selected group (2, 5, or 19). */
+    get g(): bigint;
+    /** Byte length of N (ceil(bitLength / 8)). */
+    get modulusSize(): number;
+    /**
+     * Computes the multiplier parameter k = H(PAD(N) || PAD(g)) (RFC 5054, 2.5.3).
+     * @returns k as a bigint.
+     */
+    computeK(): Promise<bigint>;
+}
+
+/**
+ * Provides prime modulus (N) and generator (g) for SRP groups (RFC 5054).
+ */
+declare class SrpGroupParams {
+    /**
+     * Returns the prime modulus N for the given SRP group.
+     * @param group - SRP group identifier.
+     * @returns N as a bigint.
+     */
+    static getN(group: SrpGroup): bigint;
+    /**
+     * Returns the generator g for the given SRP group.
+     * @param group - SRP group identifier.
+     * @returns g as a bigint (2, 5, or 19).
+     */
+    static getG(group: SrpGroup): bigint;
+}
+
+/**
+ * Factory for creating an {@link SrpContext} from an SRP group.
+ * Automatically selects the hash algorithm (SHA-256 for ≤3072-bit, SHA-384 for 4096+).
+ */
+declare class SrpContextFactory {
+    /**
+     * Creates an SRP context with the specified group.
+     * @param group - SRP group (default Rfc5054_3072).
+     * @returns A ready-to-use SrpContext.
+     */
+    static create(group?: SrpGroup): Promise<SrpContext>;
+}
+
+/**
+ * Cryptographic utility functions: Base64, BigInteger conversion, constant-time comparison, modular exponentiation.
+ */
+declare class SecurityUtils {
+    /** Encodes Uint8Array to standard Base64. */
+    static toBase64(bytes: Uint8Array): string;
+    /** Decodes URL-safe or standard Base64 to Uint8Array. */
+    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). */
+    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;
+}
+
+/**
+ * SRP-specific serialization and hashing utilities.
+ */
+declare class SrpEncoding {
+    /** Serializes a bigint to modulus-sized big-endian bytes. */
+    static toModulusBytes(ctx: SrpContext, value: bigint): Uint8Array;
+    /** Serializes a bigint to hash-sized big-endian bytes. */
+    static toHashBytes(ctx: SrpContext, value: bigint): Uint8Array;
+    /** Hashes modulus-sized values (e.g., u = H(A, B)). */
+    static hashModuli(ctx: SrpContext, ...values: bigint[]): Promise<bigint>;
+    /** Computes M1 = H(A || B || sessionKeyK). */
+    static computeM1(ctx: SrpContext, A: bigint, B: bigint, sessionKeyK: Uint8Array): Promise<bigint>;
+    /** Computes M2 = H(A || M1 || sessionKeyK). */
+    static computeM2(ctx: SrpContext, A: bigint, M1: bigint, sessionKeyK: Uint8Array): Promise<bigint>;
+    /** Computes session key K = H(S). */
+    static computeSessionKey(ctx: SrpContext, S: bigint): Promise<Uint8Array>;
+    /** Concatenates byte arrays and returns the hash as bigint. */
+    private static hash;
 }
 
-export { CryptoService, KeyDerivationService, SecurityUtils, SrpService };
+export { AesGcmOptions, CryptoProfile, CryptoProfileRegistry, CryptoService, CryptoVersion, type HashAlgorithm, KdfOptions, KeyDerivationService, SecurityConstants, SecurityUtils, SrpClientService, type SrpContext, SrpContextFactory, SrpEncoding, SrpGroup, SrpGroupParams, SrpOptions, SrpServerService, type SrpSessionState, SupportedHashAlgorithms };