@qpjoy/electron-launcher 0.2.0

package/README.md

@@ -0,0 +1,164 @@
+# @qpjoy/electron-launcher
+
+Product-facing npm entry for MX Launcher.
+
+Applications install this package directly and point it at an MX Launcher
+backend. The package hides the internal split between core, embed, and
+standalone adapters.
+
+For production SDK delivery, MX Launcher also supports role-specific packages:
+
+| Package | Use when |
+| --- | --- |
+| `@qpjoy/mx-launcher-core` | sharing protocol, manifest, capability, release, and ABI contracts |
+| `@qpjoy/mx-launcher-standalone` | building a capability owner such as MX-H2I or Luopan |
+| `@qpjoy/mx-launcher-embed-sdk` | building an embed app such as AppCenter, H2O, or an AppCenter-managed app |
+| `@qpjoy/electron-launcher` | using the unified Electron facade or existing compatibility exports |
+
+Both delivery styles are supported. The role-specific split is preferred for
+external teams because it keeps owner-only APIs out of embed apps. The unified
+Electron package remains useful for monorepo demos, legacy products, and apps
+that want a single import surface. Packages with the same major version must be
+protocol-compatible; breaking protocol or broker ABI changes require a new
+major version.
+
+See the package design notes in `../README.md`, `../launcher-core/README.md`,
+`../launcher-standalone/README.md`, and `../launcher-embed-sdk/README.md`.
+
+```ts
+import { createElectronLauncher, defineLauncherProduct } from '@qpjoy/electron-launcher';
+
+export const product = defineLauncherProduct({
+  productId: 'h2o',
+  displayName: 'H2O',
+  mode: 'embed',
+  standaloneChannelProductId: 'mx-h2i',
+  launcherActions: {
+    network: true,
+    release: true,
+    update: true,
+    rollout: true,
+    appCenter: true
+  }
+});
+
+const launcher = createElectronLauncher({
+  baseUrl: 'http://127.0.0.1:18090',
+  productId: product.productId,
+  mode: product.mode,
+  standaloneChannelProductId: product.standaloneChannelProductId,
+  requiredCapabilities: ['user.session', 'network.proxy', 'network.status']
+});
+
+const connection = launcher.mode === 'embed'
+  ? await launcher.connect()
+  : null;
+
+if (connection && !connection.ok) {
+  console.warn(connection.state, connection.message);
+}
+```
+
+`standalone` mode is for the full Launcher shell. `embed` mode is for product
+apps hosted by a standalone broker session. Embed apps do not allocate their own
+WireGuard peer lease or apply DNS/route state; call `launcher.connect()` and
+request scoped capabilities from the selected standalone channel.
+
+## Runtime adapters
+
+The package exposes optional runtime adapters as separate subpaths so products
+can depend only on the capabilities they own:
+
+| Subpath | Purpose |
+| --- | --- |
+| `@qpjoy/electron-launcher` | launcher client, product definition, standalone/embed SDK facade |
+| `@qpjoy/electron-launcher/wireguard` | WireGuard profile rendering, route proof, and peer recovery |
+| `@qpjoy/electron-launcher/system-domain-proxy` | standalone local PAC/proxy edge plus OS PAC apply/restore/verify |
+| `@qpjoy/electron-launcher/standalone-data-plane` | read-only standalone lease/data-plane route diagnostics |
+
+For standalone products, keep the state model split into two phases:
+
+1. `connectNetwork()` proves the control plane accepted the app and issued a
+   lease.
+2. WireGuard/PAC/DNS apply and route proof prove the local data plane is ready.
+
+Products should not display `connected` only because a lease exists. Use the
+read-only data-plane diagnostic before claiming traffic is ready:
+
+```ts
+import {
+  applyElectronLauncherStandaloneDataPlane,
+  diagnoseElectronLauncherStandaloneDataPlane
+} from '@qpjoy/electron-launcher/standalone-data-plane';
+
+const dataPlane = diagnoseElectronLauncherStandaloneDataPlane({
+  routePlan: session.routePlan,
+  leaseIp: session.lease.leaseIp,
+  serviceVip: session.lease.serviceVip
+});
+
+if (!dataPlane.ok) {
+  console.warn(dataPlane.state, dataPlane.message);
+}
+
+const applied = await applyElectronLauncherStandaloneDataPlane({
+  userDataDir: app.getPath('userData'),
+  profileName: `${product.productId}.conf`,
+  routePlan: session.routePlan,
+  privateKey: session.wireGuard.privateKey,
+  dnsDomains: ['mxinfo-inc.cn'],
+  ownerId: `${product.productId}:${installId}`,
+  productId: product.productId,
+  instanceId: installId,
+  dnsHosts: ['luopan.mxinfo-inc.cn'],
+  dnsZones: ['mxinfo-inc.cn'],
+  failOnOwnershipConflicts: true
+});
+```
+
+Inside the `electron-dock/mx-launcher` monorepo, demos depend on this package
+with `workspace:*`, so local package changes are used by MX-H2I, Luopan, and
+future launcher demos during development. Release builds should consume a
+published semver version from npm, matching the V1 HDO local-vs-published
+workflow.
+
+System PAC is intended for Launcher standalone owners. For MX-H2I the local edge
+listens on `127.0.0.1:2053` by default and serves both `/proxy.pac` and an
+HTTP/CONNECT proxy on TCP, plus a UDP DNS relay on the same port. Internal
+domains are resolved with the Internal IP from the route plan, `10.88.88.88` by
+default, through the WireGuard AllowedIPs path. The Domestic gateway
+`10.88.0.1` is only a fallback relay/cache target; all other domains fall back
+to the previous system proxy when one is detected or provided. If another
+standalone launcher already owns the same local edge port, a later instance
+reuses it.
+
+On macOS, local PAC alone only covers proxy-aware traffic such as browsers. When
+`systemResolver: 'dynamic'` is enabled, the package installs a runtime
+SystemConfiguration supplemental DNS entry for matched domains and points it at
+`127.0.0.1:<pacPort>`, so `ping`, CLI tools, and non-PAC applications resolve
+the same Internal names without writing `/etc/hosts` or `/etc/resolver`. A file
+resolver mode remains available as an explicit fallback and only manages files
+with the `MX_ELECTRON_LAUNCHER_RESOLVER` marker.
+
+```ts
+import { createElectronLauncherSystemDomainProxy } from '@qpjoy/electron-launcher/system-domain-proxy';
+
+const systemDomainProxy = createElectronLauncherSystemDomainProxy({
+  userDataDir: app.getPath('userData'),
+  pacPort: 2053
+});
+
+await systemDomainProxy.apply({
+  enabled: true,
+  domains: ['internal.mx', 'svc.cluster.local'],
+  matchMode: 'proxy',
+  proxy: '127.0.0.1:2053',
+  pacPort: 2053,
+  systemResolver: 'dynamic',
+  dnsServers: ['10.88.88.88', '10.88.0.1'],
+  fallbackProxy: '127.0.0.1:7890'
+});
+
+// Later, when the launcher channel disconnects:
+await systemDomainProxy.disable('disconnect');
+```

