@openchambery/web 1.19.0-beta.4 → 1.19.0-beta.41

package/server/lib/notifications/APNS.md

@@ -13,17 +13,20 @@ 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`.
 
 ## Foreground suppression
@@ -34,8 +37,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 +64,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 +110,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 +127,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. 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`.
 - `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.
@@ -67,12 +67,13 @@ 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`.
+  - `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`.
+  - `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.

package/server/lib/notifications/apns-runtime.js

@@ -2,8 +2,9 @@
 //
 // Device tokens are persisted per UI session (mirrors push-runtime.js). Delivery has two
 // modes, chosen at send time:
-//   - Relay (default): POST tokens + generic text to the central Cloudflare relay, which
-//     holds the single project APNs key and signs+sends — so users configure nothing.
+//   - Relay (default): POST tokens + generic text to the same-origin Push service
+//     (`/v1/push/*` on the effective Relay host). The isolated Push process holds the
+//     project APNs key and signs+sends — so users configure nothing.
 //   - Direct (fallback): sign an ES256 JWT with Node crypto and send over HTTP/2 ourselves,
 //     for self-hosters who set OPENCHAMBER_APNS_* and OPENCHAMBER_PUSH_RELAY_DISABLED=true.
 // Wired into the same trigger fanout as web push (see runtime.js); the relay carries only
@@ -13,18 +14,46 @@ import {
   getOrCreateRelaySigningKeypair,
   signRelayMessage as signRelayMessageShared,
 } from '../relay/signing-key.js';
+import { DEFAULT_RELAY_URL, derivePushSendUrlFromRelayUrl } from '../relay/service.js';
+import {
+  APNS_DEFAULT_LOCALE,
+  localizeApnsPayload,
+  normalizeApnsLocale,
+} from './apns-titles.js';
 
 const APNS_TOKENS_VERSION = 1;
 const APNS_HOST_PRODUCTION = 'https://api.push.apple.com';
 const APNS_HOST_SANDBOX = 'https://api.sandbox.push.apple.com';
 // APNs rejects auth tokens older than 1h; refresh well inside that window.
 const JWT_TTL_MS = 50 * 60 * 1000;
-const DEFAULT_BUNDLE_ID = 'com.openchamber.app';
-const DEFAULT_RELAY_URL = 'https://api.openchamber.dev/v1/push/send';
+const DEFAULT_BUNDLE_ID = 'com.yee94.openchamber';
 const MAX_TOKENS_PER_SESSION = 10;
+const MAX_RELAY_SEND_TOKENS = 100;
+const RELAY_REGISTER_CONCURRENCY = 16;
+const APNS_COLLAPSE_ID_MAX_BYTES = 64;
 // APNs reasons that mean the token is permanently invalid → drop it.
 const DEAD_TOKEN_REASONS = new Set(['BadDeviceToken', 'Unregistered', 'DeviceTokenNotForTopic']);
 
+const mapWithBoundedConcurrency = async (items, concurrency, mapper) => {
+  const results = new Array(items.length);
+  const limit = Math.max(1, concurrency);
+  for (let start = 0; start < items.length; start += limit) {
+    const end = Math.min(start + limit, items.length);
+    await Promise.all(
+      items.slice(start, end).map(async (item, offset) => {
+        results[start + offset] = await mapper(item, start + offset);
+      }),
+    );
+  }
+  return results;
+};
+
+const apnsCollapseId = (tag) => {
+  if (typeof tag !== 'string' || tag.length === 0) return undefined;
+  if (Buffer.byteLength(tag, 'utf8') > APNS_COLLAPSE_ID_MAX_BYTES) return undefined;
+  return tag;
+};
+
 const trimmedEnv = (name) => {
   const value = process.env[name];
   return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
@@ -44,12 +73,15 @@ export const createApnsRuntime = (deps) => {
     writeSettingsToDisk,
     // Strict settings reader gating identity regeneration (see signing-key.js).
     readSettingsStrict,
+    resolveEffectiveRelayUrl,
   } = deps;
 
   let persistLock = Promise.resolve();
   let cachedJwt = null; // { token, issuedAtMs, keyId }
   let cachedRelayKey = null; // { privateKey, publicJwk }
   let warnedUnconfigured = false;
+  let registrationSuccessCache = new Map();
+  let registrationCacheRegisterUrl = null;
 
   // ---------------------------------------------------------------------------
   // Per-server relay signing identity (ECDSA P-256). Auto-generated + persisted in settings
@@ -76,9 +108,31 @@ export const createApnsRuntime = (deps) => {
     y: publicJwk.y,
   });
 
-  const registerTokenWithRelay = async (token, platform = 'ios') => {
-    const relay = resolveRelayConfig();
-    if (!relay) return; // direct mode — no relay binding needed
+  const registrationCacheKey = (registerUrl, token, platform) =>
+    `${registerUrl}\0${token}\0${platform}`;
+
+  const rememberRelayRegisterUrl = (registerUrl) => {
+    if (registrationCacheRegisterUrl === registerUrl) return;
+    registrationSuccessCache = new Map();
+    registrationCacheRegisterUrl = registerUrl;
+  };
+
+  const boundRegistrationCache = (registerUrl, entries) => {
+    rememberRelayRegisterUrl(registerUrl);
+    const allowed = new Set(
+      entries.map((entry) => registrationCacheKey(registerUrl, entry.deviceToken, entry.platform)),
+    );
+    for (const key of registrationSuccessCache.keys()) {
+      if (!allowed.has(key)) registrationSuccessCache.delete(key);
+    }
+  };
+
+  const registerTokenWithRelay = async (token, platform = 'ios', relayOverride) => {
+    const relay = relayOverride ?? (await resolveRelayConfig());
+    if (!relay) return true; // direct mode — no relay binding needed
+    rememberRelayRegisterUrl(relay.registerUrl);
+    const cacheKey = registrationCacheKey(relay.registerUrl, token, platform);
+    if (registrationSuccessCache.has(cacheKey)) return true;
     try {
       const { privateKey, publicJwk } = await getOrCreateRelayKeypair();
       const ts = Date.now();
@@ -89,9 +143,15 @@ export const createApnsRuntime = (deps) => {
         headers: { 'content-type': 'application/json' },
         body: JSON.stringify({ token, platform, publicKeyJwk: relayPublicJwk(publicJwk), ts, sig }),
       });
-      if (!res.ok) console.warn(`[Push relay] register-token failed status=${res.status}`);
+      if (!res.ok) {
+        console.warn(`[Push relay] register-token failed status=${res.status}`);
+        return false;
+      }
+      registrationSuccessCache.set(cacheKey, true);
+      return true;
     } catch (error) {
       console.warn('[Push relay] register-token request failed:', error?.message ?? error);
+      return false;
     }
   };
 
@@ -149,6 +209,8 @@ export const createApnsRuntime = (deps) => {
           userAgent: typeof entry.userAgent === 'string' ? entry.userAgent : undefined,
           // 'ios' (APNs) or 'android' (FCM). Older entries without one are APNs by default.
           platform: entry.platform === 'android' ? 'android' : 'ios',
+          // App UI locale at last registration; missing → English titles (legacy tokens).
+          locale: normalizeApnsLocale(entry.locale),
         };
       })
       .filter(Boolean);
@@ -158,22 +220,47 @@ export const createApnsRuntime = (deps) => {
   // was the only registrant before Android/FCM existed.
   const normalizePlatform = (platform) => (platform === 'android' ? 'android' : 'ios');
 
-  const addOrUpdateApnsToken = async (uiSessionToken, deviceToken, userAgent, platform) => {
+  const listUniqueTokenEntries = (store) => {
+    const unique = [];
+    const seen = new Map();
+    for (const record of Object.values(store.tokensBySession || {})) {
+      for (const entry of normalizeTokens(record)) {
+        const key = `${entry.deviceToken}\0${entry.platform}`;
+        const priorIndex = seen.get(key);
+        if (priorIndex == null) {
+          seen.set(key, unique.length);
+          unique.push(entry);
+          continue;
+        }
+        // Same device may register under multiple UI sessions; keep the freshest locale.
+        const prior = unique[priorIndex];
+        const priorSeen = typeof prior.lastSeenAt === 'number' ? prior.lastSeenAt : 0;
+        const nextSeen = typeof entry.lastSeenAt === 'number' ? entry.lastSeenAt : 0;
+        if (nextSeen >= priorSeen) unique[priorIndex] = entry;
+      }
+    }
+    return unique;
+  };
+
+  const addOrUpdateApnsToken = async (uiSessionToken, deviceToken, userAgent, platform, locale) => {
     if (!uiSessionToken || typeof deviceToken !== 'string' || deviceToken.trim().length === 0) return;
     const token = deviceToken.trim();
     const tokenPlatform = normalizePlatform(platform);
+    const tokenLocale = normalizeApnsLocale(locale);
     const now = Date.now();
 
     await persistTokenUpdate((current) => {
       const tokensBySession = { ...(current.tokensBySession || {}) };
       const existing = normalizeTokens(tokensBySession[uiSessionToken]);
+      const prior = existing.find((entry) => entry.deviceToken === token);
       const filtered = existing.filter((entry) => entry.deviceToken !== token);
       filtered.unshift({
         deviceToken: token,
-        createdAt: now,
+        createdAt: typeof prior?.createdAt === 'number' ? prior.createdAt : now,
         lastSeenAt: now,
         userAgent: typeof userAgent === 'string' && userAgent.length > 0 ? userAgent : undefined,
         platform: tokenPlatform,
+        locale: tokenLocale,
       });
       tokensBySession[uiSessionToken] = filtered.slice(0, MAX_TOKENS_PER_SESSION);
       return { version: APNS_TOKENS_VERSION, tokensBySession };
@@ -316,8 +403,9 @@ export const createApnsRuntime = (deps) => {
         'apns-push-type': 'alert',
         'apns-priority': '10',
       };
-      // collapse-id dedups like web-push tags; APNs caps it at 64 bytes.
-      const collapseId = typeof config.tag === 'string' ? config.tag.slice(0, 64) : undefined;
+      // collapse-id dedups like web-push tags; APNs caps it at 64 UTF-8 bytes.
+      // Keep legal values; omit anything over the limit (do not truncate mid-codepoint).
+      const collapseId = apnsCollapseId(config.tag);
       if (collapseId) headers['apns-collapse-id'] = collapseId;
 
       let req;
@@ -363,61 +451,83 @@ export const createApnsRuntime = (deps) => {
       req.end(body);
     });
 
-  // Relay mode (default): the single APNs key lives in the central Cloudflare relay, not on
-  // each user's server — so users configure nothing. The server just POSTs device tokens +
-  // generic text; the relay signs + sends and reports which tokens to drop. Direct mode (below)
-  // is the fallback for self-hosters who set OPENCHAMBER_APNS_* and disable the relay.
-  const resolveRelayConfig = () => {
+  // Relay mode (default): the single APNs key lives in the isolated Push process on the same
+  // Relay origin (`/v1/push/*`), not on each user's server — so users configure nothing. The
+  // server just POSTs device tokens + generic text; Push signs + sends and reports which tokens
+  // to drop. Direct mode (below) is the fallback for self-hosters who set OPENCHAMBER_APNS_*
+  // and disable the relay.
+  const buildRelayConfig = (url) => ({
+    url,
+    registerUrl: url.replace(/\/send$/, '/register-token'),
+    environment:
+      (trimmedEnv('OPENCHAMBER_APNS_ENVIRONMENT') || 'sandbox').toLowerCase() === 'production'
+        ? 'production'
+        : 'sandbox',
+  });
+
+  const resolveRelayConfig = async () => {
     if (trimmedEnv('OPENCHAMBER_PUSH_RELAY_DISABLED') === 'true') return null;
-    const url = trimmedEnv('OPENCHAMBER_PUSH_RELAY_URL') || DEFAULT_RELAY_URL;
-    return {
-      url,
-      registerUrl: url.replace(/\/send$/, '/register-token'),
-      environment:
-        (trimmedEnv('OPENCHAMBER_APNS_ENVIRONMENT') || 'sandbox').toLowerCase() === 'production'
-          ? 'production'
-          : 'sandbox',
-    };
+    const explicit = trimmedEnv('OPENCHAMBER_PUSH_RELAY_URL');
+    if (explicit) return buildRelayConfig(explicit);
+
+    let relayWsUrl = DEFAULT_RELAY_URL;
+    if (typeof resolveEffectiveRelayUrl === 'function') {
+      try {
+        const resolved = await resolveEffectiveRelayUrl();
+        if (typeof resolved === 'string' && resolved.trim()) {
+          if (derivePushSendUrlFromRelayUrl(resolved)) relayWsUrl = resolved.trim();
+          else console.warn('[Push relay] resolver returned a non-WebSocket URL; falling back to default');
+        }
+      } catch {
+        console.warn('[Push relay] resolver failed; falling back to default');
+      }
+    }
+    const url = derivePushSendUrlFromRelayUrl(relayWsUrl) || derivePushSendUrlFromRelayUrl(DEFAULT_RELAY_URL);
+    if (!url) return null;
+    return buildRelayConfig(url);
   };
 
   const sendViaRelay = async (deviceTokens, payload, relay) => {
-    const tokens = deviceTokens.slice(0, 100);
+    if (!Array.isArray(deviceTokens) || deviceTokens.length === 0) return;
     const title = typeof payload?.title === 'string' && payload.title.length > 0 ? payload.title : 'OpenChamber';
     const { privateKey, publicJwk } = await getOrCreateRelayKeypair();
-    const ts = Date.now();
-    // Sign over the same canonical form the relay verifies: ts.sortedTokens.title.
-    const sig = signRelayMessage(privateKey, `${ts}.${[...tokens].sort().join(',')}.${title}`);
-    const requestBody = JSON.stringify({
-      tokens,
-      title,
-      body: typeof payload?.body === 'string' ? payload.body : '',
-      badge: Number.isFinite(payload?.badge) && payload.badge >= 0 ? Math.trunc(payload.badge) : undefined,
-      collapseId: typeof payload?.tag === 'string' ? payload.tag.slice(0, 64) : undefined,
-      env: relay.environment,
-      data: payload?.data && typeof payload.data === 'object' ? payload.data : undefined,
-      publicKeyJwk: relayPublicJwk(publicJwk),
-      ts,
-      sig,
-    });
-    try {
-      const res = await fetch(relay.url, {
-        method: 'POST',
-        headers: { 'content-type': 'application/json' },
-        body: requestBody,
+    for (let start = 0; start < deviceTokens.length; start += MAX_RELAY_SEND_TOKENS) {
+      const tokens = deviceTokens.slice(start, start + MAX_RELAY_SEND_TOKENS);
+      const ts = Date.now();
+      // Sign over the same canonical form the relay verifies: ts.sortedTokens.title.
+      const sig = signRelayMessage(privateKey, `${ts}.${[...tokens].sort().join(',')}.${title}`);
+      const requestBody = JSON.stringify({
+        tokens,
+        title,
+        body: typeof payload?.body === 'string' ? payload.body : '',
+        badge: Number.isFinite(payload?.badge) && payload.badge >= 0 ? Math.trunc(payload.badge) : undefined,
+        collapseId: apnsCollapseId(payload?.tag),
+        env: relay.environment,
+        data: payload?.data && typeof payload.data === 'object' ? payload.data : undefined,
+        publicKeyJwk: relayPublicJwk(publicJwk),
+        ts,
+        sig,
       });
-      if (!res.ok) {
-        console.warn(`[APNs relay] send failed status=${res.status}`);
-        return;
-      }
-      const data = await res.json().catch(() => null);
-      const results = Array.isArray(data?.results) ? data.results : [];
-      for (const result of results) {
-        if (result && result.drop === true && typeof result.token === 'string') {
-          await removeApnsTokenFromAllSessions(result.token);
+      try {
+        const res = await fetch(relay.url, {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: requestBody,
+        });
+        if (!res.ok) {
+          console.warn(`[APNs relay] send failed status=${res.status}`);
+          continue;
         }
+        const data = await res.json().catch(() => null);
+        const results = Array.isArray(data?.results) ? data.results : [];
+        for (const result of results) {
+          if (result && result.drop === true && typeof result.token === 'string') {
+            await removeApnsTokenFromAllSessions(result.token);
+          }
+        }
+      } catch (error) {
+        console.warn('[APNs relay] request failed:', error?.message ?? error);
       }
-    } catch (error) {
-      console.warn('[APNs relay] request failed:', error?.message ?? error);
     }
   };
 
@@ -473,26 +583,79 @@ export const createApnsRuntime = (deps) => {
   // background push for short responses. Instead we always send, and rely on iOS to NOT
   // display the alert while the app is foreground (presentationOptions: [] in
   // capacitor.config) — so there is no notification when the app is active, with no race.
-  const sendApnsToAllUiSessions = async (payload, _options = {}) => {
+  const reRegisterAllTokens = async () => {
+    const relay = await resolveRelayConfig();
+    if (!relay) {
+      return { attempted: 0, succeeded: 0, failed: 0 };
+    }
     const store = await readTokensFromDisk();
-    const deviceTokens = [];
-    const seen = new Set();
-    for (const record of Object.values(store.tokensBySession || {})) {
-      for (const entry of normalizeTokens(record)) {
-        if (!seen.has(entry.deviceToken)) {
-          seen.add(entry.deviceToken);
-          deviceTokens.push(entry.deviceToken);
-        }
+    const entries = listUniqueTokenEntries(store);
+    boundRegistrationCache(relay.registerUrl, entries);
+    const outcomes = await mapWithBoundedConcurrency(
+      entries,
+      RELAY_REGISTER_CONCURRENCY,
+      (entry) => registerTokenWithRelay(entry.deviceToken, entry.platform, relay),
+    );
+    let succeeded = 0;
+    let failed = 0;
+    for (const ok of outcomes) {
+      if (ok) succeeded += 1;
+      else failed += 1;
+    }
+    return { attempted: entries.length, succeeded, failed };
+  };
+
+  // Group ready device tokens by app locale so each batch can carry a localized title.
+  // Relay signatures cover title, so mixed-locale tokens must not share one send body.
+  const groupTokensByLocale = (entries) => {
+    const groups = new Map();
+    for (const entry of entries) {
+      const locale = entry?.locale ? normalizeApnsLocale(entry.locale) : APNS_DEFAULT_LOCALE;
+      const token = entry?.deviceToken;
+      if (typeof token !== 'string' || token.length === 0) continue;
+      let list = groups.get(locale);
+      if (!list) {
+        list = [];
+        groups.set(locale, list);
       }
+      list.push(token);
     }
-    if (deviceTokens.length === 0) return;
+    return groups;
+  };
 
-    const relay = resolveRelayConfig();
+  const sendApnsToAllUiSessions = async (payload, _options = {}) => {
+    const store = await readTokensFromDisk();
+    const uniqueEntries = listUniqueTokenEntries(store);
+    if (uniqueEntries.length === 0) return;
+
+    const relay = await resolveRelayConfig();
     if (relay) {
-      await sendViaRelay(deviceTokens, payload, relay);
+      boundRegistrationCache(relay.registerUrl, uniqueEntries);
+      const outcomes = await mapWithBoundedConcurrency(
+        uniqueEntries,
+        RELAY_REGISTER_CONCURRENCY,
+        async (entry) => {
+          const registered = await registerTokenWithRelay(entry.deviceToken, entry.platform, relay);
+          return registered ? entry : null;
+        },
+      );
+      const readyEntries = [];
+      const readySeen = new Set();
+      for (const entry of outcomes) {
+        if (!entry?.deviceToken || readySeen.has(entry.deviceToken)) continue;
+        readySeen.add(entry.deviceToken);
+        readyEntries.push(entry);
+      }
+      if (readyEntries.length === 0) return;
+      for (const [locale, tokens] of groupTokensByLocale(readyEntries)) {
+        await sendViaRelay(tokens, localizeApnsPayload(payload, locale), relay);
+      }
       return;
     }
-    await sendViaDirectApns(deviceTokens, payload);
+    const byLocale = groupTokensByLocale(uniqueEntries);
+    for (const [locale, deviceTokens] of byLocale) {
+      await sendViaDirectApns(deviceTokens, localizeApnsPayload(payload, locale));
+    }
   };
 
   return {
@@ -500,6 +663,7 @@ export const createApnsRuntime = (deps) => {
     removeApnsToken,
     removeApnsTokenFromAllSessions,
     sendApnsToAllUiSessions,
+    reRegisterAllTokens,
     resolveApnsConfig,
     // exposed for tests
     signApnsJwt,