macula_authorization_audit (macula v0.20.5)
View SourceAuthorization 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
Functions
Clear all audit entries.
Clear all audit entries from specific server.
Disable audit logging (telemetry still emits, ETS storage disabled).
Disable audit logging for specific server.
Enable audit logging.
Enable audit logging for specific server.
Get audit entries for a specific caller.
Get audit entries for a specific caller from specific server.
Get audit entries for a specific resource.
Get audit entries for a specific resource from specific server.
Get recent audit entries (most recent first).
Get recent audit entries from specific server.
Get audit statistics.
Get audit statistics from specific server.
Check if audit logging is enabled.
Check if audit logging is enabled for specific server.
Log an authorized operation.
Log an authorized operation to specific server.
Log a denied operation.
Log a denied operation to specific server.
Log an error during authorization check.
Log an error to specific server.
Set maximum number of entries.
Set maximum entries for specific server.
Set retention period in seconds.
Set retention period for specific server.
Start the audit server with default name.
Start the audit server with options.
Stop the default audit server.
Stop a specific audit server.
Types
-type did() :: binary().
-type operation() :: call | publish | subscribe | announce | atom().
-type opts() :: #{retention_seconds => pos_integer(), max_entries => pos_integer(), enabled => boolean(), cleanup_interval => pos_integer()}.
-type reason() :: unauthorized | invalid_ucan | expired_ucan | revoked_ucan | insufficient_capability | invalid_did | namespace_mismatch | atom().
-type resource() :: binary().
Functions
-spec clear() -> ok.
Clear all audit entries.
Clear all audit entries from specific server.
-spec disable() -> ok.
Disable audit logging (telemetry still emits, ETS storage disabled).
Disable audit logging for specific server.
-spec enable() -> ok.
Enable audit logging.
Enable audit logging for specific server.
-spec get_by_caller(did(), pos_integer()) -> [audit_entry()].
Get audit entries for a specific caller.
-spec get_by_caller(pid() | atom(), did(), pos_integer()) -> [audit_entry()].
Get audit entries for a specific caller from specific server.
-spec get_by_resource(resource(), pos_integer()) -> [audit_entry()].
Get audit entries for a specific resource.
-spec get_by_resource(pid() | atom(), resource(), pos_integer()) -> [audit_entry()].
Get audit entries for a specific resource from specific server.
-spec get_recent(pos_integer()) -> [audit_entry()].
Get recent audit entries (most recent first).
-spec get_recent(pid() | atom(), pos_integer()) -> [audit_entry()].
Get recent audit entries from specific server.
-spec get_stats() -> map().
Get audit statistics.
Get audit statistics from specific server.
-spec is_enabled() -> boolean().
Check if audit logging is enabled.
Check if audit logging is enabled for specific server.
Log an authorized operation.
Log an authorized operation to specific server.
Log a denied operation.
Log a denied operation to specific server.
Log an error during authorization check.
Log an error to specific server.
-spec set_max_entries(pos_integer()) -> ok.
Set maximum number of entries.
-spec set_max_entries(pid() | atom(), pos_integer()) -> ok.
Set maximum entries for specific server.
-spec set_retention(pos_integer()) -> ok.
Set retention period in seconds.
-spec set_retention(pid() | atom(), pos_integer()) -> ok.
Set retention period for specific server.
Start the audit server with default name.
Start the audit server with options.
-spec stop() -> ok.
Stop the default audit server.
Stop a specific audit server.