From e2cc9fcfd5b30fad748c510f75ed415dc390bce8 Mon Sep 17 00:00:00 2001 From: Pavel-Tk <110731619+Pavel-Tk@users.noreply.github.com> Date: Thu, 3 Sep 2026 18:43:34 +0000 Subject: [PATCH] Document the current substrate plugin as the 0.21.x install target Signed-off-by: Pavel-Tk <110731619+Pavel-Tk@users.noreply.github.com> --- CHANGELOG.md | 1 + COMPATIBILITY.md | 15 ++++++++++++- README.md | 6 ++++-- SECURITY.md | 9 +++++++- docs/extraction-manifest.json | 16 +++++++------- docs/public-boundary.md | 26 +++++++++++++++++------ docs/threat-model.md | 3 ++- scripts/verify_public_plugin_candidate.py | 25 +++++----------------- src/substrate_wiki/README.md | 5 +++++ 9 files changed, 67 insertions(+), 39 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b3111be..0b4dec9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,7 @@ ## Unreleased +- Add the current `substrate` plugin (`plugins/substrate`, version 0.2.x) for Hermes 0.21.x: one-prompt `hermes plugins install` of the subdirectory, self-contained RFC 8628 device onboarding on first use (browser approval link, background polling, key stored privately in the active profile's `.env`), `memory_search`/`memory_expand`/`memory_evidence` tools, verified TLS with bundled public ISRG root anchors, and health-gated legacy cutover. The legacy `substrate_wiki` 2.0.x provider below remains only for existing Hermes 0.20.x installations. - Let hosted onboarding validate only the history replay contract, so a setup-and-upload MVP does not need to advertise entity retrieval features. - Add an explicit `SUBSTRATE_WIKI_ORIGIN` override for isolated v5 import tests; the hosted origin remains the default. diff --git a/COMPATIBILITY.md b/COMPATIBILITY.md index 4de92dd..9f2083b 100644 --- a/COMPATIBILITY.md +++ b/COMPATIBILITY.md @@ -2,7 +2,20 @@ Compatibility has three independent axes: Hermes host, hosted Substrate capability contract, and plugin version. -## Certified matrix +## Current install target + +The current Hermes plugin is [`plugins/substrate`](plugins/substrate) (`substrate`, version +0.2.x). It is the only path an installing agent should select from this repository, and it is +certified for Hermes **0.21.x**. It installs with +`hermes plugins install Substrate-memory/Substrate-memory-plugins/plugins/substrate --no-enable`, +runs RFC 8628 device onboarding by itself, and registers `memory_search`, `memory_expand`, +and `memory_evidence`. It never requires a pre-existing API key. + +The table below is the **legacy** `substrate_wiki` provider record. It does not apply to the +current `substrate` plugin, and it must not be used to reject a Hermes 0.21.x install: the +legacy rows exist only for existing 0.20.x installations and migration testing. + +## Legacy certified matrix (substrate_wiki) | Plugin | Hermes | Required hosted capabilities | Status | |---|---|---|---| diff --git a/README.md b/README.md index f2d2a0d..2f9cf42 100644 --- a/README.md +++ b/README.md @@ -64,8 +64,10 @@ editor, and evidence. ## Legacy compatibility -`src/substrate_wiki` and its release tooling are retained for existing installations and -migration tests. It is not the current install target. Do not run +Hermes 0.21.x is certified for the current `substrate` plugin. The legacy +`src/substrate_wiki` provider and its release tooling are retained for existing Hermes 0.20.x +installations and migration tests. It is not the current install target, and its +compatibility rows in `COMPATIBILITY.md` apply only to 0.20.x. Do not run `scripts/install_hermes_plugin.py` for the prompt above. Legacy packaging state remains unchanged: `v2.0.5` is not published yet, its historical URL would contain `releases/download/v2.0.5`, and its unpublished checksum marker remains diff --git a/SECURITY.md b/SECURITY.md index 29ec846..749f849 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -2,7 +2,14 @@ ## Supported versions -The standalone `v2.0.0`, `v2.0.1`, `v2.0.2`, `v2.0.3`, `v2.0.4`, and `v2.0.5` releases target Hermes 0.20.x and the hosted service at `https://app.trysubstrate.co`. +The current supported install target is the `substrate` plugin (0.2.x) in +[`plugins/substrate`](plugins/substrate), certified for Hermes 0.21.x. It is the plugin an +agent should install from this repository; it self-onboards and never requires a pasted API +key. + +The standalone `v2.0.0` through `v2.0.5` releases listed below are the **legacy** +`substrate_wiki` provider for Hermes 0.20.x and the hosted service at +`https://app.trysubstrate.co`. They remain documented for existing installations only. Candidate CI artifacts are not supported releases. ## Report a vulnerability diff --git a/docs/extraction-manifest.json b/docs/extraction-manifest.json index c68422d..8adec59 100644 --- a/docs/extraction-manifest.json +++ b/docs/extraction-manifest.json @@ -59,13 +59,13 @@ "class": "standalone_repository_policy_or_test", "path": "CHANGELOG.md", "reason": "Required only by the independent public repository.", - "sha256": "5c3f024118fd7c5f492d5fc52af76b0fe1fa6bf4ee1b5ccd94b3bb34cd08a114" + "sha256": "46459da2eddfa84cae2298ef5b61cfbb6298ce9f6e9048173a7577a33fb0a5a8" }, { "class": "standalone_repository_policy_or_test", "path": "COMPATIBILITY.md", "reason": "Required only by the independent public repository.", - "sha256": "9e2f30159b85caf7682e20d5c8abcbb1881eb2a624565ca565b93353d4bb624f" + "sha256": "ba5e0559b396a1618f296b6ac8824e78431cde706a8fc8774c5e16273e121768" }, { "class": "standalone_repository_policy_or_test", @@ -77,13 +77,13 @@ "class": "standalone_repository_policy_or_test", "path": "README.md", "reason": "Required only by the independent public repository.", - "sha256": "b92ac5001e533722bd27713a39be232f25d282324179feb3e9315f1524e9c966" + "sha256": "7187a43e2c9936018e4953ae805715f49fc2c0d94fa1aa708263795d7f8d590b" }, { "class": "standalone_repository_policy_or_test", "path": "SECURITY.md", "reason": "Required only by the independent public repository.", - "sha256": "e4457fb9df863d239120b4b4d05db31c56e5a73b4331c6bf959ed12d1f06410f" + "sha256": "7b819f70e96bc4c07db083b416584dc66f6773c80746874a17f0bc5904e4fb2e" }, { "class": "standalone_repository_policy_or_test", @@ -113,7 +113,7 @@ "class": "standalone_repository_policy_or_test", "path": "docs/threat-model.md", "reason": "Required only by the independent public repository.", - "sha256": "a0f2ffd82cd29fe3c5f551134a019d815c7df6b1198bfc95dfe456d6005c46c4" + "sha256": "84c3f829b2d854690c35c6fd553ecfd25bf1ebdec428a2c167c75a1b1e0857b3" }, { "class": "standalone_repository_policy_or_test", @@ -335,7 +335,7 @@ { "class": "boundary", "destination": "docs/public-boundary.md", - "destination_sha256": "c9228e2abd22a8af558cd272988435c1caa69ad79c625cb08c8ef32e639eb0f3", + "destination_sha256": "fd5e6965cda0decaf7ef539ec53e24bcbca4de16b591d029031402ef2217b62a", "source": "docs/plugin/public-boundary.md", "source_sha256": "917feee8c785f9ae14a474e9e948079f52084700b1dfff6fe479cc3627adc0c1", "transformation": "modified_for_standalone" @@ -455,7 +455,7 @@ { "class": "build-and-install", "destination": "scripts/verify_public_plugin_candidate.py", - "destination_sha256": "b67230ca55e11a4e122341d8c508047f8b7dc9f5a1b0e1b51e24b163daa27989", + "destination_sha256": "677d119930eadc663cc8ef64587890add8a0c7db4ddd81692d50a061953d2829", "source": "scripts/verify_public_plugin_candidate.py", "source_sha256": "4130935d530075fce1758e2e89bd5d973a722e2293b5b1058cfe0d17f326172b", "transformation": "modified_for_standalone" @@ -463,7 +463,7 @@ { "class": "plugin-package", "destination": "src/substrate_wiki/README.md", - "destination_sha256": "0c555fe0adf4f0eb7112f2897ba0ce0fb22e3d15b928608c4a67447be98c3c23", + "destination_sha256": "72195739860b3d64338cff133e31a1cdaefe6cd6e09bcebc9d8c5e1f27e987b3", "source": "hermes-plugin/substrate_wiki/README.md", "source_sha256": "21b6e60ef34e408fd87570334ba6d2811d2a9ea3c95d512e4d625f958b1cb0dc", "transformation": "modified_for_standalone" diff --git a/docs/public-boundary.md b/docs/public-boundary.md index fab6b86..1a50bc9 100644 --- a/docs/public-boundary.md +++ b/docs/public-boundary.md @@ -1,9 +1,20 @@ # Public plugin boundary -This repository is the publication-approved MIT-licensed source candidate for the Hermes -`substrate_wiki` plugin. Public/release status becomes factual only after GitHub readback. +This repository publishes the current Hermes 0.21.x `substrate` plugin in +[`plugins/substrate`](../plugins/substrate) and retains the MIT-licensed legacy +`substrate_wiki` source below. Public/release status becomes factual only after GitHub +readback. -## Identity +## Identity (current substrate plugin) + +- package/plugin: `substrate` in `plugins/substrate`; +- Hermes host: 0.21.x with native plugin discovery; +- hosted origin: the configured Substrate API origin (default `https://vm-substrate-ar-01.taile961d2.ts.net:10000`); +- credential source: in-plugin RFC 8628 device onboarding storing `SUBSTRATE_API_KEY` in the active profile's `.env`; +- profile state: `$HERMES_HOME/substrate`; +- user-plugin directory: `$HERMES_HOME/plugins/substrate`. + +## Identity (legacy substrate_wiki) - package/provider: `substrate_wiki`; - Hermes configuration: `memory.provider: substrate_wiki`; @@ -24,9 +35,12 @@ runtime source. ## Compatibility and data boundary -Hermes 0.20.x is the target. The plugin connects only to hosted Substrate and fails closed on -origin or capability mismatch. Credentials may not enter source, artifacts, normal config, -logs, errors, receipts, or support material. +Hermes 0.21.x with the current `substrate` plugin in +[`plugins/substrate`](../plugins/substrate) is the current install target; the legacy +`substrate_wiki` rows below document the retained 0.20.x boundary. The plugin connects only +to the configured Substrate origin and fails closed on origin or capability mismatch. +Credentials may not enter source, artifacts, normal config, logs, errors, receipts, or +support material. Future capture begins after account connection. Past direct conversations and explicit saved memories remain local until the user approves historical upload. Group sessions, diff --git a/docs/threat-model.md b/docs/threat-model.md index 6ba1575..a20e222 100644 --- a/docs/threat-model.md +++ b/docs/threat-model.md @@ -17,7 +17,8 @@ ## Trust assumptions - Hosted account authentication and tenant isolation are operated at `app.trysubstrate.co`. -- Hermes 0.20.x invokes current user-plugin discovery and provider lifecycle hooks. +- Hermes 0.21.x invokes the current `substrate` plugin's discovery path, `pre_llm_call`/`post_llm_call` hooks, and native tool registration (see [`plugins/substrate`](../plugins/substrate)). +- Hermes 0.20.x invokes the legacy `substrate_wiki` user-plugin discovery and provider lifecycle hooks. - The operating-system user and `$HERMES_HOME` permissions protect local state. - Published checksums and release custody are verified before installation. diff --git a/scripts/verify_public_plugin_candidate.py b/scripts/verify_public_plugin_candidate.py index b0802ae..4d7b543 100644 --- a/scripts/verify_public_plugin_candidate.py +++ b/scripts/verify_public_plugin_candidate.py @@ -241,12 +241,7 @@ # Hosted-origin and legacy-name references are accepted only at these exact reviewed # file digests. Any byte change re-enables all endpoint and credential-name detectors. -_HOSTED_ONBOARDING_EXACT_ALLOWLIST = {'COMPATIBILITY.md': frozenset({'1f18a49d552f2912872c10b0e41e93ff50ccd923d2fa9c108d35084dc5a5b22c', - '1f8fc410a88c7b410c4e72f4210226629b573a3c7f0cc410bc35939cd2317cfc', - '53d4873064a5d5b1748950c08c0aeaa76a6c00c435e4a8f534a844e4f90aca87', - '67bcb14e4988ed5b49379e93f93fa588e31a068b394a8787d1ea81ba8f6a6c70', - '9e2f30159b85caf7682e20d5c8abcbb1881eb2a624565ca565b93353d4bb624f', - 'e14a7a057ee64449041a2073590641a44cfe648cff696d4d20c58eed9e4509a3'}), +_HOSTED_ONBOARDING_EXACT_ALLOWLIST = {'COMPATIBILITY.md': frozenset({'1f18a49d552f2912872c10b0e41e93ff50ccd923d2fa9c108d35084dc5a5b22c', '1f8fc410a88c7b410c4e72f4210226629b573a3c7f0cc410bc35939cd2317cfc', '53d4873064a5d5b1748950c08c0aeaa76a6c00c435e4a8f534a844e4f90aca87', '67bcb14e4988ed5b49379e93f93fa588e31a068b394a8787d1ea81ba8f6a6c70', '9e2f30159b85caf7682e20d5c8abcbb1881eb2a624565ca565b93353d4bb624f', 'ba5e0559b396a1618f296b6ac8824e78431cde706a8fc8774c5e16273e121768', 'e14a7a057ee64449041a2073590641a44cfe648cff696d4d20c58eed9e4509a3'}), 'README.md': frozenset({'0d74ffbf410fe559478ee6a67e105f275d72d0477c71e86c81531798bc07e599', '20ac49480369c8531e001466a6537a7dae310bbba7e6079bc217a6181e7d69d7', '6361beb1a5153f5dbcfca70740c1905096f3bc32ddfd4cc22157c6576c61b83a', @@ -254,31 +249,21 @@ 'a5285e1800831e754b648f49f1afd8b37858a2353600db497991579de7e4f323', 'b92ac5001e533722bd27713a39be232f25d282324179feb3e9315f1524e9c966', 'cdc48a8f8dbe1d68dfe329d5106c55895c5345924544c2cc4b3d7190c837705b'}), - 'SECURITY.md': frozenset({'48509dbbefd182381675499ff5636df18073411db580b05a1430e5eec1714df7', - '756264bc4dbd9f9df5c6e4bc016545fc1ac0921b384346e40d557706c2137fc5', - '7ef28d44f7b82b765e870434542b5b67facc703e2105a40a233de2e12783852e', - '85320ec1e6a8c655b1f4e278b95c1087a6382bf3141366f1290c0933590f4645', - '99aed8e5a9a712f0fd2d9caa5223f0b332220f98699351565a3bb35a23d2848c', - '9cf9406266336996c57227413514cf97a04eb13264d80fa58c54d325fecf3d9f', - 'd07d0c65e39f0949f91f7a880a4b584b9b57d8ed3c70ca8fd95276d8d525b517', - 'e4457fb9df863d239120b4b4d05db31c56e5a73b4331c6bf959ed12d1f06410f', - 'ef0cdf7a6c2fdc4ec7e781be15122f9b20331769929517a0f3c82ab15363480b'}), + 'SECURITY.md': frozenset({'48509dbbefd182381675499ff5636df18073411db580b05a1430e5eec1714df7', '756264bc4dbd9f9df5c6e4bc016545fc1ac0921b384346e40d557706c2137fc5', '7b819f70e96bc4c07db083b416584dc66f6773c80746874a17f0bc5904e4fb2e', '7ef28d44f7b82b765e870434542b5b67facc703e2105a40a233de2e12783852e', '85320ec1e6a8c655b1f4e278b95c1087a6382bf3141366f1290c0933590f4645', '99aed8e5a9a712f0fd2d9caa5223f0b332220f98699351565a3bb35a23d2848c', '9cf9406266336996c57227413514cf97a04eb13264d80fa58c54d325fecf3d9f', 'd07d0c65e39f0949f91f7a880a4b584b9b57d8ed3c70ca8fd95276d8d525b517', 'e4457fb9df863d239120b4b4d05db31c56e5a73b4331c6bf959ed12d1f06410f', 'ef0cdf7a6c2fdc4ec7e781be15122f9b20331769929517a0f3c82ab15363480b'}), 'docs/api-ownership.json': frozenset({'2fc837c1f89ef9948c9d542f4912f39414a9cd43eb650b1f73f9a2dc49b3ad2e', 'f1894c4653c51c6f02d23194617a3a1e9035d2cbe2b7c282f4cd6fbb26d8b65c'}), 'docs/operation.md': frozenset({'fadd72791e097d878bbfbf338922d568f3c3d47958f26a41f53d3597471988fa'}), 'docs/public-boundary.json': frozenset({'648904170d6c66de6f15cfe51fb494225467730ff5167225d6fd427a6eac3571', '976403a6a802832adddd5ab1ff56fdc2e4e4847a1fe37ea5e6a2d5f106bbbbe2', 'b3c24d1ccff43c274be683020f23661d45faaeb16b842af384d828c6b7968390'}), - 'docs/public-boundary.md': frozenset({'c9228e2abd22a8af558cd272988435c1caa69ad79c625cb08c8ef32e639eb0f3'}), + 'docs/public-boundary.md': frozenset({'c9228e2abd22a8af558cd272988435c1caa69ad79c625cb08c8ef32e639eb0f3', 'fd5e6965cda0decaf7ef539ec53e24bcbca4de16b591d029031402ef2217b62a'}), 'scripts/install_hermes_plugin.py': frozenset({'33adb95c93f478a91991a97f0b9b6a1c9d2cee77e7894ed37fe331a4403b0bb8', '4b34ee40d0d08ef24d03128e1cfc5ef73c69b39ca77b3fff59f4a4133cef76f2', '69af75e4240166896031f3a396fd0b2bdc4d00adbc836d1a4f22019bc6713b75', '72247d3537140098365350020cce29658c0743fee1aa738d7143db82316acce4', '8e37991db874b306045623c5cba39ef995b53b7b6a1a6c6f0253e2ff12c0ebb8', '9f157d5e7e3b8921a01d46f975f574a8955a53c5f554ed61b306a7bdfddd7309'}), - 'src/substrate_wiki/README.md': frozenset({'0c555fe0adf4f0eb7112f2897ba0ce0fb22e3d15b928608c4a67447be98c3c23', - '44a11fda85d6d8170d772beadba2149bd114624479344b69a69cd49634309204', - '88d492b33ee537567bf85b63dcc7a470319212ac377f4857e27e504a3a1a05a3'}), + 'src/substrate_wiki/README.md': frozenset({'0c555fe0adf4f0eb7112f2897ba0ce0fb22e3d15b928608c4a67447be98c3c23', '44a11fda85d6d8170d772beadba2149bd114624479344b69a69cd49634309204', '72195739860b3d64338cff133e31a1cdaefe6cd6e09bcebc9d8c5e1f27e987b3', '88d492b33ee537567bf85b63dcc7a470319212ac377f4857e27e504a3a1a05a3'}), 'src/substrate_wiki/__init__.py': frozenset({'425cd191f723805bed85d965d2d74daeac272dd0660eadf6bac92f1fa02d6f4a', '71c0c19d366759e67c7b999029777295cc8c25503d35fe9cfddc9460bcb34d5a'}), 'src/substrate_wiki/client.py': frozenset({'082164ad24c879f6ca6434a8f28c251cd1ee7f4b413c5a788a70b351e2187f2a', @@ -323,7 +308,7 @@ "a36a7a604d07d2478936c8f614d13adf41a34b41a8873e792338a03579a12884" ) TRUSTED_HISTORICAL_BLOB_POLICY_SHA256 = ( - "a32d829aa4f52f2cb18148c45dabfbad75dee74242bfef177c09e8c936dbf73b" + "1af56d541392836ea5fe0f5b38271b9d391e70a2193573bc419716e4fc1fa1b2" ) SCANNER_PATH = "scripts/verify_public_plugin_candidate.py" DESTINATION_MANIFEST_PATH = "docs/extraction-manifest.json" diff --git a/src/substrate_wiki/README.md b/src/substrate_wiki/README.md index 34275e7..fc66c69 100644 --- a/src/substrate_wiki/README.md +++ b/src/substrate_wiki/README.md @@ -1,5 +1,10 @@ # Substrate Wiki memory provider +> **Legacy — not the current install target.** This provider supports Hermes 0.20.x only and +> its v2.0.5 release is not published. The current Hermes 0.21.x plugin is +> [`plugins/substrate`](../../plugins/substrate); install that instead. Do not use this +> document to reject a Hermes 0.21.x installation. + `substrate_wiki` connects Hermes Agent 0.20.x to the hosted Substrate service at `https://app.trysubstrate.co`. It provides cited recall, automatic future capture, and an optional, resumable import of eligible prior conversations and explicitly saved memories.