chatgpt-auth 0.1.0__py3-none-any.whl

chatgpt_auth/__init__.py

@@ -0,0 +1,36 @@
+"""chatgpt-auth: Sign in with ChatGPT for CLI and Python applications."""
+
+from .credentials import Credentials
+from .errors import (
+    AuthError,
+    ChatGPTAuthError,
+    ConnectionChangedError,
+    LoginTimeoutError,
+    NetworkError,
+    PlanPermissionError,
+    ReauthorizationRequiredError,
+    SignInRequiredError,
+    StorageError,
+)
+from .service import login, logout, status
+from .types import AuthStatus, LogoutResult
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AuthError",
+    "AuthStatus",
+    "ChatGPTAuthError",
+    "ConnectionChangedError",
+    "Credentials",
+    "LoginTimeoutError",
+    "LogoutResult",
+    "NetworkError",
+    "PlanPermissionError",
+    "ReauthorizationRequiredError",
+    "SignInRequiredError",
+    "StorageError",
+    "login",
+    "logout",
+    "status",
+]

chatgpt_auth/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

chatgpt_auth/callback.py

@@ -0,0 +1,196 @@
+"""Loopback callback listener and pasted-URL handling for sign-in.
+
+No storage and no UI framework: the caller injects the warning sink and
+the input stream so the CLI and tests can differ.
+"""
+
+import os
+import secrets
+import select
+import sys
+import threading
+import time
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from urllib.parse import parse_qsl, urlsplit
+
+from .errors import AuthError
+
+POLL_INTERVAL_SECONDS = 0.1
+
+
+def callback_query(redirect_uri, text, *, expected_state=None):
+    """Turn a pasted callback URL into a query dict, validated for one attempt.
+
+    The URL's scheme, host, port, and path must equal the attempt's redirect
+    URI, and every query parameter must appear exactly once. Never includes
+    the pasted text in errors: it may carry an authorization code.
+    """
+    try:
+        pasted = urlsplit(text.strip())
+        pasted_port = pasted.port
+    except ValueError:
+        raise AuthError("invalid_callback_url") from None
+    expected = urlsplit(redirect_uri)
+    if (
+        pasted.scheme,
+        pasted.hostname,
+        pasted_port,
+        pasted.path,
+    ) != (
+        expected.scheme,
+        expected.hostname,
+        expected.port,
+        expected.path,
+    ):
+        raise AuthError("invalid_callback_url")
+    pairs = parse_qsl(pasted.query, keep_blank_values=True)
+    keys = [key for key, _ in pairs]
+    if len(set(keys)) != len(keys):
+        raise AuthError("invalid_callback_url")
+    query = dict(pairs)
+    if expected_state is not None and not secrets.compare_digest(
+        query.get("state", ""), expected_state
+    ):
+        raise AuthError("invalid_state")
+    if not (query.get("code") or query.get("error")):
+        # Neither a grant nor a decline: no usable result exists, so this
+        # must not end the attempt (a truncated paste stays recoverable).
+        raise AuthError("invalid_callback_url")
+    return query
+
+
+class CallbackListener:
+    """One browser authorization result, received on a private loopback listener."""
+
+    def __init__(self, port=0):
+        self.result = None
+        self.expected_state = None
+        self._received = threading.Event()
+        self._lock = threading.Lock()
+        listener = self
+
+        class Handler(BaseHTTPRequestHandler):
+            def log_message(self, format, *args):
+                pass  # Callback URLs contain a credential: do not log them.
+
+            def do_GET(self):
+                host = self.headers.get("Host")
+                expected_state = listener.expected_state
+                query = None
+                if expected_state is not None:
+                    try:
+                        query = callback_query(
+                            listener.redirect_uri,
+                            f"http://{host}{self.path}",
+                            expected_state=expected_state,
+                        )
+                    except (AuthError, ValueError):
+                        query = None
+                body = (
+                    "Authorization received. Return to your terminal for the result."
+                    if query is not None
+                    else "This authorization result could not be verified."
+                ).encode()
+                self.send_response(200 if query is not None else 400)
+                self.send_header("Content-Type", "text/plain; charset=utf-8")
+                self.send_header("Content-Length", str(len(body)))
+                self.send_header("Cache-Control", "no-store")
+                self.send_header("Referrer-Policy", "no-referrer")
+                self.end_headers()
+                self.wfile.write(body)
+                if query is not None:
+                    listener.submit(query)
+
+        self.server = ThreadingHTTPServer(("127.0.0.1", port), Handler)
+        self.server.daemon_threads = True
+        self.host = f"127.0.0.1:{self.server.server_port}"
+        self.redirect_uri = f"http://{self.host}/auth/callback"
+        self.thread = threading.Thread(target=self.server.serve_forever, daemon=True)
+
+    def start(self, state):
+        self.expected_state = state
+        self.thread.start()
+
+    def submit(self, query):
+        """Record the attempt's result; only the first caller wins."""
+        with self._lock:
+            if self.result is not None:
+                return False
+            self.result = query
+            self._received.set()
+            return True
+
+    def wait(self, timeout):
+        """Wait for the authorization result; returns None on timeout."""
+        if self._received.wait(timeout):
+            return self.result
+        return None
+
+    def close(self):
+        if self.thread.is_alive():
+            self.server.shutdown()
+            self.thread.join()
+        self.server.server_close()
+
+
+def wait_for_result(listener, deadline, stream=None, warn=None):
+    """Wait for the HTTP callback or a pasted callback URL; first wins.
+
+    A pasted URL is only read when ``stream`` is interactive (a TTY); any
+    input that fails validation is reported through ``warn`` and the wait
+    continues. On non-interactive streams only the HTTP callback is watched.
+    No background thread is created. Byte-wise reads stop exactly at the
+    newline that completes the pasted URL, so input queued behind it is
+    left in the terminal for the shell, not swallowed by sign-in.
+    """
+    warn = warn or (lambda message: print(message, file=sys.stderr))
+    try:
+        fd = stream.fileno() if stream is not None else -1
+        interactive = fd >= 0 and stream.isatty()
+    except (OSError, ValueError, AttributeError):
+        interactive = False
+    if not interactive:
+        return listener.wait(max(0.0, deadline - time.monotonic()))
+    pending = bytearray()
+    while True:
+        result = listener.wait(0)
+        if result is not None:
+            return result
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            return None
+        readable, _, _ = select.select(
+            [fd], [], [], min(remaining, POLL_INTERVAL_SECONDS)
+        )
+        if not readable:
+            continue
+        byte = os.read(fd, 1)
+        if not byte:
+            # EOF: only the loopback callback can still complete this
+            return listener.wait(max(0.0, deadline - time.monotonic()))
+        if byte != b"\n":
+            pending += byte
+            if len(pending) > 65536:
+                warn(
+                    "Rejected pasted URL (too long). Paste the full address "
+                    "the browser was redirected to."
+                )
+                pending.clear()
+            continue
+        text = pending.decode("utf-8", "replace").strip()
+        pending.clear()
+        if not text:
+            continue
+        try:
+            query = callback_query(
+                listener.redirect_uri, text, expected_state=listener.expected_state
+            )
+        except AuthError as exc:
+            warn(
+                f"Rejected pasted URL ({exc}). Paste the full address the "
+                "browser was redirected to."
+            )
+            continue
+        if listener.submit(query):
+            return query
+        return listener.wait(0)

