Skip to content

feat(approvals): approving a critical request needs its digest - #925

Draft
OAraLabs wants to merge 5 commits into
feat/approval-critical-flagfrom
feat/critical-approve-needs-digest
Draft

OAraLabs wants to merge 5 commits into
feat/approval-critical-flagfrom
feat/critical-approve-needs-digest

Conversation

@OAraLabs

@OAraLabs OAraLabs commented Nov 14, 2026 •

Copy link
Copy Markdown
Owner

Beacon iOS item 3: approving a critical request needs its digest. Stacked on #917 (the critical flag); retarget as it merges. Next release, held with it.

What changes.

  • Every served approval request carries digest: an HMAC, under a key minted per daemon process, over what the client is shown (request id, tool, description, arguments view, created and expiry times, the critical flag). It's served wherever the request is (GET /api/approvals, the approval_pending frame, and the by-id route once feat(approvals): one request by id, and a request that ends takes its notification back #913 lands, since all of these use the one serializer). It is never in a push, because the push builds its own narrow body, and the stored copy of the frame (signal_events) drops it. So a client holds it only by fetching the request. It never raises: ASCII JSON, with a repr fallback for keys that can't be sorted.
  • POST /api/approvals/{id}/approve on a critical request needs {"digest": <that value>}:
    • none is 409 with code: digest_required (prose in error, the route's 409 shape);
    • another is code: digest_mismatch;
    • nothing is approved either way. The comparison is constant-time.
  • It runs after the route's own refusals about who may answer (scoped device, desktop prompts, workers, the old-build typed-text check). A hold lift's person check runs later, inside its queue.
  • REST only: Telegram, Slack and Discord /approve are the owner typing in chat, and are unchanged.
  • all is refused (409, code: critical_pending) while a critical request it would approve is pending. all already leaves desktop, worker and hold requests alone. A separate change makes the REST route take single ids only.
  • Requests that aren't critical approve exactly as before. Denying never needs a digest.
  • server_capabilities lists approval_digest.

What it proves, stated plainly. The client fetched this exact request. It doesn't prove a person read it in the app: a notification extension that fetches the request holds the digest too. Keeping critical requests off the lock screen still rests on the client not offering Approve there, which Beacon already does from critical. The PR description, the docs and the code all say this.

Choices noted:

  • Digest of the shown request, not of the raw arguments. The id is in the digest, so it binds to exactly one request. The raw arguments are dropped at capture on purpose, so no secret is kept, and a stored digest of them would add state for little gain.
  • The derived extents are left out. They can change with the grants while a request waits, which would make a correct digest mismatch.
  • Fail closed on clients that predate this. A client that doesn't send the digest can't approve a critical request over REST and gets a 409 saying why. Telegram and the CLI are unaffected. Gating the check on a client capability would let any client skip it by not advertising one.
  • Three existing tests changed on purpose: a capable phone approving a desktop prompt, and two hold-lift person checks (including the full-tools turn). All three requests are critical, so the tests now send the served digest, and that proves the person checks still refuse with a valid one.

Clients:

  • Beacon desktop and Beacon iOS read digest from the request they fetched and send it in the approve body.
  • Beacon desktop approves over REST today, so it needs this before it can approve a critical request against a daemon with this change.

Reviews: two (approvals).

  • The review session found nothing medium or higher. Its lows are done: no digest in the stored frame, and the CHANGELOG lists the default critical kinds.
  • The agent found three mediums:
    • the digest could raise on a lone surrogate and leave a request stuck in the queue;
    • the CHANGELOG didn't say clients without the digest lose REST approval of critical requests, and the 409 didn't match the route's shape;
    • the full-tools hold-lift test passed because of the digest, not the person check.
  • All three are fixed red-first, along with these lows: an HMAC instead of an unkeyed hash, all's own code, the order comment, and the docs.

Tests: red first, tests/test_critical_approve_needs_digest.py. Local Mac suite at c90d1a9, with the venv on PATH: 16,157 passed, 0 failed. Ruff and the mypy gate are clean.

🤖 Generated with Claude Code

OAraLabs and others added 5 commits November 13, 2026 19:13
Every served request carries digest, a sha256 over what the client is
shown (id, tool, description, arguments view, created/expiry, critical),
never in a push. The REST approve of a critical request needs it: none is
409 digest_required, another 409 digest_mismatch, nothing approved. It
is the last check, after every refusal about who may answer. 'all' is
refused while a critical request it would approve is pending. Two tests
send the served digest on purpose (a desktop prompt and a hold lift are
critical), so they still prove the person checks with a valid digest.
server_capabilities lists approval_digest.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The 409 shape, all's own code, a digest that never raises and cannot be
rebuilt without fetching, no digest in the stored frame; the full-tools
hold test sends the served digest so the person check is what refuses.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
- The digest never raises (ASCII JSON, a repr fallback for keys that
  cannot be sorted), so an odd argument no longer leaves a request stuck
  in the queue until restart.
- It is an HMAC under a key minted per daemon process, and the stored
  copy of the frame drops it, so a client holds it only by fetching.
- The 409s use the route's shape (prose in error, the word in code);
  all gets its own code, critical_pending (no digest satisfies it).
- The comment says where the hold lift's person check runs; REST only.
- CHANGELOG and API guide: the default critical kinds, that a client
  which does not send the digest can no longer approve them over REST,
  chat gateways unchanged, and the subscribed capabilities.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant