@owlmeans/basic-keys

A core cryptographic library for the OwlMeans Common ecosystem, providing key pair generation, digital signing, encryption, and authentication credential management.

Overview

The @owlmeans/basic-keys package implements the core cryptographic subsystem used primarily by the OwlMeans Authentication Subsystem. It provides a unified API for working with different cryptographic algorithms through an extensible plugin system.

Features

• Key Pair Management: Generate, import, and export cryptographic key pairs
• Digital Signatures: Sign and verify data with ED25519
• Encryption: Encrypt and decrypt data with XChaCha20-Poly1305
• Authentication: Pack and unpack authentication credentials
• Plugin System: Extensible architecture for different cryptographic algorithms
• CLI Tool: Command-line interface for key generation
• Multiple Export Formats: Support for various key export formats

Supported Algorithms

• ED25519: Digital signatures and key derivation
• XChaCha20-Poly1305: Symmetric encryption and decryption

Installation

npm install @owlmeans/basic-keys

Available Exports

The package provides three main export paths:

// Main exports - core functionality
import { makeKeyPairModel, KeyType, fromPubKey, matchAddress, inputToKeyPair, packAuthCredentials, unpackAuthCredentials } from '@owlmeans/basic-keys'

// Plugin exports - cryptographic algorithm implementations  
import { plugins, ed25519Plugin, xChahaPlugin, KeyPlugin } from '@owlmeans/basic-keys/plugins'

// Utility exports - low-level helper functions
import { prepareData, prepareKey, toAddress, assertType } from '@owlmeans/basic-keys/utils'

Quick Start

import { makeKeyPairModel, KeyType } from '@owlmeans/basic-keys'

// Generate a new ED25519 key pair
const keyPair = makeKeyPairModel()

// Sign data
const signature = await keyPair.sign("Hello, World!")

// Verify signature
const isValid = await keyPair.verify("Hello, World!", signature)

// Export keys
const privateKey = keyPair.export()          // "ed25519:base64privatekey"
const publicKey = keyPair.exportPublic()     // "ed25519:base64publickey"
const address = keyPair.exportAddress()      // "ed25519:base58address"

API Reference

Core Types

KeyPair

Represents a cryptographic key pair with metadata.

interface KeyPair {
  privateKey: string  // Base64-encoded private key
  publicKey: string   // Base64-encoded public key
  address: string     // Algorithm-specific address
  type: string        // Algorithm type (e.g., "ed25519", "xchacha")
}

KeyPairModel

A model object that wraps a KeyPair with cryptographic operations.

interface KeyPairModel {
  keyPair?: KeyPair
  sign: (data: unknown) => Promise<string>
  verify: (data: unknown, signature: string) => Promise<boolean>
  export: () => string
  exportPublic: () => string
  exportAddress: () => string
  encrypt: (data: unknown) => Promise<string>
  decrypt: (data: unknown) => Promise<string>
  dcrpt: (data: unknown) => Promise<Uint8Array>
}

Key Functions

makeKeyPairModel(input?)

Creates a KeyPairModel instance.

function makeKeyPairModel(input?: KeyPair | string): KeyPairModel

Parameters:

• input (optional):
  • KeyPair object
  • Algorithm type string (e.g., "ed25519", "xchacha")
  • Encoded private key string (e.g., "ed25519:base64key")

Returns: KeyPairModel instance

Examples:

// Generate new ED25519 key pair
const keyPair1 = makeKeyPairModel()

// Generate new XChaCha20 key pair
const keyPair2 = makeKeyPairModel(KeyType.XCHACHA)

// Import from private key
const keyPair3 = makeKeyPairModel("ed25519:abcd1234...")

// Import from KeyPair object
const keyPair4 = makeKeyPairModel({
  privateKey: "abcd1234...",
  publicKey: "efgh5678...",
  address: "ijkl9012...",
  type: "ed25519"
})

fromPubKey(pubKey, type?)

Creates a KeyPairModel from a public key (verification/encryption only).

function fromPubKey(pubKey: string, type?: string): KeyPairModel

Parameters:

