OpenAgentID documentation
Source referencesRust module referenceoas-crypto

oas-crypto · proof

Declared module signatures, types, configuration, and source documentation.

Source: oas/oas/oas-crypto/src/proof.rs. SHA-256: bbcf0d5c349f02b368d9f599469e1312b3b9343941aae04f1def95045af08434.

This source reference follows declared modules and preserves feature attributes. It includes public declarations and implementation methods in those modules. Private-module exports and trait resolution still require the compiler; not every declaration is a crate-root import. Function bodies and constant values are omitted. Source comments describe their implementation context and are not a production deployment claim.

proof::PROOF_TYPE

The fixed proof type identifier per OAS Specification §9.1.

pub const PROOF_TYPE: &str;

Source line: 19.

proof::PROOF_ALGORITHM

The fixed algorithm identifier per OAS Specification §9.2.

pub const PROOF_ALGORITHM: &str;

Source line: 22.

proof::PROOF_CANONICALIZATION

The only canonicalization profile accepted for authorizing lineage proofs.

pub const PROOF_CANONICALIZATION: &str;

Source line: 25.

proof::PROOF_PURPOSE

The verification relationship required for lineage authorization.

pub const PROOF_PURPOSE: &str;

Source line: 28.

proof::LineageProofBinding

Security bindings required when issuing an authorizing lineage proof.

The proof signs every field in this structure as well as the proof type, algorithm, canonicalization profile, proof purpose, and parent public key.

#[derive(Debug, Clone, Copy)]
pub struct LineageProofBinding<'a> {
/// DID of the parent authorizing the child.

pub parent_did: &'a str,
/// DID of the child receiving authorization.

pub child_did: &'a str,
/// Stable derivation or authorization path.

pub derivation_path: &'a str,
/// Parent verification method authorized for capability delegation.

pub verification_method: &'a str,
/// Child verification method committed by the parent.

pub child_verification_method: &'a str,
/// Child public key committed by the parent.

pub child_public_key_multibase: &'a str,
/// BLAKE3 digest of the complete authenticated parent DID document.

pub parent_document_digest: &'a str,
/// Monotonic sequence of the authenticated parent DID document.

pub parent_document_sequence: u64,
/// Child position in the complete root-to-child chain.

pub generation: u32
}

Source line: 35.

proof::AgentLineageProof

An AgentLineageProof2025 linking a child entity to its parent.

This proof establishes cryptographic accountability by demonstrating that the parent entity authorized the creation of the child entity.

See OAS Specification §9 for the complete proof format.

Examples

use oas_crypto::proof::{AgentLineageProof, LineageProofBinding};
use oas_crypto::keypair::OasKeyPair;

let parent = OasKeyPair::generate();
let child = OasKeyPair::generate();
let proof = AgentLineageProof::generate_bound(
    &parent,
    &LineageProofBinding {
        parent_did: "did:oas:test:hmr:parent",
        child_did: "did:oas:test:agent:child",
        derivation_path: "/agent-child",
        verification_method: "did:oas:test:hmr:parent#key-1",
        child_verification_method: "did:oas:test:agent:child#key-1",
        child_public_key_multibase: &child.public_key_multibase(),
        parent_document_digest: "blake3:abababababababababababababababababababababababababababababababab",
        parent_document_sequence: 1,
        generation: 1,
    },
).unwrap();

assert!(proof.verify_with_key(&parent.verifying_key_bytes()).is_ok());
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct AgentLineageProof {
/// Fixed: `"AgentLineageProof2025"`

#[serde(rename = "type")]
pub proof_type: String,
/// DID of the parent entity.

pub parent_did: String,
/// DID of the child entity.

pub child_did: String,
/// The HKDF info parameter used for key derivation (e.g., `"/agent-child"`).

pub derivation_path: String,
/// Fixed: `"HKDF-SHA256-Ed25519"`

pub algorithm: String,
/// Parent's public key, multibase-encoded (base58btc with `z` prefix).

pub public_key_multibase: String,
/// Parent verification method selected from the authenticated parent document.

#[serde(default, skip_serializing_if = "Option::is_none")]
pub verification_method: Option<String>,
/// Verification relationship authorizing the parent key for lineage.

#[serde(default, skip_serializing_if = "Option::is_none")]
pub proof_purpose: Option<String>,
/// Canonicalization profile used to construct the signed payload.

#[serde(default, skip_serializing_if = "Option::is_none")]
pub canonicalization: Option<String>,
/// Child verification method committed by the parent.

#[serde(default, skip_serializing_if = "Option::is_none")]
pub child_verification_method: Option<String>,
/// Child public key committed by the parent.

#[serde(default, skip_serializing_if = "Option::is_none")]
pub child_public_key_multibase: Option<String>,
/// Digest of the authenticated parent document used for issuance.

#[serde(default, skip_serializing_if = "Option::is_none")]
pub parent_document_digest: Option<String>,
/// Sequence of the authenticated parent document used for issuance.

#[serde(default, skip_serializing_if = "Option::is_none")]
pub parent_document_sequence: Option<u64>,
/// Position of the child in the complete lineage chain.

#[serde(default, skip_serializing_if = "Option::is_none")]
pub generation: Option<u32>,
/// Ed25519 signature by the parent key over the canonical proof payload,

/// encoded as base64url.

pub signature: String
}

