Private notification previews

Developer preview; not available in build 75. The hosted backend is deployed in compatibility mode. The new iPhone build and physical-device acceptance are still pending. Keep existing integrations on standard notifications until the app release is confirmed.

Two notification choices

Standard previews work with existing integrations. HTTPS and Apple Push Notification service protect transport, while the relay and Apple can process the title, body and destination. Use generic wording for sensitive events.

Private previews encrypt that content on your backend and decrypt it on the iPhone before display. The user opts in separately for each connected app. If the phone cannot decrypt a private preview, the banner says “Your agent has an update.” It never substitutes a sensitive standard preview. iOS notification settings still control Lock Screen visibility.

Delivery metadata remains visible: routing identifiers, device tokens, timing, ciphertext size and the generic fallback. This does not hide the notification’s existence, encrypt hosted speech processing, or add forward secrecy.

What your backend adds

1. Use a distinct isolated-v1 recipient for each phone. Prepare its pairing token inside your authenticated user session, and record that owner. Verify the token’s redemption through the relay before saving the phone public key. An arbitrary configure request is not proof of recipient ownership.
2. Advertise surfaces.push.privatePreviews with version 1 and your notification public key. The app verifies that key over its direct authenticated connection.
3. Implement the authenticated parlane_configure_notifications tool. Persist the requested mode and its revision together, then return the exact acknowledgement. Both Standard and Private must remain supported.
4. Choose the sender path using that saved preference. Private delivery sends privatePreview only; omit apnsHint and the legacy encryptedPayload. A failed encryption attempt must not send readable content instead.

{
  "surfaces": {
    "push": {
      "relay": true,
      "privatePreviews": {
        "version": 1,
        "serverPublicKey": "<canonical base64url X25519 public key>"
      }
    }
  }
}

The complete versioned wire format, key derivation, acknowledgement and retry contracts are in the integration kit, section 13. A Node helper and authenticated Express reference are included in the release-candidate source; the helper is not yet published on npm.

Existing standard integrations need no encryption changes. Private previews require backend support and a new pairing QR as well as the new iPhone build. Private quick actions are not included in version 1.

Retries apply to both choices

Deduplicate actions in your backend using the authenticated user, operation and stable request ID. Save the original request fingerprint and result. A repeated ID with different content must be rejected.

For an effect in your own database, commit the effect and receipt in one transaction. For an external effect, pass a stable idempotency key to the provider. If the outcome is uncertain after a crash, retain the pending claim and reconcile it before retrying. An in-memory map cannot protect against duplicates after restart.

Hosted Pro verification

The updated iPhone app and hosted services handle installation and Pro verification. Integrating developers do not collect Apple receipts, implement Parlane billing, or supply Apple credentials. Your backend still authenticates its own users and notification preferences.