platform/docs/push-notifications-app.md

# Push notifications — the app side

**Audience:** whoever builds this in `officerdev/monorepo-mobile`. **Platform status:** the server is built,
running and core; nothing on the device exists yet. **Target: iOS first, Android soon after.**

Read `docs/push-notifications.md` first — it is the design and the _why_. This document is the contract and
the build order, and it does not repeat the reasoning.

## What the server already does

- `officer-notify` runs as a core PM2 process and is reachable at `/api/notify/*`.
- `push_devices` exists in Postgres. Registration is idempotent.
- APNs and FCM channels are implemented and unit-tested; neither has ever sent a real push.
- **Missing: credentials.** Until the owner installs an APNs `.p8`, `/api/notify/_health` reports
  `{"ok":true,"channels":[]}` and every send is a silent no-op that returns success. **A green response
  does not mean a push was sent** — check `channels` first, or you will debug the app for a day over a
  server with no key.
- **Alpha is up to date as of 2026-08-19 19:xx.** `/api/notify/*` answered `404` there for most of the day
  because the server predated this work; it now answers `401` unauthenticated, `push_devices` has its 10
  columns, and `officer-notify` is running. If you get a `404`, that server needs `git pull` +
  `pm2 restart officer`, and `officer-notify` needs starting — it is a new core process, so an existing
  install will not have it until `bun gen:ecosystem` runs.

## Which app

**Only the main Officer app (`apps/mobile`) receives pushes.** It is the hub: everything arrives there and
it deep-links onward to music, chat, photos and the rest.

`apps/chat` keeps `withoutPushEntitlement.js` — that plugin is **correct** and should not be removed. Chat
uses local notifications and is not a push receiver. Same for every other app in the monorepo.

## Phase 1 — first light

The goal is one plain banner on a real device. **No codes, no mapping, no extension.** If this does not
work, nothing later will, and everything later is harder to debug.

### 1. iOS project setup

- A bundle id for `apps/mobile` — **confirmed: `dev.officer.mobile`**, plus `dev.officer.mobile.dev`.
- `aps-environment` entitlement. Do **not** copy chat's plugin here; the hub needs the opposite.
- Push capability on the App ID in the developer portal, and a provisioning profile that includes it.

### 2. Get the token and register it

Ask for permission, get the **native APNs device token** (not an Expo push token — the server talks to
Apple directly and an Expo token will be rejected as malformed), then:

```http
POST /api/notify/_officer/devices
Authorization: Bearer <the app's normal Officer session token>
Content-Type: application/json

{
  "token": "<64-hex APNs device token>",
  "platform": "ios",
  "environment": "production",
  "bundleId": "dev.officer.mobile",
  "appSlug": "mobile"
}
```

`token`, `platform`, `bundleId` and `appSlug` are **required**; a missing one is a `400` with
`{"error":"token, platform, bundleId and appSlug are required"}`. `environment` defaults to `production`.

Response: `{"ok":true,"id":<row id>}`.

**Never send a `userId`.** The server takes the user from the authenticated session and ignores the body —
that is deliberate access control, not an oversight. Sending one is harmless but will not do what it looks
like it does.

**`environment` is the classic silent failure.** An Xcode/debug build gets a **sandbox** token; TestFlight
and App Store builds get **production** ones. A sandbox token registered as `production` fails at Apple
with `BadDeviceToken` and **no user-visible symptom** — no error on the device, nothing in the app. Derive
it from the build configuration; do not hardcode it.

**Call this on every launch.** APNs tokens rotate. Registration is an upsert keyed on
`(token, bundleId)`, so re-registering is free and expected.

### 3. The other two routes

```http
GET    /api/notify/_officer/devices              → { devices: [ … ] }
DELETE /api/notify/_officer/devices/<token>      → { ok: true }
```

`GET` returns `{ id, platform, environment, bundleId, appSlug, tokenSuffix, lastSeenAt }` per row —
**tokens are never echoed in full**, only the last 8 characters, so build any "your devices" UI against
`tokenSuffix` and `id`. Call `DELETE` on sign-out.

### 4. Ask for a test push

The owner triggers one server-side. You should get an ordinary banner. That closes the loop:
credential → APNs → device → banner.

## Phase 2 — the mapping

```http
GET /api/notify/mapping    → { version: 47, entries: { "<code>": { title, body?, target, route, thread } } }
```

**Built and live** as of 2026-08-19. `Cache-Control: no-store` — the client decides by `version`, so a
cached copy would defeat the sync it drives. The catalogue is re-read from disk per request, so installing
a plugin changes the response with no restart.

Codes are namespaced `<publisher>/<appName>:<code>`, e.g. `officerdev/music:12.3`.

The app **fetches this and caches it into a shared App Group container** — shared because the notification
extension in Phase 3 must read it without the app running. Sync on launch, and whenever a push arrives
whose `mv` **differs from** the cached `version`.

**Compare with `!==`, not `>`.** `version` is a content hash, not a counter, so it does not increase
monotonically — removing a plugin returns it to the value it had before that plugin was installed. That is
deliberate: a counter would need persistent storage and would be wrong after a restore or a rollback.

Entries are templates: `title: "{n} new emails"` rendered against the push's `n`. `route` carries the deep
link with `{id}` interpolated.

