@camstack/server 0.1.8 → 0.2.0

package/src/main.ts

@@ -1,17 +1,17 @@
 /* eslint-disable @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-argument -- pre-existing lint debt across this 800+ line bootstrap module. The flagged sites cross typed boundaries (Fastify request typing, AddonRouteRegistry, AuthService inherited methods) where the projectService context can't trace inheritance chains. Tracked separately; do not amend in unrelated edits. */
-import { fastifyTRPCPlugin } from "@trpc/server/adapters/fastify";
-import { applyWSSHandler } from "@trpc/server/adapters/ws";
-import type { CreateWSSContextFnOptions } from "@trpc/server/adapters/ws";
-import fastifyStatic from "@fastify/static";
-import fastifyCookie from "@fastify/cookie";
-import { WebSocketServer } from "ws";
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { execSync } from "node:child_process";
-import { LoggingService } from "./core/logging/logging.service";
-import { EventBusService } from "./core/events/event-bus.service";
-import { ConfigService } from "./core/config/config.service";
-import { AuthService } from "./core/auth/auth.service";
+import { fastifyTRPCPlugin } from '@trpc/server/adapters/fastify'
+import { applyWSSHandler } from '@trpc/server/adapters/ws'
+import type { CreateWSSContextFnOptions } from '@trpc/server/adapters/ws'
+import fastifyStatic from '@fastify/static'
+import fastifyCookie from '@fastify/cookie'
+import { WebSocketServer } from 'ws'
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import { execSync } from 'node:child_process'
+import { LoggingService } from './core/logging/logging.service'
+import { EventBusService } from './core/events/event-bus.service'
+import { ConfigService } from './core/config/config.service'
+import { AuthService } from './core/auth/auth.service'
 
 // Boot-time capability declaration runs over the auto-generated
 // `ALL_CAPABILITY_DEFINITIONS` array — every `*.cap.ts` file that ships
@@ -20,95 +20,89 @@ import { AuthService } from "./core/auth/auth.service";
 // `npx tsx scripts/generate-capability-router-types.ts`. The previous
 // hand-curated list silently dropped caps (zones, zone-rules,
 // zone-analytics, audio-metrics — see git for the regression).
-import { ALL_CAPABILITY_DEFINITIONS } from "@camstack/types";
-import { StreamProbeService } from "./core/streaming/stream-probe.service";
-import { FeatureService } from "./core/feature/feature.service";
-import { AgentRegistryService } from "./core/agent/agent-registry.service";
-import { MoleculerService } from "./core/moleculer/moleculer.service";
-import { AddonRegistryService } from "./core/addon/addon-registry.service";
-import { AddonPackageService } from "./core/addon/addon-package.service";
-import { ReplEngineService } from "./core/repl/repl-engine.service";
-import { NetworkQualityService } from "./core/network/network-quality.service";
-import { StorageService } from "./core/storage/storage.service";
-import { AddonBridgeService } from "./core/addon-bridge/addon-bridge.service";
-import { AddonPagesService } from "./core/addon-pages/addon-pages.service";
-import { AddonWidgetsService } from "./core/addon-widgets/addon-widgets.service";
-import { buildAppRouter } from "./api/trpc/trpc.router";
-import { buildCoreCapService } from "./api/trpc/core-cap-bridge";
+import { ALL_CAPABILITY_DEFINITIONS } from '@camstack/types'
+import { StreamProbeService } from './core/streaming/stream-probe.service'
+import { FeatureService } from './core/feature/feature.service'
+import { AgentRegistryService } from './core/agent/agent-registry.service'
+import { MoleculerService } from './core/moleculer/moleculer.service'
+import { AddonRegistryService } from './core/addon/addon-registry.service'
+import { AddonPackageService } from './core/addon/addon-package.service'
+import { ReplEngineService } from './core/repl/repl-engine.service'
+import { NetworkQualityService } from './core/network/network-quality.service'
+import { StorageService } from './core/storage/storage.service'
+import { AddonBridgeService } from './core/addon-bridge/addon-bridge.service'
+import { AddonPagesService } from './core/addon-pages/addon-pages.service'
+import { AddonWidgetsService } from './core/addon-widgets/addon-widgets.service'
+import { buildAppRouter } from './api/trpc/trpc.router'
+import { buildCoreCapService } from './api/trpc/core-cap-bridge'
+import { createTrpcContext, createWsTrpcContext } from './api/trpc/trpc.context'
+import { registerAddonUploadRoute } from './api/addon-upload'
+import { registerAuthWhoamiRoute } from './api/auth-whoami'
 import {
-  createTrpcContext,
-  createWsTrpcContext,
-} from "./api/trpc/trpc.context";
-import { registerAddonUploadRoute } from "./api/addon-upload";
-import { registerAuthWhoamiRoute } from "./api/auth-whoami";
-import { buildSessionCookie, clearSessionCookie, SESSION_COOKIE, shouldRedirectToLogin, loginRedirectUrl } from "./auth/session-cookie.js";
-import { registerHealthRoutes } from "./api/health/health.routes";
-import { registerOauth2Routes } from "./api/oauth2/oauth2-routes.js";
-import {
-  AddonRouteRegistry,
-  DataPlaneRegistry,
-  proxyToUpstream,
-} from "@camstack/core";
-import type { FastifyRequest, FastifyReply } from "fastify";
-import { loadBootstrapConfig, setupInfra } from "./boot/boot-config";
-import { bootManual } from "./manual-boot";
-
-import { PostBootService } from "./boot/post-boot.service";
-import { runIntegrationIdBackfill } from "./boot/integration-id-backfill";
+  buildSessionCookie,
+  clearSessionCookie,
+  SESSION_COOKIE,
+  shouldRedirectToLogin,
+  loginRedirectUrl,
+  isEmbedRedirectTarget,
+} from './auth/session-cookie.js'
+import { registerHealthRoutes } from './api/health/health.routes'
+import { registerOauth2Routes } from './api/oauth2/oauth2-routes.js'
+import { AddonRouteRegistry, DataPlaneRegistry, proxyToUpstream } from '@camstack/core'
+import type { FastifyRequest, FastifyReply } from 'fastify'
+import { loadBootstrapConfig, setupInfra } from './boot/boot-config'
+import { bootManual } from './manual-boot'
+
+import { PostBootService } from './boot/post-boot.service'
+import { runIntegrationIdBackfill } from './boot/integration-id-backfill'
 
 // ---- Process-level error handlers ----
 
-process.on("uncaughtException", (err) => {
-  console.error(
-    "[uncaughtException] Unhandled exception — server will continue:",
-    err,
-  );
-});
+process.on('uncaughtException', (err) => {
+  console.error('[uncaughtException] Unhandled exception — server will continue:', err)
+})
 
-process.on("unhandledRejection", (reason) => {
-  console.error(
-    "[unhandledRejection] Unhandled promise rejection — server will continue:",
-    reason,
-  );
-});
+process.on('unhandledRejection', (reason) => {
+  console.error('[unhandledRejection] Unhandled promise rejection — server will continue:', reason)
+})
 
 // ---- Graceful shutdown ----
 
 // Kill all child processes immediately on signal, then let Fastify clean up.
 // This is critical because tsx watch (dev) force-kills the main process after a short
 // timeout — if we wait for Fastify OnModuleDestroy, children become orphans.
-let shutdownStarted = false;
+let shutdownStarted = false
 function immediateChildCleanup(signal: string) {
-  if (shutdownStarted) return;
-  shutdownStarted = true;
+  if (shutdownStarted) return
+  shutdownStarted = true
 
-  console.log(`[shutdown] Received ${signal} — killing child processes immediately…`);
+  console.log(`[shutdown] Received ${signal} — killing child processes immediately…`)
 
   // Synchronously kill all children of this process via the OS.
   // This is fast and ensures no orphans even if Fastify shutdown is slow.
   try {
-    const myPid = process.pid;
-    const isMac = process.platform === "darwin";
+    const myPid = process.pid
+    const isMac = process.platform === 'darwin'
     // pkill sends SIGTERM to all processes whose parent is our PID
     const cmd = isMac
       ? `pkill -TERM -P ${myPid} 2>/dev/null; true`
-      : `kill -- -${myPid} 2>/dev/null; true`;
-    execSync(cmd, { timeout: 3000 });
-    console.log("[shutdown] Child processes signalled");
+      : `kill -- -${myPid} 2>/dev/null; true`
+    execSync(cmd, { timeout: 3000 })
+    console.log('[shutdown] Child processes signalled')
   } catch {
     // Best effort — children may have already exited
   }
 
   // Safety: force exit after 10s if Fastify shutdown stalls
   const timer = setTimeout(() => {
-    console.error("[shutdown] Graceful shutdown timed out after 10s — forcing exit");
-    process.exit(1);
-  }, 10_000);
-  timer.unref();
+    console.error('[shutdown] Graceful shutdown timed out after 10s — forcing exit')
+    process.exit(1)
+  }, 10_000)
+  timer.unref()
 }
 
-process.on("SIGTERM", () => immediateChildCleanup("SIGTERM"));
-process.on("SIGINT", () => immediateChildCleanup("SIGINT"));
+process.on('SIGTERM', () => immediateChildCleanup('SIGTERM'))
+process.on('SIGINT', () => immediateChildCleanup('SIGINT'))
 
 // ---- Orphan cleanup ----
 
