Search documentation of macula

# macula_gatekeeper (macula v0.44.2)

View Source

Gatekeeper module for validating mesh application admissions.

### Overview

The gatekeeper validates that applications are "mesh-worthy" before allowing them to participate in the Macula mesh network. Validation happens at: - Session establishment (initial admission) - Periodically during session (health checks) - On each operation (capability enforcement)

### Validation Layers

1. Protocol Compliance: App implements `macula_protocol` behaviour 2. Identity Verification: Identity matches presented certificate 3. Certificate Validation: Certificate is valid, not expired, not revoked 4. Capability Declaration: App declares its required capabilities 5. Health Status: App responds to health checks

### BEAM vs Non-BEAM Apps

For BEAM apps (Erlang/Elixir): - Use `verify_beam_app/2` which checks `code:ensure_loaded/1` - Validates behaviour callbacks via module introspection

For non-BEAM apps (via sidecar or gRPC): - Use `verify_external_app/2` which probes HTTP/gRPC endpoints - Requires macula sidecar or compatible protocol implementation

See also: macula_authorization, macula_protocol.

# Summary

## Types

app_manifest/0
certificate/0

PEM-encoded

identity/0
validation_error/0
validation_result/0

## Functions

check_health(_)

Performs a health check on a verified app.

validate_operation(_, Operation, Resource)

Validates that an app can perform an operation.

verify_beam_app(Module, CertPem)

Verifies a BEAM app is mesh-worthy.

verify_beam_app(Module, CertPem, Node)
verify_callbacks(Module)
verify_certificate(CertPem, ExpectedIdentity)

Verifies a certificate and extracts identity.

verify_external_app(Endpoint, CertPem)

Verifies a non-BEAM app via HTTP/gRPC probes.

# Types

# app_manifest/0

    -type app_manifest() ::
              #{identity := identity(),
                capabilities := [macula_protocol:capability()],
                api := macula_protocol:api_spec(),
                certificate_fingerprint := binary(),
                verified_at := calendar:datetime()}.

# certificate/0

    -type certificate() :: binary().

PEM-encoded

# identity/0

    -type identity() :: binary().

# validation_error/0

    -type validation_error() ::
              no_macula_sdk | not_macula_app | behaviour_not_implemented | identity_mismatch |
              certificate_invalid | certificate_expired | certificate_revoked | health_check_failed |
              {validation_exception, term()}.

# validation_result/0

    -type validation_result() :: {ok, app_manifest()} | {error, validation_error()}.

# Functions

# check_health(_)

    -spec check_health(app_manifest()) -> ok | {error, term()}.

Performs a health check on a verified app.

# validate_operation(_, Operation, Resource)

    -spec validate_operation(app_manifest(), atom(), binary()) -> ok | {error, term()}.

Validates that an app can perform an operation.

# verify_beam_app(Module, CertPem)

    -spec verify_beam_app(module(), certificate()) -> validation_result().

Verifies a BEAM app is mesh-worthy.

# verify_beam_app(Module, CertPem, Node)

    -spec verify_beam_app(module(), certificate(), node()) -> validation_result().

# verify_callbacks(Module)

    -spec verify_callbacks(module()) -> ok | {error, term()}.

# verify_certificate(CertPem, ExpectedIdentity)

    -spec verify_certificate(certificate(), identity()) -> {ok, binary()} | {error, validation_error()}.

Verifies a certificate and extracts identity.

# verify_external_app(Endpoint, CertPem)

    -spec verify_external_app(uri_string:uri_string(), certificate()) -> validation_result().

Verifies a non-BEAM app via HTTP/gRPC probes.