• pubKey: Public key string (with or without type prefix)
• type (optional): Algorithm type if not included in pubKey

Returns: KeyPairModel instance (without private key operations)

Examples:

// With type prefix
const publicKeyModel = fromPubKey("ed25519:abcd1234...")

// Without type prefix (defaults to ED25519)
const publicKeyModel2 = fromPubKey("abcd1234...")

// Explicit type
const publicKeyModel3 = fromPubKey("abcd1234...", KeyType.ED25519)

matchAddress(address, pubKey)

Verifies if a public key matches an address.

function matchAddress(address: string, pubKey: string): boolean

Parameters:

• address: Address string to verify
• pubKey: Public key string

Returns: boolean - true if the public key matches the address

inputToKeyPair(input?)

Converts various input formats to a KeyPair object.

function inputToKeyPair(input?: KeyPair | string): KeyPair

Parameters:

• input (optional):
  • KeyPair object
  • Algorithm type string (generates new key)
  • Encoded private key string (e.g., "ed25519:base64key")

Returns: KeyPair object

Examples:

// Generate new ED25519 key pair
const keyPair1 = inputToKeyPair()

// Generate new XChaCha20 key pair
const keyPair2 = inputToKeyPair(KeyType.XCHACHA)

// Import from private key
const keyPair3 = inputToKeyPair("ed25519:abcd1234...")

Authentication Helpers

packAuthCredentials(auth, extra, signer)

Packs authentication credentials with a signature.

function packAuthCredentials<T>(
  auth: UnsignedAuthCredentials,
  extra: T,
  signer: KeyPairModel | PayloadSigner
): Promise<AuthCredentials>

Parameters:

• auth: Unsigned authentication credentials
• extra: Additional data to include in credentials
• signer: KeyPairModel or custom signing function

Returns: Promise resolving to signed AuthCredentials

unpackAuthCredentials(auth, verifier?)

Unpacks and optionally verifies authentication credentials.

function unpackAuthCredentials<T>(
  auth: AuthCredentials,
  verifier?: KeyPairModel | PayloadVerifier
): Promise<UnpackedAuthCredentials<T>>

Parameters:

• auth: Signed authentication credentials
• verifier (optional): KeyPairModel or custom verification function

Returns: Promise resolving to UnpackedAuthCredentials<T>

Constants

KeyType

Enumeration of supported cryptographic algorithm types.

enum KeyType {
  ED25519 = 'ed25519',
  XCHACHA = 'xchacha'
}

Utility Functions

toAddress(publicKey)

Converts a public key to its corresponding address.

function toAddress(publicKey: Uint8Array): Uint8Array

Parameters:

• publicKey: Public key as Uint8Array

Returns: Uint8Array - Address bytes (last 20 bytes of Keccak-256 hash)

prepareData(data)

Converts various data types to Uint8Array for cryptographic operations.

function prepareData(data: unknown): Uint8Array

prepareKey(key)

Converts a base64-encoded key string to Uint8Array.

function prepareKey(key: string): Uint8Array

assertType(type?)

Validates that a cryptographic algorithm type is supported.

function assertType(type?: string): void

Plugin System

The library uses a plugin architecture to support different cryptographic algorithms. Each plugin implements the KeyPlugin interface:

interface KeyPlugin {
  type: string
  random: () => Uint8Array
  fromSeed?: (seed: Uint8Array) => Uint8Array
  derive?: (pk: Uint8Array, path: string) => Uint8Array
  sign: (data: Uint8Array, pk: Uint8Array) => Uint8Array
  verify: (data: Uint8Array, signature: Uint8Array, pub: Uint8Array) => boolean
  toPublic: (pk: Uint8Array) => Uint8Array
  toAdress: (pub: Uint8Array) => string
  encrypt: (data: Uint8Array, pk: Uint8Array) => Uint8Array
  decrypt: (data: Uint8Array, pk: Uint8Array) => Uint8Array
}

Built-in Plugins

ED25519 Plugin

• Type: ed25519
• Capabilities: Digital signatures, key derivation
• Address Format: Base58-encoded Keccak-256 hash
• Encryption: Not supported (throws error)