@@ -118,32 +112,32 @@ process.on("SIGINT", () => immediateChildCleanup("SIGINT"));
  * Only kills processes whose parent is PID 1 (orphaned) to avoid killing children of a live server.
  */
 function cleanupOrphanProcesses(): void {
-  const isMac = process.platform === "darwin";
-  const isLinux = process.platform === "linux";
-  if (!isMac && !isLinux) return;
+  const isMac = process.platform === 'darwin'
+  const isLinux = process.platform === 'linux'
+  if (!isMac && !isLinux) return
 
-  let killed = 0;
+  let killed = 0
 
   try {
     // Find orphaned coreml_inference.py processes (ppid=1 means orphaned)
     const cmd = isMac
       ? "ps -eo pid,ppid,command | grep -E 'coreml_inference\\.py' | grep -v grep"
-      : "ps -eo pid,ppid,cmd | grep -E 'coreml_inference\\.py' | grep -v grep";
+      : "ps -eo pid,ppid,cmd | grep -E 'coreml_inference\\.py' | grep -v grep"
 
-    const output = execSync(cmd, { encoding: "utf8", timeout: 5000 }).trim();
-    if (!output) return;
+    const output = execSync(cmd, { encoding: 'utf8', timeout: 5000 }).trim()
+    if (!output) return
 
-    for (const line of output.split("\n")) {
-      const parts = line.trim().split(/\s+/);
-      const pid = parseInt(parts[0]!, 10);
-      const ppid = parseInt(parts[1]!, 10);
+    for (const line of output.split('\n')) {
+      const parts = line.trim().split(/\s+/)
+      const pid = parseInt(parts[0]!, 10)
+      const ppid = parseInt(parts[1]!, 10)
 
       // Only kill orphans (ppid=1) — never kill children of a running server
-      if (ppid !== 1 || isNaN(pid) || pid === process.pid) continue;
+      if (ppid !== 1 || isNaN(pid) || pid === process.pid) continue
 
       try {
-        process.kill(pid, "SIGTERM");
-        killed++;
+        process.kill(pid, 'SIGTERM')
+        killed++
       } catch {
         // Process may have already exited
       }
@@ -153,7 +147,7 @@ function cleanupOrphanProcesses(): void {
   }
 
   if (killed > 0) {
-    console.log(`[cleanup] Killed ${killed} orphaned camstack process(es) from a previous run`);
+    console.log(`[cleanup] Killed ${killed} orphaned camstack process(es) from a previous run`)
   }
 }
 
@@ -161,51 +155,58 @@ function cleanupOrphanProcesses(): void {
 
 async function bootstrap() {
   // Clean up orphaned processes from previous crashes before starting
-  cleanupOrphanProcesses();
+  cleanupOrphanProcesses()
 
   // SPA fallback — set later when admin UI is resolved, used by addon route catch-all
-  let spaIndexHtml: string | null = null;
+  let spaIndexHtml: string | null = null
 
   // --- Phase 1 + 2: Load config, setup storage locations, TLS ---
   const configPath =
-    process.env.CONFIG_PATH ??
-    path.join(process.cwd(), "camstack-data", "config.yaml");
-  const bootstrapConfig = loadBootstrapConfig(configPath);
-  const infra = await setupInfra(configPath, bootstrapConfig);
+    process.env.CONFIG_PATH ?? path.join(process.cwd(), 'camstack-data', 'config.yaml')
+  const bootstrapConfig = loadBootstrapConfig(configPath)
+  const infra = await setupInfra(configPath, bootstrapConfig)
 
-  const { dataPath, tlsOptions } = infra;
-  const port = infra.bootstrapConfig.server.port;
-  const host = infra.bootstrapConfig.server.host;
+  const { dataPath, tlsOptions } = infra
+  const port = infra.bootstrapConfig.server.port
+  const host = infra.bootstrapConfig.server.host
 
   // --- Phase 3: Create app + tRPC register + listen ---
-  const fastifyOpts: Record<string, unknown> = tlsOptions
-    ? { https: tlsOptions }
-    : {};
-  const app = await bootManual({ infra, fastifyOpts });
-  app.enableShutdownHooks();
-  app.enableCors();
-
-  const fastify = app.getHttpAdapter().getInstance();
-  await fastify.register(fastifyCookie);
+  const fastifyOpts: Record<string, unknown> = tlsOptions ? { https: tlsOptions } : {}
+  const app = await bootManual({ infra, fastifyOpts })
+  app.enableShutdownHooks()
+  app.enableCors()
+
+  const fastify = app.getHttpAdapter().getInstance()
+  await fastify.register(fastifyCookie)
+
+  // Data-plane POST bodies: the addon reverse-proxy (`proxyToUpstream`) pipes
+  // `request.raw` upstream, but Fastify's default application/json parser would
+  // drain it first, so a POST body would reach the addon empty. Register a
+  // passthrough parser for application/octet-stream (used by data-plane POST
+  // clients, e.g. the app log shipper → stream-broker `clientlog`) that leaves
+  // the raw stream intact for piping. No effect on JSON API routes.
+  fastify.addContentTypeParser('application/octet-stream', (_req, _payload, done) =>
+    done(null, undefined),
+  )
 
   // Make LocationManager available to StorageService before lifecycle hooks run
-  const storageService = app.get(StorageService);
-  storageService.setLocationManager(infra.locationManager);
+  const storageService = app.get(StorageService)
+  storageService.setLocationManager(infra.locationManager)
 
   // ConfigService — SettingsStore is wired later by the settings-store capability consumer
-  const config = app.get(ConfigService);
+  const config = app.get(ConfigService)
 
   // Register addon upload route (multipart — must be registered before tRPC).
   // We pass AddonRegistryService so the handler can resolve the
   // `user-management` cap singleton at request time (the only working
   // path to validate `cst_*` scoped tokens — see addon-upload.ts).
   try {
-    const uploadAuthService = app.get(AuthService);
-    const uploadAddonBridge = app.get(AddonBridgeService);
-    const uploadMoleculer = app.get(MoleculerService);
-    const uploadAddonRegistry = app.get(AddonRegistryService);
-    const uploadAddonPackage = app.get(AddonPackageService);
-    const uploadLogger = app.get(LoggingService).createLogger("addon-upload");
+    const uploadAuthService = app.get(AuthService)
+    const uploadAddonBridge = app.get(AddonBridgeService)
+    const uploadMoleculer = app.get(MoleculerService)
+    const uploadAddonRegistry = app.get(AddonRegistryService)
+    const uploadAddonPackage = app.get(AddonPackageService)
+    const uploadLogger = app.get(LoggingService).createLogger('addon-upload')
     await registerAddonUploadRoute(
       fastify,
       uploadAddonBridge,
@@ -214,52 +215,44 @@ async function bootstrap() {
       uploadAddonRegistry,
       uploadAddonPackage,
       uploadLogger,
-    );
-    console.log(
-      "[bootstrap] Addon upload route registered at POST /api/addons/upload",
-    );
+    )
+    console.log('[bootstrap] Addon upload route registered at POST /api/addons/upload')
     // Companion endpoint: /api/auth/whoami — validates JWT or cst_*
     // scoped tokens, returns the resolved identity + scope summary.
     // Mirrors the addon-upload auth chain so the CLI can ping for
     // token-still-valid without consuming a real cap.
-    await registerAuthWhoamiRoute(
-      fastify,
-      uploadAuthService,
-      uploadAddonRegistry,
-    );
-    console.log(
-      "[bootstrap] Auth whoami route registered at GET /api/auth/whoami",
-    );
+    await registerAuthWhoamiRoute(fastify, uploadAuthService, uploadAddonRegistry)
+    console.log('[bootstrap] Auth whoami route registered at GET /api/auth/whoami')
   } catch (err) {
-    console.warn("[bootstrap] Failed to register addon upload route:", err);
+    console.warn('[bootstrap] Failed to register addon upload route:', err)
   }
 
   // Register tRPC plugin on Fastify BEFORE listen.
   // If registration fails, start in degraded mode: serve a health warning endpoint.
   // Instantiate new core services
-  const loggingService = app.get(LoggingService);
-  const addonRouteRegistry = new AddonRouteRegistry();
-  const dataPlaneRegistry = new DataPlaneRegistry();
+  const loggingService = app.get(LoggingService)
+  const addonRouteRegistry = new AddonRouteRegistry()
+  const dataPlaneRegistry = new DataPlaneRegistry()
 
   // Use Fastify-managed notification/toast wrappers (globally provided by NotificationModule)
-  const { NotificationServiceWrapper } =
-    await import("./core/notification/notification-wrapper.service");
-  const { ToastServiceWrapper } =
-    await import("./core/notification/toast-wrapper.service");
-  const notificationWrapper = app.get(NotificationServiceWrapper);
-  const toastWrapper = app.get(ToastServiceWrapper);
+  const { NotificationServiceWrapper } = await import(
+    './core/notification/notification-wrapper.service'
+  )
+  const { ToastServiceWrapper } = await import('./core/notification/toast-wrapper.service')
+  const notificationWrapper = app.get(NotificationServiceWrapper)
+  const toastWrapper = app.get(ToastServiceWrapper)
   // Expose the underlying core services for the tRPC router
-  const notificationService = notificationWrapper.service;
-  const toastService = toastWrapper.service;
+  const notificationService = notificationWrapper.service
+  const toastService = toastWrapper.service
 
   // Wire AddonRouteRegistry and NotificationService
-  const addonRegistry = app.get(AddonRegistryService);
-  addonRegistry.setAddonRouteRegistry(addonRouteRegistry);
-  addonRegistry.setDataPlaneRegistry(dataPlaneRegistry);
+  const addonRegistry = app.get(AddonRegistryService)
+  addonRegistry.setAddonRouteRegistry(addonRouteRegistry)
+  addonRegistry.setDataPlaneRegistry(dataPlaneRegistry)
 
   // ── Configure the CapabilityRegistry (created in AddonRegistryService constructor) ──
-  const capabilityRegistry = addonRegistry.getCapabilityRegistry();
-  capabilityRegistry.setConfigManager(config);
+  const capabilityRegistry = addonRegistry.getCapabilityRegistry()
+  capabilityRegistry.setConfigManager(config)
 
   // Declare every shipped capability BEFORE app.init() so addon
   // registerProvider() calls (in-process or via the Moleculer bridge
@@ -267,7 +260,7 @@ async function bootstrap() {
   // onModuleInit. The list comes from the codegen — see the import
   // comment above for the rationale.
   for (const capDef of ALL_CAPABILITY_DEFINITIONS) {
-    capabilityRegistry.declareCapability(capDef);
+    capabilityRegistry.declareCapability(capDef)
   }
 
   // Hub-internal `sso-bridge` provider — gives auth-provider addons
@@ -275,52 +268,65 @@ async function bootstrap() {
   // bridge token before redirecting to `/api/auth/sso/finish`. Without
   // this, the finish endpoint would have to trust unsigned query params
   // (anyone could craft `?isAdmin=1`). Backed by AuthService.
-  const authServiceForBridge = app.get(AuthService);
+  const authServiceForBridge = app.get(AuthService)
   capabilityRegistry.registerProvider('sso-bridge', '$hub', {
-    signBridgeToken: async ({ claims, ttlSec }: { claims: { userId: string; username: string; isAdmin: boolean; provider: string; email?: string; displayName?: string }; ttlSec?: number }) => {
-      const token = authServiceForBridge.signSsoBridgeToken(claims, ttlSec ?? 300);
-      return { token };
+    signBridgeToken: async ({
+      claims,
+      ttlSec,
+    }: {
+      claims: {
+        userId: string
+        username: string
+        isAdmin: boolean
+        provider: string
+        email?: string
+        displayName?: string
+      }
+      ttlSec?: number
+    }) => {
+      const token = authServiceForBridge.signSsoBridgeToken(claims, ttlSec ?? 300)
+      return { token }
     },
     verifyBridgeToken: async ({ token }: { token: string }) => {
-      return authServiceForBridge.verifySsoBridgeToken(token);
+      return authServiceForBridge.verifySsoBridgeToken(token)
     },
-  });
+  })
 
   // Wire registry into NotificationService for proxy-based output resolution
-  notificationService.setRegistry(capabilityRegistry);
+  notificationService.setRegistry(capabilityRegistry)
 
   // Hub metrics and sub-process info now come from Moleculer service discovery
   // and the distributed metrics-provider capability — no manual wiring needed.
 
-  let trpcRegistered = false;
-  let appRouter: ReturnType<typeof buildAppRouter> | null = null;
+  let trpcRegistered = false
+  let appRouter: ReturnType<typeof buildAppRouter> | null = null
 
   // Run app.init() FIRST so onModuleInit hooks complete (PipelineWiring, AddonBridge, etc.)
   // before we build the tRPC router which depends on their results.
-  await app.init();
-  console.log("[bootstrap] app.init() complete — all onModuleInit hooks have run");
+  await app.init()
+  console.log('[bootstrap] app.init() complete — all onModuleInit hooks have run')
 
   // Mark registry as ready — providers from app.init() are now registered
-  capabilityRegistry.ready();
+  capabilityRegistry.ready()
 
   // Register log-receiver service for agent log forwarding (after app.init
   // so Moleculer re-advertises the service list to the network)
-  const moleculer = app.get(MoleculerService);
-  moleculer.registerLogReceiver();
+  const moleculer = app.get(MoleculerService)
+  moleculer.registerLogReceiver()
 
   // ── Health routes (hub self + agent forwarding) ──────────────────
   // Registered after app.init() so the AgentRegistryService is wired and
   // the Moleculer broker is ready to forward `$agent.health` calls.
   try {
-    const hubVersion = readHubVersion();
+    const hubVersion = readHubVersion()
     registerHealthRoutes(fastify, {
       moleculer,
       agentRegistry: app.get(AgentRegistryService),
       hubVersion,
-    });
-    console.log(`[bootstrap] Health routes registered (hub v${hubVersion})`);
+    })
+    console.log(`[bootstrap] Health routes registered (hub v${hubVersion})`)
   } catch (err) {
-    console.warn("[bootstrap] Failed to register health routes:", err);
+    console.warn('[bootstrap] Failed to register health routes:', err)
   }
 
   // Seed the device-name cache the log formatter consults so logs
@@ -338,14 +344,19 @@ async function bootstrap() {
         meta: { count: devices.length, ids: devices.map((d) => d.id) },
       })
     } else {
-      loggingService.createLogger('logging').warn('device-name cache seed skipped — device-manager not available')
+      loggingService
+        .createLogger('logging')
+        .warn('device-name cache seed skipped — device-manager not available')
     }
   } catch (err) {
-    console.warn('[bootstrap] device-name cache seed skipped:', err instanceof Error ? err.message : err)
+    console.warn(
+      '[bootstrap] device-name cache seed skipped:',
+      err instanceof Error ? err.message : err,
+    )
   }
 
   try {
-    const authService = app.get(AuthService);
+    const authService = app.get(AuthService)
 
     appRouter = buildAppRouter({
       authService,
@@ -365,141 +376,155 @@ async function bootstrap() {
       toastService,
       capabilityRegistry,
       streamProbe: app.get(StreamProbeService),
-    });
+    })
 
     await fastify.register(fastifyTRPCPlugin, {
-      prefix: "/trpc",
+      prefix: '/trpc',
       trpcOptions: {
         router: appRouter,
-          createContext: ({ req }: { req: FastifyRequest }) =>
+        createContext: ({ req }: { req: FastifyRequest }) =>
           createTrpcContext(req, authService, addonRegistry),
-        onError: ({ path, error }: { path: string | undefined; error: { code: string; message: string; cause?: unknown } }) => {
-          const trpcLogger = app.get(LoggingService).createLogger("tRPC");
-          trpcLogger.warn('tRPC error', { meta: { code: error.code, path: path ?? '?', message: error.message } });
-          if (error.cause) trpcLogger.warn('tRPC error cause', { meta: { cause: error.cause instanceof Error ? error.cause.message : JSON.stringify(error.cause) } });
+        onError: ({
+          path,
+          error,
+        }: {
+          path: string | undefined
+          error: { code: string; message: string; cause?: unknown }
+        }) => {
+          const trpcLogger = app.get(LoggingService).createLogger('tRPC')
+          trpcLogger.warn('tRPC error', {
+            meta: { code: error.code, path: path ?? '?', message: error.message },
+          })
+          if (error.cause)
+            trpcLogger.warn('tRPC error cause', {
+              meta: {
+                cause:
+                  error.cause instanceof Error ? error.cause.message : JSON.stringify(error.cause),
+              },
+            })
         },
       },
-    });
-    trpcRegistered = true;
+    })
+    trpcRegistered = true
 
     // Mount the `$core-caps` Moleculer service so forked addons /
     // remote agents can reach the hub's core (non-addon) tRPC routers
     // through `ctx.api.<coreCap>`. Without it those calls hang in
     // `brokerTransportLink`'s unbounded discovery wait.
     try {
-      moleculer.registerCoreCapService(buildCoreCapService(appRouter));
-      console.log("[bootstrap] core-cap mesh bridge registered ($core-caps)");
+      moleculer.registerCoreCapService(buildCoreCapService(appRouter))
+      console.log('[bootstrap] core-cap mesh bridge registered ($core-caps)')
     } catch (err) {
-      console.warn("[bootstrap] Failed to register core-cap mesh bridge:", err);
+      console.warn('[bootstrap] Failed to register core-cap mesh bridge:', err)
     }
 
     // Register addon-pages static file endpoint
