@omnituum/pqc-shared 0.2.6

package/dist/version-BygzPVGs.d.cts

@@ -0,0 +1,55 @@
+/**
+ * Omnituum PQC Shared - Version Constants & Guards
+ *
+ * FROZEN CONTRACTS: These version strings define the wire format.
+ * Breaking changes require a version bump.
+ *
+ * @see pqc-docs/specs/envelope.v1.md
+ * @see pqc-docs/specs/vault.v1.md
+ * @see pqc-docs/specs/identity.v1.md
+ */
+/** HybridEnvelope version - hybrid encryption format */
+declare const ENVELOPE_VERSION: "omnituum.hybrid.v1";
+/** OmnituumVault version - decrypted vault format */
+declare const VAULT_VERSION: "omnituum.vault.v1";
+/** EncryptedVaultFile version - encrypted vault format (PBKDF2) */
+declare const VAULT_ENCRYPTED_VERSION: "omnituum.vault.enc.v1";
+/** EncryptedVaultFile v2 - encrypted vault format (Argon2id) */
+declare const VAULT_ENCRYPTED_VERSION_V2: "omnituum.vault.enc.v2";
+/** Algorithm suite for hybrid encryption */
+declare const ENVELOPE_SUITE: "x25519+kyber768";
+/** AEAD algorithm for envelope content */
+declare const ENVELOPE_AEAD: "xsalsa20poly1305";
+/** KDF for vault encryption (v1) */
+declare const VAULT_KDF: "PBKDF2-SHA256";
+/** KDF for vault encryption (v2) */
+declare const VAULT_KDF_V2: "Argon2id";
+/** Encryption algorithm for vault */
+declare const VAULT_ALGORITHM: "AES-256-GCM";
+/**
+ * Validate envelope structure and version.
+ * Returns detailed validation result.
+ */
+declare function validateEnvelope(envelope: unknown): {
+    valid: boolean;
+    version?: string;
+    errors: string[];
+};
+/**
+ * Validate vault structure and version.
+ */
+declare function validateVault(vault: unknown): {
+    valid: boolean;
+    version?: string;
+    errors: string[];
+};
+/**
+ * Validate encrypted vault structure and version.
+ */
+declare function validateEncryptedVault(encVault: unknown): {
+    valid: boolean;
+    version?: string;
+    errors: string[];
+};
+
+export { ENVELOPE_VERSION as E, VAULT_VERSION as V, VAULT_ENCRYPTED_VERSION as a, VAULT_KDF as b, VAULT_ALGORITHM as c, VAULT_ENCRYPTED_VERSION_V2 as d, VAULT_KDF_V2 as e, ENVELOPE_SUITE as f, ENVELOPE_AEAD as g, validateEnvelope as h, validateEncryptedVault as i, validateVault as v };

