@openchambery/web 1.18.7-beta.1 → 1.18.7-beta.3

package/server/lib/notifications/APNS.md

@@ -13,19 +13,57 @@ registered them — so a leaked device token alone can't be used to push.
    `POST /v1/push/register-token`, signed with its auto-generated ECDSA P-256 key
    (`getOrCreateRelayKeypair`, persisted in settings like the VAPID keys). The relay records
    `token → serverId` where `serverId = SHA-256(publicKey)`.
-3. On a trigger (ready/error/question/permission), the server composes **generic, content-free**
-   text — a fixed scenario title ("Agent response is ready" / "Agent needs your input" / "Agent
-   needs permission" / "Agent hit an error") + the **session name** as the body, no model/project/
-   message content — plus a **`badge`** count (see below) — and POSTs `{ tokens, title, body,
-   badge, env, data:{sessionId}, publicKeyJwk, ts, sig }` to `POST /v1/push/send`
-   (`apns-runtime.js` → `sendViaRelay`). It does **not** gate on UI visibility (see below).
-4. The **relay** (`openchamber-website/apps/api`, Cloudflare Worker) verifies the signature +
-   `ts` freshness, derives `serverId`, and only delivers to tokens bound to that server. It holds
-   the single project APNs `.p8` key, signs an ES256 JWT with `crypto.subtle`, and sends each
-   token to APNs over HTTP/2, returning per-token results; the server drops tokens flagged `drop`
-   (410 / BadDeviceToken). The relay stores no secret — only `token → serverId` hashes.
+ 3. On a trigger (ready/error/question/permission/goal_*), the server composes **generic,
+    content-free** text — a **locale-specific** scenario title (from `apns-titles.js`, keyed off
+    the locale stored with each device token at `POST /api/push/apns-token`) + the **session name**
+    as the body, no model/project/message content — plus a **`badge`** count (see below). Tokens
+    are grouped by locale (relay signatures cover `title`, so mixed locales cannot share one
+    batch) and each group POSTs `{ tokens, title, body, badge, env, data:{sessionId},
+    publicKeyJwk, ts, sig }` to `POST /v1/push/send` (`apns-runtime.js` → `sendViaRelay`). It does
+    **not** gate on UI visibility (see below). Legacy tokens without a locale fall back to English.
+4. The **Push Relay** (`packages/relay-server/src/push/`, process `openchamber-push-relay`)
+   verifies the signature + `ts` freshness, derives `serverId`, and only delivers to tokens bound
+   to that server. It holds the project APNs `.p8` key, signs an ES256 JWT with Node crypto, and
+   sends each token to APNs over HTTP/2, returning per-token results; the server drops tokens
+   flagged `drop` (410 / BadDeviceToken). The Push database stores `token → serverId` bindings,
+   not application plaintext. Layer 1 (`openchamber-relay`) never sees these secrets.
 5. Tapping a push deep-links to its session via the forwarded `sessionId`.
 
+## Live Activity (update / end)
+
+ActivityKit has issued **update/end push tokens** for an Activity that is
+**already started on-device** since **iOS 16.1**. **Push-to-start** (creating an
+Activity from APNs while the app is not running) is **iOS 17.2+** and is not
+part of this Host path.
+
+The native app registers a Live Activity token with **its own server**
+(`POST /api/push/live-activity-token`: `token`, `activityId`, `sessionId`).
+Those tokens are stored separately from alert APNs device tokens (same
+`apns-tokens.json` file, `version` 2 `liveActivityTokensBySession`; v1 alert
+data remains readable) and are never used for banner push. The Host binds them
+on the relay at `POST /v1/push/register-live-activity-token` with
+`{ token, platform: "ios", kind: "liveactivity", publicKeyJwk, ts, sig }` signed
+over `${ts}.${token}.${platform}.${kind}`. Unregister uses
+`/v1/push/unregister-live-activity-token` with the same signature, and only the
+owning UI session may delete a local token.
+
+On top-level session **completion** or **error** (child sessions and small-model
+system sessions suppressed; independent of ordinary notification settings and UI
+visibility) the Host calls `sendLiveActivityEnd`. Relay send is
+`POST /v1/push/live-activity` with `{ tokens, event, contentState,
+dismissalDate?, staleDate?, publicKeyJwk, ts, sig }` signed over
+`${ts}.${sortedTokens}.${event}.${status}.${eventVersion}.${updatedAt}.${endedAt}.${dismissalDate}.${staleDate}`.
+Direct mode uses HTTP/2 token auth, `apns-topic: ${bundleId}.push-type.liveactivity`,
+`apns-push-type: liveactivity`, and no alert.
+
+The APNs / relay payload **must not** carry `sessionId` or user/session content.
+`contentState` is only `{ status, eventVersion, updatedAt, endedAt }`.
+`complete` uses a 15-minute dismissal and `error` a 60-minute dismissal (same as
+native). `staleDate = updatedAt + 20min` is for **update** events only. After a
+successfully accepted `end`, the Host clears the local Activity tokens for those
+devices. A Live Activity failure does not drop alert tokens or block ordinary
+push. Do not log Live Activity tokens or session ids.
+
 ## Foreground suppression
 
 APNs is **not** gated on UI visibility. A backgrounded WKWebView can't reliably report "hidden"
@@ -34,8 +72,8 @@ responses. Instead the server always sends, and **iOS** suppresses the foregroun
 (`PushNotifications.presentationOptions: []` in `capacitor.config`) — so there is no notification
 while the app is active, with no race. APNs is the native app's **only** channel; local
 notifications were removed (a WKWebView can't tell foreground from background — `document.hasFocus()`
-is unreliable — so they leaked while the app was open). Cloudflare is touched only when a native
-app with notifications on has a registered token and a trigger fires.
+is unreliable — so they leaked while the app was open). The Push Relay is contacted only when a
+native app with notifications on has a registered token and a trigger fires.
 
 ## App-icon badge
 