-    const addonPagesService = app.get(AddonPagesService);
-    fastify.get<{ Params: { addonId: string; "*": string } }>(
-      "/api/addon-pages/:addonId/*",
+    const addonPagesService = app.get(AddonPagesService)
+    fastify.get<{ Params: { addonId: string; '*': string } }>(
+      '/api/addon-pages/:addonId/*',
       async (request, reply) => {
-        const { addonId } = request.params;
-        const filePath = request.params["*"];
+        const { addonId } = request.params
+        const filePath = request.params['*']
         if (!filePath) {
-          return reply.status(400).send("Missing file path");
+          return reply.status(400).send('Missing file path')
         }
-        const resolved = addonPagesService.resolveBundle(addonId, filePath);
+        const resolved = addonPagesService.resolveBundle(addonId, filePath)
         if (!resolved) {
-          return reply.status(404).send("Not found");
+          return reply.status(404).send('Not found')
         }
-        const ext = path.extname(resolved).toLowerCase();
+        const ext = path.extname(resolved).toLowerCase()
         const contentType =
-          ext === ".js" || ext === ".mjs"
-            ? "application/javascript"
-            : ext === ".css"
-              ? "text/css"
-              : ext === ".json"
-                ? "application/json"
-                : ext === ".html"
-                  ? "text/html"
-                  : "application/octet-stream";
-        const stream = fs.createReadStream(resolved);
-        return reply.type(contentType).send(stream);
+          ext === '.js' || ext === '.mjs'
+            ? 'application/javascript'
+            : ext === '.css'
+              ? 'text/css'
+              : ext === '.json'
+                ? 'application/json'
+                : ext === '.html'
+                  ? 'text/html'
+                  : 'application/octet-stream'
+        const stream = fs.createReadStream(resolved)
+        return reply.type(contentType).send(stream)
       },
-    );
+    )
 
     // Register addon-widgets static file endpoint — same shape as
     // addon-pages but reads bundles from each addon's
     // `dist/widgets.mjs` (declared per-widget in `addon-widgets-source`
     // metadata). Path-traversal protection + cap-registration check
     // both live in `AddonWidgetsService.resolveBundle`.
