buzz/WIP.md

WIP: Offline-root signing

Status: implementation paused while we confirm what “generic delegated signing” should mean.

What we are trying to protect

A Buzz account has a routine key that remains available to the desktop app and may also be accessible to agents. That key should continue to sign ordinary Buzz events. For a sensitive action such as approving a pull request, we want an additional signature from an offline root.

The original PR event and its updates are already signed and content-addressed. The offline root therefore does not need to sign another copy of the payload or participate in a separate request/policy workflow. It needs to sign the exact event ID it reviewed.

A Nostr event has one author and one signature, and its ID commits to that author, its tags, and its content. We cannot append a second signature to an existing event without changing it. The root must publish a new signed event that references the original event.

Delegation and countersigning are different

Tyler's comment that we will probably want this generically for delegated signing changes where the primitive should live, but it does not bring back the generic approval system.

There are two related operations:

• Delegation: a root authorizes another key to sign some class of future events on its behalf.
• Countersigning: a root reviews an event that already exists and signs a reference to that exact event.

Ordinary delegation alone does not solve the high-assurance problem. If the routine key is compromised, an attacker can use whatever authority was delegated to it. High-assurance approval requires the second operation: the offline root must countersign each exact sensitive event.

The two operations can share a generic representation of the relationship between an account and its signing authority, but their verification rules and security properties must remain distinct.

Proposed minimal primitive

The reusable protocol needs only two signed objects in addition to the event being approved.

First, the routine account publishes a root link. The link contains a root signature over the routine pubkey, and the routine profile signs the link in turn. This proves that both keys agree on the relationship.

Second, the root publishes an endorsement with:

• the exact subject event ID;
• the exact account/root-link event ID;
• the routine account represented by the root; and
• a short signed purpose such as approve.

The generic verifier checks the profile, subject, and endorsement signatures; the root-to-account link; the exact references; and the signed purpose. It does not know anything about pull requests.

The relay may use that same verifier before storing an endorsement. It should validate the signing relationship and referenced events, but it should not implement PR-specific rules.

Pull requests become a thin consumer

For a pull request, the subject is the current signed revision:

• the latest trusted kind 1619 update, when one exists; or
• otherwise the original kind 1618 pull-request event.

The PR code treats a valid endorsement with purpose approve as an approval by the routine account. If a new update is published, its event ID is different, so an endorsement of the previous revision no longer counts. No separate staleness or payload-digest mechanism is required.

The desktop should export the subject event and account link as an offline signing package. The root secret remains on the offline device. The desktop only imports the resulting public endorsement event.

What Tyler's comment changes

The underlying SDK and wire format should use generic event-signing language, not PR-specific types. The offline CLI should likewise sign an arbitrary exact event package. PR code supplies the subject and interprets approve.

The current direction is therefore mostly right, but any checks for PR kinds or the literal approve action belong in the PR feature, not in the generic endorsement builder or publisher.

This does not justify adding:

• approval policies;
• request and decision records;
• thresholds or quorum calculation;
• a generic approval inbox;
• copied payloads and payload digests; or
• a separate proof-object hierarchy.

Those features solve different problems and were responsible for most of the earlier size and complexity.

Root rotation and revocation

Changing or removing the root must itself require authorization from the current root. Otherwise a compromised routine key could remove the protection before performing a sensitive action.

We still need to decide how rotation affects old endorsements. There are two reasonable meanings:

• The endorsement proves that the root was valid when it signed. It remains valid historical evidence after rotation.
• An endorsement may authorize a pending action only while its referenced root link is current. Rotation immediately prevents old-root endorsements from authorizing new execution.

For PR admission, the second rule is safer. We can preserve the old event as historical evidence while requiring the current account/root link when deciding whether the PR may merge.

Questions to settle before continuing

1. Did Tyler mean classic future-event delegation, exact-event countersigning, or a shared protocol that supports both?
2. Should the account/root relationship remain a tag on the routine profile, or become a dedicated replaceable event reusable by other signing features?
3. Is the first version intentionally one root per account, or must it support multiple scoped delegates now?
4. Should active authorization always require the currently linked root, while preserving older endorsements only as audit history?

My recommendation is to ship one root per account and one generic exact-event endorsement. Use it first for PR approvals, keep PR interpretation outside the generic verifier, and defer policies, quorum, and broader delegation until a concrete second consumer requires them.