Development-signed iOS apps cannot enroll with the current gateway
because their Apple App Attest AAGUID is rejected.
Add an explicit personal development build feature and environment
setting so a development gateway can use a developer's own application
identity and sandbox APNs credentials.
Ordinary gateway builds remain production-only. Special builds also
default to production, enforce exactly the selected signed AAGUID, and
retain certificate-chain, pinned-root, nonce, app-ID, key,
credential-ID, and counter verification.
Document the matching mobile signing configuration and expose the
feature through an optional Docker build argument.
### Validation
The development image deployed successfully to a personal Railway stack;
private readiness, enrollment challenges, authenticated relay access,
and APNs sandbox TLS/HTTP2 connectivity passed.
Signed-off-by: Tom Brow <tomb@block.xyz>
## Summary
Add the Buzz Mobile vision covering intended experience, architecture,
shared client behavior, verification, release cadence, and critical
functionality. Link it from the mobile README; the existing agent
instruction to read relevant `VISION_*.md` documents makes it
discoverable during planning and review.
### Related issue
No duplicate issue or PR found.
### Testing
Documentation-only change. Diff checks and pre-push hooks passed.
Repository-wide `just ci` is running locally; Rust formatting has
passed.
---------
Signed-off-by: Tom Brow <tomb@block.xyz>
Make the push gateway origin configurable across the relay, gateway,
mobile client, and deployment chart.
This is a fresh deployment. The gateway has only run on personal
development infrastructure, and push has no existing enabled users.
Legacy migration, configured-to-unconfigured mobile transitions, and
rolling upgrades from pre-launch gateway binaries are not supported.
Populated pre-launch databases are rejected with an informative error
before migrations run; their data is untouched. Mobile builds may omit
the gateway URL, leaving push unavailable. Once push is enabled,
subsequent builds must retain that configuration.
### Validation
- All applicable CI checks pass at
`5f546cfaf403f0386f146d213adfb4392f4ec29c`, including Rust,
mobile/Swift, desktop/integration, security, image builds, and Helm
checks. An unrelated agent cancellation test passed on retry.
- PostgreSQL CI passed 384 tests, including the production-entry-point
regression for refusing populated pre-launch databases before
migrations, fresh initialization, and subsequent initialized
deployments.
- Focused local validation passed all 10 gateway PostgreSQL tests under
the CI discovery filter and all 3 unconfigured-mobile tests.
Repository-wide PostgreSQL discovery validation and the complete
pre-push hooks passed.
- Physical-device APNs/App Attest behavior and deployment to a live
cluster were not verified in this work.
---------
Signed-off-by: Tom Brow <tomb@block.xyz>
Co-authored-by: Codex <noreply@openai.com>
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>
## Summary
- align the mobile security-code confirmation screen with the Add
Community visual system while keeping the SAS verification flow
unchanged
- use “Confirm desktop code” and a 15% primary-color outline on each
digit box
- support a gitignored, debug-only Android app name and application ID
override for side-by-side device testing; release and profile identities
remain unchanged
## Validation
- `flutter test test/features/pairing/pairing_page_test.dart` (21 tests)
- full mobile pre-push suite (1,469 tests)
- focused Flutter analysis and formatting
- mobile worktree identity contract checks
---------
Signed-off-by: kenny lopez <klopez4212@gmail.com>
Signed-off-by: Wes <wesbillman@users.noreply.github.com>
Co-authored-by: Wes <wesbillman@users.noreply.github.com>
Co-authored-by: Carl <c7ebe626f000404285d3686e1dc74cc07cc60a9754a150041ba132e14bd3e2ec@buzz.block.builderlab.xyz>
## Summary
- allow agents to build and run Flutter when it provides relevant
implementation or validation evidence
- keep mobile iteration fast by reusing simulators, incremental builds,
and configured staging or production communities
- correct stale CLI, E2E, CI, worktree formatting, and mobile launch
guidance
- point community singleton reset guidance at the canonical
implementation instead of duplicating a drifting inventory
## Validation
- `git diff --check origin/main..HEAD`
- `cargo run -q -p buzz-cli -- --format compact messages thread --help`
- `cargo run -q -p buzz-cli -- --format compact messages search --help`
- `just desktop-tauri-fmt-check` from the worktree
- pre-commit: mobile Dart formatting and `flutter analyze`
- pre-push: branch-skew check and full mobile test suite (1,465 tests)
Signed-off-by: Wes <wesbillman@users.noreply.github.com>
Co-authored-by: Carl <c7ebe626f000404285d3686e1dc74cc07cc60a9754a150041ba132e14bd3e2ec@buzz.block.builderlab.xyz>
**Category:** improvement
**User Impact:** Developers can identify which worktree produced a
mobile debug app, keep a bounded set of worktree builds installed side
by side, and preserve each worktree app's login and local state while
switching branches.
**Problem:** Mobile debug builds from every checkout currently appear as
the same “Buzz” app and share one application identity, so the running
source is ambiguous and one worktree build replaces another. A
branch-keyed identity would avoid replacement but create stale installs
and fresh app state on every branch switch.
**Solution:** Give each linked worktree a stable Debug-only application
identity derived from its sanitized directory name. Show the sanitized
branch name (or short commit SHA when detached) in the display label,
persist generated native overrides for direct IDE builds, and leave
Release/Profile identities unchanged. Worktree defaults remain lower
precedence than a developer's iOS `AppOverrides.xcconfig`. `just
mobile-clean` provides a safe cleanup path for suffixed worktree
installs while preserving production Buzz.
<details>
<summary>File changes</summary>
**.github/workflows/ci.yml**
Runs the expanded worktree override contract when relevant mobile or
native configuration changes.
**AGENTS.md**
Documents worktree-aware mobile development and cleanup for contributors
and agents.
**Justfile**
Generates overrides before mobile development and Android debug builds,
and exposes `just mobile-clean`.
**mobile/README.md**
Explains stable per-worktree identities, branch/SHA labels, direct IDE
usage, cleanup, and Release/Profile guarantees.
**mobile/android/.gitignore**
Ignores generated worktree properties.
**mobile/android/app/build.gradle.kts**
Loads and validates generated properties, then applies the application
ID suffix and display label to Android Debug only.
**mobile/android/app/src/main/AndroidManifest.xml**
Resolves the Android app label through an overridable string resource.
**mobile/ios/.gitignore**
Ignores generated iOS worktree settings.
**mobile/ios/Flutter/Debug.xcconfig**
Loads generated worktree defaults before developer `AppOverrides`, so
personal signing overrides retain precedence.
**mobile/ios/Flutter/Release.xcconfig**
Pins the production display name and bundle identifier for
Release/Profile builds.
**mobile/ios/Runner/Info.plist**
Resolves the visible iOS app name from build settings.
**scripts/mobile-worktree-overrides.sh**
Detects linked worktrees, derives a stable directory-keyed identity,
sanitizes branch/SHA display context, writes native Debug overrides, and
removes stale overrides in the main checkout.
**scripts/mobile-worktree-clean.sh**
Lists or removes suffixed Buzz worktree installs from booted iOS
simulators and connected Android emulators without matching production
IDs; supports `--dry-run`.
**scripts/test-mobile-worktree-overrides.sh**
Covers worktree detection, branch-switch identity stability, detached
HEAD fallback, special-character sanitization, iOS override precedence,
brace-aware Release/Profile purity, cleanup safety, ignores, and command
integration.
</details>
## Reproduction steps
1. From a linked worktree, activate the repository toolchain and run
`just mobile-dev`.
2. Inspect the running app: its label should be `Buzz
(<sanitized-branch>)`, while its application ID suffix is derived from
the worktree directory.
3. Switch branches in the same worktree, rerun the override script, and
confirm the application ID remains stable while the display label
updates. In detached HEAD, confirm the label uses a short SHA.
4. Build Debug from a second worktree and confirm both apps remain
installed side by side with independent state.
5. Build from Xcode after setting `AppOverrides.xcconfig` and confirm
developer overrides still win over generated worktree defaults.
6. Run `just mobile-clean --dry-run`, then `just mobile-clean`, and
confirm suffixed worktree installs are targeted while the production app
is preserved.
7. Build Release/Profile and confirm the production name and application
identity remain unchanged.
8. Run `scripts/test-mobile-worktree-overrides.sh`, `just mobile-check`,
`just mobile-test`, and `just mobile-build-android`.
## Screenshots / demos
| iOS — labeled app switcher | iOS — side-by-side installs |
| --- | --- |
| <img width="360" alt="Buzz worktree label in the iOS app switcher"
src="https://github.com/user-attachments/assets/4bcae067-7ce5-4333-bb11-2803c4107663"
/> | <img width="360" alt="Buzz production and worktree debug apps
installed side by side on iOS"
src="https://github.com/user-attachments/assets/08a107b5-fdf2-463a-8a4c-81d41d7bf5e7"
/> |
| Android — side-by-side installs | Android — labeled app switcher |
| --- | --- |
| <img width="360" alt="Buzz production and worktree debug apps
installed side by side on Android"
src="https://github.com/user-attachments/assets/4f5841a1-adae-42da-ae84-47c09ec85fb9"
/> | <img width="360" alt="Buzz worktree label in the Android app
switcher"
src="https://github.com/user-attachments/assets/0546ff51-efcc-4cb6-a4bd-2a3af26cd60f"
/> |
---------
Signed-off-by: Taylor Ho <taylorkmho@gmail.com>
Co-authored-by: npub1223z34hd7vtwc6qj4s7flsxkj644nlre2nthu7lrrmkumhu3xddsrx9r6w <52a228d6edf316ec6812ac3c9fc0d696ab59fc7954d77e7be31eedcddf91335b@buzz.block.builderlab.xyz>