-    const addonWidgetsService = app.get(AddonWidgetsService);
-    fastify.get<{ Params: { addonId: string; "*": string } }>(
-      "/api/addon-widgets/:addonId/*",
+    const addonWidgetsService = app.get(AddonWidgetsService)
+    fastify.get<{ Params: { addonId: string; '*': string } }>(
+      '/api/addon-widgets/:addonId/*',
       async (request, reply) => {
-        const { addonId } = request.params;
-        const filePath = request.params["*"];
+        const { addonId } = request.params
+        const filePath = request.params['*']
         if (!filePath) {
-          return reply.status(400).send("Missing file path");
+          return reply.status(400).send('Missing file path')
         }
-        const resolved = addonWidgetsService.resolveBundle(addonId, filePath);
+        const resolved = addonWidgetsService.resolveBundle(addonId, filePath)
         if (!resolved) {
-          return reply.status(404).send("Not found");
+          return reply.status(404).send('Not found')
         }
-        const ext = path.extname(resolved).toLowerCase();
+        const ext = path.extname(resolved).toLowerCase()
         const contentType =
-          ext === ".js" || ext === ".mjs"
-            ? "application/javascript"
-            : ext === ".css"
-              ? "text/css"
-              : ext === ".json"
-                ? "application/json"
-                : ext === ".html"
-                  ? "text/html"
-                  : "application/octet-stream";
-        const stream = fs.createReadStream(resolved);
-        return reply.type(contentType).send(stream);
+          ext === '.js' || ext === '.mjs'
+            ? 'application/javascript'
+            : ext === '.css'
+              ? 'text/css'
+              : ext === '.json'
+                ? 'application/json'
+                : ext === '.html'
+                  ? 'text/html'
+                  : 'application/octet-stream'
+        const stream = fs.createReadStream(resolved)
+        return reply.type(contentType).send(stream)
       },
-    );
+    )
 
     // Serve static assets (e.g. SVG icons) from an addon's package directory
-    fastify.get<{ Params: { addonId: string; "*": string } }>(
-      "/api/addon-assets/:addonId/*",
+    fastify.get<{ Params: { addonId: string; '*': string } }>(
+      '/api/addon-assets/:addonId/*',
       async (request, reply) => {
-        const { addonId } = request.params;
-        const assetPath = request.params["*"] ?? "";
+        const { addonId } = request.params
+        const assetPath = request.params['*'] ?? ''
 
-        const packageDir = addonRegistry.getAddonPackageDir(addonId);
+        const packageDir = addonRegistry.getAddonPackageDir(addonId)
         if (!packageDir) {
-          return reply.code(404).send({ error: "Addon not found" });
+          return reply.code(404).send({ error: 'Addon not found' })
         }
 
-        const resolvedPackageDir = path.resolve(packageDir);
-        const filePath = path.resolve(resolvedPackageDir, assetPath);
+        const resolvedPackageDir = path.resolve(packageDir)
+        const filePath = path.resolve(resolvedPackageDir, assetPath)
 
         // Security: prevent path traversal attacks
         if (
           !filePath.startsWith(resolvedPackageDir + path.sep) &&
           filePath !== resolvedPackageDir
         ) {
-          return reply.code(403).send({ error: "Access denied" });
+          return reply.code(403).send({ error: 'Access denied' })
         }
 
         if (!fs.existsSync(filePath)) {
-          return reply.code(404).send({ error: "Asset not found" });
+          return reply.code(404).send({ error: 'Asset not found' })
         }
 
-        const ext = path.extname(filePath).toLowerCase();
+        const ext = path.extname(filePath).toLowerCase()
         const contentTypes: Record<string, string> = {
-          ".svg": "image/svg+xml",
-          ".png": "image/png",
-          ".jpg": "image/jpeg",
-          ".jpeg": "image/jpeg",
-          ".json": "application/json",
-          ".webp": "image/webp",
-        };
-        const contentType = contentTypes[ext] ?? "application/octet-stream";
-
-        reply.header("content-type", contentType);
-        reply.header("cache-control", "public, max-age=86400");
-        return reply.send(fs.readFileSync(filePath));
+          '.svg': 'image/svg+xml',
+          '.png': 'image/png',
+          '.jpg': 'image/jpeg',
+          '.jpeg': 'image/jpeg',
+          '.json': 'application/json',
+          '.webp': 'image/webp',
+        }
+        const contentType = contentTypes[ext] ?? 'application/octet-stream'
+
+        reply.header('content-type', contentType)
+        reply.header('cache-control', 'public, max-age=86400')
+        return reply.send(fs.readFileSync(filePath))
       },
-    );
+    )
 
     // ── SSO finish endpoint ─────────────────────────────────────────
     // OIDC / SAML / external auth providers redirect here after their
@@ -520,51 +545,48 @@ async function bootstrap() {
       Querystring: {
         bridge?: string
       }
-    }>(
-      "/api/auth/sso/finish",
-      async (request, reply) => {
-        // The auth-provider addon (OIDC, SAML, …) mints an HMAC-signed
-        // bridge token via the `sso-bridge` cap and 302s to here with
-        // `?bridge=<jwt>`. We verify the signature with the same JWT
-        // secret used elsewhere — only then do we trust the claims
-        // (including the `isAdmin` flag). This closes the prior gap
-        // where any client could call `?isAdmin=1` and become admin.
-        const bridge = request.query.bridge
-        if (!bridge) {
-          return reply.status(400).send({ error: "Missing bridge token" })
-        }
-        const ssoAuth = app.get(AuthService)
-        const claims = ssoAuth.verifySsoBridgeToken(bridge)
-        if (!claims) {
-          return reply.status(401).send({ error: "Invalid or expired bridge token" })
-        }
+    }>('/api/auth/sso/finish', async (request, reply) => {
+      // The auth-provider addon (OIDC, SAML, …) mints an HMAC-signed
+      // bridge token via the `sso-bridge` cap and 302s to here with
+      // `?bridge=<jwt>`. We verify the signature with the same JWT
+      // secret used elsewhere — only then do we trust the claims
+      // (including the `isAdmin` flag). This closes the prior gap
+      // where any client could call `?isAdmin=1` and become admin.
+      const bridge = request.query.bridge
+      if (!bridge) {
+        return reply.status(400).send({ error: 'Missing bridge token' })
+      }
+      const ssoAuth = app.get(AuthService)
+      const claims = ssoAuth.verifySsoBridgeToken(bridge)
+      if (!claims) {
+        return reply.status(401).send({ error: 'Invalid or expired bridge token' })
+      }
 
-        try {
-          const token = ssoAuth.signToken({
-            userId: claims.userId,
-            username: claims.username,
-            isAdmin: claims.isAdmin,
-            allowedProviders: '*',
-            allowedDevices: {},
-          })
-          // Redirect to the admin UI with the token in the URL fragment.
-          // Fragments don't hit the server log + don't get sent on
-          // subsequent requests — the SPA's auth-context picks the
-          // token up on mount and stores it in localStorage.
-          reply.code(302)
-          reply.header(
-            "Location",
-            `/admin/login#token=${encodeURIComponent(token)}&provider=${encodeURIComponent(claims.provider)}`,
-          )
-          return reply.send("")
-        } catch (err) {
-          return reply.status(500).send({
-            error: "SSO finish failed",
-            message: err instanceof Error ? err.message : String(err),
-          })
-        }
-      },
-    )
+      try {
+        const token = ssoAuth.signToken({
+          userId: claims.userId,
+          username: claims.username,
+          isAdmin: claims.isAdmin,
+          allowedProviders: '*',
+          allowedDevices: {},
+        })
+        // Redirect to the admin UI with the token in the URL fragment.
+        // Fragments don't hit the server log + don't get sent on
+        // subsequent requests — the SPA's auth-context picks the
+        // token up on mount and stores it in localStorage.
+        reply.code(302)
+        reply.header(
+          'Location',
+          `/admin/login#token=${encodeURIComponent(token)}&provider=${encodeURIComponent(claims.provider)}`,
+        )
+        return reply.send('')
+      } catch (err) {
+        return reply.status(500).send({
+          error: 'SSO finish failed',
+          message: err instanceof Error ? err.message : String(err),
+        })
+      }
+    })
 
     // ── Backup archive download (Phase 4 / Task 24) ────────────────
     // Streams an archive at `<locationId>/<archiveId>` through the
