### Install with npm

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/configuration.md

Install the library using npm for Node.js environments.

```bash
npm install @noble/post-quantum
```

--------------------------------

### Example: Seed Expansion Usage

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/hybrid.md

Demonstrates how to use the expandSeedXof factory function with shake256 to expand a seed to a specified length.

```typescript
import { shake256 } from '@noble/hashes/sha3.js';
import { expandSeedXof } from '@noble/post-quantum/hybrid.js';

const expandSeed = expandSeedXof(shake256);
const expanded = expandSeed(new Uint8Array(32), 64);
```

--------------------------------

### Build and Test Noble Post-Quantum Code

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/README.md

Run this command to build the code and execute all tests. Ensure you have installed dependencies first.

```bash
npm install && npm run build && npm test
```

--------------------------------

### Example: ECDH KEM Usage

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/hybrid.md

Demonstrates how to use the ecdhKem factory function to create a KEM instance and perform key generation, encapsulation, and decapsulation.

```typescript
import { x25519 } from '@noble/curves/ed25519.js';
import { ecdhKem } from '@noble/post-quantum/hybrid.js';

const kem = ecdhKem(x25519);
const { secretKey, publicKey } = kem.keygen();
const { cipherText, sharedSecret } = kem.encapsulate(publicKey);
```

--------------------------------

### ML-DSA44 Keygen, Sign, and Verify Example

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/ml-dsa.md

Demonstrates key generation, signing a message, and verifying the signature using the ml_dsa44 instance. Requires a 32-byte seed for key generation.

```typescript
import { ml_dsa44 } from '@noble/post-quantum/ml-dsa.js';

const seed = new Uint8Array(32);
const { secretKey, publicKey } = ml_dsa44.keygen(seed);

const msg = new TextEncoder().encode('hello world');
const sig = ml_dsa44.sign(msg, secretKey);
const isValid = ml_dsa44.verify(sig, msg, publicKey);
console.log(isValid); // true
```

--------------------------------

### ML-DSA65 Keygen, Sign, Verify, and GetPublicKey Example

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/ml-dsa.md

Shows key generation (with random seed if not provided), signing, verification with a context option, and retrieving the public key from the secret key using ml_dsa65.

```typescript
import { ml_dsa65 } from '@noble/post-quantum/ml-dsa.js';
import { randomBytes } from '@noble/post-quantum/utils.js';

// Generate keypair (random seed generated if not provided)
const { secretKey, publicKey } = ml_dsa65.keygen();

// Sign a message
const msg = new TextEncoder().encode('message to sign');
const sig = ml_dsa65.sign(msg, secretKey);

// Verify with context option
const isValid = ml_dsa65.verify(sig, msg, publicKey, { context: new Uint8Array([1, 2]) });
console.log(isValid);

// Get public key from secret key
const pk = ml_dsa65.getPublicKey(secretKey);
```

--------------------------------

### Falcon 512 Signature Example

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/falcon.md

Demonstrates key generation, signing, and verification using the Falcon 512 algorithm with variable-length signatures. Ensure the 'hello world' message is encoded to Uint8Array.

```typescript
import { falcon512 } from '@noble/post-quantum/falcon.js';

const { secretKey, publicKey } = falcon512.keygen();

const msg = new TextEncoder().encode('hello world');
const sig = falcon512.sign(msg, secretKey);
console.log('Signature size:', sig.length); // ~666 bytes
const isValid = falcon512.verify(sig, msg, publicKey);
console.log(isValid); // true

// Get public key from secret key
const pk = falcon512.getPublicKey(secretKey);
```

--------------------------------

### ML-KEM-768 with X25519 Hybrid KEM Example

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/hybrid.md

Example usage of the ml_kem768_x25519 hybrid KEM, which combines ML-KEM-768 with X25519. Use this for key generation, encapsulation, and decapsulation.

```typescript
import { ml_kem768_x25519 } from '@noble/post-quantum/hybrid.js';

const { secretKey, publicKey } = ml_kem768_x25519.keygen();
const { cipherText, sharedSecret } = ml_kem768_x25519.encapsulate(publicKey);
const recovered = ml_kem768_x25519.decapsulate(cipherText, secretKey);
```

--------------------------------

### KitchenSink ML-KEM-768 with X25519 Hybrid KEM Example

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/hybrid.md

Example usage of the KitchenSink_ml_kem768_x25519 hybrid KEM, which uses HKDF-SHA256 as the combiner. Use this for key generation, encapsulation, and decapsulation.

```typescript
import { KitchenSink_ml_kem768_x25519 } from '@noble/post-quantum/hybrid.js';

const { secretKey, publicKey } = KitchenSink_ml_kem768_x25519.keygen();
const { cipherText, sharedSecret } = KitchenSink_ml_kem768_x25519.encapsulate(publicKey);
const recovered = KitchenSink_ml_kem768_x25519.decapsulate(cipherText, secretKey);
```

--------------------------------

### Example: Combining KEMs

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/hybrid.md

Shows how to combine ml_kem768 (post-quantum) and an ECDH KEM (classical) using sha256 as the combiner. The 'name' option is used for error reporting.