package/dist/index.d.ts

@@ -0,0 +1,79 @@
+import { assertCompatibleBroker, brokerAbiVersion, createLauncherEmbedManifest, createLauncherClient, createLauncherNetworkSession, createLauncherWireGuardKeyPair, launcherBrokerCompatibility, launcherEmbedRuntimeContractVersion, launcherNetworkScopeForMode, launcherProtocolVersion, networkDigest, networkRefreshKey, normalizeLauncherBaseUrl, routePlanFromSnapshot, shouldRefreshNetwork, type FetchLike, type LauncherBrokerCapabilitySession, type LauncherBrokerHandshakeDeniedReason, type LauncherBrokerHandshakeRequest, type LauncherBrokerHandshakeResult, type LauncherCapability, type LauncherChannelRecord, type LauncherClient, type LauncherClientOptions, type LauncherEmbedConnectionState, type LauncherEmbedBrokerRequestName, type LauncherEmbedManifestInput, type LauncherEmbedRuntimeEventName, type LauncherIdentityKind, type LauncherManifest, type LauncherNetworkLease, type LauncherNetworkLeaseInput, type LauncherNetworkScope, type LauncherNetworkSession, type LauncherNetworkSessionInput, type LauncherNetworkSnapshot, type LauncherNetworkSnapshotInput, type LauncherProductMode, type LauncherProductNetwork, type LauncherProductNetworkInput, type LauncherProductUpdatePolicy, type LauncherRoutePlan, type LauncherWireGuardKeyMaterial, type LauncherWireGuardKeyPair, type LauncherWireGuardKeyProvider } from '@qpjoy/mx-launcher-core';
+import { createEmbedLauncher, type EmbedConnectOptions, type EmbedConnectionResult, type EmbedBrokerConnectOptions, type EmbedBrokerRequestHandler, type EmbedLauncherConnection, type EmbedLauncherEventHandler, type EmbedLauncherEventName, type EmbedLauncher, type EmbedLauncherOptions, type EmbedLegacyNetworkApi, type LauncherChannelRegistrySource, type EmbedSnapshotOptions } from '@qpjoy/mx-launcher-embed-sdk';
+import { createStandaloneLauncher, type StandaloneLeaseOptions, type StandaloneNetworkSessionOptions, type StandaloneConnectOptions, type StandaloneConnectionResult, type StandaloneLauncher, type StandaloneLauncherOptions, type StandaloneSnapshotOptions, type StandaloneUserConnectOptions } from '@qpjoy/mx-launcher-standalone';
+export { createElectronLauncherSystemDomainProxy, renderElectronLauncherPacScript, type ElectronLauncherPacProxy, type ElectronLauncherPacMatchMode, type ElectronLauncherSystemDomainProxyManager, type ElectronLauncherSystemDomainProxyOptions, type ElectronLauncherSystemDomainProxyPolicy, type ElectronLauncherSystemDomainProxyRoute, type ElectronLauncherSystemDomainProxyStatus } from './system-domain-proxy.js';
+export { classifyLauncherIpv4Address, diagnoseLauncherHostResolution, type ElectronLauncherAddressDiagnostic, type ElectronLauncherHostResolutionDiagnostics, type ElectronLauncherHostResolutionDiagnosticInput, type ElectronLauncherHostResolutionSeverity, type ElectronLauncherHostResolutionState, type ElectronLauncherIpClassification, type ElectronLauncherNetworkPhase } from './network-diagnostics.js';
+export { buildElectronLauncherNetworkOwnershipRegistry, mergedElectronLauncherDnsZones, mergedElectronLauncherReverseProxyRoutes, resolveElectronLauncherDnsOwner, type ElectronLauncherNetworkOwner, type ElectronLauncherNetworkOwnerState, type ElectronLauncherNetworkOwnershipClaim, type ElectronLauncherNetworkOwnershipConflict, type ElectronLauncherNetworkOwnershipEntry, type ElectronLauncherNetworkOwnershipRegistry, type ElectronLauncherNetworkOwnershipResource, type ElectronLauncherNetworkOwnershipRoute } from './network-ownership-registry.js';
+export { applyElectronLauncherStandaloneDataPlane, buildElectronLauncherStandaloneOwnershipClaim, diagnoseElectronLauncherStandaloneDataPlane, readElectronLauncherStandaloneOwnershipState, releaseElectronLauncherStandaloneOwnershipClaim, stopElectronLauncherStandaloneDataPlane, upsertElectronLauncherStandaloneOwnershipClaim, type ElectronLauncherStandaloneDataPlaneApplyInput, type ElectronLauncherStandaloneDataPlaneApplyResult, type ElectronLauncherStandaloneDataPlaneDiagnostics, type ElectronLauncherStandaloneDataPlaneInput, type ElectronLauncherStandaloneDataPlaneProbeTarget, type ElectronLauncherStandaloneDataPlaneSeverity, type ElectronLauncherStandaloneDataPlaneStopInput, type ElectronLauncherStandaloneDataPlaneStopResult, type ElectronLauncherStandaloneDataPlaneState, type ElectronLauncherStandaloneEndpointProbe, type ElectronLauncherStandaloneOwnershipInput, type ElectronLauncherStandaloneOwnershipState, type ElectronLauncherStandaloneRouteProbe } from './standalone-data-plane.js';
+export { createElectronLauncherReleaseUpdater, downloadElectronLauncherReleaseArtifactToFile, type ElectronLauncherArtifactDownloadInput, type ElectronLauncherArtifactDownloadResult, type ElectronLauncherReleaseActivationMode, type ElectronLauncherReleaseArtifactRef, type ElectronLauncherReleasePlan, type ElectronLauncherReleasePolicyDecision, type ElectronLauncherReleaseReportInput, type ElectronLauncherReleaseUpdateMode, type ElectronLauncherReleaseUpdater, type ElectronLauncherReleaseUpdaterOptions, type ElectronLauncherUpdateCheckInput, type ElectronLauncherUpdateCheckResult } from './release-updater.js';
+export declare const ELECTRON_LAUNCHER_PACKAGE_NAME = "@qpjoy/electron-launcher";
+export type ElectronLauncherMode = LauncherProductMode;
+export interface ElectronLauncherOptions extends LauncherClientOptions {
+    productId?: string;
+    appId?: string;
+    mode?: ElectronLauncherMode;
+    standaloneChannelProductId?: string;
+    requiredCapabilities?: LauncherCapability[];
+    sdkVersion?: string;
+    appVersion?: string;
+    displayName?: string;
+    description?: string;
+    packageName?: string;
+    category?: string;
+    runtimeContractVersion?: string;
+    channelRegistry?: LauncherChannelRegistrySource;
+    requestImpl?: EmbedBrokerRequestHandler;
+    installId?: string;
+    deviceId?: string;
+    siteId?: string;
+    publicKey?: string;
+    privateKey?: string;
+    keyPair?: LauncherWireGuardKeyPair;
+    keyProvider?: LauncherWireGuardKeyProvider;
+    deviceLabel?: string;
+}
+export type ElectronLauncher = EmbedLauncher | StandaloneLauncher;
+export interface LauncherProductActions {
+    network: boolean;
+    release: boolean;
+    update: boolean;
+    rollout: boolean;
+    appCenter: boolean;
+}
+export interface LauncherProductDefinition {
+    productId: string;
+    displayName: string;
+    mode: ElectronLauncherMode;
+    networkScope: LauncherNetworkScope;
+    standaloneChannelProductId: string;
+    appCenter: {
+        visible: boolean;
+        category: string;
+    };
+    release: {
+        componentId: string;
+        channel: string;
+        rolloutGroup: string | null;
+    };
+    launcherActions: LauncherProductActions;
+}
+export interface LauncherProductDefinitionInput {
+    productId: string;
+    displayName?: string;
+    mode?: ElectronLauncherMode;
+    standaloneChannelProductId?: string;
+    appCenter?: {
+        visible?: boolean;
+        category?: string;
+    };
+    release?: {
+        componentId?: string;
+        channel?: string;
+        rolloutGroup?: string | null;
+    };
+    launcherActions?: Partial<LauncherProductActions>;
+}
+export declare function createElectronLauncher(options: ElectronLauncherOptions): ElectronLauncher;
+export declare function defineLauncherProduct(input: LauncherProductDefinitionInput): LauncherProductDefinition;
+export { assertCompatibleBroker, brokerAbiVersion, createEmbedLauncher, createLauncherClient, createLauncherEmbedManifest, createLauncherNetworkSession, createLauncherWireGuardKeyPair, createStandaloneLauncher, launcherBrokerCompatibility, launcherEmbedRuntimeContractVersion, launcherNetworkScopeForMode, launcherProtocolVersion, networkDigest, networkRefreshKey, normalizeLauncherBaseUrl, routePlanFromSnapshot, shouldRefreshNetwork };
+export type { EmbedBrokerConnectOptions, EmbedBrokerRequestHandler, EmbedConnectOptions, EmbedConnectionResult, EmbedLauncherConnection, EmbedLauncherEventHandler, EmbedLauncherEventName, EmbedLauncher, EmbedLauncherOptions, EmbedLegacyNetworkApi, EmbedSnapshotOptions, FetchLike, LauncherBrokerCapabilitySession, LauncherBrokerHandshakeDeniedReason, LauncherBrokerHandshakeRequest, LauncherBrokerHandshakeResult, LauncherCapability, LauncherChannelRegistrySource, LauncherChannelRecord, LauncherClient, LauncherClientOptions, LauncherEmbedConnectionState, LauncherEmbedBrokerRequestName, LauncherEmbedManifestInput, LauncherEmbedRuntimeEventName, LauncherIdentityKind, LauncherManifest, LauncherNetworkLease, LauncherNetworkLeaseInput, LauncherNetworkScope, LauncherNetworkSession, LauncherNetworkSessionInput, LauncherNetworkSnapshot, LauncherNetworkSnapshotInput, LauncherProductMode, LauncherProductNetwork, LauncherProductNetworkInput, LauncherProductUpdatePolicy, LauncherRoutePlan, LauncherWireGuardKeyMaterial, LauncherWireGuardKeyPair, LauncherWireGuardKeyProvider, StandaloneConnectOptions, StandaloneConnectionResult, StandaloneLeaseOptions, StandaloneNetworkSessionOptions, StandaloneLauncher, StandaloneLauncherOptions, StandaloneSnapshotOptions, StandaloneUserConnectOptions };

