axm-vault 0.2.0

axm-vault — Credential catalogs, layered resolution and keyring storage

axm-vault separates credential declarations from value resolution and storage. Packages declare their needs; applications resolve values through environment, configuration and keyring layers, with optional prompts and Pydantic binding.

Features

• Value-less catalog — pydantic v2 models (Sensitivity, CredentialSpec, CredentialGroup) describe credential schema only; defaults and descriptions must contain no real secrets (this is a provider responsibility).
• Entry-point discovery — load_catalog() aggregates axm.credentials groups contributed by packages (empty-safe, cached).
• Layered resolution — Resolver walks env > file > keyring > default > prompt; the file tier is delegated to axm-config, the keyring tier is consulted only for SECRET specs.
• Typed binding — bind(model, group) builds a pydantic model from resolved values, wrapping SECRET fields as SecretStr and returning the concrete model type.
• Value-free doctor — doctor_data() / the vault_doctor tool report each credential's {layer, present} provenance without ever returning a secret.
• MCP tools — vault_doctor (provenance), vault_set (keyring/config), and vault_delete (keyring removal) ship as axm.tools (MCP + CLI + DAG node).
• Operator CLI — axm-vault exposes setup/get/set/rotate/delete/doctor/path; interactive setup is TTY-guarded and idempotent, get masks secrets unless --reveal.
• Frozen & strict — immutable models that forbid unknown fields (frozen=True, extra="forbid").

See the documentation for the full guide, including how to declare your package's credentials.

Installation

Requires Python 3.12 or newer. In a project managed by uv:

uv add axm-vault

Or as a workspace dependency in pyproject.toml:

[project]
dependencies = ["axm-vault"]

[tool.uv.sources]
axm-vault = { workspace = true }

Quick Start

Declare a credential schema and mask a synthetic value without consulting your configuration or keyring:

uv run python - <<'PY'
from axm_vault import CredentialGroup, CredentialSpec, as_secret

group = CredentialGroup(
    id="demo",
    package="demo-app",
    title="Demo service",
    specs=(CredentialSpec(name="token", env="DEMO_TOKEN", kind="token"),),
)
print(group.spec("token").env)
print(as_secret("synthetic-example"))
PY

This prints DEMO_TOKEN and **********. The declaration contains no credential value. Creating a group does not register it with the installed catalog; follow Declare credentials to contribute a provider. For actual resolution with isolated stores, use the synthetic credential tutorial.

Usage

Python API

Use Resolver.resolve(group, name) with an explicit group, or catalog-based get(group, name) and bind(model, group) after registering a provider. load_catalog() discovers installed axm.credentials entry points and caches the catalog. Consumer models used with bind() must accept SecretStr for SECRET fields.

CLI and AXM tools

uv run axm-vault --help
uv run axm vault_doctor --help

The operator CLI provides setup, get, set, rotate, delete, doctor and path. Interactive setup requires a TTY; blank input preserves existing values. Omit the value argument from standalone set or rotate to enter it through a hidden prompt instead of shell history or process arguments.

The vault_doctor, vault_set and vault_delete tools also support the generic axm CLI and MCP discovery. vault_set requires a value argument and has no hidden-input mode. See the CLI reference for parameters.

Security and operational boundaries

Resolver.resolve() and get() return plaintext; bind() wraps SECRET fields in SecretStr when the consumer model accepts that type. Provenance omits resolved values but reads the underlying stores. File resolution applies to all sensitivities, and arbitrary provider/backend errors are not redacted. See the security and I/O boundaries.

The selected keyring backend determines storage protection; SecretStr masks representations, it does not encrypt data. Deletion removes a keyring slot, leaving file/environment overrides and the rotation backup intact. Authentication dependencies are separate from credential provenance: vault_doctor does not check authentication sessions; axm-doctor consumes those status descriptors.

Documentation

• Published documentation
• Isolated getting-started tutorial
• Declare package credentials
• Resolver
• Doctor and tools
• Architecture and security boundaries

The README is the repository entry point; docs/index.md is the MkDocs home page.

Development

This package is part of the axm-forge uv workspace.

git clone https://github.com/axm-protocols/axm-forge.git
cd axm-forge
uv sync --all-packages --all-groups

# Run tests for this package
uv run --package axm-vault --directory packages/axm-vault pytest -x -q

# Build this package's documentation
uv run --package axm-vault --directory packages/axm-vault --group docs mkdocs build --strict

License

Licensed under Apache-2.0. See LICENSE.