Push notifications
When Ben adds an expense, Ana and Carla get a push that reads "Ben added Dinner, 42.00", while the server, Apple and Google only ever see "New activity".
1In practice
What the user sees. When Ben adds an expense, Ana and Carla get a push that reads "Ben added Dinner, 42.00", while the server, Apple and Google only ever see "New activity". Behind that, Ben's app seals the text once per recipient with sealForUser (context notification). The push carries a generic fallback text plus the sealed bytes. The recipient's phone opens them with openSealed before showing the notification.
Why. A notification's text is often the most sensitive part: who paid what, and where. Without sealing, it would pass in the clear through the server, APNs and FCM.
Pros
- The text exists in the clear only on the sender's and the recipient's phones.
- The fallback text means a push still makes sense when it can't be opened (signed out, no key on this device yet).
- Sealing adds 84 bytes before base64 (version byte, 48 bytes of box, the context header), well under APNs' and FCM's 4 KB.
- The context is bound: a sealed bank movement (09) can't be shown as a notification.
Cons and limits
- Sealed boxes are anonymous. The recipient can't tell who sealed a notification, so anyone with the public key could push a fake one (SPEC.md, Limits). Keep notifications informative only, and show the real data from the group's rows.
- The sender seals once per recipient, using public keys from the server. An active server can hand out its own key in place of a member's (SPEC.md, Limits).
- Metadata is visible: who notifies whom, when, and the payload size. Pad the text to a few fixed sizes if that matters.
- iOS needs
mutable-contentand a Notification Service Extension. Its key must be readable while the phone is locked, which is a trade-off (05).
2Step-by-step flow
Each step shows who acts, which function runs, what travels and what every party holds afterwards. Use the controls, the step list or the arrow keys to replay any step.
3Code
The key lines from example/10-push-notifications/index.ts. The full file runs every party in one process and ends with node:assert checks.
// Ben's phone, per recipient
const sealed = ez.sealForUser({ value: text(JSON.stringify(message)), context: "notification", publicKey });
const payload = { aps: { alert: fallback, "mutable-content": 1 }, ezpriv: toB64url(sealed) };
// the recipient's phone
const message = JSON.parse(read(ez.openSealed({ sealed: fromB64url(payload.ezpriv), context: "notification", keyPair })));
The notification code can't run JavaScript, so it uses the ports, tested against the same vectors:
- iOS: a Notification Service Extension calling
openSealedfromports/swift, withkey_Afrom a keychain access group shared with the app (05). - Android: a
FirebaseMessagingServicecallingopenSealedfromports/kotlin, which isn't tested yet.
| Function | Spec |
|---|---|
sealForUser, openSealed | Ciphertexts |
Run it
git clone https://github.com/ezpriv/crypto.git && cd crypto
pnpm install && pnpm build
node example/10-push-notifications/index.ts