@undefineds.co/xpod 0.4.13 → 0.4.15

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/AiGatewayManagementHandler.d.ts

@@ -6,6 +6,7 @@ import type { ProviderConnectService } from '../ai-gateway/connect';
 import type { ProviderModelSelectionService } from '../ai-gateway/models/ProviderModelSelectionService';
 import type { ProviderQuotaService } from '../ai-gateway/quota';
 import { type ProviderCustomModelsService, type ProviderModelsService } from '../ai-gateway/models';
+import type { PodInterfaceKeyGrant } from '../ai-gateway/pod/PodInterfaceKeyStore';
 import type { AiConnectionsInvocationKeyIssuer } from '../ai-gateway/auth/AiConnectionsInvocationKeyIssuer';
 import { type AiClientConfigurationCapabilityDescriptor } from '../service/AiClientConfigurationService';
 export interface AiGatewayManagementHandlerOptions {
@@ -25,6 +26,11 @@ export interface AiGatewayManagementHandlerOptions {
     gatewayAccessKeyRepository?: GatewayAccessKeyRepository;
     /** Reuses the configured CSS authenticator; never trusts the claimed registration owner. */
     validateClientCredential?: (apiKey: string) => Promise<AuthResult>;
+    /**
+     * Server-side Pod access for the owner. The wrapper being registered is the owner's own
+     * interface key, so registering it is also the moment Xpod is granted its use.
+     */
+    podInterfaceKeys?: PodInterfaceKeyGrant;
     aiClientConfiguration?: AiClientConfigurationCapabilityDescriptor;
     aiConnectionInvocationKeyIssuer?: Pick<AiConnectionsInvocationKeyIssuer, 'issue' | 'issueClientConfiguration'>;
     jsonBodyLimitBytes?: number;

package/dist/api/handlers/AiGatewayManagementHandler.js

@@ -5,8 +5,10 @@ const node_crypto_1 = require("node:crypto");
 const global_logger_factory_1 = require("global-logger-factory");
 const readBoundedJsonBody_1 = require("../http/readBoundedJsonBody");
 const GatewayPrincipal_1 = require("../ai-gateway/auth/GatewayPrincipal");
+const AuthContext_1 = require("../auth/AuthContext");
 const models_1 = require("../ai-gateway/models");
 const AiConnectionsServiceAccess_1 = require("../ai-gateway/service-access/AiConnectionsServiceAccess");
+const OwnerPodAccess_1 = require("../ai-gateway/pod/OwnerPodAccess");
 const AiClientConfigurationService_1 = require("../service/AiClientConfigurationService");
 const errors_1 = require("../ai-gateway/errors");
 const EmbeddingModelPolicy_1 = require("../../ai/service/EmbeddingModelPolicy");
@@ -117,6 +119,15 @@ function registerAiGatewayManagementRoutes(server, options) {
                 sendJson(response, 403, { error: 'CSS client credential belongs to another WebID' });
                 return;
             }
+            if ((0, AuthContext_1.hasSolidClientCredentialsAuthority)(verified.context)) {
+                // Sealed before the record is written, because writing the record is the first thing
+                // that needs it: background components reach this Pod through the standard interface
+                // as the owner, never through the caller's network position.
+                await options.podInterfaceKeys?.saveKey(owner, {
+                    clientId: verified.context.clientId,
+                    clientSecret: verified.context.clientSecret,
+                });
+            }
             const name = normalizeOptionalString(body.name) ?? 'Xpod API Key';
             const keyId = repository.createKeyId(owner, options.deployment);
             const createdAt = new Date();
@@ -1329,7 +1340,7 @@ function sendCredentialPoolError(response, error) {
 }
 function sendGatewayAccessKeyError(response, error) {
     const message = error instanceof Error ? error.message : String(error);
-    if (message === 'service_access_missing') {
+    if ((0, OwnerPodAccess_1.isPodAccessFailure)(message)) {
         sendJson(response, 403, { error: 'service_access_missing' });
         return;
     }
@@ -1465,9 +1476,11 @@ function sendModelSelectionError(response, error) {
         model_selection_exact_update_failed: { status: 409, error: 'model_selection_conflict' },
         model_selection_provider_update_failed: { status: 409, error: 'model_selection_conflict' },
         service_access_missing: { status: 403, error: 'service_access_missing' },
-        hosted_pod_auth_required: { status: 401, error: 'authentication_required' },
-        hosted_pod_solid_principal_required: { status: 403, error: 'solid_principal_required' },
-        hosted_pod_owner_mismatch: { status: 403, error: 'pod_owner_mismatch' },
+        pod_interface_key_missing: { status: 403, error: 'service_access_missing' },
+        pod_interface_key_rejected: { status: 403, error: 'service_access_missing' },
+        caller_dpop_replay_unsupported: { status: 403, error: 'service_access_missing' },
+        caller_owner_mismatch: { status: 403, error: 'pod_owner_mismatch' },
+        caller_pod_access_unavailable: { status: 401, error: 'authentication_required' },
     };
     const mapped = stable[message];
     if (mapped) {

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,20 @@ export interface NetworkSettingsHandlerOptions {
     internalAdminAuthSecret?: string;
     logger?: Pick<ReturnType<typeof getLoggerFor>, 'warn' | 'error'>;
 }
+/** The ingress address this runtime listens on, when it published one. */
+/**
+ * The address a provider console is configured with: the Gateway's tunnel entry.
+ *
+ * It is the listener that never treats a caller as local, so a tunnel reaching the runtime
+ * through it cannot inherit local trust whatever headers it carries. The banner the user
+ * copies is this one number; the Gateway's own port is what they type in a browser.
+ */
+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,22 @@ 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. */
+/**
+ * The address a provider console is configured with: the Gateway's tunnel entry.
+ *
+ * It is the listener that never treats a caller as local, so a tunnel reaching the runtime
+ * through it cannot inherit local trust whatever headers it carries. The banner the user
+ * copies is this one number; the Gateway's own port is what they type in a browser.
+ */
+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 +40,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 +156,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 +232,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 +333,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/PodSettingsHandler.d.ts

@@ -2,7 +2,7 @@ import { getLoggerFor } from 'global-logger-factory';
 import type { ApiServer } from '../ApiServer';
 import type { PodLookupRepository } from '../../identity/drizzle/PodLookupRepository';
 import type { UsageRepository } from '../../storage/quota/UsageRepository';
-import type { InternalPodAccessTokenProvider } from '../ai-gateway/pod/HostedPodDataAccess';
+import type { PodAccessFetchProvider } from '../ai-gateway/pod/OwnerPodAccess';
 export interface PodSettingsStatus {
     identity: {
         webId: string;
@@ -57,10 +57,10 @@ export interface PodSettingsHandlerOptions {
 }
 export declare function registerPodSettingsRoutes(server: ApiServer, options: PodSettingsHandlerOptions): void;
 export declare class DrizzlePodAiConnectionsStatusReader implements PodAiConnectionsStatusReader {
-    private readonly internalPodAccess?;
+    private readonly podAccess?;
     private readonly deployment;
     private readonly dbFactory;
-    constructor(internalPodAccess?: InternalPodAccessTokenProvider | undefined, deployment?: string, dbFactory?: (input: {
+    constructor(podAccess?: PodAccessFetchProvider | undefined, deployment?: string, dbFactory?: (input: {
         webId: string;
         podUrl: string;
         fetch: typeof fetch;

package/dist/api/handlers/PodSettingsHandler.js

@@ -77,13 +77,13 @@ async function readStorageStatus(usageRepo, pod) {
     };
 }
 class DrizzlePodAiConnectionsStatusReader {
-    constructor(internalPodAccess, deployment = 'local', dbFactory = createAiConnectionsStatusDb) {
-        this.internalPodAccess = internalPodAccess;
+    constructor(podAccess, deployment = 'local', dbFactory = createAiConnectionsStatusDb) {
+        this.podAccess = podAccess;
         this.deployment = deployment;
         this.dbFactory = dbFactory;
     }
     async read({ webId, podUrl }) {
-        const trustedFetch = await this.internalPodAccess?.getTrustedFetch(webId);
+        const trustedFetch = await this.podAccess?.getPodFetch(webId);
         if (!trustedFetch) {
             return { status: 'unsupported', reason: 'not_configured' };
         }

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

@@ -14,11 +14,12 @@
  *   返回 SP 配置状态，供 Linx 查询
  */
 import type { ApiServer } from '../ApiServer';
+import type { AccessRoute } from '../../edge/reachability/types';
 import type { EdgeNodeRepository } from '../../identity/drizzle/EdgeNodeRepository';
 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 +39,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 状态查询路由
  */
@@ -62,6 +68,25 @@ export interface ProvisionStatusOptions {
     cloudBaseUrl?: string;
     /** provisionCode（可选，由环境变量传入） */
     provisionCode?: string;
+    /**
+     * Live state of the public route, read per request.
+     *
+     * A configured tunnel is not the same thing as a reachable public route, and a
+     * node whose tunnel is down still owns a canonical URL that same-machine
+     * clients reach over the loopback access route (`docs/multi-channel-access.md`).
+     * Clients need to tell those apart before they decide whether a canonical
+     * request can leave the machine, so this is reported rather than implied.
+     */
+    readPublicRoute?: () => PublicRouteStatus | Promise<PublicRouteStatus>;
+    /**
+     * Every access point this node can currently prove it offers, read per request.
+     *
+     * A canonical URL is one identity reachable over several physical paths, and
+     * only the client knows which path it is standing on, so the runtime reports
+     * the paths themselves (canonical public route, tunnel, ...) instead of picking
+     * one for the client (`docs/multi-channel-access.md`).
+     */
+    readAccessRoutes?: () => AccessRoute[] | Promise<AccessRoute[]>;
     /** Persist refreshed local-only setup state to the single local setup file. */
     persistState?: (state: ProvisionStatusStateUpdate) => Promise<void> | void;
     /** 测试/调试注入 */
@@ -69,6 +94,15 @@ export interface ProvisionStatusOptions {
     now?: () => number;
     refreshGraceSeconds?: number;
 }
+/** What a client can learn about reaching this node's canonical URL from outside. */
+export interface PublicRouteStatus {
+    /** A tunnel provider is configured for this node. */
+    configured: boolean;
+    /** The provider confirmed a proxy-ready public route. */
+    available: boolean;
+    provider?: string;
+    endpoint?: string;
+}
 export interface ProvisionStatusStateUpdate {
     nodeId: string;
     nodeToken: string;

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,
@@ -437,6 +442,21 @@ function readManagedTunnelConfig(metadata) {
         },
     };
 }
+/**
+ * Only the facts a client needs to rank and use an access point are reported:
+ * where it points, how it is reached and whether it is currently known to work.
+ */
+function reportableAccessRoutes(routes) {
+    return (routes ?? []).map((route) => ({
+        id: route.id,
+        kind: route.kind,
+        targetUrl: route.targetUrl,
+        priority: route.priority,
+        requiresManagedClient: route.requiresManagedClient,
+        visibility: route.visibility,
+        health: route.health,
+    }));
+}
 function registerProvisionStatusRoute(server, options) {
     const logger = (0, global_logger_factory_1.getLoggerFor)('ProvisionStatusHandler');
     const fetchImpl = options.fetchImpl ?? fetch;
@@ -474,6 +494,37 @@ function registerProvisionStatusRoute(server, options) {
             body.cloudUrl = options.cloudUrl;
             body.oidcIssuer = normalizeUrl(options.cloudBaseUrl);
         }
+        // Whether the canonical URL is reachable from outside is a separate fact
+        // from whether it exists. A failed read is reported as unavailable, never as
+        // available, because guessing here would send a same-machine client to a
+        // public route that does not answer.
+        if (options.readPublicRoute) {
+            let publicRoute;
+            try {
+                publicRoute = await options.readPublicRoute();
+            }
+            catch (error) {
+                logger.warn(`Failed to read public route state: ${error}`);
+            }
+            body.publicRoute = {
+                configured: Boolean(publicRoute?.configured),
+                available: Boolean(publicRoute?.available),
+                ...(publicRoute?.provider ? { provider: publicRoute.provider } : {}),
+                ...(publicRoute?.endpoint ? { endpoint: publicRoute.endpoint } : {}),
+            };
+        }
+        // Access points are reported as data: which one is best depends on where the
+        // client stands, which only the client knows.
+        if (options.readAccessRoutes) {
+            let routes;
+            try {
+                routes = await options.readAccessRoutes();
+            }
+            catch (error) {
+                logger.warn(`Failed to read access routes: ${error}`);
+            }
+            body.routes = reportableAccessRoutes(routes);
+        }
         if (registered) {
             const canRefresh = canRefreshProvisionStatus(options, state);
             const currentNow = now();

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;