@omnituum/pqc-shared 0.2.6

package/src/tunnel/session.ts

@@ -0,0 +1,229 @@
+/**
+ * Omnituum Tunnel v1 - Session Implementation
+ *
+ * XChaCha20-Poly1305 encrypted tunnel with counter-based nonces.
+ * Handshake-agnostic: accepts any TunnelKeyMaterial producer.
+ *
+ * @see pqc-docs/specs/tunnel.v1.md
+ */
+
+import { xChaCha20Poly1305Encrypt, xChaCha20Poly1305Decrypt } from '../crypto/primitives/chacha';
+import { zeroMemory } from '../security';
+import type { TunnelKeyMaterial, PQCTunnelSession } from './types';
+import { TUNNEL_KEY_SIZE, TUNNEL_NONCE_SIZE } from './types';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// NONCE DERIVATION
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Derive a unique nonce from base nonce and counter.
+ *
+ * Construction:
+ * - nonce[0..16] = base[0..16]
+ * - nonce[16..24] = base[16..24] XOR BE64(counter)
+ *
+ * This ensures:
+ * - Unique nonces for each message (counter monotonicity)
+ * - Different nonces for send/recv (different base nonces)
+ * - No nonce reuse until counter overflow (~18 quintillion messages)
+ */
+function deriveNonce(base: Uint8Array, counter: bigint): Uint8Array {
+  const nonce = new Uint8Array(24);
+
+  // Copy first 16 bytes unchanged
+  nonce.set(base.subarray(0, 16), 0);
+
+  // XOR counter (big-endian) into last 8 bytes
+  const view = new DataView(nonce.buffer, 16, 8);
+  const baseView = new DataView(base.buffer, base.byteOffset + 16, 8);
+
+  // Read base's last 8 bytes as bigint and XOR with counter
+  const baseValue = baseView.getBigUint64(0, false);
+  view.setBigUint64(0, baseValue ^ counter, false);
+
+  return nonce;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// VALIDATION
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Validate tunnel key material.
+ */
+function validateKeyMaterial(keys: TunnelKeyMaterial): void {
+  if (!keys.sendKey || keys.sendKey.length !== TUNNEL_KEY_SIZE) {
+    throw new Error(`sendKey must be ${TUNNEL_KEY_SIZE} bytes`);
+  }
+  if (!keys.recvKey || keys.recvKey.length !== TUNNEL_KEY_SIZE) {
+    throw new Error(`recvKey must be ${TUNNEL_KEY_SIZE} bytes`);
+  }
+  if (!keys.sendBaseNonce || keys.sendBaseNonce.length !== TUNNEL_NONCE_SIZE) {
+    throw new Error(`sendBaseNonce must be ${TUNNEL_NONCE_SIZE} bytes`);
+  }
+  if (!keys.recvBaseNonce || keys.recvBaseNonce.length !== TUNNEL_NONCE_SIZE) {
+    throw new Error(`recvBaseNonce must be ${TUNNEL_NONCE_SIZE} bytes`);
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// SESSION FACTORY
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Create a secure tunnel session from key material.
+ *
+ * @param keys - Key material from handshake (Noise, TLS, etc.)
+ * @returns Tunnel session for encrypted communication
+ *
+ * @example
+ * ```ts
+ * // From Noise handshake
+ * const keys = toTunnelKeyMaterial(noiseState);
+ * const tunnel = createTunnelSession(keys);
+ *
+ * // Send encrypted message
+ * const ciphertext = tunnel.encrypt(plaintext);
+ * channel.send(ciphertext);
+ *
+ * // Receive encrypted message
+ * const plaintext = tunnel.decrypt(received);
+ *
+ * // Clean up when done
+ * tunnel.close();
+ * ```
+ */
+export function createTunnelSession(keys: TunnelKeyMaterial): PQCTunnelSession {
+  validateKeyMaterial(keys);
+
+  // Copy key material to prevent external mutation
+  const sendKey = new Uint8Array(keys.sendKey);
+  const recvKey = new Uint8Array(keys.recvKey);
+  const sendBaseNonce = new Uint8Array(keys.sendBaseNonce);
+  const recvBaseNonce = new Uint8Array(keys.recvBaseNonce);
+
+  // Per-direction counters
+  let sendCounter = 0n;
+  let recvCounter = 0n;
+
+  // Session state
+  let closed = false;
+
+  /**
+   * Assert tunnel is still open.
+   */
+  function assertOpen(): void {
+    if (closed) {
+      throw new Error('Tunnel is closed');
+    }
+  }
+
+  return {
+    encrypt(plaintext: Uint8Array, aad?: Uint8Array): Uint8Array {
+      assertOpen();
+
+      // Derive nonce for this message
+      const nonce = deriveNonce(sendBaseNonce, sendCounter);
+
+      // Encrypt
+      const ciphertext = xChaCha20Poly1305Encrypt(sendKey, nonce, plaintext, aad);
+
+      // Increment counter after successful encryption
+      sendCounter++;
+
+      // Zero the nonce (it contained counter information)
+      zeroMemory(nonce);
+
+      return ciphertext;
+    },
+
+    decrypt(ciphertext: Uint8Array, aad?: Uint8Array): Uint8Array | null {
+      assertOpen();
+
+      // Derive nonce for this message
+      const nonce = deriveNonce(recvBaseNonce, recvCounter);
+
+      // Decrypt
+      const plaintext = xChaCha20Poly1305Decrypt(recvKey, nonce, ciphertext, aad);
+
+      // Increment counter after successful decryption
+      // Note: We increment even on failure to stay in sync with sender
+      recvCounter++;
+
+      // Zero the nonce
+      zeroMemory(nonce);
+
+      return plaintext;
+    },
+
+    close(): void {
+      if (closed) return;
+
+      closed = true;
+
+      // Securely zero all key material
+      zeroMemory(sendKey);
+      zeroMemory(recvKey);
+      zeroMemory(sendBaseNonce);
+      zeroMemory(recvBaseNonce);
+    },
+
+    get isOpen(): boolean {
+      return !closed;
+    },
+
+    get sendCounter(): bigint {
+      return sendCounter;
+    },
+
+    get recvCounter(): bigint {
+      return recvCounter;
+    },
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// UTILITIES
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Create key material for testing (deterministic).
+ * DO NOT use in production - keys are derived from a simple seed.
+ *
+ * @internal
+ */
+export function createTestKeyMaterial(seed: string, isInitiator: boolean): TunnelKeyMaterial {
+  // Simple deterministic derivation for testing
+  const encoder = new TextEncoder();
+  const seedBytes = encoder.encode(seed);
+
+  // Generate 128 bytes of "key material" (very insecure, testing only!)
+  const material = new Uint8Array(128);
+  for (let i = 0; i < 128; i++) {
+    material[i] = (seedBytes[i % seedBytes.length] + i) % 256;
+  }
+
+  // Split into key components
+  const key1 = material.slice(0, 32);
+  const key2 = material.slice(32, 64);
+  const nonce1 = material.slice(64, 88);
+  const nonce2 = material.slice(88, 112);
+
+  // Assign based on role (initiator/responder swap to ensure symmetry)
+  if (isInitiator) {
+    return {
+      sendKey: key1,
+      recvKey: key2,
+      sendBaseNonce: nonce1,
+      recvBaseNonce: nonce2,
+    };
+  } else {
+    return {
+      sendKey: key2,
+      recvKey: key1,
+      sendBaseNonce: nonce2,
+      recvBaseNonce: nonce1,
+    };
+  }
+}

package/src/tunnel/types.ts

@@ -0,0 +1,115 @@
+/**
+ * Omnituum Tunnel v1 - Type Definitions
+ *
+ * Post-handshake encrypted tunnel interface.
+ * Handshake-agnostic: any key agreement can feed into this.
+ *
+ * @see pqc-docs/specs/tunnel.v1.md
+ */
+
+// ═══════════════════════════════════════════════════════════════════════════
+// KEY MATERIAL
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Key material required to establish a tunnel session.
+ * Produced by any key agreement protocol (Noise, TLS, custom).
+ */
+export interface TunnelKeyMaterial {
+  /** 32-byte key for outgoing messages */
+  sendKey: Uint8Array;
+
+  /** 32-byte key for incoming messages */
+  recvKey: Uint8Array;
+
+  /** 24-byte base nonce for outgoing messages */
+  sendBaseNonce: Uint8Array;
+
+  /** 24-byte base nonce for incoming messages */
+  recvBaseNonce: Uint8Array;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// SESSION INTERFACE
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * A secure tunnel session for post-handshake communication.
+ *
+ * @example
+ * ```ts
+ * import { createTunnelSession } from '@omnituum/pqc-shared';
+ *
+ * const tunnel = createTunnelSession(keys);
+ *
+ * // Send a message
+ * const ciphertext = tunnel.encrypt(plaintext);
+ *
+ * // Receive a message
+ * const plaintext = tunnel.decrypt(ciphertext);
+ * if (!plaintext) throw new Error('Authentication failed');
+ *
+ * // Clean up
+ * tunnel.close();
+ * ```
+ */
+export interface PQCTunnelSession {
+  /**
+   * Encrypt plaintext for transmission.
+   * Automatically increments the send counter.
+   *
+   * @param plaintext - Data to encrypt
+   * @param aad - Optional additional authenticated data
+   * @returns Ciphertext with authentication tag
+   * @throws Error if tunnel is closed
+   */
+  encrypt(plaintext: Uint8Array, aad?: Uint8Array): Uint8Array;
+
+  /**
+   * Decrypt received ciphertext.
+   * Automatically increments the receive counter.
+   *
+   * @param ciphertext - Data to decrypt (includes auth tag)
+   * @param aad - Optional additional authenticated data (must match encryption)
+   * @returns Plaintext, or null if authentication fails
+   * @throws Error if tunnel is closed
+   */
+  decrypt(ciphertext: Uint8Array, aad?: Uint8Array): Uint8Array | null;
+
+  /**
+   * Securely close the tunnel.
+   * Zeros all key material and rejects further operations.
+   */
+  close(): void;
+
+  /**
+   * Check if the tunnel is still open.
+   */
+  readonly isOpen: boolean;
+
+  /**
+   * Get current send counter (for debugging/monitoring).
+   */
+  readonly sendCounter: bigint;
+
+  /**
+   * Get current receive counter (for debugging/monitoring).
+   */
+  readonly recvCounter: bigint;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// CONSTANTS
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** Tunnel version string */
+export const TUNNEL_VERSION = 'omnituum.tunnel.v1' as const;
+
+/** Key size in bytes (32 = 256 bits) */
+export const TUNNEL_KEY_SIZE = 32;
+
+/** Base nonce size in bytes (24 for XChaCha20) */
+export const TUNNEL_NONCE_SIZE = 24;
+
+/** Authentication tag size in bytes (16 for Poly1305) */
+export const TUNNEL_TAG_SIZE = 16;

package/src/utils/entropy.ts

@@ -0,0 +1,128 @@
+/**
+ * Omnituum PQC Shared - Entropy & Randomness Utilities
+ *
+ * Functions for generating secure random values and measuring entropy.
+ */
+
+// ═══════════════════════════════════════════════════════════════════════════
+// ID GENERATION
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Generate a cryptographically secure random ID.
+ */
+export function generateId(): string {
+  const bytes = globalThis.crypto.getRandomValues(new Uint8Array(16));
+  return Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('');
+}
+
+/**
+ * Generate a short random ID (8 characters).
+ */
+export function generateShortId(): string {
+  const bytes = globalThis.crypto.getRandomValues(new Uint8Array(4));
+  return Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('');
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// ENTROPY MEASUREMENT
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Calculate Shannon entropy of a byte array.
+ * Returns bits per byte (max 8.0 for perfect randomness).
+ */
+export function calculateShannonEntropy(bytes: Uint8Array): number {
+  if (bytes.length === 0) return 0;
+
+  // Count byte frequencies
+  const freq = new Map<number, number>();
+  for (const byte of bytes) {
+    freq.set(byte, (freq.get(byte) || 0) + 1);
+  }
+
+  // Calculate entropy
+  let entropy = 0;
+  const len = bytes.length;
+  for (const count of freq.values()) {
+    const p = count / len;
+    entropy -= p * Math.log2(p);
+  }
+
+  return entropy;
+}
+
+/**
+ * Calculate entropy score (0-100) for key material.
+ * 100 = perfect entropy, 0 = no entropy.
+ */
+export function calculateEntropyScore(hexKey: string): number {
+  // Convert hex to bytes
+  const clean = hexKey.startsWith('0x') ? hexKey.slice(2) : hexKey;
+  const bytes = new Uint8Array(clean.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+  }
+
+  // Calculate Shannon entropy
+  const entropy = calculateShannonEntropy(bytes);
+
+  // Convert to 0-100 score (8.0 bits/byte = 100%)
+  return Math.min(100, Math.round((entropy / 8.0) * 100));
+}
+
+/**
+ * Check if a key has sufficient entropy.
+ */
+export function hasGoodEntropy(hexKey: string, threshold: number = 70): boolean {
+  return calculateEntropyScore(hexKey) >= threshold;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// KEY VALIDATION
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Validate X25519 public key format.
+ */
+export function isValidX25519Key(hexKey: string): boolean {
+  const clean = hexKey.startsWith('0x') ? hexKey.slice(2) : hexKey;
+  return /^[0-9a-fA-F]{64}$/.test(clean);
+}
+
+/**
+ * Validate Kyber public key format (base64, ~1568 bytes for ML-KEM-768).
+ */
+export function isValidKyberKey(b64Key: string): boolean {
+  try {
+    const decoded = atob(b64Key);
+    // ML-KEM-768 public key is 1184 bytes
+    return decoded.length >= 1000 && decoded.length <= 1500;
+  } catch {
+    return false;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// ROTATION AGE
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Calculate days since last rotation.
+ */
+export function daysSinceRotation(lastRotatedAt?: string, createdAt?: string): number {
+  const dateStr = lastRotatedAt || createdAt;
+  if (!dateStr) return 0;
+
+  const date = new Date(dateStr);
+  const now = new Date();
+  const diffMs = now.getTime() - date.getTime();
+  return Math.floor(diffMs / (1000 * 60 * 60 * 24));
+}
+
+/**
+ * Check if keys should be rotated (default: 90 days).
+ */
+export function shouldRotate(lastRotatedAt?: string, createdAt?: string, maxDays: number = 90): boolean {
+  return daysSinceRotation(lastRotatedAt, createdAt) >= maxDays;
+}

package/src/utils/index.ts

@@ -0,0 +1,25 @@
+/**
+ * Omnituum PQC Shared - Utils Exports
+ */
+
+// Entropy
+export {
+  generateId,
+  generateShortId,
+  calculateShannonEntropy,
+  calculateEntropyScore,
+  hasGoodEntropy,
+  isValidX25519Key,
+  isValidKyberKey,
+  daysSinceRotation,
+  shouldRotate,
+} from './entropy';
+
+// Integrity
+export {
+  computeIntegrityHash,
+  computeHashAsync,
+  verifyIntegrity,
+  computeKeyFingerprint,
+  formatFingerprint,
+} from './integrity';

package/src/utils/integrity.ts

@@ -0,0 +1,95 @@
+/**
+ * Omnituum PQC Shared - Integrity Verification
+ *
+ * SHA-256 based integrity checking for vault contents.
+ */
+
+import type { HybridIdentityRecord } from '../vault/types';
+import { toHex } from '../crypto/primitives';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// INTEGRITY HASH
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Compute SHA-256 integrity hash for a list of identities.
+ * Uses only the public keys and metadata to create a deterministic hash.
+ */
+export function computeIntegrityHash(identities: HybridIdentityRecord[]): string {
+  // Create a deterministic representation (exclude secret keys from hash input)
+  const canonical = identities.map(i => ({
+    id: i.id,
+    name: i.name,
+    x25519PubHex: i.x25519PubHex,
+    kyberPubB64: i.kyberPubB64,
+    createdAt: i.createdAt,
+    rotationCount: i.rotationCount,
+  }));
+
+  const serialized = JSON.stringify(canonical, Object.keys(canonical[0] || {}).sort());
+  return computeStringHash(serialized);
+}
+
+/**
+ * Compute SHA-256 hash of a string (synchronous fallback).
+ */
+function computeStringHash(str: string): string {
+  // Simple hash for sync operation - actual implementation uses Web Crypto
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    const char = str.charCodeAt(i);
+    hash = ((hash << 5) - hash) + char;
+    hash = hash & hash;
+  }
+  return Math.abs(hash).toString(16).padStart(16, '0');
+}
+
+/**
+ * Compute SHA-256 hash asynchronously using Web Crypto or Node fallback.
+ */
+export async function computeHashAsync(data: string): Promise<string> {
+  const encoder = new TextEncoder();
+  const bytes = encoder.encode(data);
+
+  // Browser/WebCrypto path
+  const subtle = globalThis.crypto?.subtle;
+  if (subtle) {
+    const hashBuffer = await subtle.digest('SHA-256', bytes);
+    return toHex(new Uint8Array(hashBuffer));
+  }
+
+  // Node fallback (always available, no async shim dependency)
+  const { createHash } = await import('node:crypto');
+  return toHex(new Uint8Array(createHash('sha256').update(bytes).digest()));
+}
+
+/**
+ * Verify vault integrity.
+ */
+export async function verifyIntegrity(
+  identities: HybridIdentityRecord[],
+  expectedHash: string
+): Promise<boolean> {
+  const computed = computeIntegrityHash(identities);
+  return computed === expectedHash;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// KEY FINGERPRINTS
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Compute a short fingerprint for an identity's public keys.
+ */
+export async function computeKeyFingerprint(identity: HybridIdentityRecord): Promise<string> {
+  const combined = identity.x25519PubHex + identity.kyberPubB64;
+  const hash = await computeHashAsync(combined);
+  return hash.slice(0, 16).toUpperCase();
+}
+
+/**
+ * Format a fingerprint for display (groups of 4).
+ */
+export function formatFingerprint(fingerprint: string): string {
+  return fingerprint.match(/.{1,4}/g)?.join(' ') || fingerprint;
+}