Struct Agent 

pub struct Agent {
    pub schema: Schema,
    pub config: Option<Config>,
    /* private fields */
}

Thread Safety

Agent is not internally synchronized by design. All mutable fields (value, id, version, keys, etc.) are unprotected because every production entry point wraps Agent in an external Mutex:

• SimpleAgent (simple/core.rs): agent: Mutex<Agent>
• AgentWrapper (binding-core): inner: Arc<Mutex<Agent>>
• FilesystemDocumentService: Arc<Mutex<Agent>>
• JacsMcpServer: Arc<AgentWrapper> (which holds Arc<Mutex<Agent>>)

Adding field-level synchronization (e.g., Arc<Mutex<Value>> on each field) would double-lock with the external Mutex, adding overhead without benefit. The one exception is document_schemas which uses Arc<Mutex<>> because it was designed for independent schema loading that can outlive a single lock scope.

If you use Agent directly (without SimpleAgent or AgentWrapper), you must provide your own synchronization.

Fields

schema: Schema

the JSONSchema used todo use getter

config: Option<Config>

use getter

Implementations

impl Agent

pub fn new( agentversion: &str, headerversion: &str, signature_version: &str, ) -> Result<Self, JacsError>

pub fn from_config( config: Config, password: Option<&str>, ) -> Result<Self, JacsError>

Create and load an agent from a pre-built Config and optional password.

This is the canonical one-call agent loading API. Callers compose their own config (via Config::from_file() + optional apply_env_overrides()) and pass the password directly – no env var side-channels needed.

Arguments

• config - A pre-built Config (not re-read from file)
• password - Optional private key password. If None, falls back to JACS_PRIVATE_KEY_PASSWORD env var inside keystore operations.

Example

let mut config = Config::from_file("jacs.config.json")?;
config.apply_env_overrides();
let agent = Agent::from_config(config, Some("my-password"))?;

pub fn ephemeral(algorithm: &str) -> Result<Self, JacsError>

Create an ephemeral agent with in-memory keys and storage. No config file, no directories, no environment variables needed.

pub fn is_ephemeral(&self) -> bool

Returns true if this is an ephemeral (in-memory) agent.

pub fn get_key_store(&self) -> Option<&dyn KeyStore>

Get a reference to the agent’s key store, if any.

pub fn key_paths(&self) -> Option<&KeyPaths>

Get the agent’s resolved key paths, if any.

pub fn set_key_paths(&mut self, paths: KeyPaths)

Set the agent’s key paths explicitly.

pub fn password(&self) -> Option<&str>

Get the agent-scoped password, if set.

pub fn set_password(&mut self, password: Option<String>)

Set the agent-scoped password.

pub fn resolve_password(&self) -> Result<String, JacsError>

Resolve the private key password using the agent-scoped password if available, falling back to env/jenv/keychain.

pub fn build_fs_store(&self) -> Result<FsEncryptedStore, JacsError>

Build an FsEncryptedStore from the agent’s key_paths and password.

pub fn set_dns_strict(&mut self, strict: bool)

pub fn set_dns_validate(&mut self, enabled: bool)

pub fn set_dns_required(&mut self, required: bool)

pub fn load_by_id(&mut self, lookup_id: String) -> Result<(), JacsError>

pub fn load_by_config(&mut self, path: String) -> Result<(), JacsError>

pub fn load_by_config_file_only( &mut self, path: String, ) -> Result<(), JacsError>

Load agent configuration from a file without applying env/jenv overrides.

This is the isolation-safe counterpart of load_by_config. It reads configuration exclusively from the specified file, ignoring any ambient JACS_* environment variables or jenv overrides. This eliminates the need for save/clear/restore guard patterns around the load call (Issue 008).

pub fn set_storage(&mut self, storage: MultiStorage)

let storage = MultiStorage::new(“memory”.to_string())?; agent.set_storage(storage);

pub fn storage_ref(&self) -> &MultiStorage

Returns a reference to the agent’s internal storage backend.

This is primarily used by service_from_agent to reuse the correctly-rooted MultiStorage that load_by_config set up, rather than creating a new one with a potentially-relative base directory.

pub fn set_storage_root(&mut self, root: PathBuf) -> Result<(), JacsError>

Replace the internal storage with one rooted at root.

This is used by verify_document_standalone so that absolute data/key directory paths work regardless of the current working directory. MultiStorage::clean_path strips leading slashes, turning absolute paths into paths relative to the FS store root. By rooting at / the resolved path is still correct.

