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};