@basmilius/apple-encryption 0.9.19 → 0.10.0

package/dist/index.d.mts

@@ -1,43 +1,130 @@
 declare namespace chacha20_d_exports {
   export { CHACHA20_AUTH_TAG_LENGTH, CHACHA20_NONCE_LENGTH, DecryptionError, EncryptedData, decrypt, encrypt, padNonce };
 }
+/**
+* Error thrown when ChaCha20-Poly1305 decryption fails due to an
+* authentication tag mismatch, indicating the ciphertext was tampered
+* with or the wrong key/nonce was used.
+*/
 declare class DecryptionError extends Error {
   constructor(message?: string);
 }
+/** Length in bytes of the Poly1305 authentication tag appended to ciphertext. */
 declare const CHACHA20_AUTH_TAG_LENGTH = 16;
+/** Required nonce length in bytes for ChaCha20-Poly1305. Shorter nonces are zero-padded. */
 declare const CHACHA20_NONCE_LENGTH = 12;
+/**
+* Decrypts a ChaCha20-Poly1305 sealed message and verifies its authentication tag.
+*
+* @param key - 256-bit encryption key.
+* @param nonce - Nonce (up to 12 bytes; shorter nonces are left-padded with zeros).
+* @param aad - Additional authenticated data, or null if none.
+* @param ciphertext - The encrypted payload (without the auth tag).
+* @param authTag - The 16-byte Poly1305 authentication tag.
+* @returns The decrypted plaintext.
+* @throws DecryptionError if the authentication tag does not match.
+*/
 declare function decrypt(key: Buffer, nonce: Buffer, aad: Buffer | null, ciphertext: Buffer, authTag: Buffer): Buffer;
+/**
+* Encrypts a plaintext message using ChaCha20-Poly1305 authenticated encryption.
+*
+* @param key - 256-bit encryption key.
+* @param nonce - Nonce (up to 12 bytes; shorter nonces are left-padded with zeros).
+* @param aad - Additional authenticated data, or null if none.
+* @param plaintext - The data to encrypt.
+* @returns The ciphertext and its Poly1305 authentication tag.
+*/
 declare function encrypt(key: Buffer, nonce: Buffer, aad: Buffer | null, plaintext: Buffer): EncryptedData;
+/**
+* Pads a nonce to the required 12-byte length by prepending zero bytes.
+* If the nonce is already 12 bytes or longer, it is returned unchanged.
+*
+* @param nonce - The nonce to pad.
+* @returns A nonce buffer of at least 12 bytes.
+*/
 declare function padNonce(nonce: Buffer): Buffer;
+/**
+* Result of a ChaCha20-Poly1305 encryption operation containing
+* the ciphertext and its authentication tag as separate buffers.
+*/
 type EncryptedData = {
-  readonly ciphertext: Buffer;
+  /** The encrypted payload. */readonly ciphertext: Buffer; /** The 16-byte Poly1305 authentication tag for integrity verification. */
   readonly authTag: Buffer;
 };
 //#endregion
 //#region src/types.d.ts
+/**
+* Represents a cryptographic key pair consisting of a public key and a secret key.
+* Used by both Ed25519 (signing) and Curve25519 (key exchange) operations.
+*/
 type KeyPair = {
-  readonly publicKey: Uint8Array;
+  /** The public key component, safe to share with other parties. */readonly publicKey: Uint8Array; /** The secret (private) key component, must be kept confidential. */
   readonly secretKey: Uint8Array;
 };
 declare namespace curve25519_d_exports {
   export { generateKeyPair$1 as generateKeyPair, generateSharedSecKey };
 }
+/**
+* Generates a new Curve25519 key pair for Diffie-Hellman key exchange.
+*
+* @returns A key pair with a public key and secret key.
+*/
 declare function generateKeyPair$1(): KeyPair;
+/**
+* Computes a shared secret using Curve25519 Diffie-Hellman key exchange.
+* Both parties derive the same shared secret from their own private key
+* and the other party's public key.
+*
+* @param priKey - The local party's private (secret) key.
+* @param pubKey - The remote party's public key.
+* @returns The 32-byte shared secret.
+*/
 declare function generateSharedSecKey(priKey: Uint8Array, pubKey: Uint8Array): Uint8Array;
 declare namespace ed25519_d_exports {
   export { generateKeyPair, sign, verify };
 }
