freenet_stdlib/

delegate_host.rs

//! Host function API for delegates.
//!
//! This module provides synchronous access to delegate context, secrets, and
//! contract state via host functions, eliminating the need for message round-trips.
//!
//! # Example
//!
//! ```ignore
//! use freenet_stdlib::prelude::*;
//!
//! #[delegate]
//! impl DelegateInterface for MyDelegate {
//!     fn process(
//!         ctx: &mut DelegateCtx,
//!         _params: Parameters<'static>,
//!         _attested: Option<&'static [u8]>,
//!         message: InboundDelegateMsg,
//!     ) -> Result<Vec<OutboundDelegateMsg>, DelegateError> {
//!         // Read/write temporary context
//!         let data = ctx.read();
//!         ctx.write(b"new state");
//!
//!         // Access persistent secrets
//!         if let Some(key) = ctx.get_secret(b"private_key") {
//!             // use key...
//!         }
//!         ctx.set_secret(b"new_secret", b"value");
//!
//!         // Read contract state the node already holds (no round-trip)
//!         let contract_id = [0u8; 32]; // your contract instance ID
//!         if let Some(state) = ctx.get_contract_state(&contract_id) {
//!             // process state...
//!         }
//!
//!         Ok(vec![])
//!     }
//! }
//! ```
//!
//! # Context vs Secrets vs Contracts
//!
//! - **Context** (`read`/`write`): Temporary state within a single message batch.
//!   Reset between separate runtime calls. Use for intermediate processing state.
//!
//! - **Secrets** (`get_secret`/`set_secret`): Persistent encrypted storage.
//!   Survives across all delegate invocations. Use for private keys, tokens, etc.
//!
//! - **Contracts** (`get_contract_state`): a synchronous read of contract state
//!   the node already holds locally, with no request/response round-trip.
//!
//!   There is no host function for *writing* or *subscribing*. A delegate does
//!   both by emitting the corresponding `OutboundDelegateMsg` —
//!   `PutContractRequest`, `UpdateContractRequest`, `SubscribeContractRequest` —
//!   which go through the node's normal contract path.
//!
//! # Adding a host function is the additive way to extend this API
//!
//! Host functions are resolved **by name at module instantiation**. A delegate
//! that imports one an older node does not provide fails to load, with a named
//! missing-import error; a delegate that does not import it is unaffected. So
//! adding a host function is additive for every existing delegate, and its
//! failure mode for a too-old node is loud and diagnosable at load time.
//!
//! Contrast the message API (`OutboundDelegateMsg`): a new variant sent to an
//! older host fails mid-protocol at bincode decode, with no way for the
//! delegate to have detected the host's version first. Where a capability can
//! be expressed either way, prefer the host function.
//!
//! # Error Codes
//!
//! Host functions return negative values to indicate errors:
//!
//! | Code | Meaning |
//! |------|---------|
//! | 0    | Success |
//! | -1   | Called outside process() context |
//! | -2   | Secret not found |
//! | -3   | Storage operation failed |
//! | -4   | Invalid parameter (e.g., negative length) |
//! | -5   | Context too large (exceeds i32::MAX) |
//! | -6   | Buffer too small |
//! | -7   | Contract not found in local store |
//! | -8   | Internal state store error |
//! | -9   | WASM memory bounds violation |
//! | -10  | Contract code not registered |
//!
//! The wrapper methods in [`DelegateCtx`] handle these error codes and present
//! a more ergonomic API.

