@undefineds.co/xpod 0.4.12 → 0.4.14

package/config/components-ignore.json

@@ -1,30 +1,34 @@
 [
-  "Error",
+  "ActivityEmitter",
   "BaseQuintStore",
   "ClaudeAuthenticationError",
   "CliCommandError",
   "CodeBuddyAuthError",
   "DisabledSparqlFeatureError",
+  "Error",
   "InvalidRelaySessionRequestError",
   "InvalidTunnelTokenError",
   "LEGACY_DERIVED_INDEX_CONSUMER_ID",
   "LOG_FILE_PATTERN",
-  "normalizeContext",
   "NodeRouteSourceNotFoundError",
   "Omit",
   "P2PSessionExpiredError",
   "P2PSessionNotFoundError",
   "P2PSignalingRequestError",
-  "registerDeviceNotificationRuntime",
-  "resolveCurrentLogFile",
-  "resolveLogFilePattern",
   "SearchApiError",
   "SolidFsConflictError",
   "SolidFsNotFoundError",
   "SubdomainClientError",
-  "UnsupportedSparqlQueryError",
   "Uint8Array",
+  "UnsupportedSparqlQueryError",
   "VectorApiError",
   "WaitingRunnerError",
-  "ActivityEmitter"
+  "assertPublicProbeTarget",
+  "createPinnedHeadProbeRequest",
+  "createPodOwnershipNodeAccessResolver",
+  "isPublicIpAddress",
+  "normalizeContext",
+  "registerDeviceNotificationRuntime",
+  "resolveCurrentLogFile",
+  "resolveLogFilePattern"
 ]

package/dist/acceptance/QleverSemanticConformance.js

