@omnituum/pqc-shared 0.3.1 → 0.4.1

package/src/crypto/safe/manifests.ts

@@ -0,0 +1,192 @@
+/**
+ * Primitive identity manifests.
+ *
+ * Each manifest declares the expected algorithm name and byte sizes.
+ * Used by assertPrimitiveIdentity() to verify that the underlying library
+ * is the exact primitive we intended to wrap — not a swapped, compromised,
+ * or silently upgraded implementation.
+ *
+ * This catches:
+ * - wrong algorithm resolved behind the same import
+ * - changed encoding or key format after a dependency update
+ * - supply-chain substitution of a different primitive
+ * - silent API drift in key/signature sizes
+ */
+
+export interface SignatureManifest {
+  readonly algorithm: string
+  readonly publicKeyBytes: number
+  readonly secretKeyBytes: number
+  readonly signatureBytes: number
+}
+
+export interface KemManifest {
+  readonly algorithm: string
+  readonly encapsulationKeyBytes: number
+  readonly decapsulationKeyBytes: number
+  readonly ciphertextBytes: number
+  readonly sharedSecretBytes: number
+}
+
+export interface DhManifest {
+  readonly algorithm: string
+  readonly publicKeyBytes: number
+  readonly secretKeyBytes: number
+  readonly sharedSecretBytes: number
+}
+
+export interface SecretboxManifest {
+  readonly algorithm: string
+  readonly keyBytes: number
+  readonly nonceBytes: number
+  readonly tagBytes: number
+}
+
+// ---- Concrete manifests for Omnituum's primitives ----
+
+export const ML_DSA_65: SignatureManifest = {
+  algorithm: 'ML-DSA-65',
+  publicKeyBytes: 1952,
+  secretKeyBytes: 4032,
+  signatureBytes: 3309,
+} as const
+
+export const ML_KEM_768: KemManifest = {
+  algorithm: 'ML-KEM-768',
+  encapsulationKeyBytes: 1184,
+  decapsulationKeyBytes: 2400,
+  ciphertextBytes: 1088,
+  sharedSecretBytes: 32,
+} as const
+
+export const X25519: DhManifest = {
+  algorithm: 'X25519',
+  publicKeyBytes: 32,
+  secretKeyBytes: 32,
+  sharedSecretBytes: 32,
+} as const
+
+export const XSALSA20_POLY1305: SecretboxManifest = {
+  algorithm: 'XSalsa20-Poly1305',
+  keyBytes: 32,
+  nonceBytes: 24,
+  tagBytes: 16,
+} as const
+
+// ---- Assertion helpers ----
+
+export function assertSignaturePrimitive(
+  noble: {
+    keygen(seed?: Uint8Array): { publicKey: Uint8Array; secretKey: Uint8Array }
+    sign(message: Uint8Array, secretKey: Uint8Array): Uint8Array
+    verify(signature: Uint8Array, message: Uint8Array, publicKey: Uint8Array): boolean
+  },
+  manifest: SignatureManifest,
+): void {
+  const msg = new Uint8Array([0xde, 0xad, 0xbe, 0xef])
+  const { publicKey, secretKey } = noble.keygen()
+  const sig = noble.sign(msg, secretKey)
+
+  if (publicKey.length !== manifest.publicKeyBytes) {
+    throw new Error(
+      `${manifest.algorithm}: publicKey ${publicKey.length} bytes, expected ${manifest.publicKeyBytes}`,
+    )
+  }
+  if (secretKey.length !== manifest.secretKeyBytes) {
+    throw new Error(
+      `${manifest.algorithm}: secretKey ${secretKey.length} bytes, expected ${manifest.secretKeyBytes}`,
+    )
+  }
+  if (sig.length !== manifest.signatureBytes) {
+    throw new Error(
+      `${manifest.algorithm}: signature ${sig.length} bytes, expected ${manifest.signatureBytes}`,
+    )
+  }
+  if (!noble.verify(sig, msg, publicKey)) {
+    throw new Error(`${manifest.algorithm}: sign/verify roundtrip failed`)
+  }
+}
+
+export function assertKemPrimitive(
+  noble: {
+    keygen(): { publicKey: Uint8Array; secretKey: Uint8Array }
+    encapsulate(publicKey: Uint8Array): { ciphertext: Uint8Array; sharedSecret: Uint8Array }
+    decapsulate(ciphertext: Uint8Array, secretKey: Uint8Array): Uint8Array
+  },
+  manifest: KemManifest,
+): void {
+  const { publicKey, secretKey } = noble.keygen()
+  const { ciphertext, sharedSecret: ss1 } = noble.encapsulate(publicKey)
+  const ss2 = noble.decapsulate(ciphertext, secretKey)
+
+  if (publicKey.length !== manifest.encapsulationKeyBytes) {
+    throw new Error(
+      `${manifest.algorithm}: encapsulationKey ${publicKey.length} bytes, expected ${manifest.encapsulationKeyBytes}`,
+    )
+  }
+  if (secretKey.length !== manifest.decapsulationKeyBytes) {
+    throw new Error(
+      `${manifest.algorithm}: decapsulationKey ${secretKey.length} bytes, expected ${manifest.decapsulationKeyBytes}`,
+    )
+  }
+  if (ciphertext.length !== manifest.ciphertextBytes) {
+    throw new Error(
+      `${manifest.algorithm}: ciphertext ${ciphertext.length} bytes, expected ${manifest.ciphertextBytes}`,
+    )
+  }
+  if (ss1.length !== manifest.sharedSecretBytes) {
+    throw new Error(
+      `${manifest.algorithm}: sharedSecret ${ss1.length} bytes, expected ${manifest.sharedSecretBytes}`,
+    )
+  }
+  if (ss2.length !== manifest.sharedSecretBytes) {
+    throw new Error(
+      `${manifest.algorithm}: decapsulated sharedSecret ${ss2.length} bytes, expected ${manifest.sharedSecretBytes}`,
+    )
+  }
+  for (let i = 0; i < ss1.length; i++) {
+    if (ss1[i] !== ss2[i]) {
+      throw new Error(`${manifest.algorithm}: encap/decap shared secrets differ at byte ${i}`)
+    }
+  }
+}
+
+export function assertDhPrimitive(
+  noble: {
+    getPublicKey(secretKey: Uint8Array): Uint8Array
+    getSharedSecret(secretKey: Uint8Array, publicKey: Uint8Array): Uint8Array
+    utils: { randomPrivateKey(): Uint8Array }
+  },
+  manifest: DhManifest,
+): void {
+  const sk = noble.utils.randomPrivateKey()
+  const pk = noble.getPublicKey(sk)
+
+  if (pk.length !== manifest.publicKeyBytes) {
+    throw new Error(
+      `${manifest.algorithm}: publicKey ${pk.length} bytes, expected ${manifest.publicKeyBytes}`,
+    )
+  }
+  if (sk.length !== manifest.secretKeyBytes) {
+    throw new Error(
+      `${manifest.algorithm}: secretKey ${sk.length} bytes, expected ${manifest.secretKeyBytes}`,
+    )
+  }
+
+  // Generate second keypair, compute shared secret both ways
+  const sk2 = noble.utils.randomPrivateKey()
+  const pk2 = noble.getPublicKey(sk2)
+  const ss1 = noble.getSharedSecret(sk, pk2)
+  const ss2 = noble.getSharedSecret(sk2, pk)
+
+  if (ss1.length !== manifest.sharedSecretBytes) {
+    throw new Error(
+      `${manifest.algorithm}: sharedSecret ${ss1.length} bytes, expected ${manifest.sharedSecretBytes}`,
+    )
+  }
+  for (let i = 0; i < ss1.length; i++) {
+    if (ss1[i] !== ss2[i]) {
+      throw new Error(`${manifest.algorithm}: DH commutativity check failed at byte ${i}`)
+    }
+  }
+}

