feat(push): add an Android FCM transport profile to the NIP-PL push gateway
- Dominant language
- Rust
- Stars
- 32.7k
- Forks
- 4.3k
- Avg merge
- 1d 13h
- Merged PRs (30d)
- 253
Description
## Summary
Add an Android Firebase Cloud Messaging transport profile to `buzz-push-gateway`, while preserving the existing NIP-PL capability, token-custody, replay-protection, quota, and delivery-authority model.
The current push gateway supports the iOS profiles `buzz-ios-production` and `buzz-ios-sandbox`; Android currently has no equivalent delivery path.
This proposal mirrors the NIP-PL iOS foundation established in #1924 rather than introducing a separate downstream push architecture.
Related umbrella discussion: #2754.
## Motivation
A first-party Android client needs a reliable background-notification path. Implementing this only in a downstream distribution would require a separate push proxy and would duplicate security-sensitive infrastructure:
- registration-token custody;
- provider credential management;
- replay prevention;
- quota enforcement;
- retry and permanent-failure classification;
- token invalidation and rotation;
- metrics, health checks, and deployment hardening.
That duplication would create permanent operational and security divergence between iOS and Android. FCM support is broadly useful to Buzz and fits naturally as another transport/application profile inside the existing gateway.
## Proposed direction
Introduce an Android application profile, tentatively:
```text
buzz-android-fcm
```
The exact profile name and configuration shape can follow maintainer preference.
Add:
- FCM HTTP v1 delivery support;
- Android installation enrollment;
- encrypted FCM registration-token custody;
- strict application/profile binding;
- retry classification for temporary FCM failures;
- permanent invalid/unregistered-token handling;
- bounded-cardinality Prometheus metrics;
- Kubernetes and Docker deployment configuration;
- provider-credential and encryption-key rotation documentation;
- end-to-end tests using a deterministic mock FCM endpoint.
The relay should continue receiving only opaque delivery capabilities. Raw FCM registration tokens and provider credentials should remain inside the push gateway.
## Architectural alignment
The Android implementation should reuse the existing NIP-PL boundaries where possible:
1. The client enrolls an installation with the push gateway.
2. The gateway validates the application/profile-specific enrollment proof.
3. The gateway stores the provider token encrypted and returns an opaque capability.
4. The relay stores and uses only that opaque capability.
5. Delivery admission, replay protection, endpoint quotas, and generation checks remain authoritative across gateway replicas.
6. The gateway translates an admitted delivery into an FCM HTTP v1 request.
Android-specific enrollment integrity may differ from Apple App Attest. The issue should not pre-decide whether the first implementation uses Play Integrity, application-signing-certificate binding, another Android attestation mechanism, or a staged profile with explicitly documented guarantees. That choice should be reviewed as part of the design.
## Failure classification
The FCM transport should distinguish at least:
- accepted deliveries;
- retryable provider failures;
- invalid or unregistered endpoint tokens;
- credential-refresh or provider-authentication failures;
- application/profile mismatches;
- permanent request faults;
- gateway authority or token-custody failures.
Metrics must use a closed set of labels and must never include registration tokens, pubkeys, request IDs, or other unbounded identifiers.
## Security requirements
- FCM service credentials must never be available to relay processes.
- Registration tokens must be encrypted at rest.
- A capability issued for one application profile must not be usable for another profile.
- Delivery authorization, replay prevention, and endpoint quotas must remain transactional across gateway replicas.
- Logs and metrics must not contain registration tokens or other device identifiers.
- Invalid-token handling must not let one caller revoke another installation.
- Credential and encryption-key rotation must support decrypt-only predecessor keys during a bounded migration window.
- The new profile must not weaken existing APNs validation or change current iOS behavior.
## Acceptance criteria
- [ ] An Android client can enroll an installation and receive an opaque delivery capability.
- [ ] The relay can enqueue and deliver an eligible notification through the existing gateway boundary.
- [ ] The relay never receives the raw FCM registration token.
- [ ] Retryable and permanent FCM outcomes are handled separately.
- [ ] Invalid/unregistered tokens are retired safely.
- [ ] Multiple gateway replicas share the same admission, replay, and quota state.
- [ ] Metrics expose bounded delivery outcomes without sensitive labels.
- [ ] Deployment configuration, health checks, credential rotation, and token retention are documented.
- [ ] Existing APNs profiles and tests remain unchanged.
- [ ] The Android enrollment threat model and guarantees are documented explicitly.
## Non-goals
- Building a generic plugin framework for every notification provider.
- Mattermost push compatibility.
- Per-channel notification preferences; that is a separate client-policy concern.
- Redesigning notification content in this issue.
- Sending message plaintext through push providers where the current protocol intentionally avoids it.
- Moving raw device tokens or provider credentials into the relay.
## Contribution
We are interested in contributing the FCM transport, tests, deployment changes, and documentation if this profile fits the intended `buzz-push-gateway` direction.
Contributor guide
Assessment
This issue has not been assessed yet.