package/dist/version-BygzPVGs.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Omnituum PQC Shared - Version Constants & Guards
+ *
+ * FROZEN CONTRACTS: These version strings define the wire format.
+ * Breaking changes require a version bump.
+ *
+ * @see pqc-docs/specs/envelope.v1.md
+ * @see pqc-docs/specs/vault.v1.md
+ * @see pqc-docs/specs/identity.v1.md
+ */
+/** HybridEnvelope version - hybrid encryption format */
+declare const ENVELOPE_VERSION: "omnituum.hybrid.v1";
+/** OmnituumVault version - decrypted vault format */
+declare const VAULT_VERSION: "omnituum.vault.v1";
+/** EncryptedVaultFile version - encrypted vault format (PBKDF2) */
+declare const VAULT_ENCRYPTED_VERSION: "omnituum.vault.enc.v1";
+/** EncryptedVaultFile v2 - encrypted vault format (Argon2id) */
+declare const VAULT_ENCRYPTED_VERSION_V2: "omnituum.vault.enc.v2";
+/** Algorithm suite for hybrid encryption */
+declare const ENVELOPE_SUITE: "x25519+kyber768";
+/** AEAD algorithm for envelope content */
+declare const ENVELOPE_AEAD: "xsalsa20poly1305";
+/** KDF for vault encryption (v1) */
+declare const VAULT_KDF: "PBKDF2-SHA256";
+/** KDF for vault encryption (v2) */
+declare const VAULT_KDF_V2: "Argon2id";
+/** Encryption algorithm for vault */
+declare const VAULT_ALGORITHM: "AES-256-GCM";
+/**
+ * Validate envelope structure and version.
+ * Returns detailed validation result.
+ */
+declare function validateEnvelope(envelope: unknown): {
+    valid: boolean;
+    version?: string;
+    errors: string[];
+};
+/**
+ * Validate vault structure and version.
+ */
+declare function validateVault(vault: unknown): {
+    valid: boolean;
+    version?: string;
+    errors: string[];
+};
+/**
+ * Validate encrypted vault structure and version.
+ */
+declare function validateEncryptedVault(encVault: unknown): {
+    valid: boolean;
+    version?: string;
+    errors: string[];
+};
+
+export { ENVELOPE_VERSION as E, VAULT_VERSION as V, VAULT_ENCRYPTED_VERSION as a, VAULT_KDF as b, VAULT_ALGORITHM as c, VAULT_ENCRYPTED_VERSION_V2 as d, VAULT_KDF_V2 as e, ENVELOPE_SUITE as f, ENVELOPE_AEAD as g, validateEnvelope as h, validateEncryptedVault as i, validateVault as v };

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@omnituum/pqc-shared",
+  "version": "0.2.6",
+  "description": "Omnituum PQC Shared Library - Crypto, Vault, File Encryption, and Utilities",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./crypto": {
+      "types": "./dist/crypto/index.d.ts",
+      "import": "./dist/crypto/index.js",
+      "require": "./dist/crypto/index.cjs"
+    },
+    "./vault": {
+      "types": "./dist/vault/index.d.ts",
+      "import": "./dist/vault/index.js",
+      "require": "./dist/vault/index.cjs"
+    },
+    "./utils": {
+      "types": "./dist/utils/index.d.ts",
+      "import": "./dist/utils/index.js",
+      "require": "./dist/utils/index.cjs"
+    },
+    "./fs": {
+      "types": "./dist/fs/index.d.ts",
+      "import": "./dist/fs/index.js",
+      "require": "./dist/fs/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@noble/ciphers": "^0.5.3",
+    "@noble/hashes": "^1.8.0",
+    "@noble/post-quantum": "^0.2.1",
+    "hash-wasm": "^4.11.0",
+    "kyber-crystals": "^1.0.7",
+    "tweetnacl": "^1.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.9",
+    "tsup": "^8.5.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.9.3"
+  },
+  "keywords": [
+    "pqc",
+    "post-quantum",
+    "cryptography",
+    "kyber",
+    "x25519",
+    "hybrid-encryption",
+    "vault",
+    "file-encryption",
+    "argon2",
+    "aes-gcm"
+  ],
+  "author": "Omnituum",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Omnituum/pqc-shared.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Omnituum/pqc-shared/issues"
+  },
+  "homepage": "https://github.com/Omnituum/pqc-shared#readme",
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "test:golden:generate": "pnpm -s build && tsx tests/golden/generate-vectors.ts",
+    "test:golden:verify": "pnpm -s build && tsx tests/golden/verify-vectors.ts",
+    "test:golden": "npm run test:golden:verify",
+    "pretest": "npm run build"
+  }
+}

package/src/crypto/dilithium.ts