```typescript
import { ml_kem768 } from '@noble/post-quantum/ml-kem.js';
import { x25519 } from '@noble/curves/ed25519.js';
import { combineKEMS, ecdhKem } from '@noble/post-quantum/hybrid.js';
import { sha256 } from '@noble/hashes/sha2.js';

const classicKem = ecdhKem(x25519);
const combiner = (pq: Uint8Array, classic: Uint8Array) => {
  return sha256.create().update(pq).update(classic).digest();
};

const hybridKem = combineKEMS(ml_kem768, classicKem, combiner);
```

--------------------------------

### ML-KEM768 Key Generation, Encapsulation, and Decapsulation

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/ml-kem.md

Example of key generation, encapsulation, and decapsulation using the ml_kem768 instance. A new Uint8Array is used for the seed.

```typescript
import { ml_kem768 } from '@noble/post-quantum/ml-kem.js';

const seed = new Uint8Array(64);
const { secretKey, publicKey } = ml_kem768.keygen(seed);

const { cipherText, sharedSecret } = ml_kem768.encapsulate(publicKey);
const recovered = ml_kem768.decapsulate(cipherText, secretKey);
```

--------------------------------

### SLH-DSA SHA2 128f Keygen, Sign, Verify Example

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/slh-dsa.md

Demonstrates how to generate a key pair, sign a message, and verify a signature using the `slh_dsa_sha2_128f` variant. Also shows how to derive the public key from the secret key.

```typescript
import { slh_dsa_sha2_128f } from '@noble/post-quantum/slh-dsa.js';

const { secretKey, publicKey } = slh_dsa_sha2_128f.keygen();

const msg = new TextEncoder().encode('message to sign');
const sig = slh_dsa_sha2_128f.sign(msg, secretKey);
const isValid = slh_dsa_sha2_128f.verify(sig, msg, publicKey);
console.log(isValid); // true

// Get public key from secret key
const pk = slh_dsa_sha2_128f.getPublicKey(secretKey);
```

--------------------------------

### Import All Post-Quantum Algorithms

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/README.md

Import all available post-quantum algorithms from the noble-post-quantum library. Use sub-imports instead of a wildcard import.

```js
import { ml_kem512, ml_kem768, ml_kem1024 } from '@noble/post-quantum/ml-kem.js';
import { ml_dsa44, ml_dsa65, ml_dsa87 } from '@noble/post-quantum/ml-dsa.js';
import {
  slh_dsa_sha2_128f,
  slh_dsa_sha2_128s,
  slh_dsa_sha2_192f,
  slh_dsa_sha2_192s,
  slh_dsa_sha2_256f,
  slh_dsa_sha2_256s,
  slh_dsa_shake_128f,
  slh_dsa_shake_128s,
  slh_dsa_shake_192f,
  slh_dsa_shake_192s,
  slh_dsa_shake_256f,
  slh_dsa_shake_256s,
} from '@noble/post-quantum/slh-dsa.js';
import {
  falcon512, falcon512padded, falcon1024, falcon1024padded,
} from '@noble/post-quantum/falcon.js';
import {
  ml_kem768_x25519, ml_kem768_p256, ml_kem1024_p384,
  KitchenSink_ml_kem768_x25519, XWing,
  QSF_ml_kem768_p256, QSF_ml_kem1024_p384,
} from '@noble/post-quantum/hybrid.js';
```

--------------------------------

### Immediate Input Validation Errors

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/errors.md

Input validation errors are thrown immediately before any cryptographic operations begin. This example demonstrates a TypeError for invalid input to encapsulate.

```typescript
// This throws TypeError for validation, NOT crypto-related error
try {
  ml_kem768.encapsulate("not bytes");  // Immediate TypeError
} catch (e) {
  // Only input validation errors thrown here
}
```

--------------------------------

### Run Benchmarks

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/README.md

Execute this command to run performance benchmarks for the library's algorithms.

```bash
npm run bench
```

--------------------------------

### Build Single File Bundle

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/README.md

This command is used to create a single bundled file of the project.

```bash
npm run bundle
```

--------------------------------

### SphincsHashOpts Type Definition

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/types.md

Specifies optional hash customization settings for creating an SLH-DSA context. It includes an option for compressed hashing and a factory function to get the context.

```typescript
export type SphincsHashOpts = {
  isCompressed?: boolean;
  getContext: GetContext;
};
```

--------------------------------

### Add with Deno

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/configuration.md

Add the library using Deno's JSR registry.

```bash
deno add jsr:@noble/post-quantum
```

--------------------------------

### Handle Errors in Cryptographic Operations

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/errors.md

This example demonstrates robust error handling for cryptographic operations, including input validation, signature verification, and catching potential TypeErrors or other exceptions.

```typescript
try {
  const seed = abytes(userProvidedSeed, 32, 'seed');
  const { secretKey, publicKey } = ml_dsa65.keygen(seed);
  
  const sig = ml_dsa65.sign(msg, secretKey);
  
  const isValid = ml_dsa65.verify(sig, msg, publicKey);
  if (!isValid) {
    console.error('Signature verification failed for message');
    return false;
  }
  
  return true;
} catch (e) {
  if (e instanceof TypeError) {
    console.error('Invalid input parameters:', e.message);
  } else {
    console.error('Cryptographic operation failed:', e.message);
  }
  return false;
}
```

