rb-google-oauth 0.2.2__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,59 @@
1
+ """google-oauth — общая авторизация Google для CLI-инструментов.
2
+
3
+ Один набор ключей Google (сервисный аккаунт, API-ключи) — в общем слоте
4
+ keychain `google-oauth:*` для всех инструментов (gsc, …): вход в одном
5
+ авторизует остальные. Инструмент описывает себя `Profile` и получает:
6
+
7
+ - `GoogleAuth(profile)` — найти ключи (env инструмента → общие env → keychain),
8
+ выдать access token с автообновлением (`bearer().headers()`), API-ключ, статус;
9
+ - `CredentialStore(profile)` — keychain ОС + имена переменных окружения;
10
+ - `status` — отчёт для `<cli> auth status --json` по контракту §8 стандарта tools и
11
+ `health_check()` — делегат для `Provider.health_check()` инструментов по шаблону cli-generator;
12
+ - `make_auth_app(auth, output)` (модуль `auth_command`) — готовая Typer-команда
13
+ `auth login|logout|status [--check]`.
14
+
15
+ Без keychain (Linux-сервер, `doppler run`) всё работает от переменных окружения
16
+ (`GOOGLE_OAUTH_SERVICE_ACCOUNT_JSON`, `GOOGLE_OAUTH_<NAME>_API_KEY`, …).
17
+
18
+ Импорт не трогает сеть, keychain, google-auth и typer.
19
+ """
20
+
21
+ from __future__ import annotations
22
+
23
+ from .auth import AuthStatus, BearerToken, Found, GoogleAuth, parse_service_account, refresh_credentials
24
+ from .credentials import CredentialStore
25
+ from .errors import (
26
+ CliError,
27
+ CredentialStoreUnavailable,
28
+ CredentialsUnhealthy,
29
+ InvalidArguments,
30
+ NotAuthorized,
31
+ TokenRequestFailed,
32
+ )
33
+ from .profile import ApiKey, Profile
34
+ from .status import Health, Quota, credential_status, health_check, status_exit_code, status_problems, status_report
35
+
36
+ __all__ = [
37
+ "ApiKey",
38
+ "AuthStatus",
39
+ "BearerToken",
40
+ "CliError",
41
+ "CredentialStore",
42
+ "CredentialStoreUnavailable",
43
+ "CredentialsUnhealthy",
44
+ "Found",
45
+ "GoogleAuth",
46
+ "Health",
47
+ "InvalidArguments",
48
+ "NotAuthorized",
49
+ "Profile",
50
+ "Quota",
51
+ "TokenRequestFailed",
52
+ "credential_status",
53
+ "health_check",
54
+ "parse_service_account",
55
+ "refresh_credentials",
56
+ "status_exit_code",
57
+ "status_problems",
58
+ "status_report",
59
+ ]
google_oauth/auth.py ADDED
@@ -0,0 +1,235 @@
1
+ """Ключ сервисного аккаунта, API-ключи, access token и статус — всё неинтерактивно.
2
+
3
+ `google-auth` импортируется лениво (внутри функций): импорт пакета не тянет
4
+ его и не ходит ни в сеть, ни в keychain.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import json
10
+ from dataclasses import dataclass, field
11
+ from pathlib import Path
12
+ from typing import Any, Literal, NamedTuple
13
+
14
+ from .credentials import API_KEY, SERVICE_ACCOUNT, CredentialStore
15
+ from .errors import InvalidArguments, NotAuthorized, TokenRequestFailed
16
+ from .profile import Profile
17
+
18
+ Source = Literal["env", "file", "keychain"]
19
+
20
+
21
+ class Found(NamedTuple):
22
+ """Найденный секрет: значение, тип источника и откуда именно (имя переменной / путь / запись keychain)."""
23
+
24
+ value: str
25
+ source: Source
26
+ origin: str
27
+
28
+
29
+ @dataclass
30
+ class AuthStatus:
31
+ """Готовность авторизации без исключений — для `auth status` и `doctor` инструментов.
32
+
33
+ state: ok — ключ сервисного аккаунта есть и разбирается; missing — нет или
34
+ битый; expired — Google отверг ключ (только при check=True: без сети не узнать).
35
+ """
36
+
37
+ provider: str
38
+ state: Literal["ok", "missing", "expired"]
39
+ account: str | None = None # email сервисного аккаунта
40
+ source: Source | None = None
41
+ detail: str | None = None # почему не ok
42
+ api_keys: dict[str, bool] = field(default_factory=dict)
43
+
44
+ def to_dict(self) -> dict[str, Any]:
45
+ """Плоский JSON: {"<provider>": state, "<key>_key": bool, "account", "source", "detail"}."""
46
+ return {
47
+ self.provider: self.state,
48
+ **{f"{name}_key": present for name, present in self.api_keys.items()},
49
+ "account": self.account,
50
+ "source": self.source,
51
+ "detail": self.detail,
52
+ }
53
+
54
+
55
+ def parse_service_account(text: str) -> dict[str, Any]:
56
+ """Разобрать и проверить JSON ключа сервисного аккаунта; ошибка — InvalidArguments."""
57
+ try:
58
+ info = json.loads(text)
59
+ except ValueError as exc:
60
+ raise InvalidArguments(f"Ключ сервисного аккаунта — не JSON: {exc}") from exc
61
+ if not isinstance(info, dict) or info.get("type") != "service_account":
62
+ raise InvalidArguments('Это не ключ сервисного аккаунта: нужен JSON с "type": "service_account".')
63
+ missing = [f for f in ("client_email", "private_key", "token_uri") if not info.get(f)]
64
+ if missing:
65
+ raise InvalidArguments(f"В ключе сервисного аккаунта нет полей: {', '.join(missing)}.")
66
+ return info
67
+
68
+
69
+ def refresh_credentials(creds: Any, *, provider: str, action: str) -> str:
70
+ """Получить/обновить access token у Google. Отказ → NotAuthorized, сеть → TokenRequestFailed."""
71
+ import google.auth.exceptions
72
+ import google.auth.transport.requests
73
+
74
+ try:
75
+ creds.refresh(google.auth.transport.requests.Request())
76
+ except google.auth.exceptions.RefreshError as exc:
77
+ raise NotAuthorized(provider, f"Google отверг ключ сервисного аккаунта: {exc}", action=action) from exc
78
+ except google.auth.exceptions.TransportError as exc:
79
+ raise TokenRequestFailed(provider, f"не удалось получить токен: {exc}") from exc
80
+ return creds.token
81
+
82
+
83
+ class GoogleAuth:
84
+ """Всё об авторизации одного инструмента: найти ключи, выдать токен, сохранить, показать статус."""
85
+
86
+ def __init__(self, profile: Profile, store: CredentialStore | None = None) -> None:
87
+ self.profile = profile
88
+ self.store = store or CredentialStore(profile)
89
+
90
+ @property
91
+ def login_action(self) -> str:
92
+ return f"Выполните '{self.profile.login_cmd}'."
93
+
94
+ # --- сервисный аккаунт ---------------------------------------------------------
95
+
96
+ def find_service_account(self) -> Found | None:
97
+ """JSON ключа и откуда он, или None. Порядок: env с JSON → env с путём к файлу → keychain.
98
+
99
+ Содержимое не проверяет. Переменная с путём к несуществующему файлу — NotAuthorized.
100
+ """
101
+ env = self.store.first_env(self.store.service_account_json_env())
102
+ if env:
103
+ return Found(env[0], "env", env[1])
104
+ path_env = self.store.first_env(self.store.service_account_file_env())
105
+ if path_env:
106
+ file = Path(path_env[0]).expanduser()
107
+ if not file.is_file():
108
+ raise NotAuthorized(
109
+ self.profile.provider,
110
+ f"{path_env[1]} указывает на несуществующий файл: {file}",
111
+ action=self.login_action,
112
+ )
113
+ return Found(file.read_text(encoding="utf-8"), "file", str(file))
114
+ stored = self.store.get(SERVICE_ACCOUNT)
115
+ if stored:
116
+ return Found(stored, "keychain", self.store.service_name(SERVICE_ACCOUNT))
117
+ return None
118
+
119
+ def load_service_account(self) -> dict[str, Any]:
120
+ """Словарь ключа сервисного аккаунта; нет или битый — NotAuthorized с командой-исправлением."""
121
+ found = self.find_service_account()
122
+ if found is None:
123
+ raise NotAuthorized(
124
+ self.profile.provider, "Нет ключа сервисного аккаунта Google.", action=self.login_action
125
+ )
126
+ try:
127
+ return parse_service_account(found.value)
128
+ except InvalidArguments as exc:
129
+ raise NotAuthorized(
130
+ self.profile.provider,
131
+ f"Ключ из {found.source} ({found.origin}): {exc.message}",
132
+ action=self.login_action,
133
+ ) from exc
134
+
135
+ def credentials(self, scopes: list[str] | tuple[str, ...] | None = None) -> Any:
136
+ """google-auth Credentials сервисного аккаунта (токен ещё не получен). scopes по умолчанию — первый из профиля."""
137
+ from google.oauth2 import service_account
138
+
139
+ return service_account.Credentials.from_service_account_info(
140
+ self.load_service_account(), scopes=list(scopes or self.profile.scopes[:1])
141
+ )
142
+
143
+ def refresh(self, creds: Any) -> str:
144
+ """Получить/обновить access token для creds (см. `refresh_credentials`)."""
145
+ return refresh_credentials(
146
+ creds, provider=self.profile.provider, action=f"Выполните '{self.profile.login_cmd}' с новым ключом."
147
+ )
148
+
149
+ def bearer(self, scopes: list[str] | tuple[str, ...] | None = None) -> BearerToken:
150
+ """Держатель токена для клиента API: `headers()` на каждый запрос, обновление — само."""
151
+ return BearerToken(self, scopes)
152
+
153
+ def store_service_account(self, text: str) -> dict[str, Any]:
154
+ """Проверить JSON ключа и положить в общий слот keychain. Возвращает разобранный ключ."""
155
+ info = parse_service_account(text)
156
+ self.store.set(SERVICE_ACCOUNT, text)
157
+ return info
158
+
159
+ # --- API-ключи ---------------------------------------------------------------------
160
+
161
+ def find_api_key(self, name: str) -> Found | None:
162
+ """API-ключ и откуда он. Порядок: переменные инструмента → общая `GOOGLE_OAUTH_<NAME>_API_KEY` → keychain."""
163
+ key = self.profile.api_key(name)
164
+ env = self.store.first_env(self.store.api_key_env(key))
165
+ if env:
166
+ return Found(env[0], "env", env[1])
167
+ stored = self.store.get(API_KEY, name)
168
+ if stored:
169
+ return Found(stored, "keychain", f"{self.store.service_name(API_KEY)}/{name}")
170
+ return None
171
+
172
+ def api_key(self, name: str) -> str | None:
173
+ found = self.find_api_key(name)
174
+ return found.value if found else None
175
+
176
+ def store_api_key(self, name: str, value: str) -> None:
177
+ self.profile.api_key(name) # неизвестное имя — KeyError, а не мусор в keychain
178
+ value = value.strip()
179
+ if not value:
180
+ raise InvalidArguments("Пустой API-ключ.")
181
+ self.store.set(API_KEY, value, name)
182
+
183
+ # --- выход и статус ------------------------------------------------------------------
184
+
185
+ def logout(self, provider: str) -> None:
186
+ """Удалить из общего слота keychain ключ сервисного аккаунта или API-ключ (env не трогает)."""
187
+ if provider == self.profile.provider:
188
+ self.store.delete(SERVICE_ACCOUNT)
189
+ else:
190
+ self.profile.api_key(provider)
191
+ self.store.delete(API_KEY, provider)
192
+
193
+ def status(self, *, check: bool = False) -> AuthStatus:
194
+ """Что есть из авторизации. Без check — без сети; check=True — ещё и получает токен у Google."""
195
+ api_keys = {key.name: self.find_api_key(key.name) is not None for key in self.profile.api_keys}
196
+ status = AuthStatus(provider=self.profile.provider, state="missing", api_keys=api_keys)
197
+ try:
198
+ found = self.find_service_account()
199
+ if found is None:
200
+ status.detail = f"выполните '{self.profile.login_cmd}'"
201
+ return status
202
+ info = parse_service_account(found.value)
203
+ except (NotAuthorized, InvalidArguments) as exc:
204
+ status.detail = exc.message
205
+ return status
206
+ status.state, status.account, status.source = "ok", info["client_email"], found.source
207
+ if check:
208
+ try:
209
+ self.refresh(self.credentials())
210
+ except NotAuthorized as exc:
211
+ status.state, status.detail = "expired", exc.message
212
+ return status
213
+
214
+
215
+ class BearerToken:
216
+ """Access token сервисного аккаунта для заголовка Authorization.
217
+
218
+ Ключ читается при первом `headers()`, токен обновляется, когда google-auth
219
+ считает его невалидным (истёк или истекает с запасом по времени).
220
+ """
221
+
222
+ def __init__(self, auth: GoogleAuth, scopes: list[str] | tuple[str, ...] | None = None) -> None:
223
+ self.auth = auth
224
+ self.scopes = scopes
225
+ self._creds: Any = None
226
+
227
+ def token(self) -> str:
228
+ if self._creds is None:
229
+ self._creds = self.auth.credentials(self.scopes)
230
+ if not self._creds.valid:
231
+ self.auth.refresh(self._creds)
232
+ return self._creds.token
233
+
234
+ def headers(self) -> dict[str, str]:
235
+ return {"Authorization": f"Bearer {self.token()}"}
@@ -0,0 +1,282 @@
1
+ """Готовая Typer-команда `auth login|logout|status [--check]` — одна на все Google-инструменты.
2
+
3
+ Инструмент передаёт свой `output`-модуль (guard/emit_success/опции — из общей
4
+ CLI-архитектуры), чтобы вывод, JSON-конверт и обработка ошибок были ровно
5
+ такими же, как у его собственных команд.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import getpass
11
+ import inspect
12
+ import json
13
+ import sys
14
+ from collections.abc import Callable, Mapping
15
+ from importlib import metadata
16
+ from pathlib import Path
17
+ from types import ModuleType
18
+
19
+ import typer
20
+
21
+ from . import status as status_mod
22
+ from .auth import GoogleAuth
23
+ from .errors import CredentialsUnhealthy, InvalidArguments
24
+
25
+
26
+ def _ask(text: str, *, hide: bool = False) -> str:
27
+ """Спросить строку. Вопрос — в stderr (stdout чист для --json); скрытый ввод — только в терминале."""
28
+ if hide and sys.stdin.isatty():
29
+ return getpass.getpass(f"{text}: ", stream=sys.stderr).strip()
30
+ sys.stderr.write(f"{text}: ")
31
+ sys.stderr.flush()
32
+ line = sys.stdin.readline()
33
+ if not line:
34
+ raise typer.Abort()
35
+ return line.strip()
36
+
37
+
38
+ def _read_key_file(path: str) -> str:
39
+ file = Path(path).expanduser()
40
+ if not file.is_file():
41
+ raise InvalidArguments(f"Файл не найден: {file}")
42
+ return file.read_text(encoding="utf-8")
43
+
44
+
45
+ def make_auth_app(
46
+ auth: GoogleAuth,
47
+ output: ModuleType,
48
+ *,
49
+ check: Callable[[typer.Context], None] | None = None,
50
+ api_key_checks: Mapping[str, Callable[[typer.Context], None]] | None = None,
51
+ ) -> typer.Typer:
52
+ """Собрать sub-app `auth` для инструмента.
53
+
54
+ check — необязательный живой запрос к API инструмента для `auth status --check`
55
+ (поверх получения токена сервисного аккаунта); должен бросать CliError при отказе API.
56
+ api_key_checks — имя API-ключа → такой же запрос с этим ключом; без него ключ
57
+ под `--check` остаётся `unchecked`.
58
+
59
+ Docstring'и команд — это их `--help`: подстановки `{cli}`, `{provider}` и т.п.
60
+ заполняет `_help`, строка `Example:` обязательна (стандарт tools §7).
61
+ """
62
+ profile = auth.profile
63
+ store = auth.store
64
+ human = output.human
65
+ key_checks = dict(api_key_checks or {})
66
+ app = typer.Typer(help=f"Доступы Google для {profile.service}: ключ сервисного аккаунта и API-ключи (keychain ОС).")
67
+
68
+ key_help = "; ".join(f"{k.name} — API-ключ {k.title}" for k in profile.api_keys)
69
+ provider_option = typer.Option(
70
+ profile.provider,
71
+ "--provider",
72
+ help=f"{profile.provider} — сервисный аккаунт" + (f"; {key_help}." if key_help else "."),
73
+ )
74
+ placeholders = {
75
+ "{cli}": profile.cli_name,
76
+ "{provider}": profile.provider,
77
+ "{login_hint}": profile.login_hint,
78
+ "{sa_env}": " / ".join(store.service_account_json_env() + store.service_account_file_env()),
79
+ "{key_lines}": "\n\n".join(
80
+ f"{k.name}: API-ключ {k.title} из {' / '.join(store.api_key_env(k))}, иначе спросит скрытым вводом."
81
+ + (f" {k.hint}" if k.hint else "")
82
+ for k in profile.api_keys
83
+ ),
84
+ "{key_examples}": "".join(f"\n {profile.api_key_login_cmd(k.name)}" for k in profile.api_keys),
85
+ }
86
+
87
+ def _help(func: Callable) -> Callable:
88
+ # Отступ убран до подстановки: многострочные значения вставляются без отступа
89
+ # (Python 3.13+ и так убирает его при компиляции, 3.11–3.12 — нет).
90
+ doc = inspect.cleandoc(func.__doc__ or "")
91
+ for key, value in placeholders.items():
92
+ doc = doc.replace(key, value)
93
+ func.__doc__ = doc
94
+ return func
95
+
96
+ def _provider(value: str) -> str:
97
+ if value not in profile.providers:
98
+ raise InvalidArguments(f"Неизвестный --provider '{value}': допустимо {', '.join(profile.providers)}.")
99
+ return value
100
+
101
+ def _non_interactive(ctx: typer.Context, flag: bool) -> bool:
102
+ return bool(ctx.obj.get("non_interactive") or flag)
103
+
104
+ def _login_service_account(file: Path | None, non_interactive: bool) -> dict:
105
+ if file is not None:
106
+ text = _read_key_file(str(file))
107
+ else:
108
+ found = auth.find_service_account()
109
+ if found and found.source in ("env", "file"):
110
+ text = found.value
111
+ elif non_interactive:
112
+ raise InvalidArguments(
113
+ f"Нужен --file <service-account.json> (или {store.service_account_json_env()[0]} в окружении): "
114
+ "задан --non-interactive."
115
+ )
116
+ else:
117
+ text = _read_key_file(_ask("Путь к JSON-ключу сервисного аккаунта"))
118
+ info = auth.store_service_account(text)
119
+ return {"provider": profile.provider, "account": info["client_email"], "stored": "keychain"}
120
+
121
+ def _login_api_key(name: str, non_interactive: bool) -> dict:
122
+ key = profile.api_key(name)
123
+ found = auth.find_api_key(name)
124
+ if found and found.source == "env":
125
+ value = found.value
126
+ elif non_interactive:
127
+ raise InvalidArguments(f"Нет {' / '.join(store.api_key_env(key))} в окружении, а задан --non-interactive.")
128
+ else:
129
+ value = _ask(f"API-ключ {key.title}", hide=True)
130
+ auth.store_api_key(name, value)
131
+ return {"provider": name, "account": None, "stored": "keychain"}
132
+
133
+ # --- login ---------------------------------------------------------------------
134
+
135
+ @app.command("login")
136
+ @output.guard
137
+ @_help
138
+ def login(
139
+ ctx: typer.Context,
140
+ provider: str = provider_option,
141
+ file: Path | None = typer.Option(
142
+ None, "--file", "-f", dir_okay=False, help="JSON-ключ сервисного аккаунта (для --provider по умолчанию)."
143
+ ),
144
+ non_interactive: bool = output.NonInteractiveOption,
145
+ json_output: bool = output.JsonOption,
146
+ quiet: bool = output.QuietOption,
147
+ ) -> None:
148
+ """Сохранить доступ Google в общий слот keychain ОС (один на все Google-инструменты).
149
+
150
+ {provider}: JSON-ключ сервисного аккаунта — из --file, иначе из
151
+ {sa_env}, иначе спросит путь к файлу.
152
+ {login_hint}
153
+
154
+ {key_lines}
155
+
156
+ --json: {"ok": true, "provider", "account", "stored"}.
157
+
158
+ \b
159
+ Примеры:
160
+ {cli} auth login --file ~/Downloads/service-account.json{key_examples}
161
+
162
+ Example: {cli} auth login --file ~/Downloads/service-account.json
163
+ """
164
+ non_int = _non_interactive(ctx, non_interactive)
165
+ provider = _provider(provider)
166
+ if provider == profile.provider:
167
+ result = _login_service_account(file, non_int)
168
+ else:
169
+ if file is not None:
170
+ raise InvalidArguments(f"--file только для --provider {profile.provider}.")
171
+ result = _login_api_key(provider, non_int)
172
+
173
+ def render(d: dict) -> None:
174
+ if d["account"]:
175
+ human.echo(f"Сохранено в keychain: сервисный аккаунт {d['account']}")
176
+ if profile.login_hint:
177
+ human.echo(profile.login_hint)
178
+ else:
179
+ human.echo(f"Сохранено в keychain: API-ключ {d['provider']}")
180
+
181
+ output.emit_success(ctx, result, render)
182
+
183
+ # --- logout --------------------------------------------------------------------
184
+
185
+ @app.command("logout")
186
+ @output.guard
187
+ @_help
188
+ def logout(
189
+ ctx: typer.Context,
190
+ provider: str = provider_option,
191
+ json_output: bool = output.JsonOption,
192
+ quiet: bool = output.QuietOption,
193
+ ) -> None:
194
+ """Удалить доступ из общего слота keychain — для всех Google-инструментов (переменные окружения не трогает).
195
+
196
+ --json: {"ok": true, "provider"}.
197
+
198
+ Example: {cli} auth logout
199
+ """
200
+ provider = _provider(provider)
201
+ auth.logout(provider)
202
+ output.emit_success(ctx, {"provider": provider}, lambda d: human.echo(f"Удалено из keychain: {d['provider']}"))
203
+
204
+ # --- status --------------------------------------------------------------------
205
+
206
+ @app.command("status")
207
+ @output.guard
208
+ @_help
209
+ def auth_status(
210
+ ctx: typer.Context,
211
+ check_flag: bool = typer.Option(
212
+ False, "--check", help="Проверить ключи у Google и одним дешёвым запросом к API (не дольше 10 с на ключ)."
213
+ ),
214
+ json_output: bool = output.JsonOption,
215
+ quiet: bool = output.QuietOption,
216
+ ) -> None:
217
+ """Откуда берутся ключи и работают ли они — отчёт в общей для всех инструментов форме. Значений не печатает.
218
+
219
+ Записи: {provider} (сервисный аккаунт, обязателен) и API-ключи инструмента.
220
+ Без --check — только наличие (`unchecked`, `missing`, `invalid` — битый JSON), без сети.
221
+ Код выхода 0 — всё в порядке, 3 — обязательного ключа нет или Google/API его не принимает.
222
+ --json — контракт для tools-watch (стандарт tools §8): `tool`, `version`,
223
+ `checked_at`, `credentials[]` с `provider`, `required`, `fields`, `source`,
224
+ `source_ref`, `status`, `expires_at`, `quota`, `message`; при коде 3 —
225
+ `ok: false` и `error` CREDENTIALS_UNHEALTHY рядом с отчётом.
226
+
227
+ Example: {cli} auth status --check --json
228
+ """
229
+ entries = [
230
+ status_mod.credential_status(
231
+ auth, live=check_flag, check=(lambda: check(ctx)) if check is not None else None
232
+ )
233
+ ]
234
+ for key in profile.api_keys:
235
+ key_check = key_checks.get(key.name)
236
+ entries.append(
237
+ status_mod.credential_status(
238
+ auth,
239
+ key.name,
240
+ live=check_flag,
241
+ check=(lambda c=key_check: c(ctx)) if key_check is not None else None,
242
+ )
243
+ )
244
+ report = status_mod.status_report(profile.cli_name, _tool_version(profile.cli_name), entries)
245
+ problems = status_mod.status_problems(report)
246
+ if not problems:
247
+ output.emit_success(ctx, report, _render_status)
248
+ return
249
+ error = CredentialsUnhealthy(profile, problems)
250
+ if ctx.obj.get("json"):
251
+ typer.echo(json.dumps({"ok": False, "error": error.to_dict(), **report}, ensure_ascii=False))
252
+ else:
253
+ if not ctx.obj.get("quiet"):
254
+ _render_status(report)
255
+ typer.echo(f"Error: {error.message}", err=True)
256
+ typer.echo(error.action, err=True)
257
+ raise typer.Exit(code=error.exit_code)
258
+
259
+ def _render_status(report: dict) -> None:
260
+ for entry in report["credentials"]:
261
+ mark = {"ok": "✓", "unchecked": "·"}.get(entry["status"], "✗")
262
+ detail = f" — {entry['message']}" if entry["message"] else ""
263
+ line = f"{entry['provider']}: {entry['status']} ({entry['source']}: {entry['source_ref']}){detail}"
264
+ human.echo(f"{mark} {_escape(line)}")
265
+
266
+ return app
267
+
268
+
269
+ def _tool_version(cli_name: str) -> str:
270
+ """Версия инструмента-потребителя: дистрибутив, который ставит console script `cli_name`.
271
+
272
+ По entry point, а не по имени пакета: так работает и для editable-установки.
273
+ """
274
+ for entry_point in metadata.entry_points(group="console_scripts", name=cli_name):
275
+ if entry_point.dist is not None:
276
+ return entry_point.dist.version
277
+ return "0.0.0"
278
+
279
+
280
+ def _escape(text: str) -> str:
281
+ """Экранировать `[` для rich-разметки `human.echo` (в source_ref/message бывают скобки)."""
282
+ return text.replace("[", "\\[")
@@ -0,0 +1,103 @@
1
+ """Keychain ОС + переменные окружения — где лежат ключи Google.
2
+
3
+ Пространство имён общее для всех инструментов (`Profile.keychain_namespace`,
4
+ по умолчанию `google-oauth`). Запись keychain — пара (service, username):
5
+
6
+ - ключ сервисного аккаунта: `google-oauth:service_account` / `default`, значение — JSON ключа как есть;
7
+ - API-ключ: `google-oauth:api_key` / `<имя ключа>` (`pagespeed`, …), значение — ключ.
8
+
9
+ Вид (kind) в имени сервиса оставляет место для OAuth пользователя позже
10
+ (`google-oauth:authorized_user`) без переделки схемы.
11
+
12
+ Переменные окружения переопределяют keychain: сначала «исторические»
13
+ переменные инструмента из профиля, затем общие `GOOGLE_OAUTH_…`.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ import logging
19
+ import os
20
+
21
+ import keyring
22
+ import keyring.errors
23
+ from keyring.backends import fail
24
+
25
+ from .errors import CredentialStoreUnavailable
26
+ from .profile import ApiKey, Profile
27
+
28
+ SERVICE_ACCOUNT = "service_account"
29
+ API_KEY = "api_key"
30
+ DEFAULT = "default"
31
+
32
+ log = logging.getLogger(__name__)
33
+
34
+
35
+ class CredentialStore:
36
+ def __init__(self, profile: Profile) -> None:
37
+ self.profile = profile
38
+ # Почему keychain не прочитался при последнем обращении (None — прочитался).
39
+ self.unavailable_reason: str | None = None
40
+
41
+ # --- имена ---------------------------------------------------------------
42
+
43
+ def service_name(self, kind: str) -> str:
44
+ return f"{self.profile.keychain_namespace}:{kind}"
45
+
46
+ @property
47
+ def env_prefix(self) -> str:
48
+ return self.profile.keychain_namespace.upper().replace("-", "_")
49
+
50
+ def service_account_json_env(self) -> list[str]:
51
+ return [*self.profile.service_account_env, f"{self.env_prefix}_SERVICE_ACCOUNT_JSON"]
52
+
53
+ def service_account_file_env(self) -> list[str]:
54
+ return [*self.profile.service_account_file_env, f"{self.env_prefix}_SERVICE_ACCOUNT_FILE"]
55
+
56
+ def api_key_env(self, key: ApiKey) -> list[str]:
57
+ return [*key.env, f"{self.env_prefix}_{key.name.upper()}_API_KEY"]
58
+
59
+ @staticmethod
60
+ def first_env(names: list[str]) -> tuple[str, str] | None:
61
+ """(значение, имя переменной) первой непустой переменной из списка."""
62
+ for name in names:
63
+ value = os.environ.get(name, "").strip()
64
+ if value:
65
+ return value, name
66
+ return None
67
+
68
+ # --- keychain --------------------------------------------------------------
69
+
70
+ def get(self, kind: str, name: str = DEFAULT) -> str | None:
71
+ """Значение из keychain; недоступный keychain — не ошибка (остаются переменные окружения)."""
72
+ try:
73
+ value = keyring.get_password(self.service_name(kind), name) or None
74
+ except keyring.errors.KeyringError as exc:
75
+ # Headless Linux/CI без Secret Service не должен блокировать путь через env.
76
+ if self.unavailable_reason is None: # предупредить один раз, а не на каждое чтение
77
+ log.warning("Хранилище ключей ОС недоступно (%s); только переменные окружения", exc)
78
+ self.unavailable_reason = str(exc) or type(exc).__name__
79
+ return None
80
+ self.unavailable_reason = None
81
+ return value
82
+
83
+ def set(self, kind: str, value: str, name: str = DEFAULT) -> None:
84
+ try:
85
+ keyring.set_password(self.service_name(kind), name, value)
86
+ except keyring.errors.KeyringError as exc:
87
+ raise CredentialStoreUnavailable(self.profile, str(exc)) from exc
88
+
89
+ def delete(self, kind: str, name: str = DEFAULT) -> None:
90
+ try:
91
+ keyring.delete_password(self.service_name(kind), name)
92
+ except keyring.errors.PasswordDeleteError:
93
+ pass # уже отсутствует — удаление не ошибка
94
+ except keyring.errors.KeyringError as exc:
95
+ raise CredentialStoreUnavailable(self.profile, str(exc)) from exc
96
+
97
+ @staticmethod
98
+ def backend() -> str | None:
99
+ """Имя активного бэкенда keyring или None, если пользоваться нечем (headless Linux без Secret Service)."""
100
+ backend = keyring.get_keyring()
101
+ if isinstance(backend, fail.Keyring):
102
+ return None
103
+ return f"{type(backend).__module__}.{type(backend).__name__}"
google_oauth/errors.py ADDED
@@ -0,0 +1,80 @@
1
+ from __future__ import annotations
2
+
3
+ from .profile import Profile
4
+
5
+
6
+ class CliError(Exception):
7
+ """Базовая ошибка для всех ожидаемых, показываемых пользователю сбоев CLI.
8
+
9
+ Единая для всех инструментов, использующих google-oauth: их `output.guard`
10
+ ловит именно этот класс, поэтому ошибки общего кода (ключи, keychain,
11
+ получение токена) выводятся так же, как собственные ошибки инструмента.
12
+
13
+ Каждая несёт стабильный `code`, человекочитаемое `message`, необязательное
14
+ `action` (что сделать, чтобы разблокироваться) и код выхода процесса.
15
+ """
16
+
17
+ def __init__(self, code: str, message: str, *, action: str | None = None, exit_code: int = 1) -> None:
18
+ super().__init__(message)
19
+ self.code = code
20
+ self.message = message
21
+ self.action = action
22
+ self.exit_code = exit_code
23
+
24
+ def to_dict(self) -> dict:
25
+ payload: dict = {"code": self.code, "message": self.message}
26
+ if self.action:
27
+ payload["action"] = self.action
28
+ return payload
29
+
30
+
31
+ class InvalidArguments(CliError):
32
+ def __init__(self, message: str) -> None:
33
+ super().__init__("INVALID_ARGUMENTS", message, exit_code=2)
34
+
35
+
36
+ class NotAuthorized(CliError):
37
+ """Нет учётных данных, они битые или Google их отверг. `action` — команда, которая это исправит."""
38
+
39
+ def __init__(self, provider: str, reason: str, *, action: str) -> None:
40
+ super().__init__("AUTH_REQUIRED", reason, action=action, exit_code=3)
41
+ self.provider = provider
42
+
43
+
44
+ class TokenRequestFailed(CliError):
45
+ """Не удалось получить access token из-за сети/сервера Google (ключ при этом может быть исправен)."""
46
+
47
+ def __init__(self, provider: str, message: str) -> None:
48
+ super().__init__(
49
+ "PROVIDER_ERROR",
50
+ f"Provider '{provider}': {message}",
51
+ action="Повторите позже; если не проходит — проверьте сеть и status.cloud.google.com.",
52
+ exit_code=5,
53
+ )
54
+ self.provider = provider
55
+
56
+ def to_dict(self) -> dict:
57
+ return {**super().to_dict(), "provider": self.provider}
58
+
59
+
60
+ class CredentialStoreUnavailable(CliError):
61
+ def __init__(self, profile: Profile, reason: str) -> None:
62
+ super().__init__(
63
+ "CREDENTIAL_STORE_UNAVAILABLE",
64
+ f"Не удалось обратиться к системному хранилищу ключей: {reason}",
65
+ action=f"Задайте ключ переменной окружения вместо 'auth login' (см. '{profile.cli_name} auth login --help').",
66
+ exit_code=1,
67
+ )
68
+
69
+
70
+ class CredentialsUnhealthy(CliError):
71
+ """`auth status` нашёл проблему (§8 стандарта tools): отчёт выводится целиком, рядом — эта ошибка, exit 3."""
72
+
73
+ def __init__(self, profile: Profile, problems: dict[str, str]) -> None:
74
+ listed = ", ".join(f"{provider} ({status})" for provider, status in problems.items())
75
+ super().__init__(
76
+ "CREDENTIALS_UNHEALTHY",
77
+ f"Учётные данные требуют внимания: {listed}.",
78
+ action=f"Подробности — в `message` каждой записи; войти заново: '{profile.login_cmd}'.",
79
+ exit_code=3,
80
+ )
@@ -0,0 +1,73 @@
1
+ from __future__ import annotations
2
+
3
+ from dataclasses import dataclass
4
+
5
+
6
+ @dataclass(frozen=True)
7
+ class ApiKey:
8
+ """API-ключ Google, который нужен инструменту (PageSpeed Insights, …).
9
+
10
+ name — имя ключа: запись keychain `google-oauth:api_key` / `<name>`,
11
+ значение `--provider <name>` в `auth login`, поле `<name>_key` в статусе.
12
+ title — название API для текстов («PageSpeed Insights»).
13
+ env — «исторические» переменные окружения инструмента с этим ключом,
14
+ по порядку; они приоритетнее общей `GOOGLE_OAUTH_<NAME>_API_KEY`.
15
+ hint — где взять ключ (для `auth login --help`).
16
+ required — без ключа инструмент не работает: в `auth status` его отсутствие —
17
+ код выхода 3 (иначе — только запись `missing`, §8 стандарта tools).
18
+ """
19
+
20
+ name: str
21
+ title: str
22
+ env: tuple[str, ...] = ()
23
+ hint: str = ""
24
+ required: bool = False
25
+
26
+
27
+ @dataclass(frozen=True)
28
+ class Profile:
29
+ """Чем инструмент отличается в общей схеме авторизации Google.
30
+
31
+ cli_name — имя команды (тексты подсказок, `<cli> auth login`).
32
+ service — название сервиса для текстов («Google Search Console»).
33
+ scopes — права сервисного аккаунта по умолчанию (первый — для запросов
34
+ без явных scopes).
35
+ service_account_env / service_account_file_env — «исторические» переменные
36
+ инструмента с JSON ключа / путём к файлу ключа; приоритетнее общих
37
+ `GOOGLE_OAUTH_SERVICE_ACCOUNT_JSON` / `_FILE`.
38
+ api_keys — какие API-ключи нужны инструменту.
39
+ login_hint — что сделать после входа (например, выдать email сервисного
40
+ аккаунта доступ в Search Console).
41
+ keychain_namespace — общий для всех инструментов: записи keychain
42
+ `google-oauth:<kind>`, общие переменные `GOOGLE_OAUTH_…`.
43
+ Один вход — все инструменты.
44
+ provider — имя сервисного аккаунта в `--provider` и в JSON статуса.
45
+ """
46
+
47
+ cli_name: str
48
+ service: str
49
+ scopes: tuple[str, ...]
50
+ service_account_env: tuple[str, ...] = ()
51
+ service_account_file_env: tuple[str, ...] = ()
52
+ api_keys: tuple[ApiKey, ...] = ()
53
+ login_hint: str = ""
54
+ keychain_namespace: str = "google-oauth"
55
+ provider: str = "google"
56
+
57
+ @property
58
+ def login_cmd(self) -> str:
59
+ return f"{self.cli_name} auth login --file <service-account.json>"
60
+
61
+ def api_key_login_cmd(self, name: str) -> str:
62
+ return f"{self.cli_name} auth login --provider {name}"
63
+
64
+ def api_key(self, name: str) -> ApiKey:
65
+ for key in self.api_keys:
66
+ if key.name == name:
67
+ return key
68
+ raise KeyError(f"API-ключ '{name}' не объявлен в профиле {self.cli_name}")
69
+
70
+ @property
71
+ def providers(self) -> list[str]:
72
+ """Допустимые значения `--provider`: сервисный аккаунт и API-ключи."""
73
+ return [self.provider, *(key.name for key in self.api_keys)]
google_oauth/status.py ADDED
@@ -0,0 +1,263 @@
1
+ """Контракт `<cli> auth status [--check] --json` (tools/docs/standard-release.md §8).
2
+
3
+ Два способа встроиться — оба дают одинаковые статусы у всех Google-инструментов:
4
+
5
+ - инструмент по шаблону cli-generator: его `Provider.health_check()` делегирует сюда,
6
+ а `source`/`required` запись отчёта добавляет сам CLI —
7
+
8
+ def health_check(self) -> Health:
9
+ return google_oauth.health_check(GOOGLE_AUTH, check=lambda: self.get_json("/sites"))
10
+
11
+ (`google_oauth.Health` совпадает по полям с `providers.base.Health` шаблона);
12
+ для API-ключа — `health_check(GOOGLE_AUTH, check, provider="pagespeed")`;
13
+ - инструмент на `make_auth_app`: команда `auth status` собирает весь отчёт из
14
+ `credential_status` + `status_report`, а exit-код и ошибку `CREDENTIALS_UNHEALTHY` —
15
+ из `status_exit_code` / `status_problems`.
16
+
17
+ Значения секретов в отчёт не попадают — только имена переменных, путь к файлу
18
+ и слот keychain; сообщения ошибок от них очищаются.
19
+ """
20
+
21
+ from __future__ import annotations
22
+
23
+ import concurrent.futures
24
+ from collections.abc import Callable
25
+ from dataclasses import dataclass
26
+ from datetime import UTC, datetime
27
+ from typing import Literal
28
+
29
+ from .auth import GoogleAuth, parse_service_account
30
+ from .credentials import CredentialStore
31
+ from .errors import CliError, InvalidArguments, NotAuthorized
32
+
33
+ EXIT_OK = 0
34
+ EXIT_PROBLEM = 3
35
+ CHECK_TIMEOUT = 10.0 # §8: жёсткий лимит на проверку одного провайдера, без повторов
36
+ HEALTHY = frozenset({"ok", "unchecked"})
37
+ # Проблема даже для необязательного провайдера: учётные данные есть, но негодные.
38
+ ALWAYS_PROBLEMS = frozenset({"invalid", "expired"})
39
+
40
+ HealthStatus = Literal["ok", "invalid", "expired", "quota_exhausted", "unreachable"]
41
+
42
+
43
+ @dataclass(frozen=True)
44
+ class Quota:
45
+ remaining: int | None = None
46
+ limit: int | None = None
47
+ unit: str = "requests"
48
+
49
+
50
+ @dataclass(frozen=True)
51
+ class Health:
52
+ """Итог живой проверки — поля как у `providers.base.Health` шаблона cli-generator."""
53
+
54
+ status: HealthStatus = "ok"
55
+ expires_at: datetime | None = None
56
+ quota: Quota | None = None
57
+ message: str | None = None
58
+
59
+
60
+ def health_check(
61
+ auth: GoogleAuth,
62
+ check: Callable[[], object] | None = None,
63
+ *,
64
+ provider: str | None = None,
65
+ timeout: float = CHECK_TIMEOUT,
66
+ ) -> Health:
67
+ """Живая проверка для `Provider.health_check()` инструмента: статус и сообщение.
68
+
69
+ provider — сервисный аккаунт (по умолчанию) или имя API-ключа из профиля.
70
+ Сервисный аккаунт: access token у Google (бесплатно, заодно проверка ключа),
71
+ затем `check`, если задан. API-ключ: только `check` — самый дешёвый read-only
72
+ запрос инструмента с этим ключом (без него проверять нечем → ValueError).
73
+ Всё вместе ограничено `timeout` секундами. Ошибки → статус: 401/403 и отказ
74
+ Google выдать токен → `invalid`; сеть, HTTP 429/5xx, CliError с exit_code 5,
75
+ таймаут → `unreachable`; прочие CliError → `invalid`.
76
+ Наличие ключа (`missing`) решает вызывающий — сюда приходят, когда он есть.
77
+ `expires_at` всегда None: у ключей сервисного аккаунта и API-ключей нет срока,
78
+ а час жизни access token — не срок учётных данных.
79
+ """
80
+ provider = provider or auth.profile.provider
81
+ if provider != auth.profile.provider:
82
+ auth.profile.api_key(provider) # неизвестное имя — KeyError сразу, а не статус
83
+ if check is None:
84
+ raise ValueError(f"health_check для API-ключа '{provider}' требует check — запрос с этим ключом.")
85
+ pool = concurrent.futures.ThreadPoolExecutor(max_workers=1)
86
+ try:
87
+ return pool.submit(_probe, auth, provider, check).result(timeout=timeout)
88
+ except concurrent.futures.TimeoutError:
89
+ return Health(status="unreachable", message=f"Нет ответа за {timeout:g} с.")
90
+ finally:
91
+ pool.shutdown(wait=False, cancel_futures=True)
92
+
93
+
94
+ def _probe(auth: GoogleAuth, provider: str, check: Callable[[], object] | None) -> Health:
95
+ secrets: list[str | None] = []
96
+ try:
97
+ if provider == auth.profile.provider:
98
+ info = auth.load_service_account()
99
+ secrets.append(info.get("private_key"))
100
+ creds = auth.credentials()
101
+ secrets.append(auth.refresh(creds))
102
+ else:
103
+ secrets.append(auth.api_key(provider))
104
+ if check is not None:
105
+ check()
106
+ except Exception as exc:
107
+ return Health(status=_failure_status(exc), message=_scrub(_message(exc), secrets))
108
+ return Health(status="ok")
109
+
110
+
111
+ def _http_status(exc: BaseException | None) -> int | None:
112
+ """Код HTTP-ответа из исключения клиента (httpx, requests) — без импорта самих клиентов."""
113
+ code = getattr(getattr(exc, "response", None), "status_code", None)
114
+ return code if isinstance(code, int) else None
115
+
116
+
117
+ def _failure_status(exc: Exception) -> HealthStatus:
118
+ code = _http_status(exc) or _http_status(exc.__cause__)
119
+ if code is not None:
120
+ return "invalid" if code in (401, 403) else "unreachable"
121
+ if isinstance(exc, NotAuthorized | InvalidArguments):
122
+ return "invalid"
123
+ if isinstance(exc, CliError):
124
+ return "unreachable" if exc.exit_code == 5 else "invalid"
125
+ return "unreachable"
126
+
127
+
128
+ def _message(exc: Exception) -> str:
129
+ return exc.message if isinstance(exc, CliError) else f"{type(exc).__name__}: {exc}"
130
+
131
+
132
+ def _scrub(message: str, secrets: list[str | None]) -> str:
133
+ for secret in secrets:
134
+ if secret:
135
+ message = message.replace(secret, "***")
136
+ return message
137
+
138
+
139
+ def _now() -> datetime:
140
+ return datetime.now(UTC)
141
+
142
+
143
+ def _iso(moment: datetime | None) -> str | None:
144
+ return moment.astimezone(UTC).replace(microsecond=0).isoformat().replace("+00:00", "Z") if moment else None
145
+
146
+
147
+ def credential_status(
148
+ auth: GoogleAuth,
149
+ provider: str | None = None,
150
+ *,
151
+ live: bool = False,
152
+ check: Callable[[], object] | None = None,
153
+ required: bool | None = None,
154
+ ) -> dict:
155
+ """Один элемент `credentials` отчёта: откуда ключ и (под `live`) принимает ли его Google/API.
156
+
157
+ provider — сервисный аккаунт (по умолчанию) или имя API-ключа.
158
+ live — флаг `--check`: без него только наличие (`unchecked`/`missing`/`invalid`), без сети.
159
+ check — запрос к API инструмента. Сервисный аккаунт под `live` проверяется и без него
160
+ (получением токена); API-ключ без него — `unchecked`.
161
+ required — по умолчанию: сервисный аккаунт обязателен, API-ключ — как `ApiKey.required`.
162
+ """
163
+ profile, store = auth.profile, auth.store
164
+ provider = provider or profile.provider
165
+ is_sa = provider == profile.provider
166
+ if required is None:
167
+ required = True if is_sa else profile.api_key(provider).required
168
+ entry: dict = {
169
+ "provider": provider,
170
+ "required": required,
171
+ "fields": ["service_account_json" if is_sa else "api_key"],
172
+ "source": "missing",
173
+ "source_ref": None,
174
+ "status": "missing",
175
+ "expires_at": None,
176
+ "quota": None,
177
+ "message": None,
178
+ }
179
+
180
+ if is_sa:
181
+ env_names = store.service_account_json_env() + store.service_account_file_env()
182
+ keychain_ref = f"keychain service {store.service_name('service_account')}"
183
+ login = profile.login_cmd
184
+ try:
185
+ found = auth.find_service_account()
186
+ except NotAuthorized as exc: # переменная указывает на несуществующий файл
187
+ entry.update(source="file", source_ref=_file_env(store), message=exc.message)
188
+ return entry
189
+ else:
190
+ key = profile.api_key(provider)
191
+ env_names = store.api_key_env(key)
192
+ keychain_ref = f"keychain service {store.service_name('api_key')}/{provider}"
193
+ login = profile.api_key_login_cmd(provider)
194
+ found = auth.find_api_key(provider)
195
+
196
+ if found is None:
197
+ reason = store.unavailable_reason
198
+ entry["source_ref"] = " or ".join([*env_names, keychain_ref])
199
+ entry["message"] = (f"Keychain недоступен ({reason}). " if reason else "") + (
200
+ f"Нет ключа: выполните '{login}' или задайте {env_names[0]}."
201
+ )
202
+ return entry
203
+
204
+ source_ref = {"env": found.origin, "file": found.origin, "keychain": f"keychain service {found.origin}"}
205
+ entry.update(source=found.source, source_ref=source_ref[found.source])
206
+ if is_sa:
207
+ try:
208
+ parse_service_account(found.value)
209
+ except InvalidArguments as exc:
210
+ entry.update(status="invalid", message=exc.message)
211
+ return entry
212
+
213
+ if not live:
214
+ entry["status"] = "unchecked"
215
+ return entry
216
+ if check is None and not is_sa:
217
+ entry.update(status="unchecked", message="Инструмент не задал проверочного запроса к API.")
218
+ return entry
219
+
220
+ health = health_check(auth, check, provider=provider)
221
+ entry.update(
222
+ status=health.status,
223
+ expires_at=_iso(health.expires_at),
224
+ quota=vars(health.quota) if health.quota else None,
225
+ message=health.message,
226
+ )
227
+ return entry
228
+
229
+
230
+ def _file_env(store: CredentialStore) -> str:
231
+ """Имя переменной с путём к файлу ключа, которая задана (для source_ref)."""
232
+ found = store.first_env(store.service_account_file_env())
233
+ return found[1] if found else ", ".join(store.service_account_file_env())
234
+
235
+
236
+ def status_report(tool: str, version: str, credentials: list[dict]) -> dict:
237
+ """Весь отчёт `auth status` по §8: инструмент, версия, время проверки, список учётных данных.
238
+
239
+ Конверт (`ok`, а при exit 3 — ещё `error` CREDENTIALS_UNHEALTHY) добавляет команда.
240
+ """
241
+ return {
242
+ "tool": tool,
243
+ "version": version,
244
+ "checked_at": _iso(_now()),
245
+ "credentials": credentials,
246
+ }
247
+
248
+
249
+ def is_problem(entry: dict) -> bool:
250
+ """Запись валит `auth status`: invalid/expired — всегда, прочее не ok/unchecked — если провайдер обязателен."""
251
+ if entry["status"] in ALWAYS_PROBLEMS:
252
+ return True
253
+ return entry["required"] and entry["status"] not in HEALTHY
254
+
255
+
256
+ def status_problems(report: dict) -> dict[str, str]:
257
+ """Провайдер → статус для всех проблемных записей (для ошибки CREDENTIALS_UNHEALTHY)."""
258
+ return {entry["provider"]: entry["status"] for entry in report["credentials"] if is_problem(entry)}
259
+
260
+
261
+ def status_exit_code(report: dict) -> int:
262
+ """0 — нет проблемных записей (см. `is_problem`), иначе 3."""
263
+ return EXIT_PROBLEM if status_problems(report) else EXIT_OK
@@ -0,0 +1,131 @@
1
+ Metadata-Version: 2.5
2
+ Name: rb-google-oauth
3
+ Version: 0.2.2
4
+ Summary: Shared Google authorization for CLI tools: a service account and API keys in one keychain slot.
5
+ Author: bolandau
6
+ License-Expression: MIT
7
+ License-File: LICENSE
8
+ Requires-Python: >=3.11
9
+ Requires-Dist: google-auth[requests]>=2.30
10
+ Requires-Dist: keyring>=25.0
11
+ Requires-Dist: typer<0.29,>=0.27
12
+ Description-Content-Type: text/markdown
13
+
14
+ # google-oauth (`rb-google-oauth`)
15
+
16
+ Общая авторизация Google для CLI-инструментов (`gsc`, …) — аналог [yandex-oauth](https://github.com/bolandeu/yandex-oauth) для Google. Один набор ключей — **в общем слоте keychain `google-oauth:*`** для всех инструментов: вход в любом из них авторизует остальные. Без дублирования кода и без `.env`-файлов.
17
+
18
+ Сейчас поддерживаются ключ **сервисного аккаунта** (access token получается и обновляется сам через `google-auth`) и **API-ключи** (PageSpeed Insights и другие). Вход пользователя через браузер (OAuth) пока не нужен, но схема хранения к нему готова (см. «Как добавить OAuth пользователя»).
19
+
20
+ Только macOS и Linux.
21
+
22
+ ## Что даёт
23
+
24
+ | Объект | Назначение |
25
+ |---|---|
26
+ | `Profile` | Чем инструмент отличается: имя CLI, название сервиса, scopes, «исторические» env-переменные инструмента, нужные API-ключи (`ApiKey`), подсказка после входа |
27
+ | `GoogleAuth(profile)` | Найти ключ сервисного аккаунта / API-ключ, `credentials(scopes)` (google-auth), `refresh(creds)`, `bearer(scopes).headers()` — токен с автообновлением для каждого запроса, `status(check=)`, `store_*`, `logout` |
28
+ | `CredentialStore(profile)` | Keychain ОС через `keyring` + имена переменных окружения; `backend()` для `doctor` |
29
+ | `make_auth_app(auth, output, check=None, api_key_checks=None)` | Готовая Typer-команда `auth login / logout / status [--check]` (модуль `google_oauth.auth_command`); `auth status` — отчёт §8 стандарта tools |
30
+ | `health_check(auth, check=None, provider=None)` → `Health` | Делегат для `Provider.health_check()` инструмента по шаблону cli-generator (см. «Проверка доступов») |
31
+ | `credential_status`, `status_report`, `status_problems`, `status_exit_code` | Сборка отчёта `auth status --json` для инструмента со своей командой `auth` |
32
+ | Ошибки | `CliError` (базовый — его ловит `output.guard` инструмента), `InvalidArguments` (exit 2), `NotAuthorized` (exit 3), `TokenRequestFailed` (exit 5), `CredentialStoreUnavailable`, `CredentialsUnhealthy` (exit 3) |
33
+
34
+ Импорт `google_oauth` не трогает сеть, keychain, `google-auth` и `typer`.
35
+
36
+ ## Где лежат ключи
37
+
38
+ | Что | Keychain (service / account) | Переменные окружения (по приоритету) |
39
+ |---|---|---|
40
+ | Ключ сервисного аккаунта (JSON) | `google-oauth:service_account` / `default` | env инструмента из профиля (например `GSC_GOOGLE_SERVICE_ACCOUNT_JSON`) → `GOOGLE_OAUTH_SERVICE_ACCOUNT_JSON` → env инструмента с путём к файлу → `GOOGLE_OAUTH_SERVICE_ACCOUNT_FILE` |
41
+ | API-ключ `<name>` | `google-oauth:api_key` / `<name>` | env инструмента (например `GSC_PAGESPEED_API_KEY`) → `GOOGLE_OAUTH_<NAME>_API_KEY` |
42
+
43
+ Любая переменная окружения приоритетнее keychain. Недоступный keychain (headless Linux без Secret Service) при чтении — не ошибка: работают переменные окружения, `auth status` называет причину. На сервере ключи задаются окружением, например через Doppler — `doppler run -- gsc …` с `GOOGLE_OAUTH_SERVICE_ACCOUNT_JSON` (JSON ключа целиком) и `GOOGLE_OAUTH_<NAME>_API_KEY`; ничего не записывается, `auth login` не нужен.
44
+
45
+ ## Подключение к инструменту
46
+
47
+ `pyproject.toml` инструмента:
48
+
49
+ ```toml
50
+ dependencies = ["rb-google-oauth>=0.2,<0.3", ...]
51
+
52
+ [tool.uv.sources]
53
+ rb-google-oauth = { git = "https://github.com/bolandeu/google-oauth.git", tag = "v0.2.0" }
54
+ ```
55
+
56
+ Дистрибутив — `rb-google-oauth` (`google-oauth` на PyPI — чужой пакет), импорт — `google_oauth`. Пин — на тег релиза, обновление: новый `tag` + `uv lock --upgrade-package rb-google-oauth`. После переименования в существующем venv: `uv sync --reinstall-package rb-google-oauth`.
57
+
58
+ Профиль:
59
+
60
+ ```python
61
+ from google_oauth import ApiKey, GoogleAuth, Profile
62
+
63
+ PROFILE = Profile(
64
+ cli_name="gsc",
65
+ service="Google Search Console",
66
+ scopes=("https://www.googleapis.com/auth/webmasters.readonly", "https://www.googleapis.com/auth/webmasters"),
67
+ service_account_env=("GSC_GOOGLE_SERVICE_ACCOUNT_JSON", "GOOGLE_SERVICE_ACCOUNT_JSON"),
68
+ service_account_file_env=("GOOGLE_SERVICE_ACCOUNT_FILE",),
69
+ api_keys=(ApiKey("pagespeed", "PageSpeed Insights", env=("GSC_PAGESPEED_API_KEY", "GOOGLE_PAGESPEED_API_KEY")),),
70
+ )
71
+ auth = GoogleAuth(PROFILE)
72
+ ```
73
+
74
+ Клиент API:
75
+
76
+ ```python
77
+ bearer = auth.bearer(scopes) # ключ читается при первом запросе
78
+ headers = bearer.headers() # {"Authorization": "Bearer …"}, обновляется сам
79
+ psi_key = auth.api_key("pagespeed") # или None
80
+ ```
81
+
82
+ Команда: `app.add_typer(make_auth_app(auth, output), name="auth")`. `core/errors.py` инструмента импортирует `CliError`/`InvalidArguments`/`NotAuthorized` отсюда, чтобы `output.guard` ловил ошибки общего кода. Тесты инструмента подменяют `google_oauth.credentials.keyring.*` (или тот же модуль через реэкспорт).
83
+
84
+ ## Проверка доступов (`auth status`, §8 стандарта tools)
85
+
86
+ `make_auth_app` выдаёт `auth status [--check] --json` в общей для всех инструментов форме: запись `google` (сервисный аккаунт, обязателен) и по записи на API-ключ (`ApiKey(required=…)`, по умолчанию необязателен). `source` — `env` / `file` / `keychain` / `missing`, `source_ref` — имя переменной, путь к файлу или слот keychain, значений нет. Под `--check` сервисный аккаунт проверяется получением access token у Google (бесплатно), затем запросом `check` инструмента; API-ключ — запросом из `api_key_checks={"pagespeed": …}`, без него `unchecked`. Код выхода 3 — обязательный ключ не в порядке или любой ключ `invalid`.
87
+
88
+ Инструмент по шаблону cli-generator делегирует `Provider.health_check()`:
89
+
90
+ ```python
91
+ import google_oauth
92
+
93
+
94
+ def health_check(self) -> Health:
95
+ return google_oauth.health_check(GOOGLE_AUTH, check=lambda: self.get_json("/sites"))
96
+ # API-ключ: google_oauth.health_check(GOOGLE_AUTH, check, provider="pagespeed")
97
+ ```
98
+
99
+ Лимит 10 с на всю проверку, без повторов; 401/403 и отказ Google → `invalid`, сеть/429/5xx/таймаут → `unreachable`; значения секретов вычищаются из `message`. `expires_at` — `None`: у ключей нет срока.
100
+
101
+ ## Почему так: готовые библиотеки
102
+
103
+ По правилу «сначала готовое» сравнивались (сентябрь 2026):
104
+
105
+ | Библиотека | Решение |
106
+ |---|---|
107
+ | **`google-auth`** (Google, Apache 2.0) | **Берём.** Сервисный аккаунт с автообновлением токена, `api_key.Credentials`, токен пользователя из JSON (`from_authorized_user_info`), ADC, impersonation — вся криптография и работа с токенами |
108
+ | **`keyring`** (MIT) | **Берём.** Keychain macOS / Secret Service Linux, как в yandex-oauth |
109
+ | `google-auth-oauthlib` (Google) | Позже — для входа пользователя через браузер (`InstalledAppFlow`) |
110
+ | `google-api-python-client` (Google) | Нет: это клиенты API, а не авторизация |
111
+ | `oauth2client` (Google) | Нет: устарел с 2018, заменён google-auth |
112
+ | `pydata-google-auth` | Нет: только вход пользователя, токен в файле, без сервисных аккаунтов и keychain |
113
+ | `gcloud-aio-auth` | Нет: асинхронный, инструменты синхронные |
114
+ | `Authlib` | Нет: универсальный OAuth, для Google избыточен |
115
+
116
+ Своё здесь только то, чего нет ни в одной из них: общий слот keychain и порядок env-переменных, `Profile`, Typer-команда, статус и типизированные ошибки CLI.
117
+
118
+ ADC (`google.auth.default()`, доступы `gcloud`) намеренно не подхватывается: он молча берёт чужие доступы с машины, и можно работать не под тем аккаунтом.
119
+
120
+ ## Как добавить OAuth пользователя
121
+
122
+ Вид учётных данных уже в имени записи keychain (`google-oauth:<kind>`). Для OAuth: запись `google-oauth:authorized_user` / `default` с JSON формата google-auth (`Credentials.to_json()`), вход — `google-auth-oauthlib` `InstalledAppFlow.run_local_server`, чтение — `google.oauth2.credentials.Credentials.from_authorized_user_info`, после обновления токена — перезапись JSON в keychain. `BearerToken` уже работает с любыми google-auth Credentials.
123
+
124
+ ## Разработка и релизы
125
+
126
+ ```bash
127
+ uv sync
128
+ gate check # гейт: lock, ruff, ty, pytest, wheel, osv-scanner, gitleaks; идёт на этой машине
129
+ ```
130
+
131
+ Версия — из git-тега `vX.Y.Z`; релиз — `antagor publish` (стандарт: https://homeserver.tailee01ab.ts.net:3000/bolandeu/cli-generator/src/branch/main/skills/cli-builder/reference/standard.md, «Release»). Справка команд `auth` — контракт: `uv run pytest --snapshot-update` после её изменения.
@@ -0,0 +1,11 @@
1
+ google_oauth/__init__.py,sha256=uwktTXFyry_5QzV4Pe8PTvRCHCX7UlUtn8MdMFJ1k6Y,2415
2
+ google_oauth/auth.py,sha256=uxUnuOB8NSinZRc2T4ILnXWKaYzVtUK_psAHdqKYyYk,11350
3
+ google_oauth/auth_command.py,sha256=0O3QTijLt1svtdcU-oh_LKgk97YWzNvKxJnCPiKPitc,12854
4
+ google_oauth/credentials.py,sha256=H-6Sc3FnoGDiXd3PQ2hcbjId5RDzDWbfuZiXL_kqkcI,4846
5
+ google_oauth/errors.py,sha256=NLEgpcydZ416CoHD-IYG4Ztlm-kFS7SvuRleiuiSAmk,3746
6
+ google_oauth/profile.py,sha256=VZexRsyJV98rB5xKtID3WBFJBoNs0IGtX8duz_AlIcw,3644
7
+ google_oauth/status.py,sha256=efeYmmPI1dph8cBacjyZBho_TGYVQDdj6e1Ebmh9Cag,11936
8
+ rb_google_oauth-0.2.2.dist-info/METADATA,sha256=8Ust0-t6i2tWkd198hdMhuJP0sQYo46H0qZC06XV3Js,11107
9
+ rb_google_oauth-0.2.2.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
10
+ rb_google_oauth-0.2.2.dist-info/licenses/LICENSE,sha256=5GzRg5WDp2lrQTiJlcB9JSzPewiy-E-P7YMKt9idbV4,1071
11
+ rb_google_oauth-0.2.2.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Roman Bolandau
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.