sovaria-cli 0.2.0__py3-none-any.whl

apps/cli/src/commands/login.py

@@ -0,0 +1,842 @@
+"""
+apps.cli.src.commands.login — OAuth2 PKCE browser-based login for the CLI.
+
+Phase 1 §9 Sprint 3.2:
+    "CLI performs OAuth2 PKCE flow: opens browser → local callback server
+     captures the code → exchanges for JWT token pair."
+
+Flow:
+  1. Generate code_verifier (43-128 random chars) + code_challenge = BASE64URL(SHA-256(verifier))
+  2. Open https://{api}/oauth/authorize?response_type=code&...&code_challenge=...
+    3. Start a temporary HTTP callback server (configured via env variables).
+  4. Exchange authorization_code + verifier for token pair.
+  5. Persist tokens via auth_store.save_tokens().
+
+Note: The Axis engine Sprint 3.x roadmap adds the /oauth/* endpoints.
+      This CLI command is spec-complete and will work once those are live.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import os
+import queue
+import secrets
+import time
+import webbrowser
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from urllib.parse import parse_qs, urlencode, urlparse
+
+import httpx
+import typer
+
+from apps.cli.src.utils.api_client import CLIMfaRequiredError, _apply_login_response
+from apps.cli.src.utils.auth_store import clear_mfa_pending, clear_tokens, load_mfa_pending, load_tokens, save_tokens
+from apps.cli.src.utils.config import get_api_url
+
+app = typer.Typer()
+
+_CALLBACK_PATH = "/callback"
+
+
+def _callback_host() -> str:
+    return os.getenv("SOVARIA_CLI_CALLBACK_HOST", "127.0.0.1").strip() or "127.0.0.1"
+
+
+def _callback_port() -> int:
+    raw = os.getenv("SOVARIA_CLI_CALLBACK_PORT", "9876").strip()
+    if not raw:
+        raise RuntimeError("SOVARIA_CLI_CALLBACK_PORT must be set")
+    return int(raw)
+
+
+def _redirect_uri() -> str:
+    return f"http://{_callback_host()}:{_callback_port()}{_CALLBACK_PATH}"
+
+
+# ── PKCE helpers ──────────────────────────────────────────────────────────────
+
+
+def _generate_pkce_pair() -> tuple[str, str]:
+    """Return (code_verifier, code_challenge)."""
+    code_verifier = secrets.token_urlsafe(64)  # 86 chars — well within 43-128 range
+    digest = hashlib.sha256(code_verifier.encode()).digest()
+    code_challenge = base64.urlsafe_b64encode(digest).rstrip(b"=").decode()
+    return code_verifier, code_challenge
+
+
+# ── Local callback server ─────────────────────────────────────────────────────
+
+
+def _make_callback_handler(
+    result_queue: queue.Queue[tuple[str, str | None]], expected_state: str
+) -> type[BaseHTTPRequestHandler]:
+    """
+    Factory that closes over a thread-safe queue and the expected CSRF state value.
+
+    Returns a per-request handler class so that concurrent ``login`` invocations
+    each get their own queue — eliminating the class-level ``code`` race condition
+    of a shared mutable class attribute.
+    """
+
+    class _CallbackHandler(BaseHTTPRequestHandler):
+        """One-shot HTTP handler that captures the ?code= + ?state= query parameters."""
+
+        def do_GET(self) -> None:  # noqa: N802
+            parsed = urlparse(self.path)
+            if parsed.path != _CALLBACK_PATH:
+                self._respond(404, b"Not found")
+                return
+
+            qs = parse_qs(parsed.query)
+            code = qs.get("code", [None])[0]
+            state = qs.get("state", [None])[0]
+
+            # CSRF / state check — reject responses whose state doesn't match
+            # what we sent to the auth server (RFC 6749 §10.12).
+            if state != expected_state:
+                self._respond(
+                    400,
+                    b"<html><body><h2>State mismatch - possible CSRF attack.</h2></body></html>",
+                )
+                result_queue.put(("csrf", None))
+                return
+
+            html = (
+                b"<html><body><h2>Sovaria Login Successful</h2>"
+                b"<p>You can close this tab and return to the terminal.</p></body></html>"
+            )
+            self._respond(200, html)
+            result_queue.put(("ok", code) if code else ("missing_code", None))
+
+        def _respond(self, status: int, body: bytes) -> None:
+            self.send_response(status)
+            self.send_header("Content-Type", "text/html")
+            self.end_headers()
+            self.wfile.write(body)
+
+        def log_message(self, *_: object) -> None:  # suppress access log noise
+            pass
+
+    return _CallbackHandler
+
+
+def _serve_callback(expected_state: str) -> tuple[str | None, str | None]:
+    """
+    Start the callback server and block until a code arrives or the 2-minute
+    timeout elapses.  Returns (authorization code, error reason).
+    """
+    result_queue: queue.Queue[tuple[str, str | None]] = queue.Queue()
+    handler_class = _make_callback_handler(result_queue, expected_state)
+    server = HTTPServer((_callback_host(), _callback_port()), handler_class)
+    deadline = time.monotonic() + 120
+    try:
+        while time.monotonic() < deadline:
+            server.timeout = max(0.1, min(1.0, deadline - time.monotonic()))
+            server.handle_request()
+            try:
+                status, code = result_queue.get_nowait()
+            except queue.Empty:
+                continue
+            if status == "ok" and code:
+                return code, None
+            if status == "csrf":
+                return None, "csrf"
+            if status == "missing_code":
+                return None, "missing_code"
+        return None, "timeout"
+    finally:
+        server.server_close()
+
+
+# ── Commands ──────────────────────────────────────────────────────────────────
+
+
+@app.command("login")
+def login(
+    email: str | None = typer.Option(
+        None, "--email", "-e", help="Email (skips PKCE, uses password)"
+    ),
+    password: str | None = typer.Option(
+        None,
+        "--password",
+        "-p",
+        help="Password (reads from stdin prompt if --email given without --password)",
+    ),
+    profile: str | None = typer.Option(None, "--profile", help="Config profile to use"),
+    org_id: str | None = typer.Option(None, "--org", help="Organization ID scope"),
+    project_id: str | None = typer.Option(None, "--project", help="Project ID scope"),
+    env_id: str | None = typer.Option(None, "--env", help="Environment ID scope"),
+) -> None:
+    """
+    Authenticate with Sovaria.
+
+    By default opens a browser (PKCE flow).
+    Pass --email to use password login (prompts securely if --password not given).
+    """
+    api_url = get_api_url(profile)
+
+    if email:
+        if not password:
+            import getpass
+
+            password = getpass.getpass("Password: ")
+        _password_login(api_url, email, password, org_id, project_id, env_id, profile=profile)
+    else:
+        _pkce_login(api_url, profile=profile)
+
+
+def _password_login(
+    api_url: str,
+    email: str,
+    password: str,
+    org_id: str | None = None,
+    project_id: str | None = None,
+    env_id: str | None = None,
+    profile: str | None = None,
+) -> None:
+    """Direct credential exchange — bypasses PKCE.
+
+    The CLI is a platform tool (it manages orgs, projects, deployments,
+    audit, etc.) so it always authenticates against the platform console
+    lane. End-users of customer projects must use the project login on the
+    web — they have no business running ``sov`` against the platform.
+    """
+    if any((org_id, project_id, env_id)):
+        typer.echo(
+            "Note: --org/--project/--env are ignored on `sov login`. "
+            "The CLI authenticates as a Sovaria platform user; scope is "
+            "selected per-command via `sov scope use ...`.",
+            err=True,
+        )
+
+    try:
+        resp = httpx.post(
+            f"{api_url}/api/v1/auth/console/login",
+            headers={"Content-Type": "application/json"},
+            json={"email": email, "password": password},
+            timeout=15,
+        )
+        resp.raise_for_status()
+        _apply_login_response(resp.json(), profile=profile)
+        typer.echo(typer.style("Logged in successfully", fg=typer.colors.GREEN))
+    except CLIMfaRequiredError as exc:
+        typer.echo(typer.style(str(exc), fg=typer.colors.YELLOW), err=True)
+        raise typer.Exit(2) from exc
+    except httpx.HTTPStatusError as exc:
+        msg = exc.response.text
+        try:
+            detail = exc.response.json().get("detail", msg)
+        except Exception:
+            detail = msg
+        typer.echo(f"Login failed: {detail}", err=True)
+        raise typer.Exit(1) from exc
+
+
+def _pkce_login(api_url: str, *, profile: str | None = None) -> None:
+    """Full OAuth2 PKCE browser flow."""
+    code_verifier, code_challenge = _generate_pkce_pair()
+    state = secrets.token_hex(16)
+    redirect_uri = _redirect_uri()
+
+    auth_url = f"{api_url}/oauth/authorize?" + urlencode(
+        {
+            "response_type": "code",
+            "client_id": "sovaria-cli",
+            "redirect_uri": redirect_uri,
+            "code_challenge": code_challenge,
+            "code_challenge_method": "S256",
+            "state": state,
+        }
+    )
+
+    typer.echo(f"Opening browser for authentication…\n{auth_url}")
+    webbrowser.open_new(auth_url)
+    typer.echo(f"Waiting for callback on port {_callback_port()}…")
+
+    code, callback_error = _serve_callback(expected_state=state)
+    if not code:
+        if callback_error == "csrf":
+            typer.echo("Login failed: callback state mismatch (possible CSRF).", err=True)
+        else:
+            typer.echo("No authorization code received — login timed out.", err=True)
+        raise typer.Exit(1)
+
+    # Exchange code for tokens
+    try:
+        resp = httpx.post(
+            f"{api_url}/oauth/token",
+            data={
+                "grant_type": "authorization_code",
+                "code": code,
+                "redirect_uri": redirect_uri,
+                "client_id": "sovaria-cli",
+                "code_verifier": code_verifier,
+            },
+            timeout=15,
+        )
+        resp.raise_for_status()
+        _apply_login_response(resp.json(), profile=profile)
+        typer.echo(typer.style("✓ Logged in successfully", fg=typer.colors.GREEN))
+    except CLIMfaRequiredError as exc:
+        typer.echo(typer.style(str(exc), fg=typer.colors.YELLOW), err=True)
+        raise typer.Exit(2) from exc
+    except httpx.HTTPStatusError as exc:
+        typer.echo(f"Token exchange failed: {exc.response.text}", err=True)
+        raise typer.Exit(1) from exc
+
+
+@app.command("logout")
+def logout(
+    profile: str | None = typer.Option(None, "--profile", help="Config profile to use"),
+) -> None:
+    """Revoke the session for one profile, then clear that profile's local credentials."""
+    tokens = load_tokens(profile=profile)
+    if tokens and tokens.get("access_token") and tokens.get("refresh_token"):
+        try:
+            httpx.post(
+                f"{get_api_url(profile)}/api/v1/auth/logout",
+                json={"refresh_token": tokens["refresh_token"]},
+                headers={"Authorization": f"Bearer {tokens['access_token']}"},
+                timeout=10,
+            )
+        except Exception:  # pylint: disable=broad-exception-caught
+            pass  # best-effort — always clear local tokens regardless
+    clear_tokens(profile=profile)
+    clear_mfa_pending(profile=profile)
+    typer.echo("Logged out.")
+
+
+@app.command("mfa-verify")
+def mfa_verify(
+    code: str = typer.Option(..., "--code", "-c", help="6-digit TOTP or backup code"),
+    method: str = typer.Option("totp", "--method", help="Verification method: totp or phone"),
+    profile: str | None = typer.Option(None, "--profile", help="Config profile to use"),
+) -> None:
+    """Complete MFA after login when the gateway returned mfa_required=true."""
+    pending = load_mfa_pending(profile=profile)
+    if not pending:
+        typer.echo(
+            "No pending MFA challenge found. Run `sov auth login` first.",
+            err=True,
+        )
+        raise typer.Exit(1)
+
+    challenge_token = str(pending.get("access_token") or "").strip()
+    if not challenge_token:
+        typer.echo("Stored MFA challenge token is missing or invalid.", err=True)
+        raise typer.Exit(1)
+
+    api_url = get_api_url(profile).rstrip("/")
+    try:
+        resp = httpx.post(
+            f"{api_url}/api/v1/auth/mfa/verify",
+            headers={
+                "Authorization": f"Bearer {challenge_token}",
+                "Content-Type": "application/json",
+            },
+            json={"code": code.strip(), "method": method.strip().lower()},
+            timeout=15,
+        )
+        resp.raise_for_status()
+        _apply_login_response(resp.json(), profile=profile)
+        clear_mfa_pending(profile=profile)
+        typer.echo(typer.style("MFA verified — full session established.", fg=typer.colors.GREEN))
+    except CLIMfaRequiredError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(2) from exc
+    except httpx.HTTPStatusError as exc:
+        detail = exc.response.text
+        try:
+            detail = exc.response.json().get("detail", detail)
+        except Exception:
+            pass
+        typer.echo(f"MFA verification failed: {detail}", err=True)
+        raise typer.Exit(1) from exc
+
+
+@app.command("sessions")
+def list_sessions(
+    profile: str | None = typer.Option(None, "--profile", help="Config profile to use"),
+) -> None:
+    """List active login sessions for the current user."""
+    from apps.cli.src.utils.api_client import CLIRequestError, call_api, print_json
+
+    try:
+        result = call_api(method="GET", path="/api/v1/auth/sessions", profile=profile)
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(print_json(result))
+
+
+@app.command("sessions-revoke")
+def revoke_session(
+    session_id: str = typer.Argument(..., help="Session id (refresh token JTI)"),
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """Revoke one active session."""
+    from urllib.parse import quote
+
+    from apps.cli.src.utils.api_client import CLIRequestError, call_api
+
+    safe_id = quote(session_id, safe="")
+    try:
+        call_api(
+            method="DELETE",
+            path=f"/api/v1/auth/sessions/{safe_id}",
+            profile=profile,
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(typer.style(f"Revoked session {session_id}", fg=typer.colors.GREEN))
+
+
+@app.command("sessions-revoke-others")
+def revoke_other_sessions(
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """Revoke all sessions except the current one."""
+    from apps.cli.src.utils.api_client import CLIRequestError, call_api
+
+    try:
+        call_api(
+            method="POST",
+            path="/api/v1/auth/sessions/revoke-others",
+            profile=profile,
+            body={},
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(typer.style("Other sessions revoked.", fg=typer.colors.GREEN))
+
+
+@app.command("mfa-status")
+def mfa_status(
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """Show MFA enrollment status for the current user."""
+    from apps.cli.src.utils.api_client import CLIRequestError, call_api, print_json
+
+    try:
+        result = call_api(method="GET", path="/api/v1/auth/mfa/status", profile=profile)
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(print_json(result))
+
+
+@app.command("mfa-enroll")
+def mfa_enroll(
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """Start TOTP MFA enrollment (shows secret, URI, and backup codes once)."""
+    from apps.cli.src.utils.api_client import CLIRequestError, call_api, print_json
+
+    try:
+        result = call_api(method="POST", path="/api/v1/auth/mfa/enroll", profile=profile, body={})
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(print_json(result))
+    typer.echo(
+        typer.style(
+            "\nScan the totp_uri in your authenticator app, then run:\n"
+            "  sov auth mfa-verify --code <6-digit-code>",
+            fg=typer.colors.YELLOW,
+        )
+    )
+
+
+@app.command("mfa-disable")
+def mfa_disable(
+    code: str = typer.Option(..., "--code", "-c", help="Current TOTP code to confirm disable"),
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """Disable MFA (requires current TOTP code)."""
+    from apps.cli.src.utils.api_client import CLIRequestError, call_api, print_json
+
+    try:
+        result = call_api(
+            method="DELETE",
+            path="/api/v1/auth/mfa",
+            profile=profile,
+            body={"totp_code": code.strip()},
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(print_json(result))
+    typer.echo(typer.style("MFA disabled.", fg=typer.colors.GREEN))
+
+
+magic_link_app = typer.Typer(help="Passwordless magic-link login")
+verify_email_app = typer.Typer(help="Email verification")
+sessions_config_app = typer.Typer(help="Session policy configuration")
+providers_config_app = typer.Typer(help="Auth provider configuration")
+event_hooks_app = typer.Typer(help="Auth event webhook subscriptions")
+github_state_app = typer.Typer(help="GitHub OAuth connection state")
+
+app.add_typer(magic_link_app, name="magic-link")
+app.add_typer(verify_email_app, name="verify-email")
+app.add_typer(sessions_config_app, name="sessions-config")
+app.add_typer(providers_config_app, name="providers-config")
+app.add_typer(event_hooks_app, name="event-hooks")
+app.add_typer(github_state_app, name="github-state")
+
+
+@magic_link_app.command("send")
+def magic_link_send(
+    email: str = typer.Option(..., "--email"),
+    profile: str | None = typer.Option(None, "--profile"),
+    org_id: str | None = typer.Option(None, "--org"),
+    project_id: str | None = typer.Option(None, "--project"),
+) -> None:
+    """Send a magic-link sign-in email."""
+    from apps.cli.src.utils.api_client import CLIRequestError, call_api, print_json
+
+    body: dict[str, object] = {"email": email}
+    if org_id:
+        body["org_id"] = org_id
+    if project_id:
+        body["project_id"] = project_id
+    try:
+        result = call_api(
+            method="POST",
+            path="/api/v1/auth/magic-link/send",
+            profile=profile,
+            org_id=org_id,
+            project_id=project_id,
+            body=body,
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(print_json(result))
+
+
+@magic_link_app.command("verify")
+def magic_link_verify(
+    token: str = typer.Option(..., "--token"),
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """Exchange a magic-link token for a session."""
+    from apps.cli.src.utils.api_client import CLIRequestError, call_api, _apply_login_response
+
+    api_url = get_api_url(profile).rstrip("/")
+    try:
+        resp = httpx.post(
+            f"{api_url}/api/v1/auth/magic-link/verify",
+            headers={"Content-Type": "application/json"},
+            json={"token": token.strip()},
+            timeout=15,
+        )
+        resp.raise_for_status()
+        _apply_login_response(resp.json(), profile=profile)
+        typer.echo(typer.style("Magic link verified — session established.", fg=typer.colors.GREEN))
+    except CLIMfaRequiredError as exc:
+        typer.echo(typer.style(str(exc), fg=typer.colors.YELLOW), err=True)
+        raise typer.Exit(2) from exc
+    except httpx.HTTPStatusError as exc:
+        typer.echo(f"Magic link verification failed: {exc.response.text}", err=True)
+        raise typer.Exit(1) from exc
+
+
+@verify_email_app.command("send")
+def verify_email_send(
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """Send a verification email to the authenticated user."""
+    from apps.cli.src.utils.api_client import CLIRequestError, call_api, print_json
+
+    try:
+        result = call_api(
+            method="POST",
+            path="/api/v1/auth/verify-email/send",
+            profile=profile,
+            body={},
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(print_json(result))
+
+
+@verify_email_app.command("confirm")
+def verify_email_confirm(
+    token: str = typer.Option(..., "--token"),
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """Confirm an email address using a verification token."""
+    from apps.cli.src.utils.api_client import CLIRequestError, call_api, print_json
+
+    try:
+        result = call_api(
+            method="POST",
+            path="/api/v1/auth/verify-email/confirm",
+            profile=profile,
+            body={"token": token.strip()},
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(print_json(result))
+
+
+@app.command("project-login")
+def project_login(
+    email: str = typer.Option(..., "--email", "-e"),
+    password: str | None = typer.Option(None, "--password", "-p"),
+    profile: str | None = typer.Option(None, "--profile"),
+    org_id: str | None = typer.Option(None, "--org"),
+    project_id: str | None = typer.Option(None, "--project"),
+    env_id: str | None = typer.Option(None, "--env"),
+) -> None:
+    """Authenticate against the strict project login lane."""
+    if not password:
+        import getpass
+
+        password = getpass.getpass("Password: ")
+    api_url = get_api_url(profile).rstrip("/")
+    body: dict[str, object] = {"email": email, "password": password}
+    if org_id:
+        body["org_id"] = org_id
+    if project_id:
+        body["project_id"] = project_id
+    if env_id:
+        body["env_id"] = env_id
+    try:
+        resp = httpx.post(
+            f"{api_url}/api/v1/auth/project/login",
+            headers={"Content-Type": "application/json"},
+            json=body,
+            timeout=15,
+        )
+        resp.raise_for_status()
+        _apply_login_response(resp.json(), profile=profile)
+        typer.echo(typer.style("Project login successful", fg=typer.colors.GREEN))
+    except CLIMfaRequiredError as exc:
+        typer.echo(typer.style(str(exc), fg=typer.colors.YELLOW), err=True)
+        raise typer.Exit(2) from exc
+    except httpx.HTTPStatusError as exc:
+        typer.echo(f"Project login failed: {exc.response.text}", err=True)
+        raise typer.Exit(1) from exc
+
+
+@sessions_config_app.command("get")
+def sessions_config_get(
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """Fetch the authenticated user's session policy."""
+    from apps.cli.src.utils.api_client import CLIRequestError, call_api, print_json
+
+    try:
+        result = call_api(method="GET", path="/api/v1/auth/sessions/config", profile=profile)
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(print_json(result))
+
+
+@sessions_config_app.command("set")
+def sessions_config_set(
+    config_json: str = typer.Argument(..., help="JSON session policy patch"),
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """Update the authenticated user's session policy."""
+    from apps.cli.src.utils.api_client import CLIRequestError, call_api, parse_json_arg, print_json
+
+    body = parse_json_arg(config_json, label="config")
+    if body is None or not isinstance(body, dict):
+        raise typer.BadParameter("config must be a JSON object")
+    try:
+        result = call_api(
+            method="PUT",
+            path="/api/v1/auth/sessions/config",
+            profile=profile,
+            body=body,
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(print_json(result))
+
+
+@providers_config_app.command("get")
+def providers_config_get(
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """Fetch auth provider runtime configuration."""
+    from apps.cli.src.utils.api_client import CLIRequestError, call_api, print_json
+
+    try:
+        result = call_api(method="GET", path="/api/v1/auth/providers/config", profile=profile)
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(print_json(result))
+
+
+@providers_config_app.command("set")
+def providers_config_set(
+    config_json: str = typer.Argument(..., help="JSON provider config patch"),
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """Update auth provider toggles and external database link configuration."""
+    from apps.cli.src.utils.api_client import CLIRequestError, call_api, parse_json_arg, print_json
+
+    body = parse_json_arg(config_json, label="config")
+    if body is None or not isinstance(body, dict):
+        raise typer.BadParameter("config must be a JSON object")
+    try:
+        result = call_api(
+            method="PUT",
+            path="/api/v1/auth/providers/config",
+            profile=profile,
+            body=body,
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(print_json(result))
+
+
+@event_hooks_app.command("list")
+def event_hooks_list(
+    profile: str | None = typer.Option(None, "--profile"),
+    org_id: str | None = typer.Option(None, "--org"),
+    project_id: str | None = typer.Option(None, "--project"),
+    env_id: str | None = typer.Option(None, "--env"),
+) -> None:
+    """List auth event hooks for the active project."""
+    from apps.cli.src.utils.api_client import CLIRequestError, call_api, print_json
+
+    try:
+        result = call_api(
+            method="GET",
+            path="/api/v1/auth/event-hooks",
+            profile=profile,
+            org_id=org_id,
+            project_id=project_id,
+            env_id=env_id,
+            require_scope=True,
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(print_json(result))
+
+
+@event_hooks_app.command("create")
+def event_hooks_create(
+    name: str = typer.Option(..., "--name"),
+    url: str = typer.Option(..., "--url"),
+    events: list[str] = typer.Option(..., "--event", help="Repeat for each event type"),
+    secret: str = typer.Option("", "--secret"),
+    enabled: bool = typer.Option(True, "--enabled/--disabled"),
+    profile: str | None = typer.Option(None, "--profile"),
+    org_id: str | None = typer.Option(None, "--org"),
+    project_id: str | None = typer.Option(None, "--project"),
+    env_id: str | None = typer.Option(None, "--env"),
+) -> None:
+    """Create an auth event hook subscription."""
+    from apps.cli.src.utils.api_client import CLIRequestError, call_api, print_json
+
+    try:
+        result = call_api(
+            method="POST",
+            path="/api/v1/auth/event-hooks",
+            profile=profile,
+            org_id=org_id,
+            project_id=project_id,
+            env_id=env_id,
+            require_scope=True,
+            body={
+                "name": name,
+                "url": url,
+                "events": events,
+                "secret": secret,
+                "enabled": enabled,
+            },
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(print_json(result))
+
+
+@event_hooks_app.command("delete")
+def event_hooks_delete(
+    hook_id: str = typer.Argument(..., help="Auth event hook ID"),
+    profile: str | None = typer.Option(None, "--profile"),
+    org_id: str | None = typer.Option(None, "--org"),
+    project_id: str | None = typer.Option(None, "--project"),
+    env_id: str | None = typer.Option(None, "--env"),
+) -> None:
+    """Delete an auth event hook."""
+    from urllib.parse import quote
+
+    from apps.cli.src.utils.api_client import CLIRequestError, call_api
+
+    safe_id = quote(hook_id, safe="")
+    try:
+        call_api(
+            method="DELETE",
+            path=f"/api/v1/auth/event-hooks/{safe_id}",
+            profile=profile,
+            org_id=org_id,
+            project_id=project_id,
+            env_id=env_id,
+            require_scope=True,
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(typer.style(f"Deleted auth event hook {hook_id}", fg=typer.colors.GREEN))
+
+
+@github_state_app.command("get")
+def github_state_get(
+    profile: str | None = typer.Option(None, "--profile"),
+    project_id: str | None = typer.Option(None, "--project"),
+) -> None:
+    """Fetch GitHub OAuth connection state."""
+    from apps.cli.src.utils.api_client import CLIRequestError, call_api, print_json
+
+    params = {"project_id": project_id} if project_id else None
+    try:
+        result = call_api(
+            method="GET",
+            path="/api/v1/auth/github/connection-state",
+            profile=profile,
+            params=params,
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(print_json(result))
+
+
+@github_state_app.command("disconnect")
+def github_state_disconnect(
+    profile: str | None = typer.Option(None, "--profile"),
+    project_id: str | None = typer.Option(None, "--project"),
+) -> None:
+    """Disconnect GitHub OAuth broker state."""
+    from apps.cli.src.utils.api_client import CLIRequestError, call_api, print_json
+
+    params = {"project_id": project_id} if project_id else None
+    try:
+        result = call_api(
+            method="DELETE",
+            path="/api/v1/auth/github/connection-state",
+            profile=profile,
+            params=params,
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(print_json(result))