Struct AgentWrapper 

pub struct AgentWrapper { /* private fields */ }

Thread-safe wrapper around a JACS Agent.

This provides the core agent functionality that all bindings share. Bindings wrap this in their own types and convert errors appropriately.

Implementations

impl AgentWrapper

pub fn new() -> Self

Create a new empty agent wrapper.

pub fn from_inner(inner: Arc<Mutex<Agent>>) -> Self

Create an agent wrapper from an existing Arc<Mutex>.

This is used by the Go FFI to share the agent handle’s inner agent with binding-core’s attestation methods.

pub fn inner_arc(&self) -> Arc<Mutex<Agent>>

Get the inner Arc<Mutex<Agent>>.

Used to share the agent handle with DocumentServiceWrapper and other components that need direct access to the underlying agent.

pub fn set_private_key_password( &self, password: Option<String>, ) -> BindingResult<()>

Configure a per-wrapper private-key password for load/sign operations.

This lets higher-level bindings keep per-instance passwords out of process-global environment management while the current core library still resolves decryption passwords through JACS_PRIVATE_KEY_PASSWORD.

pub fn load(&self, config_path: String) -> BindingResult<String>

Load agent configuration from a file path.

Uses Config::from_file + apply_env_overrides + Agent::from_config to avoid deprecated load_by_config and env var side-channels.

pub fn load_file_only(&self, config_path: String) -> BindingResult<String>

Load agent configuration from file only, without applying env/jenv overrides. This is the isolation-safe counterpart of [load] — the caller constructs a pristine config file and does not want ambient JACS_* environment variables to pollute it (Issue 008).

pub fn load_with_info(&self, config_path: String) -> BindingResult<String>

Load agent configuration and return canonical loaded-agent metadata.

pub fn set_storage_root(&self, root: PathBuf) -> BindingResult<()>

Re-root the internal file storage at root.

By default load_by_config roots the FS backend at the current working directory. verify_document_standalone uses this to re-root at / so that absolute data/key directory paths work regardless of CWD.

pub fn sign_agent( &self, agent_string: &str, public_key: Vec<u8>, public_key_enc_type: String, ) -> BindingResult<String>

Sign an external agent’s document with this agent’s registration signature.

pub fn verify_string( &self, data: &str, signature_base64: &str, public_key: Vec<u8>, public_key_enc_type: String, ) -> BindingResult<bool>

Verify a signature on arbitrary string data.

pub fn sign_string(&self, data: &str) -> BindingResult<String>

Sign arbitrary string data with this agent’s private key.

pub fn sign_batch(&self, messages: Vec<String>) -> BindingResult<Vec<String>>

Sign multiple messages in a single batch, decrypting the private key only once.

pub fn verify_agent(&self, agentfile: Option<String>) -> BindingResult<bool>

Verify this agent’s signature and hash.

pub fn update_agent(&self, new_agent_string: &str) -> BindingResult<String>

Update the agent document with new data.

pub fn verify_document(&self, document_string: &str) -> BindingResult<bool>

Verify a document’s signature and hash.

pub fn update_document( &self, document_key: &str, new_document_string: &str, attachments: Option<Vec<String>>, embed: Option<bool>, ) -> BindingResult<String>

Update an existing document.

pub fn verify_signature( &self, document_string: &str, signature_field: Option<String>, ) -> BindingResult<bool>

Verify a document’s signature with an optional custom signature field.

pub fn create_agreement( &self, document_string: &str, agentids: Vec<String>, question: Option<String>, context: Option<String>, agreement_fieldname: Option<String>, ) -> BindingResult<String>

Create an agreement on a document.

pub fn create_agreement_with_options( &self, document_string: &str, agentids: Vec<String>, question: Option<String>, context: Option<String>, agreement_fieldname: Option<String>, timeout: Option<String>, quorum: Option<u32>, required_algorithms: Option<Vec<String>>, minimum_strength: Option<String>, ) -> BindingResult<String>

Create an agreement with extended options (timeout, quorum, algorithm constraints).

All option parameters are optional:

• timeout: ISO 8601 deadline after which the agreement expires
• quorum: minimum number of signatures required (M-of-N)
• required_algorithms: only accept signatures from these algorithms
• minimum_strength: “classical” or “post-quantum”

pub fn sign_agreement( &self, document_string: &str, agreement_fieldname: Option<String>, ) -> BindingResult<String>

Sign an agreement on a document.

pub fn create_document( &self, document_string: &str, custom_schema: Option<String>, outputfilename: Option<String>, no_save: bool, attachments: Option<&str>, embed: Option<bool>, ) -> BindingResult<String>

Create a new JACS document.