pub fn ready(&self) -> bool

Returns true if the agent is fully initialized and ready for signing/verification.

Checks that all required state is present: ID, version, keys, config, and value.

pub fn get_value(&self) -> Option<&Value>

Get the agent’s JSON value

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

Get the agent’s key algorithm

pub fn set_keys( &mut self, private_key: Vec<u8>, public_key: Vec<u8>, key_algorithm: &str, ) -> Result<(), JacsError>

pub fn set_keys_raw( &mut self, private_key: Vec<u8>, public_key: Vec<u8>, key_algorithm: &str, )

Store keys without AES encryption. For ephemeral agents only. The raw private key bytes are wrapped in SecretBox directly.

pub fn get_private_key(&self) -> Result<&SecretPrivateKey, JacsError>

pub fn load(&mut self, agent_string: &str) -> Result<(), JacsError>

pub fn verify_self_signature(&mut self) -> Result<(), JacsError>

pub fn get_agent_for_doc( &mut self, document_key: String, signature_key_from: Option<&str>, ) -> Result<String, JacsError>

pub fn signature_verification_procedure( &self, json_value: &Value, fields: Option<&[String]>, signature_key_from: &str, public_key: Vec<u8>, public_key_enc_type: Option<String>, original_public_key_hash: Option<String>, signature: Option<String>, ) -> Result<(), JacsError>

pub fn signing_procedure( &mut self, json_value: &Value, fields: Option<&[String]>, placement_key: &str, ) -> Result<Value, JacsError>

Generates a signature JSON fragment for the specified JSON value.

This function takes a JSON value, an optional list of fields to include in the signature, and a placement key. It retrieves the values of the specified fields from the JSON value, signs them using the agent’s signing key, and returns a new JSON value containing the signature and related metadata.

If no fields are provided, the function will choose system default fields. Note that if the system default fields change, it could cause problems with signature verification.

Arguments

• json_value - A reference to the JSON value to be signed.
• fields - An optional reference to a vector of field names to include in the signature. If None, system default fields will be used.
• placement_key - A reference to a string representing the key where the signature should be placed in the resulting JSON value.

Returns

• Ok(Value) - A new JSON value containing the signature and related metadata.
• Err(JacsError) - An error occurred while generating the signature.

Errors

This function may return an error in the following cases:

• If the specified fields are not found in the JSON value.
• If an error occurs while signing the values.
• If an error occurs while serializing the accepted fields.
• If an error occurs while retrieving the agent’s public key.
• If an error occurs while validating the generated signature against the schema.

pub fn verify_hash(&self, doc: &Value) -> Result<bool, JacsError>

verify the hash of a complete document that has SHA256_FIELDNAME

pub fn verify_self_hash(&self) -> Result<bool, JacsError>

verify the hash where the document is the agent itself.

pub fn get_schema_keys(&mut self) -> Vec<String>

pub fn update_self( &mut self, new_agent_string: &str, ) -> Result<String, JacsError>

pass in modified agent’s JSON the function will replace it’s internal value after: versioning resigning rehashing

pub fn rotate_self( &mut self, algorithm_override: Option<&str>, ) -> Result<(String, Vec<u8>, Value), JacsError>

Rotates the agent’s keys and creates a new version of the agent document.

Unlike update_self which re-signs with the existing key, this method:

1. Archives old keys (filesystem) or discards them (ephemeral)
2. Generates a new keypair
3. Creates a new agent version
4. Signs the new document with the new key
5. Produces a jacsKeyRotationProof signed with the old key

Arguments

• algorithm_override - If Some, use this algorithm for the new keys instead of reading from config. The config’s jacs_agent_key_algorithm is also updated in memory.

Returns (new_version, new_public_key_bytes, signed_agent_json).

pub fn verify_transition_proof( proof: &Value, old_public_key_bytes: &[u8], ) -> Result<(), JacsError>

Verify a jacsKeyRotationProof using the old public key.

The proof contains a transitionMessage signed with the old key. This function re-derives the expected message from the proof’s metadata and checks the cryptographic signature against old_public_key_bytes.

Returns Ok(()) if the proof is valid, or Err if verification fails.

pub fn validate_header(&mut self, json: &str) -> Result<Value, JacsError>

pub fn validate_agent(&mut self, json: &str) -> Result<Value, JacsError>