--------------------------------

### Minimal Size + Fast Verification

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/configuration.md

Import Falcon512 for minimal size and fast verification.

```typescript
import { falcon512 } from '@noble/post-quantum/falcon.js';
```

--------------------------------

### Import Falcon Algorithms

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/falcon.md

Import the necessary Falcon algorithm instances from the @noble/post-quantum library.

```typescript
import {
  falcon512,
  falcon512padded,
  falcon1024,
  falcon1024padded
} from '@noble/post-quantum/falcon.js';
```

--------------------------------

### QSF

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/hybrid.md

Creates a quantum-safe fusion (QSF) hybrid KEM construction.

```APIDOC
## QSF

### Description
Creates a quantum-safe fusion (QSF) hybrid KEM construction.

### Method Signature
```ts
export function QSF(
  pqKEM: KEM,
  ecKEM: KEM,
  opts?: { allowZeroKey?: boolean }
): KEM
```

### Parameters
#### Path Parameters
- **pqKEM** (KEM) - Required - Post-quantum KEM
- **ecKEM** (KEM) - Required - Elliptic curve KEM
- **opts.allowZeroKey** (boolean) - Optional - Allow zero scalar keys

### Returns
A hybrid `KEM` using the QSF construction.
```

--------------------------------

### Import Hybrid Module

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/hybrid.md

Import all available hybrid KEM instances and utility functions from the @noble/post-quantum/hybrid.js module.

```typescript
import {
  ml_kem768_x25519, ml_kem768_p256, ml_kem1024_p384,
  KitchenSink_ml_kem768_x25519, XWing,
  QSF_ml_kem768_p256, QSF_ml_kem1024_p384,
  ecdhKem, ecSigner, expandSeedXof, combineKEMS, combineSigners, QSF, createKitchenSink
} from '@noble/post-quantum/hybrid.js';
```

--------------------------------

### ML-KEM512 Key Generation, Encapsulation, and Decapsulation

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/ml-kem.md

Demonstrates generating a keypair using a seed, encapsulating a message to create a ciphertext and shared secret, and then decapsulating the ciphertext to recover the shared secret using ml_kem512. Also shows how to derive the public key from the secret key.

```typescript
import { ml_kem512 } from '@noble/post-quantum/ml-kem.js';
import { randomBytes } from '@noble/post-quantum/utils.js';

// Generate deterministic keypair with seed
const seed = randomBytes(ml_kem512.lengths.seed);
const { secretKey, publicKey } = ml_kem512.keygen(seed);

// Encapsulate: Alice creates ciphertext and shared secret for Bob's public key
const encapsResult = ml_kem512.encapsulate(publicKey);
const cipherText = encapsResult.cipherText;
const sharedSecretAlice = encapsResult.sharedSecret;

// Decapsulate: Bob recovers the shared secret using his secret key
const sharedSecretBob = ml_kem512.decapsulate(cipherText, secretKey);

// Both parties now have the same shared secret
console.assert(sharedSecretAlice.every((v, i) => v === sharedSecretBob[i]));

// Derive public key from secret key
const recoveredPublic = ml_kem512.getPublicKey(secretKey);
```

--------------------------------

### Import ML-DSA Instances

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/ml-dsa.md

Import the specific ML-DSA instances (ml_dsa44, ml_dsa65, ml_dsa87) from the @noble/post-quantum library.

```typescript
import { ml_dsa44, ml_dsa65, ml_dsa87 } from '@noble/post-quantum/ml-dsa.js';
```

--------------------------------

### Import ML-KEM Modules

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/ml-kem.md

Import the necessary ML-KEM instances from the @noble/post-quantum library.

```typescript
import { ml_kem512, ml_kem768, ml_kem1024 } from '@noble/post-quantum/ml-kem.js';
```

--------------------------------

### createKitchenSink

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/hybrid.md

Creates a KitchenSink hybrid KEM using HKDF-SHA256 combiner.

```APIDOC
## createKitchenSink

### Description
Creates a KitchenSink hybrid KEM using HKDF-SHA256 combiner.

### Method Signature
```ts
export function createKitchenSink(
  pqKEM: KEM,
  ecdhKEM: KEM,
  opts?: { allowZeroKey?: boolean }
): KEM
```

### Parameters
#### Path Parameters
- **pqKEM** (KEM) - Required - Post-quantum KEM
- **ecdhKEM** (KEM) - Required - ECDH KEM
- **opts.allowZeroKey** (boolean) - Optional - Allow zero scalar keys

### Returns
A hybrid `KEM` with HKDF-SHA256 combination.
```

--------------------------------

### Enable Tree-Shaking with Explicit Submodule Imports

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/overview.md

Import specific algorithms from their respective submodules to enable tree-shaking. Avoid wildcard imports.

```ts
// ❌ Prevents tree-shaking
import * from '@noble/post-quantum';

// ✅ Enables tree-shaking
import { ml_kem768 } from '@noble/post-quantum/ml-kem.js';
import { ml_dsa65 } from '@noble/post-quantum/ml-dsa.js';
```

--------------------------------

### Signing with Options

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/configuration.md

