tlnt-cli 1.5.1__py3-none-any.whl

tlnt/__init__.py

@@ -0,0 +1,3 @@
+# The name on PyPI, which refuses "tlnt" as too similar to the existing
+# project "tint". The command and the import package are still "tlnt".
+DISTRIBUTION = "tlnt-cli"

tlnt/__main__.py

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

tlnt/browser/login.py

@@ -0,0 +1,414 @@
+"""Visible browser login and mobile OAuth capture."""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Callable, Iterator
+from contextlib import AbstractContextManager, contextmanager
+from dataclasses import dataclass, field
+from datetime import datetime
+from time import monotonic
+from typing import Any
+from urllib.parse import urlsplit
+
+from playwright.sync_api import Error as PlaywrightError
+from playwright.sync_api import TimeoutError as PlaywrightTimeoutError
+from playwright.sync_api import sync_playwright
+
+from tlnt.browser.oauth import authorize_url, code_from_url, pkce_pair
+from tlnt.core.clients.mekari.client import MekariClient
+from tlnt.core.clients.mekari.constants import (
+    DASHBOARD_TALENTA_URL,
+    MEKARI_DOMAIN,
+    STATIC_ASSET_SUFFIXES,
+    TALENTA_DOMAIN,
+)
+from tlnt.core.models import MobileToken, Profile, SessionState
+from tlnt.core.logs import logger
+
+
+_log = logger.bind(component="browser")
+
+LOGIN_TIMEOUT_SECONDS = 300
+FORM_TIMEOUT_MS = 10_000
+SIGN_IN_TIMEOUT_MS = 60_000
+_SIGN_IN_PATH = "/users/sign_in"
+# 127.0.0.1, not localhost: Chrome binds IPv4 loopback while localhost may
+# resolve to ::1 first.
+DEFAULT_CDP_ENDPOINT = "http://127.0.0.1:9222"
+_CDP_SCHEMES = ("http", "https", "ws", "wss")
+
+
+class LoginFailed(RuntimeError):
+    pass
+
+
+@dataclass(frozen=True)
+class Credentials:
+    email: str
+    password: str = field(repr=False)
+
+
+@contextmanager
+def chrome_context(headless: bool = False) -> Iterator[Any]:
+    """Yield a context on the installed Chrome, falling back to Edge."""
+    with sync_playwright() as playwright:
+        for channel in ("chrome", "msedge"):
+            try:
+                browser = playwright.chromium.launch(
+                    channel=channel, headless=headless
+                )
+            except PlaywrightError:
+                continue
+            try:
+                yield browser.new_context()
+            finally:
+                browser.close()
+            return
+    raise LoginFailed(
+        "Install Google Chrome or Microsoft Edge to sign in, attach to a running "
+        "browser with --cdp, or use --headless with --email on a host without a display"
+    )
+
+
+def cdp_endpoint(value: str) -> str:
+    """Normalize a port, host:port, or http(s)/ws(s) URL into a CDP endpoint."""
+    text = value.strip()
+    if text.isdigit():
+        text = f"127.0.0.1:{text}"
+    if "://" not in text:
+        text = f"http://{text}"
+    try:
+        parts = urlsplit(text)
+        valid = (
+            parts.scheme in _CDP_SCHEMES
+            and bool(parts.hostname)
+            and parts.port != 0
+        )
+    except ValueError:
+        valid = False
+    if not valid:
+        raise ValueError(
+            f"Invalid CDP endpoint '{value}': "
+            "use a port, host:port, or an http(s)/ws(s) URL"
+        )
+    return text
+
+
+@contextmanager
+def cdp_context(endpoint: str) -> Iterator[Any]:
+    """Yield the default context of a browser that is already running (CDP).
+
+    The browser, its context and its tabs belong to the user, so nothing here
+    closes them; leaving ``sync_playwright`` only drops the connection.
+    """
+    with sync_playwright() as playwright:
+        try:
+            browser = playwright.chromium.connect_over_cdp(endpoint)
+        except PlaywrightError as error:
+            raise LoginFailed(
+                f"Could not connect to a browser at {endpoint}; start it with "
+                "--remote-debugging-port=9222 "
+                "(Chrome 136+ also needs --user-data-dir)"
+            ) from error
+        yield browser.contexts[0]
+
+
+def _wait_for_dashboard(
+    context: Any,
+    opened: Any,
+    existing: list[Any],
+    deadline: float,
+) -> Any:
+    """Wait for a tab the login created, not for tabs the browser already had."""
+    while True:
+        pages = context.pages
+        if opened not in pages:
+            raise LoginFailed("Browser was closed before login completed")
+        for page in pages:
+            if page in existing:
+                continue
+            normalized = page.url.split("?", 1)[0].split("#", 1)[0].rstrip("/")
+            if normalized == DASHBOARD_TALENTA_URL:
+                return page
+        remaining = deadline - monotonic()
+        if remaining <= 0:
+            raise PlaywrightTimeoutError("Login did not reach the Talenta dashboard")
+        try:
+            opened.wait_for_timeout(min(100, remaining * 1000))
+        except (PlaywrightError, PlaywrightTimeoutError):
+            pass
+
+
+def _sign_in(page: Any, credentials: Credentials) -> None:
+    """Type the credentials into Mekari's sign-in form and submit it once."""
+    try:
+        try:
+            page.fill("#user_email", credentials.email, timeout=FORM_TIMEOUT_MS)
+        except PlaywrightTimeoutError:
+            if _SIGN_IN_PATH in page.url:
+                raise LoginFailed(
+                    "Mekari's sign-in form did not appear. Run tlnt login "
+                    "without --email to sign in yourself"
+                ) from None
+            return  # not on the sign-in page: the browser is already signed in
+        page.fill("#user_password", credentials.password, timeout=FORM_TIMEOUT_MS)
+        page.click("#new-signin-button", timeout=FORM_TIMEOUT_MS)
+        # ponytail: fixed 60 s wait; read Mekari's error text if wrong-password
+        # feedback must be faster.
+        page.wait_for_url(
+            lambda url: _SIGN_IN_PATH not in url,
+            wait_until="commit",
+            timeout=SIGN_IN_TIMEOUT_MS,
+        )
+    except PlaywrightTimeoutError:
+        # `from None` on every raise here: Playwright's call log, appended to
+        # every error class, echoes the typed value.
+        raise LoginFailed(
+            "Mekari did not accept the sign-in. Check the email and password, "
+            "or run tlnt login without --email if it asks for a code or captcha"
+        ) from None
+    except PlaywrightError:
+        raise LoginFailed(
+            "The browser stopped while tlnt was signing in. Run tlnt login again"
+        ) from None
+
+
+def _extract_profile(settings: Any) -> Profile:
+    if not isinstance(settings, dict):
+        raise LoginFailed("Talenta did not expose user profile data")
+
+    company = settings.get("company")
+    company = company if isinstance(company, dict) else {}
+    fields = {
+        "name": settings.get("name"),
+        "email": settings.get("email") or settings.get("Email"),
+        "Talenta User ID": settings.get("Talenta User ID"),
+        "Company ID": settings.get("Company ID") or company.get("id"),
+        "Company Name": settings.get("Company Name") or company.get("name"),
+    }
+    missing = next(
+        (
+            name
+            for name, value in fields.items()
+            if name != "Company Name"
+            if isinstance(value, bool)
+            or not isinstance(value, (str, int, float))
+            or not str(value).strip()
+        ),
+        None,
+    )
+    if missing:
+        raise LoginFailed(f"Talenta profile missing {missing}")
+
+    company_name = fields["Company Name"]
+    if (
+        isinstance(company_name, bool)
+        or not isinstance(company_name, (str, int, float))
+        or not str(company_name).strip()
+    ):
+        company_name = None
+
+    return Profile(
+        name=str(fields["name"]),
+        email=str(fields["email"]),
+        talenta_user_id=str(fields["Talenta User ID"]),
+        company_id=str(fields["Company ID"]),
+        company_name=str(company_name) if company_name is not None else None,
+    )
+
+
+def _is_relevant_host(url: str) -> bool:
+    host = (urlsplit(url).hostname or "").lower()
+    return any(
+        host == domain or host.endswith(f".{domain}")
+        for domain in (MEKARI_DOMAIN, TALENTA_DOMAIN)
+    )
+
+
+def _is_static_asset(path: str) -> bool:
+    return (
+        path.endswith(STATIC_ASSET_SUFFIXES)
+        or "/assets/" in path
+        or "/images/" in path
+    )
+
+class _OAuthSink:
+    def __init__(self) -> None:
+        self.code: str | None = None
+        self.urls: list[str] = []
+
+    def note(self, url: str) -> None:
+        if not _is_relevant_host(url):
+            return
+        self.urls.append(url)
+        if self.code is None:
+            self.code = code_from_url(url)
+
+    def on_response(self, response: Any) -> None:
+        self.note(response.url)
+
+
+def _redirect_chain(sink: _OAuthSink) -> str:
+    seen: list[str] = []
+    for url in sink.urls:
+        parts = urlsplit(url)
+        if _is_static_asset(parts.path):
+            continue
+        step = f"{parts.netloc}{parts.path}"
+        if not seen or seen[-1] != step:
+            seen.append(step)
+    return " -> ".join(seen) if seen else f"(no {MEKARI_DOMAIN}/{TALENTA_DOMAIN} traffic observed)"
+
+
+def _report_capture_miss(sink: _OAuthSink) -> None:
+    _log.bind(
+        event="failure",
+        phase="token_capture",
+        error_type="token_not_captured",
+    ).warning("mobile token not captured")
+    print(
+        "Mobile token not captured.\n"
+        "  checked: authorization code and PKCE token exchange\n"
+        f"  redirect chain: {_redirect_chain(sink)}\n"
+        "  Set TALENTA_BEARER to clock in now, or share the chain above to "
+        "close the gap.",
+        file=sys.stderr,
+    )
+
+
+class BrowserLogin:
+    def __init__(
+        self,
+        *,
+        client: MekariClient | None = None,
+        context_factory: Callable[[], AbstractContextManager[Any]] = chrome_context,
+        credentials: Credentials | None = None,
+    ) -> None:
+        self.client = client or MekariClient()
+        self._owns_client = client is None
+        self.context_factory = context_factory
+        self.credentials = credentials
+
+    def _capture_mobile_token(
+        self,
+        page: Any,
+        sink: _OAuthSink,
+    ) -> MobileToken | None:
+        _log.bind(
+            event="phase_started",
+            phase="token_capture",
+        ).debug("mobile token capture started")
+        try:
+            verifier, challenge = pkce_pair()
+            page.set_extra_http_headers({"X-Requested-With": "co.talenta"})
+            page.goto(
+                authorize_url(challenge),
+                wait_until="domcontentloaded",
+                timeout=30_000,
+            )
+            if sink.code is None:
+                sink.code = code_from_url(page.url)
+        except (PlaywrightError, PlaywrightTimeoutError) as error:
+            _log.bind(
+                event="failure",
+                phase="token_capture",
+                error_type=type(error).__name__,
+            ).warning("mobile token capture failed")
+            return None
+        return self._exchange(sink, verifier)
+
+    def _exchange(self, sink: _OAuthSink, verifier: str) -> MobileToken | None:
+        token = (
+            self.client.exchange_code(sink.code, verifier)
+            if sink.code is not None
+            else None
+        )
+        if token is None:
+            _report_capture_miss(sink)
+            return None
+        _log.bind(
+            event="phase_finished",
+            phase="token_capture",
+        ).debug("mobile token capture finished")
+        return token
+
+    def login(self) -> SessionState:
+        try:
+            return self._login()
+        finally:
+            if self._owns_client:
+                self.client.close()
+
+    def _capture_browser_session(
+        self,
+        sink: _OAuthSink,
+    ) -> tuple[Profile | None, MobileToken | None]:
+        with self.context_factory() as context:
+            _log.bind(
+                event="phase_started",
+                phase="browser_context",
+            ).debug("browser context started")
+            existing = list(context.pages)
+            opened = context.new_page()
+            context.on("response", sink.on_response)
+            try:
+                opened.goto(
+                    DASHBOARD_TALENTA_URL,
+                    wait_until="domcontentloaded",
+                    timeout=30_000,
+                )
+                opened.bring_to_front()
+                deadline = monotonic() + LOGIN_TIMEOUT_SECONDS
+                if self.credentials is not None:
+                    _sign_in(opened, self.credentials)
+                page = _wait_for_dashboard(context, opened, existing, deadline)
+                _log.bind(
+                    event="phase_finished",
+                    phase="dashboard",
+                ).debug("dashboard reached")
+                try:
+                    profile = _extract_profile(
+                        page.evaluate("() => window.intercomSettings ?? null")
+                    )
+                except LoginFailed:
+                    profile = None
+                mobile = self._capture_mobile_token(opened, sink)
+                return profile, mobile
+            finally:
+                context.remove_listener("response", sink.on_response)
+                opened.close()
+
+    def _login(self) -> SessionState:
+        _log.bind(event="phase_started", phase="login").debug(
+            "browser login started"
+        )
+        sink = _OAuthSink()
+        try:
+            profile, mobile = self._capture_browser_session(sink)
+        except OSError as error:
+            _log.bind(
+                event="failure",
+                phase="login",
+                error_type=type(error).__name__,
+            ).warning("browser login failed")
+            raise LoginFailed("Browser could not be started") from error
+        except (PlaywrightError, PlaywrightTimeoutError) as error:
+            _log.bind(
+                event="failure",
+                phase="login",
+                error_type=type(error).__name__,
+            ).warning("browser login failed")
+            raise LoginFailed("Login did not complete within five minutes") from error
+
+        session = SessionState(
+            version=1,
+            saved_at=datetime.now().astimezone().isoformat(),
+            web_storage={},
+            profile=profile,
+            mobile=mobile,
+        )
+        _log.bind(event="phase_finished", phase="login").debug(
+            "browser login finished"
+        )
+        return session

