@maudecode/talaria-web 1.19.0 → 1.20.0

package/sidecar/talaria_sidecar/methods/oauth.py

@@ -1,4 +1,5 @@
-"""``oauth.*``: the Agent's device-code sign-ins for Nous Portal, OpenAI Codex, xAI and MiniMax (TAL-398).
+"""``oauth.*``: the Agent's device-code sign-ins for Nous Portal, OpenAI Codex, xAI and MiniMax (TAL-398), and the
+browser sign-in of a plugin-declared OAuth client (``plugin:<key>:<id>``, TAL-1276, in ``plugin_oauth``).
 
 ``oauth.start`` asks the provider for a code and answers what the user has to see; a daemon thread then waits for the
 approval and saves the credential with the Agent's own auth-store helpers under the flow's profile home, the steps its
@@ -9,9 +10,12 @@ Flows live in this process only.
 
 from __future__ import annotations
 
+import contextlib
+import inspect
 import logging
 import os
 import secrets
+import ssl
 import threading
 import time
 from dataclasses import dataclass, field
@@ -22,6 +26,7 @@ from typing import Any, Callable
 from ..errors import InvalidParams, RpcError
 from ..home import profile_home_param, scoped_home
 from ..rpc import CallContext
+from . import plugin_oauth
 
 log = logging.getLogger("talaria_sidecar.oauth")
 
@@ -31,6 +36,8 @@ _CODEX_EXPIRES_IN = 15 * 60  # OpenAI's device-code lifetime, as the Agent dashb
 _ENDED_TTL = 10 * 60
 # A pending flow past its code's expiry by this much ends expired even if its provider call has not returned yet.
 _EXPIRY_GRACE = 60
+# How long a start waits for the flows it replaces to close their loopback listeners.
+_RELEASE_WAIT = 5.0
 
 _DENIED = "Sign-in was declined."
 _EXPIRED = "The sign-in code expired before it was approved."
@@ -55,6 +62,17 @@ class Flow:
     cancelled: threading.Event = field(default_factory=threading.Event)
     # Serialises the cancel check with the credential save: a cancel cannot land between them.
     lock: threading.Lock = field(default_factory=threading.Lock)
+    # The credential is saved but the sign-in has not finished (a guest sign-in still settles the account): a cancel or
+    # an expiry can no longer undo it, and the flow stays pending until its own ending.
+    committed: bool = False
+    # A browser sign-in also finishes from the redirect address the user pastes (``oauth.submit_redirect``).
+    submit: Callable[[str], None] | None = None
+    # Set once a browser sign-in's loopback listener is closed, so a replacing start can bind the same fixed port.
+    closed: threading.Event | None = None
+
+    @property
+    def stoppable(self) -> bool:
+        return self.status == "pending" and not self.committed
 
     def end(self, status: str, error: str | None = None) -> None:
         self.status, self.error, self.ended_at = status, error, time.time()
@@ -107,9 +125,24 @@ def _now_z() -> str:
 
 
 def _client(timeout: float, **kwargs: Any) -> Any:
+    """Every flow's HTTP client, verifying TLS as the Agent's own sign-in does: the OS trust store, and (v0.22.3+) a
+    certifi bundle an install-environment rotation deleted under this process, re-derived process-wide."""
     import httpx
 
-    return httpx.Client(timeout=httpx.Timeout(timeout), headers={"Accept": "application/json"}, **kwargs)
+    return httpx.Client(timeout=httpx.Timeout(timeout), headers={"Accept": "application/json"}, verify=_verify(), **kwargs)
+
+
+def _verify() -> Any:
+    try:
+        from agent.ssl_verify import resolve_httpx_verify
+    except ImportError:  # an Agent without it keeps httpx's default
+        return True
+    verify = resolve_httpx_verify()
+    # The resolver hands over the platform store alone when SSL_CERT_FILE/SSL_CERT_DIR is set; httpx's default trusted
+    # that bundle, so keep it, on top of the platform store the resolver installed (as ``platform_ssl_context`` does).
+    cafile, capath = os.environ.get("SSL_CERT_FILE", "").strip(), os.environ.get("SSL_CERT_DIR", "").strip()
+    cafile, capath = (cafile if os.path.isfile(cafile) else None), (capath if os.path.isdir(capath) else None)
+    return ssl.create_default_context(cafile=cafile, capath=capath) if cafile or capath else verify
 
 
 # ── providers: (begin, wait, save) over the Agent's own steps ──────────