package/dist/index.js

@@ -0,0 +1,62 @@
+import { assertCompatibleBroker, brokerAbiVersion, createLauncherEmbedManifest, createLauncherClient, createLauncherNetworkSession, createLauncherWireGuardKeyPair, launcherBrokerCompatibility, launcherEmbedRuntimeContractVersion, launcherNetworkScopeForMode, launcherProtocolVersion, networkDigest, networkRefreshKey, normalizeLauncherBaseUrl, routePlanFromSnapshot, shouldRefreshNetwork } from '@qpjoy/mx-launcher-core';
+import { createEmbedLauncher } from '@qpjoy/mx-launcher-embed-sdk';
+import { createStandaloneLauncher } from '@qpjoy/mx-launcher-standalone';
+export { createElectronLauncherSystemDomainProxy, renderElectronLauncherPacScript } from './system-domain-proxy.js';
+export { classifyLauncherIpv4Address, diagnoseLauncherHostResolution } from './network-diagnostics.js';
+export { buildElectronLauncherNetworkOwnershipRegistry, mergedElectronLauncherDnsZones, mergedElectronLauncherReverseProxyRoutes, resolveElectronLauncherDnsOwner } from './network-ownership-registry.js';
+export { applyElectronLauncherStandaloneDataPlane, buildElectronLauncherStandaloneOwnershipClaim, diagnoseElectronLauncherStandaloneDataPlane, readElectronLauncherStandaloneOwnershipState, releaseElectronLauncherStandaloneOwnershipClaim, stopElectronLauncherStandaloneDataPlane, upsertElectronLauncherStandaloneOwnershipClaim } from './standalone-data-plane.js';
+export { createElectronLauncherReleaseUpdater, downloadElectronLauncherReleaseArtifactToFile } from './release-updater.js';
+export const ELECTRON_LAUNCHER_PACKAGE_NAME = '@qpjoy/electron-launcher';
+export function createElectronLauncher(options) {
+    const mode = options.mode ?? 'embed';
+    if (mode === 'standalone') {
+        return createStandaloneLauncher({
+            ...options,
+            productId: options.productId ?? 'launcher'
+        });
+    }
+    return createEmbedLauncher({
+        ...options,
+        productId: requiredProductId(options.productId ?? options.appId),
+        appId: options.appId ?? options.productId
+    });
+}
+export function defineLauncherProduct(input) {
+    const productId = requiredProductId(input.productId);
+    const displayName = input.displayName?.trim() || productId;
+    const mode = input.mode ?? 'embed';
+    const standaloneChannelProductId = mode === 'standalone'
+        ? productId
+        : input.standaloneChannelProductId?.trim() || 'mx-h2i';
+    const actions = input.launcherActions ?? {};
+    return {
+        productId,
+        displayName,
+        mode,
+        networkScope: launcherNetworkScopeForMode(mode),
+        standaloneChannelProductId,
+        appCenter: {
+            visible: input.appCenter?.visible ?? true,
+            category: input.appCenter?.category?.trim() || 'app'
+        },
+        release: {
+            componentId: input.release?.componentId?.trim() || productId,
+            channel: input.release?.channel?.trim() || 'stable',
+            rolloutGroup: input.release?.rolloutGroup ?? null
+        },
+        launcherActions: {
+            network: actions.network ?? true,
+            release: actions.release ?? true,
+            update: actions.update ?? true,
+            rollout: actions.rollout ?? true,
+            appCenter: actions.appCenter ?? true
+        }
+    };
+}
+function requiredProductId(productId) {
+    const trimmed = productId?.trim();
+    if (!trimmed)
+        throw new Error('Electron Launcher productId is required for embed mode');
+    return trimmed;
+}
+export { assertCompatibleBroker, brokerAbiVersion, createEmbedLauncher, createLauncherClient, createLauncherEmbedManifest, createLauncherNetworkSession, createLauncherWireGuardKeyPair, createStandaloneLauncher, launcherBrokerCompatibility, launcherEmbedRuntimeContractVersion, launcherNetworkScopeForMode, launcherProtocolVersion, networkDigest, networkRefreshKey, normalizeLauncherBaseUrl, routePlanFromSnapshot, shouldRefreshNetwork };

