skills/docs/security-stack/crypto/crypto-curve/src/primitives/x25519/x25519.md

x25519

(no submodules)

• x25519.native — (no submodules)- x25519.noble — (no submodules) - x25519.noble — (no submodules)- x25519.select — (no submodules) - x25519.select — (no submodules)- x25519 — (no submodules)- x25519.native — _(no submod…
• x25519.native — (no submodules)- x25519.noble — (no submodules)- x25519.noble — (no submodules)- x25519.select — (no submodules)- x25519.select — (no submodules)- x25519 — (no submodules)- x25519.native — (no submodules)- x25519.noble — (no submodules)- x25519.noble — (no submodules)- x25519.select — (no submodules)- x25519.select — (no submodules)- x25519 — (no submodules)- x25519.native — <!-- begin:a…
• x25519.native — (no submodules)- x25519.noble — (no submodules)- x25519.noble — (no submodules)- x25519.select — (no submodules)- x25519.select — (no submodules)- x25519 — (no submodules)- x25519.native — _(no submo…
• x25519.native — (no submodules)- x25519.noble — (no submodules) - x25519.noble — (no submodules)- x25519.select — (no submodules) - x25519.select — (no submodules)- x25519 — (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

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

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.