Source line: 90.

proof::AgentLineageProof::generate

Generates a legacy, non-authorizing AgentLineageProof2025.

Implements OAS Specification §9.4:

  1. Construct the canonical proof payload via JCS
  2. Sign the payload with the parent's Ed25519 signing key
  3. Encode the signature as base64url

Arguments

  • parent_keypair - The parent entity's keypair (used for signing).
  • parent_did - The parent entity's DID string.
  • child_did - The child entity's DID string.
  • derivation_path - The HKDF derivation path.

Returns

A parseable migration proof that strict verification rejects with [CryptoError::LegacyInsecureProof].

Errors

Returns [CryptoError::CanonicalizationFailed] if JCS canonicalization fails.

Examples

use oas_crypto::proof::AgentLineageProof;
use oas_crypto::keypair::OasKeyPair;

let parent = OasKeyPair::generate();
let proof = AgentLineageProof::generate(
    &parent,
    "did:oas:ns:hmr:alice",
    "did:oas:ns:agent:bot",
    "/agent-bot",
).unwrap();
assert_eq!(proof.proof_type, "AgentLineageProof2025");
assert!(matches!(
    proof.verify(),
    Err(oas_crypto::CryptoError::LegacyInsecureProof { .. })
));
pub fn generate(
        parent_keypair: &OasKeyPair,
        parent_did: &str,
        child_did: &str,
        derivation_path: &str,
    ) -> Result<Self, CryptoError>;

Source line: 190.

proof::AgentLineageProof::generate_bound

Generates a fully bound authorizing lineage proof.

The signature commits to both DIDs, both verification methods and public keys, the authenticated parent document state, suite and proof purpose, canonicalization profile, path, and chain position.

Arguments

  • parent_keypair - Parent signing key authorized by the parent document.
  • binding - Security-relevant fields committed by the signature.

Returns

A fully bound [AgentLineageProof].

Errors

Returns [CryptoError::InvalidProofPayload] for malformed fields or a canonicalization error if JCS encoding fails.

pub fn generate_bound(
        parent_keypair: &OasKeyPair,
        binding: &LineageProofBinding<'_>,
    ) -> Result<Self, CryptoError>;

Source line: 237.

proof::AgentLineageProof::verify

Rejects standalone verification without an external trust decision.

Returns

This method never returns Ok(()). Authorizing verification requires [Self::verify_with_key] with a key obtained from a validated parent DID document or explicit verifier trust policy.

Errors

Returns [CryptoError::LegacyInsecureProof] for an unbound legacy proof, or [CryptoError::VerifierTrustRequired] for a fully bound proof.

pub fn verify(&self) -> Result<(), CryptoError>;

Source line: 277.

proof::AgentLineageProof::verify_with_key

Verifies this proof against a specific public key (not the embedded one).

Use this when you have already resolved the parent document and want to verify the proof against the known parent public key.

Arguments

  • parent_public_key_bytes - The 32-byte Ed25519 public key of the parent.

Returns

Ok(()) if the proof is valid against the provided key.

Errors

Returns an error if the proof is legacy, its suite or bindings are unsupported, the embedded parent key disagrees with the trusted key, or signature verification fails.

pub fn verify_with_key(&self, parent_public_key_bytes: &[u8]) -> Result<(), CryptoError>;

Source line: 300.

proof::AgentLineageProof::validate_security_profile

Validates mandatory authorizing fields and fixed suite values.

Errors

Returns a typed profile, suite, purpose, key encoding, or legacy error.

pub fn validate_security_profile(&self) -> Result<(), CryptoError>;

Source line: 326.

proof::canonical_proof_payload

Constructs deterministic RFC 8785 bytes for a fully bound proof.

Every representable security-relevant field except the signature itself is included. Legacy proofs therefore cannot produce authorizing canonical bytes through this function.

Arguments

  • proof - Fully bound proof whose signature payload is required.

Returns

Deterministic JCS UTF-8 bytes.

Errors

Returns a typed profile or canonicalization error.

pub fn canonical_proof_payload(proof: &AgentLineageProof) -> Result<Vec<u8>, CryptoError>;

Source line: 413.

oas-crypto · keypair

Declared module signatures, types, configuration, and source documentation.

oas-did modules

Public source declarations across the declared module tree.

On this page

proof::PROOF_TYPEproof::PROOF_ALGORITHMproof::PROOF_CANONICALIZATIONproof::PROOF_PURPOSEproof::LineageProofBindingproof::AgentLineageProofExamplesproof::AgentLineageProof::generateArgumentsReturnsErrorsExamplesproof::AgentLineageProof::generate_boundArgumentsReturnsErrorsproof::AgentLineageProof::verifyReturnsErrorsproof::AgentLineageProof::verify_with_keyArgumentsReturnsErrorsproof::AgentLineageProof::validate_security_profileErrorsproof::canonical_proof_payloadArgumentsReturnsErrors