@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

npm install @beshkenadze/react-secret-sharing

🚀 Quick Start

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)

await split("secret", { totalShares: 3, threshold: 2 });
// Output: "SGVsbG8gV29ybGQ="

Human-Readable Hex

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

BIP39 Mnemonic Words

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:

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:

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:

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

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

📝 TypeScript Types

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:

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