xStore: Universal Split-Storage

interface StorageBackend {
  /** Unique identifier for this backend (e.g. 'aws-s3-us-east-1') */
  readonly id: string;

  /** Store a share by key. Returns Result indicating success. */
  put(key: string, data: Uint8Array): Promise<Result<void, StorageError>>;

  /** Retrieve a share by key. Returns Result with data or error. */
  get(key: string): Promise<Result<Uint8Array, StorageError>>;

  /** Delete a share by key. Idempotent. */
  delete(key: string): Promise<Result<void, StorageError>>;
}

import { createStore } from '@private.me/xstore';

// Configure with backends and threshold
const store = createStore({
  backends: [s3Backend, azureBackend, fsBackend],
  threshold: { k: 2, n: 3 },
  ttl: 86400 * 30,  // optional: 30-day TTL
});

// Store data — returns a manifest
const data = new TextEncoder().encode('sensitive payload');
const putResult = await store.put('doc-001', data);
if (!putResult.ok) throw putResult.error;
const manifest = putResult.value;
// manifest.shares → [{backendId, key, hmac}, ...]
// manifest.threshold → {k: 2, n: 3}
// manifest.created → ISO timestamp

// Retrieve data — verifies HMAC, reconstructs from k shares
const getResult = await store.get(manifest);
if (!getResult.ok) throw getResult.error;
const restored = getResult.value;
// restored === data (Uint8Array, byte-identical)

const result = await store.put('large-dataset', data, {
  onProgress: (event) => {
    // Per-backend progress updates
    console.log(`Backend ${event.backendId}: ${event.shareIndex}/${event.totalShares}`);
    console.log(`Status: ${event.status}`);  // 'pending' | 'uploading' | 'complete' | 'failed'
    console.log(`Progress: ${event.bytesTransferred}/${event.totalBytes} bytes`);
  }
});

const result = await store.get(manifest, {
  onProgress: (event) => {
    // Shows which backends are being contacted for reconstruction
    console.log(`Fetching share ${event.shareIndex} from ${event.backendId}`);

    if (event.status === 'complete') {
      console.log(`Downloaded: ${event.bytesTransferred} bytes in ${event.durationMs}ms`);
    }

    if (event.status === 'failed') {
      console.warn(`Backend ${event.backendId} failed, retrying others...`);
    }
  }
});

const result = await store.get(manifest);

if (!result.ok) {
  const error = result.error;

  switch (error.code) {
    case 'SHARE_INTEGRITY_FAILED':
      // Log tamper attempt, alert security team
      logger.alert('Share tampered', { backendId: error.backendId });
      break;

    case 'BACKEND_UNAVAILABLE':
      // Retry with exponential backoff
      await retryWithBackoff(() => store.get(manifest));
      break;

    case 'INSUFFICIENT_BACKENDS':
      // Suggest user action: add more storage backends
      ui.showAlert('Add more storage backends to meet threshold');
      break;

    default:
      // Generic fallback
      console.error(`xStore error: ${error.message}`);
  }
}

import { createStore } from '@private.me/xstore';
import { S3Backend, AzureBlobBackend, GCPStorageBackend } from './backends';

// Configure three cloud backends
const s3 = new S3Backend({ region: 'us-east-1', bucket: 'private-shares' });
const azure = new AzureBlobBackend({ account: 'eu-storage', container: 'shares' });
const gcp = new GCPStorageBackend({ project: 'xstore-prod', bucket: 'apac-shares' });

// Universal split-storage layer: 2-of-3 threshold across clouds
const store = createStore({
  backends: [s3, azure, gcp],
  threshold: { k: 2, n: 3 },
  ttl: 86400 * 90,  // 90-day retention
});

// Track upload progress across all three backends
const data = new Uint8Array(1024 * 1024 * 10);  // 10MB dataset
const uploadProgress = new Map();

const putResult = await store.put('patient-genome-12345', data, {
  onProgress: (event) => {
    uploadProgress.set(event.backendId, event);

    // Real-time visibility into multi-cloud orchestration
    const completed = [...uploadProgress.values()]
      .filter(e => e.status === 'complete').length;

    console.log(`Upload: ${completed}/3 backends complete`);
    console.log(`  AWS: ${uploadProgress.get('s3')?.bytesTransferred || 0} bytes`);
    console.log(`  Azure: ${uploadProgress.get('azure')?.bytesTransferred || 0} bytes`);
    console.log(`  GCP: ${uploadProgress.get('gcp')?.bytesTransferred || 0} bytes`);
  }
});

if (!putResult.ok) {
  throw new Error(`Storage failed: ${putResult.error.message}`);
}

// Store manifest for retrieval (manifest contains backend routing + HMAC tags)
const manifest = putResult.value;

// Later: retrieve data from any 2 of the 3 backends
// Even if AWS S3 goes down, Azure + GCP can still reconstruct
const getResult = await store.get(manifest, {
  onProgress: (event) => {
    if (event.status === 'failed') {
      console.warn(`Backend ${event.backendId} unavailable, using others...`);
    }
  }
});

if (!getResult.ok) {
  throw new Error(`Retrieval failed: ${getResult.error.message}`);
}

// getResult.value === data (byte-identical, HMAC-verified)

npm install @private.me/xstore

import { createStore } from '@private.me/xstore';
import { S3Backend } from './backends/s3';
import { AzureBackend } from './backends/azure';
import { FsBackend } from './backends/fs';

// Create store with 2-of-3 threshold
const store = createStore({
  backends: [
    new S3Backend({ bucket: 'shares-us-east' }),
    new AzureBackend({ container: 'shares-eu-west' }),
    new FsBackend({ path: '/mnt/airgap/shares' }),
  ],
  threshold: { k: 2, n: 3 },
});

// Store sensitive data
const data = new TextEncoder().encode('patient record #4291');
const { value: manifest } = await store.put('record-4291', data);

// Retrieve — HMAC-verified, reconstructed from any 2 of 3 backends
const { value: restored } = await store.get(manifest);
// restored is byte-identical to data