hyperagents 1.2.3rc5.post3__py3-none-any.whl

hyperclaw/teamsetup/item.py

@@ -0,0 +1,391 @@
+"""The team 1Password item: a compact, versioned format and its parser.
+
+One line of text, pasted at a hidden prompt::
+
+    HCT1.<payload>.<check>
+
+- ``HCT1``: format version 1. A newer version is refused with "upgrade first".
+- ``payload``: base64url (no padding) of the zlib-compressed JSON object::
+
+      {"model_key": "<personal Claude Console workspace key>",
+       "hyper_key": "<Hyper access key, optional>",
+       "google_client_secret": "<team Google client secret, optional>",
+       "profile": {"profile": {...}, "signature": "<b64 Ed25519>"}}
+
+- ``check``: the first 8 hex characters of sha256(payload), so a paste that
+  lost characters is caught before anything is read.
+
+The **team profile** is the non-secret policy for the install, signed by Hyper
+with the same Ed25519 keys as qualification records (the key ships in
+``hyperclaw/qualification_keys``). A profile that doesn't verify is refused,
+so nobody can widen their allowed models by editing an item::
+
+    {"type": "hyperclaw-team-profile", "schema": 1, "name": "hyper-team",
+     "install_mode": "hyper",
+     "allowed_models": ["anthropic/claude-sonnet-5-5", "anthropic/claude-opus-5-5", "hyperspeed/hospitality"],
+     "default_model": "anthropic/claude-sonnet-5-5",
+     "model_names": {"anthropic/claude-sonnet-5-5": "Claude Sonnet 5.5", "anthropic/claude-opus-5-5": "Claude Opus 5.5"},
+     "hyper_issued_keys": ["anthropic"],
+     "telegram": true,
+     "google": {"client_id": "<id>.apps.googleusercontent.com"},
+     "slack": {"app_id": "A0C8HG64MM3", "client_id": "<id>", "redirect_port": 8766,
+               "redirect_path": "/slack/callback"},
+     "slack_team_id": "T07GE79LBBJ",
+     "gitlab": {"url": "https://gitlab.com"},
+     "restricted_clients": [{"name": "...", "aliases": [...], "domains": [...],
+                             "projects": [...]}],
+     "restricted_clients_required": true,
+     "google_calendar_write": false,
+     "issued_at": "...", "key_id": "hyper-..."}
+
+``slack_team_id`` is the one Slack workspace a sign-in may belong to (Hyper
+Nimbus: ``T07GE79LBBJ``); ``slack_enterprise_id`` is set only for an
+Enterprise Grid org. There is no default: a profile without
+``slack_team_id`` still verifies, but Slack sign-in is refused on it
+(hyperclaw.teamsetup.slack_oauth).
+
+``restricted_clients`` / ``restricted_clients_required`` feed the
+restricted-client guard (hyperclaw.client_guard); a Hyper-deployed profile
+must set ``restricted_clients_required`` to true. ``google_calendar_write``
+adds Calendar write to the Google sign-in (hyperclaw.google_workspace). The
+Google client is ``google.client_id`` here plus ``google_client_secret`` in the
+item; onboarding writes them as the install's Desktop client file.
+
+Errors never contain any part of the pasted text.
+
+Maintainers (key from the macOS keychain, never printed)::
+
+    python -m hyperclaw.teamsetup.item sign-profile profile.json --out team-profile.signed.json
+    python -m hyperclaw.teamsetup.item make --profile team-profile.signed.json --out item.txt
+"""
+from __future__ import annotations
+
+import argparse
+import base64
+import datetime as _dt
+import hashlib
+import json
+import os
+import re
+import sys
+import zlib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+PREFIX = "HCT"
+VERSION = 1
+PROFILE_TYPE = "hyperclaw-team-profile"
+PROFILE_SCHEMA = 1
+INSTALL_MODES = ("hyper", "standard")
+DEFAULT_SLACK_PORT = 8766
+DEFAULT_SLACK_PATH = "/slack/callback"
+# Exactly the user scopes of the installed Slack app A0C8HG64MM3 (Wil, 13 Oct):
+# read mentions, DMs and channels, and post on tap (chat:write; every post still
+# waits for the owner's Send in the approval queue). Nothing else is requested
+# or accepted.
+SLACK_USER_SCOPES = ("channels:history", "channels:read", "chat:write", "groups:history",
+                     "groups:read", "im:history", "im:read", "mpim:history", "mpim:read",
+                     "search:read", "users:read")
+_SLACK_TEAM = re.compile(r"^T[A-Z0-9]{2,20}$")
+_SLACK_ENTERPRISE = re.compile(r"^E[A-Z0-9]{2,20}$")
+_ENTRY = re.compile(r"^[a-z0-9_]{1,40}/(\*|[A-Za-z0-9._:-][A-Za-z0-9._:/-]{0,127})$")
+_ITEM = re.compile(r"^HCT(\d{1,3})\.([A-Za-z0-9_-]{16,})\.([0-9a-f]{8})$")
+_PRINTABLE = re.compile(r"^[\x21-\x7e]{8,512}$")
+
+
+class ItemError(Exception):
+    """A refused item. ``code`` names the reason; the text is fixed and never
+    holds any of the pasted value."""
+
+    def __init__(self, code: str):
+        self.code = code
+        super().__init__(TEXT[code])
+
+    @property
+    def text(self) -> str:
+        return TEXT[self.code]
+
+
+TEXT = {
+    "empty": "Nothing was pasted.",
+    "shape": ("That isn't a HyperAgents team item. In 1Password, copy the whole item text "
+              "(it starts with HCT1.) and paste it again."),
+    "truncated": ("The pasted item is incomplete or changed (its check didn't match). Copy it "
+                  "from 1Password again and paste the whole line."),
+    "newer": ("This item is for a newer HyperAgents. Run 'hyperclaw upgrade' first, then "
+              "onboard again."),
+    "payload": "The item's contents couldn't be read. Ask Vaughn for a new 1Password item.",
+    "model_key": ("The item has no usable model key. Ask Vaughn for a new 1Password item."),
+    "runpod": ("The item holds a key that can't be used here. Nothing was saved. Tell Vaughn."),
+    "unsigned": ("The team profile in this item isn't signed by Hyper, so nothing was saved. "
+                 "Ask Vaughn for a new 1Password item."),
+    "profile": ("The team profile in this item is incomplete. Nothing was saved. Ask Vaughn "
+                "for a new 1Password item."),
+}
+
+
+@dataclass
+class TeamItem:
+    model_key: str
+    profile: dict                                    # verified, non-secret
+    envelope: dict                                   # signed profile, as issued
+    hyper_key: str = ""
+    google_client_secret: str = ""
+    extras: dict = field(default_factory=dict)
+
+    def __repr__(self) -> str:                       # never show a secret
+        return f"TeamItem(profile={self.profile.get('name', '')!r}, secrets=hidden)"
+
+    __str__ = __repr__
+
+
+def _b64d(s: str) -> bytes:
+    return base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))
+
+
+def _b64e(b: bytes) -> str:
+    return base64.urlsafe_b64encode(b).decode("ascii").rstrip("=")
+
+
+def checksum(payload_b64: str) -> str:
+    return hashlib.sha256(payload_b64.encode("ascii")).hexdigest()[:8]
+
+
+def _secret(v) -> str:
+    v = v.strip() if isinstance(v, str) else ""
+    return v if _PRINTABLE.match(v) else ""
+
+
+# ── profile ───────────────────────────────────────────────────────────────
+
+def validate_profile(p: dict) -> dict:
+    """The profile's fields, checked and normalized. Raises ItemError('profile')."""
+    if not isinstance(p, dict) or p.get("type") != PROFILE_TYPE \
+            or p.get("schema") != PROFILE_SCHEMA:
+        raise ItemError("profile")
+    mode = p.get("install_mode")
+    allowed = p.get("allowed_models")
+    if mode not in INSTALL_MODES or not isinstance(allowed, list) or not allowed \
+            or not all(isinstance(e, str) and _ENTRY.match(e) for e in allowed):
+        raise ItemError("profile")
+    default = p.get("default_model") or allowed[0]
+    if default not in allowed:
+        raise ItemError("profile")
+    google = p.get("google") or {}
+    slack = p.get("slack") or {}
+    if not isinstance(google, dict) or not isinstance(slack, dict):
+        raise ItemError("profile")
+    scopes = slack.get("user_scopes") or list(SLACK_USER_SCOPES)
+    if not isinstance(scopes, list) or \
+            sorted({str(s).strip() for s in scopes}) != sorted(SLACK_USER_SCOPES):
+        raise ItemError("profile")           # exactly the app's scope set, nothing else
+    port = slack.get("redirect_port", DEFAULT_SLACK_PORT)
+    if not isinstance(port, int) or not 1024 <= port <= 65535:
+        raise ItemError("profile")
+    path = str(slack.get("redirect_path") or DEFAULT_SLACK_PATH)
+    if not path.startswith("/"):
+        raise ItemError("profile")
+    team_id = p.get("slack_team_id") or ""
+    enterprise_id = p.get("slack_enterprise_id") or ""
+    if not isinstance(team_id, str) or (team_id and not _SLACK_TEAM.match(team_id)):
+        raise ItemError("profile")
+    if not isinstance(enterprise_id, str) or \
+            (enterprise_id and not _SLACK_ENTERPRISE.match(enterprise_id)):
+        raise ItemError("profile")
+    restricted = p.get("restricted_clients") or []
+    if not isinstance(restricted, list) or not all(_client_entry_ok(c) for c in restricted):
+        raise ItemError("profile")
+    required = p.get("restricted_clients_required", True)
+    if not isinstance(required, bool) or (mode == "hyper" and required is not True):
+        raise ItemError("profile")       # team and client installs always require the list
+    cal_write = p.get("google_calendar_write", False)
+    if not isinstance(cal_write, bool):
+        raise ItemError("profile")
+    names = p.get("model_names") or {}
+    out = {
+        "type": PROFILE_TYPE, "schema": PROFILE_SCHEMA,
+        "name": str(p.get("name") or "hyper-team")[:60],
+        "install_mode": mode,
+        "allowed_models": list(dict.fromkeys(allowed)),
+        "default_model": default,
+        "model_names": {k: str(v)[:60] for k, v in names.items()
+                        if isinstance(k, str) and _ENTRY.match(k) and isinstance(v, str)},
+        "hyper_issued_keys": sorted({x for x in (p.get("hyper_issued_keys") or [])
+                                     if isinstance(x, str) and re.match(r"^[a-z0-9_]{1,40}$", x)}),
+        "telegram": p.get("telegram") is True,
+        "google": {"client_id": str(google.get("client_id") or "")},
+        "slack": {"app_id": str(slack.get("app_id") or ""),
+                  "client_id": str(slack.get("client_id") or ""),
+                  "redirect_port": port, "redirect_path": path,
+                  "user_scopes": sorted({str(s).strip() for s in scopes if str(s).strip()}),
+                  # the only workspace (and Grid org) a Slack sign-in may belong to
+                  "team_id": team_id, "enterprise_id": enterprise_id},
+        "slack_team_id": team_id,
+        "slack_enterprise_id": enterprise_id,
+        "gitlab": {"url": str((p.get("gitlab") or {}).get("url") or "https://gitlab.com")},
+        "restricted_clients": [_client_entry(c) for c in restricted],
+        "restricted_clients_required": required,
+        "google_calendar_write": cal_write,
+        "issued_at": str(p.get("issued_at") or ""),
+        "key_id": str(p.get("key_id") or ""),
+    }
+    if out["gitlab"]["url"] and not out["gitlab"]["url"].startswith("https://"):
+        raise ItemError("profile")
+    return out
+
+
+def _client_entry_ok(c) -> bool:
+    """A restricted-client entry (hyperclaw.client_guard): a name, plus
+    optional lists of aliases, domains and projects (strings)."""
+    if not isinstance(c, dict) or not isinstance(c.get("name"), str) or not c["name"].strip():
+        return False
+    return all(isinstance(c.get(k, []), list) and all(isinstance(x, str) for x in c.get(k, []))
+               for k in ("aliases", "domains", "projects"))
+
+
+def _client_entry(c: dict) -> dict:
+    return {"name": c["name"].strip(), **{k: list(c.get(k, [])) for k in
+                                          ("aliases", "domains", "projects") if c.get(k)}}
+
+
+def verify_profile(envelope) -> dict:
+    """The verified, validated profile, or ItemError('unsigned'/'profile')."""
+    from cryptography.exceptions import InvalidSignature
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+    from hyperclaw import qualification as q
+    if not isinstance(envelope, dict) or not isinstance(envelope.get("profile"), dict):
+        raise ItemError("unsigned")
+    prof, sig = envelope["profile"], envelope.get("signature")
+    if not isinstance(sig, str) or not sig:
+        raise ItemError("unsigned")
+    raw = q.trusted_keys().get(prof.get("key_id"))
+    if raw is None:
+        raise ItemError("unsigned")
+    try:
+        Ed25519PublicKey.from_public_bytes(raw).verify(base64.b64decode(sig, validate=True),
+                                                      q.canonical(prof))
+    except (InvalidSignature, ValueError, TypeError):
+        raise ItemError("unsigned")
+    return validate_profile(prof)
+
+
+def sign_profile(profile: dict, private_raw: bytes) -> dict:
+    """Maintainers: the signed envelope for a profile."""
+    from hyperclaw import qualification as q
+    prof = dict(profile)
+    prof.setdefault("type", PROFILE_TYPE)
+    prof.setdefault("schema", PROFILE_SCHEMA)
+    prof.setdefault("issued_at", _dt.datetime.now(_dt.timezone.utc).replace(microsecond=0)
+                    .isoformat().replace("+00:00", "Z"))
+    prof["key_id"] = q.key_id_for(q._public_raw(private_raw))
+    validate_profile(prof)
+    sig = q._private_key(private_raw).sign(q.canonical(prof))
+    return {"profile": prof, "signature": base64.b64encode(sig).decode("ascii")}
+
+
+# ── the item ──────────────────────────────────────────────────────────────
+
+def encode(payload: dict, version: int = VERSION) -> str:
+    raw = json.dumps(payload, separators=(",", ":"), sort_keys=True).encode("utf-8")
+    body = _b64e(zlib.compress(raw, 9))
+    return f"{PREFIX}{version}.{body}.{checksum(body)}"
+
+
+def parse(text: str) -> TeamItem:
+    """Parse and verify a pasted item. Raises ItemError; never echoes input."""
+    raw = "".join((text or "").split())         # 1Password may wrap long lines
+    if not raw:
+        raise ItemError("empty")
+    m = _ITEM.match(raw)
+    if not m:
+        raise ItemError("shape")
+    ver, body, check = int(m.group(1)), m.group(2), m.group(3)
+    if ver > VERSION:
+        raise ItemError("newer")
+    if ver < 1:
+        raise ItemError("shape")
+    if checksum(body) != check:
+        raise ItemError("truncated")
+    try:
+        d = zlib.decompressobj()
+        raw = d.decompress(_b64d(body), 1 << 16)       # an item is a few KB at most
+        if d.unconsumed_tail:
+            raise ValueError("too large")
+        data = json.loads(raw.decode("utf-8"))
+    except Exception:
+        raise ItemError("payload") from None
+    if not isinstance(data, dict):
+        raise ItemError("payload")
+    from hyperclaw.model_policy import check_key
+    secrets = {k: data.get(k) for k in ("model_key", "hyper_key", "google_client_secret")}
+    if any(isinstance(v, str) and check_key(v) for v in secrets.values()):
+        raise ItemError("runpod")
+    model_key = _secret(secrets["model_key"])
+    if not model_key.startswith("sk-ant-") or len(model_key) < 24:
+        raise ItemError("model_key")
+    profile = verify_profile(data.get("profile"))
+    return TeamItem(model_key=model_key, profile=profile, envelope=data["profile"],
+                    hyper_key=_secret(secrets["hyper_key"]),
+                    google_client_secret=_secret(secrets["google_client_secret"]))
+
+
+# ── maintainer command ────────────────────────────────────────────────────
+
+def _write_private(path: Path, text: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd = os.open(str(path), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w", encoding="utf-8") as f:
+        f.write(text)
+    os.chmod(path, 0o600)
+
+
+def main(argv=None, *, private_key_loader=None, ask=None) -> int:
+    import getpass
+    ap = argparse.ArgumentParser(prog="python -m hyperclaw.teamsetup.item",
+                                 description="Maintainers: sign a team profile and make "
+                                             "per-person 1Password items. Never prints a secret.")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    s = sub.add_parser("sign-profile")
+    s.add_argument("profile", type=Path)
+    s.add_argument("--out", type=Path, required=True)
+    mk = sub.add_parser("make")
+    mk.add_argument("--profile", type=Path, required=True, help="signed profile (sign-profile)")
+    mk.add_argument("--out", type=Path, required=True, help="item file to create (0600)")
+    a = ap.parse_args(argv)
+    if a.cmd == "sign-profile":
+        if private_key_loader is None:
+            from hyperclaw.qualification import keychain_private_key as private_key_loader
+        try:
+            env = sign_profile(json.loads(a.profile.read_text(encoding="utf-8")),
+                               private_key_loader())
+            verify_profile(env)
+        except ItemError as e:
+            print(f"refused: {e.text}", file=sys.stderr)
+            return 2
+        _write_private(a.out, json.dumps(env, indent=2, sort_keys=True) + "\n")
+        print(f"signed team profile -> {a.out} (key {env['profile']['key_id']})")
+        return 0
+    ask = ask or (lambda label: getpass.getpass(f"{label} (hidden): "))
+    env = json.loads(a.profile.read_text(encoding="utf-8"))
+    payload = {"profile": env, "model_key": ask("Personal Claude Console workspace key")}
+    for k, label in (("hyper_key", "Hyper access key (Enter for none)"),
+                     ("google_client_secret", "Team Google client secret (Enter for none)")):
+        v = ask(label).strip()
+        if v:
+            payload[k] = v
+    item = encode(payload)
+    try:
+        parse(item)
+    except ItemError as e:
+        print(f"refused: {e.text}", file=sys.stderr)
+        return 2
+    _write_private(a.out, item + "\n")
+    print(f"item written to {a.out} (0600). Put its text in the person's 1Password item, "
+          f"then delete the file.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

hyperclaw/teamsetup/oauth_loopback.py

@@ -0,0 +1,84 @@
+"""A one-shot loopback listener for an OAuth redirect (Slack sign-in).
+
+It listens on a fixed local port (the one registered with the app, e.g.
+8766), on 127.0.0.1 and, when available, ::1, so ``http://localhost:<port>``
+works whichever address the browser picks. Nothing is logged: the query holds
+the authorization code.
+"""
+from __future__ import annotations
+
+import socket
+import threading
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from urllib.parse import parse_qs, urlsplit
+
+DONE_PAGE = (b"<!doctype html><meta charset=utf-8><title>HyperAgents</title>"
+             b"<p>HyperAgents has your answer. You can close this tab and go back to the "
+             b"terminal.</p>")
+
+
+class PortBusy(Exception):
+    pass
+
+
+class _V6Server(HTTPServer):
+    address_family = socket.AF_INET6
+
+
+class Catcher:
+    def __init__(self, port: int, path: str = "/"):
+        self.result: dict = {}
+        self.event = threading.Event()
+        self.path = path
+        outer = self
+
+        class H(BaseHTTPRequestHandler):
+            def log_message(self, *a):           # never log the query (it holds the code)
+                pass
+
+            def do_GET(self):
+                u = urlsplit(self.path)
+                q = {k: v[0] for k, v in parse_qs(u.query).items()}
+                if u.path == outer.path and ("code" in q or "error" in q) \
+                        and not outer.event.is_set():
+                    outer.result = q
+                    outer.event.set()
+                self.send_response(200)
+                self.send_header("Content-Type", "text/html; charset=utf-8")
+                self.send_header("Content-Length", str(len(DONE_PAGE)))
+                self.end_headers()
+                self.wfile.write(DONE_PAGE)
+
+        self.servers = []
+        try:
+            self.servers.append(HTTPServer(("127.0.0.1", port), H))
+        except OSError:
+            raise PortBusy(port) from None
+        try:
+            self.servers.append(_V6Server(("::1", port), H))
+        except OSError:
+            pass                                  # no IPv6 loopback: 127.0.0.1 is enough
+        self.port = self.servers[0].server_address[1]
+        self.threads = [threading.Thread(target=self._serve, args=(s,), daemon=True)
+                        for s in self.servers]
+
+    def _serve(self, srv):
+        while not self.event.is_set():
+            srv.handle_request()
+
+    def start(self):
+        for s in self.servers:
+            s.timeout = 0.3
+        for t in self.threads:
+            t.start()
+
+    def wait(self, timeout: float) -> bool:
+        return self.event.wait(timeout)
+
+    def close(self):
+        self.event.set()
+        for s in self.servers:
+            try:
+                s.server_close()
+            except Exception:
+                pass