@tstdl/base 0.93.178 → 0.93.180

package/{utils → cryptography}/jwt.d.ts

@@ -1,6 +1,5 @@
 import type { OneOrMany, Record } from '../types/index.js';
-import type { Key } from './cryptography.js';
-export type JwtTokenAlgorithm = 'HS256' | 'HS384' | 'HS512';
+export type JwtTokenAlgorithm = 'HS256' | 'HS384' | 'HS512' | 'KMAC128' | 'KMAC256';
 export type JwtTokenHeader<T extends Record<string> = Record<string>> = {
     alg: JwtTokenAlgorithm;
     typ: 'JWT';
@@ -27,6 +26,25 @@ export type JwtTokenParseResult<T extends JwtToken = JwtToken> = {
         payload: string;
     };
 };
+/**
+ * Parses a JWT token string into its components. This function does not perform any validation of the token's signature.
+ * @param tokenString JWT token string.
+ * @returns Parsed JWT token result.
+ */
 export declare function parseJwtTokenString<T extends JwtToken = JwtToken>(tokenString: string): JwtTokenParseResult<T>;
-export declare function createJwtTokenString(jwtToken: JwtToken, key: Key | string): Promise<string>;
-export declare function parseAndValidateJwtTokenString<T extends JwtToken = JwtToken>(tokenString: string, allowedAlgorithms: OneOrMany<JwtTokenAlgorithm>, key: Key | string): Promise<T>;
+/**
+ * Creates a JWT token string.
+ * @param jwtToken The JWT token object.
+ * @param key The CryptoKey to sign the token with.
+ * @returns Signed JWT token string.
+ */
+export declare function createJwtTokenString(jwtToken: JwtToken, key: CryptoKey): Promise<string>;
+/**
+ * Parses and validates a JWT token string.
+ * @param tokenString The JWT token string.
+ * @param allowedAlgorithms One or more allowed algorithms.
+ * @param key The CryptoKey to verify the signature with.
+ * @returns The parsed token object if valid.
+ * @throws {InvalidTokenError} If the token is invalid or the signature fails verification.
+ */
+export declare function parseAndValidateJwtTokenString<T extends JwtToken = JwtToken>(tokenString: string, allowedAlgorithms: OneOrMany<JwtTokenAlgorithm>, key: CryptoKey): Promise<T>;

package/{utils → cryptography}/jwt.js

@@ -1,9 +1,20 @@
 import { InvalidTokenError } from '../errors/invalid-token.error.js';
