hermes-github-app-plugin 0.2.0__tar.gz → 0.3.1__tar.gz

{hermes_github_app_plugin-0.2.0 → hermes_github_app_plugin-0.3.1}/.github/workflows/cd.yaml

@@ -16,7 +16,7 @@ jobs:
       release_tag: ${{ steps.validate.outputs.release_tag }}
     steps:
       - uses: actions/checkout@v7
-      - uses: actions/setup-python@v6
+      - uses: actions/setup-python@v7
         with:
           python-version: '3.12'
       - name: Validate tag and package version
@@ -48,7 +48,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
-      - uses: actions/setup-python@v6
+      - uses: actions/setup-python@v7
         with:
           python-version: '3.12'
           cache: pip

{hermes_github_app_plugin-0.2.0 → hermes_github_app_plugin-0.3.1}/.github/workflows/ci.yaml

@@ -15,7 +15,7 @@ jobs:
         python-version: ["3.10", "3.12"]
     steps:
       - uses: actions/checkout@v7
-      - uses: actions/setup-python@v6
+      - uses: actions/setup-python@v7
         with:
           python-version: ${{ matrix.python-version }}
           cache: pip

{hermes_github_app_plugin-0.2.0 → hermes_github_app_plugin-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: hermes-github-app-plugin
-Version: 0.2.0
+Version: 0.3.1
 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
@@ -43,6 +43,7 @@ Environment variables with the same meaning are also supported:
 - `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.
 
@@ -102,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:
@@ -135,8 +165,8 @@ Before the first release, configure PyPI Trusted Publishing for this repository
 Release example:
 
 ```bash
-git tag 0.2.0
-git push origin 0.2.0
+git tag 0.3.1
+git push origin 0.3.1
 ```
 
 Tags like `v0.1.0`, `0.1`, or `0.1.0rc1` will not publish.

{hermes_github_app_plugin-0.2.0 → hermes_github_app_plugin-0.3.1}/README.md

@@ -24,6 +24,7 @@ Environment variables with the same meaning are also supported:
 - `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.
 
@@ -83,6 +84,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:
@@ -116,8 +146,8 @@ Before the first release, configure PyPI Trusted Publishing for this repository
 Release example:
 
 ```bash
-git tag 0.2.0
-git push origin 0.2.0
+git tag 0.3.1
+git push origin 0.3.1
 ```
 
 Tags like `v0.1.0`, `0.1`, or `0.1.0rc1` will not publish.

{hermes_github_app_plugin-0.2.0 → hermes_github_app_plugin-0.3.1}/plugin.yaml

@@ -1,5 +1,5 @@
 name: github-app
-version: 0.1.0
+version: 0.3.1
 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:
@@ -26,5 +26,8 @@ requires_env:
     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-0.2.0 → hermes_github_app_plugin-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hermes-github-app-plugin"
-version = "0.2.0"
+version = "0.3.1"
 description = "Hermes plugin for per-agent GitHub App identity, gh/git wrappers, and GitHub App-aware tools."
 readme = "README.md"
 requires-python = ">=3.10"

{hermes_github_app_plugin-0.2.0/src/hermes_github_app_plugin → hermes_github_app_plugin-0.3.1}/skills/github-app-workflow/SKILL.md

@@ -36,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-0.2.0 → hermes_github_app_plugin-0.3.1}/src/hermes_github_app_plugin/auth.py

@@ -12,9 +12,10 @@ from urllib.parse import urlparse
 import httpx
 import jwt
 
-from .config import GitHubAppConfig
+from .config import NONO_PLACEHOLDER, GitHubAppConfig
 
 _MIN_REDACT_LENGTH = 8
+_BROKERED_TOKEN_LIFETIME = timedelta(hours=1)
 
 
 @dataclass(frozen=True)
@@ -26,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:
@@ -48,7 +50,13 @@ class GitHubAppAuth:
         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_PLACEHOLDER
         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")
@@ -67,6 +75,26 @@ class GitHubAppAuth:
         ):
             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_PLACEHOLDER,
+            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/{installation_id}/access_tokens",
             headers={
@@ -79,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=installation_id,
             client_id=self._config.client_id,
             app_slug=self._config.app_slug,
         )
-        self._cached_tokens[installation_id] = token
-        return token
 
     def app_request(
         self,
@@ -125,6 +151,7 @@ class GitHubAppAuth:
                 "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},
@@ -197,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(),
     }
 

{hermes_github_app_plugin-0.2.0 → hermes_github_app_plugin-0.3.1}/src/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:
@@ -38,6 +44,12 @@ def register_cli(parser: argparse.ArgumentParser) -> None:
         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"
@@ -134,6 +146,15 @@ 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(
@@ -151,7 +172,11 @@ def _setup(args: argparse.Namespace) -> int:
             non_interactive=bool(args.non_interactive),
         ),
         "installation_ids": installation_ids,
-        "private_key_path": _value_or_prompt(
+        "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",
@@ -166,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:
@@ -189,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(repo=repo, force_refresh=True)
-            checks.append(("installation token minted", True, token.redacted))
+            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:
@@ -230,6 +253,35 @@ 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)
@@ -258,6 +310,12 @@ def _token(repo: str | None, *, json_output: bool) -> int:
         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
 
 

{hermes_github_app_plugin-0.2.0 → hermes_github_app_plugin-0.3.1}/src/hermes_github_app_plugin/config.py

@@ -11,6 +11,14 @@ 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",)
+# Named so Hermes's plugin scanner doesn't read `<...>TOKEN = "<20+ chars>"` as a hardcoded secret
+# and refuse the install; the old name stays as an alias for imports.
+NONO_PLACEHOLDER = "nono-phantom-github-app"
+NONO_PHANTOM_TOKEN = NONO_PLACEHOLDER
+
 
 class ConfigurationError(RuntimeError):
     """Raised when GitHub App configuration is missing or invalid."""
@@ -18,7 +26,10 @@ 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
@@ -27,6 +38,7 @@ class GitHubAppConfig:
     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."""
@@ -118,6 +130,21 @@ def _parse_installation_ids(raw: Any) -> dict[str, str]:
     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:
@@ -159,7 +186,16 @@ def load_config() -> GitHubAppConfig:
     if not installation_id:
         # Use a deterministic fallback for commands that cannot infer an OWNER/REPO.
         installation_id = next(iter(installation_ids.values()))
-    private_key, private_key_source = _read_private_key(section)
+    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,
@@ -169,4 +205,5 @@ def load_config() -> GitHubAppConfig:
         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-0.2.0 → hermes_github_app_plugin-0.3.1/src/hermes_github_app_plugin}/skills/github-app-workflow/SKILL.md

@@ -36,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-0.2.0 → hermes_github_app_plugin-0.3.1}/src/hermes_github_app_plugin/tools.py

@@ -42,6 +42,7 @@ def github_app_status(params: dict[str, Any], **_: Any) -> str:
             "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",
         }

hermes_github_app_plugin-0.3.1/tests/conftest.py

@@ -0,0 +1,18 @@
+"""Shared test isolation: never read the developer's real Hermes config or GitHub App env."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import pytest
+
+
+@pytest.fixture(autouse=True)
+def isolated_environment(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("HERMES_HOME", str(tmp_path / "isolated-hermes-home"))
+    for name in list(os.environ):
+        if name.startswith(("GITHUB_APP_", "GITHUB_API_URL")):
+            monkeypatch.delenv(name)
+    for name in ("HTTPS_PROXY", "https_proxy"):
+        monkeypatch.delenv(name, raising=False)