/// Error codes returned by host functions.
///
/// Negative values indicate errors, non-negative values indicate success
/// (usually the number of bytes read/written).
pub mod error_codes {
    /// Operation succeeded.
    pub const SUCCESS: i32 = 0;
    /// Called outside of a process() context.
    pub const ERR_NOT_IN_PROCESS: i32 = -1;
    /// Secret not found.
    pub const ERR_SECRET_NOT_FOUND: i32 = -2;
    /// Storage operation failed.
    pub const ERR_STORAGE_FAILED: i32 = -3;
    /// Invalid parameter (e.g., negative length).
    pub const ERR_INVALID_PARAM: i32 = -4;
    /// Context too large (exceeds i32::MAX).
    pub const ERR_CONTEXT_TOO_LARGE: i32 = -5;
    /// Buffer too small to hold the data.
    pub const ERR_BUFFER_TOO_SMALL: i32 = -6;
    /// Contract not found in local store.
    pub const ERR_CONTRACT_NOT_FOUND: i32 = -7;
    /// Internal state store error.
    pub const ERR_STORE_ERROR: i32 = -8;
    /// WASM memory bounds violation (pointer/length out of range).
    pub const ERR_MEMORY_BOUNDS: i32 = -9;
    /// Contract code not registered in the index.
    pub const ERR_CONTRACT_CODE_NOT_REGISTERED: i32 = -10;
    /// Delegate creation depth limit exceeded.
    pub const ERR_DEPTH_EXCEEDED: i32 = -20;
    /// Per-call delegate creation limit exceeded.
    pub const ERR_CREATIONS_EXCEEDED: i32 = -21;
    /// Invalid WASM module (failed to construct DelegateContainer).
    pub const ERR_INVALID_WASM: i32 = -23;
    /// Failed to register delegate in secret/delegate store.
    pub const ERR_STORE_FAILED: i32 = -24;
}

// ============================================================================
// Host function declarations (WASM only)
// ============================================================================

#[cfg(target_family = "wasm")]
#[link(wasm_import_module = "freenet_delegate_ctx")]
extern "C" {
    /// Returns the current context length in bytes, or negative error code.
    fn __frnt__delegate__ctx_len() -> i32;
    /// Reads context into the buffer at `ptr` (max `len` bytes). Returns bytes written, or negative error code.
    fn __frnt__delegate__ctx_read(ptr: i64, len: i32) -> i32;
    /// Writes `len` bytes from `ptr` into the context, replacing existing content. Returns 0 on success, or negative error code.
    fn __frnt__delegate__ctx_write(ptr: i64, len: i32) -> i32;
}

#[cfg(target_family = "wasm")]
#[link(wasm_import_module = "freenet_delegate_secrets")]
extern "C" {
    /// Get a secret. Returns bytes written to `out_ptr`, or negative error code.
    fn __frnt__delegate__get_secret(key_ptr: i64, key_len: i32, out_ptr: i64, out_len: i32) -> i32;
    /// Get secret length without fetching value. Returns length, or negative error code.
    fn __frnt__delegate__get_secret_len(key_ptr: i64, key_len: i32) -> i32;
    /// Store a secret. Returns 0 on success, or negative error code.
    fn __frnt__delegate__set_secret(key_ptr: i64, key_len: i32, val_ptr: i64, val_len: i32) -> i32;
    /// Check if a secret exists. Returns 1 if yes, 0 if no, or negative error code.
    fn __frnt__delegate__has_secret(key_ptr: i64, key_len: i32) -> i32;
    /// Remove a secret. Returns 0 on success, or negative error code.
    fn __frnt__delegate__remove_secret(key_ptr: i64, key_len: i32) -> i32;
    /// Length (in bytes) of the serialized key list for all stored secret keys
    /// whose raw key starts with the `prefix_len`-byte prefix at `prefix_ptr`
    /// (an empty prefix matches every key). Returns the byte count to allocate
    /// before calling `__frnt__delegate__list_secrets`, or a negative error code.
    fn __frnt__delegate__list_secrets_len(prefix_ptr: i64, prefix_len: i32) -> i32;
    /// Enumerate stored secret keys matching the prefix. Writes a length-prefixed
    /// list to `out_ptr` (max `out_len` bytes): each record is a 4-byte
    /// little-endian length followed by that many key bytes. Returns the number
    /// of bytes written, or a negative error code.
    fn __frnt__delegate__list_secrets(
        prefix_ptr: i64,
        prefix_len: i32,
        out_ptr: i64,
        out_len: i32,
    ) -> i32;
}

#[cfg(target_family = "wasm")]
#[link(wasm_import_module = "freenet_delegate_contracts")]
extern "C" {
    /// Get contract state length. Returns byte count, or negative error code (i64).
    fn __frnt__delegate__get_contract_state_len(id_ptr: i64, id_len: i32) -> i64;
    /// Get contract state. Returns byte count written, or negative error code (i64).
    fn __frnt__delegate__get_contract_state(
        id_ptr: i64,
        id_len: i32,
        out_ptr: i64,
        out_len: i64,
    ) -> i64;
}

#[cfg(target_family = "wasm")]
#[link(wasm_import_module = "freenet_delegate_management")]
extern "C" {
    /// Create a new delegate from WASM code + parameters.
    /// Returns 0 on success, negative error code on failure.
    /// On success, writes 32 bytes to out_key_ptr and 32 bytes to out_hash_ptr.
    fn __frnt__delegate__create_delegate(
        wasm_ptr: i64,
        wasm_len: i64,
        params_ptr: i64,
        params_len: i64,
        cipher_ptr: i64,
        nonce_ptr: i64,
        out_key_ptr: i64,
        out_hash_ptr: i64,
    ) -> i32;
}

// ============================================================================
// DelegateCtx - Unified handle to context, secrets, and contracts
// ============================================================================

/// Opaque handle to the delegate's execution environment.
///
/// Provides access to:
/// - **Temporary context**: State shared within a single message batch (reset between calls)
/// - **Persistent secrets**: Encrypted storage that survives across all invocations
/// - **Contract state**: Direct synchronous read of local contract state
///
/// # Context Methods
/// - [`read`](Self::read), [`write`](Self::write), [`len`](Self::len), [`clear`](Self::clear)
///
/// # Secret Methods
/// - [`get_secret`](Self::get_secret), [`set_secret`](Self::set_secret),
///   [`has_secret`](Self::has_secret), [`remove_secret`](Self::remove_secret)
///
/// # Contract Methods
/// - [`get_contract_state`](Self::get_contract_state)
///
/// # Delegate Management Methods
/// - [`create_delegate`](Self::create_delegate)
#[derive(Default)]
#[repr(transparent)]
pub struct DelegateCtx {
    _private: (),
}

impl DelegateCtx {
    /// Creates the context handle.
    ///
    /// # Safety
    ///
    /// This should only be called by macro-generated code when the runtime
    /// has set up the delegate execution environment.
    #[doc(hidden)]
    pub unsafe fn __new() -> Self {
        Self { _private: () }
    }

    // ========================================================================
    // Context methods (temporary state within a batch)
    // ========================================================================

    /// Returns the current context length in bytes.
    #[inline]
    pub fn len(&self) -> usize {
        #[cfg(target_family = "wasm")]
        {
            let len = unsafe { __frnt__delegate__ctx_len() };
            if len < 0 {
                0
            } else {
                len as usize
            }
        }
        #[cfg(not(target_family = "wasm"))]
        {
            0
        }
    }

    /// Returns `true` if the context is empty.
    #[inline]
    pub fn is_empty(&self) -> bool {
        self.len() == 0
    }

    /// Read the current context bytes.
    ///
    /// Returns an empty `Vec` if no context has been written.
    pub fn read(&self) -> Vec<u8> {
        #[cfg(target_family = "wasm")]
        {
            let len = unsafe { __frnt__delegate__ctx_len() };
            if len <= 0 {
                return Vec::new();
            }
            let mut buf = vec![0u8; len as usize];
            let read = unsafe { __frnt__delegate__ctx_read(buf.as_mut_ptr() as i64, len) };
            buf.truncate(read.max(0) as usize);
            buf
        }
        #[cfg(not(target_family = "wasm"))]
        {
            Vec::new()
        }
    }

    /// Read context into a provided buffer.
    ///
    /// Returns the number of bytes actually read.
    pub fn read_into(&self, buf: &mut [u8]) -> usize {
        #[cfg(target_family = "wasm")]
        {
            let read =
                unsafe { __frnt__delegate__ctx_read(buf.as_mut_ptr() as i64, buf.len() as i32) };
            read.max(0) as usize
        }
        #[cfg(not(target_family = "wasm"))]
        {
            let _ = buf;
            0
        }
    }

