Skip to content

Doctor

doctor

Value-free credential provenance — the vault doctor.

:func:doctor_data answers a single question for every credential in the catalog: which layer would supply it, and is it present at all — WITHOUT ever reading or returning the value itself (security invariant AC2). It probes each resolution layer for presence only, reducing the probe to a boolean the instant a layer responds, so a plaintext secret never enters the report.

Provenance = dict[str, dict[str, str | bool]]

Per-credential report: {"group.name": {"layer": str, "present": bool}}.

For a SECRET spec whose keyring backend is unavailable (headless host), the entry additionally carries "keyring": "unavailable" so the doctor surfaces the outage rather than silently reporting the credential as merely missing.

doctor_data(package=None, *, catalog=None, instance=None)

Report the winning layer and presence of every credential, value-free.

Parameters:

Name Type Description Default
package str | None

When given, restrict the report to credential groups contributed by that package; otherwise cover the whole catalog.

 None
catalog Catalog | None

Catalog to inspect; defaults to the discovered :func:~axm_vault.catalog.load_catalog result.

 None
instance str | None

Optional multi-instance identity. When given, it takes precedence over instance discovery.

 None

Returns:

Name Type Description
A Provenance

data:Provenance mapping canonical keyring usernames to
Provenance

{layer, present}, with an instance segment for multi-instance groups.
Provenance

layer is the first probed layer to supply the credential, or
Provenance

"missing" when none does; present mirrors that. The value
Provenance

itself is NEVER included (security invariant).
Source code in packages/axm-vault/src/axm_vault/doctor.py
Python
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
def doctor_data(
    package: str | None = None,
    *,
    catalog: Catalog | None = None,
    instance: str | None = None,
) -> Provenance:
    """Report the winning layer and presence of every credential, value-free.

    Args:
        package: When given, restrict the report to credential groups
            contributed by that package; otherwise cover the whole catalog.
        catalog: Catalog to inspect; defaults to the discovered
            :func:`~axm_vault.catalog.load_catalog` result.
        instance: Optional multi-instance identity. When given, it takes
            precedence over instance discovery.

    Returns:
        A :data:`Provenance` mapping canonical keyring usernames to
        ``{layer, present}``, with an instance segment for multi-instance groups.
        ``layer`` is the first probed layer to supply the credential, or
        ``"missing"`` when none does; ``present`` mirrors that. The value
        itself is NEVER included (security invariant).
    """
    cat = catalog if catalog is not None else load_catalog()
    groups = cat.for_package(package) if package is not None else cat.groups()
    resolver = Resolver()
    keyring_ok = resolver.keyring_available()
    report: Provenance = {}
    for group in groups:
        report_instances: tuple[str | None, ...]
        if not group.multi:
            report_instances = (None,)
        elif instance is not None:
            report_instances = (instance,)
        else:
            discovered = list_instances(group)
            report_instances = tuple(discovered) if discovered else (None,)
        for report_instance in report_instances:
            for spec in group.specs:
                key = KeyringStore.username(group.id, spec.name, report_instance)
                report[key] = _probe(
                    resolver,
                    group,
                    spec,
                    report_instance,
                    keyring_ok=keyring_ok,
                )
    return report