package/src/crypto/safe/secretbox.ts

@@ -0,0 +1,24 @@
+/**
+ * Safe secretbox (xsalsa20-poly1305) adapter.
+ *
+ * Object parameters + branded types.
+ */
+
+import { secretboxRaw, secretboxOpenRaw } from '../nacl'
+import type { SymmetricKey, Nonce } from './types'
+
+export function seal(params: {
+  key: SymmetricKey
+  plaintext: Uint8Array
+  nonce: Nonce
+}): Uint8Array {
+  return secretboxRaw(params.key, params.plaintext, params.nonce)
+}
+
+export function open(params: {
+  key: SymmetricKey
+  ciphertext: Uint8Array
+  nonce: Nonce
+}): Uint8Array | null {
+  return secretboxOpenRaw(params.key, params.ciphertext, params.nonce)
+}

package/src/crypto/safe/types.ts

@@ -0,0 +1,88 @@
+/**
+ * Branded cryptographic types.
+ *
+ * Raw Uint8Array must never cross module boundaries without type branding.
+ * These types make argument inversion a compile-time error.
+ */
+
+// ---- Dilithium ML-DSA-65 ----
+
+export type DilithiumSecretKey = Uint8Array & { readonly __brand: 'DilithiumSecretKey' }
+export type DilithiumPublicKey = Uint8Array & { readonly __brand: 'DilithiumPublicKey' }
+export type DilithiumSignature = Uint8Array & { readonly __brand: 'DilithiumSignature' }
+
+export interface DilithiumKeyPair {
+  publicKey: DilithiumPublicKey
+  secretKey: DilithiumSecretKey
+}
+
+// ---- Kyber ML-KEM-768 ----
+
+export type KyberEncapsulationKey = Uint8Array & { readonly __brand: 'KyberEncapsulationKey' }
+export type KyberDecapsulationKey = Uint8Array & { readonly __brand: 'KyberDecapsulationKey' }
+export type KyberCiphertext = Uint8Array & { readonly __brand: 'KyberCiphertext' }
+export type SharedSecret = Uint8Array & { readonly __brand: 'SharedSecret' }
+
+export interface KyberKeyPair {
+  encapsulationKey: KyberEncapsulationKey
+  decapsulationKey: KyberDecapsulationKey
+}
+
+export interface KyberEncapsulation {
+  ciphertext: KyberCiphertext
+  sharedSecret: SharedSecret
+}
+
+// ---- X25519 ----
+
+export type X25519PublicKey = Uint8Array & { readonly __brand: 'X25519PublicKey' }
+export type X25519SecretKey = Uint8Array & { readonly __brand: 'X25519SecretKey' }
+
+export interface X25519KeyPair {
+  publicKey: X25519PublicKey
+  secretKey: X25519SecretKey
+}
+
+// ---- Symmetric ----
+
+export type SymmetricKey = Uint8Array & { readonly __brand: 'SymmetricKey' }
+export type Nonce = Uint8Array & { readonly __brand: 'Nonce' }
+export type Message = Uint8Array & { readonly __brand: 'Message' }
+
+// ---- Branding helpers ----
+
+export function asMessage(data: Uint8Array): Message {
+  return data as Message
+}
+
+export function asDilithiumSecretKey(data: Uint8Array): DilithiumSecretKey {
+  return data as DilithiumSecretKey
+}
+
+export function asDilithiumPublicKey(data: Uint8Array): DilithiumPublicKey {
+  return data as DilithiumPublicKey
+}
+
+export function asKyberEncapsulationKey(data: Uint8Array): KyberEncapsulationKey {
+  return data as KyberEncapsulationKey
+}
+
+export function asKyberDecapsulationKey(data: Uint8Array): KyberDecapsulationKey {
+  return data as KyberDecapsulationKey
+}
+
+export function asX25519PublicKey(data: Uint8Array): X25519PublicKey {
+  return data as X25519PublicKey
+}
+
+export function asX25519SecretKey(data: Uint8Array): X25519SecretKey {
+  return data as X25519SecretKey
+}
+
+export function asSymmetricKey(data: Uint8Array): SymmetricKey {
+  return data as SymmetricKey
+}
+
+export function asNonce(data: Uint8Array): Nonce {
+  return data as Nonce
+}