## Phase 3 — the Notification Service Extension

A push arrives looking like this:

```jsonc
{
  "aps": {
    "alert": { "title": "Officer" }, // the fallback the OS shows if the extension does not run
    "mutable-content": 1,
    "sound": "default",
    "thread-id": "officerdev/music",
    "badge": 3,
  },
  "officer": { "c": "officerdev/music:12.3", "n": 3, "id": 412, "mv": 47 },
}
```

The extension resolves `c` against the **cached** mapping and rewrites the banner.

**It must not make a network request.** The lookup is a local dictionary read against the App Group cache.
This is the single most important constraint in the whole design: it is what makes notifications work when
the tailnet is down, on cellular, with the VPN off. An extension that fetches on arrival will appear to
work in every test you run at your desk and fail in the field.

**Unknown code** — the push outran the sync, or came from an uninstalled plugin:

> **Unknown notification**
> code `officerdev/music:12.3` — tap to sync

deep-linking to `officer://resync-notification-mapping`. Keep the code in the body; when this fires on the
owner's phone, _which_ code is the only useful thing to know.

That screen must be able to **give up**. An uninstalled plugin's codes are gone from the catalogue forever,
so "resync, still missing, resync" would loop. After one failed resync, say it came from something no
longer installed and stop.

**One build, ever.** The extension is a generic resolver — it must never `switch` on known codes, or every
new notification kind becomes an app store release, which is the entire thing this design exists to avoid.

Expo: `ios/` is generated by prebuild, so the NSE target comes from a config plugin. **One already exists
in this repo** — `packages/bw-vault/plugin/withVaultAutofillTarget.js` creates the AutoFill extension
target. Follow it rather than inventing one.

## Phase 4 — deep linking

`route` from the mapping is the destination. Tapping a notification opens the hub, which routes onward to
the target app or screen. The scheme is **`officer://`** (`officer-dev://` in the dev variant), from
`app.config.ts`.

## Android — later, but design for it now

No extension needed. Send **FCM data-only messages at high priority** and the app composes the notification
itself; same codes, same mapping, same cache. Register with `platform: "android"` and the FCM registration
token.

**Do not start Android before the owner settles one thing.** `apps/mobile/PUSH_NOTIFICATIONS.md`
(2026-07-24) rejects FCM because the Pixel runs GrapheneOS with no Play Services; the platform design chose
FCM a week later without addressing it. If the target device has no Play Services, FCM cannot reach it at
all and the fallback is a foreground service holding a tailnet socket. That decision changes the whole
Android build and is not yours to absorb.

## Things that will waste your time if nobody tells you

- **A successful `POST /_officer/notify` means "queued", not "delivered".** With no credentials configured
  every channel is skipped and the call still succeeds.
- **`X-Officer-User` is injected by the platform proxy.** You never set it; if you see a `401` mentioning
  it, the request bypassed the proxy.
- **Tokens are addresses, not secrets**, but the server still refuses to echo them back in full. Don't
  build anything that needs the whole token back.
- **Until 2026-08-19 a non-owner could not register a device at all** — the permission's `personal` paths
  did not match the real route. Fixed. If you test with a member account on an older server, that is why.
- **`appSlug` means the deep-link destination**, not "which app receives this". The name is a leftover from
  the first design, where each app had its own token.

## Answered, from the app repo (2026-08-19)

**Bundle ids exist.** `dev.officer.mobile`, and `dev.officer.mobile.dev` for the side-by-side dev variant.
Two bundle ids is fine and needs nothing special: `push_devices` is unique on `(token, bundleId)`, so the
two variants register as separate rows on the same phone. **Register the dev variant as
`environment: "sandbox"` and production as `"production"`** — that mapping is now concrete, so derive it
from the variant rather than the build config guesswork this document suggested earlier.

**The URL scheme is `officer://`, and `officer-dev://` in the dev variant.** Both come from
`app.config.ts`, and the share extension embeds the same string natively, so they cannot desync. So the
unknown-code fallback deep link is `officer://resync-notification-mapping` as written.

**Expo prebuild (CNG), not bare** — `ios/` is generated and gitignored; everything native comes from config
plugins. This is better news than the document assumed: **a config plugin that creates an iOS app-extension
target already exists in this repo**, `packages/bw-vault/plugin/withVaultAutofillTarget.js`, which builds
the AutoFill extension that prebuild cannot. **The NSE follows that pattern rather than being invented**,
which removes what this document called the longest pole in Phase 3.

**`expo-notifications` is NOT in `apps/mobile`** — only in `apps/chat`, for local turn alerts. Correcting
this document's assumption. Chat's `withoutPushEntitlement.js` still stays exactly as described above; the
hub needs the opposite.

## The one real blocker: the push entitlement

Today's signed build (`2026.08.19.02`) has **no `aps-environment` entitlement at all**. Nothing else in
Phase 1 can be tested until it does.

It has a known shape here. On 2026-08-05 adding a Network Extension failed for the same reason:
`-allowProvisioningUpdates` **cannot add a capability while Xcode has no account signed in**. The fix is a
one-time manual step by the owner — Xcode → Settings → Accounts, team `RGHC4NJC77` — after which it is
automatic again.

**Owner action, and it is the critical path.** Along with the APNs `.p8`, this is the whole of what stands
between here and a banner on a phone.