@oneciel-ai/ciel-runtime 0.2.27 → 0.2.28

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 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.28 — 2026-08-24
+
+- Replaced manual `zcode://` callback pasting in the Z.AI authorization-code
+  fallback with a one-shot, state-bound listener at
+  `http://localhost:9899/callback`.
+- Validate the exact callback host, port, path, and state before token exchange;
+  reject occupied ports, unrelated paths, oversized request targets, and stale
+  callbacks without changing the stored credential.
+- Use the same localhost redirect URI for authorization and token exchange, and
+  return a secret-free browser completion page.
+
 ## 0.2.27 — 2026-08-24
 
 - Repair Codex startup only when an invalid TOML file contains equivalent MCP

package/ciel_runtime_support/runtime_constants.py

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

package/ciel_runtime_support/zai_oauth.py

@@ -19,11 +19,16 @@ from dataclasses import dataclass
 from datetime import datetime, timezone
 from typing import Any, Callable, Mapping
 
+from .zai_oauth_callback import (
+    ZAI_OAUTH_CALLBACK_REDIRECT_URI,
+    ZaiOAuthLocalCallbackReceiver,
+)
+
 
 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_OAUTH_REDIRECT_URI = ZAI_OAUTH_CALLBACK_REDIRECT_URI
 ZAI_BUSINESS_BASE_URL = "https://api.z.ai"
 ZAI_OAUTH_PROVIDER = "zai"
 ZAI_CODING_PLAN_KEY_NAME = "zcode-api-key"
@@ -129,24 +134,42 @@ class ZaiOAuthClient:
         return data
 
     @staticmethod
-    def authorize_url(state: str) -> str:
+    def authorize_url(state: str, redirect_uri: str = ZAI_OAUTH_REDIRECT_URI) -> str:
         query = urllib.parse.urlencode(
             {
                 "client_id": ZAI_OAUTH_CLIENT_ID,
-                "redirect_uri": ZAI_OAUTH_REDIRECT_URI,
+                "redirect_uri": 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]:
+    def exchange_callback(
+        self,
+        callback_url: str,
+        expected_state: str,
+        redirect_uri: str = ZAI_OAUTH_REDIRECT_URI,
+    ) -> 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":
+        try:
+            expected = urllib.parse.urlparse(redirect_uri)
+            callback_target_matches = (
+                parsed.scheme.lower() == expected.scheme.lower()
+                and (parsed.hostname or "").lower() == (expected.hostname or "").lower()
+                and parsed.port == expected.port
+                and path == f"/{expected.path.strip('/')}"
+                and not parsed.username
+                and not parsed.password
+                and not parsed.fragment
+            )
+        except ValueError:
+            callback_target_matches = False
+        if not callback_target_matches:
             if (
                 parsed.scheme == "https"
                 and parsed.hostname == "chat.z.ai"
@@ -154,7 +177,7 @@ class ZaiOAuthClient:
             ):
                 raise ZaiOAuthError(
                     "The pasted URL is the authorization page, not the completed callback. "
-                    "Finish authorization and paste the complete zcode://zai-auth/callback URL."
+                    "Finish authorization in the browser and wait for the localhost callback."
                 )
             raise ZaiOAuthError("Z.AI returned an unexpected OAuth callback target.")
         query = urllib.parse.parse_qs(parsed.query)
@@ -175,7 +198,7 @@ class ZaiOAuthClient:
             body={
                 "provider": ZAI_OAUTH_PROVIDER,
                 "code": code,
-                "redirect_uri": ZAI_OAUTH_REDIRECT_URI,
+                "redirect_uri": redirect_uri,
                 "state": state,
             },
         )
@@ -310,7 +333,7 @@ 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
+    callback_receiver_factory: Callable[[str, float], Any] = ZaiOAuthLocalCallbackReceiver
     random_token: Callable[[], str] = lambda: secrets.token_hex(32)
     timeout_seconds: float = ZAI_OAUTH_TIMEOUT_SECONDS
 