Use the `opts` parameter to provide optional context or extra entropy during signing. Ensure `extraEntropy` is a Uint8Array or `false` to disable.

```ts
interface SigOpts {
  context?: Uint8Array;
  extraEntropy?: Uint8Array | false;
}
```

```ts
const opts = {
  context: new Uint8Array([1, 2, 3]),
  extraEntropy: new Uint8Array(32)
};
const sig = ml_dsa65.sign(msg, secretKey, opts);
```

--------------------------------

### Category 3 Security with Classical Fallback

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/configuration.md

Import ML-KEM768 with X25519 and XWing for Category 3 security with a classical fallback.

```typescript
import { ml_kem768_x25519, XWing } from '@noble/post-quantum/hybrid.js';
```

--------------------------------

### Create Kitchen Sink Hybrid KEM

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/hybrid.md

Constructs a hybrid KEM using the 'Kitchen Sink' approach, combining a post-quantum KEM with an ECDH KEM, using HKDF-SHA256 as the combiner.

```typescript
export function createKitchenSink(
  pqKEM: KEM,
  ecdhKEM: KEM,
  opts?: { allowZeroKey?: boolean }
): KEM
```

--------------------------------

### Verification with Options

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/configuration.md

When verifying, the `opts` parameter must include a `context` that exactly matches the one used during signing. Mismatched context will cause verification to fail.

```ts
interface VerOpts {
  context?: Uint8Array;
}
```

```ts
const opts = {
  context: new Uint8Array([1, 2, 3])
};
const isValid = ml_dsa65.verify(sig, msg, publicKey, opts);
```

--------------------------------

### falcon1024padded

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/falcon.md

Falcon instance with n=1024, producing fixed-length signatures (1280 bytes).

```APIDOC
## falcon1024padded

### Description
A `Falcon` instance implementing Falcon with n=1024, producing fixed-length signatures.

### Type
`Falcon` (extends `Signer`)

### Properties
- `lengths.publicKey`: 1793 bytes
- `lengths.secretKey`: 2305 bytes
- `lengths.signature`: 1280 bytes (fixed)
- `info.type`: `'falcon'`
- `info.n`: 1024

### Methods
Same as `falcon512`.
```

--------------------------------

### Category 5 Security with Classical Fallback

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/configuration.md

Import ML-KEM1024 with P384 for Category 5 security with a classical fallback.

```typescript
import { ml_kem1024_p384 } from '@noble/post-quantum/hybrid.js';
```

--------------------------------

### Lint and Format Code

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/README.md

Use these commands to run the linter and automatically fix linting issues.

```bash
npm run lint
```

```bash
npm run format
```

--------------------------------

### Importing Utilities and Types from @noble/post-quantum/utils

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/utils.md

Import various utility functions, type definitions, and interfaces used throughout the @noble/post-quantum library. This import statement brings in tools for byte array manipulation, cryptographic options, and message handling.

```typescript
import {
  randomBytes, abytes, copyBytes, equalBytes, concatBytes,
  byteSwap64, baswap64If, cleanBytes, getMask,
  CryptoKeys, VerOpts, SigOpts, Signer, KEM,
  validateOpts, validateVerOpts, validateSigOpts,
  splitCoder, vecCoder,
  getMessage, getMessagePrehash, checkHash,
  type Coder, type BytesCoder, type BytesCoderLen, type TArg, type TRet
} from '@noble/post-quantum/utils.js';
```

--------------------------------

### Import Hybrid Cryptographic Schemes

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/README.md

Imports various hybrid cryptographic schemes that combine post-quantum KEMs with elliptic curve cryptography. These are categorized by their underlying KEM, curve, and construction method (e.g., CG Framework, QSF).

```javascript
import {
  ml_kem768_x25519, ml_kem768_p256, ml_kem1024_p384,
  KitchenSink_ml_kem768_x25519, XWing,
  QSF_ml_kem768_p256, QSF_ml_kem1024_p384,
} from '@noble/post-quantum/hybrid.js';
```

--------------------------------

### Import SLH-DSA Variants

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/slh-dsa.md

Import all available SLH-DSA variants from the '@noble/post-quantum/slh-dsa.js' module. These variants offer different trade-offs between security level, signature size, and performance.

```typescript
import {
  slh_dsa_sha2_128f, slh_dsa_sha2_128s, slh_dsa_sha2_192f, slh_dsa_sha2_192s,
  slh_dsa_sha2_256f, slh_dsa_sha2_256s,
  slh_dsa_shake_128f, slh_dsa_shake_128s, slh_dsa_shake_192f, slh_dsa_shake_192s,
  slh_dsa_shake_256f, slh_dsa_shake_256s,
} from '@noble/post-quantum/slh-dsa.js';
```

--------------------------------

### Create Quantum-Safe Fusion (QSF) KEM

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/hybrid.md

Constructs a hybrid KEM using the Quantum-Safe Fusion (QSF) method, combining a post-quantum KEM with an elliptic curve KEM.

```typescript
export function QSF(
  pqKEM: KEM,
  ecKEM: KEM,
  opts?: { allowZeroKey?: boolean }
): KEM
```

--------------------------------

### Generate and Verify Falcon Signatures

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/README.md

