Search documentation of macula

# macula_authorization_audit (macula v0.44.2)

View Source

Authorization Audit Logging Module.

Provides comprehensive audit logging for all authorization decisions in the Macula mesh. Uses telemetry for real-time metrics and optionally stores recent entries in ETS for debugging and analysis.

### Telemetry Events

- `[macula, authorization, allowed]` - Authorization succeeded - `[macula, authorization, denied]` - Authorization denied - `[macula, authorization, error]` - Authorization check error

### Event Metadata

All events include: - `operation` - The operation type (call, publish, subscribe, announce) - `caller` - The caller's DID - `resource` - The topic or procedure - `timestamp` - Unix timestamp

Denied events also include: - `reason` - Why authorization failed

### Usage

Log an authorized operation:

`macula_authorization_audit:log_authorized(call, CallerDID, Procedure).`

Log a denied operation:

`macula_authorization_audit:log_denied(publish, CallerDID, Topic, unauthorized).`

Query recent audit entries (for debugging):

`Entries = macula_authorization_audit:get_recent(100).`

### Performance

Designed for sub-millisecond overhead: - Telemetry events are synchronous but fast - ETS writes are non-blocking - Periodic cleanup prevents unbounded growth

# Summary

## Types

audit_entry/0
did/0
operation/0
opts/0
reason/0
resource/0

## Functions

clear()

Clear all audit entries.

clear(ServerRef)

Clear all audit entries from specific server.

disable()

Disable audit logging (telemetry still emits, ETS storage disabled).

disable(ServerRef)

Disable audit logging for specific server.

enable()

Enable audit logging.

enable(ServerRef)

Enable audit logging for specific server.

get_by_caller(CallerDID, Limit)

Get audit entries for a specific caller.

get_by_caller(ServerRef, CallerDID, Limit)

Get audit entries for a specific caller from specific server.

get_by_resource(Resource, Limit)

Get audit entries for a specific resource.

get_by_resource(ServerRef, Resource, Limit)

Get audit entries for a specific resource from specific server.

get_recent(Limit)

Get recent audit entries (most recent first).

get_recent(ServerRef, Limit)

Get recent audit entries from specific server.

get_stats()

Get audit statistics.

get_stats(ServerRef)

Get audit statistics from specific server.

is_enabled()

Check if audit logging is enabled.

is_enabled(ServerRef)

Check if audit logging is enabled for specific server.

log_authorized(Operation, CallerDID, Resource)

Log an authorized operation.

log_authorized(ServerRef, Operation, CallerDID, Resource)

Log an authorized operation to specific server.

log_denied(Operation, CallerDID, Resource, Reason)

Log a denied operation.

log_denied(ServerRef, Operation, CallerDID, Resource, Reason)

Log a denied operation to specific server.

log_error(Operation, CallerDID, Resource, Error)

Log an error during authorization check.

log_error(ServerRef, Operation, CallerDID, Resource, Error)

Log an error to specific server.

set_max_entries(MaxEntries)

Set maximum number of entries.

set_max_entries(ServerRef, MaxEntries)

Set maximum entries for specific server.

set_retention(Seconds)

Set retention period in seconds.

set_retention(ServerRef, Seconds)

Set retention period for specific server.

start_link()

Start the audit server with default name.

start_link(Opts)

Start the audit server with options.

stop()

Stop the default audit server.

stop(ServerRef)

Stop a specific audit server.

# Types

# audit_entry/0

    -type audit_entry() ::
              #{id := binary(),
                timestamp := integer(),
                operation := operation(),
                caller := did(),
                resource := resource(),
                result := allowed | denied | error,
                reason => reason(),
                metadata => map()}.

# did/0

    -type did() :: binary().

# operation/0

    -type operation() :: call | publish | subscribe | announce | atom().

# opts/0

    -type opts() ::
              #{retention_seconds => pos_integer(),
                max_entries => pos_integer(),
                enabled => boolean(),
                cleanup_interval => pos_integer()}.

# reason/0

    -type reason() ::
              unauthorized | invalid_ucan | expired_ucan | revoked_ucan | insufficient_capability |
              invalid_did | namespace_mismatch |
              atom().

