hyperagents 1.2.3rc5.post3__py3-none-any.whl

hyperclaw/teamsetup/slack_oauth.py

@@ -0,0 +1,442 @@
+"""Slack sign-in for a team install: OAuth v2 with PKCE, user token: reads, and posts only on the owner's Send.
+
+- The Slack app (``app_id``, ``client_id``) comes from the Hyper-signed team
+  profile; no client secret is used (PKCE, S256).
+- The redirect is ``http://localhost:<port><path>`` (team profile; port 8766
+  by default), caught by a one-shot loopback listener. The person signs in in
+  their own browser.
+- Exactly the app's user scopes are requested (``SLACK_USER_SCOPES``: read
+  mentions, DMs and channels, plus ``chat:write`` to post on tap; every post
+  still waits for the owner's Send). A grant that differs in any way is
+  refused and nothing is stored.
+- The token bundle (access token, refresh token, expiries) is stored in the
+  OS secret store (hyperclaw.teamsetup.secrets, name ``slack_user_token``).
+- **Refresh** (the app: PKCE on, token rotation off; the main service checks
+  hourly, docs/TEAM-ONBOARDING.md):
+  - a grant with no ``expires_in`` and no refresh token is a long-lived user
+    token: nothing to refresh; a new sign-in is needed only if it is revoked;
+  - a grant with a refresh token: the access token is refreshed 10 minutes
+    before it expires. Slack's PKCE refresh tokens expire 30 days after they
+    are issued. A refresh that returns a new refresh token restarts the 30
+    days; one that doesn't leaves the original date. Three days before that
+    date the owner is told once on Telegram (``SIGN_IN_SOON``); a refused
+    refresh is told once (``SIGN_IN_AGAIN``).
+- A connection is proven with one authenticated call, ``auth.test``.
+- **One workspace only** (fail-closed). The signed team profile names the
+  Slack workspace (``slack_team_id``; and ``slack_enterprise_id`` only for an
+  Enterprise Grid org). After the OAuth exchange, on every refresh and on
+  every connection check, the token's team id (and its enterprise id, when
+  Slack reports one) must match exactly. On a mismatch the token is
+  discarded (revoked with Slack, best effort, and nothing is stored or the
+  stored bundle is removed) and the person is told plainly
+  (``TEXT["wrong_workspace"]``). A profile with no ``slack_team_id`` refuses
+  Slack sign-in, and stored tokens are not handed out, with the fix shown.
+
+Nothing here prints, logs or raises with a token, a code or a verifier.
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import logging
+import os
+import secrets as _secrets
+import time
+from dataclasses import dataclass
+from typing import Callable, Optional
+from urllib.parse import urlencode, urlsplit
+
+import httpx
+
+from hyperclaw.teamsetup import secrets
+from hyperclaw.teamsetup.item import SLACK_USER_SCOPES
+from hyperclaw.teamsetup.oauth_loopback import Catcher, PortBusy
+
+log = logging.getLogger("hyperclaw.teamsetup.slack")
+
+AUTH_URL = "https://slack.com/oauth/v2/authorize"
+API = "https://slack.com/api"
+API_ENV = "HYPERCLAW_TEAM_SLACK_API"     # tests only: must be loopback
+SECRET = "slack_user_token"
+TIMEOUT = 20.0
+CONSENT_WAIT = 300.0
+REFRESH_LIMIT = 30 * 86400             # a PKCE refresh token's life from when it is issued
+WARN_BEFORE = 3 * 86400                # tell the owner this long before it runs out
+EARLY = 600                            # refresh an access token 10 min before expiry
+
+SIGN_IN_AGAIN = ("Slack needs you to sign in again (your Slack sign-in has expired or was "
+                 "removed). Run: hyperclaw onboard --team --step slack")
+SIGN_IN_SOON = ("Slack will sign HyperAgents out on {date}. To stay connected, sign in again "
+                "before then: hyperclaw onboard --team --step slack")
+
+TEXT = {
+    "no_app": "the team profile has no Slack app, so Slack sign-in isn't set up for you",
+    "port_busy": ("another program on this computer is using port {port}, which Slack sign-in "
+                  "needs. Close it and try again"),
+    "denied": "Slack sign-in was cancelled or didn't finish",
+    "timeout": "Slack sign-in didn't finish within 5 minutes",
+    "scopes": ("Slack granted different access than HyperAgents asks for, so nothing was "
+               "saved"),
+    "rejected": "Slack didn't accept the sign-in",
+    "unreachable": "Slack couldn't be reached",
+    "expired": "your Slack sign-in has expired or was removed",
+    "not_connected": "Slack isn't connected",
+    "wrong_workspace": ("This Slack sign-in is for a different workspace than the "
+                        "workspace your team profile names, so it was discarded and nothing was "
+                        "saved. Sign in again and choose your team's workspace"),
+    "no_workspace": ("your team profile doesn't name the Slack workspace (slack_team_id), so "
+                     "Slack sign-in is refused"),
+}
+
+RERUN = "hyperclaw onboard --team --step slack"
+FIX = {
+    "no_workspace": ("ask Vaughn for a new 1Password item whose signed team profile includes "
+                     "slack_team_id, then run: hyperclaw onboard --team --step item"),
+}
+WRONG_WORKSPACE = TEXT["wrong_workspace"] + ": " + RERUN
+
+
+class SlackAuthError(Exception):
+    def __init__(self, code: str, **fmt):
+        self.code = code
+        super().__init__(TEXT[code].format(**fmt))
+
+    @property
+    def text(self) -> str:
+        return str(self)
+
+    @property
+    def fix(self) -> str:
+        return FIX.get(self.code, RERUN)
+
+
+def api_base() -> str:
+    override = os.environ.get(API_ENV, "").strip()
+    if override and (urlsplit(override).hostname or "") in ("127.0.0.1", "localhost", "::1"):
+        return override.rstrip("/")
+    return API
+
+
+def _pkce() -> tuple:
+    verifier = base64.urlsafe_b64encode(_secrets.token_bytes(48)).rstrip(b"=").decode()
+    challenge = base64.urlsafe_b64encode(
+        hashlib.sha256(verifier.encode()).digest()).rstrip(b"=").decode()
+    return verifier, challenge
+
+
+def redirect_uri(cfg: dict) -> str:
+    return f"http://localhost:{int(cfg.get('redirect_port') or 8766)}" \
+           f"{cfg.get('redirect_path') or '/slack/callback'}"
+
+
+def authorize_url(cfg: dict, state: str, challenge: str) -> str:
+    return AUTH_URL + "?" + urlencode({
+        "client_id": cfg["client_id"],
+        "user_scope": ",".join(SLACK_USER_SCOPES),
+        "redirect_uri": redirect_uri(cfg),
+        "state": state,
+        "code_challenge": challenge,
+        "code_challenge_method": "S256",
+    })
+
+
+# ── token bundle ──────────────────────────────────────────────────────────
+
+def load_bundle() -> dict:
+    raw = secrets.get(SECRET)
+    try:
+        data = json.loads(raw) if raw else {}
+    except ValueError:
+        data = {}
+    return data if isinstance(data, dict) else {}
+
+
+def save_bundle(b: dict) -> str:
+    return secrets.put(SECRET, json.dumps(b, separators=(",", ":")))
+
+
+def connected() -> bool:
+    return bool(load_bundle().get("access_token"))
+
+
+def _bundle_from(resp: dict, now: float, old: Optional[dict] = None) -> dict:
+    """The stored bundle from an oauth.v2.access answer (first grant or a
+    refresh; Slack nests user tokens under authed_user on the first grant)."""
+    u = resp.get("authed_user") if isinstance(resp.get("authed_user"), dict) else {}
+    src = u if u.get("access_token") else resp
+    old = old or {}
+    exp = src.get("expires_in")
+    team = resp.get("team") if isinstance(resp.get("team"), dict) else {}
+    ent = resp.get("enterprise") if isinstance(resp.get("enterprise"), dict) else {}
+    return {
+        "access_token": str(src.get("access_token") or ""),
+        "refresh_token": str(src.get("refresh_token") or old.get("refresh_token") or ""),
+        # a new refresh token restarts its 30 days; otherwise the old date stands
+        "refresh_issued_at": now if src.get("refresh_token") else
+        float(old.get("refresh_issued_at") or old.get("refreshed_at") or now),
+        "expires_at": (now + float(exp)) if exp else 0,
+        "refreshed_at": now,
+        "scope": str(src.get("scope") or old.get("scope") or ""),
+        "team_id": str(team.get("id") or old.get("team_id") or ""),
+        "team_name": str(team.get("name") or old.get("team_name") or ""),
+        "enterprise_id": str(ent.get("id") or old.get("enterprise_id") or ""),
+        "user_id": str(u.get("id") or src.get("user_id") or old.get("user_id") or ""),
+    }
+
+
+def _post(path: str, data: dict, http: Optional[httpx.Client], headers=None) -> dict:
+    c = http or httpx.Client(timeout=TIMEOUT, follow_redirects=False)
+    try:
+        r = c.post(f"{api_base()}/{path}", data=data, headers=headers or {})
+    except httpx.HTTPError as e:
+        log.warning("slack %s: network error (%s)", path, type(e).__name__)
+        raise SlackAuthError("unreachable") from None
+    finally:
+        if http is None:
+            c.close()
+    if r.status_code >= 500 or r.status_code == 429:
+        raise SlackAuthError("unreachable")
+    try:
+        body = r.json()
+    except ValueError:
+        body = {}
+    return body if isinstance(body, dict) else {}
+
+
+_EXPIRED = {"invalid_refresh_token", "invalid_grant", "token_revoked", "token_expired",
+            "invalid_auth", "not_authed", "account_inactive"}
+
+
+def _check_scopes(scope: str) -> None:
+    got = sorted({s.strip() for s in (scope or "").split(",") if s.strip()})
+    if got != sorted(SLACK_USER_SCOPES):
+        raise SlackAuthError("scopes")
+
+
+# ── the one workspace ─────────────────────────────────────────────────────
+
+def expected_workspace(cfg: dict) -> tuple:
+    """(team_id, enterprise_id) the profile allows. Raises
+    SlackAuthError('no_workspace') when the profile names no workspace."""
+    team = str(cfg.get("team_id") or "").strip()
+    if not team:
+        raise SlackAuthError("no_workspace")
+    return team, str(cfg.get("enterprise_id") or "").strip()
+
+
+def workspace_matches(cfg: dict, team_id: str, enterprise_id: str = "") -> bool:
+    """Exact match on the team id; an enterprise id, when either side has
+    one, must match too (a Grid org the profile doesn't name is refused)."""
+    want_team, want_ent = expected_workspace(cfg)
+    return bool(team_id) and team_id == want_team and (enterprise_id or "") == want_ent
+
+
+def _revoke(token: str, http: Optional[httpx.Client]) -> None:
+    """Best effort: tell Slack to drop a token we won't keep."""
+    if not token:
+        return
+    try:
+        _post("auth.revoke", {}, http, headers={"Authorization": f"Bearer {token}"})
+    except SlackAuthError:
+        pass
+
+
+def _discard(token: str, http: Optional[httpx.Client], *, stored: bool) -> None:
+    _revoke(token, http)
+    if stored and not secrets.remove(SECRET):
+        save_bundle({})                     # the store wouldn't delete: overwrite it empty
+    log.warning("slack: sign-in for a different workspace discarded")
+
+
+def _auth_test(token: str, http: Optional[httpx.Client]) -> dict:
+    body = _post("auth.test", {}, http, headers={"Authorization": f"Bearer {token}"})
+    if not body.get("ok"):
+        if str(body.get("error") or "") in _EXPIRED:
+            raise SlackAuthError("expired")
+        raise SlackAuthError("rejected")
+    return body
+
+
+# ── sign-in ───────────────────────────────────────────────────────────────
+
+def sign_in(cfg: dict, *, show: Callable[[str], None] = print,
+            open_browser: Optional[Callable[[str], object]] = None,
+            http: Optional[httpx.Client] = None, wait: float = CONSENT_WAIT,
+            on_listening: Optional[Callable[[str, str], None]] = None,
+            now: Callable[[], float] = time.time) -> dict:
+    """Run the PKCE sign-in and store the token bundle. Returns the
+    non-secret {"team_name", "user_id", "scope", "store"}."""
+    if not cfg.get("client_id"):
+        raise SlackAuthError("no_app")
+    expected_workspace(cfg)                 # no named workspace: refuse before any sign-in
+    port = int(cfg.get("redirect_port") or 8766)
+    verifier, challenge = _pkce()
+    state = _secrets.token_urlsafe(24)
+    try:
+        catcher = Catcher(port, cfg.get("redirect_path") or "/slack/callback")
+    except PortBusy:
+        raise SlackAuthError("port_busy", port=port) from None
+    catcher.start()
+    try:
+        url = authorize_url(cfg, state, challenge)
+        show("Your browser will open Slack. Sign in to the Hyper workspace and choose Allow. "
+             "HyperAgents asks to read your messages and channels, and to post only when "
+             "you press Send. If the browser didn't open, copy this address "
+             "into it:\n\n" + url + "\n")
+        if open_browser:
+            try:
+                open_browser(url)
+            except Exception:
+                pass
+        if on_listening:
+            on_listening(redirect_uri(cfg), state)
+        if not catcher.wait(wait):
+            raise SlackAuthError("timeout")
+        res = catcher.result
+    finally:
+        catcher.close()
+    if res.get("state") != state or res.get("error") or not res.get("code"):
+        raise SlackAuthError("denied")
+    body = _post("oauth.v2.access", {
+        "client_id": cfg["client_id"], "code": res["code"], "code_verifier": verifier,
+        "redirect_uri": redirect_uri(cfg), "grant_type": "authorization_code"}, http)
+    if not body.get("ok"):
+        raise SlackAuthError("rejected")
+    bundle = _bundle_from(body, now())
+    if not bundle["access_token"]:
+        raise SlackAuthError("rejected")
+    if not workspace_matches(cfg, bundle["team_id"], bundle["enterprise_id"]):
+        _discard(bundle["access_token"], http, stored=False)
+        raise SlackAuthError("wrong_workspace")
+    _check_scopes(bundle["scope"])
+    where = save_bundle(bundle)
+    return {"team_name": bundle["team_name"], "user_id": bundle["user_id"],
+            "scope": bundle["scope"], "store": where}
+
+
+# ── refresh ───────────────────────────────────────────────────────────────
+
+@dataclass
+class RefreshResult:
+    status: str            # "fresh" | "refreshed" | "sign_in_again" | "retry_later" |
+    #                        "not_connected" | "wrong_workspace" | "no_workspace"
+    message: str = ""
+
+
+def needs_refresh(b: dict, now: float) -> bool:
+    """Only an access token about to expire is refreshed (a long-lived token
+    without a refresh token never is)."""
+    if not b.get("refresh_token"):
+        return False
+    exp = float(b.get("expires_at") or 0)
+    return bool(exp) and exp - EARLY <= now
+
+
+def sign_in_by(b: dict) -> float:
+    """When a new sign-in is needed (the refresh token's 30 days), or 0 when
+    the token doesn't expire."""
+    if not b.get("refresh_token"):
+        return 0.0
+    return float(b.get("refresh_issued_at") or b.get("refreshed_at") or 0) + REFRESH_LIMIT
+
+
+def expiry_warning(b: dict, now: float) -> str:
+    """SIGN_IN_SOON when the sign-in runs out within WARN_BEFORE, else ''."""
+    by = sign_in_by(b)
+    if not by or by - now > WARN_BEFORE:
+        return ""
+    import datetime as _dt
+    date = _dt.datetime.fromtimestamp(by).strftime("%a %d %b")
+    return SIGN_IN_SOON.format(date=date) if by > now else SIGN_IN_AGAIN
+
+
+def refresh(cfg: dict, *, http: Optional[httpx.Client] = None, force: bool = False,
+            now: Callable[[], float] = time.time) -> RefreshResult:
+    b = load_bundle()
+    if not b.get("access_token"):
+        return RefreshResult("not_connected", TEXT["not_connected"])
+    try:
+        expected_workspace(cfg)
+    except SlackAuthError as e:
+        return RefreshResult("no_workspace", f"Slack is off: {e.text}. Fix: {e.fix}")
+    if b.get("team_id") and not workspace_matches(cfg, b["team_id"], b.get("enterprise_id", "")):
+        _discard(b["access_token"], http, stored=True)
+        return RefreshResult("wrong_workspace", WRONG_WORKSPACE)
+    t = now()
+    if not force and not needs_refresh(b, t):
+        return RefreshResult("fresh", expiry_warning(b, t))
+    if not b.get("refresh_token"):
+        return RefreshResult("fresh")
+    try:
+        body = _post("oauth.v2.access", {"client_id": cfg.get("client_id") or "",
+                                         "grant_type": "refresh_token",
+                                         "refresh_token": b["refresh_token"]}, http)
+    except SlackAuthError:
+        return RefreshResult("retry_later", expiry_warning(b, t))
+    if not body.get("ok"):
+        if str(body.get("error") or "") in _EXPIRED:
+            return RefreshResult("sign_in_again", SIGN_IN_AGAIN)
+        return RefreshResult("retry_later")
+    nb = _bundle_from(body, t, old=b)
+    if not nb["access_token"]:
+        return RefreshResult("retry_later")
+    team = body.get("team") if isinstance(body.get("team"), dict) else {}
+    ent = body.get("enterprise") if isinstance(body.get("enterprise"), dict) else {}
+    if team.get("id"):
+        got = (str(team["id"]), str(ent.get("id") or ""))
+    else:                                   # Slack didn't say: ask with the new token
+        try:
+            who = _auth_test(nb["access_token"], http)
+        except SlackAuthError:
+            return RefreshResult("retry_later")
+        got = (str(who.get("team_id") or ""), str(who.get("enterprise_id") or ""))
+    if not workspace_matches(cfg, *got):
+        _revoke(nb["access_token"], http)
+        _discard(b["access_token"], http, stored=True)
+        return RefreshResult("wrong_workspace", WRONG_WORKSPACE)
+    nb["team_id"], nb["enterprise_id"] = got
+    save_bundle(nb)
+    return RefreshResult("refreshed", expiry_warning(nb, t))
+
+
+def _current(cfg: dict, http: Optional[httpx.Client]) -> dict:
+    r = refresh(cfg, http=http)
+    if r.status in ("not_connected", "no_workspace", "wrong_workspace"):
+        raise SlackAuthError(r.status)
+    if r.status == "sign_in_again":
+        raise SlackAuthError("expired")
+    return load_bundle()
+
+
+def access_token(cfg: dict, *, http: Optional[httpx.Client] = None) -> str:
+    """A current user token for other Slack code (refreshed when due), only
+    for the profile's workspace. Raises SlackAuthError('expired' /
+    'not_connected' / 'no_workspace' / 'wrong_workspace')."""
+    b = _current(cfg, http)
+    if not b.get("team_id"):                # never confirmed: confirm before handing it out
+        _confirm(cfg, b, http)
+    return load_bundle().get("access_token", "")
+
+
+def _confirm(cfg: dict, b: dict, http: Optional[httpx.Client]) -> dict:
+    """auth.test with the stored token; the workspace must be the profile's.
+    A mismatch discards the stored token and raises 'wrong_workspace'."""
+    body = _auth_test(b["access_token"], http)
+    team, ent = str(body.get("team_id") or ""), str(body.get("enterprise_id") or "")
+    if not workspace_matches(cfg, team, ent):
+        _discard(b["access_token"], http, stored=True)
+        raise SlackAuthError("wrong_workspace")
+    if b.get("team_id") != team or b.get("enterprise_id", "") != ent:
+        save_bundle(dict(b, team_id=team, enterprise_id=ent))
+    return body
+
+
+# ── verify ────────────────────────────────────────────────────────────────
+
+def verify(cfg: dict, *, http: Optional[httpx.Client] = None) -> dict:
+    """One authenticated call (auth.test), which must answer for the
+    profile's workspace (else the token is discarded: 'wrong_workspace').
+    Returns {"team", "user_id"}."""
+    body = _confirm(cfg, _current(cfg, http), http)
+    return {"team": str(body.get("team") or ""), "user_id": str(body.get("user_id") or "")}

hyperclaw/teamsetup/tty.py

@@ -0,0 +1,62 @@
+"""Hidden input that takes a long paste.
+
+``getpass`` reads in the terminal's line mode, which on macOS cuts a line at
+1024 characters, shorter than some 1Password items. This reader turns echo
+and line mode off and reads characters itself until Enter, so nothing shows
+on screen and nothing is cut. Backspace works; Ctrl-C raises
+KeyboardInterrupt. Without a terminal it falls back to ``getpass``.
+"""
+from __future__ import annotations
+
+import getpass
+import os
+import sys
+
+MAX_CHARS = 16384
+
+
+def read_hidden(prompt: str) -> str:
+    try:
+        import termios
+        fd = sys.stdin.fileno()
+        if not os.isatty(fd):
+            raise OSError
+        old = termios.tcgetattr(fd)
+    except (ImportError, OSError, ValueError, AttributeError):
+        return getpass.getpass(prompt)
+    sys.stdout.write(prompt)
+    sys.stdout.flush()
+    new = termios.tcgetattr(fd)
+    new[3] &= ~(termios.ECHO | termios.ICANON)       # lflags: no echo, no line mode
+    new[6][termios.VMIN] = 1
+    new[6][termios.VTIME] = 0
+    chars = []
+    try:
+        termios.tcsetattr(fd, termios.TCSAFLUSH, new)
+        while True:
+            b = os.read(fd, 4096)
+            if not b:
+                break
+            done = False
+            for ch in b.decode("utf-8", errors="ignore"):
+                if ch in ("\r", "\n"):
+                    done = True
+                    break
+                if ch == "\x03":
+                    raise KeyboardInterrupt
+                if ch == "\x04" and not chars:
+                    done = True
+                    break
+                if ch in ("\x7f", "\x08"):
+                    if chars:
+                        chars.pop()
+                    continue
+                if len(chars) < MAX_CHARS:
+                    chars.append(ch)
+            if done:
+                break
+    finally:
+        termios.tcsetattr(fd, termios.TCSAFLUSH, old)
+        sys.stdout.write("\n")
+        sys.stdout.flush()
+    return "".join(chars)