@@ -347,23 +370,23 @@ class ZaiOAuthService:
         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."
+            with self.callback_receiver_factory(state, self.timeout_seconds) as receiver:
+                redirect_uri = receiver.redirect_uri
+                authorize_url = self.client.authorize_url(state, redirect_uri)
+                on_authorize_url(authorize_url)
+                if not no_browser:
+                    self.open_url(authorize_url)
+                callback_url = receiver.wait()
+        except RuntimeError as exc:
+            raise ZaiOAuthError(str(exc)) from exc
+        return self._resolve_result(
+            self.client.exchange_callback(
+                callback_url,
+                state,
+                redirect_uri=redirect_uri,
             )
-        return self._resolve_result(self.client.exchange_callback(callback_url, state))
+        )
 
     def _resolve_result(self, result: Mapping[str, Any]) -> ZaiOAuthResult:
         zai = result.get("zai")

package/ciel_runtime_support/zai_oauth_callback.py

@@ -0,0 +1,157 @@
+"""Loopback callback receiver for the Z.AI authorization-code flow."""
+
+from __future__ import annotations
+
+import hmac
+import socket
+import threading
+import urllib.parse
+from dataclasses import dataclass, field
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+
+ZAI_OAUTH_CALLBACK_HOST = "127.0.0.1"
+ZAI_OAUTH_CALLBACK_PUBLIC_HOST = "localhost"
+ZAI_OAUTH_CALLBACK_PORT = 9899
+ZAI_OAUTH_CALLBACK_PATH = "/callback"
+ZAI_OAUTH_CALLBACK_REDIRECT_URI = "http://localhost:9899/callback"
+_MAX_REQUEST_TARGET_BYTES = 8_192
+
+
+class _ExclusiveThreadingHTTPServer(ThreadingHTTPServer):
+    allow_reuse_address = False
+    daemon_threads = True
+
+    def server_bind(self) -> None:
+        if hasattr(socket, "SO_EXCLUSIVEADDRUSE"):
+            self.socket.setsockopt(socket.SOL_SOCKET, socket.SO_EXCLUSIVEADDRUSE, 1)
+        super().server_bind()
+
+
+@dataclass(slots=True)
+class ZaiOAuthLocalCallbackReceiver:
+    """Receive one state-bound OAuth callback on a loopback-only HTTP server."""
+
+    expected_state: str
+    timeout_seconds: float
+    host: str = ZAI_OAUTH_CALLBACK_HOST
+    port: int = ZAI_OAUTH_CALLBACK_PORT
+    public_host: str = ZAI_OAUTH_CALLBACK_PUBLIC_HOST
+    path: str = ZAI_OAUTH_CALLBACK_PATH
+    _server: _ExclusiveThreadingHTTPServer | None = field(default=None, init=False)
+    _thread: threading.Thread | None = field(default=None, init=False)
+    _callback_url: str = field(default="", init=False)
+    _callback_ready: threading.Event = field(default_factory=threading.Event, init=False)
+    _callback_lock: threading.Lock = field(default_factory=threading.Lock, init=False)
+
+    @property
+    def redirect_uri(self) -> str:
+        port = self._server.server_port if self._server is not None else self.port
+        return f"http://{self.public_host}:{port}{self.path}"
+
+    def __enter__(self) -> ZaiOAuthLocalCallbackReceiver:
+        receiver = self
+
+        class CallbackHandler(BaseHTTPRequestHandler):
+            def do_GET(self) -> None:  # noqa: N802 - BaseHTTPRequestHandler contract
+                receiver._handle_get(self)
+
+            def log_message(self, _format: str, *_args: object) -> None:
+                return
+
+        try:
+            self._server = _ExclusiveThreadingHTTPServer((self.host, self.port), CallbackHandler)
+        except OSError as exc:
+            raise RuntimeError(
+                f"Z.AI OAuth callback listener could not bind to {self.host}:{self.port}."
+            ) from exc
+        self._thread = threading.Thread(
+            target=self._server.serve_forever,
+            kwargs={"poll_interval": 0.05},
+            name="ciel-zai-oauth-callback",
+            daemon=True,
+        )
+        self._thread.start()
+        return self
+
+    def __exit__(self, _exc_type: object, _exc: object, _traceback: object) -> None:
+        server, thread = self._server, self._thread
+        if server is not None:
+            server.shutdown()
+            server.server_close()
+        if thread is not None:
+            thread.join(timeout=2.0)
+        self._server = None
+        self._thread = None
+
+    def wait(self) -> str:
+        if self._server is None:
+            raise RuntimeError("Z.AI OAuth callback listener was not started.")
+        if not self._callback_ready.wait(max(0.0, self.timeout_seconds)):
+            raise RuntimeError(
+                f"Z.AI OAuth localhost callback timed out after {int(self.timeout_seconds)} seconds."
+            )
+        with self._callback_lock:
+            callback_url = self._callback_url
+        if not callback_url:
+            raise RuntimeError("Z.AI OAuth localhost callback was empty.")
+        return callback_url
+
+    def _handle_get(self, handler: BaseHTTPRequestHandler) -> None:
+        if len(handler.path.encode("utf-8", errors="ignore")) > _MAX_REQUEST_TARGET_BYTES:
+            self._respond(handler, 414, "OAuth callback request was too large.")
+            return
+        try:
+            parsed = urllib.parse.urlsplit(handler.path)
+            query = urllib.parse.parse_qs(parsed.query, keep_blank_values=True)
+        except ValueError:
+            self._respond(handler, 400, "Invalid OAuth callback request.")
+            return
+        if parsed.path != self.path:
+            self._respond(handler, 404, "OAuth callback path was not found.")
+            return
+        state = str((query.get("state") or [""])[0])
+        if not state or not hmac.compare_digest(state, self.expected_state):
+            self._respond(handler, 400, "OAuth callback state did not match.")
+            return
+        with self._callback_lock:
+            if self._callback_url:
+                self._respond(handler, 409, "OAuth callback was already received.")
+                return
+            self._callback_url = (
+                f"{self.redirect_uri}?{parsed.query}" if parsed.query else self.redirect_uri
+            )
+        self._respond(
+            handler,
+            200,
+            "Z.AI authorization received. You may close this tab and return to Ciel Runtime.",
+        )
+        self._callback_ready.set()
+
+    @staticmethod
+    def _respond(handler: BaseHTTPRequestHandler, status: int, message: str) -> None:
+        body = (
+            "<!doctype html><meta charset=\"utf-8\"><title>Ciel Runtime OAuth</title>"
+            f"<p>{message}</p>"
+        ).encode("utf-8")
+        handler.send_response(status)
+        handler.send_header("Content-Type", "text/html; charset=utf-8")
+        handler.send_header("Content-Length", str(len(body)))
+        handler.send_header("Cache-Control", "no-store")
+        handler.send_header("Connection", "close")
+        handler.end_headers()
+        handler.close_connection = True
+        try:
+            handler.wfile.write(body)
+        except (BrokenPipeError, ConnectionResetError):
+            pass
+
+
+__all__ = [
+    "ZAI_OAUTH_CALLBACK_HOST",
+    "ZAI_OAUTH_CALLBACK_PATH",
+    "ZAI_OAUTH_CALLBACK_PORT",
+    "ZAI_OAUTH_CALLBACK_PUBLIC_HOST",
+    "ZAI_OAUTH_CALLBACK_REDIRECT_URI",
+    "ZaiOAuthLocalCallbackReceiver",
+]