@@ -573,97 +595,103 @@ async function bootstrap() {
     // fetch and trigger a save dialog (no cookie auth on this server,
     // so we can't rely on `window.location.assign`).
     fastify.get<{ Params: { locationId: string; archiveId: string } }>(
-      "/api/backup/download/:locationId/:archiveId",
+      '/api/backup/download/:locationId/:archiveId',
       async (request, reply) => {
-        const authHeader = request.headers.authorization;
+        const authHeader = request.headers.authorization
         if (!authHeader) {
-          return reply.status(401).send({ error: "Unauthorized" });
+          return reply.status(401).send({ error: 'Unauthorized' })
         }
         try {
-          const token = authHeader.replace("Bearer ", "");
-          const downloadAuth = app.get(AuthService);
-          const payload = downloadAuth.verifyToken(token);
+          const token = authHeader.replace('Bearer ', '')
+          const downloadAuth = app.get(AuthService)
+          const payload = downloadAuth.verifyToken(token)
           if (!payload.isAdmin) {
-            return reply.status(403).send({ error: "Admin required" });
+            return reply.status(403).send({ error: 'Admin required' })
           }
         } catch {
-          return reply.status(401).send({ error: "Invalid token" });
+          return reply.status(401).send({ error: 'Invalid token' })
         }
 
-        const { locationId, archiveId } = request.params;
+        const { locationId, archiveId } = request.params
         const backupSingleton = capabilityRegistry.getSingleton<{
-          listArchives: (input: { destinationId: string }) => Promise<readonly { id: string; filename: string; sizeBytes: number; label?: string }[]>
-        }>("backup");
+          listArchives: (input: {
+            destinationId: string
+          }) => Promise<
+            readonly { id: string; filename: string; sizeBytes: number; label?: string }[]
+          >
+        }>('backup')
         if (!backupSingleton?.listArchives) {
-          return reply.status(503).send({ error: "Backup orchestrator unavailable" });
+          return reply.status(503).send({ error: 'Backup orchestrator unavailable' })
         }
-        const archives = await backupSingleton.listArchives({ destinationId: locationId });
-        const archive = archives.find((a) => a.id === archiveId);
+        const archives = await backupSingleton.listArchives({ destinationId: locationId })
+        const archive = archives.find((a) => a.id === archiveId)
         if (!archive) {
-          return reply.status(404).send({ error: "Archive not found" });
+          return reply.status(404).send({ error: 'Archive not found' })
         }
 
         const storage = capabilityRegistry.getSingleton<{
-          beginDownload: (input: { location: string; relativePath: string }) => Promise<{ downloadId: string; sizeBytes: number }>
-          readChunk: (input: { downloadId: string; offset: number; length: number }) => Promise<Uint8Array>
+          beginDownload: (input: {
+            location: string
+            relativePath: string
+          }) => Promise<{ downloadId: string; sizeBytes: number }>
+          readChunk: (input: {
+            downloadId: string
+            offset: number
+            length: number
+          }) => Promise<Uint8Array>
           endDownload: (input: { downloadId: string }) => Promise<void>
-        }>("storage");
+        }>('storage')
         if (!storage?.beginDownload) {
-          return reply.status(503).send({ error: "Storage cap unavailable" });
+          return reply.status(503).send({ error: 'Storage cap unavailable' })
         }
 
-        const downloadName = `${archive.label ?? archive.id}.tar.gz`;
+        const downloadName = `${archive.label ?? archive.id}.tar.gz`
         // Sanitize: strip newlines and double-quotes which would break
         // the Content-Disposition header. Whitespace is fine.
-        const safeName = downloadName.replace(/[\r\n"]/g, "_");
-        reply.header("content-type", "application/gzip");
-        reply.header("content-length", String(archive.sizeBytes));
-        reply.header(
-          "content-disposition",
-          `attachment; filename="${safeName}"`,
-        );
+        const safeName = downloadName.replace(/[\r\n"]/g, '_')
+        reply.header('content-type', 'application/gzip')
+        reply.header('content-length', String(archive.sizeBytes))
+        reply.header('content-disposition', `attachment; filename="${safeName}"`)
 
         const { downloadId, sizeBytes } = await storage.beginDownload({
           location: locationId,
           relativePath: archive.filename,
-        });
-        const CHUNK = 8 * 1024 * 1024;
+        })
+        const CHUNK = 8 * 1024 * 1024
         try {
-          let offset = 0;
+          let offset = 0
           // Stream the chunked response. Fastify's `reply.raw` is the
           // Node.js writable; we write each chunk and `end()` once
           // we've drained the source. Per-write back-pressure is
           // handled inside the runtime — buffered writes pile up but
           // never beyond the OS socket buffer.
           while (offset < sizeBytes) {
-            const len = Math.min(CHUNK, sizeBytes - offset);
-            const chunk = await storage.readChunk({ downloadId, offset, length: len });
+            const len = Math.min(CHUNK, sizeBytes - offset)
+            const chunk = await storage.readChunk({ downloadId, offset, length: len })
             if (chunk.byteLength === 0) {
-              throw new Error(
-                `backup download: empty chunk at offset ${offset}/${sizeBytes}`,
-              );
+              throw new Error(`backup download: empty chunk at offset ${offset}/${sizeBytes}`)
             }
-            reply.raw.write(chunk);
-            offset += chunk.byteLength;
+            reply.raw.write(chunk)
+            offset += chunk.byteLength
           }
-          reply.raw.end();
+          reply.raw.end()
         } catch (err) {
-          console.error("[backup-download] stream failed:", err);
+          console.error('[backup-download] stream failed:', err)
           // Headers may already be flushed — abort the socket if so.
           if (!reply.raw.headersSent) {
-            return reply.status(500).send({ error: "Download failed" });
+            return reply.status(500).send({ error: 'Download failed' })
           }
-          reply.raw.destroy(err instanceof Error ? err : new Error(String(err)));
+          reply.raw.destroy(err instanceof Error ? err : new Error(String(err)))
         } finally {
           try {
-            await storage.endDownload({ downloadId });
+            await storage.endDownload({ downloadId })
           } catch {
             /* best-effort */
           }
         }
-        return reply;
+        return reply
       },
-    );
+    )
 
     // POST /api/auth/session — upgrade a tRPC-issued JWT to a browser cookie.
     fastify.post<{ Body: { token?: string } }>('/api/auth/session', async (request, reply) => {
@@ -671,7 +699,7 @@ async function bootstrap() {
       if (!token) return reply.status(400).send({ error: 'token required' })
       let ttlSec: number
       try {
-        const payload = authService.verifyToken(token)   // throws on invalid/expired
+        const payload = authService.verifyToken(token) // throws on invalid/expired
         const expSec = typeof payload.exp === 'number' ? payload.exp : 0
         ttlSec = Math.max(0, expSec - Math.floor(Date.now() / 1000))
       } catch {
@@ -689,116 +717,145 @@ async function bootstrap() {
       return reply.send({ ok: true })
     })
 
+    // GET /api/embed-auth?next=<embed-path> — establish the browser session
+    // cookie from a Bearer token, then 302 to the embed. A native WebView can
+    // pass `Authorization` only on the INITIAL navigation, not on the page's
+    // asset sub-requests; the data-plane `authenticated` gate reads the cookie,
+    // so we mint it here (mirroring POST /api/auth/session) and bounce to the
+    // embed — page + assets then authenticate via the cookie. `next` is
+    // restricted to the stream-broker embed prefix (no open redirect).
+    fastify.get<{ Querystring: { next?: string } }>('/api/embed-auth', async (request, reply) => {
+      const authHeader = request.headers.authorization
+      const token = authHeader?.startsWith('Bearer ')
+        ? authHeader.slice('Bearer '.length)
+        : undefined
+      if (!token) return reply.status(401).send({ error: 'Bearer token required' })
+      const next = request.query?.next ?? ''
+      if (!isEmbedRedirectTarget(next)) return reply.status(400).send({ error: 'invalid next' })
+      let ttlSec: number
+      try {
+        const payload = authService.verifyToken(token)
+        const expSec = typeof payload.exp === 'number' ? payload.exp : 0
+        ttlSec = Math.max(0, expSec - Math.floor(Date.now() / 1000))
+      } catch {
+        return reply.status(401).send({ error: 'invalid token' })
+      }
+      const c = buildSessionCookie(token, ttlSec)
+      reply.setCookie(c.name, c.value, c.options)
+      return reply.redirect(next)
+    })
+
     // Addon HTTP API route catch-all: /addon/:addonId/*
     // Only handles non-GET or routes that actually exist in the addon route registry.
     // GET requests that don't match an addon route are SPA pages — handled by the /* fallback.
     fastify.all<{
-      Params: { addonId: string; "*": string }
+      Params: { addonId: string; '*': string }
       Querystring: Record<string, string>
       Headers: Record<string, string>
-    }>("/addon/:addonId/*", async (request, reply) => {
-      const { addonId } = request.params;
-      const subPath = request.params["*"] ?? "";
-      const method = request.method;
-      const fullPath = `/addon/${addonId}/${subPath}`;
-      const query: Record<string, string> = request.query ?? {};
-      const headers: Record<string, string> = {};
+    }>('/addon/:addonId/*', async (request, reply) => {
+      const { addonId } = request.params
+      const subPath = request.params['*'] ?? ''
+      const method = request.method
+      const fullPath = `/addon/${addonId}/${subPath}`
+      const query: Record<string, string> = request.query ?? {}
+      const headers: Record<string, string> = {}
       for (const [k, v] of Object.entries(request.headers)) {
-        if (typeof v === "string") headers[k] = v;
-        else if (Array.isArray(v)) headers[k] = v.join(",");
+        if (typeof v === 'string') headers[k] = v
+        else if (Array.isArray(v)) headers[k] = v.join(',')
       }
 
       // ── HTTP data-plane: reverse-proxy to the addon's own listener ───────
       // Checked BEFORE control routes. A hit means the addon serves this prefix
       // via `ctx.dataPlane` (it streams the bytes with real req/res); the hub
       // authenticates here, then pipes. Same origin/cert as the admin-ui.
-      const dpMatch = dataPlaneRegistry.match(addonId, subPath);
+      const dpMatch = dataPlaneRegistry.match(addonId, subPath)
       if (dpMatch) {
-        const access = dpMatch.endpoint.access;
-        if (access !== "public") {
-          const authHeader = request.headers.authorization;
-          const cookieToken = request.cookies?.[SESSION_COOKIE];
+        const access = dpMatch.endpoint.access
+        if (access !== 'public') {
+          const authHeader = request.headers.authorization
+          const cookieToken = request.cookies?.[SESSION_COOKIE]
           if (!authHeader && !cookieToken) {
-            return reply.status(401).send({ error: "Unauthorized" });
+            return reply.status(401).send({ error: 'Unauthorized' })
           }
-          const token = authHeader ? authHeader.replace("Bearer ", "") : cookieToken!;
-          if (token.startsWith("cst_")) {
-            const userMgmt = capabilityRegistry?.getSingleton("user-management");
-            if (!userMgmt) return reply.status(503).send({ error: "User management not available" });
-            const scopedToken = await userMgmt.validateScopedToken({ token });
+          const token = authHeader ? authHeader.replace('Bearer ', '') : cookieToken!
+          if (token.startsWith('cst_')) {
+            const userMgmt = capabilityRegistry?.getSingleton('user-management')
+            if (!userMgmt) return reply.status(503).send({ error: 'User management not available' })
+            const scopedToken = await userMgmt.validateScopedToken({ token })
             const scopeOk = scopedToken?.scopes.some(
-              (scope: { type: string; target?: string }) => scope.type === "addon" && scope.target === addonId,
-            );
+              (scope: { type: string; target?: string }) =>
+                scope.type === 'addon' && scope.target === addonId,
+            )
             if (!scopedToken || !scopeOk) {
-              return reply.status(403).send({ error: "Token scope mismatch" });
+              return reply.status(403).send({ error: 'Token scope mismatch' })
             }
           } else {
             try {
-              const payload = authService.verifyToken(token);
-              if (access === "admin" && !payload.isAdmin) {
-                return reply.status(403).send({ error: "Admin required" });
+              const payload = authService.verifyToken(token)
+              if (access === 'admin' && !payload.isAdmin) {
+                return reply.status(403).send({ error: 'Admin required' })
               }
             } catch {
-              return reply.status(401).send({ error: "Invalid token" });
+              return reply.status(401).send({ error: 'Invalid token' })
             }
           }
         }
-        const qIdx = request.url.indexOf("?");
-        const query = qIdx >= 0 ? request.url.slice(qIdx) : "";
+        const qIdx = request.url.indexOf('?')
+        const query = qIdx >= 0 ? request.url.slice(qIdx) : ''
         // Forward the FULL sub-path INCLUDING the prefix — the addon's facility
         // multiplexes by prefix, so it strips the prefix itself. (`dpMatch.rest`
         // is only used to pick the endpoint, not to rewrite the path.)
-        const upstreamPath = `/${subPath}${query}`;
+        const upstreamPath = `/${subPath}${query}`
         // Take over the socket — `proxyToUpstream` drives the raw response.
-        reply.hijack();
+        reply.hijack()
         proxyToUpstream({
           baseUrl: dpMatch.endpoint.baseUrl,
           secret: dpMatch.endpoint.secret,
           upstreamPath,
           clientReq: request.raw,
           clientRes: reply.raw,
-        });
-        return;
+        })
+        return
       }
 
-      const match = addonRouteRegistry.matchRoute(method, fullPath);
+      const match = addonRouteRegistry.matchRoute(method, fullPath)
       if (!match) {
-        if (method === "GET" && spaIndexHtml) {
-          return reply.type("text/html").send(fs.createReadStream(spaIndexHtml));
+        if (method === 'GET' && spaIndexHtml) {
+          return reply.type('text/html').send(fs.createReadStream(spaIndexHtml))
         }
-        return reply.status(404).send({ error: "Not found" });
+        return reply.status(404).send({ error: 'Not found' })
       }
 
       // Auth check based on route.access
-      if (match.route.access !== "public") {
-        const authHeader = request.headers.authorization;
+      if (match.route.access !== 'public') {
+        const authHeader = request.headers.authorization
         // Browser navigation has no Authorization header — fall back to the
         // session cookie, and if that is missing bounce to the login page.
-        const cookieToken = request.cookies?.[SESSION_COOKIE];
+        const cookieToken = request.cookies?.[SESSION_COOKIE]
         if (!authHeader && !cookieToken) {
           if (shouldRedirectToLogin(request.method, request.headers.accept)) {
-            const qs = request.url.includes('?') ? request.url.slice(request.url.indexOf('?')) : '';
-            return reply.redirect(loginRedirectUrl(fullPath + qs));
+            const qs = request.url.includes('?') ? request.url.slice(request.url.indexOf('?')) : ''
+            return reply.redirect(loginRedirectUrl(fullPath + qs))
           }
-          return reply.status(401).send({ error: "Unauthorized" });
+          return reply.status(401).send({ error: 'Unauthorized' })
         }
-        const token = authHeader ? authHeader.replace("Bearer ", "") : cookieToken!;
-        if (token.startsWith("cst_")) {
-          const userMgmt = capabilityRegistry?.getSingleton('user-management');
-          if (!userMgmt) return reply.status(503).send({ error: "User management not available" });
-          const scopedToken = await userMgmt.validateScopedToken({ token });
+        const token = authHeader ? authHeader.replace('Bearer ', '') : cookieToken!
+        if (token.startsWith('cst_')) {
+          const userMgmt = capabilityRegistry?.getSingleton('user-management')
+          if (!userMgmt) return reply.status(503).send({ error: 'User management not available' })
+          const scopedToken = await userMgmt.validateScopedToken({ token })
           if (!scopedToken) {
-            return reply.status(401).send({ error: "Invalid token" });
+            return reply.status(401).send({ error: 'Invalid token' })
           }
           // v2 model: scoped tokens grant by cap-category/cap-name/addon.
           // For addon-route REST endpoints we match the `addon` scope
           // type only — generic route-prefix scopes were dropped with
           // the caps-only refactor.
           const scopeMatch = scopedToken.scopes.some((scope) => {
-            return scope.type === 'addon' && scope.target === addonId;
-          });
+            return scope.type === 'addon' && scope.target === addonId
+          })
           if (!scopeMatch) {
-            return reply.status(403).send({ error: "Token scope mismatch" });
+            return reply.status(403).send({ error: 'Token scope mismatch' })
           }
           // Build addon request with scoped token context
           const addonRequest = {
@@ -811,14 +868,14 @@ async function bootstrap() {
               userId: scopedToken.userId,
               scopes: scopedToken.scopes,
             },
-          };
-          const addonReply = buildAddonReply(reply);
-          return match.route.handler(addonRequest, addonReply);
+          }
+          const addonReply = buildAddonReply(reply)
+          return match.route.handler(addonRequest, addonReply)
         } else {
           try {
-            const payload = authService.verifyToken(token);
-            if (match.route.access === "admin" && !payload.isAdmin) {
-              return reply.status(403).send({ error: "Admin required" });
+            const payload = authService.verifyToken(token)
+            if (match.route.access === 'admin' && !payload.isAdmin) {
+              return reply.status(403).send({ error: 'Admin required' })
             }
             const addonRequest = {
               params: match.params,
@@ -826,15 +883,15 @@ async function bootstrap() {
               body: request.body,
               headers,
               user: {
-                id: payload.userId ?? "unknown",
-                username: payload.username ?? "unknown",
+                id: payload.userId ?? 'unknown',
+                username: payload.username ?? 'unknown',
                 isAdmin: payload.isAdmin,
               },
-            };
-            const addonReply = buildAddonReply(reply);
-            return match.route.handler(addonRequest, addonReply);
+            }
+            const addonReply = buildAddonReply(reply)
+            return match.route.handler(addonRequest, addonReply)
           } catch {
-            return reply.status(401).send({ error: "Invalid token" });
+            return reply.status(401).send({ error: 'Invalid token' })
           }
         }
       }
@@ -845,10 +902,10 @@ async function bootstrap() {
         query,
         body: request.body,
         headers,
-      };
-      const addonReply = buildAddonReply(reply);
-      return match.route.handler(addonRequest, addonReply);
-    });
+      }
+      const addonReply = buildAddonReply(reply)
+      return match.route.handler(addonRequest, addonReply)
+    })
 
     // ── OAuth2 authorization endpoints ─────────────────────────────────────
     // Mounted under /api/oauth2/* so they sit inside the universal "/api/"
@@ -859,63 +916,75 @@ async function bootstrap() {
       getRegistry: () => capabilityRegistry,
       verifyToken: (t) => authService.verifyToken(t),
       publicHubUrl: () => process.env.CAMSTACK_PUBLIC_ORIGIN ?? `https://localhost:${port}`,
-    });
-    console.log('[bootstrap] OAuth2 routes registered at /api/oauth2/*');
+    })
+    console.log('[bootstrap] OAuth2 routes registered at /api/oauth2/*')
 
     // Attach tRPC WebSocket handler using noServer mode to avoid
     // Fastify intercepting the upgrade request with a 400 response.
