Sealed Notifications

A phone can only receive a push from a server that holds the App’s Apple Push key. So pocketty runs a small relay. The design makes sure that relay never needs to see what it carries.

The Parts

Part	Holds
The App	A push token from Apple, a grant from the relay, and an X25519 key pair for seals. The private key stays in the Keychain, where the notification extension can read it while the phone is locked.
The daemon	Its own X25519 key pair (daemon.key), and one pairing per phone: the phone’s grant and public seal key.
The relay	The Apple Push key and the keys that sign grants. No database.

Pairing

1. The App gets a push token from Apple.
2. It asks the relay for a grant. The relay signs the token with HMAC-SHA256 and returns it. It keeps no copy.
3. When the App connects to a host, it runs pocketty pair over SSH and sends the grant and its public seal key. The daemon answers with its own public key.

The App pairs again only when the grant, the seal key or the relay changed.

Sending

When an agent changes state:

1. The daemon writes the note: host, session, workspace, tab, Pane, agent, state and time. It never adds text from the Pane.
2. It seals the note with HPKE in auth mode: DHKEM(X25519, HKDF-SHA256), HKDF-SHA256 and ChaCha20-Poly1305. Auth mode uses the daemon’s private key too, so the phone can check which daemon sent it.
3. It sends the sealed note and the grant to the relay.
4. The relay checks the grant and the rate limits, and sends an Apple Push alert with mutable-content and the placeholder text pocketty: Agent update.
5. On the phone, the notification extension opens the seal with the phone’s private key, checks the sender against the paired daemons, and replaces the placeholder with the real text.

If the seal does not open, or comes from a daemon the phone does not know, the placeholder text stays.

Limits

• The relay accepts 10 grant requests and 60 pushes per minute, per IP address and per push token.
• A sealed note must fit Apple’s 4 KB payload limit. The note itself is at most 2 KB before sealing.
• One notification per Pane is kept on the phone. A newer one replaces it.

What a Leaked Grant Allows

A grant lets its holder push sealed blobs to one phone, through the relay. It cannot read anything, and without the daemon’s private key, the phone shows only the placeholder for anything it sends. Rotating the relay’s signing key revokes every grant at once.

When the App Is Removed

If Apple reports that a push token is no longer valid, the relay tells the daemon, and the daemon deletes that pairing.