Crate ucan

Expand description

Implement UCAN-based authorization with conciseness and ease!

UCANs are an emerging pattern based on JSON Web Tokens (aka JWTs) that facilitate distributed and/or decentralized authorization flows in web applications. Visit https://ucan.xyz for an introduction to UCANs and ideas for how you can use them in your application.

Examples

This crate offers the builder::UcanBuilder abstraction to generate signed UCAN tokens.

To generate a signed token, you need to provide a [crypto::SigningKey] implementation. For more information on providing a signing key, see the crypto module documentation.

use ucan::{
  builder::UcanBuilder,
  crypto::KeyMaterial,
};

async fn generate_token<'a, K: KeyMaterial>(issuer_key: &'a K, audience_did: &'a str) -> Result<String, anyhow::Error> {
    UcanBuilder::default()
      .issued_by(issuer_key)
      .for_audience(audience_did)
      .with_lifetime(60)
      .build()?
      .sign().await?
      .encode()
}

The crate also offers a validating parser to interpret UCAN tokens and the capabilities they grant via their issuer and/or witnessing proofs: the chain::ProofChain.

Most capabilities are closely tied to a specific application domain. See the capability module documentation to read more about defining your own domain-specific semantics.

use ucan::{
  chain::{ProofChain, CapabilityInfo},
  capability::{CapabilitySemantics, Scope, Action},
  crypto::did::{DidParser, KeyConstructorSlice}
};

const SUPPORTED_KEY_TYPES: &KeyConstructorSlice = &[
    // You must bring your own key support
];

async fn get_capabilities<'a, Semantics, S, A>(ucan_token: &'a str, semantics: &'a Semantics) -> Result<Vec<CapabilityInfo<S, A>>, anyhow::Error>
    where
        Semantics: CapabilitySemantics<S, A>,
        S: Scope,
        A: Action
{
    let mut did_parser = DidParser::new(SUPPORTED_KEY_TYPES);

    Ok(ProofChain::try_from_token_string(ucan_token, &mut did_parser).await?
        .reduce_capabilities(semantics))
}

Note that you must bring your own key support in order to build a ProofChain, via a crypto::did::DidParser. This is so that the core library can remain agnostic of backing implementations for specific key types.

Modules