intflow-authctl 0.2.1__tar.gz → 0.2.3__tar.gz

intflow_authctl-0.2.3/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: intflow-authctl
+Version: 0.2.3
+Summary: Intflow Auth operator CLI.
+Author: Intflow
+License: Proprietary
+Requires-Python: >=3.12
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: keyring<26,>=25
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == 'dev'
+Requires-Dist: hatchling==1.31.0; extra == 'dev'
+Requires-Dist: mypy<3,>=1.13; extra == 'dev'
+Requires-Dist: packaging<27,>=24; extra == 'dev'
+Requires-Dist: pytest-cov<8,>=6; extra == 'dev'
+Requires-Dist: pytest-timeout<3,>=2.4; extra == 'dev'
+Requires-Dist: pytest<10,>=8; extra == 'dev'
+Requires-Dist: ruff<1,>=0.9; extra == 'dev'
+Requires-Dist: twine<7,>=6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# intflow-authctl
+
+Intflow Auth 운영자용 CLI의 Python 배포판입니다. 권한을 받은 운영자가 사용자, OAuth client, 운영자 토큰, 감사 기록을 관리할 때 씁니다. 서비스 자체나 데이터베이스 migration은 들어 있지 않습니다.
+
+## 요구 사항
+
+- Python 3.12 이상
+- Intflow Auth `operator` 또는 `admin` 역할
+
+## 설치
+
+```bash
+python -m pip install --user --upgrade intflow-authctl
+```
+
+## 사용 예
+
+```bash
+intflow-authctl login
+intflow-authctl whoami
+intflow-authctl clients list
+intflow-authctl clients rotate-secret <oauth-client-id> --secret-file /private/rotation.json
+intflow-authctl logout --revoke
+```
+
+로그인한 운영자 신원과 client 목록을 확인합니다. 교체한 client secret은 `--secret-file`로 지정한 보호된 새 파일에만 저장되고, `logout --revoke`는 서버 토큰도 폐기합니다. 운영자 자격증명은 지원되는 OS 자격증명 저장소에 둡니다.
+
+## 문서
+
+- 명령과 옵션: `intflow-authctl --help`와 `intflow-authctl docs`, 접근 진단은 `intflow-authctl doctor`
+- 상세 문서: 저장소 `yeon3724/intflow-auth`의 `docs/operations.md` (Routine administration, 영어)
+- 저장소: `yeon3724/intflow-auth` (읽기 전용 미러 `intflow/intflow-auth`)

intflow_authctl-0.2.3/README.md

@@ -0,0 +1,32 @@
+# intflow-authctl
+
+Intflow Auth 운영자용 CLI의 Python 배포판입니다. 권한을 받은 운영자가 사용자, OAuth client, 운영자 토큰, 감사 기록을 관리할 때 씁니다. 서비스 자체나 데이터베이스 migration은 들어 있지 않습니다.
+
+## 요구 사항
+
+- Python 3.12 이상
+- Intflow Auth `operator` 또는 `admin` 역할
+
+## 설치
+
+```bash
+python -m pip install --user --upgrade intflow-authctl
+```
+
+## 사용 예
+
+```bash
+intflow-authctl login
+intflow-authctl whoami
+intflow-authctl clients list
+intflow-authctl clients rotate-secret <oauth-client-id> --secret-file /private/rotation.json
+intflow-authctl logout --revoke
+```
+
+로그인한 운영자 신원과 client 목록을 확인합니다. 교체한 client secret은 `--secret-file`로 지정한 보호된 새 파일에만 저장되고, `logout --revoke`는 서버 토큰도 폐기합니다. 운영자 자격증명은 지원되는 OS 자격증명 저장소에 둡니다.
+
+## 문서
+
+- 명령과 옵션: `intflow-authctl --help`와 `intflow-authctl docs`, 접근 진단은 `intflow-authctl doctor`
+- 상세 문서: 저장소 `yeon3724/intflow-auth`의 `docs/operations.md` (Routine administration, 영어)
+- 저장소: `yeon3724/intflow-auth` (읽기 전용 미러 `intflow/intflow-auth`)