-    const wss = new WebSocketServer({ noServer: true });
+    const wss = new WebSocketServer({ noServer: true })
     applyWSSHandler({
       wss,
       router: appRouter,
-      createContext: (opts: CreateWSSContextFnOptions) => createWsTrpcContext(opts, authService, addonRegistry),
-      onError: ({ path, error }: { path: string | undefined; error: { code: string; message: string; cause?: unknown } }) => {
-        const trpcLogger = app.get(LoggingService).createLogger("tRPC:ws");
-        trpcLogger.warn('tRPC error', { meta: { code: error.code, path: path ?? '?', message: error.message } });
-        if (error.cause) trpcLogger.warn('tRPC error cause', { meta: { cause: error.cause instanceof Error ? error.cause.message : JSON.stringify(error.cause) } });
+      createContext: (opts: CreateWSSContextFnOptions) =>
+        createWsTrpcContext(opts, authService, addonRegistry),
+      onError: ({
+        path,
+        error,
+      }: {
+        path: string | undefined
+        error: { code: string; message: string; cause?: unknown }
+      }) => {
+        const trpcLogger = app.get(LoggingService).createLogger('tRPC:ws')
+        trpcLogger.warn('tRPC error', {
+          meta: { code: error.code, path: path ?? '?', message: error.message },
+        })
+        if (error.cause)
+          trpcLogger.warn('tRPC error cause', {
+            meta: {
+              cause:
+                error.cause instanceof Error ? error.cause.message : JSON.stringify(error.cause),
+            },
+          })
       },
-    });
+    })
 
     // Manually handle HTTP upgrade for /trpc path.
     // Must use 'upgrade' on the raw Node HTTP server BEFORE Fastify processes it.
