@nealireverse_dev/utils/README.md

Utilities for internal use

# NPM Keypair Utils

A strongly-typed utility library for working with Solana keypairs. Provides secure keypair generation, import/export, validation, encryption, and caching. Designed for internal use, but follows best practices and strict type safety for robust integration.

## Installation

```bash
npm install @nealireverse_dev/utils
```

## Features

- Generate new Solana keypairs
- Import keypairs from array, base58, Uint8Array, SolanaKeypair, or file
- Export keypairs to array, base58, Uint8Array, or encrypted format
- Validate keypair structure and integrity
- Encrypt and decrypt keypairs (AES-256-GCM, password-based)
- Public/private key extraction
- Keypair metadata and hash
- In-memory keypair cache
- Fully type-safe API (no `any`)

## Quick Start

```typescript
import { Keypair } from "@nealireverse_dev/utils";

// Generate a new keypair
const keypair = Keypair.generate();

// Export to base58
const base58 = keypair.toBase58();

// Import from base58
const imported = Keypair.fromBase58(base58);

// Create SolanaKeypair from base58 using Keypair.from
const solanaKeypair = Keypair.from({ keypair: base58 });

// Get public key
const publicKey = keypair.getPublicKey();

// Validate keypair
const validation = keypair.validate();

// Encrypt keypair
const encrypted = keypair.encrypt();

// Decrypt keypair
const decrypted = Keypair.decrypt(encrypted);
```

## API Reference

### Keypair Class

#### Static Methods

- `Keypair.generate(): Keypair` — Generate a new random Solana keypair
- `Keypair.from(options: KeypairOptions): SolanaKeypair` — Create SolanaKeypair from various formats
- `Keypair.fromKeypair(options: KeypairOptions): Keypair` — Create Keypair instance from various formats
- `Keypair.fromArray(array: number[]): Keypair` — Import from number array
- `Keypair.fromBase58(base58: string): Keypair` — Import from base58 string
- `Keypair.fromFile(filePath: string): Keypair` — Import from file (array/base58/encrypted)
- `Keypair.fromSolanaKeypair(solanaKeypair: SolanaKeypair): Keypair` — Import from SolanaKeypair
- `Keypair.decrypt(encryptedData: string): Keypair` — Decrypt encrypted keypair
- `Keypair.getCacheInfo(): { size: number }` — Get cache size
- `Keypair.clearCache(): void` — Clear in-memory cache

#### Instance Methods

- `toArray(): number[]` — Export as number array
- `toBase58(): string` — Export as base58 string
- `toUint8Array(): Uint8Array` — Export as Uint8Array
- `toSolanaKeypair(): SolanaKeypair` — Get SolanaKeypair instance
- `getPublicKey(): PublicKey` — Get public key
- `export(options: ExportOptions): number[] | string | Uint8Array | EncryptedKeypair` — Export in specified format
- `encrypt(): string` — Encrypt keypair (returns base58 string)
- `getProtected(): boolean` — Is keypair protected (encrypted)
- `getHash(): string` — Get SHA-256 hash of keypair data
- `getLength(): number` — Get keypair byte length
- `getInfo(): KeypairInfo` — Get metadata (length, format, hash, etc.)
- `validate(): KeypairValidation` — Validate keypair structure

### Types

All types are exported from `@nealireverse_dev/utils`:

- `KeypairOptions` — `{ keypair: KeypairInput; protect_keypair?: boolean }`
- `KeypairInput` — `number[] | string | SolanaKeypair | Uint8Array`
- `ExportOptions` — `{ format: 'array' | 'base58' | 'uint8array' | 'encrypted'; encryptionOptions?: { algorithm?: string; iterations?: number } }`
- `EncryptedKeypair` — `{ encryptedData: string; metadata: { algorithm: string; version: string; timestamp: number } }`
- `KeypairValidation` — `{ isValid: boolean; length: number; format: string; errors?: string[] }`
- `KeypairInfo` — `{ length: number; isProtected: boolean; originalFormat: string; createdAt: number; hash?: string }`

### Encryption

- Uses AES-256-GCM with PBKDF2 password-based key derivation
- Password and encryption config are set in internal config (not public API)
- Encrypted keypairs are base58-encoded

## Examples

#### Import from File

```typescript
const keypair = Keypair.fromFile("./my-keypair.json");
```

#### Export Encrypted

```typescript
const encrypted = keypair.export({ format: "encrypted" });
```

#### Validate Keypair

```typescript
const result = keypair.validate();
if (!result.isValid) {
  throw new Error(result.errors?.join(", "));
}
```

## Development

```bash
pnpm install
pnpm build
pnpm test
pnpm dev
```

## License

UNLICENSED — Private library for internal use only.