pub fn load_custom_schemas( &mut self, schema_paths: &[String], ) -> Result<(), String>

pub fn save(&self) -> Result<String, JacsError>

pub fn create_agent_and_load( &mut self, json: &str, create_keys: bool, _create_keys_algorithm: Option<&str>, ) -> Result<Value, JacsError>

create an agent, and provde id and version as a result

pub fn sign_config(&mut self, config_json: &Value) -> Result<Value, JacsError>

Sign a config JSON value, producing a JACS document with header fields.

Uses Schema::create for initial ID/version assignment. The resulting JSON has jacsType: "config", jacsLevel: "config", a jacsSignature, and jacsSha256.

pub fn verify_config(&mut self, config_json: &Value) -> Result<(), JacsError>

Verify a previously signed config document: schema + hash + signature.

This mirrors the same checks that SimpleAgent::verify() performs:

1. validate_header — schema validation + verify_hash
2. signature_verification_procedure — cryptographic signature check

pub fn update_config(&mut self, config_json: &Value) -> Result<Value, JacsError>

Update and re-sign an existing signed config document.

Bumps jacsVersion, sets jacsPreviousVersion, re-signs and re-hashes. jacsId is preserved.

pub fn builder() -> AgentBuilder

Returns an AgentBuilder for constructing an Agent with a fluent API.

Example

use jacs::agent::Agent;

// Build an agent with default v1 versions
let agent = Agent::builder().build()?;

// Build an agent with custom configuration
let agent = Agent::builder()
    .config_path("path/to/jacs.config.json")
    .dns_strict(true)
    .build()?;

// Build an agent with explicit versions
let agent = Agent::builder()
    .agent_version("v1")
    .header_version("v1")
    .signature_version("v1")
    .build()?;

pub fn verify_batch( &self, items: &[(String, String, Vec<u8>, Option<String>)], ) -> Vec<Result<(), JacsError>>

Verifies multiple signatures in a batch operation.

This method processes each verification sequentially. For CPU-bound signature verification, this is often efficient due to the cryptographic operations being compute-intensive. If parallel verification is needed, consider using rayon’s par_iter() on the input slice externally.

Arguments

• items - A slice of tuples containing:
  • data: The string data that was signed
  • signature: The base64-encoded signature
  • public_key: The public key bytes for verification
  • algorithm: Optional algorithm hint (e.g., “ring-Ed25519”, “RSA-PSS”)

Returns

A vector of Result<(), JacsError> in the same order as the input items.

• Ok(()) indicates the signature is valid
• Err(JacsError) indicates verification failed with a specific reason

Example

use jacs::agent::Agent;

let agent = Agent::builder().build()?;

let items = vec![
    ("message1".to_string(), sig1, pk1.clone(), None),
    ("message2".to_string(), sig2, pk2.clone(), Some("ring-Ed25519".to_string())),
];

let results = agent.verify_batch(&items);
for (i, result) in results.iter().enumerate() {
    match result {
        Ok(()) => println!("Item {} verified successfully", i),
        Err(e) => println!("Item {} failed: {}", i, e),
    }
}

Performance Notes

• Verification is sequential; for parallel verification, use rayon externally
• Each verification is independent and does not short-circuit on failure
• The method returns all results even if some verifications fail

impl Agent

pub fn sign_bytes(&mut self, data: &[u8]) -> Result<Vec<u8>, JacsError>

Sign raw bytes and return the base64-encoded signature.

This is the byte-level equivalent of sign_string. Used by the email signing module where the payload is binary.

pub fn generate_keys_with_store( &mut self, ks: &dyn KeyStore, ) -> Result<(), JacsError>

Generate keys using a specific KeyStore implementation. For ephemeral agents, uses set_keys_raw (no AES encryption). For persistent agents, uses set_keys (AES-encrypts private key).

Trait Implementations

impl Agreement for Agent

fn remove_agents_from_agreement( &mut self, document_key: &str, agentids: &[String], agreement_fieldname: Option<String>, ) -> Result<JACSDocument, JacsError>

TODO also remove their signature

fn agreement_get_question_and_context( &self, document_key: &str, agreement_fieldname: Option<String>, ) -> Result<(String, String), JacsError>

get human readable fields

fn check_agreement( &self, document_key: &str, agreement_fieldname: Option<String>, ) -> Result<String, JacsError>

checking agreements requires you have the public key of each signatory if the document hashes don’t match or there are unsigned, it will fail

