yera.creds.auth

Credential group resolution, authorisation, and TOFU for tool credentials.

Symbols

def append_resolved_root_if_missing — Append the resolved project root if it is not already authorised canonically.

def authorised_credential_group_credentials — Return ``(store, credentials)`` for *group_name* after TOFU / authorisation.

def canonical_authorised_root_key — Return a normalised path string for comparing authorised roots.

def ensure_authorised_credential_store — Return *store* after ensuring *group_name* exists and the project root is authorised.

def ensure_credential_group_exists_and_authorised — Ensure *group_name* exists in *store* and the current root is authorised.

def is_authorised — Return True when the calling project root is authorised.

def project_root_authorised_in_roots — Return True when *project_root* is authorised (including ``'*'`` wildcard).

def require_resolved_credential_group — Return *resolved* or raise if no credential group is configured.

def resolve_active_credential_group — Resolve the active credential group name from ``pyproject.toml``.

class ResolvedCredentialGroup — Active credential group name from ``[tool.yera.overrides] cred-group``.

append_resolved_root_if_missing

append_resolved_root_if_missing(
    project_root: Path,
    authorised_roots: list[str],
) → bool

Append the resolved project root if it is not already authorised canonically.

Returns

type: bool

True when a new entry was appended (caller should persist the store).

authorised_credential_group_credentials

authorised_credential_group_credentials(
    store: CredentialStore,
    group_name: str,
    get_project_root: Callable[[], Path | None] = resolve_project_root,
) → tuple[CredentialStore, dict[str, dict[str, Any]]]

Return (store, credentials) for group_name after TOFU / authorisation.

canonical_authorised_root_key

canonical_authorised_root_key(
    path: Path | str,
) → str

Return a normalised path string for comparing authorised roots.

Resolves . / .., trailing separators, and symlinks so the same directory stored under different spellings matches.

ensure_authorised_credential_store

ensure_authorised_credential_store(
    store: CredentialStore,
    group_name: str,
    get_project_root: Callable[[], Path | None] = resolve_project_root,
) → CredentialStore

Return store after ensuring group_name exists and the project root is authorised.

ensure_credential_group_exists_and_authorised

ensure_credential_group_exists_and_authorised(
    store: CredentialStore,
    group_name: str,
    get_project_root: Callable[[], Path | None],
) → tuple[CredentialStore, bool]

Ensure group_name exists in store and the current root is authorised.

TOFU (Trust On First Use):

Group absent → create it, auto-add current project root to authorised_roots, return (store, True).
Group present, root authorised → return (store, False).
Group present, root NOT authorised → raise CredentialGroupNotAuthorisedError with the spec's recovery messaging.

Returns

type: CredentialStore

(store, was_created) — store is mutated in-place when a new group is created.

is_authorised

is_authorised(
    get_project_root: Callable[[], Path | None],
    authorised_roots: list[str],
) → bool

Return True when the calling project root is authorised.

The "*" sentinel is checked unconditionally first. get_project_root is only called when "*" is absent, so resolve_project_root() is never invoked in a deployed / CI context where the credential store carries ["*"].

project_root_authorised_in_roots

project_root_authorised_in_roots(
    project_root: Path | None,
    authorised_roots: list[str],
) → bool

Return True when project_root is authorised (including '*' wildcard).

require_resolved_credential_group

require_resolved_credential_group(
    resolved: ResolvedCredentialGroup | None,
) → ResolvedCredentialGroup

Return resolved or raise if no credential group is configured.

resolve_active_credential_group

resolve_active_credential_group() → ResolvedCredentialGroup | None

Resolve the active credential group name from pyproject.toml.

Reads non-empty cred-group under [tool.yera.overrides]. Whitespace-only values are treated as absent. When no pyproject.toml is found or no value is set → None.

ResolvedCredentialGroup

Active credential group name from [tool.yera.overrides] cred-group.

← back to docs