@oqs/liboqs-js 0.15.0

package/src/cli/commands/kem.js

@@ -0,0 +1,91 @@
+/**
+ * @fileoverview KEM command handlers
+ */
+
+import { mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { getKemFactory } from '../algorithms.js';
+import { readInput, writeOutput } from '../io.js';
+
+export async function handleKemCommand(parsed) {
+  const { subcommand, args, options } = parsed;
+
+  switch (subcommand) {
+    case 'keygen':
+      return await kemKeygen(args[0], options);
+    case 'encapsulate':
+      return await kemEncapsulate(args[0], args[1], options);
+    case 'decapsulate':
+      return await kemDecapsulate(args[0], args[1], args[2], options);
+    default:
+      throw new Error(`Unknown KEM subcommand: ${subcommand}`);
+  }
+}
+
+async function kemKeygen(algorithm, options) {
+  if (!algorithm) {
+    throw new Error('Algorithm name required');
+  }
+
+  const factory = getKemFactory(algorithm);
+  const kem = await factory();
+
+  try {
+    const { publicKey, secretKey } = kem.generateKeyPair();
+
+    if (options.outputDir) {
+      await mkdir(options.outputDir, { recursive: true });
+      await writeOutput(publicKey, options.format, join(options.outputDir, 'public.key'));
+      await writeOutput(secretKey, options.format, join(options.outputDir, 'secret.key'));
+      console.log(`Keypair saved to ${options.outputDir}/`);
+    } else {
+      console.log('Public Key:');
+      await writeOutput(publicKey, options.format, null);
+      console.log('\nSecret Key:');
+      await writeOutput(secretKey, options.format, null);
+    }
+  } finally {
+    kem.destroy();
+  }
+}
+
+async function kemEncapsulate(algorithm, publicKeyInput, options) {
+  if (!algorithm || !publicKeyInput) {
+    throw new Error('Algorithm and public key required');
+  }
+
+  const factory = getKemFactory(algorithm);
+  const kem = await factory();
+
+  try {
+    const publicKey = await readInput(publicKeyInput, options.inputFormat);
+    const { ciphertext, sharedSecret } = kem.encapsulate(publicKey);
+
+    console.log('Ciphertext:');
+    await writeOutput(ciphertext, options.format, options.output ? options.output + '.ct' : null);
+    console.log('\nShared Secret:');
+    await writeOutput(sharedSecret, options.format, options.output ? options.output + '.ss' : null);
+  } finally {
+    kem.destroy();
+  }
+}
+
+async function kemDecapsulate(algorithm, ciphertextInput, secretKeyInput, options) {
+  if (!algorithm || !ciphertextInput || !secretKeyInput) {
+    throw new Error('Algorithm, ciphertext, and secret key required');
+  }
+
+  const factory = getKemFactory(algorithm);
+  const kem = await factory();
+
+  try {
+    const ciphertext = await readInput(ciphertextInput, options.inputFormat);
+    const secretKey = await readInput(secretKeyInput, options.inputFormat);
+    const sharedSecret = kem.decapsulate(ciphertext, secretKey);
+
+    console.log('Shared Secret:');
+    await writeOutput(sharedSecret, options.format, options.output);
+  } finally {
+    kem.destroy();
+  }
+}

package/src/cli/commands/list.js

@@ -0,0 +1,30 @@
+/**
+ * @fileoverview List command handler
+ */
+
+import { KEM_ALGORITHMS, SIG_ALGORITHMS } from '../algorithms.js';
+
+export function handleListCommand(parsed) {
+  const { options } = parsed;
+
+  if (options.kem) {
+    console.log('KEM Algorithms:');
+    Object.keys(KEM_ALGORITHMS).sort((a, b) => a.localeCompare(b)).forEach(alg => {
+      console.log(`  ${alg}`);
+    });
+  } else if (options.sig) {
+    console.log('Signature Algorithms:');
+    Object.keys(SIG_ALGORITHMS).sort((a, b) => a.localeCompare(b)).forEach(alg => {
+      console.log(`  ${alg}`);
+    });
+  } else {
+    console.log('KEM Algorithms:');
+    Object.keys(KEM_ALGORITHMS).sort((a, b) => a.localeCompare(b)).forEach(alg => {
+      console.log(`  ${alg}`);
+    });
+    console.log('\nSignature Algorithms:');
+    Object.keys(SIG_ALGORITHMS).sort((a, b) => a.localeCompare(b)).forEach(alg => {
+      console.log(`  ${alg}`);
+    });
+  }
+}

package/src/cli/commands/sig.js

@@ -0,0 +1,98 @@
+/**
+ * @fileoverview Signature command handlers
+ */
+
+import { mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { getSigFactory } from '../algorithms.js';
+import { readInput, writeOutput } from '../io.js';
+import process from "node:process";
+
+export async function handleSigCommand(parsed) {
+  const { subcommand, args, options } = parsed;
+
+  switch (subcommand) {
+    case 'keygen':
+      return await sigKeygen(args[0], options);
+    case 'sign':
+      return await sigSign(args[0], args[1], args[2], options);
+    case 'verify':
+      return await sigVerify(args[0], args[1], args[2], args[3], options);
+    default:
+      throw new Error(`Unknown SIG subcommand: ${subcommand}`);
+  }
+}
+
+async function sigKeygen(algorithm, options) {
+  if (!algorithm) {
+    throw new Error('Algorithm name required');
+  }
+
+  const factory = getSigFactory(algorithm);
+  const sig = await factory();
+
+  try {
+    const { publicKey, secretKey } = sig.generateKeyPair();
+
+    if (options.outputDir) {
+      await mkdir(options.outputDir, { recursive: true });
+      await writeOutput(publicKey, options.format, join(options.outputDir, 'public.key'));
+      await writeOutput(secretKey, options.format, join(options.outputDir, 'secret.key'));
+      console.log(`Keypair saved to ${options.outputDir}/`);
+    } else {
+      console.log('Public Key:');
+      await writeOutput(publicKey, options.format, null);
+      console.log('\nSecret Key:');
+      await writeOutput(secretKey, options.format, null);
+    }
+  } finally {
+    sig.destroy();
+  }
+}
+
+async function sigSign(algorithm, messageInput, secretKeyInput, options) {
+  if (!algorithm || !messageInput || !secretKeyInput) {
+    throw new Error('Algorithm, message, and secret key required');
+  }
+
+  const factory = getSigFactory(algorithm);
+  const sig = await factory();
+
+  try {
+    const message = await readInput(messageInput, options.inputFormat);
+    const secretKey = await readInput(secretKeyInput, options.inputFormat);
+    const signature = await sig.sign(message, secretKey);
+
+    console.log('Signature:');
+    await writeOutput(signature, options.format, options.output);
+  } finally {
+    sig.destroy();
+  }
+}
+
+async function sigVerify(algorithm, messageInput, signatureInput, publicKeyInput, options) {
+  if (!algorithm || !messageInput || !signatureInput || !publicKeyInput) {
+    throw new Error('Algorithm, message, signature, and public key required');
+  }
+
+  const factory = getSigFactory(algorithm);
+  const sig = await factory();
+
+  try {
+    const message = await readInput(messageInput, options.inputFormat);
+    const signature = await readInput(signatureInput, options.inputFormat);
+    const publicKey = await readInput(publicKeyInput, options.inputFormat);
+
+    const isValid = sig.verify(message, signature, publicKey);
+
+    if (isValid) {
+      console.log('✓ Signature is valid');
+      process.exit(0);
+    } else {
+      console.log('✗ Signature is invalid');
+      process.exit(1);
+    }
+  } finally {
+    sig.destroy();
+  }
+}

package/src/cli/index.js

@@ -0,0 +1,86 @@
+/**
+ * @fileoverview CLI main module
+ */
+
+import { parseArgs } from './parser.js';
+import { handleKemCommand } from './commands/kem.js';
+import { handleSigCommand } from './commands/sig.js';
+import { handleListCommand } from './commands/list.js';
+import { handleInfoCommand } from './commands/info.js';
+import process from "node:process";
+
+export function createCLI() {
+  return {
+    async parse(argv) {
+      const parsed = parseArgs(argv);
+
+      switch (parsed.command) {
+        case 'kem':
+          return await handleKemCommand(parsed);
+        case 'sig':
+          return await handleSigCommand(parsed);
+        case 'list':
+          return handleListCommand(parsed);
+        case 'info':
+          return handleInfoCommand(parsed);
+        case 'help':
+          printHelp();
+          break;
+        default:
+          printHelp();
+          process.exit(1);
+      }
+    }
+  };
+}
+
+function printHelp() {
+  console.log(`
+liboqs - Post-quantum cryptography CLI
+
+Usage:
+  liboqs <command> [options]
+
+Commands:
+  kem keygen <algorithm>                      Generate KEM keypair
+  kem encapsulate <algorithm> <public-key>    Encapsulate to create shared secret
+  kem decapsulate <algorithm> <ct> <sk>       Decapsulate to recover shared secret
+
+  sig keygen <algorithm>                      Generate signature keypair
+  sig sign <algorithm> <message> <sk>         Sign a message
+  sig verify <algorithm> <msg> <sig> <pk>     Verify a signature
+
+  list [--kem|--sig]                          List available algorithms
+  info <algorithm>                            Show algorithm information
+
+Options:
+  --format <hex|base64|raw>                   Output encoding (default: hex)
+  --input-format <hex|base64>                 Input encoding (default: auto)
+  --output <file>                             Write output to file
+  --output-dir <dir>                          Directory for keygen output
+  --help, -h                                  Show this help
+
+Input Methods:
+  - File path:          ./path/to/file
+  - Direct string:      "hello world"
+  - Hex/Base64:         hex:a1b2c3... or base64:SGVsbG8=
+  - Stdin:              - (dash for piped input)
+  - Env var:            LIBOQS_SECRET_KEY or $LIBOQS_SECRET_KEY
+
+Examples:
+  # Generate ML-KEM-768 keypair
+  liboqs kem keygen ml-kem-768 --output-dir ./keys
+
+  # Sign a message
+  liboqs sig sign ml-dsa-65 "Hello" ./secret.key --output sig.bin
+
+  # Verify with piped message
+  echo "Hello" | liboqs sig verify ml-dsa-65 - sig.bin ./public.key
+
+  # Use environment variables
+  export LIBOQS_SECRET_KEY="$(cat secret.key)"
+  liboqs sig sign ml-dsa-65 message.txt LIBOQS_SECRET_KEY
+
+For more information: https://open-quantum-safe.github.io/liboqs-js
+`);
+}

package/src/cli/io.js

@@ -0,0 +1,147 @@
+/**
+ * @fileoverview CLI input/output utilities
+ */
+
+import { existsSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import process from "node:process";
+import { Buffer } from "node:buffer";
+
+/**
+ * Read input from various sources
+ * @param {string} input - Input string (file path, hex:, base64:, -, or LIBOQS_* env var)
+ * @param {string} inputFormat - Format override (hex|base64|auto)
+ * @returns {Promise<Uint8Array>}
+ */
+export async function readInput(input, inputFormat = 'auto') {
+  // Check for stdin
+  if (input === '-') {
+    return await readStdin();
+  }
+
+  // Check for env var reference (LIBOQS_* or $LIBOQS_*)
+  const envVarName = input.startsWith('$') ? input.slice(1) : input;
+  if (envVarName.startsWith('LIBOQS_')) {
+    const envValue = process.env[envVarName];
+    if (!envValue) {
+      throw new Error(`Environment variable ${envVarName} is not set`);
+    }
+    input = envValue;
+  }
+
+  // Check for explicit encoding prefix
+  if (input.startsWith('hex:')) {
+    return hexToBytes(input.slice(4));
+  }
+  if (input.startsWith('base64:')) {
+    return base64ToBytes(input.slice(7));
+  }
+
+  // Try to read as file
+  if (existsSync(input)) {
+    const buffer = await readFile(input);
+    // Convert Buffer to Uint8Array for compatibility with algorithm validation
+    return new Uint8Array(buffer);
+  }
+
+  // Auto-detect format or treat as raw string
+  if (inputFormat === 'hex' || (inputFormat === 'auto' && /^[0-9a-fA-F]+$/.test(input))) {
+    return hexToBytes(input);
+  }
+  if (inputFormat === 'base64' || (inputFormat === 'auto' && /^[A-Za-z0-9+/=]+$/.test(input))) {
+    return base64ToBytes(input);
+  }
+
+  // Treat as raw string
+  return new TextEncoder().encode(input);
+}
+
+/**
+ * Read from stdin
+ * @returns {Promise<Uint8Array>}
+ */
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  const buffer = Buffer.concat(chunks);
+  // Convert Buffer to Uint8Array for compatibility with algorithm validation
+  return new Uint8Array(buffer);
+}
+
+/**
+ * Write output to file or stdout
+ * @param {Uint8Array} data - Data to write
+ * @param {string} format - Output format (hex|base64|raw)
+ * @param {string|null} outputPath - Output file path or null for stdout
+ */
+export async function writeOutput(data, format = 'hex', outputPath = null) {
+  let output;
+
+  switch (format) {
+    case 'hex':
+      output = bytesToHex(data);
+      break;
+    case 'base64':
+      output = bytesToBase64(data);
+      break;
+    case 'raw':
+      output = data;
+      break;
+    default:
+      throw new Error(`Unknown output format: ${format}`);
+  }
+
+  if (outputPath) {
+    if (typeof output === 'string') {
+      await writeFile(outputPath, output, 'utf8');
+    } else {
+      await writeFile(outputPath, output);
+    }
+  } else if (typeof output === 'string') {
+    console.log(output);
+  } else {
+    process.stdout.write(output);
+  }
+}
+
+/**
+ * Convert hex string to Uint8Array
+ */
+function hexToBytes(hex) {
+  const clean = hex.replaceAll(/\s/g, '');
+  if (clean.length % 2 !== 0) {
+    throw new Error('Invalid hex string length');
+  }
+  const bytes = new Uint8Array(clean.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = Number.parseInt(clean.substr(i * 2, 2), 16);
+  }
+  return bytes;
+}
+
+/**
+ * Convert base64 string to Uint8Array
+ */
+function base64ToBytes(base64) {
+  const buffer = Buffer.from(base64, 'base64');
+  // Convert Buffer to Uint8Array for compatibility with algorithm validation
+  return new Uint8Array(buffer);
+}
+
+/**
+ * Convert Uint8Array to hex string
+ */
+function bytesToHex(bytes) {
+  return Array.from(bytes)
+    .map(b => b.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+/**
+ * Convert Uint8Array to base64 string
+ */
+function bytesToBase64(bytes) {
+  return Buffer.from(bytes).toString('base64');
+}

package/src/cli/parser.js

@@ -0,0 +1,64 @@
+/**
+ * @fileoverview CLI argument parser
+ */
+
+export function parseArgs(argv) {
+  if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
+    return { command: 'help' };
+  }
+
+  const command = argv[0];
+
+  // Commands without subcommands: list, info
+  const noSubcommandCommands = ['list', 'info'];
+  const hasSubcommand = !noSubcommandCommands.includes(command) && argv[1] && !argv[1].startsWith('--');
+
+  const subcommand = hasSubcommand ? argv[1] : null;
+  const startIndex = hasSubcommand ? 2 : 1;
+
+  const args = [];
+  const options = {
+    format: 'hex',
+    inputFormat: 'auto',
+    output: null,
+    outputDir: null,
+    kem: false,
+    sig: false
+  };
+
+  // Parse arguments and flags
+  for (let i = startIndex; i < argv.length; i++) {
+    const arg = argv[i];
+
+    if (arg.startsWith('--')) {
+      const flag = arg.slice(2);
+
+      if (flag === 'format' || flag === 'input-format' || flag === 'output' || flag === 'output-dir') {
+        const value = argv[++i];
+        if (!value) {
+          throw new Error(`Missing value for --${flag}`);
+        }
+
+        if (flag === 'format') options.format = value;
+        else if (flag === 'input-format') options.inputFormat = value;
+        else if (flag === 'output') options.output = value;
+        else if (flag === 'output-dir') options.outputDir = value;
+      } else if (flag === 'kem') {
+        options.kem = true;
+      } else if (flag === 'sig') {
+        options.sig = true;
+      } else {
+        throw new Error(`Unknown option: --${flag}`);
+      }
+    } else {
+      args.push(arg);
+    }
+  }
+
+  return {
+    command,
+    subcommand,
+    args,
+    options
+  };
+}

package/src/core/errors.js

@@ -0,0 +1,75 @@
+/**
+ * @fileoverview Error classes for LibOQS operations
+ * @module @oqs/liboqs-js/errors
+ */
+
+/**
+ * Base error class for all LibOQS errors
+ * @extends Error
+ */
+export class LibOQSError extends Error {
+  /**
+   * @param {string} message - Error message
+   * @param {string} [algorithm] - Algorithm name
+   * @param {string} [operation] - Operation name
+   */
+  constructor(message, algorithm, operation) {
+    super(message);
+    this.name = 'LibOQSError';
+    this.algorithm = algorithm;
+    this.operation = operation;
+
+    // Maintains proper stack trace for where our error was thrown (only available on V8)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+}
+
+/**
+ * Error thrown during algorithm initialization
+ * @extends LibOQSError
+ */
+export class LibOQSInitError extends LibOQSError {
+  /**
+   * @param {string} algorithm - Algorithm name
+   * @param {string} [details] - Additional error details
+   */
+  constructor(algorithm, details) {
+    const message = `Failed to initialize ${algorithm}${details ? ': ' + details : ''}`;
+    super(message, algorithm, 'init');
+    this.name = 'LibOQSInitError';
+  }
+}
+
+/**
+ * Error thrown during cryptographic operations
+ * @extends LibOQSError
+ */
+export class LibOQSOperationError extends LibOQSError {
+  /**
+   * @param {string} operation - Operation name (e.g., 'keypair', 'encaps', 'sign')
+   * @param {string} algorithm - Algorithm name
+   * @param {string} [details] - Additional error details
+   */
+  constructor(operation, algorithm, details) {
+    const message = `${operation} failed for ${algorithm}${details ? ': ' + details : ''}`;
+    super(message, algorithm, operation);
+    this.name = 'LibOQSOperationError';
+  }
+}
+
+/**
+ * Error thrown for validation failures
+ * @extends LibOQSError
+ */
+export class LibOQSValidationError extends LibOQSError {
+  /**
+   * @param {string} message - Error message
+   * @param {string} [algorithm] - Algorithm name
+   */
+  constructor(message, algorithm) {
+    super(message, algorithm, 'validation');
+    this.name = 'LibOQSValidationError';
+  }
+}

package/src/core/validation.js

@@ -0,0 +1,28 @@
+/**
+ * @fileoverview Cross-realm validation utilities
+ * @module core/validation
+ * @description
+ * Provides validation functions that work across different JavaScript realms
+ * (e.g., different iframes, workers, WASM contexts, jsdom vs real browser).
+ *
+ * Uses duck-typing instead of instanceof to avoid cross-realm issues.
+ */
+
+/**
+ * Check if a value is a Uint8Array (cross-realm safe)
+ *
+ * @param {*} value - Value to check
+ * @returns {boolean} True if value is Uint8Array-like
+ *
+ * @example
+ * isUint8Array(new Uint8Array([1, 2, 3])); // true
+ * isUint8Array([1, 2, 3]); // false
+ * isUint8Array(null); // false
+ */
+export function isUint8Array(value) {
+  // Check if value is a typed array view and specifically Uint8Array
+  return value != null &&
+    typeof value === 'object' &&
+    ArrayBuffer.isView(value) &&
+    value.constructor.name === 'Uint8Array';
+}