@camstack/server 0.2.2 → 1.0.1

package/dist/main.js

@@ -0,0 +1,1098 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/* 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. */
+const fastify_1 = require("@trpc/server/adapters/fastify");
+const ws_1 = require("@trpc/server/adapters/ws");
+const static_1 = __importDefault(require("@fastify/static"));
+const cookie_1 = __importDefault(require("@fastify/cookie"));
+const ws_2 = require("ws");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const logging_service_1 = require("./core/logging/logging.service");
+const event_bus_service_1 = require("./core/events/event-bus.service");
+const config_service_1 = require("./core/config/config.service");
+const auth_service_1 = require("./core/auth/auth.service");
+// Boot-time capability declaration runs over the auto-generated
+// `ALL_CAPABILITY_DEFINITIONS` array — every `*.cap.ts` file that ships
+// with `@camstack/types` is included automatically. Adding a new cap
+// requires no edit to this file: drop the `*.cap.ts` and re-run
+// `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).
+const types_1 = require("@camstack/types");
+const stream_probe_service_1 = require("./core/streaming/stream-probe.service");
+const feature_service_1 = require("./core/feature/feature.service");
+const agent_registry_service_1 = require("./core/agent/agent-registry.service");
+const moleculer_service_1 = require("./core/moleculer/moleculer.service");
+const addon_registry_service_1 = require("./core/addon/addon-registry.service");
+const addon_package_service_1 = require("./core/addon/addon-package.service");
+const repl_engine_service_1 = require("./core/repl/repl-engine.service");
+const network_quality_service_1 = require("./core/network/network-quality.service");
+const storage_service_1 = require("./core/storage/storage.service");
+const addon_bridge_service_1 = require("./core/addon-bridge/addon-bridge.service");
+const addon_pages_service_1 = require("./core/addon-pages/addon-pages.service");
+const addon_widgets_service_1 = require("./core/addon-widgets/addon-widgets.service");
+const trpc_router_1 = require("./api/trpc/trpc.router");
+const core_cap_bridge_1 = require("./api/trpc/core-cap-bridge");
+const trpc_context_1 = require("./api/trpc/trpc.context");
+const addon_upload_1 = require("./api/addon-upload");
+const auth_whoami_1 = require("./api/auth-whoami");
+const session_cookie_js_1 = require("./auth/session-cookie.js");
+const health_routes_1 = require("./api/health/health.routes");
+const oauth2_routes_js_1 = require("./api/oauth2/oauth2-routes.js");
+const core_1 = require("@camstack/core");
+const boot_config_1 = require("./boot/boot-config");
+const manual_boot_1 = require("./manual-boot");
+const post_boot_service_1 = require("./boot/post-boot.service");
+const integration_id_backfill_1 = require("./boot/integration-id-backfill");
+// ---- Process-level error handlers ----
+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);
+});
+// ---- 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;
+function immediateChildCleanup(signal) {
+    if (shutdownStarted)
+        return;
+    shutdownStarted = true;
+    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';
+        // 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`;
+        (0, node_child_process_1.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();
+}
+process.on('SIGTERM', () => immediateChildCleanup('SIGTERM'));
+process.on('SIGINT', () => immediateChildCleanup('SIGINT'));
+// ---- Orphan cleanup ----
+/**
+ * Kill leftover camstack processes from a previous crash.
+ * Targets: coreml_inference.py (Python engines).
+ * Only kills processes whose parent is PID 1 (orphaned) to avoid killing children of a live server.
+ */
+function cleanupOrphanProcesses() {
+    const isMac = process.platform === 'darwin';
+    const isLinux = process.platform === 'linux';
+    if (!isMac && !isLinux)
+        return;
+    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";
+        const output = (0, node_child_process_1.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);
+            // Only kill orphans (ppid=1) — never kill children of a running server
+            if (ppid !== 1 || isNaN(pid) || pid === process.pid)
+                continue;
+            try {
+                process.kill(pid, 'SIGTERM');
+                killed++;
+            }
+            catch {
+                // Process may have already exited
+            }
+        }
+    }
+    catch {
+        // grep returns exit code 1 when no matches — that's fine
+    }
+    if (killed > 0) {
+        console.log(`[cleanup] Killed ${killed} orphaned camstack process(es) from a previous run`);
+    }
+}
+// ---- Bootstrap ----
+async function bootstrap() {
+    // Clean up orphaned processes from previous crashes before starting
+    cleanupOrphanProcesses();
+    // SPA fallback — set later when admin UI is resolved, used by addon route catch-all
+    let spaIndexHtml = 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 = (0, boot_config_1.loadBootstrapConfig)(configPath);
+    const infra = await (0, boot_config_1.setupInfra)(configPath, bootstrapConfig);
+    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 = tlsOptions ? { https: tlsOptions } : {};
+    const app = await (0, manual_boot_1.bootManual)({ infra, fastifyOpts });
+    app.enableShutdownHooks();
+    app.enableCors();
+    const fastify = app.getHttpAdapter().getInstance();
+    await fastify.register(cookie_1.default);
+    // 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(storage_service_1.StorageService);
+    storageService.setLocationManager(infra.locationManager);
+    // ConfigService — SettingsStore is wired later by the settings-store capability consumer
+    const config = app.get(config_service_1.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(auth_service_1.AuthService);
+        const uploadAddonBridge = app.get(addon_bridge_service_1.AddonBridgeService);
+        const uploadMoleculer = app.get(moleculer_service_1.MoleculerService);
+        const uploadAddonRegistry = app.get(addon_registry_service_1.AddonRegistryService);
+        const uploadAddonPackage = app.get(addon_package_service_1.AddonPackageService);
+        const uploadLogger = app.get(logging_service_1.LoggingService).createLogger('addon-upload');
+        await (0, addon_upload_1.registerAddonUploadRoute)(fastify, uploadAddonBridge, uploadAuthService, uploadMoleculer, uploadAddonRegistry, uploadAddonPackage, uploadLogger);
+        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 (0, auth_whoami_1.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);
+    }
+    // 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(logging_service_1.LoggingService);
+    const addonRouteRegistry = new core_1.AddonRouteRegistry();
+    const dataPlaneRegistry = new core_1.DataPlaneRegistry();
+    // Use Fastify-managed notification/toast wrappers (globally provided by NotificationModule)
+    const { NotificationServiceWrapper } = await Promise.resolve().then(() => __importStar(require('./core/notification/notification-wrapper.service')));
+    const { ToastServiceWrapper } = await Promise.resolve().then(() => __importStar(require('./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;
+    // Wire AddonRouteRegistry and NotificationService
+    const addonRegistry = app.get(addon_registry_service_1.AddonRegistryService);
+    addonRegistry.setAddonRouteRegistry(addonRouteRegistry);
+    addonRegistry.setDataPlaneRegistry(dataPlaneRegistry);
+    // ── Configure the CapabilityRegistry (created in AddonRegistryService constructor) ──
+    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
+    // from forked workers / agents) find their definition during
+    // onModuleInit. The list comes from the codegen — see the import
+    // comment above for the rationale.
+    for (const capDef of types_1.ALL_CAPABILITY_DEFINITIONS) {
+        capabilityRegistry.declareCapability(capDef);
+    }
+    // Hub-internal `sso-bridge` provider — gives auth-provider addons
+    // (OIDC, SAML, magic-link, …) a typed gateway to mint an HMAC-signed
+    // 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(auth_service_1.AuthService);
+    capabilityRegistry.registerProvider('sso-bridge', '$hub', {
+        signBridgeToken: async ({ claims, ttlSec, }) => {
+            const token = authServiceForBridge.signSsoBridgeToken(claims, ttlSec ?? 300);
+            return { token };
+        },
+        verifyBridgeToken: async ({ token }) => {
+            return authServiceForBridge.verifySsoBridgeToken(token);
+        },
+    });
+    // Wire registry into NotificationService for proxy-based output resolution
+    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 = 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');
+    // Mark registry as ready — providers from app.init() are now registered
+    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(moleculer_service_1.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();
+        (0, health_routes_1.registerHealthRoutes)(fastify, {
+            moleculer,
+            agentRegistry: app.get(agent_registry_service_1.AgentRegistryService),
+            hubVersion,
+        });
+        console.log(`[bootstrap] Health routes registered (hub v${hubVersion})`);
+    }
+    catch (err) {
+        console.warn('[bootstrap] Failed to register health routes:', err);
+    }
+    // Seed the device-name cache the log formatter consults so logs
+    // emitted before the first DeviceRegistered already resolve names.
+    // Subsequent registers/unregisters flow through the event-bus
+    // subscription installed in `LoggingService.attachDeviceNameStream`.
+    try {
+        const dm = capabilityRegistry.getSingleton('device-manager');
+        if (dm?.listAll) {
+            const devices = await dm.listAll({});
+            loggingService.setDeviceNames(devices.map((d) => ({ id: d.id, name: d.name })));
+            loggingService.createLogger('logging').info('device-name cache seeded from device-manager', {
+                meta: { count: devices.length, ids: devices.map((d) => d.id) },
+            });
+        }
+        else {
+            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);
+    }
+    try {
+        const authService = app.get(auth_service_1.AuthService);
+        appRouter = (0, trpc_router_1.buildAppRouter)({
+            authService,
+            configService: config,
+            featureService: app.get(feature_service_1.FeatureService),
+            loggingService,
+            eventBus: app.get(event_bus_service_1.EventBusService),
+            agentRegistry: app.get(agent_registry_service_1.AgentRegistryService),
+            moleculer: app.get(moleculer_service_1.MoleculerService),
+            addonRegistry,
+            replEngine: app.get(repl_engine_service_1.ReplEngineService),
+            networkQualityService: app.get(network_quality_service_1.NetworkQualityService),
+            addonBridge: app.get(addon_bridge_service_1.AddonBridgeService),
+            addonPackageService: app.get(addon_package_service_1.AddonPackageService),
+            notificationService,
+            toastService,
+            capabilityRegistry,
+            streamProbe: app.get(stream_probe_service_1.StreamProbeService),
+        });
+        await fastify.register(fastify_1.fastifyTRPCPlugin, {
+            prefix: '/trpc',
+            trpcOptions: {
+                router: appRouter,
+                createContext: ({ req }) => (0, trpc_context_1.createTrpcContext)(req, authService, addonRegistry),
+                onError: ({ path, error, }) => {
+                    const trpcLogger = app.get(logging_service_1.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;
+        // 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((0, core_cap_bridge_1.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);
+        }
+        // Register addon-pages static file endpoint
+        const addonPagesService = app.get(addon_pages_service_1.AddonPagesService);
+        fastify.get('/api/addon-pages/:addonId/*', async (request, reply) => {
+            const { addonId } = request.params;
+            const filePath = request.params['*'];
+            if (!filePath) {
+                return reply.status(400).send('Missing file path');
+            }
+            const resolved = addonPagesService.resolveBundle(addonId, filePath);
+            if (!resolved) {
+                return reply.status(404).send('Not found');
+            }
+            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);
+        });
+        // 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(addon_widgets_service_1.AddonWidgetsService);
+        fastify.get('/api/addon-widgets/:addonId/*', async (request, reply) => {
+            const { addonId } = request.params;
+            const filePath = request.params['*'];
+            if (!filePath) {
+                return reply.status(400).send('Missing file path');
+            }
+            const resolved = addonWidgetsService.resolveBundle(addonId, filePath);
+            if (!resolved) {
+                return reply.status(404).send('Not found');
+            }
+            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);
+        });
+        // Serve static assets (e.g. SVG icons) from an addon's package directory
+        fastify.get('/api/addon-assets/:addonId/*', async (request, reply) => {
+            const { addonId } = request.params;
+            const assetPath = request.params['*'] ?? '';
+            const packageDir = addonRegistry.getAddonPackageDir(addonId);
+            if (!packageDir) {
+                return reply.code(404).send({ error: 'Addon not found' });
+            }
+            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' });
+            }
+            if (!fs.existsSync(filePath)) {
+                return reply.code(404).send({ error: 'Asset not found' });
+            }
+            const ext = path.extname(filePath).toLowerCase();
+            const contentTypes = {
+                '.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
+        // own callback handler validated the IdP response. We trust the
+        // claims because:
+        //   1. The path is server-internal — providers run in-process and
+        //      issue the redirect with their own validated state.
+        //   2. The query string is consumed once and immediately swapped
+        //      for a JWT in the URL fragment (#token=...) which never hits
+        //      the server logs and isn't replayable.
+        //
+        // The provider prefixes the redirect with `provider=auth-oidc` so
+        // we can attribute the session. The mint is currently best-effort
+        // — a future hardening should require the provider to also pass a
+        // nonce signed with the auth.jwtSecret so we can verify the redirect
+        // came from the addon's own callback handler.
+        fastify.get('/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(auth_service_1.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),
+                });
+            }
+        });
+        // ── Backup archive download (Phase 4 / Task 24) ────────────────
+        // Streams an archive at `<locationId>/<archiveId>` through the
+        // storage cap's chunked-download protocol straight to an HTTP
+        // response. The admin UI uses an authenticated `fetch` + Blob to
+        // fetch and trigger a save dialog (no cookie auth on this server,
+        // so we can't rely on `window.location.assign`).
+        fastify.get('/api/backup/download/:locationId/:archiveId', async (request, reply) => {
+            const authHeader = request.headers.authorization;
+            if (!authHeader) {
+                return reply.status(401).send({ error: 'Unauthorized' });
+            }
+            try {
+                const token = authHeader.replace('Bearer ', '');
+                const downloadAuth = app.get(auth_service_1.AuthService);
+                const payload = downloadAuth.verifyToken(token);
+                if (!payload.isAdmin) {
+                    return reply.status(403).send({ error: 'Admin required' });
+                }
+            }
+            catch {
+                return reply.status(401).send({ error: 'Invalid token' });
+            }
+            const { locationId, archiveId } = request.params;
+            const backupSingleton = capabilityRegistry.getSingleton('backup');
+            if (!backupSingleton?.listArchives) {
+                return reply.status(503).send({ error: 'Backup orchestrator unavailable' });
+            }
+            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' });
+            }
+            const storage = capabilityRegistry.getSingleton('storage');
+            if (!storage?.beginDownload) {
+                return reply.status(503).send({ error: 'Storage cap unavailable' });
+            }
+            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 { downloadId, sizeBytes } = await storage.beginDownload({
+                location: locationId,
+                relativePath: archive.filename,
+            });
+            const CHUNK = 8 * 1024 * 1024;
+            try {
+                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 });
+                    if (chunk.byteLength === 0) {
+                        throw new Error(`backup download: empty chunk at offset ${offset}/${sizeBytes}`);
+                    }
+                    reply.raw.write(chunk);
+                    offset += chunk.byteLength;
+                }
+                reply.raw.end();
+            }
+            catch (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' });
+                }
+                reply.raw.destroy(err instanceof Error ? err : new Error(String(err)));
+            }
+            finally {
+                try {
+                    await storage.endDownload({ downloadId });
+                }
+                catch {
+                    /* best-effort */
+                }
+            }
+            return reply;
+        });
+        // POST /api/auth/session — upgrade a tRPC-issued JWT to a browser cookie.
+        fastify.post('/api/auth/session', async (request, reply) => {
+            const token = request.body?.token;
+            if (!token)
+                return reply.status(400).send({ error: 'token required' });
+            let ttlSec;
+            try {
+                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 {
+                return reply.status(401).send({ error: 'invalid token' });
+            }
+            const c = (0, session_cookie_js_1.buildSessionCookie)(token, ttlSec);
+            reply.setCookie(c.name, c.value, c.options);
+            return reply.send({ ok: true });
+        });
+        // DELETE /api/auth/session — clear the cookie on logout.
+        fastify.delete('/api/auth/session', async (_request, reply) => {
+            const c = (0, session_cookie_js_1.clearSessionCookie)();
+            reply.setCookie(c.name, c.value, c.options);
+            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('/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 (!(0, session_cookie_js_1.isEmbedRedirectTarget)(next))
+                return reply.status(400).send({ error: 'invalid next' });
+            let ttlSec;
+            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 = (0, session_cookie_js_1.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('/addon/:addonId/*', async (request, reply) => {
+            const { addonId } = request.params;
+            const subPath = request.params['*'] ?? '';
+            const method = request.method;
+            const fullPath = `/addon/${addonId}/${subPath}`;
+            const query = request.query ?? {};
+            const headers = {};
+            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(',');
+            }
+            // ── 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);
+            if (dpMatch) {
+                const access = dpMatch.endpoint.access;
+                if (access !== 'public') {
+                    const authHeader = request.headers.authorization;
+                    const cookieToken = request.cookies?.[session_cookie_js_1.SESSION_COOKIE];
+                    if (!authHeader && !cookieToken) {
+                        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 scopeOk = scopedToken?.scopes.some((scope) => scope.type === 'addon' && scope.target === addonId);
+                        if (!scopedToken || !scopeOk) {
+                            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' });
+                            }
+                        }
+                        catch {
+                            return reply.status(401).send({ error: 'Invalid token' });
+                        }
+                    }
+                }
+                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}`;
+                // Take over the socket — `proxyToUpstream` drives the raw response.
+                reply.hijack();
+                (0, core_1.proxyToUpstream)({
+                    baseUrl: dpMatch.endpoint.baseUrl,
+                    secret: dpMatch.endpoint.secret,
+                    upstreamPath,
+                    clientReq: request.raw,
+                    clientRes: reply.raw,
+                });
+                return;
+            }
+            const match = addonRouteRegistry.matchRoute(method, fullPath);
+            if (!match) {
+                if (method === 'GET' && spaIndexHtml) {
+                    return reply.type('text/html').send(fs.createReadStream(spaIndexHtml));
+                }
+                return reply.status(404).send({ error: 'Not found' });
+            }
+            // Auth check based on route.access
+            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_js_1.SESSION_COOKIE];
+                if (!authHeader && !cookieToken) {
+                    if ((0, session_cookie_js_1.shouldRedirectToLogin)(request.method, request.headers.accept)) {
+                        const qs = request.url.includes('?') ? request.url.slice(request.url.indexOf('?')) : '';
+                        return reply.redirect((0, session_cookie_js_1.loginRedirectUrl)(fullPath + qs));
+                    }
+                    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 });
+                    if (!scopedToken) {
+                        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;
+                    });
+                    if (!scopeMatch) {
+                        return reply.status(403).send({ error: 'Token scope mismatch' });
+                    }
+                    // Build addon request with scoped token context
+                    const addonRequest = {
+                        params: match.params,
+                        query,
+                        body: request.body,
+                        headers,
+                        scopedToken: {
+                            id: scopedToken.id,
+                            userId: scopedToken.userId,
+                            scopes: scopedToken.scopes,
+                        },
+                    };
+                    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 addonRequest = {
+                            params: match.params,
+                            query,
+                            body: request.body,
+                            headers,
+                            user: {
+                                id: payload.userId ?? 'unknown',
+                                username: payload.username ?? 'unknown',
+                                isAdmin: payload.isAdmin,
+                            },
+                        };
+                        const addonReply = buildAddonReply(reply);
+                        return match.route.handler(addonRequest, addonReply);
+                    }
+                    catch {
+                        return reply.status(401).send({ error: 'Invalid token' });
+                    }
+                }
+            }
+            // Public route — no auth required
+            const addonRequest = {
+                params: match.params,
+                query,
+                body: request.body,
+                headers,
+            };
+            const addonReply = buildAddonReply(reply);
+            return match.route.handler(addonRequest, addonReply);
+        });
+        // ── OAuth2 authorization endpoints ─────────────────────────────────────
+        // Mounted under /api/oauth2/* so they sit inside the universal "/api/"
+        // namespace already excluded from the SPA catch-all everywhere.
+        // getRegistry is a closure so it always resolves the live registry at
+        // request time (safe even if called before ready()).
+        (0, oauth2_routes_js_1.registerOauth2Routes)(fastify, {
+            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/*');
+        // Attach tRPC WebSocket handler using noServer mode to avoid
+        // Fastify intercepting the upgrade request with a 400 response.
+        const wss = new ws_2.WebSocketServer({ noServer: true });
+        (0, ws_1.applyWSSHandler)({
+            wss,
+            router: appRouter,
+            createContext: (opts) => (0, trpc_context_1.createWsTrpcContext)(opts, authService, addonRegistry),
+            onError: ({ path, error, }) => {
+                const trpcLogger = app.get(logging_service_1.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;
+        // Remove any existing upgrade listeners that might conflict
+        const existingUpgradeListeners = httpServer.listeners('upgrade');
+        httpServer.removeAllListeners('upgrade');
+        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);
+                });
+            }
+            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]);
+                }
+            }
+        });
+    }
+    catch (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, reply) => {
+            reply.status(503).send({
+                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');
+    }
+    // ScopedTokenManager and admin user creation handled by local-auth addon.
+    // Serve admin UI static files from the admin-ui singleton capability.
+    // Always enabled — in dev mode Vite runs on its own port and doesn't interfere.
+    //
+    // The admin-ui addon runs in its own dedicated runner subprocess and
+    // finishes registering 1-3s after bootstrap; poll briefly for it
+    // before giving up to avoid the 'admin-ui capability not registered —
+    // no static file serving' warn that left the SPA unserved until next
+    // restart.
+    try {
+        const addonRegistry = app.get(addon_registry_service_1.AddonRegistryService);
+        const capRegistry = addonRegistry.getCapabilityRegistry();
+        let adminUI = capRegistry?.getSingleton('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';
+        if (!adminUI && capRegistry && !skipAdminUIWait) {
+            // Forked-addon spawn + Moleculer registration + tRPC hydration
+            // can take ~15-20s on cold boot, especially when several runners
+            // are spawning in parallel. The previous 10s window was racing
+            // 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;
+            while (!adminUI && Date.now() < deadline) {
+                await new Promise((r) => setTimeout(r, POLL_MS));
+                adminUI = capRegistry.getSingleton('admin-ui');
+            }
+        }
+        if (adminUI) {
+            const { staticDir } = await adminUI.getStaticDir();
+            const indexPath = path.join(staticDir, 'index.html');
+            if (fs.existsSync(staticDir) && fs.existsSync(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`.
+                // The old `wildcard: false` registered one route per file enumerated
+                // AT BOOT, so a redeployed admin-ui's new content-hashed assets had no
+                // route and 404'd until a hub restart. Live `sendFile` removes that.
+                await fastify.register(static_1.default, {
+                    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');
+                if (fs.existsSync(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;
+                    if (url.startsWith('/trpc') ||
+                        url.startsWith('/api/') ||
+                        url.startsWith('/agent') ||
+                        url.startsWith('/health')) {
+                        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
+                    // admin-ui's new content-hashed files are picked up without a hub
+                    // restart. When the file is missing, 404 — never the SPA
+                    // `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;
+                    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)) {
+                            // 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;
+                            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');
+                            }
+                            else {
+                                reply.header('cache-control', 'no-cache');
+                            }
+                            return reply.sendFile(rel);
+                        }
+                        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})`);
+            }
+            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');
+        }
+    }
+    catch (err) {
+        console.error('[bootstrap] Failed to set up admin UI static serving:', err);
+    }
+    try {
+        await app.listen(port, host);
+    }
+    catch (listenErr) {
+        if (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);
+        }
+        throw listenErr;
+    }
+    const logger = app.get(logging_service_1.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(post_boot_service_1.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),
+    // so deleting their integration cascades them. Idempotent — only touches
+    // untagged top-level devices of single-instance addons.
+    try {
+        const dmForBackfill = capabilityRegistry.getSingleton('device-manager');
+        const integrationRegistry = addonRegistry.getIntegrationRegistry();
+        if (dmForBackfill?.listAll && dmForBackfill?.setIntegrationId && integrationRegistry) {
+            const listAll = dmForBackfill.listAll;
+            const setIntegrationId = dmForBackfill.setIntegrationId;
+            const backfillLogger = loggingService.createLogger('integration-backfill');
+            await (0, integration_id_backfill_1.runIntegrationIdBackfill)({
+                listIntegrations: async () => (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,
+                })),
+                setIntegrationId: (deviceId, integrationId) => setIntegrationId({ deviceId, integrationId }),
+                logger: {
+                    info: (message, meta) => backfillLogger.info(message, { meta }),
+                    warn: (message, meta) => backfillLogger.warn(message, { meta }),
+                },
+            });
+        }
+    }
+    catch (err) {
+        console.warn('[bootstrap] integrationId backfill skipped:', err instanceof Error ? err.message : err);
+    }
+}
+/**
+ * Read the hub's own package version (best-effort) for /health responses.
+ */
+function readHubVersion() {
+    try {
+        const pkgPath = path.resolve(__dirname, '..', 'package.json');
+        if (fs.existsSync(pkgPath)) {
+            const raw = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+            if (typeof raw.version === 'string')
+                return raw.version;
+        }
+    }
+    catch {
+        // best-effort
+    }
+    return 'unknown';
+}
+/**
+ * Build an AddonHttpReply wrapper around a Fastify reply.
+ */
+function buildAddonReply(reply) {
+    const wrapper = {
+        status(code) {
+            reply.status(code);
+            return wrapper;
+        },
+        code(code) {
+            reply.code(code);
+            return wrapper;
+        },
+        send(data) {
+            reply.send(data);
+        },
+        redirect(url) {
+            reply.redirect(url);
+        },
+        header(name, value) {
+            reply.header(name, value);
+            return wrapper;
+        },
+        type(mime) {
+            reply.type(mime);
+            return wrapper;
+        },
+    };
+    return wrapper;
+}
+bootstrap().catch((err) => {
+    console.error('Bootstrap failed:', err);
+    process.exit(1);
+});