@undefineds.co/xpod 0.4.12 → 0.4.14

package/dist/tunnel/LocalTunnelProvider.js

@@ -1,8 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LocalTunnelProvider = void 0;
+exports.readDashboardOrigin = readDashboardOrigin;
 const node_child_process_1 = require("node:child_process");
 const global_logger_factory_1 = require("global-logger-factory");
+const TunnelLifecycle_1 = require("./TunnelLifecycle");
 /** cloudflared metrics 端口 */
 const CLOUDFLARED_METRICS_PORT = 33863;
 /**
@@ -31,6 +33,7 @@ class LocalTunnelProvider {
         this.tunnelToken = options.tunnelToken;
         this.publicUrl = normalizePublicEndpoint(options.publicUrl);
         this.cloudflaredPath = options.cloudflaredPath ?? 'cloudflared';
+        this.connectTimeoutMs = options.connectTimeoutMs ?? 30_000;
     }
     /**
      * Local 模式不需要 setup，直接返回基于 Token 的配置
@@ -71,7 +74,7 @@ class LocalTunnelProvider {
             throw new Error('Tunnel token is required');
         }
         this.logger.info('Starting cloudflared tunnel...');
-        this.status = { running: true, connected: false };
+        this.status = (0, TunnelLifecycle_1.createTunnelStatus)('process-started', { endpoint: this.status.endpoint });
         this.managedByUs = true;
         const args = [
             'tunnel',
@@ -92,10 +95,13 @@ class LocalTunnelProvider {
             if (output) {
                 this.logOutput(output);
             }
-            // 检测连接成功
-            if (output.includes('Connection registered') || output.includes('Registered tunnel connection')) {
-                this.status.connected = true;
-                this.status.lastHeartbeat = new Date();
+            // 检测连接成功：只有连接注册成功才代表代理已发布
+            if (output.includes('Registered tunnel connection') || output.includes('Connection registered')) {
+                this.status = (0, TunnelLifecycle_1.createTunnelStatus)('proxy-ready', {
+                    endpoint: this.status.endpoint,
+                    lastHeartbeat: new Date(),
+                    error: this.status.error,
+                });
                 this.logger.info('Tunnel connected successfully');
             }
         });
@@ -106,10 +112,31 @@ class LocalTunnelProvider {
                 this.logOutput(output);
                 // 检测连接成功
                 if (output.includes('Registered tunnel connection') || output.includes('Connection registered')) {
-                    this.status.connected = true;
-                    this.status.lastHeartbeat = new Date();
+                    this.status = (0, TunnelLifecycle_1.createTunnelStatus)('proxy-ready', {
+                        endpoint: this.status.endpoint,
+                        lastHeartbeat: new Date(),
+                        error: this.status.error ?? this.originMismatch,
+                    });
                     // logOutput 已经打印了信息，这里不需要重复打印
                 }
+                // A remotely-managed tunnel forwards to the port the dashboard declares, which is
+                // not the port we dialled if the operator never matched them: naming that mismatch
+                // is the difference between "the entry is unreachable" and a fixable configuration.
+                const declared = readDashboardOrigin(output);
+                if (declared !== undefined) {
+                    const dialled = this.currentConfig?.originUrl;
+                    // Scheme matters as much as the port: an https service pointed at this plain-HTTP
+                    // ingress listener fails the handshake, which the edge reports as a bare 502.
+                    this.originMismatch = dialled && (declared.port !== readPort(dialled) || declared.scheme !== readScheme(dialled))
+                        ? `origin-mismatch:dashboard=${declared.scheme}://localhost:${declared.port},runtime=${dialled}`
+                        : undefined;
+                    if (this.originMismatch) {
+                        this.logger.warn(`The Cloudflare dashboard forwards this hostname to ${declared.scheme}://localhost:${declared.port}, but this runtime serves ${dialled}: set the dashboard service to that address`);
+                    }
+                    if (this.status.stage === 'proxy-ready') {
+                        this.status.error = this.originMismatch ?? this.status.error;
+                    }
+                }
                 // 检测错误
                 if (output.includes('ERR') || output.includes('failed')) {
                     this.status.error = output;
@@ -118,24 +145,25 @@ class LocalTunnelProvider {
         });
         this.process.on('exit', (code) => {
             this.logger.info(`Process exited with code ${code}`);
-            this.status = { running: false, connected: false };
+            this.status = (0, TunnelLifecycle_1.createTunnelStatus)('failed', {
+                endpoint: this.status.endpoint,
+                error: this.status.error ?? (code === 0 ? 'cloudflared-exited' : `cloudflared exited with code ${code}`),
+            });
             this.process = null;
             this.managedByUs = false;
         });
         this.process.on('error', (error) => {
-            this.logger.error(`Failed to start: ${error.message}`);
-            this.status = { running: false, connected: false, error: error.message };
+            const described = (0, TunnelLifecycle_1.describeSpawnError)('cloudflare', this.cloudflaredPath, error);
+            this.logger.error(`Failed to start: ${described}`);
+            this.status = (0, TunnelLifecycle_1.createTunnelStatus)('failed', { endpoint: this.status.endpoint, error: described });
             this.process = null;
             this.managedByUs = false;
         });
         this.currentConfig = actualConfig;
         this.status.endpoint = actualConfig.endpoint;
         // 等待连接建立
-        await this.waitForConnection();
+        await this.waitForConnection(this.connectTimeoutMs);
     }
-    /**
-     * 解析并打印 cloudflared 日志
-     */
     logOutput(raw) {
         const lines = raw.split('\n');
         for (const line of lines) {
@@ -174,7 +202,8 @@ class LocalTunnelProvider {
     async stop() {
         if (!this.managedByUs) {
             this.logger.info('Not managed by us, skipping stop');
-            this.status = { running: false, connected: false };
+            // Keep the last error: stopping must not launder a failed tunnel into a clean one.
+            this.status = (0, TunnelLifecycle_1.createTunnelStatus)('stopped', { endpoint: this.status.endpoint, error: this.status.error });
             return;
         }
         if (this.process) {
@@ -195,7 +224,7 @@ class LocalTunnelProvider {
             this.process = null;
             this.logger.info('Tunnel stopped');
         }
-        this.status = { running: false, connected: false };
+        this.status = (0, TunnelLifecycle_1.createTunnelStatus)('stopped', { endpoint: this.status.endpoint, error: this.status.error });
         this.managedByUs = false;
     }
     /**
@@ -280,8 +309,13 @@ class LocalTunnelProvider {
             }
             await new Promise((r) => setTimeout(r, 500));
         }
-        // 超时不抛错，cloudflared 可能还在连接中
-        this.logger.warn('Connection timeout, tunnel may still be connecting...');
+        // A timeout is a fact the caller has to see: the process exists but nothing is
+        // published yet, so the tunnel is not ready.
+        this.status = (0, TunnelLifecycle_1.createTunnelStatus)('failed', {
+            endpoint: this.status.endpoint,
+            error: this.status.error ?? 'cloudflared-connect-timeout',
+        });
+        this.logger.warn('cloudflared did not register a tunnel connection before the timeout');
     }
     /**
      * 获取是否由我们管理
@@ -306,4 +340,39 @@ function normalizePublicEndpoint(value) {
         return value.trim();
     }
 }
+/**
+ * The origin a remotely-managed tunnel declares for its hostname.
+ *
+ * Both halves are reported: pointing the dashboard at `https://localhost:<port>` while this
+ * runtime serves plain HTTP there fails the TLS handshake, and the edge shows only a 502.
+ */
+function readDashboardOrigin(output) {
+    const match = /"service"\s*:\s*"(https?):\/\/(?:localhost|127\.0\.0\.1):(\d+)/iu.exec(output)
+        ?? /ingress[^\n]*service["']?\s*[:=]\s*["']?(https?):\/\/(?:localhost|127\.0\.0\.1):(\d+)/iu.exec(output);
+    if (!match) {
+        return undefined;
+    }
+    const port = Number.parseInt(match[2], 10);
+    return Number.isInteger(port) && port > 0 ? { scheme: match[1].toLowerCase(), port } : undefined;
+}
+function readPort(value) {
+    if (!value)
+        return undefined;
+    try {
+        return Number.parseInt(new URL(value).port, 10) || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function readScheme(value) {
+    if (!value)
+        return undefined;
+    try {
+        return new URL(value).protocol.replace(':', '');
+    }
+    catch {
+        return undefined;
+    }
+}
 //# sourceMappingURL=LocalTunnelProvider.js.map

package/dist/tunnel/LocalTunnelProvider.jsonld

@@ -43,6 +43,19 @@
             ]
           },
           "comment": "cloudflared 可执行文件路径 (默认 'cloudflared')"
+        },
+        {
+          "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider_options_connectTimeoutMs",
+          "range": {
+            "@type": "ParameterRangeUnion",
+            "parameterRangeElements": [
+              "xsd:number",
+              {
+                "@type": "ParameterRangeUndefined"
+              }
+            ]
+          },
+          "comment": "等待代理发布的毫秒数；超时后状态为 failed，而不是\"仍在连接\""
         }
       ],
       "memberFields": [
@@ -66,6 +79,10 @@
           "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider__member_cloudflaredPath",
           "memberFieldName": "cloudflaredPath"
         },
+        {
+          "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider__member_connectTimeoutMs",
+          "memberFieldName": "connectTimeoutMs"
+        },
         {
           "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider__member_process",
           "memberFieldName": "process"
@@ -94,6 +111,10 @@
           "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider__member_start",
           "memberFieldName": "start"
         },
+        {
+          "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider__member_originMismatch",
+          "memberFieldName": "originMismatch"
+        },
         {
           "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider__member_logOutput",
           "memberFieldName": "logOutput"
@@ -156,6 +177,12 @@
               "value": {
                 "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider_options_cloudflaredPath"
               }
+            },
+            {
+              "keyRaw": "connectTimeoutMs",
+              "value": {
+                "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider_options_connectTimeoutMs"
+              }
             }
           ]
         }

package/dist/tunnel/NgrokTunnelProvider.d.ts

@@ -31,6 +31,8 @@ export declare class NgrokTunnelProvider implements TunnelProvider {
     private status;
     private currentConfig;
     private managedByUs;
+    /** Origin this instance asked ngrok to expose; the agent answer must match it. */
+    private expectedLocalOrigin?;
     constructor(options?: NgrokTunnelProviderOptions);
     setup(options: TunnelSetupOptions): Promise<TunnelConfig>;
     start(config?: TunnelConfig): Promise<void>;
@@ -44,3 +46,5 @@ export declare class NgrokTunnelProvider implements TunnelProvider {
     private waitForConnection;
     private discoverEndpointFromAgentApi;
 }
+/** Loopback endpoints belong to the agent itself, never to a published tunnel. */
+export declare function isLocalAgentUrl(url: string): boolean;

package/dist/tunnel/NgrokTunnelProvider.js

@@ -1,8 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NgrokTunnelProvider = void 0;
+exports.isLocalAgentUrl = isLocalAgentUrl;
 const node_child_process_1 = require("node:child_process");
 const global_logger_factory_1 = require("global-logger-factory");
+const TunnelLifecycle_1 = require("./TunnelLifecycle");
 /**
  * Starts a user-owned ngrok agent for Local SP access.
  *
@@ -37,6 +39,7 @@ class NgrokTunnelProvider {
             endpoint: normalizeEndpointForConfig(this.configuredUrl) ?? '',
             originUrl,
         };
+        this.expectedLocalOrigin = originUrl;
         this.currentConfig = config;
         return config;
     }
@@ -59,11 +62,9 @@ class NgrokTunnelProvider {
             args.push('--url', endpointForCli);
         }
         args.push(actualConfig.originUrl);
-        this.status = {
-            running: true,
-            connected: false,
+        this.status = (0, TunnelLifecycle_1.createTunnelStatus)('process-started', {
             endpoint: normalizeEndpointForConfig(endpointForCli),
-        };
+        });
         this.currentConfig = {
             ...actualConfig,
             endpoint: this.status.endpoint ?? actualConfig.endpoint,
@@ -81,23 +82,20 @@ class NgrokTunnelProvider {
         this.process.stderr?.on('data', (data) => this.handleOutput(data.toString()));
         this.process.on('exit', (code) => {
             this.logger.info(`ngrok exited with code ${code}`);
-            this.status = {
-                running: false,
-                connected: false,
+            this.status = (0, TunnelLifecycle_1.createTunnelStatus)('failed', {
                 endpoint: this.status.endpoint,
-                error: this.status.error ?? (code === 0 ? undefined : `ngrok exited with code ${code}`),
-            };
+                error: this.status.error ?? (code === 0 ? 'ngrok-exited' : `ngrok exited with code ${code}`),
+            });
             this.process = null;
             this.managedByUs = false;
         });
         this.process.on('error', (error) => {
-            this.logger.error(`Failed to start ngrok: ${error.message}`);
-            this.status = {
-                running: false,
-                connected: false,
+            const described = (0, TunnelLifecycle_1.describeSpawnError)('ngrok', this.ngrokPath, error);
+            this.logger.error(`Failed to start ngrok: ${described}`);
+            this.status = (0, TunnelLifecycle_1.createTunnelStatus)('failed', {
                 endpoint: this.status.endpoint,
-                error: error.message,
-            };
+                error: described,
+            });
             this.process = null;
             this.managedByUs = false;
         });
@@ -105,7 +103,8 @@ class NgrokTunnelProvider {
     }
     async stop() {
         if (!this.managedByUs) {
-            this.status = { running: false, connected: false, endpoint: this.status.endpoint };
+            // Keep the last error: stopping must not turn a failed tunnel into a clean one.
+            this.status = (0, TunnelLifecycle_1.createTunnelStatus)('stopped', { endpoint: this.status.endpoint, error: this.status.error });
             return;
         }
         if (this.process) {
@@ -122,7 +121,7 @@ class NgrokTunnelProvider {
             });
             this.process = null;
         }
-        this.status = { running: false, connected: false, endpoint: this.status.endpoint };
+        this.status = (0, TunnelLifecycle_1.createTunnelStatus)('stopped', { endpoint: this.status.endpoint, error: this.status.error });
         this.managedByUs = false;
     }
     getStatus() {
@@ -158,17 +157,36 @@ class NgrokTunnelProvider {
         }
     }
     markConnected(endpoint) {
-        const normalized = normalizeEndpointForConfig(endpoint);
-        if (!normalized) {
+        // Readiness requires a process we still own: without one, any endpoint we just learned
+        // about (for example from the machine-wide agent API) belongs to someone else.
+        if (!this.process || !this.managedByUs) {
+            return;
+        }
+        const discovered = normalizeEndpointForConfig(endpoint);
+        const declared = normalizeEndpointForConfig(this.configuredUrl);
+        // A discovered entry has to be a real public endpoint: the local agent's own web
+        // interface is not one, and accepting it made a tunnel that published nothing look up.
+        if (!declared && (!discovered || isLocalAgentUrl(discovered))) {
             return;
         }
-        this.status.connected = true;
-        this.status.endpoint = normalized;
-        this.status.lastHeartbeat = new Date();
+        const effective = declared ?? discovered;
+        if (!effective) {
+            return;
+        }
+        if (declared && discovered && normalizeOrigin(declared) !== normalizeOrigin(discovered)) {
+            // The operator declared one entry and ngrok published another; report the declared
+            // one but leave the discrepancy in the log for whoever has to explain reachability.
+            this.logger.warn(`ngrok published ${discovered} while ${declared} is declared; keeping the declared entry`);
+        }
+        this.status = (0, TunnelLifecycle_1.createTunnelStatus)('proxy-ready', {
+            endpoint: effective,
+            lastHeartbeat: new Date(),
+            error: this.status.error,
+        });
         this.currentConfig = {
-            ...(this.currentConfig ?? { subdomain: 'local', provider: 'ngrok', endpoint: normalized }),
+            ...(this.currentConfig ?? { subdomain: 'local', provider: 'ngrok', endpoint: effective }),
             provider: 'ngrok',
-            endpoint: normalized,
+            endpoint: effective,
         };
     }
     async waitForConnection() {
@@ -180,49 +198,71 @@ class NgrokTunnelProvider {
             if (!this.status.running && this.status.error) {
                 throw new Error(`ngrok failed to start: ${this.status.error}`);
             }
-            const endpoint = await this.discoverEndpointFromAgentApi();
-            if (endpoint) {
-                this.markConnected(endpoint);
-                return;
+            // The agent API is machine-wide: another instance's agent answers on the same port.
+            // Only consult it while this provider actually has a process, otherwise a provider
+            // that failed to start would adopt someone else's tunnel as its own.
+            if (this.process && this.managedByUs) {
+                const endpoint = await this.discoverEndpointFromAgentApi();
+                if (endpoint) {
+                    this.markConnected(endpoint);
+                    // Discovery may have been refused (foreign entry, no live process); only an
+                    // actual readiness transition ends the wait.
+                    if (this.status.connected) {
+                        return;
+                    }
+                }
             }
             await new Promise((resolve) => setTimeout(resolve, Math.min(250, Math.max(25, this.connectTimeoutMs))));
         }
         if (!this.status.running && this.status.error) {
             throw new Error(`ngrok failed to start: ${this.status.error}`);
         }
-        if (this.status.endpoint) {
-            this.logger.warn('ngrok connection was not confirmed before timeout; keeping configured endpoint as degraded.');
-            this.status.connected = false;
-            return;
-        }
-        throw new Error('ngrok connection timeout');
+        // A timeout must not be reported as a running tunnel that merely lacks a heartbeat:
+        // the endpoint is recorded, but the stage says nothing is serving yet.
+        this.status = (0, TunnelLifecycle_1.createTunnelStatus)('failed', {
+            endpoint: this.status.endpoint,
+            error: this.status.error ?? 'ngrok-connect-timeout',
+        });
+        throw new Error(`ngrok connection timeout${this.status.endpoint ? ` for ${this.status.endpoint}` : ''}`);
     }
     async discoverEndpointFromAgentApi() {
         const base = this.agentApiUrl.replace(/\/+$/u, '');
-        return await readNgrokAgentEndpoint(`${base}/api/tunnels`)
-            ?? await readNgrokAgentEndpoint(`${base}/api/endpoints`);
+        return await readNgrokAgentEndpoint(`${base}/api/tunnels`, this.expectedLocalOrigin)
+            ?? await readNgrokAgentEndpoint(`${base}/api/endpoints`, this.expectedLocalOrigin);
     }
 }
 exports.NgrokTunnelProvider = NgrokTunnelProvider;
-async function readNgrokAgentEndpoint(url) {
+/** Loopback endpoints belong to the agent itself, never to a published tunnel. */
+function isLocalAgentUrl(url) {
+    try {
+        const { hostname } = new URL(url);
+        const normalized = hostname.replace(/^\[/u, '').replace(/\]$/u, '').toLowerCase();
+        return normalized === 'localhost' || normalized === '::1' || normalized.startsWith('127.');
+    }
+    catch {
+        return true;
+    }
+}
+async function readNgrokAgentEndpoint(url, expectedLocalOrigin) {
     try {
         const response = await fetch(url);
         if (!response.ok) {
             return undefined;
         }
         const body = await response.json();
-        return extractEndpointFromAgentBody(body);
+        return extractEndpointFromAgentBody(body, expectedLocalOrigin);
     }
     catch {
         return undefined;
     }
 }
-function extractEndpointFromAgentBody(body) {
+function extractEndpointFromAgentBody(body, expectedLocalOrigin) {
     if (!body || typeof body !== 'object') {
         return undefined;
     }
     const record = body;
     const lists = [record.tunnels, record.endpoints].filter(Array.isArray);
+    const candidates = [];
     for (const list of lists) {
         for (const item of list) {
             if (!item || typeof item !== 'object') {
@@ -232,12 +272,44 @@ function extractEndpointFromAgentBody(body) {
             const publicUrl = typeof value.public_url === 'string' ? value.public_url : undefined;
             const url = typeof value.url === 'string' ? value.url : undefined;
             const endpoint = normalizeEndpointForConfig(publicUrl ?? url);
-            if (endpoint?.startsWith('https://')) {
-                return endpoint;
+            if (!endpoint?.startsWith('https://') || isLocalAgentUrl(endpoint)) {
+                continue;
             }
+            const config = value.config;
+            const address = config && typeof config === 'object'
+                ? config.addr
+                : undefined;
+            candidates.push({ endpoint, ...(typeof address === 'string' ? { address } : {}) });
         }
     }
-    return undefined;
+    if (candidates.length === 0) {
+        return undefined;
+    }
+    if (!expectedLocalOrigin) {
+        return candidates[0].endpoint;
+    }
+    // An entry exposing our own origin is ours. When the agent reports no address at all we
+    // can only accept it if there is exactly one candidate, otherwise ownership is a guess.
+    const matched = candidates.find((candidate) => candidate.address
+        && normalizeOrigin(candidate.address) === normalizeOrigin(expectedLocalOrigin));
+    if (matched) {
+        return matched.endpoint;
+    }
+    return candidates.length === 1 && !candidates[0].address ? candidates[0].endpoint : undefined;
+}
+function normalizeOrigin(value) {
+    try {
+        const url = new URL(value);
+        const hostname = url.hostname.replace(/^\[/u, '').replace(/\]$/u, '').toLowerCase();
+        // `localhost`, `::1` and `127.x` are the same machine; agents spell them differently.
+        const host = hostname === 'localhost' || hostname === '::1' || hostname.startsWith('127.')
+            ? '127.0.0.1'
+            : hostname;
+        return `${url.protocol}//${host}:${url.port || (url.protocol === 'https:' ? '443' : '80')}`;
+    }
+    catch {
+        return value.trim().replace(/\/+$/u, '');
+    }
 }
 function extractEndpoint(output) {
     try {
@@ -261,10 +333,12 @@ function extractEndpointFromText(value) {
 }
 function isConnectionLine(output) {
     const lower = output.toLowerCase();
+    // A bare "started" is not evidence that a tunnel exists: the agent logs it for its own
+    // web interface as well.
     return lower.includes('started tunnel')
         || lower.includes('tunnel started')
         || lower.includes('client session established')
-        || lower.includes('started');
+        || lower.includes('started tunnel session');
 }
 function extractError(output) {
     try {

package/dist/tunnel/NgrokTunnelProvider.jsonld

@@ -124,6 +124,10 @@
           "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider__member_managedByUs",
           "memberFieldName": "managedByUs"
         },
+        {
+          "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider__member_expectedLocalOrigin",
+          "memberFieldName": "expectedLocalOrigin"
+        },
         {
           "@id": "undefineds:dist/tunnel/NgrokTunnelProvider.jsonld#NgrokTunnelProvider__member_constructor",
           "memberFieldName": "constructor"

package/dist/tunnel/SakuraFrpTunnelProvider.d.ts

@@ -4,21 +4,30 @@
  * 使用 SakuraFRP 提供隧道服务
  * 用于没有公网 IP 的 Local 节点
  *
- * 需要用户在 SakuraFRP 控制台创建隧道并获取 Token
+ * 凭据就是控制台「配置文件」里那串启动参数 (`<访问密钥>:<隧道ID>`)。公网入口
+ * **不由用户声明**：控制台只让用户选节点和本地端口，访问地址是平台分配的，因此
+ * provider 用同一个凭据向 SakuraFrp 开放 API 查询分配结果（节点地址 + 远程端口），
+ * 声明字段只作为 API 不可用时的可选兜底。
  */
 import type { TunnelProvider, TunnelConfig, TunnelSetupOptions, TunnelStatus } from './TunnelProvider';
 /**
  * SakuraFRP Tunnel Provider 配置
  */
 export interface SakuraFrpTunnelProviderOptions {
-    /** SakuraFRP Token (从环境变量 SAKURA_TUNNEL_TOKEN 获取) */
+    /** SakuraFRP 启动参数 (`<访问密钥>:<隧道ID>[,<隧道ID>...]`)，来自 SAKURA_TUNNEL_TOKEN */
     token: string;
-    /** Active profile public endpoint, shown in status and DDNS diagnostics. */
+    /** Optional declared endpoint, used only when the provider cannot be asked. */
     publicUrl?: string;
     /** frpc 可执行文件路径 (默认 'frpc') */
     frpcPath?: string;
+    /** 等待代理发布的毫秒数；超时后状态为 failed */
+    connectTimeoutMs?: number;
     /** SakuraFRP 服务端地址 (如果需要自定义) */
     serverAddr?: string;
+    /** SakuraFrp open API base, where the assigned public entry can be read back. */
+    apiBaseUrl?: string;
+    /** Injection point for tests; defaults to the global fetch. */
+    fetchImpl?: typeof fetch;
 }
 /**
  * SakuraFRP Tunnel Provider
@@ -31,12 +40,49 @@ export declare class SakuraFrpTunnelProvider implements TunnelProvider {
     private readonly token;
     private readonly publicUrl?;
     private readonly frpcPath;
+    private readonly connectTimeoutMs;
     private readonly serverAddr?;
+    private readonly apiBaseUrl;
+    private readonly fetchImpl;
+    /** Endpoint the platform assigned, once discovery has answered. */
+    private discoveredEndpoint?;
+    /** Credential actually handed to frpc, completed from the platform answer when needed. */
+    private clientCredential?;
+    /** Why no browser-facing entry can be claimed, when the platform refuses plain HTTP. */
+    private discoveryBlockedReason?;
+    /** Whether the platform terminates TLS for this entry (auto HTTPS). */
+    private autoHttpsEnabled;
+    /** Entry the client itself printed, used when the platform API cannot name one. */
+    private logEndpoint?;
     private process;
     private status;
     private currentConfig;
     private managedByUs;
     constructor(options: SakuraFrpTunnelProviderOptions);
+    /**
+     * Reads back the entry the platform assigned to this tunnel.
+     *
+     * The console never asks for a domain: for a TCP tunnel it assigns a node host and a
+     * remote port, and for a bound tunnel it assigns the domain itself. Asking the provider
+     * is therefore the only honest way to learn the entry, and a failure to ask changes
+     * nothing except that the status stops short of naming an endpoint.
+     */
+    private discoverEndpoint;
+    /**
+     * Builds the parameter frpc needs, completing a bare access key with the tunnel it owns.
+     *
+     * `-f` accepts `<访问密钥>:<隧道ID>`; an operator who pasted only the access key would
+     * otherwise get `Bad fetch parameter` even though discovery can read the tunnel with that
+     * same key. Completion is only safe when the answer is unambiguous.
+     */
+    private resolveClientCredential;
+    private resolveNodeHost;
+    private fetchJson;
+    /**
+     * The endpoint to report: what the platform assigned, else what the client printed, else
+     * what was declared. Nothing is invented when no source names an entry.
+     */
+    private currentEndpoint;
     /**
      * Setup: 解析 Token 获取配置
      */
@@ -60,3 +106,19 @@ export declare class SakuraFrpTunnelProvider implements TunnelProvider {
     private waitForConnection;
     isManagedByUs(): boolean;
 }
+/**
+ * The local port the SakuraFrp console told the tunnel to forward to.
+ *
+ * The console already owns this fact, and the provider reads the same API for the public
+ * entry, so the runtime must take the port from there instead of asking the operator to type
+ * it a second time.
+ */
+export declare function resolveSakuraAssignedLocalPort(token: string | undefined, options?: {
+    apiBaseUrl?: string;
+    fetchImpl?: typeof fetch;
+}): Promise<number | undefined>;
+/** Splits the console's startup parameter into the access key and the tunnel ids. */
+export declare function parseSakuraCredential(value: string | undefined): {
+    accessKey?: string;
+    tunnelIds: string[];
+};