@@ -124,8 +157,9 @@ def _nous_begin() -> tuple[dict, dict]:
     # v0.22.0 replaced ``guest_enabled`` with ``guest_allowed``; 0.21.x releases only have the former.
     guest_gate = getattr(anon_auth, "guest_allowed", None) or getattr(anon_auth, "guest_enabled")
     if guest_gate() and anon_auth.has_guest():
-        # The free tier's sign-in moves its connectors to the account (``anon_auth.run_sign_in``); a plain device-code
-        # sign-in here would orphan them.
+        # The native sign-in owns the guest's connector handoff for its installed protocol.
+        if hasattr(anon_auth, "run_sign_in"):
+            return _nous_sign_in(anon_auth)
         hint = getattr(anon_auth, "UPGRADE_HINT", None) or "Sign in from Hermes with `hermes auth upgrade`."
         raise RpcError(f"This profile uses the Nous free tier. {hint}", condition="oauth_unsupported")
     pconfig = PROVIDER_REGISTRY["nous"]
@@ -136,7 +170,63 @@ def _nous_begin() -> tuple[dict, dict]:
     return display, {"portal": portal, "client_id": pconfig.client_id, "scope": pconfig.scope, "device_code": str(data["device_code"])}
 
 
+def _nous_sign_in(anon_auth: Any) -> tuple[dict, dict]:
+    """Over a guest, the Agent's own sign-in (``anon_auth.run_sign_in``, as its dashboard runs it): it moves the guest's
+    connected apps to the account, then persists and settles the account itself. Its cancel check, persist guard and
+    home scope read the flow ``_nous_wait`` binds into the state; before that only ``start``'s first step runs, already
+    under the flow's home."""
+    state: dict = {}
+
+    def cancelled() -> bool:
+        flow = state.get("flow")
+        return flow is not None and flow.cancelled.is_set()
+
+    @contextlib.contextmanager
+    def persist_guard():
+        # As ``_run`` does for a plain save, the final cancel check and the save share the flow's lock; the flow ends
+        # approved only when the Agent has also settled the account, through ``_run``.
+        flow = state["flow"]
+        with flow.lock:
+            may_persist = flow.status == "pending"
+            yield may_persist
+            if may_persist:
+                flow.committed = True
+
+    def scope():
+        flow = state.get("flow")
+        return scoped_home(flow.home) if flow is not None else contextlib.nullcontext()
+
+    # Older Agents use promotion; v0.22.5 removed its option in favor of plain device login and native handoff.
+    options = {"cancel_wins_after_promotion": True} if "cancel_wins_after_promotion" in inspect.signature(anon_auth.run_sign_in).parameters else {}
+    sign_in = anon_auth.run_sign_in(cancelled=cancelled, persist_guard=persist_guard, scope=scope, **options)
+    first = next(sign_in)
+    if first.kind != "code":
+        sign_in.close()
+        raise RpcError(first.copy_terminal, condition="oauth_unsupported" if first.precondition else "oauth_failed")
+    state["sign_in"] = sign_in
+    return {"user_code": first.code, "verification_url": first.link, "expires_in": first.expires_in, "interval": first.interval}, state
+
+
+class _SignInEnded(Exception):
+    """A guest sign-in that ended without an account; ``code`` lets ``_ending`` classify a decline and an expiry."""
+
+    def __init__(self, ended: Any):
+        super().__init__(ended.copy)
+        self.code = {"declined": "access_denied", "timed_out": "expired_token"}.get(ended.kind, ended.kind)
+
+
 def _nous_wait(flow: Flow, state: dict) -> dict:
+    sign_in = state.get("sign_in")
+    if sign_in is not None:
+        state["flow"] = flow
+        try:
+            for ended in sign_in:  # the generator always ends on one terminal state
+                pass
+        finally:
+            sign_in.close()
+        if not ended.ok:
+            raise _SignInEnded(ended)
+        return {}
     from hermes_cli.auth import _poll_for_token
 
     with _client(15.0) as client:
@@ -145,6 +235,8 @@ def _nous_wait(flow: Flow, state: dict) -> dict:
 
 
 def _nous_save(flow: Flow, state: dict, token_data: dict) -> None:
+    if "sign_in" in state:  # the guest sign-in persisted and settled the account itself
+        return
     from hermes_cli import anon_auth
     from hermes_cli.auth import persist_nous_credentials, refresh_nous_oauth_from_state
 
@@ -213,8 +305,10 @@ def _codex_save(flow: Flow, state: dict, tokens: dict) -> None:
 def _xai_begin() -> tuple[dict, dict]:
     from hermes_cli.auth import _xai_oauth_discovery, _xai_oauth_request_device_code
 
-    discovery = _xai_oauth_discovery(20.0)
     with _client(20.0) as client:
+        # The Agent's discovery is a bare ``httpx.get``: building the client first gives it the platform store and a
+        # certifi re-derived after a rotation.
+        discovery = _xai_oauth_discovery(20.0)
         data = _xai_oauth_request_device_code(client)
     display = {"user_code": str(data["user_code"]), "verification_url": str(data.get("verification_uri_complete") or data["verification_uri"]),
                "expires_in": int(data["expires_in"]), "interval": int(data["interval"])}
@@ -323,9 +417,16 @@ def _run(flow: Flow, wait: Callable[[Flow, dict], dict], save: Callable[[Flow, d
         log.info("oauth: %s sign-in ended %s (flow=%s)", flow.provider, flow.status, flow.flow_id[:6])
 
 
+def _discard(state: dict) -> None:
+    """Releases a begun sign-in that is never published: a guest sign-in's generator holds its HTTP client."""
+    if "sign_in" in state:
+        state["sign_in"].close()
+    plugin_oauth.discard(state)
+
+
 def _cancel(flow: Flow) -> None:
     with flow.lock:
-        if flow.status == "pending":
+        if flow.stoppable:
             flow.cancelled.set()
             flow.end("cancelled")
 
@@ -357,7 +458,7 @@ def _pending(home: Path, provider: str) -> list[Flow]:
 
 
 def start(home: Path, provider: str, *, providers: dict[str, Provider] | None = None) -> dict:
-    steps = (providers or PROVIDERS).get(provider)
+    steps = (providers or PROVIDERS).get(provider) or plugin_oauth.steps(provider)
     if steps is None:
         raise InvalidParams(f"{provider} has no device-code sign-in")
     begin, wait, save = steps
@@ -369,6 +470,11 @@ def start(home: Path, provider: str, *, providers: dict[str, Provider] | None =
     # old code that lands while the provider answers can no longer save.
     for old in _pending(home, provider):
         _cancel(old)
+    # A cancelled browser sign-in closes its listener from its own thread; a fixed redirect port is free only after that.
+    with _FLOWS_LOCK:
+        listening = [f for f in _FLOWS.values() if f.provider == provider and f.closed is not None and not f.closed.is_set() and _same_home(f.home, home)]
+    for old in listening:
+        old.closed.wait(_RELEASE_WAIT)
     try:
         with scoped_home(home):
             display, state = begin()
@@ -379,11 +485,13 @@ def start(home: Path, provider: str, *, providers: dict[str, Provider] | None =
         raise RpcError(_first_line(exc), condition="oauth_failed") from exc
     if not str(display["verification_url"]).lower().startswith(("https://", "http://")):
         # The browser opens this link: anything but a web address is refused before a flow exists.
+        _discard(state)
         raise RpcError("The provider answered an invalid sign-in link.", condition="oauth_failed")
-    flow = Flow(secrets.token_urlsafe(16), provider, home, time.time() + int(display["expires_in"]), max(1, int(display["interval"])))
+    flow = Flow(secrets.token_urlsafe(16), provider, home, time.time() + int(display["expires_in"]), max(1, int(display["interval"])), submit=state.get("submit"), closed=state.get("closed"))
     with _FLOWS_LOCK:
         if _GENERATIONS.get(key) != generation:
             # A newer start for this home and provider began while this one waited on the provider: it owns the sign-in.
+            _discard(state)
             raise RpcError("A newer sign-in for this provider replaced this one.", condition="oauth_superseded")
         superseded = [f for f in _FLOWS.values() if f.provider == provider and f.status == "pending" and _same_home(f.home, home)]
         _FLOWS[flow.flow_id] = flow
@@ -403,10 +511,10 @@ def _flow(home: Path, flow_id: str) -> Flow:
 
 def poll(home: Path, flow_id: str) -> dict:
     flow = _flow(home, flow_id)
-    if flow.status == "pending" and time.time() > flow.expires_at + _EXPIRY_GRACE:
+    if flow.stoppable and time.time() > flow.expires_at + _EXPIRY_GRACE:
         # The provider call outlived its code: end it now, and a late approval can no longer save.
         with flow.lock:
-            if flow.status == "pending":
+            if flow.stoppable:
                 flow.cancelled.set()
                 flow.end("expired", _EXPIRED)
     return flow.view()
@@ -418,6 +526,18 @@ def cancel(home: Path, flow_id: str) -> dict:
     return flow.view()
 
 
+def submit_redirect(home: Path, flow_id: str, url: str) -> dict:
+    """Finish a browser sign-in with the address its redirect reached, when the browser runs on another machine."""
+    flow = _flow(home, flow_id)
+    if flow.submit is None:
+        raise InvalidParams("This sign-in takes no redirect address.")
+    with flow.lock:
+        if not flow.stoppable or time.time() >= flow.expires_at:
+            raise RpcError("This sign-in already ended.", condition="oauth_flow_ended")
+    flow.submit(url)
+    return flow.view()
+
+
 def _flow_id(params: dict) -> str:
     flow_id = str(params.get("flow_id") or "").strip()
     if not flow_id:
@@ -428,7 +548,8 @@ def _flow_id(params: dict) -> str:
 def register(reg) -> None:
     @reg.method("oauth.start")
     def start_(ctx: CallContext, params: dict) -> dict:
-        provider = str(params.get("provider") or "").strip().lower()
+        provider = str(params.get("provider") or "").strip()
+        provider = provider if provider.startswith(plugin_oauth.PREFIX) else provider.lower()
         if not provider:
             raise InvalidParams("provider is required")
         return start(profile_home_param(params), provider)
@@ -440,3 +561,10 @@ def register(reg) -> None:
     @reg.method("oauth.cancel", requires_agent=False)
     def cancel_(ctx: CallContext, params: dict) -> dict:
         return cancel(profile_home_param(params), _flow_id(params))
+
+    @reg.method("oauth.submit_redirect", requires_agent=False)
+    def submit_(ctx: CallContext, params: dict) -> dict:
+        url = str(params.get("url") or "").strip()
+        if not url:
+            raise InvalidParams("url is required")
+        return submit_redirect(profile_home_param(params), _flow_id(params), url)

package/sidecar/talaria_sidecar/methods/plugin_catalog.py

@@ -0,0 +1,198 @@
+"""Reviewed Agent catalog and disabled installs. Agent owns cache, scan and publication."""
+from __future__ import annotations
+
+import hashlib
+import inspect
+import json
+import os
+from pathlib import Path
+import re
+import secrets
+import threading
+import time
+
+from ..errors import InvalidParams, RpcError
+
+_receipts: dict[str, dict] = {}
+_lock = threading.Lock()
+
+
+def _agent():
+    try:
+        from hermes_cli import plugin_catalog as source, plugins_cmd as pc, plugins_cmd_catalog as native
+        if 'before_swap' not in inspect.signature(native.install_catalog_entry).parameters:
+            return None
+        return source, pc, native
+    except (ImportError, AttributeError):
+        return None
+
+
+def _refusal(entry, pc, native):
+    try:
+        native.raise_if_removed(entry.name, entry.repo)
+        native._refuse_unsupported_catalog_platform(entry)
+        from hermes_cli.plugins_manifest import requires_hermes_error
+        reason = requires_hermes_error({'requires_hermes': entry.requires_hermes})
+        if reason:
+            return reason
+        if not re.fullmatch(r'[a-f0-9]{40}', entry.sha):
+            return 'The catalog has no immutable reviewed pin.'
+    except pc.PluginOperationError as exc:
+        return str(exc)
+    return None
+
+
+def _requirements(entry):
+    caps = entry.capabilities
+    values = []
+    for label, items in [('Hermes', [entry.requires_hermes] if entry.requires_hermes else []),
+                         ('Platforms', entry.platforms), ('Environment', caps.requires_env),
+                         ('Tools', caps.provides_tools), ('Hooks', caps.provides_hooks),
+                         ('Middleware', caps.provides_middleware)]:
+        if items:
+            values.append(f'{label}: {", ".join(items)}')
+    return values + list(entry.known_issues)
+
+
+def catalog(query='', offset=0, limit=20):
+    if not isinstance(query, str) or len(query) > 200 or type(offset) is not int or not 0 <= offset <= 10000 or type(limit) is not int or not 1 <= limit <= 50:
+        raise InvalidParams('Invalid catalog search or page')
+    agent = _agent()
+    if agent is None:
+        return {'supported': False, 'entries': [], 'total': 0, 'next_offset': None}
+    source, pc, native = agent
+    # Read authoritative installer metadata only. Native discovery may load plugins or adopt old records.
+    metadata = pc._read_install_metadata()
+    rows = []
+    for entry in sorted(source.load_catalog_live(), key=lambda e: e.name)[:10000]:
+        if query.casefold() not in ' '.join([entry.name, entry.description, entry.tier, entry.category]).casefold():
+            continue
+        matches = [(key, record) for key, record in metadata.items() if isinstance(record, dict)
+                   and isinstance(record.get('catalog'), dict) and record['catalog'].get('name') == entry.name
+                   and (pc._plugins_dir() / key).is_dir()]
+        key, record = matches[0] if len(matches) == 1 else (None, {})
+        refusal = _refusal(entry, pc, native)
+        rows.append({'name': entry.name, 'title': entry.title or entry.name, 'description': entry.description,
+                     'repo': entry.repo, 'sha': entry.sha, 'tier': entry.tier, 'category': entry.category,
+                     'requirements': _requirements(entry), 'installed_key': key,
+                     'installed_sha': str(record.get('revision') or '') or None,
+                     'can_install': not matches and refusal is None, 'refusal': refusal})
+    end = offset + limit
+    return {'supported': True, 'entries': rows[offset:end], 'total': len(rows), 'next_offset': end if end < len(rows) else None}
+
+
+def _tree_digest(tree):
+    # Git's mutable clone metadata is not part of the code being reviewed.
+    digest = hashlib.sha256()
+    count = total = 0
+    for root, dirs, files in os.walk(tree, followlinks=False):
+        base = Path(root)
+        links = [name for name in dirs if (base / name).is_symlink()]
+        dirs[:] = sorted(name for name in dirs if name not in {'.git', '__pycache__'} and name not in links)
+        for name in sorted(files + links):
+            path = base / name
+            info = path.lstat()
+            count += 1
+            total += info.st_size
+            if count > 10000 or total > 64 * 1024 * 1024:
+                raise RpcError('The plugin tree exceeds the bounded review size.', condition='plugin_install_refused')
+            digest.update(json.dumps([str(path.relative_to(tree)), info.st_mode, info.st_size]).encode() + b'\0')
+            if path.is_symlink():
+                digest.update(os.readlink(path).encode())
+            else:
+                with path.open('rb') as stream:
+                    for chunk in iter(lambda: stream.read(1024 * 1024), b''):
+                        digest.update(chunk)
+    return digest.hexdigest()
+
+
+def install(name, consent_token=None):
+    if not isinstance(name, str) or not re.fullmatch(r'[a-z0-9_-]{1,64}', name) or consent_token is not None and not isinstance(consent_token, str):
+        raise InvalidParams('Choose a catalog name, without a URL or ref override')
+    agent = _agent()
+    if agent is None:
+        raise RpcError('This Agent cannot install reviewed catalog plugins', condition='plugin_catalog_unsupported')
+    source, pc, native = agent
+    from hermes_constants import get_hermes_home
+    from pm.plugin_declarations import read_python_declaration
+    from pm.workspace import enabled_plugin_dirs
+    from hermes_cli.plugin_capabilities import VALID_CAPABILITY_IDS
+
+    with _lock:
+        now = time.monotonic()
+        for token in list(_receipts):
+            if _receipts[token]['expires'] <= now:
+                del _receipts[token]
+        receipt = _receipts.pop(consent_token, None) if consent_token else None
+    changed = 'Plugin confirmation expired or changed; review the plugin again.'
+    def refuse_changed():
+        raise RpcError(changed, condition='plugin_install_consent_changed')
+    if consent_token and receipt is None:
+        refuse_changed()
+    entry = next((e for e in source.load_catalog_live() if e.name == name), None)
+    if entry is None:
+        raise RpcError('This plugin is no longer in the catalog', condition='plugin_install_refused')
+    identity = [str(get_hermes_home().resolve()), entry.to_dict()]
+    if receipt and receipt['identity'] != identity:
+        refuse_changed()
+    refusal = _refusal(entry, pc, native)
+    if refusal:
+        return {'name': name, 'status': 'blocked', 'findings': refusal}
+    preview = {}
+    findings = ''
+
+    class ReviewNeeded(Exception):
+        pass
+
+    def check_tree(manifest, tree):
+        nonlocal preview, findings
+        key = manifest.get('name')
+        if not isinstance(key, str) or not key:
+            raise pc.PluginOperationError('The plugin needs an explicit manifest name for reviewed installation.')
+        target = pc._sanitize_plugin_name(key, pc._plugins_dir())
+        if target.exists() or target.is_symlink():
+            raise pc.PluginOperationError('This plugin is already installed; use its existing controls.')
+        if target.resolve() in enabled_plugin_dirs(installing=target):
+            raise pc.PluginOperationError('This plugin is already selected in the profile. Review that selection before installing.')
+        from hermes_cli.plugins_manifest import requires_hermes_error
+        reason = requires_hermes_error(manifest)
+        if reason:
+            raise pc.PluginOperationError(reason)
+        raw_caps = manifest.get('capabilities') or []
+        if not isinstance(raw_caps, list) or any(not isinstance(c, str) or c not in VALID_CAPABILITY_IDS for c in raw_caps):
+            raise pc.PluginOperationError('The plugin declares capabilities this Agent cannot verify.')
+        deps = list(read_python_declaration(tree).install_requirements)
+        preview = {'tree': _tree_digest(tree), 'key': key, 'dependencies': deps, 'capabilities': raw_caps}
+        findings = '\n'.join([f'{entry.name} · {entry.tier} · {entry.sha}', entry.repo, *_requirements(entry),
+                              *([f'Python dependencies, not approved: {", ".join(deps)}'] if deps else []),
+                              *([f'Host capabilities, not granted: {", ".join(raw_caps)}'] if raw_caps else []),
+                              'Installs disabled. No dependency, host capability or sidecar permission is granted.',
+                              'Native Desktop contributions are unverified and do not run in Talaria.'])
+        if not receipt:
+            raise ReviewNeeded()
+        if receipt['preview'] != preview:
+            refuse_changed()
+        # Revalidate removal/repin immediately before the native scan/publication path.
+        current = next((e for e in source.load_catalog_live() if e.name == name), None)
+        if current is None or current.to_dict() != entry.to_dict():
+            refuse_changed()
+        native.raise_if_removed(entry.name, entry.repo)
+        return []
+
+    try:
+        # Same native core as dashboard_install_plugin(enable=False), with its staging hook binding review.
+        target, _manifest, key = native.install_catalog_entry(entry, force=False, ref=entry.sha,
+            allow_removed=False, assume_deps_consent=False, before_swap=check_tree)
+        return {'name': name, 'key': key, 'status': 'installed', 'enabled': False}
+    except ReviewNeeded:
+        pass
+    except pc.PluginScanBlocked as exc:
+        return {'name': name, 'status': 'blocked', 'findings': str(exc)}
+    except pc.PluginOperationError as exc:
+        return {'name': name, 'status': 'blocked', 'findings': str(exc)}
+    token = secrets.token_urlsafe(32)
+    with _lock:
+        if len(_receipts) >= 64:
+            del _receipts[next(iter(_receipts))]
+        _receipts[token] = {'identity': identity, 'preview': preview, 'expires': time.monotonic() + 300}
+    return {'name': name, 'status': 'needs_consent', 'findings': findings, 'consent_token': token}