Backups to master, replacement-VPS restore, broker proxy, multi-instance

Four features:

- Backup: lib/backup-sync.ts pushes the full settings table and firm
  credentials (the deliberate exception to "credentials never leave the
  machine") to the master's bearer-gated /api/instances/backup — every
  5 minutes when the content hash changed, within seconds of a settings
  or credential edit, and on the new backup-now command. Enabled by the
  master_backup_token setting.

- Restore: a dead VPS's replacement pulls the backup and adopts its
  uuid/name, so roster, payouts and card links carry on. Pre-boot via
  seed-settings.js --restore-from (setup-linux.sh prompts for it) or
  the Settings page's restore picker (lib/backup-restore.ts). Stop the
  old machine first; the master 409s a live-name rename.

- Proxy: the proxy_url setting routes BROKER traffic only — TopstepX
  REST + SignalR hub, Tradovate REST + websocket, Yahoo quotes — via
  lib/outbound-proxy.ts (axios agents, undici dispatcher, ws agent).
  The master link, reporter, catalog and backup push stay direct, so a
  dead proxy cannot take down the control channel. Restart to apply.

- Multi-instance: AUTOFIRMER_DB moves the SQLite file so one checkout
  runs N instances; scripts/instances.json (per-device, gitignored)
  drives start-all/update-check, and add-instance.sh / remove-instance.sh
  manage the extra PM2 processes. Absent registry = single-instance
  behavior, unchanged. Instance 1 keeps port 3000 for the clicker and
  extension.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

app/api/backup/restore/route.ts

@@ -0,0 +1,68 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { getSetting } from '@/lib/db';
+import { applyBackup, fetchBackup, fetchBackupList } from '@/lib/backup-restore';
+
+/**
+ * Restore-from-master for the settings page.
+ *
+ * The browser talks to this route and this route talks to the master with the
+ * machine's own stored master_dashboard_url + master_backup_token, so the
+ * token never reaches the browser.
+ *
+ * GET  — the available backups, for the picker.
+ * POST { id } — pull that backup and apply it, adopting its identity.
+ *               The process must be restarted afterwards; the response says so.
+ */
+
+function config(): { masterUrl: string; token: string } | NextResponse {
+    const masterUrl = getSetting('master_dashboard_url');
+    const token = getSetting('master_backup_token');
+    if (!masterUrl) return NextResponse.json({ error: 'master_dashboard_url is not set' }, { status: 400 });
+    if (!token) return NextResponse.json({ error: 'master_backup_token is not set' }, { status: 400 });
+    return { masterUrl, token };
+}
+
+export async function GET() {
+    const cfg = config();
+    if (cfg instanceof NextResponse) return cfg;
+
+    try {
+        const backups = await fetchBackupList(cfg.masterUrl, cfg.token);
+        return NextResponse.json({ backups });
+    } catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        return NextResponse.json({ error }, { status: 502 });
+    }
+}
+
+export async function POST(req: NextRequest) {
+    const cfg = config();
+    if (cfg instanceof NextResponse) return cfg;
+
+    let id = '';
+    try {
+        const body = await req.json();
+        id = typeof body?.id === 'string' ? body.id.trim() : '';
+    } catch { /* falls through to the check below */ }
+    if (!id) return NextResponse.json({ error: 'id is required' }, { status: 400 });
+
+    try {
+        const payload = await fetchBackup(cfg.masterUrl, cfg.token, id);
+        const restored = applyBackup(payload);
+        return NextResponse.json({
+            ok: true,
+            restored,
+            savedAt: payload.savedAt,
+            adopted: {
+                name: payload.settings.instance_name ?? '',
+                id: payload.settings.instance_id ?? '',
+            },
+            // Live platform clients, the master link's hello and the proxy all
+            // predate the restore — a restart is the only honest way in.
+            restartRequired: true,
+        });
+    } catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        return NextResponse.json({ error }, { status: 502 });
+    }
+}

app/api/firms/[id]/credentials/route.ts

@@ -2,12 +2,15 @@ import { NextRequest, NextResponse } from 'next/server';
 import { getCachedFirm } from '@/lib/firm-catalog';
 import { setCredentials, clearCredentials } from '@/lib/db';
 import { reconcileClients, removeClient } from '@/lib/clients';
+import { scheduleBackupPush } from '@/lib/backup-sync';
 
 type Params = { params: Promise<{ id: string }> };
 
 /** The platform login for one firm. This is the only firm data this machine
- *  owns — everything else comes from the master catalog, and these credentials
- *  never go the other way.
+ *  owns — everything else comes from the master catalog. The one path these
+ *  credentials travel is the encrypted, bearer-gated backup to the master
+ *  (lib/backup-sync.ts); they are still absent from the catalog and the
+ *  control socket.
  *
  *  Tradovate firms need username + password. TopstepX firms need the API key;
  *  username is optional for now (the loginKey call still wants it, so the
@@ -36,6 +39,7 @@ export async function PUT(req: NextRequest, { params }: Params) {
         setCredentials(id, firm.name, username, password, apiKey);
         // Picks up the new login immediately rather than at the next restart.
         reconcileClients();
+        scheduleBackupPush();
         return NextResponse.json({ ok: true });
     } catch (err) {
         console.error('[PUT /api/firms/:id/credentials]', err);
@@ -47,5 +51,6 @@ export async function DELETE(_req: NextRequest, { params }: Params) {
     const { id } = await params;
     const cleared = clearCredentials(id);
     removeClient(id);
+    scheduleBackupPush();
     return NextResponse.json({ ok: cleared });
 }

app/api/settings/route.ts

@@ -1,7 +1,8 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { getSetting, setSetting } from '@/lib/db';
+import { scheduleBackupPush } from '@/lib/backup-sync';
 
-const VALID_KEYS = ['max_concurrent_accounts', 'tick_interval_seconds', 'master_dashboard_url', 'instance_name', 'trading_hours', 'twocaptcha_api_key', 'twocaptcha_proxy'] as const;
+const VALID_KEYS = ['max_concurrent_accounts', 'tick_interval_seconds', 'master_dashboard_url', 'instance_name', 'trading_hours', 'twocaptcha_api_key', 'twocaptcha_proxy', 'master_backup_token', 'proxy_url'] as const;
 type SettingKey = typeof VALID_KEYS[number];
 
 export async function GET() {
@@ -12,6 +13,8 @@ export async function GET() {
     // Read-only on purpose (not in VALID_KEYS): the master issues this uuid,
     // and editing it by hand would detach the instance from its person.
     result.instance_id = getSetting('instance_id');
+    result.backup_last_push_at = getSetting('backup_last_push_at');
+    result.backup_last_error = getSetting('backup_last_error');
     return NextResponse.json(result);
 }
 
@@ -27,6 +30,10 @@ export async function PATCH(req: NextRequest) {
             }
         }
 
+        // The edit should reach the master's backup within seconds, not at the
+        // next poll.
+        scheduleBackupPush();
+
         return NextResponse.json({ ok: true });
     } catch (err: any) {
         return NextResponse.json({ error: err?.message ?? 'Failed to save settings' }, { status: 500 });