package/docs/CLI-Reference.md

@@ -120,10 +120,13 @@ ciel-runtimectl zai-oauth logout
 
 ZCode CLI의 Z.AI init/poll OAuth 흐름으로 로그인하고 Coding Plan 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만 지우며 원격 승인을 철회하지 않는다.
+계약으로 전환하며, `http://localhost:9899/callback`의 일회성 loopback listener가
+브라우저 콜백을 자동으로 수신한다. `--no-browser`는 브라우저를 자동으로 열지
+않지만 동일한 listener에서 기다린다. 브라우저와 Ciel Runtime이 서로 다른
+머신이면 먼저 `ssh -L 9899:127.0.0.1:9899 user@runtime-host`처럼 callback port를
+전달해야 한다. 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 및 authorization-code fallback OAuth 흐름: `ciel-runtimectl zai-oauth login`
+- ZCode CLI의 init/poll 및 localhost:9899 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/24/kevin-codex-config-mia-zai-oauth-recovery.okf

@@ -6,7 +6,7 @@ knowledge:
     objective: >-
       Restore Kevin's Codex startup and prevent Mia's Z.AI OAuth callback input
       error from terminating the Ciel prelaunch interface.
-    status: validation-in-progress
+    status: complete
 
   evidence:
     kevin:
@@ -23,6 +23,11 @@ knowledge:
         toml_valid: true
         codex_mcp_list_exit: 0
         ciel_runtime_codex_version_exit: 0
