Search documentation of macula

# macula_ucan_nif (macula v4.4.9)

View Source

UCAN (User Controlled Authorization Networks) token operations.

This module provides creation, verification, and manipulation of UCAN tokens for decentralized authorization in the Macula mesh. UCANs are self-contained capability tokens that support delegation.

### Token Structure

UCAN tokens follow JWT format: header.payload.signature

Header: - alg: "EdDSA" (Ed25519) - typ: "JWT" - ucv: "0.10.0" (UCAN version)

Payload: - iss: Issuer DID (did:macula:io.macula.org) - aud: Audience DID - cap: Capabilities [{with, can}, ...] - exp: Expiration (optional, unix timestamp) - nbf: Not before (optional, unix timestamp) - nnc: Nonce (optional, for uniqueness) - fct: Facts (optional, metadata) - prf: Proof chain (CIDs of parent tokens)

# Summary

## Types

capability/0
did/0
ucan_opts/0

## Functions

compute_cid(Token)

Compute the CID (Content ID) of a UCAN token. Used for proof chains.

create(Issuer, Audience, Capabilities, PrivateKey)

Equivalent to create(Issuer, Audience, Capabilities, PrivateKey, #{}).

create(Issuer, Audience, Capabilities, PrivateKey, Opts)

Create a new UCAN token with options.

decode(Token)

Decode a UCAN token without verification. WARNING: This does NOT verify the signature!

get_audience(Token)

Get the audience DID from a UCAN token.

get_capabilities(Token)

Get capabilities from a UCAN token.

get_expiration(Token)

Get expiration timestamp from a UCAN token.

get_issuer(Token)

Get the issuer DID from a UCAN token.

get_proofs(Token)

Get proof chain from a UCAN token.

is_expired(Token)

Check if a UCAN token is expired.

is_nif_loaded()

Check if the NIF is loaded.

nif_compute_cid(Token)
nif_create(Issuer, Audience, CapsJson, PrivateKey, OptsJson)
nif_decode(Token)
nif_get_audience(Token)
nif_get_issuer(Token)
nif_verify(Token, PublicKey)
verify(Token, PublicKey)

Verify a UCAN token. Checks signature, expiration, and not-before. Returns the decoded payload on success.

# Types

# capability/0

    -type capability() :: #{with := binary(), can := binary()}.

# did/0

    -type did() :: binary().

# ucan_opts/0

    -type ucan_opts() ::
              #{exp => non_neg_integer(),
                nbf => non_neg_integer(),
                nnc => binary(),
                fct => map(),
                prf => [binary()]}.

# Functions

# compute_cid(Token)

    -spec compute_cid(Token :: binary()) -> binary().

Compute the CID (Content ID) of a UCAN token. Used for proof chains.

# create(Issuer, Audience, Capabilities, PrivateKey)

    -spec create(Issuer :: did(), Audience :: did(), Capabilities :: [capability()], PrivateKey :: binary()) ->
                    {ok, Token :: binary()} | {error, term()}.

Equivalent to create(Issuer, Audience, Capabilities, PrivateKey, #{}).

Create a new UCAN token.

# create(Issuer, Audience, Capabilities, PrivateKey, Opts)

    -spec create(Issuer :: did(),
                 Audience :: did(),
                 Capabilities :: [capability()],
                 PrivateKey :: binary(),
                 Opts :: ucan_opts()) ->
                    {ok, Token :: binary()} | {error, term()}.

Create a new UCAN token with options.

Options: - exp: Expiration timestamp (unix seconds) - nbf: Not before timestamp (unix seconds) - nnc: Nonce (for uniqueness) - fct: Facts map (metadata) - prf: Proof chain (list of CIDs of parent tokens)

# decode(Token)

    -spec decode(Token :: binary()) -> {ok, Payload :: map()} | {error, term()}.

Decode a UCAN token without verification. WARNING: This does NOT verify the signature!

# get_audience(Token)

    -spec get_audience(Token :: binary()) -> {ok, did()} | {error, term()}.

Get the audience DID from a UCAN token.

# get_capabilities(Token)

    -spec get_capabilities(Token :: binary()) -> {ok, [capability()]} | {error, term()}.

Get capabilities from a UCAN token.

# get_expiration(Token)

    -spec get_expiration(Token :: binary()) -> {ok, non_neg_integer() | null} | {error, term()}.

Get expiration timestamp from a UCAN token.

# get_issuer(Token)

    -spec get_issuer(Token :: binary()) -> {ok, did()} | {error, term()}.

Get the issuer DID from a UCAN token.

# get_proofs(Token)

    -spec get_proofs(Token :: binary()) -> {ok, [binary()]} | {error, term()}.

Get proof chain from a UCAN token.

# is_expired(Token)

    -spec is_expired(Token :: binary()) -> boolean() | {error, term()}.

Check if a UCAN token is expired.

# is_nif_loaded()

    -spec is_nif_loaded() -> boolean().

Check if the NIF is loaded.

# nif_compute_cid(Token)

# nif_create(Issuer, Audience, CapsJson, PrivateKey, OptsJson)

# nif_decode(Token)

# nif_get_audience(Token)

# nif_get_issuer(Token)

# nif_verify(Token, PublicKey)

# verify(Token, PublicKey)

    -spec verify(Token :: binary(), PublicKey :: binary()) -> {ok, Payload :: map()} | {error, term()}.

Verify a UCAN token. Checks signature, expiration, and not-before. Returns the decoded payload on success.