@thevinci/web 1.0.0

package/server/lib/tunnels/DOCUMENTATION.md

@@ -0,0 +1,18 @@
+# Tunnels Module Documentation
+
+## Purpose
+This module contains tunnel provider orchestration for Vinci, including provider registry/service wiring, managed remote token config lifecycle, and tunnel HTTP route registration.
+
+## Entrypoints and structure
+- `packages/web/server/lib/tunnels/index.js`: tunnel service orchestration.
+- `packages/web/server/lib/tunnels/registry.js`: provider registry.
+- `packages/web/server/lib/tunnels/managed-config.js`: managed remote tunnel token/preset persistence runtime.
+- `packages/web/server/lib/tunnels/routes.js`: tunnel API route registration and request orchestration runtime.
+- `packages/web/server/lib/tunnels/types.js`: tunnel constants, normalization, and shared type helpers.
+- `packages/web/server/lib/tunnels/providers/cloudflare.js`: Cloudflare tunnel provider implementation.
+
+## Public exports (routes.js)
+- `createTunnelRoutesRuntime(dependencies)`: creates tunnel routes runtime and helpers.
+- Returned API:
+  - `registerRoutes(app)`
+  - `startTunnelWithNormalizedRequest(request)`

package/server/lib/tunnels/index.js

@@ -0,0 +1,166 @@
+import {
+  TUNNEL_MODE_QUICK,
+  TUNNEL_PROVIDER_CLOUDFLARE,
+  TunnelServiceError,
+  normalizeTunnelStartRequest,
+  validateTunnelStartRequest,
+} from './types.js';
+
+export function createTunnelService({
+  registry,
+  getController,
+  setController,
+  getActivePort,
+  onQuickTunnelWarning,
+}) {
+  if (!registry) {
+    throw new Error('Tunnel service requires a provider registry');
+  }
+
+  const resolveActiveMode = () => {
+    const controller = getController();
+    if (!controller || typeof controller.mode !== 'string') {
+      return null;
+    }
+    return controller.mode;
+  };
+
+  const resolveActiveProvider = () => {
+    const controller = getController();
+    if (!controller || typeof controller.provider !== 'string') {
+      return null;
+    }
+    return controller.provider;
+  };
+
+  const stop = () => {
+    const controller = getController();
+    if (!controller) {
+      return false;
+    }
+
+    const providerId = typeof controller.provider === 'string' ? controller.provider : '';
+    const provider = providerId ? registry.get(providerId) : null;
+    if (provider?.stop) {
+      provider.stop(controller);
+    } else {
+      controller.stop?.();
+    }
+    setController(null);
+    return true;
+  };
+
+  const checkAvailability = async (providerId) => {
+    const provider = registry.get(providerId);
+    if (!provider) {
+      throw new TunnelServiceError('provider_unsupported', `Unsupported tunnel provider: ${providerId}`);
+    }
+    const result = await provider.checkAvailability();
+    return result;
+  };
+
+  // Mutex to prevent concurrent tunnel starts from orphaning child processes.
+  let startLock = Promise.resolve();
+
+  const start = async (rawRequest, options = {}) => {
+    let releaseLock;
+    const lockPromise = new Promise((resolve) => { releaseLock = resolve; });
+    const previousLock = startLock;
+    startLock = lockPromise;
+
+    await previousLock;
+
+    try {
+      const request = normalizeTunnelStartRequest(rawRequest);
+      const provider = registry.get(request.provider);
+
+      if (!provider) {
+        throw new TunnelServiceError('provider_unsupported', `Unsupported tunnel provider: ${request.provider}`);
+      }
+
+      validateTunnelStartRequest(request, provider.capabilities);
+
+      let publicUrl = provider.resolvePublicUrl(getController());
+      const activeMode = resolveActiveMode();
+
+      if (publicUrl && activeMode !== request.mode) {
+        stop();
+        publicUrl = null;
+      }
+
+      if (!publicUrl) {
+        const availability = await provider.checkAvailability();
+        if (!availability?.available) {
+          const missingDependencyMessage = typeof availability?.message === 'string' && availability.message.trim().length > 0
+            ? availability.message
+            : (request.provider === TUNNEL_PROVIDER_CLOUDFLARE
+              ? 'cloudflared is not installed. Install it with: brew install cloudflared'
+              : `Required dependency for provider '${request.provider}' is missing`);
+          throw new TunnelServiceError('missing_dependency', missingDependencyMessage);
+        }
+
+        const activePort = Number.isFinite(getActivePort?.()) ? getActivePort() : null;
+        const originUrl = activePort !== null ? `http://127.0.0.1:${activePort}` : undefined;
+
+        const controller = await provider.start(request, {
+          activePort,
+          originUrl,
+          ...options,
+        });
+        controller.provider = request.provider;
+        setController(controller);
+
+        publicUrl = provider.resolvePublicUrl(controller);
+        if (!publicUrl) {
+          stop();
+          throw new TunnelServiceError('startup_failed', 'Tunnel started but no public URL was assigned');
+        }
+
+        if (request.mode === TUNNEL_MODE_QUICK) {
+          onQuickTunnelWarning?.();
+        }
+      }
+
+      return {
+        publicUrl,
+        request,
+        activeMode: request.mode,
+        provider: request.provider,
+        providerMetadata: provider.getMetadata?.(getController()) ?? null,
+      };
+    } finally {
+      releaseLock();
+    }
+  };
+
+  const getPublicUrl = () => {
+    const controller = getController();
+    if (!controller) {
+      return null;
+    }
+    const provider = registry.get(controller.provider);
+    if (!provider) {
+      return controller.getPublicUrl?.() ?? null;
+    }
+    return provider.resolvePublicUrl(controller);
+  };
+
+  const getProviderMetadata = () => {
+    const controller = getController();
+    if (!controller) {
+      return null;
+    }
+    const provider = registry.get(controller.provider);
+    return provider?.getMetadata?.(controller) ?? null;
+  };
+
+  return {
+    start,
+    stop,
+    checkAvailability,
+    getPublicUrl,
+    getProviderMetadata,
+    resolveActiveMode,
+    resolveActiveProvider,
+  };
+}

