codex-workspaces 0.3.2__tar.gz → 0.3.4__tar.gz

{codex_workspaces-0.3.2 → codex_workspaces-0.3.4}/CHANGELOG.md

@@ -4,7 +4,32 @@ All notable changes to `codex-workspaces` will be documented in this file.
 
 This project follows a simple changelog format while it is still pre-release.
 
-## 0.3.2 - 2026-07-04
+## 0.3.4 - 2026-07-04
+
+### Added
+
+- Added `accounts current --id` and `accounts current --json` for shell-friendly account composition.
+
+### Changed
+
+- Default experimental private API quota configuration now points at the ChatGPT WHAM usage endpoint while remaining disabled by default.
+- Updated WHAM quota parsing for `rate_limit.primary_window`, reset times, window duration, allowed/limit status, and credits metadata.
+- Tightened quota auth extraction to use ChatGPT `auth.json` fields (`tokens.access_token`, `tokens.refresh_token`, and `tokens.account_id`) without recursively guessing token fields.
+- Updated README and testing docs to document the current `base_url`, `quota_endpoint`, and `account_endpoint` configuration fields.
+
+### Fixed
+
+- Fixed `quota`, `quota --json`, `accounts quota`, and `accounts list -a` so disabled or failing private API quota calls return friendly errors instead of Python tracebacks.
+- Fixed `accounts list -a` so one account's realtime quota failure does not interrupt the whole account list.
+- Fixed `accounts current` command composition by documenting `accounts info "$(codex-workspaces accounts current --id)"`.
+- Fixed WHAM quota requests to include `OpenAI-Account-Id`.
+- Fixed unauthorized and expired-access-token quota failures to return actionable login/refresh hints without leaking credentials.
+
+### Security
+
+- Avoids using `id_token` or recursively discovered token-like fields as private API bearer tokens.
+
+## 0.3.3 - 2026-07-04
 
 ### Added
 
@@ -23,7 +48,7 @@ This project follows a simple changelog format while it is still pre-release.
 
 - Improved account list/info metadata enrichment while keeping auth parsing optional and non-blocking.
 - Improved local stats presentation while keeping all statistics local and read-only.
-- Updated README, design, testing, release, and changelog docs for the 0.3.2 workflow.
+- Updated README, design, testing, release, and changelog docs for the 0.3.3 workflow.
 
 ### Security
 

