@juspay/shooter 1.24.1 → 1.25.0

package/src/lib/modules/server/apn/notify-fanout.ts

@@ -0,0 +1,40 @@
+/**
+ * Pure orchestration helpers for the /api/notify multi-device fan-out (PR 5).
+ *
+ * Separated from the route so the platform-selection and result-combination
+ * logic is unit-testable; the route wires these to the registry, the APNs/FCM
+ * services, and pruning.
+ */
+
+import type { APNsFanOutResult, FCMFanOutResult, NotifyDeliverySummary } from '$lib/types';
+
+/**
+ * DEVICE_PLATFORM is a delivery FILTER, not a binary switch. Unset (or an
+ * unrecognized value) fans out to BOTH platforms — the new multi-device default.
+ */
+export function selectPlatforms(platformFilter: string | undefined): {
+  doAndroid: boolean;
+  doIos: boolean;
+} {
+  if (platformFilter === 'ios') {
+    return { doAndroid: false, doIos: true };
+  }
+  if (platformFilter === 'android') {
+    return { doAndroid: true, doIos: false };
+  }
+  return { doAndroid: true, doIos: true };
+}
+
+export function summarizeNotifyDelivery(
+  apns: APNsFanOutResult,
+  fcm: FCMFanOutResult
+): NotifyDeliverySummary {
+  const sent = apns.totalSent + fcm.successCount;
+  const failed = apns.totalFailed + fcm.failureCount;
+  const staleTokens = [...apns.staleTokens, ...fcm.staleTokens];
+  const succeededTokens = [
+    ...apns.results.filter((r) => r.success).map((r) => r.token),
+    ...fcm.results.filter((r) => r.success).map((r) => r.token),
+  ];
+  return { delivered: sent > 0, failed, sent, staleTokens, succeededTokens };
+}

package/src/lib/modules/server/fcm/fcm-classify.ts

@@ -0,0 +1,61 @@
+/**
+ * Pure FCM stale-token classification, multicast chunking, and fan-out
+ * aggregation. Kept separate from fcm-service.ts (which pulls in firebase-admin
+ * and needs credentials) so the prune decision is unit-testable in isolation.
+ *
+ * Rule (plan §8): ONLY `messaging/registration-token-not-registered` is a dead
+ * token. `messaging/invalid-argument` is explicitly NOT prunable — it usually
+ * signals a payload format bug affecting the whole batch, and pruning on it
+ * would silently wipe out every Android device.
+ */
+
+import type { FcmDeliveryOutcome, FCMFanOutResult } from '$lib/types';
+
+const PRUNABLE_FCM_CODES: ReadonlySet<string> = new Set([
+  'messaging/registration-token-not-registered',
+]);
+
+/** Split into groups of at most `size`, preserving order. */
+export function chunk<T>(items: readonly T[], size: number): T[][] {
+  if (size <= 0) {
+    // `i += size` would never advance — guard the public API against a hang.
+    throw new RangeError('chunk size must be >= 1');
+  }
+  const out: T[][] = [];
+  for (let i = 0; i < items.length; i += size) {
+    out.push(items.slice(i, i + size));
+  }
+  return out;
+}
+
+/** Decide whether one FCM error code means the token is dead ('prune') or should be kept. */
+export function classifyFcmError(code: null | string): 'keep' | 'prune' {
+  return code && PRUNABLE_FCM_CODES.has(code) ? 'prune' : 'keep';
+}
+
+/** Aggregate per-token FCM outcomes into success/failure counts and the prune-worthy stale-token list. */
+export function summarizeFcmFanOut(outcomes: readonly FcmDeliveryOutcome[]): FCMFanOutResult {
+  const results: FCMFanOutResult['results'] = [];
+  const staleTokens: string[] = [];
+  let successCount = 0;
+  let failureCount = 0;
+
+  for (const o of outcomes) {
+    if (o.success) {
+      successCount += 1;
+    } else {
+      failureCount += 1;
+      if (classifyFcmError(o.errorCode) === 'prune') {
+        staleTokens.push(o.token);
+      }
+    }
+    results.push({
+      error: o.errorCode,
+      messageId: o.messageId,
+      success: o.success,
+      token: o.token,
+    });
+  }
+
+  return { failureCount, results, staleTokens, successCount };
+}

package/src/lib/modules/server/fcm/fcm-service.ts

