@private.me/crypto

Zero-dependency TypeScript implementation of XorIDA threshold secret sharing (XorIDA over GF(2)), designed for split-channel secure messaging. Easy to integrate into your applications for information-theoretically secure data protection.

Features

• XorIDA threshold sharing — information-theoretically secure k-of-n secret splitting
• HMAC-SHA256 integrity — share verification before reconstruction (Web Crypto API)
• TLV serialization — Type-Length-Value encoding for messages and attachments
• PKCS#7 padding — block padding with mandatory minimum one byte
• High-level API — createShares() and reconstructMessage() for common workflows
• Minimal dependencies — only @private.me/shared (Result<T,E> types) + Web Crypto API
• 100% test coverage — known-answer vectors, fuzz tests, security property tests

Installation

npm install @private.me/crypto

Dependencies

Runtime Dependencies:

• @private.me/shared — Result<T,E> error handling primitives and core types

Platform Dependencies:

• Web Crypto API — crypto.subtle, crypto.getRandomValues (built-in to Node.js 18+ and modern browsers)

Quick Start

import { createShares, reconstructMessage } from '@private.me/crypto';

// Split a message into 3 shares, any 2 can reconstruct
const result = await createShares('Secret message', {
  n: 3,    // total shares
  k: 2,    // threshold to reconstruct
  channels: ['gmail', 'outlook', 'yahoo'],
});

if (result.ok) {
  const { shares } = result.value;
  // Send each share through a different email channel
}

// Reconstruct from any 2 shares
const message = await reconstructMessage([shares[0], shares[2]]);
if (message.ok) {
  console.log(message.value); // 'Secret message'
}

Capability Check

Check for Web Crypto API availability before using crypto operations:

import { isSupported } from '@private.me/crypto';

if (!isSupported()) {
  console.error('This runtime lacks Web Crypto support required for XorIDA operations.');
  process.exit(1);
}

Verify-Only Sub-Path

For verification-only use cases (checking HMAC integrity, decoding base64), import the lightweight sub-path:

import { verifyHMAC, fromBase64, isSupported } from '@private.me/crypto/verify';

This pulls in only HMAC verification, base64 encoding/decoding, and the capability check — no XorIDA splitting, no reconstruction, no padding.

API Reference

High-Level: createShares(message, options) • reconstructMessage(shares)

XorIDA: splitXorIDA(data, n, k) • reconstructXorIDA(shares, k, originalLength) • nextOddPrime(n)

Integrity: generateHMAC(key, data) • verifyHMAC(key, data, tag) • signHMAC(key, data)

Serialization: serializeMessage(message) • deserializeMessage(data)

Padding: pkcs7Pad(data, blockSize) • pkcs7Unpad(data)

Encoding: toBase64(data) • fromBase64(str) • toBase64Url(data) • fromBase64Url(str) • generateUUID() • uuidToBytes(uuid) • bytesToUuid(bytes)

Errors

| Code | Description | |---|---| | INVALID_PADDING | PKCS#7 padding bytes are invalid or inconsistent. Data may be corrupted. | | HMAC_FAILURE | HMAC-SHA256 verification failed during reconstruction. One or more shares have been tampered with. | | INVALID_SHARES | Shares have inconsistent lengths, duplicate indices, or mismatched parameters. | | INSUFFICIENT_SHARES | Fewer shares provided than the required threshold k. | | INVALID_INDEX | A share index is out of range (must be 0 to n-1). | | UUID_MISMATCH | Shares reference different message UUIDs and cannot be combined. | | INVALID_TLV | TLV data is malformed or truncated. | | BUFFER_OVERFLOW | TLV length field exceeds available data. | | MISSING_FIELD | A required TLV field (e.g., MESSAGE_UUID) is absent. | | INVALID_TYPE | An unrecognized TLV type tag was encountered in a required position. | | HMAC_MISMATCH | Standalone HMAC verification failed. Data or key is incorrect. | | KEY_ERROR | HMAC key import failed (invalid length or format). |

Security Model

Information-theoretic security via XorIDA threshold sharing. Attackers with <k shares gain zero information, regardless of computational power.

Key properties: HMAC-before-reconstruct • Cryptographic randomness only (crypto.getRandomValues()) • Fail-closed error handling • Sub-millisecond performance (1-10KB) • ~33ms for 1MB (2-of-2)

Full specification: docs/crypto-spec.md

Testing

# Run all crypto tests (100% line coverage required)
pnpm test:crypto

# Run with coverage report
pnpm test:crypto --coverage

# Run security property + fuzz tests only
pnpm test:security

The test suite includes:

• Known-answer test vectors for every algorithm
• All-pairs reconstruction tests for multiple k-of-n configurations
• Statistical independence tests (chi-squared, Pearson correlation)
• Fuzz tests with random inputs and configurations
• RFC 4231 HMAC-SHA256 test vectors

Runtime Requirements

Node.js 20+ | Web Crypto API required (crypto.subtle)

Supported: Node.js 20+, Tauri v2, Chromium 113+, Firefox 130+, Safari 17+, Deno 1.40+, Bun 1.0+

Full Control IP Protection

This package uses real XorIDA 2-of-2 threshold secret sharing for IP protection:

• Share 1 (181KB): Included in npm package (Store Front) - public distribution
• Share 2 (181KB): Payment-gated on EC2 server (Vault Store) - authenticated access only
• Both shares required to reconstruct the proprietary XorIDA algorithm
• Information-theoretic security: Each share alone is cryptographically useless

This implementation follows the Store Front / Vault Store model for patent-protected intellectual property. The algorithm only becomes operational after secure authentication and share reconstruction.

Pricing

All Private.Me ACIs use usage-based pricing:

• 100,000 operations/month FREE
• $5 per 100,000 operations (overage)
• 90-day free trial (no credit card required)
• Enterprise tier: Custom pricing for volume and compliance features

1 operation = One complete cryptographic transaction (split, reconstruct, HMAC verification)

For complete pricing details, see pricing documentation.

Subscribe: Start your free trial

Purchase API

Programmatic subscription management via the Private.Me Purchase API:

// Start subscription for crypto ACI
const response = await fetch('https://private.me/aci/purchase', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    product: 'crypto',
    tier: 'pro',
    billingEmail: '[email protected]'
  })
});

const result = await response.json();
if (response.ok) {
  console.log('Subscription active:', result.subscriptionId);
} else {
  // RFC 7807 structured error response
  console.error('Error:', result.title, result.detail);
}

Error Handling: API returns RFC 7807 Problem Details for structured error responses with type, title, detail, and fields object for field-level validation errors.

Documentation: Purchase API Reference

Legal

• Terms of Service
• Privacy Policy
• License

Export Control Notice

This package contains cryptographic software. Export restrictions may apply. Users are responsible for compliance with U.S. Export Administration Regulations (EAR) and jurisdiction-specific export control requirements.

License: Proprietary | Company: Standard Clouds, Inc. dba PRIVATE.ME

Questions? Documentation • Issues