Shows how to generate keys, sign messages, and verify signatures using the Falcon-512 algorithm. An optional seed can be provided for key generation to ensure reproducibility.

```typescript
import { falcon512, falcon1024 } from '@noble/post-quantum/falcon.js';
import { randomBytes } from '@noble/post-quantum/utils.js';
const seed3 = randomBytes(48); // seed is optional
const keys3 = falcon512.keygen(seed3);
const msg3 = new TextEncoder().encode('hello noble');
const sig3 = falcon512.sign(msg3, keys3.secretKey);
const isValid3 = falcon512.verify(sig3, msg3, keys3.publicKey);
```

--------------------------------

### falcon512padded

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/falcon.md

Falcon instance with n=512, producing fixed-length signatures (690 bytes). Preferred when fixed-length signatures are required.

```APIDOC
## falcon512padded

### Description
A `Falcon` instance implementing Falcon with n=512, producing fixed-length signatures.

### Type
`Falcon` (extends `Signer`)

### Properties
- `lengths.publicKey`: 897 bytes
- `lengths.secretKey`: 1281 bytes
- `lengths.signature`: 690 bytes (fixed)
- `info.type`: `'falcon'`
- `info.n`: 512

### Methods
Same as `falcon512`.

### Use Case
Preferred when fixed-length signatures are required (e.g., in certificate chains or concatenated key formats).
```

--------------------------------

### KitchenSink_ml_kem768_x25519

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/hybrid.md

A hybrid KEM combining ML-KEM-768 with X25519 using HKDF-SHA256 as the combiner. Supports key generation, encapsulation, and decapsulation.

```APIDOC
## KitchenSink_ml_kem768_x25519

### Description
A hybrid KEM combining ML-KEM-768 with X25519 using HKDF-SHA256 as the combiner.

### Type
`KEM`

### Alias
`KitchenSinkMLKEM768X25519`

### Properties
Same as `ml_kem768_x25519`

### Example
```ts
import { KitchenSink_ml_kem768_x25519 } from '@noble/post-quantum/hybrid.js';

const { secretKey, publicKey } = KitchenSink_ml_kem768_x25519.keygen();
const { cipherText, sharedSecret } = KitchenSink_ml_kem768_x25519.encapsulate(publicKey);
const recovered = KitchenSink_ml_kem768_x25519.decapsulate(cipherText, secretKey);
```
```

--------------------------------

### ml_kem1024

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/ml-kem.md

A KEM instance implementing ML-KEM with security parameter k=4, suitable for Category 5 (256-bit equivalent) security. Recommended for long-term security. Supports key generation, public key retrieval, encapsulation, and decapsulation.

```APIDOC
## ml_kem1024.keygen

### Description
Generates a new key pair for ML-KEM.

### Method Signature
`keygen(seed?: Uint8Array): { secretKey: Uint8Array; publicKey: Uint8Array }`

### Parameters
- **seed** (Uint8Array) - Optional - A seed for deterministic key generation. If not provided, a random seed is used.

### Returns
An object containing the `secretKey` and `publicKey`.

## ml_kem1024.getPublicKey

### Description
Derives the public key from a given secret key.

### Method Signature
`getPublicKey(secretKey: Uint8Array): Uint8Array`

### Parameters
- **secretKey** (Uint8Array) - Required - The secret key.

### Returns
The corresponding public key.

## ml_kem1024.encapsulate

### Description
Encapsulates a shared secret using the recipient's public key, producing a ciphertext and the shared secret.

### Method Signature
`encapsulate(publicKey: Uint8Array, msg?: Uint8Array): { cipherText: Uint8Array; sharedSecret: Uint8Array }`

### Parameters
- **publicKey** (Uint8Array) - Required - The recipient's public key.
- **msg** (Uint8Array) - Optional - A message to be encapsulated with the shared secret.

### Returns
An object containing the `cipherText` and the `sharedSecret`.

## ml_kem1024.decapsulate

### Description
Decapsulates a ciphertext using the recipient's secret key to recover the shared secret.

### Method Signature
`decapsulate(cipherText: Uint8Array, secretKey: Uint8Array): Uint8Array`

### Parameters
- **cipherText** (Uint8Array) - Required - The ciphertext to decapsulate.
- **secretKey** (Uint8Array) - Required - The recipient's secret key.

### Returns
The recovered shared secret.
```

--------------------------------

### ml_dsa44

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/ml-dsa.md

A DSA instance implementing ML-DSA with security parameters K=4, L=4. It offers key generation, public key retrieval, signing, and verification methods.

```APIDOC
## ml_dsa44

### Description
A `DSA` instance implementing ML-DSA with security parameters K=4, L=4, suitable for Category 2 (theoretical equivalent) security.

### Properties
- `lengths.seed`: 32 bytes
- `lengths.publicKey`: 1312 bytes
- `lengths.secretKey`: 2560 bytes
- `lengths.signature`: 2420 bytes
- `lengths.signRand`: 32 bytes (internal)
- `info.type`: `'ml-dsa'`
- `internal`: Access to internal signing/verification with raw message handling

### Methods
- `keygen(seed?: Uint8Array): { secretKey: Uint8Array; publicKey: Uint8Array }`
- `getPublicKey(secretKey: Uint8Array): Uint8Array`
- `sign(msg: Uint8Array, secretKey: Uint8Array, opts?: SigOpts): Uint8Array`
- `verify(sig: Uint8Array, msg: Uint8Array, publicKey: Uint8Array, opts?: VerOpts): boolean`

### Example
```ts
import { ml_dsa44 } from '@noble/post-quantum/ml-dsa.js';

