mxm-secrets

Typed, authorization-aware secret resolution for the Money Ex Machina ecosystem.

mxm-secrets resolves public secret names into backend secret values using configured secret references, stores, policies, and runtime identity.

The package provides the Resolution layer of the MXM Runtime Context Architecture.

Purpose

mxm-secrets exists to separate:

application code

from:

secret storage
authorization
runtime identity
secret resolution

Applications should never:

• hardcode secret values,
• depend on gopass paths,
• implement authorization logic,
• or perform secret discovery themselves.

Instead, applications request secrets through a configured API:

secret = api.get_secret(
    secret_name="databento_api_key",
    identity=runtime_identity,
)

The package then:

resolves the secret reference
derives the principal
evaluates authorization
resolves the backend location
retrieves the secret value

Architecture

mxm-secrets implements the Resolution layer:

RuntimeIdentity
    ↓
Principal
    ↓
SecretPolicy
    ↓
Authorization
    ↓
SecretRef
    ↓
SecretStore
    ↓
ResolvedSecretLocation
    ↓
Backend Retrieval

The package accepts plain configuration data and can construct configured registries and API instances from that data.

Configuration discovery and loading remain the responsibility of mxm-runtime and mxm-config.

mxm-runtime

which constructs configured API instances from configuration data.

Core Concepts

RuntimeIdentity

Represents the operational runtime requesting access.

Example:

machine      bridge
environment  dev
role         marketdata

Runtime identity is always supplied explicitly.

Principal

Represents the operational authority requesting a secret.

Examples:

marketdata
execution
research
human_admin

Principals are derived from runtime identity.

SecretRef

Represents a logical secret reference.

Example:

SecretRef(
    name="databento_api_key",
    store="red",
    path="marketdata/databento/api_key",
    policy="marketdata_access",
)

Applications depend on secret names rather than storage locations.

SecretStore

Represents a configured secret authority.

Example:

SecretStore(
    name="red",
    backend="gopass",
    root="mxm/red",
)

SecretPolicy

Represents authorization rules.

Example:

SecretPolicy(
    name="marketdata_access",
    allowed_principals=(
        "marketdata",
        "research",
    ),
)

Resolution Flow

A secret request follows the path:

secret_name
    ↓
SecretRefRegistry
    ↓
RuntimeIdentity
    ↓
Principal
    ↓
SecretPolicyRegistry
    ↓
Policy Evaluation
    ↓
SecretStoreRegistry
    ↓
ResolvedSecretLocation
    ↓
Secret Retrieval
    ↓
secret value

Unauthorized requests fail before backend retrieval occurs.

Installation

Install from PyPI:

poetry add mxm-secrets

Or install from source:

git clone https://github.com/moneyexmachina/mxm-secrets.git
cd mxm-secrets
poetry install

Usage

Constructing a SecretsApi

The package is intentionally explicit.

Callers construct registries and provide them to SecretsApi.

Example:

api = SecretsApi.from_config_data(
    {
        "stores": {...},
        "refs": {...},
        "policies": {...},
    }
)

Advanced callers may construct registries directly, but the preferred construction path is through configuration data.

Configuration Shape

The package accepts plain configuration data with the structure:

stores:
  red:
    backend: gopass
    root: mxm/red

refs:
  databento_api_key:
    store: red
    path: marketdata/databento/api_key
    policy: marketdata_access

policies:
  marketdata_access:
    allowed_principals:
      - marketdata
      - research

This configuration is typically loaded by mxm-runtime from mxm-config and passed to:

SecretsApi.from_config_data(...)

Retrieving a Secret

secret = api.get_secret(
    secret_name="databento_api_key",
    identity=runtime_identity,
)

Authorization is evaluated automatically before secret retrieval.

Backend Support

Current backend support:

The backend abstraction remains intentionally small.

Future backends may be added if required by MXM deployment architecture.

Security Model

mxm-secrets separates:

storage

from:

authorization

The existence of a secret in a backend does not imply authorization.

Authorization is evaluated through:

Principal
SecretPolicy
SecretPolicyRegistry

before retrieval occurs.

The package:

• does not cache secrets,
• does not preload secret collections,
• does not expose backend paths to applications,
• does not infer runtime identity,
• does not perform configuration discovery.

Relationship To mxm-runtime

mxm-secrets provides semantics.

mxm-runtime provides materialisation.

Responsibilities are separated:

mxm-config
    owns configuration data

mxm-secrets
    owns resolution and authorization semantics

mxm-runtime
    owns assembly and RuntimeContext construction

Applications are expected to consume configured APIs through:

RuntimeContext

rather than constructing production APIs directly.

Development

Install development dependencies:

poetry install

Run formatting:

make fmt

Run linting:

make lint

Run static typing:

make type

Run tests:

make test

Run full validation:

make check

Run MXM package compliance validation:

mxm-foundry check .

Testing

The test suite includes coverage for:

• secret references,
• secret stores,
• secret policies,
• principals,
• registries,
• policy evaluation,
• runtime identity mapping,
• secret resolution,
• backend retrieval,
• API orchestration,
• CLI diagnostics.

Tests are executed using:

pytest

Status

Current release status:

Resolution Layer Complete
Config-Driven Construction Complete
RuntimeContext Integration Pending

mxm-secrets now supports construction of configured registries and SecretsApi instances from plain configuration data.

RuntimeContext materialisation remains the responsibility of mxm-runtime.

License

MIT License. See LICENSE.

Links

• https://moneyexmachina.com
• https://www.gopass.pw
• https://keepachangelog.com
• https://semver.org