+        nightly_installed: 0.2.27-nightly.20260824-061806.8e24b2e
+      post_install_observation: >-
+        The first Ciel-routed Codex version probe encountered a transient router
+        port claim failure on 8802. The listener was absent immediately after the
+        failure, and the identical probe then exited 0 with codex-cli 0.149.1.
       backup: /home/kevin-codex/.codex/config.toml.ciel-repair-20260824T0555Z.bak
       attribution: >-
         The config and AI-Net managed artifacts were written in the same second,
@@ -33,6 +38,10 @@ knowledge:
       source_behavior: >-
         ZaiOAuthClient rejected the target with ZaiOAuthError and the prelaunch
         API-key panel invoked the action without a RuntimeError boundary.
+      nightly_installed: 0.2.27-nightly.20260824-061806.8e24b2e
+      installed_guard_probe:
+        exit: 0
+        result: authorize page rejected with completed callback guidance
 
   implementation:
     codex_preflight:
@@ -64,6 +73,10 @@ knowledge:
       - npm package dry run for version 0.2.27
       - local install reports ciel-runtime 0.2.27
       - local Ciel-routed Codex version exit 0
-    pending:
-      - main and nightly publication
-      - Kevin and Mia nightly installation verification
+      - npm latest reports 0.2.27
+      - npm nightly reports 0.2.27-nightly.20260824-061806.8e24b2e
+      - registry-installed nightly execution reports ciel-runtime 0.2.27
+      - main CI and npm publication workflows succeeded
+      - nightly CI and npm publication workflows succeeded
+      - Kevin nightly installation and Ciel-routed Codex version probe exited 0
+      - Mia nightly installation and installed OAuth guard probe exited 0

package/docs/journal/2026/08/24/mia-zai-oauth-state-mismatch.okf