    /// Write new context bytes, replacing any existing content.
    ///
    /// Returns `true` on success, `false` on error.
    pub fn write(&mut self, data: &[u8]) -> bool {
        #[cfg(target_family = "wasm")]
        {
            let result =
                unsafe { __frnt__delegate__ctx_write(data.as_ptr() as i64, data.len() as i32) };
            result == 0
        }
        #[cfg(not(target_family = "wasm"))]
        {
            let _ = data;
            false
        }
    }

    /// Clear the context.
    #[inline]
    pub fn clear(&mut self) {
        self.write(&[]);
    }

    // ========================================================================
    // Secret methods (persistent encrypted storage)
    // ========================================================================

    /// Get the length of a secret without retrieving its value.
    ///
    /// Returns `None` if the secret does not exist.
    pub fn get_secret_len(&self, key: &[u8]) -> Option<usize> {
        #[cfg(target_family = "wasm")]
        {
            let result =
                unsafe { __frnt__delegate__get_secret_len(key.as_ptr() as i64, key.len() as i32) };
            if result < 0 {
                None
            } else {
                Some(result as usize)
            }
        }
        #[cfg(not(target_family = "wasm"))]
        {
            let _ = key;
            None
        }
    }

    /// Get a secret by key.
    ///
    /// Returns `None` if the secret does not exist.
    pub fn get_secret(&self, key: &[u8]) -> Option<Vec<u8>> {
        #[cfg(target_family = "wasm")]
        {
            // First get the length to allocate the right buffer size
            let len = self.get_secret_len(key)?;

            if len == 0 {
                return Some(Vec::new());
            }

            let mut out = vec![0u8; len];
            let result = unsafe {
                __frnt__delegate__get_secret(
                    key.as_ptr() as i64,
                    key.len() as i32,
                    out.as_mut_ptr() as i64,
                    out.len() as i32,
                )
            };
            if result < 0 {
                None
            } else {
                out.truncate(result as usize);
                Some(out)
            }
        }
        #[cfg(not(target_family = "wasm"))]
        {
            let _ = key;
            None
        }
    }

    /// Store a secret.
    ///
    /// Returns `true` on success, `false` on error.
    pub fn set_secret(&mut self, key: &[u8], value: &[u8]) -> bool {
        #[cfg(target_family = "wasm")]
        {
            let result = unsafe {
                __frnt__delegate__set_secret(
                    key.as_ptr() as i64,
                    key.len() as i32,
                    value.as_ptr() as i64,
                    value.len() as i32,
                )
            };
            result == 0
        }
        #[cfg(not(target_family = "wasm"))]
        {
            let _ = (key, value);
            false
        }
    }

    /// Check if a secret exists.
    pub fn has_secret(&self, key: &[u8]) -> bool {
        #[cfg(target_family = "wasm")]
        {
            let result =
                unsafe { __frnt__delegate__has_secret(key.as_ptr() as i64, key.len() as i32) };
            result == 1
        }
        #[cfg(not(target_family = "wasm"))]
        {
            let _ = key;
            false
        }
    }

    /// Remove a secret.
    ///
    /// Returns `true` if the secret was removed, `false` if it didn't exist.
    pub fn remove_secret(&mut self, key: &[u8]) -> bool {
        #[cfg(target_family = "wasm")]
        {
            let result =
                unsafe { __frnt__delegate__remove_secret(key.as_ptr() as i64, key.len() as i32) };
            result == 0
        }
        #[cfg(not(target_family = "wasm"))]
        {
            let _ = key;
            false
        }
    }

