Skip to main content

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}