luna/twitter-cli-cookiefile
1
0
Fork 0
Code Issues Pull Requests Actions Releases Activity

feat: improve cookie extraction diagnostics and add doctor command

Browse Source 
- Add _diagnose_keychain_issues() for macOS Keychain/SSH detection
- Extraction functions now return (cookies, diagnostics) tuples
- Error messages include actionable Keychain hints (e.g. unlock-keychain)
- Add 'twitter doctor' diagnostic command for troubleshooting
- Enhance bug_report.yml with browser/access method/diagnostics fields
- Expand README troubleshooting (EN+CN) with Keychain/SSH solutions
- Add 5 new tests for Keychain diagnostics

Closes #11
This commit is contained in:
jackwener
2026-03-11 16:53:06 +08:00
parent 47be88e62d
commit 60e1e7c580
5 changed files with 366 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files

123
twitter_cli/auth.py
View File

@@ -30,6 +30,48 @@ def _is_twitter_domain(domain: str) -> bool:
return domain in _TWITTER_DOMAINS or domain.endswith(".x.com") or domain.endswith(".twitter.com")
# ---------------------------------------------------------------------------
# Keychain / environment diagnostics
# ---------------------------------------------------------------------------
_KEYCHAIN_ERROR_KEYWORDS = (
"key for cookie decryption",
"safe storage",
"keychain",
"secretstorage",
)
def _diagnose_keychain_issues(diagnostics: List[str]) -> Optional[str]:
"""Analyse extraction diagnostics for Keychain permission issues.
Returns a user-friendly hint string, or None.
"""
lowered = " ".join(diagnostics).lower()
if not any(kw in lowered for kw in _KEYCHAIN_ERROR_KEYWORDS):
return None
is_ssh = bool(os.environ.get("SSH_CLIENT") or os.environ.get("SSH_TTY") or os.environ.get("SSH_CONNECTION"))
if sys.platform == "darwin":
if is_ssh:
return (
"macOS Keychain is locked (SSH session detected).\n"
" Fix: security unlock-keychain ~/Library/Keychains/login.keychain-db\n"
" Then retry the command."
)
return (
"macOS Keychain permission denied — your terminal is not authorized to read browser cookie encryption keys.\n"
" Fix: Open Keychain Access → search for \"<Browser> Safe Storage\" → Access Control → add your Terminal app.\n"
" Or click \"Always Allow\" when the Keychain authorization popup appears."
)
# Linux: gnome-keyring / SecretStorage issues
return (
"System keyring access failed — the cookie encryption key could not be retrieved.\n"
" If running headless or via SSH, ensure your keyring daemon is unlocked."
)
def load_from_env() -> Optional[Dict[str, str]]:
"""Load cookies from environment variables."""
auth_token = os.environ.get("TWITTER_AUTH_TOKEN", "")
@@ -197,7 +239,7 @@ def _iter_chrome_cookie_files(browser_name: str) -> List[str]:
return paths
def _extract_in_process() -> Optional[Dict[str, str]]:
def _extract_in_process() -> Tuple[Optional[Dict[str, str]], List[str]]:
"""Extract cookies in the main process (required on macOS for Keychain access).
On macOS, Chrome encrypts cookies using a key stored in the system Keychain.
@@ -205,12 +247,14 @@ def _extract_in_process() -> Optional[Dict[str, str]]:
browser_cookie3 must run in the main process to decrypt cookies.
For Chromium-based browsers, iterates all profiles to find Twitter cookies.
Returns (cookies_dict | None, diagnostics_list).
"""
try:
import browser_cookie3
except ImportError:
logger.debug("browser_cookie3 not installed, skipping in-process extraction")
return None
return None, ["browser-cookie3 not installed"]
browsers = [
("arc", browser_cookie3.arc),
@@ -219,7 +263,8 @@ def _extract_in_process() -> Optional[Dict[str, str]]:
("firefox", browser_cookie3.firefox),
("brave", browser_cookie3.brave),
]
attempts = []
attempts: List[str] = []
diagnostics: List[str] = []
for name, fn in browsers:
if name in _CHROMIUM_BASE_DIRS:
@@ -232,11 +277,12 @@ def _extract_in_process() -> Optional[Dict[str, str]]:
except Exception as e:
logger.debug("%s in-process extraction failed: %s", name, e)
attempts.append("%s=%s" % (name, type(e).__name__))
diagnostics.append("%s: %s" % (name, e))
continue
cookies = _extract_cookies_from_jar(jar, source="%s(in-process)" % name)
if cookies:
logger.info("Found cookies in %s (in-process, default)", name)
return cookies
return cookies, diagnostics
attempts.append("%s=no-cookies" % name)
continue
@@ -247,11 +293,12 @@ def _extract_in_process() -> Optional[Dict[str, str]]:
except Exception as e:
logger.debug("%s[%s] in-process extraction failed: %s", name, profile_name, e)
attempts.append("%s[%s]=%s" % (name, profile_name, type(e).__name__))
diagnostics.append("%s[%s]: %s" % (name, profile_name, e))
continue
cookies = _extract_cookies_from_jar(jar, source="%s[%s](in-process)" % (name, profile_name))
if cookies:
logger.info("Found cookies in %s profile '%s' (in-process)", name, profile_name)
return cookies
return cookies, diagnostics
attempts.append("%s[%s]=no-cookies" % (name, profile_name))
else:
# Non-Chromium (Firefox): use default behavior
@@ -260,20 +307,24 @@ def _extract_in_process() -> Optional[Dict[str, str]]:
except Exception as e:
logger.debug("%s in-process extraction failed: %s", name, e)
attempts.append("%s=%s" % (name, type(e).__name__))
diagnostics.append("%s: %s" % (name, e))
continue
cookies = _extract_cookies_from_jar(jar, source="%s(in-process)" % name)
if cookies:
logger.info("Found cookies in %s (in-process)", name)
return cookies
return cookies, diagnostics
attempts.append("%s=no-cookies" % name)
if attempts:
logger.debug("In-process extraction attempts: %s", ", ".join(attempts))
return None
return None, diagnostics
def _extract_via_subprocess() -> Optional[Dict[str, str]]:
"""Extract cookies via subprocess (fallback if in-process fails, e.g. SQLite lock)."""
def _extract_via_subprocess() -> Tuple[Optional[Dict[str, str]], List[str]]:
"""Extract cookies via subprocess (fallback if in-process fails, e.g. SQLite lock).
Returns (cookies_dict | None, diagnostics_list).
"""
extract_script = '''
import glob, json, os, sys
try:
@@ -351,7 +402,7 @@ for name, fn in browsers:
try:
jar = fn()
except Exception as exc:
attempts.append(f"{name}={type(exc).__name__}")
attempts.append(f"{name}={type(exc).__name__}: {exc}")
continue
r = extract_from_jar(jar, name)
if r:
@@ -364,7 +415,7 @@ for name, fn in browsers:
try:
jar = fn(cookie_file=cf)
except Exception as exc:
attempts.append(f"{name}[{pname}]={type(exc).__name__}")
attempts.append(f"{name}[{pname}]={type(exc).__name__}: {exc}")
continue
r = extract_from_jar(jar, name, pname)
if r:
@@ -375,7 +426,7 @@ for name, fn in browsers:
try:
jar = fn()
except Exception as exc:
attempts.append(f"{name}={type(exc).__name__}")
attempts.append(f"{name}={type(exc).__name__}: {exc}")
continue
r = extract_from_jar(jar, name)
if r:
@@ -390,6 +441,8 @@ print(json.dumps({
sys.exit(1)
'''
diagnostics: List[str] = []
def _run_extract_command(
cmd: list[str],
timeout: int,
@@ -427,6 +480,7 @@ sys.exit(1)
attempts = data.get("attempts") or []
if attempts:
logger.debug("Subprocess extraction attempts (%s): %s", label, ", ".join(str(item) for item in attempts))
diagnostics.extend(str(item) for item in attempts)
retryable = data.get("error") == "browser-cookie3 not installed"
return None, retryable
@@ -446,7 +500,7 @@ sys.exit(1)
)
if data is None:
return None
return None, diagnostics
logger.info("Found cookies in %s (subprocess)", data.get("browser", "unknown"))
# Build full cookie string from all extracted cookies
@@ -456,30 +510,36 @@ sys.exit(1)
cookie_str = "; ".join("%s=%s" % (k, v) for k, v in all_cookies.items())
cookies["cookie_string"] = cookie_str
logger.info("Extracted %d total cookies for full browser fingerprint", len(all_cookies))
return cookies
return cookies, diagnostics
except KeyError as exc:
logger.debug("Cookie extraction subprocess returned incomplete payload: %s", exc)
return None
return None, diagnostics
def extract_from_browser() -> Optional[Dict[str, str]]:
def extract_from_browser() -> Tuple[Optional[Dict[str, str]], List[str]]:
"""Auto-extract ALL Twitter cookies from local browser using browser-cookie3.
Strategy:
1. Try in-process first (required on macOS for Keychain access)
2. Fall back to subprocess (handles SQLite lock when browser is running)
Returns (cookies_dict | None, diagnostics_list).
"""
all_diagnostics: List[str] = []
# 1. In-process (works on macOS, may fail with SQLite lock)
cookies = _extract_in_process()
cookies, diag = _extract_in_process()
all_diagnostics.extend(diag)
if cookies:
return cookies
return cookies, all_diagnostics
# 2. Subprocess fallback (handles SQLite lock, but fails on macOS Keychain)
logger.debug("In-process extraction failed, trying subprocess fallback")
cookies = _extract_via_subprocess()
cookies, diag = _extract_via_subprocess()
all_diagnostics.extend(diag)
if not cookies:
logger.warning("Twitter cookie extraction failed in both in-process and subprocess modes")
return cookies
return cookies, all_diagnostics
def get_cookies() -> Dict[str, str]:
@@ -488,6 +548,7 @@ def get_cookies() -> Dict[str, str]:
Raises RuntimeError if no cookies found.
"""
cookies: Optional[Dict[str, str]] = None
diagnostics: List[str] = []
# 1. Try environment variables
cookies = load_from_env()
@@ -497,14 +558,22 @@ def get_cookies() -> Dict[str, str]:
# 2. Try browser extraction (auto-detect)
if not cookies:
logger.debug("Attempting browser cookie extraction")
cookies = extract_from_browser()
cookies, diagnostics = extract_from_browser()
if not cookies:
raise RuntimeError(
"No Twitter cookies found.\n"
"Option 1: Set TWITTER_AUTH_TOKEN and TWITTER_CT0 environment variables\n"
"Option 2: Make sure you are logged into x.com in your browser (Arc/Chrome/Edge/Firefox/Brave)"
)
lines = ["No Twitter cookies found."]
# Add actionable Keychain hint when relevant
hint = _diagnose_keychain_issues(diagnostics)
if hint:
lines.append("")
lines.append("Likely cause:")
lines.extend(" " + l for l in hint.splitlines())
lines.append("")
lines.append("Option 1: Set TWITTER_AUTH_TOKEN and TWITTER_CT0 environment variables")
lines.append("Option 2: Make sure you are logged into x.com in your browser (Arc/Chrome/Edge/Firefox/Brave)")
lines.append("")
lines.append("Run 'twitter doctor' for full diagnostics.")
raise RuntimeError("\n".join(lines))
# Verify only for explicit auth failures; transient endpoint issues are tolerated.
try:
@@ -512,7 +581,7 @@ def get_cookies() -> Dict[str, str]:
except RuntimeError:
# Auth failure — re-extract from browser and retry verification
logger.info("Cookie verification failed, re-extracting from browser")
fresh_cookies = extract_from_browser()
fresh_cookies, _ = extract_from_browser()
if fresh_cookies:
# Verify fresh cookies — if this also fails, let it raise
verify_cookies(fresh_cookies["auth_token"], fresh_cookies["ct0"], fresh_cookies.get("cookie_string"))

133
twitter_cli/cli.py
View File

@@ -28,6 +28,7 @@ Write commands:
from __future__ import annotations
import logging
import os
import re
import sys
import time
@@ -992,5 +993,137 @@ def unbookmark(tweet_id, as_json, as_yaml):
_write_action("🔖", "Removing bookmark", "unbookmark_tweet", tweet_id, as_json=as_json, as_yaml=as_yaml)
@cli.command(name="doctor")
@structured_output_options
def doctor(as_json, as_yaml):
# type: (bool, bool) -> None
"""Run diagnostics for cookie extraction and authentication.
Useful for troubleshooting auth issues and for pasting into bug reports.
"""
import platform
from .auth import (
_diagnose_keychain_issues,
_extract_in_process,
_extract_via_subprocess,
extract_from_browser,
load_from_env,
verify_cookies,
)
info: Dict[str, Any] = {}
mode = _structured_mode(as_json=as_json, as_yaml=as_yaml)
# -- System info --
info["version"] = __version__
info["python"] = sys.version.split()[0]
info["platform"] = platform.platform()
info["os"] = sys.platform
# -- Environment --
is_ssh = bool(
os.environ.get("SSH_CLIENT")
or os.environ.get("SSH_TTY")
or os.environ.get("SSH_CONNECTION")
)
info["ssh_session"] = is_ssh
info["env_auth_token_set"] = bool(os.environ.get("TWITTER_AUTH_TOKEN"))
info["env_ct0_set"] = bool(os.environ.get("TWITTER_CT0"))
info["chrome_profile_override"] = os.environ.get("TWITTER_CHROME_PROFILE", "")
# -- Cookie extraction --
env_cookies = load_from_env()
info["env_cookies"] = "found" if env_cookies else "not set"
# In-process extraction
in_proc_cookies, in_proc_diag = _extract_in_process()
info["in_process"] = {
"status": "ok" if in_proc_cookies else "failed",
"diagnostics": in_proc_diag,
}
# Subprocess extraction
sub_cookies, sub_diag = _extract_via_subprocess()
info["subprocess"] = {
"status": "ok" if sub_cookies else "failed",
"diagnostics": sub_diag,
}
# Combined diagnostics
all_diag = in_proc_diag + sub_diag
cookies = in_proc_cookies or sub_cookies or env_cookies
# Keychain hint
hint = _diagnose_keychain_issues(all_diag)
if hint:
info["keychain_hint"] = hint
# Verification
if cookies:
try:
result = verify_cookies(
cookies["auth_token"],
cookies["ct0"],
cookies.get("cookie_string"),
)
info["verification"] = "ok"
info["screen_name"] = result.get("screen_name", "")
except RuntimeError as exc:
info["verification"] = "failed: %s" % exc
else:
info["verification"] = "skipped (no cookies)"
# -- Output --
if _emit_mode_payload(info, mode):
return
console.print("\n🩺 [bold]twitter-cli doctor[/bold]\n")
console.print(" Version: %s" % info["version"])
console.print(" Python: %s" % info["python"])
console.print(" Platform: %s" % info["platform"])
console.print(" SSH session: %s" % ("yes ⚠️" if is_ssh else "no"))
console.print()
console.print("[bold]Environment:[/bold]")
console.print(" TWITTER_AUTH_TOKEN: %s" % ("set ✅" if info["env_auth_token_set"] else "not set"))
console.print(" TWITTER_CT0: %s" % ("set ✅" if info["env_ct0_set"] else "not set"))
if info["chrome_profile_override"]:
console.print(" TWITTER_CHROME_PROFILE: %s" % info["chrome_profile_override"])
console.print()
console.print("[bold]Cookie Extraction:[/bold]")
in_status = info["in_process"]["status"]
console.print(
" In-process: %s" % ("[green]ok ✅[/green]" if in_status == "ok" else "[red]failed ❌[/red]")
)
for d in info["in_process"]["diagnostics"]:
console.print(" [dim]• %s[/dim]" % d)
sub_status = info["subprocess"]["status"]
console.print(
" Subprocess: %s" % ("[green]ok ✅[/green]" if sub_status == "ok" else "[red]failed ❌[/red]")
)
for d in info["subprocess"]["diagnostics"]:
console.print(" [dim]• %s[/dim]" % d)
console.print()
if hint:
console.print("[yellow]💡 Hint:[/yellow]")
for line in hint.splitlines():
console.print(" [yellow]%s[/yellow]" % line)
console.print()
v = info["verification"]
if v == "ok":
screen = info.get("screen_name", "")
console.print("[green]✅ Authentication: OK[/green]%s" % (" (@%s)" % screen if screen else ""))
elif v.startswith("failed"):
console.print("[red]❌ Authentication: %s[/red]" % v)
else:
console.print("[yellow]⚠️ Authentication: %s[/yellow]" % v)
console.print()
if __name__ == "__main__":
cli()