+/**
+* Generates a new Ed25519 key pair for digital signature operations.
+*
+* @returns A key pair with a public key and secret key.
+*/
 declare function generateKeyPair(): KeyPair;
+/**
+* Creates an Ed25519 digital signature for a message.
+*
+* @param message - The data to sign.
+* @param secretKey - The signer's secret (private) key.
+* @returns The 64-byte Ed25519 signature.
+*/
 declare function sign(message: Uint8Array, secretKey: Uint8Array): Uint8Array;
+/**
+* Verifies an Ed25519 digital signature against a message and public key.
+*
+* @param message - The original signed data.
+* @param signature - The 64-byte Ed25519 signature to verify.
+* @param publicKey - The signer's public key.
+* @returns True if the signature is valid, false otherwise.
+*/
 declare function verify(message: Uint8Array, signature: Uint8Array, publicKey: Uint8Array): boolean;
 //#endregion
 //#region src/hkdf.d.ts
+/**
+* Derives a cryptographic key using HKDF (HMAC-based Key Derivation Function)
+* as defined in RFC 5869. Used throughout the protocol stack to derive
+* encryption and authentication keys from shared secrets.
+*
+* @param options - The HKDF parameters including hash algorithm, input key material, salt, info, and desired output length.
+* @returns The derived key material as a Buffer.
+*/
 declare function export_default(options: HKDFOptions): Buffer;
+/**
+* Configuration options for HKDF key derivation.
+*/
 type HKDFOptions = {
-  readonly hash: string;
-  readonly key: Buffer;
-  readonly length: number;
-  readonly salt: Buffer;
+  /** The hash algorithm to use (e.g. 'sha512'). */readonly hash: string; /** The input key material (e.g. a shared secret from Diffie-Hellman). */
+  readonly key: Buffer; /** The desired length of the derived key in bytes. */
+  readonly length: number; /** Optional salt value for the extract step (can be zero-length). */
+  readonly salt: Buffer; /** Context and application-specific info string for the expand step. */
   readonly info: Buffer;
 };
 //#endregion

package/dist/index.mjs

@@ -833,14 +833,32 @@ var chacha20_exports = /* @__PURE__ */ __exportAll({
 	encrypt: () => encrypt,
 	padNonce: () => padNonce
 });
+/**
+* Error thrown when ChaCha20-Poly1305 decryption fails due to an
+* authentication tag mismatch, indicating the ciphertext was tampered
+* with or the wrong key/nonce was used.
+*/
 var DecryptionError = class extends Error {
 	constructor(message = "Decryption failed: authentication tag mismatch") {
 		super(message);
 		this.name = "DecryptionError";
 	}
 };
+/** Length in bytes of the Poly1305 authentication tag appended to ciphertext. */
 const CHACHA20_AUTH_TAG_LENGTH = 16;
+/** Required nonce length in bytes for ChaCha20-Poly1305. Shorter nonces are zero-padded. */
 const CHACHA20_NONCE_LENGTH = 12;