# resource/0

    -type resource() :: binary().

# Functions

# clear()

    -spec clear() -> ok.

Clear all audit entries.

# clear(ServerRef)

    -spec clear(pid() | atom()) -> ok.

Clear all audit entries from specific server.

# disable()

    -spec disable() -> ok.

Disable audit logging (telemetry still emits, ETS storage disabled).

# disable(ServerRef)

    -spec disable(pid() | atom()) -> ok.

Disable audit logging for specific server.

# enable()

    -spec enable() -> ok.

Enable audit logging.

# enable(ServerRef)

    -spec enable(pid() | atom()) -> ok.

Enable audit logging for specific server.

# get_by_caller(CallerDID, Limit)

    -spec get_by_caller(did(), pos_integer()) -> [audit_entry()].

Get audit entries for a specific caller.

# get_by_caller(ServerRef, CallerDID, Limit)

    -spec get_by_caller(pid() | atom(), did(), pos_integer()) -> [audit_entry()].

Get audit entries for a specific caller from specific server.

# get_by_resource(Resource, Limit)

    -spec get_by_resource(resource(), pos_integer()) -> [audit_entry()].

Get audit entries for a specific resource.

# get_by_resource(ServerRef, Resource, Limit)

    -spec get_by_resource(pid() | atom(), resource(), pos_integer()) -> [audit_entry()].

Get audit entries for a specific resource from specific server.

# get_recent(Limit)

    -spec get_recent(pos_integer()) -> [audit_entry()].

Get recent audit entries (most recent first).

# get_recent(ServerRef, Limit)

    -spec get_recent(pid() | atom(), pos_integer()) -> [audit_entry()].

Get recent audit entries from specific server.

# get_stats()

    -spec get_stats() -> map().

Get audit statistics.

# get_stats(ServerRef)

    -spec get_stats(pid() | atom()) -> map().

Get audit statistics from specific server.

# is_enabled()

    -spec is_enabled() -> boolean().

Check if audit logging is enabled.

# is_enabled(ServerRef)

    -spec is_enabled(pid() | atom()) -> boolean().

Check if audit logging is enabled for specific server.

# log_authorized(Operation, CallerDID, Resource)

    -spec log_authorized(operation(), did(), resource()) -> ok.

Log an authorized operation.

# log_authorized(ServerRef, Operation, CallerDID, Resource)

    -spec log_authorized(pid() | atom(), operation(), did(), resource()) -> ok.

Log an authorized operation to specific server.

# log_denied(Operation, CallerDID, Resource, Reason)

    -spec log_denied(operation(), did(), resource(), reason()) -> ok.

Log a denied operation.

# log_denied(ServerRef, Operation, CallerDID, Resource, Reason)

    -spec log_denied(pid() | atom(), operation(), did(), resource(), reason()) -> ok.

Log a denied operation to specific server.

# log_error(Operation, CallerDID, Resource, Error)

    -spec log_error(operation(), did(), resource(), term()) -> ok.

Log an error during authorization check.

# log_error(ServerRef, Operation, CallerDID, Resource, Error)

    -spec log_error(pid() | atom(), operation(), did(), resource(), term()) -> ok.

Log an error to specific server.

# set_max_entries(MaxEntries)

    -spec set_max_entries(pos_integer()) -> ok.

Set maximum number of entries.

# set_max_entries(ServerRef, MaxEntries)

    -spec set_max_entries(pid() | atom(), pos_integer()) -> ok.

Set maximum entries for specific server.

# set_retention(Seconds)

    -spec set_retention(pos_integer()) -> ok.

Set retention period in seconds.

# set_retention(ServerRef, Seconds)

    -spec set_retention(pid() | atom(), pos_integer()) -> ok.

Set retention period for specific server.

# start_link()

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

Start the audit server with default name.

# start_link(Opts)

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

Start the audit server with options.

# stop()

    -spec stop() -> ok.

Stop the default audit server.

# stop(ServerRef)

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

Stop a specific audit server.