feat(protocol): stabilize the mobile workflow-approval event contract
- Dominant language
- Rust
- Stars
- 32.7k
- Forks
- 4.3k
- Avg merge
- 1d 13h
- Merged PRs (30d)
- 253
Description
## Problem
We are prototyping Hermes Mobile as an external iOS safety/approval client for Buzz agents, but the current approval wire contract is not yet interoperable.
Verified against `block/buzz@485d03a358b6d695aaf97879f3fbaf2f308d0755`:
- `buzz-sdk::build_workflow_approval` emits kind `46030`/`46031` with `d = hex(SHA-256(raw approval token))`.
- The relay command executor accepts a `d` or `e` approval reference and resolves it as the stored token hash.
- `desktop/src-tauri/src/events.rs::build_approval_grant/build_approval_deny` instead emit `t = raw token`, which the relay handler does not inspect.
- `request_approval` still has the WF-08 TODO to persist the approval and emit kind `46010`, so an external client has no stable request envelope to consume yet.
This appears to block both Buzz's own event-based desktop path and third-party mobile approval clients.
## Proposed contract
Before implementing another client-specific interpretation, could Buzz define one canonical contract for:
1. Kind `46010` request tags/content: stable request id or token-hash reference, workflow/run/step identity, designated approver, expiry, and safe human-readable context.
2. Kind `46030`/`46031` response: canonical reference tag (`d` or `e`), whether clients ever receive the raw token, and optional decision note.
3. Authorization and replay behavior: signer requirements, tenant/community binding, expiry, already-decided handling, and idempotent duplicate submission.
4. A signed request/approve/deny fixture plus relay conformance tests that desktop, CLI, mobile, and third-party clients can share.
The existing SDK/relay `d = SHA-256(token)` representation looks like the strongest starting point because it avoids publishing the raw capability token in a response event.
## Integration offer
Once the request contract is stable, I can contribute a narrow external-client conformance fixture and validate it with Hermes Mobile as an iOS approval surface: verify the signed `46010` event, render the proposed action, obtain an explicit operator decision, sign `46030`/`46031`, and prove tamper/replay/expiry/duplicate-decision rejection.
Related: #2376 (WF-08) and #2754 (stable downstream extension points).
Contributor guide
Research direction
Start with desktop/src-tauri/src/events.rs, buzz-sdk::build_workflow_approval, the relay command executor, and request_approval, then compare the existing event and token handling with related issues #2376 and #2754. Define the canonical request and response contract, authorization and replay rules, and shared signed fixtures or conformance tests; done means desktop, CLI, mobile, and third-party clients can validate the same behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- ios, rust
- Domain
- api, backend-api-design, security
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100