Public declaration syntax from forge-rs/crates/forge-contracts/src/identity.rs
Original source SHA-256: 58c5e34cd14b4451e3a60dead538762779e9dcee7117e3802069b64877fe620f
Function bodies and constant values are omitted. This is not the complete implementation.

Source line 56
pub const CONTRACT_VERSION: &str;

Source line 78
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct IdentityHandle {
/// The OAS DID string (e.g., "did:oas:l1fe:agent:code-reviewer").

pub did: String,
/// Depth in the lineage chain (0 = HMR root, 1 = direct child, etc.).

pub lineage_depth: u32,
/// The OAS namespace (e.g., "l1fe").

pub namespace: String,
/// The entity name within the DID (e.g., "code-reviewer").

pub entity_name: String
}

Source line 111
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DerivedIdentityRequest {
/// The parent agent's DID from which to derive.

pub parent_did: String,
/// The name for the child agent identity.

pub child_name: String,
/// The OAS namespace for the child DID.

pub namespace: String,
/// Optional org ID for organizational context.

pub org_id: Option<String>,
/// Optional department ID for organizational context.

pub department_id: Option<String>,
/// Maximum allowed lineage depth. Derivation fails if this would

/// be exceeded. Default: 16.

pub max_lineage_depth: u32
}

Source line 137
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct LineageInfo {
/// The DID of the identity being verified.

pub did: String,
/// Depth in the lineage chain (0 = root).

pub depth: u32,
/// The root DID at the top of the chain (usually an HMR/MHR).

pub root_did: String,
/// Whether the full chain from root to this identity verifies.

pub chain_valid: bool,
/// Each hop in the chain from root to this identity.

pub chain: Vec<LineageHop>
}

Source line 156
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct LineageHop {
/// The parent DID at this hop.

pub parent_did: String,
/// The child DID derived at this hop.

pub child_did: String,
/// The derivation path used.

pub derivation_path: String,
/// Whether this individual hop's signature verifies.

pub signature_valid: bool
}

Source line 189
#[async_trait]
pub trait IdentityContract: Send + Sync {
    /// Creates a new root identity (HMR) for an organization.
    ///
    /// This is called once per organization founding. The HMR is the
    /// cryptographic root from which all agent identities are derived.
    ///
    /// # Arguments
    ///
    /// * `namespace` - The OAS namespace (e.g., "l1fe").
    /// * `root_name` - The root identity name (e.g., "root-holder").
    ///
    /// # Returns
    ///
    /// A handle to the created root identity.
    async fn create_root_identity(
        &self,
        namespace: &str,
        root_name: &str,
    ) -> ContractResult<IdentityHandle>;

    /// Derives a child identity from an existing parent.
    ///
    /// The child's Ed25519 keypair is deterministically derived via
    /// HKDF-SHA256 from the parent's keypair and the derivation path.
    ///
    /// # Arguments
    ///
    /// * `request` - The derivation parameters.
    ///
    /// # Returns
    ///
    /// A handle to the derived child identity.
    ///
    /// # Errors
    ///
    /// - `ContractError::IdentityDerivationFailed` if derivation fails.
    /// - `ContractError::IdentityDerivationFailed` if max lineage depth
    ///   would be exceeded.
    async fn derive_identity(
        &self,
        request: DerivedIdentityRequest,
    ) -> ContractResult<IdentityHandle>;

    /// Verifies the lineage chain of an identity.
    ///
    /// Walks the chain from the given DID back to its root and verifies
    /// every hop's cryptographic proof.
    ///
    /// # Arguments
    ///
    /// * `did` - The DID to verify.
    ///
    /// # Returns
    ///
    /// Lineage information including chain validity.
    ///
    /// # Errors
    ///
    /// - `ContractError::DidResolutionFailed` if the DID cannot be resolved.
    /// - `ContractError::LineageVerificationFailed` if any hop fails.
    async fn verify_lineage(&self, did: &str) -> ContractResult<LineageInfo>;

    /// Resolves a DID to its public identity information.
    ///
    /// For local identities, this is immediate. For remote identities,
    /// this may involve network resolution.
    ///
    /// # Arguments
    ///
    /// * `did` - The DID string to resolve.
    ///
    /// # Returns
    ///
    /// The identity handle with public information.
    ///
    /// # Errors
    ///
    /// - `ContractError::DidResolutionFailed` if resolution fails.
    async fn resolve_did(&self, did: &str) -> ContractResult<IdentityHandle>;

    /// Signs arbitrary data with the specified identity's private key.
    ///
    /// # Arguments
    ///
    /// * `did` - The DID of the signing identity.
    /// * `data` - The data to sign.
    ///
    /// # Returns
    ///
    /// The Ed25519 signature bytes.
    ///
    /// # Errors
    ///
    /// - `ContractError::DidResolutionFailed` if the DID is not local.
    async fn sign(&self, did: &str, data: &[u8]) -> ContractResult<Vec<u8>>;

    /// Verifies a signature against a DID's public key.
    ///
    /// # Arguments
    ///
    /// * `did` - The DID of the alleged signer.
    /// * `data` - The data that was signed.
    /// * `signature` - The signature to verify.
    ///
    /// # Returns
    ///
    /// `true` if the signature is valid.
    ///
    /// # Errors
    ///
    /// - `ContractError::DidResolutionFailed` if the DID cannot be resolved.
    async fn verify(&self, did: &str, data: &[u8], signature: &[u8]) -> ContractResult<bool>;
}