@camstack/server 0.1.3

package/src/api/trpc/trpc.router.ts

@@ -0,0 +1,275 @@
+import { trpcRouter } from './trpc.middleware'
+// All capability tRPC routers are auto-mounted via `mountAllCaps()` below.
+// Only the OVERRIDES (service-backed providers, custom collection
+// dispatch logic, hub-only remote-proxy caps) and the CORE (non-cap)
+// routers are wired manually in this file. Tracking comment for the
+// historical migration index (every `create<X>Router` that used to live
+// here has been replaced by its codegen'd cap-router counterpart):
+//   auth → auth (kept manual for AuthService DI), users/system →
+//   `userMgmt`/`system` caps, settings → `system-config` builtin,
+//   devices → `deviceManager` cap, integrations → `integrations` cap,
+//   streaming → `streamingManagement` cap, events → `eventQuery` cap,
+//   logs → kept manual, live → kept manual, processes → `processMgmt`
+//   cap, agents → `nodes` cap, sessions → `session` cap, trackMedia /
+//   trackTrail → caps, recording → `recordingEngine` cap, network →
+//   `networkQuality` cap, addons → `addons` cap, bridgePipeline removed
+//   (legacy), detection → `detectionConfig` cap, capabilities → kept
+//   manual, update → addons cap, addonPages → cap, notification →
+//   `notifications` (kept manual for NotificationService DI),
+//   scopedToken → `userManagement`, toast → `toast` cap, inference →
+//   `pipelineExecutor` cap, pipeline → `pipelineConfig` cap,
+//   systemEvents → kept manual.
+import type { CapabilityRegistry } from '@camstack/kernel'
+import type { InferProvider } from '@camstack/types'
+import {
+  pipelineExecutorCapability,
+  pipelineRunnerCapability,
+  pipelineOrchestratorCapability,
+  audioAnalyzerCapability,
+  audioCodecCapability,
+  platformProbeCapability,
+  decoderCapability,
+  localNetworkCapability,
+} from '@camstack/types'
+import {
+  // The auto-mount covers ~75 caps. The handful re-imported below back
+  // the manual overrides that need service-backed providers or custom
+  // collection dispatch logic; the auto-mount entry is replaced by the
+  // override line via spread precedence.
+  createCapRouter_pipelineExecutor,
+  createCapRouter_pipelineRunner,
+  createCapRouter_pipelineOrchestrator,
+  createCapRouter_audioAnalyzer,
+  createCapRouter_audioCodec,
+  createCapRouter_decoder,
+  createCapRouter_platformProbe,
+  createCapRouter_localNetwork,
+  createCapRouter_snapshotProvider,
+  createCapRouter_networkQuality,
+  createCapRouter_system,
+  createCapRouter_toast,
+  createCapRouter_integrations,
+  createCapRouter_nodes,
+  createCapRouter_addons,
+} from './generated-cap-routers'
+import { mountAllCaps } from './generated-cap-mounts.js'
+import {
+  buildSystemProvider,
+  buildNetworkQualityProvider,
+  buildToastProvider,
+  buildNodesProvider,
+  buildIntegrationsProvider,
+  buildAddonsProvider,
+} from '../core/cap-providers.js'
+import { createAuthRouter } from '../core/auth.router.js'
+import { createAddonSettingsRouter } from '../core/addon-settings.router.js'
+import { createSettingsBackendRouter } from '../core/settings-backend.router.js'
+import { createEventBusProxyRouter } from '../core/event-bus-proxy.router.js'
+import { createReplRouter } from '../core/repl.router.js'
+import { createNotificationsRouter } from '../core/notifications.router.js'
+import { createLogsRouter } from '../core/logs.router.js'
+import { createSystemEventsRouter } from '../core/system-events.router.js'
+import { createLiveEventsRouter } from '../core/live-events.router.js'
+import { createCapabilitiesRouter } from '../core/capabilities.router.js'
+import { createStreamProbeRouter } from '../core/stream-probe.router.js'
+import { createHwAccelRouter } from '../core/hwaccel.router.js'
+import { requireSingleton, firstSupported, anySupports } from './cap-mount-helpers.js'
+import type { AuthService } from '../../core/auth/auth.service'
+import type { ConfigService } from '../../core/config/config.service'
+import type { FeatureService } from '../../core/feature/feature.service'
+import type { LoggingService } from '../../core/logging/logging.service'
+import type { EventBusService } from '../../core/events/event-bus.service'
+import type { AgentRegistryService } from '../../core/agent/agent-registry.service'
+import type { MoleculerService } from '../../core/moleculer/moleculer.service'
+import type { AddonRegistryService } from '../../core/addon/addon-registry.service'
+import type { AddonPackageService } from '../../core/addon/addon-package.service'
+import type { ReplEngineService } from '../../core/repl/repl-engine.service'
+import type { NetworkQualityService } from '../../core/network/network-quality.service'
+import type { AddonBridgeService } from '../../core/addon-bridge/addon-bridge.service'
+import type { NotificationService, ToastService } from '@camstack/core'
+import type { StreamProbeService } from '../../core/streaming/stream-probe.service'
+
+export interface RouterServices {
+  authService: AuthService
+  configService: ConfigService
+  featureService: FeatureService
+  loggingService: LoggingService
+  eventBus: EventBusService
+  agentRegistry: AgentRegistryService
+  moleculer: MoleculerService
+  addonRegistry: AddonRegistryService
+  replEngine: ReplEngineService
+  networkQualityService: NetworkQualityService
+  addonBridge: AddonBridgeService
+  addonPackageService: AddonPackageService
+  notificationService: NotificationService | null
+  toastService: ToastService | null
+  capabilityRegistry: CapabilityRegistry | null
+  streamProbe: StreamProbeService | null
+}
+
+/**
+ * Build the AppRouter. Mounts every codegen'd cap router via the auto-
+ * mount entrypoint and overrides the handful that need service-backed
+ * providers or custom collection dispatch. Non-cap (core) routers ride
+ * alongside in the same root object.
+ *
+ * Override-by-spread: spread `mountAllCaps(services)` first, then the
+ * overrides AFTER — the later property wins. The drift guard in
+ * `scripts/codegen.ts` ensures every codegen'd `createCapRouter_X` is
+ * present in the auto-mount inventory (or explicitly in the legacy
+ * skip-list), so the override list below NEVER needs to add a new entry
+ * just to mount a new cap — only to swap in a custom provider.
+ */
+function buildCapabilityRouters(services: RouterServices) {
+  return {
+    // ── Auto-mount: every codegen'd cap router with a canonical
+    //    provider shape. Everything below this line OVERRIDES the
+    //    auto-mount entry for caps with service-backed providers,
+    //    custom collection routing, or a hub-only `null` remote proxy.
+    ...mountAllCaps(services),
+
+    // ── Non-cap (core) routers — hand-written, single-impl ──────────
+    notifications: createNotificationsRouter(services.notificationService),
+    // Raw DB proxy for forked workers to read/write addon store.
+    // Workers use ctx.api.addonSettingsRaw.getGlobal.query({...}).
+    // NOT the three-level settings gateway — that's the codegen'd
+    // `addonSettings` cap router (mounted via auto-mount above).
+    addonSettingsRaw: createAddonSettingsRouter(services.configService),
+    settingsBackend: createSettingsBackendRouter(() => services.addonRegistry.getSettingsBackend()),
+    eventBusProxy: createEventBusProxyRouter(services.eventBus),
+    repl: createReplRouter(services.replEngine),
+    systemEvents: createSystemEventsRouter(services.eventBus),
+    capabilities: createCapabilitiesRouter(services.capabilityRegistry, services.configService),
+    logs: createLogsRouter(services.loggingService),
+    live: createLiveEventsRouter(services.eventBus, services.addonRegistry),
+    // stream-probe — fixed core API (ffprobe wrapper), not a cap.
+    streamProbe: createStreamProbeRouter(services.streamProbe),
+    // hwaccel — fixed core API, wraps the per-node `$hwaccel` Moleculer
+    // service. UI pipeline / NodeDetail pages query per-node to show
+    // which hardware backend each agent will use.
+    hwaccel: createHwAccelRouter(services.moleculer?.broker ?? null),
+    auth: createAuthRouter(services.authService, services.capabilityRegistry),
+
+    // ── Cap overrides: service-backed providers ─────────────────────
+    // These caps don't have an addon registering a provider in the
+    // CapabilityRegistry — the provider is built on-demand from
+    // backend services. `mountAllCaps` would return `null` for them
+    // (registry lookup miss), so we re-mount with `buildXProvider`.
+    networkQuality: createCapRouter_networkQuality(
+      (_ctx) => buildNetworkQualityProvider(services.networkQualityService),
+    ),
+    system: createCapRouter_system(
+      (_ctx) => buildSystemProvider(services.featureService, services.capabilityRegistry),
+    ),
+    toast: createCapRouter_toast(
+      (ctx) => buildToastProvider(services.toastService, ctx),
+    ),
+    integrations: createCapRouter_integrations(
+      (_ctx) => buildIntegrationsProvider(services.addonRegistry, services.eventBus, services.loggingService),
+    ),
+    nodes: createCapRouter_nodes(
+      (_ctx) => buildNodesProvider(
+        services.agentRegistry,
+        services.moleculer,
+        services.addonRegistry,
+      ),
+    ),
+    addons: createCapRouter_addons(
+      (ctx) => buildAddonsProvider(
+        services.addonRegistry,
+        services.addonPackageService,
+        services.loggingService,
+        services.moleculer,
+        services.configService,
+        ctx,
+      ),
+    ),
+
+    // ── Cap overrides: cross-node remote-proxy cast ─────────────────
+    // These caps' providers have manual interface types that pre-date
+    // `InferProvider<typeof xCap>` — structurally identical, nominally
+    // distinct. Casting at the override site is cheaper than reworking
+    // the provider declarations. Auto-mount can't infer the cast.
+    pipelineExecutor: createCapRouter_pipelineExecutor(
+      (_ctx) => requireSingleton(services.capabilityRegistry, 'pipeline-executor') as InferProvider<typeof pipelineExecutorCapability> | null,
+      (capName, nodeId) => services.moleculer.createCapabilityProxy(capName, nodeId) as InferProvider<typeof pipelineExecutorCapability> | null,
+    ),
+    pipelineRunner: createCapRouter_pipelineRunner(
+      (_ctx) => requireSingleton(services.capabilityRegistry, 'pipeline-runner') as InferProvider<typeof pipelineRunnerCapability> | null,
+      (capName, nodeId) => services.moleculer.createCapabilityProxy(capName, nodeId) as InferProvider<typeof pipelineRunnerCapability> | null,
+    ),
+    pipelineOrchestrator: createCapRouter_pipelineOrchestrator(
+      (_ctx) => requireSingleton(services.capabilityRegistry, 'pipeline-orchestrator') as InferProvider<typeof pipelineOrchestratorCapability> | null,
+      (capName, nodeId) => services.moleculer.createCapabilityProxy(capName, nodeId) as InferProvider<typeof pipelineOrchestratorCapability> | null,
+    ),
+    audioAnalyzer: createCapRouter_audioAnalyzer(
+      (_ctx) => requireSingleton(services.capabilityRegistry, 'audio-analyzer'),
+      (capName, nodeId) => services.moleculer.createCapabilityProxy(capName, nodeId) as InferProvider<typeof audioAnalyzerCapability> | null,
+    ),
+    audioCodec: createCapRouter_audioCodec(
+      (_ctx) => requireSingleton(services.capabilityRegistry, 'audio-codec') as InferProvider<typeof audioCodecCapability> | null,
+      (capName, nodeId) => services.moleculer.createCapabilityProxy(capName, nodeId) as InferProvider<typeof audioCodecCapability> | null,
+    ),
+    decoder: createCapRouter_decoder(
+      (_ctx) => requireSingleton(services.capabilityRegistry, 'decoder') as InferProvider<typeof decoderCapability> | null,
+      (capName, nodeId) => services.moleculer.createCapabilityProxy(capName, nodeId) as InferProvider<typeof decoderCapability> | null,
+    ),
+    platformProbe: createCapRouter_platformProbe(
+      (_ctx) => requireSingleton(services.capabilityRegistry, 'platform-probe'),
+      (capName, nodeId) => services.moleculer.createCapabilityProxy(capName, nodeId) as InferProvider<typeof platformProbeCapability> | null,
+    ),
+
+    // ── Cap overrides: hub-only, no remote fallback ─────────────────
+    // The cap is intentionally single-node; agents are not directly
+    // addressable. Auto-mount would still set up a proxy factory; we
+    // explicitly return `null` to short-circuit any cross-node attempt.
+    localNetwork: createCapRouter_localNetwork(
+      (_ctx) => requireSingleton(services.capabilityRegistry, 'local-network'),
+      (_capName, _nodeId) => null as InferProvider<typeof localNetworkCapability> | null,
+    ),
+
+    // ── Cap overrides: collection dispatch (contribution / probe) ──
+    // `turn-provider.getTurnServers` is now handled generically by the
+    // auto-mount: it's an array-output method on a `collection` cap, so
+    // `mountAllCaps` fans it across every enabled provider via
+    // `concatCollection` when no `addonId` is supplied. No hand-written
+    // override needed.
+    //
+    // `snapshot-provider.supportsDevice` is an OR across providers;
+    // `getSnapshot` picks the first one that claims the device. The
+    // generic first-provider resolver from the auto-mount can't model
+    // this — we hand-write the probe + fan-out logic.
+    snapshotProvider: createCapRouter_snapshotProvider(
+      (_ctx) => {
+        const reg = services.capabilityRegistry
+        if (!reg) return null
+        type SnapshotProviderInferred = import('@camstack/types').CapabilityProviderMap['snapshot-provider']
+        const providers = reg.getCollection<SnapshotProviderInferred>('snapshot-provider')
+        if (!providers || providers.length === 0) return null
+        const supportsDevice = anySupports(providers, 'supportsDevice')
+        const getSnapshot = firstSupported(providers, 'supportsDevice', 'getSnapshot')
+        return { supportsDevice, getSnapshot }
+      },
+    ),
+
+    // NOT MOUNTED — legacy provider shapes (positional args / sync
+    // returns) that don't match the codegen routers' {input}-object +
+    // Promise<T> contract. Tracked by `LEGACY_SHAPE_SKIP` in
+    // `generated-cap-mounts.ts` until the provider refactor (task #195):
+    //   - addon-routes        (IAddonRouteProvider: getRoutes sync)
+    //   - auth-provider       (IAuthProvider: positional credentials)
+    //   - log-destination     (ILogDestination: positional + extra lifecycle)
+    //   - restreamer          (IRestreamer: registerDevice positional)
+    //   - streaming-engine    (IStreamingEngine: registerStream positional)
+    //   - webrtc              (IWebRtcProvider: missing hasAdaptiveBitrate)
+  }
+}
+
+export function buildAppRouter(services: RouterServices) {
+  return trpcRouter({
+    ...buildCapabilityRouters(services),
+  })
+}
+
+export type AppRouter = ReturnType<typeof buildAppRouter>

