mxm-secrets 0.2.0

Minimal secrets interface for Money Ex Machina, supporting gopass and env backends

mxm-secrets

A typed, minimal, pluggable Python interface for operational secret access within the Money Ex Machina ecosystem.

Built around explicit, scoped secret retrieval using gopass, with support for additional backends and deployment environments over time.

Purpose

mxm-secrets provides the canonical secret access layer for MXM packages.

The package exists to separate:

application code

from:

secret storage and operational credential management

MXM packages should never:

• hardcode secrets,
• preload global credential blobs,
• depend directly on backend implementations,
• or assume a particular secret storage mechanism.

Instead, packages retrieve secrets explicitly:

from mxm.secrets import get_secret

api_key = get_secret("prod/some-api-key")

This establishes:

• explicit dependency boundaries,
• process-local secret access,
• backend composability,
• operational portability,
• and testable infrastructure interfaces.

Philosophy

Explicit

Secrets must be requested individually by name.

No global credential injection or hidden runtime state.

Scoped

Each process retrieves only the secrets it requires.

Composable

Designed for Unix-style workflows, automation pipelines, REPLs, and distributed runtime environments.

Pluggable

Supports multiple backend implementations behind a stable API surface.

Minimal

Small dependency surface, strict typing, and reproducible operational behavior.

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

Python API

from mxm.secrets import get_secret

api_key = get_secret("mxm/dev/api-key")
smtp_password = get_secret("prod/smtp-password", default="changeme")

CLI Usage

Retrieve a secret:

python -m mxm.secrets get mxm/dev/api-key

With fallback value:

python -m mxm.secrets get mxm/dev/api-key --default "changeme"

Verbose mode:

python -m mxm.secrets get mxm/dev/api-key --verbose

Secret Resolution Logic

When:

get_secret("mxm/dev/api-key")

is called, the package attempts resolution using configured backends in priority order.

Current default order:

1. gopass
2. environment variables

Example:

mxm/dev/api-key

maps to:

gopass show mxm/dev/api-key

and environment fallback:

MXM_DEV_API_KEY

If no backend resolves the secret:

• the provided default value is returned,
• otherwise None.

Secret Store Layout

Typical gopass structure:

mxm/
├── prod/
│   └── email-password
├── dev/
│   └── test-api-key
├── runtime/
└── bootstrap/

Each subtree may use separate .gpg-id files for scoped access control.

Example:

gopass insert mxm/dev/test-api-key

---

Available Backends

Backend	Status	Description
gopass	Stable	Local encrypted secret storage via GPG
Environment	Stable	Environment variable fallback backend
age	Planned	File-based encrypted secret backend
Vault	Planned	Centralized secret infrastructure

Configuration

Current backend priority is statically defined inside the package.

Future versions will support configuration through:

mxm-config

Planned future capabilities:

• configurable backend ordering,
• runtime session backends,
• Vault integration,
• Age integration,
• deployment-specific backend chains.

Security Notes

mxm-secrets:

• does not cache secrets,
• does not preload credentials,
• does not globally export secrets,
• does not persist runtime secret state.

Secrets remain external to MXM repositories and operational codebases.

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:

• backend dispatch,
• gopass integration behavior,
• environment fallback logic,
• CLI functionality,
• typing and packaging integration.

Tests are executed using:

pytest

License

MIT License. See LICENSE.

Links

• Money Ex Machina
• gopass
• Keep a Changelog
• Semantic Versioning