const seed = new Uint8Array(32);
const { secretKey, publicKey } = ml_dsa44.keygen(seed);

const msg = new TextEncoder().encode('hello world');
const sig = ml_dsa44.sign(msg, secretKey);
const isValid = ml_dsa44.verify(sig, msg, publicKey);
console.log(isValid); // true
```
```

--------------------------------

### Hybrid Construction Imports

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/overview.md

Imports pre-built hybrid cryptographic instances and factory functions for creating custom hybrid constructions. Supports combinations of ML-KEM with X25519, P-256, and P-384, along with various combiners.

```typescript
import {
  ml_kem768_x25519, ml_kem768_p256, ml_kem1024_p384,
  KitchenSink_ml_kem768_x25519, XWing,
  QSF_ml_kem768_p256, QSF_ml_kem1024_p384,
  ecdhKem, ecSigner, expandSeedXof, combineKEMS, combineSigners, QSF, createKitchenSink
} from '@noble/post-quantum/hybrid.js';
import { type Combiner, type ExpandSeed } from '@noble/post-quantum/hybrid.js';
```

--------------------------------

### ML-KEM Predefined Parameter Sets

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/ml-kem.md

Provides a record of KEMParam configurations for different security levels (512, 768, 1024). These presets are keyed by their security parameter and are ready for use with ML-KEM operations.

```typescript
export const PARAMS: Record<string, KEMParam> = {
  512: { N: 256, K: 2, Q: 3329, ETA1: 3, ETA2: 2, du: 10, dv: 4, RBGstrength: 128 },
  768: { N: 256, K: 3, Q: 3329, ETA1: 2, ETA2: 2, du: 10, dv: 4, RBGstrength: 192 },
  1024: { N: 256, K: 4, Q: 3329, ETA1: 2, ETA2: 2, du: 11, dv: 5, RBGstrength: 256 },
};
```

--------------------------------

### Format Message for Signing/Verification

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/utils.md

Use `getMessage` to format a message with optional context before signing or verification. It ensures the message is in the correct byte format.

```typescript
export function getMessage(msg: TArg<Uint8Array>, ctx?: TArg<Uint8Array>): TRet<Uint8Array>
```

--------------------------------

### expandSeedXof

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/hybrid.md

Creates a seed expansion function using an extendable output function (XOF).

```APIDOC
## expandSeedXof

### Description
Creates a seed expansion function using an extendable output function (XOF).

### Method Signature
```ts
export function expandSeedXof(xof: CHashXOF): ExpandSeed
```

### Parameters
#### Path Parameters
- **xof** (CHashXOF) - Required - Hash function with XOF capability (e.g., shake256)

### Returns
A function that expands a seed to a requested length. Type: `ExpandSeed = (seed: Uint8Array, len: number) => Uint8Array`

### Example
```ts
import { shake256 } from '@noble/hashes/sha3.js';
import { expandSeedXof } from '@noble/post-quantum/hybrid.js';

const expandSeed = expandSeedXof(shake256);
const expanded = expandSeed(new Uint8Array(32), 64);
```
```

--------------------------------

### GetContext

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/types.md

A factory function type that creates SLH-DSA hash contexts based on provided SphincsOpts.

```APIDOC
## GetContext

Factory function for creating SLH-DSA hash contexts.

```ts
export type GetContext = (
  opts: SphincsOpts
) => (pub_seed: Uint8Array, sk_seed?: Uint8Array) => Context;
```
```

--------------------------------

### ML-KEM API

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/overview.md

Provides interfaces for ML-KEM (Module Learning With Errors Key Encapsulation Mechanism) with three key sizes: 512, 768, and 1024 bits.

```APIDOC
## ML-KEM Operations

### Key Generation

Generates a public and secret key pair.

- **Method:** `keygen(seed?: Uint8Array): { secretKey, publicKey }`
- **Parameters:**
  - `seed` (Uint8Array, Optional): A seed for deterministic key generation.
- **Returns:** An object containing `secretKey` and `publicKey`.

### Get Public Key

Derives the public key from a secret key.

- **Method:** `getPublicKey(secretKey: Uint8Array): Uint8Array`
- **Parameters:**
  - `secretKey` (Uint8Array): The secret key.
- **Returns:** The corresponding public key.

### Encapsulation

Encapsulates a message to generate a ciphertext and a shared secret.

- **Method:** `encapsulate(publicKey: Uint8Array, msg?: Uint8Array): { cipherText, sharedSecret }`
- **Parameters:**
  - `publicKey` (Uint8Array): The recipient's public key.
  - `msg` (Uint8Array, Optional): A message to encapsulate.
- **Returns:** An object containing `cipherText` and `sharedSecret`.

### Decapsulation

Decapsulates a ciphertext to recover the shared secret.

- **Method:** `decapsulate(cipherText: Uint8Array, secretKey: Uint8Array): Uint8Array`
- **Parameters:**
  - `cipherText` (Uint8Array): The ciphertext to decapsulate.
  - `secretKey` (Uint8Array): The recipient's secret key.
- **Returns:** The recovered shared secret.
```

