feat(notifications): FCM + APNS silent-push dispatch

createDispatcher builds the content-free payload ({txid, event, subscriptionId})
and routes by platform to injected FCM/APNS senders, pruning on a dead-token
result and swallowing transient errors. Real senders: FCM HTTP v1 via
google-auth-library, APNS background push over HTTP/2 with an ES256 provider JWT
signed by node:crypto (no jsonwebtoken dep). Senders are injected so the module
needs no credentials to build or test.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: NateIsern

server/lib/push/apns.ts

@@ -0,0 +1,124 @@
+// APNS token-based sender over HTTP/2. Signs a provider-authentication JWT
+// (ES256, from the `.p8` key) with Node's built-in crypto — no third-party JWT
+// dependency — and sends a silent `content-available` background push. Only wire
+// this when the APNS_* env is configured — see the notifications config.
+
+import http2 from 'node:http2'
+import { createPrivateKey, sign as cryptoSign, type KeyObject } from 'node:crypto'
+import { logger } from '../logger'
+import type { ApnsSender } from './types'
+
+/**
+ * How long a provider JWT is reused before re-signing. Apple requires refreshing
+ * no more than once every 20 min and at least once every 60 min; 30 min sits
+ * safely inside that window.
+ */
+const APNS_JWT_TTL_SECONDS = 30 * 60
+
+const HOST_PRODUCTION = 'https://api.push.apple.com'
+const HOST_SANDBOX = 'https://api.sandbox.push.apple.com'
+
+export interface ApnsConfig {
+  /** Contents of the AuthKey `.p8` (PKCS#8 PEM). */
+  p8: string
+  /** The key's 10-character Key ID. */
+  keyId: string
+  /** The Apple Developer Team ID. */
+  teamId: string
+  /** App bundle id, sent as `apns-topic`. */
+  bundleId: string
+  /** true → api.push.apple.com; false → the sandbox host. */
+  production: boolean
+}
+
+function base64url(input: string | Buffer): string {
+  return Buffer.from(input).toString('base64url')
+}
+
+/** Sign the APNS provider-authentication JWT (ES256) for the given issue time. */
+function signProviderJwt(privateKey: KeyObject, keyId: string, teamId: string, iat: number): string {
+  const header = base64url(JSON.stringify({ alg: 'ES256', kid: keyId }))
+  const claims = base64url(JSON.stringify({ iss: teamId, iat }))
+  const signingInput = `${header}.${claims}`
+  // ieee-p1363 yields the raw R||S signature JWS ES256 requires (not DER).
+  const signature = cryptoSign('sha256', Buffer.from(signingInput), {
+    key: privateKey,
+    dsaEncoding: 'ieee-p1363',
+  })
+  return `${signingInput}.${base64url(signature)}`
+}
+
+/**
+ * Build an {@link ApnsSender}. Maintains one persistent HTTP/2 session (lazily
+ * reconnected) and a cached provider JWT. A push resolves `{ deadToken: true }`
+ * on 410 Unregistered / 400 BadDeviceToken; any other non-200 throws (transient).
+ */
+export function createApnsSender(config: ApnsConfig): ApnsSender {
+  const host = config.production ? HOST_PRODUCTION : HOST_SANDBOX
+  const privateKey = createPrivateKey(config.p8)
+
+  let session: http2.ClientHttp2Session | null = null
+  let cachedJwt: { token: string; issuedAt: number } | null = null
+
+  function getSession(): http2.ClientHttp2Session {
+    if (session && !session.closed && !session.destroyed) {
+      return session
+    }
+    const next = http2.connect(host)
+    next.on('error', (error) => {
+      logger.error('[push] APNS HTTP/2 session error', error)
+      if (session === next) {
+        session = null
+      }
+    })
+    session = next
+    return next
+  }
+
+  function getJwt(): string {
+    const now = Math.floor(Date.now() / 1000)
+    if (cachedJwt && now - cachedJwt.issuedAt < APNS_JWT_TTL_SECONDS) {
+      return cachedJwt.token
+    }
+    const token = signProviderJwt(privateKey, config.keyId, config.teamId, now)
+    cachedJwt = { token, issuedAt: now }
+    return token
+  }
+
+  return (deviceToken, payload) =>
+    new Promise((resolve, reject) => {
+      const request = getSession().request({
+        ':method': 'POST',
+        ':path': `/3/device/${deviceToken}`,
+        authorization: `bearer ${getJwt()}`,
+        'apns-topic': config.bundleId,
+        'apns-push-type': 'background',
+        'apns-priority': '5',
+        'content-type': 'application/json',
+      })
+
+      let status = 0
+      let body = ''
+      request.setEncoding('utf8')
+      request.on('response', (headers) => {
+        status = Number(headers[':status'] ?? 0)
+      })
+      request.on('data', (chunk: string) => {
+        body += chunk
+      })
+      request.on('end', () => {
+        if (status === 200) {
+          resolve({ deadToken: false })
+          return
+        }
+        if (status === 410 || (status === 400 && body.includes('BadDeviceToken'))) {
+          logger.debug(`[push] APNS reports dead token (${status})`)
+          resolve({ deadToken: true })
+          return
+        }
+        reject(new Error(`APNS send failed: ${status} ${body}`))
+      })
+      request.on('error', reject)
+      request.end(JSON.stringify(payload))
+    })
+}