@@ -61,36 +99,45 @@ mirrors the device zeroing its icon badge on `sceneDidBecomeActive` (`AppDelegat
 server and device in sync.
 
 The value flows `runtime.js` (`toApnsGenericPayload`) → `apns-runtime.js` (`sendViaRelay` body /
-direct-mode `aps.badge`) → relay (`pushSendSchema.badge` → `aps.badge`). It is **not** signed (like
-`body`/`data`); the relay still only delivers to bound tokens. The set is server-global, so every
-device token of a server sees the same badge.
+direct-mode `aps.badge`) → Push Relay (`packages/relay-server/src/push/schema.js` → `aps.badge`).
+It is **not** signed (like `body`/`data`); the relay still only delivers to bound tokens. The set
+is server-global, so every device token of a server sees the same badge.
 
 ## Modes
 
-- **Relay (default):** server has no Apple key; `OPENCHAMBER_PUSH_RELAY_URL` defaults to
-  `https://api.openchamber.dev/v1/push/send` (register URL is derived as `…/register-token`).
+- **Relay (default):** Host has no Apple key. Unless `OPENCHAMBER_PUSH_RELAY_URL` is set, the
+  Host maps the effective Relay `wss://`/`ws://` URL to the same host as `https://`/`http://`
+  `/v1/push/send` (register URL is `/v1/push/register-token`). A Relay switch re-registers
+  persisted tokens and binds them again before the first send.
 - **Direct (fallback):** set `OPENCHAMBER_PUSH_RELAY_DISABLED=true` + `OPENCHAMBER_APNS_KEY_ID/
   TEAM_ID/P8` to sign+send from the server itself (HTTP/2 + ES256 JWT); no relay binding needed.
 
 ## Config
 
-Server (`apns-runtime.js`):
-- `OPENCHAMBER_PUSH_RELAY_URL` (default the public relay), `OPENCHAMBER_APNS_ENVIRONMENT`
-  (`sandbox` default / `production`). The signing keypair is auto-generated — nothing to set.
+Host (`apns-runtime.js`):
+- `OPENCHAMBER_PUSH_RELAY_URL` (explicit send-URL override), `OPENCHAMBER_APNS_ENVIRONMENT`
+  (`sandbox` default / `production` for TestFlight and App Store). The signing keypair is
+  auto-generated — nothing to set.
 - Direct fallback: `OPENCHAMBER_APNS_KEY_ID`, `OPENCHAMBER_APNS_TEAM_ID`, `OPENCHAMBER_APNS_P8`
   (or `_P8_PATH`), `OPENCHAMBER_APNS_BUNDLE_ID`, `OPENCHAMBER_PUSH_RELAY_DISABLED=true`.
 
-Relay (Cloudflare Worker secrets via `wrangler secret put` / GitHub Actions): `APNS_P8`,
-`APNS_KEY_ID`, `APNS_TEAM_ID`, optional `APNS_BUNDLE_ID` / `APNS_DEFAULT_ENV`. The `push_tokens`
-binding table is created by `migrations/0002_push_tokens.sql` (applied on deploy).
+Push process (`packages/relay-server/src/push/`, env prefix `OPENCHAMBER_PUSH_RELAY_`):
+`HOST` (default `127.0.0.1`), `PORT` (default `8788`), `TRUST_PROXY`, `DATABASE_PATH`,
+timestamp/replay/rate-limit/token/`MAX_IN_FLIGHT` limits, plus APNs `APNS_KEY_ID`,
+`APNS_TEAM_ID`, `APNS_BUNDLE_ID`, and `APNS_P8` or `APNS_P8_PATH`. See
+`packages/relay-server/README.md`. SQLite is single-instance. Do not log `.p8` material,
+device tokens, or signatures.
 
 ## Apple setup (one-time)
 
 1. Apple **Keys** (not Certificates) → create an **APNs Auth Key** (`.p8`) → Key ID + Team ID;
-   enable **Push Notifications** on App ID `com.openchamber.app`.
-2. In the **openchamber-website** repo → Actions secrets: `APNS_P8` (PEM), `APNS_KEY_ID`,
-   `APNS_TEAM_ID`. Push to `main` → relay deploys, secrets sync, D1 migrations apply.
+   enable **Push Notifications** on the App ID. TestFlight / App Store builds of this product
+   use bundle ID `com.yee94.openchamber`.
+2. Give those values only to the Push process (environment or Docker secret). Do not put the
+   `.p8` on Layer 1 or on each OpenChamber Host when using Relay mode.
 3. Xcode: confirm the Push Notifications capability; Clean Build Folder; run on device.
+   Development builds use APNs `sandbox`. TestFlight and App Store Hosts set
+   `OPENCHAMBER_APNS_ENVIRONMENT=production`.
 
 ## Security posture
 
@@ -98,10 +145,12 @@ binding table is created by `migrations/0002_push_tokens.sql` (applied on deploy
   is signed by the server's private key, and the relay only delivers to a token from its bound
   `serverId`. A leaked token alone is useless — an attacker has neither the private key nor a
   matching binding.
-- `serverId` self-certifies (`SHA-256(publicKey)`), so the relay holds no secret; a D1 leak
-  exposes only `token → serverId` hashes. The signed `ts` (±5 min window) blocks replay.
+- `serverId` self-certifies (`SHA-256(publicKey)`). A SQLite leak exposes `token → serverId`
+  bindings, not Host private keys or application plaintext. The signed `ts` (±5 min window)
+  blocks replay. Signature verification lives in `packages/relay-server/src/push/crypto.js`
+  and must stay aligned with `packages/web/server/lib/relay/signing-key.js`.
 - Residual: trust-on-first-bind (whoever registers a token first owns it) — acceptable, since
-  registering already requires possessing the token. Cloudflare rate limiting is defence-in-depth.
+  registering already requires possessing the token. Process rate limits are defence-in-depth.
 
 ## Data confidentiality (what the relay / Apple can see)
 
@@ -113,17 +162,18 @@ to APNs). The request **signature is authentication, not encryption** — the re
 Who can read the alert text:
 
 - **Network hops:** nothing (TLS).
-- **The relay (Cloudflare):** the generic title + body (session name), the device token, and
-  `sessionId`. It stores only `token → serverId` hashes (no text, no payload).
+- **The Push Relay process:** the generic title + body (session name), the device token, and
+  `sessionId`. It stores `token → serverId` bindings (no alert text, no payload).
 - **Apple APNs:** the alert text too — APNs always reads the alert payload of an `alert` push.
 - **The device:** displays it.
 
-This is acceptable **because the text is deliberately content-free**: a fixed scenario title +
-the session name only — no model, project, or message content (`runtime.js` →
-`toApnsGenericPayload`). The session name is the single semi-personal field that crosses the
-relay/Apple. To hide even that from Apple would require an end-to-end **encrypted payload**
-(`mutable-content` + a Notification Service Extension that decrypts on-device with a key never
-sent to the relay) — not implemented, and unnecessary for generic text.
+This is acceptable **because the text is deliberately content-free**: a fixed scenario title
+(localized per device) + the session name only — no model, project, or message content
+(`runtime.js` → `toApnsGenericPayload` → `localizeApnsPayload`). The session name is the single
+semi-personal field that crosses the relay/Apple. To hide even that from Apple would require an
+end-to-end **encrypted payload** (`mutable-content` + a Notification Service Extension that
+decrypts on-device with a key never sent to the relay) — not implemented, and unnecessary for
+generic text.
 
 ## Android (FCM) note
 

package/server/lib/notifications/DOCUMENTATION.md

@@ -7,7 +7,7 @@ This module provides notification message preparation utilities for the web serv
 - `packages/web/server/lib/notifications/index.js`: public entrypoint imported by `packages/web/server/index.js`.
 - `packages/web/server/lib/notifications/routes.js`: route registration for push, visibility, and session status/attention endpoints.
 - `packages/web/server/lib/notifications/push-runtime.js`: push subscription persistence, VAPID initialization, and UI visibility runtime.
-- `packages/web/server/lib/notifications/apns-runtime.js`: native iOS APNs device-token persistence + delivery. Two modes: **relay** (default — sign + POST tokens + generic text to the central Cloudflare relay `https://api.openchamber.dev/v1/push/send`, which holds the single project APNs key) and **direct** (fallback — sign ES256 JWT with Node crypto + HTTP/2, when `OPENCHAMBER_PUSH_RELAY_DISABLED=true`). Each server has an auto-generated ECDSA P-256 keypair (`getOrCreateRelayKeypair`, persisted in settings); it binds tokens on the relay (`/v1/push/register-token`) and signs every relay request, so the relay only delivers to tokens bound to that server. APNs is the native app's sole notification channel (no local notifications) and is NOT gated on UI visibility — iOS suppresses the foreground banner instead. Mobile push carries only generic text (scenario title + session name) — see `APNS.md`.
+- `packages/web/server/lib/notifications/apns-runtime.js`: native iOS APNs device-token persistence + delivery, plus a separate Live Activity token store and `end` send path. Two modes: **relay** (default — sign + POST tokens + generic text to the isolated Push Relay in `packages/relay-server/src/push/`, which holds the project APNs key) and **direct** (fallback — sign ES256 JWT with Node crypto + HTTP/2, when `OPENCHAMBER_PUSH_RELAY_DISABLED=true`). Unless `OPENCHAMBER_PUSH_RELAY_URL` is set, the Host maps the effective Relay `wss`/`ws` URL to the same host as `https`/`http` `/v1/push/send`. Before each relay send, the runtime checks an in-memory registration success cache (keyed by current register URL + token + platform) and only POSTs `/v1/push/register-token` for cache misses; only successfully bound tokens are sent. Switching Relay/Push URL clears that cache so persisted tokens re-bind to the new origin on the next send or `reRegisterAllTokens()`. Each server has an auto-generated ECDSA P-256 keypair (`getOrCreateRelayKeypair`, persisted in settings); it binds tokens on the relay (`/v1/push/register-token`) and signs every relay request, so the relay only delivers to tokens bound to that server. APNs is the native app's sole notification channel (no local notifications) and is NOT gated on UI visibility — iOS suppresses the foreground banner instead. Mobile push carries only generic text (scenario title + session name) — see `APNS.md`. Live Activity tokens are persisted beside alert tokens in the same file (`version` 2, `liveActivityTokensBySession`) without mixing the two token types; v1 files remain readable. Live Activity relay bind/send uses `/v1/push/register-live-activity-token`, `/v1/push/unregister-live-activity-token`, and `/v1/push/live-activity`.
 - `packages/web/server/lib/notifications/emitter-runtime.js`: desktop/stdout + UI SSE notification emission runtime.
 - `packages/web/server/lib/notifications/runtime.js`: trigger runtime for OpenCode event-driven notification fanout.
 - `packages/web/server/lib/notifications/template-runtime.js`: notification template variables and session text/title enrichment runtime. Zen-model helpers are retained as compatibility stubs only.
@@ -27,6 +27,8 @@ This module provides notification message preparation utilities for the web serv
   - `DELETE /api/push/subscribe`
   - `POST /api/push/apns-token` (native iOS APNs device-token registration)
   - `DELETE /api/push/apns-token`
+  - `POST /api/push/live-activity-token` (native iOS Live Activity token registration; UI-auth, length-limited `token` / `activityId` / `sessionId`)
+  - `DELETE /api/push/live-activity-token` (owning UI session only)
   - `POST /api/push/visibility`
   - `GET /api/push/visibility`
   - `GET /api/notifications/stream`
@@ -46,6 +48,7 @@ This module provides notification message preparation utilities for the web serv
   - `maybeSendPushForTrigger(payload)`
 - Owns:
   - top-level completion/question/permission trigger routing; completion is the sole task-status notification and child sessions plus small-model system sessions (`metadata.openchamber.smallModel.purpose`) are suppressed
+  - top-level completion/error Live Activity `end` (`sendLiveActivityEnd`), independent of ordinary push settings and UI visibility, with the same child/small-model suppression; duplicate terminal events are idempotent at the token store
   - session meta cache for child-session and small-model suppression
   - template resolution and fallback behavior
   - native notification fanout and web push payload fanout
@@ -67,12 +70,16 @@ This module provides notification message preparation utilities for the web serv
 ### APNs runtime API (apns-runtime.js)
 - `createApnsRuntime(dependencies)`: creates runtime for native iOS APNs push and device-token state. Dependencies: `fsPromises`, `path`, `crypto`, `http2`, `APNS_TOKENS_FILE_PATH`, `readSettingsFromDiskMigrated`, `writeSettingsToDisk` (persists the auto-generated relay signing keypair).
 - Returned API:
-  - `addOrUpdateApnsToken(uiSessionToken, deviceToken, userAgent)` — also binds a newly-seen token on the relay (signed `/v1/push/register-token`).
+  - `addOrUpdateApnsToken(uiSessionToken, deviceToken, userAgent, platform?, locale?)` — also binds a newly-seen token on the relay (signed `/v1/push/register-token`). Persists app UI `locale` for localized push titles.
   - `removeApnsToken(uiSessionToken, deviceToken)`
   - `removeApnsTokenFromAllSessions(deviceToken)`
-  - `sendApnsToAllUiSessions(payload)` — signs + sends to all registered tokens (no UI-visibility gate; iOS suppresses the foreground banner). No-ops with a single warning when APNs is unconfigured. Drops tokens on `410` / `BadDeviceToken` / `Unregistered`.
+  - `addOrUpdateLiveActivityToken(uiSessionToken, token, activityId, sessionId)` — idempotent upsert bound to the UI session + OpenCode `sessionId` + ActivityKit `activityId`. Token refresh replaces that activity's previous token. Caps per UI session and lazily expires stale entries. Binds on the relay (`/v1/push/register-live-activity-token`, `kind: "liveactivity"`). Does not log tokens or session ids.
+  - `removeLiveActivityToken(uiSessionToken, token)` — owning UI session only; unregisters from the relay when no local copies remain.
+  - `sendLiveActivityEnd({ sessionId, status, eventVersion?, endedAt? })` — looks up Live Activity tokens for that OpenCode session and sends `event: "end"` with `contentState` `{ status, eventVersion, updatedAt, endedAt }` only. `complete` dismisses after 15 minutes, `error` after 60 minutes (same as native). `staleDate` (`updatedAt + 20min`) is update-only and omitted on end. `eventVersion` is monotonic per session using current milliseconds. Relay body follows the signed live-activity contract; direct mode uses token auth, topic `${bundleId}.push-type.liveactivity`, `apns-push-type: liveactivity`, and no alert. APNs payloads must not carry `sessionId` or user content. Successfully accepted tokens are cleared locally; failures do not drop alert tokens or block ordinary push.
+  - `sendApnsToAllUiSessions(payload)` — localizes scenario titles per stored token locale (`apns-titles.js`), groups tokens by locale, then signs + sends (no UI-visibility gate; iOS suppresses the foreground banner). Before a relay send, each token is checked against the in-memory registration success cache for the current register URL; cache hits skip `/v1/push/register-token`, misses are registered with bounded concurrency, and only successfully bound tokens are sent. Switching Relay/Push URL clears that cache so the next send re-binds persisted tokens to the new origin. No-ops with a single warning when APNs is unconfigured. Drops tokens on `410` / `BadDeviceToken` / `Unregistered`. Never sends Live Activity tokens.
+  - `reRegisterAllTokens()` — binds every persisted device token to the current Push origin (same success cache and URL-switch invalidation as send).
   - `resolveApnsConfig()`
-- Configuration (env first, then `settings.apnsConfig`): `OPENCHAMBER_APNS_KEY_ID`, `OPENCHAMBER_APNS_TEAM_ID`, `OPENCHAMBER_APNS_P8` (PEM contents; literal `\n` accepted) or `OPENCHAMBER_APNS_P8_PATH`, `OPENCHAMBER_APNS_BUNDLE_ID` (default `com.openchamber.app`), `OPENCHAMBER_APNS_ENVIRONMENT` (`sandbox` default, or `production`).
+- Configuration (env first, then `settings.apnsConfig`): `OPENCHAMBER_PUSH_RELAY_URL` (optional send-URL override), `OPENCHAMBER_PUSH_RELAY_DISABLED`, `OPENCHAMBER_APNS_KEY_ID`, `OPENCHAMBER_APNS_TEAM_ID`, `OPENCHAMBER_APNS_P8` (PEM contents; literal `\n` accepted) or `OPENCHAMBER_APNS_P8_PATH`, `OPENCHAMBER_APNS_BUNDLE_ID` (default `com.yee94.openchamber`), `OPENCHAMBER_APNS_ENVIRONMENT` (`sandbox` default, or `production` for TestFlight and App Store).
 
 ### Emitter runtime API (emitter-runtime.js)
 - `createNotificationEmitterRuntime(dependencies)`: creates runtime for unified notification emission channels.