hermes-github-app-plugin 0.1.2__py3-none-any.whl → 0.3.0__py3-none-any.whl

hermes_github_app_plugin/auth.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import re
 import time
 from dataclasses import dataclass
 from datetime import datetime, timedelta, timezone
@@ -11,9 +12,10 @@ from urllib.parse import urlparse
 import httpx
 import jwt
 
-from .config import GitHubAppConfig
+from .config import NONO_PHANTOM_TOKEN, GitHubAppConfig
 
 _MIN_REDACT_LENGTH = 8
+_BROKERED_TOKEN_LIFETIME = timedelta(hours=1)
 
 
 @dataclass(frozen=True)
@@ -25,6 +27,7 @@ class InstallationToken:
     installation_id: str
     client_id: str
     app_slug: str | None
+    token_broker: str | None = None
 
     @property
     def redacted(self) -> str:
@@ -40,31 +43,60 @@ class GitHubAppAuth:
     def __init__(self, config: GitHubAppConfig, client: httpx.Client | None = None) -> None:
         self._config = config
         self._client = client or httpx.Client(timeout=20)
-        self._cached_token: InstallationToken | None = None
+        self._cached_tokens: dict[str, InstallationToken] = {}
 
     @property
     def config(self) -> GitHubAppConfig:
         return self._config
 
     def create_jwt(self) -> str:
-        """Create a GitHub App JWT for installation-token exchange."""
+        """Create a GitHub App JWT for installation-token exchange.
+
+        In token broker mode there is no key to sign with; the placeholder is sent and the
+        broker replaces it outside the sandbox.
+        """
+        if self._config.token_broker:
+            return NONO_PHANTOM_TOKEN
         now = int(time.time())
         payload = {"iat": now - 60, "exp": now + 9 * 60, "iss": self._config.client_id}
         encoded = jwt.encode(payload, self._config.private_key, algorithm="RS256")
         return str(encoded)
 
-    def get_installation_token(self, *, force_refresh: bool = False) -> InstallationToken:
+    def get_installation_token(
+        self, *, repo: str | None = None, force_refresh: bool = False
+    ) -> InstallationToken:
         """Return a valid installation token, refreshing when near expiry."""
+        installation_id = self._config.installation_id_for_repo(repo)
+        cached_token = self._cached_tokens.get(installation_id)
         if (
             not force_refresh
-            and self._cached_token is not None
-            and self._cached_token.expires_at > datetime.now(timezone.utc) + timedelta(minutes=5)
+            and cached_token is not None
+            and cached_token.expires_at > datetime.now(timezone.utc) + timedelta(minutes=5)
         ):
-            return self._cached_token
+            return cached_token
 
+        if self._config.token_broker:
+            token = self._brokered_token(installation_id)
+        else:
+            token = self._exchange_app_jwt(installation_id)
+        self._cached_tokens[installation_id] = token
+        return token
+
+    def _brokered_token(self, installation_id: str) -> InstallationToken:
+        """Return the placeholder token with no network call; the broker injects the real one."""
+        return InstallationToken(
+            token=NONO_PHANTOM_TOKEN,
+            expires_at=datetime.now(timezone.utc) + _BROKERED_TOKEN_LIFETIME,
+            installation_id=installation_id,
+            client_id=self._config.client_id,
+            app_slug=self._config.app_slug,
+            token_broker=self._config.token_broker,
+        )
+
+    def _exchange_app_jwt(self, installation_id: str) -> InstallationToken:
+        """Exchange the app JWT for an installation access token."""
         response = self._client.post(
-            f"{self._config.github_api_url}/app/installations/"
-            f"{self._config.installation_id}/access_tokens",
+            f"{self._config.github_api_url}/app/installations/{installation_id}/access_tokens",
             headers={
                 "Accept": "application/vnd.github+json",
                 "Authorization": f"Bearer {self.create_jwt()}",
@@ -75,15 +107,13 @@ class GitHubAppAuth:
         data = response.json()
         expires_at_raw = str(data["expires_at"])
         expires_at = datetime.fromisoformat(expires_at_raw.replace("Z", "+00:00"))
-        token = InstallationToken(
+        return InstallationToken(
             token=str(data["token"]),
             expires_at=expires_at,
-            installation_id=self._config.installation_id,
+            installation_id=installation_id,
             client_id=self._config.client_id,
             app_slug=self._config.app_slug,
         )
-        self._cached_token = token
-        return token
 
     def app_request(
         self,
@@ -120,6 +150,8 @@ class GitHubAppAuth:
                 "client_id": self._config.client_id,
                 "app_slug": self._config.app_slug,
                 "installation_id": self._config.installation_id,
+                "installation_ids": dict(self._config.installation_ids),
+                "token_broker": self._config.token_broker,
             },
             "status_code": response.status_code,
             "result": response.json() if response.content else {"ok": True},
@@ -135,7 +167,8 @@ class GitHubAppAuth:
         params: dict[str, Any] | None = None,
     ) -> dict[str, Any]:
         """Call the GitHub REST API using the installation token."""
-        token = self.get_installation_token()
+        repo = repo or repo_from_path(path)
+        token = self.get_installation_token(repo=repo)
         url = (
             path if path.startswith("http") else f"{self._config.github_api_url}/{path.lstrip('/')}"
         )
@@ -158,9 +191,11 @@ class GitHubAppAuth:
             "result": parsed,
         }
 
-    def graphql(self, query: str, variables: dict[str, Any] | None = None) -> dict[str, Any]:
+    def graphql(
+        self, query: str, variables: dict[str, Any] | None = None, *, repo: str | None = None
+    ) -> dict[str, Any]:
         """Call GitHub GraphQL API using the installation token."""
-        token = self.get_installation_token()
+        token = self.get_installation_token(repo=repo)
         response = self._client.post(
             f"{self._config.github_api_url}/graphql",
             headers={
@@ -172,7 +207,7 @@ class GitHubAppAuth:
         )
         response.raise_for_status()
         return {
-            "auth": auth_metadata(token),
+            "auth": auth_metadata(token, repo=repo),
             "status_code": response.status_code,
             "result": response.json(),
         }
@@ -189,6 +224,7 @@ def auth_metadata(token: InstallationToken, *, repo: str | None = None) -> dict[
         "actor_expected": actor,
         "repository": repo,
         "token": token.redacted,
+        "token_broker": token.token_broker,
         "expires_at": token.expires_at.isoformat(),
     }
 
@@ -203,3 +239,17 @@ def requires_app_jwt(path: str) -> bool:
             return False
     normalized = "/" + path_only.lstrip("/")
     return normalized == "/app" or normalized.startswith("/app/")
+
+
+def repo_from_path(path: str) -> str | None:
+    """Infer OWNER/REPO from common REST API repository paths."""
+    path_only = path.split("?", 1)[0]
+    if path_only.startswith("http"):
+        try:
+            path_only = urlparse(path_only).path
+        except ValueError:
+            return None
+    match = re.match(r"^/?repos/([^/]+)/([^/]+)(?:/|$)", path_only)
+    if not match:
+        return None
+    return f"{match.group(1)}/{match.group(2)}"

hermes_github_app_plugin/cli.py

@@ -16,7 +16,13 @@ from typing import Any, NoReturn
 import httpx
 
 from .auth import GitHubAppAuth, auth_metadata, requires_app_jwt
-from .config import ConfigurationError, load_config, write_github_app_config
+from .config import (
+    ConfigurationError,
+    GitHubAppConfig,
+    load_config,
+    parse_token_broker,
+    write_github_app_config,
+)
 
 
 def register_cli(parser: argparse.ArgumentParser) -> None:
@@ -29,8 +35,21 @@ def register_cli(parser: argparse.ArgumentParser) -> None:
         "--non-interactive", action="store_true", help="Read values from flags/env only"
     )
     setup.add_argument("--client-id", help="GitHub App client ID")
-    setup.add_argument("--installation-id", help="GitHub App installation ID")
+    setup.add_argument("--installation-id", help="Default GitHub App installation ID")
+    setup.add_argument(
+        "--installation-id-for",
+        action="append",
+        default=[],
+        metavar="OWNER=ID",
+        help="Owner-specific installation ID mapping; repeat for multiple orgs",
+    )
     setup.add_argument("--private-key-path", help="Path to GitHub App private key PEM")
+    setup.add_argument(
+        "--token-broker",
+        metavar="NAME",
+        help="Credentials are injected outside the sandbox by this broker (supported: nono); "
+        "no private key is configured",
+    )
     setup.add_argument("--app-slug", help="Optional GitHub App slug, e.g. my-agent")
     setup.add_argument(
         "--skip-verify", action="store_true", help="Write config without minting a token"
@@ -87,9 +106,9 @@ def gh_app_main() -> NoReturn:
         print("usage: gh-app [--repo OWNER/REPO] [--] <gh args...>")
         print("Runs gh with GH_TOKEN/GITHUB_TOKEN set to a GitHub App installation token.")
         raise SystemExit(0)
-    _, child_args = _extract_repo(args)
+    repo, child_args = _extract_repo(args)
     config = load_config()
-    token = GitHubAppAuth(config).get_installation_token()
+    token = GitHubAppAuth(config).get_installation_token(repo=repo)
     env = os.environ.copy()
     env["GH_TOKEN"] = token.token
     env["GITHUB_TOKEN"] = token.token
@@ -102,9 +121,9 @@ def git_app_main() -> NoReturn:
         print("usage: git-app [--repo OWNER/REPO] [--] <git args...>")
         print("Runs git with a temporary askpass helper backed by a GitHub App token.")
         raise SystemExit(0)
-    _, child_args = _extract_repo(sys.argv[1:])
+    repo, child_args = _extract_repo(sys.argv[1:])
     config = load_config()
-    token = GitHubAppAuth(config).get_installation_token()
+    token = GitHubAppAuth(config).get_installation_token(repo=repo)
     with tempfile.TemporaryDirectory(prefix="git-app-") as temp_dir:
         askpass = Path(temp_dir) / "askpass.sh"
         askpass.write_text(
@@ -127,6 +146,16 @@ def _setup(args: argparse.Namespace) -> int:
     """Interactively write GitHub App configuration."""
     print("Hermes GitHub App setup")
     print("Required values are unmarked. Optional prompts include '(optional)'.")
+    token_broker = parse_token_broker(
+        getattr(args, "token_broker", None) or os.environ.get("GITHUB_APP_TOKEN_BROKER"),
+        source="--token-broker or GITHUB_APP_TOKEN_BROKER",
+    )
+    if token_broker and args.private_key_path:
+        raise ConfigurationError(
+            "--private-key-path cannot be combined with --token-broker; "
+            "the private key must stay outside the agent's sandbox"
+        )
+    installation_ids = _parse_installation_id_for_args(list(args.installation_id_for))
     values = {
         "client_id": _value_or_prompt(
             args.client_id,
@@ -139,10 +168,15 @@ def _setup(args: argparse.Namespace) -> int:
             args.installation_id,
             "GitHub App installation ID",
             env="GITHUB_APP_INSTALLATION_ID",
-            required=True,
+            required=not installation_ids,
             non_interactive=bool(args.non_interactive),
         ),
-        "private_key_path": _value_or_prompt(
+        "installation_ids": installation_ids,
+        "token_broker": token_broker,
+        # An empty value removes any private_key_path left by an earlier non-brokered setup.
+        "private_key_path": ""
+        if token_broker
+        else _value_or_prompt(
             args.private_key_path,
             "GitHub App private key path",
             env="GITHUB_APP_PRIVATE_KEY_PATH",
@@ -157,10 +191,11 @@ def _setup(args: argparse.Namespace) -> int:
             non_interactive=bool(args.non_interactive),
         ),
     }
-    key_path = Path(str(values["private_key_path"])).expanduser()
-    if not key_path.exists():
-        raise ConfigurationError(f"private key file does not exist: {key_path}")
-    _warn_private_key_permissions(key_path)
+    if not token_broker:
+        key_path = Path(str(values["private_key_path"])).expanduser()
+        if not key_path.exists():
+            raise ConfigurationError(f"private key file does not exist: {key_path}")
+        _warn_private_key_permissions(key_path)
     written = write_github_app_config(values)
     print(f"Wrote GitHub App config to {written}")
     if args.skip_verify:
@@ -180,22 +215,19 @@ def _doctor(repo: str | None, *, skip_network: bool) -> int:
     try:
         config = load_config()
         checks.append(("GitHub App config loaded", True, "client_id and installation_id present"))
-        key_source = Path(config.private_key_source).expanduser()
-        if config.private_key_source == "GITHUB_APP_PRIVATE_KEY":
-            checks.append(("private key loaded", True, "inline environment variable"))
+        if config.token_broker:
+            checks.extend(_token_broker_checks(config.token_broker))
         else:
-            checks.append(("private key file exists", key_source.exists(), str(key_source)))
-            checks.append(
-                (
-                    "private key file permissions",
-                    _private_key_permissions_ok(key_source),
-                    _mode(key_source),
-                )
-            )
+            checks.extend(_private_key_checks(config))
         if not skip_network:
             auth = GitHubAppAuth(config)
-            token = auth.get_installation_token(force_refresh=True)
-            checks.append(("installation token minted", True, token.redacted))
+            token = auth.get_installation_token(repo=repo, force_refresh=True)
+            minted_label = (
+                f"installation token brokered by {config.token_broker}"
+                if config.token_broker
+                else "installation token minted"
+            )
+            checks.append((minted_label, True, token.redacted))
             app_result = auth.app_request("GET", "/app")["result"]
             checks.append(("/app API reachable", True, str(app_result.get("slug", "ok"))))
             if repo:
@@ -221,10 +253,39 @@ def _doctor(repo: str | None, *, skip_network: bool) -> int:
     return 1
 
 
+def _private_key_checks(config: GitHubAppConfig) -> list[tuple[str, bool, str]]:
+    if config.private_key_source == "GITHUB_APP_PRIVATE_KEY":
+        return [("private key loaded", True, "inline environment variable")]
+    key_source = Path(config.private_key_source).expanduser()
+    return [
+        ("private key file exists", key_source.exists(), str(key_source)),
+        (
+            "private key file permissions",
+            _private_key_permissions_ok(key_source),
+            _mode(key_source),
+        ),
+    ]
+
+
+def _token_broker_checks(broker: str) -> list[tuple[str, bool, str]]:
+    proxy_set = bool(os.environ.get("HTTPS_PROXY") or os.environ.get("https_proxy"))
+    return [
+        ("token broker", True, f"{broker}; credentials are injected outside the sandbox"),
+        (
+            "HTTPS_PROXY set",
+            proxy_set,
+            "set"
+            if proxy_set
+            else "not set; agent does not appear to be running inside nono, "
+            "so no credentials will be injected",
+        ),
+    ]
+
+
 def _status(repo: str | None) -> int:
     config = load_config()
     auth = GitHubAppAuth(config)
-    token = auth.get_installation_token(force_refresh=True)
+    token = auth.get_installation_token(repo=repo, force_refresh=True)
     app = auth.app_request("GET", "/app")["result"]
     repo_probe = auth.request("GET", f"/repos/{repo}", repo=repo)["result"] if repo else None
     print(
@@ -244,11 +305,17 @@ def _status(repo: str | None) -> int:
 
 def _token(repo: str | None, *, json_output: bool) -> int:
     config = load_config()
-    token = GitHubAppAuth(config).get_installation_token()
+    token = GitHubAppAuth(config).get_installation_token(repo=repo)
     if json_output:
         print(json.dumps({"token": token.token, "auth": auth_metadata(token, repo=repo)}, indent=2))
     else:
         print(token.token)
+    if config.token_broker:
+        print(
+            "note: token broker mode. The printed value is a placeholder; the real installation "
+            "token lives outside the sandbox and the nono proxy injects it into GitHub requests.",
+            file=sys.stderr,
+        )
     return 0
 
 
@@ -262,6 +329,25 @@ def _api(method: str, path: str, *, repo: str | None, body: dict[str, Any] | Non
     return 0
 
 
+def _parse_installation_id_for_args(values: list[str]) -> dict[str, str]:
+    """Parse repeated OWNER=INSTALLATION_ID setup flags."""
+    installation_ids: dict[str, str] = {}
+    for value in values:
+        if "=" not in value:
+            raise ConfigurationError(
+                f"invalid --installation-id-for value: {value!r}; expected OWNER=INSTALLATION_ID"
+            )
+        owner, installation_id = value.split("=", 1)
+        owner = owner.strip().lower()
+        installation_id = installation_id.strip()
+        if not owner or not installation_id:
+            raise ConfigurationError(
+                f"invalid --installation-id-for value: {value!r}; expected OWNER=INSTALLATION_ID"
+            )
+        installation_ids[owner] = installation_id
+    return installation_ids
+
+
 def _value_or_prompt(
     value: str | None,
     label: str,

hermes_github_app_plugin/config.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import json
 import os
 from collections.abc import Mapping
 from dataclasses import dataclass
@@ -10,6 +11,11 @@ from typing import Any
 
 import yaml
 
+# Token brokers keep the private key outside the agent's sandbox. The broker injects real
+# credentials into outbound requests, so the agent only ever sends this placeholder.
+SUPPORTED_TOKEN_BROKERS: tuple[str, ...] = ("nono",)
+NONO_PHANTOM_TOKEN = "nono-phantom-github-app"
+
 
 class ConfigurationError(RuntimeError):
     """Raised when GitHub App configuration is missing or invalid."""
@@ -17,14 +23,28 @@ class ConfigurationError(RuntimeError):
 
 @dataclass(frozen=True)
 class GitHubAppConfig:
-    """Per-agent GitHub App configuration."""
+    """Per-agent GitHub App configuration.
+
+    In token broker mode `private_key` is empty and `token_broker` names the broker.
+    """
 
     client_id: str
     installation_id: str
     private_key: str
+    installation_ids: dict[str, str]
     private_key_source: str
     app_slug: str | None = None
     github_api_url: str = "https://api.github.com"
+    token_broker: str | None = None
+
+    def installation_id_for_repo(self, repo: str | None = None) -> str:
+        """Return the installation ID for an optional OWNER/REPO target."""
+        if repo and "/" in repo:
+            owner = repo.split("/", 1)[0].lower()
+            installation_id = self.installation_ids.get(owner)
+            if installation_id:
+                return installation_id
+        return self.installation_id
 
 
 def hermes_home() -> Path:
@@ -63,7 +83,7 @@ def write_github_app_config(values: Mapping[str, Any]) -> Path:
         section = {}
         data["github_app"] = section
     for key, value in values.items():
-        if value in (None, "", (), []):
+        if value in (None, "", (), []) or (isinstance(value, Mapping) and not value):
             section.pop(key, None)
         else:
             section[key] = value
@@ -76,6 +96,52 @@ def write_github_app_config(values: Mapping[str, Any]) -> Path:
     return path
 
 
+def _parse_installation_ids(raw: Any) -> dict[str, str]:
+    """Parse owner-to-installation-ID mapping from YAML or environment values."""
+    if raw in (None, ""):
+        return {}
+    parsed: Any = raw
+    if isinstance(raw, str):
+        try:
+            parsed = json.loads(raw)
+        except json.JSONDecodeError:
+            parsed = {}
+            for item in raw.replace("\n", ",").split(","):
+                if not item.strip():
+                    continue
+                if "=" not in item:
+                    raise ConfigurationError(
+                        "invalid GITHUB_APP_INSTALLATION_IDS entry: "
+                        f"{item!r}; expected OWNER=INSTALLATION_ID"
+                    ) from None
+                owner, installation_id = item.split("=", 1)
+                parsed[owner.strip()] = installation_id.strip()
+    if not isinstance(parsed, Mapping):
+        raise ConfigurationError("github_app.installation_ids must be a mapping of owner to ID")
+    result: dict[str, str] = {}
+    for owner, installation_id in parsed.items():
+        owner_text = str(owner).strip().lower()
+        installation_text = str(installation_id).strip()
+        if owner_text and installation_text:
+            result[owner_text] = installation_text
+    return result
+
+
+def parse_token_broker(raw: object, *, source: str) -> str | None:
+    """Normalize a token broker name; empty values mean no broker."""
+    if raw is None:
+        return None
+    text = str(raw).strip().lower()
+    if not text:
+        return None
+    if text not in SUPPORTED_TOKEN_BROKERS:
+        supported = ", ".join(SUPPORTED_TOKEN_BROKERS)
+        raise ConfigurationError(
+            f"unsupported token broker {str(raw)!r} from {source}; supported: {supported}"
+        )
+    return text
+
+
 def _read_private_key(section: Mapping[str, Any]) -> tuple[str, str]:
     inline_key = os.environ.get("GITHUB_APP_PRIVATE_KEY") or str(section.get("private_key", ""))
     if inline_key:
@@ -106,18 +172,35 @@ def load_config() -> GitHubAppConfig:
         raise ConfigurationError(
             "missing GitHub App client ID: set GITHUB_APP_CLIENT_ID or github_app.client_id"
         )
-    if not installation_id:
+    installation_ids = _parse_installation_ids(
+        os.environ.get("GITHUB_APP_INSTALLATION_IDS") or section.get("installation_ids", {})
+    )
+    if not installation_id and not installation_ids:
         raise ConfigurationError(
-            "missing GitHub App installation ID: set GITHUB_APP_INSTALLATION_ID "
-            "or github_app.installation_id"
+            "missing GitHub App installation ID: set GITHUB_APP_INSTALLATION_ID, "
+            "github_app.installation_id, or github_app.installation_ids"
         )
-    private_key, private_key_source = _read_private_key(section)
+    if not installation_id:
+        # Use a deterministic fallback for commands that cannot infer an OWNER/REPO.
+        installation_id = next(iter(installation_ids.values()))
+    broker_env = os.environ.get("GITHUB_APP_TOKEN_BROKER")
+    token_broker = parse_token_broker(
+        broker_env or section.get("token_broker"),
+        source="GITHUB_APP_TOKEN_BROKER" if broker_env else "github_app.token_broker",
+    )
+    if token_broker:
+        # The private key never enters a brokered agent's environment; ignore any key settings.
+        private_key, private_key_source = "", f"token broker: {token_broker}"
+    else:
+        private_key, private_key_source = _read_private_key(section)
     return GitHubAppConfig(
         client_id=client_id,
         installation_id=installation_id,
         private_key=private_key,
+        installation_ids=installation_ids,
         private_key_source=private_key_source,
         app_slug=os.environ.get("GITHUB_APP_SLUG") or section.get("app_slug"),
         github_api_url=os.environ.get("GITHUB_API_URL")
         or str(section.get("github_api_url", "https://api.github.com")).rstrip("/"),
+        token_broker=token_broker,
     )

hermes_github_app_plugin/plugin.yaml

@@ -1,5 +1,5 @@
 name: github-app
-version: 0.1.0
+version: 0.3.0
 description: "GitHub App identity integration for Hermes: per-agent app token minting, GitHub API tools, gh/git wrappers, CLI, and workflow skill."
 author: Hermes GitHub App Plugin Contributors
 provides_tools:
@@ -20,8 +20,14 @@ requires_env:
     description: "GitHub App client ID for this Hermes agent. Can also be set in ~/.hermes/config.yaml under github_app.client_id."
     secret: false
   - name: GITHUB_APP_INSTALLATION_ID
-    description: "GitHub App installation ID for this Hermes agent. Can also be set in ~/.hermes/config.yaml under github_app.installation_id."
+    description: "Default GitHub App installation ID for this Hermes agent. Can also be set in ~/.hermes/config.yaml under github_app.installation_id."
+    secret: false
+  - name: GITHUB_APP_INSTALLATION_IDS
+    description: "Optional owner-to-installation-ID mapping for apps installed in multiple orgs. JSON object or OWNER=ID,OWNER2=ID2. Can also be set under github_app.installation_ids."
     secret: false
   - name: GITHUB_APP_PRIVATE_KEY_PATH
-    description: "Path to the GitHub App private key PEM. Can also be set in ~/.hermes/config.yaml under github_app.private_key_path."
+    description: "Path to the GitHub App private key PEM. Can also be set in ~/.hermes/config.yaml under github_app.private_key_path. Not used when GITHUB_APP_TOKEN_BROKER is set."
     secret: true
+  - name: GITHUB_APP_TOKEN_BROKER
+    description: "Set to nono when the agent runs in the nono sandbox and the token broker injects credentials. No private key is read in this mode. Can also be set in ~/.hermes/config.yaml under github_app.token_broker."
+    secret: false

hermes_github_app_plugin/skills/github-app-workflow/SKILL.md

@@ -11,7 +11,17 @@ Use this skill for GitHub operations from Hermes agents that are configured with
 
 ## First-time setup
 
-Run `hermes-github-app setup` to write `github_app` config into `~/.hermes/config.yaml`. The setup walkthrough marks optional values with `(optional)`; the required values are GitHub App client ID, installation ID, and private key path.
+Run `hermes-github-app setup` to write `github_app` config into `~/.hermes/config.yaml`. The setup walkthrough marks optional values with `(optional)`; the required values are GitHub App client ID, a default installation ID or owner-specific `installation_ids`, and private key path. For apps installed in multiple organizations, pass repeated `--installation-id-for OWNER=ID` flags or configure:
+
+```yaml
+github_app:
+  installation_id: "123456"  # default/fallback
+  installation_ids:
+    ExampleOrg: "123456"
+    ExampleInfra: "789012"
+```
+
+The plugin chooses an owner-specific installation ID from `--repo OWNER/REPO` or `/repos/OWNER/REPO` REST API paths and falls back to `installation_id` when no repository owner is available.
 
 After setup, run `hermes-github-app doctor --repo OWNER/REPO` to verify console scripts, config loading, private-key permissions, token minting, and repository access. Use `--skip-network` only for container/image builds where secrets or network access are not available yet.
 
@@ -26,6 +36,14 @@ After setup, run `hermes-github-app doctor --repo OWNER/REPO` to verify console
 7. Expect comments, PRs, and API writes to appear as `<app-slug>[bot]`.
 8. Treat the GitHub App installation scope as the repository access boundary. The plugin does not maintain a separate local repository/owner allowlist.
 
+## Running inside nono (token broker mode)
+
+If `hermes-github-app doctor` reports `token broker: nono`, this agent runs in the nono sandbox. By design it holds no GitHub App private key and cannot obtain a real installation token.
+
+- Do not search for, copy, or request a private key or a real token. `hermes-github-app token` prints a placeholder; nono's proxy outside the sandbox injects the real credentials into GitHub requests.
+- `github_app_*` tools, `gh-app`, and `git-app` work as described above. Plain `gh` and HTTPS `git push` also work because the proxy injects credentials, so keep remotes HTTPS.
+- If `doctor` reports `HTTPS_PROXY set` as failed, the agent is not running inside nono and no credentials will be injected. Stop and report that. Do not fall back to local human credentials or SSH keys.
+
 ## Updating existing Hermes skills
 
 Patch any GitHub-related skill, cron prompt, or subagent instruction that mentions `gh`, `git push`, GitHub SSH remotes, or `@me` assumptions:

hermes_github_app_plugin/tools.py

@@ -39,8 +39,10 @@ def github_app_status(params: dict[str, Any], **_: Any) -> str:
             "configured": True,
             "client_id": config.client_id,
             "installation_id": config.installation_id,
+            "installation_ids": dict(config.installation_ids),
             "app_slug": config.app_slug,
             "private_key_source": config.private_key_source,
+            "token_broker": config.token_broker,
             "github_api_url": config.github_api_url,
             "scope_management": "github_app_installation",
         }
@@ -54,7 +56,7 @@ def github_app_verify_identity(params: dict[str, Any], **_: Any) -> str:
     def run() -> dict[str, Any]:
         repo = _repo(params)
         auth = _auth()
-        token = auth.get_installation_token(force_refresh=True)
+        token = auth.get_installation_token(repo=repo, force_refresh=True)
         app = auth.app_request("GET", "/app")
         repo_probe = auth.request("GET", f"/repos/{repo}", repo=repo) if repo else None
         return {
@@ -92,7 +94,9 @@ def github_app_graphql(params: dict[str, Any], **_: Any) -> str:
     def run() -> dict[str, Any]:
         variables = params.get("variables")
         return _auth().graphql(
-            str(params["query"]), variables if isinstance(variables, dict) else None
+            str(params["query"]),
+            variables if isinstance(variables, dict) else None,
+            repo=_repo(params),
         )
 
     return _handle_errors(run)

{hermes_github_app_plugin-0.1.2.dist-info → hermes_github_app_plugin-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: hermes-github-app-plugin
-Version: 0.1.2
+Version: 0.3.0
 Summary: Hermes plugin for per-agent GitHub App identity, gh/git wrappers, and GitHub App-aware tools.
 Author: Hermes GitHub App Plugin Contributors
 License: MIT
@@ -26,7 +26,12 @@ Each Hermes agent runs the same package but is configured with its own GitHub Ap
 ```yaml
 github_app:
   client_id: "Iv1.exampleclientid"
+  # Optional default used when a command cannot infer OWNER/REPO.
   installation_id: "987654"
+  # Optional owner-specific installation IDs for apps installed in multiple orgs.
+  installation_ids:
+    ExampleOrg: "123456"
+    ExampleInfra: "987654"
   private_key_path: "~/.hermes/secrets/agent-github-app.private-key.pem"
   app_slug: "hermes-agent"
 ```
@@ -35,8 +40,10 @@ Environment variables with the same meaning are also supported:
 
 - `GITHUB_APP_CLIENT_ID`
 - `GITHUB_APP_INSTALLATION_ID`
+- `GITHUB_APP_INSTALLATION_IDS` (JSON object or `OWNER=ID,OWNER2=ID2` mapping)
 - `GITHUB_APP_PRIVATE_KEY_PATH`
 - `GITHUB_APP_PRIVATE_KEY` (PEM contents; useful for CI)
+- `GITHUB_APP_TOKEN_BROKER=nono` (no private key in this environment; see [Running inside nono](#running-inside-nono-token-broker-mode))
 
 Repository access is controlled by the GitHub App installation scope in GitHub. If an agent should not access a repository, remove that repository from the GitHub App installation scope.
 
@@ -46,7 +53,7 @@ Repository access is controlled by the GitHub App installation scope in GitHub.
 
 `installation_id` identifies one installation of that app on a specific user or organization account. It is required when exchanging the app JWT for an installation access token via `POST /app/installations/{installation_id}/access_tokens`.
 
-In other words: `client_id` answers "which GitHub App is signing this JWT?" while `installation_id` answers "which installed copy of that app should this token act as?" The same GitHub App can have multiple installation IDs if it is installed on multiple accounts.
+In other words: `client_id` answers "which GitHub App is signing this JWT?" while `installation_id` answers "which installed copy of that app should this token act as?" The same GitHub App can have multiple installation IDs if it is installed on multiple accounts. Configure `installation_ids` when one app is installed in multiple organizations; the plugin chooses an owner-specific ID from `--repo OWNER/REPO` or `/repos/OWNER/REPO` REST paths and falls back to `installation_id` when no repository owner is available.
 
 ## Install
 
@@ -72,6 +79,8 @@ For scripted installs, pass flags and skip the network verification until secret
 hermes-github-app setup --non-interactive --skip-verify \
   --client-id Iv1.exampleclientid \
   --installation-id 987654 \
+  --installation-id-for ExampleOrg=123456 \
+  --installation-id-for ExampleInfra=987654 \
   --private-key-path ~/.hermes/secrets/agent-github-app.private-key.pem \
   --app-slug hermes-agent
 ```
@@ -94,6 +103,35 @@ git-app --repo OWNER/REPO push origin my-branch
 `gh-app` injects an ephemeral installation token as `GH_TOKEN` and `GITHUB_TOKEN` for the child `gh` process.
 `git-app` injects a temporary askpass helper so HTTPS Git operations authenticate as the GitHub App installation token without writing credentials into the remote URL.
 
+## Running inside nono (token broker mode)
+
+[nono](https://nono.sh) can run the agent in a sandbox that never holds the GitHub App private key. Enable broker mode with `GITHUB_APP_TOKEN_BROKER=nono` or `github_app.token_broker: nono`:
+
+```yaml
+github_app:
+  client_id: "Iv1.exampleclientid"
+  installation_ids:
+    ExampleOrg: "123456"
+  token_broker: nono
+```
+
+```bash
+hermes-github-app setup --token-broker nono --client-id Iv1.exampleclientid --installation-id 987654
+```
+
+In broker mode the plugin reads no private key; `private_key_path` and `GITHUB_APP_PRIVATE_KEY*` are ignored. Installation tokens are not minted locally. The plugin sends the placeholder `nono-phantom-github-app` as its token, and nono's supervisor, outside the sandbox, handles the real credentials:
+
+- Its TLS-intercepting proxy replaces the `Authorization` header on requests to `api.github.com`, `uploads.github.com`, and `github.com` with an installation token chosen by owner from the request path. Git HTTPS uses the same token as Basic `x-access-token`.
+- The app JWT is injected for exactly `GET /app`.
+
+What this means for agents:
+
+- `github_app_*` tools, `hermes-github-app api`, `gh-app`, and `git-app` work unchanged; the placeholder flows through.
+- Plain `git push` over HTTPS and plain `gh` also work, because the proxy injects credentials into those requests. Keep remotes HTTPS. SSH remotes use local SSH keys and are not covered.
+- The agent cannot obtain a real token, by design. `hermes-github-app token` prints the placeholder with a note on stderr.
+- `client_id` is still required in broker mode. It is non-secret and is reported in auth metadata.
+- `hermes-github-app doctor` shows a `token broker` check and an `HTTPS_PROXY set` check. If the proxy variable is missing, the agent is not running inside nono and no credentials will be injected.
+
 ## Migrating existing Hermes skills and jobs
 
 To keep agents from falling back to local human credentials, update existing GitHub-related Hermes skills, cron jobs, and subagent prompts with these rules:
@@ -127,8 +165,8 @@ Before the first release, configure PyPI Trusted Publishing for this repository
 Release example:
 
 ```bash
-git tag 0.1.2
-git push origin 0.1.2
+git tag 0.3.0
+git push origin 0.3.0
 ```
 
 Tags like `v0.1.0`, `0.1`, or `0.1.0rc1` will not publish.

hermes_github_app_plugin-0.3.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+hermes_github_app_plugin/__init__.py,sha256=NnRzmqrrdX7lgoqhFn8LXVyo7pCzAT9Hyx9U452RIvc,1956
+hermes_github_app_plugin/auth.py,sha256=QRvLk3aqWxWrtYrMIVuxsKZLPwlINf-qlWcD3g6v0E8,9183
+hermes_github_app_plugin/cli.py,sha256=qOkahrMpK_6JktDBEzWDjBL88X5vHx7tjOgb5DgmaVI,15707
+hermes_github_app_plugin/config.py,sha256=fdnHmsI15li387Y8DOx8KTQlWXlpEPJ8V9tO-TwDpSA,7813
+hermes_github_app_plugin/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hermes_github_app_plugin/schemas.py,sha256=yNDBOEvXzhDRtMWfX8mGmdMyAFtP_d9H4_j40C_BqTo,3099
+hermes_github_app_plugin/tools.py,sha256=_H439zRIYDcExbzepl1OiTtw1N4Q2SExK6BN3myexGA,5489
+hermes_github_app_plugin/skills/github-app-workflow/SKILL.md,sha256=rteb4bR3YcA8VMpIjGARsqcw6Bbv0hVz-5YniazOvpA,4314
+hermes_github_app_plugin/plugin.yaml,sha256=_WEbl9TlTQHSi9yOOz5a9xJlFeFUlGOvQEYq06Y4no4,1657
+hermes_github_app_plugin-0.3.0.dist-info/METADATA,sha256=m3W7Z4H5ZzT-I4EeXtpeFgYDStwq83bwlv3a0ULudfM,8413
+hermes_github_app_plugin-0.3.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+hermes_github_app_plugin-0.3.0.dist-info/entry_points.txt,sha256=ydr4f-i9GywzITOEUQovI8QkquJwew8NrHbOsE5qrYQ,236
+hermes_github_app_plugin-0.3.0.dist-info/licenses/LICENSE,sha256=6zZgOs9Rdg8m9nRz_a-8VmYPNTVOA45JCqXUfpUYmdE,1094
+hermes_github_app_plugin-0.3.0.dist-info/RECORD,,

{hermes_github_app_plugin-0.1.2.dist-info → hermes_github_app_plugin-0.3.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.30.1
+Generator: hatchling 1.33.0
 Root-Is-Purelib: true
 Tag: py3-none-any

hermes_github_app_plugin-0.1.2.dist-info/RECORD

@@ -1,14 +0,0 @@
-hermes_github_app_plugin/__init__.py,sha256=NnRzmqrrdX7lgoqhFn8LXVyo7pCzAT9Hyx9U452RIvc,1956
-hermes_github_app_plugin/auth.py,sha256=vJ6mzKINoMu6QawVy9V_8G4RWEreGY-jpNODuHw3374,7131
-hermes_github_app_plugin/cli.py,sha256=ll3sKLO_VZWmBRdTj0d64X3QgswzC4V-f00vtm_QiZw,12443
-hermes_github_app_plugin/config.py,sha256=m0s7IDGnnchndhjsoPzMJAONTYk8SLcZjNi0K1qiaQM,4217
-hermes_github_app_plugin/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-hermes_github_app_plugin/schemas.py,sha256=yNDBOEvXzhDRtMWfX8mGmdMyAFtP_d9H4_j40C_BqTo,3099
-hermes_github_app_plugin/tools.py,sha256=Rgq1vbub5YHUYJ92h2KDDjxQxDjbWschckC0dnGh9W0,5321
-hermes_github_app_plugin/skills/github-app-workflow/SKILL.md,sha256=2W2-Hp5xfR8ZyxhgBmJyP1SJmkLStP9wbNdCVsw68YI,3002
-hermes_github_app_plugin/plugin.yaml,sha256=1bYCxwR5wVbaWWRh3mHx5Wd8ghTZIbWIyqDzhMgo09E,1088
-hermes_github_app_plugin-0.1.2.dist-info/METADATA,sha256=PzmyeW8DZEdmdexnP_wL_Ee-OYK0yCrnKheCtGcxm5o,5785
-hermes_github_app_plugin-0.1.2.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-hermes_github_app_plugin-0.1.2.dist-info/entry_points.txt,sha256=ydr4f-i9GywzITOEUQovI8QkquJwew8NrHbOsE5qrYQ,236
-hermes_github_app_plugin-0.1.2.dist-info/licenses/LICENSE,sha256=6zZgOs9Rdg8m9nRz_a-8VmYPNTVOA45JCqXUfpUYmdE,1094
-hermes_github_app_plugin-0.1.2.dist-info/RECORD,,