Struct CoreAgent 

pub struct CoreAgent { /* private fields */ }

In-memory agent holding the optional unlocked signer + the published public key + the embedded agent JSON.

CoreAgent is constructed by either:

• CoreAgent::from_encrypted_material — production path, takes an AgentMaterial and an UnlockSecret.
• CoreAgent::ephemeral — testing / one-off path, generates a fresh keypair and synthesizes a minimal agent JSON.

Signing and verification methods are added in Task 013 and live in the verify module + an extended impl block.

Implementations

impl CoreAgent

pub fn from_encrypted_material( material: AgentMaterial, secret: UnlockSecret<'_>, ) -> Result<Self, CoreError>

Construct from encrypted material plus an unlock secret.

Password runs the envelope through the V2/legacy sniffer in envelope::decrypt_private_key. RawPrivateKey takes the bytes as-is.

Errors mirror the underlying primitives: InvalidPassword, MalformedEnvelope, MalformedKey, UnsupportedAlgorithm.

pub fn ephemeral(algorithm: SigningAlgorithm) -> Result<Self, CoreError>

Generate a fresh ephemeral agent for the given algorithm. Synthesizes a minimal agent JSON via ephemeral_agent_json so the result looks like an agent for downstream sign / verify code paths (Task 013) without taking a dependency on the full native agent loader.

pub fn algorithm(&self) -> SigningAlgorithm

The signing algorithm of this agent.

pub fn public_key(&self) -> &[u8]

Raw public-key bytes. Survives clear_secrets — verification with this agent still works after the private key is dropped.

pub fn is_unlocked(&self) -> bool

true iff a signer is currently held (a private key is unlocked).

pub fn clear_secrets(&mut self)

Idempotent secret eviction. After this call:

• is_unlocked() returns false.
• sign_message (Task 013) returns CoreError::Locked.
• public_key, algorithm, verify, verify_with_key continue to work.

pub fn export_agent(&self) -> Value

Borrow a clone of the embedded agent JSON. Used by callers (browser or native facade) that want to re-emit the agent record without taking ownership of the CoreAgent.

pub fn export_encrypted_material( &self, password: &str, ) -> Result<AgentMaterial, CoreError>

Round-trip the unlocked agent into an AgentMaterial whose encrypted_private_key is encrypted under password with the V2 Argon2id envelope (envelope::encrypt_private_key).

The result is the same shape from_encrypted_material accepts — the wasm browser layer round-trips through this method to implement BrowserAgent.save(storageKey) / load(storageKey, {password}) (HAIAI_WASM Issue 003) without any local crypto in the wrapper.

Returns CoreError::Locked if the signer has been cleared, or the underlying EncryptionFailed if envelope encryption fails.

pub fn sign_message(&mut self, data: &Value) -> Result<Value, CoreError>

Sign a JSON payload as a JACS message and return the signed document. Shape:

{
  "jacsType": "message",
  "jacsLevel": "raw",
  "content": { ... },
  "jacsSignature": { ... }
}

The canonical signature payload is built per PRD §4.5 (v2 layout, serde_json_canonicalizer for canonical JSON). The signer must be unlocked; otherwise returns CoreError::Locked.

pub fn sign_document_inplace( &mut self, document: &mut Value, placement_key: &str, ) -> Result<(), CoreError>

Sign document in place, attaching the signature object under placement_key. Used by sign_message (placement key "jacsSignature") and by jacs-core::agreements in Task 014.

Returns CoreError::Locked if the signer has been cleared.

pub fn sign_raw_bytes(&self, bytes: &[u8]) -> Result<Vec<u8>, CoreError>

Sign exact bytes with the unlocked signer and return the raw signature bytes. No JSON wrapping, no canonicalization, no metadata — the caller decides what bytes are signed.

Use this for protocol primitives where the verifier reconstructs the exact same byte string from independent inputs (auth headers, nonce-bound challenges, JWT-style payloads). For JACS document signing, use sign_message / sign_document_inplace instead so the verifier can reproduce the canonical payload from the document’s published fields.

Returns CoreError::Locked if clear_secrets has been called.

pub fn verify_raw_bytes_with_key( public_key: &[u8], algorithm: SigningAlgorithm, bytes: &[u8], signature: &[u8], ) -> Result<bool, CoreError>

Static verify path for sign_raw_bytes output. Returns Ok(true) when the signature matches, Ok(false) when it does not, and Err(CoreError::UnsupportedAlgorithm) / MalformedKey / MalformedDocument if the inputs are structurally invalid.

Mirrors verify_with_key for document signing — the verifier does not need an unlocked agent because it only requires the public key bytes + algorithm.

pub fn verify(&self, signed: &Value) -> Result<VerificationOutcome, CoreError>

Verify a signed JACS document against this agent’s public key + algorithm. Always uses the jacsSignature placement key.

Returns CoreError::AlgorithmMismatch if the document was signed under a different algorithm than this agent. Returns a VerificationOutcome with valid = false and one entry in errors when the signature itself does not verify.

pub fn verify_with_key( signed: &Value, public_key: &[u8], algorithm: SigningAlgorithm, ) -> Result<VerificationOutcome, CoreError>

Static verify path — does not require an unlocked agent.

public_key and algorithm must match what the document was signed under; otherwise the cryptographic check fails and the returned outcome has valid = false. The signed document’s signingAlgorithm field is checked against algorithm and returns CoreError::AlgorithmMismatch on conflict — this is a typed failure (algorithm choice errors are different from bad signatures).

Trait Implementations

impl Debug for CoreAgent

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

Formats the value using the given formatter.