    /// Enumerate the keys of every secret this delegate has stored whose raw
    /// key begins with `prefix` (pass an empty slice to list all keys).
    ///
    /// Returns the matching raw keys (the same byte strings originally passed
    /// to [`set_secret`](Self::set_secret)). Order is unspecified. The host
    /// caps the number of keys returned; if storage holds more matching keys
    /// than the cap, the list is truncated (callers needing exhaustive
    /// enumeration should narrow the prefix).
    ///
    /// This closes the gap that previously forced apps storing an open-ended
    /// key family (e.g. `room:<owner_vk>`) to maintain their own key registry:
    /// after a delegate-WASM rebuild the delegate can now rediscover what it
    /// has stored instead of probing a hardcoded key set.
    pub fn list_secrets(&self, prefix: &[u8]) -> Vec<Vec<u8>> {
        #[cfg(target_family = "wasm")]
        {
            let len = unsafe {
                __frnt__delegate__list_secrets_len(prefix.as_ptr() as i64, prefix.len() as i32)
            };
            if len <= 0 {
                // Negative => error; zero => no matching keys. Either way the
                // caller gets an empty list (errors are non-fatal: enumeration
                // is advisory).
                return Vec::new();
            }
            let mut out = vec![0u8; len as usize];
            let written = unsafe {
                __frnt__delegate__list_secrets(
                    prefix.as_ptr() as i64,
                    prefix.len() as i32,
                    out.as_mut_ptr() as i64,
                    out.len() as i32,
                )
            };
            if written < 0 {
                return Vec::new();
            }
            out.truncate(written as usize);
            decode_secret_key_list(&out)
        }
        #[cfg(not(target_family = "wasm"))]
        {
            let _ = prefix;
            Vec::new()
        }
    }

    // ========================================================================
    // Contract methods (direct synchronous read of local state)
    // ========================================================================

    /// Get contract state by instance ID.
    ///
    /// Returns `Some(state_bytes)` if the contract exists locally,
    /// `None` if not found or on error.
    ///
    /// Uses a two-step protocol: first queries the state length, then reads
    /// the state bytes into an allocated buffer.
    pub fn get_contract_state(&self, instance_id: &[u8; 32]) -> Option<Vec<u8>> {
        #[cfg(target_family = "wasm")]
        {
            // Step 1: Get the state length
            let len = unsafe {
                __frnt__delegate__get_contract_state_len(instance_id.as_ptr() as i64, 32)
            };
            if len < 0 {
                return None;
            }
            let len = len as usize;
            if len == 0 {
                return Some(Vec::new());
            }

            // Step 2: Read the state bytes
            let mut buf = vec![0u8; len];
            let read = unsafe {
                __frnt__delegate__get_contract_state(
                    instance_id.as_ptr() as i64,
                    32,
                    buf.as_mut_ptr() as i64,
                    buf.len() as i64,
                )
            };
            if read < 0 {
                None
            } else {
                buf.truncate(read as usize);
                Some(buf)
            }
        }
        #[cfg(not(target_family = "wasm"))]
        {
            let _ = instance_id;
            None
        }
    }

    /// Create a new child delegate from WASM bytecode and parameters.
    ///
    /// This V2 host function allows a delegate to spawn new delegates at runtime.
    /// The child delegate is registered in the node's delegate store and secret store
    /// with the provided cipher and nonce.
    ///
    /// Returns `Ok((key_hash, code_hash))` where both are 32-byte arrays identifying
    /// the newly created delegate. Returns `Err(error_code)` on failure.
    ///
    /// # Resource Limits
    /// - Maximum creation depth: 4 (prevents fork bombs)
    /// - Maximum creations per process() call: 8
    ///
    /// # Error Codes
    /// - `-1`: Called outside process() context
    /// - `-4`: Invalid parameter
    /// - `-9`: WASM memory bounds violation
    /// - `-20`: Depth limit exceeded
    /// - `-21`: Per-call creation limit exceeded
    /// - `-23`: Invalid WASM module
    /// - `-24`: Store registration failed
    pub fn create_delegate(
        &mut self,
        wasm_code: &[u8],
        params: &[u8],
        cipher: &[u8; 32],
        nonce: &[u8; 24],
    ) -> Result<([u8; 32], [u8; 32]), i32> {
        #[cfg(target_family = "wasm")]
        {
            let mut key_buf = [0u8; 32];
            let mut hash_buf = [0u8; 32];
            let result = unsafe {
                __frnt__delegate__create_delegate(
                    wasm_code.as_ptr() as i64,
                    wasm_code.len() as i64,
                    params.as_ptr() as i64,
                    params.len() as i64,
                    cipher.as_ptr() as i64,
                    nonce.as_ptr() as i64,
                    key_buf.as_mut_ptr() as i64,
                    hash_buf.as_mut_ptr() as i64,
                )
            };
            if result == 0 {
                Ok((key_buf, hash_buf))
            } else {
                Err(result)
            }
        }
        #[cfg(not(target_family = "wasm"))]
        {
            let _ = (wasm_code, params, cipher, nonce);
            Err(error_codes::ERR_NOT_IN_PROCESS)
        }
    }
}

