mirror of
https://github.com/block/buzz.git
synced 2026-10-27 04:30:52 +00:00
feat(mobile): push notifications MVP (#6269)
This PR implements MVP, iOS-only,
[NIP-PL](8d2d0ff5ad/docs/nips/NIP-PL.md)-compliant
push notifications.
A relay with `BUZZ_PUSH_ENABLED` will send a push notification for any
message that appears in the in-app Notifications tab.
## Enrollment flow
The first time the client first connects to a relay with
`BUZZ_PUSH_ENABLED`:
```mermaid
sequenceDiagram
autonumber
participant App as Buzz iOS app
participant iOS
participant Relay as Buzz relay
participant Attest as Apple App Attest
participant Gateway as Push gateway
App->>Relay: Fetch NIP-11 push capability
Relay-->>App: Push profile, current relay public key, and limits
par
App->>iOS: Request notification permission
iOS-->>App: Permission result
and
App->>iOS: Register for remote notifications
iOS-->>App: Device token
end
App->>Gateway: Request installation challenge
Gateway-->>App: Single-use challenge
App->>Attest: Attest installation transcript
Attest-->>App: Attestation proof
App->>Gateway: Enroll device token and proof
Gateway-->>App: Installation handle
App->>Gateway: Request delegation challenge
Gateway-->>App: Single-use challenge
App->>Attest: Assert relay-key delegation
Attest-->>App: Assertion
App->>Gateway: Create delegation
Gateway-->>App: Opaque endpoint grant
App->>Relay: Publish encrypted push lease and filters
Relay-->>App: Lease acknowledged
```
## Push-time flow
When a notification-eligible event is received by the relay:
```mermaid
%%{init: {
"sequence": {
"actorMargin": 20,
"width": 110,
"messageMargin": 18,
"diagramMarginX": 8,
"wrap": true
}
}}%%
sequenceDiagram
autonumber
participant Relay as Buzz relay
participant Gateway as Push gateway
participant APNs as Apple Push<br/>Notification service
participant iOS
participant NSE as Notification service<br/>extension
Relay->>Gateway: POST /v1/deliveries/apns<br/>opaque endpoint grant, request ID, expiry, NIP-98 authorization
Gateway->>APNs: POST /3/device/{device-token}<br/>topic, request ID, expiry, constant mutable-content payload
APNs-->>Gateway: 200 OK: request accepted
Gateway-->>Relay: 200 OK: accepted status
APNs-->>iOS: Notification: constant reconnect alert<br/>mutable-content = 1
iOS->>NSE: Invoke extension<br/>original notification content
NSE->>Relay: POST /query: subscription filters, limit 10<br/>NIP-98 authorization
Relay-->>NSE: 200 OK: signed Nostr events<br/>kinds 9, 40002, 45001, or 45003
NSE->>iOS: Complete notification: title, body, subtitle<br/>thread ID, exact-message target
```
relay → push gateway → APNs -> NSE -> Notification Center
## Known limitations
The APNs wake payload is intentionally constant and opaque: it contains
no originating community or message identifier, in keeping with the
implemented NIP-PL privacy design.
The Notification Service Extension must therefore reconnect to the relay
and resolve eligible messages after each wake. Around overlapping wakes,
timing boundaries, or resolution windows, notification presentation may
occasionally omit an expected message or display a message more than
once.
This best-effort behavior is deliberately accepted for the current
implementation and will be measured during the internal rollout to
determine whether the user experience is acceptable before any broader
deployment; the implementation does not claim exactly-once presentation.
## Validation
Live end-to-end hardware validation used an internal remotely hosted
development relay and push gateway, the APNs sandbox, and a physical
iPhone 12 mini:
- A second real Buzz client published a uniquely marked message through
the hosted relay.
- The relay matched the message and sent the constant opaque wake
through the hosted gateway. The gateway made an actual APNs request; no
`simctl push` or simulated notification was used.
- The iPhone received the notification on its lock screen. The
Notification Service Extension reconnected to the relay, fetched the
event, verified its ID and signature, and replaced the placeholder
content with the real notification title and body.
- After the app populated its shared presentation cache, a final marked
notification visibly showed the sender display name, sender avatar, and
hashtag-prefixed channel name.
- Tapping a lock-screen notification opened Buzz and exercised the
notification-response path and navigated to the corresponding message.
Final validation with a dogfood-signed artifact and production App
Attest/APNs configuration remains a release step.
## Independent pre-reviews
- **First pass:**
[Carl](buzz://message?channel=18882f4c-289f-41db-942f-81f6f8066da1&id=74ab9a93bb227f3e762568f1cf9fee66d7495b0edc3918735ff787238b9cc585)
found missing transient retries, executor-key rotation suppression,
duplicate installation renewal, and an unauthenticated challenge write
amplifier. These were resolved by [retry-safe
bootstrap](https://github.com/block/buzz/pull/6269/changes/12c66ea62)
and [authenticated renewal plus a cross-replica
quota](https://github.com/block/buzz/pull/6269/changes/8e5ece0bd).
[sol-max](buzz://message?channel=ad83385f-8e9e-4461-9a35-c1bf2e208532&id=d26d53daa4684669e2ed354638241f13f36c3a97027fe8b4dd738aff09038962)
found delegation generation burning and an edited applied migration,
resolved by [exact-generation
revocation](https://github.com/block/buzz/pull/6269/changes/c26d2159d)
and a [forward-only
migration](https://github.com/block/buzz/pull/6269/changes/956c1d099).
[k3-max](buzz://message?channel=5e46055d-a766-4065-ae25-05d1e4aaa6b2&id=d43139138a0b15f806cbdbeeedd8f69d992cadf2e805876db6fdde6a34c7eda1)
found no blockers.
- **Exact-head re-review:**
[Carl](buzz://message?channel=18882f4c-289f-41db-942f-81f6f8066da1&id=a897721673459301b0cf26e8b85a1478d7ebbb56a4621f93d774c98d395b8f68),
[sol-max](buzz://message?channel=ad83385f-8e9e-4461-9a35-c1bf2e208532&id=fb2159f709ec68f74f7b21459acd76da0e8a7c5c0f3d469f99826b0cc2380849),
and
[k3-max](buzz://message?channel=5e46055d-a766-4065-ae25-05d1e4aaa6b2&id=2ce2842910435f562e9d9cc718595848f281b122c94605e523a4b964254b8bfb)
independently returned **NO BLOCKERS** at `7eb3a650b`; k3-max also
revalidated every remediation and the endpoint-specific App Attest
enrollment bound.
---------
Signed-off-by: Tom Brow <tomb@squareup.com>
Signed-off-by: Tom Brow <tomb@block.xyz>
Co-authored-by: Tom Brow <tomb@squareup.com>
Co-authored-by: Codex <noreply@openai.com>
Co-authored-by: Jordan Mecom <jm@squareup.com>
This commit is contained in:
Tom Brow
@@ -264,15 +264,22 @@ This section registers the public last-hop profile served at `https://push.buzz.
|
||||
|
||||
### Registered values and lease mapping
|
||||
|
||||
The registered `app_profile` values are `buzz-ios-production` (Apple production APNs environment) and `buzz-ios-sandbox` (Apple sandbox APNs environment). A gateway deployment MUST enable only profiles for which its App Attest application identifier, APNs topic, credentials, and APNs environment are configured consistently. The APNs token registered with the gateway is called the **installation endpoint** and never leaves gateway custody after enrollment.
|
||||
The registered `app_profile` value is `buzz-ios-dogfood`. It identifies the
|
||||
closed Buzz dogfood application identity, not an APNs transport environment.
|
||||
The canonical gateway owns its exact App Attest application identifier, APNs
|
||||
topic, certificate-backed connection pool, and APNs environment. Enrollment
|
||||
succeeds only when App Attest cryptographically verifies the configured
|
||||
application identifier. The gateway MUST NOT accept an APNs topic from a client. The APNs token
|
||||
registered with the gateway is called the **installation endpoint** and never
|
||||
leaves gateway custody after enrollment.
|
||||
|
||||
The opaque string returned as `endpoint_grant` by `POST /v1/delegations` is the **delivery capability**. For this profile, the active lease plaintext's `endpoint` member MUST contain that `endpoint_grant`, not the raw APNs token. `transport` MUST be `apns`, and `app_profile` MUST equal the profile sealed into the grant. Base-protocol endpoint uniqueness, rotation, hashing, and coalescing operate on this opaque lease `endpoint` within an origin. A capability is scoped to one installation, relay signing pubkey, endpoint epoch, generation, and expiry; grants independently issued to different relays are intentionally distinct. The gateway separately enforces global installation-endpoint uniqueness using `(app_profile, SHA-256(token))`. A public-profile relay MUST treat `endpoint` as opaque and MUST NOT parse or transform it.
|
||||
|
||||
### Common HTTP and value rules
|
||||
|
||||
All routes below accept only `POST`. Clients MUST send `Content-Type: application/json`; bodies are UTF-8 JSON and MUST be at most 8192 bytes. Every request object is closed: unknown members, duplicate members at any depth, missing or incorrectly typed members, trailing non-whitespace data, or a `v` other than integer `1` are `400 {"error":"invalid_request"}`. Integers are signed JSON integers in the ranges stated below. Unix times are integer seconds. UUIDs use the canonical lowercase hyphenated representation. Relay pubkeys are exactly 64 lowercase hexadecimal characters. APNs endpoints are non-empty, even-length lowercase hexadecimal strings encoding at most 512 bytes. Challenges are exactly 32 bytes encoded as unpadded URL-safe base64. `key_id`, `attestation`, and `assertion` use padded or unpadded standard base64 as accepted by Apple's App Attest API; decoded key ids are exactly 32 bytes, attestations are 1..16384 bytes, and assertions are 1..1024 bytes. An `endpoint_grant`, including its key-id prefix, MUST be at most 4096 bytes.
|
||||
All routes below accept only `POST`. Clients MUST send `Content-Type: application/json`; bodies are UTF-8 JSON and MUST be at most 8192 bytes, except `POST /v1/installations`, whose body MUST be at most 23896 bytes. That installation-only ceiling is derived from the maximum permitted base64-encoded 16384-byte App Attest object, the maximum 512-byte APNs endpoint encoded as hex, and 1024 bytes for the remaining closed envelope. A body over its applicable limit is rejected with HTTP `413` before JSON parsing. Every request object is closed: unknown members, duplicate members at any depth, missing or incorrectly typed members, trailing non-whitespace data, or a `v` other than integer `1` are `400 {"error":"invalid_request"}`. Integers are signed JSON integers in the ranges stated below. Unix times are integer seconds. UUIDs use the canonical lowercase hyphenated representation. Relay pubkeys are exactly 64 lowercase hexadecimal characters. APNs endpoints are non-empty, even-length lowercase hexadecimal strings encoding at most 512 bytes. Challenges are exactly 32 bytes encoded as unpadded URL-safe base64. `key_id`, `attestation`, and `assertion` use padded or unpadded standard base64 as accepted by Apple's App Attest API; decoded key ids are exactly 32 bytes, attestations are 1..16384 bytes, and assertions are 1..1024 bytes. An `endpoint_grant`, including its key-id prefix, MUST be at most 4096 bytes.
|
||||
|
||||
Successful and error responses are UTF-8 `application/json`. Closed error bodies are `{"error":"invalid_request"}`, `{"error":"invalid_attestation"}`, `{"error":"not_authorized"}`, `{"error":"invalid_auth"}`, `{"error":"invalid_grant"}`, `{"error":"temporarily_unavailable"}`, `{"error":"configuration_fault"}`, or `{"error":"not_ready"}`. Authority/custody/quota rejection MUST NOT reveal whether an installation, delegation, or endpoint exists. In particular, delivery grant/authority/replay/quota failures collapse to `404 invalid_grant`; storage failures use `503 temporarily_unavailable`.
|
||||
Handler responses are UTF-8 `application/json`. Closed error bodies are `{"error":"invalid_request"}`, `{"error":"invalid_attestation"}`, `{"error":"not_authorized"}`, `{"error":"invalid_auth"}`, `{"error":"invalid_grant"}`, `{"error":"rate_limited"}`, `{"error":"temporarily_unavailable"}`, `{"error":"configuration_fault"}`, or `{"error":"not_ready"}`. Authority, custody, and quota rejection MUST NOT reveal whether an installation, delegation, or endpoint exists. Delivery grant, authority, and replay failures collapse to `404 invalid_grant`; endpoint quota exhaustion uses `429 rate_limited`; storage failures use `503 temporarily_unavailable`.
|
||||
|
||||
### Exact App Attest transcript construction
|
||||
|
||||
@@ -296,7 +303,7 @@ Success `200`:
|
||||
{"challenge_id":"<uuid>","challenge":"<base64url-no-pad-32-bytes>","expires_at":<unix-seconds>}
|
||||
```
|
||||
|
||||
The challenge is single-use. Invalid input is `400 invalid_request`; storage/randomness failure is `503 temporarily_unavailable`.
|
||||
The challenge is single-use. Invalid input is `400 invalid_request`; deployment-global challenge issuance limits return `429 rate_limited`; storage/randomness failure is `503 temporarily_unavailable`.
|
||||
|
||||
### Installation enrollment
|
||||
|
||||
@@ -305,7 +312,7 @@ The challenge is single-use. Invalid input is `400 invalid_request`; storage/ran
|
||||
Request members, in any request order:
|
||||
|
||||
```json
|
||||
{"v":1,"challenge_id":"<uuid>","challenge":"<challenge>","key_id":"<standard-base64>","attestation":"<standard-base64 CBOR>","app_profile":"buzz-ios-production","endpoint":"<lowercase APNs-token hex>","endpoint_epoch":1,"expires_at":<unix-seconds>}
|
||||
{"v":1,"challenge_id":"<uuid>","challenge":"<challenge>","key_id":"<standard-base64>","attestation":"<standard-base64 CBOR>","app_profile":"buzz-ios-dogfood","endpoint":"<lowercase APNs-token hex>","endpoint_epoch":1,"expires_at":<unix-seconds>}
|
||||
```
|
||||
|
||||
`expires_at` MUST satisfy `now < expires_at <= now + configured_max_installation_lifetime`; the selected profile MUST be enabled. The exact transcript is domain `buzz.push.enroll.v1` followed by this ordered object:
|
||||
@@ -320,7 +327,9 @@ The gateway verifies Apple's attestation chain, configured application identifie
|
||||
{"installation_handle":"<uuid>","endpoint_epoch":1,"expires_at":<unix-seconds>}
|
||||
```
|
||||
|
||||
Invalid attestation is `401 invalid_attestation`; a consumed/expired challenge or duplicate key/token is `404 not_authorized`.
|
||||
The client MUST durably journal the exact attested enrollment request before its first send and retain it until delegation state is durable. If that exact request is replayed after the installation commit, the gateway MUST return the same success response after re-verifying the attestation, even though the challenge was already consumed. Idempotency requires exact equality of attested key, profile, endpoint fingerprint, epoch, and expiration, and the recovered public key MUST equal the committed key; any mismatch remains indistinguishable from other authority rejection. This recovery rule grants no authority beyond replaying the already authenticated request.
|
||||
|
||||
Invalid attestation is `401 invalid_attestation`; a consumed/expired challenge or a key/token owned by a live installation is `404 not_authorized`. A fresh verified enrollment may replace expired or revoked ownership so an app that missed its renewal window can recover.
|
||||
|
||||
### Relay delegation and capability issuance
|
||||
|
||||
@@ -330,7 +339,7 @@ Invalid attestation is `401 invalid_attestation`; a consumed/expired challenge o
|
||||
{"v":1,"challenge_id":"<uuid>","challenge":"<challenge>","installation_handle":"<uuid>","endpoint_epoch":<positive-integer>,"generation":<positive-integer>,"relay_pubkey":"<64-lowercase-hex>","not_before":<unix-seconds>,"expires_at":<unix-seconds>,"assertion":"<standard-base64 CBOR>"}
|
||||
```
|
||||
|
||||
`not_before <= now + 300`, `not_before < expires_at`, and `expires_at <= min(now + configured_max_grant_lifetime, installation.expires_at)`. The endpoint epoch MUST equal the current installation epoch. For each `(installation_handle, relay_pubkey)`, generation MUST strictly increase. Transcript domain `buzz.push.delegate.v1`; ordered object:
|
||||
`not_before <= now + 300`, `not_before < expires_at`, and `expires_at <= now + configured_max_grant_lifetime`. The endpoint epoch MUST equal the current installation epoch. For each `(installation_handle, relay_pubkey)`, generation MUST strictly increase. A successful delegation atomically extends the authenticated installation lifetime through at least the delegation's `expires_at`, allowing renewal without duplicate token enrollment. Transcript domain `buzz.push.delegate.v1`; ordered object:
|
||||
|
||||
```json
|
||||
{"v":1,"audience":"https://push.buzz.xyz/v1/delegations","challenge_id":"<uuid>","challenge":"<challenge>","installation_handle":"<uuid>","endpoint_epoch":<integer>,"generation":<integer>,"relay_pubkey":"<hex>","not_before":<integer>,"expires_at":<integer>}
|
||||
@@ -404,7 +413,8 @@ Responses:
|
||||
- `503 {"error":"configuration_fault"}` — provider configuration fault; request reservation released after processing.
|
||||
- `400 {"error":"invalid_request"}` — malformed request or permanent APNs request fault; a provider-reached permanent fault is terminal.
|
||||
- `401 {"error":"invalid_auth"}` — absent or invalid NIP-98 authorization.
|
||||
- `404 {"error":"invalid_grant"}` — capability, signer, authority, replay, expiry, or quota rejection.
|
||||
- `404 {"error":"invalid_grant"}` — capability, signer, authority, replay, or expiry rejection.
|
||||
- `429 {"error":"rate_limited"}` — endpoint delivery quota exhausted.
|
||||
- `503 {"error":"temporarily_unavailable"}` — durable authority/custody/disposition failure.
|
||||
|
||||
The gateway performs one APNs request, except that an APNs expired-provider-token response permits one credential refresh and one retry. The application body is always the exact constant registered in the APNs transport profile above; no request or grant field enters it.
|
||||
@@ -439,4 +449,4 @@ Zombie leases (e.g. `#h` after leaving a channel) are neutralized by match-time
|
||||
- NIP-11 `supported_extensions`: contains `"nip-pl"` pre-numbering; descriptor object `push` as specified in Executor Discovery
|
||||
- Classes: `silent`, `default`, `time_sensitive`, `urgent`
|
||||
- `h_grammar` values: `"uuid-v4-lowercase"` (initial entry; origins may register additional grammars with this NIP)
|
||||
- Public APNs gateway profile: base URL `https://push.buzz.xyz`; app profiles `buzz-ios-production`, `buzz-ios-sandbox`; wire version `1`
|
||||
- Public APNs gateway profile: base URL `https://push.buzz.xyz`; app profile `buzz-ios-dogfood`; wire version `1`
|
||||
|
||||
@@ -16,21 +16,38 @@
|
||||
| `BUZZ_PUSH_PUBLIC_DELIVERY_URL` | Exact externally signed URL, normally `https://push.buzz.xyz/v1/deliveries/apns`. |
|
||||
| `BUZZ_PUSH_MAX_GRANT_LIFETIME_SECONDS` | Maximum delegation capability lifetime (`1..=31536000`). |
|
||||
| `BUZZ_PUSH_MAX_INSTALLATION_LIFETIME_SECONDS` | Maximum encrypted-token installation lifetime (default 90 days, max one year). Clients must renew before expiry. |
|
||||
| `BUZZ_PUSH_ENABLED_PROFILES` | Comma-separated `buzz-ios-production` and/or `buzz-ios-sandbox`. |
|
||||
| `BUZZ_PUSH_APP_ATTEST_APP_ID` | Exact Apple App Attest application identifier (`TEAMID.bundle-id`). |
|
||||
| `BUZZ_PUSH_APP_ATTEST_ROOT_CERT_PATH` | Read-only mounted Apple App Attest root certificate PEM. |
|
||||
| `BUZZ_PUSH_APNS_KEY_PATH` | Read-only mounted Apple APNs `.p8` provider key. |
|
||||
| `BUZZ_PUSH_APNS_KEY_ID` | APNs provider key id. |
|
||||
| `BUZZ_PUSH_APNS_TEAM_ID` | Apple developer team id. |
|
||||
| `BUZZ_PUSH_APNS_TOPIC` | Buzz iOS bundle id. |
|
||||
| `BUZZ_PUSH_DOGFOOD_APP_ATTEST_APP_ID` | Exact server-owned Apple App Attest application identifier (`TEAMID.bundle-id`). |
|
||||
| `BUZZ_PUSH_DOGFOOD_APNS_TOPIC` | Server-owned APNs topic. Never accepted from a client. |
|
||||
| `BUZZ_PUSH_DOGFOOD_APNS_ENVIRONMENT` | `production` or `sandbox`, selected by deployment configuration. |
|
||||
| `BUZZ_PUSH_DOGFOOD_APNS_CERT_PATH` | Read-only certificate/private-key PEM. |
|
||||
| `BUZZ_PUSH_GRANT_KEYS` | Capability AEAD keyring, `id:base64-32-bytes[,predecessor...]`; current key first. |
|
||||
| `BUZZ_PUSH_TOKEN_KEYS` | Independent token-custody AEAD keyring in the same format. Never reuse grant keys. |
|
||||
|
||||
The canonical `push.buzz.xyz` MVP serves the dogfood application identity
|
||||
(`xyz.block.buzz.dogfood.mobile`). App Attest must cryptographically validate
|
||||
the configured application ID before enrollment. Assertions and delivery use
|
||||
the server-owned APNs topic, certificate-backed connection pool, and
|
||||
environment. No client request or relay grant can supply or override an APNs
|
||||
topic.
|
||||
|
||||
This MVP has exactly one compiled-in application profile,
|
||||
`buzz-ios-dogfood`. The chart value
|
||||
`profiles.dogfood.appAttestAppId` is rendered as
|
||||
`BUZZ_PUSH_DOGFOOD_APP_ATTEST_APP_ID`; the gateway rejects startup when it is
|
||||
missing or empty. The exact `TEAMID.bundle-id` is environment-owned,
|
||||
non-secret deployment configuration. The chart's production values file leaves
|
||||
it empty deliberately so a production renderer must supply it from the GitOps
|
||||
environment rather than baking a Block team identifier into this repository.
|
||||
Supporting another application identity requires an explicit code, schema,
|
||||
chart, credential, and deployment change; this gateway does not currently
|
||||
select among multiple application profiles.
|
||||
|
||||
Optional endpoint quota policy variables are `BUZZ_PUSH_ENDPOINT_QUOTA_WINDOW_SECONDS` (default `10`, max `86400`) and `BUZZ_PUSH_ENDPOINT_QUOTA_MAX_DELIVERIES` (default `10`, max `10000`). These are Buzz policy hypotheses, not Apple-published limits; tune under load while retaining a hard ceiling.
|
||||
|
||||
## Secret and key rotation rules
|
||||
|
||||
Mount the App Attest root read-only and startup will reject any byte mismatch. The sole accepted artifact is Apple’s **Apple App Attestation Root CA** from `https://www.apple.com/certificateauthority/Apple_App_Attestation_Root_CA.pem`: certificate SHA-256 fingerprint `1C:B9:82:3B:A2:8B:A6:AD:2D:33:A0:06:94:1D:E2:AE:4F:51:3E:F1:D4:E8:31:B9:F7:E0:FA:7B:62:42:C9:32`; exact PEM-file SHA-256 `c778d09ac341f7fd9f8f3b19e2b815af6aed4ad4490e1e92c05cb355212a5013`. Treat an Apple root rotation as a reviewed code/config rollout, not an unpinned mount replacement. Mount the APNs key and both AEAD keyrings from a secret manager; never place values in an image, manifest, log, or metrics label. Keep the current AEAD key first and retain decrypt-only predecessors until every capability/token encrypted under them has expired or been re-encrypted. Grant and token key ids and bytes must be distinct. Rotation is an operator rollout: add the new current key while retaining predecessors, deploy, wait through the retention window, then remove the old key.
|
||||
Mount the App Attest root read-only and startup will reject any byte mismatch. The sole accepted artifact is Apple’s **Apple App Attestation Root CA** from `https://www.apple.com/certificateauthority/Apple_App_Attestation_Root_CA.pem`: certificate SHA-256 fingerprint `1C:B9:82:3B:A2:8B:A6:AD:2D:33:A0:06:94:1D:E2:AE:4F:51:3E:F1:D4:E8:31:B9:F7:E0:FA:7B:62:42:C9:32`; exact PEM-file SHA-256 `c778d09ac341f7fd9f8f3b19e2b815af6aed4ad4490e1e92c05cb355212a5013`. Treat an Apple root rotation as a reviewed code/config rollout, not an unpinned mount replacement. Mount the APNs certificate identity and both AEAD keyrings from a secret manager; never place values in an image, manifest, log, or metrics label. Keep the current AEAD key first and retain decrypt-only predecessors until every capability/token encrypted under them has expired or been re-encrypted. Grant and token key ids and bytes must be distinct. Rotation is an operator rollout: add the new current key while retaining predecessors, deploy, wait through the retention window, then remove the old key.
|
||||
|
||||
The gateway stores APNs tokens encrypted in PostgreSQL. Database backups therefore contain ciphertext plus authority metadata and must receive the same access controls and retention treatment as the service secrets.
|
||||
|
||||
@@ -44,13 +61,12 @@ The service reaps expired challenges and replay rows, idle quota rows, expired/r
|
||||
|
||||
## Metrics and alerting
|
||||
|
||||
The gateway serves Prometheus metrics at `GET /metrics` on the **private health listener** (`BUZZ_PUSH_HEALTH_ADDR`, default `0.0.0.0:8081`) — the same port as the probes, never on the public `8080`. All series are sanitized and bounded-cardinality: label values are drawn only from closed sets (the six APNs outcome classes, the fixed admission results, the static error codes already returned to callers, and the readiness causes). No endpoint, device token, relay pubkey, request id, or any request-scoped identifier is ever used as a label.
|
||||
The gateway serves Prometheus metrics at `GET /metrics` on the **private health listener** (`BUZZ_PUSH_HEALTH_ADDR`, default `0.0.0.0:8081`) — the same port as the probes, never on the public `8080`. All series are sanitized and bounded-cardinality: label values are drawn only from closed sets (the five APNs outcome classes, the fixed admission results, the static error codes already returned to callers, and the readiness causes). No endpoint, device token, relay pubkey, request id, or any request-scoped identifier is ever used as a label.
|
||||
|
||||
| Metric | Type | Labels | Meaning |
|
||||
|---|---|---|---|
|
||||
| `push_gateway_apns_deliveries_total` | counter | `outcome` = `accepted` \| `invalid_endpoint` \| `retry` \| `refresh_credential` \| `configuration_fault` \| `permanent_request_fault` | Terminal APNs send outcomes. |
|
||||
| `push_gateway_apns_deliveries_total` | counter | `outcome` = `accepted` \| `invalid_endpoint` \| `retry` \| `configuration_fault` \| `permanent_request_fault` | Terminal APNs send outcomes. |
|
||||
| `push_gateway_apns_delivery_seconds` | histogram | — | APNs send round-trip latency (seconds). |
|
||||
| `push_gateway_apns_credential_refreshes_total` | counter | — | Provider JWT refreshed after APNs reported expiry. |
|
||||
| `push_gateway_admissions_total` | counter | `result` = `admitted` \| `rejected` \| `unavailable` | Outcome at the `authorize_delivery` replay/quota fence. |
|
||||
| `push_gateway_delivery_errors_total` | counter | `class` (static) | Selected delivery-handler exit classes only (see note). |
|
||||
| `push_gateway_reaper_failures_total` | counter | — | Retention reaper sweep failures. |
|
||||
@@ -64,7 +80,7 @@ Alerting rules ship as an opt-in prometheus-operator `PrometheusRule` (`promethe
|
||||
|
||||
| Alert | Fires when | Severity | Action |
|
||||
|---|---|---|---|
|
||||
| `PushGatewayConfigurationFault` | any `configuration_fault` outcomes for 10m | critical | APNs provider token/topic is unhealthy. Check the `.p8` key, `BUZZ_PUSH_APNS_KEY_ID`, `..._TEAM_ID`, and `..._TOPIC`. No endpoints are being invalidated, but nothing is delivering. |
|
||||
| `PushGatewayConfigurationFault` | any `configuration_fault` outcomes for 10m | critical | The APNs certificate/topic/environment is unhealthy. Check `BUZZ_PUSH_DOGFOOD_APNS_*` configuration. No endpoints are being invalidated. |
|
||||
| `PushGatewayAdmissionUnavailable` | any admission `unavailable` for 5m | critical | PostgreSQL authority store is unreachable. Check DB connectivity and the pod's `postgresEgressCidrs` NetworkPolicy. |
|
||||
| `PushGatewayReadinessAuthorityFailing` | readiness `authority` failures for 5m | warning | Replicas are being pulled from the Service on DB check failure. Fix DB health before capacity drops below the PodDisruptionBudget. |
|
||||
| `PushGatewayReaperFailing` | reaper failed ≥2 times within 30m (runs every 5m) | warning | Expired reservations aren't being swept, growing the bounded-until-expiry window. Check DB write availability. |
|
||||
@@ -72,23 +88,98 @@ Alerting rules ship as an opt-in prometheus-operator `PrometheusRule` (`promethe
|
||||
|
||||
## Relay configuration
|
||||
|
||||
Relays default `BUZZ_PUSH_GATEWAY_DELIVERY_URL` to the exact public delivery URL
|
||||
`https://push.buzz.xyz/v1/deliveries/apns`. Operators can override it with
|
||||
another exact HTTPS `/v1/deliveries/apns` URL, or explicitly disable NIP-PL push
|
||||
by setting the variable to an empty string. When enabled, the relay advertises
|
||||
its host-scoped NIP-PL descriptor in NIP-11 and starts the matcher and delivery
|
||||
worker. Relays retain lease matching, authorization, coalescing, durable
|
||||
Relay push is an explicit deployment opt-in through `BUZZ_PUSH_ENABLED=true`;
|
||||
the established strict boolean parser rejects unknown values and the default is
|
||||
false. When enabled, an absent `BUZZ_PUSH_GATEWAY_DELIVERY_URL` selects the exact
|
||||
canonical URL `https://push.buzz.xyz/v1/deliveries/apns`; operators can provide
|
||||
another exact HTTPS `/v1/deliveries/apns` URL as an advanced override. An
|
||||
explicitly empty URL while enabled is a startup error. Only an enabled relay
|
||||
advertises its host-scoped NIP-PL descriptor, accepts leases, and starts the
|
||||
matcher and delivery worker. Relays retain lease matching, authorization, durable
|
||||
jobs/retries, and generation checks; they receive only opaque capabilities and
|
||||
never APNs tokens or provider credentials.
|
||||
|
||||
An enabled relay exports the following bounded-cardinality series on its
|
||||
existing Prometheus endpoint. None carries a community, account, relay key,
|
||||
installation, event, or request identifier as a label.
|
||||
|
||||
| Metric | Type | Labels | Meaning |
|
||||
|---|---|---|---|
|
||||
| `buzz_push_enabled` | gauge | — | `1` only when the deployment opt-in is active. |
|
||||
| `buzz_push_match_jobs_total` | counter | `result` = `matched` \| `unmatched` \| `error` \| `context_error` | Accepted message events evaluated by the matcher. |
|
||||
| `buzz_push_match_queue_seconds` | histogram | — | Relay receipt to matcher evaluation latency. |
|
||||
| `buzz_push_wakes_total` | counter | `result` = `enqueued` \| `duplicate` \| `inactive_lease` | Durable wake-enqueue outcomes. |
|
||||
| `buzz_push_wake_enqueue_errors_total` | counter | — | Set-wise outbox transactions that failed. |
|
||||
| `buzz_push_wake_queue_seconds` | histogram | — | First-attempt outbox enqueue-to-worker latency. |
|
||||
| `buzz_push_gateway_requests_total` | counter | — | Relay requests that reached the gateway transport seam. |
|
||||
| `buzz_push_gateway_request_seconds` | histogram | — | Relay-observed gateway request latency. |
|
||||
| `buzz_push_deliveries_total` | counter | `outcome` (static closed set) | Accepted, retried, suppressed, exhausted, invalid, or failed relay delivery outcomes. |
|
||||
|
||||
## Relay integration status
|
||||
|
||||
The operational relay integration is complete: per-origin event matching with
|
||||
read-authorization checks, durable enqueue, send-time revalidation, and NIP-98
|
||||
delivery run whenever the gateway URL is enabled. End-to-end use still requires
|
||||
delivery run only when `BUZZ_PUSH_ENABLED=true`. End-to-end use still requires
|
||||
the client App Attest enrollment/delegation flow to place a gateway-issued opaque
|
||||
capability—not a raw APNs token—into the encrypted relay lease.
|
||||
|
||||
## Internal dogfood evaluation and rollback
|
||||
|
||||
The MVP is ready to enable only when the canonical gateway's sole dogfood
|
||||
profile is configured with its server-owned App Attest app ID, APNs topic,
|
||||
production certificate identity, and production APNs environment, and only the
|
||||
selected internal relay deployments set `BUZZ_PUSH_ENABLED=true`. Every iOS
|
||||
artifact contains the native push bridge and Notification Service Extension,
|
||||
but the client remains inactive until its current authenticated relay
|
||||
advertises a fully valid NIP-11 `nip-pl` descriptor. There is no App Store
|
||||
gateway profile in this MVP.
|
||||
|
||||
Physical-device validation must use an application whose App Attest identity
|
||||
and APNs topic match the configured dogfood profile. The current gateway cannot
|
||||
enroll `xyz.block.buzz.mobile` or another bundle identifier merely by changing
|
||||
deployment values: adding another identity requires the explicit multi-profile
|
||||
work described above.
|
||||
|
||||
Dogfood end-to-end release validation starts after this feature reaches `main`:
|
||||
publish the next immutable `mobile-vX.Y.Z-rc.N` candidate from the exact current
|
||||
`origin/main` commit, build that tag through the normal Block release pipeline,
|
||||
and wait for the signed `xyz.block.buzz.dogfood.mobile` artifact to appear in
|
||||
Mobile Releases/Comp Portal before installing it on a physical device. Verify
|
||||
APNs delivery, fetched and signature-verified notification content, and
|
||||
exact-message tap routing against the canonical gateway and a push-enabled
|
||||
internal relay before widening the internal evaluation.
|
||||
|
||||
Before that first candidate, the private dogfood builder's manual signing and
|
||||
export configuration must map separate distribution
|
||||
profiles for both `xyz.block.buzz.dogfood.mobile` and
|
||||
`xyz.block.buzz.dogfood.mobile.NotificationService`; an app-only profile does
|
||||
not provision the extension. App Store rollout remains off through relay and
|
||||
gateway deployment configuration until separately approved.
|
||||
Before enabling rich message presentation, enable Apple's Communication
|
||||
Notifications capability on the parent dogfood App ID and regenerate its app
|
||||
provisioning profile. The extension profile does not need that capability.
|
||||
Apply the same parent-App-ID prerequisite to the eventual App Store rollout;
|
||||
updating Block Apple portal records is a separately authorized release step.
|
||||
|
||||
For each evaluation cohort, measure relay receipt-to-match, wake queue, relay-to-
|
||||
gateway, and gateway-to-APNs latencies from the histograms above. Track the
|
||||
ratio of accepted or replay-terminal relay outcomes to newly enqueued wakes,
|
||||
gateway APNs accepted/retry/invalid/configuration outcomes, retry exhaustion,
|
||||
and NSE resolution fallback. APNs acceptance cannot prove device presentation:
|
||||
record a small manual physical-device sample with event-created, banner-visible,
|
||||
and notification-tap timestamps, and verify that the visible title/body came
|
||||
from fetched, signature-verified relay content and that the tap opened the exact
|
||||
triggering message. Keep fallback-to-channel and placeholder/failure cases as
|
||||
explicit counts in the manual sample until privacy-preserving client telemetry
|
||||
is designed.
|
||||
|
||||
Rollback does not require deleting credentials or mutating existing leases.
|
||||
Set `BUZZ_PUSH_ENABLED=false` on the enabled relays to stop advertisement, lease
|
||||
acceptance, matching, workers, and new gateway traffic. If the gateway itself
|
||||
is unhealthy, disable the gateway deployment only after relay delivery is off.
|
||||
Existing leases and gateway authorities then expire naturally. Adding an App
|
||||
Store application profile is outside this internal evaluation.
|
||||
|
||||
## Helm production inputs
|
||||
|
||||
The chart defaults to the `main` image tag because `.github/workflows/docker.yml` publishes it from the push-gateway lane. For a production rollout, open that workflow run's **Publish public push gateway image** job summary and copy its `sha256:...` digest. Verify the published subject and provenance before injecting it:
|
||||
@@ -99,11 +190,11 @@ gh attestation verify \
|
||||
--owner block
|
||||
```
|
||||
|
||||
Only after that command succeeds, set the exact digest as `image.digest`; the chart then renders `ghcr.io/block/buzz-push-gateway@sha256:...` and ignores the mutable tag. `values-production.yaml` is an intentionally invalid production-input contract: deployment CI must inject this verified `image.digest`, the provisioned Apple application identifier, an environment-owned Gateway parent reference, and the actual PostgreSQL network. Schema validation rejects the artifact when any remains empty; the render guard proves both rejection and a fully injected render.
|
||||
Only after that command succeeds, set the exact digest as `image.digest`; the chart then renders `ghcr.io/block/buzz-push-gateway@sha256:...` and ignores the mutable tag. `values-production.yaml` is an intentionally invalid production-input contract: deployment CI must inject this verified `image.digest`, the provisioned dogfood Apple application identifier, an environment-owned Gateway parent reference, and the actual PostgreSQL network. Schema validation rejects the artifact when any remains empty; the render guard proves both rejection and a fully injected render.
|
||||
|
||||
Network policy keeps APNs HTTPS and PostgreSQL egress in separate CIDR lists. APNs currently requires broad TCP/443 reachability; `networkPolicy.postgresEgressCidrs` must be narrowed to the production database network, and the DNS namespace/pod selectors must match the cluster DNS deployment. The sample private CIDR is not a claim about the production topology.
|
||||
|
||||
Kubernetes does not restart pods when referenced Secret bytes change. AEAD or APNs credential rotation therefore requires an explicit rolling restart after the secret manager update (for example, `kubectl rollout restart deployment/<release>-buzz-push-gateway`) and readiness verification before removing predecessor keys. Service-account token automount is disabled.
|
||||
Kubernetes does not restart pods when referenced Secret bytes change. AEAD or APNs certificate rotation therefore requires an explicit rolling restart after the secret manager update (for example, `kubectl rollout restart deployment/<release>-buzz-push-gateway`) and readiness verification before removing predecessor keys. Service-account token automount is disabled.
|
||||
|
||||
## Gateway chart release
|
||||
|
||||
|
||||
Reference in New Issue
Block a user