@omnituum/pqc-shared 0.2.6

package/src/crypto/kyber.ts

@@ -0,0 +1,199 @@
+/**
+ * Omnituum PQC Shared - Kyber ML-KEM-768
+ *
+ * Browser-compatible Kyber operations using kyber-crystals.
+ * NIST Level 3 security - quantum-resistant.
+ */
+
+import { b64, ub64, sha256 } from './primitives';
+import nacl from 'tweetnacl';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// TYPES
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface KyberKeypair {
+  publicKey: Uint8Array;
+  secretKey: Uint8Array;
+}
+
+export interface KyberKeypairB64 {
+  publicB64: string;
+  secretB64: string;
+}
+
+export interface KyberEncapsulation {
+  ciphertext: Uint8Array;
+  sharedSecret: Uint8Array;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// KYBER LIBRARY LOADING
+// ═══════════════════════════════════════════════════════════════════════════
+
+let kyberModule: any = null;
+
+async function loadKyber(): Promise<any> {
+  if (kyberModule) return kyberModule;
+
+  try {
+    const m = await import('kyber-crystals');
+    const k = (m as any).default ?? m;
+    kyberModule = k.kyber ?? k;
+    return kyberModule;
+  } catch (e) {
+    console.warn('[Kyber] Failed to load kyber-crystals:', e);
+    return null;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// AVAILABILITY CHECK
+// ═══════════════════════════════════════════════════════════════════════════
+
+export async function isKyberAvailable(): Promise<boolean> {
+  const mod = await loadKyber();
+  return mod !== null;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// KEY GENERATION
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Generate a Kyber ML-KEM-768 keypair.
+ */
+export async function generateKyberKeypair(): Promise<KyberKeypairB64 | null> {
+  try {
+    const mod = await loadKyber();
+    if (!mod) return null;
+
+    if (mod?.ready?.then) {
+      await mod.ready;
+    }
+
+    const fn = mod?.keypair ?? mod?.keyPair ?? mod?.generateKeyPair ?? null;
+    if (typeof fn !== 'function') {
+      console.warn('[Kyber] No keypair function found');
+      return null;
+    }
+
+    const kp = await fn.call(mod);
+    const pub = kp?.publicKey ?? kp?.public ?? kp?.pk;
+    const priv = kp?.privateKey ?? kp?.secretKey ?? kp?.secret ?? kp?.sk;
+
+    if (!pub || !priv) {
+      console.warn('[Kyber] Invalid keypair result');
+      return null;
+    }
+
+    return {
+      publicB64: b64(new Uint8Array(pub)),
+      secretB64: b64(new Uint8Array(priv)),
+    };
+  } catch (e) {
+    console.warn('[Kyber] Key generation failed:', e);
+    return null;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// ENCAPSULATION / DECAPSULATION
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Encapsulate a shared secret using Kyber ML-KEM-768.
+ */
+export async function kyberEncapsulate(pubKeyB64: string): Promise<KyberEncapsulation> {
+  const kyber = await loadKyber();
+  if (!kyber?.encrypt) {
+    throw new Error('Kyber encrypt not available');
+  }
+
+  const pk = ub64(pubKeyB64);
+  const r: any = await kyber.encrypt(pk);
+
+  // Normalize ciphertext
+  const ctRaw =
+    r?.ciphertext ?? r?.cyphertext ?? r?.ct ??
+    r?.bytes?.ciphertext ?? r?.bytes?.cyphertext ?? r?.bytes?.ct ??
+    (Array.isArray(r) ? r[0] : undefined);
+
+  // Normalize shared secret
+  const ssRaw =
+    r?.key ?? r?.sharedSecret ?? r?.secret ??
+    r?.bytes?.key ?? r?.bytes?.sharedSecret ??
+    (Array.isArray(r) ? r[1] : undefined);
+
+  if (!ctRaw || !ssRaw) {
+    throw new Error('Kyber encapsulate failed: missing ciphertext or shared secret');
+  }
+
+  return {
+    ciphertext: new Uint8Array(ctRaw),
+    sharedSecret: new Uint8Array(ssRaw),
+  };
+}
+
+/**
+ * Decapsulate a shared secret using Kyber ML-KEM-768.
+ */
+export async function kyberDecapsulate(
+  kemCiphertextB64: string,
+  secretKeyB64: string
+): Promise<Uint8Array> {
+  const kyber = await loadKyber();
+  if (!kyber?.decrypt && !kyber?.decapsulate) {
+    throw new Error('Kyber decrypt/decapsulate not available');
+  }
+
+  const ct = ub64(kemCiphertextB64);
+  const sk = ub64(secretKeyB64);
+
+  const r: any = kyber.decrypt
+    ? await kyber.decrypt(ct, sk)
+    : await kyber.decapsulate(ct, sk);
+
+  const key = (r && (r.key ?? r.sharedSecret)) ? (r.key ?? r.sharedSecret) : r;
+  return new Uint8Array(key);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// KEY WRAPPING HELPERS
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Wrap a message key using Kyber shared secret.
+ */
+export function kyberWrapKey(sharedSecret: Uint8Array, msgKey32: Uint8Array): {
+  nonce: string;
+  wrapped: string;
+} {
+  if (msgKey32.length !== 32) {
+    throw new Error('Message key must be 32 bytes');
+  }
+
+  const kek = sha256(sharedSecret); // Derive KEK from shared secret
+  const nonce = globalThis.crypto.getRandomValues(new Uint8Array(24));
+  const wrapped = nacl.secretbox(msgKey32, nonce, kek);
+
+  return {
+    nonce: b64(nonce),
+    wrapped: b64(wrapped),
+  };
+}
+
+/**
+ * Unwrap a message key using Kyber shared secret.
+ */
+export function kyberUnwrapKey(
+  sharedSecret: Uint8Array,
+  nonceB64: string,
+  wrappedB64: string
+): Uint8Array | null {
+  const kek = sha256(sharedSecret);
+  const nonce = ub64(nonceB64);
+  const wrapped = ub64(wrappedB64);
+
+  return nacl.secretbox.open(wrapped, nonce, kek) || null;
+}

package/src/crypto/nacl.ts

@@ -0,0 +1,204 @@
+/**
+ * Omnituum PQC Shared - NaCl Secretbox Operations
+ *
+ * Symmetric encryption using XSalsa20-Poly1305 (NaCl secretbox).
+ * 32-byte key, 24-byte nonce, authenticated encryption.
+ */
+
+import nacl from 'tweetnacl';
+import { rand24, toB64, fromB64, assertLen } from './primitives';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// TYPES
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface SecretboxPayload {
+  /** Scheme identifier for format detection */
+  scheme: 'nacl.secretbox';
+  /** Nonce (base64, 24 bytes) */
+  nonce: string;
+  /** Ciphertext (base64, includes auth tag) */
+  ciphertext: string;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// ENCRYPTION
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Encrypt data using NaCl secretbox (XSalsa20-Poly1305).
+ *
+ * @param key - 32-byte symmetric key
+ * @param plaintext - Data to encrypt
+ * @param nonce - Optional 24-byte nonce (generated if not provided)
+ * @returns Encrypted payload with nonce and ciphertext
+ */
+export function secretboxEncrypt(
+  key: Uint8Array,
+  plaintext: Uint8Array,
+  nonce?: Uint8Array
+): SecretboxPayload {
+  assertLen('secretbox key', key, 32);
+
+  const n = nonce ?? rand24();
+  assertLen('nonce', n, 24);
+
+  const ciphertext = nacl.secretbox(plaintext, n, key);
+
+  return {
+    scheme: 'nacl.secretbox' as const,
+    nonce: toB64(n),
+    ciphertext: toB64(ciphertext),
+  };
+}
+
+/**
+ * Encrypt a string using NaCl secretbox.
+ */
+export function secretboxEncryptString(
+  key: Uint8Array,
+  plaintext: string,
+  nonce?: Uint8Array
+): SecretboxPayload {
+  return secretboxEncrypt(key, new TextEncoder().encode(plaintext), nonce);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// DECRYPTION
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Decrypt data using NaCl secretbox.
+ *
+ * @param key - 32-byte symmetric key
+ * @param payload - Encrypted payload from secretboxEncrypt
+ * @returns Decrypted data, or null if authentication fails
+ */
+export function secretboxDecrypt(
+  key: Uint8Array,
+  payload: SecretboxPayload
+): Uint8Array | null {
+  if (payload.scheme !== 'nacl.secretbox') {
+    return null;
+  }
+  assertLen('secretbox key', key, 32);
+
+  const nonce = fromB64(payload.nonce);
+  const ciphertext = fromB64(payload.ciphertext);
+
+  return nacl.secretbox.open(ciphertext, nonce, key) || null;
+}
+
+/**
+ * Decrypt to a string using NaCl secretbox.
+ */
+export function secretboxDecryptString(
+  key: Uint8Array,
+  payload: SecretboxPayload
+): string | null {
+  const result = secretboxDecrypt(key, payload);
+  if (!result) return null;
+  return new TextDecoder().decode(result);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// RAW OPERATIONS (for low-level use)
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Raw secretbox encryption (returns raw bytes).
+ */
+export function secretboxRaw(
+  key: Uint8Array,
+  plaintext: Uint8Array,
+  nonce: Uint8Array
+): Uint8Array {
+  assertLen('secretbox key', key, 32);
+  assertLen('nonce', nonce, 24);
+  return nacl.secretbox(plaintext, nonce, key);
+}
+
+/**
+ * Raw secretbox decryption (returns raw bytes).
+ */
+export function secretboxOpenRaw(
+  key: Uint8Array,
+  ciphertext: Uint8Array,
+  nonce: Uint8Array
+): Uint8Array | null {
+  assertLen('secretbox key', key, 32);
+  assertLen('nonce', nonce, 24);
+  return nacl.secretbox.open(ciphertext, nonce, key) || null;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// BOX OPERATIONS (authenticated public-key encryption)
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface BoxPayload {
+  /** Nonce (base64, 24 bytes) */
+  nonce: string;
+  /** Ciphertext (base64) */
+  ciphertext: string;
+}
+
+/**
+ * Encrypt data using NaCl box (X25519 + XSalsa20-Poly1305).
+ *
+ * @param plaintext - Data to encrypt
+ * @param nonce - 24-byte nonce
+ * @param recipientPubKey - Recipient's X25519 public key (32 bytes)
+ * @param senderSecKey - Sender's X25519 secret key (32 bytes)
+ * @returns Encrypted ciphertext
+ */
+export function boxEncrypt(
+  plaintext: Uint8Array,
+  nonce: Uint8Array,
+  recipientPubKey: Uint8Array,
+  senderSecKey: Uint8Array
+): Uint8Array {
+  assertLen('nonce', nonce, 24);
+  assertLen('recipient pubKey', recipientPubKey, 32);
+  assertLen('sender secKey', senderSecKey, 32);
+  return nacl.box(plaintext, nonce, recipientPubKey, senderSecKey);
+}
+
+/**
+ * Decrypt data using NaCl box.
+ *
+ * @param ciphertext - Encrypted data
+ * @param nonce - 24-byte nonce
+ * @param senderPubKey - Sender's X25519 public key (32 bytes)
+ * @param recipientSecKey - Recipient's X25519 secret key (32 bytes)
+ * @returns Decrypted data, or null if authentication fails
+ */
+export function boxDecrypt(
+  ciphertext: Uint8Array,
+  nonce: Uint8Array,
+  senderPubKey: Uint8Array,
+  recipientSecKey: Uint8Array
+): Uint8Array | null {
+  assertLen('nonce', nonce, 24);
+  assertLen('sender pubKey', senderPubKey, 32);
+  assertLen('recipient secKey', recipientSecKey, 32);
+  return nacl.box.open(ciphertext, nonce, senderPubKey, recipientSecKey) || null;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// CONSTANTS
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** NaCl secretbox key size (32 bytes) */
+export const SECRETBOX_KEY_SIZE = nacl.secretbox.keyLength;
+
+/** NaCl secretbox nonce size (24 bytes) */
+export const SECRETBOX_NONCE_SIZE = nacl.secretbox.nonceLength;
+
+/** NaCl secretbox overhead (16 bytes auth tag) */
+export const SECRETBOX_OVERHEAD = nacl.secretbox.overheadLength;
+
+/** NaCl box key size (32 bytes) */
+export const BOX_KEY_SIZE = nacl.box.publicKeyLength;
+
+/** NaCl box nonce size (24 bytes) */
+export const BOX_NONCE_SIZE = nacl.box.nonceLength;

package/src/crypto/primitives/blake3.ts

@@ -0,0 +1,141 @@
+/**
+ * Omnituum PQC Shared - BLAKE3 Hash Primitive
+ *
+ * BLAKE3 is a cryptographic hash function that provides:
+ * - Fast performance (faster than SHA-256, SHA-3)
+ * - 256-bit security (collision resistance)
+ * - Variable output length (default 32 bytes)
+ *
+ * Used in Noise protocols for transcript hashing.
+ */
+
+import { blake3 as nobleBlake3 } from '@noble/hashes/blake3';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// TYPES
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface Blake3Options {
+  /** Output length in bytes (default: 32) */
+  outputLength?: number;
+  /** Optional key for keyed hashing (32 bytes) */
+  key?: Uint8Array;
+  /** Optional context string for domain separation */
+  context?: string;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// BLAKE3 HASH
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Compute BLAKE3 hash of input data.
+ *
+ * @param data - Data to hash (Uint8Array or string)
+ * @param options - Optional configuration
+ * @returns BLAKE3 hash (default 32 bytes)
+ *
+ * @example
+ * ```ts
+ * // Simple hash
+ * const hash = blake3(new Uint8Array([1, 2, 3]));
+ *
+ * // Hash with context (domain separation)
+ * const hash = blake3(data, { context: 'MyApp v1.0 signing' });
+ *
+ * // Keyed hash (requires 32-byte key)
+ * const hash = blake3(data, { key: keyBytes });
+ *
+ * // Variable output length
+ * const hash = blake3(data, { outputLength: 64 });
+ * ```
+ */
+export function blake3(
+  data: Uint8Array | string,
+  options?: Blake3Options
+): Uint8Array {
+  const input = typeof data === 'string'
+    ? new TextEncoder().encode(data)
+    : data;
+
+  // @noble/hashes blake3 supports key and context options
+  const opts: { dkLen?: number; key?: Uint8Array; context?: Uint8Array } = {};
+
+  if (options?.outputLength) {
+    opts.dkLen = options.outputLength;
+  }
+
+  if (options?.key) {
+    if (options.key.length !== 32) {
+      throw new Error('BLAKE3 key must be exactly 32 bytes');
+    }
+    opts.key = options.key;
+  }
+
+  if (options?.context) {
+    opts.context = new TextEncoder().encode(options.context);
+  }
+
+  return nobleBlake3(input, opts);
+}
+
+/**
+ * Compute BLAKE3 hash and return as hex string.
+ */
+export function blake3Hex(
+  data: Uint8Array | string,
+  options?: Blake3Options
+): string {
+  const hash = blake3(data, options);
+  return Array.from(hash)
+    .map(b => b.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+/**
+ * Create a keyed BLAKE3 hash (MAC).
+ *
+ * @param key - 32-byte key
+ * @param data - Data to hash
+ * @returns BLAKE3-MAC (32 bytes by default)
+ */
+export function blake3Mac(
+  key: Uint8Array,
+  data: Uint8Array,
+  outputLength = 32
+): Uint8Array {
+  if (key.length !== 32) {
+    throw new Error('BLAKE3 MAC key must be exactly 32 bytes');
+  }
+  return blake3(data, { key, outputLength });
+}
+
+/**
+ * Derive a key from a context and key material using BLAKE3.
+ * This uses BLAKE3's built-in KDF mode.
+ *
+ * @param context - Domain separation string
+ * @param keyMaterial - Input key material
+ * @param outputLength - Desired output length (default 32)
+ * @returns Derived key
+ */
+export function blake3DeriveKey(
+  context: string,
+  keyMaterial: Uint8Array,
+  outputLength = 32
+): Uint8Array {
+  return blake3(keyMaterial, { context, outputLength });
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// CONSTANTS
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** Default BLAKE3 output length (32 bytes = 256 bits) */
+export const BLAKE3_OUTPUT_LENGTH = 32;
+
+/** BLAKE3 key length for keyed mode (32 bytes) */
+export const BLAKE3_KEY_LENGTH = 32;
+
+/** BLAKE3 block size (64 bytes) */
+export const BLAKE3_BLOCK_SIZE = 64;