package/src/auth/session-cookie.ts

@@ -0,0 +1,44 @@
+/** Browser session cookie carrying the hub JWT. Set by POST /api/auth/session
+ *  after a tRPC login; read by the addon-route catch-all for `authenticated`
+ *  routes hit by a plain browser navigation. */
+export const SESSION_COOKIE = 'camstack_session'
+
+interface CookieSpec {
+  readonly name: string
+  readonly value: string
+  readonly options: {
+    httpOnly: boolean
+    sameSite: 'lax'
+    secure: boolean
+    path: string
+    maxAge: number
+  }
+}
+
+export function buildSessionCookie(token: string, ttlSec: number): CookieSpec {
+  return {
+    name: SESSION_COOKIE,
+    value: token,
+    options: { httpOnly: true, sameSite: 'lax', secure: true, path: '/', maxAge: ttlSec },
+  }
+}
+
+export function clearSessionCookie(): CookieSpec {
+  return {
+    name: SESSION_COOKIE,
+    value: '',
+    options: { httpOnly: true, sameSite: 'lax', secure: true, path: '/', maxAge: 0 },
+  }
+}
+
+/** A browser navigation we can bounce to the login page: a top-level GET
+ *  that wants HTML. Anything else (API call, POST, non-HTML) keeps the
+ *  401 behavior so programmatic clients get a clean error. */
+export function shouldRedirectToLogin(method: string, accept: string | undefined): boolean {
+  return method === 'GET' && typeof accept === 'string' && accept.includes('text/html')
+}
+
+/** Build the `/login?next=…` URL for an unauthenticated browser request. */
+export function loginRedirectUrl(originalUrl: string): string {
+  return `/login?next=${encodeURIComponent(originalUrl)}`
+}