package/src/crypto/safe/x25519.ts

@@ -0,0 +1,31 @@
+/**
+ * Safe X25519 adapter.
+ *
+ * Object parameters + branded types.
+ */
+
+import {
+  generateX25519Keypair as rawKeygen,
+  x25519SharedSecret as rawEcdh,
+} from '../x25519'
+import type {
+  X25519KeyPair,
+  X25519PublicKey,
+  X25519SecretKey,
+  SharedSecret,
+} from './types'
+
+export function keygen(): X25519KeyPair {
+  const kp = rawKeygen()
+  return {
+    publicKey: kp.publicBytes as X25519PublicKey,
+    secretKey: kp.secretBytes as X25519SecretKey,
+  }
+}
+
+export function sharedSecret(params: {
+  ourSecretKey: X25519SecretKey
+  theirPublicKey: X25519PublicKey
+}): SharedSecret {
+  return rawEcdh(params.ourSecretKey, params.theirPublicKey) as SharedSecret
+}

package/src/index.ts

@@ -5,7 +5,7 @@ import './runtime/crypto';
  * Omnituum PQC Shared
  *
  * Unified cryptographic and vault utilities for PQC applications.
- * Combines X25519 (classical) + Kyber ML-KEM-768 (post-quantum) encryption.
+ * Combines X25519 (classical) + Kyber ML-KEM-1024 (FIPS 203, post-quantum) encryption.
  *
  * FROZEN CONTRACTS - see pqc-docs/specs/ for format specifications.
  *
