platform/docs/push-notifications.md

# Push notifications — design

**Status:** agreed design, 2026-07-31. Implementation starting. Server side; the app side is a separate
document handed to the apps repo (`officer-suite/COMMS/PUSH_NOTIFICATIONS_APP.md`).

## What was decided, and what was rejected

**Apple and Google are unavoidable and we accept them.** There is no direct server→phone push on either
platform: iOS suspends apps, so only APNs can wake one, and Android only accepts pushes from FCM. An
earlier plan had these the other way round — believing iOS could be pushed to directly and Android needed
a bridge. It is the reverse.

**Expo is rejected.** Its push service is a relay in front of APNs and FCM, and it does not remove either
credential — a standalone Android build still needs an FCM service account, which you would upload *to
Expo*. All it adds is fan-out convenience, in exchange for our payloads and our APNs key living on a
fourth party's servers. We talk to Apple and Google ourselves.

**The Android foreground-service alternative is rejected for now.** A persistent socket plus a local
notification genuinely avoids Google, and the tailnet makes the connection easy. It costs a permanent
"Officer is running" entry in the notification shade and is unreliable against OEM battery managers
(Samsung, Xiaomi). Recorded here because it remains the fallback if FCM ever becomes unacceptable.

## Payload policy — the notification is a doorbell, not a message

**This is the load-bearing decision, and it is not optional.**

Both services see metadata regardless: which device, how often, at what times. What they must not see is
content. So a push carries a category and an id, never the substance:

```
✅ { type: 'mail', count: 3 }              ❌ { title: 'Re: invoice', from: 'x@y.com' }
✅ { type: 'job', id: 412, ok: false }     ❌ { error: 'ENOENT /home/pastilhas/…' }
```

The app already has a tailnet connection. On tap it fetches the real content itself. The visible text is
generic ("3 new emails"), assembled on the device from the category, not sent through Apple or Google.

Cost of both services: **free**. No per-message charge on either.

## Where it lives

A new **`officer-notify` sidecar**, PM2 peer, its own loopback HTTP listener, announced as
`notify:server` and proxied at `/api/notify` by `createSidecarProxy`.

Not the platform, because the producers are spread out — the queue, the email sidecar, the agent sidecar —
and a platform-owned notifier would force every sidecar to call *back* into the platform. That is the
inversion just removed from email. As a sidecar, anything POSTs to it over loopback.

It also absorbs `src/servers/notify/discord.ts`, so there is one outbound-notification surface with
channels behind it rather than a Discord path and a push path that do not know about each other.

```
producer (queue / email / agent / platform)
        │  POST /_officer/notify { type, ... }
        ▼
  officer-notify ─┬─ apns   → api.push.apple.com        (HTTP/2, ES256 JWT)
                  ├─ fcm    → fcm.googleapis.com/v1     (OAuth2 bearer)
                  └─ discord→ webhook                    (existing)
```

## Credentials

Env only, on the sidecar, never in the platform process and never in the database.

| var | what |
|---|---|
| `APNS_KEY_P8` | contents of the `.p8` auth key (PKCS#8 EC P-256) |
| `APNS_KEY_ID` | the key's 10-char Key ID |
| `APNS_TEAM_ID` | Apple Developer Team ID |
| `APNS_ENV` | `production` or `sandbox` — different hosts AND different tokens |
| `FCM_SERVICE_ACCOUNT` | the service-account JSON |
| `DISCORD_WEBHOOK_URL` | existing, moves here |

The `.p8` does not expire and can push to your apps forever. Treat it as spending-grade.

## Both protocols, verified in Bun before designing around them

- **APNs**: HTTP/2 only. `node:http2` works in Bun 1.3.10 (checked against a live server). Auth is an
  ES256 JWT signed with the `.p8`, valid ≤1h, refreshed no more often than every 20 min or Apple rejects
  it. **The signature must be raw `r||s` (64 bytes)** — `createSign(...).sign({ key, dsaEncoding:
  'ieee-p1363' })`. Node's default DER encoding is silently rejected.
- **FCM v1**: ordinary HTTPS. Sign an RS256 JWT with the service-account key, exchange it at
  `oauth2.googleapis.com/token` for a 1-hour access token, cache that, then POST to
  `fcm.googleapis.com/v1/projects/<id>/messages:send`.

No push library is needed for either — `node:crypto` and `node:http2` cover it. All three endpoints are
reachable from this host.

## Device registry

New table `push_devices`:

| column | note |
|---|---|
| `id` | serial |
| `user_id` | fk users |
| `token` | the native token — APNs device token or FCM registration token |
| `platform` | `ios` \| `android` |
| `environment` | `production` \| `sandbox` — an iOS dev-build token fails against prod with a silent `BadDeviceToken` |
| `bundle_id` | `apns-topic`; also distinguishes the three apps |
| `app_slug` | `mobile` \| `music` \| `read-aloud` |
| `last_seen_at`, `failure_count`, `created_at` | pruning |

Unique on `(token, bundle_id)`. Registration is idempotent: the app re-registers on every launch, since
tokens rotate.

## Failure handling — the part that is usually skipped

**APNs** answers inline: `410 Unregistered` or `400 BadDeviceToken` means delete the row immediately.

**FCM** answers inline too: `UNREGISTERED` / `INVALID_ARGUMENT` means delete.

Everything else increments `failure_count`; three strikes and the row goes. Without this the registry
fills with dead tokens and delivery quietly degrades.

(If Expo were used, this would instead require a deferred receipt poll ~15 min after send. Going direct
removes that entire mechanism — a genuine simplification, worth noting against the fan-out we gave up.)

## Open, deliberately deferred

- **Which events notify.** Out of scope by instruction: build the pipe first. Candidates when we get
  there: job finished, new mail, long agent turn done, download complete.
- **Quiet hours and batching.** New mail on an 18k-mail account is unusable at one push per message.
- **`apps/mobile` EAS/bundle id** — only `apps/music` is confirmed to have one (`dev.officer.music`).

## Build order

1. `push_devices` table + `bun db:push`.
2. `officer-notify` sidecar shell: listener, `notify:server`, PM2 entry, `/api/notify` proxy. Discord
   channel moved in — one real channel end-to-end before any push credential exists.
3. APNs channel + `POST /_officer/devices` registration.
4. FCM channel.
5. First producer wired.