@oneciel-ai/ciel-runtime 0.2.24 → 0.2.25

package/CHANGELOG.md

@@ -3,6 +3,13 @@
 This file records stable Ciel Runtime releases. Changes are grouped by user-visible
 capability, followed by the complete commit ledger merged into each release.
 
+## 0.2.25 — 2026-08-23
+
+- Added the ZCode wrapper's authorization-code contract as a cross-platform manual
+  callback fallback when the ZCode CLI init endpoint returns HTTP 404.
+- Validates the callback target and OAuth state before token exchange, retains
+  transient tokens in memory, and leaves configuration unchanged on cancellation.
+
 ## 0.2.24 — 2026-08-23
 
 - Added cross-platform Z.AI OAuth login through ZCode's CLI init/poll contract and

package/ciel_runtime_support/runtime_constants.py

@@ -87,7 +87,7 @@ OPENCODE_ENDPOINT_ALIASES = {
 }
 
 APP_NAME = "Ciel Runtime"
-VERSION = "0.2.24"
+VERSION = "0.2.25"
 CREDITS = "Credits: One Ciel LLC"
 PRELAUNCH_CANCEL = 10
 PRELAUNCH_LAUNCH_CODEX = 11

package/ciel_runtime_support/zai_oauth.py

@@ -8,6 +8,7 @@ access tokens and ZCode JWTs are deliberately kept in memory.
 from __future__ import annotations
 
 import json
+import hmac
 import secrets
 import time
 import urllib.error
@@ -20,6 +21,9 @@ from typing import Any, Callable, Mapping
 
 
 ZCODE_OAUTH_BASE_URL = "https://zcode.z.ai/api/v1"
+ZAI_AUTHORIZE_ENDPOINT = "https://chat.z.ai/api/oauth/authorize"
+ZAI_OAUTH_CLIENT_ID = "client_P8X5CMWmlaRO9gyO-KSqtg"
+ZAI_OAUTH_REDIRECT_URI = "zcode://zai-auth/callback"
 ZAI_BUSINESS_BASE_URL = "https://api.z.ai"
 ZAI_OAUTH_PROVIDER = "zai"
 ZAI_CODING_PLAN_KEY_NAME = "zcode-api-key"
@@ -29,6 +33,10 @@ ZAI_OAUTH_TIMEOUT_SECONDS = 300.0
 class ZaiOAuthError(RuntimeError):
     """A bounded, secret-free OAuth diagnostic."""
 
+    def __init__(self, message: str, *, http_status: int | None = None) -> None:
+        super().__init__(message)
+        self.http_status = http_status
+
 
 @dataclass(frozen=True, slots=True)
 class ZaiOAuthInit:
@@ -69,7 +77,9 @@ class ZaiOAuthHttp:
             with urllib.request.urlopen(request, timeout=timeout) as response:
                 raw = response.read(1_048_577)
         except urllib.error.HTTPError as exc:
-            raise ZaiOAuthError(f"Z.AI OAuth HTTP {exc.code} at {url}") from exc
+            raise ZaiOAuthError(
+                f"Z.AI OAuth HTTP {exc.code} at {url}", http_status=exc.code
+            ) from exc
         except urllib.error.URLError as exc:
             reason = type(exc.reason).__name__ if exc.reason is not None else "network_error"
             raise ZaiOAuthError(f"Z.AI OAuth network error ({reason}) at {url}") from exc
@@ -118,6 +128,50 @@ class ZaiOAuthClient:
             raise ZaiOAuthError("Z.AI OAuth poll returned an invalid status.")
         return data
 
