# x25519

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->
  - [x25519.native](./impl/x25519.native/x25519.native.md) — <!-- begin:auto-docs --> _(no submodules)_- [x25519.noble](./impl/x25519.noble/x25519.noble.md) — <!-- begin:auto-docs --> _(no submodules)_  - [x25519.noble](./impl/x25519.noble/x25519.noble.md) — <!-- begin:auto-docs --> _(no submodules)_- [x25519.select](./x25519.select/x25519.select.md) — <!-- begin:auto-docs --> _(no submodules)_  - [x25519.select](./x25519.select/x25519.select.md) — <!-- begin:auto-docs --> _(no submodules)_- [x25519](./x25519.md) — <!-- begin:auto-docs --> _(no submodules)_- x25519.native — <!-- begin:auto-docs --> _(no submod…
- [x25519.native](./impl/x25519.native/x25519.native.md) — <!-- begin:auto-docs --> _(no submodules)_- [x25519.noble](./impl/x25519.noble/x25519.noble.md) — <!-- begin:auto-docs --> _(no submodules)_- [x25519.noble](./impl/x25519.noble/x25519.noble.md) — <!-- begin:auto-docs --> _(no submodules)_- [x25519.select](./x25519.select/x25519.select.md) — <!-- begin:auto-docs --> _(no submodules)_- [x25519.select](./x25519.select/x25519.select.md) — <!-- begin:auto-docs --> _(no submodules)_- [x25519](./x25519.md) — <!-- begin:auto-docs --> _(no submodules)_- [x25519.native](./impl/x25519.native/x25519.native.md) — <!-- begin:auto-docs --> _(no submodules)_- [x25519.noble](./impl/x25519.noble/x25519.noble.md) — <!-- begin:auto-docs --> _(no submodules)_- [x25519.noble](./impl/x25519.noble/x25519.noble.md) — <!-- begin:auto-docs --> _(no submodules)_- [x25519.select](./x25519.select/x25519.select.md) — <!-- begin:auto-docs --> _(no submodules)_- [x25519.select](./x25519.select/x25519.select.md) — <!-- begin:auto-docs --> _(no submodules)_- [x25519](./x25519.md) — <!-- begin:auto-docs --> _(no submodules)_- x25519.native — <!-- begin:a…
- [x25519.native](./impl/x25519.native/x25519.native.md) — <!-- begin:auto-docs --> _(no submodules)_- [x25519.noble](./impl/x25519.noble/x25519.noble.md) — <!-- begin:auto-docs --> _(no submodules)_- [x25519.noble](./impl/x25519.noble/x25519.noble.md) — <!-- begin:auto-docs --> _(no submodules)_- [x25519.select](./x25519.select/x25519.select.md) — <!-- begin:auto-docs --> _(no submodules)_- [x25519.select](./x25519.select/x25519.select.md) — <!-- begin:auto-docs --> _(no submodules)_- [x25519](./x25519.md) — <!-- begin:auto-docs --> _(no submodules)_- x25519.native — <!-- begin:auto-docs --> _(no submo…
- [x25519.native](./impl/x25519.native/x25519.native.md) — <!-- begin:auto-docs --> _(no submodules)_- [x25519.noble](./impl/x25519.noble/x25519.noble.md) — <!-- begin:auto-docs --> _(no submodules)_  - [x25519.noble](./impl/x25519.noble/x25519.noble.md) — <!-- begin:auto-docs --> _(no submodules)_- [x25519.select](./x25519.select/x25519.select.md) — <!-- begin:auto-docs --> _(no submodules)_  - [x25519.select](./x25519.select/x25519.select.md) — <!-- begin:auto-docs --> _(no submodules)_- [x25519](./x25519.md) — <!-- begin:auto-docs --> _(no submodules)_
## Purpose

`x25519.ts` is the stable public entry point for the X25519 elliptic-curve Diffie-Hellman primitive in `@suaveplan/crypto-curve`. It re-exports everything from `x25519.select.ts`, which forwards to either the Noble-backed or native implementation based on `crypto.config.ts`.

X25519 (RFC 7748) is the Diffie-Hellman function over Curve25519 in Montgomery form. It is the standard for ephemeral key agreement in TLS 1.3, Signal, Noise Protocol, and SSH. Its defining property is that any 32-byte value is a valid private key (no validity check required), and the output is a 32-byte shared secret that must be passed through a KDF before use as a symmetric key.

## Features

- `getPublicKey(privateKey)` — 32-byte Montgomery-form public key (u-coordinate).
- `getSharedSecret(privateKey, peerPublicKey)` — 32-byte raw ECDH output. Must be KDF-processed.
- `randomPrivateKey()` — 32 cryptographically random bytes (any 32-byte value is valid).

## Usage: Basic Example

```ts
import * as x25519 from "@suaveplan/crypto-curve/x25519";

const aliceSk = x25519.randomPrivateKey();
const alicePk = x25519.getPublicKey(aliceSk);

const bobSk = x25519.randomPrivateKey();
const bobPk = x25519.getPublicKey(bobSk);

const aliceShared = x25519.getSharedSecret(aliceSk, bobPk);
const bobShared = x25519.getSharedSecret(bobSk, alicePk);
// aliceShared and bobShared are identical
```

## Usage: Advanced Example

```ts
import * as x25519 from "@suaveplan/crypto-curve/x25519";
import { hkdf } from "@suaveplan/crypto-hash/kdf";
import { zeroize } from "@suaveplan/crypto-utils/zeroize";

// Ephemeral ECDH with HKDF key derivation (Noise XX pattern excerpt).
function deriveSessionKey(
    localSk: Uint8Array,
    remotePk: Uint8Array,
    handshakeHash: Uint8Array
): Uint8Array {
    const rawSecret = x25519.getSharedSecret(localSk, remotePk);
    try {
        return hkdf("SHA-256", rawSecret, {
            salt: handshakeHash,
            info: new TextEncoder().encode("noise-session"),
            length: 32,
        });
    } finally {
        zeroize(rawSecret);
    }
}
```

## API Reference

All symbols re-exported from `x25519.select.ts`:

- `getPublicKey(privateKey: Uint8Array): Uint8Array`
- `getSharedSecret(privateKey: Uint8Array, peerPublicKey: Uint8Array): Uint8Array`
- `randomPrivateKey(): Uint8Array`

## Implementation Notes

This file is a zero-logic re-export barrel. Its sole purpose is the stable import path `@suaveplan/crypto-curve/x25519`. Logic belongs in the implementation files. The raw ECDH output of X25519 is not safe to use directly as a symmetric key — always run it through HKDF or another KDF before using for encryption or MAC operations.