{codex_workspaces-0.3.2/src/codex_workspaces.egg-info → codex_workspaces-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-workspaces
-Version: 0.3.2
+Version: 0.3.4
 Summary: Cross-platform Codex workspace switcher with a preserved macOS shell workflow.
 Author: blockchain-project-lives
 Project-URL: Homepage, https://github.com/blockchain-project-lives/codex-workspaces
@@ -223,9 +223,14 @@ Enable explicitly:
 ```bash
 codex-workspaces config set experimental_private_api.enabled true
 codex-workspaces config set experimental_private_api.quota_enabled true
-codex-workspaces config set experimental_private_api.refresh_enabled true
 ```
 
+The current endpoint fields are:
+
+- `experimental_private_api.base_url` defaults to `https://chatgpt.com`
+- `experimental_private_api.quota_endpoint` defaults to `/backend-api/wham/usage`
+- `experimental_private_api.account_endpoint` defaults to an empty string
+
 Query current account quota:
 
 ```bash
@@ -254,6 +259,8 @@ codex-workspaces accounts refresh acct_work
 codex-workspaces accounts refresh --all --json
 ```
 
+Refresh remains disabled by default. The current `account_endpoint` is not the Codex responses API; do not point it at the responses endpoint unless the provider logic is updated to support that POST-based flow.
+
 Realtime quota uses explicit experimental configuration, timeout, serial account iteration, and a local TTL cache under `~/.codex-workspaces/cache/quota/`. The cache stores quota summaries and auth hashes only; it does not store tokens, cookies, authorization headers, or raw `auth.json`.
 
 `stats` and `quota` are different: `stats` is local historical usage from SQLite, while `quota` is a realtime remote lookup. Quota failures do not affect local workspace/account switching.
@@ -274,6 +281,7 @@ Manage account metadata and snapshots:
 ```bash
 codex-workspaces accounts note acct_research "lab account"
 codex-workspaces accounts info acct_research
+codex-workspaces accounts info "$(codex-workspaces accounts current --id)"
 codex-workspaces accounts rename acct_research acct_lab
 codex-workspaces accounts delete acct_lab --force
 ```

{codex_workspaces-0.3.2 → codex_workspaces-0.3.4}/README.MD

@@ -195,9 +195,14 @@ Enable explicitly:
 ```bash
 codex-workspaces config set experimental_private_api.enabled true
 codex-workspaces config set experimental_private_api.quota_enabled true
-codex-workspaces config set experimental_private_api.refresh_enabled true
 ```
 
+The current endpoint fields are:
+
+- `experimental_private_api.base_url` defaults to `https://chatgpt.com`
+- `experimental_private_api.quota_endpoint` defaults to `/backend-api/wham/usage`
+- `experimental_private_api.account_endpoint` defaults to an empty string
+
 Query current account quota:
 
 ```bash
@@ -226,6 +231,8 @@ codex-workspaces accounts refresh acct_work
 codex-workspaces accounts refresh --all --json
 ```
 
+Refresh remains disabled by default. The current `account_endpoint` is not the Codex responses API; do not point it at the responses endpoint unless the provider logic is updated to support that POST-based flow.
+
 Realtime quota uses explicit experimental configuration, timeout, serial account iteration, and a local TTL cache under `~/.codex-workspaces/cache/quota/`. The cache stores quota summaries and auth hashes only; it does not store tokens, cookies, authorization headers, or raw `auth.json`.
 
 `stats` and `quota` are different: `stats` is local historical usage from SQLite, while `quota` is a realtime remote lookup. Quota failures do not affect local workspace/account switching.
@@ -246,6 +253,7 @@ Manage account metadata and snapshots:
 ```bash
 codex-workspaces accounts note acct_research "lab account"
 codex-workspaces accounts info acct_research
+codex-workspaces accounts info "$(codex-workspaces accounts current --id)"
 codex-workspaces accounts rename acct_research acct_lab
 codex-workspaces accounts delete acct_lab --force
 ```

{codex_workspaces-0.3.2 → codex_workspaces-0.3.4}/README.zh-CN.md

@@ -195,9 +195,14 @@ codex-workspaces stats work --days 14
 ```bash
 codex-workspaces config set experimental_private_api.enabled true
 codex-workspaces config set experimental_private_api.quota_enabled true
-codex-workspaces config set experimental_private_api.refresh_enabled true
 ```
 
+当前 endpoint 配置字段是：
+
+- `experimental_private_api.base_url` 默认 `https://chatgpt.com`
+- `experimental_private_api.quota_endpoint` 默认 `/backend-api/wham/usage`
+- `experimental_private_api.account_endpoint` 默认空字符串
+
 查询当前账号额度：
 
 ```bash
@@ -226,6 +231,8 @@ codex-workspaces accounts refresh acct_work
 codex-workspaces accounts refresh --all --json
 ```
 
+refresh 当前仍默认关闭。当前 `account_endpoint` 不是 Codex responses API；除非 provider 实现了 POST responses 流程，否则不要把它指向 responses endpoint。
+
 实时额度能力使用显式实验配置、请求超时、串行账号遍历和本地 TTL 缓存，缓存目录为 `~/.codex-workspaces/cache/quota/`。缓存只保存额度摘要和 auth hash，不保存 token、cookie、authorization header 或原始 `auth.json`。
 
 `stats` 和 `quota` 不同：`stats` 是本地 SQLite 历史统计，`quota` 是实时远端查询。额度查询失败不会影响本地 workspace/account 切换。
@@ -246,6 +253,7 @@ codex-workspaces accounts restore-default
 ```bash
 codex-workspaces accounts note acct_research "实验室账号"
 codex-workspaces accounts info acct_research
+codex-workspaces accounts info "$(codex-workspaces accounts current --id)"
 codex-workspaces accounts rename acct_research acct_lab
 codex-workspaces accounts delete acct_lab --force
 ```

{codex_workspaces-0.3.2 → codex_workspaces-0.3.4}/docs/RELEASE.zh-CN.md

@@ -88,9 +88,9 @@ permissions:
 1. 更新版本号和 `CHANGELOG.md`。
 2. 本地执行测试和构建检查。
 3. 合并到 `main`。
-4. 创建 Git tag，例如 `v0.3.2`，触发 `Publish to TestPyPI`。
+4. 创建 Git tag，例如 `v0.3.4`，触发 `Publish to TestPyPI`。
 5. 确认 TestPyPI 上传和安装正常。
-6. 从同一个提交创建并推送正式发布分支，例如 `release/v0.3.2`，触发 `Publish to PyPI`。
+6. 从同一个提交创建并推送正式发布分支，例如 `release/v0.3.4`，触发 `Publish to PyPI`。
 7. 如果 `pypi` Environment 配置了 Required reviewers，在 GitHub Actions 里批准部署。
 8. 在 PyPI 页面确认 wheel、sdist 和 README 渲染正常。
 

{codex_workspaces-0.3.2 → codex_workspaces-0.3.4}/docs/TESTING.zh-CN.md

@@ -130,7 +130,7 @@ CODEX_WORKSPACES_LINK="$tmp_home/.codex" \
 CODEX_WORKSPACES_ROOT="$tmp_home/.codex-workspaces" \
 codex-workspaces config set experimental_private_api.quota_enabled true
 
-# 需要配置实际 provider endpoint 后才会真实请求；无 endpoint 时会安全失败。
+# 默认内置 chatgpt.com WHAM quota endpoint；开启后会真实请求实验性 private API。
 # CODEX_WORKSPACES_LINK="$tmp_home/.codex" \
 # CODEX_WORKSPACES_ROOT="$tmp_home/.codex-workspaces" \
 # codex-workspaces quota --json

{codex_workspaces-0.3.2 → codex_workspaces-0.3.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codex-workspaces"
-version = "0.3.2"
+version = "0.3.4"
 description = "Cross-platform Codex workspace switcher with a preserved macOS shell workflow."
 readme = "README.MD"
 requires-python = ">=3.9"

{codex_workspaces-0.3.2 → codex_workspaces-0.3.4}/src/codex_workspaces/__init__.py

@@ -1,3 +1,3 @@
 """Codex workspace switching utilities."""
 
-__version__ = "0.3.2"
+__version__ = "0.3.4"

{codex_workspaces-0.3.2 → codex_workspaces-0.3.4}/src/codex_workspaces/cli.py

@@ -50,8 +50,7 @@ def run(argv: Sequence[str], manager: WorkspaceManager) -> int:
                 no_cache = True
             else:
                 manager.fail(f"未知参数: {arg}", f"Unknown option: {arg}")
-        manager.show_quota(json_output=json_output, no_cache=no_cache)
-        return 0
+        return manager.show_quota(json_output=json_output, no_cache=no_cache)
     if command == "accounts":
         return run_accounts(args, manager)
     if command == "stats":
@@ -262,9 +261,18 @@ def run_accounts(args: Sequence[str], manager: WorkspaceManager) -> int:
         manager.accounts_list(all_with_quota=all_with_quota, no_cache=no_cache, json_output=json_output, verbose=verbose)
         return 0
     if command in {"current", "whoami"}:
-        if rest:
-            manager.fail(f"未知参数: {rest[0]}", f"Unknown option: {rest[0]}")
-        manager.accounts_current()
+        id_only = False
+        json_output = False
+        for arg in rest:
+            if arg == "--id":
+                id_only = True
+            elif arg == "--json":
+                json_output = True
+            else:
+                manager.fail(f"未知参数: {arg}", f"Unknown option: {arg}")
+        if id_only and json_output:
+            manager.fail("--id 和 --json 不能同时使用", "--id and --json cannot be used together")
+        manager.accounts_current(id_only=id_only, json_output=json_output)
         return 0
     if command == "info":
         if len(rest) != 1:
@@ -319,8 +327,7 @@ def run_accounts(args: Sequence[str], manager: WorkspaceManager) -> int:
                 account = arg
             else:
                 manager.fail(f"未知参数: {arg}", f"Unknown option: {arg}")
-        manager.accounts_quota(account or "", json_output=json_output, no_cache=no_cache)
-        return 0
+        return manager.accounts_quota(account or "", json_output=json_output, no_cache=no_cache)
     if command == "export":
         if not rest:
             manager.fail(

{codex_workspaces-0.3.2 → codex_workspaces-0.3.4}/src/codex_workspaces/core.py

@@ -22,7 +22,16 @@ from .errors import CodexWorkspacesError
 from .platforms import SystemPlatform
 from .private_api import AccountRemoteInfo, AuthMaterial, ConfiguredHttpPrivateApiProvider, PrivateApiProvider, QuotaInfo
 from .private_api.auth import extract_auth_material
-from .private_api.errors import PrivateApiDisabledError, PrivateApiError
+from .private_api.errors import (
+    PrivateApiAuthError,
+    PrivateApiDisabledError,
+    PrivateApiError,
+    PrivateApiForbiddenError,
+    PrivateApiNetworkError,
+    PrivateApiRateLimitedError,
+    PrivateApiUnsupportedResponseError,
+    redact_sensitive_text,
+)
 from .store import AccountMeta, WorkspaceMeta, WorkspaceStore, auth_hash, chmod_best_effort, copy_auth, iso_now, read_json, write_json_atomic
 from .stats import ModelUsage, StatsBundle, StatsError, WorkspaceStats, combine_workspace_stats, compute_workspace_stats
 
@@ -419,6 +428,11 @@ class WorkspaceManager:
         defaults = self.default_private_api_config()
         for key, value in defaults.items():
             private.setdefault(key, value)
+        if private.get("provider") == "codex":
+            if not private.get("base_url"):
+                private["base_url"] = defaults["base_url"]
+            if not private.get("quota_endpoint"):
+                private["quota_endpoint"] = defaults["quota_endpoint"]
         return data
 
     def write_tool_config(self, data: dict) -> None:
@@ -430,8 +444,8 @@ class WorkspaceManager:
             "quota_enabled": False,
             "refresh_enabled": False,
             "provider": "codex",
-            "base_url": "",
-            "quota_endpoint": "",
+            "base_url": "https://chatgpt.com",
+            "quota_endpoint": "/backend-api/wham/usage",
             "account_endpoint": "",
             "timeout_seconds": 10,
             "rate_limit_per_minute": 20,
@@ -528,6 +542,116 @@ class WorkspaceManager:
             user_agent=f"codex-workspaces/{self.tool_version()} experimental-private-api",
         )
 
+    def ensure_quota_endpoint_configured(self, settings: dict) -> None:
+        if self.private_api_provider is None and not settings.get("quota_endpoint"):
+            raise PrivateApiUnsupportedResponseError("quota endpoint is not configured")
+
+    def private_api_error_payload(self, exc: Exception) -> dict[str, object]:
+        if isinstance(exc, PrivateApiDisabledError):
+            error_type = "disabled"
+        elif isinstance(exc, PrivateApiAuthError):
+            error_type = "auth_error"
+        elif isinstance(exc, PrivateApiRateLimitedError):
+            error_type = "rate_limited"
+        elif isinstance(exc, PrivateApiForbiddenError):
+            error_type = "forbidden"
+        elif isinstance(exc, PrivateApiUnsupportedResponseError):
+            error_type = "unsupported_response"
+        elif isinstance(exc, PrivateApiNetworkError):
+            error_type = "network_error"
+        elif isinstance(exc, CodexWorkspacesError) and (
+            "experimental private API features are disabled" in str(exc) or "private API 功能未开启" in str(exc)
+        ):
+            error_type = "disabled"
+        else:
+            error_type = "internal_error"
+        return {"type": error_type, "message": redact_sensitive_text(str(exc))}
+
+    def quota_list_status_from_error(self, exc: Exception) -> str:
+        payload = self.private_api_error_payload(exc)
+        error_type = str(payload["type"])
+        message = str(payload["message"])
+        if error_type == "unsupported_response" and "quota endpoint is not configured" in message:
+            return "not-configured"
+        return {
+            "auth_error": "auth-error",
+            "rate_limited": "rate-limited",
+            "network_error": "network-error",
+            "unsupported_response": "error",
+            "internal_error": "error",
+        }.get(error_type, error_type.replace("_", "-"))
+
+    def format_private_api_error(self, exc: Exception) -> str:
+        payload = self.private_api_error_payload(exc)
+        error_type = str(payload["type"])
+        message = str(payload["message"])
+        if error_type == "disabled":
+            return "\n".join(
+                [
+                    "ERROR: experimental private API features are disabled.",
+                    "",
+                    "Enable explicitly:",
+                    "  codex-workspaces config set experimental_private_api.enabled true",
+                    "  codex-workspaces config set experimental_private_api.quota_enabled true",
+                ]
+            )
+        if error_type == "unsupported_response" and "quota endpoint is not configured" in message:
+            return "\n".join(
+                [
+                    "ERROR: realtime quota is not configured.",
+                    "",
+                    message,
+                    "",
+                    "Hint:",
+                    "  Configure experimental_private_api.quota_endpoint, or disable quota:",
+                    "  codex-workspaces config set experimental_private_api.quota_enabled false",
+                ]
+            )
+        titles = {
+            "auth_error": "ERROR: realtime quota authentication failed.",
+            "forbidden": "ERROR: realtime quota access was forbidden.",
+            "rate_limited": "ERROR: realtime quota is rate limited.",
+            "network_error": "ERROR: realtime quota request failed.",
+            "unsupported_response": "ERROR: realtime quota response is unsupported.",
+        }
+        return "\n".join(
+            [
+                titles.get(error_type, "ERROR: realtime quota failed."),
+                "",
+                message,
+                "",
+                "Hint:",
+                "  Check experimental_private_api settings, your account auth, or try again later.",
+            ]
+        )
+
+    def render_private_api_error(
+        self,
+        exc: Exception,
+        *,
+        json_output: bool,
+        account_id: Optional[str],
+        workspace: Optional[str],
+    ) -> int:
+        payload = self.private_api_error_payload(exc)
+        if json_output:
+            self.info(
+                json.dumps(
+                    {
+                        "status": "error",
+                        "account": account_id,
+                        "workspace": workspace,
+                        "error": payload,
+                    },
+                    ensure_ascii=False,
+                    indent=2,
+                    sort_keys=True,
+                )
+            )
+        else:
+            self.info(self.format_private_api_error(exc))
+        return 2
+
     def show_stats(
         self,
         name: Optional[str] = None,
@@ -1539,12 +1663,29 @@ class WorkspaceManager:
                 f"{(quota.plan or account.plan or '-'): <7} {self.percent_text(quota.used_percent):<8} {reset_at:<17} {status:<10} {quota.source}"
             )
 
-    def accounts_current(self) -> None:
+    def accounts_current(self, *, id_only: bool = False, json_output: bool = False) -> None:
         current = self.current_target()
         if current.kind != "target" or current.path is None:
             self.fail("当前工作区不存在。", "Current workspace does not exist.")
         name = self.current_name(current.path) or "current"
         meta = self.store.ensure_workspace_meta(name, current.path)
+        if id_only:
+            self.info(meta.active_account_id or "")
+            return
+        if json_output:
+            self.info(
+                json.dumps(
+                    {
+                        "workspace": name,
+                        "active_account_id": meta.active_account_id,
+                        "default_account_id": meta.default_account_id,
+                    },
+                    ensure_ascii=False,
+                    indent=2,
+                    sort_keys=True,
+                )
+            )
+            return
         self.info(f"{name}: active={meta.active_account_id or '-'} default={meta.default_account_id or '-'}")
 
     def accounts_info(self, account: str) -> None:
@@ -1658,6 +1799,7 @@ class WorkspaceManager:
 
     def get_account_quota(self, account_id: str, *, no_cache: bool = False) -> QuotaInfo:
         settings = self.ensure_private_api_enabled("quota")
+        self.ensure_quota_endpoint_configured(settings)
         auth_material = self.account_auth_material(account_id)
         ttl = int(settings.get("cache_ttl_seconds") or 300)
         if not no_cache:
@@ -1692,22 +1834,39 @@ class WorkspaceManager:
                 return QuotaInfo(status="disabled", error=str(exc), source="disabled")
             return QuotaInfo(status="no-auth", error=str(exc), source="local")
         except PrivateApiError as exc:
-            return QuotaInfo(status="error", error=str(exc) if verbose else None, source="private-api")
+            return QuotaInfo(status=self.quota_list_status_from_error(exc), error=str(exc) if verbose else None, source="private-api")
+        except Exception as exc:
+            return QuotaInfo(
+                status=self.quota_list_status_from_error(exc),
+                error=redact_sensitive_text(str(exc)) if verbose else None,
+                source="private-api",
+            )
 
-    def show_quota(self, *, json_output: bool = False, no_cache: bool = False) -> None:
-        workspace, _, meta = self.current_workspace_account()
-        account_id = meta.active_account_id or meta.default_account_id
-        assert account_id is not None
-        quota = self.get_account_quota(account_id, no_cache=no_cache)
-        account_meta = self.store.read_account_meta(account_id) if self.store.account_meta_path(account_id).is_file() else None
-        self.render_quota(workspace, account_id, quota, account_meta, json_output=json_output)
+    def show_quota(self, *, json_output: bool = False, no_cache: bool = False) -> int:
+        workspace = None
+        account_id = None
+        try:
+            workspace, _, meta = self.current_workspace_account()
+            account_id = meta.active_account_id or meta.default_account_id
+            assert account_id is not None
+            quota = self.get_account_quota(account_id, no_cache=no_cache)
+            account_meta = self.store.read_account_meta(account_id) if self.store.account_meta_path(account_id).is_file() else None
+            self.render_quota(workspace, account_id, quota, account_meta, json_output=json_output)
+            return 0
+        except Exception as exc:
+            return self.render_private_api_error(exc, json_output=json_output, account_id=account_id, workspace=workspace)
 
-    def accounts_quota(self, account: str, *, json_output: bool = False, no_cache: bool = False) -> None:
-        account_id = self.account_id_from_input(account)
-        if not self.store.account_meta_path(account_id).is_file():
-            self.fail(f"账号不存在: {account_id}", f"Account not found: {account_id}")
-        quota = self.get_account_quota(account_id, no_cache=no_cache)
-        self.render_quota(None, account_id, quota, self.store.read_account_meta(account_id), json_output=json_output)
+    def accounts_quota(self, account: str, *, json_output: bool = False, no_cache: bool = False) -> int:
+        account_id = None
+        try:
+            account_id = self.account_id_from_input(account)
+            if not self.store.account_meta_path(account_id).is_file():
+                self.fail(f"账号不存在: {account_id}", f"Account not found: {account_id}")
+            quota = self.get_account_quota(account_id, no_cache=no_cache)
+            self.render_quota(None, account_id, quota, self.store.read_account_meta(account_id), json_output=json_output)
+            return 0
+        except Exception as exc:
+            return self.render_private_api_error(exc, json_output=json_output, account_id=account_id, workspace=None)
 
     def render_quota(self, workspace: Optional[str], account_id: str, quota: QuotaInfo, account_meta: Optional[AccountMeta], *, json_output: bool) -> None:
         payload = {
@@ -2806,7 +2965,7 @@ def usage(lang: str) -> str:
       迁移旧 ~/.codex-<工作区名> 目录，并可导入旧 ~/.codex-accounts。
 
   codex-workspaces accounts list
-  codex-workspaces accounts current
+  codex-workspaces accounts current [--id|--json]
   codex-workspaces accounts info <账号>
   codex-workspaces accounts init <账号>
   codex-workspaces accounts save <账号>
@@ -2910,7 +3069,7 @@ Usage:
       Migrate legacy ~/.codex-<workspace> directories and optionally import old ~/.codex-accounts.
 
   codex-workspaces accounts list
-  codex-workspaces accounts current
+  codex-workspaces accounts current [--id|--json]
   codex-workspaces accounts info <account>
   codex-workspaces accounts init <account>
   codex-workspaces accounts save <account>

codex_workspaces-0.3.4/src/codex_workspaces/private_api/auth.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from ..store import auth_hash
+from .errors import PrivateApiAuthError
+from .models import AuthMaterial
+
+
+def extract_auth_material(account_id: str, auth_path: Path) -> AuthMaterial:
+    raw_hash = auth_hash(auth_path)
+    try:
+        data = json.loads(auth_path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise PrivateApiAuthError("auth.json is not readable JSON") from exc
+    if not isinstance(data, dict):
+        raise PrivateApiAuthError("auth.json is not a JSON object")
+
+    auth_mode = string_value(data.get("auth_mode"))
+    if auth_mode != "chatgpt":
+        raise PrivateApiAuthError("unsupported auth_mode; run codex login or an official codex command to refresh auth")
+
+    tokens = data.get("tokens")
+    if not isinstance(tokens, dict):
+        raise PrivateApiAuthError("missing tokens in auth.json; run codex login or an official codex command to refresh auth")
+
+    access_token = string_value(tokens.get("access_token"))
+    refresh_token = string_value(tokens.get("refresh_token"))
+    openai_account_id = string_value(tokens.get("account_id")) or string_value(data.get("account_id"))
+    if not access_token:
+        raise PrivateApiAuthError("missing tokens.access_token; run codex login or an official codex command to refresh auth")
+
+    return AuthMaterial(
+        account_id=account_id,
+        auth_path=auth_path,
+        access_token=access_token,
+        refresh_token=refresh_token,
+        raw_auth_hash=raw_hash,
+        openai_account_id=openai_account_id,
+    )
+
+
+def string_value(value: Any) -> str | None:
+    if isinstance(value, str) and value.strip():
+        return value.strip()
+    return None