+    @staticmethod
+    def authorize_url(state: str) -> str:
+        query = urllib.parse.urlencode(
+            {
+                "client_id": ZAI_OAUTH_CLIENT_ID,
+                "redirect_uri": ZAI_OAUTH_REDIRECT_URI,
+                "response_type": "code",
+                "state": state,
+            }
+        )
+        return f"{ZAI_AUTHORIZE_ENDPOINT}?{query}"
+
+    def exchange_callback(self, callback_url: str, expected_state: str) -> Mapping[str, Any]:
+        try:
+            parsed = urllib.parse.urlparse(callback_url.strip())
+        except ValueError as exc:
+            raise ZaiOAuthError("Z.AI returned an invalid OAuth callback URL.") from exc
+        path = f"/{parsed.path.strip('/')}"
+        if parsed.scheme != "zcode" or parsed.netloc != "zai-auth" or path != "/callback":
+            raise ZaiOAuthError("Z.AI returned an unexpected OAuth callback target.")
+        query = urllib.parse.parse_qs(parsed.query)
+        state = str((query.get("state") or [""])[0])
+        if not state or not hmac.compare_digest(state, expected_state):
+            raise ZaiOAuthError("Z.AI OAuth state did not match. Please retry login.")
+        error = str((query.get("error_description") or query.get("error") or [""])[0])
+        if error:
+            safe_error = " ".join(error.split())[:300]
+            raise ZaiOAuthError(f"Z.AI authorization failed: {safe_error}")
+        code = str((query.get("code") or query.get("authCode") or [""])[0])
+        if not code:
+            raise ZaiOAuthError("Z.AI OAuth callback did not include an authorization code.")
+        response = self.http.request(
+            "POST",
+            f"{self.oauth_base_url.rstrip('/')}/oauth/token",
+            headers={"Content-Type": "application/json", "Accept": "application/json"},
+            body={
+                "provider": ZAI_OAUTH_PROVIDER,
+                "code": code,
+                "redirect_uri": ZAI_OAUTH_REDIRECT_URI,
+                "state": state,
+            },
+        )
+        return self._envelope_data(response, "token exchange")
+
     def resolve_coding_plan_api_key(self, oauth_access_token: str) -> str:
         login = self._business_data(
             "POST",
@@ -247,11 +301,22 @@ class ZaiOAuthService:
     now: Callable[[], float] = time.time
     sleep: Callable[[float], None] = time.sleep
     open_url: Callable[[str], bool] = webbrowser.open
+    read_callback: Callable[[str], str] = input
+    random_token: Callable[[], str] = lambda: secrets.token_hex(32)
     timeout_seconds: float = ZAI_OAUTH_TIMEOUT_SECONDS
 
     def login(self, *, no_browser: bool = False, on_authorize_url: Callable[[str], None]) -> ZaiOAuthResult:
-        poll_token = secrets.token_hex(32)
-        initialized = self.client.initialize(poll_token)
+        poll_token = self.random_token()
+        try:
+            initialized = self.client.initialize(poll_token)
+        except ZaiOAuthError as exc:
+            if exc.http_status != 404:
+                raise
+            return self._authorization_code_login(
+                state=poll_token,
+                no_browser=no_browser,
+                on_authorize_url=on_authorize_url,
+            )
         on_authorize_url(initialized.authorize_url)
         if not no_browser:
             self.open_url(initialized.authorize_url)
@@ -262,25 +327,55 @@ class ZaiOAuthService:
             if status == "failed":
                 raise ZaiOAuthError("Z.AI OAuth authorization was denied or failed.")
             if status == "ready":
-                zai = result.get("zai")
-                access_token = (
-                    str(zai.get("access_token") or "").strip()
-                    if isinstance(zai, Mapping)
-                    else ""
-                )
-                user = result.get("user")
-                user_id = (
-                    str(user.get("user_id") or "").strip()
-                    if isinstance(user, Mapping)
-                    else ""
-                )
-                if not access_token or not user_id:
-                    raise ZaiOAuthError("Z.AI OAuth ready response is missing credentials or user identity.")
-                api_key = self.client.resolve_coding_plan_api_key(access_token)
-                return ZaiOAuthResult(api_key=api_key, user_id=user_id)
+                return self._resolve_result(result)
             self.sleep(min(initialized.poll_interval_seconds, max(0.0, deadline - self.now())))
         raise ZaiOAuthError("Z.AI OAuth authorization timed out.")
 
+    def _authorization_code_login(
+        self,
+        *,
+        state: str,
+        no_browser: bool,
+        on_authorize_url: Callable[[str], None],
+    ) -> ZaiOAuthResult:
+        authorize_url = self.client.authorize_url(state)
+        on_authorize_url(authorize_url)
+        if not no_browser:
+            self.open_url(authorize_url)
+        try:
+            callback_url = self.read_callback(
+                "Paste the complete zcode://zai-auth/callback URL here: "
+            ).strip()
+        except (EOFError, KeyboardInterrupt) as exc:
+            raise ZaiOAuthError(
+                "Z.AI OAuth callback URL was not provided; login was not changed."
+            ) from exc
+        if not callback_url:
+            raise ZaiOAuthError(
+                "Z.AI OAuth callback URL was not provided; login was not changed."
+            )
+        return self._resolve_result(self.client.exchange_callback(callback_url, state))
+
+    def _resolve_result(self, result: Mapping[str, Any]) -> ZaiOAuthResult:
+        zai = result.get("zai")
+        access_token = (
+            str(zai.get("access_token") or "").strip()
+            if isinstance(zai, Mapping)
+            else ""
+        )
+        user = result.get("user")
+        user_id = (
+            str(user.get("user_id") or "").strip()
+            if isinstance(user, Mapping)
+            else ""
+        )
+        if not access_token or not user_id:
+            raise ZaiOAuthError(
+                "Z.AI OAuth ready response is missing credentials or user identity."
+            )
+        api_key = self.client.resolve_coding_plan_api_key(access_token)
+        return ZaiOAuthResult(api_key=api_key, user_id=user_id)
+
 
 @dataclass(frozen=True, slots=True)
 class ZaiOAuthRuntimePorts:

package/docs/CLI-Reference.md

@@ -104,9 +104,11 @@ ciel-runtimectl zai-oauth logout
 ```
 
 ZCode CLI의 Z.AI init/poll OAuth 흐름으로 로그인하고 Coding Plan API key를
-발급한다. `--no-browser`는 인증 URL만 출력한다. Ciel은 OAuth access token이나
-ZCode JWT를 디스크에 저장하지 않는다. `logout`은 OAuth로 만든 로컬 API key만
-지우며 원격 승인을 철회하지 않는다.
+발급한다. init endpoint가 404이면 공개 ZCode 래퍼와 동일한 authorization-code
+계약으로 전환하며, 터미널에 완전한 `zcode://zai-auth/callback` URL을 붙여 넣어
+완료한다. `--no-browser`는 브라우저를 자동으로 열지 않는다. Ciel은 OAuth access
+token이나 ZCode JWT를 디스크에 저장하지 않는다. `logout`은 OAuth로 만든 로컬
+API key만 지우며 원격 승인을 철회하지 않는다.
 
 #### `api-key`
 ```bash

package/docs/Providers.md

@@ -183,7 +183,7 @@ Anthropic thinking 객체나 문서로 확인되지 않은 GLM-5.2 effort 문자
 
 - GLM 시리즈 모델 제공.
 - 기본 모델: `glm-5.3[1m]`
-- ZCode CLI와 동일한 init/poll OAuth 흐름: `ciel-runtimectl zai-oauth login`
+- ZCode CLI의 init/poll 및 authorization-code fallback OAuth 흐름: `ciel-runtimectl zai-oauth login`
 - OAuth access token과 ZCode JWT는 메모리에만 유지하고, 최종 Coding Plan API key만 기존 Ciel credential 규칙으로 저장한다.
 - GLM-5.3은 reasoning을 끌 수 없으며 `low`, `high`, `max` effort만 사용한다.
 - Managed MCP 서버 포함: `web-search-prime`, `web-reader`, `zread`

package/docs/journal/2026/08/23/zcode-zai-oauth-glm53-support.okf

@@ -32,7 +32,14 @@
       "observed_result": "HTTP 404 with an empty response on 2026-08-23 from this workstation",
       "control": "The same result was reproduced by invoking the bundled zcode.cjs login command directly.",
       "config_unchanged": true,
-      "conclusion": "The local implementation cannot claim a completed live login while the upstream initialization endpoint returns 404."
+      "conclusion": "The init/poll path is currently unavailable and must trigger the authorization-code fallback."
+    },
+    "authorization_code_probe": {
+      "authorize_endpoint": "https://chat.z.ai/api/oauth/authorize",
+      "token_endpoint": "https://zcode.z.ai/api/v1/oauth/token",
+      "observed_result": "authorize returned HTTP 307 to /auth; token endpoint returned a structured code 2007 response for an intentionally invalid code",
+      "source_contract": "ZCode wrapper revision ce2dcfb and bundled zcode.cjs callback-stdin path",
+      "conclusion": "The authorization-code endpoints are live and can be used as the verified fallback contract; account authorization was not performed by the agent."
     }
   },
   "implementation": {
@@ -40,7 +47,8 @@
       "Added bounded init/poll client and browser/no-browser service.",
       "Added Coding Plan organization/project/API-key resolution.",
       "Persists only the final API key after the complete flow succeeds.",
-      "A failed flow does not mutate configuration; logout does not remove manually configured keys."
+      "A failed flow does not mutate configuration; logout does not remove manually configured keys.",
+      "Falls back on init HTTP 404 to a state-validated authorization-code callback pasted by the user."
     ],
     "glm_5_3": [
       "Added catalog/default/context metadata.",
@@ -51,12 +59,12 @@
   "verification": {
     "targeted": "33 passed",
     "unit": "1165 passed, 44 skipped",
-    "router": "929 passed",
+    "router": "932 passed",
     "channel": "381 passed, 80 skipped",
     "runtime": "252 passed, 12 skipped",
-    "aggregate": "2727 passed, 136 skipped",
-    "package_dry_run": "oneciel-ai-ciel-runtime-0.2.24.tgz; 415 files; 947347 bytes packed; 4335786 bytes unpacked",
-    "local_deployment": "installed into C:\\Users\\djlov\\.local\\share\\ciel-runtime; installed wrapper reported 0.2.24 and zai-oauth status exited 0",
-    "live_oauth": "blocked by confirmed upstream HTTP 404; no local credential or config was changed"
+    "aggregate": "2730 passed, 136 skipped",
+    "package_dry_run": "oneciel-ai-ciel-runtime-0.2.25.tgz; 415 files; 948640 bytes packed; 4341060 bytes unpacked",
+    "local_deployment": "installed into C:\\Users\\djlov\\.local\\share\\ciel-runtime; installed wrapper reported 0.2.25 and zai-oauth status exited 0",
+    "live_oauth": "init returned HTTP 404, the verified authorization URL was emitted, missing callback input cancelled with exit 1, and the config SHA-256 remained unchanged; successful account authorization was not performed"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oneciel-ai/ciel-runtime",
-  "version": "0.2.24",
+  "version": "0.2.25",
   "description": "Universal AI coding-agent runtime and model-routing layer for Claude, Codex, AGY, and compatible runtimes.",
   "license": "MIT",
   "author": "One Ciel LLC",