@undefineds.co/xpod 0.4.20 → 0.4.27

package/dist/tunnel/NgrokTunnelProvider.jsonld

@@ -52,6 +52,30 @@
           },
           "comment": "ngrok executable path."
         },
+        {
+          "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider_options_env",
+          "range": {
+            "@type": "ParameterRangeCollectEntries",
+            "parameterRangeCollectEntriesParameters": [
+              {
+                "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider_options_env_key"
+              },
+              {
+                "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider_options_env_value",
+                "range": {
+                  "@type": "ParameterRangeUnion",
+                  "parameterRangeElements": [
+                    "xsd:string",
+                    {
+                      "@type": "ParameterRangeUndefined"
+                    }
+                  ]
+                }
+              }
+            ]
+          },
+          "comment": "Environment used to resolve the client binary; injectable for tests."
+        },
         {
           "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider_options_agentApiUrl",
           "range": {
@@ -199,6 +223,21 @@
                 "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider_options_ngrokPath"
               }
             },
+            {
+              "keyRaw": "env",
+              "value": {
+                "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider_options_env__constructorArgument",
+                "fields": [
+                  {
+                    "collectEntries": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider_options_env",
+                    "key": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider_options_env_key",
+                    "value": {
+                      "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider_options_env_value"
+                    }
+                  }
+                ]
+              }
+            },
             {
               "keyRaw": "agentApiUrl",
               "value": {

package/dist/tunnel/SakuraFrpTunnelProvider.d.ts

@@ -20,6 +20,8 @@ export interface SakuraFrpTunnelProviderOptions {
     publicUrl?: string;
     /** frpc 可执行文件路径 (默认 'frpc') */
     frpcPath?: string;
+    /** Environment used to resolve the client binary; injectable for tests. */
+    env?: Record<string, string | undefined>;
     /** 等待代理发布的毫秒数；超时后状态为 failed */
     connectTimeoutMs?: number;
     /** SakuraFRP 服务端地址 (如果需要自定义) */
@@ -35,7 +37,7 @@ export interface SakuraFrpTunnelProviderOptions {
  * 通过 frpc 客户端连接 SakuraFRP 服务
  */
 export declare class SakuraFrpTunnelProvider implements TunnelProvider {
-    readonly name = "sakura-frp";
+    readonly name = "sakura_frp";
     private readonly logger;
     private readonly token;
     private readonly publicUrl?;

package/dist/tunnel/SakuraFrpTunnelProvider.js

@@ -14,6 +14,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SakuraFrpTunnelProvider = void 0;
 exports.resolveSakuraAssignedLocalPort = resolveSakuraAssignedLocalPort;
 exports.parseSakuraCredential = parseSakuraCredential;
+const TunnelClientResolver_1 = require("./TunnelClientResolver");
 const node_child_process_1 = require("node:child_process");
 const global_logger_factory_1 = require("global-logger-factory");
 const TunnelLifecycle_1 = require("./TunnelLifecycle");
@@ -26,7 +27,9 @@ const DEFAULT_SAKURA_API_BASE_URL = 'https://api.natfrp.com/v4';
  */
 class SakuraFrpTunnelProvider {
     constructor(options) {
-        this.name = 'sakura-frp';
+        // The catalog id, not a hyphenated implementation name: the provider vocabulary has exactly
+        // one spelling, and this one is also what failure details embed.
+        this.name = 'sakura_frp';
         this.logger = (0, global_logger_factory_1.getLoggerFor)(this);
         /** Whether the platform terminates TLS for this entry (auto HTTPS). */
         this.autoHttpsEnabled = false;
@@ -39,7 +42,8 @@ class SakuraFrpTunnelProvider {
         this.managedByUs = false;
         this.token = options.token;
         this.publicUrl = normalizePublicEndpoint(options.publicUrl);
-        this.frpcPath = options.frpcPath ?? 'frpc';
+        this.frpcPath = options.frpcPath
+            ?? (0, TunnelClientResolver_1.resolveTunnelClient)('sakura_frp', { env: options.env }).command;
         this.connectTimeoutMs = options.connectTimeoutMs ?? 30_000;
         this.serverAddr = options.serverAddr;
         this.apiBaseUrl = (options.apiBaseUrl ?? DEFAULT_SAKURA_API_BASE_URL).replace(/\/+$/u, '');
@@ -259,7 +263,7 @@ class SakuraFrpTunnelProvider {
             this.managedByUs = false;
         });
         this.process.on('error', (error) => {
-            const described = (0, TunnelLifecycle_1.describeSpawnError)('sakura-frp', this.frpcPath, error);
+            const described = (0, TunnelLifecycle_1.describeSpawnError)('sakura_frp', this.frpcPath, error);
             this.logger.error(`Failed to start frpc: ${described}`);
             this.status = (0, TunnelLifecycle_1.createTunnelStatus)('failed', { endpoint: this.currentEndpoint(), error: described });
             this.process = null;

package/dist/tunnel/TunnelClientManager.d.ts

@@ -0,0 +1,73 @@
+import { getLoggerFor } from 'global-logger-factory';
+import { type ResolvedTunnelClient } from './TunnelClientResolver';
+import { type TunnelProviderId } from './TunnelProviderCatalog';
+/**
+ * The settings page's "check" and "download" buttons for tunnel clients (audit N16).
+ *
+ * The plugin model says the artifacts ship no clients; the operator still deserves a button
+ * instead of a shell command. "Check" reports where each provider's client would come from and
+ * whether it runs; "download" fetches a client from its vendor into the plugin directory and
+ * verifies it before anything is kept.
+ *
+ * Only clients with a stable, direct, platform-addressed download are installable this way
+ * (cloudflared today). ngrok ships through a CDN whose URL scheme we do not pin, and the natfrp
+ * frpc fork has no published direct asset: for those the answer is the install hint, not a guess.
+ */
+export type TunnelClientState = 'ready' | 'missing';
+export interface TunnelClientInspection {
+    provider: TunnelProviderId;
+    label: string;
+    binary: string;
+    state: TunnelClientState;
+    source: ResolvedTunnelClient['source'];
+    /** Absolute path when one was resolved. */
+    path?: string;
+    /** `--version` output, when the client answered. */
+    version?: string;
+    installHint: string;
+    redistributable: boolean;
+    license: string;
+    /** Whether the "download" action can install this client on this platform. */
+    installable: boolean;
+    /** Why not, when `installable` is false. */
+    installableReason?: string;
+}
+export interface TunnelClientManagerOptions {
+    packageRoot?: string;
+    env?: Record<string, string | undefined>;
+    platform?: NodeJS.Platform;
+    arch?: string;
+    fetchImpl?: typeof fetch;
+    /** Runs `<binary> --version`; injected in tests. */
+    runVersion?: (binary: string) => Promise<string | undefined>;
+    /** Extracts a `.tgz` asset; injected in tests. */
+    extractTgz?: (archivePath: string, destination: string) => Promise<void>;
+    logger?: Pick<ReturnType<typeof getLoggerFor>, 'info' | 'warn'>;
+}
+export interface InstallTunnelClientResult {
+    provider: TunnelProviderId;
+    installedPath: string;
+    version?: string;
+    sourceUrl: string;
+}
+export declare class TunnelClientManager {
+    private readonly options;
+    private readonly logger;
+    private readonly packageRoot;
+    private readonly platform;
+    private readonly arch;
+    constructor(options?: TunnelClientManagerOptions);
+    /** Where downloaded clients live; also the resolver's second source. */
+    pluginDirectory(): string;
+    inspectAll(): Promise<TunnelClientInspection[]>;
+    inspect(provider: TunnelProviderId): Promise<TunnelClientInspection>;
+    /**
+     * Downloads a client into the plugin directory and keeps it only if it runs.
+     *
+     * Verification is "does the freshly written binary answer `--version`"; a file that cannot run
+     * is deleted again, so a broken or bogus download never looks installed.
+     */
+    install(provider: TunnelProviderId, options?: {
+        signal?: AbortSignal;
+    }): Promise<InstallTunnelClientResult>;
+}

package/dist/tunnel/TunnelClientManager.js

@@ -0,0 +1,181 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TunnelClientManager = void 0;
+const node_fs_1 = require("node:fs");
+const node_child_process_1 = require("node:child_process");
+const promises_1 = require("node:stream/promises");
+const node_stream_1 = require("node:stream");
+const node_path_1 = __importDefault(require("node:path"));
+const global_logger_factory_1 = require("global-logger-factory");
+const package_root_1 = require("../runtime/package-root");
+const TunnelClientResolver_1 = require("./TunnelClientResolver");
+const TunnelProviderCatalog_1 = require("./TunnelProviderCatalog");
+/** Download assets we are willing to fetch, per platform. */
+function downloadPlan(provider, platform, arch) {
+    if (provider !== 'cloudflare') {
+        return undefined;
+    }
+    const architecture = arch === 'x64' ? 'amd64' : arch === 'arm64' ? 'arm64' : undefined;
+    if (!architecture) {
+        return undefined;
+    }
+    const base = 'https://github.com/cloudflare/cloudflared/releases/latest/download';
+    if (platform === 'linux') {
+        return { url: `${base}/cloudflared-linux-${architecture}`, archive: 'binary', binary: 'cloudflared' };
+    }
+    if (platform === 'darwin') {
+        return { url: `${base}/cloudflared-darwin-${architecture}.tgz`, archive: 'tgz', binary: 'cloudflared' };
+    }
+    return undefined;
+}
+class TunnelClientManager {
+    constructor(options = {}) {
+        this.options = options;
+        this.logger = options.logger ?? (0, global_logger_factory_1.getLoggerFor)('TunnelClientManager');
+        this.packageRoot = options.packageRoot ?? package_root_1.PACKAGE_ROOT;
+        this.platform = options.platform ?? process.platform;
+        this.arch = options.arch ?? process.arch;
+    }
+    /** Where downloaded clients live; also the resolver's second source. */
+    pluginDirectory() {
+        return node_path_1.default.join(this.packageRoot, 'vendor', 'tunnel-clients');
+    }
+    async inspectAll() {
+        return await Promise.all(TunnelProviderCatalog_1.TUNNEL_PROVIDERS.map(async (descriptor) => this.inspect(descriptor.id)));
+    }
+    async inspect(provider) {
+        const descriptor = TunnelProviderCatalog_1.TUNNEL_PROVIDERS.find((entry) => entry.id === provider);
+        if (!descriptor) {
+            throw new Error(`Unknown tunnel provider: ${provider}`);
+        }
+        const client = descriptor.client;
+        const plan = downloadPlan(provider, this.platform, this.arch);
+        let resolved;
+        let resolutionError;
+        try {
+            resolved = (0, TunnelClientResolver_1.resolveTunnelClient)(provider, { packageRoot: this.packageRoot, env: this.options.env });
+        }
+        catch (error) {
+            resolutionError = error instanceof Error ? error.message : String(error);
+        }
+        const resolvedPath = resolved?.resolvedPath;
+        const version = resolvedPath
+            ? await (this.options.runVersion ?? runBinaryVersion)(resolvedPath)
+            : undefined;
+        // A PATH-resolved name is only "ready" once it actually answers: the bare name tells us
+        // nothing until something runs.
+        const state = resolvedPath && version ? 'ready' : 'missing';
+        const installable = Boolean(plan) && this.platform !== 'win32';
+        return {
+            provider,
+            label: descriptor.label,
+            binary: client.binary,
+            state,
+            source: resolved?.source ?? 'path',
+            ...(resolvedPath ? { path: resolvedPath } : {}),
+            ...(version ? { version } : {}),
+            installHint: client.installHint,
+            redistributable: client.redistributable,
+            license: client.license,
+            installable,
+            ...(installable
+                ? {}
+                : {
+                    installableReason: resolutionError
+                        ?? (plan ? `platform ${this.platform}/${this.arch} has no pinned asset` : 'no pinned direct download; install it yourself'),
+                }),
+        };
+    }
+    /**
+     * Downloads a client into the plugin directory and keeps it only if it runs.
+     *
+     * Verification is "does the freshly written binary answer `--version`"; a file that cannot run
+     * is deleted again, so a broken or bogus download never looks installed.
+     */
+    async install(provider, options = {}) {
+        const descriptor = TunnelProviderCatalog_1.TUNNEL_PROVIDERS.find((entry) => entry.id === provider);
+        const plan = descriptor ? downloadPlan(provider, this.platform, this.arch) : undefined;
+        if (!descriptor || !plan) {
+            throw new Error(`No pinned download is available for ${provider} on ${this.platform}/${this.arch}; ${descriptor?.client.installHint ?? 'install it manually'}`);
+        }
+        const directory = this.pluginDirectory();
+        await node_fs_1.promises.mkdir(directory, { recursive: true });
+        const fetchImpl = this.options.fetchImpl ?? fetch;
+        const response = await fetchImpl(plan.url, {
+            ...(options.signal ? { signal: options.signal } : {}),
+            redirect: 'follow',
+        });
+        if (!response.ok || !response.body) {
+            throw new Error(`download failed: HTTP ${response.status} from ${plan.url}`);
+        }
+        const target = node_path_1.default.join(directory, plan.binary);
+        if (plan.archive === 'binary') {
+            await writeBody(response, target);
+        }
+        else {
+            const archivePath = `${target}.tgz`;
+            await writeBody(response, archivePath);
+            try {
+                await (this.options.extractTgz ?? extractTgzWithTar)(archivePath, directory);
+            }
+            finally {
+                await node_fs_1.promises.rm(archivePath, { force: true });
+            }
+        }
+        await node_fs_1.promises.chmod(target, 0o755);
+        const version = await (this.options.runVersion ?? runBinaryVersion)(target);
+        if (!version) {
+            await node_fs_1.promises.rm(target, { force: true });
+            throw new Error(`the downloaded ${plan.binary} did not run, so it was removed: ${plan.url}`);
+        }
+        this.logger.info(`installed ${plan.binary} ${version} into ${directory}`);
+        return { provider, installedPath: target, version, sourceUrl: plan.url };
+    }
+}
+exports.TunnelClientManager = TunnelClientManager;
+async function writeBody(response, target) {
+    if (!response.body) {
+        throw new Error('download returned no body');
+    }
+    // Stream to disk: a tunnel client is tens of megabytes and must not be buffered in memory.
+    await (0, promises_1.pipeline)(node_stream_1.Readable.fromWeb(response.body), (0, node_fs_1.createWriteStream)(target, { mode: 0o755 }));
+}
+async function runBinaryVersion(binary) {
+    if (!(0, node_fs_1.existsSync)(binary)) {
+        return undefined;
+    }
+    return await new Promise((resolve) => {
+        const child = (0, node_child_process_1.spawn)(binary, ['--version'], { stdio: ['ignore', 'pipe', 'pipe'] });
+        let output = '';
+        const timer = setTimeout(() => {
+            child.kill('SIGKILL');
+            resolve(undefined);
+        }, 5_000);
+        child.stdout?.on('data', (chunk) => {
+            output += chunk.toString();
+        });
+        child.stderr?.on('data', (chunk) => {
+            output += chunk.toString();
+        });
+        child.once('error', () => {
+            clearTimeout(timer);
+            resolve(undefined);
+        });
+        child.once('exit', (code) => {
+            clearTimeout(timer);
+            const first = output.split('\n').map((line) => line.trim()).find((line) => line.length > 0);
+            resolve(code === 0 && first ? first : undefined);
+        });
+    });
+}
+async function extractTgzWithTar(archivePath, destination) {
+    await new Promise((resolve, reject) => {
+        const child = (0, node_child_process_1.spawn)('tar', ['-xzf', archivePath, '-C', destination], { stdio: 'ignore' });
+        child.once('error', reject);
+        child.once('exit', (code) => (code === 0 ? resolve() : reject(new Error(`tar exited with ${code}`))));
+    });
+}
+//# sourceMappingURL=TunnelClientManager.js.map

package/dist/tunnel/TunnelClientResolver.d.ts

@@ -0,0 +1,56 @@
+import { type TunnelProviderClient, type TunnelProviderId } from './TunnelProviderCatalog';
+/**
+ * One resolution order for every tunnel client (audit N16).
+ *
+ * The providers used to spawn a bare default name each, so "which binary did it actually run"
+ * was spread over three constructors, an explicit path that did not exist failed as a plain
+ * ENOENT, and a release artifact that shipped a client had nowhere to say so.
+ *
+ * Order, highest first:
+ *   1. an explicit path (provider option or the catalog's env key) — if the operator named a
+ *      path, a missing file is an error, not a reason to quietly use something else;
+ *   2. a binary bundled next to the package (`vendor/tunnel-clients/<binary>`);
+ *   3. the bare name, which the OS resolves through PATH.
+ */
+export interface ResolveTunnelClientOptions {
+    /** Provider option that already carries a path (e.g. `ngrokPath`). */
+    explicitPath?: string;
+    /** Package root that may contain `vendor/tunnel-clients/`. */
+    packageRoot?: string;
+    env?: Record<string, string | undefined>;
+    /** Injectable for tests: decides whether a resolved path is usable. */
+    isExecutable?: (candidate: string) => boolean;
+}
+export interface ResolvedTunnelClient {
+    /** What to spawn. */
+    command: string;
+    source: 'explicit' | 'bundled' | 'path';
+    /** Absolute path when one was resolved. */
+    resolvedPath?: string;
+    /** Catalog facts for diagnostics. */
+    client: TunnelProviderClient;
+}
+/** An explicit path that does not exist is a configuration error, not a fallback. */
+export declare class TunnelClientPathError extends Error {
+    readonly provider: TunnelProviderId;
+    readonly configuredPath: string;
+    readonly installHint: string;
+    constructor(provider: TunnelProviderId, configuredPath: string, installHint: string);
+}
+export declare function describeTunnelClientMissing(provider: TunnelProviderId | string, binary?: string): string;
+export declare function resolveTunnelClient(provider: TunnelProviderId, options?: ResolveTunnelClientOptions): ResolvedTunnelClient;
+/** Resolves every provider's client, for preflight/reporting. */
+export declare function resolveAllTunnelClients(options?: ResolveTunnelClientOptions): Array<{
+    provider: TunnelProviderId;
+    resolved?: ResolvedTunnelClient;
+    error?: Error;
+}>;
+/** Providers whose client may be shipped in a release artifact, with the licence to keep. */
+export declare function redistributableTunnelClients(): Array<{
+    provider: TunnelProviderId;
+    client: TunnelProviderClient;
+}>;
+/** One sentence stating which clients an artifact may ship, derived from the catalog. */
+export declare function redistributePolicyNote(): string;
+/** Finds an executable by name on the given environment's PATH (no shell involved). */
+export declare function findOnPath(binary: string, env?: Record<string, string | undefined>, isExecutable?: (candidate: string) => boolean): string | undefined;

package/dist/tunnel/TunnelClientResolver.js

@@ -0,0 +1,135 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TunnelClientPathError = void 0;
+exports.describeTunnelClientMissing = describeTunnelClientMissing;
+exports.resolveTunnelClient = resolveTunnelClient;
+exports.resolveAllTunnelClients = resolveAllTunnelClients;
+exports.redistributableTunnelClients = redistributableTunnelClients;
+exports.redistributePolicyNote = redistributePolicyNote;
+exports.findOnPath = findOnPath;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const TunnelProviderCatalog_1 = require("./TunnelProviderCatalog");
+/** An explicit path that does not exist is a configuration error, not a fallback. */
+class TunnelClientPathError extends Error {
+    constructor(provider, configuredPath, installHint) {
+        super(`tunnel client for ${provider} is configured as "${configuredPath}", but nothing executable is there; `
+            + installHint);
+        this.provider = provider;
+        this.configuredPath = configuredPath;
+        this.installHint = installHint;
+        this.name = 'TunnelClientPathError';
+    }
+}
+exports.TunnelClientPathError = TunnelClientPathError;
+function describeTunnelClientMissing(provider, binary) {
+    // One spelling reaches an operator: the catalog id. A caller that still uses a legacy or
+    // implementation-local name (`sakura-frp`) is normalized here instead of leaking a provider
+    // id no catalog lookup can resolve.
+    const id = (0, TunnelProviderCatalog_1.canonicalTunnelProviderId)(provider) ?? provider;
+    const descriptor = TunnelProviderCatalog_1.TUNNEL_PROVIDERS.find((entry) => entry.id === id);
+    const client = descriptor?.client;
+    const name = binary ?? client?.binary ?? 'unknown';
+    return `binary-missing:${id}:${name}` + (client ? ` (${client.installHint})` : '');
+}
+function resolveTunnelClient(provider, options = {}) {
+    const descriptor = TunnelProviderCatalog_1.TUNNEL_PROVIDERS.find((entry) => entry.id === provider);
+    if (!descriptor) {
+        throw new Error(`Unknown tunnel provider: ${provider}`);
+    }
+    const client = descriptor.client;
+    const env = options.env ?? process.env;
+    const isExecutable = options.isExecutable ?? defaultIsExecutable;
+    const configuredPath = normalizePath(options.explicitPath) ?? normalizePath(env[client.envKey]);
+    if (configuredPath) {
+        if (!isExecutable(configuredPath)) {
+            throw new TunnelClientPathError(provider, configuredPath, client.installHint);
+        }
+        return { command: configuredPath, source: 'explicit', resolvedPath: configuredPath, client };
+    }
+    const bundled = options.packageRoot
+        ? node_path_1.default.join(options.packageRoot, 'vendor', 'tunnel-clients', client.binary)
+        : undefined;
+    if (bundled && isExecutable(bundled)) {
+        return { command: bundled, source: 'bundled', resolvedPath: bundled, client };
+    }
+    // Look the name up on PATH ourselves instead of leaving it to the spawn: the settings page
+    // has to be able to say "ready, at <path>, version X", and two places deciding "is it on
+    // PATH" is how the check button and the preflight script ended up disagreeing.
+    const onPath = findOnPath(client.binary, env, isExecutable);
+    if (onPath) {
+        return { command: onPath, source: 'path', resolvedPath: onPath, client };
+    }
+    // Not found: hand the bare name to the OS anyway, so a PATH entry this process cannot read
+    // still gets its chance; a real miss surfaces as ENOENT and becomes
+    // `binary-missing:<provider>:<binary>` with the install hint attached.
+    return { command: client.binary, source: 'path', client };
+}
+/** Resolves every provider's client, for preflight/reporting. */
+function resolveAllTunnelClients(options = {}) {
+    return TunnelProviderCatalog_1.TUNNEL_PROVIDERS.map((descriptor) => {
+        try {
+            return { provider: descriptor.id, resolved: resolveTunnelClient(descriptor.id, options) };
+        }
+        catch (error) {
+            return { provider: descriptor.id, error: error instanceof Error ? error : new Error(String(error)) };
+        }
+    });
+}
+/** Providers whose client may be shipped in a release artifact, with the licence to keep. */
+function redistributableTunnelClients() {
+    return TunnelProviderCatalog_1.TUNNEL_PROVIDERS
+        .filter((descriptor) => descriptor.client.redistributable)
+        .map((descriptor) => ({ provider: descriptor.id, client: descriptor.client }));
+}
+/** One sentence stating which clients an artifact may ship, derived from the catalog. */
+function redistributePolicyNote() {
+    const allowed = redistributableTunnelClients().map((entry) => entry.client.binary);
+    const blocked = TunnelProviderCatalog_1.TUNNEL_PROVIDERS
+        .filter((descriptor) => !descriptor.client.redistributable)
+        .map((descriptor) => `${descriptor.id} (${descriptor.client.license})`);
+    return `bundled clients allowed: ${allowed.join(', ') || 'none'}; not ours to ship: ${blocked.join(', ') || 'none'}`;
+}
+/** Finds an executable by name on the given environment's PATH (no shell involved). */
+function findOnPath(binary, env = process.env, isExecutable = defaultIsExecutable) {
+    for (const entry of (env.PATH ?? '').split(node_path_1.default.delimiter)) {
+        if (!entry) {
+            continue;
+        }
+        const candidate = node_path_1.default.join(entry, binary);
+        if (isExecutable(candidate)) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+function normalizePath(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : undefined;
+}
+function defaultIsExecutable(candidate) {
+    try {
+        if (!(0, node_fs_1.existsSync)(candidate)) {
+            const matches = safeReaddir(node_path_1.default.dirname(candidate))
+                .filter((entry) => entry === node_path_1.default.basename(candidate));
+            return matches.length > 0;
+        }
+        const stats = (0, node_fs_1.statSync)(candidate);
+        return stats.isFile() || stats.isFIFO();
+    }
+    catch {
+        return false;
+    }
+}
+function safeReaddir(directory) {
+    try {
+        return (0, node_fs_1.readdirSync)(directory);
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=TunnelClientResolver.js.map

package/dist/tunnel/TunnelDeclaredOrigin.d.ts

@@ -0,0 +1,78 @@
+import { spawn } from 'node:child_process';
+import { resolveSakuraAssignedLocalPort } from './SakuraFrpTunnelProvider';
+/**
+ * The origin port a provider *console* already declares, read back before this runtime binds
+ * its tunnel entry.
+ *
+ * A console-owned tunnel (Cloudflare dashboard, SakuraFrp console) forwards to a number that
+ * lives in that console. Asking the operator to edit the console so it matches the runtime is
+ * the behaviour the operator rejected: the runtime adopts what the console already says. Both
+ * readers below are the same ones the providers use for their own diagnostics, so there is
+ * only ever one parser per provider.
+ */
+export interface DeclaredIngressOrigin {
+    port: number;
+    /** Scheme the console declares for its origin service, when it declares one. */
+    scheme?: string;
+    /** Where the value came from, for logs and evidence. */
+    readBack: string;
+}
+export interface DeclaredOriginReadResult {
+    origin?: DeclaredIngressOrigin;
+    /** Why no origin could be read; never silently treated as "no console declaration". */
+    error?: string;
+}
+export interface DeclaredOriginProfile {
+    id: string;
+    provider: string;
+    credentialEnvKey?: string;
+    credentialConfigured?: boolean;
+}
+export interface ReadDeclaredOriginOptions {
+    env?: Record<string, string | undefined>;
+    /**
+     * Whether this profile is the active one. A Cloudflare read-back starts a short-lived
+     * connector, so it only runs for the profile whose port the runtime is about to adopt.
+     */
+    active?: boolean;
+    /** Explicit cloudflared path; falls back to the catalog env key and PATH. */
+    cloudflaredPath?: string;
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+    sakuraApiBaseUrl?: string;
+    /** Injected in tests. */
+    readCloudflare?: typeof readCloudflareRemoteOrigin;
+    readSakura?: typeof resolveSakuraAssignedLocalPort;
+}
+/**
+ * Reads the origin the active profile's console declares, using that provider's own reader.
+ *
+ * A provider that owns the origin at runtime (`originOwner: 'runtime'`) has nothing to read:
+ * the port is ours to choose, and pretending otherwise would invent a console value.
+ */
+export declare function readDeclaredIngressOrigin(profile: DeclaredOriginProfile, options?: ReadDeclaredOriginOptions): Promise<DeclaredOriginReadResult>;
+export interface CloudflareOriginReadOptions {
+    command: string;
+    timeoutMs?: number;
+    env?: Record<string, string | undefined>;
+    /** Injected in tests: yields the lines a real cloudflared would print. */
+    spawnImpl?: typeof spawn;
+}
+export interface CloudflareOriginRead {
+    origin?: DeclaredIngressOrigin;
+    /** Lines that mentioned an ingress service, for the log line when the read fails. */
+    log: string[];
+    error?: string;
+}
+/**
+ * Reads the remote configuration of a named tunnel from the connector that fetches it.
+ *
+ * A named tunnel's ingress is stored at Cloudflare, and the connector token is not a
+ * Cloudflare API credential, so the only local read-back is what cloudflared itself echoes
+ * when it fetches that configuration. The parser is `readDashboardOrigin` — the same one
+ * `LocalTunnelProvider` uses for its `origin-mismatch` diagnostic — so the two cannot drift.
+ *
+ * The probe connector is short-lived and is always terminated; the runtime's real connector
+ * starts later, and a tunnel tolerates several connectors while it is up.
+ */
+export declare function readCloudflareRemoteOrigin(token: string, options: CloudflareOriginReadOptions): Promise<CloudflareOriginRead>;