@omnituum/pqc-shared 0.2.6

package/src/crypto/primitives/chacha.ts

@@ -0,0 +1,211 @@
+/**
+ * Omnituum PQC Shared - ChaCha20-Poly1305 Primitives
+ *
+ * AEAD ciphers for authenticated encryption:
+ * - ChaCha20-Poly1305: Standard AEAD (12-byte nonce)
+ * - XChaCha20-Poly1305: Extended nonce variant (24-byte nonce)
+ *
+ * Used in Noise protocols and general-purpose encryption.
+ */
+
+import { chacha20poly1305, xchacha20poly1305 } from '@noble/ciphers/chacha';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// TYPES
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface ChaChaPayload {
+  /** Nonce (12 bytes for standard, 24 bytes for xchacha) */
+  nonce: Uint8Array;
+  /** Ciphertext with Poly1305 tag (16 bytes appended) */
+  ciphertext: Uint8Array;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// CHACHA20-POLY1305 (12-byte nonce)
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Encrypt using ChaCha20-Poly1305.
+ *
+ * @param key - 32-byte encryption key
+ * @param nonce - 12-byte nonce (must be unique per key)
+ * @param plaintext - Data to encrypt
+ * @param aad - Optional additional authenticated data
+ * @returns Ciphertext with Poly1305 tag appended
+ */
+export function chaCha20Poly1305Encrypt(
+  key: Uint8Array,
+  nonce: Uint8Array,
+  plaintext: Uint8Array,
+  aad?: Uint8Array
+): Uint8Array {
+  if (key.length !== 32) {
+    throw new Error('ChaCha20-Poly1305 key must be 32 bytes');
+  }
+  if (nonce.length !== 12) {
+    throw new Error('ChaCha20-Poly1305 nonce must be 12 bytes');
+  }
+
+  const cipher = chacha20poly1305(key, nonce, aad);
+  return cipher.encrypt(plaintext);
+}
+
+/**
+ * Decrypt using ChaCha20-Poly1305.
+ *
+ * @param key - 32-byte encryption key
+ * @param nonce - 12-byte nonce
+ * @param ciphertext - Ciphertext with Poly1305 tag
+ * @param aad - Optional additional authenticated data
+ * @returns Plaintext, or null if authentication fails
+ */
+export function chaCha20Poly1305Decrypt(
+  key: Uint8Array,
+  nonce: Uint8Array,
+  ciphertext: Uint8Array,
+  aad?: Uint8Array
+): Uint8Array | null {
+  if (key.length !== 32) {
+    throw new Error('ChaCha20-Poly1305 key must be 32 bytes');
+  }
+  if (nonce.length !== 12) {
+    throw new Error('ChaCha20-Poly1305 nonce must be 12 bytes');
+  }
+
+  try {
+    const cipher = chacha20poly1305(key, nonce, aad);
+    return cipher.decrypt(ciphertext);
+  } catch {
+    return null;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// XCHACHA20-POLY1305 (24-byte nonce)
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Encrypt using XChaCha20-Poly1305 (extended 24-byte nonce).
+ *
+ * XChaCha20-Poly1305 is preferred for most applications because:
+ * - 24-byte nonce can be safely generated randomly
+ * - No nonce collision risk with ~2^80 messages per key
+ *
+ * @param key - 32-byte encryption key
+ * @param nonce - 24-byte nonce (can be random)
+ * @param plaintext - Data to encrypt
+ * @param aad - Optional additional authenticated data
+ * @returns Ciphertext with Poly1305 tag appended
+ */
+export function xChaCha20Poly1305Encrypt(
+  key: Uint8Array,
+  nonce: Uint8Array,
+  plaintext: Uint8Array,
+  aad?: Uint8Array
+): Uint8Array {
+  if (key.length !== 32) {
+    throw new Error('XChaCha20-Poly1305 key must be 32 bytes');
+  }
+  if (nonce.length !== 24) {
+    throw new Error('XChaCha20-Poly1305 nonce must be 24 bytes');
+  }
+
+  const cipher = xchacha20poly1305(key, nonce, aad);
+  return cipher.encrypt(plaintext);
+}
+
+/**
+ * Decrypt using XChaCha20-Poly1305.
+ *
+ * @param key - 32-byte encryption key
+ * @param nonce - 24-byte nonce
+ * @param ciphertext - Ciphertext with Poly1305 tag
+ * @param aad - Optional additional authenticated data
+ * @returns Plaintext, or null if authentication fails
+ */
+export function xChaCha20Poly1305Decrypt(
+  key: Uint8Array,
+  nonce: Uint8Array,
+  ciphertext: Uint8Array,
+  aad?: Uint8Array
+): Uint8Array | null {
+  if (key.length !== 32) {
+    throw new Error('XChaCha20-Poly1305 key must be 32 bytes');
+  }
+  if (nonce.length !== 24) {
+    throw new Error('XChaCha20-Poly1305 nonce must be 24 bytes');
+  }
+
+  try {
+    const cipher = xchacha20poly1305(key, nonce, aad);
+    return cipher.decrypt(ciphertext);
+  } catch {
+    return null;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// FACTORY FUNCTIONS (for Noise protocol compatibility)
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Create an XChaCha20-Poly1305 cipher instance.
+ * Compatible with @noble/ciphers API used in noise-kyber.
+ *
+ * @param key - 32-byte encryption key
+ * @param nonce - 24-byte nonce
+ * @param aad - Optional additional authenticated data
+ * @returns Cipher with encrypt/decrypt methods
+ */
+export function createXChaCha20Poly1305(
+  key: Uint8Array,
+  nonce: Uint8Array,
+  aad?: Uint8Array
+) {
+  if (key.length !== 32) {
+    throw new Error('XChaCha20-Poly1305 key must be 32 bytes');
+  }
+  if (nonce.length !== 24) {
+    throw new Error('XChaCha20-Poly1305 nonce must be 24 bytes');
+  }
+  return xchacha20poly1305(key, nonce, aad);
+}
+
+/**
+ * Create a ChaCha20-Poly1305 cipher instance.
+ *
+ * @param key - 32-byte encryption key
+ * @param nonce - 12-byte nonce
+ * @param aad - Optional additional authenticated data
+ * @returns Cipher with encrypt/decrypt methods
+ */
+export function createChaCha20Poly1305(
+  key: Uint8Array,
+  nonce: Uint8Array,
+  aad?: Uint8Array
+) {
+  if (key.length !== 32) {
+    throw new Error('ChaCha20-Poly1305 key must be 32 bytes');
+  }
+  if (nonce.length !== 12) {
+    throw new Error('ChaCha20-Poly1305 nonce must be 12 bytes');
+  }
+  return chacha20poly1305(key, nonce, aad);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// CONSTANTS
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** ChaCha20-Poly1305 key size (32 bytes) */
+export const CHACHA20_KEY_SIZE = 32;
+
+/** ChaCha20-Poly1305 nonce size (12 bytes) */
+export const CHACHA20_NONCE_SIZE = 12;
+
+/** XChaCha20-Poly1305 nonce size (24 bytes) */
+export const XCHACHA20_NONCE_SIZE = 24;
+
+/** Poly1305 tag size (16 bytes) */
+export const POLY1305_TAG_SIZE = 16;

package/src/crypto/primitives/hkdf.ts

@@ -0,0 +1,192 @@
+/**
+ * Omnituum PQC Shared - HKDF (HMAC-based Key Derivation Function)
+ *
+ * HKDF is a NIST-approved key derivation function (RFC 5869).
+ * Supports SHA-256 (default) and SHA-512 hash functions.
+ *
+ * Two-step process:
+ * 1. Extract: Derive a pseudorandom key from input keying material
+ * 2. Expand: Generate output keying material from the PRK
+ *
+ * Used in Noise protocols for key derivation.
+ */
+
+import { hkdf, extract, expand } from '@noble/hashes/hkdf';
+import { sha256 } from '@noble/hashes/sha256';
+import { sha512 } from '@noble/hashes/sha512';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// TYPES
+// ═══════════════════════════════════════════════════════════════════════════
+
+export type HkdfHash = 'sha256' | 'sha512';
+
+export interface HkdfOptions {
+  /** Hash function to use (default: 'sha256') */
+  hash?: HkdfHash;
+  /** Context info for domain separation */
+  info?: Uint8Array | string;
+  /** Salt (defaults to zeroes if not provided) */
+  salt?: Uint8Array;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// HKDF FUNCTIONS
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Derive keys using HKDF (Extract + Expand).
+ *
+ * @param ikm - Input keying material
+ * @param outputLength - Desired output length in bytes
+ * @param options - Optional salt, info, and hash selection
+ * @returns Derived key material
+ *
+ * @example
+ * ```ts
+ * // Basic key derivation
+ * const key = hkdfDerive(sharedSecret, 32);
+ *
+ * // With domain separation
+ * const key = hkdfDerive(sharedSecret, 32, {
+ *   info: 'MyApp v1.0 encryption key'
+ * });
+ *
+ * // With salt
+ * const key = hkdfDerive(sharedSecret, 32, {
+ *   salt: randomSalt,
+ *   info: 'session key'
+ * });
+ * ```
+ */
+export function hkdfDerive(
+  ikm: Uint8Array,
+  outputLength: number,
+  options?: HkdfOptions
+): Uint8Array {
+  const hashFn = getHashFunction(options?.hash ?? 'sha256');
+  const info = normalizeInfo(options?.info);
+  const salt = options?.salt;
+
+  return hkdf(hashFn, ikm, salt, info, outputLength);
+}
+
+/**
+ * HKDF-Extract: Derive a pseudorandom key from input keying material.
+ *
+ * @param ikm - Input keying material
+ * @param salt - Optional salt (defaults to zeroes)
+ * @param hash - Hash function ('sha256' or 'sha512')
+ * @returns Pseudorandom key (32 bytes for SHA-256, 64 for SHA-512)
+ */
+export function hkdfExtract(
+  ikm: Uint8Array,
+  salt?: Uint8Array,
+  hash: HkdfHash = 'sha256'
+): Uint8Array {
+  const hashFn = getHashFunction(hash);
+  return extract(hashFn, ikm, salt);
+}
+
+/**
+ * HKDF-Expand: Expand a pseudorandom key into output keying material.
+ *
+ * @param prk - Pseudorandom key (from hkdfExtract)
+ * @param info - Context info for domain separation
+ * @param outputLength - Desired output length in bytes
+ * @param hash - Hash function ('sha256' or 'sha512')
+ * @returns Output keying material
+ */
+export function hkdfExpand(
+  prk: Uint8Array,
+  info: Uint8Array | string | undefined,
+  outputLength: number,
+  hash: HkdfHash = 'sha256'
+): Uint8Array {
+  const hashFn = getHashFunction(hash);
+  return expand(hashFn, prk, normalizeInfo(info), outputLength);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// NOISE PROTOCOL HELPERS
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * HKDF for Noise protocol key derivation.
+ * Splits output into chaining key and output key.
+ *
+ * @param chainingKey - Current chaining key (salt)
+ * @param inputKeyMaterial - New key material to mix in
+ * @returns [newChainingKey, outputKey] - both 32 bytes
+ */
+export function hkdfSplitForNoise(
+  chainingKey: Uint8Array,
+  inputKeyMaterial: Uint8Array
+): [Uint8Array, Uint8Array] {
+  const prk = hkdfExtract(inputKeyMaterial, chainingKey, 'sha256');
+  const output = hkdfExpand(prk, undefined, 64, 'sha256');
+
+  return [
+    output.slice(0, 32),  // New chaining key
+    output.slice(32, 64), // Output key
+  ];
+}
+
+/**
+ * HKDF for Noise protocol with three outputs.
+ * Used when deriving transport keys at the end of handshake.
+ *
+ * @param chainingKey - Current chaining key
+ * @param inputKeyMaterial - Key material to mix
+ * @returns [ck, k1, k2] - chaining key and two output keys
+ */
+export function hkdfTripleSplitForNoise(
+  chainingKey: Uint8Array,
+  inputKeyMaterial: Uint8Array
+): [Uint8Array, Uint8Array, Uint8Array] {
+  const prk = hkdfExtract(inputKeyMaterial, chainingKey, 'sha256');
+  const output = hkdfExpand(prk, undefined, 96, 'sha256');
+
+  return [
+    output.slice(0, 32),   // New chaining key
+    output.slice(32, 64),  // Output key 1
+    output.slice(64, 96),  // Output key 2
+  ];
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// HELPERS
+// ═══════════════════════════════════════════════════════════════════════════
+
+function getHashFunction(hash: HkdfHash) {
+  switch (hash) {
+    case 'sha256':
+      return sha256;
+    case 'sha512':
+      return sha512;
+    default:
+      throw new Error(`Unsupported HKDF hash: ${hash}`);
+  }
+}
+
+function normalizeInfo(info: Uint8Array | string | undefined): Uint8Array {
+  if (!info) return new Uint8Array(0);
+  if (typeof info === 'string') return new TextEncoder().encode(info);
+  return info;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// CONSTANTS
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** HKDF-SHA256 output size (32 bytes) */
+export const HKDF_SHA256_OUTPUT_SIZE = 32;
+
+/** HKDF-SHA512 output size (64 bytes) */
+export const HKDF_SHA512_OUTPUT_SIZE = 64;
+
+/** Maximum HKDF output length for SHA-256 (255 * 32 = 8160 bytes) */
+export const HKDF_SHA256_MAX_OUTPUT = 255 * 32;
+
+/** Maximum HKDF output length for SHA-512 (255 * 64 = 16320 bytes) */
+export const HKDF_SHA512_MAX_OUTPUT = 255 * 64;

package/src/crypto/primitives/index.ts

@@ -0,0 +1,54 @@
+/**
+ * Omnituum PQC Shared - Cryptographic Primitives
+ *
+ * Low-level cryptographic building blocks for higher-level protocols.
+ * These are exported for use in noise-kyber and other protocol implementations.
+ *
+ * PRIMITIVES (use directly):
+ * - BLAKE3: Fast hash function for transcripts
+ * - ChaCha20-Poly1305: AEAD encryption (12-byte nonce)
+ * - XChaCha20-Poly1305: AEAD encryption (24-byte nonce, safer)
+ * - HKDF: Key derivation function (NIST-approved)
+ */
+
+// BLAKE3 hash function
+export {
+  blake3,
+  blake3Hex,
+  blake3Mac,
+  blake3DeriveKey,
+  BLAKE3_OUTPUT_LENGTH,
+  BLAKE3_KEY_LENGTH,
+  BLAKE3_BLOCK_SIZE,
+  type Blake3Options,
+} from './blake3';
+
+// ChaCha20-Poly1305 AEAD
+export {
+  chaCha20Poly1305Encrypt,
+  chaCha20Poly1305Decrypt,
+  xChaCha20Poly1305Encrypt,
+  xChaCha20Poly1305Decrypt,
+  createChaCha20Poly1305,
+  createXChaCha20Poly1305,
+  CHACHA20_KEY_SIZE,
+  CHACHA20_NONCE_SIZE,
+  XCHACHA20_NONCE_SIZE,
+  POLY1305_TAG_SIZE,
+  type ChaChaPayload,
+} from './chacha';
+
+// HKDF key derivation
+export {
+  hkdfDerive,
+  hkdfExtract,
+  hkdfExpand,
+  hkdfSplitForNoise,
+  hkdfTripleSplitForNoise,
+  HKDF_SHA256_OUTPUT_SIZE,
+  HKDF_SHA512_OUTPUT_SIZE,
+  HKDF_SHA256_MAX_OUTPUT,
+  HKDF_SHA512_MAX_OUTPUT,
+  type HkdfHash,
+  type HkdfOptions,
+} from './hkdf';

package/src/crypto/primitives.ts

@@ -0,0 +1,144 @@
+/**
+ * Omnituum PQC Shared - Cryptographic Primitives
+ *
+ * Pure browser implementation - no Node.js dependencies.
+ * Uses Web Crypto API and @noble/hashes for all operations.
+ */
+
+import { sha256 as nobleSha256 } from '@noble/hashes/sha256';
+import { hmac } from '@noble/hashes/hmac';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// TEXT ENCODING
+// ═══════════════════════════════════════════════════════════════════════════
+
+export const textEncoder = new TextEncoder();
+export const textDecoder = new TextDecoder();
+
+// ═══════════════════════════════════════════════════════════════════════════
+// BASE64 UTILITIES
+// ═══════════════════════════════════════════════════════════════════════════
+
+export function toB64(bytes: Uint8Array): string {
+  let binary = '';
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+
+export function fromB64(str: string): Uint8Array {
+  const binary = atob(str);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// HEX UTILITIES
+// ═══════════════════════════════════════════════════════════════════════════
+
+export function toHex(bytes: Uint8Array): string {
+  return Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('');
+}
+
+export function fromHex(hex: string): Uint8Array {
+  const s = hex.startsWith('0x') ? hex.slice(2) : hex;
+  const normalized = s.length % 2 ? '0' + s : s;
+  const out = new Uint8Array(normalized.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    out[i] = parseInt(normalized.slice(i * 2, i * 2 + 2), 16);
+  }
+  return out;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// VALIDATION
+// ═══════════════════════════════════════════════════════════════════════════
+
+export function assertLen(label: string, arr: Uint8Array, n: number): void {
+  if (arr.length !== n) {
+    throw new Error(`${label} must be ${n} bytes, got ${arr.length}`);
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// RANDOMNESS (Web Crypto API)
+// ═══════════════════════════════════════════════════════════════════════════
+
+export function rand32(): Uint8Array {
+  return globalThis.crypto.getRandomValues(new Uint8Array(32));
+}
+
+export function rand24(): Uint8Array {
+  return globalThis.crypto.getRandomValues(new Uint8Array(24));
+}
+
+export function rand12(): Uint8Array {
+  return globalThis.crypto.getRandomValues(new Uint8Array(12));
+}
+
+export function randN(n: number): Uint8Array {
+  return globalThis.crypto.getRandomValues(new Uint8Array(n));
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// HASHING (@noble/hashes)
+// ═══════════════════════════════════════════════════════════════════════════
+
+export function sha256(bytes: Uint8Array): Uint8Array {
+  return nobleSha256(bytes);
+}
+
+export function sha256String(str: string): Uint8Array {
+  return sha256(textEncoder.encode(str));
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// KEY DERIVATION (HKDF-SHA-256)
+// ═══════════════════════════════════════════════════════════════════════════
+
+export function hkdfSha256(
+  ikm: Uint8Array,
+  opts?: { salt?: Uint8Array; info?: Uint8Array; length?: number }
+): Uint8Array {
+  const salt = opts?.salt ?? new Uint8Array(32);
+  const info = opts?.info ?? new Uint8Array(0);
+  const L = opts?.length ?? 32;
+
+  // Extract
+  const prk = hmac(nobleSha256, salt, ikm);
+
+  // Expand
+  let t = new Uint8Array(0);
+  const chunks: Uint8Array[] = [];
+  for (let i = 1; i <= Math.ceil(L / 32); i++) {
+    const input = new Uint8Array(t.length + info.length + 1);
+    input.set(t, 0);
+    input.set(info, t.length);
+    input[input.length - 1] = i;
+    t = new Uint8Array(hmac(nobleSha256, prk, input));
+    chunks.push(t);
+  }
+
+  const out = new Uint8Array(L);
+  let off = 0;
+  for (const c of chunks) {
+    out.set(c.subarray(0, L - off), off);
+    off += c.length;
+    if (off >= L) break;
+  }
+  return out;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// CONVENIENCE EXPORTS
+// ═══════════════════════════════════════════════════════════════════════════
+
+export const b64 = toB64;
+export const ub64 = fromB64;
+
+export const u8 = (s: string | Uint8Array) =>
+  typeof s === 'string' ? textEncoder.encode(s) : s;