-import { toArray } from './array/array.js';
-import { decodeBase64Url, encodeBase64Url } from './base64.js';
-import { importHmacKey, sign } from './cryptography.js';
-import { encodeUtf8 } from './encoding.js';
-import { timingSafeBinaryEquals } from './equals.js';
+import { toArray } from '../utils/array/array.js';
+import { decodeBase64Url, encodeBase64Url } from '../utils/base64.js';
+import { encodeUtf8 } from '../utils/encoding.js';
+import { sign, verify } from './cryptography.js';
+const jwtAlgorithmMap = {
+    HS256: { name: 'HMAC', hash: 'SHA-256' },
+    HS384: { name: 'HMAC', hash: 'SHA-384' },
+    HS512: { name: 'HMAC', hash: 'SHA-512' },
+    KMAC128: { name: 'KMAC128', outputLength: 32 },
+    KMAC256: { name: 'KMAC256', outputLength: 64 },
+};
+/**
+ * Parses a JWT token string into its components. This function does not perform any validation of the token's signature.
+ * @param tokenString JWT token string.
+ * @returns Parsed JWT token result.
+ */
 export function parseJwtTokenString(tokenString) {
     const splits = tokenString.split('.');
     if (splits.length != 3) {
@@ -45,6 +56,12 @@ export function parseJwtTokenString(tokenString) {
         throw new InvalidTokenError('Invalid token format');
     }
 }
+/**
+ * Creates a JWT token string.
+ * @param jwtToken The JWT token object.
+ * @param key The CryptoKey to sign the token with.
+ * @returns Signed JWT token string.
+ */
 export async function createJwtTokenString(jwtToken, key) {
     const headerBuffer = encodeUtf8(JSON.stringify(jwtToken.header));
     const payloadBuffer = encodeUtf8(JSON.stringify(jwtToken.payload));
@@ -52,20 +69,30 @@ export async function createJwtTokenString(jwtToken, key) {
     const encodedPayload = encodeBase64Url(payloadBuffer, 0, payloadBuffer.byteLength);
     const headerPayloadDataString = `${encodedHeader}.${encodedPayload}`;
     const headerPayloadData = encodeUtf8(headerPayloadDataString);
-    const signature = await getSignature(headerPayloadData, jwtToken.header.alg, key);
+    const algorithm = jwtAlgorithmMap[jwtToken.header.alg];
+    const signature = await sign(algorithm, key, headerPayloadData).toBuffer();
     const encodedSignature = encodeBase64Url(signature);
     const tokenString = `${headerPayloadDataString}.${encodedSignature}`;
     return tokenString;
 }
+/**
+ * Parses and validates a JWT token string.
+ * @param tokenString The JWT token string.
+ * @param allowedAlgorithms One or more allowed algorithms.
+ * @param key The CryptoKey to verify the signature with.
+ * @returns The parsed token object if valid.
+ * @throws {InvalidTokenError} If the token is invalid or the signature fails verification.
+ */
 export async function parseAndValidateJwtTokenString(tokenString, allowedAlgorithms, key) {
     try {
         const { encoded, bytes, token } = parseJwtTokenString(tokenString);
         if (!toArray(allowedAlgorithms).includes(token.header.alg)) {
             throw new InvalidTokenError('Invalid signature algorithm');
         }
-        const calculatedSignature = await getSignature(encodeUtf8(`${encoded.header}.${encoded.payload}`), token.header.alg, key);
-        const validSignature = timingSafeBinaryEquals(bytes.signature, calculatedSignature);
-        if (!validSignature) {
+        const encodedHeaderPayload = encodeUtf8(`${encoded.header}.${encoded.payload}`);
+        const algorithm = jwtAlgorithmMap[token.header.alg];
+        const isValid = await verify(algorithm, key, bytes.signature, encodedHeaderPayload);
+        if (!isValid) {
             throw new InvalidTokenError('Invalid token signature');
         }
         return token;
@@ -77,12 +104,3 @@ export async function parseAndValidateJwtTokenString(tokenString, allowedAlgorit
         throw new InvalidTokenError('Invalid token');
     }
 }
-async function getSignature(data, algorithm, secret) {
-    const hashAlgorithm = getHmacHashAlgorithm(algorithm);
-    const hmacKey = await importHmacKey(hashAlgorithm, secret, false);
-    const hmacSignature = sign('HMAC', hmacKey, data);
-    return await hmacSignature.toBuffer();
-}
-function getHmacHashAlgorithm(algorithm) {
-    return algorithm.replace('HS', 'SHA-');
-}

package/cryptography/module.d.ts

@@ -0,0 +1,35 @@
+/** biome-ignore-all lint/nursery/noExcessiveClassesPerFile: <explanation> */
+import { Injector } from '../injector/index.js';
+import { type ImportAlgorithm, type KeyData, type KmacImportParams, type KmacParams } from './cryptography.js';
+export type SecretOptions = {
+    salt?: string | BufferSource;
+};
+export declare class SecretsModuleConfig {
+    key: CryptoKey | BufferSource | string;
+}
+export declare const masterSecretAlgorithm: KmacImportParams;
+export declare const masterSecretKeyUsages: KeyUsage[];
+/**
+ * Configure secrets module
+ */
+export declare function configureSecrets({ injector, ...config }: SecretsModuleConfig & {
+    injector?: Injector;
+}): void;
+export declare class DerivedKey {
+    #private;
+    constructor(baseKey: CryptoKey | Promise<CryptoKey>, params: KmacParams, salt: BufferSource, length: number);
+    constructor(baseKey: CryptoKey | Promise<CryptoKey>, params: KmacParams, salt: BufferSource, keyOptions: ImportAlgorithm, keyUsages: KeyUsage[]);
+    getBytes(): Promise<ArrayBuffer>;
+    getKey(): Promise<CryptoKey>;
+}
+/**
+ * Derive raw bytes using KMAC256
+ * @param customization The context/label (used as KMAC customization string)
+ */
+export declare function injectDerivedBytes(customization: string | BufferSource, length: number, options?: SecretOptions): DerivedKey;
+/**
+ * Derive a CryptoKey (e.g. AES-GCM) using KMAC256
+ * @param customization The context/label (used as KMAC customization string)
+ */
+export declare function injectDerivedCryptoKey(customization: string | BufferSource, derivedKeyAlgorithm: ImportAlgorithm, keyUsages: KeyUsage[], options?: SecretOptions): DerivedKey;
+export declare function importMasterKey(keyMaterial: KeyData | string): Promise<CryptoKey>;

package/cryptography/module.js

@@ -0,0 +1,148 @@
+/** biome-ignore-all lint/nursery/noExcessiveClassesPerFile: <explanation> */
+import { getCurrentInjector, Injector } from '../injector/index.js';
+import { encodeUtf8 } from '../utils/encoding.js';
+import { hasOwnProperty } from '../utils/object/object.js';
+import { assertDefined, assertDefinedPass, isDefined, isNotNull, isNumber, isString, isUndefined } from '../utils/type-guards.js';
+import { importKey, importKmacKey, isBufferSource, sign } from './cryptography.js';
+export class SecretsModuleConfig {
+    key;
+}
+export const masterSecretAlgorithm = { name: 'KMAC256' };
+export const masterSecretKeyUsages = ['sign', 'verify'];
+const masterKeyMap = new WeakMap();
+const hashSizeMap = {
+    'SHA-1': 20,
+    'SHA-256': 32,
+    'SHA3-256': 32,
+    'SHA-384': 48,
+    'SHA3-384': 48,
+    'SHA-512': 64,
+    'SHA3-512': 64,
+    'cSHAKE128': 16,
+    'cSHAKE256': 32,
+};
+/**
+ * Configure secrets module
+ */
+export function configureSecrets({ injector, ...config }) {
+    const targetInjector = injector ?? Injector;
+    let baseKeyPromise;
+    if (config.key instanceof CryptoKey) {
+        baseKeyPromise = config.key;
+    }
+    else {
+        const keyMaterial = isString(config.key) ? encodeUtf8(config.key) : config.key;
+        // Import the key immediately. The raw material is only held in the local scope of this function.
+        baseKeyPromise = importKmacKey('raw-secret', 'KMAC256', keyMaterial, false);
+    }
+    masterKeyMap.set(targetInjector, baseKeyPromise);
+}
+export class DerivedKey {
+    #baseKey;
+    #kmacParams;
+    #salt;
+    #isCryptoKey;
+    #keyOptions;
+    #keyUsages;
+    #derivedBytes;
+    #derivedKey;
+    constructor(baseKey, params, salt, lengthOrKeyOptions, keyUsages) {
+        this.#baseKey = baseKey;
+        this.#kmacParams = params;
+        this.#salt = salt;
+        if (isNumber(lengthOrKeyOptions)) {
+            this.#isCryptoKey = false;
+        }
+        else {
+            this.#isCryptoKey = true;
+            this.#keyOptions = lengthOrKeyOptions;
+            this.#keyUsages = keyUsages;
+        }
+    }
+    async getBytes() {
+        assertDefined(this.#isCryptoKey ? undefined : true, 'This key was not configured to derive bytes. Use injectDerivedBytes().');
+        if (isUndefined(this.#derivedBytes)) {
+            this.#derivedBytes = this.#computeRawBytes();
+            this.#derivedBytes = await this.#derivedBytes;
+        }
+        return this.#derivedBytes; // eslint-disable-line @typescript-eslint/return-await
+    }
+    async getKey() {
+        assertDefined(this.#keyOptions, 'This key was not configured to derive a CryptoKey. Use injectDerivedCryptoKey().');
+        assertDefined(this.#keyUsages, 'This key was not configured to derive a CryptoKey. Use injectDerivedCryptoKey().');
+        if (isUndefined(this.#derivedKey)) {
+            this.#derivedKey = (async () => {
+                const rawBytes = await this.#computeRawBytes();
+                try {
+                    return await importKey('raw-secret', rawBytes, this.#keyOptions, false, this.#keyUsages);
+                }
+                finally {
+                    crypto.getRandomValues(new Uint8Array(rawBytes));
+                }
+            })();
+            this.#derivedKey = await this.#derivedKey;
+        }
+        return this.#derivedKey; // eslint-disable-line @typescript-eslint/return-await
+    }
+    async #computeRawBytes() {
+        const baseKey = await this.#baseKey;
+        return await sign(this.#kmacParams, baseKey, this.#salt).toBuffer();
+    }
+}
+function getBaseKeyFromInjector() {
+    let current = getCurrentInjector(true);
+    while (isNotNull(current)) {
+        const secret = masterKeyMap.get(current);
+        if (isDefined(secret)) {
+            return secret;
+        }
+        current = current.parent;
+    }
+    const globalSecret = masterKeyMap.get(Injector);
+    if (isDefined(globalSecret)) {
+        return globalSecret;
+    }
+    throw new Error('No secret key configured. Call configureSecrets() first.');
+}
+/**
+ * Derive raw bytes using KMAC256
+ * @param customization The context/label (used as KMAC customization string)
+ */
+export function injectDerivedBytes(customization, length, options) {
+    const { params, salt } = buildKmacDerivation(customization, length, options);
+    return new DerivedKey(getBaseKeyFromInjector(), params, salt, length);
+}
+/**
+ * Derive a CryptoKey (e.g. AES-GCM) using KMAC256
+ * @param customization The context/label (used as KMAC customization string)
+ */
+export function injectDerivedCryptoKey(customization, derivedKeyAlgorithm, keyUsages, options) {
+    const algorithmName = isString(derivedKeyAlgorithm) ? derivedKeyAlgorithm : derivedKeyAlgorithm.name;
+    const length = hasOwnProperty(derivedKeyAlgorithm, 'length') && isNumber(derivedKeyAlgorithm.length)
+        ? derivedKeyAlgorithm.length / 8
+        : hasOwnProperty(derivedKeyAlgorithm, 'hash') && isString(derivedKeyAlgorithm.hash)
+            ? assertDefinedPass(hashSizeMap[derivedKeyAlgorithm.hash], 'Unsupported hash function specified in derived key algorithm.')
+            : (algorithmName == 'KMAC128')
+                ? 16
+                : (algorithmName == 'KMAC256')
+                    ? 32
+                    : undefined;
+    assertDefined(length, 'Derived key algorithm must specify a key length either directly or via the hash function.');
+    const { params, salt } = buildKmacDerivation(customization, length, options);
+    return new DerivedKey(getBaseKeyFromInjector(), params, salt, derivedKeyAlgorithm, keyUsages);
+}
+export async function importMasterKey(keyMaterial) {
+    const keyFormat = isBufferSource(keyMaterial) ? 'raw-secret' : 'jwk';
+    const keyData = isString(keyMaterial) ? encodeUtf8(keyMaterial) : keyMaterial;
+    return await importKey(keyFormat, keyData, masterSecretAlgorithm, false, masterSecretKeyUsages);
+}
+function buildKmacDerivation(customization, length, options) {
+    const customizationBytes = isString(customization) ? encodeUtf8(customization) : customization;
+    const salt = (isString(options?.salt) ? encodeUtf8(options.salt) : options?.salt) ?? new Uint8Array();
+    const params = {
+        name: 'KMAC256',
+        outputLength: length,
+        customization: customizationBytes,
+    };
+    return { params, salt };
+}

package/cryptography/tests/cryptography.test.d.ts

@@ -0,0 +1 @@
+export {};

package/cryptography/tests/cryptography.test.js

@@ -0,0 +1,175 @@
+import { describe, expect, test } from 'vitest';
+import { encodeUtf8 } from '../../utils/encoding.js';
+import { decrypt, deriveBytes, digest, encrypt, generateEcdsaKey, generateHmacKey, generatePbkdf2Key, generateSymmetricKey, importEcdsaKey, importHkdfKey, importHmacKey, importPbkdf2Key, importSymmetricKey, sign, verify } from '../cryptography.js';
+describe('Cryptography Utilities', () => {
+    test('encrypt and decrypt with AES-GCM (string)', async () => {
+        const key = await generateSymmetricKey({ name: 'AES-GCM', length: 256 });
+        const data = 'Hello World';
+        const iv = globalThis.crypto.getRandomValues(new Uint8Array(12));
+        const algorithm = { name: 'AES-GCM', iv };
+        const encryptionResult = encrypt(algorithm, key, data);
+        const encryptedBuffer = await encryptionResult.toBuffer();
+        const decryptionResult = decrypt(algorithm, key, encryptedBuffer);
+        const decryptedText = await decryptionResult.toUtf8();
+        expect(decryptedText).toBe(data);
+        expect(await encryptionResult.toHex()).toBeTypeOf('string');
+        expect(await encryptionResult.toBase64()).toBeTypeOf('string');
+        expect(await encryptionResult.toBase64Url()).toBeTypeOf('string');
+        expect(await encryptionResult.toZBase32()).toBeTypeOf('string');
+    });
+    test('encrypt and decrypt with AES-CBC (Uint8Array)', async () => {
+        const key = await generateSymmetricKey({ name: 'AES-CBC', length: 256 });
+        const data = new Uint8Array([1, 2, 3, 4, 5]);
+        const iv = globalThis.crypto.getRandomValues(new Uint8Array(16));
+        const algorithm = { name: 'AES-CBC', iv };
+        const encryptionResult = encrypt(algorithm, key, data);
+        const encryptedBuffer = await encryptionResult.toBuffer();
+        const decryptionResult = decrypt(algorithm, key, encryptedBuffer);
+        const decryptedBuffer = await decryptionResult.toBuffer();
+        expect(new Uint8Array(decryptedBuffer)).toEqual(data);
+    });
+    test('digest with SHA-256', async () => {
+        const data = 'Hello World';
+        const result = digest('SHA-256', data);
+        const hex = await result.toHex();
+        // SHA-256 of "Hello World"
+        expect(hex).toBe('a591a6d40bf420404a011733cfb7b190d62c65bf0bcda32b57b277d9ad9f146e');
+        const bufferResult = digest('SHA-256', encodeUtf8(data));
+        expect(await bufferResult.toHex()).toBe(hex);
+    });
+    test('sign and verify with HMAC', async () => {
+        const key = await generateHmacKey('SHA-256');
+        const data = 'Hello World';
+        const algorithm = { name: 'HMAC', hash: 'SHA-256' };
+        const signatureResult = sign(algorithm, key, data);
+        const signature = await signatureResult.toBuffer();
+        // Test with mixed string/binary
+        expect(await verify(algorithm, key, signature, data)).toBe(true);
+        expect(await verify(algorithm, key, new Uint8Array(signature), encodeUtf8(data))).toBe(true);
+        const isInvalid = await verify(algorithm, key, signature, 'Wrong Data');
+        expect(isInvalid).toBe(false);
+        const isInvalidSignature = await verify(algorithm, key, new Uint8Array(signature.byteLength), data);
+        expect(isInvalidSignature).toBe(false);
+    });
+    test('import and export HMAC key (raw)', async () => {
+        const rawKey = encodeUtf8('my-secret-key');
+        const key = await importHmacKey('raw-secret', 'SHA-256', rawKey, true);
+        expect(key.algorithm.name).toBe('HMAC');
+        expect(key.algorithm.hash.name).toBe('SHA-256');
+        const exportedKey = await globalThis.crypto.subtle.exportKey('raw', key);
+        expect(new Uint8Array(exportedKey)).toEqual(rawKey);
+        // Test import with string
+        const keyFromString = await importHmacKey('raw-secret', 'SHA-256', encodeUtf8('my-secret-key'));
+        expect(keyFromString.algorithm.name).toBe('HMAC');
+    });
+    test('import HMAC key (JWK)', async () => {
+        const jwk = {
+            kty: 'oct',
+            k: 'bXktc2VjcmV0LWtleQ', // "my-secret-key" in base64url
+            alg: 'HS256',
+            ext: true,
+        };
+        const key = await importHmacKey('jwk', 'SHA-256', jwk, true);
+        expect(key.algorithm.name).toBe('HMAC');
+        const exportedKey = await globalThis.crypto.subtle.exportKey('raw', key);
+        expect(new Uint8Array(exportedKey)).toEqual(encodeUtf8('my-secret-key'));
+    });
+    test('import symmetric key (raw)', async () => {
+        const rawKey = globalThis.crypto.getRandomValues(new Uint8Array(32));
+        const key = await importSymmetricKey('raw-secret', { name: 'AES-GCM', length: 256 }, rawKey, true);
+        expect(key.algorithm.name).toBe('AES-GCM');
+        expect(key.algorithm.length).toBe(256);
+        const exportedKey = await globalThis.crypto.subtle.exportKey('raw', key);
+        expect(new Uint8Array(exportedKey)).toEqual(rawKey);
+        // Test import with encoded string (exactly 32 chars)
+        const keyFromString = await importSymmetricKey('raw-secret', { name: 'AES-GCM', length: 256 }, encodeUtf8('01234567890123456789012345678901'));
+        expect(keyFromString.algorithm.name).toBe('AES-GCM');
+    });
+    test('import symmetric key (JWK)', async () => {
+        const jwk = {
+            kty: 'oct',
+            k: 'AAECAwQFBgcICQoLDA0ODw', // [0, 1, ..., 15]
+            alg: 'A128GCM',
+            ext: true,
+        };
+        const key = await importSymmetricKey('jwk', { name: 'AES-GCM', length: 128 }, jwk, true);
+        expect(key.algorithm.name).toBe('AES-GCM');
+        const exportedJwk = await globalThis.crypto.subtle.exportKey('jwk', key);
+        expect(exportedJwk.k).toBe(jwk.k);
+    });
+    test('sign and verify with ECDSA', async () => {
+        const keyPair = await generateEcdsaKey('P-256');
+        const data = 'Hello World';
+        const algorithm = { name: 'ECDSA', hash: 'SHA-256' };
+        const signatureResult = sign(algorithm, keyPair.privateKey, data);
+        const signature = await signatureResult.toBuffer();
+        const isValid = await verify(algorithm, keyPair.publicKey, signature, data);
+        expect(isValid).toBe(true);
+    });
+    test('import ECDSA public key (SPKI)', async () => {
+        const keyPair = await generateEcdsaKey('P-256', true);
+        const spki = await globalThis.crypto.subtle.exportKey('spki', keyPair.publicKey);
+        const importedKey = await importEcdsaKey('spki', 'P-256', spki);
+        expect(importedKey.type).toBe('public');
+        expect(importedKey.algorithm.name).toBe('ECDSA');
+    });
+    test('import ECDSA public key (JWK)', async () => {
+        const keyPair = await generateEcdsaKey('P-256', true);
+        const jwk = await globalThis.crypto.subtle.exportKey('jwk', keyPair.publicKey);
+        const importedKey = await importEcdsaKey('jwk', 'P-256', jwk);
+        expect(importedKey.type).toBe('public');
+        expect(importedKey.algorithm.name).toBe('ECDSA');
+    });
+    test('import HKDF key', async () => {
+        const baseKeyMaterial = encodeUtf8('base-secret');
+        const baseKey = await importHkdfKey('raw', baseKeyMaterial);
+        expect(baseKey.algorithm.name).toBe('HKDF');
+        // Test import with string
+        const keyFromString = await importHkdfKey('raw', encodeUtf8('base-secret'));
+        expect(keyFromString.algorithm.name).toBe('HKDF');
+    });
+    test('PBKDF2 derivation', async () => {
+        const baseKey = await generatePbkdf2Key();
+        const salt = globalThis.crypto.getRandomValues(new Uint8Array(16));
+        const algorithm = {
+            name: 'PBKDF2',
+            salt,
+            iterations: 1000,
+            hash: 'SHA-256',
+        };
+        const derivedBytes = await deriveBytes(algorithm, baseKey, 32);
+        expect(derivedBytes.byteLength).toBe(32);
+        const importedKey = await importPbkdf2Key('raw-secret', encodeUtf8('password'));
+        const derivedBytes2 = await deriveBytes(algorithm, importedKey, 32);
+        expect(derivedBytes2.byteLength).toBe(32);
+        // Test import with string
+        const keyFromString = await importPbkdf2Key('raw-secret', encodeUtf8('password'));
+        expect(keyFromString.algorithm.name).toBe('PBKDF2');
+    });
+    test('CryptionResult helper methods', async () => {
+        const data = 'Hello World';
+        const result = digest('SHA-256', data);
+        expect(await result.toBuffer()).toBeInstanceOf(ArrayBuffer);
+        expect(await result.toHex()).toBeTypeOf('string');
+        expect(await result.toBase64()).toBeTypeOf('string');
+        expect(await result.toBase64Url()).toBeTypeOf('string');
+        expect(await result.toZBase32()).toBeTypeOf('string');
+        const key = await generateHmacKey('SHA-256');
+        const signResult = sign({ name: 'HMAC', hash: 'SHA-256' }, key, data);
+        expect(await signResult.toHex()).toBeTypeOf('string');
+        expect(await signResult.toBase64()).toBeTypeOf('string');
+        expect(await signResult.toBase64Url()).toBeTypeOf('string');
+        expect(await signResult.toZBase32()).toBeTypeOf('string');
+        const symKey = await generateSymmetricKey({ name: 'AES-GCM', length: 256 });
+        const iv = globalThis.crypto.getRandomValues(new Uint8Array(12));
+        const encResult = encrypt({ name: 'AES-GCM', iv }, symKey, data);
+        const encrypted = await encResult.toBuffer();
+        expect(await encResult.toHex()).toBeTypeOf('string');
+        const decResult = decrypt({ name: 'AES-GCM', iv }, symKey, encrypted);
+        expect(await decResult.toHex()).toBeTypeOf('string');
+        expect(await decResult.toBase64()).toBeTypeOf('string');
+        expect(await decResult.toBase64Url()).toBeTypeOf('string');
+        expect(await decResult.toZBase32()).toBeTypeOf('string');
+        expect(await decResult.toUtf8()).toBe(data);
+    });
+});

package/cryptography/tests/jwt.test.d.ts

@@ -0,0 +1 @@
+export {};

package/cryptography/tests/jwt.test.js

@@ -0,0 +1,54 @@
+import { describe, expect, test } from 'vitest';
+import { InvalidTokenError } from '../../errors/invalid-token.error.js';
+import { generateKmacKey, generateSymmetricKey } from '../cryptography.js';
+import { createJwtTokenString, parseAndValidateJwtTokenString, parseJwtTokenString } from '../jwt.js';
+describe('JWT Utilities', () => {
+    test('create, parse and validate JWT', async () => {
+        const key = await generateKmacKey('KMAC256');
+        const token = {
+            header: { alg: 'KMAC256', typ: 'JWT' },
+            payload: { sub: '1234567890', name: 'John Doe', iat: 1516239022 },
+        };
+        const tokenString = await createJwtTokenString(token, key);
+        expect(tokenString).toBeTypeOf('string');
+        expect(tokenString.split('.').length).toBe(3);
+        const parsed = parseJwtTokenString(tokenString);
+        expect(parsed.token.payload).toEqual(token.payload);
+        const validated = await parseAndValidateJwtTokenString(tokenString, 'KMAC256', key);
+        expect(validated.payload).toEqual(token.payload);
+    });
+    test('fail on invalid signature', async () => {
+        const key = await generateKmacKey('KMAC256');
+        const otherKey = await generateKmacKey('KMAC256');
+        const token = {
+            header: { alg: 'KMAC256', typ: 'JWT' },
+            payload: { sub: '1234567890' },
+        };
+        const tokenString = await createJwtTokenString(token, key);
+        await expect(parseAndValidateJwtTokenString(tokenString, 'KMAC256', otherKey)).rejects.toThrow(InvalidTokenError);
+    });
+    test('fail on disallowed algorithm', async () => {
+        const key = await generateKmacKey('KMAC256');
+        const token = {
+            header: { alg: 'KMAC256', typ: 'JWT' },
+            payload: { sub: '1234567890' },
+        };
+        const tokenString = await createJwtTokenString(token, key);
+        await expect(parseAndValidateJwtTokenString(tokenString, 'KMAC128', key)).rejects.toThrow(InvalidTokenError);
+    });
+    test('fail on malformed token', () => {
+        expect(() => parseJwtTokenString('a.b')).toThrow('Invalid token format');
+        expect(() => parseJwtTokenString('')).toThrow('Missing authorization token');
+    });
+    test('fail on generic error in parseAndValidateJwtTokenString', async () => {
+        const key = await generateKmacKey('KMAC256');
+        const token = {
+            header: { alg: 'KMAC256', typ: 'JWT' },
+            payload: { sub: '1234567890' },
+        };
+        const tokenString = await createJwtTokenString(token, key);
+        // Use an incompatible key type to trigger a generic error in Web Crypto
+        const aesKey = await generateSymmetricKey({ name: 'AES-GCM', length: 256 });
+        await expect(parseAndValidateJwtTokenString(tokenString, 'KMAC256', aesKey)).rejects.toThrow('Invalid token');
+    });
+});

package/cryptography/tests/modern.test.d.ts

@@ -0,0 +1 @@
+export {};

package/cryptography/tests/modern.test.js

@@ -0,0 +1,105 @@
+import { encodeUtf8 } from '../../utils/encoding.js';
+import { describe, expect, test } from 'vitest';
+import { decrypt, deriveBytes, encrypt, generateAsymmetricKey, generateSymmetricKey, getPublicKey, importKey, importSymmetricKey, sign, supports, verify } from '../cryptography.js';
+describe('Modern Cryptography Features', () => {
+    test('SubtleCrypto.supports', async () => {
+        expect(await supports('generateKey', { name: 'AES-GCM', length: 256 })).toBe(true);
+        expect(await supports('sign', { name: 'HMAC', hash: 'SHA-256' })).toBe(true);
+    });
+    test('KMAC128 signing and verification', async () => {
+        const isSupported = await supports('generateKey', { name: 'KMAC128' });
+        if (!isSupported) {
+            throw new Error('KMAC128 not supported in this environment');
+        }
+        const key = await importSymmetricKey('raw-secret', { name: 'KMAC128' }, encodeUtf8('my-secret-key-128bits'));
+        const data = 'Hello KMAC';
+        const algorithm = { name: 'KMAC128', length: 128, outputLength: 32 };
+        const signatureResult = sign(algorithm, key, data);
+        const signature = await signatureResult.toBuffer();
+        expect(await verify(algorithm, key, signature, data)).toBe(true);
+    });
+    test('KMAC256 signing and verification', async () => {
+        const isSupported = await supports('generateKey', { name: 'KMAC256' });
+        console.log('KMAC256 supported:', isSupported);
+        if (!isSupported) {
+            return;
+        }
+        const key = await importSymmetricKey('raw-secret', { name: 'KMAC256' }, encodeUtf8('my-secret-key-256bits-long-enough-for-kmac256'));
+        const data = 'Hello KMAC256';
+        const algorithm = { name: 'KMAC256', length: 256, outputLength: 64 };
+        const signatureResult = sign(algorithm, key, data);
+        const signature = await signatureResult.toBuffer();
+        expect(await verify(algorithm, key, signature, data)).toBe(true);
+    });
+    test('Argon2id derivation', async () => {
+        const isSupported = await supports('importKey', 'Argon2id');
+        if (!isSupported) {
+            throw new Error('Argon2id not supported in this environment');
+        }
+        const password = 'my-password';
+        const salt = globalThis.crypto.getRandomValues(new Uint8Array(16));
+        const key = await importKey('raw-secret', encodeUtf8(password), { name: 'Argon2id' }, false, ['deriveBits']);
+        const argon2Params = {
+            name: 'Argon2id',
+            nonce: salt,
+            memory: 8,
+            parallelism: 1,
+            passes: 1,
+        };
+        const derivedBits = await deriveBytes(argon2Params, key, 32);
+        expect(derivedBits.byteLength).toBe(32);
+    });
+    test('ML-DSA-44 signing and verification', async () => {
+        const isSupported = await supports('generateKey', 'ML-DSA-44');
+        if (!isSupported) {
+            throw new Error('ML-DSA-44 not supported in this environment');
+        }
+        const keyPair = await generateAsymmetricKey({ name: 'ML-DSA-44', namedCurve: 'ML-DSA-44' }, true, ['sign', 'verify']);
+        const data = 'Hello ML-DSA';
+        const algorithm = { name: 'ML-DSA-44' };
+        const signatureResult = sign(algorithm, keyPair.privateKey, data);
+        const signature = await signatureResult.toBuffer();
+        expect(await verify(algorithm, keyPair.publicKey, signature, data)).toBe(true);
+    });
+    test('ChaCha20-Poly1305 encryption and decryption', async () => {
+        const isSupported = await supports('generateKey', { name: 'ChaCha20-Poly1305' });
+        if (!isSupported) {
+            throw new Error('ChaCha20-Poly1305 not supported in this environment');
+        }
+        const key = await generateSymmetricKey({ name: 'ChaCha20-Poly1305', length: 256 });
+        const data = 'Hello ChaCha20';
+        const nonce = globalThis.crypto.getRandomValues(new Uint8Array(12));
+        const algorithm = { name: 'ChaCha20-Poly1305', iv: nonce };
+        const encryptionResult = encrypt(algorithm, key, data);
+        const encryptedBuffer = await encryptionResult.toBuffer();
+        const decryptionResult = decrypt(algorithm, key, encryptedBuffer);
+        const decryptedText = await decryptionResult.toUtf8();
+        expect(decryptedText).toBe(data);
+    });
+    test('AES-OCB encryption and decryption', async () => {
+        const isSupported = await supports('generateKey', { name: 'AES-OCB', length: 256 });
+        if (!isSupported) {
+            throw new Error('AES-OCB not supported in this environment');
+        }
+        const key = await generateSymmetricKey({ name: 'AES-OCB', length: 256 });
+        const data = 'Hello AES-OCB';
+        const iv = globalThis.crypto.getRandomValues(new Uint8Array(12));
+        const algorithm = { name: 'AES-OCB', iv };
+        const encryptionResult = encrypt(algorithm, key, data);
+        const encryptedBuffer = await encryptionResult.toBuffer();
+        const decryptionResult = decrypt(algorithm, key, encryptedBuffer);
+        const decryptedText = await decryptionResult.toUtf8();
+        expect(decryptedText).toBe(data);
+    });
+    test('getPublicKey from private key', async () => {
+        const isSupported = await supports('getPublicKey', 'Ed25519'); // getPublicKey support is often generic but checking Ed25519
+        if (!isSupported) {
+            // Fallback check if getPublicKey is supported but supports doesn't report it well for Ed25519
+            throw new Error('getPublicKey not supported in this environment');
+        }
+        const keyPair = await generateAsymmetricKey({ name: 'Ed25519', namedCurve: 'Ed25519' }, true, ['sign', 'verify']);
+        const publicKey = await getPublicKey(keyPair.privateKey, ['verify']);
+        expect(publicKey.type).toBe('public');
+        expect(publicKey.algorithm.name).toBe('Ed25519');
+    });
+});

package/cryptography/tests/module.test.d.ts

@@ -0,0 +1 @@
+export {};