@@ -0,0 +1,74 @@
+okf_version: "1.0"
+knowledge:
+  task:
+    id: mia-zai-oauth-state-mismatch-20260824
+    date: "2026-08-24"
+    objective: >-
+      Diagnose Mia's Z.AI OAuth state mismatch without weakening the OAuth
+      request-to-callback binding.
+    status: diagnosis-complete
+
+  evidence:
+    supplied_values:
+      authorization_state_length: 64
+      callback_state_length: 64
+      states_equal: false
+      secrets_recorded: false
+    installed_runtime:
+      host: mia@100.95.132.58
+      version: 0.2.27-nightly.20260824-061806.8e24b2e
+    ciel_source:
+      comparison: hmac.compare_digest(callback_state, expected_state)
+      token_exchange_before_mismatch: false
+    zcode_source:
+      repository: https://github.com/kingsword09/zcode-cli.git
+      revision: ce2dcfbdeee3e5cca54095fbe1191fb2d03c10db
+      behavior: rejects callbacks whose state differs from the active login state
+    live_provider_probe:
+      initial_endpoint_status: 307
+      redirect_target: /auth
+      state_preserved: true
+      browser_authorization_page_state_preserved: true
+    mia_recovery_flow:
+      oauth_status: connected
+      stale_waiting_process: terminated
+      expected_callback: complete callback URL from the same authorization flow
+    localhost_callback_test:
+      redirect_uri: http://localhost:9899/callback
+      provider_accepted_redirect_uri: true
+      callback_received: true
+      authorization_code_present: true
+      state_match: true
+      authorization_code_recorded: false
+    post_login_provider_test:
+      ciel_route:
+        endpoint: https://api.z.ai/api/anthropic
+        model: glm-5.3
+        status: 429
+        provider_code: "1113"
+        provider_message: Insufficient balance or no resource package
+      official_zcode_direct:
+        client: zcode-app-cli 3.8.1-15
+        runtime: 0.16.3
+        endpoint: https://api.z.ai/api/anthropic
+        model: glm-5.3
+        same_oauth_resolved_key: true
+        status: 429
+        provider_code: "1113"
+        provider_message: Insufficient balance or no resource package
+
+  conclusion:
+    confirmed: >-
+      The callback supplied by the user was not bound to the active authorization
+      request. Accepting it would bypass the OAuth CSRF state check and is not a
+      valid fix.
+    code_change_required: false
+    provider_model: >-
+      Z.AI Direct API and Z.AI Coding Plan are distinct credential and
+      entitlement profiles. ZCode remains a client, not the upstream provider.
+    retry_cause_excluded:
+      - Ciel Runtime User-Agent difference
+      - Ciel Runtime request-shape difference
+    unresolved_external_state: >-
+      The OAuth-resolved Coding Plan key has no usable resource package on the
+      upstream account according to provider code 1113.

package/docs/journal/2026/08/24/zai-localhost-oauth-callback.okf

@@ -0,0 +1,70 @@
+okf_version: "1.0"
+knowledge:
+  task:
+    id: zai-localhost-oauth-callback-20260824
+    date: "2026-08-24"
+    objective: >-
+      Replace manual Z.AI custom-scheme callback entry with an automatic,
+      state-bound localhost OAuth callback receiver.
+    status: verified
+
+  requirements:
+    redirect_uri: http://localhost:9899/callback
+    bind_address: 127.0.0.1
+    automatic_browser_callback: true
+    preserve_state_validation: true
+    token_exchange_redirect_must_match: true
+
+  implementation:
+    receiver: ciel_runtime_support/zai_oauth_callback.py
+    integration: ciel_runtime_support/zai_oauth.py
+    lifecycle:
+      - bind listener before presenting the authorization URL
+      - accept only the configured path and matching state
+      - return a secret-free browser completion page
+      - exchange the callback using the same redirect URI
+      - close the one-shot listener after success or timeout
+    remote_runtime: >-
+      Forward local port 9899 to runtime-host 127.0.0.1:9899 when the browser
+      and Ciel Runtime run on different machines.
+
+  evidence:
+    provider_browser_probe:
+      redirect_uri: http://localhost:9899/callback
+      provider_accepted_redirect_uri: true
+      callback_received: true
+      state_match: true
+      authorization_code_recorded: false
+    authorization_plan_screen:
+      observed_options:
+        - Start Plan
+        - Individual Plan
+        - API key
+      endpoint_urls_verified: false
+      conclusion: >-
+        The screen proves that three authorization choices are exposed. It does
+        not by itself prove that three different API endpoint URLs are used.
+    focused_tests:
+      status: passed
+      count: 18
+    final_verification:
+      status: passed
+      local_install_version: 0.2.28
+      callback_uri: http://localhost:9899/callback
+      callback_http_status: 200
+      callback_url_exact_match: true
+      browser_response_contains_authorization_code: false
+      listener_port_released_after_completion: true
+      full_test_groups:
+        unit:
+          tests: 1172
+          skipped: 44
+        router:
+          tests: 942
+        channel:
+          tests: 381
+          skipped: 80
+        runtime:
+          tests: 255
+          skipped: 12
+      full_test_exit_code: 0

package/package.json

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