ucan/lib.rs
1//! Implement UCAN-based authorization with conciseness and ease!
2//!
3//! [UCANs][UCAN docs] are an emerging pattern based on
4//! [JSON Web Tokens][JWT docs] (aka JWTs) that facilitate distributed and/or
5//! decentralized authorization flows in web applications. Visit
6//! [https://ucan.xyz][UCAN docs] for an introduction to UCANs and ideas for
7//! how you can use them in your application.
8//!
9//! # Examples
10//!
11//! This crate offers the [`builder::UcanBuilder`] abstraction to generate
12//! signed UCAN tokens.
13//!
14//! To generate a signed token, you need to provide a [`crypto::KeyMaterial`]
15//! implementation. For more information on providing a signing key, see the
16//! [`crypto`] module documentation.
17//!
18//! ```rust
19//! use ucan::{
20//! builder::UcanBuilder,
21//! crypto::KeyMaterial,
22//! };
23//!
24//! async fn generate_token<'a, K: KeyMaterial>(issuer_key: &'a K, audience_did: &'a str) -> Result<String, anyhow::Error> {
25//! UcanBuilder::default()
26//! .issued_by(issuer_key)
27//! .for_audience(audience_did)
28//! .with_lifetime(60)
29//! .build()?
30//! .sign().await?
31//! .encode()
32//! }
33//! ```
34//!
35//! The crate also offers a validating parser to interpret UCAN tokens and
36//! the capabilities they grant via their issuer and/or witnessing proofs:
37//! the [`chain::ProofChain`].
38//!
39//! Most capabilities are closely tied to a specific application domain. See the
40//! [`capability`] module documentation to read more about defining your own
41//! domain-specific semantics.
42//!
43//! ```rust
44//! use ucan::{
45//! chain::{ProofChain, CapabilityInfo},
46//! capability::{CapabilitySemantics, Scope, Ability},
47//! crypto::did::{DidParser, KeyConstructorSlice},
48//! store::UcanJwtStore
49//! };
50//!
51//! const SUPPORTED_KEY_TYPES: &KeyConstructorSlice = &[
52//! // You must bring your own key support
53//! ];
54//!
55//! async fn get_capabilities<'a, Semantics, S, A, Store>(ucan_token: &'a str, semantics: &'a Semantics, store: &'a Store) -> Result<Vec<CapabilityInfo<S, A>>, anyhow::Error>
56//! where
57//! Semantics: CapabilitySemantics<S, A>,
58//! S: Scope,
59//! A: Ability,
60//! Store: UcanJwtStore
61//! {
62//! let mut did_parser = DidParser::new(SUPPORTED_KEY_TYPES);
63//!
64//! Ok(ProofChain::try_from_token_string(ucan_token, None, &mut did_parser, store).await?
65//! .reduce_capabilities(semantics))
66//! }
67//! ```
68//!
69//! Note that you must bring your own key support in order to build a
70//! `ProofChain`, via a [`crypto::did::DidParser`]. This is so that the core
71//! library can remain agnostic of backing implementations for specific key
72//! types.
73//!
74//! [JWT docs]: https://jwt.io/
75//! [UCAN docs]: https://ucan.xyz/
76//! [DID spec]: https://www.w3.org/TR/did-core/
77//! [DID Key spec]: https://w3c-ccg.github.io/did-method-key/
78
79pub mod crypto;
80pub mod time;
81
82pub mod builder;
83pub mod capability;
84pub mod chain;
85pub mod ipld;
86pub mod serde;
87pub mod store;
88pub mod ucan;
89pub use self::ucan::Ucan;
90
91#[cfg(test)]
92mod tests;