server/lib/push/fcm.ts

@@ -0,0 +1,87 @@
+// FCM HTTP v1 sender. Builds a data-only message and authenticates with an OAuth
+// access token minted from the Firebase service account (google-auth-library
+// caches/refreshes the token). Only wire this when FCM_SERVICE_ACCOUNT_JSON is
+// configured — see the notifications config.
+
+import { JWT } from 'google-auth-library'
+import { logger } from '../logger'
+import type { FcmSender } from './types'
+
+/** OAuth scope required to send FCM messages via HTTP v1. */
+const FCM_SCOPE = 'https://www.googleapis.com/auth/firebase.messaging'
+
+/** The service-account fields we read (the JSON has many more). */
+interface FcmServiceAccount {
+  client_email: string
+  private_key: string
+  project_id: string
+}
+
+function parseServiceAccount(json: string): FcmServiceAccount {
+  const parsed: unknown = JSON.parse(json)
+  if (parsed === null || typeof parsed !== 'object') {
+    throw new Error('FCM_SERVICE_ACCOUNT_JSON is not a JSON object')
+  }
+  const record = parsed as Record<string, unknown>
+  const clientEmail = record.client_email
+  const privateKey = record.private_key
+  const projectId = record.project_id
+  if (typeof clientEmail !== 'string' || typeof privateKey !== 'string' || typeof projectId !== 'string') {
+    throw new Error('FCM_SERVICE_ACCOUNT_JSON missing client_email/private_key/project_id')
+  }
+  return { client_email: clientEmail, private_key: privateKey, project_id: projectId }
+}
+
+/**
+ * Build an {@link FcmSender} from a Firebase service-account JSON string. The
+ * sender posts a data-only, high-priority message; a permanently invalid token
+ * resolves as `{ deadToken: true }` and any other non-2xx throws (transient).
+ */
+export function createFcmSender(serviceAccountJson: string): FcmSender {
+  const account = parseServiceAccount(serviceAccountJson)
+  const jwtClient = new JWT({
+    email: account.client_email,
+    key: account.private_key,
+    scopes: [FCM_SCOPE],
+  })
+  const endpoint = `https://fcm.googleapis.com/v1/projects/${account.project_id}/messages:send`
+
+  return async (deviceToken, data) => {
+    const { token } = await jwtClient.getAccessToken()
+    if (!token) {
+      throw new Error('FCM: failed to obtain an access token')
+    }
+
+    const response = await fetch(endpoint, {
+      method: 'POST',
+      headers: {
+        authorization: `Bearer ${token}`,
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify({
+        message: {
+          token: deviceToken,
+          data,
+          android: { priority: 'high' },
+        },
+      }),
+    })
+
+    if (response.ok) {
+      return { deadToken: false }
+    }
+
+    const body = await response.text()
+    // A token FCM no longer recognizes (uninstalled app / rotated token): prune.
+    if (
+      response.status === 404 ||
+      body.includes('UNREGISTERED') ||
+      (response.status === 400 && body.includes('INVALID_ARGUMENT'))
+    ) {
+      logger.debug(`[push] FCM reports dead token (${response.status})`)
+      return { deadToken: true }
+    }
+
+    throw new Error(`FCM send failed: ${response.status} ${body}`)
+  }
+}

server/lib/push/index.test.ts

@@ -0,0 +1,89 @@
+import { describe, it, expect, vi } from 'vitest'
+import { createDispatcher } from './index'
+import type { ApnsSender, FcmSender, PushSendResult } from './types'
+
+const androidTarget = { subscriptionId: 'sub-1', deviceToken: 'fcm-token', platform: 'android' as const }
+const iosTarget = { subscriptionId: 'sub-2', deviceToken: 'apns-token', platform: 'ios' as const }
+const message = { txid: 'e'.repeat(64), event: 'incoming_pending' as const }
+
+const delivered: PushSendResult = { deadToken: false }
+const dead: PushSendResult = { deadToken: true }
+
+describe('createDispatcher', () => {
+  it('sends android pushes via FCM with a content-free data payload', async () => {
+    const fcm = vi.fn<FcmSender>(async () => delivered)
+    const apns = vi.fn<ApnsSender>(async () => delivered)
+    const dispatch = createDispatcher({ fcm, apns })
+
+    await dispatch(androidTarget, message)
+
+    expect(fcm).toHaveBeenCalledTimes(1)
+    expect(apns).not.toHaveBeenCalled()
+    const [token, data] = fcm.mock.calls[0]
+    expect(token).toBe('fcm-token')
+    // The payload keys are EXACTLY the content-free wake signal — nothing else.
+    expect(Object.keys(data).sort()).toEqual(['event', 'subscriptionId', 'txid'])
+    expect(data).toEqual({ txid: 'e'.repeat(64), event: 'incoming_pending', subscriptionId: 'sub-1' })
+    // Defense-in-depth: no amount/address/balance leaked into the payload.
+    const serialized = JSON.stringify(data).toLowerCase()
+    expect(serialized).not.toMatch(/amount|address|balance|value|fair/)
+  })
+
+  it('sends ios pushes via APNS as a silent content-available push with no alert', async () => {
+    const fcm = vi.fn<FcmSender>(async () => delivered)
+    const apns = vi.fn<ApnsSender>(async () => delivered)
+    const dispatch = createDispatcher({ fcm, apns })
+
+    await dispatch(iosTarget, message)
+
+    expect(apns).toHaveBeenCalledTimes(1)
+    expect(fcm).not.toHaveBeenCalled()
+    const [token, payload] = apns.mock.calls[0]
+    expect(token).toBe('apns-token')
+    expect(payload.aps['content-available']).toBe(1)
+    // Silent push: no alert dictionary, so the OS shows nothing on its own.
+    expect('alert' in payload.aps).toBe(false)
+    expect(payload).toMatchObject({ txid: 'e'.repeat(64), event: 'incoming_pending', subscriptionId: 'sub-2' })
+    const serialized = JSON.stringify(payload).toLowerCase()
+    expect(serialized).not.toMatch(/amount|address|balance|"value"|fair/)
+  })
+
+  it('prunes the subscription when FCM reports a dead token', async () => {
+    const fcm = vi.fn(async (): Promise<PushSendResult> => dead)
+    const onDeadToken = vi.fn(async () => {})
+    const dispatch = createDispatcher({ fcm, onDeadToken })
+
+    await dispatch(androidTarget, message)
+
+    expect(onDeadToken).toHaveBeenCalledWith('sub-1')
+  })
+
+  it('prunes the subscription when APNS reports a dead token', async () => {
+    const apns = vi.fn(async (): Promise<PushSendResult> => dead)
+    const onDeadToken = vi.fn(async () => {})
+    const dispatch = createDispatcher({ apns, onDeadToken })
+
+    await dispatch(iosTarget, message)
+
+    expect(onDeadToken).toHaveBeenCalledWith('sub-2')
+  })
+
+  it('swallows a transient send error and does not prune the token', async () => {
+    const fcm = vi.fn(async (): Promise<PushSendResult> => {
+      throw new Error('503 upstream')
+    })
+    const onDeadToken = vi.fn(async () => {})
+    const dispatch = createDispatcher({ fcm, onDeadToken })
+
+    await expect(dispatch(androidTarget, message)).resolves.toBeUndefined()
+    expect(onDeadToken).not.toHaveBeenCalled()
+  })
+
+  it('is a no-op when no sender is configured for the platform', async () => {
+    const apns = vi.fn(async (): Promise<PushSendResult> => delivered)
+    const dispatch = createDispatcher({ apns }) // android target, no fcm sender
+
+    await expect(dispatch(androidTarget, message)).resolves.toBeUndefined()
+    expect(apns).not.toHaveBeenCalled()
+  })
+})

server/lib/push/index.ts

@@ -0,0 +1,76 @@
+// Push dispatch: turn a matched (target, message) into one silent provider push.
+//
+// The dispatcher owns the payload contract — the ONLY thing that transits
+// FCM/APNS is `{ txid, event, subscriptionId }` (FCM data message / APNS
+// content-available background push). It never sends an amount, address,
+// balance, or user identity; the visible notification is composed on-device.
+//
+// The concrete FCM/APNS senders are injected (built from env in server startup,
+// mocked in tests), so this module has no network/credential dependency and is a
+// pure, inert no-op when no sender is configured.
+
+import { logger } from '../logger'
+import type {
+  ApnsSender,
+  FcmSender,
+  PushData,
+  PushDispatcher,
+  PushSendResult,
+} from './types'
+
+export type { PushDispatcher } from './types'
+
+export interface DispatcherConfig {
+  /** Android transport. Absent → android pushes are a no-op. */
+  fcm?: FcmSender
+  /** iOS transport. Absent → ios pushes are a no-op. */
+  apns?: ApnsSender
+  /** Invoked with the subscriptionId when a provider reports a permanently dead token. */
+  onDeadToken?: (subscriptionId: string) => Promise<void>
+}
+
+/**
+ * Build a {@link PushDispatcher} from the configured senders. The returned
+ * function never throws: transient provider errors are logged (pushes are
+ * best-effort — the wallet reconciles true state on next open), and a dead-token
+ * result triggers `onDeadToken` so the stale subscription is pruned.
+ */
+export function createDispatcher(config: DispatcherConfig): PushDispatcher {
+  return async (target, message) => {
+    // The complete, content-free application payload.
+    const data: PushData = {
+      txid: message.txid,
+      event: message.event,
+      subscriptionId: target.subscriptionId,
+    }
+
+    let result: PushSendResult
+    try {
+      if (target.platform === 'android') {
+        if (!config.fcm) {
+          logger.debug('[push] no FCM sender configured; skipping android push')
+          return
+        }
+        result = await config.fcm(target.deviceToken, data)
+      } else {
+        if (!config.apns) {
+          logger.debug('[push] no APNS sender configured; skipping ios push')
+          return
+        }
+        result = await config.apns(target.deviceToken, {
+          aps: { 'content-available': 1 },
+          txid: data.txid,
+          event: data.event,
+          subscriptionId: data.subscriptionId,
+        })
+      }
+    } catch (error) {
+      logger.error(`[push] ${target.platform} send failed for ${target.subscriptionId}`, error)
+      return
+    }
+
+    if (result.deadToken && config.onDeadToken) {
+      await config.onDeadToken(target.subscriptionId)
+    }
+  }
+}