@undefineds.co/xpod 0.4.14 → 0.4.16

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

@@ -25,6 +25,12 @@ export interface AiGatewayManagementHandlerOptions {
     gatewayAccessKeyRepository?: GatewayAccessKeyRepository;
     /** Reuses the configured CSS authenticator; never trusts the claimed registration owner. */
     validateClientCredential?: (apiKey: string) => Promise<AuthResult>;
+    /**
+     * Forget sessions cached for a client whose registration is gone. Revocation happens at the
+     * issuer, so deleting the record is the moment this process learns the credential must stop
+     * being accepted - without it a revoked API Key keeps working until its token expires.
+     */
+    invalidateClientCredential?: (clientId: string) => void;
     aiClientConfiguration?: AiClientConfigurationCapabilityDescriptor;
     aiConnectionInvocationKeyIssuer?: Pick<AiConnectionsInvocationKeyIssuer, 'issue' | 'issueClientConfiguration'>;
     jsonBodyLimitBytes?: number;

package/dist/api/handlers/AiGatewayManagementHandler.js

@@ -7,6 +7,7 @@ const readBoundedJsonBody_1 = require("../http/readBoundedJsonBody");
 const GatewayPrincipal_1 = require("../ai-gateway/auth/GatewayPrincipal");
 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 +118,10 @@ function registerAiGatewayManagementRoutes(server, options) {
                 sendJson(response, 403, { error: 'CSS client credential belongs to another WebID' });
                 return;
             }
+            // Registering an application is about that application's own credential - where it is in
+            // effect, and how to revoke it. Background Pod access is a separate, explicit grant the user
+            // makes where they manage index/embedding work (`POST /api/ai/task-credentials`), so nothing
+            // about it is written here.
             const name = normalizeOptionalString(body.name) ?? 'Xpod API Key';
             const keyId = repository.createKeyId(owner, options.deployment);
             const createdAt = new Date();
@@ -202,6 +207,9 @@ function registerAiGatewayManagementRoutes(server, options) {
             // This removes the saved client configuration only. The Account host
             // revokes CSS credentials before requesting this companion cleanup.
             await repository.delete(record.id, { auth: request.auth });
+            if (record.clientCredentialId) {
+                options.invalidateClientCredential?.(record.clientCredentialId);
+            }
             sendJson(response, 200, {
                 deleted: true,
                 record: publicGatewayAccessKeyRecord(record, false),
@@ -1329,7 +1337,8 @@ 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)) {
+        logger.warn(`Gateway API Key operation refused: ${(0, AiClientConfigurationService_1.redactSecretText)(message)}`);
         sendJson(response, 403, { error: 'service_access_missing' });
         return;
     }
@@ -1465,9 +1474,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/ChatKitHandler.js

@@ -11,6 +11,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerChatKitRoutes = registerChatKitRoutes;
 const global_logger_factory_1 = require("global-logger-factory");
 const AuthContext_1 = require("../auth/AuthContext");
+const PodAccessFailureResponse_1 = require("./PodAccessFailureResponse");
 /**
  * Register ChatKit routes on the API server
  */
@@ -56,6 +57,10 @@ function registerChatKitRoutes(server, options) {
             }
         }
         catch (error) {
+            // A Pod this process cannot open is the caller's state to fix, not an internal failure.
+            if (!response.headersSent && (0, PodAccessFailureResponse_1.sendPodAccessFailure)(response, error)) {
+                return;
+            }
             logger.error(`ChatKit request failed: ${error}`);
             if (!response.headersSent) {
                 sendJsonError(response, 500, 'internal_error', error.message || 'Internal server error');

package/dist/api/handlers/ChatKitV1Handler.js

@@ -14,6 +14,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerChatKitV1Routes = registerChatKitV1Routes;
 const types_1 = require("../chatkit/types");
 const AuthContext_1 = require("../auth/AuthContext");
+const PodAccessFailureResponse_1 = require("./PodAccessFailureResponse");
 function registerChatKitV1Routes(server, options) {
     const { store } = options;
     const buildContext = (request) => {
@@ -22,7 +23,7 @@ function registerChatKitV1Routes(server, options) {
         return { userId, auth };
     };
     // GET /v1/chatkit/threads
-    server.get('/v1/chatkit/threads', async (request, response) => {
+    server.get('/v1/chatkit/threads', (0, PodAccessFailureResponse_1.guardPodAccessRoute)(async (request, response) => {
         const url = new URL(request.url ?? '', `http://${request.headers.host}`);
         const limit = parseOptionalInt(url.searchParams.get('limit')) ?? 20;
         const after = url.searchParams.get('after') ?? undefined;
@@ -35,9 +36,9 @@ function registerChatKitV1Routes(server, options) {
             has_more: page.has_more,
             after: page.after,
         });
-    });
+    }));
     // GET /v1/chatkit/threads/:thread_id
-    server.get('/v1/chatkit/threads/:thread_id', async (request, response, params) => {
+    server.get('/v1/chatkit/threads/:thread_id', (0, PodAccessFailureResponse_1.guardPodAccessRoute)(async (request, response, params) => {
         const threadRef = getThreadRefFromRequest(request, response, params.thread_id);
         if (!threadRef) {
             return;
@@ -54,9 +55,9 @@ function registerChatKitV1Routes(server, options) {
                 data: items.data.map((it) => ({ ...it, object: 'chatkit.thread_item' })),
             },
         });
-    });
+    }));
     // DELETE /v1/chatkit/threads/:thread_id
-    server.delete('/v1/chatkit/threads/:thread_id', async (request, response, params) => {
+    server.delete('/v1/chatkit/threads/:thread_id', (0, PodAccessFailureResponse_1.guardPodAccessRoute)(async (request, response, params) => {
         const threadRef = getThreadRefFromRequest(request, response, params.thread_id);
         if (!threadRef) {
             return;
@@ -64,9 +65,9 @@ function registerChatKitV1Routes(server, options) {
         await store.deleteThread(threadRef, buildContext(request));
         // OpenAI style: return a success object (keep simple)
         sendJson(response, 200, { success: true });
-    });
+    }));
     // GET /v1/chatkit/threads/:thread_id/items
-    server.get('/v1/chatkit/threads/:thread_id/items', async (request, response, params) => {
+    server.get('/v1/chatkit/threads/:thread_id/items', (0, PodAccessFailureResponse_1.guardPodAccessRoute)(async (request, response, params) => {
         const url = new URL(request.url ?? '', `http://${request.headers.host}`);
         const threadRef = getThreadRefFromRequest(request, response, params.thread_id);
         if (!threadRef) {
@@ -83,7 +84,7 @@ function registerChatKitV1Routes(server, options) {
             has_more: page.has_more,
             after: page.after,
         });
-    });
+    }));
 }
 function parseOptionalInt(value) {
     if (!value) {

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

@@ -1,4 +1,7 @@
 import { getLoggerFor } from 'global-logger-factory';
+import { type EndpointReachabilityResult } from '../network/EndpointReachabilityProbe';
+import { type TunnelClientInspection } from '../../tunnel/TunnelClientManager';
+import type { TunnelProviderId } from '../../tunnel/TunnelProviderCatalog';
 import type { ApiServer } from '../ApiServer';
 import type { AuthContext } from '../auth/AuthContext';
 import { type TunnelProviderDescriptor } from '../../tunnel/TunnelProviderCatalog';
@@ -109,7 +112,15 @@ export interface NetworkDiagnosticCheckResult {
     label: string;
     status: DiagnosticStatus;
     detail?: string;
-    durationMs?: number;
+    /**
+     * How long the check itself took — **not** a network latency (audit N12).
+     *
+     * These checks read local state (is an address configured, what does the TLS/DNS/tunnel
+     * capability say); a duration here says nothing about reachability, so it is named after the
+     * check and consumers must not render it as a round-trip time. A real probe would have to add
+     * its own measurement.
+     */
+    checkDurationMs?: number;
     checkedAt?: string;
 }
 export interface NetworkDiagnosticCheck {
@@ -150,6 +161,25 @@ export interface NetworkPublicAddressReaderOptions {
 }
 export interface NetworkSettingsHandlerOptions {
     endpoint: string | (() => string | undefined);
+    /**
+     * On-demand reachability probe for the declared public entry (audit N12).
+     *
+     * It runs only when the operator triggers a diagnose pass — never on a timer — and defaults to
+     * the public-address-only probe; tests inject a stub.
+     */
+    endpointReachabilityProbe?: (endpoint: string) => Promise<EndpointReachabilityResult>;
+    /**
+     * Tunnel-client plugin actions for the settings page (audit N16): list where each provider's
+     * client would come from, and install one on request. Injectable for tests.
+     */
+    tunnelClients?: {
+        inspectAll: () => Promise<TunnelClientInspection[]>;
+        install: (provider: TunnelProviderId) => Promise<{
+            installedPath: string;
+            version?: string;
+            sourceUrl: string;
+        }>;
+    };
     localAddresses?: () => string[];
     lanAddresses?: () => string[];
     publicAddresses?: () => string[];
@@ -164,6 +194,13 @@ export interface NetworkSettingsHandlerOptions {
     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;

package/dist/api/handlers/NetworkSettingsHandler.js

@@ -12,10 +12,19 @@ exports.createCertificateCapability = createCertificateCapability;
 exports.redactSecretText = redactSecretText;
 const node_os_1 = require("node:os");
 const global_logger_factory_1 = require("global-logger-factory");
+const EndpointReachabilityProbe_1 = require("../network/EndpointReachabilityProbe");
+const TunnelClientManager_1 = require("../../tunnel/TunnelClientManager");
 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) {
@@ -59,6 +68,46 @@ function registerNetworkSettingsRoutes(server, options) {
             sendJson(response, 500, { error: 'Failed to run network diagnostics' });
         }
     }, { optionalAuth: true });
+    // The tunnel-client plugin actions live next to the tunnel configuration they serve: one
+    // "check" that says where each client comes from, one "download" that installs it (N16).
+    server.get('/api/network/settings/tunnel-clients', async (request, response) => {
+        if (!await requireNetworkPermission(request, response, authorizer, 'read', options.internalAdminAuthSecret)) {
+            return;
+        }
+        try {
+            const manager = options.tunnelClients ?? new TunnelClientManager_1.TunnelClientManager();
+            sendJson(response, 200, { clients: await manager.inspectAll() });
+        }
+        catch (error) {
+            logger.error(`Failed to inspect tunnel clients: ${redactSecretText(error)}`);
+            sendJson(response, 500, { error: 'Failed to inspect tunnel clients' });
+        }
+    }, { optionalAuth: true });
+    server.post('/api/network/settings/tunnel-clients/:provider/install', async (request, response, params) => {
+        const provider = String(params?.provider ?? '');
+        const known = ['ngrok', 'cloudflare', 'sakura_frp', 'frp'].includes(provider);
+        if (!known) {
+            sendJson(response, 404, { error: `Unknown tunnel provider: ${provider}` });
+            return;
+        }
+        if (!await requireNetworkPermission(request, response, authorizer, 'write', options.internalAdminAuthSecret)) {
+            return;
+        }
+        try {
+            const manager = options.tunnelClients ?? new TunnelClientManager_1.TunnelClientManager();
+            const installed = await manager.install(provider);
+            sendJson(response, 200, {
+                installed,
+                clients: await manager.inspectAll(),
+            });
+        }
+        catch (error) {
+            // A refused download is a normal answer (no pinned asset), not a server fault.
+            const message = redactSecretText(error);
+            logger.warn(`Tunnel client install refused for ${provider}: ${message}`);
+            sendJson(response, 400, { error: message });
+        }
+    }, { optionalAuth: true });
     if (options.certificateRenewer) {
         server.post('/api/network/settings/certificate/renew', async (request, response) => {
             if (!await requireNetworkPermission(request, response, authorizer, 'write', options.internalAdminAuthSecret)) {
@@ -337,6 +386,28 @@ function buildDefaultDiagnostics(options, logger) {
                     : { status: 'unsupported', detail: 'endpoint_unavailable' };
             },
         },
+        {
+            // Only runs because the operator asked for a diagnose pass; it never polls. The verdict
+            // is deliberately "from this node": a node reaching its own public entry says nothing
+            // about a remote user's path (NAT hairpin), so the wording keeps that distinction.
+            id: 'endpoint-reachability',
+            label: 'Endpoint reachability from this node',
+            run: async () => {
+                const endpoint = normalizeEndpoint(resolveValue(options.endpoint));
+                if (!endpoint) {
+                    return { status: 'unsupported', detail: 'endpoint_unavailable' };
+                }
+                const probe = options.endpointReachabilityProbe ?? EndpointReachabilityProbe_1.probeEndpointReachability;
+                const result = await probe(endpoint);
+                if (result.verdict === 'reachable-from-this-node') {
+                    return { status: 'ok', detail: result.detail };
+                }
+                if (result.verdict === 'blocked') {
+                    return { status: 'unsupported', detail: result.detail };
+                }
+                return { status: 'warning', detail: result.detail };
+            },
+        },
         {
             id: 'tls',
             label: 'TLS',
@@ -356,7 +427,7 @@ function buildDefaultDiagnostics(options, logger) {
 }
 async function runDiagnostic(check, logger) {
     const startedAt = Date.now();
-    const evidence = () => ({ durationMs: Math.max(0, Date.now() - startedAt), checkedAt: new Date().toISOString() });
+    const evidence = () => ({ checkDurationMs: Math.max(0, Date.now() - startedAt), checkedAt: new Date().toISOString() });
     try {
         const result = await check.run();
         if (typeof result === 'string') {
@@ -375,14 +446,23 @@ async function runDiagnostic(check, logger) {
         return { id: check.id, label: check.label, status: 'error', detail: redactSecretText(error), ...evidence() };
     }
 }
+/**
+ * Maps a provider capability onto a diagnostic level.
+ *
+ * Only statuses that positively mean "verified" become `ok`, and known-bad ones become `error`
+ * (an invalid or expired certificate is a failure, not something to warn about). Anything else
+ * stays a warning: a status we cannot place must never be rendered as a pass (audit N12).
+ */
+const VERIFIED_CAPABILITY_STATUSES = new Set(['active', 'valid', 'synced', 'direct', 'ready']);
+const FAILED_CAPABILITY_STATUSES = new Set(['error', 'invalid', 'failed', 'expired', 'untrusted', 'mismatch']);
 function capabilityToDiagnostic(capability) {
     if (!capability.supported) {
         return { status: 'unsupported', detail: capability.status };
     }
-    if (capability.status === 'active' || capability.status === 'valid' || capability.status === 'synced' || capability.status === 'direct') {
+    if (VERIFIED_CAPABILITY_STATUSES.has(capability.status)) {
         return { status: 'ok', detail: capability.status };
     }
-    if (capability.status === 'error') {
+    if (FAILED_CAPABILITY_STATUSES.has(capability.status)) {
         return { status: 'error', detail: capability.status };
     }
     return { status: 'warning', detail: capability.status };

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

@@ -0,0 +1,24 @@
+import type { ServerResponse } from 'node:http';
+import type { RouteHandler } from '../ApiServer';
+/** The wire code callers already report when Xpod cannot open the Pod for them. */
+export declare const SERVICE_ACCESS_MISSING = "service_access_missing";
+export interface PodAccessFailureResponse {
+    status: number;
+    error: string;
+}
+/**
+ * Status and code for a Pod access failure, or undefined when the error is something else.
+ *
+ * A Pod-backed surface that cannot reach the Pod has to say so. Answering an empty list instead
+ * leaves the caller with a state it cannot act on, and the reason codes exist precisely so the
+ * caller can tell "sign in" from "grant this app access to your Pod".
+ */
+export declare function podAccessFailureResponse(error: unknown): PodAccessFailureResponse | undefined;
+/** Answer with the mapped failure. Returns false when the error is not a Pod access failure. */
+export declare function sendPodAccessFailure(response: ServerResponse, error: unknown): boolean;
+/**
+ * Wrap a route so a Pod access failure answers with the mapped status instead of a generic 500.
+ *
+ * Anything else keeps propagating, so unrelated bugs are not reported as missing Pod access.
+ */
+export declare function guardPodAccessRoute(handler: RouteHandler): RouteHandler;

package/dist/api/handlers/PodAccessFailureResponse.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SERVICE_ACCESS_MISSING = void 0;
+exports.podAccessFailureResponse = podAccessFailureResponse;
+exports.sendPodAccessFailure = sendPodAccessFailure;
+exports.guardPodAccessRoute = guardPodAccessRoute;
+const CallerPodAccess_1 = require("../ai-gateway/auth/CallerPodAccess");
+const OwnerPodAccess_1 = require("../ai-gateway/pod/OwnerPodAccess");
+/** The wire code callers already report when Xpod cannot open the Pod for them. */
+exports.SERVICE_ACCESS_MISSING = 'service_access_missing';
+/**
+ * Status and code for a Pod access failure, or undefined when the error is something else.
+ *
+ * A Pod-backed surface that cannot reach the Pod has to say so. Answering an empty list instead
+ * leaves the caller with a state it cannot act on, and the reason codes exist precisely so the
+ * caller can tell "sign in" from "grant this app access to your Pod".
+ */
+function podAccessFailureResponse(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (!(0, OwnerPodAccess_1.isPodAccessFailure)(message)) {
+        return undefined;
+    }
+    if (message.startsWith(CallerPodAccess_1.CALLER_POD_ACCESS_UNAVAILABLE)) {
+        return { status: 401, error: 'authentication_required' };
+    }
+    if (message.startsWith(CallerPodAccess_1.CALLER_OWNER_MISMATCH)) {
+        return { status: 403, error: 'pod_owner_mismatch' };
+    }
+    return { status: 403, error: exports.SERVICE_ACCESS_MISSING };
+}
+/** Answer with the mapped failure. Returns false when the error is not a Pod access failure. */
+function sendPodAccessFailure(response, error) {
+    const mapped = podAccessFailureResponse(error);
+    if (!mapped) {
+        return false;
+    }
+    response.statusCode = mapped.status;
+    response.setHeader('Content-Type', 'application/json');
+    response.end(JSON.stringify({ error: mapped.error }));
+    return true;
+}
+/**
+ * Wrap a route so a Pod access failure answers with the mapped status instead of a generic 500.
+ *
+ * Anything else keeps propagating, so unrelated bugs are not reported as missing Pod access.
+ */
+function guardPodAccessRoute(handler) {
+    return async (request, response, params) => {
+        try {
+            await handler(request, response, params);
+        }
+        catch (error) {
+            if (!sendPodAccessFailure(response, error)) {
+                throw error;
+            }
+        }
+    };
+}
+//# sourceMappingURL=PodAccessFailureResponse.js.map

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

@@ -2,7 +2,8 @@ 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';
+import type { AuthContext } from '../auth/AuthContext';
 export interface PodSettingsStatus {
     identity: {
         webId: string;
@@ -43,9 +44,15 @@ export type PodAiConnectionsStatus = {
     reason: string;
 };
 export interface PodAiConnectionsStatusReader {
+    /**
+     * `auth` is the caller's own context. A signed-in user's status has to be read with the
+     * credential that user presented; without one this reports `not_configured` instead of
+     * borrowing the deployment's stored owner key.
+     */
     read(input: {
         webId: string;
         podUrl?: string;
+        auth?: AuthContext;
     }): Promise<PodAiConnectionsStatus>;
 }
 export interface PodSettingsHandlerOptions {
@@ -57,17 +64,18 @@ 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;
     }) => Promise<AiConnectionsStatusDb>);
-    read({ webId, podUrl }: {
+    read({ webId, podUrl, auth }: {
         webId: string;
         podUrl?: string;
+        auth?: AuthContext;
     }): Promise<PodAiConnectionsStatus>;
 }
 type AiConnectionsStatusDb = {

package/dist/api/handlers/PodSettingsHandler.js

@@ -22,7 +22,7 @@ function registerPodSettingsRoutes(server, options) {
             const podUrl = pod?.storageUrl ?? pod?.baseUrl;
             const [storage, aiConnection] = await Promise.all([
                 readStorageStatus(options.usageRepo, pod),
-                aiConnectionStatusReader.read({ webId, podUrl }).catch((error) => {
+                aiConnectionStatusReader.read({ webId, podUrl, auth: request.auth }).catch((error) => {
                     const reason = safeAiConnectionsFailureReason(error);
                     logger.warn(`Failed to read Pod AI Connection status: ${reason}`);
                     return { status: 'error', reason };
@@ -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);
+    async read({ webId, podUrl, auth }) {
+        const trustedFetch = await this.podAccess?.getPodFetch(webId, auth ? { auth } : {});
         if (!trustedFetch) {
             return { status: 'unsupported', reason: 'not_configured' };
         }

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

@@ -14,6 +14,7 @@
  *   返回 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';
@@ -67,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;
     /** 测试/调试注入 */
@@ -74,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

@@ -442,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;
@@ -479,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.js

@@ -64,6 +64,7 @@ function registerReachabilityRoutes(server, options) {
                     ...(access.kind === 'solid' ? { owner: { type: 'solid', webId: access.webId } } : {}),
                     capabilities: Array.isArray(body.capabilities) ? body.capabilities.filter((entry) => typeof entry === 'string') : [],
                     candidates: enrichP2PCandidatesWithObservedAddress(Array.isArray(body.candidates) ? body.candidates : [], resolveObservedAddress(request)),
+                    ...(typeof body.dataPlaneSecret === 'string' ? { dataPlaneSecret: body.dataPlaneSecret } : {}),
                 });
                 sendJson(response, 201, session);
             }
@@ -76,6 +77,10 @@ function registerReachabilityRoutes(server, options) {
                     sendJson(response, 429, { error: 'P2P active session limit exceeded' });
                     return;
                 }
+                if (error instanceof ReachabilitySessionService_1.InvalidP2PSessionRequestError) {
+                    sendJson(response, 400, { error: error.message });
+                    return;
+                }
                 if (error instanceof ReachabilitySessionService_1.P2PCandidateUpdateLimitExceededError) {
                     sendJson(response, 429, { error: 'P2P candidate update limit exceeded' });
                     return;
@@ -214,7 +219,9 @@ function resolveAccess(request, nodeId) {
         if (auth.nodeId !== nodeId) {
             return { allowed: false, status: 403, error: 'Node token cannot access another node' };
         }
-        return { allowed: true, audience: 'managed' };
+        // The node asking about itself stands on its own host, which is the one place its
+        // `local-only` loopback access point is usable (`docs/multi-channel-access.md`).
+        return { allowed: true, audience: 'local' };
     }
     if ((0, AuthContext_1.isServiceAuth)(auth)) {
         return { allowed: true, audience: 'managed' };