Enforces optional agreement constraints:

• timeout: if set and expired, returns an error
• quorum: if set, only quorum signatures are required (M-of-N)
• requiredAlgorithms: if set, rejects signatures not using a listed algorithm
• minimumStrength: if set, rejects signatures below the strength tier

fn agreement_hash( &self, value: Value, agreement_fieldname: &str, ) -> Result<String, JacsError>

agreements update documents however this updates the document, which updates, version, lastversion and version date the agreement itself needs it’s own hash to track on a subset of fields the standard hash detects any changes at all

fn trim_fields_for_hashing_and_signing( &self, value: Value, agreement_fieldname: &str, ) -> Result<(String, Vec<String>), JacsError>

remove fields that should not be used for agreement signature

fn create_agreement( &mut self, document_key: &str, agentids: &[String], question: Option<&str>, context: Option<&str>, agreement_fieldname: Option<String>, ) -> Result<JACSDocument, JacsError>

given a document id and a list of agents, return an updated document with an agreement field fails if an agreement field exists no other fields can be modified or the agreement fails overwrites previous agreements

fn create_agreement_with_options( &mut self, document_key: &str, agentids: &[String], question: Option<&str>, context: Option<&str>, agreement_fieldname: Option<String>, options: &AgreementOptions, ) -> Result<JACSDocument, JacsError>

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

fn add_agents_to_agreement( &mut self, document_key: &str, agentids: &[String], agreement_fieldname: Option<String>, ) -> Result<JACSDocument, JacsError>

given a document id and a list of agents, return an updated document

fn sign_agreement( &mut self, document_key: &str, agreement_fieldname: Option<String>, ) -> Result<JACSDocument, JacsError>

given a document id sign a document, return an updated document

impl BoilerPlate for Agent

fn get_lookup_id(&self) -> Result<String, JacsError>

combination of id and value

fn get_id(&self) -> Result<String, JacsError>

fn get_public_key(&self) -> Result<Vec<u8>, JacsError>

fn get_version(&self) -> Result<String, JacsError>

fn as_string(&self) -> Result<String, JacsError>

impl Debug for Agent

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Agent

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl DocumentTraits for Agent

fn create_document_and_load( &mut self, json: &str, attachments: Option<Vec<String>>, embed: Option<bool>, ) -> Result<JACSDocument, JacsError>

create an document, and provde id and version as a result filepaths:

fn update_document( &mut self, document_key: &str, new_document_string: &str, attachments: Option<Vec<String>>, embed: Option<bool>, ) -> Result<JACSDocument, JacsError>

pass in modified doc the original document needs to be marked as obsolete but this means not a deletion, but a move of the file

fn copy_document( &mut self, document_key: &str, ) -> Result<JACSDocument, JacsError>

copys document without modifications

fn diff_json_strings( &self, json1: &str, json2: &str, ) -> Result<(String, String), JacsError>

Function to diff two JSON strings and print the differences.

fn validate_document_with_custom_schema( &self, schema_path: &str, json: &Value, ) -> Result<(), String>

fn create_file_json( &mut self, filepath: &str, embed: bool, ) -> Result<Value, JacsError>

fn verify_document_files(&mut self, document: &Value) -> Result<(), JacsError>

fn load_document( &mut self, document_string: &str, ) -> Result<JACSDocument, JacsError>

fn load_all( &mut self, store: bool, load_only_recent: bool, ) -> Result<Vec<JACSDocument>, Vec<JacsError>>

fn hash_doc(&self, doc: &Value) -> Result<String, JacsError>

fn store_jacs_document( &mut self, value: &Value, ) -> Result<JACSDocument, JacsError>

fn get_document(&self, document_key: &str) -> Result<JACSDocument, JacsError>

fn remove_document( &mut self, document_key: &str, ) -> Result<JACSDocument, JacsError>

fn get_document_keys(&mut self) -> Vec<String>

fn archive_old_version( &mut self, original_document: &JACSDocument, ) -> Result<(), JacsError>

fn save_document( &mut self, document_key: &str, output_filename: Option<String>, export_embedded: Option<bool>, extract_only: Option<bool>, ) -> Result<(), JacsError>

export_embedded if there is embedded files recreate them, default false

fn verify_external_document_signature( &mut self, document_key: &str, ) -> Result<(), JacsError>

fn get_document_signature_agent_id( &mut self, document_key: &str, ) -> Result<String, JacsError>