{intflow_authctl-0.2.1 → intflow_authctl-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "intflow-authctl"
-version = "0.2.1"
+version = "0.2.3"
 description = "Intflow Auth operator CLI."
 readme = "README.md"
 requires-python = ">=3.12"

intflow_authctl-0.2.3/src/intflow_authctl/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.3"

{intflow_authctl-0.2.1 → intflow_authctl-0.2.3}/src/intflow_authctl/api_client.py

@@ -1,12 +1,10 @@
-"""HTTP transport helpers for the Intflow Auth operator CLI."""
-
 import re
 
 import httpx
 
 from intflow_authctl.constants import DEFAULT_AUTHCTL_TIMEOUT_SECONDS
 from intflow_authctl.discovery import permission_hint
-from intflow_authctl.errors import AuthctlError
+from intflow_authctl.errors import AuthctlError, AuthctlHttpError
 from intflow_authctl.validation import _normalize_base_url
 
 MAX_RETRY_AFTER_SECONDS = 86_400
@@ -46,6 +44,7 @@ def _api_request_without_auth(
     *,
     client_factory,
     json_body: dict[str, object] | None = None,
+    timeout_seconds: float = DEFAULT_AUTHCTL_TIMEOUT_SECONDS,
 ) -> dict[str, object]:
     return _api_request_to_base_url(
         base_url,
@@ -55,6 +54,7 @@ def _api_request_without_auth(
         json_body=json_body,
         params=None,
         client_factory=client_factory,
+        timeout_seconds=timeout_seconds,
     )
 
 
@@ -67,13 +67,14 @@ def _api_request_to_base_url(
     client_factory,
     json_body: dict[str, object] | None,
     params: dict[str, object] | None,
+    timeout_seconds: float = DEFAULT_AUTHCTL_TIMEOUT_SECONDS,
 ) -> dict[str, object]:
     base_url = _normalize_base_url(base_url)
     try:
         with client_factory(
             base_url=base_url,
             headers=headers,
-            timeout=DEFAULT_AUTHCTL_TIMEOUT_SECONDS,
+            timeout=min(timeout_seconds, DEFAULT_AUTHCTL_TIMEOUT_SECONDS),
         ) as client:
             request_kwargs: dict[str, object] = {"params": params}
             if json_body is not None:
@@ -93,10 +94,12 @@ def _api_request_to_base_url(
     if response.status_code >= 400:
         retry_after = _retry_after_seconds(response.headers.get("retry-after"))
         retry_message = "" if retry_after is None else f" Retry after {retry_after} seconds."
-        raise AuthctlError(
+        raise AuthctlHttpError(
             f"Admin API request failed: {response.status_code} "
             f"{_safe_error_message(response)}.{retry_message}"
-            f"{permission_hint(response.status_code, method, path)}"
+            f"{permission_hint(response.status_code, method, path)}",
+            response.status_code,
+            retry_after,
         )
     if response.status_code == 204 or not response.content:
         return {"status": "ok"}

{intflow_authctl-0.2.1 → intflow_authctl-0.2.3}/src/intflow_authctl/audit.py

@@ -1,5 +1,3 @@
-"""Audit-event command handlers for authctl."""
-
 import argparse
 
 from intflow_authctl.api_client import _api_request

{intflow_authctl-0.2.1 → intflow_authctl-0.2.3}/src/intflow_authctl/cli.py

@@ -1,5 +1,3 @@
-"""Operator Admin API command-line entry point."""
-
 import sys
 from typing import TextIO
 
@@ -39,7 +37,7 @@ def authctl_main(
     client_factory=httpx.Client,
     credential_store: AuthctlCredentialStore | None = None,
 ) -> None:
-    """Run the routine operator Admin API CLI."""
+
     parser = _build_authctl_parser()
     args = parser.parse_args(argv)
     try:

{intflow_authctl-0.2.1 → intflow_authctl-0.2.3}/src/intflow_authctl/clients.py

@@ -1,5 +1,3 @@
-"""OAuth client command handlers for authctl."""
-
 import argparse
 
 from intflow_authctl.api_client import _api_request
@@ -63,6 +61,8 @@ def _run_authctl_clients_command(
         }
         if args.admin_access_required:
             create_body["admin_access_required"] = True
+        if args.assignment_required:
+            create_body["assignment_required"] = True
         return with_secret_file(
             args.secret_file,
             lambda: _api_request(
@@ -89,6 +89,10 @@ def _run_authctl_clients_command(
             update_body["admin_access_required"] = True
         if args.no_admin_access_required:
             update_body["admin_access_required"] = False
+        if args.assignment_required:
+            update_body["assignment_required"] = True
+        if args.no_assignment_required:
+            update_body["assignment_required"] = False
         if not update_body:
             raise AuthctlError("At least one client update field is required.")
         return _api_request(
@@ -123,6 +127,18 @@ def _run_authctl_clients_command(
             config,
             client_factory=client_factory,
         )
+    if args.clients_command == "roles":
+        return _run_authctl_client_roles_command(
+            args,
+            config,
+            client_factory=client_factory,
+        )
+    if args.clients_command == "pending-roles":
+        return _run_authctl_client_pending_roles_command(
+            args,
+            config,
+            client_factory=client_factory,
+        )
     raise AuthctlError(f"Unsupported clients command: {args.clients_command}")
 
 
@@ -158,6 +174,65 @@ def _run_authctl_client_admins_command(
     raise AuthctlError(f"Unsupported clients admins command: {args.client_admins_command}")
 
 
+def _run_authctl_client_roles_command(
+    args: argparse.Namespace,
+    config: dict[str, object],
+    *,
+    client_factory,
+) -> dict[str, object]:
+    base_path = f"/v1/admin/clients/{args.client_id}"
+    if args.client_roles_command == "list":
+        return _api_request(
+            config,
+            "GET",
+            f"{base_path}/role-assignments",
+            params=_request_params(args, "limit", "cursor", extra={"role_name": args.role}),
+            client_factory=client_factory,
+        )
+    if args.client_roles_command in {"grant", "revoke"}:
+        return _api_request(
+            config,
+            "PUT" if args.client_roles_command == "grant" else "DELETE",
+            f"{base_path}/roles/{args.role_name}/users/{args.user_id}",
+            client_factory=client_factory,
+        )
+    raise AuthctlError(f"Unsupported clients roles command: {args.client_roles_command}")
+
+
+def _run_authctl_client_pending_roles_command(
+    args: argparse.Namespace,
+    config: dict[str, object],
+    *,
+    client_factory,
+) -> dict[str, object]:
+    base_path = f"/v1/admin/clients/{args.client_id}/pending-role-grants"
+    command = args.client_pending_roles_command
+    if command == "list":
+        return _api_request(
+            config,
+            "GET",
+            base_path,
+            params=_request_params(args, "email", "limit", "cursor"),
+            client_factory=client_factory,
+        )
+    if command == "create":
+        return _api_request(
+            config,
+            "POST",
+            base_path,
+            json_body={"email": args.email, "role_name": args.role_name},
+            client_factory=client_factory,
+        )
+    if command == "delete":
+        return _api_request(
+            config,
+            "DELETE",
+            f"{base_path}/{args.grant_id}",
+            client_factory=client_factory,
+        )
+    raise AuthctlError(f"Unsupported clients pending-roles command: {command}")
+
+
 def _validate_cli_redirect_uris(values: list[str]) -> tuple[str, ...]:
     try:
         return validate_redirect_uris(values)

{intflow_authctl-0.2.1 → intflow_authctl-0.2.3}/src/intflow_authctl/command_utils.py

@@ -1,5 +1,3 @@
-"""Shared helpers for authctl command-family modules."""
-
 import argparse
 
 from intflow_authctl.output import _response_list
@@ -10,11 +8,7 @@ def _request_params(
     *names: str,
     extra: dict[str, object] | None = None,
 ) -> dict[str, object] | None:
-    params = {
-        name: value
-        for name in names
-        if (value := getattr(args, name, None)) is not None
-    }
+    params = {name: value for name in names if (value := getattr(args, name, None)) is not None}
     if extra is not None:
         params.update({name: value for name, value in extra.items() if value is not None})
     return params or None

{intflow_authctl-0.2.1 → intflow_authctl-0.2.3}/src/intflow_authctl/commands.py

@@ -1,6 +1,5 @@
-"""Command dispatch for the Intflow Auth operator CLI."""
-
 import argparse
+import math
 import os
 import time
 import webbrowser
@@ -17,13 +16,14 @@ from intflow_authctl.clients import _run_authctl_clients_command
 from intflow_authctl.config import (
     _authctl_config_path,
     _authctl_credential_store,
+    _check_credential_storage,
     _delete_authctl_config,
     _load_authctl_config,
     _save_authctl_config,
 )
 from intflow_authctl.credentials import AuthctlCredentialStore
 from intflow_authctl.discovery import documentation
-from intflow_authctl.errors import AuthctlError
+from intflow_authctl.errors import AuthctlError, AuthctlHttpError
 from intflow_authctl.external_access import _run_authctl_external_access_command
 from intflow_authctl.tokens import _run_authctl_tokens_command
 from intflow_authctl.users import _run_authctl_users_command
@@ -51,6 +51,7 @@ def _run_authctl_command(
             webbrowser.open(str(result["api_docs"]))
         return result
     if args.command == "login":
+        _check_credential_storage(config_path, selected_credential_store)
         if args.token is not None:
             print(
                 "WARNING: --token is deprecated because command arguments may enter "
@@ -76,9 +77,9 @@ def _run_authctl_command(
         )
 
     if args.command == "logout":
-        config = _load_authctl_config(config_path, selected_credential_store)
-        _warn_if_file_config(config, config_path, error_output)
         if args.revoke:
+            config = _load_authctl_config(config_path, selected_credential_store)
+            _warn_if_file_config(config, config_path, error_output)
             token_id = config.get("token_id")
             if not isinstance(token_id, str) or not token_id:
                 whoami = _api_request(
@@ -104,6 +105,17 @@ def _run_authctl_command(
         _delete_authctl_config(config_path, selected_credential_store)
         return {"status": "logged_out"}
 
+    if args.command == "doctor" and args.check_store:
+        _check_credential_storage(config_path, selected_credential_store)
+        return {
+            "status": "ok",
+            "checks": ["config_writable", "credential_store_probe"],
+            "credential_backend": (
+                selected_credential_store.backend_name if selected_credential_store else "file"
+            ),
+            "next": "intflow-authctl login",
+        }
+
     config = _load_authctl_config(config_path, selected_credential_store)
     _warn_if_file_config(config, config_path, error_output)
     if args.command in {"whoami", "doctor"}:
@@ -207,6 +219,9 @@ def _run_authctl_browser_login(
 ) -> dict[str, object]:
     base_url = _normalize_base_url(args.base_url)
     ttl_seconds = _parse_ttl_seconds(args.ttl)
+    timeout = _positive_float(args.timeout_seconds, "timeout-seconds")
+    if not math.isfinite(args.poll_interval):
+        raise AuthctlError("poll-interval must be finite.")
     start_body: dict[str, object] = {
         "name": args.name,
         "ttl_seconds": ttl_seconds,
@@ -227,28 +242,57 @@ def _run_authctl_browser_login(
     if not args.no_browser:
         webbrowser.open(verification_uri)
 
-    deadline = time.monotonic() + _positive_float(args.timeout_seconds, "timeout-seconds")
-    poll_interval = max(args.poll_interval, 0.0)
+    deadline = time.monotonic() + timeout
+    advertised = transaction.get("poll_interval_seconds")
+    server_interval = (
+        float(advertised)
+        if isinstance(advertised, (float, int)) and math.isfinite(advertised) and advertised > 0
+        else 2.0
+    )
+    poll_interval = max(args.poll_interval, server_interval, 1.0)
     while True:
-        response = _api_request_without_auth(
-            base_url,
-            "POST",
-            f"/v1/cli-login-transactions/{transaction_id}:redeem",
-            json_body={"poll_secret": poll_secret},
-            client_factory=client_factory,
-        )
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            raise AuthctlError("CLI login timed out before browser approval completed.")
+        try:
+            response = _api_request_without_auth(
+                base_url,
+                "POST",
+                f"/v1/cli-login-transactions/{transaction_id}:redeem",
+                json_body={"poll_secret": poll_secret},
+                client_factory=client_factory,
+                timeout_seconds=remaining,
+            )
+        except AuthctlHttpError as exc:
+            if exc.status != 429:
+                raise
+            delay = max(poll_interval, exc.retry_after or server_interval)
+            print(
+                "Login polling was rate limited; waiting within the login deadline.",
+                file=error_output,
+            )
+            time.sleep(min(delay, max(deadline - time.monotonic(), 0.0)))
+            continue
         if response.get("status") != "pending":
             token = _required_response_string(response, "token")
             operator_token = response.get("operator_token")
             config: dict[str, object] = {"base_url": base_url, "token": token}
             if isinstance(operator_token, dict) and operator_token.get("id"):
                 config["token_id"] = str(operator_token["id"])
-            _save_authctl_config(
-                config_path,
-                config,
-                token=token,
-                credential_store=credential_store,
-            )
+            try:
+                _save_authctl_config(
+                    config_path,
+                    config,
+                    token=token,
+                    credential_store=credential_store,
+                )
+            except (AuthctlError, OSError):
+                raise AuthctlError(
+                    "Login token was issued but local storage failed. Run doctor --check-store, "
+                    "then log in again; inspect tokens list and explicitly revoke "
+                    "the unused token. "
+                    "No token was printed or automatically revoked."
+                ) from None
             return {
                 "status": "logged_in",
                 "base_url": base_url,

{intflow_authctl-0.2.1 → intflow_authctl-0.2.3}/src/intflow_authctl/config.py

@@ -1,5 +1,3 @@
-"""Credential configuration helpers for the Intflow Auth operator CLI."""
-
 import argparse
 import json
 import os
@@ -72,9 +70,7 @@ def _load_authctl_config(
     if not isinstance(service, str) or not isinstance(account, str):
         raise AuthctlError(f"Invalid CLI config file: {path}")
     if credential_store is None:
-        raise AuthctlError(
-            "CLI config uses an OS credential store; use --credential-store auto."
-        )
+        raise AuthctlError("CLI config uses an OS credential store; use --credential-store auto.")
     store = credential_store
     if backend != store.backend_name:
         raise AuthctlError(f"Invalid CLI config file: {path}")
@@ -95,9 +91,11 @@ def _save_authctl_config(
     token: str,
     credential_store: AuthctlCredentialStore | None,
 ) -> None:
+    previous = _load_raw_authctl_config(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
     stored_config = dict(config)
     stored_config.pop("token", None)
-    credential_account = _credential_account(stored_config)
+    credential_account = f"{_credential_account(stored_config)}|local-{secrets.token_hex(16)}"
     secret_stored = False
     if credential_store is not None:
         try:
@@ -112,6 +110,7 @@ def _save_authctl_config(
                     "credential_backend": credential_store.backend_name,
                     "credential_service": AUTHCTL_CREDENTIAL_SERVICE,
                     "credential_account": credential_account,
+                    "credential_owner": _config_owner(path),
                 }
             )
         except AuthctlCredentialStoreError as exc:
@@ -122,7 +121,6 @@ def _save_authctl_config(
     else:
         stored_config.update({"credential_backend": "file", "token": token})
 
-    path.parent.mkdir(parents=True, exist_ok=True)
     temporary_path = path.with_name(f".{path.name}.{secrets.token_hex(8)}.tmp")
     replaced = False
     try:
@@ -150,7 +148,72 @@ def _save_authctl_config(
         if secret_stored and credential_store is not None:
             with suppress(AuthctlCredentialStoreError):
                 credential_store.delete_password(AUTHCTL_CREDENTIAL_SERVICE, credential_account)
-        raise
+        raise AuthctlError(
+            "Could not save CLI configuration; the previous login was retained where possible."
+        ) from None
+    if (
+        previous
+        and previous.get("credential_account")
+        and previous.get("credential_backend") != "file"
+    ):
+        if (
+            credential_store is not None
+            and previous.get("credential_backend") == credential_store.backend_name
+            and previous.get("credential_owner") == _config_owner(path)
+            and previous.get("credential_service") == AUTHCTL_CREDENTIAL_SERVICE
+        ):
+            try:
+                credential_store.delete_password(
+                    AUTHCTL_CREDENTIAL_SERVICE, str(previous["credential_account"])
+                )
+            except AuthctlCredentialStoreError:
+                _storage_warning(
+                    "Login saved, but the previous local credential could not be removed."
+                )
+        else:
+            _storage_warning(
+                "Previous legacy/shared credential retained to protect other profiles."
+            )
+
+
+def _storage_warning(message: str) -> None:
+
+    import sys
+
+    print(f"WARNING: {message} Remote tokens were not revoked.", file=sys.stderr)
+
+
+def _config_owner(path: Path) -> str:
+    return os.path.normcase(os.path.abspath(path))
+
+
+def _check_credential_storage(path: Path, store: AuthctlCredentialStore | None) -> None:
+    probe = f"probe-{secrets.token_hex(16)}"
+    temporary = path.parent / f".authctl-{probe}"
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        if path.exists() and not path.is_file():
+            raise OSError("Not a file")
+        descriptor = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+        with os.fdopen(descriptor, "w") as probe_file:
+            probe_file.write(probe)
+            probe_file.flush()
+            os.fsync(probe_file.fileno())
+        if store is not None:
+            try:
+                store.set_password(AUTHCTL_CREDENTIAL_SERVICE, probe, probe)
+                if store.get_password(AUTHCTL_CREDENTIAL_SERVICE, probe) != probe:
+                    raise AuthctlCredentialStoreError("Probe failed")
+            finally:
+                store.delete_password(AUTHCTL_CREDENTIAL_SERVICE, probe)
+    except (OSError, AuthctlCredentialStoreError):
+        raise AuthctlError(
+            "Credential storage is unavailable; no login request was sent. Check config directory "
+            "and OS keyring, or explicitly select --credential-store file if acceptable."
+        ) from None
+    finally:
+        with suppress(OSError):
+            temporary.unlink(missing_ok=True)
 
 
 def _delete_authctl_config(
@@ -168,7 +231,8 @@ def _delete_authctl_config(
                 )
             store = credential_store
             try:
-                store.delete_password(service, account)
+                if store.get_password(service, account) is not None:
+                    store.delete_password(service, account)
             except AuthctlCredentialStoreError as exc:
                 raise AuthctlError(
                     "Stored CLI credential could not be deleted; local config was retained."

{intflow_authctl-0.2.1 → intflow_authctl-0.2.3}/src/intflow_authctl/constants.py

@@ -1,5 +1,3 @@
-"""Constants for the Intflow Auth operator CLI."""
-
 AUTHCTL_CONFIG_ENV = "INTFLOW_AUTHCTL_CONFIG"
 AUTHCTL_CREDENTIAL_SERVICE = "intflow-authctl"
 DEFAULT_AUTHCTL_BASE_URL = "https://id.intflow.dev"

{intflow_authctl-0.2.1 → intflow_authctl-0.2.3}/src/intflow_authctl/credentials.py

@@ -1,49 +1,43 @@
-"""Credential-store adapters for the intflow-authctl CLI."""
-
 from importlib import import_module
 from typing import Protocol
 
 
 class AuthctlCredentialStore(Protocol):
-    """Minimal credential-store interface used by intflow-authctl."""
-
     backend_name: str
 
     def get_password(self, service: str, account: str) -> str | None:
-        """Return one stored secret or None."""
+        pass
 
     def set_password(self, service: str, account: str, password: str) -> None:
-        """Store one secret."""
+        pass
 
     def delete_password(self, service: str, account: str) -> None:
-        """Delete one secret."""
+        pass
 
 
 class AuthctlCredentialStoreError(RuntimeError):
-    """Raised when a credential-store backend is unavailable or fails."""
+    pass
 
 
 class KeyringAuthctlCredentialStore:
-    """Credential-store adapter backed by the optional keyring package."""
-
     backend_name = "keyring"
 
     def get_password(self, service: str, account: str) -> str | None:
-        """Return one stored secret or None."""
+
         try:
             return self._keyring().get_password(service, account)
         except Exception as exc:
             raise AuthctlCredentialStoreError("Credential store lookup failed.") from exc
 
     def set_password(self, service: str, account: str, password: str) -> None:
-        """Store one secret."""
+
         try:
             self._keyring().set_password(service, account, password)
         except Exception as exc:
             raise AuthctlCredentialStoreError("Credential store write failed.") from exc
 
     def delete_password(self, service: str, account: str) -> None:
-        """Delete one secret."""
+
         try:
             self._keyring().delete_password(service, account)
         except Exception as exc:

{intflow_authctl-0.2.1 → intflow_authctl-0.2.3}/src/intflow_authctl/discovery.py

@@ -1,4 +1,7 @@
-"""Offline onboarding and locally authored permission guidance."""
+def _is_app_role_path(path: str) -> bool:
+    return any(
+        part in path for part in ("/admins", "/roles/", "/role-assignments", "/pending-role-grants")
+    )
 
 
 def permission_hint(status: int, method: str, path: str) -> str:
@@ -8,7 +11,7 @@ def permission_hint(status: int, method: str, path: str) -> str:
         return ""
     resource = None
     if path.startswith("/v1/admin/clients"):
-        resource = "app_roles" if "/admins" in path else "clients"
+        resource = "app_roles" if _is_app_role_path(path) else "clients"
     elif path.startswith("/v1/admin/operator-tokens"):
         resource = "tokens"
     elif path.startswith("/v1/admin/audit"):

intflow_authctl-0.2.3/src/intflow_authctl/errors.py

@@ -0,0 +1,9 @@
+class AuthctlError(RuntimeError):
+    pass
+
+
+class AuthctlHttpError(AuthctlError):
+    def __init__(self, message: str, status: int, retry_after: int | None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.retry_after = retry_after