@iota-big3/sdk-quantum/README.md

Quantum-ready architecture with post-quantum cryptography

# @iota-big3/sdk-quantum

Quantum-ready architecture with post-quantum cryptography and future-proof security.

## Features

- ⚛️ **Post-Quantum Cryptography**: NIST-approved algorithms
- 🔐 **Hybrid Encryption**: Classical + quantum protection
- 🔄 **Migration Tools**: Smooth transition to quantum-safe
- 🌀 **Quantum Simulator**: Test quantum algorithms
- 💾 **Quantum Storage**: Secure data with PQ crypto
- 🚀 **Crypto Agility**: Switch algorithms seamlessly

## Installation

```bash
npm install @iota-big3/sdk-quantum
```

## Quick Start

```typescript
import { createQuantumArchitecture } from '@iota-big3/sdk-quantum';

// Initialize quantum architecture
const quantum = createQuantumArchitecture({
  mode: 'hybrid',
  algorithms: {
    kem: 'kyber',
    signature: 'dilithium'
  },
  securityLevel: 3 // 192-bit security
});

await quantum.initialize();

// Generate quantum-safe keys
const keyPair = await quantum.getCrypto().generateKeyPair('kyber', ['keyEncapsulation']);
```

## Post-Quantum Algorithms

### Key Encapsulation (KEM)
```typescript
// Kyber - NIST standardized
const keys = await crypto.generateKeyPair('kyber', ['keyEncapsulation']);

// Encapsulate (sender)
const { ciphertext, sharedSecret } = await crypto.encapsulate(keys.publicKey);

// Decapsulate (receiver)
const recovered = await crypto.decapsulate(ciphertext, keys.privateKey);
```

### Digital Signatures
```typescript
// Dilithium - Lattice-based
const sigKeys = await crypto.generateKeyPair('dilithium', ['sign', 'verify']);

// Sign
const signature = await crypto.sign(message, sigKeys.privateKey);

// Verify
const valid = await crypto.verify(message, signature, sigKeys.publicKey);
```

### Alternative Algorithms
```typescript
// SPHINCS+ - Hash-based (stateless)
const sphincs = await crypto.generateKeyPair('sphincs+', ['sign']);

// FrodoKEM - Conservative choice
const frodo = await crypto.generateKeyPair('frodo', ['keyEncapsulation']);
```

## Hybrid Cryptography

### Dual Protection
```typescript
// Encrypt with both classical and quantum
const result = await crypto.hybridEncrypt(
  data,
  quantumPublicKey,
  classicalPublicKey // Optional
);

// Both must succeed to decrypt
const plaintext = await crypto.hybridDecrypt(
  result.quantumCiphertext,
  result.encapsulatedKey,
  quantumPrivateKey,
  result.classicalCiphertext,
  classicalPrivateKey
);
```

## Migration Tools

### Plan Migration
```typescript
const migration = quantum.getMigration();

// Create migration path
const path = migration.planMigration('rsa-2048', 'kyber');

console.log(`Steps: ${path.steps.length}`);
console.log(`Time: ${path.estimatedTime} hours`);
```

### Execute Migration
```typescript
// Start migration
const migrationId = await migration.startMigration('system-1', path);

// Monitor progress
const progress = await migration.getProgress(migrationId);
console.log(`Status: ${progress.status}`);
console.log(`Current step: ${progress.currentStep}/${progress.totalSteps}`);
```

### Test Readiness
```typescript
const ready = await migration.testQuantumReadiness();

if (!ready.ready) {
  console.log('Issues:', ready.issues);
  console.log('Recommendations:', ready.recommendations);
}
```

## Quantum Simulator

### Create Circuit
```typescript
const simulator = quantum.createSimulator(3); // 3 qubits
const circuit = simulator.createCircuit(3);

// Add gates
simulator.addGate(circuit, { type: 'H', qubits: [0] }); // Hadamard
simulator.addGate(circuit, { type: 'CNOT', qubits: [0, 1] }); // Entangle

// Measure
simulator.addMeasurement(circuit, 0, 0);
simulator.addMeasurement(circuit, 1, 1);
```

### Execute Circuit
```typescript
const results = await simulator.execute(circuit, 1024); // 1024 shots

// Analyze results
for (const [state, count] of Object.entries(results.counts)) {
  console.log(`|${state}⟩: ${count} times`);
}

console.log(`Entanglement: ${results.state.entanglement}`);
```

## Quantum-Safe Storage

### Initialize Storage
```typescript
const storage = quantum.getStorage();
await storage.initialize('strong-password');
```

### Store Encrypted Data
```typescript
const id = await storage.store('api-key', {
  key: 'sk_live_...',
  permissions: ['read', 'write']
});
```

### Create Backup
```typescript
const backup = await storage.createBackup(
  ['api-key', 'private-key'],
  'Critical keys backup'
);

// Save backup securely
await saveToSecureLocation(backup);
```

### Secret Sharing
```typescript
// Split secret into shares
const secret = crypto.getRandomValues(new Uint8Array(32));
const shares = await storage.createSecretShares(
  secret,
  3, // threshold
  5  // total shares
);

// Reconstruct with any 3 shares
const recovered = await storage.reconstructSecret(
  [shares[0], shares[2], shares[4]],
  3
);
```

## Security Levels

### NIST Security Levels
- **Level 1**: 128-bit security (AES-128 equivalent)
- **Level 3**: 192-bit security (AES-192 equivalent)
- **Level 5**: 256-bit security (AES-256 equivalent)

### Choose Security Level
```typescript
const config = {
  securityLevel: quantum.recommendSecurityLevel(20) // 20 years protection
};
```

## Performance Optimization

### Enable Caching
```typescript
{
  performance: {
    cacheKeys: true,
    parallelOperations: 4,
    optimizeFor: 'speed' // or 'size', 'balanced'
  }
}
```

### Benchmark Operations
```typescript
const metrics = await quantum.getMetrics();

console.log(`Key gen: ${metrics.keyGenerationTime}ms`);
console.log(`Ops/sec: ${metrics.operationsPerSecond}`);
```

## Best Practices

1. **Start Migration Now**
   - Inventory crypto usage
   - Identify long-term data
   - Plan transition timeline

2. **Use Hybrid Mode**
   ```typescript
   mode: 'hybrid' // Not 'quantum-only' yet
   ```

3. **Monitor Quantum Progress**
   ```typescript
   const years = quantum.timeToQuantumThreat();
   console.log(`${years} years until threat`);
   ```

4. **Test Thoroughly**
   - Benchmark performance
   - Verify compatibility
   - Test migration paths

## API Reference

See [API Documentation](./API.md) for detailed reference.

## Examples

- [Basic Usage](./examples/basic.ts)
- [Migration Guide](./examples/migration.ts)
- [Quantum Circuits](./examples/quantum-circuits.ts)
- [Secure Storage](./examples/secure-storage.ts)

## Resources

- [NIST PQC Standards](https://csrc.nist.gov/projects/post-quantum-cryptography)
- [Quantum Threat Timeline](https://globalriskinstitute.org/quantum-threat-timeline/)
- [Migration Best Practices](./docs/migration.md)