--------------------------------

### Enable Tree-Shaking with Specific Imports

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/INDEX.md

To ensure efficient tree-shaking, always import specific algorithms from their respective submodules rather than from the root of the library.

```typescript
// ❌ Prevents tree-shaking
import * from '@noble/post-quantum';

// ✅ Enables tree-shaking
import { ml_kem768 } from '@noble/post-quantum/ml-kem.js';
```

--------------------------------

### SphincsOpts

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/types.md

Configuration options for SLH-DSA parameter sets. It defines security parameters, Winternitz parameter, hypertree height and layers, and FORS tree parameters.

```APIDOC
## SphincsOpts

Parameter set configuration for SLH-DSA.

```ts
export type SphincsOpts = {
  N: number;              // Security parameter in bytes (16, 24, 32)
  W: number;              // Winternitz parameter (always 16)
  H: number;              // Total hypertree height
  D: number;              // Number of hypertree layers
  K: number;              // Number of FORS trees
  A: number;              // Height of each FORS tree
  securityLevel: number;  // Security level in bits (128, 192, 256)
};
```

**PARAMS presets:**
- `PARAMS['128f']`: N=16, W=16, H=66, D=22, K=33, A=6, securityLevel=128
- `PARAMS['128s']`: N=16, W=16, H=63, D=7, K=14, A=12, securityLevel=128
- `PARAMS['192f']`: N=24, W=16, H=66, D=22, K=33, A=8, securityLevel=192
- `PARAMS['192s']`: N=24, W=16, H=63, D=7, K=17, A=14, securityLevel=192
- `PARAMS['256f']`: N=32, W=16, H=68, D=17, K=35, A=9, securityLevel=256
- `PARAMS['256s']`: N=32, W=16, H=64, D=8, K=22, A=14, securityLevel=256
```

--------------------------------

### Falcon Signer Interface

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/falcon.md

The Falcon interface extends the base `Signer` interface and provides methods for key generation, signing, and verification, along with Falcon-specific information.

```APIDOC
## Falcon Interface

### Description
Provides methods for key generation, signing, and verification using the Falcon algorithm. It also includes Falcon-specific information such as the algorithm type and parameter `n`.

### Methods
- `keygen(seed?: Uint8Array): { secretKey: Uint8Array; publicKey: Uint8Array }`: Generates a new secret and public key pair. An optional seed can be provided for deterministic key generation.
- `getPublicKey(secretKey: Uint8Array): Uint8Array`: Derives the public key from a given secret key.
- `sign(msg: Uint8Array, secretKey: Uint8Array, opts?: SigOpts): Uint8Array`: Signs a message using the provided secret key and optional signing options.
- `verify(sig: Uint8Array, msg: Uint8Array, publicKey: Uint8Array, opts?: VerOpts): boolean`: Verifies a signature against a message and public key, using optional verification options.

### Properties
- `lengths: { publicKey: number; secretKey: number; signature: number }`: An object containing the byte lengths for public keys, secret keys, and signatures.
- `info: { type: 'falcon'; n: 512 | 1024 }`: Information about the Falcon instance, specifying the type as 'falcon' and the parameter `n` (either 512 or 1024).

### Signing Options (`SigOpts`)
- `extraEntropy` (Uint8Array | false): Optional extra entropy for randomized signing. `false` disables randomization. Default is random.
- `context` (Uint8Array): Optional application-defined context string.
```

--------------------------------

### ml_kem512

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/ml-kem.md

A KEM instance implementing ML-KEM with security parameter k=2, suitable for Category 1 (128-bit equivalent) security. Supports key generation, public key retrieval, encapsulation, and decapsulation.

```APIDOC
## ml_kem512.keygen

### Description
Generates a new key pair for ML-KEM.

### Method Signature
`keygen(seed?: Uint8Array): { secretKey: Uint8Array; publicKey: Uint8Array }`

### Parameters
- **seed** (Uint8Array) - Optional - A seed for deterministic key generation. If not provided, a random seed is used.

### Returns
An object containing the `secretKey` and `publicKey`.

## ml_kem512.getPublicKey

### Description
Derives the public key from a given secret key.

### Method Signature
`getPublicKey(secretKey: Uint8Array): Uint8Array`

### Parameters
- **secretKey** (Uint8Array) - Required - The secret key.

### Returns
The corresponding public key.

## ml_kem512.encapsulate

### Description
Encapsulates a shared secret using the recipient's public key, producing a ciphertext and the shared secret.

### Method Signature
`encapsulate(publicKey: Uint8Array, msg?: Uint8Array): { cipherText: Uint8Array; sharedSecret: Uint8Array }`

### Parameters
- **publicKey** (Uint8Array) - Required - The recipient's public key.
- **msg** (Uint8Array) - Optional - A message to be encapsulated with the shared secret.

### Returns
An object containing the `cipherText` and the `sharedSecret`.

## ml_kem512.decapsulate

### Description
Decapsulates a ciphertext using the recipient's secret key to recover the shared secret.

### Method Signature
`decapsulate(cipherText: Uint8Array, secretKey: Uint8Array): Uint8Array`

### Parameters
- **cipherText** (Uint8Array) - Required - The ciphertext to decapsulate.
- **secretKey** (Uint8Array) - Required - The recipient's secret key.

### Returns
The recovered shared secret.
```

