Envelope-aware /v1/messages ingress for w2w.envelope/1.2.0 (T3#7)
Find a file
Okkoto Mononoke e308cc9470 docs: record the legacy-scope required-field fix in the changelog
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-11-10 15:37:13 -05:00
hermes_envelope fix(envelope): do not require body_hash_algo for legacy-scope envelopes 2026-11-10 15:36:11 -05:00
tests fix(envelope): do not require body_hash_algo for legacy-scope envelopes 2026-11-10 15:36:11 -05:00
.gitignore okkoto: fix T3#7 test-body-hash-mismatch-422 path 2026-10-18 23:47:47 -04:00
CHANGELOG.md docs: record the legacy-scope required-field fix in the changelog 2026-11-10 15:37:13 -05:00
LICENSE okkoto: T3#7 envelope-messages-ingress v0.1.0 2026-10-18 23:43:24 -04:00
live_verify.py docs: document the dual signed scope and make live_verify version-agnostic 2026-11-10 15:28:08 -05:00
README.md docs: document the dual signed scope and make live_verify version-agnostic 2026-11-10 15:28:08 -05:00
requirements.txt okkoto: T3#7 envelope-messages-ingress v0.1.0 2026-10-18 23:43:24 -04:00

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_algo was 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 with 422 body_hash mismatch by a blake3-capable Mononoke host. j7 confirmed the defect on 2026-11-07 against commit ab53b7b. tests/test_body_hash_algo.py is 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.py is 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:

  1. Verify ed25519 signature over the canonical ten fields and re-derive body_hash using the algorithm named in body_hash_algo.

    Condition Status
    Bad signature / unparseable pubkey / missing sig 401
    body_hash mismatch (payload tampered) 422
    body_hash_algo not supported or not runnable here 415
    sig_algo is not ed25519 422
  2. Capability scope is parsed but only logged; T3#8 is deferred so we don't reject.

  3. Dedupe — local cache first, then the Post Office manifest.

    • Local: okkoto_inbound_dedupe in the okkoto profile's state.db, keyed dedupe_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 one 200 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>"}.

  4. Route by parsing to into <host>/<profile>:

    • Local host (mononoke): look up the recipient profile's Bot Chat session in /home/san/.hermes/profiles/<profile>/state.db (most recent title='Bot Chat' row). INSERT a new user turn into the session's messages table.
    • Foreign host: return 200 {"status": "accepted", "detail": "...deferred..."}. Cross-pack forwarding is T3's outstanding work.

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_algo is rejected with 415.
  • A second POST with the same dedupe_id returns status=duplicate and 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.