Skip to content

Universal SEO skill for Claude Code. 26 sub-skills + 19 sub-agents covering technical SEO, E-E-A-T, schema, GEO/AEO, agent readiness (Lighthouse Agentic Browsing, WebMCP, llms.txt), backlinks, local SEO, e-commerce, international SEO, Google APIs, and PDF/Excel reporting. 9 optional extensions for live SEO data.

fix(google_auth): bind the sign-in to its run with state and PKCE

Agrici Danieldde50dc732ea
diff --git a/scripts/google_auth.py b/scripts/google_auth.py
index a413b0b..fbe3ef2 100644
--- a/scripts/google_auth.py
+++ b/scripts/google_auth.py
@@ -16,9 +16,13 @@ Usage:
"""
import argparse
+import base64
+import hashlib
+import hmac
import json
import os
import re
+import secrets
import sys
import time
from typing import Optional
@@ -50,6 +54,13 @@ OAUTH_SCOPES = (
"https://www.googleapis.com/auth/analytics.readonly"
)
OAUTH_REDIRECT_URI = "http://localhost:8085"
+# How long --auth waits for the browser redirect, and how long the pending
+# sign-in (state + PKCE verifier) stays usable for a manual --exchange.
+OAUTH_WAIT_SECONDS = 300
+OAUTH_PENDING_MAX_AGE = 600
+# A redirect connection that sends no request is dropped after this many
+# seconds, so it cannot hold the single-threaded server.
+OAUTH_REQUEST_TIMEOUT = 10
# Human-readable service names
SERVICE_NAMES = {
@@ -266,7 +277,12 @@ def _load_oauth_token() -> Optional[dict]:
def _save_oauth_token(token_data: dict):
- """Save OAuth token to TOKEN_PATH with secure (0o600) permissions.
+ """Save OAuth token to TOKEN_PATH with secure (0o600) permissions."""
+ _write_private_json(TOKEN_PATH, token_data)
+
+
+def _write_private_json(path: str, data: dict):
+ """Write JSON to ``path`` with secure (0o600) permissions.
Belt-and-suspenders sequence:
1. Pre-chmod any existing file (closes a v1.9.x umask=022 legacy).
@@ -277,13 +293,13 @@ def _save_oauth_token(token_data: dict):
os.path.exists()/os.open() TOCTOU race where an external
creator could install a 0o644 file between the two calls.
- The token file is never world-readable, even briefly.
+ The file is never world-readable, even briefly.
"""
- os.makedirs(os.path.dirname(TOKEN_PATH), exist_ok=True)
- if os.path.exists(TOKEN_PATH):
- _chmod_quiet(TOKEN_PATH, 0o600)
+ os.makedirs(os.path.dirname(path), exist_ok=True)
+ if os.path.exists(path):
+ _chmod_quiet(path, 0o600)
flags = os.O_WRONLY | os.O_CREAT | os.O_TRUNC
- fd = os.open(TOKEN_PATH, flags, 0o600)
+ fd = os.open(path, flags, 0o600)
# fchmod on the open fd guarantees 0o600 even if the file existed at
# open time (in which case os.open's mode arg is ignored by the OS).
# os.fdopen takes ownership of fd: it closes the fd whether the
@@ -295,7 +311,89 @@ def _save_oauth_token(token_data: dict):
except OSError:
pass # FS may not support fchmod (e.g. some Windows filesystems)
with os.fdopen(fd, "w") as f:
- json.dump(token_data, f, indent=2)
+ json.dump(data, f, indent=2)
+
+
+def _pending_flow_path() -> str:
+ """Where an unfinished --auth keeps its state and PKCE verifier."""
+ return os.path.join(os.path.dirname(TOKEN_PATH), "oauth-pending.json")
+
+
+def _pkce_pair() -> tuple[str, str]:
+ """Return a PKCE (code_verifier, S256 code_challenge) pair (RFC 7636)."""
+ verifier = secrets.token_urlsafe(64)
+ digest = hashlib.sha256(verifier.encode("ascii")).digest()
+ challenge = base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")
+ return verifier, challenge
+
+
+def _save_pending_flow(state: str, code_verifier: str):
+ """Persist the pending sign-in so a manual --exchange can finish it."""
+ _write_private_json(_pending_flow_path(), {
+ "state": state,
+ "code_verifier": code_verifier,
+ "redirect_uri": OAUTH_REDIRECT_URI,
+ "created_at": time.time(),
+ })
+
+
+def _clear_pending_flow():
+ try:
+ os.remove(_pending_flow_path())
+ except OSError:
+ pass
+
+
+def _load_pending_flow() -> Optional[dict]:
+ """Load the pending sign-in, or None when absent, unreadable or expired."""
+ path = _pending_flow_path()
+ if not os.path.exists(path):
+ return None
+ try:
+ with open(path, "r") as f:
+ data = json.load(f)
+ except (json.JSONDecodeError, IOError):
+ return None
+ try:
+ age = time.time() - float(data["created_at"])
+ except (KeyError, TypeError, ValueError):
+ age = -1
+ if (
+ not isinstance(data, dict)
+ or not data.get("state")
+ or not data.get("code_verifier")
+ or data.get("redirect_uri") != OAUTH_REDIRECT_URI
+ or not 0 <= age <= OAUTH_PENDING_MAX_AGE
+ ):
+ _clear_pending_flow()
+ return None
+ return data
+
+
+def _manual_exchange_inputs(code_or_url: str) -> tuple[Optional[str], Optional[str], Optional[str]]:
+ """Turn --exchange --code input into (code, code_verifier, error).
+
+ Accepts the bare code or the full redirect URL from the address bar.
+ When a URL is pasted, its ``state`` must match the pending sign-in.
+ """
+ import urllib.parse
+
+ pending = _load_pending_flow()
+ verifier = pending["code_verifier"] if pending else None
+ value = code_or_url.strip()
+ if not value.lower().startswith(("http://", "https://")):
+ return value, verifier, None
+ params = urllib.parse.parse_qs(urllib.parse.urlparse(value).query)
+ if "error" in params:
+ return None, None, f"Google returned an error: {params['error'][0]}"
+ code = params.get("code", [None])[0]
+ if not code:
+ return None, None, "The pasted URL has no 'code' parameter."
+ if pending:
+ returned_state = params.get("state", [""])[0]
+ if not hmac.compare_digest(returned_state, pending["state"]):
+ return None, None, "The pasted URL does not belong to the pending sign-in. Run --auth again."
+ return code, verifier, None
def _persist_oauth_client_path(creds_path: str):
@@ -349,7 +447,7 @@ def _refresh_oauth_token(client: dict, token_data: dict) -> Optional[dict]:
try:
req = urllib.request.Request(client.get("token_uri", "https://oauth2.googleapis.com/token"), data=params)
- with urllib.request.urlopen(req) as resp:
+ with urllib.request.urlopen(req, timeout=30) as resp:
new_data = json.loads(resp.read())
token_data["access_token"] = new_data["access_token"]
token_data["expires_at"] = time.time() + new_data.get("expires_in", 3600)
@@ -438,22 +536,52 @@ def run_oauth_flow(creds_path: str):
print("Error: Could not load OAuth client credentials.", file=sys.stderr)
sys.exit(1)
+ # state binds the redirect to this run (CSRF); PKCE binds the code to
+ # this machine. Both are kept on disk for the manual --exchange path.
+ _clear_pending_flow()
+ state = secrets.token_urlsafe(32)
+ code_verifier, code_challenge = _pkce_pair()
+ _save_pending_flow(state, code_verifier)
+
auth_url = (
- f"{client.get('auth_uri', 'https://accounts.google.com/o/oauth2/auth')}"
- f"?client_id={client['client_id']}"
- f"&redirect_uri={urllib.parse.quote(OAUTH_REDIRECT_URI)}"
- f"&response_type=code"
- f"&scope={urllib.parse.quote(OAUTH_SCOPES)}"
- f"&access_type=offline&prompt=consent"
+ client.get("auth_uri", "https://accounts.google.com/o/oauth2/auth")
+ + "?"
+ + urllib.parse.urlencode({
+ "client_id": client["client_id"],
+ "redirect_uri": OAUTH_REDIRECT_URI,
+ "response_type": "code",
+ "scope": OAUTH_SCOPES,
+ "access_type": "offline",
+ "prompt": "consent",
+ "state": state,
+ "code_challenge": code_challenge,
+ "code_challenge_method": "S256",
+ })
)
- auth_code = [None]
+ result = {"code": None, "error": None}
class Handler(http.server.BaseHTTPRequestHandler):
+ # A connection that never sends a request must not stall the wait.
+ timeout = OAUTH_REQUEST_TIMEOUT
+
def do_GET(self):
params = urllib.parse.parse_qs(urllib.parse.urlparse(self.path).query)
- if "code" in params:
- auth_code[0] = params["code"][0]
+ returned_state = params.get("state", [""])[0]
+ if not hmac.compare_digest(returned_state, state):
+ # Not our redirect (a stray request or a forged one): refuse
+ # it and keep waiting for the real one.
+ self.send_response(400)
+ self.end_headers()
+ return
+ if "error" in params:
+ result["error"] = params["error"][0]
+ self.send_response(400)
+ self.send_header("Content-Type", "text/html")
+ self.end_headers()
+ self.wfile.write(b"<h1>Authentication was not completed.</h1><p>Close this tab.</p>")
+ elif "code" in params:
+ result["code"] = params["code"][0]
self.send_response(200)
self.send_header("Content-Type", "text/html")
self.end_headers()
@@ -461,63 +589,87 @@ def run_oauth_flow(creds_path: str):
else:
self.send_response(400)
self.end_headers()
+
def log_message(self, *a):
pass
- server = http.server.HTTPServer(("localhost", 8085), Handler)
- server.timeout = 300
+ port = urllib.parse.urlparse(OAUTH_REDIRECT_URI).port or 80
+ server = http.server.HTTPServer(("localhost", port), Handler)
print(f"\nOpen this URL in your browser:\n\n{auth_url}\n")
- print("Waiting up to 5 minutes for authentication...")
+ print(f"Waiting up to {OAUTH_WAIT_SECONDS} seconds for authentication...")
try:
webbrowser.open(auth_url)
except Exception:
pass
- server.handle_request()
- server.server_close()
+ deadline = time.monotonic() + OAUTH_WAIT_SECONDS
+ try:
+ while result["code"] is None and result["error"] is None:
+ remaining = deadline - time.monotonic()
+ if remaining <= 0:
+ break
+ server.timeout = remaining
+ server.handle_request()
+ finally:
+ server.server_close()
+
+ if result["error"]:
+ _clear_pending_flow()
+ print(f"\nGoogle returned an error: {result['error']}", file=sys.stderr)
+ sys.exit(1)
- if not auth_code[0]:
+ if not result["code"]:
print("\nAuthentication failed or timed out.", file=sys.stderr)
print("If the browser showed 'localhost refused to connect', copy the full URL")
- print("from the browser address bar and run:")
- print(f" python scripts/google_auth.py --exchange --creds {creds_path} --code 'THE_CODE'")
+ print(f"from the browser address bar within {OAUTH_PENDING_MAX_AGE // 60} minutes and run:")
+ print(f" python scripts/google_auth.py --exchange --creds {creds_path} --code 'THE_FULL_URL'")
sys.exit(1)
# Exchange code for tokens
- _exchange_code(client, auth_code[0], creds_path)
+ _exchange_code(client, result["code"], creds_path, code_verifier)
-def _exchange_code(client: dict, code: str, creds_path: Optional[str] = None):
+def _exchange_code(
+ client: dict,
+ code: str,
+ creds_path: Optional[str] = None,
+ code_verifier: Optional[str] = None,
+):
"""Exchange an authorization code for tokens.
If creds_path is provided, persist its absolute path to the user config
as 'oauth_client_path' so subsequent refresh flows can locate the
- client_secret file without re-prompting.
+ client_secret file without re-prompting. ``code_verifier`` is the PKCE
+ verifier of the sign-in that produced ``code``.
"""
import urllib.parse
import urllib.request
- params = urllib.parse.urlencode({
+ fields = {
"code": code,
"client_id": client["client_id"],
"client_secret": client["client_secret"],
"redirect_uri": OAUTH_REDIRECT_URI,
"grant_type": "authorization_code",
- }).encode()
+ }
+ if code_verifier:
+ fields["code_verifier"] = code_verifier
+ params = urllib.parse.urlencode(fields).encode()
try:
req = urllib.request.Request(
client.get("token_uri", "https://oauth2.googleapis.com/token"), data=params
)
- with urllib.request.urlopen(req) as resp:
+ with urllib.request.urlopen(req, timeout=30) as resp:
token_data = json.loads(resp.read())
token_data["expires_at"] = time.time() + token_data.get("expires_in", 3600)
token_data["client_id"] = client["client_id"]
# SECURITY: Never store client_secret in token file. It stays in client_secret.json only.
token_data.pop("client_secret", None)
_save_oauth_token(token_data)
+ _clear_pending_flow()
print("OAuth token saved successfully!")
# Persist oauth_client_path so refresh works after process restart.
@@ -891,7 +1043,7 @@ def main():
)
parser.add_argument(
"--code",
- help="Authorization code to exchange (for --exchange)",
+ help="Authorization code, or the full redirect URL from the address bar (for --exchange)",
)
args = parser.parse_args()
@@ -909,7 +1061,11 @@ def main():
sys.exit(1)
client = _load_oauth_client(args.creds)
if client:
- _exchange_code(client, args.code, args.creds)
+ code, code_verifier, error = _manual_exchange_inputs(args.code)
+ if error:
+ print(f"Error: {error}", file=sys.stderr)
+ sys.exit(1)
+ _exchange_code(client, code, args.creds, code_verifier)
return
if args.setup:
diff --git a/tests/test_google_oauth_flow.py b/tests/test_google_oauth_flow.py
new file mode 100644
index 0000000..5528012
--- /dev/null
+++ b/tests/test_google_oauth_flow.py
@@ -0,0 +1,222 @@
+"""The Google sign-in flow (--auth / --exchange) is bound to the run that started it.
+
+state rejects forged or stray redirects, PKCE (S256) binds the code to this
+machine, and both token calls carry a timeout. These tests run a real local
+redirect server on a free port and never touch Google.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import os
+import socket
+import sys
+import threading
+import time
+import urllib.parse
+import urllib.request
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "scripts"))
+import google_auth # noqa: E402
+
+CLIENT = {
+ "client_id": "client-id.apps.googleusercontent.com",
+ "client_secret": "client-secret",
+ "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+ "token_uri": "https://oauth2.googleapis.com/token",
+}
+
+
+def _free_port() -> int:
+ with socket.socket() as s:
+ s.bind(("localhost", 0))
+ return s.getsockname()[1]
+
+
+def isolated(tmp_path, monkeypatch):
+ monkeypatch.setattr(google_auth, "CONFIG_PATH", str(tmp_path / "google-api.json"))
+ monkeypatch.setattr(google_auth, "TOKEN_PATH", str(tmp_path / "oauth-token.json"))
+ monkeypatch.setattr(google_auth, "OAUTH_REDIRECT_URI", f"http://localhost:{_free_port()}")
+ creds = tmp_path / "client_secret.json"
+ creds.write_text(json.dumps({"installed": CLIENT}))
+ return creds
+
+
+class _TokenResponse:
+ def __init__(self, payload: dict) -> None:
+ self._body = json.dumps(payload).encode()
+
+ def read(self) -> bytes:
+ return self._body
+
+ def __enter__(self):
+ return self
+
+ def __exit__(self, *exc) -> None:
+ return None
+
+
+def _fake_urlopen(calls: list):
+ def urlopen(req, timeout=None):
+ calls.append({"url": req.full_url, "data": urllib.parse.parse_qs(req.data.decode()), "timeout": timeout})
+ return _TokenResponse({"access_token": "at", "refresh_token": "rt", "expires_in": 3600})
+ return urlopen
+
+
+def _get(url: str, timeout: float = 5) -> int:
+ try:
+ with urllib.request.urlopen(url, timeout=timeout) as resp:
+ return resp.status
+ except urllib.error.HTTPError as e:
+ return e.code
+
+
+def _run_flow_with_browser(isolated, monkeypatch, browser):
+ """Run run_oauth_flow with ``browser(auth_url)`` standing in for the person."""
+ exchanged = {}
+ monkeypatch.setattr(
+ google_auth, "_exchange_code",
+ lambda client, code, creds_path=None, code_verifier=None: exchanged.update(
+ code=code, code_verifier=code_verifier
+ ),
+ )
+ opened = {}
+
+ def open_browser(url):
+ opened["url"] = url
+ opened["thread"] = threading.Thread(target=browser, args=(url,), daemon=True)
+ opened["thread"].start()
+ return True
+
+ monkeypatch.setattr("webbrowser.open", open_browser)
+ try:
+ google_auth.run_oauth_flow(str(isolated))
+ finally:
+ # The flow returns once the server has answered; let the "browser"
+ # finish reading that answer before the test inspects it.
+ if "thread" in opened:
+ opened["thread"].join(timeout=30)
+ return opened["url"], exchanged
+
+
+def _redirect(url_params: dict) -> str:
+ return f"{google_auth.OAUTH_REDIRECT_URI}/?{urllib.parse.urlencode(url_params)}"
+
+
+def test_auth_url_carries_state_and_s256_challenge(isolated, monkeypatch):
+ def browser(url):
+ state = urllib.parse.parse_qs(urllib.parse.urlparse(url).query)["state"][0]
+ _get(_redirect({"state": state, "code": "the-code"}))
+
+ url, exchanged = _run_flow_with_browser(isolated, monkeypatch, browser)
+ q = urllib.parse.parse_qs(urllib.parse.urlparse(url).query)
+ assert q["client_id"] == [CLIENT["client_id"]]
+ assert q["redirect_uri"] == [google_auth.OAUTH_REDIRECT_URI]
+ assert q["code_challenge_method"] == ["S256"]
+ assert len(q["state"][0]) >= 32
+ verifier = exchanged["code_verifier"]
+ expected = base64.urlsafe_b64encode(hashlib.sha256(verifier.encode()).digest()).rstrip(b"=").decode()
+ assert q["code_challenge"] == [expected]
+ assert 43 <= len(verifier) <= 128
+ assert exchanged["code"] == "the-code"
+
+
+def test_stray_and_forged_requests_do_not_end_the_wait(isolated, monkeypatch):
+ statuses = []
+
+ def browser(url):
+ state = urllib.parse.parse_qs(urllib.parse.urlparse(url).query)["state"][0]
+ statuses.append(_get(f"{google_auth.OAUTH_REDIRECT_URI}/favicon.ico"))
+ statuses.append(_get(_redirect({"state": "forged", "code": "attacker-code"})))
+ statuses.append(_get(_redirect({"code": "no-state-code"})))
+ statuses.append(_get(_redirect({"state": state, "code": "real-code"})))
+
+ _url, exchanged = _run_flow_with_browser(isolated, monkeypatch, browser)
+ assert statuses == [400, 400, 400, 200]
+ assert exchanged["code"] == "real-code"
+
+
+def test_a_silent_connection_does_not_block_the_real_redirect(isolated, monkeypatch):
+ monkeypatch.setattr(google_auth, "OAUTH_WAIT_SECONDS", 30)
+ monkeypatch.setattr(google_auth, "OAUTH_REQUEST_TIMEOUT", 1)
+ port = urllib.parse.urlparse(google_auth.OAUTH_REDIRECT_URI).port
+ idle = []
+
+ def browser(url):
+ state = urllib.parse.parse_qs(urllib.parse.urlparse(url).query)["state"][0]
+ idle.append(socket.create_connection(("localhost", port))) # connects, sends nothing
+ # The server drops the idle connection after OAUTH_REQUEST_TIMEOUT.
+ _get(_redirect({"state": state, "code": "real-code"}), timeout=20)
+
+ started = time.monotonic()
+ _url, exchanged = _run_flow_with_browser(isolated, monkeypatch, browser)
+ for sock in idle:
+ sock.close()
+ assert exchanged["code"] == "real-code"
+ assert time.monotonic() - started < 15
+
+
+def test_google_error_with_our_state_stops_and_clears_the_pending_flow(isolated, monkeypatch, capsys):
+ def browser(url):
+ state = urllib.parse.parse_qs(urllib.parse.urlparse(url).query)["state"][0]
+ _get(_redirect({"state": state, "error": "access_denied"}))
+
+ with pytest.raises(SystemExit):
+ _run_flow_with_browser(isolated, monkeypatch, browser)
+ assert "access_denied" in capsys.readouterr().err
+ assert google_auth._load_pending_flow() is None
+
+
+def test_timeout_keeps_the_pending_flow_for_manual_exchange(isolated, monkeypatch):
+ monkeypatch.setattr(google_auth, "OAUTH_WAIT_SECONDS", 1)
+ with pytest.raises(SystemExit):
+ _run_flow_with_browser(isolated, monkeypatch, lambda url: None)
+ pending = google_auth._load_pending_flow()
+ assert pending and pending["code_verifier"] and pending["state"]
+ path = google_auth._pending_flow_path()
+ if os.name == "posix":
+ assert os.stat(path).st_mode & 0o777 == 0o600
+
+
+def test_manual_exchange_checks_state_of_a_pasted_url(isolated):
+ google_auth._save_pending_flow("good-state", "v" * 64)
+ code, verifier, error = google_auth._manual_exchange_inputs(_redirect({"state": "good-state", "code": "c1"}))
+ assert (code, verifier, error) == ("c1", "v" * 64, None)
+ code, verifier, error = google_auth._manual_exchange_inputs(_redirect({"state": "other", "code": "c2"}))
+ assert code is None and "pending sign-in" in error
+ code, verifier, error = google_auth._manual_exchange_inputs("bare-code")
+ assert (code, verifier, error) == ("bare-code", "v" * 64, None)
+
+
+def test_expired_pending_flow_is_refused(isolated, monkeypatch):
+ google_auth._save_pending_flow("s", "v" * 64)
+ real_time = time.time
+ monkeypatch.setattr(google_auth.time, "time", lambda: real_time() + google_auth.OAUTH_PENDING_MAX_AGE + 5)
+ assert google_auth._load_pending_flow() is None
+ assert not os.path.exists(google_auth._pending_flow_path())
+
+
+def test_exchange_sends_verifier_with_timeout_and_clears_pending(isolated, monkeypatch):
+ google_auth._save_pending_flow("s", "v" * 64)
+ calls: list = []
+ monkeypatch.setattr(urllib.request, "urlopen", _fake_urlopen(calls))
+ google_auth._exchange_code(CLIENT, "the-code", None, "v" * 64)
+ assert calls[0]["data"]["code_verifier"] == ["v" * 64]
+ assert calls[0]["timeout"] == 30
+ assert google_auth._load_pending_flow() is None
+ token = json.loads(Path(google_auth.TOKEN_PATH).read_text())
+ assert "client_secret" not in token and token["access_token"] == "at"
+
+
+def test_refresh_passes_a_timeout(isolated, monkeypatch):
+ calls: list = []
+ monkeypatch.setattr(urllib.request, "urlopen", _fake_urlopen(calls))
+ refreshed = google_auth._refresh_oauth_token(CLIENT, {"refresh_token": "rt"})
+ assert refreshed and refreshed["access_token"] == "at"
+ assert calls[0]["timeout"] == 30