feat(sync): validate scopes server-side + make UI a sync consumer

Author: pyramation

packages/server/__tests__/sync.test.ts

@@ -114,6 +114,20 @@ describe('server config sync (Phase D)', () => {
     expect(div.map((x) => x.deviceId)).not.toContain('devA');
     d.ws.close();
   });
+
+  it('drops a push with an unknown scope (no revision, no broadcast)', async () => {
+    const store = openStore();
+    const before = store.getSyncState('demo').revision;
+    const e = await connect(port);
+    await wait(50);
+
+    send(e.ws, { type: 'sync_push', scope: 'garbage', config: { evil: true }, deviceId: 'devA', baseRevision: before });
+    await wait(150);
+
+    expect(e.sync.find((m) => m.type === 'sync_update')).toBeUndefined();
+    expect(store.getSyncState('demo').revision).toBe(before);
+    e.ws.close();
+  });
 });
 
 describe('server config sync — disabled + secrets gate', () => {

packages/server/src/server.ts

@@ -1,6 +1,6 @@
 import { advertise, type AdvertiseHandle } from '@wavegrid/discovery';
 import { type Layout, loadWavegridConfig, type ResolvedConfig } from '@wavegrid/layout';
-import { openStore } from '@wavegrid/settings';
+import { isValidScope, openStore } from '@wavegrid/settings';
 import * as fs from 'fs';
 import http from 'http';
 import { resolve } from 'path';
@@ -380,6 +380,8 @@ function broadcastSync(update: SyncUpdateMessage): void {
 /** Serialize + persist a client's config push, then broadcast the revision. */
 function handleSyncPush(msg: SyncPushMessage): void {
   if (!msg.scope) return;
+  // Reject anything that isn't a known scope (project / device:<id> / secrets).
+  if (!isValidScope(msg.scope)) return;
   // Replication off: the edit stays local to the laptop that made it.
   if (!syncEnabled()) return;
   // Secrets never ride the sync channel unless explicitly opted in.

packages/settings/__tests__/sync.test.ts

@@ -7,6 +7,7 @@ import {
   applyUpdate,
   deviceScope,
   divergentDevices,
+  isValidScope,
   mergeRemote,
   projectScope,
   readSyncState,
@@ -37,6 +38,47 @@ describe('config sync (settings layer)', () => {
     expect(s.entries[deviceScope('B')].config).toEqual({ shard: [0, 5] });
   });
 
+  it('validates scopes: project / device:<id> / secrets, rejects junk', () => {
+    expect(isValidScope('project')).toBe(true);
+    expect(isValidScope('device:abc123')).toBe(true);
+    expect(isValidScope('secrets')).toBe(true);
+    expect(isValidScope('secret:beyond')).toBe(true);
+    expect(isValidScope('secrets:beyond')).toBe(true);
+    // junk
+    expect(isValidScope('')).toBe(false);
+    expect(isValidScope('device:')).toBe(false);
+    expect(isValidScope('haxor')).toBe(false);
+    expect(isValidScope('__proto__')).toBe(false);
+    expect(isValidScope(42)).toBe(false);
+    expect(isValidScope(null)).toBe(false);
+  });
+
+  it('rejects a write with an invalid scope', () => {
+    const p = paths();
+    expect(() =>
+      applyUpdate(p, 'demo', { scope: 'garbage', config: { x: 1 }, deviceId: 'A' })
+    ).toThrow(/Invalid sync scope/);
+    // nothing was persisted
+    expect(readSyncState(p, 'demo').revision).toBe(0);
+  });
+
+  it('mergeRemote drops entries with invalid scopes', () => {
+    const p = paths();
+    const remote: SyncState = {
+      version: 1,
+      revision: 3,
+      entries: {
+        [projectScope()]: { scope: projectScope(), config: { ok: true }, revision: 1, updatedAt: '2026-06-01T00:00:00Z', deviceId: 'B' },
+        haxor: { scope: 'haxor', config: { evil: true }, revision: 3, updatedAt: '2026-06-01T00:00:00Z', deviceId: 'B' }
+      },
+      acks: {}
+    };
+    const { state, changed } = mergeRemote(p, 'demo', remote);
+    expect(changed).toBe(true);
+    expect(state.entries[projectScope()].config).toEqual({ ok: true });
+    expect(state.entries.haxor).toBeUndefined();
+  });
+
   it('records the author as having acked its own write', () => {
     const p = paths();
     applyUpdate(p, 'demo', { scope: projectScope(), config: {}, deviceId: 'A' });

packages/settings/src/index.ts

@@ -22,6 +22,7 @@ export {
   type ConfigUpdate,
   deviceScope,
   type DivergentDevice,
+  isValidScope,
   projectScope,
   type SyncEntry,
   type SyncScope,

packages/settings/src/sync.ts

@@ -35,6 +35,19 @@ export function deviceScope(deviceId: string): SyncScope {
   return `device:${deviceId}`;
 }
 
+/**
+ * Whether `scope` is a well-formed sync scope. The wire type is a bare string,
+ * so a peer could push anything; this is the one gate that keeps junk out of
+ * the replicated document. Accepts the project scope, a `device:<id>` scope,
+ * and the secret scopes (`secrets` / `secret:<name>` / `secrets:<name>`), which
+ * the server separately gates behind `sync.secrets`.
+ */
+export function isValidScope(scope: unknown): scope is SyncScope {
+  if (typeof scope !== 'string' || scope.length === 0) return false;
+  if (scope === 'project' || scope === 'secrets') return true;
+  return /^device:.+$/.test(scope) || /^secrets?:.+$/.test(scope);
+}
+
 /** One revisioned config entry within a project. */
 export interface SyncEntry {
   scope: SyncScope;
@@ -106,6 +119,7 @@ function write(paths: StorePaths, project: string, state: SyncState): void {
  */
 export function applyUpdate(paths: StorePaths, project: string, update: ConfigUpdate): ApplyResult {
   if (!update.scope) throw new Error('A config update requires a scope.');
+  if (!isValidScope(update.scope)) throw new Error(`Invalid sync scope: ${update.scope}`);
   const state = readSyncState(paths, project);
   const staleBase =
     typeof update.baseRevision === 'number' && update.baseRevision < state.revision;
@@ -150,6 +164,7 @@ export function mergeRemote(
   const state = readSyncState(paths, project);
   let changed = false;
   for (const [scope, incoming] of Object.entries(remote.entries ?? {})) {
+    if (!isValidScope(scope)) continue; // never let a peer inject a junk scope
     const current = state.entries[scope];
     if (!current || wins(incoming, current)) {
       state.entries[scope] = incoming;

packages/ui/src/app.tsx

@@ -441,9 +441,14 @@ function MasterSliders({
 /* ---------- Main page ---------- */
 
 export default function Home() {
-  const config = useConfig();
+  const [configRev, setConfigRev] = useState(0);
+  const config = useConfig(configRev);
   const { user, token, checked, login } = useAuth();
-  const { connected, grid, orientation, playlistState, settings, send } = useSocket(config?.simulatorUrl ?? null, token);
+  const { connected, grid, orientation, playlistState, settings, send } = useSocket(
+    config?.simulatorUrl ?? null,
+    token,
+    useCallback(() => setConfigRev((n) => n + 1), [])
+  );
   const isPhone = useIsPhone();
 
   const NUM_CANNONS = config?.numCannons ?? 49;

packages/ui/src/lib/use-config.ts

@@ -20,8 +20,11 @@ export interface GridConfig {
  * Fetch the resolved layout/config from the runtime API route.
  * A single UI build serves any installation — the layout (fixtures,
  * topology, counts) is the source of geometry.
+ *
+ * `refetchKey` re-runs the fetch when it changes — bump it when a config
+ * change is replicated over the sync channel so the browser stays current.
  */
-export function useConfig(): GridConfig | null {
+export function useConfig(refetchKey: number = 0): GridConfig | null {
   const [config, setConfig] = useState<GridConfig | null>(null);
 
   useEffect(() => {
@@ -37,7 +40,7 @@ export function useConfig(): GridConfig | null {
           gridColumns: layout.cols
         });
       });
-  }, []);
+  }, [refetchKey]);
 
   return config;
 }

packages/ui/src/lib/use-socket.ts

@@ -30,8 +30,15 @@ export interface Settings {
   animation: string | null;
 }
 
-export function useSocket(url: string | null, token: string | null) {
+export function useSocket(
+  url: string | null,
+  token: string | null,
+  onSyncConfig?: () => void
+) {
   const wsRef = useRef<WebSocket | null>(null);
+  // Keep the latest callback without re-subscribing the socket on every render.
+  const onSyncConfigRef = useRef(onSyncConfig);
+  onSyncConfigRef.current = onSyncConfig;
   const [connected, setConnected] = useState(false);
   const [grid, setGrid] = useState<CannonColor[]>([]);
   const [orientation, setOrientation] = useState<Orientation>({ rotation: 0, flipH: false, flipV: false });
@@ -72,6 +79,10 @@ export function useSocket(url: string | null, token: string | null) {
             speed: msg.speed ?? 1.0,
             animation: msg.animation ?? null
           });
+        } else if (msg.type === 'sync_update' || msg.type === 'sync_state') {
+          // A config change was replicated from another device — refetch it so
+          // the browser reflects the new layout/light-map without a reload.
+          onSyncConfigRef.current?.();
         }
       } catch {
         // ignore