@@ -34,7 +34,7 @@ import './runtime/crypto';
 // ═══════════════════════════════════════════════════════════════════════════
 
 /**
- * @stable Hybrid X25519 + Kyber-768 encryption primitives.
+ * @stable Hybrid X25519 + Kyber ML-KEM-1024 (FIPS 203) encryption primitives.
  * The core post-quantum encryption interface.
  */
 export {
@@ -54,25 +54,33 @@ export type {
 } from './crypto/hybrid';
 
 // ═══════════════════════════════════════════════════════════════════════════
-// KYBER (ML-KEM-768) (@stable)
+// KYBER (ML-KEM-1024, FIPS 203) (@stable)
 // ═══════════════════════════════════════════════════════════════════════════
 
 /**
- * @stable Kyber ML-KEM-768 post-quantum KEM primitives.
+ * @stable Kyber ML-KEM-1024 (FIPS 203) post-quantum KEM primitives.
  */
 export {
   isKyberAvailable,
   generateKyberKeypair,
+  generateKyberKeypairFromSeed,
   kyberEncapsulate,
   kyberDecapsulate,
   kyberWrapKey,
   kyberUnwrapKey,
+  KYBER_SUITE,
+  KYBER_PUBLIC_KEY_SIZE,
+  KYBER_SECRET_KEY_SIZE,
+  KYBER_CIPHERTEXT_SIZE,
+  KYBER_SHARED_SECRET_SIZE,
+  KYBER_SEED_SIZE,
 } from './crypto/kyber';
 
 export type {
   KyberKeypair,
   KyberKeypairB64,
   KyberEncapsulation,
+  KyberSuite,
 } from './crypto/kyber';
 
 // ═══════════════════════════════════════════════════════════════════════════

package/src/version.ts

@@ -9,15 +9,20 @@
  * @see pqc-docs/specs/identity.v1.md
  */
 
+import {
+  OMNI_VERSIONS,
+  DEPRECATED_VERSIONS,
+} from '@omnituum/envelope-registry';
+
 // ═══════════════════════════════════════════════════════════════════════════
 // VERSION CONSTANTS (FROZEN)
 // ═══════════════════════════════════════════════════════════════════════════
 
-/** HybridEnvelope version - hybrid encryption format */
-export const ENVELOPE_VERSION = 'omnituum.hybrid.v1' as const;
+/** HybridEnvelope version - hybrid encryption format (from registry) */
+export const ENVELOPE_VERSION = OMNI_VERSIONS.HYBRID_V1;
 
-/** Legacy envelope version for backwards compatibility */
-export const ENVELOPE_VERSION_LEGACY = 'pqc-demo.hybrid.v1' as const;
+/** Legacy envelope version for backwards compatibility (from registry) */
+export const ENVELOPE_VERSION_LEGACY = DEPRECATED_VERSIONS.PQC_DEMO_HYBRID_V1;
 
 /** OmnituumVault version - decrypted vault format */
 export const VAULT_VERSION = 'omnituum.vault.v1' as const;

package/dist/version-BygzPVGs.d.cts

@@ -1,55 +0,0 @@
-/**
- * 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

@@ -1,55 +0,0 @@
-/**
- * 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 };