@@ -0,0 +1,233 @@
+/**
+ * Omnituum PQC Shared - Dilithium ML-DSA-65 Signatures
+ *
+ * Post-quantum digital signatures using ML-DSA-65 (formerly CRYSTALS-Dilithium).
+ * NIST Level 3 security - quantum-resistant.
+ *
+ * Uses @noble/post-quantum for browser-compatible implementation.
+ */
+
+import { toB64, fromB64, sha256, randN } from './primitives';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// TYPES
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface DilithiumKeypair {
+  publicKey: Uint8Array;
+  secretKey: Uint8Array;
+}
+
+export interface DilithiumKeypairB64 {
+  publicB64: string;
+  secretB64: string;
+}
+
+export interface DilithiumSignature {
+  /** Signature (base64) */
+  signature: string;
+  /** Algorithm identifier */
+  algorithm: 'ML-DSA-65';
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// LIBRARY LOADING
+// ═══════════════════════════════════════════════════════════════════════════
+
+let dilithiumModule: any = null;
+
+async function loadDilithium(): Promise<any> {
+  if (dilithiumModule) return dilithiumModule;
+
+  try {
+    // @noble/post-quantum provides ml-dsa
+    const { ml_dsa65 } = await import('@noble/post-quantum/ml-dsa');
+    dilithiumModule = ml_dsa65;
+    return dilithiumModule;
+  } catch (e) {
+    console.warn('[Dilithium] Failed to load @noble/post-quantum:', e);
+    return null;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// AVAILABILITY CHECK
+// ═══════════════════════════════════════════════════════════════════════════
+
+export async function isDilithiumAvailable(): Promise<boolean> {
+  const mod = await loadDilithium();
+  return mod !== null;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// KEY GENERATION
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Generate a Dilithium ML-DSA-65 keypair.
+ *
+ * @returns Keypair with base64-encoded keys, or null if unavailable
+ */
+export async function generateDilithiumKeypair(): Promise<DilithiumKeypairB64 | null> {
+  try {
+    const mod = await loadDilithium();
+    if (!mod) return null;
+
+    // Generate random seed
+    const seed = randN(32);
+
+    // Generate keypair from seed for determinism
+    const kp = mod.keygen(seed);
+
+    return {
+      publicB64: toB64(kp.publicKey),
+      secretB64: toB64(kp.secretKey),
+    };
+  } catch (e) {
+    console.warn('[Dilithium] Key generation failed:', e);
+    return null;
+  }
+}
+
+/**
+ * Generate a deterministic Dilithium keypair from a seed.
+ *
+ * @param seed - 32-byte seed
+ * @returns Keypair
+ */
+export async function generateDilithiumKeypairFromSeed(
+  seed: Uint8Array
+): Promise<DilithiumKeypair> {
+  const mod = await loadDilithium();
+  if (!mod) {
+    throw new Error('Dilithium library not available');
+  }
+
+  if (seed.length !== 32) {
+    throw new Error('Dilithium seed must be 32 bytes');
+  }
+
+  // Hash seed for uniformity
+  const uniformSeed = sha256(seed);
+  const kp = mod.keygen(uniformSeed);
+
+  return {
+    publicKey: kp.publicKey,
+    secretKey: kp.secretKey,
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// SIGNING
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Sign a message using Dilithium ML-DSA-65.
+ *
+ * @param message - Message to sign (Uint8Array or string)
+ * @param secretKeyB64 - Secret key (base64)
+ * @returns Signature object
+ */
+export async function dilithiumSign(
+  message: Uint8Array | string,
+  secretKeyB64: string
+): Promise<DilithiumSignature> {
+  const mod = await loadDilithium();
+  if (!mod) {
+    throw new Error('Dilithium library not available');
+  }
+
+  const sk = fromB64(secretKeyB64);
+  const msg = typeof message === 'string' ? new TextEncoder().encode(message) : message;
+
+  const signature = mod.sign(sk, msg);
+
+  return {
+    signature: toB64(signature),
+    algorithm: 'ML-DSA-65',
+  };
+}
+
+/**
+ * Sign raw bytes (returns raw signature).
+ */
+export async function dilithiumSignRaw(
+  message: Uint8Array,
+  secretKey: Uint8Array
+): Promise<Uint8Array> {
+  const mod = await loadDilithium();
+  if (!mod) {
+    throw new Error('Dilithium library not available');
+  }
+
+  return mod.sign(secretKey, message);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// VERIFICATION
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Verify a Dilithium signature.
+ *
+ * @param message - Original message
+ * @param signatureB64 - Signature (base64)
+ * @param publicKeyB64 - Public key (base64)
+ * @returns true if signature is valid
+ */
+export async function dilithiumVerify(
+  message: Uint8Array | string,
+  signatureB64: string,
+  publicKeyB64: string
+): Promise<boolean> {
+  const mod = await loadDilithium();
+  if (!mod) {
+    throw new Error('Dilithium library not available');
+  }
+
+  const pk = fromB64(publicKeyB64);
+  const sig = fromB64(signatureB64);
+  const msg = typeof message === 'string' ? new TextEncoder().encode(message) : message;
+
+  try {
+    return mod.verify(pk, msg, sig);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Verify raw signature bytes.
+ */
+export async function dilithiumVerifyRaw(
+  message: Uint8Array,
+  signature: Uint8Array,
+  publicKey: Uint8Array
+): Promise<boolean> {
+  const mod = await loadDilithium();
+  if (!mod) {
+    throw new Error('Dilithium library not available');
+  }
+
+  try {
+    return mod.verify(publicKey, message, signature);
+  } catch {
+    return false;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// CONSTANTS
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** ML-DSA-65 public key size */
+export const DILITHIUM_PUBLIC_KEY_SIZE = 1952;
+
+/** ML-DSA-65 secret key size */
+export const DILITHIUM_SECRET_KEY_SIZE = 4032;
+
+/** ML-DSA-65 signature size */
+export const DILITHIUM_SIGNATURE_SIZE = 3309;
+
+/** Algorithm identifier */
+export const DILITHIUM_ALGORITHM = 'ML-DSA-65';