types - xero/leviathan-crypto GitHub Wiki

interface Hash {
  hash(msg: Uint8Array): Uint8Array;
  dispose(): void;
}

interface KeyedHash {
  hash(key: Uint8Array, msg: Uint8Array): Uint8Array;
  dispose(): void;
}

interface Blockcipher {
  encrypt(block: Uint8Array): Uint8Array;
  decrypt(block: Uint8Array): Uint8Array;
  dispose(): void;
}

interface Streamcipher {
  encrypt(msg: Uint8Array): Uint8Array;
  decrypt(msg: Uint8Array): Uint8Array;
  dispose(): void;
}

interface AEAD {
  encrypt(msg: Uint8Array, aad?: Uint8Array): Uint8Array;
  decrypt(ciphertext: Uint8Array, aad?: Uint8Array): Uint8Array;
  dispose(): void;
}

import type { Hash } from 'leviathan-crypto'

function digestAndLog(hasher: Hash, data: Uint8Array): Uint8Array {
  const digest = hasher.hash(data)
  console.log('digest length:', digest.length)
  return digest
}

import type { AEAD } from 'leviathan-crypto'

function sealMessage(aead: AEAD, plaintext: Uint8Array, metadata: Uint8Array): Uint8Array {
  return aead.encrypt(plaintext, metadata)
}

function openMessage(aead: AEAD, ciphertext: Uint8Array, metadata: Uint8Array): Uint8Array {
  // decrypt() throws on auth failure, no null check needed
  return aead.decrypt(ciphertext, metadata)
}

import type { KeyedHash } from 'leviathan-crypto'

function authenticate(mac: KeyedHash, key: Uint8Array, ...parts: Uint8Array[]): Uint8Array {
  // Concatenate all message parts, then compute the tag
  const total = parts.reduce((sum, p) => sum + p.length, 0)
  const msg = new Uint8Array(total)
  let offset = 0
  for (const part of parts) {
    msg.set(part, offset)
    offset += part.length
  }
  return mac.hash(key, msg)
}

import type { Streamcipher, Blockcipher } from 'leviathan-crypto'

interface EncryptionContext {
  cipher: Streamcipher | Blockcipher
  mode: 'stream' | 'block'
}

function cleanup(ctx: EncryptionContext): void {
  ctx.cipher.dispose()
}

interface Generator {
  readonly keySize: number;       // bytes
  readonly blockSize: number;     // bytes per cipher block
  readonly counterSize: number;   // bytes
  readonly wasmModules: readonly string[];
  generate(key: Uint8Array, counter: Uint8Array, n: number): Uint8Array;
}

interface HashFn {
  readonly outputSize: number;    // bytes
  readonly wasmModules: readonly string[];
  digest(msg: Uint8Array): Uint8Array;
}

interface MlKemLike {
  readonly params: KyberParams
  keygen(): { encapsulationKey: Uint8Array; decapsulationKey: Uint8Array }
  encapsulate(ek: Uint8Array): { ciphertext: Uint8Array; sharedSecret: Uint8Array }
  decapsulate(dk: Uint8Array, ct: Uint8Array): Uint8Array
}

interface RatchetInitResult {
  readonly nextRootKey:  Uint8Array  // 32 bytes
  readonly sendChainKey: Uint8Array  // 32 bytes
  readonly recvChainKey: Uint8Array  // 32 bytes
}

interface KemEncapResult {
  readonly nextRootKey:  Uint8Array  // 32 bytes
  readonly sendChainKey: Uint8Array  // 32 bytes
  readonly recvChainKey: Uint8Array  // 32 bytes
  readonly kemCt:        Uint8Array  // ML-KEM ciphertext — transmit in-band
}

interface KemDecapResult {
  readonly nextRootKey:  Uint8Array  // 32 bytes
  readonly sendChainKey: Uint8Array  // 32 bytes
  readonly recvChainKey: Uint8Array  // 32 bytes
}

interface RatchetMessageHeader {
  readonly epoch:   number        // sender's epoch at seal time; starts 0, increments on ratchet step
  readonly counter: number        // KDFChain.n at seal time (post-step value, first message = 1)
  readonly pn?:     number        // previous chain length — present only on the first message of a new epoch
  readonly kemCt?:  Uint8Array    // ML-KEM ciphertext — present only on the first message of a new epoch (encap side)
}

interface ResolveHandle {
  readonly key: Uint8Array  // 32-byte message key — throws after settlement
  commit():   void          // wipe key and mark settled — call on successful decrypt
  rollback(): void          // return key to store and mark settled — call on auth failure
}