@crossdyne/security 0.5.0-beta.2 → 2.0.0

package/dist/index.d.cts

@@ -1,17 +1,26 @@
 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;
 };
 
 declare const SupportedHashAlgorithms: ReadonlyArray<HashAlgorithm>;
 
+type SupportedAlgorithm = 'AES-GCM';
+
 /**
  * Supported cryptographic profile versions.
  * V1: baseline (PBKDF2-HMAC-SHA256, AES-256-GCM, 12-byte nonce, 16-byte tag).
@@ -30,24 +39,37 @@ 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 key - A non-extractable CryptoKey obtained via {@link CryptoService.importKey}.
     * @returns Base64-encoded ciphertext with prepended nonce.
     */
-    encryptData<T>(dataModel: T, key: Uint8Array, version?: CryptoVersion): Promise<string>;
+    encryptData<T>(dataModel: T, key: CryptoKey, 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 key - A non-extractable CryptoKey obtained via {@link CryptoService.importKey}.
     * @returns Deserialized object, or null if input is empty.
     * @throws If authentication tag mismatch or corrupted data.
     */
-    decryptData<T>(encryptedBase64: string, key: Uint8Array, isBytes?: boolean): Promise<T | null>;
+    decryptData<T>(encryptedBase64: string, key: CryptoKey, 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;
+    /**
+     * Imports raw key bytes into a non-extractable CryptoKey based on the crypto profile version.
+     *
+     * The resulting key cannot be exported back to raw bytes (extractable: false),
+     * ensuring that sensitive key material does not persist in JavaScript-accessible memory.
+     * Callers should securely wipe the original raw key buffer immediately after import.
+     *
+     * @param rawKey - Raw key bytes (e.g. a Data Encryption Key).
+     * @param version - Crypto profile version that determines the algorithm and parameters.
+     * @param usages - Allowed key operations (e.g. ['encrypt', 'decrypt']).
+     * @returns A non-extractable CryptoKey bound to the algorithm defined by the profile.
+     */
+    importKey(rawKey: Uint8Array, version: CryptoVersion, usages: KeyUsage[]): Promise<CryptoKey>;
 }
 
 /**
@@ -70,58 +92,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;
 }
 
 /**
@@ -131,6 +142,7 @@ declare class KdfOptions {
 declare class CryptoProfile {
     /** Protocol version, influencing KDF defaults, cipher modes, and serialization. */
     readonly version: CryptoVersion;
+    readonly algorithmName: SupportedAlgorithm;
     /** Key derivation parameters (iterations, hash algorithm). */
     readonly kdfOptions: KdfOptions;
     /** AES-GCM encryption parameters (nonce size, tag size, AAD). */
@@ -141,6 +153,7 @@ declare class CryptoProfile {
      */
     constructor(params: {
         version: CryptoVersion;
+        algorithmName: SupportedAlgorithm;
         kdfOptions: KdfOptions;
         aesGcmOptions: AesGcmOptions;
     });
@@ -151,9 +164,8 @@ declare class CryptoProfile {
  * Returns a fresh profile per call.
  */
 declare class CryptoProfileRegistry {
+    private static readonly V1_PROFILE;
     static getProfile(version: CryptoVersion): CryptoProfile;
-    /** Latest supported profile (currently V1). */
-    static get latest(): CryptoProfile;
 }
 
 /**
@@ -416,4 +428,4 @@ declare class SrpEncoding {
     private static hash;
 }
 
-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 };
+export { AesGcmOptions, CryptoProfile, CryptoProfileRegistry, CryptoService, CryptoVersion, type HashAlgorithm, KdfOptions, KeyDerivationService, SecurityConstants, SecurityUtils, SrpClientService, type SrpContext, SrpContextFactory, SrpEncoding, SrpGroup, SrpGroupParams, SrpKeyDerivationService, SrpOptions, SrpServerService, type SrpSessionState, type SupportedAlgorithm, SupportedHashAlgorithms };

package/dist/index.d.ts

@@ -1,17 +1,26 @@
 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;
 };
 
 declare const SupportedHashAlgorithms: ReadonlyArray<HashAlgorithm>;
 
+type SupportedAlgorithm = 'AES-GCM';
+
 /**
  * Supported cryptographic profile versions.
  * V1: baseline (PBKDF2-HMAC-SHA256, AES-256-GCM, 12-byte nonce, 16-byte tag).
@@ -30,24 +39,37 @@ 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 key - A non-extractable CryptoKey obtained via {@link CryptoService.importKey}.
     * @returns Base64-encoded ciphertext with prepended nonce.
     */
-    encryptData<T>(dataModel: T, key: Uint8Array, version?: CryptoVersion): Promise<string>;
+    encryptData<T>(dataModel: T, key: CryptoKey, 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 key - A non-extractable CryptoKey obtained via {@link CryptoService.importKey}.
     * @returns Deserialized object, or null if input is empty.
     * @throws If authentication tag mismatch or corrupted data.
     */
-    decryptData<T>(encryptedBase64: string, key: Uint8Array, isBytes?: boolean): Promise<T | null>;
+    decryptData<T>(encryptedBase64: string, key: CryptoKey, 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;
+    /**
+     * Imports raw key bytes into a non-extractable CryptoKey based on the crypto profile version.
+     *
+     * The resulting key cannot be exported back to raw bytes (extractable: false),
+     * ensuring that sensitive key material does not persist in JavaScript-accessible memory.
+     * Callers should securely wipe the original raw key buffer immediately after import.
+     *
+     * @param rawKey - Raw key bytes (e.g. a Data Encryption Key).
+     * @param version - Crypto profile version that determines the algorithm and parameters.
+     * @param usages - Allowed key operations (e.g. ['encrypt', 'decrypt']).
+     * @returns A non-extractable CryptoKey bound to the algorithm defined by the profile.
+     */
+    importKey(rawKey: Uint8Array, version: CryptoVersion, usages: KeyUsage[]): Promise<CryptoKey>;
 }
 
 /**
@@ -70,58 +92,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;
 }
 
 /**
@@ -131,6 +142,7 @@ declare class KdfOptions {
 declare class CryptoProfile {
     /** Protocol version, influencing KDF defaults, cipher modes, and serialization. */
     readonly version: CryptoVersion;
+    readonly algorithmName: SupportedAlgorithm;
     /** Key derivation parameters (iterations, hash algorithm). */
     readonly kdfOptions: KdfOptions;
     /** AES-GCM encryption parameters (nonce size, tag size, AAD). */
@@ -141,6 +153,7 @@ declare class CryptoProfile {
      */
     constructor(params: {
         version: CryptoVersion;
+        algorithmName: SupportedAlgorithm;
         kdfOptions: KdfOptions;
         aesGcmOptions: AesGcmOptions;
     });
@@ -151,9 +164,8 @@ declare class CryptoProfile {
  * Returns a fresh profile per call.
  */
 declare class CryptoProfileRegistry {
+    private static readonly V1_PROFILE;
     static getProfile(version: CryptoVersion): CryptoProfile;
-    /** Latest supported profile (currently V1). */
-    static get latest(): CryptoProfile;
 }
 
 /**
@@ -416,4 +428,4 @@ declare class SrpEncoding {
     private static hash;
 }
 
-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 };
+export { AesGcmOptions, CryptoProfile, CryptoProfileRegistry, CryptoService, CryptoVersion, type HashAlgorithm, KdfOptions, KeyDerivationService, SecurityConstants, SecurityUtils, SrpClientService, type SrpContext, SrpContextFactory, SrpEncoding, SrpGroup, SrpGroupParams, SrpKeyDerivationService, SrpOptions, SrpServerService, type SrpSessionState, type SupportedAlgorithm, SupportedHashAlgorithms };