import { ed25519 } from '@noble/curves/ed25519.js' import * as Bytes from './Bytes.js' import * as Errors from './Errors.js' import * as Hash from './Hash.js' import * as Hex from './Hex.js' import * as engine from './internal/ed25519.js' import * as keyDerivation from './internal/keyDerivation.js' import * as mnemonic_ from './internal/mnemonic.js' /** Re-export of noble/curves Ed25519 utilities. */ export const noble = ed25519 /** * Creates a new Ed25519 key pair consisting of a private key and its corresponding public key. * * @example * ```ts twoslash * import { Ed25519 } from 'ox' * * const { privateKey, publicKey } = Ed25519.createKeyPair() * ``` * * @param options - The options to generate the key pair. * @returns The generated key pair containing both private and public keys. */ export function createKeyPair( options: createKeyPair.Options = {}, ): createKeyPair.ReturnType { const { as = 'Hex' } = options const privateKey = randomPrivateKey({ as }) const publicKey = getPublicKey({ privateKey, as }) return { privateKey: privateKey as never, publicKey: publicKey as never, } } export declare namespace createKeyPair { type Options = { /** * Format of the returned private and public keys. * @default 'Hex' */ as?: as | 'Hex' | 'Bytes' | undefined } type ReturnType = { privateKey: | (as extends 'Bytes' ? Bytes.Bytes : never) | (as extends 'Hex' ? Hex.Hex : never) publicKey: | (as extends 'Bytes' ? Bytes.Bytes : never) | (as extends 'Hex' ? Hex.Hex : never) } type ErrorType = | Hex.fromBytes.ErrorType | randomPrivateKey.ErrorType | getPublicKey.ErrorType | Errors.GlobalErrorType } /** * Derives an Ed25519 private key from a 32-byte WebAuthn PRF output. * * The permanent derivation contract uses the PRF output as the HMAC-SHA256 * key. The HMAC message uses the `ox.ed25519.fromPrf.v1` domain followed by a * 32-bit big-endian counter set to zero. * * @example * ```ts twoslash * import { Ed25519 } from 'ox' * * const privateKey = Ed25519.fromPrf( * '0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f' * ) * ``` * * @param value - A 32-byte WebAuthn PRF output. * @param options - Options. * @returns An Ed25519 private key. */ export function fromPrf( value: Hex.Hex | Bytes.Bytes, options: fromPrf.Options = {}, ): fromPrf.ReturnType { const { as = 'Hex' } = options const bytes = Bytes.from(value) if (bytes.length !== 32) throw new InvalidPrfSizeError({ size: bytes.length }) const privateKey = Hash.hmac256( bytes, Bytes.concat(fromPrfDomain, Bytes.fromNumber(0, { size: 4 })), { as: 'Bytes' }, ) if (as === 'Hex') { const value = Hex.fromBytes(privateKey) privateKey.fill(0) return value as never } return privateKey as never } export declare namespace fromPrf { type Options = { /** * Format of the returned private key. * @default 'Hex' */ as?: as | 'Hex' | 'Bytes' | undefined } type ReturnType = | (as extends 'Bytes' ? Bytes.Bytes : never) | (as extends 'Hex' ? Hex.Hex : never) type ErrorType = | Bytes.concat.ErrorType | Bytes.from.ErrorType | Bytes.fromNumber.ErrorType | Hash.hmac256.ErrorType | Hex.fromBytes.ErrorType | InvalidPrfSizeError | Errors.GlobalErrorType } /** * Derives an Ed25519 private key from a BIP-39 mnemonic. * * This is equivalent to passing `Mnemonic.toSeed(mnemonic, { passphrase })` * to {@link ox#Ed25519.fromSeed}. * * @example * ```ts twoslash * import { Ed25519 } from 'ox' * * const privateKey = Ed25519.fromMnemonic( * 'test test test test test test test test test test test junk' * ) * ``` * * @param mnemonic - BIP-39 mnemonic phrase. * @param options - Options. * @returns An Ed25519 private key. */ export function fromMnemonic( mnemonic: string, options: fromMnemonic.Options = {}, ): fromMnemonic.ReturnType { const { passphrase } = options const seed = mnemonic_.toSeed(mnemonic, passphrase) try { return fromSeed(seed, options) } finally { seed.fill(0) } } export declare namespace fromMnemonic { type Options = { /** * Format of the returned private key. * @default 'Hex' */ as?: as | 'Hex' | 'Bytes' | undefined /** Optional BIP-39 passphrase. */ passphrase?: string | undefined } type ReturnType = fromSeed.ReturnType type ErrorType = fromSeed.ErrorType } /** * Derives an Ed25519 private key from a seed. * * The seed must contain at least 32 bytes of cryptographically strong key * material. Do not pass a password directly; use a password KDF first. * * The permanent derivation contract uses the seed as the HMAC-SHA256 * key. The HMAC message uses the `ox.ed25519.fromSeed.v1` domain followed by a * 32-bit big-endian counter set to zero. * * @example * ```ts twoslash * import { Ed25519 } from 'ox' * * const privateKey = Ed25519.fromSeed( * '0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f' * ) * ``` * * @param seed - Seed containing at least 32 bytes of cryptographically strong key material. * @param options - Options. * @returns An Ed25519 private key. */ export function fromSeed( seed: Hex.Hex | Bytes.Bytes, options: fromSeed.Options = {}, ): fromSeed.ReturnType { const { as = 'Hex' } = options const bytes = Bytes.from(seed) if (bytes.length < 32) throw new InvalidSeedSizeError({ size: bytes.length }) const privateKey = keyDerivation.derive(bytes, fromSeedDomain) if (as === 'Hex') { const value = Hex.fromBytes(privateKey) privateKey.fill(0) return value as never } return privateKey as never } export declare namespace fromSeed { type Options = { /** * Format of the returned private key. * @default 'Hex' */ as?: as | 'Hex' | 'Bytes' | undefined } type ReturnType = | (as extends 'Bytes' ? Bytes.Bytes : never) | (as extends 'Hex' ? Hex.Hex : never) type ErrorType = | Bytes.from.ErrorType | Hex.fromBytes.ErrorType | keyDerivation.derive.ErrorType | InvalidSeedSizeError | Errors.GlobalErrorType } /** * Computes the Ed25519 public key from a provided private key. * * @example * ```ts twoslash * import { Ed25519 } from 'ox' * * const publicKey = Ed25519.getPublicKey({ * privateKey: '0x...' * }) * ``` * * @param options - The options to compute the public key. * @returns The computed public key. */ export function getPublicKey( options: getPublicKey.Options, ): getPublicKey.ReturnType { const { as = 'Hex', privateKey } = options const privateKeyBytes = Bytes.from(privateKey) const publicKeyBytes = engine.getPublicKey(privateKeyBytes) if (as === 'Hex') return Hex.fromBytes(publicKeyBytes) as never return publicKeyBytes as never } export declare namespace getPublicKey { type Options = { /** * Format of the returned public key. * @default 'Hex' */ as?: as | 'Hex' | 'Bytes' | undefined /** * Private key to compute the public key from. */ privateKey: Hex.Hex | Bytes.Bytes } type ReturnType = | (as extends 'Bytes' ? Bytes.Bytes : never) | (as extends 'Hex' ? Hex.Hex : never) type ErrorType = | Bytes.from.ErrorType | Hex.fromBytes.ErrorType | Errors.GlobalErrorType } /** * Generates a random Ed25519 private key. * * @example * ```ts twoslash * import { Ed25519 } from 'ox' * * const privateKey = Ed25519.randomPrivateKey() * ``` * * @param options - The options to generate the private key. * @returns The generated private key. */ export function randomPrivateKey( options: randomPrivateKey.Options = {}, ): randomPrivateKey.ReturnType { const { as = 'Hex' } = options const bytes = engine.randomSecretKey() if (as === 'Hex') return Hex.fromBytes(bytes) as never return bytes as never } export declare namespace randomPrivateKey { type Options = { /** * Format of the returned private key. * @default 'Hex' */ as?: as | 'Hex' | 'Bytes' | undefined } type ReturnType = | (as extends 'Bytes' ? Bytes.Bytes : never) | (as extends 'Hex' ? Hex.Hex : never) type ErrorType = Hex.fromBytes.ErrorType | Errors.GlobalErrorType } /** * Signs the payload with the provided private key and returns an Ed25519 signature. * * @example * ```ts twoslash * import { Ed25519 } from 'ox' * * const signature = Ed25519.sign({ * // [!code focus] * payload: '0xdeadbeef', // [!code focus] * privateKey: '0x...' // [!code focus] * }) // [!code focus] * ``` * * @param options - The signing options. * @returns The Ed25519 signature. */ export function sign( options: sign.Options, ): sign.ReturnType { const { as = 'Hex', payload, privateKey } = options const payloadBytes = Bytes.from(payload) const privateKeyBytes = Bytes.from(privateKey) const signatureBytes = engine.sign(payloadBytes, privateKeyBytes) if (as === 'Hex') return Hex.fromBytes(signatureBytes) as never return signatureBytes as never } export declare namespace sign { type Options = { /** * Format of the returned signature. * @default 'Hex' */ as?: as | 'Hex' | 'Bytes' | undefined /** * Payload to sign. */ payload: Hex.Hex | Bytes.Bytes /** * Ed25519 private key. */ privateKey: Hex.Hex | Bytes.Bytes } type ReturnType = | (as extends 'Bytes' ? Bytes.Bytes : never) | (as extends 'Hex' ? Hex.Hex : never) type ErrorType = | Bytes.from.ErrorType | Hex.fromBytes.ErrorType | Errors.GlobalErrorType } /** * Verifies a payload was signed by the provided public key. * * @example * ```ts twoslash * import { Ed25519 } from 'ox' * * const { privateKey, publicKey } = Ed25519.createKeyPair() * const signature = Ed25519.sign({ * payload: '0xdeadbeef', * privateKey * }) * * const verified = Ed25519.verify({ * // [!code focus] * publicKey, // [!code focus] * payload: '0xdeadbeef', // [!code focus] * signature // [!code focus] * }) // [!code focus] * ``` * * @param options - The verification options. * @returns Whether the payload was signed by the provided public key. */ export function verify(options: verify.Options): boolean { const { payload, publicKey, signature } = options const payloadBytes = Bytes.from(payload) const publicKeyBytes = Bytes.from(publicKey) const signatureBytes = Bytes.from(signature) return engine.verify(signatureBytes, payloadBytes, publicKeyBytes) } export declare namespace verify { type Options = { /** Payload that was signed. */ payload: Hex.Hex | Bytes.Bytes /** Public key that signed the payload. */ publicKey: Hex.Hex | Bytes.Bytes /** Signature of the payload. */ signature: Hex.Hex | Bytes.Bytes } type ErrorType = Bytes.from.ErrorType | Errors.GlobalErrorType } /** * Converts an Ed25519 public key to an X25519 public key. * * This is useful for performing X25519 Diffie-Hellman key exchange * using an Ed25519 signing key pair. * * @example * ```ts twoslash * import { Ed25519, X25519 } from 'ox' * * const { privateKey, publicKey } = Ed25519.createKeyPair() * * const x25519PublicKey = Ed25519.toX25519PublicKey({ * publicKey * }) * ``` * * @param options - The options. * @returns The X25519 public key. */ export function toX25519PublicKey( options: toX25519PublicKey.Options, ): toX25519PublicKey.ReturnType { const { as = 'Hex', publicKey } = options const publicKeyBytes = Bytes.from(publicKey) const x25519PublicKeyBytes = engine.toMontgomery(publicKeyBytes) if (as === 'Hex') return Hex.fromBytes(x25519PublicKeyBytes) as never return x25519PublicKeyBytes as never } export declare namespace toX25519PublicKey { type Options = { /** * Format of the returned public key. * @default 'Hex' */ as?: as | 'Hex' | 'Bytes' | undefined /** Ed25519 public key to convert. */ publicKey: Hex.Hex | Bytes.Bytes } type ReturnType = | (as extends 'Bytes' ? Bytes.Bytes : never) | (as extends 'Hex' ? Hex.Hex : never) type ErrorType = | Bytes.from.ErrorType | Hex.fromBytes.ErrorType | Errors.GlobalErrorType } /** * Converts an Ed25519 private key to an X25519 private key. * * This is useful for performing X25519 Diffie-Hellman key exchange * using an Ed25519 signing key pair. * * @example * ```ts twoslash * import { Ed25519, X25519 } from 'ox' * * const { privateKey, publicKey } = Ed25519.createKeyPair() * * const x25519PrivateKey = Ed25519.toX25519PrivateKey({ * privateKey * }) * ``` * * @param options - The options. * @returns The X25519 private key. */ export function toX25519PrivateKey( options: toX25519PrivateKey.Options, ): toX25519PrivateKey.ReturnType { const { as = 'Hex', privateKey } = options const privateKeyBytes = Bytes.from(privateKey) const x25519PrivateKeyBytes = engine.toMontgomerySecret(privateKeyBytes) if (as === 'Hex') return Hex.fromBytes(x25519PrivateKeyBytes) as never return x25519PrivateKeyBytes as never } export declare namespace toX25519PrivateKey { type Options = { /** * Format of the returned private key. * @default 'Hex' */ as?: as | 'Hex' | 'Bytes' | undefined /** Ed25519 private key to convert. */ privateKey: Hex.Hex | Bytes.Bytes } type ReturnType = | (as extends 'Bytes' ? Bytes.Bytes : never) | (as extends 'Hex' ? Hex.Hex : never) type ErrorType = | Bytes.from.ErrorType | Hex.fromBytes.ErrorType | Errors.GlobalErrorType } /** Thrown when a WebAuthn PRF output is not 32 bytes. */ export class InvalidPrfSizeError extends Errors.BaseError { override readonly name = 'Ed25519.InvalidPrfSizeError' constructor(options: InvalidPrfSizeError.Options) { super( `PRF output must be exactly 32 bytes. Received ${options.size} bytes.`, ) } } export declare namespace InvalidPrfSizeError { /** Options for {@link ox#Ed25519.InvalidPrfSizeError}. */ type Options = { /** Received PRF output size. */ size: number } } /** Thrown when a seed contains fewer than 32 bytes. */ export class InvalidSeedSizeError extends Errors.BaseError { override readonly name = 'Ed25519.InvalidSeedSizeError' constructor(options: InvalidSeedSizeError.Options) { super( `Seed must contain at least 32 bytes. Received ${options.size} bytes.`, ) } } export declare namespace InvalidSeedSizeError { /** Options for {@link ox#Ed25519.InvalidSeedSizeError}. */ type Options = { /** Received seed size. */ size: number } } const fromPrfDomain = Bytes.fromString('ox.ed25519.fromPrf.v1') const fromSeedDomain = Bytes.fromString('ox.ed25519.fromSeed.v1')