--------------------------------

### ml_dsa65

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/ml-dsa.md

A DSA instance implementing ML-DSA with security parameters K=6, L=5, suitable for Category 3 (192-bit equivalent) security. This is the most commonly recommended variant.

```APIDOC
## ml_dsa65

### Description
A `DSA` instance implementing ML-DSA with security parameters K=6, L=5, suitable for Category 3 (192-bit equivalent) security. This is the most commonly recommended variant.

### Properties
- `lengths.seed`: 32 bytes
- `lengths.publicKey`: 1952 bytes
- `lengths.secretKey`: 4032 bytes
- `lengths.signature`: 3309 bytes
- `lengths.signRand`: 32 bytes
- `info.type`: `'ml-dsa'`

### Methods
Same as ml_dsa44

### Example
```ts
import { ml_dsa65 } from '@noble/post-quantum/ml-dsa.js';
import { randomBytes } from '@noble/post-quantum/utils.js';

// Generate keypair (random seed generated if not provided)
const { secretKey, publicKey } = ml_dsa65.keygen();

// Sign a message
const msg = new TextEncoder().encode('message to sign');
const sig = ml_dsa65.sign(msg, secretKey);

// Verify with context option
const isValid = ml_dsa65.verify(sig, msg, publicKey, { context: new Uint8Array([1, 2]) });
console.log(isValid);

// Get public key from secret key
const pk = ml_dsa65.getPublicKey(secretKey);
```
```

--------------------------------

### Noble Post-Quantum Type System Explanation

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/overview.md

Explains the `TArg<T>` and `TRet<T>` types used for input and output in public functions, ensuring TypeScript compatibility and flexible byte input.

```typescript
TArg<T>  // Accepts T and compatible input forms
TRet<T>  // Returns T in normalized form

// Example: ml_kem768.keygen()
keygen(seed?: TArg<Uint8Array>): { 
  secretKey: TRet<Uint8Array>; 
  publicKey: TRet<Uint8Array> 
}
```

--------------------------------

### ML-KEM Imports and Constants

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/overview.md

Imports necessary functions and constants for ML-KEM with different key sizes. ML-KEM offers three key sizes: 512 (128-bit), 768 (192-bit), and 1024 (256-bit).

```typescript
import { ml_kem512, ml_kem768, ml_kem1024 } from '@noble/post-quantum/ml-kem.js';
import { PARAMS } from '@noble/post-quantum/ml-kem.js';
import { type KEMParam } from '@noble/post-quantum/ml-kem.js';
```

--------------------------------

### Signing Options Interface

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/README.md

Defines optional parameters for signing operations, including domain separation context and extra entropy for determinism.

```typescript
interface SigOpts {
  context?: Uint8Array;              // Domain separation
  extraEntropy?: Uint8Array | false; // Extra randomness or deterministic
}
```

--------------------------------

### Hybrid API

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/overview.md

Provides pre-built hybrid cryptographic instances combining ML-KEM with various elliptic curve cryptography (ECC) schemes, and factory functions for custom constructions.

```APIDOC
## Hybrid Cryptography

This module offers pre-built hybrid cryptographic instances and factory functions to create custom constructions. It combines ML-KEM with ECC schemes like X25519, P-256, and P-384, and supports various combiners.
```

--------------------------------

### baswap64If

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/utils.md

Conditionally swaps 64-bit lanes based on host endianness. Primarily used internally for cross-architecture compatibility.

```APIDOC
## baswap64If

### Description
Conditionally swaps 64-bit lanes based on host endianness.

### Method
`export const baswap64If: <T extends ArrayBufferView>(arr: T) => T`

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Parameters
- **arr** (`ArrayBufferView`) - Required - Buffer to normalize

### Returns
The same buffer (swapped on big-endian, unchanged on little-endian).

### Note
Used internally by Falcon to normalize float tables across architectures.

### Example
```ts
import { baswap64If } from '@noble/post-quantum/utils.js';

const buf = new Uint8Array(16);
baswap64If(buf); // swaps if host is big-endian
```
```

--------------------------------

### Establish Shared Secret with ML-KEM

Source: https://github.com/paulmillr/noble-post-quantum/blob/main/_autodocs/overview.md

Alice generates a keypair, Bob encapsulates a shared secret to Alice using her public key, and Alice decapsulates it using her secret key. Both should arrive at the same shared secret.

```typescript
import { ml_kem768 } from '@noble/post-quantum/ml-kem.js';

// Alice generates keypair
const { secretKey: aliceSecret, publicKey: alicePublic } = ml_kem768.keygen();

// Bob encapsulates to Alice
const { cipherText, sharedSecret: bobSecret } = ml_kem768.encapsulate(alicePublic);

// Alice decapsulates
const aliceSecret = ml_kem768.decapsulate(cipherText, aliceSecret);

// Both have same shared secret
console.assert(bobSecret === aliceSecret);
```