@hg-ts/rsa 0.7.26 → 0.8.0

package/src/X25519/x25519.test.ts

@@ -1,4 +1,4 @@
-import { NotImplementedException } from '@hg-ts/exception';
+import Buffer from '@hg-ts/buffer';
 import {
 	Describe,
 	expect,
@@ -9,79 +9,12 @@ import {
 import { z } from '@hg-ts/validation';
 import sodium from 'libsodium-wrappers';
 
-import { InvalidDecryptionKeyExpection } from '../exceptions/index.js';
 import { X25519KeyPair } from './key-pair.js';
 import { X25519PrivateKey } from './private-key.js';
 import { X25519PublicKey } from './public-key.js';
 
 @Describe()
 export class X25519Test extends Suite {
-	@Test()
-	public async encryption(): Promise<void> {
-		const bob = new X25519KeyPair();
-		const alice = new X25519KeyPair();
-		const value = Math.random().toString();
-
-		const encrypted = alice.encrypt(value, bob.publicKeyInstance);
-
-		expect(bob.decrypt(encrypted.toString('base64'), alice.publicKeyInstance)).toBe(value);
-	}
-	@Test()
-	public async duplicateEncryptionDifferences(): Promise<void> {
-		const alice = new X25519KeyPair();
-		const bob = new X25519KeyPair();
-		const value = Math.random().toString();
-
-		const encryptedA = alice.publicKeyInstance.encrypt(value, bob.privateKeyInstance);
-		const encryptedB = alice.publicKeyInstance.encrypt(value, bob.privateKeyInstance);
-
-		expect(encryptedA).not.toMatchObject(encryptedB);
-		expect(alice.decrypt(encryptedA, bob.publicKeyInstance)).toBe(value);
-		expect(alice.decrypt(encryptedB, bob.publicKeyInstance)).toBe(value);
-	}
-
-	@Test()
-	@ExpectException(InvalidDecryptionKeyExpection)
-	public async encryptionFailsForAnotherRecipient(): Promise<void> {
-		const bob = new X25519KeyPair();
-		const alice = new X25519KeyPair();
-		const anotherRecipient = new X25519KeyPair();
-		const value = Math.random().toString();
-
-		const encrypted = alice.encrypt(value, bob.publicKeyInstance);
-
-		anotherRecipient.decrypt(encrypted, alice.publicKeyInstance);
-	}
-
-	@Test()
-	public async encryptionBuffer(): Promise<void> {
-		const bob = new X25519KeyPair();
-		const alice = new X25519KeyPair();
-		const value = Buffer.from(Math.random().toString(), 'utf8');
-
-		const encrypted = alice.encrypt(value, bob.publicKeyInstance);
-
-		expect(Buffer.from(bob.decrypt(encrypted, alice.publicKeyInstance))).toMatchObject(value);
-	}
-
-	@Test()
-	@ExpectException(NotImplementedException)
-	public async signature(): Promise<void> {
-		const x25519 = new X25519KeyPair();
-		const value = Math.random().toString();
-
-		x25519.sign(value);
-	}
-
-	@Test()
-	@ExpectException(NotImplementedException)
-	public async verify(): Promise<void> {
-		const x25519 = new X25519KeyPair();
-		const value = Math.random().toString();
-
-		x25519.verify(Buffer.from(value), value);
-	}
-
 	@Test()
 	public async keyPairFromPrivateKeyString(): Promise<void> {
 		const x25519 = new X25519KeyPair();
@@ -131,6 +64,86 @@ export class X25519Test extends Suite {
 		expect(publicKey.toString()).toBe(x25519.publicKey);
 	}
 
+	@Test()
+	public async deriveSharedSecret(): Promise<void> {
+		const alice = new X25519KeyPair();
+		const bob = new X25519KeyPair();
+
+		const aliceSecret = alice.deriveSharedSecret(bob.publicKeyInstance);
+		const bobSecret = bob.deriveSharedSecret(alice.publicKeyInstance);
+
+		expect(aliceSecret).toMatchObject(bobSecret);
+	}
+
+	@Test()
+	public async deriveSharedSecretDifferentPairs(): Promise<void> {
+		const alice = new X25519KeyPair();
+		const bob = new X25519KeyPair();
+		const anotherBob = new X25519KeyPair();
+
+		const bobSecret = alice.deriveSharedSecret(bob.publicKeyInstance);
+		const anotherBobSecret = alice.deriveSharedSecret(anotherBob.publicKeyInstance);
+
+		expect(bobSecret).not.toMatchObject(anotherBobSecret);
+	}
+
+	@Test()
+	public async deriveSharedSecretFromRestoredKeys(): Promise<void> {
+		const alice = new X25519KeyPair();
+		const bob = new X25519KeyPair();
+		const restoredAlicePrivateKey = X25519PrivateKey.fromString(alice.privateKey);
+		const restoredBobPublicKey = X25519PublicKey.fromString(bob.publicKey);
+
+		const originalSecret = alice.deriveSharedSecret(bob.publicKeyInstance);
+		const restoredSecret = restoredAlicePrivateKey.deriveSharedSecret(restoredBobPublicKey);
+
+		expect(restoredSecret).toMatchObject(originalSecret);
+	}
+
+	@Test()
+	public async signAndVerify(): Promise<void> {
+		const x25519 = new X25519KeyPair();
+		const value = Math.random().toString();
+
+		const signature = x25519.sign(value);
+
+		expect(x25519.verify(signature, value)).toBeTruthy();
+		expect(x25519.publicKeyInstance.verify(signature.toString('base64'), value)).toBeTruthy();
+	}
+
+	@Test()
+	public async signAndVerifyFromRestoredKeys(): Promise<void> {
+		const x25519 = new X25519KeyPair();
+		const privateKey = X25519PrivateKey.fromString(x25519.privateKey);
+		const publicKey = X25519PublicKey.fromString(x25519.publicKey);
+		const value = Math.random().toString();
+
+		const signature = privateKey.sign(value);
+
+		expect(publicKey.verify(signature, value)).toBeTruthy();
+	}
+
+	@Test()
+	public async verifyFailsForAnotherMessage(): Promise<void> {
+		const x25519 = new X25519KeyPair();
+		const value = Math.random().toString();
+
+		const signature = x25519.sign(value);
+
+		expect(x25519.verify(signature, `${value}-another`)).toBeFalsy();
+	}
+
+	@Test()
+	public async verifyFailsForAnotherPublicKey(): Promise<void> {
+		const x25519 = new X25519KeyPair();
+		const anotherX25519 = new X25519KeyPair();
+		const value = Math.random().toString();
+
+		const signature = x25519.sign(value);
+
+		expect(anotherX25519.verify(signature, value)).toBeFalsy();
+	}
+
 	@Test()
 	public async publicKeyValidationValid(): Promise<void> {
 		const x25519 = new X25519KeyPair();

package/src/aead/index.ts

@@ -0,0 +1 @@
+export * from './xchacha20-poly1305.js';

package/src/aead/xchacha20-poly1305.test.ts

@@ -0,0 +1,147 @@
+import Buffer from '@hg-ts/buffer';
+import {
+	Describe,
+	expect,
+	ExpectException,
+	Suite,
+	Test,
+} from '@hg-ts/tests';
+import sodium from 'libsodium-wrappers';
+
+import {
+	InvalidDecryptionKeyExpection,
+	InvalidEncryptionKeyException,
+} from '../exceptions/index.js';
+import { X25519KeyPair } from '../X25519/index.js';
+import { XChaCha20Poly1305Aead } from './xchacha20-poly1305.js';
+
+@Describe()
+export class XChaCha20Poly1305AeadTest extends Suite {
+	@Test()
+	public async encryption(): Promise<void> {
+		const { aliceKey, bobKey } = this.deriveAliceBobKeys();
+		const value = Math.random().toString();
+		const aead = new XChaCha20Poly1305Aead();
+
+		const encrypted = aead.encrypt(value, aliceKey);
+		const decrypted = aead.decrypt(encrypted.toString('base64'), bobKey);
+
+		expect(decrypted.toString('utf8')).toBe(value);
+	}
+
+	@Test()
+	public async encryptionBuffer(): Promise<void> {
+		const { aliceKey, bobKey } = this.deriveAliceBobKeys();
+		const value = Buffer.from(Math.random().toString(), 'utf8');
+		const aead = new XChaCha20Poly1305Aead();
+
+		const encrypted = aead.encrypt(value, aliceKey);
+		const decrypted = aead.decrypt(encrypted, bobKey);
+
+		expect(decrypted).toMatchObject(value);
+	}
+
+	@Test()
+	public async duplicateEncryptionDifferences(): Promise<void> {
+		const { aliceKey, bobKey } = this.deriveAliceBobKeys();
+		const value = Math.random().toString();
+		const aead = new XChaCha20Poly1305Aead();
+
+		const encryptedA = aead.encrypt(value, aliceKey);
+		const encryptedB = aead.encrypt(value, aliceKey);
+
+		expect(encryptedA).not.toMatchObject(encryptedB);
+		expect(aead.decrypt(encryptedA, bobKey).toString('utf8')).toBe(value);
+		expect(aead.decrypt(encryptedB, bobKey).toString('utf8')).toBe(value);
+	}
+
+	@Test()
+	public async associatedData(): Promise<void> {
+		const { aliceKey, bobKey } = this.deriveAliceBobKeys();
+		const value = Math.random().toString();
+		const associatedData = Buffer.from('message-header', 'utf8');
+		const aead = new XChaCha20Poly1305Aead();
+
+		const encrypted = aead.encrypt(value, aliceKey, associatedData);
+		const decrypted = aead.decrypt(encrypted, bobKey, associatedData);
+
+		expect(decrypted.toString('utf8')).toBe(value);
+	}
+
+	@Test()
+	@ExpectException(InvalidDecryptionKeyExpection)
+	public async decryptFailsForAnotherAssociatedData(): Promise<void> {
+		const { aliceKey, bobKey } = this.deriveAliceBobKeys();
+		const aead = new XChaCha20Poly1305Aead();
+
+		const encrypted = aead.encrypt(Math.random().toString(), aliceKey, 'message-header');
+
+		aead.decrypt(encrypted, bobKey, 'another-message-header');
+	}
+
+	@Test()
+	@ExpectException(InvalidDecryptionKeyExpection)
+	public async decryptFailsForAnotherKey(): Promise<void> {
+		const { aliceKey } = this.deriveAliceBobKeys();
+		const anotherKey = new X25519KeyPair().privateKeyInstance.nativeKey;
+		const aead = new XChaCha20Poly1305Aead();
+
+		const encrypted = aead.encrypt(Math.random().toString(), aliceKey);
+
+		aead.decrypt(encrypted, anotherKey);
+	}
+
+	@Test()
+	@ExpectException(InvalidEncryptionKeyException)
+	public async encryptionFailsForInvalidKeyLength(): Promise<void> {
+		const aead = new XChaCha20Poly1305Aead();
+
+		aead.encrypt(Math.random().toString(), Buffer.from('invalid-key', 'utf8'));
+	}
+
+	@Test()
+	public async deriveKeyDependsOnPublicKeyOrder(): Promise<void> {
+		const alice = new X25519KeyPair();
+		const bob = new X25519KeyPair();
+		const sharedSecret = alice.deriveSharedSecret(bob.publicKeyInstance);
+		const aead = new XChaCha20Poly1305Aead();
+
+		const keyA = aead.deriveKey(
+			sharedSecret,
+			alice.publicKeyInstance.nativeKey,
+			bob.publicKeyInstance.nativeKey,
+		);
+		const keyB = aead.deriveKey(
+			sharedSecret,
+			bob.publicKeyInstance.nativeKey,
+			alice.publicKeyInstance.nativeKey,
+		);
+
+		expect(keyA).not.toMatchObject(keyB);
+	}
+
+	public override async setUp(): Promise<void> {
+		await sodium.ready;
+	}
+
+	private deriveAliceBobKeys(): { aliceKey: Buffer; bobKey: Buffer } {
+		const alice = new X25519KeyPair();
+		const bob = new X25519KeyPair();
+		const aliceSecret = alice.deriveSharedSecret(bob.publicKeyInstance);
+		const bobSecret = bob.deriveSharedSecret(alice.publicKeyInstance);
+		const aead = new XChaCha20Poly1305Aead();
+
+		return {
+			aliceKey: aead.deriveKey(
+				aliceSecret,
+				alice.publicKeyInstance.nativeKey,
+				bob.publicKeyInstance.nativeKey,
+			),
+			bobKey: aead.deriveKey(
+				bobSecret,
+				alice.publicKeyInstance.nativeKey,
+				bob.publicKeyInstance.nativeKey,
+			),
+		};
+	}
+}

package/src/aead/xchacha20-poly1305.ts

@@ -0,0 +1,80 @@
+import Buffer from '@hg-ts/buffer';
+import sodium from 'libsodium-wrappers';
+
+import {
+	InvalidDecryptionKeyExpection,
+	InvalidEncryptionKeyException,
+} from '../exceptions/index.js';
+import { deriveKey } from '../utils/index.js';
+
+const ALGORITHM = Buffer.from('X25519-XChaCha20-Poly1305', 'utf8');
+
+sodium.ready.catch(() => {});
+
+export class XChaCha20Poly1305Aead {
+	public deriveKey(...values: Buffer[]): Buffer {
+		return deriveKey(
+			sodium.crypto_aead_xchacha20poly1305_ietf_KEYBYTES,
+			ALGORITHM,
+			...values,
+		);
+	}
+
+	public encrypt(value: string | Buffer, key: Buffer, associatedData?: string | Buffer): Buffer {
+		this.validateKey(key);
+		const nonce = Buffer.from(
+			sodium.randombytes_buf(sodium.crypto_aead_xchacha20poly1305_ietf_NPUBBYTES),
+		);
+		const ciphertext = Buffer.from(sodium.crypto_aead_xchacha20poly1305_ietf_encrypt(
+			this.toBuffer(value),
+			this.toOptionalBuffer(associatedData),
+			null,
+			nonce,
+			key,
+		));
+
+		return Buffer.concat([nonce, ciphertext]);
+	}
+
+	public decrypt(value: string | Buffer, key: Buffer, associatedData?: string | Buffer): Buffer {
+		this.validateKey(key);
+		const encrypted = typeof value === 'string'
+			? Buffer.from(value, 'base64')
+			: value;
+
+		try {
+			const nonce = encrypted.subarray(0, sodium.crypto_aead_xchacha20poly1305_ietf_NPUBBYTES);
+			const ciphertext = encrypted.subarray(sodium.crypto_aead_xchacha20poly1305_ietf_NPUBBYTES);
+
+			return Buffer.from(sodium.crypto_aead_xchacha20poly1305_ietf_decrypt(
+				null,
+				ciphertext,
+				this.toOptionalBuffer(associatedData),
+				nonce,
+				key,
+			));
+		} catch {
+			throw new InvalidDecryptionKeyExpection();
+		}
+	}
+
+	private validateKey(key: Buffer): void {
+		if (key.length !== sodium.crypto_aead_xchacha20poly1305_ietf_KEYBYTES) {
+			throw new InvalidEncryptionKeyException();
+		}
+	}
+
+	private toBuffer(value: string | Buffer): Buffer {
+		return typeof value === 'string'
+			? Buffer.from(value, 'utf8')
+			: value;
+	}
+
+	private toOptionalBuffer(value?: string | Buffer): Buffer | null {
+		if (!value) {
+			return null;
+		}
+
+		return this.toBuffer(value);
+	}
+}

package/src/base/index.ts

@@ -1,3 +1,4 @@
+export * from './key-capabilities.js';
 export * from './key.js';
 export * from './private-key.js';
 export * from './public-key.js';

package/src/base/key-capabilities.ts

@@ -0,0 +1,54 @@
+export type SerializableKey<TKey = unknown> = {
+	readonly nativeKey: TKey;
+
+	toString(): string;
+};
+
+export type PublicKey<TKey = unknown> = SerializableKey<TKey>;
+
+export type PrivateKey<
+	TNativeKey = unknown,
+	TPublicKey extends PublicKey = PublicKey,
+> = SerializableKey<TNativeKey> & {
+	toPublicKey(): TPublicKey;
+};
+
+export type EncryptingPublicKey = {
+	encrypt(value: string | Buffer): Buffer;
+};
+
+export type DecryptingPrivateKey = {
+	decrypt(value: string | Buffer): string;
+};
+
+export type SigningPrivateKey = {
+	sign(value: string): Buffer;
+};
+
+export type VerifyingPublicKey = {
+	verify(signature: string | Buffer, value: string): boolean;
+};
+
+export type KemEncapsulation = {
+	cipherText: Buffer;
+	sharedSecret: Buffer;
+};
+
+export type EncapsulatingPublicKey = {
+	encapsulate(message?: string | Buffer): KemEncapsulation;
+};
+
+export type DecapsulatingPrivateKey = {
+	decapsulate(cipherText: string | Buffer): Buffer;
+};
+
+export type KeyAgreementPublicKey<TKey = unknown> = PublicKey<TKey>;
+
+export type KeyAgreementPrivateKey<
+	TPublicKey extends KeyAgreementPublicKey,
+	TNativeKey = unknown,
+> = PrivateKey<TNativeKey, TPublicKey> & KeyAgreement<TPublicKey>;
+
+export type KeyAgreement<TPublicKey extends KeyAgreementPublicKey> = {
+	deriveSharedSecret(peerPublicKey: TPublicKey): Buffer;
+};

package/src/base/key-pair.ts

@@ -4,12 +4,15 @@ import {
 } from './private-key.js';
 import { BasePublicKey } from './public-key.js';
 
-export type NewKeyPairOptions = {
+export type NewKeyPairOptions<TBits extends number = number> = {
 	seed?: string;
-	bits?: number;
+	bits?: TBits;
 };
 
-export type KeyPairOptions<TPrivateKey extends BasePrivateKey> = NewKeyPairOptions & {
+export type KeyPairOptions<
+	TPrivateKey extends BasePrivateKey,
+	TBits extends number = number
+> = NewKeyPairOptions<TBits> & {
 	privateKey?: TPrivateKey | string;
 };
 
@@ -36,14 +39,6 @@ export abstract class BaseKeyPair<
 		this.publicKeyInstance = keyPair.publicKey;
 	}
 
-	public abstract encrypt(value: string | Buffer, ...additionalArguments: unknown[]): Buffer;
-
-	public abstract decrypt(value: string | Buffer, ...additionalArguments: unknown[]): string;
-
-	public abstract sign(value: string): Buffer;
-
-	public abstract verify(signature: string | Buffer, value: string): boolean;
-
 	public get publicKey(): string {
 		return this.publicKeyInstance.toString();
 	}

package/src/base/key.ts

@@ -1,4 +1,6 @@
-export abstract class BaseKey<TKey = unknown> {
+import { SerializableKey } from './key-capabilities.js';
+
+export abstract class BaseKey<TKey = unknown> implements SerializableKey<TKey> {
 	protected readonly key: TKey;
 
 	public constructor(key: TKey) {

package/src/base/private-key.ts

@@ -1,4 +1,5 @@
 import { BaseKey } from './key.js';
+import { PrivateKey } from './key-capabilities.js';
 import { BasePublicKey } from './public-key.js';
 
 export type StaticPrivateKey<T extends BasePrivateKey> = Class<T, any[]> & {
@@ -8,10 +9,6 @@ export type StaticPrivateKey<T extends BasePrivateKey> = Class<T, any[]> & {
 export abstract class BasePrivateKey<
 	TNativeKey = unknown,
 	TPublicKey extends BasePublicKey = BasePublicKey,
-> extends BaseKey<TNativeKey> {
-	public abstract decrypt(encrypted: string | Buffer, ...additionalArguments: unknown[]): string;
-
-	public abstract sign(value: string): Buffer;
-
+> extends BaseKey<TNativeKey> implements PrivateKey<TNativeKey, TPublicKey> {
 	public abstract toPublicKey(): TPublicKey;
 }

package/src/base/public-key.ts

@@ -1,7 +1,6 @@
 import { BaseKey } from './key.js';
+import { PublicKey } from './key-capabilities.js';
 
-export abstract class BasePublicKey<TNativeKey = unknown> extends BaseKey<TNativeKey> {
-	public abstract encrypt(value: string | Buffer, ...additionalArguments: unknown[]): Buffer;
-
-	public abstract verify(signature: string | Buffer, value: string): boolean;
-}
+export abstract class BasePublicKey<TNativeKey = unknown>
+	extends BaseKey<TNativeKey>
+	implements PublicKey<TNativeKey> {}

package/src/exceptions/hkdf-output-length.exception.ts

@@ -0,0 +1,7 @@
+import { BaseException } from '@hg-ts/exception';
+
+export class HkdfOutputLengthException extends BaseException {
+	public constructor(maxLength: number) {
+		super(`HKDF output length must not exceed ${maxLength} bytes`);
+	}
+}

package/src/exceptions/index.ts

@@ -1 +1,5 @@
+export * from './hkdf-output-length.exception.js';
 export * from './invalid-decryption-key.expection.js';
+export * from './invalid-encryption-key.exception.js';
+export * from './invalid-pq-kem-key-length.exception.js';
+export * from './invalid-pq-kem-message-length.exception.js';

package/src/exceptions/invalid-encryption-key.exception.ts

@@ -0,0 +1,7 @@
+import { BaseException } from '@hg-ts/exception';
+
+export class InvalidEncryptionKeyException extends BaseException {
+	public constructor() {
+		super('Invalid encryption key');
+	}
+}

package/src/exceptions/invalid-pq-kem-key-length.exception.ts

@@ -0,0 +1,7 @@
+import { BaseException } from '@hg-ts/exception';
+
+export class InvalidPqKemKeyLengthException extends BaseException {
+	public constructor(keyType: 'publicKey' | 'secretKey', length: number) {
+		super(`Invalid PQKEM ${keyType} length: ${length}`);
+	}
+}

package/src/exceptions/invalid-pq-kem-message-length.exception.ts

@@ -0,0 +1,7 @@
+import { BaseException } from '@hg-ts/exception';
+
+export class InvalidPqKemMessageLengthException extends BaseException {
+	public constructor(expectedLength: number, actualLength: number) {
+		super(`PQKEM encapsulation message must be ${expectedLength} bytes, got ${actualLength}`);
+	}
+}

package/src/index.ts

@@ -1,4 +1,7 @@
 export * from './base/index.js';
+export * from './aead/index.js';
 export * from './exceptions/index.js';
+export * from './pq-kem/index.js';
 export * from './rsa/index.js';
 export * from './X25519/index.js';
+export * from './utils/index.js';

package/src/pq-kem/algorithm.ts

@@ -0,0 +1,51 @@
+import {
+	ml_kem1024 as mlKem1024,
+	ml_kem512 as mlKem512,
+	ml_kem768 as mlKem768,
+} from '@noble/post-quantum/ml-kem.js';
+import type { KEM } from '@noble/post-quantum/utils.js';
+
+import { InvalidPqKemKeyLengthException } from '../exceptions/index.js';
+
+export type PqKemAlgorithm = 512 | 768 | 1024;
+
+export const DEFAULT_PQ_KEM_ALGORITHM: PqKemAlgorithm = 768;
+
+export const PQ_KEM_ALGORITHMS = [
+	512,
+	768,
+	1024,
+] as const satisfies readonly PqKemAlgorithm[];
+
+export type PqKemImplementation = KEM & {
+	lengths: {
+		cipherText: number;
+		msg: number;
+		publicKey: number;
+		secretKey: number;
+		seed: number;
+	};
+};
+
+const IMPLEMENTATIONS: Record<PqKemAlgorithm, PqKemImplementation> = {
+	512: mlKem512 as PqKemImplementation,
+	768: mlKem768 as PqKemImplementation,
+	1024: mlKem1024 as PqKemImplementation,
+};
+
+export function getPqKemImplementation(bits: PqKemAlgorithm): PqKemImplementation {
+	return IMPLEMENTATIONS[bits];
+}
+
+export function inferPqKemBitsByKeyLength(
+	length: number,
+	keyType: 'publicKey' | 'secretKey',
+): PqKemAlgorithm {
+	for (const [bits, candidate] of Object.entries(IMPLEMENTATIONS)) {
+		if (candidate.lengths[keyType] === length) {
+			return Number(bits) as PqKemAlgorithm;
+		}
+	}
+
+	throw new InvalidPqKemKeyLengthException(keyType, length);
+}

package/src/pq-kem/index.ts

@@ -0,0 +1,4 @@
+export * from './algorithm.js';
+export * from './private-key.js';
+export * from './public-key.js';
+export * from './key-pair.js';