macula_ucan_revocation (macula v0.20.5)

View Source

UCAN Revocation Module.

Manages revocation of UCAN tokens via mesh PubSub gossip. Revocations are stored in an ETS cache and checked during authorization.

Revocation Flow

1. Issuer calls revoke/2` with their DID and the UCAN CID 2. Module broadcasts revocation to `io.macula.system.ucan_revoked` topic 3. All mesh nodes receive via PubSub subscription 4. Each node validates signature (issuer must be UCAN creator) 5. Valid revocations stored in local ETS cache with TTL 6. Authorization checks consult cache via `is_revoked/2` == System Topic == All revocations are published to: `io.macula.system.ucan_revoked

Rate Limiting

Maximum 10 revocations per issuer per minute to prevent abuse.

Cache Auto-Expiry

Revocation entries expire based on original UCAN expiry time. A cleanup process runs periodically to purge expired entries.

Summary

Types

did/0
revocation_msg/0
timestamp/0
ucan_cid/0
ucan_token/0

Functions

clear_cache()

Clear all revocation cache entries (uses default server).

clear_cache(ServerRef)

Clear all revocation cache entries via specific server.

get_stats()

Get revocation statistics (uses default server).

get_stats(ServerRef)

Get revocation statistics via specific server.

handle_call(_, From, State)
handle_cast(Msg, State)
handle_info(Info, State)
handle_revocation_message(Msg)

Handle incoming revocation message from PubSub.

handle_revocation_message(ServerRef, Msg)

Handle incoming revocation message via specific server.

init(Opts)
is_revoked(IssuerDID, UcanCID)

Check if a UCAN is revoked (uses default server).

is_revoked(ServerRef, IssuerDID, UcanCID)

Check if a UCAN is revoked via specific server.

revoke(IssuerDID, UcanToken, ExpiresAt)

Revoke a UCAN token (uses default server).

revoke(ServerRef, IssuerDID, UcanToken, ExpiresAt)

Revoke a UCAN token via specific server.

start_link()

Start the revocation server with default name.

start_link(Opts)

Start the revocation server with options.

stop()

Stop the revocation server (default name).

stop(ServerRef)

Stop a specific revocation server.

terminate(Reason, State)

Types

did/0

-type did() :: binary().

revocation_msg/0

-type revocation_msg() :: #{binary() => binary() | timestamp()}.

timestamp/0

-type timestamp() :: non_neg_integer().

ucan_cid/0

-type ucan_cid() :: binary().

ucan_token/0

-type ucan_token() :: binary().

Functions

clear_cache()

-spec clear_cache() -> ok.

Clear all revocation cache entries (uses default server).

clear_cache(ServerRef)

-spec clear_cache(ServerRef :: atom() | pid()) -> ok.

Clear all revocation cache entries via specific server.

get_stats()

-spec get_stats() -> #{atom() => term()}.

Get revocation statistics (uses default server).

get_stats(ServerRef)

-spec get_stats(ServerRef :: atom() | pid()) -> #{atom() => term()}.

Get revocation statistics via specific server.

handle_call(_, From, State)

handle_cast(Msg, State)

handle_info(Info, State)

handle_revocation_message(Msg)

-spec handle_revocation_message(Msg :: revocation_msg()) -> ok | {error, term()}.

Handle incoming revocation message from PubSub.

handle_revocation_message(ServerRef, Msg)

-spec handle_revocation_message(ServerRef :: atom() | pid(), Msg :: revocation_msg()) ->
                                   ok | {error, term()}.

Handle incoming revocation message via specific server.

init(Opts)

is_revoked(IssuerDID, UcanCID)

-spec is_revoked(IssuerDID :: did(), UcanCID :: ucan_cid()) -> boolean().

Check if a UCAN is revoked (uses default server).

is_revoked(ServerRef, IssuerDID, UcanCID)

-spec is_revoked(ServerRef :: atom() | pid(), IssuerDID :: did(), UcanCID :: ucan_cid()) -> boolean().

Check if a UCAN is revoked via specific server.

revoke(IssuerDID, UcanToken, ExpiresAt)

-spec revoke(IssuerDID :: did(), UcanToken :: ucan_token(), ExpiresAt :: timestamp()) ->
                {ok, ucan_cid()} | {error, term()}.

Revoke a UCAN token (uses default server).

The issuer must sign the revocation message. The revocation is broadcast to all mesh nodes via PubSub.

UcanToken is the full UCAN JWT token being revoked. ExpiresAt is the original expiry time of the UCAN. PrivateKey is used to sign the revocation (Ed25519).

revoke(ServerRef, IssuerDID, UcanToken, ExpiresAt)

-spec revoke(ServerRef :: atom() | pid(),
             IssuerDID :: did(),
             UcanToken :: ucan_token(),
             ExpiresAt :: timestamp()) ->
                {ok, ucan_cid()} | {error, term()}.

Revoke a UCAN token via specific server.

start_link()

-spec start_link() -> {ok, pid()} | {error, term()}.

Start the revocation server with default name.

start_link(Opts)

-spec start_link(Opts :: map()) -> {ok, pid()} | {error, term()}.

Start the revocation server with options.

stop()

-spec stop() -> ok.

Stop the revocation server (default name).

stop(ServerRef)

-spec stop(ServerRef :: atom() | pid()) -> ok.

Stop a specific revocation server.

terminate(Reason, State)