Secret-Key Encryption

/**
 * Generates a random 32-byte key for secret-key encryption
 * @returns 32-byte encryption key
 */
function crypto_secretbox_keygen();

/**
 * Encrypts a message with a secret key
 * @param message - The plaintext message to encrypt
 * @param nonce - 24-byte nonce (must be unique for each message with the same key)
 * @param key - 32-byte secret key
 * @returns Encrypted ciphertext with authentication tag
 */
function crypto_secretbox_easy(message, nonce, key);

/**
 * Decrypts a message with a secret key
 * @param ciphertext - The encrypted message to decrypt
 * @param nonce - 24-byte nonce used during encryption
 * @param key - 32-byte secret key used for encryption
 * @returns Decrypted plaintext message
 * @throws Error if decryption fails or authentication is invalid
 */
function crypto_secretbox_open_easy(ciphertext, nonce, key);

/**
 * Encrypts a message with detached authentication tag
 * @param message - The plaintext message to encrypt
 * @param nonce - 24-byte nonce
 * @param key - 32-byte secret key
 * @returns Object with cipher and mac properties
 */
function crypto_secretbox_detached(message, nonce, key);

/**
 * Decrypts a message with detached authentication tag
 * @param ciphertext - The encrypted message
 * @param mac - The detached authentication tag
 * @param nonce - 24-byte nonce used during encryption
 * @param key - 32-byte secret key
 * @returns Decrypted plaintext message
 */
function crypto_secretbox_open_detached(ciphertext, mac, nonce, key);

// Generate key and nonce
const key = sodium.crypto_secretbox_keygen();
const nonce = sodium.randombytes_buf(sodium.crypto_secretbox_NONCEBYTES);

// Encrypt a message
const message = sodium.from_string("Secret message");
const ciphertext = sodium.crypto_secretbox_easy(message, nonce, key);

// Decrypt the message
const decrypted = sodium.crypto_secretbox_open_easy(ciphertext, nonce, key);
console.log(sodium.to_string(decrypted)); // "Secret message"

/**
 * Generates a random 32-byte key for secret streams
 * @returns 32-byte stream key
 */
function crypto_secretstream_xchacha20poly1305_keygen();

/**
 * Initializes encryption state for a secret stream
 * @param key - 32-byte stream key
 * @returns Object with state and header properties
 */
function crypto_secretstream_xchacha20poly1305_init_push(key);

/**
 * Encrypts a chunk of data in the stream
 * @param state_address - State from init_push
 * @param message_chunk - Data chunk to encrypt
 * @param ad - Optional additional data to authenticate
 * @param tag - Message tag (TAG_MESSAGE, TAG_PUSH, TAG_REKEY, or TAG_FINAL)
 * @returns Encrypted chunk with authentication
 */
function crypto_secretstream_xchacha20poly1305_push(state_address, message_chunk, ad, tag);

/**
 * Initializes decryption state for a secret stream
 * @param header - Stream header from init_push
 * @param key - 32-byte stream key
 * @returns State address for decryption operations
 */
function crypto_secretstream_xchacha20poly1305_init_pull(header, key);

/**
 * Decrypts a chunk of data from the stream
 * @param state_address - State from init_pull
 * @param cipher - Encrypted chunk to decrypt
 * @param ad - Additional data that was authenticated during encryption
 * @returns Object with message and tag properties
 */
function crypto_secretstream_xchacha20poly1305_pull(state_address, cipher, ad);

/**
 * Rekeys the stream state for forward secrecy
 * @param state_address - State to rekey
 * @returns true on success
 */
function crypto_secretstream_xchacha20poly1305_rekey(state_address);

// Initialize encryption
const key = sodium.crypto_secretstream_xchacha20poly1305_keygen();
const {state, header} = sodium.crypto_secretstream_xchacha20poly1305_init_push(key);

// Encrypt chunks
const chunk1 = sodium.crypto_secretstream_xchacha20poly1305_push(
  state, 
  sodium.from_string("First chunk"), 
  null, 
  sodium.crypto_secretstream_xchacha20poly1305_TAG_MESSAGE
);

const chunk2 = sodium.crypto_secretstream_xchacha20poly1305_push(
  state, 
  sodium.from_string("Final chunk"), 
  null, 
  sodium.crypto_secretstream_xchacha20poly1305_TAG_FINAL
);

// Initialize decryption
const pullState = sodium.crypto_secretstream_xchacha20poly1305_init_pull(header, key);

// Decrypt chunks
const decrypted1 = sodium.crypto_secretstream_xchacha20poly1305_pull(pullState, chunk1, null);
const decrypted2 = sodium.crypto_secretstream_xchacha20poly1305_pull(pullState, chunk2, null);

console.log(sodium.to_string(decrypted1.message)); // "First chunk"
console.log(sodium.to_string(decrypted2.message)); // "Final chunk"

// Secret Box
const crypto_secretbox_KEYBYTES = 32;     // Key size
const crypto_secretbox_NONCEBYTES = 24;   // Nonce size
const crypto_secretbox_MACBYTES = 16;     // Authentication tag size

// Secret Streams  
const crypto_secretstream_xchacha20poly1305_KEYBYTES = 32;     // Key size
const crypto_secretstream_xchacha20poly1305_HEADERBYTES = 24;  // Header size
const crypto_secretstream_xchacha20poly1305_ABYTES = 17;       // Auth tag size

// Stream Tags
const crypto_secretstream_xchacha20poly1305_TAG_MESSAGE = 0;   // Regular message
const crypto_secretstream_xchacha20poly1305_TAG_PUSH = 1;      // End of chunk
const crypto_secretstream_xchacha20poly1305_TAG_REKEY = 2;     // Rekey point
const crypto_secretstream_xchacha20poly1305_TAG_FINAL = 3;     // End of stream