Search documentation of macula

# macula_foundation (macula v4.4.1)

View Source

Foundation trust anchor — firmware-embedded pubkeys for the Macula Foundation FROST-Ed25519 aggregated signer.

The Foundation signs Tier A seed lists, protocol parameters, realm trust lists, and T3 attestations (Part 6 §9.14–§9.17). Stations verify those records against a small, firmware-embedded set of foundation pubkeys — the root of trust for the Tier A bootstrap path (Part 5 §4).

### Custodians

Production deployments embed five foundation pubkeys, each held by an independent custodian. FROST m-of-n thresholds keep the signing key resilient: any m custodians can sign, no single custodian can unilaterally authorise a record. See Part 5 §12.

### Rotation

Replacing an embedded pubkey requires a firmware update. The existing record cache survives rotation — records signed by a retired key remain valid until their `valid_until` elapses.

### Placeholders

The five keys returned by `pubkeys/0` at the time of this writing are deterministic placeholders (`&lt;&lt;"macula-v2-foundation-*"&gt;&gt;` SHA-256 digests). They are NOT backed by live FROST shares. Any record signed against a placeholder will fail verification because no corresponding private key exists. Production firmware MUST override `pubkeys/0` via `application:set_env(macula_record, foundation_pubkeys, [...])` before any Tier A record is trusted.

Callers that need to operate strictly against the live keys should use `live_pubkeys/0`, which returns the app-env override or an empty list (never the placeholders).

Reference: plans/PLAN_MACULA_V2_PART5_BOOTSTRAP.md §4, §12; plans/PLAN_MACULA_V2_PART6_PROTOCOL.md §9.14–§9.17.

# Summary

## Types

pubkey/0
verify_error/0

## Functions

is_foundation(Key)

True iff `Key` is one of the trusted foundation pubkeys.

live_pubkeys()

Return live (non-placeholder) foundation pubkeys, or `[]`.

placeholder_mode()

`true` iff the running station is using placeholder keys.

placeholder_pubkeys()

Placeholder foundation pubkeys — deterministic, publicly derivable, NOT backed by any private key. Production firmware MUST override via app env before any Tier A record is consumed.

pubkeys()

Return the current foundation pubkey list.

verify_record(Record)

Verify a foundation-signed record.

# Types

# pubkey/0

    -type pubkey() :: macula_identity:pubkey().

# verify_error/0

    -type verify_error() :: bad_record | signature_invalid | expired | not_foundation_signed | wrong_type.

# Functions

# is_foundation(Key)

    -spec is_foundation(binary()) -> boolean().

True iff `Key` is one of the trusted foundation pubkeys.

# live_pubkeys()

    -spec live_pubkeys() -> [pubkey()].

Return live (non-placeholder) foundation pubkeys, or `[]`.

Use this when callers must refuse to trust placeholder keys — e.g. production bootstrap paths that would otherwise accept a record signed by no real private key.

# placeholder_mode()

    -spec placeholder_mode() -> boolean().

`true` iff the running station is using placeholder keys.

Production code should refuse to bootstrap under `true` — see `live_pubkeys/0`.

# placeholder_pubkeys()

    -spec placeholder_pubkeys() -> [pubkey()].

Placeholder foundation pubkeys — deterministic, publicly derivable, NOT backed by any private key. Production firmware MUST override via app env before any Tier A record is consumed.

# pubkeys()

    -spec pubkeys() -> [pubkey()].

Return the current foundation pubkey list.

Resolution order:

1. `application:get_env(macula_record, foundation_pubkeys, [])` if non-empty — production-embedded keys.
2. Deterministic placeholder keys from `placeholder_pubkeys/0` — development / test only.

# verify_record(Record)

    -spec verify_record(macula_record:record()) -> {ok, macula_record:record()} | {error, verify_error()}.

Verify a foundation-signed record.

Succeeds iff the record type is one of the foundation tags (`0x0D–0x10`), the envelope `k` field is a trusted foundation pubkey, and the signature + expiry pass `macula_record:verify/1`.