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 segment forwarded to the probe.	`None`

Returns:

Name	Type	Description
`A`	`Provenance`	data:`Provenance` mapping `"group.name"` to `{layer, present}`.
	`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
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 segment forwarded to the probe.

    Returns:
        A :data:`Provenance` mapping ``"group.name"`` to ``{layer, present}``.
        ``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:
        for spec in group.specs:
            report[f"{group.id}.{spec.name}"] = _probe(
                resolver, group, spec, instance, keyring_ok=keyring_ok
            )
    return report