@ajna-inc/vaults 0.1.0

package/wasm/vault_crypto.d.ts

@@ -0,0 +1,526 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * Encrypt using AES-256-GCM (§4.1 P1 suite)
+ *
+ * # Arguments
+ * * `key` - 32-byte encryption key
+ * * `nonce` - 12-byte nonce (must be unique per key)
+ * * `plaintext` - Data to encrypt
+ * * `aad` - Associated data (authenticated but not encrypted)
+ *
+ * # Returns
+ * Ciphertext with authentication tag appended (plaintext.len() + 16 bytes)
+ */
+export function aesGcmEncrypt(key: Uint8Array, nonce: Uint8Array, plaintext: Uint8Array, aad: Uint8Array): AeadResult;
+/**
+ * Decrypt using AES-256-GCM (§4.1 P1 suite)
+ *
+ * # Arguments
+ * * `key` - 32-byte encryption key
+ * * `nonce` - 12-byte nonce (same as encryption)
+ * * `ciphertext` - Encrypted data with tag
+ * * `aad` - Associated data (must match encryption)
+ *
+ * # Returns
+ * Plaintext (ciphertext.len() - 16 bytes)
+ */
+export function aesGcmDecrypt(key: Uint8Array, nonce: Uint8Array, ciphertext: Uint8Array, aad: Uint8Array): Uint8Array;
+/**
+ * Encrypt using XChaCha20-Poly1305 (§4.1 H1 suite)
+ *
+ * # Arguments
+ * * `key` - 32-byte encryption key
+ * * `nonce` - 24-byte nonce (extended nonce for XChaCha)
+ * * `plaintext` - Data to encrypt
+ * * `aad` - Associated data (authenticated but not encrypted)
+ *
+ * # Returns
+ * Ciphertext with authentication tag appended
+ */
+export function xchachaEncrypt(key: Uint8Array, nonce: Uint8Array, plaintext: Uint8Array, aad: Uint8Array): AeadResult;
+/**
+ * Decrypt using XChaCha20-Poly1305 (§4.1 H1 suite)
+ *
+ * # Arguments
+ * * `key` - 32-byte encryption key
+ * * `nonce` - 24-byte nonce (same as encryption)
+ * * `ciphertext` - Encrypted data with tag
+ * * `aad` - Associated data (must match encryption)
+ *
+ * # Returns
+ * Plaintext
+ */
+export function xchachaDecrypt(key: Uint8Array, nonce: Uint8Array, ciphertext: Uint8Array, aad: Uint8Array): Uint8Array;
+/**
+ * Generate ML-KEM-768 keypair (§4.1 P1 suite)
+ *
+ * # Returns
+ * Keypair with:
+ * - Public key: 1184 bytes
+ * - Secret key: 2400 bytes
+ */
+export function kemGenerateKeypair(): KemKeypair;
+/**
+ * Encapsulate a shared secret to a recipient's public key (§6.1)
+ *
+ * # Arguments
+ * * `recipient_public_key` - Recipient's ML-KEM-768 public key (1184 bytes)
+ *
+ * # Returns
+ * - `sharedSecret`: 32-byte shared secret (use as KEK to wrap CEK)
+ * - `ciphertext`: KEM ciphertext to send to recipient
+ */
+export function kemEncapsulate(recipient_public_key: Uint8Array): KemEncapResult;
+/**
+ * Decapsulate to recover shared secret from ciphertext (§6.1)
+ *
+ * # Arguments
+ * * `ciphertext` - KEM ciphertext from encapsulation
+ * * `secret_key` - Recipient's ML-KEM-768 secret key (2400 bytes)
+ *
+ * # Returns
+ * 32-byte shared secret (same as encapsulation)
+ */
+export function kemDecapsulate(ciphertext: Uint8Array, secret_key: Uint8Array): Uint8Array;
+/**
+ * Wrap a CEK using KEM + AES-KW pattern
+ *
+ * This is a convenience function that:
+ * 1. Encapsulates to get a KEK (Key Encryption Key)
+ * 2. Uses KEK with AES-GCM to wrap the CEK
+ *
+ * # Arguments
+ * * `cek` - Content Encryption Key to wrap (typically 32 bytes)
+ * * `recipient_public_key` - Recipient's ML-KEM-768 public key
+ *
+ * # Returns
+ * Wrapped CEK ciphertext (includes both KEM ciphertext and AES-GCM encrypted CEK)
+ */
+export function kemWrapCek(cek: Uint8Array, recipient_public_key: Uint8Array): Uint8Array;
+/**
+ * Unwrap a CEK using KEM + AES-KW pattern
+ *
+ * Inverse of `kemWrapCek`.
+ *
+ * # Arguments
+ * * `wrapped_cek` - Combined KEM ciphertext + AES-GCM encrypted CEK
+ * * `secret_key` - Recipient's ML-KEM-768 secret key
+ *
+ * # Returns
+ * Unwrapped CEK
+ */
+export function kemUnwrapCek(wrapped_cek: Uint8Array, secret_key: Uint8Array): Uint8Array;
+/**
+ * Derive key using HKDF-SHA256 (§10.3)
+ *
+ * # Arguments
+ * * `ikm` - Input Key Material
+ * * `salt` - Optional salt (use empty array for none)
+ * * `info` - Context/domain string
+ * * `length` - Output key length in bytes
+ *
+ * # Returns
+ * Derived key of requested length
+ */
+export function hkdfExpand(ikm: Uint8Array, salt: Uint8Array, info: string, length: number): Uint8Array;
+/**
+ * HKDF-join: Order-independent key folding for all-of policy (§6.2)
+ *
+ * Combines multiple keys into a single wrap key deterministically.
+ * Order-independent by sorting KIDs before folding.
+ *
+ * # Arguments
+ * * `keys` - Array of key materials (each with KID and key bytes)
+ * * `context` - Context string (e.g., "doc:uuid:epoch:3")
+ *
+ * # Returns
+ * 32-byte joint wrap key
+ *
+ * # Example
+ * ```javascript
+ * const keys = [
+ *   { kid: "alice", key: aliceKeyBytes },
+ *   { kid: "bob", key: bobKeyBytes },
+ * ];
+ * const wrapKey = hkdfJoin(keys, "doc:abc:epoch:0");
+ * ```
+ */
+export function hkdfJoin(keys: any, context: string): Uint8Array;
+/**
+ * Simple HKDF for CEK derivation from seed
+ *
+ * # Arguments
+ * * `seed` - Random seed material
+ * * `context` - Context string
+ *
+ * # Returns
+ * 32-byte CEK
+ */
+export function deriveCek(seed: Uint8Array, context: string): Uint8Array;
+/**
+ * Derive key identifier (KID) from public key (§10.1)
+ *
+ * KID = base64url(SHA256(publicKey))
+ *
+ * # Arguments
+ * * `public_key` - Public key bytes
+ *
+ * # Returns
+ * Base64url-encoded KID
+ */
+export function deriveKid(public_key: Uint8Array): string;
+/**
+ * Derive key identifier from symmetric key (§10.1)
+ *
+ * For symmetric keys, use HKDF to avoid reversibility:
+ * KID = base64url(HKDF-Expand(key, "kid:v1", 16))
+ *
+ * # Arguments
+ * * `key` - Symmetric key bytes
+ *
+ * # Returns
+ * Base64url-encoded KID (truncated to 16 bytes for compactness)
+ */
+export function deriveSymmetricKid(key: Uint8Array): string;
+/**
+ * Split secret into Shamir shares (t-of-n threshold)
+ *
+ * # Arguments
+ * * `secret` - Secret to split (typically a CEK, 32 bytes)
+ * * `threshold` - Minimum shares needed to reconstruct (t)
+ * * `total_shares` - Total number of shares to create (n)
+ *
+ * # Returns
+ * Array of n shares, any t of which can reconstruct the secret
+ *
+ * # Example
+ * ```javascript
+ * const cek = new Uint8Array(32); // 32-byte CEK
+ * crypto.getRandomValues(cek);
+ *
+ * // Create 5 shares, need any 3 to reconstruct
+ * const shares = shamirSplit(cek, 3, 5);
+ * ```
+ */
+export function shamirSplit(secret: Uint8Array, threshold: number, total_shares: number): any;
+/**
+ * Reconstruct secret from Shamir shares
+ *
+ * # Arguments
+ * * `shares` - Array of shares (must have at least threshold shares)
+ *
+ * # Returns
+ * Reconstructed secret
+ *
+ * # Example
+ * ```javascript
+ * // Use any 3 of the 5 shares
+ * const selectedShares = [shares[0], shares[2], shares[4]];
+ * const reconstructed = shamirReconstruct(selectedShares);
+ * ```
+ */
+export function shamirReconstruct(shares: any): Uint8Array;
+/**
+ * Helper: Split and KEM-wrap shares for threshold policy (§6.3)
+ *
+ * Combines Shamir splitting with KEM encapsulation.
+ * Each share is encrypted to a participant's public key.
+ *
+ * # Arguments
+ * * `secret` - CEK to split and wrap
+ * * `threshold` - Minimum shares needed
+ * * `recipient_public_keys` - Array of ML-KEM-768 public keys (1184 bytes each)
+ *
+ * # Returns
+ * Array of wrapped shares (each contains KEM ciphertext + encrypted share)
+ */
+export function shamirSplitAndWrap(secret: Uint8Array, threshold: number, recipient_public_keys: any): any;
+/**
+ * Helper: Unwrap and reconstruct from KEM-wrapped shares
+ *
+ * # Arguments
+ * * `wrapped_shares` - Array of wrapped shares
+ * * `secret_keys` - Array of ML-KEM-768 secret keys (2400 bytes each)
+ *
+ * # Returns
+ * Reconstructed secret (if threshold met)
+ */
+export function shamirUnwrapAndReconstruct(wrapped_shares: any, secret_keys: any): Uint8Array;
+/**
+ * Generate random bytes using cryptographically secure RNG
+ *
+ * # Arguments
+ * * `length` - Number of random bytes to generate
+ *
+ * # Returns
+ * Cryptographically random bytes
+ */
+export function randomBytes(length: number): Uint8Array;
+/**
+ * Generate a random 32-byte CEK (Content Encryption Key)
+ *
+ * # Returns
+ * 32-byte random CEK
+ */
+export function generateCek(): Uint8Array;
+/**
+ * Generate random nonce for AES-GCM (12 bytes)
+ *
+ * # Returns
+ * 12-byte random nonce
+ */
+export function generateNonceAesGcm(): Uint8Array;
+/**
+ * Generate random nonce for XChaCha20-Poly1305 (24 bytes)
+ *
+ * # Returns
+ * 24-byte random nonce
+ */
+export function generateNonceXchacha(): Uint8Array;
+/**
+ * Compute key commitment: HMAC-SHA256(CEK, "kcmp:v1") (§5.1)
+ *
+ * Key commitment ensures the CEK is bound to the ciphertext and prevents
+ * key substitution attacks.
+ *
+ * # Arguments
+ * * `cek` - Content Encryption Key
+ *
+ * # Returns
+ * 32-byte key commitment value
+ */
+export function keyCommitment(cek: Uint8Array): Uint8Array;
+/**
+ * Verify key commitment
+ *
+ * # Arguments
+ * * `cek` - Content Encryption Key
+ * * `expected_kcmp` - Expected commitment value
+ *
+ * # Returns
+ * true if commitment matches
+ */
+export function verifyKeyCommitment(cek: Uint8Array, expected_kcmp: Uint8Array): boolean;
+/**
+ * Compute SHA-256 hash
+ *
+ * # Arguments
+ * * `data` - Data to hash
+ *
+ * # Returns
+ * 32-byte SHA-256 digest
+ */
+export function sha256(data: Uint8Array): Uint8Array;
+/**
+ * Compute BLAKE2s-256 hash
+ *
+ * # Arguments
+ * * `data` - Data to hash
+ *
+ * # Returns
+ * 32-byte BLAKE2s-256 digest
+ */
+export function blake2s256(data: Uint8Array): Uint8Array;
+/**
+ * Compute summary hash for WYSIWYS (What You See Is What You Sign)
+ *
+ * Summary = BLAKE2s-256(digest)[..16]
+ *
+ * # Arguments
+ * * `digest` - Transaction or document digest
+ *
+ * # Returns
+ * 16-byte summary hash (fingerprint)
+ */
+export function computeSummary(digest: Uint8Array): Uint8Array;
+/**
+ * Constant-time equality comparison
+ *
+ * # Arguments
+ * * `a` - First byte array
+ * * `b` - Second byte array
+ *
+ * # Returns
+ * true if arrays are equal (constant-time)
+ */
+export function constantTimeEq(a: Uint8Array, b: Uint8Array): boolean;
+/**
+ * Encode bytes to base64url (no padding)
+ *
+ * # Arguments
+ * * `data` - Bytes to encode
+ *
+ * # Returns
+ * Base64url-encoded string
+ */
+export function toBase64Url(data: Uint8Array): string;
+/**
+ * Decode bytes from base64url
+ *
+ * # Arguments
+ * * `encoded` - Base64url-encoded string
+ *
+ * # Returns
+ * Decoded bytes
+ */
+export function fromBase64Url(encoded: string): Uint8Array;
+/**
+ * Encode bytes to hex string
+ *
+ * # Arguments
+ * * `data` - Bytes to encode
+ *
+ * # Returns
+ * Hex-encoded string
+ */
+export function toHex(data: Uint8Array): string;
+/**
+ * Decode bytes from hex string
+ *
+ * # Arguments
+ * * `encoded` - Hex-encoded string
+ *
+ * # Returns
+ * Decoded bytes
+ */
+export function fromHex(encoded: string): Uint8Array;
+/**
+ * Generate UUID v4
+ *
+ * # Returns
+ * UUID v4 string
+ */
+export function generateUuid(): string;
+/**
+ * Zeroize (securely erase) a byte array
+ *
+ * # Arguments
+ * * `data` - Mutable byte array to zeroize
+ */
+export function zeroize(data: Uint8Array): void;
+/**
+ * Create canonical AAD (Associated Authenticated Data) for envelope encryption (§5.3)
+ *
+ * AAD includes: {v, suite, aead, docId, vaultId?, epoch, policy.mode}
+ *
+ * # Arguments
+ * * `header_fields` - JSON object with header fields
+ *
+ * # Returns
+ * Canonical JSON bytes for AAD
+ */
+export function canonicalAad(header_fields: any): Uint8Array;
+/**
+ * Build context string for key derivation (§10.2)
+ *
+ * Format: "doc:{docId}:epoch:{epoch}"
+ *
+ * # Arguments
+ * * `doc_id` - Document ID
+ * * `epoch` - Epoch number
+ *
+ * # Returns
+ * Context string
+ */
+export function buildContext(doc_id: string, epoch: number): string;
+/**
+ * Initialize panic hook for better error messages in WASM
+ */
+export function init(): void;
+/**
+ * Get version info
+ */
+export function version(): string;
+/**
+ * AEAD encryption result
+ */
+export class AeadResult {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Get ciphertext as base64url
+   */
+  toBase64Url(): string;
+  /**
+   * Get ciphertext as bytes
+   */
+  readonly ciphertext: Uint8Array;
+}
+/**
+ * KEM encapsulation result (shared secret + ciphertext)
+ */
+export class KemEncapResult {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Get ciphertext as base64url
+   */
+  ciphertextBase64(): string;
+  /**
+   * Get shared secret (32 bytes)
+   */
+  readonly sharedSecret: Uint8Array;
+  /**
+   * Get ciphertext (to send to recipient)
+   */
+  readonly ciphertext: Uint8Array;
+}
+/**
+ * ML-KEM-768 keypair
+ */
+export class KemKeypair {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Get public key as base64url
+   */
+  publicKeyBase64(): string;
+  /**
+   * Get secret key as base64url
+   */
+  secretKeyBase64(): string;
+  /**
+   * Get public key bytes
+   */
+  readonly publicKey: Uint8Array;
+  /**
+   * Get secret key bytes
+   */
+  readonly secretKey: Uint8Array;
+}
+/**
+ * A Shamir secret share
+ */
+export class SecretShare {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Serialize share to JSON
+   */
+  toJson(): string;
+  /**
+   * Deserialize share from JSON
+   */
+  static fromJson(json: string): SecretShare;
+  /**
+   * Get share as base64url
+   */
+  toBase64(): string;
+  /**
+   * Deserialize share from base64url
+   */
+  static fromBase64(b64: string): SecretShare;
+  /**
+   * Get share identifier
+   */
+  readonly identifier: number;
+  /**
+   * Get share value as bytes
+   */
+  readonly value: Uint8Array;
+}