fn get_document_signature_date( &mut self, document_key: &str, ) -> Result<String, JacsError>

fn verify_document_signature( &mut self, document_key: &str, signature_key_from: Option<&str>, fields: Option<&[String]>, public_key: Option<Vec<u8>>, public_key_enc_type: Option<String>, ) -> Result<(), JacsError>

fn parse_attachement_arg( &mut self, attachments: Option<&str>, ) -> Option<Vec<String>>

util function for parsing arguments for attachments

fn diff_strings( &self, string_one: &str, string_two: &str, ) -> (String, String, String)

fn create_documents_batch( &mut self, documents: &[&str], ) -> Result<Vec<JACSDocument>, JacsError>

Creates and signs multiple documents in a batch operation.

impl FileLoader for Agent

Available on non-WebAssembly only.

fn fs_load_public_key(&self, hash: &str) -> Result<Vec<u8>, JacsError>

in JACS the public keys need to be added manually

fn fs_save_remote_public_key( &self, agent_id_and_version: &str, public_key: &[u8], public_key_enc_type: &[u8], ) -> Result<(), JacsError>

in JACS the public keys need to be added manually

fn fs_preload_keys( &mut self, private_key_filename: &str, public_key_filename: &str, custom_key_algorithm: Option<String>, ) -> Result<(), JacsError>

a way to load keys that aren’t default

fn fs_docs_load_all(&mut self) -> Result<Vec<String>, Vec<JacsError>>

function used to load all documents present

fn create_backup(&self, file_path: &str) -> Result<String, JacsError>

private Helper function to create a backup file name based on the current timestamp

fn use_filesystem(&self) -> bool

fn fs_save_keys(&mut self) -> Result<(), JacsError>

fn fs_load_keys(&mut self) -> Result<(), JacsError>

fn fs_load_public_key_type(&self, hash: &str) -> Result<String, JacsError>

fn fs_agent_load(&self, agentid: &str) -> Result<String, JacsError>

fn fs_agent_save( &self, agentid: &str, agent_string: &str, ) -> Result<String, JacsError>

fn fs_document_archive(&self, lookup_key: &str) -> Result<(), JacsError>

fn fs_document_save( &self, document_id: &str, document_string: &str, output_filename: Option<String>, ) -> Result<String, JacsError>

fn fs_get_document_content( &self, document_filepath: String, ) -> Result<String, JacsError>

used to get base64 content from a filepath

fn load_public_key_file(&self, filename: &str) -> Result<Vec<u8>, JacsError>

fn load_private_key(&self, filename: &str) -> Result<Vec<u8>, JacsError>

fn save_private_key( &self, full_filepath: &str, private_key: &[u8], ) -> Result<String, JacsError>

fn make_data_directory_path(&self, filename: &str) -> Result<String, JacsError>

fn make_key_directory_path(&self, filename: &str) -> Result<String, JacsError>

impl KeyManager for Agent

fn generate_keys(&mut self) -> Result<(), JacsError>

this necessatates updateding the version of the agent

fn sign_string(&mut self, data: &str) -> Result<String, JacsError>

fn sign_batch(&mut self, messages: &[&str]) -> Result<Vec<String>, JacsError>

Signs multiple strings in a batch operation.

fn verify_string( &self, data: &str, signature_base64: &str, public_key: Vec<u8>, public_key_enc_type: Option<String>, ) -> Result<(), JacsError>

impl PayloadTraits for Agent

fn sign_payload(&mut self, jacs_payload: Value) -> Result<String, JacsError>

fn verify_payload( &mut self, document_string: String, max_replay_time_delta: Option<u64>, ) -> Result<Value, JacsError>

fn verify_payload_with_agent_id( &mut self, document_string: String, max_replay_time_delta_seconds: Option<u64>, ) -> Result<(Value, String), JacsError>

impl SecurityTraits for Agent

fn check_data_directory(&self) -> Result<(), JacsError>

this function attempts to detect executable files if they should be there alert the user /// it will move all exuctable documents in JACS_DATA_DIRECTORY a quarantine directory

fn use_security(&self) -> bool

determine if the system is configured ot use security features EXPERIMENTAL

fn use_fs_security(&self) -> bool

fn mark_file_not_executable(&self, path: &Path) -> Result<(), JacsError>

fn is_executable(&self, path: &Path) -> bool

fn quarantine_file(&self, file_path: &Path) -> Result<(), JacsError>