@undefineds.co/xpod 0.4.20 → 0.4.27

package/dist/storage/rdf/RdfAccessScope.js

@@ -16,10 +16,10 @@ exports.RdfAccessMode = {
 };
 function isRestrictiveRdfAccessScope(scope) {
     return Boolean(scope
-        && ((scope.allowedGraphUrls?.length ?? 0) > 0
+        && (scope.allowedGraphUrls !== undefined
             || (scope.deniedGraphUrls?.length ?? 0) > 0
             || (scope.deniedGraphPrefixes?.length ?? 0) > 0
-            || (scope.allowedSourceUrls?.length ?? 0) > 0
+            || scope.allowedSourceUrls !== undefined
             || (scope.deniedSourceUrls?.length ?? 0) > 0
             || (scope.deniedSourcePrefixes?.length ?? 0) > 0));
 }
@@ -46,7 +46,7 @@ function applyRdfAccessScope(query, scope) {
         return query;
     }
     const state = {
-        impossibleGraph: n3_1.DataFactory.namedNode('urn:xpod:rdf-access-denied'),
+        impossibleGraph: { $in: [] },
     };
     const scoped = applyScopeToQuery(query, scope, state);
     return {
@@ -82,7 +82,7 @@ function rdfAccessGraphAllowed(graph, scope) {
     if (!graph.startsWith(scope.basePath)) {
         return false;
     }
-    if (scope.allowedGraphUrls?.length && !scope.allowedGraphUrls.includes(graph)) {
+    if (scope.allowedGraphUrls !== undefined && !scope.allowedGraphUrls.includes(graph)) {
         return false;
     }
     if (scope.deniedGraphUrls?.includes(graph)) {
@@ -92,7 +92,11 @@ function rdfAccessGraphAllowed(graph, scope) {
 }
 function applyScopeToQuery(query, scope, state) {
     const rootFilters = [...(query.filters ?? [])];
-    const patterns = (query.patterns ?? []).map((pattern) => scopePattern(pattern, rootFilters, scope, state));
+    const hasOtherSource = Boolean(query.values?.length || query.textSearch?.length || query.vectorSearch?.length || query.unions?.length);
+    // Engines interpret an otherwise empty root as an implicit all-facts pattern.
+    // Make that pattern explicit before applying permissions, never after them.
+    const rootPatterns = query.patterns?.length || hasOtherSource ? query.patterns ?? [] : [{}];
+    const patterns = rootPatterns.map((pattern) => scopePattern(pattern, rootFilters, scope, state));
     return {
         ...query,
         patterns,
@@ -152,8 +156,7 @@ function scopeExistsGroup(group, scope, state) {
 }
 function scopeOptionalGroup(group, scope, state) {
     if (Array.isArray(group)) {
-        const ignoredFilters = [];
-        return group.map((pattern) => scopePattern(pattern, ignoredFilters, scope, state));
+        return scopeOptionalGroup({ patterns: group }, scope, state);
     }
     const filters = [...(group.filters ?? [])];
     return {
@@ -168,6 +171,9 @@ function scopeOptionalGroup(group, scope, state) {
 }
 function scopePattern(pattern, filters, scope, state) {
     const sourceScope = scopeFactSources(pattern.sourceScope, scope);
+    if (scope.allowedGraphUrls?.length === 0) {
+        return { ...pattern, graph: state.impossibleGraph, ...(sourceScope ? { sourceScope } : {}) };
+    }
     const requested = pattern.graph;
     // A container IRI names a container, not a graph: asking for it asks for that
     // container and its subgraphs (LDP containment). The trailing slash is what
@@ -197,8 +203,11 @@ function scopePattern(pattern, filters, scope, state) {
             if (defaultGraphSourceScope === false) {
                 return { ...pattern, graph: state.impossibleGraph, ...(sourceScope ? { sourceScope } : {}) };
             }
-            return scope.allowedGraphUrls?.length
-                ? { ...pattern, graph: state.impossibleGraph, ...(sourceScope ? { sourceScope } : {}) }
+            return scope.allowedGraphUrls !== undefined
+                ? { ...pattern,
+                    graph: scopeGraphOperators({ $startsWith: scope.basePath }, scope, state.impossibleGraph),
+                    ...(defaultGraphSourceScope ? { sourceScope: defaultGraphSourceScope } : {}),
+                }
                 : { ...pattern, ...(defaultGraphSourceScope ? { sourceScope: defaultGraphSourceScope } : {}) };
         }
         return rdfAccessGraphAllowed(graph.value, scope)
@@ -235,9 +244,9 @@ function scopeGraphOperators(graph, scope, impossibleGraph) {
     if (prefix) {
         operators.$startsWith = prefix;
     }
-    if (scope.allowedGraphUrls?.length) {
+    if (scope.allowedGraphUrls !== undefined) {
         const allowedTerms = scope.allowedGraphUrls
-            .filter((url) => graphOperatorsMayMatch(operators, url))
+            .filter((url) => rdfAccessGraphAllowed(url, scope) && graphOperatorsMayMatch(operators, url))
             .map((url) => n3_1.DataFactory.namedNode(url));
         if (allowedTerms.length === 0) {
             return impossibleGraph;
@@ -278,7 +287,7 @@ function addGraphAccessFilters(filters, variable, scope) {
         operator: '$startsWith',
         value: scope.basePath,
     });
-    if (scope.allowedGraphUrls?.length) {
+    if (scope.allowedGraphUrls !== undefined) {
         filters.push({
             variable,
             operator: '$in',
@@ -352,12 +361,8 @@ function scopeFactSources(existing, scope) {
     const prefix = existing?.sourcePrefix;
     const deniedPrefixes = nonEmptyStrings(unionStringArrays(existing?.deniedSourcePrefixes, scope.deniedSourcePrefixes));
     const deniedSources = nonEmptyStrings(unionStringArrays(existing?.deniedSources, scope.deniedSourceUrls));
-    // An empty access-scope allow-list means that no source restriction was
-    // resolved. An explicitly empty pattern sourceScope remains fail-closed via
-    // existing?.allowedSources.
-    const allowedFromScope = scope.allowedSourceUrls?.length
-        ? scope.allowedSourceUrls
-        : undefined;
+    // Undefined means no source restriction; an explicitly empty list grants none.
+    const allowedFromScope = scope.allowedSourceUrls;
     const allowedSources = filterStringsByPrefix(intersectStringArrays(existing?.allowedSources, allowedFromScope), prefix);
     const hasAllowedRestriction = existing?.allowedSources !== undefined || allowedFromScope !== undefined;
     if (!existing

package/dist/supervisor/Supervisor.d.ts

@@ -1,10 +1,20 @@
+import { type LogLevel } from '../logging/normalize-log';
 import type { ServiceConfig, ServiceState, ServiceStatus, StatusChangeHandler } from './types';
 export interface SupervisorLog {
     timestamp: string;
-    level: 'info' | 'warn' | 'error';
+    level: LogLevel;
     source: string;
     message: string;
 }
+export interface SupervisorOptions {
+    handleProcessSignals?: boolean;
+    /** Consecutive failed runs tolerated before giving up. */
+    maxRestarts?: number;
+    /** First restart delay; doubles per consecutive failure up to 60s. */
+    restartBaseDelayMs?: number;
+    /** Uptime that counts as a healthy run and resets the failure streak. */
+    healthyUptimeMs?: number;
+}
 export declare class Supervisor {
     private processes;
     private managedStops;
@@ -13,16 +23,20 @@ export declare class Supervisor {
     private logs;
     private onStatusChange?;
     private isShuttingDown;
-    constructor(options?: {
-        handleProcessSignals?: boolean;
-    });
+    private childOutput;
+    private pendingRestarts;
+    private intentionalStops;
+    private readonly maxRestarts;
+    private readonly restartBaseDelayMs;
+    private readonly healthyUptimeMs;
+    constructor(options?: SupervisorOptions);
     private shutdown;
     private killAll;
     setStatusChangeHandler(handler: StatusChangeHandler): void;
     register(config: ServiceConfig): void;
     registerManaged(name: string, stop?: () => Promise<void> | void): void;
     setStatus(name: string, status: ServiceStatus, extra?: Partial<ServiceState>): void;
-    addLog(source: string, level: SupervisorLog['level'], message: string): void;
+    addLog(source: string, level: SupervisorLog['level'], message: string): SupervisorLog;
     getLogs(filters?: {
         level?: string;
         source?: string;
@@ -31,6 +45,16 @@ export declare class Supervisor {
     startAll(): Promise<void>;
     stopAll(): Promise<void>;
     start(name: string): void;
+    /**
+     * Stop restarting a service and say why. The gateway must not keep advertising itself as
+     * healthy afterwards: readiness derives from supervised state, not from HTTP reachability.
+     */
+    private giveUp;
+    /**
+     * Readiness of the supervised set: every configured child must be running. Managed services
+     * (for example the gateway itself) are lifecycle-owned elsewhere and are not required here.
+     */
+    isReady(): boolean;
     stop(name: string): Promise<void>;
     restart(name: string): Promise<boolean>;
     getStatus(name: string): ServiceState | undefined;

package/dist/supervisor/Supervisor.js

@@ -6,8 +6,33 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Supervisor = void 0;
 const node_child_process_1 = require("node:child_process");
 const tree_kill_1 = __importDefault(require("tree-kill"));
+const normalize_log_1 = require("../logging/normalize-log");
+const log_secrets_1 = require("../logging/log-secrets");
 const MAX_RESTARTS = 5;
 const MAX_LOGS = 500;
+/** Restart backoff: 2s, 4s, 8s, 16s, 32s, capped at 60s. */
+const RESTART_BASE_DELAY_MS = 2_000;
+const RESTART_MAX_DELAY_MS = 60_000;
+/** A run that stays up this long counts as healthy and clears the failure streak. */
+const HEALTHY_UPTIME_MS = 60_000;
+/** Bounded tail of child output kept per service for crash diagnosis. */
+const MAX_CHILD_OUTPUT_LINES = 20;
+/**
+ * Failures that cannot be fixed by retrying: the child's own runtime cannot resolve a module,
+ * so every restart fails identically. Retrying only hides the breakage behind a healthy-looking
+ * gateway, which is exactly how the audited instance stayed half-dead for hours (N20).
+ */
+const NON_RETRYABLE_PATTERNS = [
+    { pattern: /Cannot find package ['"][^'"]+['"]/u, reason: 'missing dependency (Cannot find package)' },
+    { pattern: /Cannot find module ['"][^'"]+['"]/u, reason: 'missing module (Cannot find module)' },
+    { pattern: /\bMODULE_NOT_FOUND\b/u, reason: 'missing module (MODULE_NOT_FOUND)' },
+];
+/** Mask credentials before child output is stored in supervisor state or served over HTTP. */
+function redactSecrets(line) {
+    return line
+        .replace(/([A-Za-z0-9_]*(?:token|secret|password|passwd|api[_-]?key|credential)[A-Za-z0-9_]*)(\s*[:=]\s*)("[^"]*"|'[^']*'|\S+)/giu, (_match, key, separator) => `${key}${separator}***`)
+        .replace(/\b([Bb]earer)\s+[A-Za-z0-9\-._~+/=]{8,}/gu, '$1 ***');
+}
 class Supervisor {
     constructor(options = {}) {
         this.processes = new Map();
@@ -16,6 +41,12 @@ class Supervisor {
         this.configs = new Map();
         this.logs = [];
         this.isShuttingDown = false;
+        this.childOutput = new Map();
+        this.pendingRestarts = new Map();
+        this.intentionalStops = new Set();
+        this.maxRestarts = options.maxRestarts ?? MAX_RESTARTS;
+        this.restartBaseDelayMs = options.restartBaseDelayMs ?? RESTART_BASE_DELAY_MS;
+        this.healthyUptimeMs = options.healthyUptimeMs ?? HEALTHY_UPTIME_MS;
         if (options.handleProcessSignals === false) {
             return;
         }
@@ -80,15 +111,18 @@ class Supervisor {
         });
     }
     addLog(source, level, message) {
-        this.logs.push({
+        const normalized = (0, normalize_log_1.normalizeLog)(message, level);
+        const entry = {
             timestamp: new Date().toISOString(),
-            level,
+            level: normalized.level,
             source,
-            message,
-        });
+            message: (0, log_secrets_1.redactConfiguredLogSecrets)(redactSecrets(normalized.message), process.env),
+        };
+        this.logs.push(entry);
         if (this.logs.length > MAX_LOGS) {
             this.logs.splice(0, this.logs.length - MAX_LOGS);
         }
+        return entry;
     }
     getLogs(filters) {
         let rows = this.logs;
@@ -111,6 +145,10 @@ class Supervisor {
     }
     async stopAll() {
         this.isShuttingDown = true;
+        for (const [name, timer] of this.pendingRestarts) {
+            clearTimeout(timer);
+            this.pendingRestarts.delete(name);
+        }
         const promises = [];
         for (const name of this.processes.keys()) {
             promises.push(this.stop(name));
@@ -129,9 +167,16 @@ class Supervisor {
             return;
         if (state.status === 'running' || state.status === 'starting')
             return;
+        const pendingRestart = this.pendingRestarts.get(name);
+        if (pendingRestart) {
+            clearTimeout(pendingRestart);
+            this.pendingRestarts.delete(name);
+        }
+        this.intentionalStops.delete(name);
+        this.childOutput.set(name, []);
         console.log(`[Supervisor] Starting ${name}...`);
         this.addLog(name, 'info', 'Service starting');
-        this.updateState(name, { status: 'starting', startTime: Date.now() });
+        this.updateState(name, { status: 'starting', startTime: Date.now(), givenUpReason: undefined });
         const env = config.env ?? process.env;
         const child = (0, node_child_process_1.spawn)(config.command, config.args, {
             stdio: ['ignore', 'pipe', 'pipe'],
@@ -141,6 +186,16 @@ class Supervisor {
         });
         this.processes.set(name, child);
         this.updateState(name, { status: 'running', pid: child.pid });
+        const recordOutput = (line) => {
+            const tail = this.childOutput.get(name);
+            if (!tail) {
+                return;
+            }
+            tail.push(line);
+            if (tail.length > MAX_CHILD_OUTPUT_LINES) {
+                tail.splice(0, tail.length - MAX_CHILD_OUTPUT_LINES);
+            }
+        };
         const prefixLog = (source, data, isError = false) => {
             const output = data.toString();
             const lines = output.split('\n');
@@ -149,13 +204,16 @@ class Supervisor {
                 if (!trimmed) {
                     continue;
                 }
+                // Redact once, at the single point where child output enters supervisor state:
+                // the console, the log ring buffer (served by /service/logs) and the retained
+                // crash tail must not disagree about what the child printed.
+                const { message: text } = this.addLog(source, isError ? 'error' : 'info', trimmed);
+                recordOutput(text);
                 if (isError) {
-                    console.error(`[${source}] ${trimmed}`);
-                    this.addLog(source, 'error', trimmed);
+                    console.error(`[${source}] ${text}`);
                 }
                 else {
-                    console.log(`[${source}] ${trimmed}`);
-                    this.addLog(source, 'info', trimmed);
+                    console.log(`[${source}] ${text}`);
                 }
             }
         };
@@ -168,44 +226,94 @@ class Supervisor {
         child.on('error', (err) => {
             console.error(`[Supervisor] Error spawning ${name}:`, err);
             this.addLog(name, 'error', `Spawn error: ${String(err)}`);
-            this.updateState(name, { status: 'crashed' });
+            this.updateState(name, { status: 'crashed', givenUpReason: `Spawn error: ${String(err)}` });
         });
         child.on('exit', (code, signal) => {
+            const exitedAt = Date.now();
+            const stateBeforeExit = this.states.get(name);
+            const uptimeMs = stateBeforeExit?.startTime ? exitedAt - stateBeforeExit.startTime : 0;
+            const wasManualStop = stateBeforeExit?.status === 'stopped' || this.intentionalStops.has(name);
+            const wasHealthy = uptimeMs >= this.healthyUptimeMs;
+            const consecutiveFailures = wasHealthy ? 0 : (stateBeforeExit?.consecutiveFailures ?? 0) + 1;
+            const outputTail = this.childOutput.get(name) ?? [];
+            const nonRetryable = NON_RETRYABLE_PATTERNS.find(({ pattern }) => outputTail.some((line) => pattern.test(line)));
             console.log(`[Supervisor] ${name} exited with code ${code} signal ${signal}`);
             this.addLog(name, code === 0 ? 'info' : 'error', `Exited with code ${code ?? 'null'} signal ${signal ?? 'null'}`);
-            const currentState = this.states.get(name);
-            const wasManualStop = currentState?.status === 'stopped';
+            this.processes.delete(name);
+            this.childOutput.delete(name);
+            this.intentionalStops.delete(name);
             this.updateState(name, {
                 status: 'stopped',
                 lastExitCode: code ?? undefined,
+                lastExitAt: exitedAt,
+                lastOutput: outputTail,
+                consecutiveFailures,
                 pid: undefined,
             });
-            this.processes.delete(name);
-            // Auto-restart on crash (not on manual stop or shutdown)
-            if (code !== 0 && !wasManualStop && !this.isShuttingDown) {
-                const newState = this.states.get(name);
-                const restartCount = (newState?.restartCount || 0) + 1;
-                if (restartCount <= MAX_RESTARTS) {
-                    this.updateState(name, { restartCount });
-                    console.log(`[Supervisor] Restarting ${name} in 2s... (attempt ${restartCount}/${MAX_RESTARTS})`);
-                    this.addLog(name, 'warn', `Restarting in 2s (attempt ${restartCount}/${MAX_RESTARTS})`);
-                    setTimeout(() => this.start(name), 2000);
-                }
-                else {
-                    console.error(`[Supervisor] ${name} exceeded max restarts (${MAX_RESTARTS}), giving up`);
-                    this.addLog(name, 'error', `Exceeded max restarts (${MAX_RESTARTS})`);
-                }
+            // Auto-restart on crash (not on clean exit, manual stop or shutdown)
+            if (code === 0 || wasManualStop || this.isShuttingDown) {
+                return;
+            }
+            if (nonRetryable) {
+                this.giveUp(name, `Unrecoverable child failure: ${nonRetryable.reason}; restart suppressed`, consecutiveFailures);
+                return;
             }
+            if (consecutiveFailures > this.maxRestarts) {
+                this.giveUp(name, `Exceeded max restarts (budget ${this.maxRestarts}, ${consecutiveFailures} consecutive failures)`, consecutiveFailures);
+                return;
+            }
+            const delay = Math.min(this.restartBaseDelayMs * 2 ** (consecutiveFailures - 1), RESTART_MAX_DELAY_MS);
+            this.updateState(name, { restartCount: (stateBeforeExit?.restartCount ?? 0) + 1 });
+            const attempt = `(${consecutiveFailures}/${this.maxRestarts} consecutive failures)`;
+            console.log(`[Supervisor] Restarting ${name} in ${delay}ms... ${attempt}`);
+            this.addLog(name, 'warn', `Restarting in ${Math.round(delay / 1000)}s ${attempt}`);
+            const timer = setTimeout(() => {
+                this.pendingRestarts.delete(name);
+                this.start(name);
+            }, delay);
+            this.pendingRestarts.set(name, timer);
         });
     }
+    /**
+     * Stop restarting a service and say why. The gateway must not keep advertising itself as
+     * healthy afterwards: readiness derives from supervised state, not from HTTP reachability.
+     */
+    giveUp(name, reason, consecutiveFailures) {
+        console.error(`[Supervisor] ${name}: ${reason}`);
+        this.addLog(name, 'error', `Giving up on ${name}: ${reason}`);
+        this.updateState(name, { status: 'given-up', givenUpReason: reason, consecutiveFailures });
+    }
+    /**
+     * Readiness of the supervised set: every configured child must be running. Managed services
+     * (for example the gateway itself) are lifecycle-owned elsewhere and are not required here.
+     */
+    isReady() {
+        for (const name of this.configs.keys()) {
+            if (this.states.get(name)?.status !== 'running') {
+                return false;
+            }
+        }
+        return true;
+    }
     stop(name) {
         return new Promise((resolve) => {
+            const pendingRestart = this.pendingRestarts.get(name);
+            if (pendingRestart) {
+                // A service waiting out its backoff is not running, but it is not stopped either:
+                // cancel the timer so a stop request cannot be undone by a scheduled restart.
+                clearTimeout(pendingRestart);
+                this.pendingRestarts.delete(name);
+            }
             const child = this.processes.get(name);
             if (!child || !child.pid) {
+                if (this.states.has(name)) {
+                    this.updateState(name, { status: 'stopped', pid: undefined, givenUpReason: undefined });
+                }
                 resolve();
                 return;
             }
             // Mark as stopped first to prevent auto-restart
+            this.intentionalStops.add(name);
             this.updateState(name, { status: 'stopped' });
             this.addLog(name, 'info', 'Stopping service');
             (0, tree_kill_1.default)(child.pid, 'SIGTERM', (err) => {
@@ -230,6 +338,8 @@ class Supervisor {
             this.addLog(name, 'error', 'Timed out waiting for service to stop before restart');
             return false;
         }
+        // An explicit restart follows a deliberate operator action: grant a fresh retry budget.
+        this.updateState(name, { consecutiveFailures: 0, givenUpReason: undefined });
         this.addLog(name, 'info', 'Service restart requested');
         this.start(name);
         return true;

package/dist/supervisor/types.d.ts

@@ -6,7 +6,12 @@ export interface ServiceConfig {
     cwd?: string;
     readyUrl?: string;
 }
-export type ServiceStatus = 'stopped' | 'starting' | 'running' | 'crashed';
+/**
+ * `given-up` means the supervisor stopped restarting the child on purpose (unrecoverable
+ * failure or exhausted retries). It is distinct from `stopped` (intentional stop) and
+ * `crashed` (spawn failed) because a given-up child never returns without operator action.
+ */
+export type ServiceStatus = 'stopped' | 'starting' | 'running' | 'crashed' | 'given-up';
 export interface ServiceState {
     name: string;
     status: ServiceStatus;
@@ -14,6 +19,14 @@ export interface ServiceState {
     startTime?: number;
     uptime?: number;
     lastExitCode?: number;
+    /** Epoch millis of the last child exit, so a stale crash can be told apart from a live one. */
+    lastExitAt?: number;
     restartCount: number;
+    /** Consecutive failed runs; a run that stayed up long enough clears it. */
+    consecutiveFailures?: number;
+    /** Bounded, redacted tail of the child's own output, for diagnosing a crash without shell access. */
+    lastOutput?: string[];
+    /** Why the supervisor stopped restarting this service (set while status is `given-up`). */
+    givenUpReason?: string;
 }
 export type StatusChangeHandler = (name: string, state: ServiceState) => void;

package/dist/test-utils/local-managed-client-p2p-e2e-smoke.js

@@ -66,9 +66,24 @@ async function runLocalManagedClientP2PE2ESmoke(options = {}) {
                 nodeId,
                 baseUrl: `https://${nodeId}.${baseStorageDomain}/`,
             });
+            // The node serves many sessions on one socket, so it resolves the per-session data plane
+            // secret from the signaling API on handshake (audit N03). A session without a secret is
+            // refused there, which is why the smoke client always creates one.
+            const dataPlaneSignaling = (0, reachability_1.createP2PSignalingClient)({
+                apiBaseUrl: signalApi.baseUrl,
+                nodeId,
+                token: nodeToken,
+            });
             const dataPlaneServer = (0, reachability_1.createTcpP2PDataPlaneServer)({
                 handler: (0, reachability_1.createP2PDataPlaneHandler)({ targetBaseUrl: target.baseUrl }),
                 host: p2pHost,
+                secure: {
+                    role: 'server',
+                    resolveSessionSecret: async (sessionId) => {
+                        const session = await dataPlaneSignaling.getP2PSession(sessionId);
+                        return session.dataPlaneSecret;
+                    },
+                },
             });
             await dataPlaneServer.listen(0);
             nodePlan = {

package/dist/tunnel/LocalTunnelProvider.d.ts

@@ -10,6 +10,8 @@ export interface LocalTunnelProviderOptions {
     publicUrl?: string;
     /** cloudflared 可执行文件路径 (默认 'cloudflared') */
     cloudflaredPath?: string;
+    /** Environment used to resolve the client binary; injectable for tests. */
+    env?: Record<string, string | undefined>;
     /** 等待代理发布的毫秒数；超时后状态为 failed，而不是"仍在连接" */
     connectTimeoutMs?: number;
 }
@@ -96,6 +98,11 @@ export declare class LocalTunnelProvider implements TunnelProvider {
  *
  * 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.
+ *
+ * cloudflared logs the configuration it fetched as an escaped JSON string inside one log line
+ * (`config="{\"ingress\":[{\"service\":\"http://localhost:5737\"}]}"`), so the quotes around
+ * the JSON keys arrive backslash-escaped. Unescaping first is what makes this read-back work
+ * against a real connector; a line where the JSON is not escaped is still accepted.
  */
 export declare function readDashboardOrigin(output: string): {
     scheme: string;

package/dist/tunnel/LocalTunnelProvider.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LocalTunnelProvider = void 0;
 exports.readDashboardOrigin = readDashboardOrigin;
+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");
@@ -32,7 +33,8 @@ class LocalTunnelProvider {
         this.managedByUs = false;
         this.tunnelToken = options.tunnelToken;
         this.publicUrl = normalizePublicEndpoint(options.publicUrl);
-        this.cloudflaredPath = options.cloudflaredPath ?? 'cloudflared';
+        this.cloudflaredPath = options.cloudflaredPath
+            ?? (0, TunnelClientResolver_1.resolveTunnelClient)('cloudflare', { env: options.env }).command;
         this.connectTimeoutMs = options.connectTimeoutMs ?? 30_000;
     }
     /**
@@ -345,10 +347,16 @@ function normalizePublicEndpoint(value) {
  *
  * 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.
+ *
+ * cloudflared logs the configuration it fetched as an escaped JSON string inside one log line
+ * (`config="{\"ingress\":[{\"service\":\"http://localhost:5737\"}]}"`), so the quotes around
+ * the JSON keys arrive backslash-escaped. Unescaping first is what makes this read-back work
+ * against a real connector; a line where the JSON is not escaped is still accepted.
  */
 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);
+    const unescaped = output.includes('\\"') ? output.replace(/\\"/gu, '"') : output;
+    const match = /"service"\s*:\s*"(https?):\/\/(?:localhost|127\.0\.0\.1):(\d+)/iu.exec(unescaped)
+        ?? /ingress[^\n]*service["']?\s*[:=]\s*["']?(https?):\/\/(?:localhost|127\.0\.0\.1):(\d+)/iu.exec(unescaped);
     if (!match) {
         return undefined;
     }

package/dist/tunnel/LocalTunnelProvider.jsonld

@@ -44,6 +44,30 @@
           },
           "comment": "cloudflared 可执行文件路径 (默认 'cloudflared')"
         },
+        {
+          "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider_options_env",
+          "range": {
+            "@type": "ParameterRangeCollectEntries",
+            "parameterRangeCollectEntriesParameters": [
+              {
+                "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider_options_env_key"
+              },
+              {
+                "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider_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/LocalTunnelProvider.jsonld#LocalTunnelProvider_options_connectTimeoutMs",
           "range": {
@@ -178,6 +202,21 @@
                 "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider_options_cloudflaredPath"
               }
             },
+            {
+              "keyRaw": "env",
+              "value": {
+                "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider_options_env__constructorArgument",
+                "fields": [
+                  {
+                    "collectEntries": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider_options_env",
+                    "key": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider_options_env_key",
+                    "value": {
+                      "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider_options_env_value"
+                    }
+                  }
+                ]
+              }
+            },
             {
               "keyRaw": "connectTimeoutMs",
               "value": {

package/dist/tunnel/NgrokTunnelProvider.d.ts

@@ -6,6 +6,8 @@ export interface NgrokTunnelProviderOptions {
     url?: string;
     /** ngrok executable path. */
     ngrokPath?: string;
+    /** Environment used to resolve the client binary; injectable for tests. */
+    env?: Record<string, string | undefined>;
     /** ngrok local Agent API, used to discover generated dev domains. */
     agentApiUrl?: string;
     /** Startup wait timeout. */

package/dist/tunnel/NgrokTunnelProvider.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NgrokTunnelProvider = void 0;
 exports.isLocalAgentUrl = isLocalAgentUrl;
+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,8 @@ class NgrokTunnelProvider {
         this.managedByUs = false;
         this.authtoken = options.authtoken;
         this.configuredUrl = normalizeEndpointForCli(options.url);
-        this.ngrokPath = options.ngrokPath ?? 'ngrok';
+        this.ngrokPath = options.ngrokPath
+            ?? (0, TunnelClientResolver_1.resolveTunnelClient)('ngrok', { env: options.env }).command;
         this.agentApiUrl = options.agentApiUrl ?? 'http://127.0.0.1:4040';
         this.connectTimeoutMs = options.connectTimeoutMs ?? 30_000;
     }