agentvault-hermes 0.1.0__tar.gz

agentvault_hermes-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+.venv/
+venv/
+*.log
+
+# Phase 0 spike build artifacts (regenerated via _spike/interop/regen.sh)
+_spike/interop/libmls_rs_uniffi.dylib
+_spike/interop/libmls_rs_uniffi.so
+_spike/interop/mls_rs_uniffi.py
+_spike/interop/artifacts/
+_spike/interop/node_modules/

agentvault_hermes-0.1.0/PKG-INFO

@@ -0,0 +1,244 @@
+Metadata-Version: 2.4
+Name: agentvault-hermes
+Version: 0.1.0
+Summary: Native AgentVault plugin for the Hermes agent runtime — E2E encrypted owner-↔-agent and A2A messaging via MLS
+Project-URL: Homepage, https://agentvault.chat
+Project-URL: Documentation, https://agentvault.chat/docs/hermes
+Project-URL: Repository, https://github.com/motiveflowllc/agentvault-gen2
+Project-URL: Issues, https://github.com/motiveflowllc/agentvault-gen2/issues
+Author-email: MotiveFlow LLC <support@agentvault.chat>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1.0
+Requires-Dist: httpx-ws>=0.6.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pynacl>=1.5.0
+Requires-Dist: ruamel-yaml>=0.18.0
+Provides-Extra: dev
+Requires-Dist: aiohttp>=3.9.0; extra == 'dev'
+Requires-Dist: hypothesis>=6.100; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: mls
+Requires-Dist: agentvault-mls-rs-uniffi==0.1.1; extra == 'mls'
+Description-Content-Type: text/markdown
+
+# agentvault-hermes
+
+Native AgentVault plugin for the Hermes agent runtime by Nous Research.
+
+End-to-end encrypted, zero-knowledge messaging between AI agent owners and
+their Hermes agents, plus A2A discovery + messaging across other
+AgentVault-enabled frameworks.
+
+## Quickstart
+
+The setup flow mirrors the OpenClaw plugin's: create an invite via the
+AgentVault web app, enroll the device from the CLI, approve in the web
+UI, and the plugin auto-activates.
+
+### 1. Install the package
+
+```bash
+pip install -e ".[dev]"
+```
+
+(Once published to PyPI, this becomes `pip install agentvault-hermes`.)
+
+### 2. Create an invite at agentvault.chat
+
+1. Log in to <https://agentvault.chat>.
+2. Open **My Agents → Quick Add** (or `/agents/quick-add`).
+3. Enter an agent name and click **Create**.
+4. The web UI displays a CLI command containing your invite token.
+   The token is the part after `--token=`. Copy that.
+
+### 3. Run the Hermes setup command on your machine
+
+```bash
+agentvault-hermes setup --token=<paste-the-token>
+```
+
+The plugin will:
+- check your environment (`hermes` binary, `~/.hermes/config.yaml`)
+- detect any OpenClaw coexistence and pick a non-colliding port
+- generate Ed25519 + X25519 + MLS init keys
+- POST `/api/v1/enroll` to the AV backend (your device is now PENDING)
+- **wait** for you to approve in the web UI
+
+### 4. Approve the device in agentvault.chat
+
+The web UI's pending-device card auto-detects your enrollment. Click
+**Approve and Chat**. The CLI is polling `/api/v1/devices/{id}/status`
+and will see the change within ~3 seconds.
+
+### 5. Plugin finishes automatically
+
+After approval, the plugin:
+- POSTs `/api/v1/devices/{id}/activate` to receive the device JWT
+- writes `~/.hermes/agentvault/<account>/state.json` (mode 0o600)
+- adds an `agentvault` MCP server entry to `~/.hermes/config.yaml`
+  (a timestamped backup of the original is written next to it)
+
+### 6. Start the Hermes gateway
+
+> [!IMPORTANT]
+> **This step is required.** Running the `hermes` TUI alone only registers
+> plugins — it does NOT activate the AgentVault gateway platform that
+> opens the WebSocket to AgentVault. Without a running gateway, your
+> agent appears **Offline** in `agentvault.chat` indefinitely even though
+> enrollment succeeded.
+
+Pick one:
+
+**Foreground (recommended for first run / debugging):**
+
+```bash
+hermes gateway run
+```
+
+You'll see `✓ agentvault connected` once the WS handshake completes.
+`Ctrl-C` to stop. Logs land in `~/.hermes/logs/agent.log` and
+`~/.hermes/logs/errors.log`.
+
+**Background (launchd / systemd service):**
+
+```bash
+hermes gateway install
+hermes gateway start
+```
+
+This installs a persistent service that auto-starts on login. Check
+status with `hermes gateway status`; stop/restart with
+`hermes gateway stop` / `hermes gateway restart`.
+
+### 7. Verify
+
+```bash
+agentvault-hermes doctor
+```
+
+Reports green on three checks:
+- **Configuration** — state.json exists with a valid JWT
+- **Connectivity** — AV backend reachable
+- **OpenClaw coexistence** — neighbor framework detected (or not)
+
+The doctor command does NOT yet verify the gateway is running —
+[tracked as a follow-up](https://github.com/motiveflowllc/agentvault-gen2/issues).
+For now confirm via `hermes gateway status` (or by sending a message
+from agentvault.chat and seeing the reply land).
+
+## Troubleshooting
+
+### "I sent a message in agentvault.chat but the agent never replies"
+
+99% of first-run reports are a missing **Step 6**. Run
+`hermes gateway status` — if it says **not running**, start it with
+`hermes gateway run` (foreground) or `hermes gateway start` (background
+service).
+
+The TUI's `hermes` and `hermes chat` commands intentionally do NOT
+start the gateway — they're chat surfaces, not daemon launchers. The
+WebSocket that delivers your inbound messages to the agent runtime
+lives in the gateway daemon process, not the TUI.
+
+### "Agent shows Offline in agentvault.chat even with the gateway running"
+
+Check `~/.hermes/logs/agent.log` for the
+`AV adapter connected: account=...` line. If absent, the gateway
+either crashed at startup or never tried to activate the platform.
+Common causes: stale `state.json` (re-enroll), wrong API base URL in
+`~/.hermes/agentvault/<account>/state.json`, or a backend pairing
+already mapped to a different device (delete the agent in AV-web and
+re-enroll a fresh device).
+
+## Re-enrolling
+
+`state.json` makes setup idempotent — re-running `agentvault-hermes setup`
+with `state.json` present is a no-op. To re-enroll (new invite, new
+device record):
+
+```bash
+rm ~/.hermes/agentvault/default/state.json
+agentvault-hermes setup --token=<new-token>
+```
+
+Invite tokens are single-use, so each re-enrollment requires a fresh
+invite from the web UI.
+
+## Multi-account
+
+```bash
+agentvault-hermes setup --account=alice --token=<token-1>
+agentvault-hermes setup --account=bob   --token=<token-2>
+```
+
+Each account gets its own `~/.hermes/agentvault/<account-id>/`
+subdirectory with separate keys and JWT.
+
+## Status
+
+This package is in active development. Phase 0 (mls-rs interop spike),
+Phase 1 (foundation: identity, transport, CLI, integration tests, CI),
+and Phase 2 (MLS crypto core) have shipped on `main`. Phase 3 (full
+encrypted send/receive over the live transport) is next.
+
+## Phase 2 capabilities (shipped)
+
+The crypto module under `src/agentvault_hermes/crypto/` is feature-complete
+for the four primitives Hermes needs and is byte-compatible with the
+OpenClaw plugin's TypeScript implementation where mathematically possible.
+
+| Capability | Module | Tests |
+|---|---|---|
+| **X3DH** key agreement (Ed25519↔X25519, BLAKE2b-256) | `crypto/x3dh.py` | `tests/unit/crypto/test_x3dh.py` + `tests/unit/crypto/vectors/test_x3dh_vectors.py` (byte-equal vs OC) |
+| **Double Ratchet** 1:1 messaging (XChaCha20-Poly1305 + Ed25519 header sigs + V2 header encryption) | `crypto/ratchet.py` | `tests/unit/crypto/test_ratchet.py` + `tests/unit/crypto/vectors/test_ratchet_vectors.py` (5 byte-equal scenarios) |
+| **MLS group state** (mls-rs-uniffi 0.1.x wrapper, RFC 9420) | `crypto/mls_group.py` | `tests/unit/crypto/test_mls_group.py` + `tests/unit/crypto/vectors/test_mls_group_vectors.py` (parse-only structural) |
+| **Persistence** (per-conversation directory layout, atomic meta writes) | `crypto/persistence.py` | `tests/unit/crypto/test_persistence.py` |
+
+Cross-module flows (X3DH → DR bootstrap, MLS multi-member lifecycle,
+state save/reload, telemetry hooks) are exercised in
+`tests/integration/test_crypto_*.py`.
+
+The Phase 2 acceptance smoke at
+`tests/integration/test_phase2_demo.py` is the runnable summary — it
+imports every public crypto surface and walks through the four primitives
+in one test. When that file fails, expect a packaging-level break;
+localized regressions surface in the deeper test suites listed above.
+
+To run only the Phase 2 acceptance demo:
+
+```bash
+cd packages/plugin-hermes
+uv run pytest tests/integration/test_phase2_demo.py -v
+```
+
+To run the full Phase 2 suite (~210 tests, runtime ~2s, includes 9
+documented `xfail`s for cross-impl bridges that land in WS-25 follow-up
+and Phase 6 telemetry):
+
+```bash
+uv run pytest tests/ -v
+```
+
+## Plans + design docs
+
+See in the AgentVault repo:
+
+- `docs/plans/2026-05-05-hermes-native-integration-design.md` — original
+  design.
+- `docs/plans/2026-05-05-hermes-native-integration-phase0-1-implementation.md`
+  — Phase 0/1 implementation plan.
+- `docs/plans/2026-05-07-hermes-phase2-implementation.md` — Phase 2
+  work-stream breakdown (WS-22 through WS-27).

agentvault_hermes-0.1.0/README.md

@@ -0,0 +1,208 @@
+# agentvault-hermes
+
+Native AgentVault plugin for the Hermes agent runtime by Nous Research.
+
+End-to-end encrypted, zero-knowledge messaging between AI agent owners and
+their Hermes agents, plus A2A discovery + messaging across other
+AgentVault-enabled frameworks.
+
+## Quickstart
+
+The setup flow mirrors the OpenClaw plugin's: create an invite via the
+AgentVault web app, enroll the device from the CLI, approve in the web
+UI, and the plugin auto-activates.
+
+### 1. Install the package
+
+```bash
+pip install -e ".[dev]"
+```
+
+(Once published to PyPI, this becomes `pip install agentvault-hermes`.)
+
+### 2. Create an invite at agentvault.chat
+
+1. Log in to <https://agentvault.chat>.
+2. Open **My Agents → Quick Add** (or `/agents/quick-add`).
+3. Enter an agent name and click **Create**.
+4. The web UI displays a CLI command containing your invite token.
+   The token is the part after `--token=`. Copy that.
+
+### 3. Run the Hermes setup command on your machine
+
+```bash
+agentvault-hermes setup --token=<paste-the-token>
+```
+
+The plugin will:
+- check your environment (`hermes` binary, `~/.hermes/config.yaml`)
+- detect any OpenClaw coexistence and pick a non-colliding port
+- generate Ed25519 + X25519 + MLS init keys
+- POST `/api/v1/enroll` to the AV backend (your device is now PENDING)
+- **wait** for you to approve in the web UI
+
+### 4. Approve the device in agentvault.chat
+
+The web UI's pending-device card auto-detects your enrollment. Click
+**Approve and Chat**. The CLI is polling `/api/v1/devices/{id}/status`
+and will see the change within ~3 seconds.
+
+### 5. Plugin finishes automatically
+
+After approval, the plugin:
+- POSTs `/api/v1/devices/{id}/activate` to receive the device JWT
+- writes `~/.hermes/agentvault/<account>/state.json` (mode 0o600)
+- adds an `agentvault` MCP server entry to `~/.hermes/config.yaml`
+  (a timestamped backup of the original is written next to it)
+
+### 6. Start the Hermes gateway
+
+> [!IMPORTANT]
+> **This step is required.** Running the `hermes` TUI alone only registers
+> plugins — it does NOT activate the AgentVault gateway platform that
+> opens the WebSocket to AgentVault. Without a running gateway, your
+> agent appears **Offline** in `agentvault.chat` indefinitely even though
+> enrollment succeeded.
+
+Pick one:
+
+**Foreground (recommended for first run / debugging):**
+
+```bash
+hermes gateway run
+```
+
+You'll see `✓ agentvault connected` once the WS handshake completes.
+`Ctrl-C` to stop. Logs land in `~/.hermes/logs/agent.log` and
+`~/.hermes/logs/errors.log`.
+
+**Background (launchd / systemd service):**
+
+```bash
+hermes gateway install
+hermes gateway start
+```
+
+This installs a persistent service that auto-starts on login. Check
+status with `hermes gateway status`; stop/restart with
+`hermes gateway stop` / `hermes gateway restart`.
+
+### 7. Verify
+
+```bash
+agentvault-hermes doctor
+```
+
+Reports green on three checks:
+- **Configuration** — state.json exists with a valid JWT
+- **Connectivity** — AV backend reachable
+- **OpenClaw coexistence** — neighbor framework detected (or not)
+
+The doctor command does NOT yet verify the gateway is running —
+[tracked as a follow-up](https://github.com/motiveflowllc/agentvault-gen2/issues).
+For now confirm via `hermes gateway status` (or by sending a message
+from agentvault.chat and seeing the reply land).
+
+## Troubleshooting
+
+### "I sent a message in agentvault.chat but the agent never replies"
+
+99% of first-run reports are a missing **Step 6**. Run
+`hermes gateway status` — if it says **not running**, start it with
+`hermes gateway run` (foreground) or `hermes gateway start` (background
+service).
+
+The TUI's `hermes` and `hermes chat` commands intentionally do NOT
+start the gateway — they're chat surfaces, not daemon launchers. The
+WebSocket that delivers your inbound messages to the agent runtime
+lives in the gateway daemon process, not the TUI.
+
+### "Agent shows Offline in agentvault.chat even with the gateway running"
+
+Check `~/.hermes/logs/agent.log` for the
+`AV adapter connected: account=...` line. If absent, the gateway
+either crashed at startup or never tried to activate the platform.
+Common causes: stale `state.json` (re-enroll), wrong API base URL in
+`~/.hermes/agentvault/<account>/state.json`, or a backend pairing
+already mapped to a different device (delete the agent in AV-web and
+re-enroll a fresh device).
+
+## Re-enrolling
+
+`state.json` makes setup idempotent — re-running `agentvault-hermes setup`
+with `state.json` present is a no-op. To re-enroll (new invite, new
+device record):
+
+```bash
+rm ~/.hermes/agentvault/default/state.json
+agentvault-hermes setup --token=<new-token>
+```
+
+Invite tokens are single-use, so each re-enrollment requires a fresh
+invite from the web UI.
+
+## Multi-account
+
+```bash
+agentvault-hermes setup --account=alice --token=<token-1>
+agentvault-hermes setup --account=bob   --token=<token-2>
+```
+
+Each account gets its own `~/.hermes/agentvault/<account-id>/`
+subdirectory with separate keys and JWT.
+
+## Status
+
+This package is in active development. Phase 0 (mls-rs interop spike),
+Phase 1 (foundation: identity, transport, CLI, integration tests, CI),
+and Phase 2 (MLS crypto core) have shipped on `main`. Phase 3 (full
+encrypted send/receive over the live transport) is next.
+
+## Phase 2 capabilities (shipped)
+
+The crypto module under `src/agentvault_hermes/crypto/` is feature-complete
+for the four primitives Hermes needs and is byte-compatible with the
+OpenClaw plugin's TypeScript implementation where mathematically possible.
+
+| Capability | Module | Tests |
+|---|---|---|
+| **X3DH** key agreement (Ed25519↔X25519, BLAKE2b-256) | `crypto/x3dh.py` | `tests/unit/crypto/test_x3dh.py` + `tests/unit/crypto/vectors/test_x3dh_vectors.py` (byte-equal vs OC) |
+| **Double Ratchet** 1:1 messaging (XChaCha20-Poly1305 + Ed25519 header sigs + V2 header encryption) | `crypto/ratchet.py` | `tests/unit/crypto/test_ratchet.py` + `tests/unit/crypto/vectors/test_ratchet_vectors.py` (5 byte-equal scenarios) |
+| **MLS group state** (mls-rs-uniffi 0.1.x wrapper, RFC 9420) | `crypto/mls_group.py` | `tests/unit/crypto/test_mls_group.py` + `tests/unit/crypto/vectors/test_mls_group_vectors.py` (parse-only structural) |
+| **Persistence** (per-conversation directory layout, atomic meta writes) | `crypto/persistence.py` | `tests/unit/crypto/test_persistence.py` |
+
+Cross-module flows (X3DH → DR bootstrap, MLS multi-member lifecycle,
+state save/reload, telemetry hooks) are exercised in
+`tests/integration/test_crypto_*.py`.
+
+The Phase 2 acceptance smoke at
+`tests/integration/test_phase2_demo.py` is the runnable summary — it
+imports every public crypto surface and walks through the four primitives
+in one test. When that file fails, expect a packaging-level break;
+localized regressions surface in the deeper test suites listed above.
+
+To run only the Phase 2 acceptance demo:
+
+```bash
+cd packages/plugin-hermes
+uv run pytest tests/integration/test_phase2_demo.py -v
+```
+
+To run the full Phase 2 suite (~210 tests, runtime ~2s, includes 9
+documented `xfail`s for cross-impl bridges that land in WS-25 follow-up
+and Phase 6 telemetry):
+
+```bash
+uv run pytest tests/ -v
+```
+
+## Plans + design docs
+
+See in the AgentVault repo:
+
+- `docs/plans/2026-05-05-hermes-native-integration-design.md` — original
+  design.
+- `docs/plans/2026-05-05-hermes-native-integration-phase0-1-implementation.md`
+  — Phase 0/1 implementation plan.
+- `docs/plans/2026-05-07-hermes-phase2-implementation.md` — Phase 2
+  work-stream breakdown (WS-22 through WS-27).

agentvault_hermes-0.1.0/_spike/MLS_RS_PYTHON_AUDIT.md

@@ -0,0 +1,152 @@
+# mls-rs-python audit
+
+**Version checked:** mls-rs-uniffi 0.13.0 (from source — NOT on PyPI)
+**Date:** 2026-05-06
+
+## Summary finding
+
+The package name `mls-rs-python` **does not exist on PyPI** under any variant tested.
+The correct binding is `mls-rs-uniffi`, a UniFFI-generated binding living in the
+`mls-rs-uniffi/` subdirectory of `https://github.com/awslabs/mls-rs`.
+It generates Python files from Rust via Mozilla's UniFFI framework and is **not published
+to PyPI** — it must be built from source using `maturin` + a Rust toolchain.
+
+All eight package-name variants were checked against PyPI and returned `No matching distribution found`:
+
+| Name tried | Result |
+|---|---|
+| `mls-rs-python` | 404 / not found |
+| `mls-rs` | not found |
+| `mls_rs` | not found |
+| `mls-rs-py` | not found |
+| `pymls-rs` | not found |
+| `mlsrs` | not found |
+| `mls_rs_python` | not found |
+| `mls-rs-uniffi` | not found |
+| `mls_rs_uniffi` | not found |
+
+The mls-rs repository also has **no GitHub releases** — it ships as a Rust workspace only.
+
+**Rust toolchain is NOT installed on this machine** (`cargo` / `rustc` not found in PATH).
+Any build-from-source path requires `rustup install` as a prerequisite.
+
+---
+
+## Feature coverage vs ts-mls (`mls-conversation.test.ts`)
+
+The ts-mls column maps to actual function calls in `packages/crypto/src/mls-group.ts`.
+The mls-rs-uniffi column maps to the Python API exposed by
+`mls-rs-uniffi/src/lib.rs` (v0.13.0, commit `a0eb41d`, 2026-04-21)
+and verified against the Python integration tests in `mls-rs-uniffi/tests/`.
+
+| Feature | ts-mls API (`mls-group.ts`) | mls-rs-uniffi Python API | Notes |
+|---|---|---|---|
+| Key package generation | `generateKeyPackage(credential, caps, lifetime, exts, cs)` → returns `{publicPackage, privatePackage}` | `client.generate_key_package_message()` → `Message` | ts-mls splits public/private; uniffi bundles into opaque `Message`. No separate private key object. |
+| Serialize key package | `encodeMlsMessage({wireformat:'mls_key_package', keyPackage})` | key packages are already serialized `Message` objects passed by reference | ts-mls requires explicit TLS encoding for transport; uniffi handles encoding internally. |
+| Create group | `createGroup(groupId, pubPkg, privPkg, exts, cs)` → `ClientState` | `client.create_group(group_id: Optional[bytes])` → `Group` | ts-mls is stateless (returns new state); uniffi `Group` object is stateful and writes to storage. Conceptually equivalent. |
+| Add member | `createCommit({state, cipherSuite, pskIndex}, {extraProposals: [{proposalType:'add', add:{keyPackage}}], ratchetTreeExtension: true})` | `group.add_members([key_package_message])` → `CommitOutput` | ts-mls uses a generic commit with proposal list; uniffi has a dedicated `add_members()`. Both produce commit + welcome. |
+| Remove member | `createCommit({state, cs, pskIndex}, {extraProposals: [{proposalType:'remove', remove:{removed: idx}}]})` | `group.remove_members([signing_identity])` → `CommitOutput` | **API mismatch**: ts-mls removes by leaf index (integer); uniffi removes by `SigningIdentity` object. Mapping requires identity lookup. |
+| Update key (self-update) | `createCommit({state, cs, pskIndex}, {})` — empty proposals forces implicit update | `group.commit()` → `CommitOutput` | Both support empty commit / implicit self-update. Functionally equivalent. |
+| Welcome processing | `joinGroup(welcome, pubPkg, privPkg, pskIndex, cs)` → `ClientState` | `client.join_group(ratchet_tree, welcome_message)` → `JoinInfo` | ts-mls is stateless; uniffi creates a persistent `Group` stored by the `Client`. Equivalent outcome. |
+| Commit processing (incoming) | `processMessage(mlsMsg, state, pskIndex, acceptAll, cs)` → `ProcessMessageResult` | `group.process_incoming_message(message)` → `ReceivedMessage` | Both handle commit + application messages via the same call. Equivalent. |
+| Application message encrypt | `createApplicationMessage(state, plaintext, cs)` → `{newState, privateMessage}` then `encodeMlsMessage(...)` | `group.encrypt_application_message(message: bytes)` → `Message` | ts-mls is stateless (caller must update state); uniffi mutates `Group` in-place. Semantically equivalent. |
+| Application message decrypt | `processMessage(mlsMsg, state, pskIndex, acceptAll, cs)` → `{kind:'applicationMessage', message: Uint8Array}` | `group.process_incoming_message(message)` → `ReceivedMessage` (check `.kind == 'ApplicationMessage'`) | Both distinguish application vs handshake messages in the result. |
+| State export / serialization | `encodeGroupState(clientState)` → `Uint8Array`, then base64 | `group.write_to_storage()` + `client.load_group(group_id)` | **Architecture mismatch**: ts-mls uses explicit in-memory serialization; uniffi requires a storage backend (`ClientConfig` with SQLite or custom `GroupStateStorage`). No direct `exportState()` equivalent returning raw bytes. |
+| State import / restore | `decodeGroupState(bytes)` → `GroupState`, reconstruct `ClientState` | `client.load_group(group_id)` from configured storage | Same as above — storage backend required; there is no raw-bytes round-trip without configuring storage. |
+| Exporter secret | Not used in `mls-group.ts` but `ts-mls` exports `exporterSecret()` from `ClientState` | **NOT AVAILABLE** — `lib.rs` exposes no exporter_secret, export_secret, or epoch-keying method | This is a noted gap in the uniffi API per the lib.rs source review. |
+| Ciphersuite selection | `getCiphersuiteFromName(name)` / `getCiphersuiteImpl(suite, cryptoProvider)` | `CipherSuite.CURVE25519_AES128` enum — no pluggable crypto provider | ts-mls uses a pluggable provider (noble-crypto default); uniffi hardcodes OpenSSL via `mls-rs-crypto-openssl`. Different crypto backend. |
+| Epoch accessor | `clientState.groupContext.epoch` (bigint) | No direct epoch accessor on `Group` exposed to Python | Epoch tracking for replay protection requires workaround. |
+
+---
+
+## Gaps identified
+
+1. **No PyPI distribution** — `mls-rs-uniffi` is build-from-source only. Requires Rust toolchain
+   (`rustup` + `cargo`) and `maturin`. Installation is a multi-step compile, not `pip install`.
+   On CI/CD this means a Rust build step on every environment setup.
+
+2. **Exporter secret not exposed** — The uniffi Python binding does not expose `exporter_secret()`
+   or any epoch-keyed key derivation. This feature is available in the underlying `mls-rs` Rust
+   crate but was not surfaced in the UniFFI layer. Impact: any protocol that derives
+   per-session keys from the MLS exporter (e.g., SFrame, SRTP, or AV's own LLM proxy auth)
+   cannot use this binding without patching the Rust source.
+
+3. **Storage backend required for state persistence** — ts-mls uses explicit byte serialization
+   (`encodeGroupState`/`decodeGroupState`) so the caller controls persistence. The uniffi binding
+   requires configuring a `GroupStateStorage` (SQLite default, or custom). There is no raw-bytes
+   export equivalent. The Hermes plugin will need to configure and ship an SQLite file or
+   implement the custom storage callback interface (which involves UniFFI callback objects —
+   more complex to implement in Python).
+
+4. **Remove-by-index vs remove-by-identity** — ts-mls removes members by leaf index (integer).
+   The uniffi binding requires a `SigningIdentity` object. In practice the plugin must maintain
+   a membership roster that maps identities to group slots, adding bookkeeping overhead.
+
+5. **Hardcoded OpenSSL crypto backend** — ts-mls uses noble-crypto (pure JS, no native deps).
+   mls-rs-uniffi links against OpenSSL via `mls-rs-crypto-openssl`. This adds a system library
+   dependency (OpenSSL headers at build time, libssl at runtime). On macOS arm64 this typically
+   means installing OpenSSL via Homebrew. On Linux it depends on the distribution.
+
+6. **No Rust toolchain on this machine** — confirmed `cargo` and `rustc` are not installed.
+   Build-from-source is not currently possible in this environment without first running
+   `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`.
+
+7. **Stateful vs stateless design divergence** — ts-mls is purely functional / stateless
+   (every operation takes state and returns new state). mls-rs-uniffi wraps a stateful `Group`
+   object that mutates in place and persists to storage. The Hermes plugin wrapper will need
+   careful lifecycle management to avoid state corruption on concurrent message processing.
+
+---
+
+## Pinned version recommendation
+
+**There is no PyPI version to pin.**
+
+The binding must be installed from source at a specific git commit. The most recent
+commit to `mls-rs-uniffi/` is:
+
+```
+SHA: a0eb41d (full: e96b484e1bc5e90161d532b192b71f696e1a06b9 on main)
+Date: 2026-04-21
+Crate version: 0.13.0
+```
+
+If a build-from-source approach is adopted, pin to the repo HEAD SHA:
+
+```
+mls-rs-uniffi @ git+https://github.com/awslabs/mls-rs.git@e96b484e1bc5e90161d532b192b71f696e1a06b9#subdirectory=mls-rs-uniffi
+```
+
+**However**, this dependency cannot currently be expressed in a standard `pyproject.toml`
+`dependencies` list and requires `maturin` to compile the Rust crate. It is not installable
+via a plain `pip install` without a build backend that understands Rust + UniFFI.
+
+### WS-5.1 GO/NO-GO input
+
+This audit surfaces three paths for the WS-5.1 decision:
+
+**Path A — Build mls-rs-uniffi from source (CAUTION)**
+- Requires Rust + maturin in every dev/CI/production environment
+- Exporter secret gap requires upstream PR or local patch to `lib.rs`
+- Storage backend must be designed (SQLite file location, concurrency, cleanup)
+- Significant operational complexity for customers running the Hermes plugin
+- Viable but non-trivial; estimate +1-2 weeks beyond original Phase 0 scope
+
+**Path B — Pure-Python MLS implementation (CONSIDER)**
+- `pymls` or `mlslib` may exist as pure-Python RFC 9420 implementations
+- Not audited in this task; recommend checking as an alternative in WS-5.1
+- Avoids Rust toolchain dependency entirely
+- Likely slower and potentially incomplete for production use
+
+**Path C — Skip Python-side MLS; defer to Node binding (PREFERRED short-term)**
+- The Hermes plugin (Python) acts as a relay: it forwards encrypted bytes to/from the AV backend
+- MLS encrypt/decrypt runs in the Node spike (WS-2.x), which CAN use ts-mls directly
+- Python plugin does NOT need its own MLS stack if the architecture is:
+  `Hermes agent → Python plugin → AV backend (stores ciphertext) ← Node bridge → ts-mls`
+- This avoids the Rust toolchain problem entirely and is consistent with the
+  "server never sees plaintext" model where E2E crypto happens in the client layer (Node/TS)
+
+**Recommendation for WS-5.1:** Escalate Path C as the primary architecture question
+before investing in the mls-rs-uniffi build-from-source path. The core blocker is not
+"which Python MLS library" but "does the Hermes plugin need to do MLS crypto itself,
+or does it proxy ciphertext to a TS/Node layer that already has ts-mls?"