@@ -1,9 +1,15 @@
-import type { NotificationPayload } from '$lib/types';
+import type { FcmDeliveryOutcome, FCMFanOutResult, NotificationPayload } from '$lib/types';
 
 import admin from 'firebase-admin';
 
+import { maskToken } from '../push/device-format.js';
+import { chunk, summarizeFcmFanOut } from './fcm-classify.js';
+
 let app: admin.app.App | null = null;
 
+// FCM multicast accepts up to 500 tokens; 100 keeps each HTTP/2 batch small.
+const FCM_MULTICAST_CHUNK = 100;
+
 export function isFCMConfigured(): boolean {
   return !!(
     process.env.FCM_PROJECT_ID &&
@@ -12,40 +18,17 @@ export function isFCMConfigured(): boolean {
   );
 }
 
+/**
+ * Send one data push to a single device. Thin backward-compat wrapper retained
+ * for existing callers; multi-device fan-out goes through sendFCMNotificationMulti.
+ */
 export async function sendFCMNotification(
   deviceToken: string,
   payload: NotificationPayload
 ): Promise<{ error?: string; messageId?: string; success: boolean }> {
   try {
     const fcmApp = getApp();
-
-    // Use DATA-ONLY messages (not notification messages)
-    // This is critical: notification messages are auto-displayed by Android
-    // and cannot have custom action buttons. Data messages always reach
-    // onMessageReceived() giving the app full control.
-    const message: admin.messaging.Message = {
-      android: {
-        priority: 'high', // Ensures delivery even in Doze mode
-        ttl: 300000, // 5 minutes TTL (matches pending request expiry)
-      },
-      data: {
-        body: payload.body || payload.message || '',
-        category:
-          payload.category ??
-          (typeof payload.data?.category === 'string' ? payload.data.category : ''),
-        project: typeof payload.data?.project === 'string' ? payload.data.project : '',
-        requestId: typeof payload.data?.requestId === 'string' ? payload.data.requestId : '',
-        source: typeof payload.data?.source === 'string' ? payload.data.source : '',
-        subtitle: payload.subtitle ?? '',
-        timestamp: new Date().toISOString(),
-        title: payload.title,
-        toolInput: payload.data?.toolInput ? JSON.stringify(payload.data.toolInput) : '',
-        toolName: typeof payload.data?.toolName === 'string' ? payload.data.toolName : '',
-        type: typeof payload.data?.type === 'string' ? payload.data.type : '',
-      },
-      token: deviceToken,
-    };
-
+    const message: admin.messaging.Message = { ...buildDataMessage(payload), token: deviceToken };
     const messageId = await admin.messaging(fcmApp).send(message);
     return { messageId, success: true };
   } catch (error) {
@@ -55,6 +38,122 @@ export async function sendFCMNotification(
   }
 }
 
+/**
+ * Fan out one data push to many devices via sendEachForMulticast (one HTTP call
+ * per 100-token chunk). Returns per-token results + the set of stale tokens
+ * (only `registration-token-not-registered`) for the caller to prune.
+ */
+export async function sendFCMNotificationMulti(
+  tokens: readonly string[],
+  payload: NotificationPayload
+): Promise<FCMFanOutResult> {
+  if (tokens.length === 0) {
+    return { failureCount: 0, results: [], staleTokens: [], successCount: 0 };
+  }
+
+  let fcmApp: admin.app.App;
+  try {
+    fcmApp = getApp();
+  } catch (error) {
+    // FCM not configured / init failure — return a structured all-failed result
+    // rather than throwing, matching sendFCMNotification's contract so callers
+    // always get an FCMFanOutResult instead of an unhandled rejection.
+    const msg = error instanceof Error ? error.message : String(error);
+    console.error('[FCM] multi-send setup failed:', fcmErrorLabel(error));
+    return {
+      failureCount: tokens.length,
+      results: tokens.map((token) => ({ error: msg, messageId: null, success: false, token })),
+      staleTokens: [],
+      successCount: 0,
+    };
+  }
+  const base = buildDataMessage(payload);
+  const outcomes: FcmDeliveryOutcome[] = [];
+
+  for (const group of chunk(tokens, FCM_MULTICAST_CHUNK)) {
+    try {
+      const batch = await admin
+        .messaging(fcmApp)
+        .sendEachForMulticast({ ...base, tokens: [...group] });
+      batch.responses.forEach((resp, i) => {
+        const errorCode = resp.error?.code ?? null;
+        if (errorCode === 'messaging/invalid-argument') {
+          // Per-token invalid-argument = this specific token string is malformed
+          // (wrong length/characters), NOT a batch payload bug (that would throw
+          // and be caught below). Surface it, but never prune — the token may be
+          // valid once its registration data is corrected.
+          // Log the structured error code + masked token (never the raw FCM
+          // message, which is free-text and could grow more verbose across SDK
+          // versions) so diagnostics stay token-safe.
+          console.error(`[FCM] invalid-argument for token ${maskToken(group[i])}: ${errorCode}`);
+        }
+        outcomes.push({
+          errorCode,
+          messageId: resp.messageId ?? null,
+          success: resp.success,
+          token: group[i],
+        });
+      });
+    } catch (error) {
+      // Whole-chunk failure (auth, network) — count as failures, never stale.
+      console.error('[FCM] multicast chunk failed:', fcmErrorLabel(error));
+      for (const token of group) {
+        outcomes.push({ errorCode: null, messageId: null, success: false, token });
+      }
+    }
+  }
+
+  return summarizeFcmFanOut(outcomes);
+}
+
+/**
+ * Build the shared DATA-ONLY message (no token). Data messages always reach
+ * onMessageReceived() so the Android app keeps full control over rendering and
+ * action buttons (notification messages are auto-displayed and can't).
+ */
+function buildDataMessage(
+  payload: NotificationPayload
+): Pick<admin.messaging.MulticastMessage, 'android' | 'data'> {
+  return {
+    android: {
+      priority: 'high', // Ensures delivery even in Doze mode
+      ttl: 300000, // 5 minutes TTL (matches pending request expiry)
+    },
+    data: {
+      body: payload.body || payload.message || '',
+      category:
+        payload.category ??
+        (typeof payload.data?.category === 'string' ? payload.data.category : ''),
+      project: typeof payload.data?.project === 'string' ? payload.data.project : '',
+      requestId: typeof payload.data?.requestId === 'string' ? payload.data.requestId : '',
+      source: typeof payload.data?.source === 'string' ? payload.data.source : '',
+      subtitle: payload.subtitle ?? '',
+      timestamp: new Date().toISOString(),
+      title: payload.title,
+      toolInput: payload.data?.toolInput ? JSON.stringify(payload.data.toolInput) : '',
+      toolName: typeof payload.data?.toolName === 'string' ? payload.data.toolName : '',
+      type: typeof payload.data?.type === 'string' ? payload.data.type : '',
+    },
+  };
+}
+
+/**
+ * Log-safe label for an FCM error: prefer the Firebase SDK's structured `.code`
+ * (e.g. 'app/invalid-credential', 'messaging/authentication-error') over its
+ * free-text `.message`, which can echo project/config details. Plain Errors
+ * (e.g. our own "FCM not configured: missing FCM_*" — env-var names only) fall
+ * back to the message.
+ */
+function fcmErrorLabel(error: unknown): string {
+  if (error && typeof error === 'object' && 'code' in error) {
+    const code = (error as { code?: unknown }).code;
+    if (typeof code === 'string' && code.length > 0) {
+      return code;
+    }
+  }
+  return error instanceof Error ? error.message : String(error);
+}
+
 function getApp(): admin.app.App {
   if (!app) {
     const projectId = process.env.FCM_PROJECT_ID;

package/src/lib/modules/server/push/device-format.ts

@@ -0,0 +1,42 @@
+/**
+ * Presentation helpers for the device registry HTTP surface.
+ *
+ * `maskToken` keeps a short prefix + suffix and hides the middle so the
+ * registered-devices list (and any log of it) never carries a full APNs/FCM
+ * push token. `toDeviceListItem` maps an internal DeviceRecord to the masked
+ * API shape returned by GET /api/device-token — deliberately dropping the raw
+ * `token` field.
+ */
+
+import type { DeviceListItem, DeviceRecord } from '$lib/types';
+
+export function maskToken(token: null | string | undefined): string {
+  if (!token) {
+    return '';
+  }
+  if (token.length < 8) {
+    // Too short to reveal prefix + suffix without the slices overlapping (a
+    // 4-char token would be fully exposed) — mask entirely. Real APNs (64) /
+    // FCM (~152) tokens never reach this branch.
+    return '••••';
+  }
+  if (token.length <= 10) {
+    return `${token.slice(0, 2)}…${token.slice(-2)}`;
+  }
+  return `${token.slice(0, 6)}…${token.slice(-4)}`;
+}
+
+export function toDeviceListItem(record: DeviceRecord): DeviceListItem {
+  return {
+    appEnv: record.appEnv,
+    deviceId: record.deviceId,
+    failureCount: record.failureCount,
+    friendlyName: record.friendlyName,
+    id: record.id,
+    isActive: record.isActive,
+    lastSeenAt: record.lastSeenAt,
+    platform: record.platform,
+    registeredAt: record.registeredAt,
+    tokenMasked: maskToken(record.token),
+  };
+}

package/src/lib/modules/server/push/device-token-store.ts

@@ -0,0 +1,354 @@
+/**
+ * Device Token Store — SQLite registry for multi-device push notifications.
+ *
+ * Replaces the flat `~/.shooter/device-tokens.json` ({ ios?, android? }) with
+ * a `device_tokens` table in the existing `~/.shooter/shooter.db`. Supports any
+ * number of devices per platform, idempotent upsert with token rotation keyed
+ * by a stable deviceId, lazy stale-token pruning, a 30-day inactive-row
+ * cleanup, and migration from the legacy JSON file + a setup-wizard seed file.
+ *
+ * Same better-sqlite3 + WAL + globalThis-singleton pattern as terminal-store.ts.
+ * Timestamps are injectable (`now`) for deterministic tests — the presence-store
+ * idiom. Migration/cleanup are explicit methods (called from server.ts at
+ * startup in a later PR), not constructor side effects, so importing the module
+ * never touches the registry.
+ *
+ * Deferred to PR 3 (added where first used, inside APNs sendToMany): a
+ * `getAppEnv(token)` accessor and `failure_count` accumulation. `pruneByTokens`
+ * here only soft-deactivates; the failure-count threshold lives with PR 3.
+ */
+
+import type { AppEnv, DevicePlatform, DeviceRecord, DeviceUpsertInput } from '$lib/types';
+
+import Database from 'better-sqlite3';
+import { randomUUID } from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+
+// `isDeviceRecord` is a runtime VALUE, imported relatively (not via the `$lib`
+// alias) so this module loads under tsx in server.ts at startup — the container
+// runs `node --import tsx server.ts`, where the SvelteKit `$lib` alias is
+// unresolvable. Type-only `$lib/types` imports above are erased, so they're fine.
+import { isDeviceRecord } from '../../../types/device.js';
+import { shooterDataDir } from '../utils/shooter-home.js';
+
+const THIRTY_DAYS_MS = 30 * 24 * 60 * 60 * 1000;
+
+// Defensive upper bounds on caller-supplied strings. Real values are far smaller
+// (APNs tokens ~64 hex, FCM ~152 chars; ids/names/bundle-ids are short), so these
+// only reject pathological input that would bloat a SQLite row — they never affect
+// a legitimate client. Enforced at the store boundary and the HTTP route.
+export const MAX_TOKEN_LENGTH = 512;
+export const MAX_DEVICE_ID_LENGTH = 256;
+export const MAX_NAME_LENGTH = 256;
+export const MAX_BUNDLE_ID_LENGTH = 256;
+
+export class DeviceTokenStore {
+  private dataDir: string;
+  private db: Database.Database;
+
+  constructor(dataDir: string = shooterDataDir()) {
+    this.dataDir = dataDir;
+    fs.mkdirSync(dataDir, { recursive: true });
+
+    this.db = new Database(path.join(dataDir, 'shooter.db'));
+    this.db.pragma('journal_mode = WAL');
+
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS device_tokens (
+        id            TEXT PRIMARY KEY,
+        token         TEXT NOT NULL,
+        platform      TEXT NOT NULL CHECK(platform IN ('ios', 'android')),
+        app_env       TEXT NOT NULL DEFAULT 'sandbox'
+                                    CHECK(app_env IN ('sandbox', 'production')),
+        device_id     TEXT,
+        friendly_name TEXT,
+        bundle_id     TEXT,
+        registered_at TEXT NOT NULL,
+        last_seen_at  TEXT NOT NULL,
+        failure_count INTEGER NOT NULL DEFAULT 0,
+        is_active     INTEGER NOT NULL DEFAULT 1,
+        UNIQUE(token),
+        UNIQUE(device_id, platform)
+      );
+      CREATE INDEX IF NOT EXISTS idx_device_tokens_active
+        ON device_tokens(platform, is_active);
+    `);
+  }
+
+  close(): void {
+    this.db.close();
+  }
+
+  /** Soft-delete a device by id (sets is_active = 0; auditable until cleanup). */
+  deleteById(id: string): number {
+    return this.db.prepare('UPDATE device_tokens SET is_active = 0 WHERE id = ?').run(id).changes;
+  }
+
+  getByToken(token: string): DeviceRecord | null {
+    const row = this.db.prepare('SELECT * FROM device_tokens WHERE token = ?').get(token) as
+      | Record<string, unknown>
+      | undefined;
+    return row ? rowToRecord(row) : null;
+  }
+
+  /** All active tokens for a platform, most-recently-seen first. */
+  listActive(platform: DevicePlatform): DeviceRecord[] {
+    const rows = this.db
+      .prepare(
+        'SELECT * FROM device_tokens WHERE platform = ? AND is_active = 1 ORDER BY last_seen_at DESC'
+      )
+      .all(platform) as Record<string, unknown>[];
+    return rows.map(rowToRecord);
+  }
+
+  /** Active tokens for a platform filtered by APNs gateway env. */
+  listActiveForEnv(platform: DevicePlatform, appEnv: AppEnv): DeviceRecord[] {
+    const rows = this.db
+      .prepare(
+        `SELECT * FROM device_tokens
+         WHERE platform = ? AND app_env = ? AND is_active = 1
+         ORDER BY last_seen_at DESC`
+      )
+      .all(platform, appEnv) as Record<string, unknown>[];
+    return rows.map(rowToRecord);
+  }
+
+  /**
+   * Import tokens from the legacy device-tokens.json and the setup-wizard
+   * device-token-seeds.json, then rename the consumed files. Idempotent: the
+   * rename prevents re-import, and INSERT OR IGNORE prevents UNIQUE(token) dups.
+   */
+  migrate(now: Date = new Date()): void {
+    this.importFile(path.join(this.dataDir, 'device-tokens.json'), '.migrated', now);
+    this.importFile(path.join(this.dataDir, 'device-token-seeds.json'), '.processed', now);
+  }
+
+  /** Soft-delete a set of dead tokens (lazy pruning after a failed delivery). */
+  pruneByTokens(tokens: readonly string[]): number {
+    if (tokens.length === 0) {
+      return 0;
+    }
+    const placeholders = tokens.map(() => '?').join(', ');
+    return this.db
+      .prepare(`UPDATE device_tokens SET is_active = 0 WHERE token IN (${placeholders})`)
+      .run(...tokens).changes;
+  }
+
+  /**
+   * Hard-delete inactive rows whose last_seen_at is older than 30 days.
+   * Active rows are NEVER deleted by age — a device that is still on but
+   * hasn't re-registered should keep receiving notifications.
+   */
+  startupCleanup(now: Date = new Date()): number {
+    const cutoff = new Date(now.getTime() - THIRTY_DAYS_MS).toISOString();
+    return this.db
+      .prepare('DELETE FROM device_tokens WHERE is_active = 0 AND last_seen_at < ?')
+      .run(cutoff).changes;
+  }
+
+  /** Bump last_seen_at for tokens that just delivered successfully. */
+  touchLastSeen(tokens: readonly string[], now: Date = new Date()): number {
+    if (tokens.length === 0) {
+      return 0;
+    }
+    const placeholders = tokens.map(() => '?').join(', ');
+    return this.db
+      .prepare(`UPDATE device_tokens SET last_seen_at = ? WHERE token IN (${placeholders})`)
+      .run(now.toISOString(), ...tokens).changes;
+  }
+
+  /**
+   * Register or refresh a device. Three cases, resolved in one transaction:
+   *  1. Known device (deviceId matches an existing row) → rotate token in place.
+   *     If the incoming token is currently held by a DIFFERENT row, APNs has
+   *     recycled it to us, so that stale row is hard-deleted first — otherwise
+   *     the rotation UPDATE would violate UNIQUE(token). (A soft-delete would
+   *     NOT free the constraint: the token value stays in the inactive row.)
+   *  2. New legacy device (no deviceId) → deactivate prior null-device rows for
+   *     the platform (can't tell them apart) then insert/refresh by token.
+   *  3. New device (deviceId not yet known) → insert; on token conflict, the
+   *     ownership WHERE guard gates the WHOLE update: an unknown device cannot
+   *     steal OR clobber the metadata of a token already owned by another active
+   *     device (the conflict resolves to a no-op, leaving that row untouched).
+   */
+  upsert(input: DeviceUpsertInput, now: Date = new Date()): DeviceRecord {
+    const ts = now.toISOString();
+    // Old apps omit appEnv → default to the server's configured APNs gateway
+    // (matches importTokenMap and the spec), NOT a hardcoded 'sandbox' — else a
+    // production server would file old-app tokens under 'sandbox' and the
+    // listActiveForEnv('ios','production') fan-out would silently skip them.
+    const appEnv: AppEnv =
+      input.appEnv ?? (process.env.APNS_PRODUCTION === 'true' ? 'production' : 'sandbox');
+    const deviceId = input.deviceId ?? null;
+    const friendlyName = input.friendlyName ?? null;
+    const bundleId = input.bundleId ?? null;
+    const { platform } = input;
+    // Normalize at the store boundary so a caller passing an un-trimmed token
+    // can't create a logically-duplicate row (whitespace) that would poison
+    // fan-out/pruning. The HTTP route already trims, but the store shouldn't
+    // trust every caller.
+    const token = input.token.trim();
+    if (token.length === 0) {
+      throw new Error('DeviceTokenStore.upsert: token must be a non-empty string');
+    }
+    // Reject pathologically large fields so a single row can't exhaust storage.
+    if (token.length > MAX_TOKEN_LENGTH) {
+      throw new Error(`DeviceTokenStore.upsert: token exceeds ${MAX_TOKEN_LENGTH} chars`);
+    }
+    if (deviceId !== null && deviceId.length > MAX_DEVICE_ID_LENGTH) {
+      throw new Error(`DeviceTokenStore.upsert: deviceId exceeds ${MAX_DEVICE_ID_LENGTH} chars`);
+    }
+    if (friendlyName !== null && friendlyName.length > MAX_NAME_LENGTH) {
+      throw new Error(`DeviceTokenStore.upsert: friendlyName exceeds ${MAX_NAME_LENGTH} chars`);
+    }
+    if (bundleId !== null && bundleId.length > MAX_BUNDLE_ID_LENGTH) {
+      throw new Error(`DeviceTokenStore.upsert: bundleId exceeds ${MAX_BUNDLE_ID_LENGTH} chars`);
+    }
+
+    this.db.transaction(() => {
+      if (deviceId !== null) {
+        const ownRow = this.db
+          .prepare('SELECT id FROM device_tokens WHERE device_id = ? AND platform = ?')
+          .get(deviceId, platform) as undefined | { id: string };
+        if (ownRow) {
+          // Retire any other row holding the (possibly recycled) incoming token
+          // before the rotation UPDATE touches UNIQUE(token). Tokens are globally
+          // unique, so at most one other row can hold it; if APNs gave it to us,
+          // its previous owner is dead.
+          this.db
+            .prepare('DELETE FROM device_tokens WHERE token = ? AND id != ?')
+            .run(token, ownRow.id);
+          this.db
+            .prepare(
+              `UPDATE device_tokens SET
+                 token         = ?,
+                 last_seen_at  = ?,
+                 app_env       = ?,
+                 failure_count = 0,
+                 is_active     = 1,
+                 friendly_name = COALESCE(?, friendly_name),
+                 bundle_id     = COALESCE(?, bundle_id)
+               WHERE id = ?`
+            )
+            .run(token, ts, appEnv, friendlyName, bundleId, ownRow.id);
+          return;
+        }
+        // No row for this device yet → fall through to the token-keyed INSERT,
+        // whose CASE guard preserves an existing token owner (identity theft).
+      } else {
+        // Legacy device: collapse indistinguishable null-device rows so an old
+        // app's token rotation doesn't leave a dead row drawing duplicate pushes.
+        this.db
+          .prepare(
+            `UPDATE device_tokens SET is_active = 0
+             WHERE platform = ? AND device_id IS NULL AND token != ? AND is_active = 1`
+          )
+          .run(platform, token);
+      }
+
+      this.db
+        .prepare(
+          `INSERT INTO device_tokens
+             (id, token, platform, app_env, device_id, friendly_name, bundle_id,
+              registered_at, last_seen_at, failure_count, is_active)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 0, 1)
+           ON CONFLICT(token) DO UPDATE SET
+             last_seen_at  = excluded.last_seen_at,
+             app_env       = excluded.app_env,
+             failure_count = 0,
+             is_active     = 1,
+             friendly_name = COALESCE(excluded.friendly_name, device_tokens.friendly_name),
+             bundle_id     = COALESCE(excluded.bundle_id, device_tokens.bundle_id),
+             device_id     = excluded.device_id
+           WHERE device_tokens.device_id IS NULL
+              OR device_tokens.device_id = excluded.device_id
+              OR device_tokens.is_active = 0`
+        )
+        .run(randomUUID(), token, platform, appEnv, deviceId, friendlyName, bundleId, ts, ts);
+    })();
+
+    const rec = this.getByToken(token);
+    if (!rec) {
+      throw new Error('DeviceTokenStore.upsert: row not found after write');
+    }
+    return rec;
+  }
+
+  private importFile(filePath: string, renameSuffix: string, now: Date): void {
+    if (!fs.existsSync(filePath)) {
+      return;
+    }
+    try {
+      const raw: unknown = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+      this.importTokenMap(raw, now);
+      fs.renameSync(filePath, filePath + renameSuffix);
+    } catch (err) {
+      // Corrupt/unreadable file: skip without crashing startup or losing data
+      // (left in place, harmlessly retried next startup).
+      console.warn(`[device-token-store] failed to import ${filePath}:`, err);
+    }
+  }
+
+  private importTokenMap(raw: unknown, now: Date): void {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+      return;
+    }
+    const obj = raw as Record<string, unknown>;
+    const ts = now.toISOString();
+    const appEnv: AppEnv = process.env.APNS_PRODUCTION === 'true' ? 'production' : 'sandbox';
+    const insert = this.db.prepare(
+      `INSERT OR IGNORE INTO device_tokens
+         (id, token, platform, app_env, device_id, friendly_name, bundle_id,
+          registered_at, last_seen_at, failure_count, is_active)
+       VALUES (?, ?, ?, ?, NULL, NULL, NULL, ?, ?, 0, 1)`
+    );
+    for (const platform of ['ios', 'android'] as const) {
+      const value = obj[platform];
+      const tokens = Array.isArray(value) ? value : typeof value === 'string' ? [value] : [];
+      for (const tok of tokens) {
+        if (typeof tok !== 'string') {
+          continue;
+        }
+        const normalized = tok.trim();
+        if (normalized.length > 0) {
+          insert.run(randomUUID(), normalized, platform, appEnv, ts, ts);
+        }
+      }
+    }
+  }
+}
+
+function rowToRecord(row: Record<string, unknown>): DeviceRecord {
+  const rec: DeviceRecord = {
+    appEnv: row.app_env as AppEnv,
+    bundleId: (row.bundle_id as string) ?? null,
+    deviceId: (row.device_id as string) ?? null,
+    failureCount: row.failure_count as number,
+    friendlyName: (row.friendly_name as string) ?? null,
+    id: row.id as string,
+    isActive: row.is_active === 1,
+    lastSeenAt: row.last_seen_at as string,
+    platform: row.platform as DevicePlatform,
+    registeredAt: row.registered_at as string,
+    token: row.token as string,
+  };
+  // The columns are CHECK/NOT NULL-constrained, but validate the assembled
+  // record so a future schema drift or an unexpected NULL surfaces as a clear
+  // error instead of a malformed DeviceRecord that type-checks yet is wrong.
+  if (!isDeviceRecord(rec)) {
+    throw new Error(`DeviceTokenStore: row failed DeviceRecord validation (id=${String(row.id)})`);
+  }
+  return rec;
+}
+
+// ── Singleton ────────────────────────────────────────────────────────
+// globalThis-keyed so a single instance is shared across module loaders
+// (same pattern as terminal-store / pty-manager). Schema-only side effect at
+// import; migrate()/startupCleanup() are invoked explicitly at server startup.
+
+const DTS_GLOBAL_KEY = '__shooter_device_token_store';
+export const deviceTokenStore: DeviceTokenStore =
+  ((globalThis as Record<string, unknown>)[DTS_GLOBAL_KEY] as DeviceTokenStore) ||
+  new DeviceTokenStore();
+(globalThis as Record<string, unknown>)[DTS_GLOBAL_KEY] = deviceTokenStore;