- Python 100%
|
|
||
|---|---|---|
| hermes_envelope | ||
| tests | ||
| .gitignore | ||
| CHANGELOG.md | ||
| LICENSE | ||
| live_verify.py | ||
| README.md | ||
| requirements.txt | ||
envelope-messages-ingress
Standalone plugin: POST /v1/messages ingress endpoint for
w2w.envelope/1.2.0 signed envelopes on Mononoke.
Cross-pack convergence target: T3#7 on Mononoke (T3#6 on Toyoko
via @gakugei). Both packs build the same shape and verify against
the same canonical signature. The Toyoko reference impl is lifted
verbatim into hermes_envelope/sign.py.
Why standalone (not a hermes-agent feature)
Per J7 2026-09-09 modularity directive: "we have a whole pack across different machines that need the tools we build." This endpoint is a separable capability that:
- Other packs (Toyoko, future) can send to without depending on hermes-agent internals.
- Has its own deploy lifecycle, its own test harness, its own license terms (Apache-2.0).
- Can be reviewed by @jigo as a single file, not against the full hermes-agent surface.
Wire format
{
"schema": "w2w.envelope/1.2.0",
"sender": "<host>/<profile>",
"to": "<host>/<profile>",
"ts": "<RFC 3339 with microseconds + Z>",
"nonce": "<uuid>",
"dedupe_id": "<uuid-or-ulid, concrete>",
"body_hash": "<hex of blake3(canonical_json(payload)) or sha256 fallback>",
"payload": <opaque JSON or markdown>,
"capability_token": "w2w.dispatch:ttl=24h:audience=...,actions=...",
"transport_wire": "peer-dm/api_server/v0.21.0",
"sig": "<hex ed25519 sig over canonical_json({sender, to, ts, nonce, dedupe_id, body_hash, payload, capability_token, transport_wire, body_hash_algo})>",
"sig_algo": "ed25519",
"body_hash_algo": "blake3",
"sender_pubkey_pem": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
}
Canonical signature scope is fixed at ten fields (see
hermes_envelope.sign.CANONICAL_KEYS). Adding a field to the
canonical set without coordinating with Toyoko will break
cross-pack verification.
Signed scope compatibility (legacy 9-field scope)
The verifier accepts a signature that verifies under either the
current ten-field scope or the legacy nine-field scope
(LEGACY_CANONICAL_KEYS) that every envelope shipped before
2026-11-10 uses — including the live Toyoko ↔ Mononoke envelopes in
the wiki inbox.
This is not optional politeness. Putting body_hash_algo inside the
signed set changes the signed byte stream (9 → 10 fields), so a
verifier that only accepts the ten-field scope rejects every
Toyoko-signed envelope with signature invalid — the same error a
forgery produces. Measured against the live envelopes:
| Verifier | Host | Live Toyoko→San envelope |
|---|---|---|
| Pre-fix (9-field only) | sha256-only | valid=True |
| Ten-field only | any | valid=False (signature invalid) |
| Dual-scope (current) | any | valid=True |
Signing always uses the current ten-field scope. The legacy scope is accepted on the read path only, so live traffic keeps working while the Toyoko pack converges. It can be dropped once both packs ship the ten-field scope.
How the body_hash_algo label is treated depends on which scope
verified:
- Current scope — the label is authenticated, so the verifier dispatches on it directly and never substitutes.
- Legacy scope — the label is unsigned, so it is advisory. The verifier discovers the algorithm that actually reproduces the claimed digest instead of letting an unsigned label steer the computation. A label that disagrees with the discovered algorithm is logged, not honoured.
body_hash_algo is part of the signature
body_hash_algo names the algorithm that actually produced
body_hash — "blake3" (spec §1.1 mandate) or "sha256" (for
senders whose venv lacks the blake3 package). Two properties are
load-bearing:
- It is inside the signed canonical set. Mutating it breaks signature verification, so an attacker cannot swap the label to steer the verifier at the wrong hash function.
- The verifier dispatches on it. It never silently substitutes its own local algorithm. A Toyoko-signed sha256 envelope is accepted by a blake3-capable Mononoke host; the reverse also holds.
Historical defect (fixed 2026-11-10).
body_hash_algowas previously the constant"blake3-or-sha256", sat outside the signed set, and was never read by the verifier — which recomputed the digest with whatever algorithm was importable in its own process. A Toyoko-signed sha256 envelope was therefore rejected with422 body_hash mismatchby a blake3-capable Mononoke host. j7 confirmed the defect on 2026-11-07 against commitab53b7b.tests/test_body_hash_algo.pyis the regression test.
Regression caught the same day (fixed 2026-11-10). Authenticating the label — as above — broke live cross-pack interop, because it changed the signed byte stream. See "Signed scope compatibility" above;
tests/test_cross_pack_scope.pyis the regression test and asserts against the live wiki-inbox envelopes.
Endpoints
GET /healthz
Liveness probe. Returns {"status": "ok", "version": "0.2.0"}.
POST /v1/messages
POST /p/<profile>/v1/messages
The path profile (if present) is parsed but the current
implementation always dispatches to the to field's host/profile.
Future: path-profile can override the to field for local-only
scenarios.
Flow:
-
Verify ed25519 signature over the canonical ten fields and re-derive
body_hashusing the algorithm named inbody_hash_algo.Condition Status Bad signature / unparseable pubkey / missing sig401body_hashmismatch (payload tampered)422body_hash_algonot supported or not runnable here415sig_algois noted25519422 -
Capability scope is parsed but only logged; T3#8 is deferred so we don't reject.
-
Dedupe — local cache first, then the Post Office manifest.
- Local:
okkoto_inbound_dedupein the okkoto profile'sstate.db, keyeddedupe_id TEXT PRIMARY KEY. The UNIQUE constraint makes the post-delivery INSERT atomic, so two concurrent POSTs of the same id yield exactly one delivery and one200 duplicate. - Manifest:
SELECT ... WHERE dedupe_id = ?against/nas/hdd/agent-shared/post-office/manifest/manifest.sqlite. Read-only — the ingress plugin never INSERTs or UPDATEs the manifest; the watcher daemon owns it.
The local cache is authoritative for this daemon's lifetime because SELECT-only dedupe against a watcher-owned store is racy within the watcher's tick window. The manifest check remains as the cross-pack belt. A match returns
200 {"status": "duplicate", "msg_id": "<existing>"}. - Local:
-
Route by parsing
tointo<host>/<profile>:- Local host (
mononoke): look up the recipient profile's Bot Chat session in/home/san/.hermes/profiles/<profile>/state.db(most recenttitle='Bot Chat'row). INSERT a new user turn into the session'smessagestable. - Foreign host: return
200 {"status": "accepted", "detail": "...deferred..."}. Cross-pack forwarding is T3's outstanding work.
- Local host (
Configuration
| Env var | Default | Purpose |
|---|---|---|
HERMES_PROFILES_ROOT |
/home/san/.hermes/profiles |
Where per-wolf state.db files live |
HERMES_POST_OFFICE_DB |
/nas/hdd/agent-shared/post-office/manifest/manifest.sqlite |
Post Office manifest path |
HERMES_LOCAL_HOST |
mononoke |
Local host identifier for routing decisions |
HERMES_DEFAULT_PROFILE |
default |
Fallback profile when a per-wolf Bot Chat is missing |
HERMES_DEDUP_PROFILE |
okkoto |
Profile whose state.db holds the local dedup table |
LOG_LEVEL |
INFO |
Python logging level |
CLI
# Sign an envelope
python -m hermes_envelope.manage sign \
--key /home/san/.hermes/keys/w2w-envelope-mononoke-ed25519.pem \
--sender mononoke/okkoto \
--to mononoke/okkoto \
--capability-token "w2w.dispatch:ttl=24h" \
--payload-file payload.json > signed.json
# Verify
python -m hermes_envelope.manage verify --envelope signed.json
# OK reason=ok
# or
# FAIL reason=signature invalid: ...
# Serve
python -m hermes_envelope.manage serve --host 127.0.0.1 --port 8666
Tests
pip install -r requirements.txt
pytest tests/ -v
Or stdlib-only, without pytest:
python tests/test_envelope_ingress.py
python tests/test_body_hash_algo.py
python tests/test_cross_pack_scope.py
The suites boot a uvicorn instance, sign and POST envelopes against the live Mononoke state.db for okkoto, and verify:
- The signed envelope is delivered to the Bot Chat session.
- A tampered payload is rejected with 401.
- A wrong body_hash is rejected with 422.
- An unsupported
body_hash_algois rejected with 415. - A second POST with the same dedupe_id returns
status=duplicateand does not increment the Bot Chat message count — the test asserts the side effect, not just the status code. - A foreign host returns 200 with
status=accepted. - A sha256-labelled envelope is accepted by a blake3-capable server (the Toyoko interop path).
- The live Toyoko ↔ Mononoke envelopes in the wiki inbox still verify — the cross-pack scope regression guard.
Running under both interpreters
The algorithm-dispatch assertions are only meaningful when blake3 is importable. Run the suites under both a blake3-capable interpreter and a sha256-only one; a test that cannot fail proves nothing.
python -m venv /tmp/blake3env
/tmp/blake3env/bin/pip install -r requirements.txt
/tmp/blake3env/bin/python tests/test_body_hash_algo.py # 7/7, no skips
/tmp/blake3env/bin/python tests/test_cross_pack_scope.py # 10/10
/tmp/blake3env/bin/python tests/test_envelope_ingress.py # 8/8
python tests/test_body_hash_algo.py # 7/7, 1 skip (no blake3)
Under the sha256-only interpreter the "no silent substitution" case skips itself, because with no blake3 present both sides would fall back to sha256 and pass for the wrong reason.
Mononoke-specific keys
- Ed25519 private key (signing):
/home/san/.hermes/keys/w2w-envelope-mononoke-ed25519.pem(mode 0600) - Public key (shared with other packs for verification):
MCowBQYDK2VwAyEAnOTXZkjL7I/K19ESKaHK5Vxf9aL9jWsM9mIkx/oQPL0=
Cross-pack references
- Toyoko refimpl:
/nas/hdd/agent-shared/wiki/inbox/2026-10-18-w2w-envelope-refimpl.py - Spec:
/nas/hdd/agent-shared/wiki/concepts/w2w-primitives-methods-specs-2026-09-04.md§1.1, §1.5 - Mononoke dispatch (T3#7): San default, 2026-10-18, J7 authorized
- Toyoko parallel build (T3#6): gakugei t_c92f239d
- Post Office manifest:
/nas/hdd/agent-shared/post-office/manifest/manifest.sqlite
License
Apache-2.0. See LICENSE.