package/dist/network-diagnostics.d.ts

@@ -0,0 +1,42 @@
+export type ElectronLauncherNetworkPhase = 'bootstrap' | 'connected' | 'disconnected' | 'unknown';
+export type ElectronLauncherIpClassification = 'expected-internal-target' | 'internal-overlay' | 'v1-hdo-overlay' | 'proxy-fake-ip' | 'loopback' | 'private' | 'public' | 'invalid';
+export type ElectronLauncherHostResolutionState = 'expected-internal' | 'internal-overlay' | 'v1-hdo-overlay' | 'proxy-fake-ip' | 'public' | 'private' | 'loopback' | 'unresolved' | 'invalid-host';
+export type ElectronLauncherHostResolutionSeverity = 'ok' | 'info' | 'warning' | 'error';
+export interface ElectronLauncherAddressDiagnostic {
+    address: string;
+    classification: ElectronLauncherIpClassification;
+}
+export interface ElectronLauncherHostResolutionDiagnostics {
+    host: string | null;
+    phase: ElectronLauncherNetworkPhase;
+    addresses: ElectronLauncherAddressDiagnostic[];
+    state: ElectronLauncherHostResolutionState;
+    severity: ElectronLauncherHostResolutionSeverity;
+    ok: boolean;
+    message: string;
+    expectedInternalTargets: string[];
+    internalCidrs: string[];
+    v1HdoCidrs: string[];
+    proxyFakeIpCidrs: string[];
+    error?: string | null;
+    updatedAt: string;
+}
+export interface ElectronLauncherHostResolutionDiagnosticInput {
+    host?: string | null;
+    phase?: ElectronLauncherNetworkPhase | null;
+    expectedInternalTargets?: Array<string | null | undefined> | null;
+    internalCidrs?: Array<string | null | undefined> | null;
+    v1HdoCidrs?: Array<string | null | undefined> | null;
+    proxyFakeIpCidrs?: Array<string | null | undefined> | null;
+    lookup?: ((host: string) => Promise<Array<string | {
+        address?: string | null;
+        family?: number | null;
+    }>>) | null;
+}
+export declare function diagnoseLauncherHostResolution(input: ElectronLauncherHostResolutionDiagnosticInput): Promise<ElectronLauncherHostResolutionDiagnostics>;
+export declare function classifyLauncherIpv4Address(address: string, options?: {
+    expectedInternalTargets?: Array<string | null | undefined> | null;
+    internalCidrs?: Array<string | null | undefined> | null;
+    v1HdoCidrs?: Array<string | null | undefined> | null;
+    proxyFakeIpCidrs?: Array<string | null | undefined> | null;
+}): ElectronLauncherIpClassification;

