macula_ucan_nif (macula v1.4.25)

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.