package/server/lib/tunnels/managed-config.js

@@ -0,0 +1,201 @@
+export const createManagedTunnelConfigRuntime = (deps) => {
+  const {
+    fsPromises,
+    path,
+    normalizeManagedRemoteTunnelHostname,
+    normalizeManagedRemoteTunnelPresets,
+    constants,
+  } = deps;
+
+  const {
+    CLOUDFLARE_MANAGED_REMOTE_TUNNELS_FILE_PATH,
+    CLOUDFLARE_LEGACY_NAMED_TUNNELS_FILE_PATH,
+    CLOUDFLARE_MANAGED_REMOTE_TUNNELS_VERSION,
+  } = constants;
+
+  let persistManagedRemoteTunnelConfigLock = Promise.resolve();
+
+  const sanitizeManagedRemoteTunnelConfigEntries = (value) => {
+    if (!Array.isArray(value)) {
+      return [];
+    }
+
+    const result = [];
+    const seenIds = new Set();
+    const seenHostnames = new Set();
+    for (const entry of value) {
+      if (!entry || typeof entry !== 'object') {
+        continue;
+      }
+
+      const id = typeof entry.id === 'string' ? entry.id.trim() : '';
+      const name = typeof entry.name === 'string' ? entry.name.trim() : '';
+      const hostname = normalizeManagedRemoteTunnelHostname(entry.hostname);
+      const token = typeof entry.token === 'string' ? entry.token.trim() : '';
+      const updatedAt = Number.isFinite(entry.updatedAt) ? entry.updatedAt : Date.now();
+
+      if (!id || !name || !hostname || !token) {
+        continue;
+      }
+      if (seenIds.has(id) || seenHostnames.has(hostname)) {
+        continue;
+      }
+
+      seenIds.add(id);
+      seenHostnames.add(hostname);
+      result.push({ id, name, hostname, token, updatedAt });
+    }
+
+    return result;
+  };
+
+  const writeManagedRemoteTunnelConfigToDisk = async (data) => {
+    await fsPromises.mkdir(path.dirname(CLOUDFLARE_MANAGED_REMOTE_TUNNELS_FILE_PATH), { recursive: true });
+    await fsPromises.writeFile(CLOUDFLARE_MANAGED_REMOTE_TUNNELS_FILE_PATH, JSON.stringify(data, null, 2), { encoding: 'utf8', mode: 0o600 });
+  };
+
+  const migrateManagedRemoteTunnelConfigFromLegacyFile = async () => {
+    try {
+      const legacyRaw = await fsPromises.readFile(CLOUDFLARE_LEGACY_NAMED_TUNNELS_FILE_PATH, 'utf8');
+      const parsed = JSON.parse(legacyRaw);
+      const tunnels = sanitizeManagedRemoteTunnelConfigEntries(parsed?.tunnels);
+      const migrated = {
+        version: CLOUDFLARE_MANAGED_REMOTE_TUNNELS_VERSION,
+        tunnels,
+      };
+      await writeManagedRemoteTunnelConfigToDisk(migrated);
+      return migrated;
+    } catch (error) {
+      if (error && typeof error === 'object' && error.code === 'ENOENT') {
+        return { version: CLOUDFLARE_MANAGED_REMOTE_TUNNELS_VERSION, tunnels: [] };
+      }
+      console.warn('Failed to migrate legacy named tunnel config file:', error);
+      return { version: CLOUDFLARE_MANAGED_REMOTE_TUNNELS_VERSION, tunnels: [] };
+    }
+  };
+
+  const readManagedRemoteTunnelConfigFromDisk = async () => {
+    try {
+      const raw = await fsPromises.readFile(CLOUDFLARE_MANAGED_REMOTE_TUNNELS_FILE_PATH, 'utf8');
+      const parsed = JSON.parse(raw);
+      if (!parsed || typeof parsed !== 'object') {
+        return { version: CLOUDFLARE_MANAGED_REMOTE_TUNNELS_VERSION, tunnels: [] };
+      }
+
+      return {
+        version: CLOUDFLARE_MANAGED_REMOTE_TUNNELS_VERSION,
+        tunnels: sanitizeManagedRemoteTunnelConfigEntries(parsed.tunnels),
+      };
+    } catch (error) {
+      if (error && typeof error === 'object' && error.code === 'ENOENT') {
+        return migrateManagedRemoteTunnelConfigFromLegacyFile();
+      }
+      console.warn('Failed to read managed remote tunnel config file:', error);
+      return { version: CLOUDFLARE_MANAGED_REMOTE_TUNNELS_VERSION, tunnels: [] };
+    }
+  };
+
+  const updateManagedRemoteTunnelConfig = async (mutate) => {
+    persistManagedRemoteTunnelConfigLock = persistManagedRemoteTunnelConfigLock.then(async () => {
+      const current = await readManagedRemoteTunnelConfigFromDisk();
+      const next = mutate({
+        version: CLOUDFLARE_MANAGED_REMOTE_TUNNELS_VERSION,
+        tunnels: sanitizeManagedRemoteTunnelConfigEntries(current.tunnels),
+      });
+
+      await writeManagedRemoteTunnelConfigToDisk({
+        version: CLOUDFLARE_MANAGED_REMOTE_TUNNELS_VERSION,
+        tunnels: sanitizeManagedRemoteTunnelConfigEntries(next?.tunnels),
+      });
+    });
+
+    return persistManagedRemoteTunnelConfigLock;
+  };
+
+  const syncManagedRemoteTunnelConfigWithPresets = async (presets) => {
+    const sanitizedPresets = normalizeManagedRemoteTunnelPresets(presets) || [];
+
+    await updateManagedRemoteTunnelConfig((current) => {
+      const byId = new Map(current.tunnels.map((entry) => [entry.id, entry]));
+      const byHostname = new Map(current.tunnels.map((entry) => [entry.hostname, entry]));
+
+      const nextTunnels = [];
+      for (const preset of sanitizedPresets) {
+        const existing = byId.get(preset.id) || byHostname.get(preset.hostname) || null;
+        if (!existing) {
+          continue;
+        }
+
+        nextTunnels.push({
+          ...existing,
+          id: preset.id,
+          name: preset.name,
+          hostname: preset.hostname,
+        });
+      }
+
+      return {
+        version: CLOUDFLARE_MANAGED_REMOTE_TUNNELS_VERSION,
+        tunnels: nextTunnels,
+      };
+    });
+  };
+
+  const upsertManagedRemoteTunnelToken = async ({ id, name, hostname, token }) => {
+    if (typeof id !== 'string' || typeof name !== 'string' || typeof hostname !== 'string' || typeof token !== 'string') {
+      return;
+    }
+    const normalizedId = id.trim();
+    const normalizedName = name.trim();
+    const normalizedHostname = normalizeManagedRemoteTunnelHostname(hostname);
+    const normalizedToken = token.trim();
+    if (!normalizedId || !normalizedName || !normalizedHostname || !normalizedToken) {
+      return;
+    }
+
+    await updateManagedRemoteTunnelConfig((current) => {
+      const withoutConflicts = current.tunnels.filter((entry) => entry.id !== normalizedId && entry.hostname !== normalizedHostname);
+      withoutConflicts.push({
+        id: normalizedId,
+        name: normalizedName,
+        hostname: normalizedHostname,
+        token: normalizedToken,
+        updatedAt: Date.now(),
+      });
+
+      return {
+        version: CLOUDFLARE_MANAGED_REMOTE_TUNNELS_VERSION,
+        tunnels: withoutConflicts,
+      };
+    });
+  };
+
+  const resolveManagedRemoteTunnelToken = async ({ presetId, hostname }) => {
+    const normalizedPresetId = typeof presetId === 'string' ? presetId.trim() : '';
+    const normalizedHostname = normalizeManagedRemoteTunnelHostname(hostname);
+    const config = await readManagedRemoteTunnelConfigFromDisk();
+
+    if (normalizedPresetId) {
+      const byId = config.tunnels.find((entry) => entry.id === normalizedPresetId);
+      if (byId?.token) {
+        return byId.token;
+      }
+    }
+
+    if (normalizedHostname) {
+      const byHostname = config.tunnels.find((entry) => entry.hostname === normalizedHostname);
+      if (byHostname?.token) {
+        return byHostname.token;
+      }
+    }
+
+    return '';
+  };
+
+  return {
+    readManagedRemoteTunnelConfigFromDisk,
+    syncManagedRemoteTunnelConfigWithPresets,
+    upsertManagedRemoteTunnelToken,
+    resolveManagedRemoteTunnelToken,
+  };
+};