@@ -161,8 +161,15 @@ async function prepareAndApplyUpdate(engine, sparql, sourceUri, timeoutMs) {
 }
 const nativeSemanticCaseExecutor = {
     prepareAndApplyUpdate,
+    // The fixture queries a container endpoint (`DEFAULT_BASE_PATH`), and every
+    // `Pod` query that is not inside `GRAPH` reads that container plus its
+    // subgraphs. `scopedUnion` is the dataset mode the product uses for a
+    // container endpoint (`SubgraphSparqlHttpHandler`), so the native authority is
+    // exercised under the same rule as the public authority, which has no dataset
+    // switch and always reads the endpoint scope.
     query: (engine, testCase, timeoutMs) => nativeSparqlQuery(engine, testCase.query, {
         basePath: RdfSemanticConformance_1.DEFAULT_BASE_PATH,
+        defaultDataset: 'scopedUnion',
         operation: (0, RdfSemanticConformance_1.queryOperation)(testCase.acceptMediaType),
         acceptMediaType: testCase.acceptMediaType,
         timeoutMs,

package/dist/api/ai-gateway/providers/OfferingAuthorization.d.ts

@@ -3,7 +3,12 @@ export interface OfferingAuthorizationMethod {
     id: string;
     authMode: 'oauth' | 'deviceCode' | 'local' | 'apiKey';
     connectMode?: 'authorizationCodeOAuth' | 'deviceCodeOAuth' | 'browserAssistedApiKey';
-    label: string;
+    /**
+     * Wording is the applet's (`display-wording.ts` in `@undefineds.co/ai-connections`),
+     * decided from the entry's id. The gateway names the entry and says whether this
+     * deployment can offer it; it does not write the button.
+     */
+    label?: string;
     lifecycle: 'active' | 'unavailable';
     reason?: string;
 }

package/dist/api/ai-gateway/providers/OfferingAuthorization.js

@@ -12,7 +12,6 @@ function subscriptionAuthorizationMethods(deployment, binding) {
             id: 'browser-oauth',
             authMode: 'oauth',
             connectMode: 'authorizationCodeOAuth',
-            label: '浏览器登录',
             lifecycle: deployment === 'local' ? 'active' : 'unavailable',
             ...(deployment === 'local' ? {} : { reason: '浏览器登录需要本机回调，请在本机 Xpod 中使用，或选择设备码登录。' }),
         }] : [];
@@ -22,13 +21,11 @@ function subscriptionAuthorizationMethods(deployment, binding) {
             id: 'device-code',
             authMode: 'deviceCode',
             connectMode: 'deviceCodeOAuth',
-            label: '设备码登录',
             lifecycle: 'active',
         },
         {
             id: 'local-session-import',
             authMode: 'local',
-            label: '已有登录态',
             lifecycle: deployment === 'local' ? 'active' : 'unavailable',
             ...(deployment === 'local' ? {} : { reason: '请在运行本机客户端的 Xpod 上导入登录态。' }),
         },

package/dist/api/ai-gateway/providers/ProviderRegistry.js

@@ -280,7 +280,7 @@ function providerProductsForDeployment(deployment) {
             }
             else if (offering.kind === 'local') {
                 authorizationMethods.push({
-                    id: 'local-service', authMode: 'local', label: '本地服务',
+                    id: 'local-service', authMode: 'local',
                     lifecycle: offering.lifecycle === 'unavailable' ? 'unavailable' : 'active',
                 });
             }

package/dist/api/container/index.js

@@ -232,6 +232,7 @@ function loadConfigFromEnv() {
         ngrokAuthToken: process.env.NGROK_AUTHTOKEN,
         ngrokUrl: process.env.NGROK_URL,
         ngrokPath: process.env.NGROK_BIN,
+        frpcPath: process.env.FRPC_BIN,
         // Edge 节点管理 (cloud 模式)
         edgeNodesEnabled: process.env.XPOD_EDGE_NODES_ENABLED === 'true',
     };

package/dist/api/container/local.js

@@ -15,6 +15,7 @@ const NgrokTunnelProvider_1 = require("../../tunnel/NgrokTunnelProvider");
 const SakuraFrpTunnelProvider_1 = require("../../tunnel/SakuraFrpTunnelProvider");
 const DEFAULT_CLOUD_API_ENDPOINT = 'https://api.undefineds.co';
 const CloudflareDnsProvider_1 = require("../../dns/cloudflare/CloudflareDnsProvider");
+const TencentDnsProvider_1 = require("../../dns/tencent/TencentDnsProvider");
 const SubdomainService_1 = require("../../subdomain/SubdomainService");
 const EdgeNodeDnsCoordinator_1 = require("../../edge/EdgeNodeDnsCoordinator");
 const EdgeNodeCapabilityDetector_1 = require("../../edge/EdgeNodeCapabilityDetector");
@@ -27,7 +28,7 @@ const PodLookupRepository_1 = require("../../identity/drizzle/PodLookupRepositor
  */
 function registerLocalServices(container) {
     const config = container.resolve('config');
-    const { cloudApiEndpoint, nodeId, nodeToken, cloudflareTunnelToken, sakuraTunnelToken, ngrokAuthToken, ngrokUrl, ngrokPath, subdomain: subdomainConfig, } = config;
+    const { cloudApiEndpoint, nodeId, nodeToken, cloudflareTunnelToken, sakuraTunnelToken, ngrokAuthToken, ngrokUrl, ngrokPath, frpcPath, subdomain: subdomainConfig, } = config;
     container.register({
         podLookupRepo: (0, awilix_1.asFunction)(({ db }) => {
             return new PodLookupRepository_1.PodLookupRepository(db);
@@ -42,11 +43,17 @@ function registerLocalServices(container) {
         ngrokUrl,
     });
     const activeTunnelProvider = activeTunnel.provider;
+    // The settings page stores one credential per profile; the provider-global env key is
+    // only the legacy fallback. Without this the profile's own secret never reached the
+    // provider and the tunnel could not start even though the profile looked configured.
+    const activeCredential = activeTunnel.profile?.credentialEnvKey
+        ? readCredential(process.env[activeTunnel.profile.credentialEnvKey])
+        : undefined;
     if (activeTunnelProvider === 'ngrok') {
         container.register({
             localTunnelProvider: (0, awilix_1.asFunction)(() => {
                 return new NgrokTunnelProvider_1.NgrokTunnelProvider({
-                    authtoken: ngrokAuthToken,
+                    authtoken: activeCredential ?? ngrokAuthToken,
                     url: activeTunnel.profile?.publicUrl ?? ngrokUrl,
                     ngrokPath,
                 });
@@ -58,7 +65,7 @@ function registerLocalServices(container) {
         container.register({
             localTunnelProvider: (0, awilix_1.asFunction)(() => {
                 return new LocalTunnelProvider_1.LocalTunnelProvider({
-                    tunnelToken: cloudflareTunnelToken,
+                    tunnelToken: (activeCredential ?? cloudflareTunnelToken),
                     publicUrl: activeTunnel.profile?.publicUrl,
                 });
             }).singleton(),
@@ -69,8 +76,9 @@ function registerLocalServices(container) {
         container.register({
             localTunnelProvider: (0, awilix_1.asFunction)(() => {
                 return new SakuraFrpTunnelProvider_1.SakuraFrpTunnelProvider({
-                    token: sakuraTunnelToken,
+                    token: (activeCredential ?? sakuraTunnelToken),
                     publicUrl: activeTunnel.profile?.publicUrl,
+                    frpcPath,
                 });
             }).singleton(),
         });
@@ -81,8 +89,8 @@ function registerLocalServices(container) {
     const apiToken = subdomainConfig?.cloudflareApiToken;
     // 在 Local 模式下，强制使用 CSS_BASE_URL 作为域名来源
     // 简化用户配置心智
-    let baseDomain;
-    if (process.env.CSS_BASE_URL) {
+    let baseDomain = process.env.XPOD_DNS_DOMAIN?.trim() || undefined;
+    if (!baseDomain && process.env.CSS_BASE_URL) {
         try {
             const url = new URL(process.env.CSS_BASE_URL);
             baseDomain = url.hostname;
@@ -93,14 +101,20 @@ function registerLocalServices(container) {
     }
     // DEBUG: 打印变量状态
     console.log(`[Local] Debug: apiToken=${apiToken ? '***' : 'undefined'}, baseDomain=${baseDomain}, CSS_BASE_URL=${process.env.CSS_BASE_URL}`);
-    if (apiToken && baseDomain) {
-        console.log('[Local] Self-hosted DNS mode detected (IPv6 Ready)');
+    // The settings page lets an operator pick the DNS provider, so the runtime honours that
+    // choice instead of always wiring Cloudflare and ignoring a saved "tencent".
+    const dnsProviderId = process.env.XPOD_DNS_PROVIDER?.trim().toLowerCase() || 'cloudflare';
+    const tencentDnsToken = process.env.XPOD_TENCENT_DNS_TOKEN?.trim();
+    const tencentDnsTokenId = process.env.XPOD_TENCENT_DNS_TOKEN_ID?.trim();
+    const dnsCredentialReady = dnsProviderId === 'tencent' ? Boolean(tencentDnsToken) : Boolean(apiToken);
+    if (dnsCredentialReady && baseDomain) {
+        console.log(`[Local] Self-hosted DNS mode detected (provider: ${dnsProviderId})`);
         container.register({
-            // DNS Provider
+            // DNS Provider: one axis, the selected implementation.
             dnsProvider: (0, awilix_1.asFunction)(() => {
-                return new CloudflareDnsProvider_1.CloudflareDnsProvider({
-                    apiToken: apiToken,
-                });
+                return dnsProviderId === 'tencent'
+                    ? new TencentDnsProvider_1.TencentDnsProvider({ tokenId: tencentDnsTokenId, token: tencentDnsToken })
+                    : new CloudflareDnsProvider_1.CloudflareDnsProvider({ apiToken: apiToken });
             }).singleton(),
             // DNS Coordinator (DnsMaintainer)
             dnsCoordinator: (0, awilix_1.asFunction)(({ dnsProvider }) => {
@@ -230,6 +244,10 @@ function resolveActiveLocalTunnel(options) {
         }),
     };
 }
+/** A credential only counts when it actually carries a value. */
+function readCredential(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
 function resolveLocalTunnelProvider(options) {
     const explicit = options.explicit?.trim().toLowerCase();
     if (explicit) {

package/dist/api/container/routes.js

@@ -33,6 +33,7 @@ exports.resolveCloudSignalApiUrl = resolveCloudSignalApiUrl;
 exports.resolveLocalStorageProviderBaseUrl = resolveLocalStorageProviderBaseUrl;
 const EdgeNodeSignalHandler_1 = require("../handlers/EdgeNodeSignalHandler");
 const ReachabilityHandler_1 = require("../handlers/ReachabilityHandler");
+const NodeAccessResolver_1 = require("../../edge/reachability/NodeAccessResolver");
 const NodeHandler_1 = require("../handlers/NodeHandler");
 const ChatHandler_1 = require("../handlers/ChatHandler");
 const SubdomainHandler_1 = require("../handlers/SubdomainHandler");
@@ -162,6 +163,7 @@ function registerSharedRoutes(container, server) {
         repository: nodeRepo,
         baseStorageDomain: config.subdomain?.baseStorageDomain,
         apiBaseUrl: config.cloudApiEndpoint ?? process.env.CSS_BASE_URL,
+        canAccessNode: (0, NodeAccessResolver_1.createPodOwnershipNodeAccessResolver)(podLookupRepository),
     });
     (0, NodeHandler_1.registerNodeRoutes)(server, { repository: nodeRepo });
     const aiGatewayService = container.resolve('aiGatewayService');

package/dist/api/container/types.d.ts

@@ -183,6 +183,8 @@ export interface ApiContainerConfig {
     ngrokUrl?: string;
     /** ngrok executable path. */
     ngrokPath?: string;
+    /** frpc executable path (FRPC_BIN); the SakuraFrp build is required, not the generic one. */
+    frpcPath?: string;
     /** 是否接受 Edge 节点注册 (cloud 模式) */
     edgeNodesEnabled?: boolean;
 }

package/dist/api/handlers/AdminHandler.d.ts

@@ -40,7 +40,23 @@ export declare function createAdminServicesCapabilities(req: AuthenticatedReques
     };
 };
 export declare function readDurableAdminEnvironment(): Record<string, string>;
-export declare function writeDurableAdminEnvironmentPatch(input: Record<string, string>): void;
+/**
+ * Tunnel profiles exactly as the runtime resolved them.
+ *
+ * `credentialEnvKey` is the profile-scoped key when one is configured, so a caller can
+ * write a secret where the runtime will actually read it.
+ */
+export declare function projectTunnelProfiles(): Array<{
+    id: string;
+    provider: string;
+    label?: string;
+    publicUrl?: string;
+    credentialEnvKey?: string;
+    credentialConfigured: boolean;
+    active: boolean;
+    parameters?: Record<string, string>;
+}>;
+export declare function writeDurableAdminEnvironmentPatch(input: Record<string, string>, removals?: string[]): void;
 /**
  * Why a coordinated public domain cannot be served, or `null` when nothing
  * rules it out.

package/dist/api/handlers/AdminHandler.js

@@ -15,6 +15,7 @@ exports.sanitizeLogMessage = sanitizeLogMessage;
 exports.isAdminMutationAllowed = isAdminMutationAllowed;
 exports.createAdminServicesCapabilities = createAdminServicesCapabilities;
 exports.readDurableAdminEnvironment = readDurableAdminEnvironment;
+exports.projectTunnelProfiles = projectTunnelProfiles;
 exports.writeDurableAdminEnvironmentPatch = writeDurableAdminEnvironmentPatch;
 exports.describeUnservedPublicRoute = describeUnservedPublicRoute;
 exports.registerAdminRoutes = registerAdminRoutes;
@@ -25,6 +26,8 @@ const fs_2 = require("fs");
 const readline_1 = require("readline");
 const runtime_1 = require("../../runtime");
 const log_file_1 = require("../../logging/log-file");
+const TunnelProviderCatalog_1 = require("../../tunnel/TunnelProviderCatalog");
+const TunnelProfiles_1 = require("../../tunnel/TunnelProfiles");
 const GatewayAdminProxyAuth_1 = require("../../runtime/GatewayAdminProxyAuth");
 const CONFIG_DIR = path_1.default.resolve(runtime_1.PACKAGE_ROOT, 'config');
 function getEnvFilePath() {
@@ -110,7 +113,7 @@ function sanitizeEnvForRead(env) {
 function createAllowedAdminConfigPatch(input) {
     const patch = {};
     for (const [key, value] of Object.entries(input)) {
-        if (!ALLOWED_ADMIN_CONFIG_KEY_SET.has(key)) {
+        if (!ALLOWED_ADMIN_CONFIG_KEY_SET.has(key) && !(0, TunnelProviderCatalog_1.isTunnelProfileCredentialEnvKey)(key)) {
             continue;
         }
         if (isAdminSecretEnvKey(key) && !value) {
@@ -248,11 +251,40 @@ function writeEnvFile(filePath, config) {
 function readDurableAdminEnvironment() {
     return readEnvFile(getEnvFilePath());
 }
-function writeDurableAdminEnvironmentPatch(input) {
+/**
+ * Tunnel profiles exactly as the runtime resolved them.
+ *
+ * `credentialEnvKey` is the profile-scoped key when one is configured, so a caller can
+ * write a secret where the runtime will actually read it.
+ */
+function projectTunnelProfiles() {
+    const state = (0, TunnelProfiles_1.resolveTunnelProfileState)(process.env);
+    return state.profiles.map((profile) => ({
+        id: profile.id,
+        provider: profile.provider,
+        ...(profile.label ? { label: profile.label } : {}),
+        ...(profile.publicUrl ? { publicUrl: profile.publicUrl } : {}),
+        ...(profile.credentialEnvKey ? { credentialEnvKey: profile.credentialEnvKey } : {}),
+        credentialConfigured: profile.credentialConfigured === true,
+        active: state.activeProfile?.id === profile.id,
+        // Served to the console so an edit there cannot silently erase parameters the settings
+        // page wrote.
+        ...(profile.parameters ? { parameters: profile.parameters } : {}),
+    }));
+}
+function writeDurableAdminEnvironmentPatch(input, removals = []) {
     const filePath = getEnvFilePath();
     const current = readEnvFile(filePath);
     const patch = createAllowedAdminConfigPatch(input);
-    writeEnvFile(filePath, { ...current, ...patch });
+    const next = { ...current, ...patch };
+    // Deleting a profile has to delete its credential: an empty secret value is filtered
+    // out of the patch (see createAllowedAdminConfigPatch), so removals are explicit.
+    for (const key of removals) {
+        if (ALLOWED_ADMIN_CONFIG_KEY_SET.has(key) || (0, TunnelProviderCatalog_1.isTunnelProfileCredentialEnvKey)(key)) {
+            delete next[key];
+        }
+    }
+    writeEnvFile(filePath, next);
 }
 /**
  * List available config files
@@ -411,6 +443,11 @@ function registerAdminRoutes(server, options = {}) {
             sendJson(res, 200, {
                 ...sanitizeEnvForRead(env),
                 configFiles: listConfigFiles(),
+                // Operator pages render the same provider axis the runtime honours.
+                providers: TunnelProviderCatalog_1.TUNNEL_PROVIDERS,
+                // Profiles as the runtime resolved them, including the credential key that belongs
+                // to each profile: the operator console must not invent its own key naming.
+                tunnelProfiles: projectTunnelProfiles(),
             });
         }
         catch (error) {

package/dist/api/handlers/EdgeNodeSignalHandler.js

@@ -44,8 +44,14 @@ function registerEdgeNodeSignalRoutes(server, options) {
             let metadata = mergeMetadata(existing?.metadata ?? {}, payload, now);
             // 从 DB connectivity 列注入 subdomain/ipv4，供 dnsCoordinator 使用
             const connectivityInfo = await repo.getNodeConnectivityInfo(nodeId);
+            // The subdomain a node may publish is assigned by the control plane, never by the
+            // node itself: a heartbeat must not be able to retarget another node's record.
+            delete metadata.subdomain;
+            if (isRecord(metadata.dns)) {
+                metadata.dns = Object.fromEntries(Object.entries(metadata.dns).filter(([key]) => key !== 'subdomain'));
+            }
             if (connectivityInfo) {
-                if (connectivityInfo.subdomain && !metadata.subdomain) {
+                if (connectivityInfo.subdomain) {
                     metadata.subdomain = connectivityInfo.subdomain;
                 }
                 if (connectivityInfo.ipv4 && !metadata.ipv4) {
@@ -78,7 +84,9 @@ function registerEdgeNodeSignalRoutes(server, options) {
                 }
             }
             if (dnsCoordinator) {
-                await dnsCoordinator.synchronize(nodeId, metadata);
+                // The control plane decides which subdomain this node owns; the coordinator gets
+                // that assignment explicitly instead of reading it back out of node metadata.
+                await dnsCoordinator.synchronize(nodeId, metadata, { subdomain: connectivityInfo?.subdomain });
             }
             logger.debug(`Signal received from node ${nodeId}`);
             sendJson(response, 200, {

package/dist/api/handlers/NetworkSettingsHandler.d.ts

@@ -1,6 +1,7 @@
 import { getLoggerFor } from 'global-logger-factory';
 import type { ApiServer } from '../ApiServer';
 import type { AuthContext } from '../auth/AuthContext';
+import { type TunnelProviderDescriptor } from '../../tunnel/TunnelProviderCatalog';
 export interface NetworkSettingsStatus {
     endpoint: string;
     addresses: {
@@ -22,6 +23,21 @@ export interface NetworkSettingsStatus {
         renewCertificate: boolean;
     };
     configuration?: NetworkDesiredConfiguration;
+    /**
+     * The provider axis, served so the settings page renders the same declaration the
+     * runtime honours instead of keeping its own list.
+     */
+    providers?: readonly TunnelProviderDescriptor[];
+    /**
+     * The address a remote tunnel must forward to.
+     *
+     * Remotely-managed tunnels dial a port the operator typed into a provider console, so the
+     * page shows this value to copy rather than making the operator guess it.
+     */
+    ingress?: {
+        port: number;
+        originUrl: string;
+    };
 }
 export interface NetworkDesiredConfiguration {
     domainDns: {
@@ -51,12 +67,17 @@ export interface NetworkDesiredConfiguration {
 }
 export interface NetworkTunnelProfile {
     id: string;
-    provider: 'ngrok' | 'cloudflare' | 'frp';
+    provider: string;
     label: string;
-    publicEndpoint?: string;
+    publicUrl?: string;
     credentialConfigured: boolean;
     parameters?: Record<string, string>;
 }
+/** `publicEndpoint` is the field older settings clients sent; `publicUrl` is canonical. */
+export type NetworkTunnelProfilePatch = Omit<NetworkTunnelProfile, 'credentialConfigured'> & {
+    credential?: string;
+    publicEndpoint?: string;
+};
 export type NetworkConfigurationPatch = {
     domainDns?: Partial<Omit<NetworkDesiredConfiguration['domainDns'], 'credentialConfigured'>> & {
         credential?: string;
@@ -64,9 +85,7 @@ export type NetworkConfigurationPatch = {
     https?: Partial<NetworkDesiredConfiguration['https']>;
     tunnelProfiles?: {
         activeProfileId?: string;
-        profiles?: Array<Omit<NetworkTunnelProfile, 'credentialConfigured'> & {
-            credential?: string;
-        }>;
+        profiles?: NetworkTunnelProfilePatch[];
     };
     p2p?: Partial<NetworkDesiredConfiguration['p2p']>;
 };
@@ -77,6 +96,12 @@ export interface NetworkConfigurationStore {
 export interface CapabilityStatus {
     supported: boolean;
     status: string;
+    /** Readiness stage of the provider, when the provider reports one. */
+    stage?: string;
+    /** Endpoint the provider actually observed; distinct from a declared/configured address. */
+    endpoint?: string;
+    /** Redacted reason for a non-active status; absent when there is nothing to explain. */
+    detail?: string;
 }
 export type DiagnosticStatus = 'ok' | 'warning' | 'error' | 'unsupported';
 export interface NetworkDiagnosticCheckResult {
@@ -138,6 +163,13 @@ export interface NetworkSettingsHandlerOptions {
     internalAdminAuthSecret?: string;
     logger?: Pick<ReturnType<typeof getLoggerFor>, 'warn' | 'error'>;
 }
+/** The ingress address this runtime listens on, when it published one. */
+export declare function readIngressAddress(env?: NodeJS.ProcessEnv): {
+    ingress?: {
+        port: number;
+        originUrl: string;
+    };
+};
 export declare function registerNetworkSettingsRoutes(server: ApiServer, options: NetworkSettingsHandlerOptions): void;
 export declare function createDeploymentNetworkSettingsAuthorizer(options?: NetworkSettingsIdentityAuthorizerOptions): NetworkSettingsAuthorizer;
 export declare function createAddressReaders(input: {

package/dist/api/handlers/NetworkSettingsHandler.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.readIngressAddress = readIngressAddress;
 exports.registerNetworkSettingsRoutes = registerNetworkSettingsRoutes;
 exports.createDeploymentNetworkSettingsAuthorizer = createDeploymentNetworkSettingsAuthorizer;
 exports.createAddressReaders = createAddressReaders;
@@ -13,6 +14,15 @@ const node_os_1 = require("node:os");
 const global_logger_factory_1 = require("global-logger-factory");
 const readBoundedJsonBody_1 = require("../http/readBoundedJsonBody");
 const AdminHandler_1 = require("./AdminHandler");
+const TunnelProviderCatalog_1 = require("../../tunnel/TunnelProviderCatalog");
+/** The ingress address this runtime listens on, when it published one. */
+function readIngressAddress(env = process.env) {
+    const port = Number.parseInt(env.XPOD_GATEWAY_INGRESS_PORT ?? '', 10);
+    if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+        return {};
+    }
+    return { ingress: { port, originUrl: `http://127.0.0.1:${port}` } };
+}
 function registerNetworkSettingsRoutes(server, options) {
     const logger = options.logger ?? (0, global_logger_factory_1.getLoggerFor)('NetworkSettingsHandler');
     const authorizer = options.authorizer ?? createDeploymentNetworkSettingsAuthorizer();
@@ -23,7 +33,12 @@ function registerNetworkSettingsRoutes(server, options) {
         try {
             const status = await readNetworkStatus(options, logger);
             const configuration = await options.configurationStore?.read();
-            sendJson(response, 200, configuration ? { ...status, configuration } : status);
+            sendJson(response, 200, {
+                ...status,
+                providers: TunnelProviderCatalog_1.TUNNEL_PROVIDERS,
+                ...readIngressAddress(),
+                ...(configuration ? { configuration } : {}),
+            });
         }
         catch (error) {
             logger.error(`Failed to read network settings status: ${redactSecretText(error)}`);
@@ -134,11 +149,16 @@ function parseNetworkConfigurationPatch(value) {
     return value;
 }
 function validTunnelProfile(value) {
-    if (!isPlainRecord(value) || hasUnknownKeys(value, ['id', 'provider', 'label', 'publicEndpoint', 'credential', 'parameters']))
+    // `publicUrl` is canonical; `publicEndpoint` is what older clients sent.
+    if (!isPlainRecord(value) || hasUnknownKeys(value, ['id', 'provider', 'label', 'publicUrl', 'publicEndpoint', 'credential', 'parameters']))
         return false;
     if (typeof value.id !== 'string' || !value.id.trim() || typeof value.label !== 'string' || !value.label.trim())
         return false;
-    if (!['ngrok', 'cloudflare', 'frp'].includes(String(value.provider)) || !optionalString(value.publicEndpoint) || !optionalString(value.credential))
+    if (!(0, TunnelProviderCatalog_1.isTunnelProviderId)(value.provider) || !optionalString(value.publicUrl) || !optionalString(value.publicEndpoint) || !optionalString(value.credential))
+        return false;
+    // A provider the local runtime cannot start must be refused here rather than stored and
+    // reported as "configured" while nothing can ever come up.
+    if ((0, TunnelProviderCatalog_1.tunnelProviderDescriptor)(value.provider)?.runtimeSupported === false)
         return false;
     return value.parameters === undefined || (isPlainRecord(value.parameters) && Object.values(value.parameters).every((item) => typeof item === 'string'));
 }
@@ -205,16 +225,20 @@ function createTunnelStatusReader(tunnelProvider) {
     return {
         read: async () => {
             const status = tunnelProvider.getStatus();
+            const detail = status.error ? redactSecretText(status.error) : undefined;
+            const observed = typeof status.endpoint === 'string' && status.endpoint ? { endpoint: status.endpoint } : {};
+            const stage = status.stage ? { stage: status.stage } : {};
             if (status.connected) {
-                return { supported: true, status: 'active' };
+                return { supported: true, status: 'active', ...stage, ...observed };
             }
             if (status.running) {
-                return { supported: true, status: 'starting' };
+                // A running process is not a published proxy: say which stage it reached.
+                return { supported: true, status: 'starting', ...stage, ...observed };
             }
-            if (status.error) {
-                return { supported: true, status: 'error' };
+            if (detail) {
+                return { supported: true, status: 'error', ...stage, ...observed, detail };
             }
-            return { supported: true, status: 'inactive' };
+            return { supported: true, status: 'inactive', ...observed };
         },
     };
 }
@@ -302,11 +326,15 @@ function safeAddressList(reader, logger) {
 function buildDefaultDiagnostics(options, logger) {
     return [
         {
-            id: 'endpoint',
-            label: 'Endpoint',
+            // This check only proves that an address is configured. Reachability is a different
+            // fact and needs a real probe, so the result must not be rendered as one.
+            id: 'address-configuration',
+            label: 'Address configuration',
             run: async () => {
                 const endpoint = normalizeEndpoint(resolveValue(options.endpoint));
-                return endpoint ? { status: 'ok', detail: endpoint } : { status: 'unsupported', detail: 'endpoint_unavailable' };
+                return endpoint
+                    ? { status: 'ok', detail: `configured: ${endpoint}` }
+                    : { status: 'unsupported', detail: 'endpoint_unavailable' };
             },
         },
         {

package/dist/api/handlers/ProvisionHandler.d.ts

@@ -18,7 +18,7 @@ import type { EdgeNodeRepository } from '../../identity/drizzle/EdgeNodeReposito
 import type { ServiceTokenRepositoryPort } from '../../identity/drizzle/ServiceTokenRepository';
 import type { DdnsRepository } from '../../identity/drizzle/DdnsRepository';
 import type { DnsProvider } from '../../dns/DnsProvider';
-import type { TunnelProvider } from '../../tunnel/TunnelProvider';
+import type { TunnelProvider, TunnelConfig } from '../../tunnel/TunnelProvider';
 export interface ProvisionHandlerOptions {
     repository: EdgeNodeRepository;
     ddnsRepo?: DdnsRepository;
@@ -38,6 +38,11 @@ export interface ProvisionHandlerOptions {
     serviceTokenRepository?: ServiceTokenRepositoryPort;
 }
 export declare function registerProvisionRoutes(server: ApiServer, options: ProvisionHandlerOptions): void;
+export declare function readManagedTunnelConfig(metadata: Record<string, unknown> | null): {
+    subdomain?: string;
+    localPort?: number;
+    config: TunnelConfig;
+} | undefined;
 /**
  * Local 端 SP 状态查询路由
  */

package/dist/api/handlers/ProvisionHandler.js

@@ -16,10 +16,12 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerProvisionRoutes = registerProvisionRoutes;
+exports.readManagedTunnelConfig = readManagedTunnelConfig;
 exports.registerProvisionStatusRoute = registerProvisionStatusRoute;
 exports.createLocalSetupProvisionStateWriter = createLocalSetupProvisionStateWriter;
 const node_crypto_1 = require("node:crypto");
 const global_logger_factory_1 = require("global-logger-factory");
+const TunnelProviderCatalog_1 = require("../../tunnel/TunnelProviderCatalog");
 const ProvisionCodeCodec_1 = require("../../provision/ProvisionCodeCodec");
 const ServiceAccessTokenCodec_1 = require("../../provision/ServiceAccessTokenCodec");
 const LocalProvisionState_1 = require("../../provision/LocalProvisionState");
@@ -421,7 +423,10 @@ function readManagedTunnelConfig(metadata) {
     const tunnelId = value.tunnelId;
     const subdomain = typeof value.subdomain === 'string' ? value.subdomain : undefined;
     const localPort = typeof value.localPort === 'number' ? value.localPort : undefined;
-    if ((provider !== 'cloudflare' && provider !== 'frp' && provider !== 'sakura-frp')
+    // Provision callers historically spell Sakura with a hyphen; the catalogue owns the
+    // canonical id, so accept either spelling and store one.
+    const canonicalProvider = (0, TunnelProviderCatalog_1.parseTunnelProvider)(provider);
+    if ((canonicalProvider !== 'cloudflare' && canonicalProvider !== 'frp' && canonicalProvider !== 'sakura_frp')
         || typeof endpoint !== 'string') {
         return undefined;
     }
@@ -429,7 +434,7 @@ function readManagedTunnelConfig(metadata) {
         subdomain,
         localPort,
         config: {
-            provider,
+            provider: canonicalProvider,
             subdomain: subdomain ?? 'local',
             endpoint,
             tunnelId: typeof tunnelId === 'string' ? tunnelId : undefined,

package/dist/api/handlers/ReachabilityHandler.d.ts

@@ -9,5 +9,11 @@ export interface ReachabilityHandlerOptions {
     maxActiveP2PSessionsPerNode?: number;
     maxP2PCandidatesPerUpdate?: number;
     maxP2PCandidatesPerSession?: number;
+    /**
+     * Whether a Solid principal may act on a node, e.g. through Pod ownership or an
+     * explicit grant. Absent means "cannot prove access", which denies instead of
+     * handing an unrelated WebID signaling access to the node.
+     */
+    canAccessNode?: (nodeId: string, webId: string) => Promise<boolean> | boolean;
 }
 export declare function registerReachabilityRoutes(server: ApiServer, options: ReachabilityHandlerOptions): void;