package/src/boot/boot-config.ts

@@ -0,0 +1,278 @@
+/**
+ * Phase 1: Bootstrap config loading and infrastructure setup.
+ *
+ * Extracted from main.ts — pure extraction, no behavior change.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as yaml from "js-yaml";
+import { randomBytes } from "node:crypto";
+import { asJsonObject } from "@camstack/types";
+import { bootstrapSchema } from "../core/config/config.schema";
+import type { BootstrapConfig } from "../core/config/config.schema";
+import { StorageLocationManager } from "../core/storage/storage-location-manager";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type { BootstrapConfig };
+
+export interface InfraContext {
+  readonly bootstrapConfig: BootstrapConfig;
+  readonly dataPath: string;
+  readonly locationManager: StorageLocationManager;
+  readonly tlsOptions: { key: Buffer; cert: Buffer } | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const CONFIG_DEFAULTS: Record<string, unknown> = {
+  server: { port: 4443, host: "0.0.0.0", dataPath: "camstack-data" },
+  auth: {
+    jwtSecret: null,
+    adminUsername: "admin",
+    adminPassword: "changeme",
+  },
+};
+
+const ENV_VAR_MAP: Record<string, string> = {
+  CAMSTACK_PORT: "server.port",
+  CAMSTACK_HOST: "server.host",
+  CAMSTACK_DATA: "server.dataPath",
+  CAMSTACK_JWT_SECRET: "auth.jwtSecret",
+  CAMSTACK_ADMIN_USER: "auth.adminUsername",
+  CAMSTACK_ADMIN_PASS: "auth.adminPassword",
+  CAMSTACK_HUB_URL: "hub.url",
+  CAMSTACK_HUB_TOKEN: "hub.token",
+  CAMSTACK_AGENT_NAME: "agent.name",
+  CAMSTACK_TLS_ENABLED: "tls.enabled",
+  CAMSTACK_TLS_CERT: "tls.certPath",
+  CAMSTACK_TLS_KEY: "tls.keyPath",
+};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function setNested(
+  obj: Record<string, unknown>,
+  p: string,
+  value: unknown,
+): Record<string, unknown> {
+  const [head, ...rest] = p.split(".");
+  if (!head) return obj;
+  if (rest.length === 0) return { ...obj, [head]: value };
+  const child = asJsonObject(obj[head]) ?? {};
+  return { ...obj, [head]: setNested(child, rest.join("."), value) };
+}
+
+// ---------------------------------------------------------------------------
+// loadBootstrapConfig
+// ---------------------------------------------------------------------------
+
+/**
+ * Load bootstrap config from a YAML file, apply env-var overrides, and
+ * validate via the bootstrap Zod schema.
+ */
+export function loadBootstrapConfig(configPath: string): BootstrapConfig {
+  // Only bootstrap sections live in config.yaml.
+  // All runtime settings are stored in the SQL system_settings table.
+
+  let raw: Record<string, unknown>;
+
+  if (fs.existsSync(configPath)) {
+    const content = fs.readFileSync(configPath, "utf-8");
+    raw = asJsonObject(yaml.load(content)) ?? {};
+    // Merge in any missing bootstrap sections (server, auth only)
+    let updated = false;
+    for (const [key, defaults] of Object.entries(CONFIG_DEFAULTS)) {
+      if (!(key in raw)) {
+        raw[key] = defaults;
+        updated = true;
+      }
+    }
+    if (updated) {
+      try {
+        const tmpPath = `${configPath}.tmp`;
+        fs.writeFileSync(
+          tmpPath,
+          yaml.dump(raw, { lineWidth: 120, indent: 2, quotingType: '"' }),
+          "utf-8",
+        );
+        fs.renameSync(tmpPath, configPath);
+        console.log(
+          `[Phase1] Updated config.yaml with missing bootstrap defaults`,
+        );
+      } catch (err) {
+        console.warn(`[Phase1] Could not update config.yaml:`, err);
+      }
+    }
+    console.log(`[Phase1] Loaded bootstrap config from: ${configPath}`);
+  } else {
+    console.log(
+      `[Phase1] Config file not found at: ${configPath} — writing defaults`,
+    );
+    const defaults = { ...CONFIG_DEFAULTS };
+    try {
+      fs.mkdirSync(path.dirname(configPath), { recursive: true });
+      const tmpPath = `${configPath}.tmp`;
+      fs.writeFileSync(
+        tmpPath,
+        yaml.dump(defaults, { lineWidth: 120, indent: 2, quotingType: '"' }),
+        "utf-8",
+      );
+      fs.renameSync(tmpPath, configPath);
+      console.log(`[Phase1] Default config.yaml written to: ${configPath}`);
+    } catch (err) {
+      console.warn(`[Phase1] Could not write default config.yaml:`, err);
+    }
+    raw = defaults;
+  }
+
+  // Apply env var overrides for bootstrap keys
+  for (const [envKey, configPath_] of Object.entries(ENV_VAR_MAP)) {
+    const envValue = process.env[envKey];
+    if (envValue === undefined || envValue === "") continue;
+    const coerced: unknown =
+      configPath_ === "server.port"
+        ? Number(envValue)
+        : configPath_ === "tls.enabled"
+          ? envValue === "true"
+          : envValue;
+    raw = setNested(raw, configPath_, coerced);
+    console.log(`[Phase1] Env override: ${envKey} → ${configPath_}`);
+  }
+
+  return bootstrapSchema.parse(raw);
+}
+
+// ---------------------------------------------------------------------------
+// autoGenerateJwtSecret
+// ---------------------------------------------------------------------------
+
+/**
+ * If `jwtSecret` is null in the parsed config, generate a random secret,
+ * persist it to the YAML file, and return an updated config.
+ */
+export function autoGenerateJwtSecret(
+  configPath: string,
+  bootstrapConfig: BootstrapConfig,
+): BootstrapConfig {
+  if (bootstrapConfig.auth.jwtSecret !== null) {
+    return bootstrapConfig;
+  }
+
+  const secret = randomBytes(32).toString("hex");
+  console.log(
+    "[Phase1] jwtSecret is null — auto-generating and writing to config.yaml",
+  );
+
+  let raw: Record<string, unknown> = {};
+  if (fs.existsSync(configPath)) {
+    raw = asJsonObject(yaml.load(fs.readFileSync(configPath, "utf-8"))) ?? {};
+  }
+
+  const authSection = asJsonObject(raw.auth) ?? {};
+  raw.auth = { ...authSection, jwtSecret: secret };
+
+  const tmpPath = `${configPath}.tmp`;
+  try {
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(
+      tmpPath,
+      yaml.dump(raw, { lineWidth: 120, indent: 2, quotingType: '"' }),
+      "utf-8",
+    );
+    fs.renameSync(tmpPath, configPath);
+  } catch (err) {
+    console.warn(
+      "[Phase1] Could not write auto-generated jwtSecret to config.yaml:",
+      err,
+    );
+  }
+
+  return {
+    ...bootstrapConfig,
+    auth: { ...bootstrapConfig.auth, jwtSecret: secret },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// setupInfra
+// ---------------------------------------------------------------------------
+
+/**
+ * Phase 2: Create StorageLocationManager, ensure directories, configure TLS.
+ * Returns the full InfraContext needed by subsequent boot phases.
+ */
+export async function setupInfra(
+  configPath: string,
+  bootstrapConfig: BootstrapConfig,
+): Promise<InfraContext> {
+  // Auto-generate jwtSecret if not set
+  const config = autoGenerateJwtSecret(configPath, bootstrapConfig);
+
+  const dataPath = path.resolve(config.server.dataPath);
+  const port = config.server.port;
+  const host = config.server.host;
+
+  console.log(
+    `[Phase1] Bootstrap: port=${port}, host=${host}, dataPath=${dataPath}`,
+  );
+
+  // --- Phase 2: Init StorageLocationManager → ensure all dirs exist ---
+  console.log("[Phase2] Initializing storage locations…");
+  const locationManager = new StorageLocationManager(dataPath);
+  await locationManager.initializeDefaults();
+
+  const locationStatus = locationManager.getStatus();
+  for (const { name, available, path: locPath } of locationStatus) {
+    console.log(
+      `[Phase2] Location "${name}": ${available ? "OK" : "UNAVAILABLE"} → ${locPath}`,
+    );
+  }
+
+  // --- Phase 2c: TLS certificate setup ---
+  let tlsOptions: { key: Buffer; cert: Buffer } | undefined;
+
+  if (config.tls.enabled) {
+    // Use require() instead of import() — the ESM build of @camstack/core has
+    // broken chunks with require("fs") when leaked .js files exist in core/src/.
+    // CJS build works correctly and tsx supports require().
+    const core = require("@camstack/core") as typeof import("@camstack/core");
+    const { ensureTlsCert, loadTlsCert } = core;
+    if (config.tls.certPath && config.tls.keyPath) {
+      // User-provided cert
+      console.log(
+        `[Phase2c] Loading custom TLS cert from ${config.tls.certPath}`,
+      );
+      const pair = loadTlsCert(config.tls.certPath, config.tls.keyPath);
+      tlsOptions = { key: pair.key, cert: pair.cert };
+    } else {
+      // Auto-generate self-signed
+      const tlsResult = await ensureTlsCert(dataPath);
+      if (tlsResult.generated) {
+        console.log(
+          `[Phase2c] Generated self-signed TLS cert at ${tlsResult.certPath}`,
+        );
+      } else {
+        console.log(
+          `[Phase2c] Using existing TLS cert at ${tlsResult.certPath}`,
+        );
+      }
+      const pair = loadTlsCert(tlsResult.certPath, tlsResult.keyPath);
+      tlsOptions = { key: pair.key, cert: pair.cert };
+    }
+  }
+
+  return {
+    bootstrapConfig: config,
+    dataPath,
+    locationManager,
+    tlsOptions,
+  };
+}