Skip to main content

did_bio_core/
lib.rs

1//! Data model and resolution for the `did:bio` DID method, a W3C DID 1.0
2//! conformant method for biological research data, anchored on the Solana
3//! blockchain by the `bio-did-registry` program.
4//!
5//! This crate is the transport free core shared by resolvers, backends,
6//! and tooling. It provides the pieces below.
7//!
8//! - [`BioDid`] and [`DidUrl`] parse identifiers and validate them against
9//!   the method ABNF (spec Section 4).
10//! - [`multikey`] encodes and decodes Multikey values (Controlled
11//!   Identifiers v1.0) for Ed25519, X25519, and secp256k1 keys.
12//! - [`DidDocument`] and its related types are the DID document data model
13//!   (spec Section 5). It includes the post quantum ML-DSA-87 (FIPS 204)
14//!   verification method type, a `JsonWebKey` with the `AKP` key type.
15//! - [`DidAccountState`] is a dependency free deserializer for the
16//!   registry's on chain account format.
17//! - [`KeyBufferState`] decodes the staging account through which keys
18//!   larger than one transaction, such as ML-DSA-87 keys, are uploaded in
19//!   chunks.
20//! - [`resolve_from_account`] runs steps 6-9 of the resolution algorithm
21//!   (spec Section 6.2) as a pure function, with the generative fallback.
22//!   [`resolve_with`], [`resolve_with_async`] and
23//!   [`resolve_with_async_local`] drive it through a pluggable
24//!   [`RegistryReader`], and [`dereference`] finds what a DID URL names.
25//! - [`Quorum`] reads through several readers and accepts an account only
26//!   when a majority agree, against an RPC node that withholds one.
27//! - [`find_did_account_address`], [`find_key_buffer_address`] and
28//!   [`find_owned_subject`] derive PDAs without a Solana SDK dependency,
29//!   under the `pda` feature.
30//!
31//! # Resolution without a network
32//!
33//! A subject is either an Ed25519 key or an owned subject, a program
34//! derived address that `initialize_owned` binds to the wallet that signed
35//! for it. [`BioDid::is_key_subject`] tells them apart. Every key subject
36//! resolves. Without on chain state it yields the deterministic generative
37//! document containing the key itself, while an owned subject without an
38//! account resolves to `notFound`.
39//!
40//! ```
41//! use did_bio_core::{resolve_from_account, BioDid};
42//!
43//! let did: BioDid = "did:bio:devnet:2T6zLFvMx7NJac5qQtiKTaPhMwHLkwKETWjUK1yKv4tc"
44//!     .parse()
45//!     .unwrap();
46//!
47//! // Without a registry account the result is the generative document
48//! // with versionId "0".
49//! let resolution = resolve_from_account(&did, None);
50//! let document = resolution.document.unwrap();
51//! assert_eq!(document.id, did.to_string());
52//! assert_eq!(
53//!     document.verification_method[0].id,
54//!     did.default_verification_method_id(),
55//! );
56//! assert_eq!(resolution.document_metadata.version_id.as_deref(), Some("0"));
57//! ```
58//!
59//! # Features
60//!
61//! - `pda` is on by default. It adds PDA derivation
62//!   ([`find_did_account_address`]) and the [`resolve_with`] and
63//!   [`resolve_with_async`] drivers, in pure Rust with `sha2`.
64//! - `verify` adds signature verification for Ed25519, ES256K and ML-DSA-87
65//!   verification methods via `aws-lc-rs`.
66//! - `fips` is like `verify`, but binds the FIPS validated AWS-LC module.
67//!
68//! The spec is the `did:bio` DID Method Specification v1.2
69//! (<https://github.com/ekayana-labs/bio-did-spec>). Section references
70//! throughout this crate point there.
71
72#![forbid(unsafe_code)]
73#![deny(missing_docs)]
74
75pub mod account;
76pub mod datetime;
77pub mod did;
78pub mod document;
79pub mod error;
80pub mod multikey;
81#[cfg(feature = "pda")]
82pub mod pda;
83pub mod quorum;
84pub mod resolve;
85#[cfg(feature = "verify")]
86pub mod verify;
87
88pub use account::{
89    DidAccountState, KeyBufferState, KeyType, StoredService, StoredVerificationMethod,
90};
91pub use did::is_on_curve;
92pub use did::{BioDid, DidUrl, Network};
93pub use document::{
94    AkpPublicJwk, Dereferenced, DidDocument, DidDocumentMetadata, DidResolution,
95    DidResolutionMetadata, ServiceMap, VerificationMaterial, VerificationMethodMap,
96    VerificationRelationship,
97};
98pub use error::{resolution_error, Error};
99#[cfg(feature = "pda")]
100pub use pda::{
101    find_did_account_address, find_key_buffer_address, find_owned_subject, find_program_address,
102    try_find_program_address,
103};
104pub use quorum::{Quorum, QuorumError};
105pub use resolve::{
106    deactivated_document, dereference, generative_document, materialize_document,
107    resolve_from_account, resolve_str, AsyncRegistryReader, LocalAsyncRegistryReader, RawAccount,
108    RegistryReader,
109};
110#[cfg(feature = "pda")]
111pub use resolve::{resolve_with, resolve_with_async, resolve_with_async_local};