alexandria_verify/lib.rs
1//! Alexandria credential verification.
2//!
3//! Everything needed to decide whether an Alexandria credential is genuine:
4//! the VC envelope types, JCS canonicalization, the Data Integrity proof
5//! (`DataIntegrityProof`, cryptosuite `eddsa-jcs-2022`), `did:key`
6//! resolution, and Bitstring Status List revocation and suspension. Around
7//! them sit the checks a reader makes of what a credential says: device
8//! attestation evidence ([`attestation`]), organisation backing ([`org`]),
9//! the coverage statement registry ([`coverage`]), the issuance policy
10//! rule an issuer and a hosted service share ([`policy`]), and the evidence
11//! entry naming the credential a role credential was issued on
12//! ([`assessed`]).
13//!
14//! The crate performs no I/O. Verification needs to consult persistent state
15//! in four places — the key registered for an issuer whose DID is not
16//! self-resolving, a status list's bits (revocation and suspension alike),
17//! whether something supersedes the credential, and an observed ledger anchor
18//! of its hash — and each of those arrives through
19//! [`VerificationStore`] rather than a database handle or a chain client. Callers implement the trait over whatever they have:
20//! SQLite in the app, a credential bundle in the CLI, Postgres on a server.
21//!
22//! That indirection is the point. A verifier should link a signature checker,
23//! not an application.
24
25pub mod access;
26pub mod assessed;
27pub mod attestation;
28pub mod course;
29pub mod coverage;
30pub mod did;
31pub mod exchange;
32pub mod governance;
33pub mod hash;
34pub mod integrity;
35pub mod json;
36pub mod org;
37pub mod policy;
38pub mod qualification;
39pub mod talent;
40pub mod trust;
41pub mod vc;
42
43pub use did::{Did, DidError, KeyRegistryEntry, VerificationMethodRef};
44
45/// Persistent state that verification consults.
46///
47/// Every method distinguishes a known value, a confirmed missing value, and an
48/// unavailable lookup. Verification must never turn missing status evidence or
49/// a storage failure into a clean active credential.
50pub trait VerificationStore {
51 /// The key registered for an issuer whose DID method is not
52 /// self-resolving, if the registry holds one.
53 ///
54 /// Never consulted for a `did:key`: that resolves to the key in its
55 /// identifier, and no registry state can change it.
56 fn registered_key(&self, did: &Did) -> StoreLookup<KeyRegistryEntry>;
57
58 /// Raw bits of a known status list, whatever its purpose. Suspension is
59 /// read from here too: a credential's suspension entry names a list of
60 /// purpose `suspension`, and its bit is the only suspension state
61 /// verification reads.
62 fn status_list_bits(&self, list_id: &str) -> StoreLookup<Vec<u8>>;
63
64 /// Whether a locally-held credential supersedes this one.
65 fn is_superseded(&self, credential_id: &str) -> StoreLookup<bool>;
66
67 /// The anchor receipt for `credential_hash` and the caller's ledger
68 /// observation of the transaction it names (spec §11.3.1), if both are
69 /// known. The verifier folds the receipt from the recomputed hash and
70 /// checks root, transaction, issuer and required signer before trusting
71 /// it.
72 ///
73 /// Stores that know nothing about anchors keep the default: `Missing`, so
74 /// `integrityAnchored` is false.
75 fn integrity_anchor(&self, _credential_hash: &str) -> StoreLookup<vc::anchor::AnchorEvidence> {
76 StoreLookup::Missing
77 }
78}
79
80/// Result of consulting verification state supplied by a caller.
81#[derive(Debug, Clone, PartialEq, Eq)]
82pub enum StoreLookup<T> {
83 Found(T),
84 Missing,
85 Unavailable,
86}
87
88/// A store that knows nothing.
89///
90/// Use it to verify a credential purely on its own contents — the signature,
91/// the expiry, and `did:key` self-resolution. A credential that references a
92/// status list remains pending because this store cannot supply that list.
93pub struct NullStore;
94
95impl VerificationStore for NullStore {
96 fn registered_key(&self, _did: &Did) -> StoreLookup<KeyRegistryEntry> {
97 StoreLookup::Missing
98 }
99 fn status_list_bits(&self, _list_id: &str) -> StoreLookup<Vec<u8>> {
100 StoreLookup::Missing
101 }
102 fn is_superseded(&self, _credential_id: &str) -> StoreLookup<bool> {
103 StoreLookup::Missing
104 }
105}