package/server/lib/tunnels/providers/cloudflare.js

@@ -0,0 +1,260 @@
+import {
+  checkCloudflareApiReachability,
+  checkCloudflaredAvailable,
+  inspectManagedLocalCloudflareConfig,
+  normalizeCloudflareTunnelHostname,
+  startCloudflareManagedLocalTunnel,
+  startCloudflareManagedRemoteTunnel,
+  startCloudflareQuickTunnel,
+} from '../../cloudflare-tunnel.js';
+
+import {
+  TUNNEL_INTENT_EPHEMERAL_PUBLIC,
+  TUNNEL_INTENT_PERSISTENT_PUBLIC,
+  TUNNEL_MODE_MANAGED_LOCAL,
+  TUNNEL_MODE_MANAGED_REMOTE,
+  TUNNEL_MODE_QUICK,
+  TUNNEL_PROVIDER_CLOUDFLARE,
+  TunnelServiceError,
+} from '../types.js';
+
+export const cloudflareTunnelProviderCapabilities = {
+  provider: TUNNEL_PROVIDER_CLOUDFLARE,
+  defaults: {
+    mode: TUNNEL_MODE_QUICK,
+    optionDefaults: {},
+  },
+  modes: [
+    {
+      key: TUNNEL_MODE_QUICK,
+      label: 'Quick Tunnel',
+      intent: TUNNEL_INTENT_EPHEMERAL_PUBLIC,
+      requires: [],
+      supports: ['sessionTTL'],
+      stability: 'ga',
+    },
+    {
+      key: TUNNEL_MODE_MANAGED_REMOTE,
+      label: 'Managed Remote Tunnel',
+      intent: TUNNEL_INTENT_PERSISTENT_PUBLIC,
+      requires: ['token', 'hostname'],
+      supports: ['customDomain', 'sessionTTL'],
+      stability: 'ga',
+    },
+    {
+      key: TUNNEL_MODE_MANAGED_LOCAL,
+      label: 'Managed Local Tunnel',
+      intent: TUNNEL_INTENT_PERSISTENT_PUBLIC,
+      requires: [],
+      supports: ['configFile', 'customDomain', 'sessionTTL'],
+      stability: 'ga',
+    },
+  ],
+};
+
+export function createCloudflareTunnelProvider() {
+  const validateTokenShape = (value) => {
+    if (typeof value !== 'string') {
+      return { ok: false, detail: 'Managed remote token is missing.' };
+    }
+    const trimmed = value.trim();
+    if (!trimmed) {
+      return { ok: false, detail: 'Managed remote token is missing.' };
+    }
+    if (/\s/.test(trimmed)) {
+      return { ok: false, detail: 'Managed remote token has whitespace; provide the raw token value.' };
+    }
+    return { ok: true, detail: 'Managed remote token looks valid.' };
+  };
+
+  const createModeSummary = (checks) => {
+    const failures = checks.filter((entry) => entry.status === 'fail').length;
+    const warnings = checks.filter((entry) => entry.status === 'warn').length;
+    return {
+      ready: failures === 0,
+      failures,
+      warnings,
+    };
+  };
+
+  const describeMode = ({ mode, checks }) => {
+    const summary = createModeSummary(checks);
+    const blockers = checks
+      .filter((entry) => entry.status === 'fail' && entry.id !== 'startup_readiness')
+      .map((entry) => entry.detail || entry.label || entry.id);
+    return {
+      mode,
+      checks,
+      summary,
+      ready: summary.ready,
+      blockers,
+    };
+  };
+
+  return {
+    id: TUNNEL_PROVIDER_CLOUDFLARE,
+    capabilities: cloudflareTunnelProviderCapabilities,
+    checkAvailability: async () => {
+      const result = await checkCloudflaredAvailable();
+      if (result.available) {
+        return result;
+      }
+      return {
+        ...result,
+        message: 'cloudflared is not installed. Install it with: brew install cloudflared',
+      };
+    },
+    diagnose: async (request = {}) => {
+      const dependency = await checkCloudflaredAvailable();
+      const network = await checkCloudflareApiReachability();
+
+      const providerChecks = [
+        {
+          id: 'dependency',
+          label: 'cloudflared installed',
+          status: dependency.available ? 'pass' : 'fail',
+          detail: dependency.available
+            ? (dependency.version || dependency.path || 'cloudflared available')
+            : 'cloudflared is not installed. Install it with: brew install cloudflared',
+        },
+        {
+          id: 'network',
+          label: 'Cloudflare API reachable',
+          status: network.reachable ? 'pass' : 'fail',
+          detail: network.reachable
+            ? (network.status ? `HTTP ${network.status}` : 'Reachable')
+            : (network.error || 'Could not reach api.trycloudflare.com'),
+        },
+      ];
+
+      const startupReady = dependency.available && network.reachable;
+      const startupDetail = startupReady
+        ? 'Provider dependency and network checks passed.'
+        : 'Resolve provider checks before starting tunnels.';
+
+      const quickChecks = [
+        {
+          id: 'startup_readiness',
+          label: 'Provider startup readiness',
+          status: startupReady ? 'pass' : 'fail',
+          detail: startupDetail,
+        },
+        {
+          id: 'quick_mode_prerequisites',
+          label: 'Quick tunnel prerequisites',
+          status: network.reachable ? 'pass' : 'fail',
+          detail: network.reachable
+            ? 'Cloudflare edge is reachable for quick tunnels.'
+            : 'Cloudflare edge is not reachable for quick tunnels.',
+        },
+      ];
+
+      const managedLocalInspection = inspectManagedLocalCloudflareConfig({
+        configPath: request.configPath,
+        hostname: request.hostname,
+      });
+      const managedLocalChecks = [
+        {
+          id: 'startup_readiness',
+          label: 'Provider startup readiness',
+          status: startupReady ? 'pass' : 'fail',
+          detail: startupDetail,
+        },
+        {
+          id: 'managed_local_config',
+          label: 'Managed local config',
+          status: managedLocalInspection.ok ? 'pass' : 'fail',
+          detail: managedLocalInspection.ok
+            ? `${managedLocalInspection.effectiveConfigPath}${managedLocalInspection.resolvedHostname ? ` (${managedLocalInspection.resolvedHostname})` : ''}`
+            : managedLocalInspection.error,
+        },
+      ];
+
+      const normalizedHost = normalizeCloudflareTunnelHostname(request.hostname);
+      const hostnameMissing = !normalizedHost;
+      const remoteTokenValidation = validateTokenShape(request.token);
+      const tokenMissing = typeof request.token !== 'string' || request.token.trim().length === 0;
+      const hasSavedManagedRemoteProfile = request.hasSavedManagedRemoteProfile === true;
+      const tokenProvided = request.tokenProvided === true;
+      const hostnameProvided = request.hostnameProvided === true;
+      const hasExplicitManagedRemoteInput = tokenProvided || hostnameProvided;
+      const canUseSavedProfileForHostname = !hasExplicitManagedRemoteInput && hostnameMissing && hasSavedManagedRemoteProfile;
+      const canUseSavedProfileForToken = !hasExplicitManagedRemoteInput && tokenMissing && hasSavedManagedRemoteProfile;
+      const savedProfileReadyDetail = 'at least one saved profile present';
+      const managedRemoteChecks = [
+        {
+          id: 'startup_readiness',
+          label: 'Provider startup readiness',
+          status: startupReady ? 'pass' : 'fail',
+          detail: startupDetail,
+        },
+        {
+          id: 'managed_remote_hostname',
+          label: 'Managed remote hostname',
+          status: normalizedHost || canUseSavedProfileForHostname ? 'pass' : 'fail',
+          detail: normalizedHost
+            ? normalizedHost
+            : canUseSavedProfileForHostname
+              ? savedProfileReadyDetail
+              : 'Managed remote hostname is required (use --hostname).',
+        },
+        {
+          id: 'managed_remote_token',
+          label: 'Managed remote token',
+          status: remoteTokenValidation.ok || canUseSavedProfileForToken ? 'pass' : 'fail',
+          detail: canUseSavedProfileForToken
+            ? savedProfileReadyDetail
+            : remoteTokenValidation.detail,
+        },
+      ];
+
+      const allModes = [
+        describeMode({ mode: TUNNEL_MODE_QUICK, checks: quickChecks }),
+        describeMode({ mode: TUNNEL_MODE_MANAGED_REMOTE, checks: managedRemoteChecks }),
+        describeMode({ mode: TUNNEL_MODE_MANAGED_LOCAL, checks: managedLocalChecks }),
+      ];
+
+      const modeFilter = typeof request.mode === 'string' && request.mode.trim().length > 0
+        ? request.mode.trim().toLowerCase()
+        : null;
+      const modes = modeFilter ? allModes.filter((entry) => entry.mode === modeFilter) : allModes;
+
+      return {
+        providerChecks,
+        modes,
+      };
+    },
+    start: async (request, context = {}) => {
+      if (request.mode === TUNNEL_MODE_MANAGED_REMOTE) {
+        return startCloudflareManagedRemoteTunnel({
+          token: request.token,
+          hostname: request.hostname,
+        });
+      }
+
+      if (request.mode === TUNNEL_MODE_MANAGED_LOCAL) {
+        return startCloudflareManagedLocalTunnel({
+          configPath: request.configPath,
+          hostname: request.hostname,
+        });
+      }
+
+      if (!context.originUrl) {
+        throw new TunnelServiceError('validation_error', 'originUrl is required for quick tunnel mode');
+      }
+
+      return startCloudflareQuickTunnel({
+        originUrl: context.originUrl,
+        port: context.activePort,
+      });
+    },
+    stop: (controller) => {
+      controller?.stop?.();
+    },
+    resolvePublicUrl: (controller) => controller?.getPublicUrl?.() ?? null,
+    getMetadata: (controller) => ({
+      configPath: controller?.getEffectiveConfigPath?.() ?? null,
+      resolvedHostname: controller?.getResolvedHostname?.() ?? null,
+    }),
+  };
+}

