Low-level X25519 Operations

/**
 * Generate a random X25519 key pair using secure random number generation
 * @param prng - Optional random source, uses system random if not provided
 * @returns KeyPair containing public and secret keys
 */
function generateKeyPair(prng?: RandomSource): KeyPair;

/**
 * Generate deterministic X25519 key pair from a 32-byte seed
 * @param seed - 32-byte seed for deterministic key generation
 * @returns KeyPair containing public and secret keys
 * @throws Error if seed length is not 32 bytes
 */
function generateKeyPairFromSeed(seed: Uint8Array): KeyPair;

import { generateKeyPair, generateKeyPairFromSeed } from "@stablelib/x25519";

// Generate random key pair
const keyPair = generateKeyPair();
console.log("Public key length:", keyPair.publicKey.length); // 32
console.log("Secret key length:", keyPair.secretKey.length); // 32

// Generate deterministic key pair from seed
const seed = new Uint8Array(32); // Fill with your seed data
const deterministicKeyPair = generateKeyPairFromSeed(seed);

/**
 * Compute shared secret using X25519 key agreement
 * @param mySecretKey - Your 32-byte secret key
 * @param theirPublicKey - Peer's 32-byte public key
 * @param rejectZero - If true, throws error when shared key is all-zero
 * @returns 32-byte shared secret (MUST be processed through KDF before use)
 * @throws Error if key lengths are incorrect or shared key is zero (when rejectZero=true)
 * 
 * IMPORTANT: The returned key is raw scalar multiplication output and MUST be
 * processed through a key derivation function before use as encryption keys.
 */
function sharedKey(
  mySecretKey: Uint8Array, 
  theirPublicKey: Uint8Array, 
  rejectZero?: boolean
): Uint8Array;

import { generateKeyPair, sharedKey } from "@stablelib/x25519";

// Both parties generate key pairs
const alice = generateKeyPair();
const bob = generateKeyPair();

// Compute shared secrets (both will be identical)
const aliceShared = sharedKey(alice.secretKey, bob.publicKey);
const bobShared = sharedKey(bob.secretKey, alice.publicKey);

// Shared secrets are equal
console.log("Secrets match:", 
  aliceShared.every((byte, i) => byte === bobShared[i])); // true

// Reject all-zero shared keys (recommended for protocols)
try {
  const safeShared = sharedKey(alice.secretKey, bob.publicKey, true);
} catch (error) {
  console.log("Invalid shared key detected");
}

/**
 * Perform scalar multiplication on Curve25519
 * @param n - 32-byte scalar value
 * @param p - 32-byte point on the curve
 * @returns 32-byte result of scalar multiplication
 */
function scalarMult(n: Uint8Array, p: Uint8Array): Uint8Array;

/**
 * Scalar multiplication by the base point (generator)
 * @param n - 32-byte scalar value
 * @returns 32-byte public key corresponding to the scalar
 */
function scalarMultBase(n: Uint8Array): Uint8Array;

import { scalarMult, scalarMultBase } from "@stablelib/x25519";

// Generate public key from private key
const privateKey = new Uint8Array(32); // Your private key
const publicKey = scalarMultBase(privateKey);

// Generic scalar multiplication
const scalar = new Uint8Array(32); // Your scalar
const point = new Uint8Array(32);  // Point on the curve
const result = scalarMult(scalar, point);

/** Length of X25519 public keys in bytes */
const PUBLIC_KEY_LENGTH: 32;

/** Length of X25519 secret keys in bytes */
const SECRET_KEY_LENGTH: 32;

/** Length of X25519 shared keys in bytes */
const SHARED_KEY_LENGTH: 32;

/** X25519 key pair containing public and secret keys */
interface KeyPair {
  /** 32-byte public key */
  publicKey: Uint8Array;
  /** 32-byte secret key */
  secretKey: Uint8Array;
}

/** Interface for secure random number generation */
interface RandomSource {
  /** Generate random bytes of specified length */
  randomBytes(length: number): Uint8Array;
  /** Indicates if the random source is available */
  isAvailable: boolean;
}