chatgpt_auth/cli.py

@@ -0,0 +1,247 @@
+"""The ``chatgpt-auth`` command line: login, status, token, refresh, logout."""
+
+import sys
+import time
+import webbrowser
+from datetime import UTC, datetime
+
+import click
+
+from . import service
+from .credentials import Credentials
+from .errors import (
+    ChatGPTAuthError,
+    ConnectionChangedError,
+    LoginTimeoutError,
+    NetworkError,
+    PlanPermissionError,
+    ReauthorizationRequiredError,
+    SignInRequiredError,
+    StorageError,
+)
+from .oauth import (
+    DEFAULT_AGENT_NAME,
+    DEFAULT_TIMEOUT_SECONDS,
+    MAX_TIMEOUT_SECONDS,
+)
+
+USAGE_URL = "https://chatgpt.com/settings/usage"
+
+
+@click.group()
+@click.option(
+    "--credentials",
+    "credentials_path",
+    metavar="PATH",
+    default=None,
+    help="Credentials file to use (overrides CHATGPT_AUTH_CREDENTIALS)",
+)
+@click.pass_context
+def main(ctx, credentials_path):
+    """Manage a Sign in with ChatGPT connection."""
+    ctx.obj = credentials_path
+
+
+def _path(ctx):
+    return ctx.obj
+
+
+def _auth_message(exc) -> str:
+    if isinstance(exc, SignInRequiredError):
+        return "Not signed in. Run: chatgpt-auth login"
+    if isinstance(exc, ReauthorizationRequiredError):
+        return str(exc) or "Sign-in expired or was revoked. Run: chatgpt-auth login"
+    if isinstance(exc, PlanPermissionError):
+        return (
+            "ChatGPT plan usage was not granted. Check your usage sharing "
+            f"settings: {USAGE_URL}"
+        )
+    if isinstance(exc, ConnectionChangedError):
+        return str(exc)
+    if isinstance(exc, (StorageError, NetworkError, LoginTimeoutError)):
+        return str(exc)
+    code = str(exc)
+    guidance = {
+        "sign_in_declined": "Sign-in was declined in the browser.",
+        "expired_sign_in": "The sign-in attempt expired. Run login again.",
+        "connection_changed": (
+            "The connection changed while signing in. Run chatgpt-auth login again."
+        ),
+        "account_mismatch": (
+            "A different ChatGPT account signed in. Run login again or use "
+            "--replace to switch accounts."
+        ),
+    }
+    return guidance.get(
+        code,
+        f"Sign-in failed: {code}. Run chatgpt-auth login to try again.",
+    )
+
+
+def _show_manual_url(url, browser_failed):
+    if browser_failed:
+        click.echo("Could not open a browser automatically.", err=True)
+    click.echo("Open this URL to sign in with ChatGPT and approve plan usage:")
+    click.echo(url)
+    if sys.stdin.isatty():
+        click.echo(
+            "After approving, the browser is redirected to a local address. "
+            "If the redirect does not reach this machine, copy the full URL "
+            "from the address bar and paste it here."
+        )
+    else:
+        click.echo(
+            "Pasted URLs are not accepted in this session; complete the "
+            "sign-in in a browser that can reach this machine."
+        )
+
+
+def _fail(exc):
+    raise click.ClickException(_auth_message(exc)) from exc
+
+
+@main.command()
+@click.option(
+    "--replace",
+    is_flag=True,
+    help="Replace the current connection with a new sign-in",
+)
+@click.option(
+    "--manual",
+    is_flag=True,
+    help="Show the sign-in URL instead of opening a browser; the loopback "
+    "callback or a pasted callback URL completes sign-in",
+)
+@click.option(
+    "--timeout",
+    type=int,
+    default=DEFAULT_TIMEOUT_SECONDS,
+    show_default=True,
+    help="Seconds to wait for browser sign-in (1-600)",
+)
+@click.option("--port", type=int, default=0, help="Callback port (0 = automatic)")
+@click.option(
+    "--agent-name",
+    default=DEFAULT_AGENT_NAME,
+    show_default=True,
+    help="Application name sent on first-time registration",
+)
+@click.pass_context
+def login(ctx, replace, manual, timeout, port, agent_name):
+    """Sign in with ChatGPT and save the OAuth connection"""
+    if not 1 <= timeout <= MAX_TIMEOUT_SECONDS:
+        raise click.UsageError("--timeout must be between 1 and 600")
+    if not (port == 0 or 1024 <= port <= 65535):
+        raise click.UsageError("--port must be 0 or between 1024 and 65535")
+    try:
+        if not manual:
+            click.echo(
+                "Opening a browser to sign in with ChatGPT and approve plan usage...",
+                err=True,
+            )
+        credentials = service.login(
+            _path(ctx),
+            agent_name=agent_name,
+            replace=replace,
+            manual=manual,
+            timeout=timeout,
+            port=port,
+            open_browser=webbrowser.open,
+            show_url=_show_manual_url,
+            input_stream=sys.stdin,
+            warn=lambda message: click.echo(message, err=True),
+        )
+    except ChatGPTAuthError as exc:
+        _fail(exc)
+    except KeyboardInterrupt:
+        click.echo("Sign-in aborted.", err=True)
+        ctx.exit(130)
+    account = credentials.email or credentials.subject
+    click.echo(f"Signed in and verified ChatGPT plan access for {account}.")
+
+
+@main.command()
+@click.pass_context
+def status(ctx):
+    """Show the local state of the stored connection"""
+    try:
+        report = service.status(_path(ctx))
+    except ChatGPTAuthError as exc:
+        _fail(exc)
+    except KeyboardInterrupt:
+        ctx.exit(130)
+    if not report.connected:
+        click.echo("Not signed in.")
+        if report.email:
+            click.echo(f"Last account: {report.email}")
+        click.echo(f"Storage: {report.path}")
+        return
+    click.echo(
+        "Signed in." if report.state == "active" else "Signed in (refresh needed)."
+    )
+    if report.email:
+        click.echo(
+            f"Account: {report.email}" + (f" ({report.name})" if report.name else "")
+        )
+    elif report.subject:
+        click.echo(f"Account: {report.subject}")
+    expires = datetime.fromtimestamp(report.expires_at, tz=UTC)
+    remaining = int(report.expires_at - time.time())
+    if remaining > 0:
+        click.echo(
+            f"Access token expires: {expires.isoformat()} (in {remaining // 60} min)"
+        )
+    else:
+        click.echo(f"Access token expired: {expires.isoformat()}")
+    click.echo(f"Storage: {report.path}")
+
+
+@main.command(name="print-access-token")
+@click.pass_context
+def print_access_token(ctx):
+    """Print a valid access token (stdout only, nothing else)"""
+    try:
+        token = Credentials.load(_path(ctx)).get_access_token()
+    except ChatGPTAuthError as exc:
+        _fail(exc)
+    except KeyboardInterrupt:
+        ctx.exit(130)
+    click.echo(token)
+
+
+@main.command()
+@click.pass_context
+def refresh(ctx):
+    """Force a token refresh now; the token is not displayed"""
+    try:
+        Credentials.load(_path(ctx)).refresh()
+    except ChatGPTAuthError as exc:
+        _fail(exc)
+    except KeyboardInterrupt:
+        ctx.exit(130)
+    click.echo("Access token refreshed and saved.")
+
+
+@main.command()
+@click.pass_context
+def logout(ctx):
+    """Sign out: remove local tokens and try to revoke the session"""
+    try:
+        result = service.logout(_path(ctx))
+    except ChatGPTAuthError as exc:
+        _fail(exc)
+    except KeyboardInterrupt:
+        ctx.exit(130)
+    if not result.was_connected:
+        click.echo("Not signed in.")
+        return
+    if result.remote_revoked:
+        click.echo("Signed out. The ChatGPT session was revoked remotely.")
+    else:
+        click.echo("Signed out locally.")
+        click.echo(
+            "Could not confirm the remote session was revoked. To "
+            "disconnect this app completely, remove it in ChatGPT under "
+            "Settings > Security and login > Sign in with ChatGPT.",
+            err=True,
+        )