package/server/lib/tunnels/registry.js

@@ -0,0 +1,51 @@
+const REQUIRED_PROVIDER_METHODS = ['start', 'stop', 'checkAvailability', 'resolvePublicUrl'];
+
+export function createTunnelProviderRegistry(initialProviders = []) {
+  const providers = new Map();
+  let sealed = false;
+
+  const register = (provider) => {
+    if (sealed) {
+      throw new Error('Tunnel provider registry is sealed; no further registrations allowed');
+    }
+    if (!provider || typeof provider.id !== 'string' || provider.id.trim().length === 0) {
+      throw new Error('Tunnel provider must define a non-empty id');
+    }
+    for (const method of REQUIRED_PROVIDER_METHODS) {
+      if (typeof provider[method] !== 'function') {
+        throw new Error(`Tunnel provider '${provider.id}' must implement ${method}()`);
+      }
+    }
+    const key = provider.id.trim().toLowerCase();
+    if (providers.has(key)) {
+      throw new Error(`Tunnel provider '${key}' is already registered`);
+    }
+    providers.set(key, provider);
+    return provider;
+  };
+
+  const get = (providerId) => {
+    if (typeof providerId !== 'string' || providerId.trim().length === 0) {
+      return null;
+    }
+    return providers.get(providerId.trim().toLowerCase()) ?? null;
+  };
+
+  const list = () => Array.from(providers.values());
+
+  const listCapabilities = () => list().map((provider) => ({ ...provider.capabilities }));
+
+  for (const provider of initialProviders) {
+    register(provider);
+  }
+
+  const seal = () => { sealed = true; };
+
+  return {
+    register,
+    get,
+    list,
+    listCapabilities,
+    seal,
+  };
+}