tlnt/browser/oauth.py

@@ -0,0 +1,50 @@
+"""PKCE helpers for the Mekari mobile authorization flow."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import secrets
+from urllib.parse import parse_qsl, urlencode, urlsplit
+
+from tlnt.core.clients.mekari import constants
+from tlnt.core.clients.mekari.constants import (
+    OAUTH_AUTHORIZE_URL,
+    OAUTH_SCOPE,
+    TOKEN_REDIRECT_URL,
+)
+
+
+def pkce_pair() -> tuple[str, str]:
+    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 authorize_url(challenge: str) -> str:
+    params = {
+        "client_id": constants.client_id(),
+        "scope": OAUTH_SCOPE,
+        "response_type": "code",
+        "redirect_uri": TOKEN_REDIRECT_URL,
+        "code_challenge": challenge,
+        "code_challenge_method": "s256",
+    }
+    return f"{OAUTH_AUTHORIZE_URL}?{urlencode(params)}"
+
+
+def code_from_url(url: str) -> str | None:
+    parts = urlsplit(url)
+    redirect = urlsplit(TOKEN_REDIRECT_URL)
+    if (parts.scheme, parts.netloc, parts.path) != (
+        redirect.scheme,
+        redirect.netloc,
+        redirect.path,
+    ):
+        return None
+    for raw in (parts.query, parts.fragment):
+        for key, value in parse_qsl(raw):
+            if key == "code" and value:
+                return value
+    return None

tlnt/browser/scripted.py

@@ -0,0 +1,183 @@
+"""Login through browsers that expose no CDP port (ego lite, Yab).
+
+One short script runs through the vendor CLI per check. tlnt repeats it until
+the user is signed in to Talenta in that browser, and that same run does the
+OAuth hop. The PKCE verifier never leaves this process.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from time import monotonic, sleep
+from typing import Any, Literal
+
+from tlnt.browser.login import (
+    LOGIN_TIMEOUT_SECONDS,
+    BrowserLogin,
+    LoginFailed,
+    _extract_profile,
+    _OAuthSink,
+)
+from tlnt.browser.oauth import authorize_url, pkce_pair
+from tlnt.core.clients.mekari.client import MekariClient
+from tlnt.core.clients.mekari.constants import DASHBOARD_TALENTA_URL
+from tlnt.core.logs import logger
+from tlnt.core.models import MobileToken, Profile
+
+
+_log = logger.bind(component="browser")
+
+POLL_SECONDS = 5
+RUN_TIMEOUT_SECONDS = 90
+
+_COMMANDS = {
+    "ego": ["ego-browser", "nodejs"],
+    "yab": ["yab", "exec", "-", "--timeout", "80"],
+}
+LABELS = {"ego": "ego lite", "yab": "Yab"}
+
+# Each script opens the dashboard in a throwaway agent tab. Signed out, it
+# reports that and closes the tab. Signed in, it also reads the profile, does
+# the OAuth hop and reports the URLs it saw. __CONFIG__ becomes a JSON object
+# with `dashboard` and `authorize`.
+_EGO_SCRIPT = r"""
+const cfg = __CONFIG__;
+const bare = (u) => u.split(/[?#]/)[0].replace(/\/$/, "");
+const task = await taskSpace("tlnt login");
+const page = task.page("p1");
+const result = { signedIn: false, settings: null, urls: [] };
+try {
+  await page.goto(cfg.dashboard, { timeout: 30000 });
+  try {
+    await page.waitForURL((u) => bare(u.href) === cfg.dashboard, { timeout: 3000 });
+    result.signedIn = true;
+  } catch (e) {}
+  if (result.signedIn) {
+    result.settings = await page.evaluate(() => window.intercomSettings ?? null);
+    await page.cdp("Network.enable");
+    await page.cdp("Network.setExtraHTTPHeaders", { headers: { "X-Requested-With": "co.talenta" } });
+    await page.events();
+    // The last redirect may abort the navigation; requests seen so far still count.
+    try { await page.goto(cfg.authorize, { timeout: 30000 }); } catch (e) {}
+    for (const e of await page.events()) {
+      if (e.method === "Network.requestWillBeSent") result.urls.push(e.params.request.url);
+    }
+    result.urls.push(await page.url());
+  }
+} finally {
+  await task.finish({ keep: [] });
+}
+console.log(JSON.stringify(result));
+"""
+
+# Yab's eval runs in an isolated world, so it cannot read intercomSettings
+# (no profile is saved) and no request header can be set on the OAuth hop.
+_YAB_SCRIPT = r"""
+const cfg = __CONFIG__;
+const bare = (u) => u.split(/[?#]/)[0].replace(/\/$/, "");
+const t = open(cfg.dashboard);
+const here = () => {
+  const row = tabs().find((x) => x.id === t.id);
+  return row ? row.line.slice(row.line.lastIndexOf(", ") + 2) : "";
+};
+const result = { signedIn: false, settings: null, urls: [] };
+try {
+  result.signedIn = bare(here()) === cfg.dashboard;
+  if (result.signedIn) {
+    try { t.navigate(cfg.authorize); } catch (e) {}
+    result.urls.push(here());
+  }
+} finally {
+  t.close();
+}
+return JSON.stringify(result);
+"""
+
+_SCRIPTS = {"ego": _EGO_SCRIPT, "yab": _YAB_SCRIPT}
+
+
+def _script_result(stdout: str) -> dict[str, Any]:
+    """Return the last JSON object line, skipping notices and `(N steps)`."""
+    for line in reversed(stdout.splitlines()):
+        try:
+            data = json.loads(line)
+        except ValueError:
+            continue
+        if isinstance(data, dict):
+            return data
+    raise LoginFailed("Browser script returned no result")
+
+
+def _run_script(backend: str, authorize: str) -> dict[str, Any]:
+    argv = _COMMANDS[backend]
+    label = LABELS[backend]
+    config = json.dumps({"dashboard": DASHBOARD_TALENTA_URL, "authorize": authorize})
+    try:
+        done = subprocess.run(
+            argv,
+            input=_SCRIPTS[backend].replace("__CONFIG__", config),
+            capture_output=True,
+            text=True,
+            timeout=RUN_TIMEOUT_SECONDS,
+            check=False,
+        )
+    except FileNotFoundError as error:
+        raise LoginFailed(f"{argv[0]} was not found on PATH; install it first") from error
+    except subprocess.TimeoutExpired as error:
+        raise LoginFailed(
+            f"{label} did not respond within {RUN_TIMEOUT_SECONDS} seconds"
+        ) from error
+    if done.returncode != 0:
+        _log.bind(
+            event="failure",
+            phase="scripted_check",
+            backend=backend,
+            exit_code=done.returncode,
+        ).warning("browser script failed")
+        raise LoginFailed(
+            f"{label} stopped (exit {done.returncode}); "
+            "check its window for a prompt, then retry"
+        )
+    # ego-browser prints console.log to stderr, yab prints its result to stdout.
+    return _script_result(f"{done.stdout}\n{done.stderr}")
+
+
+class ScriptedLogin(BrowserLogin):
+    def __init__(
+        self,
+        backend: Literal["ego", "yab"],
+        *,
+        client: MekariClient | None = None,
+    ) -> None:
+        super().__init__(client=client)
+        self.backend = backend
+
+    def _capture_browser_session(
+        self,
+        sink: _OAuthSink,
+    ) -> tuple[Profile | None, MobileToken | None]:
+        verifier, challenge = pkce_pair()
+        authorize = authorize_url(challenge)
+        deadline = monotonic() + LOGIN_TIMEOUT_SECONDS
+        while True:
+            data = _run_script(self.backend, authorize)
+            if data.get("signedIn") is True:
+                break
+            if monotonic() >= deadline:
+                raise LoginFailed("Login did not complete within five minutes")
+            sleep(POLL_SECONDS)
+        _log.bind(
+            event="phase_finished",
+            phase="scripted_check",
+            backend=self.backend,
+        ).debug("signed in to Talenta")
+        try:
+            profile = _extract_profile(data.get("settings"))
+        except LoginFailed:
+            profile = None
+        urls = data.get("urls")
+        for url in urls if isinstance(urls, list) else []:
+            if isinstance(url, str):
+                sink.note(url)
+        return profile, self._exchange(sink, verifier)