pub fn save_signed_document( &self, document_string: &str, outputfilename: Option<String>, export_embedded: Option<bool>, extract_only: Option<bool>, ) -> BindingResult<String>

Persist an already-signed JACS document and return its lookup key.

Stores the document both in the agent’s data directory (for file-based access) and in the storage index (documents/) so that list_document_keys() can find it.

pub fn list_document_keys(&self) -> BindingResult<Vec<String>>

Return all known document lookup keys from the agent’s configured storage.

pub fn check_agreement( &self, document_string: &str, agreement_fieldname: Option<String>, ) -> BindingResult<String>

Check an agreement on a document.

pub fn sign_request(&self, payload_value: Value) -> BindingResult<String>

Sign a request payload (wraps in a JACS document).

pub fn verify_response(&self, document_string: String) -> BindingResult<Value>

Verify a response payload and return the payload value.

pub fn verify_response_with_agent_id( &self, document_string: String, ) -> BindingResult<(Value, String)>

Verify a response payload and return (payload, agent_id).

pub fn verify_document_by_id(&self, document_id: &str) -> BindingResult<bool>

Verify a document looked up by its ID from storage.

This is a convenience method for when you have a document ID rather than the full JSON string. The document ID should be in “uuid:version” format.

pub fn get_document_by_id(&self, document_id: &str) -> BindingResult<String>

Load a document by ID from the agent’s configured storage.

The document ID should be in “uuid:version” format.

pub fn get_agent_id(&self) -> BindingResult<String>

Get the loaded agent’s canonical JACS identifier.

pub fn reencrypt_key( &self, old_password: &str, new_password: &str, ) -> BindingResult<()>

Re-encrypt the agent’s private key with a new password.

Reads the encrypted private key file, decrypts with old_password, validates new_password, re-encrypts, and writes the updated file.

pub fn ephemeral(&self, algorithm: Option<&str>) -> BindingResult<String>

Create an ephemeral in-memory agent. No config, no files, no env vars needed.

Replaces the inner agent with a freshly created ephemeral agent that lives entirely in memory. Returns a JSON string with agent info (agent_id, name, version, algorithm). Default algorithm is pq2025.

pub fn diagnostics(&self) -> String

Returns diagnostic information including loaded agent details as a JSON string.

pub fn get_setup_instructions( &self, domain: &str, ttl: u32, ) -> BindingResult<String>

Returns setup instructions for publishing DNS records and enabling DNSSEC.

Requires a loaded agent (call load() first).

pub fn export_agent(&self) -> BindingResult<String>

Export the loaded agent’s full JSON document.

pub fn get_public_key_pem(&self) -> BindingResult<String>

Get the loaded agent’s public key as a PEM string.

pub fn get_agent_json(&self) -> BindingResult<String>

Get the agent’s JSON representation as a string.

Returns the agent’s full JSON document.

impl AgentWrapper

pub fn build_auth_header(&self) -> BindingResult<String>

Build the JACS Authorization header value.

Format: "JACS {jacs_id}:{unix_timestamp}:{base64_signature}". Requires a loaded agent with keys.

pub fn canonicalize_json(&self, json_string: &str) -> BindingResult<String>

Deterministically serialize a JSON string per RFC 8785 (JCS).

Accepts a JSON string, parses it, and returns the canonicalized form.

pub fn sign_response(&self, payload_json: &str) -> BindingResult<String>

Build and sign a JACS response envelope.

Accepts a JSON payload string, returns a signed envelope JSON string containing version, document_type, data, metadata, and jacsSignature.

pub fn encode_verify_payload(&self, document: &str) -> BindingResult<String>

Encode a document as URL-safe base64 (no padding) for verification.

SDK clients use this to build verification URLs. JACS does not impose any URL structure — that is the SDK’s responsibility.

pub fn decode_verify_payload(&self, encoded: &str) -> BindingResult<String>

Decode a URL-safe base64 verification payload back to the original document string.

pub fn extract_document_id(&self, document: &str) -> BindingResult<String>

Extract the document ID from a JACS-signed document.

Checks jacsDocumentId, document_id, id in priority order. SDK clients use this to build hosted verification URLs.

pub fn unwrap_signed_event( &self, event_json: &str, server_keys_json: &str, ) -> BindingResult<String>

Unwrap a JACS-signed event, verifying the signature when the signer’s public key is known.

event_json is the signed event as a JSON string. server_keys_json is a JSON object mapping agent IDs to base64-encoded public key bytes: {"agent_id": "base64_key", ...}.

Returns a JSON string: {"data": <unwrapped>, "verified": <bool>}.

Trait Implementations

impl Clone for AgentWrapper

fn clone(&self) -> AgentWrapper

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for AgentWrapper

fn default() -> Self

Returns the “default value” for a type.