@beshkenadze/react-secret-sharing/README.md

A clean, minimalist implementation of Shamir Secret Sharing with React hooks for easy integration

# @beshkenadze/react-secret-sharing

[![npm version](https://badge.fury.io/js/@beshkenadze%2Freact-secret-sharing.svg)](https://www.npmjs.com/package/@beshkenadze/react-secret-sharing)

A clean, minimalist implementation of **Shamir Secret Sharing** with React hooks for easy integration.

## ✨ Features

- 🔐 **Secure**: Based on Shamir's Secret Sharing algorithm
- 📦 **Simple**: Clean API with full TypeScript support
- ⚛️ **React Ready**: Custom hooks for seamless React integration
- 🎯 **Flexible**: Three output formats (Base64, Hex, BIP39 Mnemonic)
- 🔍 **Auto-Detection**: Automatically detects share formats when combining

## 📦 Installation

```bash
npm install @beshkenadze/react-secret-sharing
```

## 🚀 Quick Start

```tsx
import { useShamir } from "@beshkenadze/react-secret-sharing";

function MyComponent() {
  const { split, combine, shares, isLoading, error, reset } = useShamir();
  
  const handleSplit = async () => {
    await split("my-secret", { totalShares: 3, threshold: 2 });
  };
  
  const handleCombine = async () => {
    const secret = await combine(shares.slice(0, 2));
    console.log('Reconstructed:', secret);
  };
  
  return (
    <div>
      {error && <div>Error: {error}</div>}
      {isLoading && <div>Loading...</div>}
      <button onClick={handleSplit}>Split Secret</button>
      <button onClick={handleCombine}>Combine Shares</button>
      <button onClick={reset}>Reset</button>
    </div>
  );
}
```

## 🎨 Share Formats

### Base64 (Default)
```tsx
await split("secret", { totalShares: 3, threshold: 2 });
// Output: "SGVsbG8gV29ybGQ="
```

### Human-Readable Hex
```tsx
await split("secret", { totalShares: 3, threshold: 2 }, { encoding: 'human' });
// Output: "48-65-6c-6c-6f-20-57-6f-72-6c-64"
```

### BIP39 Mnemonic Words
```tsx
await split("secret", { totalShares: 3, threshold: 2 }, { encoding: 'mnemonic' });
// Output: "search only exotic way tomato sure despair ship speed beef"
```

## 📚 API Reference

### `useShamir()` Hook

The main hook for stateful Shamir operations:

```tsx
const {
  // State
  isLoading,           // boolean - loading state
  error,               // string | null - error message
  shares,              // TShare[] - generated shares
  reconstructedSecret, // string | null - reconstructed secret
  
  // Actions
  split,               // (secret, config, options?) => Promise<TShare[]>
  combine,             // (shares) => Promise<string>
  reset,               // () => void - reset all state
  clearError           // () => void - clear error only
} = useShamir();
```

**Methods:**

- **`split(secret, config, options?)`** - Split a secret into shares
  - `secret: string` - The secret to split
  - `config: TShamirConfig` - Configuration for shares
  - `options?: TShamirOptions` - Optional encoding format
  - Returns: `Promise<TShare[]>` - Array of generated shares

- **`combine(shares)`** - Combine shares to reconstruct the secret
  - `shares: TShare[]` - Array of shares to combine
  - Returns: `Promise<string>` - The reconstructed secret

- **`reset()`** - Reset all state (shares, secret, error)

- **`clearError()`** - Clear only the error state

### `useShamirOperations()` Hook

For one-time operations without state management:

```tsx
const { splitSecret, combineShares } = useShamirOperations();

// Direct usage
const result = await splitSecret("secret", { totalShares: 3, threshold: 2 });
const reconstructed = await combineShares(result.shares.slice(0, 2));
```

### Core Functions

You can also import the core functions directly:

```tsx
import { splitSecret, combineShares } from "@beshkenadze/react-secret-sharing";

const { shares } = await splitSecret("secret", { totalShares: 3, threshold: 2 });
const { secret } = await combineShares(shares);
```

## 📝 TypeScript Types

```tsx
interface TShamirConfig {
  totalShares: number;  // 2-255: total number of shares to create
  threshold: number;    // 2-totalShares: minimum shares needed to reconstruct
}

interface TShamirOptions {
  encoding?: 'base64' | 'human' | 'mnemonic'; // output format
}

interface TShare {
  id: number;    // share identifier (1-based)
  data: string;  // encoded share data
}

interface TSplitResult {
  shares: TShare[];
  config: TShamirConfig;
}

interface TCombineResult {
  secret: string;
}
```

## 🧩 Auto-Detection Magic

The `combine` function automatically detects share formats - mix them seamlessly:

```tsx
const mixedShares = [
  { id: 1, data: "SGVsbG8gV29ybGQ=" },           // Base64
  { id: 2, data: "48-65-6c-6c-6f-20-57-6f-72" }, // Hex  
  { id: 3, data: "search only exotic way tomato" } // Mnemonic
];

const secret = await combine(mixedShares); // ✅ Works perfectly!
```

## 🛡️ Security Notes

- Shares are generated using cryptographically secure random numbers
- Based on proven Shamir Secret Sharing algorithm
- No secrets are stored in memory longer than necessary
- Each share reveals no information about the original secret
- Threshold security: need exactly K shares to reconstruct

## 📄 License

MIT © [Akira Beshkenadze](https://github.com/beshkenadze)