+/**
+* Decrypts a ChaCha20-Poly1305 sealed message and verifies its authentication tag.
+*
+* @param key - 256-bit encryption key.
+* @param nonce - Nonce (up to 12 bytes; shorter nonces are left-padded with zeros).
+* @param aad - Additional authenticated data, or null if none.
+* @param ciphertext - The encrypted payload (without the auth tag).
+* @param authTag - The 16-byte Poly1305 authentication tag.
+* @returns The decrypted plaintext.
+* @throws DecryptionError if the authentication tag does not match.
+*/
 function decrypt(key, nonce, aad, ciphertext, authTag) {
 	nonce = padNonce(nonce);
 	const chacha = new ChaCha20Poly1305(key);
@@ -849,6 +867,15 @@ function decrypt(key, nonce, aad, ciphertext, authTag) {
 	if (!plaintext) throw new DecryptionError();
 	return Buffer.from(plaintext);
 }
+/**
+* Encrypts a plaintext message using ChaCha20-Poly1305 authenticated encryption.
+*
+* @param key - 256-bit encryption key.
+* @param nonce - Nonce (up to 12 bytes; shorter nonces are left-padded with zeros).
+* @param aad - Additional authenticated data, or null if none.
+* @param plaintext - The data to encrypt.
+* @returns The ciphertext and its Poly1305 authentication tag.
+*/
 function encrypt(key, nonce, aad, plaintext) {
 	nonce = padNonce(nonce);
 	const sealed = new ChaCha20Poly1305(key).seal(nonce, plaintext, aad ?? void 0);
@@ -857,6 +884,13 @@ function encrypt(key, nonce, aad, plaintext) {
 		authTag: Buffer.from(sealed.subarray(sealed.length - 16))
 	};
 }
+/**
+* Pads a nonce to the required 12-byte length by prepending zero bytes.
+* If the nonce is already 12 bytes or longer, it is returned unchanged.
+*
+* @param nonce - The nonce to pad.
+* @returns A nonce buffer of at least 12 bytes.
+*/
 function padNonce(nonce) {
 	if (nonce.length >= 12) return nonce;
 	return Buffer.concat([Buffer.alloc(12 - nonce.length, 0), nonce]);
@@ -1474,9 +1508,23 @@ var curve25519_exports = /* @__PURE__ */ __exportAll({
 	generateKeyPair: () => generateKeyPair$2,
 	generateSharedSecKey: () => generateSharedSecKey
 });
+/**
+* Generates a new Curve25519 key pair for Diffie-Hellman key exchange.
+*
+* @returns A key pair with a public key and secret key.
+*/
 function generateKeyPair$2() {
 	return generateKeyPair$3();
 }
+/**
+* Computes a shared secret using Curve25519 Diffie-Hellman key exchange.
+* Both parties derive the same shared secret from their own private key
+* and the other party's public key.
+*
+* @param priKey - The local party's private (secret) key.
+* @param pubKey - The remote party's public key.
+* @returns The 32-byte shared secret.
+*/
 function generateSharedSecKey(priKey, pubKey) {
 	return sharedKey(priKey, pubKey);
 }
@@ -2965,18 +3013,46 @@ var ed25519_exports = /* @__PURE__ */ __exportAll({
 	sign: () => sign,
 	verify: () => verify
 });
+/**
+* Generates a new Ed25519 key pair for digital signature operations.
+*
+* @returns A key pair with a public key and secret key.
+*/
 function generateKeyPair() {
 	return generateKeyPair$1();
 }
+/**
+* Creates an Ed25519 digital signature for a message.
+*
+* @param message - The data to sign.
+* @param secretKey - The signer's secret (private) key.
+* @returns The 64-byte Ed25519 signature.
+*/
 function sign(message, secretKey) {
 	return sign$1(secretKey, message);
 }
+/**
+* Verifies an Ed25519 digital signature against a message and public key.
+*
+* @param message - The original signed data.
+* @param signature - The 64-byte Ed25519 signature to verify.
+* @param publicKey - The signer's public key.
+* @returns True if the signature is valid, false otherwise.
+*/
 function verify(message, signature, publicKey) {
 	return verify$1(publicKey, message, signature);
 }
 
 //#endregion
 //#region src/hkdf.ts
+/**
+* Derives a cryptographic key using HKDF (HMAC-based Key Derivation Function)
+* as defined in RFC 5869. Used throughout the protocol stack to derive
+* encryption and authentication keys from shared secrets.
+*
+* @param options - The HKDF parameters including hash algorithm, input key material, salt, info, and desired output length.
+* @returns The derived key material as a Buffer.
+*/
 function hkdf_default(options) {
 	return Buffer.from(hkdfSync(options.hash, options.key, options.salt, options.info, options.length));
 }

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@basmilius/apple-encryption",
     "description": "Common encryption utilities for Apple Protocols.",
-    "version": "0.9.19",
+    "version": "0.10.0",
     "type": "module",
     "license": "MIT",
     "author": {