Struct SimpleAgentWrapper 

pub struct SimpleAgentWrapper { /* private fields */ }

Thread-safe, Clone-able FFI wrapper around the narrow SimpleAgent contract.

All methods return BindingResult<String> (or simple scalars) so that language bindings (Python/PyO3, Node/NAPI, Go/CGo) never touch Rust-only types.

Implementations

impl SimpleAgentWrapper

pub fn create( name: &str, purpose: Option<&str>, key_algorithm: Option<&str>, ) -> BindingResult<(Self, String)>

Create a new agent with persistent identity.

Returns (wrapper, info_json) where info_json is a serialized jacs::simple::AgentInfo.

pub fn load( config_path: Option<&str>, strict: Option<bool>, ) -> BindingResult<Self>

Load an existing agent from a config file.

pub fn load_with_info( config_path: Option<&str>, strict: Option<bool>, ) -> BindingResult<(Self, String)>

Load an existing agent from a config file and return canonical metadata.

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

Create an ephemeral (in-memory, throwaway) agent.

Returns (wrapper, info_json).

pub fn create_with_params(params_json: &str) -> BindingResult<(Self, String)>

Create an agent with full programmatic control via JSON parameters.

params_json is a JSON string of [CreateAgentParams] fields. The storage field is skipped during deserialization (use builder for that). Returns (wrapper, info_json) where info_json is a serialized jacs::simple::AgentInfo.

pub fn from_agent(agent: SimpleAgent) -> Self

Wrap an existing SimpleAgent in a SimpleAgentWrapper.

pub fn inner_ref(&self) -> &SimpleAgent

Get a reference to the inner SimpleAgent.

This is intended for advanced operations (attestation, reencrypt, etc.) that need direct access to the underlying agent. Language bindings should prefer the wrapper methods for the narrow contract.

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

Get the agent’s unique ID.

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

Get the JACS key ID (signing key identifier).

pub fn is_strict(&self) -> bool

Whether the agent is in strict mode.

pub fn config_path(&self) -> Option<String>

Config file path, if loaded from disk.

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

Export the agent’s identity JSON for P2P exchange.

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

Get the public key as a PEM string.

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

Get the public key as base64-encoded raw bytes (FFI-safe).

pub fn diagnostics(&self) -> String

Runtime diagnostic info as a JSON string.

pub fn export_w3c_did(&self, origin: Option<&str>) -> BindingResult<String>

Export this agent’s did:wba identifier.

pub fn export_w3c_did_document_json( &self, origin: Option<&str>, ) -> BindingResult<String>

Export this agent’s did:wba DID document as JSON.

pub fn export_w3c_agent_description_json( &self, origin: Option<&str>, ) -> BindingResult<String>

Export this agent’s W3C agent description as JSON.

pub fn generate_w3c_well_known_json( &self, origin: Option<&str>, ) -> BindingResult<String>

Generate W3C well-known discovery documents as a JSON object keyed by path.

pub fn sign_w3c_request_json(&self, params_json: &str) -> BindingResult<String>

Sign a request-bound DID authentication proof.

params_json is a JSON string of W3cRequestProofParams.

pub fn verify_w3c_request_json( &self, proof_json: &str, did_document_json: &str, body: Option<&str>, max_age_seconds: u64, expected_method: Option<&str>, expected_url: Option<&str>, ) -> BindingResult<String>

Verify a request-bound DID authentication proof.

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

Verify the agent’s own document signature. Returns JSON VerificationResult.

pub fn verify_json(&self, signed_document: &str) -> BindingResult<String>

Verify a signed document JSON string. Returns JSON VerificationResult.

pub fn verify_with_key_json( &self, signed_document: &str, public_key_base64: &str, ) -> BindingResult<String>

Verify a signed document with an explicit public key (base64-encoded). Returns JSON VerificationResult.

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

Verify a stored document by its ID (e.g., “uuid:version”). Returns JSON VerificationResult.

pub fn sign_message_json(&self, data_json: &str) -> BindingResult<String>

Sign a JSON message string. Returns the signed JACS document JSON.

pub fn sign_raw_bytes_base64(&self, data: &[u8]) -> BindingResult<String>

Sign raw bytes and return the signature as base64 (FFI-safe).

pub fn sign_file_json( &self, file_path: &str, embed: bool, ) -> BindingResult<String>

Sign a file with optional content embedding. Returns the signed JACS document JSON.

pub fn to_yaml(&self, json_str: &str) -> BindingResult<String>

Convert a JSON string to YAML.

pub fn from_yaml(&self, yaml_str: &str) -> BindingResult<String>

Convert a YAML string to pretty-printed JSON.

pub fn to_html(&self, json_str: &str) -> BindingResult<String>

Convert a JSON string to a self-contained HTML document.

pub fn from_html(&self, html_str: &str) -> BindingResult<String>

Extract JSON from an HTML document produced by to_html.

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

Rotate the agent’s cryptographic keys.

Optionally change the signing algorithm. Returns a JSON string of the RotationResult (jacs_id, old_version, new_version, key hash, proof).

pub fn sign_text_file_json( &self, path: &str, opts_json: &str, ) -> BindingResult<String>

Sign a text / markdown file in-place. PRD §4.1.

opts_json accepts:

• "" | "null" | "{}" — defaults (backup: true, allow_duplicate: false).
• {"backup": false} — disable .bak.
• {"allow_duplicate": true} — allow duplicate-signer no-op to still write.

Returns a JSON string of jacs::simple::types::SignTextOutcome.

pub fn verify_text_file_json( &self, path: &str, opts_json: &str, ) -> BindingResult<String>

Verify a signed text file. PRD §4.1, §4.1.5.

opts_json accepts:

• "" | "null" | "{}" — strict=false, key_dir=None (permissive).
• {"strict": true} — strict mode (missing-signature returns Err).
• {"keyDir": "/abs/path"} — --key-dir override.
• {"strict": true, "keyDir": "..."} — both.

Permissive returns JSON with a status discriminator. Strict mode on an unsigned file returns Err(BindingCoreError::missing_signature(path)).

pub fn sign_image_json( &self, in_path: &str, out_path: &str, opts_json: &str, ) -> BindingResult<String>

Sign an image (PNG/JPEG/WebP). PRD §4.2.

opts_json accepts (all keys optional):

• {"robust": bool} — enable LSB embedding (PNG/JPEG only).
• {"refuseOverwrite": bool} — refuse if input already signed.
• {"backup": bool} — auto-backup before in-place writes (default true).
• {"unsafeBakMode": 0o644} — override the default 0o600 backup mode.

pub fn verify_image_json( &self, path: &str, opts_json: &str, ) -> BindingResult<String>

Verify an image signature. PRD §4.2.

opts_json accepts:

• {"strict": bool} — strict-mode missing-signature is an error.
• {"keyDir": "/abs/path"} — --key-dir override.
• {"robust": bool} — scan LSB channel as a fallback (default false).

pub fn extract_media_signature_json( &self, path: &str, opts_json: &str, ) -> BindingResult<String>

Extract the JACS signature payload from an image. PRD §3.2.

opts_json accepts:

• {"rawPayload": bool} (default false = decoded JSON)
• {"scanRobust": bool} / {"scan_robust": bool} (R-011, default false). When true, fall back to LSB scan if the metadata channel has no payload — mirrors verify_image --robust (PRD §4.2.4).

Returns a JSON envelope { "present": bool, "payload": string | null }.

Trait Implementations

impl Clone for SimpleAgentWrapper

fn clone(&self) -> SimpleAgentWrapper

Returns a duplicate of the value.

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

Performs copy-assignment from source.