Search documentation of macula

# macula_realm_trust (macula v0.44.2)

View Source

Realm Trust Management for Hybrid Trust Model

Implements the Hybrid Trust Model (ADR-001) with three trust levels: - Level 1: Realm Authentication (API key/token validation) - Level 2: Certificate Trust (TOFU within authenticated realm) - Level 3: Optional CA-signed certificates for seed nodes

This module manages: - Realm authentication via API keys - Certificate fingerprint registration and verification - Trust On First Use (TOFU) pattern - Fingerprint change detection - Trust revocation

# Summary

## Types

fingerprint/0
node_id/0
realm/0
session/0

## Functions

authenticate(Realm, ApiKey)

Authenticate to a realm using API key Returns a session map on success, error tuple on failure Implements rate limiting per realm

extract_fingerprint(CertPEM)

Extract SHA-256 fingerprint from certificate PEM

get_auth_attempt_count(Realm)

Get the current auth attempt count for a realm

get_fingerprint_info(Realm, NodeId)

Get fingerprint info for a node in a realm

get_trusted_peers(Realm)

Get all trusted peers in a realm

init_rate_limiter()

Initialize the rate limiter ETS table

register_fingerprint(Realm, NodeId, Fingerprint)

Register a certificate fingerprint for a node in a realm

reset_rate_limit(Realm)

Reset the rate limit for a realm

revoke_trust(Realm, NodeId)

Revoke trust for a node in a realm

verify_fingerprint(Realm, NodeId, Fingerprint)

Verify a certificate fingerprint for a node in a realm Implements Trust On First Use (TOFU) - first connection is automatically trusted

# Types

# fingerprint/0

    -type fingerprint() :: binary().

# node_id/0

    -type node_id() :: binary().

# realm/0

    -type realm() :: binary().

# session/0

    -type session() :: #{realm := realm(), session_token := binary(), authenticated_at := integer()}.

# Functions

# authenticate(Realm, ApiKey)

    -spec authenticate(realm(), binary()) -> {ok, session()} | {error, term()}.

Authenticate to a realm using API key Returns a session map on success, error tuple on failure Implements rate limiting per realm

# extract_fingerprint(CertPEM)

    -spec extract_fingerprint(binary()) -> {ok, fingerprint()} | {error, term()}.

Extract SHA-256 fingerprint from certificate PEM

# get_auth_attempt_count(Realm)

    -spec get_auth_attempt_count(realm()) -> {ok, non_neg_integer()}.

Get the current auth attempt count for a realm

# get_fingerprint_info(Realm, NodeId)

    -spec get_fingerprint_info(realm(), node_id()) -> {ok, map()} | {error, not_found}.

Get fingerprint info for a node in a realm

# get_trusted_peers(Realm)

    -spec get_trusted_peers(realm()) -> {ok, [map()]}.

Get all trusted peers in a realm

# init_rate_limiter()

    -spec init_rate_limiter() -> ok.

Initialize the rate limiter ETS table

# register_fingerprint(Realm, NodeId, Fingerprint)

    -spec register_fingerprint(realm(), node_id(), fingerprint()) -> {ok, registered}.

Register a certificate fingerprint for a node in a realm

# reset_rate_limit(Realm)

    -spec reset_rate_limit(realm()) -> ok.

Reset the rate limit for a realm

# revoke_trust(Realm, NodeId)

    -spec revoke_trust(realm(), node_id()) -> {ok, revoked | not_found}.

Revoke trust for a node in a realm

# verify_fingerprint(Realm, NodeId, Fingerprint)

    -spec verify_fingerprint(realm(), node_id(), fingerprint()) ->
                                {ok, trusted | trusted_first_use} |
                                {error,
                                 {fingerprint_mismatch,
                                  #{expected := fingerprint(), received := fingerprint()}}}.

Verify a certificate fingerprint for a node in a realm Implements Trust On First Use (TOFU) - first connection is automatically trusted