package/dist/network-diagnostics.js

@@ -0,0 +1,254 @@
+import { lookup as dnsLookup } from 'node:dns/promises';
+import { isIP } from 'node:net';
+const DEFAULT_INTERNAL_CIDRS = ['10.88.0.0/13'];
+const DEFAULT_V1_HDO_CIDRS = ['100.88.0.0/16', '100.89.0.0/16', '100.90.0.0/16', '100.91.0.0/16'];
+const DEFAULT_PROXY_FAKE_IP_CIDRS = ['198.18.0.0/15'];
+const PRIVATE_CIDRS = [
+    '10.0.0.0/8',
+    '172.16.0.0/12',
+    '192.168.0.0/16',
+    '100.64.0.0/10',
+    '169.254.0.0/16'
+];
+const LOOPBACK_CIDRS = ['127.0.0.0/8'];
+export async function diagnoseLauncherHostResolution(input) {
+    const host = normalizeHost(input.host);
+    const phase = normalizePhase(input.phase);
+    const expectedInternalTargets = normalizeIpv4List(input.expectedInternalTargets);
+    const internalCidrs = normalizeCidrList(input.internalCidrs, DEFAULT_INTERNAL_CIDRS);
+    const v1HdoCidrs = normalizeCidrList(input.v1HdoCidrs, DEFAULT_V1_HDO_CIDRS);
+    const proxyFakeIpCidrs = normalizeCidrList(input.proxyFakeIpCidrs, DEFAULT_PROXY_FAKE_IP_CIDRS);
+    if (!host) {
+        return resolutionResult({
+            host: null,
+            phase,
+            addresses: [],
+            state: 'invalid-host',
+            expectedInternalTargets,
+            internalCidrs,
+            v1HdoCidrs,
+            proxyFakeIpCidrs,
+            error: 'host is empty'
+        });
+    }
+    try {
+        const records = isIP(host) === 4
+            ? [host]
+            : await resolveHostAddresses(host, input.lookup);
+        const addresses = uniqueStrings(records)
+            .filter((address) => isIP(address) === 4)
+            .map((address) => ({
+            address,
+            classification: classifyLauncherIpv4Address(address, {
+                expectedInternalTargets,
+                internalCidrs,
+                v1HdoCidrs,
+                proxyFakeIpCidrs
+            })
+        }));
+        return resolutionResult({
+            host,
+            phase,
+            addresses,
+            state: resolutionState(addresses),
+            expectedInternalTargets,
+            internalCidrs,
+            v1HdoCidrs,
+            proxyFakeIpCidrs
+        });
+    }
+    catch (err) {
+        return resolutionResult({
+            host,
+            phase,
+            addresses: [],
+            state: 'unresolved',
+            expectedInternalTargets,
+            internalCidrs,
+            v1HdoCidrs,
+            proxyFakeIpCidrs,
+            error: errorMessage(err)
+        });
+    }
+}
+export function classifyLauncherIpv4Address(address, options = {}) {
+    if (isIP(address) !== 4)
+        return 'invalid';
+    const expectedInternalTargets = normalizeIpv4List(options.expectedInternalTargets);
+    const internalCidrs = normalizeCidrList(options.internalCidrs, DEFAULT_INTERNAL_CIDRS);
+    const v1HdoCidrs = normalizeCidrList(options.v1HdoCidrs, DEFAULT_V1_HDO_CIDRS);
+    const proxyFakeIpCidrs = normalizeCidrList(options.proxyFakeIpCidrs, DEFAULT_PROXY_FAKE_IP_CIDRS);
+    if (expectedInternalTargets.includes(address))
+        return 'expected-internal-target';
+    if (cidrsContainIp(proxyFakeIpCidrs, address))
+        return 'proxy-fake-ip';
+    if (cidrsContainIp(LOOPBACK_CIDRS, address))
+        return 'loopback';
+    if (cidrsContainIp(v1HdoCidrs, address))
+        return 'v1-hdo-overlay';
+    if (cidrsContainIp(internalCidrs, address))
+        return 'internal-overlay';
+    if (cidrsContainIp(PRIVATE_CIDRS, address))
+        return 'private';
+    return 'public';
+}
+function resolutionResult(input) {
+    const { severity, ok, message } = evaluateResolution(input);
+    return {
+        host: input.host,
+        phase: input.phase,
+        addresses: input.addresses,
+        state: input.state,
+        severity,
+        ok,
+        message,
+        expectedInternalTargets: input.expectedInternalTargets,
+        internalCidrs: input.internalCidrs,
+        v1HdoCidrs: input.v1HdoCidrs,
+        proxyFakeIpCidrs: input.proxyFakeIpCidrs,
+        error: input.error ?? null,
+        updatedAt: new Date().toISOString()
+    };
+}
+function evaluateResolution(input) {
+    const host = input.host || 'host';
+    if (input.state === 'invalid-host') {
+        return { severity: 'warning', ok: false, message: '未配置可诊断的 bootstrap 域名。' };
+    }
+    if (input.state === 'unresolved') {
+        const suffix = input.error ? `：${input.error}` : '。';
+        if (input.phase === 'connected') {
+            return { severity: 'error', ok: false, message: `${host} 在 V2 connected 状态下未解析${suffix}` };
+        }
+        return { severity: 'warning', ok: false, message: `${host} 当前未解析${suffix}` };
+    }
+    if (input.phase === 'connected') {
+        if (input.state === 'expected-internal' || input.state === 'internal-overlay') {
+            return { severity: 'ok', ok: true, message: `${host} 已由 V2 split DNS 指向 Internal。` };
+        }
+        if (input.state === 'proxy-fake-ip') {
+            return { severity: 'error', ok: false, message: `${host} 仍命中 Clash/mihomo fake-ip；V2 split DNS 尚未接管该域名。` };
+        }
+        if (input.state === 'public') {
+            return { severity: 'error', ok: false, message: `${host} 仍走外部 DNS；V2 split DNS 尚未接管该域名。` };
+        }
+        if (input.state === 'v1-hdo-overlay') {
+            return { severity: 'warning', ok: false, message: `${host} 当前落在 V1 HDO 网段；V2 connected 状态应切到 10.* Internal。` };
+        }
+        return { severity: 'warning', ok: false, message: `${host} 当前解析到 ${input.state}，不是 V2 Internal 目标。` };
+    }
+    if (input.phase === 'bootstrap') {
+        if (input.state === 'proxy-fake-ip') {
+            return { severity: 'info', ok: true, message: `${host} bootstrap 当前由系统代理/TUN fake-ip 接管，这只能作为外部可达路径，不是 V2 ready 证明。` };
+        }
+        if (input.state === 'public') {
+            return { severity: 'ok', ok: true, message: `${host} bootstrap 当前走外部 DNS，可用于连接前发现 Domestic/Internal 入口。` };
+        }
+        if (input.state === 'expected-internal' || input.state === 'internal-overlay') {
+            return { severity: 'info', ok: true, message: `${host} bootstrap 当前解析到 Internal；这通常依赖 V1 DNS 或保留 overlay。` };
+        }
+        return { severity: 'info', ok: true, message: `${host} bootstrap 当前解析到 ${input.state}。` };
+    }
+    if (input.phase === 'disconnected') {
+        if (input.state === 'public' || input.state === 'proxy-fake-ip') {
+            return { severity: 'ok', ok: true, message: `${host} disconnected 状态已回到系统/外部解析路径。` };
+        }
+        return { severity: 'warning', ok: true, message: `${host} disconnected 状态仍解析到 ${input.state}；如果未开启 V1/V2/代理，可能存在残留 resolver 或 DNS cache。` };
+    }
+    return { severity: 'info', ok: true, message: `${host} 当前解析状态为 ${input.state}。` };
+}
+async function resolveHostAddresses(host, customLookup) {
+    const records = customLookup
+        ? await customLookup(host)
+        : await dnsLookup(host, { all: true, family: 4 });
+    return records
+        .map((record) => typeof record === 'string' ? record : record.address || '')
+        .map((address) => address.trim())
+        .filter(Boolean);
+}
+function resolutionState(addresses) {
+    if (addresses.length === 0)
+        return 'unresolved';
+    const classes = addresses.map((row) => row.classification);
+    if (classes.includes('expected-internal-target'))
+        return 'expected-internal';
+    if (classes.includes('internal-overlay'))
+        return 'internal-overlay';
+    if (classes.includes('v1-hdo-overlay'))
+        return 'v1-hdo-overlay';
+    if (classes.includes('proxy-fake-ip'))
+        return 'proxy-fake-ip';
+    if (classes.includes('public'))
+        return 'public';
+    if (classes.includes('private'))
+        return 'private';
+    if (classes.includes('loopback'))
+        return 'loopback';
+    return 'unresolved';
+}
+function normalizePhase(value) {
+    if (value === 'bootstrap' || value === 'connected' || value === 'disconnected')
+        return value;
+    return 'unknown';
+}
+function normalizeHost(value) {
+    const text = typeof value === 'string' ? value.trim() : '';
+    if (!text)
+        return null;
+    if (/^https?:\/\//i.test(text)) {
+        try {
+            return new URL(text).hostname.toLowerCase() || null;
+        }
+        catch {
+            return null;
+        }
+    }
+    return text.replace(/:\d{1,5}$/, '').toLowerCase();
+}
+function normalizeIpv4List(values) {
+    return uniqueStrings((values ?? [])
+        .map((value) => String(value || '').trim())
+        .filter((value) => isIP(value) === 4));
+}
+function normalizeCidrList(values, fallback) {
+    const normalized = (values?.length ? values : fallback)
+        .map((value) => String(value || '').trim())
+        .filter((value) => parseCidr(value) !== null);
+    return uniqueStrings(normalized);
+}
+function cidrsContainIp(cidrs, ip) {
+    return cidrs.some((cidr) => cidrContainsIp(cidr, ip));
+}
+function cidrContainsIp(cidr, ip) {
+    const parsed = parseCidr(cidr);
+    const target = ipv4ToInt(ip);
+    if (!parsed || target === null)
+        return false;
+    const mask = parsed.prefix === 0 ? 0 : (0xffffffff << (32 - parsed.prefix)) >>> 0;
+    return (target & mask) === (parsed.base & mask);
+}
+function parseCidr(value) {
+    const [ip, prefixText] = value.split('/');
+    const base = ipv4ToInt(ip);
+    const prefix = Number(prefixText);
+    if (base === null || !Number.isInteger(prefix) || prefix < 0 || prefix > 32)
+        return null;
+    return { base, prefix };
+}
+function ipv4ToInt(value) {
+    const text = value?.trim();
+    if (!text || isIP(text) !== 4)
+        return null;
+    const parts = text.split('.').map((part) => Number(part));
+    if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255))
+        return null;
+    return (((parts[0] * 256 + parts[1]) * 256 + parts[2]) * 256 + parts[3]) >>> 0;
+}
+function uniqueStrings(values) {
+    return values.filter((value, index, rows) => value && rows.indexOf(value) === index);
+}
+function errorMessage(err) {
+    if (err instanceof Error)
+        return err.message || String(err);
+    return String(err);
+}