sidiangongyuan/codex-skills-library / skills/feishu-paper-reading
feishu-paper-reading
VerifiedSearch, screen, deeply read, synthesize, and publish recent research papers for a user-specified topic, window, count, quality/attention balance, and language. Use for evidence-anchored literature digests, cross-paper comparisons, original-language excerpts, Chinese explanations, guided Feishu setup, or Feishu research reports.
| File | Kind | Size |
|---|---|---|
| LICENSE | other | 1.0 KB |
| SKILL.md | skill md | 14.7 KB |
| agents/openai.yaml | config | 569 B |
| references/evidence-policy.md | markdown | 4.2 KB |
| references/feishu-onboarding.md | markdown | 39.8 KB |
| references/feishu-publishing.md | markdown | 6.2 KB |
| references/report-schema.md | markdown | 4.7 KB |
| scripts/check_feishu_connection.py | script | 54.1 KB |
| scripts/feishu_process_environment.py | script | 1.5 KB |
| scripts/install_lark_cli.py | script | 38.0 KB |
| scripts/publication_checkpoint.py | script | 41.2 KB |
| scripts/run_feishu_auth.py | script | 79.7 KB |
| scripts/run_feishu_config_init.py | script | 60.5 KB |
| scripts/validate_digest.py | script | 16.7 KB |
scripts/run_feishu_auth.py
View on GitHub#!/usr/bin/env python3
"""Run a bounded Feishu/Lark user authorization without exposing credentials.
The helper owns one blocking ``lark-cli auth login`` child. Child output is
treated as sensitive: stdout is parsed into a tiny safe event, stderr is
drained and discarded, and neither stream is returned or written to disk.
The child is parent-death-contained so an abruptly terminated helper cannot
leave an authorization process running.
"""
from __future__ import annotations
import argparse
import contextlib
import datetime as dt
import hashlib
import io
import json
import os
import queue
import re
import select
import signal
import stat
import subprocess
import sys
import tempfile
import threading
import time
from dataclasses import dataclass
from pathlib import Path
from typing import Any, BinaryIO, Callable
from urllib.parse import unquote, urlsplit, urlunsplit
from feishu_process_environment import build_isolated_cli_environment
REQUIRED_SCOPES = "docx:document:create docx:document:readonly"
DEFAULT_TIMEOUT_SECONDS = 600.0
MAX_TIMEOUT_SECONDS = 1800.0
TERMINATION_GRACE_SECONDS = 3.0
STALE_ACTIVE_GRACE_SECONDS = 5.0
MAX_EVENT_BYTES = 256 * 1024
MAX_STATE_BYTES = 16 * 1024
STATE_FIELDS = frozenset(
{
"state",
"verification_url",
"expires_at",
"pid",
"started_at",
"updated_at",
"finished_at",
"reason",
"brand",
"profile",
"executable_sha256",
"config_dir",
"config_dir_identity_sha256",
"data_dir",
"data_dir_identity_sha256",
}
)
TERMINAL_STATES = frozenset({"succeeded", "failed", "timed_out", "cancelled"})
ACTIVE_STATES = frozenset({"starting", "pending"})
VALID_STATES = frozenset(
{
*ACTIVE_STATES,
*TERMINAL_STATES,
"absent",
"expired",
"cleaned",
}
)
VALID_REASONS = frozenset(
{
"login_process_starting",
"awaiting_user_verification",
"authorization_completed",
"lark_cli_not_found",
"lark_cli_path_invalid",
"lark_cli_hash_mismatch",
"login_launch_failed",
"login_process_failed",
"authorization_completion_unverified",
"authorization_timed_out",
"authorization_cancelled",
"unexpected_authorization_failure",
"state_file_conflict",
"state_file_invalid",
"no_state_file",
"authorization_expired",
"authorization_process_not_running",
"cleanup_refused_active_authorization",
"state_file_removed",
}
)
REASONS_BY_STATE = {
"starting": frozenset(
{"login_process_starting", "cleanup_refused_active_authorization"}
),
"pending": frozenset(
{
"awaiting_user_verification",
"cleanup_refused_active_authorization",
}
),
"succeeded": frozenset({"authorization_completed"}),
"failed": frozenset(
{
"lark_cli_not_found",
"lark_cli_path_invalid",
"lark_cli_hash_mismatch",
"login_launch_failed",
"login_process_failed",
"authorization_completion_unverified",
"unexpected_authorization_failure",
"state_file_conflict",
"state_file_invalid",
"authorization_process_not_running",
}
),
"timed_out": frozenset({"authorization_timed_out"}),
"cancelled": frozenset({"authorization_cancelled"}),
"absent": frozenset({"no_state_file"}),
"expired": frozenset({"authorization_expired"}),
"cleaned": frozenset({"no_state_file", "state_file_removed"}),
}
OFFICIAL_HOSTS = {
"auto": frozenset({"accounts.feishu.cn", "accounts.larksuite.com"}),
"feishu": frozenset({"accounts.feishu.cn"}),
"lark": frozenset({"accounts.larksuite.com"}),
}
URL_KEY_PRIORITY = (
"verification_uri_complete",
"verification_uri",
"verification_url",
)
SECRET_KEY_MARKERS = (
"token",
"secret",
"password",
"cookie",
"device_code",
"user_code",
"authorization",
)
@dataclass(frozen=True)
class SafeEvent:
"""The only information permitted to leave the child-output parser."""
verification_url: str | None = None
expires_at: float | None = None
authorization_complete: bool = False
Emitter = Callable[[dict[str, Any]], None]
ProcessFactory = Callable[..., Any]
_UNSET = object()
@contextlib.contextmanager
def _temporary_environment(overrides: dict[str, str]):
original = os.environ.copy()
try:
os.environ.update(overrides)
yield
finally:
os.environ.clear()
os.environ.update(original)
def _utc_timestamp(value: float | None = None) -> str:
instant = dt.datetime.fromtimestamp(
time.time() if value is None else value,
tz=dt.timezone.utc,
)
return instant.isoformat(timespec="seconds").replace("+00:00", "Z")
def _parse_timestamp(value: Any) -> float | None:
if not isinstance(value, str) or len(value) > 40:
return None
try:
parsed = dt.datetime.fromisoformat(value.replace("Z", "+00:00"))
except ValueError:
return None
if parsed.tzinfo is None:
return None
return parsed.timestamp()
def _normalized_key(value: Any) -> str:
text = str(value)
result: list[str] = []
for index, character in enumerate(text):
if (
index
and character.isupper()
and (text[index - 1].islower() or text[index - 1].isdigit())
):
result.append("_")
result.append(character.casefold() if character.isalnum() else "_")
return "_".join(part for part in "".join(result).split("_") if part)
def _secret_values(
value: Any,
*,
include_user_code: bool = True,
depth: int = 0,
) -> set[str]:
if depth > 8:
return set()
found: set[str] = set()
if isinstance(value, dict):
for key, child in list(value.items())[:128]:
normalized = _normalized_key(key)
if (
any(marker in normalized for marker in SECRET_KEY_MARKERS)
or normalized == "code"
):
if (
isinstance(child, str)
and child
and (include_user_code or normalized != "user_code")
):
found.add(child)
else:
found.update(
_secret_values(
child,
include_user_code=include_user_code,
depth=depth + 1,
)
)
elif isinstance(value, list):
for child in value[:128]:
found.update(
_secret_values(
child,
include_user_code=include_user_code,
depth=depth + 1,
)
)
return found
def _candidate_values(
value: Any,
wanted_keys: frozenset[str],
*,
depth: int = 0,
) -> list[Any]:
if depth > 8:
return []
found: list[Any] = []
if isinstance(value, dict):
for key, child in list(value.items())[:128]:
if _normalized_key(key) in wanted_keys:
found.append(child)
if isinstance(child, (dict, list)):
found.extend(
_candidate_values(child, wanted_keys, depth=depth + 1)
)
elif isinstance(value, list):
for child in value[:128]:
found.extend(_candidate_values(child, wanted_keys, depth=depth + 1))
return found
def _validate_verification_url(
value: Any,
*,
brand: str,
secret_values: set[str],
allow_opaque_suffix: bool = False,
) -> str | None:
if not isinstance(value, str) or not 1 <= len(value) <= 2048:
return None
if any(ord(character) < 32 for character in value):
return None
try:
parsed = urlsplit(value)
port = parsed.port
except ValueError:
return None
hostname = (parsed.hostname or "").casefold().rstrip(".")
if (
parsed.scheme.casefold() != "https"
or hostname not in OFFICIAL_HOSTS[brand]
or parsed.username is not None
or parsed.password is not None
or port not in {None, 443}
or not parsed.path.startswith("/")
or parsed.fragment
or "\\" in parsed.path
):
return None
if not allow_opaque_suffix and parsed.query:
return None
decoded = unquote(value)
for secret in secret_values:
if len(secret) >= 3 and (secret in value or secret in decoded):
return None
if not allow_opaque_suffix:
# Bare verification URLs are fixed pages. Reject opaque path
# components that could smuggle a user code into the trusted origin.
for component in parsed.path.split("/"):
if len(component) > 64:
return None
return urlunsplit(("https", hostname, parsed.path, "", ""))
# verification_uri_complete is defined by the official endpoint as an
# opaque URL. Preserve it byte-for-byte after validating its origin and
# excluding every secret except the user code embedded by that endpoint.
return value
def _expiry_from_payload(
payload: Any,
*,
now: float,
deadline: float,
) -> float:
candidates: list[float] = []
for value in _candidate_values(
payload,
frozenset({"expires_in", "expires_at", "expiration"}),
):
if isinstance(value, bool):
continue
if isinstance(value, (int, float)):
numeric = float(value)
if numeric > 10_000_000_000:
numeric /= 1000.0
if numeric < 10_000_000:
numeric = now + numeric
candidates.append(numeric)
elif isinstance(value, str):
parsed = _parse_timestamp(value)
if parsed is not None:
candidates.append(parsed)
usable = [candidate for candidate in candidates if candidate > now]
return min([deadline, *usable])
def _safe_event_from_payload(
payload: Any,
*,
brand: str,
now: float,
deadline: float,
) -> SafeEvent:
completion = _valid_completion_event(payload)
for key in URL_KEY_PRIORITY:
candidates = _candidate_values(payload, frozenset({key}))
for candidate in candidates:
complete_url = key == "verification_uri_complete"
secrets = _secret_values(
payload,
include_user_code=not complete_url,
)
validated = _validate_verification_url(
candidate,
brand=brand,
secret_values=secrets,
allow_opaque_suffix=complete_url,
)
if validated is not None:
return SafeEvent(
verification_url=validated,
expires_at=_expiry_from_payload(
payload,
now=now,
deadline=deadline,
),
authorization_complete=completion,
)
return SafeEvent(authorization_complete=completion)
def _scope_values(payload: dict[str, Any], key: str) -> set[str] | None:
value = payload.get(key)
if not isinstance(value, list) or len(value) > 256:
return None
result: set[str] = set()
for item in value:
if not isinstance(item, str) or not item or len(item) > 256:
return None
result.add(item)
return result
def _valid_completion_event(payload: Any) -> bool:
if not isinstance(payload, dict):
return False
if payload.get("event") != "authorization_complete":
return False
missing = _scope_values(payload, "missing")
requested = _scope_values(payload, "requested")
granted = _scope_values(payload, "granted")
required = set(REQUIRED_SCOPES.split())
return (
missing == set()
and requested is not None
and granted is not None
and required.issubset(requested)
and required.issubset(granted)
)
def _read_stdout_events(
stream: BinaryIO,
events: queue.Queue[SafeEvent | None],
*,
brand: str,
deadline: float,
) -> None:
try:
while True:
raw_line = stream.readline(MAX_EVENT_BYTES + 1)
if not raw_line:
break
if len(raw_line) > MAX_EVENT_BYTES:
continue
try:
payload = json.loads(raw_line.decode("utf-8", errors="replace"))
except (UnicodeError, json.JSONDecodeError, TypeError, ValueError):
continue
safe = _safe_event_from_payload(
payload,
brand=brand,
now=time.time(),
deadline=deadline,
)
if safe.verification_url is not None or safe.authorization_complete:
events.put(safe)
except Exception:
pass
finally:
events.put(None)
def _discard_stream(stream: BinaryIO) -> None:
try:
while stream.read(64 * 1024):
pass
except Exception:
pass
def _sanitize_state(
payload: Any,
*,
brand: str = "auto",
profile: str | None = None,
approved_executable_sha256: str | None = None,
config_dir: Any = _UNSET,
config_dir_identity_sha256: Any = _UNSET,
data_dir: Any = _UNSET,
data_dir_identity_sha256: Any = _UNSET,
) -> dict[str, Any] | None:
if not isinstance(payload, dict) or not set(payload).issubset(STATE_FIELDS):
return None
state = payload.get("state")
reason = payload.get("reason")
if (
state not in VALID_STATES
or reason not in VALID_REASONS
or reason not in REASONS_BY_STATE[state]
):
return None
result: dict[str, Any] = {"state": state, "reason": reason}
unbound_failure_reasons = {
"lark_cli_not_found",
"lark_cli_path_invalid",
"lark_cli_hash_mismatch",
"state_file_conflict",
"state_file_invalid",
}
binding_required = (
state in ACTIVE_STATES
or state in {"succeeded", "timed_out", "cancelled", "expired"}
or (state == "failed" and reason not in unbound_failure_reasons)
)
state_brand = payload.get("brand")
state_profile = payload.get("profile")
executable_sha256 = payload.get("executable_sha256")
binding_present = (
state_brand is not None
and state_profile is not None
and executable_sha256 is not None
)
if binding_required and not binding_present:
return None
if any(
value is not None
for value in (state_brand, state_profile, executable_sha256)
) and not binding_present:
return None
if binding_present:
if state_brand not in {"feishu", "lark"}:
return None
if brand != "auto" and state_brand != brand:
return None
result["brand"] = state_brand
if _validated_profile(state_profile) is None:
return None
if profile is not None and state_profile != profile:
return None
result["profile"] = state_profile
if not isinstance(executable_sha256, str) or not re.fullmatch(
r"[0-9a-f]{64}",
executable_sha256,
):
return None
if (
approved_executable_sha256 is not None
and executable_sha256 != approved_executable_sha256.casefold()
):
return None
result["executable_sha256"] = executable_sha256
state_config_dir = payload.get("config_dir")
state_config_identity = payload.get("config_dir_identity_sha256")
if state_config_dir is not None:
normalized_state_config_dir = _normalized_config_dir(
state_config_dir,
must_exist=False,
)
if normalized_state_config_dir is None:
return None
result["config_dir"] = normalized_state_config_dir
if (
not isinstance(state_config_identity, str)
or not re.fullmatch(r"[0-9a-f]{64}", state_config_identity)
):
return None
result["config_dir_identity_sha256"] = state_config_identity
elif state_config_identity is not None:
return None
if config_dir is not _UNSET and config_dir is not None:
normalized_expected_config_dir = _normalized_config_dir(
config_dir,
must_exist=False,
)
if (
normalized_expected_config_dir is None
or state_config_dir != normalized_expected_config_dir
):
return None
elif config_dir is None and state_config_dir is not None:
return None
if config_dir_identity_sha256 is not _UNSET:
if config_dir_identity_sha256 is None:
if state_config_identity is not None:
return None
elif state_config_identity != config_dir_identity_sha256:
return None
state_data_dir = payload.get("data_dir")
state_data_identity = payload.get("data_dir_identity_sha256")
if state_data_dir is not None:
if state_config_dir is None:
return None
normalized_state_data_dir = _normalized_config_dir(
state_data_dir,
must_exist=False,
)
if normalized_state_data_dir is None:
return None
if (
not isinstance(state_data_identity, str)
or not re.fullmatch(r"[0-9a-f]{64}", state_data_identity)
):
return None
result["data_dir"] = normalized_state_data_dir
result["data_dir_identity_sha256"] = state_data_identity
elif state_data_identity is not None:
return None
if data_dir is not _UNSET and data_dir is not None:
normalized_expected_data_dir = _normalized_config_dir(
data_dir,
must_exist=False,
)
if (
normalized_expected_data_dir is None
or state_data_dir != normalized_expected_data_dir
):
return None
elif data_dir is None and state_data_dir is not None:
return None
if data_dir_identity_sha256 is not _UNSET:
if data_dir_identity_sha256 is None:
if state_data_identity is not None:
return None
elif state_data_identity != data_dir_identity_sha256:
return None
for field in ("started_at", "updated_at", "finished_at", "expires_at"):
if field in payload:
if _parse_timestamp(payload[field]) is None:
return None
result[field] = payload[field]
if "pid" in payload:
pid = payload["pid"]
if isinstance(pid, bool) or not isinstance(pid, int) or not 0 < pid < 2**63:
return None
result["pid"] = pid
if "verification_url" in payload:
if state != "pending":
return None
validated = _validate_verification_url(
payload["verification_url"],
brand=brand,
secret_values=set(),
allow_opaque_suffix=True,
)
if validated is None:
return None
result["verification_url"] = validated
if state in TERMINAL_STATES and "verification_url" in result:
return None
return result
def _state_bytes(payload: dict[str, Any]) -> bytes:
sanitized = _sanitize_state(payload)
if sanitized is None:
raise ValueError("invalid safe state")
return (
json.dumps(
sanitized,
ensure_ascii=True,
separators=(",", ":"),
sort_keys=True,
)
+ "\n"
).encode("utf-8")
def _write_initial_state(path: Path, payload: dict[str, Any]) -> None:
data = _state_bytes(payload)
descriptor = os.open(
path,
os.O_WRONLY | os.O_CREAT | os.O_EXCL,
0o600,
)
try:
with os.fdopen(descriptor, "wb") as handle:
handle.write(data)
handle.flush()
os.fsync(handle.fileno())
except Exception:
with contextlib.suppress(OSError):
path.unlink()
raise
def _replace_state(path: Path, payload: dict[str, Any]) -> None:
data = _state_bytes(payload)
descriptor, temporary_name = tempfile.mkstemp(
prefix=f".{path.name}.",
suffix=".tmp",
dir=path.parent,
)
temporary = Path(temporary_name)
try:
with os.fdopen(descriptor, "wb") as handle:
with contextlib.suppress(OSError):
os.chmod(temporary, 0o600)
handle.write(data)
handle.flush()
os.fsync(handle.fileno())
os.replace(temporary, path)
finally:
with contextlib.suppress(OSError):
temporary.unlink()
def _read_state(
path: Path,
*,
brand: str = "auto",
profile: str | None = None,
approved_executable_sha256: str | None = None,
config_dir: Any = _UNSET,
config_dir_identity_sha256: Any = _UNSET,
data_dir: Any = _UNSET,
data_dir_identity_sha256: Any = _UNSET,
) -> dict[str, Any] | None:
try:
metadata = path.lstat()
if path.is_symlink() or not stat.S_ISREG(metadata.st_mode):
return None
if metadata.st_size > MAX_STATE_BYTES:
return None
with path.open("rb") as handle:
data = handle.read(MAX_STATE_BYTES + 1)
if len(data) > MAX_STATE_BYTES:
return None
payload = json.loads(data.decode("utf-8"))
except (OSError, UnicodeError, json.JSONDecodeError):
return None
return _sanitize_state(
payload,
brand=brand,
profile=profile,
approved_executable_sha256=approved_executable_sha256,
config_dir=config_dir,
config_dir_identity_sha256=config_dir_identity_sha256,
data_dir=data_dir,
data_dir_identity_sha256=data_dir_identity_sha256,
)
def _emit_json(payload: dict[str, Any]) -> None:
safe = _sanitize_state(payload)
if safe is None:
safe = {
"state": "failed",
"reason": "unexpected_authorization_failure",
"updated_at": _utc_timestamp(),
}
print(json.dumps(safe, ensure_ascii=True, sort_keys=True), flush=True)
def _command_for(
executable: str,
profile: str,
) -> list[str]:
return [
executable,
"--profile",
profile,
"auth",
"login",
"--scope",
REQUIRED_SCOPES,
"--json",
]
def _validated_executable(
value: str | None,
) -> str | None:
if not value:
return None
candidate = Path(value).expanduser()
if not candidate.is_absolute():
return None
try:
metadata = candidate.lstat()
if not stat.S_ISREG(metadata.st_mode) or candidate.is_symlink():
return None
suffix = candidate.suffix.casefold()
if suffix in {".bat", ".cmd", ".ps1"}:
return None
if os.name == "nt" and suffix != ".exe":
return None
if os.name != "nt" and not os.access(candidate, os.X_OK):
return None
except OSError:
return None
return os.fspath(candidate)
def _validated_profile(value: Any) -> str | None:
if not isinstance(value, str) or not value or value != value.strip():
return None
if len(value) > 128 or any(ord(character) < 32 for character in value):
return None
return value
def _normalized_config_dir(
value: Any,
*,
must_exist: bool,
) -> str | None:
if not isinstance(value, str) or not value or value != value.strip():
return None
candidate = Path(value).expanduser()
if not candidate.is_absolute():
return None
absolute = Path(os.path.abspath(os.fspath(candidate)))
if must_exist:
try:
metadata = absolute.lstat()
except OSError:
return None
reparse_point = bool(
getattr(metadata, "st_file_attributes", 0) & 0x400
)
if (
absolute.is_symlink()
or reparse_point
or not stat.S_ISDIR(metadata.st_mode)
):
return None
try:
resolved = absolute.resolve(strict=True)
except OSError:
return None
if os.path.normcase(os.fspath(resolved)) != os.path.normcase(
os.fspath(absolute)
):
return None
return os.fspath(resolved)
return os.fspath(absolute)
def _config_dir_identity(config_dir: str) -> str | None:
normalized = _normalized_config_dir(config_dir, must_exist=True)
if normalized is None:
return None
try:
metadata = Path(normalized).lstat()
except OSError:
return None
material = "\0".join(
(
os.path.normcase(normalized),
str(metadata.st_dev),
str(metadata.st_ino),
str(stat.S_IFMT(metadata.st_mode)),
)
)
return hashlib.sha256(material.encode("utf-8")).hexdigest()
def _sha256_file(path: str) -> str:
digest = hashlib.sha256()
with open(path, "rb") as handle:
for chunk in iter(lambda: handle.read(1024 * 1024), b""):
digest.update(chunk)
return digest.hexdigest()
class _WindowsJob:
def __init__(self, handle: int, close_handle: Callable[[int], Any]) -> None:
self._handle = handle
self._close_handle = close_handle
def close(self) -> None:
if self._handle:
self._close_handle(self._handle)
self._handle = 0
class _PosixProcess:
def __init__(self, pid: int, stdout_fd: int, stderr_fd: int) -> None:
self.pid = pid
self.stdout = os.fdopen(stdout_fd, "rb", buffering=0)
self.stderr = os.fdopen(stderr_fd, "rb", buffering=0)
self._returncode: int | None = None
@staticmethod
def _decode_status(status_value: int) -> int:
return os.waitstatus_to_exitcode(status_value)
def poll(self) -> int | None:
if self._returncode is not None:
return self._returncode
try:
waited_pid, status_value = os.waitpid(self.pid, os.WNOHANG)
except ChildProcessError:
return self._returncode
if waited_pid == self.pid:
self._returncode = self._decode_status(status_value)
return self._returncode
def wait(self, timeout: float | None = None) -> int:
deadline = None if timeout is None else time.time() + timeout
while True:
returncode = self.poll()
if returncode is not None:
return returncode
if deadline is not None and time.time() >= deadline:
raise subprocess.TimeoutExpired(["contained-lark-cli"], timeout)
time.sleep(0.05)
def _signal_group(self, signal_value: int) -> None:
with contextlib.suppress(ProcessLookupError):
os.killpg(self.pid, signal_value)
return
with contextlib.suppress(ProcessLookupError):
os.kill(self.pid, signal_value)
def terminate(self) -> None:
self._signal_group(signal.SIGTERM)
def kill(self) -> None:
self._signal_group(signal.SIGKILL)
class _PosixWatchdog:
def __init__(self, control_fd: int, watchdog_pid: int) -> None:
self._control_fd = control_fd
self._watchdog_pid = watchdog_pid
def close(self) -> None:
if self._control_fd >= 0:
with contextlib.suppress(OSError):
os.write(self._control_fd, b"D")
with contextlib.suppress(OSError):
os.close(self._control_fd)
self._control_fd = -1
if self._watchdog_pid:
deadline = time.time() + 2.0
while time.time() < deadline:
try:
waited, _ = os.waitpid(self._watchdog_pid, os.WNOHANG)
except ChildProcessError:
waited = self._watchdog_pid
if waited == self._watchdog_pid:
self._watchdog_pid = 0
break
time.sleep(0.05)
def _kill_posix_group(pid: int) -> None:
with contextlib.suppress(ProcessLookupError):
os.killpg(pid, signal.SIGTERM)
deadline = time.time() + TERMINATION_GRACE_SECONDS
while time.time() < deadline:
if not _pid_is_alive(pid):
return
time.sleep(0.05)
with contextlib.suppress(ProcessLookupError):
os.killpg(pid, signal.SIGKILL)
def _start_posix_contained(
command: list[str],
process_kwargs: dict[str, Any],
) -> tuple[_PosixProcess, _PosixWatchdog]:
environment = process_kwargs.get("env")
if environment is None:
environment = os.environ.copy()
if not isinstance(environment, dict) or not all(
isinstance(key, str) and isinstance(value, str)
for key, value in environment.items()
):
raise ValueError("contained process environment must contain strings")
working_directory = process_kwargs.get("cwd")
if working_directory is not None:
working_directory = os.fspath(working_directory)
stdout_read, stdout_write = os.pipe()
stderr_read, stderr_write = os.pipe()
gate_read, gate_write = os.pipe()
control_read, control_write = os.pipe()
ready_read, ready_write = os.pipe()
parent_pid = os.getpid()
child_pid = os.fork()
if child_pid == 0:
try:
for descriptor in (
stdout_read,
stderr_read,
gate_write,
control_read,
control_write,
ready_read,
ready_write,
):
os.close(descriptor)
os.setsid()
if os.read(gate_read, 1) != b"G" or os.getppid() != parent_pid:
os._exit(125)
os.close(gate_read)
devnull = os.open(os.devnull, os.O_RDONLY)
os.dup2(devnull, 0)
os.dup2(stdout_write, 1)
os.dup2(stderr_write, 2)
for descriptor in (devnull, stdout_write, stderr_write):
if descriptor > 2:
os.close(descriptor)
if working_directory is not None:
os.chdir(working_directory)
os.execve(command[0], command, environment)
except BaseException:
os._exit(126)
watchdog_pid = 0
try:
watchdog_pid = os.fork()
if watchdog_pid == 0:
try:
for descriptor in (
stdout_read,
stdout_write,
stderr_read,
stderr_write,
gate_read,
gate_write,
control_write,
ready_read,
):
os.close(descriptor)
os.write(ready_write, b"R")
os.close(ready_write)
while True:
readable, _, _ = select.select([control_read], [], [], 0.2)
if readable:
value = os.read(control_read, 1)
if value == b"D":
os._exit(0)
if value == b"":
_kill_posix_group(child_pid)
os._exit(0)
if os.getppid() != parent_pid:
_kill_posix_group(child_pid)
os._exit(0)
except BaseException:
_kill_posix_group(child_pid)
os._exit(1)
for descriptor in (
stdout_write,
stderr_write,
gate_read,
control_read,
ready_write,
):
os.close(descriptor)
readable, _, _ = select.select([ready_read], [], [], 5.0)
if not readable or os.read(ready_read, 1) != b"R":
raise RuntimeError("authorization watchdog did not become ready")
os.close(ready_read)
os.write(gate_write, b"G")
os.close(gate_write)
return (
_PosixProcess(child_pid, stdout_read, stderr_read),
_PosixWatchdog(control_write, watchdog_pid),
)
except BaseException:
for descriptor in (
stdout_read,
stdout_write,
stderr_read,
stderr_write,
gate_read,
gate_write,
control_read,
control_write,
ready_read,
ready_write,
):
with contextlib.suppress(OSError):
os.close(descriptor)
with contextlib.suppress(ProcessLookupError):
os.kill(child_pid, signal.SIGKILL)
if watchdog_pid:
with contextlib.suppress(ProcessLookupError):
os.kill(watchdog_pid, signal.SIGKILL)
raise
def _start_windows_contained(
command: list[str],
process_kwargs: dict[str, Any],
) -> tuple[Any, _WindowsJob]:
import ctypes
from ctypes import wintypes
class IO_COUNTERS(ctypes.Structure):
_fields_ = [
("ReadOperationCount", ctypes.c_ulonglong),
("WriteOperationCount", ctypes.c_ulonglong),
("OtherOperationCount", ctypes.c_ulonglong),
("ReadTransferCount", ctypes.c_ulonglong),
("WriteTransferCount", ctypes.c_ulonglong),
("OtherTransferCount", ctypes.c_ulonglong),
]
class JOBOBJECT_BASIC_LIMIT_INFORMATION(ctypes.Structure):
_fields_ = [
("PerProcessUserTimeLimit", ctypes.c_longlong),
("PerJobUserTimeLimit", ctypes.c_longlong),
("LimitFlags", wintypes.DWORD),
("MinimumWorkingSetSize", ctypes.c_size_t),
("MaximumWorkingSetSize", ctypes.c_size_t),
("ActiveProcessLimit", wintypes.DWORD),
("Affinity", ctypes.c_size_t),
("PriorityClass", wintypes.DWORD),
("SchedulingClass", wintypes.DWORD),
]
class JOBOBJECT_EXTENDED_LIMIT_INFORMATION(ctypes.Structure):
_fields_ = [
("BasicLimitInformation", JOBOBJECT_BASIC_LIMIT_INFORMATION),
("IoInfo", IO_COUNTERS),
("ProcessMemoryLimit", ctypes.c_size_t),
("JobMemoryLimit", ctypes.c_size_t),
("PeakProcessMemoryUsed", ctypes.c_size_t),
("PeakJobMemoryUsed", ctypes.c_size_t),
]
kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
ntdll = ctypes.WinDLL("ntdll", use_last_error=True)
kernel32.CreateJobObjectW.argtypes = [ctypes.c_void_p, wintypes.LPCWSTR]
kernel32.CreateJobObjectW.restype = wintypes.HANDLE
kernel32.SetInformationJobObject.argtypes = [
wintypes.HANDLE,
ctypes.c_int,
ctypes.c_void_p,
wintypes.DWORD,
]
kernel32.SetInformationJobObject.restype = wintypes.BOOL
kernel32.AssignProcessToJobObject.argtypes = [wintypes.HANDLE, wintypes.HANDLE]
kernel32.AssignProcessToJobObject.restype = wintypes.BOOL
kernel32.CloseHandle.argtypes = [wintypes.HANDLE]
kernel32.CloseHandle.restype = wintypes.BOOL
ntdll.NtResumeProcess.argtypes = [wintypes.HANDLE]
ntdll.NtResumeProcess.restype = ctypes.c_long
job_handle = kernel32.CreateJobObjectW(None, None)
if not job_handle:
raise OSError("could not create authorization containment job")
job = _WindowsJob(int(job_handle), kernel32.CloseHandle)
process: Any | None = None
try:
information = JOBOBJECT_EXTENDED_LIMIT_INFORMATION()
information.BasicLimitInformation.LimitFlags = 0x00002000
if not kernel32.SetInformationJobObject(
job_handle,
9,
ctypes.byref(information),
ctypes.sizeof(information),
):
raise OSError("could not configure authorization containment job")
process = subprocess.Popen(
command,
creationflags=0x00000004,
**process_kwargs,
)
process_handle = wintypes.HANDLE(int(process._handle))
if not kernel32.AssignProcessToJobObject(job_handle, process_handle):
raise OSError("could not bind authorization process to containment job")
if ntdll.NtResumeProcess(process_handle) != 0:
raise OSError("could not resume contained authorization process")
return process, job
except BaseException:
if process is not None:
with contextlib.suppress(Exception):
process.kill()
job.close()
raise
def _start_contained_process(
command: list[str],
*,
process_factory: ProcessFactory,
process_kwargs: dict[str, Any],
) -> tuple[Any, Any | None]:
if process_factory is not subprocess.Popen:
return process_factory(command, **process_kwargs), None
if os.name == "nt":
return _start_windows_contained(command, process_kwargs)
return _start_posix_contained(command, process_kwargs)
def _terminate_owned_child(process: Any) -> None:
if process.poll() is not None:
return
with contextlib.suppress(Exception):
process.terminate()
try:
process.wait(timeout=TERMINATION_GRACE_SECONDS)
return
except Exception:
pass
if process.poll() is None:
with contextlib.suppress(Exception):
process.kill()
with contextlib.suppress(Exception):
process.wait(timeout=TERMINATION_GRACE_SECONDS)
def _pid_is_alive(pid: int) -> bool:
"""Check liveness without sending a signal or taking process ownership."""
if os.name == "nt":
try:
import ctypes
from ctypes import wintypes
process_query_limited_information = 0x1000
still_active = 259
kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
kernel32.OpenProcess.argtypes = [
wintypes.DWORD,
wintypes.BOOL,
wintypes.DWORD,
]
kernel32.OpenProcess.restype = wintypes.HANDLE
kernel32.GetExitCodeProcess.argtypes = [
wintypes.HANDLE,
ctypes.POINTER(wintypes.DWORD),
]
kernel32.GetExitCodeProcess.restype = wintypes.BOOL
kernel32.CloseHandle.argtypes = [wintypes.HANDLE]
kernel32.CloseHandle.restype = wintypes.BOOL
handle = kernel32.OpenProcess(
process_query_limited_information,
False,
pid,
)
if not handle:
# ERROR_INVALID_PARAMETER is the documented result for a PID
# that does not exist. Access-denied and other failures are
# indeterminate, so callers that gate cleanup must fail closed.
return ctypes.get_last_error() != 87
try:
exit_code = wintypes.DWORD()
if not kernel32.GetExitCodeProcess(
handle,
ctypes.byref(exit_code),
):
return True
return exit_code.value == still_active
finally:
kernel32.CloseHandle(handle)
except Exception:
return True
try:
os.kill(pid, 0)
except ProcessLookupError:
return False
except (OSError, PermissionError):
return True
return True
def _terminal_state(
*,
state: str,
reason: str,
pid: int | None,
started_at: str,
binding: dict[str, str] | None = None,
) -> dict[str, Any]:
now = _utc_timestamp()
result: dict[str, Any] = {
"state": state,
"reason": reason,
"started_at": started_at,
"updated_at": now,
"finished_at": now,
}
if pid is not None:
result["pid"] = pid
if binding is not None:
result.update(binding)
return result
def run_authorization(
*,
state_path: Path,
brand: str,
profile: str,
timeout_seconds: float,
lark_cli_path: str,
approved_executable_sha256: str,
config_dir: str | None = None,
data_dir: str | None = None,
process_factory: ProcessFactory = subprocess.Popen,
emit: Emitter = _emit_json,
) -> int:
"""Start, monitor, and finish one credential-silent authorization."""
executable = _validated_executable(lark_cli_path)
validated_profile = _validated_profile(profile)
normalized_config_dir = (
_normalized_config_dir(config_dir, must_exist=True)
if config_dir is not None
else None
)
normalized_data_dir = (
_normalized_config_dir(data_dir, must_exist=True)
if data_dir is not None
else None
)
expected_sha256 = approved_executable_sha256.casefold()
if (
brand not in {"feishu", "lark"}
or executable is None
or validated_profile is None
or not re.fullmatch(r"[0-9a-f]{64}", expected_sha256)
or (config_dir is not None and normalized_config_dir is None)
or (data_dir is not None and normalized_data_dir is None)
or (normalized_data_dir is not None and normalized_config_dir is None)
):
emit(
{
"state": "failed",
"reason": "lark_cli_path_invalid",
"updated_at": _utc_timestamp(),
"finished_at": _utc_timestamp(),
}
)
return 3
try:
actual_sha256 = _sha256_file(executable)
except OSError:
actual_sha256 = ""
if actual_sha256 != expected_sha256:
emit(
{
"state": "failed",
"reason": "lark_cli_hash_mismatch",
"updated_at": _utc_timestamp(),
"finished_at": _utc_timestamp(),
}
)
return 3
binding = {
"brand": brand,
"profile": validated_profile,
"executable_sha256": actual_sha256,
}
if normalized_config_dir is not None:
binding["config_dir"] = normalized_config_dir
config_identity = _config_dir_identity(normalized_config_dir)
if config_identity is None:
emit(
{
"state": "failed",
"reason": "lark_cli_path_invalid",
"updated_at": _utc_timestamp(),
"finished_at": _utc_timestamp(),
}
)
return 3
binding["config_dir_identity_sha256"] = config_identity
if normalized_data_dir is not None:
data_identity = _config_dir_identity(normalized_data_dir)
if data_identity is None:
emit(
{
"state": "failed",
"reason": "lark_cli_path_invalid",
"updated_at": _utc_timestamp(),
"finished_at": _utc_timestamp(),
}
)
return 3
binding["data_dir"] = normalized_data_dir
binding["data_dir_identity_sha256"] = data_identity
started_epoch = time.time()
deadline = started_epoch + timeout_seconds
started_at = _utc_timestamp(started_epoch)
starting = {
"state": "starting",
"reason": "login_process_starting",
"started_at": started_at,
"updated_at": started_at,
"expires_at": _utc_timestamp(deadline),
**binding,
}
try:
_write_initial_state(state_path, starting)
except FileExistsError:
emit(
{
"state": "failed",
"reason": "state_file_conflict",
"updated_at": _utc_timestamp(),
"finished_at": _utc_timestamp(),
}
)
return 4
except OSError:
emit(
{
"state": "failed",
"reason": "unexpected_authorization_failure",
"updated_at": _utc_timestamp(),
"finished_at": _utc_timestamp(),
}
)
return 5
emit(starting)
command = _command_for(executable, validated_profile)
child_environment = build_isolated_cli_environment(
config_dir=normalized_config_dir,
data_dir=normalized_data_dir,
)
containment: Any | None = None
try:
executable_still_matches = _sha256_file(executable) == actual_sha256
except OSError:
executable_still_matches = False
config_dir_still_matches = (
normalized_config_dir is None
or _config_dir_identity(normalized_config_dir)
== binding.get("config_dir_identity_sha256")
)
data_dir_still_matches = (
normalized_data_dir is None
or _config_dir_identity(normalized_data_dir)
== binding.get("data_dir_identity_sha256")
)
if (
not executable_still_matches
or not config_dir_still_matches
or not data_dir_still_matches
):
terminal = _terminal_state(
state="failed",
reason=(
"lark_cli_hash_mismatch"
if not executable_still_matches
else "state_file_invalid"
),
pid=None,
started_at=started_at,
binding=binding,
)
_replace_state(state_path, terminal)
emit(terminal)
return 3
try:
process, containment = _start_contained_process(
command,
process_factory=process_factory,
process_kwargs={
"stdin": subprocess.DEVNULL,
"stdout": subprocess.PIPE,
"stderr": subprocess.PIPE,
"bufsize": 0,
"env": child_environment,
},
)
except Exception:
terminal = _terminal_state(
state="failed",
reason="login_launch_failed",
pid=None,
started_at=started_at,
binding=binding,
)
_replace_state(state_path, terminal)
emit(terminal)
return 3
try:
pid = int(process.pid)
running = {
**starting,
"pid": pid,
"updated_at": _utc_timestamp(),
}
_replace_state(state_path, running)
events: queue.Queue[SafeEvent | None] = queue.Queue()
stdout_thread = threading.Thread(
target=_read_stdout_events,
args=(process.stdout, events),
kwargs={"brand": brand, "deadline": deadline},
daemon=True,
)
stderr_thread = threading.Thread(
target=_discard_stream,
args=(process.stderr,),
daemon=True,
)
stdout_thread.start()
stderr_thread.start()
except Exception:
_terminate_owned_child(process)
if containment is not None:
containment.close()
terminal = _terminal_state(
state="failed",
reason="unexpected_authorization_failure",
pid=None,
started_at=started_at,
binding=binding,
)
with contextlib.suppress(OSError):
_replace_state(state_path, terminal)
emit(terminal)
return 5
stdout_finished = False
completion_verified = False
terminal_state: dict[str, Any] | None = None
try:
while terminal_state is None:
remaining = deadline - time.time()
if remaining <= 0:
_terminate_owned_child(process)
terminal_state = _terminal_state(
state="timed_out",
reason="authorization_timed_out",
pid=pid,
started_at=started_at,
binding=binding,
)
break
try:
event = events.get(timeout=min(0.2, remaining))
except queue.Empty:
event = ...
if event is None:
stdout_finished = True
elif isinstance(event, SafeEvent):
if event.authorization_complete:
completion_verified = True
if event.verification_url is not None:
pending = {
"state": "pending",
"reason": "awaiting_user_verification",
"verification_url": event.verification_url,
"expires_at": _utc_timestamp(
event.expires_at or deadline
),
"pid": pid,
"started_at": started_at,
"updated_at": _utc_timestamp(),
**binding,
}
_replace_state(state_path, pending)
emit(pending)
returncode = process.poll()
if returncode is not None and stdout_finished:
verified_success = returncode == 0 and completion_verified
terminal_state = _terminal_state(
state="succeeded" if verified_success else "failed",
reason=(
"authorization_completed"
if verified_success
else "authorization_completion_unverified"
if returncode == 0
else "login_process_failed"
),
pid=pid,
started_at=started_at,
binding=binding,
)
except KeyboardInterrupt:
_terminate_owned_child(process)
terminal_state = _terminal_state(
state="cancelled",
reason="authorization_cancelled",
pid=pid,
started_at=started_at,
binding=binding,
)
except Exception:
_terminate_owned_child(process)
terminal_state = _terminal_state(
state="failed",
reason="unexpected_authorization_failure",
pid=pid,
started_at=started_at,
binding=binding,
)
finally:
stdout_thread.join(timeout=1.0)
stderr_thread.join(timeout=1.0)
assert terminal_state is not None
if containment is not None:
containment.close()
_replace_state(state_path, terminal_state)
emit(terminal_state)
return 0 if terminal_state["state"] == "succeeded" else 2
def status(
state_path: Path,
*,
brand: str,
profile: str,
approved_executable_sha256: str,
config_dir: str | None = None,
data_dir: str | None = None,
emit: Emitter = _emit_json,
) -> int:
if config_dir is not None:
normalized_config_dir = _normalized_config_dir(
config_dir,
must_exist=True,
)
if normalized_config_dir is None:
emit(
{
"state": "failed",
"reason": "state_file_invalid",
"updated_at": _utc_timestamp(),
}
)
return 2
config_dir = normalized_config_dir
config_dir_identity = _config_dir_identity(config_dir)
if config_dir_identity is None:
emit(
{
"state": "failed",
"reason": "state_file_invalid",
"updated_at": _utc_timestamp(),
}
)
return 2
else:
config_dir_identity = None
if data_dir is not None:
normalized_data_dir = _normalized_config_dir(
data_dir,
must_exist=True,
)
if normalized_data_dir is None or config_dir is None:
emit(
{
"state": "failed",
"reason": "state_file_invalid",
"updated_at": _utc_timestamp(),
}
)
return 2
data_dir = normalized_data_dir
data_dir_identity = _config_dir_identity(data_dir)
if data_dir_identity is None:
emit(
{
"state": "failed",
"reason": "state_file_invalid",
"updated_at": _utc_timestamp(),
}
)
return 2
else:
data_dir_identity = None
if not state_path.exists():
emit(
{
"state": "absent",
"reason": "no_state_file",
"updated_at": _utc_timestamp(),
}
)
return 1
current = _read_state(
state_path,
brand=brand,
profile=profile,
approved_executable_sha256=approved_executable_sha256,
config_dir=config_dir,
config_dir_identity_sha256=config_dir_identity,
data_dir=data_dir,
data_dir_identity_sha256=data_dir_identity,
)
if current is None:
emit(
{
"state": "failed",
"reason": "state_file_invalid",
"updated_at": _utc_timestamp(),
}
)
return 2
expires_at = _parse_timestamp(current.get("expires_at"))
if current["state"] in ACTIVE_STATES and expires_at is not None:
if expires_at <= time.time():
expired = {
"state": "expired",
"reason": "authorization_expired",
"updated_at": _utc_timestamp(),
}
for field in (
"pid",
"started_at",
"brand",
"profile",
"executable_sha256",
"config_dir",
"config_dir_identity_sha256",
"data_dir",
"data_dir_identity_sha256",
):
if field in current:
expired[field] = current[field]
emit(expired)
return 2
pid = current.get("pid")
updated_at = _parse_timestamp(current.get("updated_at"))
stale = (
updated_at is not None
and time.time() - updated_at >= STALE_ACTIVE_GRACE_SECONDS
)
if (
current["state"] in ACTIVE_STATES
and isinstance(pid, int)
and stale
and not _pid_is_alive(pid)
):
stopped = {
"state": "failed",
"reason": "authorization_process_not_running",
"updated_at": _utc_timestamp(),
"finished_at": _utc_timestamp(),
"pid": pid,
}
for field in (
"started_at",
"brand",
"profile",
"executable_sha256",
"config_dir",
"config_dir_identity_sha256",
"data_dir",
"data_dir_identity_sha256",
):
if field in current:
stopped[field] = current[field]
emit(stopped)
return 2
emit(current)
return 0
def cleanup(
state_path: Path,
*,
brand: str,
profile: str,
approved_executable_sha256: str,
config_dir: str | None = None,
data_dir: str | None = None,
emit: Emitter = _emit_json,
) -> int:
if config_dir is not None:
normalized_config_dir = _normalized_config_dir(
config_dir,
must_exist=True,
)
if normalized_config_dir is None:
emit(
{
"state": "failed",
"reason": "state_file_invalid",
"updated_at": _utc_timestamp(),
}
)
return 2
config_dir = normalized_config_dir
config_dir_identity = _config_dir_identity(config_dir)
if config_dir_identity is None:
emit(
{
"state": "failed",
"reason": "state_file_invalid",
"updated_at": _utc_timestamp(),
}
)
return 2
else:
config_dir_identity = None
if data_dir is not None:
normalized_data_dir = _normalized_config_dir(
data_dir,
must_exist=True,
)
if normalized_data_dir is None or config_dir is None:
emit(
{
"state": "failed",
"reason": "state_file_invalid",
"updated_at": _utc_timestamp(),
}
)
return 2
data_dir = normalized_data_dir
data_dir_identity = _config_dir_identity(data_dir)
if data_dir_identity is None:
emit(
{
"state": "failed",
"reason": "state_file_invalid",
"updated_at": _utc_timestamp(),
}
)
return 2
else:
data_dir_identity = None
if not state_path.exists():
emit(
{
"state": "cleaned",
"reason": "no_state_file",
"updated_at": _utc_timestamp(),
}
)
return 0
current = _read_state(
state_path,
brand=brand,
profile=profile,
approved_executable_sha256=approved_executable_sha256,
config_dir=config_dir,
config_dir_identity_sha256=config_dir_identity,
data_dir=data_dir,
data_dir_identity_sha256=data_dir_identity,
)
if current is None:
emit(
{
"state": "failed",
"reason": "state_file_invalid",
"updated_at": _utc_timestamp(),
}
)
return 2
expires_at = _parse_timestamp(current.get("expires_at"))
active = current["state"] in ACTIVE_STATES
expired = expires_at is not None and expires_at <= time.time()
pid = current.get("pid")
process_may_be_active = isinstance(pid, int) and _pid_is_alive(pid)
updated_at = _parse_timestamp(current.get("updated_at"))
recently_updated = (
updated_at is not None
and time.time() - updated_at < STALE_ACTIVE_GRACE_SECONDS
)
starting_without_pid = pid is None and recently_updated
if active and (process_may_be_active or starting_without_pid):
response = {
"state": current["state"],
"reason": "cleanup_refused_active_authorization",
"updated_at": _utc_timestamp(),
}
for field in (
"pid",
"started_at",
"expires_at",
"brand",
"profile",
"executable_sha256",
"config_dir",
"config_dir_identity_sha256",
"data_dir",
"data_dir_identity_sha256",
):
if field in current:
response[field] = current[field]
emit(response)
return 2
try:
state_path.unlink()
except OSError:
emit(
{
"state": "failed",
"reason": "unexpected_authorization_failure",
"updated_at": _utc_timestamp(),
}
)
return 2
emit(
{
"state": "cleaned",
"reason": "state_file_removed",
"updated_at": _utc_timestamp(),
}
)
return 0
class _FakeProcess:
def __init__(self, command: list[str], stdout: bytes, stderr: bytes) -> None:
self.command = command
self.stdout = io.BytesIO(stdout)
self.stderr = io.BytesIO(stderr)
self.pid = 4242
self._returncode = 0
def poll(self) -> int:
return self._returncode
def wait(self, timeout: float | None = None) -> int:
del timeout
return self._returncode
def terminate(self) -> None:
self._returncode = -15
def kill(self) -> None:
self._returncode = -9
def _containment_probe_parent() -> int:
process, _containment = _start_contained_process(
[
sys.executable,
"-c",
"import time; time.sleep(30)",
],
process_factory=subprocess.Popen,
process_kwargs={
"stdin": subprocess.DEVNULL,
"stdout": subprocess.PIPE,
"stderr": subprocess.PIPE,
"bufsize": 0,
},
)
print(process.pid, flush=True)
os._exit(0)
def run_self_test() -> None:
device_code = "DEVICE_CODE_MUST_NEVER_ESCAPE_8675309"
user_code = "USER_CODE_MUST_NEVER_ESCAPE_2468"
token = "ACCESS_TOKEN_MUST_NEVER_ESCAPE_0123456789"
fake_complete_url = (
"https://accounts.feishu.cn/device"
f"?user_code={user_code}&source=lark-cli"
)
fake_output = (
json.dumps(
{
"event": "authorization_pending",
"verification_uri": "https://accounts.feishu.cn/device",
"verification_uri_complete": fake_complete_url,
"expires_in": 300,
"device_code": device_code,
"user_code": user_code,
"access_token": token,
}
).encode("utf-8")
+ b"\n"
+ json.dumps(
{
"event": "authorization_complete",
"access_token": token,
"refresh_token": token,
"requested": REQUIRED_SCOPES.split(),
"granted": [*REQUIRED_SCOPES.split(), "offline_access"],
"missing": [],
}
).encode("utf-8")
+ b"\n"
)
fake_stderr = f"debug device_code={device_code} token={token}\n".encode()
captured_commands: list[list[str]] = []
emitted: list[dict[str, Any]] = []
def fake_factory(command: list[str], **kwargs: Any) -> _FakeProcess:
del kwargs
captured_commands.append(list(command))
return _FakeProcess(command, fake_output, fake_stderr)
with tempfile.TemporaryDirectory() as temporary_directory:
root = Path(temporary_directory).resolve(strict=True)
state_path = root / "auth-state.json"
fake_lark_cli = root / (
"lark-cli.exe" if os.name == "nt" else "lark-cli"
)
fake_lark_cli.touch(mode=0o700)
with contextlib.suppress(OSError):
fake_lark_cli.chmod(0o700)
fake_digest = _sha256_file(os.fspath(fake_lark_cli))
shim = root / "lark-cli.cmd"
shim.write_text("@echo off\n", encoding="utf-8")
assert _validated_executable(os.fspath(shim)) is None
mismatch_emitted: list[dict[str, Any]] = []
mismatch_code = run_authorization(
state_path=root / "hash-mismatch.json",
brand="feishu",
profile="codex-paper-reading",
timeout_seconds=5,
lark_cli_path=os.fspath(fake_lark_cli),
approved_executable_sha256="0" * 64,
process_factory=lambda *_args, **_kwargs: (_ for _ in ()).throw(
AssertionError("a hash-mismatched executable must not run")
),
emit=lambda payload: mismatch_emitted.append(dict(payload)),
)
assert mismatch_code != 0
assert mismatch_emitted[-1]["reason"] == "lark_cli_hash_mismatch"
assert not (root / "hash-mismatch.json").exists()
captured_stdout = io.StringIO()
captured_stderr = io.StringIO()
with contextlib.redirect_stdout(captured_stdout), contextlib.redirect_stderr(
captured_stderr
):
returncode = run_authorization(
state_path=state_path,
brand="feishu",
profile="codex-paper-reading",
timeout_seconds=5,
lark_cli_path=os.fspath(fake_lark_cli),
approved_executable_sha256=fake_digest,
process_factory=fake_factory,
emit=lambda payload: emitted.append(dict(payload)),
)
assert returncode == 0
assert captured_commands == [
[
os.fspath(fake_lark_cli),
"--profile",
"codex-paper-reading",
"auth",
"login",
"--scope",
REQUIRED_SCOPES,
"--json",
]
]
flattened = "\n".join(
(
state_path.read_text(encoding="utf-8"),
json.dumps(emitted, sort_keys=True),
captured_stdout.getvalue(),
captured_stderr.getvalue(),
json.dumps(captured_commands),
)
)
for secret in (device_code, token):
assert secret not in flattened
assert f'"user_code": "{user_code}"' not in flattened
terminal = _read_state(state_path)
assert terminal is not None
assert terminal["state"] == "succeeded"
assert "verification_url" not in terminal
assert any(
item.get("verification_url") == fake_complete_url
for item in emitted
)
pending_events = [
item for item in emitted if item.get("state") == "pending"
]
assert pending_events
assert pending_events[-1]["brand"] == "feishu"
assert pending_events[-1]["profile"] == "codex-paper-reading"
assert pending_events[-1]["executable_sha256"] == fake_digest
assert not any(
forbidden in argument
for command in captured_commands
for argument in command
for forbidden in (
"--no-wait",
"--device-code",
device_code,
user_code,
token,
)
)
assert (
status(
state_path,
brand="feishu",
profile="wrong-profile",
approved_executable_sha256=fake_digest,
emit=lambda _: None,
)
!= 0
)
assert (
status(
state_path,
brand="feishu",
profile="codex-paper-reading",
approved_executable_sha256=fake_digest,
emit=lambda _: None,
)
== 0
)
assert (
cleanup(
state_path,
brand="feishu",
profile="codex-paper-reading",
approved_executable_sha256=fake_digest,
emit=lambda _: None,
)
== 0
)
assert not state_path.exists()
dedicated_config_dir = root / "dedicated-config"
dedicated_config_dir.mkdir(mode=0o700)
dedicated_data_dir = dedicated_config_dir / "data"
dedicated_data_dir.mkdir(mode=0o700)
dedicated_state = root / "dedicated-auth.json"
captured_environments: list[dict[str, str]] = []
def dedicated_factory(
command: list[str],
**kwargs: Any,
) -> _FakeProcess:
environment = kwargs.get("env")
assert isinstance(environment, dict)
captured_environments.append(dict(environment))
return _FakeProcess(command, fake_output, fake_stderr)
with _temporary_environment(
{
"LARKSUITE_CLI_APP_SECRET": token,
"LARKSUITE_CLI_CONFIG_DIR": "must-not-survive",
"LARKSUITE_CLI_PROXY_ENABLE": "true",
"LARKSUITE_CLI_PROXY_ADDRESS": "https://127.0.0.1:9443",
"LARKSUITE_CLI_CA_PATH": token,
"LARKSUITE_CLI_PROFILE": "ambient-profile",
"HTTPS_PROXY": "https://127.0.0.1:9443",
"SSL_CERT_FILE": token,
"OPENCLAW_HOME": "must-not-survive",
"OPENCLAW_CLI": "must-not-survive",
"HERMES_SESSION_KEY": token,
}
):
dedicated_code = run_authorization(
state_path=dedicated_state,
brand="feishu",
profile="codex-paper-reading-isolated",
timeout_seconds=5,
lark_cli_path=os.fspath(fake_lark_cli),
approved_executable_sha256=fake_digest,
config_dir=os.fspath(dedicated_config_dir),
data_dir=os.fspath(dedicated_data_dir),
process_factory=dedicated_factory,
emit=lambda _: None,
)
assert dedicated_code == 0
assert captured_environments
dedicated_environment = captured_environments[-1]
assert (
dedicated_environment["LARKSUITE_CLI_CONFIG_DIR"]
== os.fspath(dedicated_config_dir)
)
assert dedicated_environment["LARKSUITE_CLI_DATA_DIR"] == os.fspath(
dedicated_data_dir
)
for forbidden_variable in (
"LARKSUITE_CLI_APP_SECRET",
"LARKSUITE_CLI_PROXY_ENABLE",
"LARKSUITE_CLI_PROXY_ADDRESS",
"LARKSUITE_CLI_CA_PATH",
"LARKSUITE_CLI_PROFILE",
"HTTPS_PROXY",
"SSL_CERT_FILE",
"OPENCLAW_HOME",
"OPENCLAW_CLI",
"HERMES_SESSION_KEY",
):
assert forbidden_variable not in dedicated_environment
dedicated_payload = _read_state(dedicated_state)
assert dedicated_payload is not None
assert dedicated_payload["config_dir"] == os.fspath(dedicated_config_dir)
assert re.fullmatch(
r"[0-9a-f]{64}",
dedicated_payload["config_dir_identity_sha256"],
)
assert (
status(
dedicated_state,
brand="feishu",
profile="codex-paper-reading-isolated",
approved_executable_sha256=fake_digest,
config_dir=os.fspath(dedicated_config_dir),
data_dir=os.fspath(dedicated_data_dir),
emit=lambda _: None,
)
== 0
)
original_config_dir = root / "original-config"
dedicated_config_dir.rename(original_config_dir)
dedicated_config_dir.mkdir(mode=0o700)
replacement_data_dir = dedicated_config_dir / "data"
replacement_data_dir.mkdir(mode=0o700)
assert (
status(
dedicated_state,
brand="feishu",
profile="codex-paper-reading-isolated",
approved_executable_sha256=fake_digest,
config_dir=os.fspath(dedicated_config_dir),
data_dir=os.fspath(replacement_data_dir),
emit=lambda _: None,
)
!= 0
)
clean_exit_path = root / "clean-exit-state.json"
def incomplete_factory(
command: list[str],
**kwargs: Any,
) -> _FakeProcess:
del kwargs
return _FakeProcess(
command,
(
json.dumps(
{
"event": "device_authorization",
"verification_uri_complete": fake_complete_url,
"user_code": user_code,
"device_code": device_code,
}
).encode("utf-8")
+ b"\n"
),
fake_stderr,
)
incomplete_emitted: list[dict[str, Any]] = []
incomplete_code = run_authorization(
state_path=clean_exit_path,
brand="feishu",
profile="codex-paper-reading",
timeout_seconds=5,
lark_cli_path=os.fspath(fake_lark_cli),
approved_executable_sha256=fake_digest,
process_factory=incomplete_factory,
emit=lambda payload: incomplete_emitted.append(dict(payload)),
)
assert incomplete_code != 0
incomplete_state = _read_state(clean_exit_path)
assert incomplete_state is not None
assert incomplete_state["state"] == "failed"
assert (
incomplete_state["reason"]
== "authorization_completion_unverified"
)
incomplete_flattened = "\n".join(
(
clean_exit_path.read_text(encoding="utf-8"),
json.dumps(incomplete_emitted, sort_keys=True),
)
)
for secret in (device_code, token):
assert secret not in incomplete_flattened
recoverable_path = root / "recoverable.json"
_write_initial_state(
recoverable_path,
{
"state": "pending",
"reason": "awaiting_user_verification",
"verification_url": "https://accounts.feishu.cn/device",
"expires_at": _utc_timestamp(time.time() + 300),
"pid": os.getpid(),
"started_at": _utc_timestamp(),
"updated_at": _utc_timestamp(),
"brand": "feishu",
"profile": "codex-paper-reading",
"executable_sha256": fake_digest,
},
)
recoverable_status: list[dict[str, Any]] = []
assert (
status(
recoverable_path,
brand="feishu",
profile="codex-paper-reading",
approved_executable_sha256=fake_digest,
emit=lambda payload: recoverable_status.append(dict(payload)),
)
== 0
)
assert recoverable_status[-1]["state"] == "pending"
assert (
cleanup(
recoverable_path,
brand="feishu",
profile="codex-paper-reading",
approved_executable_sha256=fake_digest,
emit=lambda _: None,
)
!= 0
)
assert (
_validate_verification_url(
"https://evil.example/device",
brand="auto",
secret_values=set(),
)
is None
)
assert (
_validate_verification_url(
f"https://accounts.feishu.cn/device?code={user_code}",
brand="auto",
secret_values={user_code},
allow_opaque_suffix=True,
)
is None
)
direct_command = _command_for("/verified/lark-cli", "codex-paper-reading")
assert direct_command == [
"/verified/lark-cli",
"--profile",
"codex-paper-reading",
"auth",
"login",
"--scope",
REQUIRED_SCOPES,
"--json",
]
unexpected_exit = _safe_event_from_payload(
{"event": "authorization_complete", "missing": []},
brand="auto",
now=time.time(),
deadline=time.time() + 5,
)
assert unexpected_exit.authorization_complete is False
assert _validated_executable("relative/lark-cli") is None
assert _validated_executable(os.path.abspath("missing-lark-cli")) is None
probe_parent = subprocess.Popen(
[sys.executable, os.path.abspath(__file__), "--containment-probe-parent"],
stdin=subprocess.DEVNULL,
stdout=subprocess.PIPE,
stderr=subprocess.PIPE,
text=True,
)
assert probe_parent.stdout is not None
child_pid_text = probe_parent.stdout.readline().strip()
assert child_pid_text.isdigit()
contained_child_pid = int(child_pid_text)
assert probe_parent.wait(timeout=10) == 0
containment_deadline = time.time() + 8.0
while _pid_is_alive(contained_child_pid) and time.time() < containment_deadline:
time.sleep(0.1)
assert not _pid_is_alive(contained_child_pid)
def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
parser = argparse.ArgumentParser(
description=(
"Run or inspect one credential-silent Feishu/Lark authorization."
)
)
mode = parser.add_mutually_exclusive_group()
mode.add_argument("--status", action="store_true")
mode.add_argument("--cleanup", action="store_true")
mode.add_argument("--self-test", action="store_true")
parser.add_argument(
"--state-file",
help="explicit path for the ephemeral authorization state JSON",
)
parser.add_argument(
"--brand",
choices=tuple(OFFICIAL_HOSTS),
default="auto",
help="restrict the accepted verification host (default: auto)",
)
parser.add_argument(
"--lark-cli",
help="absolute path to the approved standalone lark-cli executable",
)
parser.add_argument(
"--approved-executable-sha256",
help="exact executable SHA-256 returned by the verified installer",
)
parser.add_argument(
"--profile",
help="exact named lark-cli profile to use for this authorization",
)
parser.add_argument(
"--config-dir",
help=(
"optional absolute dedicated lark-cli configuration directory; "
"when supplied it is bound into authorization state"
),
)
parser.add_argument(
"--data-dir",
help=(
"optional absolute protected-data directory paired with a "
"dedicated config directory"
),
)
parser.add_argument(
"--timeout-seconds",
type=float,
default=DEFAULT_TIMEOUT_SECONDS,
help=(
"authorization timeout in seconds "
f"(default: {DEFAULT_TIMEOUT_SECONDS:g}, max: "
f"{MAX_TIMEOUT_SECONDS:g})"
),
)
args = parser.parse_args(argv)
if not args.self_test and not args.state_file:
parser.error("--state-file is required")
if not args.self_test and (
args.brand == "auto"
or not args.approved_executable_sha256
or not args.profile
):
parser.error(
"authorization state operations require explicit --brand, --profile, "
"and --approved-executable-sha256"
)
mutating_run = not args.self_test and not args.status and not args.cleanup
if mutating_run:
if (
not args.lark_cli
):
parser.error(
"authorization requires explicit --lark-cli in addition to the "
"state binding arguments"
)
if not 1 <= args.timeout_seconds <= MAX_TIMEOUT_SECONDS:
parser.error(
f"--timeout-seconds must be between 1 and {MAX_TIMEOUT_SECONDS:g}"
)
return args
def main(argv: list[str] | None = None) -> int:
effective_argv = sys.argv[1:] if argv is None else argv
if effective_argv == ["--containment-probe-parent"]:
return _containment_probe_parent()
args = parse_args(effective_argv)
if args.self_test:
run_self_test()
print(json.dumps({"self_test": "passed"}, sort_keys=True))
return 0
assert args.state_file is not None
expanded = Path(args.state_file).expanduser()
state_path = Path(os.path.abspath(os.fspath(expanded)))
if not state_path.parent.is_dir():
_emit_json(
{
"state": "failed",
"reason": "unexpected_authorization_failure",
"updated_at": _utc_timestamp(),
}
)
return 5
if args.status:
assert args.profile is not None
assert args.approved_executable_sha256 is not None
return status(
state_path,
brand=args.brand,
profile=args.profile,
approved_executable_sha256=args.approved_executable_sha256,
config_dir=args.config_dir,
data_dir=args.data_dir,
)
if args.cleanup:
assert args.profile is not None
assert args.approved_executable_sha256 is not None
return cleanup(
state_path,
brand=args.brand,
profile=args.profile,
approved_executable_sha256=args.approved_executable_sha256,
config_dir=args.config_dir,
data_dir=args.data_dir,
)
try:
assert args.lark_cli is not None
assert args.approved_executable_sha256 is not None
assert args.profile is not None
return run_authorization(
state_path=state_path,
brand=args.brand,
profile=args.profile,
timeout_seconds=args.timeout_seconds,
lark_cli_path=args.lark_cli,
approved_executable_sha256=args.approved_executable_sha256,
config_dir=args.config_dir,
data_dir=args.data_dir,
)
except Exception:
_emit_json(
{
"state": "failed",
"reason": "unexpected_authorization_failure",
"updated_at": _utc_timestamp(),
}
)
return 5
if __name__ == "__main__":
raise SystemExit(main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| add-product-e2e-evalpaperclipai/paperclipAdd or extend a Paperclip full-stack runner E2E workflow, fixture, matcher, or report evidence path for local or Daytona execution. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| add-runner-evalpaperclipai/paperclipAdd or extend a Paperclip Runner protocol evaluation definition, roster, assertion, or report fixture with provenance and narrow validation. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| diagnose-why-work-stoppedpaperclipai/paperclipCompatibility entry point for failed, stalled, looping, or over-recovered Paperclip work. Use fix-failed-paperclip-run for the full diagnosis, regression, repair, real verification, and green-PR workflow; honor an explicitly requested diagnosis-only scope. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| fix-failed-paperclip-runpaperclipai/paperclipDiagnose and fix failed, stuck, slow, or incorrectly blocked Paperclip tasks and runs. Use with a task/run URL or failure report to trace the root cause, prove a regression red then green, check second-order effects, verify the real workflow, and deliver a PR with passing checks. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |