hermes-agent 0.18.2 → 0.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/SECURITY.md CHANGED
@@ -1,184 +1,337 @@
1
- # Security notes for the npm postinstall script
2
1
 
3
- This package intentionally includes a `postinstall` script:
2
+ # Security policy
4
3
 
5
- ```json
6
- {
7
- "scripts": {
8
- "postinstall": "node scripts/postinstall.js"
9
- }
10
- }
11
- ```
12
-
13
- Install scripts deserve careful review because they execute automatically during
14
- `npm install`. This document explains exactly why this package has one, what it
15
- does, and what it does not do.
16
-
17
- ## Why postinstall exists
18
-
19
- `hermes-agent` on npm is an unofficial small Node.js bridge for the upstream
20
- Python project:
4
+ ## Supported versions
21
5
 
22
- https://github.com/NousResearch/Hermes-Agent
6
+ Only the latest published `hermes-agent` npm release receives bridge security
7
+ updates.
23
8
 
24
- This npm bridge is not affiliated with, endorsed by, sponsored by, or maintained
25
- by Nous Research. See [DISCLAIMER.md](DISCLAIMER.md) and [NOTICE](NOTICE) for
26
- the project attribution and legal notice.
9
+ | Version | Status | Deployment model |
10
+ | --- | --- | --- |
11
+ | Latest published `>=0.20.0` | Supported | Release-pinned Git checkout and package-local `uv`/Python runtime |
12
+ | Older `>=0.20.0` | Unsupported | Same deployment model without current bridge fixes |
13
+ | `<0.20.0` | Unsupported | Legacy system-Python and PyPI installation |
27
14
 
28
- The actual Hermes Agent runtime is distributed as the Python package
29
- `hermes-agent`. The npm package provides convenient global commands:
15
+ Security fixes in upstream Hermes Agent become available to this channel after
16
+ upstream publishes a GitHub Release and the matching npm bridge passes its
17
+ release checks. The native rolling channel can receive upstream commits sooner,
18
+ with the different trust boundary described below.
30
19
 
31
- ```bash
32
- hermes
33
- hermes-agent
34
- ```
20
+ ## Reporting a vulnerability
35
21
 
36
- The canonical npm package is `hermes-agent`. The package `hermesagent` is an
37
- alias manifest for users who search for the name without the hyphen. npm blocks
38
- publishing the unscoped `hermesagent` package because the name is too similar to
39
- `hermes-agent`; a scoped alias such as `@wyrtensi/hermesagent` can be published
40
- separately if needed.
22
+ Report vulnerabilities in this npm bridge through GitHub private vulnerability
23
+ reporting:
41
24
 
42
- The `postinstall` step installs the matching Python package version so that a
43
- single command prepares the npm wrapper and the Python runtime:
25
+ https://github.com/wyrtensi/hermes-agent-npm/security/advisories/new
44
26
 
45
- ```bash
46
- npm install -g hermes-agent
47
- ```
27
+ Include the npm version, operating system and architecture, affected command or
28
+ lifecycle step, impact, and reproduction details. Do not open a public issue
29
+ for an untriaged vulnerability.
48
30
 
49
- Without `postinstall`, users would need to run a second command manually:
31
+ Report vulnerabilities in Hermes Agent runtime behavior to upstream:
50
32
 
51
- ```bash
52
- python -m pip install --upgrade hermes-agent==<npm package version>
53
- ```
54
-
55
- ## Exact behavior
56
-
57
- The script is located at:
58
-
59
- ```text
60
- scripts/postinstall.js
61
- ```
33
+ https://github.com/NousResearch/hermes-agent/security
62
34
 
63
- It performs these steps:
35
+ Use the public bridge issue tracker only for non-sensitive installation and
36
+ compatibility bugs:
64
37
 
65
- 1. Finds an available Python 3 interpreter.
66
- - On Windows it tries `py -3`, then `python`, then `python3`.
67
- - On macOS and Linux it tries `python3`, then `python`.
68
- 2. Verifies that the interpreter is Python 3.11 or newer.
69
- 3. Builds the pinned Python package spec from `package.json`, for example:
38
+ https://github.com/wyrtensi/hermes-agent-npm/issues
70
39
 
71
- ```bash
72
- hermes-agent==<npm package version>
73
- ```
40
+ ## Security scope
74
41
 
75
- 4. Runs:
42
+ This policy covers:
76
43
 
77
- ```bash
78
- python -m pip install --upgrade hermes-agent==<npm package version>
79
- ```
44
+ - the npm command shims and `hermes-npm` release-channel commands;
45
+ - the explicit `hermes-npm migrate upstream` handoff and its preflight checks;
46
+ - npm lifecycle provisioning in `scripts/postinstall.js`;
47
+ - `uv` asset selection, download, checksum verification, and extraction;
48
+ - GitHub Release metadata synchronization and npm publishing workflows;
49
+ - confinement of npm lifecycle installer-created files to the installed npm
50
+ package.
80
51
 
81
- 5. If that install fails, retries with:
52
+ The upstream agent, its tools and integrations, model providers, and actions a
53
+ user authorizes the agent to perform are separate trust domains.
82
54
 
83
- ```bash
84
- python -m pip install --upgrade --user hermes-agent==<npm package version>
85
- ```
55
+ ## Security invariants
86
56
 
87
- 6. Exits with a non-zero status if both attempts fail.
57
+ The bridge is intended to preserve these properties:
88
58
 
89
- The script also checks whether the related alias package is already installed
90
- globally. If `hermes-agent` is installed and a user installs `hermesagent`, or
91
- the other way around, it prints a warning explaining that both packages point to
92
- the same Hermes Agent runtime. It does not uninstall packages or modify npm
93
- global state.
59
+ 1. A missing package-local runtime never falls back to a system Python.
60
+ 2. Installer subprocesses use executable/argument arrays and do not evaluate
61
+ downloaded shell or PowerShell scripts.
62
+ 3. The downloaded `uv` archive must match a SHA-256 digest committed in this
63
+ repository before any executable is extracted.
64
+ 4. Release installation fetches the recorded Git tag and verifies that it
65
+ resolves to the full commit SHA recorded in `package.json`.
66
+ 5. npm lifecycle installer deletion/replacement targets must resolve inside
67
+ the npm package.
68
+ 6. Python, the virtual environment, the Git checkout, and temporary caches
69
+ created by npm lifecycle installation remain inside the npm package.
70
+ 7. `hermes update` is passed to the upstream console entrypoint unchanged; the
71
+ bridge does not falsely represent rolling source as npm-attested source.
72
+ 8. A release-channel reset returns tracked upstream source to the commit pinned
73
+ by npm without deleting untracked files with `git clean`.
74
+ 9. npm publication is blocked unless Windows, macOS, and Linux runtime smoke
75
+ jobs succeed for the same upstream tag, commit, and version.
76
+ 10. The upstream installer is never run during npm lifecycle provisioning.
77
+ A handoff requires `migrate upstream --yes`, uses the script from the
78
+ verified Release checkout, pins the same full commit, verifies the new
79
+ checkout/venv, and removes npm ownership only after that verification.
94
80
 
95
- ## What the script does not do
81
+ A change that violates one of these invariants is security-relevant even if no
82
+ exploit has yet been demonstrated.
96
83
 
97
- The `postinstall` script does not:
84
+ ## Why `postinstall` exists
98
85
 
99
- - read SSH keys, npm tokens, GitHub tokens, or other secrets
100
- - inspect project source files outside this npm package
101
- - upload telemetry or analytics
102
- - call custom remote shell scripts
103
- - run `curl | sh`, PowerShell downloads, or arbitrary downloaded code
104
- - modify shell profiles such as `.bashrc`, `.zshrc`, or PowerShell profiles
105
- - add startup items, services, scheduled tasks, or background daemons
106
- - change Git configuration
107
- - install npm packages dynamically
86
+ Upstream stopped publishing new PyPI releases. The bridge therefore provisions
87
+ the runtime during npm installation so this remains sufficient:
108
88
 
109
- Its network activity is limited to the normal package downloads performed by
110
- `pip` from the user's configured Python package index.
111
-
112
- ## Publishing security
89
+ ```bash
90
+ npm install --global hermes-agent
91
+ ```
113
92
 
114
- The npm package is published by GitHub Actions through npm trusted publishing
115
- with OpenID Connect. The publish workflow is allowed to publish only from:
93
+ Lifecycle scripts execute with the installing user's permissions. Review the
94
+ package before installation when that is not an acceptable trust decision; the
95
+ audit procedure below avoids lifecycle execution.
96
+
97
+ ## Exact install behavior
98
+
99
+ `scripts/postinstall.js` and `lib/uv-installer.js`:
100
+
101
+ 1. validate the upstream repository, Release tag, and full commit SHA stored in
102
+ `package.json`;
103
+ 2. require Git and initialize a shallow package-local checkout;
104
+ 3. fetch the exact tag and verify its peeled commit before checkout;
105
+ 4. select a pinned Astral `uv` asset for Windows, macOS, or Linux, including
106
+ supported architecture and Linux libc variants;
107
+ 5. enforce compressed and extracted size limits, verify SHA-256, and extract
108
+ only `uv`/`uv.exe` with Node.js;
109
+ 6. provision managed Python 3.11 under `runtime/python/`;
110
+ 7. create `runtime/hermes-agent/venv/` and run
111
+ `uv sync --locked --extra all --no-dev` using upstream project configuration
112
+ and `uv.lock`;
113
+ 8. remove the temporary dependency cache and write a runtime identity marker.
114
+
115
+ The installer does not invoke an upstream installer script, a system package
116
+ manager, system Python/pip, `curl`, `tar`, PowerShell download evaluation, or
117
+ `HERMES_NIX_BUILD`.
118
+
119
+ This statement applies to npm lifecycle provisioning. The optional upstream
120
+ handoff described below intentionally invokes the official installer only
121
+ after an explicit command and confirmation.
122
+
123
+ ## Update trust boundaries
124
+
125
+ The bridge deliberately provides two update channels.
126
+
127
+ ### npm Release channel
128
+
129
+ `hermes-npm check` reads the npm `latest` dist-tag from the canonical public
130
+ registry. When a newer package exists, `hermes-npm update` installs the exact
131
+ version that was checked from that same registry; it does not perform a second
132
+ mutable `@latest` resolution. If the npm package is already current, the command
133
+ resets a clean rolling checkout in place to the tag/commit pinned by the
134
+ installed npm version. A dirty or damaged checkout is replaced transactionally
135
+ with rollback where possible.
136
+
137
+ npm integrity and provenance cover the bridge tarball and its pinned Release
138
+ identity. They do not include dependencies downloaded during lifecycle
139
+ execution.
140
+
141
+ ### Native rolling channel
142
+
143
+ `hermes update` and `hermes update --check` run the unmodified upstream updater.
144
+ The updater normally follows upstream `main`, mutates the package-local checkout
145
+ and venv, and may install managed tools under `HERMES_HOME` (currently a managed
146
+ `uv` under `HERMES_HOME/bin`). After a rolling update, npm provenance no longer
147
+ attests to the live upstream source.
148
+
149
+ Use `hermes-npm status --json` to distinguish `npm-release`, `upstream-native`,
150
+ and `missing` runtime states. Use `hermes-npm update` to return to the npm
151
+ Release boundary.
152
+
153
+ ### Upstream-managed handoff
154
+
155
+ `hermes-npm migrate upstream` is a read-only plan. The `--yes` form transfers
156
+ ownership to an upstream-managed installation. It does not download or
157
+ evaluate the mutable installer endpoint: it runs `scripts/install.sh` or
158
+ `scripts/install.ps1` from the package's verified, Release-pinned checkout and
159
+ passes the same full commit with forced pinning, non-interactive mode, and
160
+ setup skipped.
161
+
162
+ Before execution the bridge requires an `npm-release` runtime, refuses an
163
+ external target that is not a Git checkout when it already exists, validates
164
+ an existing checkout's origin against the official upstream repository,
165
+ refuses a dirty target, and refuses `HERMES_HOME` inside the npm package. After
166
+ installation it verifies a clean exact Git HEAD and the platform venv console
167
+ executable. npm uninstall is
168
+ started only after these checks pass. The official installer's `path` stage is
169
+ then re-run from the verified external checkout, which repairs command links
170
+ if global npm removal shared their bin directory. If installation or
171
+ verification fails, the npm package remains the active owner.
172
+
173
+ The handoff is intentionally not side-by-side. The official installer may
174
+ write outside the npm package, manage `HERMES_HOME/bin`, user PATH, Python,
175
+ Node/browser prerequisites, configuration templates, and bundled skills. Its
176
+ behavior is upstream's trust domain after the user explicitly elects to leave
177
+ npm ownership. Interactive setup, gateway startup, and Desktop building are
178
+ disabled by the bridge invocation.
179
+
180
+ ## Network and configuration boundaries
181
+
182
+ Installation may contact:
183
+
184
+ - GitHub for the pinned upstream tag/commit and pinned Astral `uv` asset;
185
+ - Astral-managed Python distribution endpoints used by `uv`;
186
+ - package indexes and artifact hosts referenced by upstream project
187
+ configuration and `uv.lock`.
188
+
189
+ `hermes-npm check` and the update it authorizes are bound to
190
+ `https://registry.npmjs.org`; npm can still honor applicable proxy, CA, and
191
+ authentication settings. Git commands may honor user proxy, credential-helper,
192
+ and CA configuration. Git is run with terminal credential prompts disabled and
193
+ inherited `GIT_DIR`, `GIT_WORK_TREE`, and `GIT_INDEX_FILE` removed.
194
+
195
+ Bootstrap operations disable ambient `uv` configuration so Python and cache
196
+ locations remain package-local. Dependency synchronization intentionally uses
197
+ the checked-out upstream project's `uv` configuration and lockfile.
198
+
199
+ ## Filesystem boundary
200
+
201
+ npm installation creates or modifies only these package-local locations:
116
202
 
117
203
  ```text
118
- GitHub owner: wyrtensi
119
- GitHub repository: hermes-agent-npm
120
- Workflow file: npm-publish.yml
121
- Allowed npm action: npm publish
204
+ .hermes-agent-runtime.json
205
+ .uv_bin/
206
+ runtime/cache/
207
+ runtime/python/
208
+ runtime/hermes-agent/
122
209
  ```
123
210
 
124
- The workflow does not use a long-lived npm publish token. npm package settings
125
- should use `Require two-factor authentication and disallow tokens` so manual
126
- publishes require 2FA and traditional npm tokens cannot publish this package.
127
- Trusted publishing continues to work because it uses short-lived OIDC
128
- credentials issued for the configured workflow.
129
-
130
- ## Why the package is version-pinned
131
-
132
- The npm package version and the Python package version are kept in sync. The
133
- postinstall script installs the exact matching Python version:
134
-
135
- ```bash
136
- hermes-agent==<npm package version>
137
- ```
211
+ It does not modify system Python, shell profiles, the global `PATH` beyond
212
+ normal npm command shims, services, scheduled tasks, or Git configuration.
138
213
 
139
- This avoids silently installing a newer Python Hermes runtime than the npm
140
- wrapper was published for.
214
+ Running upstream Hermes is different from installing the bridge. Upstream may
215
+ write configuration, credentials, logs, backups, managed tools, and runtime
216
+ state under `HERMES_HOME` and may start user-requested gateways or integrations.
217
+ Uninstalling npm does not remove that user data.
141
218
 
142
- Release automation uses PyPI as the source of truth for the latest Hermes Agent
143
- version because this package installs the upstream Python package from PyPI.
144
- The upstream Git repository may update its source tree or tags on a different
145
- timeline than PyPI package publication.
219
+ Do not run upstream `hermes uninstall` while npm owns the runtime. Upstream
220
+ derives its project root from the running Python package, so in npm mode it can
221
+ remove the checkout inside `node_modules` without removing the npm package or
222
+ its marker. Use scope-appropriate `npm uninstall` instead. After a completed
223
+ handoff, upstream owns the checkout and its native uninstaller is appropriate.
146
224
 
147
- Scheduled GitHub Actions runs are best-effort and can be delayed or skipped by
148
- GitHub. The publish workflow checks several times per hour, but manual
149
- `workflow_dispatch` remains available when a release needs to be published
150
- immediately.
225
+ For a project-local installation, `hermes-npm update` invokes `npm install` in
226
+ the owning project and may update its dependency manifest and lockfile according
227
+ to normal npm behavior.
151
228
 
152
- ## How to audit locally
229
+ ## Publishing security
153
230
 
154
- Review the install script:
231
+ The publish workflow:
232
+
233
+ - polls the latest non-draft, non-prerelease upstream GitHub Release;
234
+ - resolves annotated tags to their final commit and records the full SHA;
235
+ - refuses to overwrite an npm version whose published tag/commit identity
236
+ differs;
237
+ - fails if the upstream Release changes between prepare, smoke, and publish;
238
+ - runs unit, package, native-update-check, and full runtime smoke tests on
239
+ Windows, macOS, and Linux;
240
+ - pins third-party GitHub Actions by commit SHA;
241
+ - grants `id-token: write` only to the publish job;
242
+ - publishes through npm trusted publishing with provenance and no long-lived
243
+ npm token in the workflow.
244
+
245
+ Repository and npm settings should continue to protect the default branch,
246
+ require review of workflow and checksum changes, require 2FA for maintainers,
247
+ and disallow legacy publish tokens after trusted publishing is configured.
248
+
249
+ ## Severity guidance
250
+
251
+ Examples of bridge findings that should be reported privately include:
252
+
253
+ - **Critical:** bypass of publish identity/provenance controls, or remote code
254
+ execution before pinned artifact/commit verification;
255
+ - **High:** command injection, installer path escape or arbitrary overwrite,
256
+ checksum/tag-to-commit verification bypass, or credential exfiltration;
257
+ - **Medium:** a reliable integrity downgrade, unsafe update-channel confusion,
258
+ or proxy/configuration handling that redirects executable content contrary to
259
+ documented verification;
260
+ - **Low:** hardening gaps with limited impact, such as avoidable information
261
+ disclosure or denial of service requiring local access.
262
+
263
+ Final severity depends on reachability, required privileges, user interaction,
264
+ and impact; these examples are not automatic ratings.
265
+
266
+ ## Accepted risks and limitations
267
+
268
+ - npm lifecycle execution downloads and executes a verified `uv` binary and
269
+ installs code selected by the upstream lockfile. `--ignore-scripts` is the
270
+ supported opt-out.
271
+ - The upstream repository, GitHub Release/tag administration, Astral release
272
+ process, Python artifact indexes, npm, GitHub Actions, and applicable local
273
+ Git/npm proxy, CA, credential, and authentication configuration remain
274
+ supply-chain trust dependencies.
275
+ - The commit pin prevents tag retargeting from silently changing a published
276
+ npm version, but this bridge does not independently verify a Git tag's GPG or
277
+ SSH signature.
278
+ - Native rolling updates intentionally follow a mutable upstream branch and
279
+ can move beyond reviewed Releases or create files outside the npm package
280
+ under `HERMES_HOME`.
281
+ - Host compromise, malicious npm/Git configuration, or write access to the
282
+ installed package can invalidate local guarantees.
283
+ - Only the latest npm bridge release is maintained; users must update to
284
+ receive bridge fixes.
285
+ - Windows can prevent replacement while Hermes processes hold runtime files;
286
+ users should stop agents, gateways, and desktop processes before npm-channel
287
+ replacement.
288
+ - The optional handoff expands the filesystem and tool-management boundary to
289
+ the official upstream installer. A failure after official verification but
290
+ during npm uninstall can temporarily leave both deployments present; remove
291
+ the npm package with the exact command shown in the handoff plan.
292
+
293
+ ## Out of scope
294
+
295
+ - vulnerabilities solely in upstream Hermes Agent, its bundled skills, or its
296
+ third-party dependencies, unless the bridge introduces or amplifies them;
297
+ - model-provider behavior, prompt injection against an intentionally running
298
+ agent, and actions explicitly authorized through upstream tools;
299
+ - vulnerabilities in npm, GitHub, Git, Astral infrastructure, Python package
300
+ indexes, or the operating system itself;
301
+ - unsupported bridge versions and manually modified or forked runtime source.
302
+
303
+ Reports that reveal a bridge-specific exploit path through an otherwise
304
+ out-of-scope component are still welcome.
305
+
306
+ ## Auditing before installation
307
+
308
+ Fetch and unpack without running lifecycle scripts:
155
309
 
156
310
  ```bash
157
311
  npm pack hermes-agent
158
- tar -xzf hermes-agent-*.tgz
159
- cat package/scripts/postinstall.js
160
- cat package/lib/python-launcher.js
312
+ npm install --ignore-scripts ./hermes-agent-*.tgz
161
313
  ```
162
314
 
163
- Install without running lifecycle scripts:
315
+ Review at minimum:
164
316
 
165
- ```bash
166
- npm install -g hermes-agent --ignore-scripts
317
+ ```text
318
+ package/package.json
319
+ package/scripts/postinstall.js
320
+ package/lib/uv-installer.js
321
+ package/lib/python-launcher.js
322
+ package/lib/npm-channel.js
323
+ package/lib/upstream-migration.js
167
324
  ```
168
325
 
169
- Then install the Python runtime manually:
326
+ Compare `hermesAgent.upstreamGitTag` and `hermesAgent.upstreamCommit` with the
327
+ official upstream Release. After review, provision with:
170
328
 
171
329
  ```bash
172
- python -m pip install --upgrade hermes-agent==<npm package version>
330
+ npm rebuild hermes-agent
331
+ # or, for a global installation:
332
+ npm rebuild --global hermes-agent
173
333
  ```
174
334
 
175
- ## Why security scanners flag this package
176
-
177
- Some scanners flag every npm package with `preinstall`, `install`, or
178
- `postinstall` scripts because those scripts can execute code automatically.
179
- That warning is useful and should not be ignored.
180
-
181
- For this package, the install script is intentionally small and exists only to
182
- install the pinned Python Hermes Agent runtime. Users who prefer not to run npm
183
- lifecycle scripts can use `--ignore-scripts` and install the Python package
184
- manually.
335
+ Security scanners are expected to flag the lifecycle script. Treat that as a
336
+ prompt to review the explicit download, verification, and execution boundary,
337
+ not as proof that the lifecycle step is safe or malicious by itself.
@@ -0,0 +1,5 @@
1
+ #!/usr/bin/env node
2
+
3
+ const { runNpmChannel } = require("../lib/npm-channel");
4
+
5
+ runNpmChannel(process.argv.slice(2));