oas-sdk · lineage
Declared module signatures, types, configuration, and source documentation.
Source: oas/oas/oas-sdk/src/lineage.rs. SHA-256: dfb1c98b450d92cbca537fbbb0b1c744efda2674b3b83ba27dafa2ae5557a988.
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.
lineage::DerivedIdentity
The result of deriving a child entity.
Contains the signed child identity document and the derived keypair.
#[derive(Debug)]
pub struct DerivedIdentity {
/// The signed child OAS Identity Document (with lineage section).
pub document: OasDocument,
/// The derived Ed25519 keypair for this child entity.
pub keypair: OasKeyPair
}Source line: 22.
lineage::AuthorityPathKind
A required privileged authority path shape.
OAS keeps this intentionally small and stringly-extensible so downstream systems can add product-specific paths without forking lineage semantics.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum AuthorityPathKind {
/// Human root delegates authority to an agent.
HumanToAgent,
/// Agent acts on behalf of an organization.
AgentToOrg,
/// Organization delegates authority to an agent.
OrgToAgent,
/// Agent acts toward a human subject.
AgentToHuman,
/// Deployment-specific path kind.
Custom(String),
}Source line: 34.
lineage::AuthorityPathKind::as_str
Stable wire label for this path kind.
pub fn as_str(&self) -> &str;Source line: 49.
lineage::LineageAuthorityRequest
Request passed from OAS into a Sigil-backed lineage authority source.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct LineageAuthorityRequest {
/// DID whose authority is being checked.
pub subject_did: String,
/// Root DID proven by portable/local lineage verification.
pub local_root_did: String,
/// Local chain as declared by the document, ordered root to subject when known.
pub local_chain: Vec<String>,
/// Required privileged path kind.
pub path_kind: AuthorityPathKind,
/// Scopes the caller wants this lineage path to authorize.
pub required_scopes: Vec<String>,
/// Optional lower bound for acceptable Sigil finality.
pub min_finalized_block: Option<u64>
}Source line: 62.
lineage::LineageAuthorityRecord
Sigil-backed authority record returned by a lineage finality source.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct LineageAuthorityRecord {
/// DID whose authority was verified.
pub subject_did: String,
/// Finalized root DID for the verified authority path.
pub root_did: String,
/// Reconstructed finalized path, ordered root to subject.
pub finalized_path: Vec<String>,
/// Sigil block height at which the authority proof is finalized.
pub finalized_block: u64,
/// Backend/source identifier, e.g. "sigil_gal".
pub source: String,
/// Scopes proven for this path.
pub scopes: Vec<String>,
/// Optional authority expiry timestamp.
pub expires_at: Option<String>
}Source line: 79.
lineage::LineageAuthorityVerification
Result of privileged lineage authority verification.
#[derive(Debug, Clone)]
pub struct LineageAuthorityVerification {
/// Portable local lineage verification result.
pub portable: VerifyResult,
/// Sigil-backed finality record.
pub authority: LineageAuthorityRecord
}Source line: 98.
lineage::LineageAuthoritySource
Backend that proves privileged lineage authority.
Production implementations are expected to query Sigil GAL or verify a fresh proof/cache of Sigil GAL state. Implementations must fail closed: returning an error means the privileged action is not authorized.
pub trait LineageAuthoritySource {
/// Verify the requested path against finalized lineage state.
fn verify_authority(
&self,
request: &LineageAuthorityRequest,
) -> Result<LineageAuthorityRecord, OasError>;
}Source line: 110.
lineage::derive_child
Derives a child entity from a parent identity.
Performs HKDF-SHA256 key derivation, constructs a lineage proof, builds the child document with the lineage section, and signs it.
Arguments
parent_keypair- The parent's Ed25519 keypair.parent_doc- The parent's signed OAS Identity Document.child_namespace- The child's namespace (often same as parent).child_kind- The child's entity kind (e.g.,"agent","tool").child_identifier- The child's unique identifier.derivation_path- The HKDF derivation path string.created- ISO 8601 timestamp.
Returns
A [DerivedIdentity] containing the signed child document and derived keypair.
Errors
Returns [OasError] if key derivation, document building, or signing fails.
Examples
use oas_sdk::identity::create_hmr;
use oas_sdk::lineage::derive_child;
let parent = create_hmr("test", "alice", "2026-01-15T00:00:00Z").unwrap();
let child = derive_child(
&parent.keypair,
&parent.document,
"test",
"agent",
"analyzer",
"agent/analyzer",
"2026-01-15T00:00:00Z",
);
assert!(child.is_ok());
let child = child.unwrap();
assert_eq!(child.document.id, "did:oas:test:agent:analyzer");
assert!(child.document.lineage.is_some());pub fn derive_child(
parent_keypair: &OasKeyPair,
parent_doc: &OasDocument,
child_namespace: &str,
child_kind: &str,
child_identifier: &str,
derivation_path: &str,
created: &str,
) -> Result<DerivedIdentity, OasError>;Source line: 162.
lineage::verify_chain
Verifies a lineage chain for a given document.
Walks the chain from the child to the root, verifying each hop's AgentLineageProof2025 signature.
Arguments
document- The document whose lineage to verify.provider- A provider that can resolve parent DIDs to documents.config- Verification configuration (timeouts, max depth).
Returns
A [VerifyResult] on success.
Errors
Returns [OasError::Lineage] if verification fails.
Examples
use oas_sdk::identity::create_hmr;
use oas_sdk::lineage::{derive_child, verify_chain};
use oas_lineage::provider::InMemoryProvider;
use oas_lineage::config::{TrustAnchor, VerifyConfig};
let parent = create_hmr("test", "alice", "2026-01-15T00:00:00Z").unwrap();
let child = derive_child(
&parent.keypair,
&parent.document,
"test", "agent", "bot",
"agent/bot",
"2026-01-15T00:00:00Z",
).unwrap();
let mut provider = InMemoryProvider::new();
provider.register(parent.document.clone());
let anchor = TrustAnchor::new(
&parent.document.id,
format!("{}#key-1", parent.document.id),
parent.keypair.public_key_multibase(),
).with_document_digest(parent.document.canonical_digest().unwrap());
let config = VerifyConfig::new().with_trust_anchor(anchor);
let result = verify_chain(&child.document, &provider, &config);
assert!(result.is_ok());pub fn verify_chain(
document: &OasDocument,
provider: &dyn DocumentProvider,
config: &VerifyConfig,
) -> Result<VerifyResult, OasError>;Source line: 241.
lineage::verify_privileged_authority
Verifies local lineage and then requires Sigil-backed privileged authority.
This is the SDK-level contract downstream systems should call before issuing ACTs, credentials, sessions, org membership, wallet authority, or other privileged access. If the authority source is unavailable or rejects the request, this function fails closed.
pub fn verify_privileged_authority(
document: &OasDocument,
provider: &dyn DocumentProvider,
config: &VerifyConfig,
authority_source: &dyn LineageAuthoritySource,
path_kind: AuthorityPathKind,
required_scopes: &[String],
min_finalized_block: Option<u64>,
) -> Result<LineageAuthorityVerification, OasError>;Source line: 255.