impl std::fmt::Debug for DelegateCtx {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("DelegateCtx")
            .field("context_len", &self.len())
            .finish_non_exhaustive()
    }
}

// ============================================================================
// Secret-key-list wire codec (shared host↔delegate contract for list_secrets)
// ============================================================================

/// Serialize a list of raw secret keys into the wire format read back by
/// [`decode_secret_key_list`]: for each key, a 4-byte little-endian length
/// followed by that many key bytes. This is the encoding the host
/// (`__frnt__delegate__list_secrets`) writes into the delegate's output buffer.
///
/// Kept in stdlib (rather than only in the host) so the format has exactly one
/// authoritative definition that both sides — and the round-trip tests — share.
pub fn encode_secret_key_list<'a, I>(keys: I) -> Vec<u8>
where
    I: IntoIterator<Item = &'a [u8]>,
{
    let mut buf = Vec::new();
    for key in keys {
        buf.extend_from_slice(&(key.len() as u32).to_le_bytes());
        buf.extend_from_slice(key);
    }
    buf
}

/// Inverse of [`encode_secret_key_list`]. A truncated trailing record (which can
/// only happen if the buffer was clipped mid-record) is dropped rather than
/// panicking, so a short read degrades to "fewer keys" instead of a trap.
pub fn decode_secret_key_list(buf: &[u8]) -> Vec<Vec<u8>> {
    let mut keys = Vec::new();
    let mut pos = 0usize;
    while pos + 4 <= buf.len() {
        let len = u32::from_le_bytes([buf[pos], buf[pos + 1], buf[pos + 2], buf[pos + 3]]) as usize;
        pos += 4;
        if pos + len > buf.len() {
            // Truncated record: stop here rather than over-read.
            break;
        }
        keys.push(buf[pos..pos + len].to_vec());
        pos += len;
    }
    keys
}

#[cfg(test)]
mod secret_key_list_codec_tests {
    use super::{decode_secret_key_list, encode_secret_key_list};

    #[test]
    fn round_trip_multiple_keys() {
        let keys: Vec<&[u8]> = vec![b"room:alice", b"room:bob", b"private_key"];
        let encoded = encode_secret_key_list(keys.iter().copied());
        let decoded = decode_secret_key_list(&encoded);
        assert_eq!(
            decoded,
            vec![
                b"room:alice".to_vec(),
                b"room:bob".to_vec(),
                b"private_key".to_vec()
            ]
        );
    }

    #[test]
    fn round_trip_empty_list() {
        let encoded = encode_secret_key_list(std::iter::empty::<&[u8]>());
        assert!(encoded.is_empty());
        assert!(decode_secret_key_list(&encoded).is_empty());
    }

    #[test]
    fn round_trip_empty_key() {
        // A zero-length key is a legal (if unusual) record.
        let encoded = encode_secret_key_list([b"".as_slice()]);
        assert_eq!(encoded, vec![0, 0, 0, 0]);
        assert_eq!(decode_secret_key_list(&encoded), vec![Vec::<u8>::new()]);
    }

    #[test]
    fn truncated_trailing_record_is_dropped() {
        let mut encoded = encode_secret_key_list([b"abc".as_slice(), b"defgh".as_slice()]);
        // Clip mid-way through the second record's payload.
        encoded.truncate(encoded.len() - 2);
        assert_eq!(decode_secret_key_list(&encoded), vec![b"abc".to_vec()]);
    }
}