chatgpt_auth/config.py

@@ -0,0 +1,97 @@
+"""Credentials file location: resolution order, naming rules, validation.
+
+A connection is not a single JSON file: it is the credentials file plus
+the auxiliary files (host.json, pending.json, runtime.lock, login.lock)
+that live next to it. When the credentials file is named the canonical
+``credentials.json``, the auxiliary files keep their canonical names —
+the same names llm-chatgpt-plan uses in its state directory — so pointing
+this tool at an existing store shares files and locks with the old tool.
+Any other file name gets auxiliary names derived by suffix, so distinct
+stores never share auxiliary files.
+"""
+
+import os
+from pathlib import Path
+
+from .errors import StorageError
+
+ENV_VAR = "CHATGPT_AUTH_CREDENTIALS"
+DEFAULT_DIR_NAME = "chatgpt-auth"
+CREDENTIALS_NAME = "credentials.json"
+
+CANONICAL_AUX = {
+    "host": "host.json",
+    "pending": "pending.json",
+    "runtime_lock": "runtime.lock",
+    "login_lock": "login.lock",
+    "models": "models.json",
+}
+AUX_SUFFIXES = {
+    "host": ".host.json",
+    "pending": ".pending.json",
+    "runtime_lock": ".runtime.lock",
+    "login_lock": ".login.lock",
+    "models": ".models.json",
+}
+RESERVED_NAMES = frozenset(CANONICAL_AUX.values())
+RESERVED_SUFFIXES = tuple(AUX_SUFFIXES.values())
+
+
+def validate_credentials_name(name: str) -> None:
+    """Reject file names that would collide with a store's own files."""
+    if not name or name in (".", ".."):
+        raise StorageError("Credentials file name is empty")
+    if name in RESERVED_NAMES or name.endswith(RESERVED_SUFFIXES):
+        raise StorageError(f"Reserved credentials file name: {name}")
+
+
+def aux_path(credentials_path: Path, kind: str) -> Path:
+    """Auxiliary file for ``kind`` next to the given credentials file."""
+    if credentials_path.name == CREDENTIALS_NAME:
+        name = CANONICAL_AUX[kind]
+    else:
+        name = credentials_path.name + AUX_SUFFIXES[kind]
+    return credentials_path.parent / name
+
+
+def _anchor(path: Path, cwd: Path) -> Path:
+    """Expand ~ and pin a relative path to the given working directory."""
+    expanded = Path(os.path.expanduser(str(path)))
+    if not expanded.is_absolute():
+        expanded = cwd / expanded
+    return Path(os.path.abspath(expanded))
+
+
+def default_path(*, env=None, cwd=None) -> Path:
+    """${XDG_CONFIG_HOME:-~/.config}/chatgpt-auth/credentials.json.
+
+    A relative XDG_CONFIG_HOME is ignored in favor of ~/.config.
+    """
+    env = os.environ if env is None else env
+    cwd = Path.cwd() if cwd is None else cwd
+    xdg = env.get("XDG_CONFIG_HOME")
+    if xdg:
+        candidate = Path(os.path.expanduser(xdg))
+        base = candidate if candidate.is_absolute() else Path.home() / ".config"
+    else:
+        base = Path.home() / ".config"
+    return base / DEFAULT_DIR_NAME / CREDENTIALS_NAME
+
+
+def resolve_path(explicit=None, *, env=None, cwd=None) -> Path:
+    """Resolve the credentials file path in priority order:
+
+    1. the explicit ``path`` argument (CLI --credentials / API path)
+    2. the CHATGPT_AUTH_CREDENTIALS environment variable
+    3. the default location
+    """
+    env = os.environ if env is None else env
+    cwd = Path.cwd() if cwd is None else cwd
+    if explicit is not None:
+        path = _anchor(Path(explicit), cwd)
+    elif env.get(ENV_VAR):
+        path = _anchor(Path(env[ENV_VAR]), cwd)
+    else:
+        path = default_path(env=env, cwd=cwd)
+    validate_credentials_name(path.name)
+    return path