@omnituum/pqc-shared 0.2.6

package/src/fs/decrypt.ts

@@ -0,0 +1,320 @@
+/**
+ * Omnituum FS - File Decryption
+ *
+ * Decrypt .oqe (Omnituum Quantum Encrypted) files using hybrid PQC or password.
+ */
+
+import nacl from 'tweetnacl';
+import {
+  fromHex,
+  hkdfSha256,
+  toB64,
+  u8,
+} from '../crypto/primitives';
+import { kyberDecapsulate, isKyberAvailable } from '../crypto/kyber';
+import {
+  ALGORITHM_SUITES,
+  OQEMetadata,
+  HybridDecryptOptions,
+  PasswordDecryptOptions,
+  DecryptOptions,
+  OQEDecryptResult,
+  OQEError,
+  FileInput,
+  toUint8Array,
+} from './types';
+import { deriveKeyFromPassword, isArgon2Available } from './argon2';
+import { aesDecrypt } from './aes';
+import {
+  parseOQEFile,
+  parseHybridKeyMaterial,
+  parsePasswordKeyMaterial,
+  parseMetadata,
+} from './format';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// HELPERS
+// ═══════════════════════════════════════════════════════════════════════════
+
+function hkdfFlex(ikm: Uint8Array, salt: string, info: string): Uint8Array {
+  return hkdfSha256(ikm, { salt: u8(salt), info: u8(info), length: 32 });
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// HYBRID MODE DECRYPTION
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Decrypt an OQE file using hybrid X25519 + Kyber768.
+ * Tries Kyber first (post-quantum), falls back to X25519 (classical).
+ */
+async function decryptHybrid(
+  encryptedData: Uint8Array,
+  options: HybridDecryptOptions
+): Promise<OQEDecryptResult> {
+  // Parse file structure
+  const { header, keyMaterial, encryptedMetadata, encryptedContent } = parseOQEFile(encryptedData);
+
+  // Verify algorithm
+  if (header.algorithmSuite !== ALGORITHM_SUITES.HYBRID_X25519_KYBER768_AES256GCM) {
+    throw new OQEError(
+      'UNSUPPORTED_ALGORITHM',
+      'This file was not encrypted with hybrid mode. Use password decryption.'
+    );
+  }
+
+  // Parse key material
+  const km = parseHybridKeyMaterial(keyMaterial);
+
+  let contentKey: Uint8Array | null = null;
+
+  // Try Kyber first (post-quantum path)
+  if (await isKyberAvailable()) {
+    try {
+      // Kyber decapsulate expects base64 ciphertext
+      const kyberShared = await kyberDecapsulate(
+        toB64(km.kyberCiphertext),
+        options.recipientSecretKeys.kyberSecB64
+      );
+      const kyberKek = hkdfFlex(kyberShared, 'omnituum/fs/kyber', 'wrap-content-key');
+      const unwrapped = nacl.secretbox.open(km.kyberWrappedKey, km.kyberNonce, kyberKek);
+
+      if (unwrapped) {
+        contentKey = unwrapped;
+        console.log('[OQE] Decrypted content key via Kyber (post-quantum secure)');
+      }
+    } catch (e) {
+      console.warn('[OQE] Kyber decapsulation failed, trying X25519:', e);
+    }
+  }
+
+  // Fall back to X25519 (classical path)
+  if (!contentKey) {
+    try {
+      const ephPk = km.x25519EphemeralPk;
+      const sk = fromHex(options.recipientSecretKeys.x25519SecHex);
+      const x25519Shared = nacl.scalarMult(sk, ephPk);
+      const x25519Kek = hkdfFlex(x25519Shared, 'omnituum/fs/x25519', 'wrap-content-key');
+      const unwrapped = nacl.secretbox.open(km.x25519WrappedKey, km.x25519Nonce, x25519Kek);
+
+      if (unwrapped) {
+        contentKey = unwrapped;
+        console.log('[OQE] Decrypted content key via X25519 (classical)');
+      }
+    } catch (e) {
+      console.warn('[OQE] X25519 decryption failed:', e);
+    }
+  }
+
+  if (!contentKey) {
+    throw new OQEError('KEY_UNWRAP_FAILED', 'Could not unwrap content key with provided keys');
+  }
+
+  // Decrypt metadata
+  let metadata: OQEMetadata;
+  try {
+    const metadataBytes = await aesDecrypt(encryptedMetadata, contentKey, header.iv);
+    metadata = parseMetadata(metadataBytes);
+  } catch (e) {
+    throw new OQEError('DECRYPTION_FAILED', 'Failed to decrypt file metadata');
+  }
+
+  // Decrypt file content
+  let plaintext: Uint8Array;
+  try {
+    plaintext = await aesDecrypt(encryptedContent, contentKey, header.iv);
+  } catch (e) {
+    throw new OQEError('DECRYPTION_FAILED', 'Failed to decrypt file content');
+  }
+
+  return {
+    data: plaintext,
+    filename: metadata.filename,
+    mimeType: metadata.mimeType,
+    originalSize: metadata.originalSize,
+    metadata,
+    mode: 'hybrid',
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// PASSWORD MODE DECRYPTION
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Decrypt an OQE file using password (Argon2id + AES-256-GCM).
+ */
+async function decryptPassword(
+  encryptedData: Uint8Array,
+  options: PasswordDecryptOptions
+): Promise<OQEDecryptResult> {
+  // Verify Argon2 is available
+  if (!(await isArgon2Available())) {
+    throw new OQEError('ARGON2_UNAVAILABLE', 'Argon2 library not available in this environment');
+  }
+
+  // Parse file structure
+  const { header, keyMaterial, encryptedMetadata, encryptedContent } = parseOQEFile(encryptedData);
+
+  // Verify algorithm
+  if (header.algorithmSuite !== ALGORITHM_SUITES.PASSWORD_ARGON2ID_AES256GCM) {
+    throw new OQEError(
+      'UNSUPPORTED_ALGORITHM',
+      'This file was not encrypted with password mode. Use hybrid decryption.'
+    );
+  }
+
+  // Parse key material (Argon2 parameters)
+  const km = parsePasswordKeyMaterial(keyMaterial);
+
+  // Derive content key from password
+  const contentKey = await deriveKeyFromPassword(options.password, km.salt, {
+    memoryCost: km.memoryCost,
+    timeCost: km.timeCost,
+    parallelism: km.parallelism,
+    hashLength: 32,
+    saltLength: km.salt.length,
+  });
+
+  // Decrypt metadata (also verifies password)
+  let metadata: OQEMetadata;
+  try {
+    const metadataBytes = await aesDecrypt(encryptedMetadata, contentKey, header.iv);
+    metadata = parseMetadata(metadataBytes);
+  } catch (e) {
+    throw new OQEError('PASSWORD_WRONG', 'Incorrect password or corrupted file');
+  }
+
+  // Decrypt file content
+  let plaintext: Uint8Array;
+  try {
+    plaintext = await aesDecrypt(encryptedContent, contentKey, header.iv);
+  } catch (e) {
+    throw new OQEError('DECRYPTION_FAILED', 'Failed to decrypt file content');
+  }
+
+  return {
+    data: plaintext,
+    filename: metadata.filename,
+    mimeType: metadata.mimeType,
+    originalSize: metadata.originalSize,
+    metadata,
+    mode: 'password',
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// MAIN DECRYPTION API
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Decrypt an OQE file.
+ *
+ * @param encryptedData - Encrypted .oqe file data
+ * @param options - Decryption options (hybrid or password mode)
+ * @returns Decrypted file result
+ *
+ * @example
+ * // Hybrid mode (with identity)
+ * const result = await decryptFile(oqeData, {
+ *   mode: 'hybrid',
+ *   recipientSecretKeys: identity.getSecretKeys(),
+ * });
+ *
+ * @example
+ * // Password mode
+ * const result = await decryptFile(oqeData, {
+ *   mode: 'password',
+ *   password: 'my-secure-password',
+ * });
+ */
+export async function decryptFile(
+  encryptedData: FileInput,
+  options: DecryptOptions
+): Promise<OQEDecryptResult> {
+  const data = await toUint8Array(encryptedData);
+
+  if (options.mode === 'hybrid') {
+    return decryptHybrid(data, options);
+  } else {
+    return decryptPassword(data, options);
+  }
+}
+
+/**
+ * Decrypt a file encrypted for self.
+ * Convenience method for personal file decryption.
+ */
+export async function decryptFileForSelf(
+  encryptedData: FileInput,
+  identity: {
+    x25519SecHex: string;
+    kyberSecB64: string;
+  }
+): Promise<OQEDecryptResult> {
+  return decryptFile(encryptedData, {
+    mode: 'hybrid',
+    recipientSecretKeys: {
+      x25519SecHex: identity.x25519SecHex,
+      kyberSecB64: identity.kyberSecB64,
+    },
+  });
+}
+
+/**
+ * Quick decrypt with password (simple API).
+ */
+export async function decryptFileWithPassword(
+  encryptedData: FileInput,
+  password: string
+): Promise<OQEDecryptResult> {
+  return decryptFile(encryptedData, {
+    mode: 'password',
+    password,
+  });
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// FILE INSPECTION (without decryption)
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface OQEFileInfo {
+  /** Format version */
+  version: number;
+  /** Encryption mode */
+  mode: 'hybrid' | 'password';
+  /** Algorithm name */
+  algorithm: string;
+  /** Can decrypt with Kyber (for hybrid mode) */
+  supportsKyber: boolean;
+  /** File size */
+  fileSize: number;
+}
+
+/**
+ * Inspect an OQE file without decrypting it.
+ * Useful for determining what credentials are needed.
+ */
+export async function inspectOQEFile(data: FileInput): Promise<OQEFileInfo> {
+  const bytes = await toUint8Array(data);
+  const { header } = parseOQEFile(bytes);
+
+  let mode: 'hybrid' | 'password';
+  let algorithm: string;
+
+  if (header.algorithmSuite === ALGORITHM_SUITES.HYBRID_X25519_KYBER768_AES256GCM) {
+    mode = 'hybrid';
+    algorithm = 'X25519 + Kyber768 + AES-256-GCM';
+  } else {
+    mode = 'password';
+    algorithm = 'Argon2id + AES-256-GCM';
+  }
+
+  return {
+    version: header.version,
+    mode,
+    algorithm,
+    supportsKyber: mode === 'hybrid' && (await isKyberAvailable()),
+    fileSize: bytes.length,
+  };
+}

package/src/fs/encrypt.ts

@@ -0,0 +1,324 @@
+/**
+ * Omnituum FS - File Encryption
+ *
+ * Encrypt files using hybrid post-quantum cryptography or password-based encryption.
+ * Outputs .oqe (Omnituum Quantum Encrypted) files.
+ */
+
+import nacl from 'tweetnacl';
+import {
+  rand32,
+  rand24,
+  rand12,
+  toHex,
+  fromHex,
+  hkdfSha256,
+  sha256,
+  u8,
+} from '../crypto/primitives';
+import { kyberEncapsulate, isKyberAvailable } from '../crypto/kyber';
+import {
+  OQE_FORMAT_VERSION,
+  ALGORITHM_SUITES,
+  OQEMetadata,
+  OQEHeader,
+  HybridKeyMaterial,
+  PasswordKeyMaterial,
+  HybridEncryptOptions,
+  PasswordEncryptOptions,
+  EncryptOptions,
+  OQEEncryptResult,
+  OQEError,
+  FileInput,
+  toUint8Array,
+  DEFAULT_ARGON2ID_PARAMS,
+} from './types';
+import { deriveKeyFromPassword, generateArgon2Salt, isArgon2Available } from './argon2';
+import { aesEncrypt } from './aes';
+import {
+  serializeHybridKeyMaterial,
+  serializePasswordKeyMaterial,
+  serializeMetadata,
+  assembleOQEFile,
+  addOQEExtension,
+} from './format';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// HELPERS
+// ═══════════════════════════════════════════════════════════════════════════
+
+function hkdfFlex(ikm: Uint8Array, salt: string, info: string): Uint8Array {
+  return hkdfSha256(ikm, { salt: u8(salt), info: u8(info), length: 32 });
+}
+
+function computeIdentityHash(publicKeyHex: string): string {
+  const hash = sha256(fromHex(publicKeyHex));
+  return toHex(hash).slice(0, 16); // First 8 bytes = 16 hex chars
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// HYBRID MODE ENCRYPTION
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Encrypt a file using hybrid X25519 + Kyber768 encryption.
+ * Provides post-quantum security through dual-algorithm key wrapping.
+ */
+async function encryptHybrid(
+  plaintext: Uint8Array,
+  metadata: OQEMetadata,
+  options: HybridEncryptOptions
+): Promise<OQEEncryptResult> {
+  // Verify Kyber is available
+  if (!(await isKyberAvailable())) {
+    throw new OQEError('KYBER_UNAVAILABLE', 'Kyber library not available in this environment');
+  }
+
+  // 1. Generate random content key (32 bytes for AES-256)
+  const contentKey = rand32();
+
+  // 2. Generate IV for AES-GCM
+  const iv = rand12();
+
+  // 3. Wrap content key with X25519 ECDH
+  const x25519EphKp = nacl.box.keyPair();
+  const recipientX25519Pk = fromHex(options.recipientPublicKeys.x25519PubHex);
+  const x25519Shared = nacl.scalarMult(x25519EphKp.secretKey, recipientX25519Pk);
+  const x25519Kek = hkdfFlex(x25519Shared, 'omnituum/fs/x25519', 'wrap-content-key');
+  const x25519Nonce = rand24();
+  const x25519WrappedKey = nacl.secretbox(contentKey, x25519Nonce, x25519Kek);
+
+  // 4. Wrap content key with Kyber KEM
+  const kyberResult = await kyberEncapsulate(options.recipientPublicKeys.kyberPubB64);
+  const kyberKek = hkdfFlex(kyberResult.sharedSecret, 'omnituum/fs/kyber', 'wrap-content-key');
+  const kyberNonce = rand24();
+  const kyberWrappedKey = nacl.secretbox(contentKey, kyberNonce, kyberKek);
+
+  // 5. Serialize key material
+  const keyMaterial: HybridKeyMaterial = {
+    x25519EphemeralPk: x25519EphKp.publicKey,
+    x25519Nonce,
+    x25519WrappedKey,
+    kyberCiphertext: kyberResult.ciphertext,
+    kyberNonce,
+    kyberWrappedKey,
+  };
+  const keyMaterialBytes = serializeHybridKeyMaterial(keyMaterial);
+
+  // 6. Encrypt metadata
+  const metadataBytes = serializeMetadata(metadata);
+  const { ciphertext: encryptedMetadata } = await aesEncrypt(metadataBytes, contentKey, iv);
+
+  // 7. Encrypt file content
+  const { ciphertext: encryptedContent } = await aesEncrypt(plaintext, contentKey, iv);
+
+  // 8. Build header
+  const header: OQEHeader = {
+    version: OQE_FORMAT_VERSION,
+    algorithmSuite: ALGORITHM_SUITES.HYBRID_X25519_KYBER768_AES256GCM,
+    flags: 0,
+    metadataLength: encryptedMetadata.length,
+    keyMaterialLength: keyMaterialBytes.length,
+    iv,
+  };
+
+  // 9. Assemble complete file
+  const fileData = assembleOQEFile({
+    header,
+    keyMaterial: keyMaterialBytes,
+    encryptedMetadata,
+    encryptedContent,
+  });
+
+  return {
+    data: fileData,
+    filename: addOQEExtension(metadata.filename),
+    metadata,
+    mode: 'hybrid',
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// PASSWORD MODE ENCRYPTION
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Encrypt a file using password-based encryption (Argon2id + AES-256-GCM).
+ * Suitable for standalone file protection without identity system.
+ */
+async function encryptPassword(
+  plaintext: Uint8Array,
+  metadata: OQEMetadata,
+  options: PasswordEncryptOptions
+): Promise<OQEEncryptResult> {
+  // Verify Argon2 is available
+  if (!(await isArgon2Available())) {
+    throw new OQEError('ARGON2_UNAVAILABLE', 'Argon2 library not available in this environment');
+  }
+
+  // Merge user params with defaults
+  const params = {
+    ...DEFAULT_ARGON2ID_PARAMS,
+    ...options.argon2Params,
+  };
+
+  // 1. Generate salt
+  const salt = generateArgon2Salt(params.saltLength);
+
+  // 2. Derive content key from password
+  const contentKey = await deriveKeyFromPassword(options.password, salt, params);
+
+  // 3. Generate IV for AES-GCM
+  const iv = rand12();
+
+  // 4. Serialize key material (Argon2 params + salt)
+  const keyMaterial: PasswordKeyMaterial = {
+    salt,
+    memoryCost: params.memoryCost,
+    timeCost: params.timeCost,
+    parallelism: params.parallelism,
+  };
+  const keyMaterialBytes = serializePasswordKeyMaterial(keyMaterial);
+
+  // 5. Encrypt metadata
+  const metadataBytes = serializeMetadata(metadata);
+  const { ciphertext: encryptedMetadata } = await aesEncrypt(metadataBytes, contentKey, iv);
+
+  // 6. Encrypt file content
+  const { ciphertext: encryptedContent } = await aesEncrypt(plaintext, contentKey, iv);
+
+  // 7. Build header
+  const header: OQEHeader = {
+    version: OQE_FORMAT_VERSION,
+    algorithmSuite: ALGORITHM_SUITES.PASSWORD_ARGON2ID_AES256GCM,
+    flags: 0,
+    metadataLength: encryptedMetadata.length,
+    keyMaterialLength: keyMaterialBytes.length,
+    iv,
+  };
+
+  // 8. Assemble complete file
+  const fileData = assembleOQEFile({
+    header,
+    keyMaterial: keyMaterialBytes,
+    encryptedMetadata,
+    encryptedContent,
+  });
+
+  return {
+    data: fileData,
+    filename: addOQEExtension(metadata.filename),
+    metadata,
+    mode: 'password',
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// MAIN ENCRYPTION API
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface EncryptFileInput {
+  /** File data */
+  data: FileInput;
+  /** Original filename */
+  filename: string;
+  /** Optional MIME type */
+  mimeType?: string;
+}
+
+/**
+ * Encrypt a file using hybrid PQC or password-based encryption.
+ *
+ * @param input - File data and metadata
+ * @param options - Encryption options (hybrid or password mode)
+ * @returns Encrypted .oqe file result
+ *
+ * @example
+ * // Hybrid mode (with identity)
+ * const result = await encryptFile(
+ *   { data: fileBytes, filename: 'secret.pdf' },
+ *   {
+ *     mode: 'hybrid',
+ *     recipientPublicKeys: identity.getPublicKeys(),
+ *   }
+ * );
+ *
+ * @example
+ * // Password mode
+ * const result = await encryptFile(
+ *   { data: fileBytes, filename: 'secret.pdf' },
+ *   {
+ *     mode: 'password',
+ *     password: 'my-secure-password',
+ *   }
+ * );
+ */
+export async function encryptFile(
+  input: EncryptFileInput,
+  options: EncryptOptions
+): Promise<OQEEncryptResult> {
+  // Convert input to Uint8Array
+  const plaintext = await toUint8Array(input.data);
+
+  // Build metadata
+  const metadata: OQEMetadata = {
+    filename: input.filename,
+    originalSize: plaintext.length,
+    mimeType: input.mimeType,
+    encryptedAt: new Date().toISOString(),
+  };
+
+  // Add identity hashes for hybrid mode
+  if (options.mode === 'hybrid') {
+    metadata.recipientIdHash = computeIdentityHash(options.recipientPublicKeys.x25519PubHex);
+    if (options.sender) {
+      metadata.encryptorIdHash = options.sender.id;
+    }
+  }
+
+  // Encrypt based on mode
+  if (options.mode === 'hybrid') {
+    return encryptHybrid(plaintext, metadata, options);
+  } else {
+    return encryptPassword(plaintext, metadata, options);
+  }
+}
+
+/**
+ * Encrypt a file for self (encrypt and decrypt with same identity).
+ * Convenience method for personal file encryption.
+ */
+export async function encryptFileForSelf(
+  input: EncryptFileInput,
+  identity: {
+    id: string;
+    name?: string;
+    x25519PubHex: string;
+    kyberPubB64: string;
+  }
+): Promise<OQEEncryptResult> {
+  return encryptFile(input, {
+    mode: 'hybrid',
+    recipientPublicKeys: {
+      x25519PubHex: identity.x25519PubHex,
+      kyberPubB64: identity.kyberPubB64,
+    },
+    sender: {
+      id: identity.id,
+      name: identity.name,
+    },
+  });
+}
+
+/**
+ * Quick encrypt with password (simple API).
+ */
+export async function encryptFileWithPassword(
+  input: EncryptFileInput,
+  password: string
+): Promise<OQEEncryptResult> {
+  return encryptFile(input, {
+    mode: 'password',
+    password,
+  });
+}