XChaCha20-Poly1305 Plugin

• Type: xchacha
• Capabilities: Symmetric encryption and decryption
• Address Format: "no-address" (not applicable)
• Signing: Not supported (throws error)

Using Plugins

import { plugins } from '@owlmeans/basic-keys/plugins'
// Or import individual plugins
import { ed25519Plugin, xChahaPlugin } from '@owlmeans/basic-keys/plugins'

// Access plugin directly
const ed25519Plugin = plugins['ed25519']

// Generate random private key
const privateKey = ed25519Plugin.random()

// Convert to public key
const publicKey = ed25519Plugin.toPublic(privateKey)

// Sign data
const signature = ed25519Plugin.sign(data, privateKey)

// Verify signature
const isValid = ed25519Plugin.verify(data, signature, publicKey)

CLI Tool

The package includes a command-line tool for key generation:

# Generate keys
npx owlkeys

# Or if installed globally
owlkeys

The CLI tool generates and displays:

• ED25519 private key export
• ED25519 public key export
• ED25519 address (DID format)
• XChaCha20 key export

Advanced Usage

Custom Signing and Verification

import type { PayloadSigner, PayloadVerifier } from '@owlmeans/basic-keys'

// Custom signer function
const customSigner: PayloadSigner = async (payload) => {
  // Custom signing logic
  return signature
}

// Custom verifier function
const customVerifier: PayloadVerifier = async (payload, signature) => {
  // Custom verification logic
  return isValid
}

// Use with authentication helpers
const credentials = await packAuthCredentials(auth, extra, customSigner)
const unpacked = await unpackAuthCredentials(credentials, customVerifier)

Working with Raw Data

import { prepareData, prepareKey, toAddress, assertType } from '@owlmeans/basic-keys/utils'

// Prepare various data types for cryptographic operations
const data1 = prepareData("string data")           // UTF-8 encoded
const data2 = prepareData({ key: "value" })        // JSON canonicalized
const data3 = prepareData(new Uint8Array([1, 2]))  // As-is

// Prepare keys
const keyBytes = prepareKey("base64KeyString")

// Generate address from public key
const address = toAddress(publicKeyBytes)

// Assert algorithm type is supported
assertType("ed25519") // No error
assertType("unknown") // Throws error

Encryption and Decryption

// For encryption, use XChaCha20 keys
const encryptionKey = makeKeyPairModel(KeyType.XCHACHA)

// Encrypt data
const encrypted = await encryptionKey.encrypt("sensitive data")

// Decrypt data  
const decrypted = await encryptionKey.decrypt(encrypted)

// Decrypt to raw bytes
const rawBytes = await encryptionKey.dcrpt(encrypted)

Error Handling

The library throws descriptive errors for various failure conditions:

• basic.keys:string-type-or-key - Invalid key string format
• basic.keys:missing-keypair - KeyPair not available
• basic.keys:missing-pk - Private key not available
• basic.keys:sign-data-type - Invalid data type for signing
• basic.keys:unknown-type - Unsupported algorithm type
• ed25519:encryption-support - ED25519 doesn't support encryption
• xchacha:signing - XChaCha20 doesn't support signing
• xchacha:verification - XChaCha20 doesn't support verification

Integration with OwlMeans Common

This package is designed to integrate seamlessly with other OwlMeans Common libraries:

• @owlmeans/auth: Authentication and authorization
• @owlmeans/client-auth: Client-side authentication
• @owlmeans/server-auth: Server-side authentication

TypeScript Support

The library is written in TypeScript and provides comprehensive type definitions. All exports are properly typed for optimal developer experience.

Security Considerations

• Private keys are stored as base64-encoded strings
• All cryptographic operations use well-established libraries (@noble/curves, @noble/ciphers)
• Data is canonicalized before signing to prevent signature malleability
• Key generation uses cryptographically secure random number generation

Contributing

This package is part of the OwlMeans Common ecosystem. Please refer to the main repository for contribution guidelines.

License

See the LICENSE file in the repository root for license information.