-    const httpServer = fastify.server;
+    const httpServer = fastify.server
     // Remove any existing upgrade listeners that might conflict
-    const existingUpgradeListeners = httpServer.listeners("upgrade");
-    httpServer.removeAllListeners("upgrade");
+    const existingUpgradeListeners = httpServer.listeners('upgrade')
+    httpServer.removeAllListeners('upgrade')
 
-    httpServer.on("upgrade", (request, socket, head) => {
-      const pathname = (request.url ?? "").split("?")[0];
-      if (pathname === "/trpc") {
+    httpServer.on('upgrade', (request, socket, head) => {
+      const pathname = (request.url ?? '').split('?')[0]
+      if (pathname === '/trpc') {
         wss.handleUpgrade(request, socket, head, (ws) => {
-          wss.emit("connection", ws, request);
-        });
+          wss.emit('connection', ws, request)
+        })
       } else {
         // Re-emit for other upgrade handlers (agent WS, etc.)
         // `EventEmitter.listeners()` returns `Function[]` with no call
         // signature — use Reflect.apply to invoke without a cast.
         for (const listener of existingUpgradeListeners) {
-          Reflect.apply(listener, httpServer, [request, socket, head]);
+          Reflect.apply(listener, httpServer, [request, socket, head])
         }
       }
-    });
+    })
   } catch (err) {
-    console.error(
-      "[bootstrap] tRPC registration failed — starting in degraded mode:",
-      err,
-    );
+    console.error('[bootstrap] tRPC registration failed — starting in degraded mode:', err)
     // Register a fallback health endpoint that signals degraded state
-    fastify.get("/trpc/health", async (_req: FastifyRequest, reply: FastifyReply) => {
+    fastify.get('/trpc/health', async (_req: FastifyRequest, reply: FastifyReply) => {
       reply.status(503).send({
-        status: "degraded",
-        message: "tRPC router failed to initialize. Check server logs.",
-      });
-    });
+        status: 'degraded',
+        message: 'tRPC router failed to initialize. Check server logs.',
+      })
+    })
   }
 
   // Wire the app router into AddonRegistry so addons get context.api
   if (appRouter) {
-    await addonRegistry.setAppRouter(appRouter);
-    console.log("[bootstrap] AddonRegistry wired with tRPC direct caller");
+    await addonRegistry.setAppRouter(appRouter)
+    console.log('[bootstrap] AddonRegistry wired with tRPC direct caller')
   }
 
   // ScopedTokenManager and admin user creation handled by local-auth addon.
@@ -929,8 +998,8 @@ async function bootstrap() {
   // no static file serving' warn that left the SPA unserved until next
   // restart.
   try {
-    const addonRegistry = app.get(AddonRegistryService);
-    const capRegistry = addonRegistry.getCapabilityRegistry();
+    const addonRegistry = app.get(AddonRegistryService)
+    const capRegistry = addonRegistry.getCapabilityRegistry()
     // The admin-ui addon runs in its own dedicated runner subprocess
     // (one addon, one process — base-layer D2), so `getSingleton`
     // returns a RemoteProxy whose method calls cross the broker — every
@@ -938,15 +1007,15 @@ async function bootstrap() {
     // `{version}` objects so plain (in-process) and remote-proxied
     // providers share the same Promise<object> signature.
     type AdminUI = {
-      getStaticDir(): Promise<{ readonly staticDir: string }>;
-      getVersion(): Promise<{ readonly version: string }>;
-    };
-    let adminUI = capRegistry?.getSingleton<AdminUI>("admin-ui");
+      getStaticDir(): Promise<{ readonly staticDir: string }>
+      getVersion(): Promise<{ readonly version: string }>
+    }
+    let adminUI = capRegistry?.getSingleton<AdminUI>('admin-ui')
     // CAMSTACK_SKIP_ADMIN_UI_WAIT — bypass the 60s poll. Used by the
     // e2e harness, which doesn't need the SPA served and spawns hubs
     // with strict boot timeouts. Production keeps the poll so cold
     // boots wait for the forked admin-ui group to register.
-    const skipAdminUIWait = process.env['CAMSTACK_SKIP_ADMIN_UI_WAIT'] === '1';
+    const skipAdminUIWait = process.env['CAMSTACK_SKIP_ADMIN_UI_WAIT'] === '1'
     if (!adminUI && capRegistry && !skipAdminUIWait) {
       // Forked-addon spawn + Moleculer registration + tRPC hydration
       // can take ~15-20s on cold boot, especially when several runners
@@ -954,19 +1023,19 @@ async function bootstrap() {
       // the admin-ui runner's boot — fastify-static didn't register and
       // every `GET /` returned 404. Bump to 60s; we only pay this
       // wait once at boot.
-      const ADMIN_UI_WAIT_MS = 60_000;
-      const POLL_MS = 200;
-      const deadline = Date.now() + ADMIN_UI_WAIT_MS;
+      const ADMIN_UI_WAIT_MS = 60_000
+      const POLL_MS = 200
+      const deadline = Date.now() + ADMIN_UI_WAIT_MS
       while (!adminUI && Date.now() < deadline) {
-        await new Promise<void>(r => setTimeout(r, POLL_MS));
-        adminUI = capRegistry.getSingleton<AdminUI>("admin-ui");
+        await new Promise<void>((r) => setTimeout(r, POLL_MS))
+        adminUI = capRegistry.getSingleton<AdminUI>('admin-ui')
       }
     }
     if (adminUI) {
-      const { staticDir } = await adminUI.getStaticDir();
-      const indexPath = path.join(staticDir, "index.html");
+      const { staticDir } = await adminUI.getStaticDir()
+      const indexPath = path.join(staticDir, 'index.html')
       if (fs.existsSync(staticDir) && fs.existsSync(indexPath)) {
-        spaIndexHtml = indexPath;
+        spaIndexHtml = indexPath
         // `serve: false` registers no route — it only decorates
         // `reply.sendFile`, so the single SPA `/*` handler below owns all
         // routing and serves each asset LIVE from the current `staticDir`.
@@ -977,27 +1046,27 @@ async function bootstrap() {
           root: staticDir,
           serve: false,
           decorateReply: true,
-        });
+        })
         // Dev diagnostic: serve webrtc-test.html from dataPath if it exists.
-        const webrtcTestPath = path.join(dataPath, "webrtc-test.html");
+        const webrtcTestPath = path.join(dataPath, 'webrtc-test.html')
         if (fs.existsSync(webrtcTestPath)) {
-          fastify.get("/webrtc-test.html", async (_request, reply) => {
-            return reply.type("text/html").send(fs.createReadStream(webrtcTestPath));
-          });
+          fastify.get('/webrtc-test.html', async (_request, reply) => {
+            return reply.type('text/html').send(fs.createReadStream(webrtcTestPath))
+          })
         }
 
         // SPA fallback + live static serving: this single catch-all owns every
         // GET. Core API prefixes fall through to their own routers via
         // `callNotFound`. Uses a wildcard route instead of setNotFoundHandler.
-        fastify.get("/*", async (request, reply) => {
-          const url = request.url;
+        fastify.get('/*', async (request, reply) => {
+          const url = request.url
           if (
-            url.startsWith("/trpc") ||
-            url.startsWith("/api/") ||
-            url.startsWith("/agent") ||
-            url.startsWith("/health")
+            url.startsWith('/trpc') ||
+            url.startsWith('/api/') ||
+            url.startsWith('/agent') ||
+            url.startsWith('/health')
           ) {
-            return reply.callNotFound();
+            return reply.callNotFound()
           }
           // A request whose last path segment has a file extension is a static
           // asset: serve it LIVE from the current dist so a redeployed
@@ -1006,85 +1075,72 @@ async function bootstrap() {
           // `index.html`: serving HTML under a `.js`/`.css` URL makes upstream
           // caches (Cloudflare, the browser) pin `text/html`, which then fails
           // the module MIME check long after the file is actually available.
-          const pathOnly = url.split("?")[0] ?? url;
+          const pathOnly = url.split('?')[0] ?? url
           if (/\.[a-zA-Z0-9]+$/.test(pathOnly)) {
-            const rel = pathOnly.replace(/^\/+/, "");
-            const abs = path.join(staticDir, rel);
-            if (
-              (abs === staticDir || abs.startsWith(staticDir + path.sep)) &&
-              fs.existsSync(abs)
-            ) {
+            const rel = pathOnly.replace(/^\/+/, '')
+            const abs = path.join(staticDir, rel)
+            if ((abs === staticDir || abs.startsWith(staticDir + path.sep)) && fs.existsSync(abs)) {
               // Cache policy that lets PWA updates actually propagate (the
               // stale-bundle bug): the service worker + registration + manifest
               // MUST be revalidated every load or a redeploy never reaches the
               // client (the SW keeps serving the old precache). Content-hashed
               // build assets (assets/index-<hash>.js) are immutable. Everything
               // else gets a short cache.
-              const base = rel.split("/").pop() ?? rel;
+              const base = rel.split('/').pop() ?? rel
               if (/^(sw\.js|registerSW\.js|workbox-.*\.js|manifest\.webmanifest)$/.test(base)) {
-                reply.header("cache-control", "no-cache, must-revalidate");
-              } else if (rel.startsWith("assets/") && /-[A-Za-z0-9_-]{8,}\./.test(base)) {
-                reply.header("cache-control", "public, max-age=31536000, immutable");
+                reply.header('cache-control', 'no-cache, must-revalidate')
+              } else if (rel.startsWith('assets/') && /-[A-Za-z0-9_-]{8,}\./.test(base)) {
+                reply.header('cache-control', 'public, max-age=31536000, immutable')
               } else {
-                reply.header("cache-control", "no-cache");
+                reply.header('cache-control', 'no-cache')
               }
-              return reply.sendFile(rel);
+              return reply.sendFile(rel)
             }
-            return reply.callNotFound();
+            return reply.callNotFound()
           }
           // index.html (the SPA shell) must never be cached — it references the
           // content-hashed bundles, so a stale copy pins the old app forever.
-          reply.header("cache-control", "no-cache, must-revalidate");
-          return reply.type("text/html").send(fs.createReadStream(spaIndexHtml!));
-        });
-        const { version } = await adminUI.getVersion();
-        console.log(
-          `[bootstrap] Admin UI served from: ${staticDir} (v${version})`,
-        );
+          reply.header('cache-control', 'no-cache, must-revalidate')
+          return reply.type('text/html').send(fs.createReadStream(spaIndexHtml!))
+        })
+        const { version } = await adminUI.getVersion()
+        console.log(`[bootstrap] Admin UI served from: ${staticDir} (v${version})`)
       } else {
         console.warn(
           `[bootstrap] Admin UI dist not found at: ${staticDir} — run 'npm run build' in addon-admin-ui`,
-        );
+        )
       }
     } else {
-      console.warn(
-        "[bootstrap] admin-ui capability not registered — no static file serving",
-      );
+      console.warn('[bootstrap] admin-ui capability not registered — no static file serving')
     }
   } catch (err) {
-    console.error(
-      "[bootstrap] Failed to set up admin UI static serving:",
-      err,
-    );
+    console.error('[bootstrap] Failed to set up admin UI static serving:', err)
   }
 
   try {
-    await app.listen(port, host);
+    await app.listen(port, host)
   } catch (listenErr: unknown) {
     if (
-      listenErr !== null
-      && typeof listenErr === 'object'
-      && 'code' in listenErr
-      && listenErr.code === "EADDRINUSE"
+      listenErr !== null &&
+      typeof listenErr === 'object' &&
+      'code' in listenErr &&
+      listenErr.code === 'EADDRINUSE'
     ) {
       console.error(
         `[bootstrap] FATAL: Port ${port} is already in use. Stop the other process or change server.port in config.yaml.`,
-      );
-      process.exit(1);
+      )
+      process.exit(1)
     }
