block / block/buzz

feat(protocol): stabilize the mobile workflow-approval event contract

Open
#3,523 1 comment 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.