-    throw listenErr;
+    throw listenErr
   }
 
-  const logger = app.get(LoggingService).createLogger("System");
-  const protocol = tlsOptions ? "https" : "http";
-  logger.info(
-    'CamStack server listening',
-    { meta: { protocol, host, port, trpcRegistered } },
-  );
+  const logger = app.get(LoggingService).createLogger('System')
+  const protocol = tlsOptions ? 'https' : 'http'
+  logger.info('CamStack server listening', { meta: { protocol, host, port, trpcRegistered } })
 
   // Post-boot: fork workers, register device streams, emit system.boot
-  const postBoot = app.get(PostBootService);
-  await postBoot.run({ port, host, dataPath, trpcRegistered });
+  const postBoot = app.get(PostBootService)
+  await postBoot.run({ port, host, dataPath, trpcRegistered })
 
   // One-time backfill: stamp integrationId on devices created before the
   // device-manager forwarder started stamping it (legacy camera providers),
@@ -1092,9 +1148,14 @@ async function bootstrap() {
   // untagged top-level devices of single-instance addons.
   try {
     const dmForBackfill = capabilityRegistry.getSingleton('device-manager') as {
-      listAll?: (input: { addonId?: string }) => Promise<readonly {
-        id: number; addonId: string; parentDeviceId: number | null; integrationId?: string
-      }[]>
+      listAll?: (input: { addonId?: string }) => Promise<
+        readonly {
+          id: number
+          addonId: string
+          parentDeviceId: number | null
+          integrationId?: string
+        }[]
+      >
       setIntegrationId?: (input: { deviceId: number; integrationId: string }) => Promise<void>
     } | null
     const integrationRegistry = addonRegistry.getIntegrationRegistry()
@@ -1104,12 +1165,19 @@ async function bootstrap() {
       const backfillLogger = loggingService.createLogger('integration-backfill')
       await runIntegrationIdBackfill({
         listIntegrations: async () =>
-          (await integrationRegistry.listIntegrations()).map((i) => ({ id: i.id, addonId: i.addonId })),
+          (await integrationRegistry.listIntegrations()).map((i) => ({
+            id: i.id,
+            addonId: i.addonId,
+          })),
         listDevices: async () =>
           (await listAll({})).map((d) => ({
-            id: d.id, addonId: d.addonId, parentDeviceId: d.parentDeviceId, integrationId: d.integrationId,
+            id: d.id,
+            addonId: d.addonId,
+            parentDeviceId: d.parentDeviceId,
+            integrationId: d.integrationId,
           })),
-        setIntegrationId: (deviceId, integrationId) => setIntegrationId({ deviceId, integrationId }),
+        setIntegrationId: (deviceId, integrationId) =>
+          setIntegrationId({ deviceId, integrationId }),
         logger: {
           info: (message, meta) => backfillLogger.info(message, { meta }),
           warn: (message, meta) => backfillLogger.warn(message, { meta }),
@@ -1117,7 +1185,10 @@ async function bootstrap() {
       })
     }
   } catch (err) {
-    console.warn('[bootstrap] integrationId backfill skipped:', err instanceof Error ? err.message : err)
+    console.warn(
+      '[bootstrap] integrationId backfill skipped:',
+      err instanceof Error ? err.message : err,
+    )
   }
 }
 
@@ -1126,15 +1197,15 @@ async function bootstrap() {
  */
 function readHubVersion(): string {
   try {
-    const pkgPath = path.resolve(__dirname, "..", "package.json");
+    const pkgPath = path.resolve(__dirname, '..', 'package.json')
     if (fs.existsSync(pkgPath)) {
-      const raw = JSON.parse(fs.readFileSync(pkgPath, "utf-8")) as { version?: string };
-      if (typeof raw.version === "string") return raw.version;
+      const raw = JSON.parse(fs.readFileSync(pkgPath, 'utf-8')) as { version?: string }
+      if (typeof raw.version === 'string') return raw.version
     }
   } catch {
     // best-effort
   }
-  return "unknown";
+  return 'unknown'
 }
 
 /**
@@ -1143,32 +1214,32 @@ function readHubVersion(): string {
 function buildAddonReply(reply: FastifyReply) {
   const wrapper = {
     status(code: number) {
-      reply.status(code);
-      return wrapper;
+      reply.status(code)
+      return wrapper
     },
     code(code: number) {
-      reply.code(code);
-      return wrapper;
+      reply.code(code)
+      return wrapper
     },
     send(data: unknown) {
-      reply.send(data);
+      reply.send(data)
     },
     redirect(url: string) {
-      reply.redirect(url);
+      reply.redirect(url)
     },
     header(name: string, value: string) {
-      reply.header(name, value);
-      return wrapper;
+      reply.header(name, value)
+      return wrapper
     },
     type(mime: string) {
-      reply.type(mime);
-      return wrapper;
+      reply.type(mime)
+      return wrapper
     },
-  };
-  return wrapper;
+  }
+  return wrapper
 }
 
 bootstrap().catch((err) => {
-  console.error("Bootstrap failed:", err);
-  process.exit(1);
-});
+  console.error('Bootstrap failed:', err)
+  process.exit(1)
+})