@undefineds.co/xpod 0.4.14 → 0.4.15

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,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

@@ -214,7 +214,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' };

package/dist/api/runtime.d.ts

@@ -26,5 +26,14 @@ export declare function autoProvisionFirstRunLocal(config: ApiContainerConfig, l
  * would let forwarded remote requests inherit local trust. Falls back to the
  * historical gateway port only when no ingress listener was provisioned.
  */
+/**
+ * The port a remote tunnel forwards to: the Gateway's tunnel entry.
+ *
+ * The runtime records the listener it actually bound in `XPOD_GATEWAY_INGRESS_PORT`, and the
+ * Gateway's own port is only the fallback for an embedding that started no tunnel entry. The
+ * gate is structural - anything arriving on that listener is remote whatever it claims - so a
+ * tunnel pointed at the Gateway port by mistake still has the forwarding-header check behind
+ * it rather than inheriting local trust.
+ */
 export declare function resolveTunnelIngressPort(env?: NodeJS.ProcessEnv): number;
 export declare function startApiService(options?: StartApiServiceOptions): Promise<ApiServiceHandle>;

package/dist/api/runtime.js

@@ -323,10 +323,23 @@ async function reconcileLocalOwnerRoles(container, config, logger) {
  * would let forwarded remote requests inherit local trust. Falls back to the
  * historical gateway port only when no ingress listener was provisioned.
  */
+/**
+ * The port a remote tunnel forwards to: the Gateway's tunnel entry.
+ *
+ * The runtime records the listener it actually bound in `XPOD_GATEWAY_INGRESS_PORT`, and the
+ * Gateway's own port is only the fallback for an embedding that started no tunnel entry. The
+ * gate is structural - anything arriving on that listener is remote whatever it claims - so a
+ * tunnel pointed at the Gateway port by mistake still has the forwarding-header check behind
+ * it rather than inheriting local trust.
+ */
 function resolveTunnelIngressPort(env = process.env) {
-    const raw = env.XPOD_GATEWAY_INGRESS_PORT ?? env.XPOD_MAIN_PORT ?? env.CSS_PORT ?? env.PORT ?? '3000';
-    const parsed = Number.parseInt(raw, 10);
-    return Number.isFinite(parsed) && parsed > 0 ? parsed : 3000;
+    for (const value of [env.XPOD_GATEWAY_INGRESS_PORT, env.XPOD_MAIN_PORT, env.XPOD_PORT, env.PORT]) {
+        const parsed = Number.parseInt(value ?? '', 10);
+        if (Number.isFinite(parsed) && parsed > 0) {
+            return parsed;
+        }
+    }
+    return 3000;
 }
 async function startBackgroundServices(container, logger) {
     try {

package/dist/cli/commands/start.d.ts

@@ -17,12 +17,19 @@ export declare const startCommand: CommandModule<object, StartArgs>;
  * port → an OS-assigned loopback port. The first two are strict, because a tunnel that
  * forwards to a specific port cannot follow us somewhere else.
  */
-export declare function resolveIngressPort(config: {
+/**
+ * The port a remote tunnel forwards to: the Gateway's tunnel entry.
+ *
+ * It is derived from the Gateway port by the same rule the runtime uses, so the CLI can hand
+ * it to the managed edge agent before the runtime binds it. A console that forwards somewhere
+ * else is a mismatch the tunnel provider reports from its own read-back - the runtime never
+ * moves its gate to match a console.
+ */
+export declare function resolveIngressPort(provisionedConfig: {
     tunnelProfiles?: Array<{
         id: string;
         provider: string;
         credentialEnvKey?: string;
-        credentialConfigured?: boolean;
     }>;
     tunnelActiveProfileId?: string;
 }, mainPort: number): Promise<number>;

package/dist/cli/commands/start.js

@@ -239,30 +239,28 @@ exports.startCommand = {
  * port → an OS-assigned loopback port. The first two are strict, because a tunnel that
  * forwards to a specific port cannot follow us somewhere else.
  */
-async function resolveIngressPort(config, mainPort) {
-    const explicit = process.env.XPOD_GATEWAY_INGRESS_PORT?.trim();
-    if (explicit) {
-        return await (0, runtime_1.requireFreePortForWildcard)(Number.parseInt(explicit, 10));
-    }
-    const active = config.tunnelProfiles?.find((profile) => profile.id === config.tunnelActiveProfileId)
-        ?? config.tunnelProfiles?.find((profile) => profile.provider === 'sakura_frp');
+/**
+ * The port a remote tunnel forwards to: the Gateway's tunnel entry.
+ *
+ * It is derived from the Gateway port by the same rule the runtime uses, so the CLI can hand
+ * it to the managed edge agent before the runtime binds it. A console that forwards somewhere
+ * else is a mismatch the tunnel provider reports from its own read-back - the runtime never
+ * moves its gate to match a console.
+ */
+async function resolveIngressPort(provisionedConfig, mainPort) {
+    const port = await (0, runtime_1.findGatewayIngressPort)(mainPort);
+    const active = provisionedConfig.tunnelProfiles?.find((profile) => profile.id === provisionedConfig.tunnelActiveProfileId) ?? provisionedConfig.tunnelProfiles?.find((profile) => profile.provider === 'sakura_frp');
     if (active?.provider === 'sakura_frp') {
         const credential = active.credentialEnvKey
             ? process.env[active.credentialEnvKey] ?? process.env.SAKURA_TUNNEL_TOKEN
             : process.env.SAKURA_TUNNEL_TOKEN;
         const assigned = await (0, SakuraFrpTunnelProvider_1.resolveSakuraAssignedLocalPort)(credential);
-        if (assigned && assigned !== mainPort) {
-            return await (0, runtime_1.requireFreePortForWildcard)(assigned);
+        if (assigned !== undefined && assigned !== port) {
+            (0, global_logger_factory_1.getLoggerFor)('XpodStart').warn(`The Sakura console forwards to local port ${assigned}, but this runtime's tunnel entry is ${port}; `
+                + `update the tunnel's local port in the console to ${port}`);
         }
     }
-    // The operator copies this address into a provider console, so it has to survive
-    // restarts instead of being a fresh OS-assigned port every time.
-    const stateFile = path_1.default.join(process.cwd(), '.xpod', 'runtime', 'ingress-port');
-    const stable = await (0, runtime_1.resolveStableLoopbackPort)(stateFile);
-    if (stable.changed) {
-        (0, global_logger_factory_1.getLoggerFor)('XpodStart').warn(`The ingress port changed to ${stable.port}; update the tunnel console if it still forwards to the previous port`);
-    }
-    return stable.port;
+    return port;
 }
 function resolveCliOidcIssuer(env, provisionedIssuer, edition) {
     return (0, oidc_issuer_1.resolveExternalOidcIssuer)(env)

package/dist/components/components.jsonld

@@ -31,7 +31,6 @@
     "undefineds:dist/logging/ConfigurableLoggerFactory.jsonld",
     "undefineds:dist/storage/SparqlUpdateResourceStore.jsonld",
     "undefineds:dist/http/SubgraphSparqlHttpHandler.jsonld",
-    "undefineds:dist/http/InternalPodDataHttpHandler.jsonld",
     "undefineds:dist/http/quota/QuotaAdminHttpHandler.jsonld",
     "undefineds:dist/http/ClusterIngressRouter.jsonld",
     "undefineds:dist/http/ClusterWebSocketConfigurator.jsonld",
@@ -134,6 +133,7 @@
     "undefineds:dist/api/reconciler/WakeAgentQueue.jsonld",
     "undefineds:dist/api/reconciler/ServerGroupReconcilerService.jsonld",
     "undefineds:dist/edge/reachability/types.jsonld",
+    "undefineds:dist/edge/reachability/RouteSetBuilder.jsonld",
     "undefineds:dist/edge/reachability/ReachabilitySessionService.jsonld",
     "undefineds:dist/edge/reachability/ManagedRouteSelector.jsonld",
     "undefineds:dist/edge/reachability/CanonicalFetch.jsonld",

package/dist/components/context.jsonld

@@ -1111,48 +1111,6 @@
           }
         }
       },
-      "InternalPodDataHttpHandler": {
-        "@id": "undefineds:dist/http/InternalPodDataHttpHandler.jsonld#InternalPodDataHttpHandler",
-        "@prefix": true,
-        "@context": {
-          "options_resourceStore": {
-            "@id": "undefineds:dist/http/InternalPodDataHttpHandler.jsonld#InternalPodDataHttpHandler_options_resourceStore"
-          },
-          "options_gatewayAdminProxyAuthSecret": {
-            "@id": "undefineds:dist/http/InternalPodDataHttpHandler.jsonld#InternalPodDataHttpHandler_options_gatewayAdminProxyAuthSecret"
-          },
-          "options_patchBodyParser": {
-            "@id": "undefineds:dist/http/InternalPodDataHttpHandler.jsonld#InternalPodDataHttpHandler_options_patchBodyParser"
-          },
-          "options_sparqlHandler": {
-            "@id": "undefineds:dist/http/InternalPodDataHttpHandler.jsonld#InternalPodDataHttpHandler_options_sparqlHandler"
-          },
-          "options_baseUrl": {
-            "@id": "undefineds:dist/http/InternalPodDataHttpHandler.jsonld#InternalPodDataHttpHandler_options_baseUrl"
-          },
-          "options_basePath": {
-            "@id": "undefineds:dist/http/InternalPodDataHttpHandler.jsonld#InternalPodDataHttpHandler_options_basePath"
-          },
-          "resourceStore": {
-            "@id": "undefineds:dist/http/InternalPodDataHttpHandler.jsonld#InternalPodDataHttpHandler_options_resourceStore"
-          },
-          "gatewayAdminProxyAuthSecret": {
-            "@id": "undefineds:dist/http/InternalPodDataHttpHandler.jsonld#InternalPodDataHttpHandler_options_gatewayAdminProxyAuthSecret"
-          },
-          "patchBodyParser": {
-            "@id": "undefineds:dist/http/InternalPodDataHttpHandler.jsonld#InternalPodDataHttpHandler_options_patchBodyParser"
-          },
-          "sparqlHandler": {
-            "@id": "undefineds:dist/http/InternalPodDataHttpHandler.jsonld#InternalPodDataHttpHandler_options_sparqlHandler"
-          },
-          "baseUrl": {
-            "@id": "undefineds:dist/http/InternalPodDataHttpHandler.jsonld#InternalPodDataHttpHandler_options_baseUrl"
-          },
-          "basePath": {
-            "@id": "undefineds:dist/http/InternalPodDataHttpHandler.jsonld#InternalPodDataHttpHandler_options_basePath"
-          }
-        }
-      },
       "QuotaAdminHttpHandler": {
         "@id": "undefineds:dist/http/quota/QuotaAdminHttpHandler.jsonld#QuotaAdminHttpHandler",
         "@prefix": true,
@@ -4024,6 +3982,11 @@
         "@prefix": true,
         "@context": {}
       },
+      "BuildPublicAccessRoutesOptions": {
+        "@id": "undefineds:dist/edge/reachability/RouteSetBuilder.jsonld#BuildPublicAccessRoutesOptions",
+        "@prefix": true,
+        "@context": {}
+      },
       "ReachabilitySessionService": {
         "@id": "undefineds:dist/edge/reachability/ReachabilitySessionService.jsonld#ReachabilitySessionService",
         "@prefix": true,

package/dist/edge/EdgeNodeAgent.d.ts

@@ -91,6 +91,16 @@ export declare class EdgeNodeAgent {
     private recordWithContent;
     private collectSystemMetrics;
     private buildHeartbeatMetadata;
+    /**
+     * Same-machine access point: the local runtime the agent heartbeats for.
+     *
+     * It is published as `local-only`, so it never reaches public route discovery -
+     * a loopback address is meaningless on any other machine - while managed
+     * clients still see it first (priority 10). The canonical URL stays canonical:
+     * loopback is only its access route.
+     */
+    private buildLoopbackHeartbeatRoute;
+    private resolveLoopbackTargetUrl;
     private buildLanHeartbeatRoutes;
     private buildLanHeartbeatRoute;
     private buildP2PHeartbeatRoute;

package/dist/edge/EdgeNodeAgent.js

@@ -229,6 +229,13 @@ class EdgeNodeAgent {
     }
     buildHeartbeatMetadata(options) {
         const metadata = { ...(options.metadata ?? {}) };
+        // Every access point this node has is reported, not just the public one:
+        // clients pick the best path for where they are (`docs/multi-channel-access.md`),
+        // and a same-machine client needs the loopback entry to do that.
+        const loopbackRoute = this.buildLoopbackHeartbeatRoute(options);
+        if (loopbackRoute) {
+            metadata.routes = this.mergeHeartbeatRoutes(metadata.routes, [loopbackRoute]);
+        }
         const lanRoutes = this.buildLanHeartbeatRoutes(options);
         if (lanRoutes.length > 0) {
             metadata.routes = this.mergeHeartbeatRoutes(metadata.routes, lanRoutes);
@@ -239,6 +246,54 @@ class EdgeNodeAgent {
         }
         return metadata;
     }
+    /**
+     * Same-machine access point: the local runtime the agent heartbeats for.
+     *
+     * It is published as `local-only`, so it never reaches public route discovery -
+     * a loopback address is meaningless on any other machine - while managed
+     * clients still see it first (priority 10). The canonical URL stays canonical:
+     * loopback is only its access route.
+     */
+    buildLoopbackHeartbeatRoute(options) {
+        const target = options.p2p?.targetBaseUrl;
+        const targetUrl = this.resolveLoopbackTargetUrl(target);
+        if (!targetUrl) {
+            return undefined;
+        }
+        return {
+            id: 'loopback',
+            nodeId: options.nodeId,
+            ...(options.baseUrl ? { canonicalUrl: options.baseUrl } : {}),
+            kind: 'loopback',
+            targetUrl,
+            priority: 10,
+            requiresManagedClient: true,
+            visibility: 'local-only',
+            health: 'healthy',
+            metadata: {
+                source: 'local-runtime',
+            },
+        };
+    }
+    resolveLoopbackTargetUrl(target) {
+        if (!target) {
+            return undefined;
+        }
+        try {
+            const url = target instanceof URL ? target : new URL(String(target));
+            if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+                return undefined;
+            }
+            const hostname = url.hostname.toLowerCase().replace(/^\[|\]$/gu, '');
+            if (hostname !== 'localhost' && hostname !== '127.0.0.1' && hostname !== '::1') {
+                return undefined;
+            }
+            return url.href.endsWith('/') ? url.href : `${url.href}/`;
+        }
+        catch {
+            return undefined;
+        }
+    }
     buildLanHeartbeatRoutes(options) {
         const p2p = options.p2p;
         if (!p2p || this.normalizeBoolean(p2p.enabled) === false) {

package/dist/edge/EdgeNodeAgent.jsonld

@@ -212,6 +212,14 @@
           "@id": "undefineds:dist/edge/EdgeNodeAgent.jsonld#EdgeNodeAgent__member_buildHeartbeatMetadata",
           "memberFieldName": "buildHeartbeatMetadata"
         },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeAgent.jsonld#EdgeNodeAgent__member_buildLoopbackHeartbeatRoute",
+          "memberFieldName": "buildLoopbackHeartbeatRoute"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeAgent.jsonld#EdgeNodeAgent__member_resolveLoopbackTargetUrl",
+          "memberFieldName": "resolveLoopbackTargetUrl"
+        },
         {
           "@id": "undefineds:dist/edge/EdgeNodeAgent.jsonld#EdgeNodeAgent__member_buildLanHeartbeatRoutes",
           "memberFieldName": "buildLanHeartbeatRoutes"

package/dist/edge/reachability/ReachabilitySessionService.js

@@ -38,7 +38,10 @@ class ReachabilitySessionService {
             throw new P2PCandidateSessionLimitExceededError('P2P candidate session limit exceeded');
         }
         const routeSet = (0, RouteSetBuilder_1.buildRouteSet)(source, {
-            audience: 'managed',
+            // The node publishes its own access points, loopback included: a client on this host
+            // reaches the node there, and a client elsewhere ranks the path out by probing it
+            // (`docs/multi-channel-access.md`).
+            audience: 'local',
             baseStorageDomain: this.options.baseStorageDomain,
             now: createdAt,
         });

package/dist/edge/reachability/RouteSetBuilder.d.ts

@@ -1,2 +1,19 @@
-import type { BuildRouteSetOptions, BuildRouteSetSource, RouteSet } from './types';
+import type { AccessRoute, BuildRouteSetOptions, BuildRouteSetSource, RouteSet } from './types';
 export declare function buildRouteSet(source: BuildRouteSetSource, options?: BuildRouteSetOptions): RouteSet;
+export interface BuildPublicAccessRoutesOptions {
+    /** The node's canonical public URL, when it has one. */
+    canonicalUrl?: string;
+    /** A provider confirmed the canonical URL is proxy-ready right now. */
+    publicRouteAvailable?: boolean;
+    /** Endpoint of the user's own tunnel, when one is connected. */
+    tunnelEndpoint?: string;
+}
+/**
+ * Access points a node can prove from its own configuration: the canonical public
+ * URL and the user's tunnel endpoint.
+ *
+ * Loopback and LAN are deliberately absent: whether either works depends on where
+ * the client stands, so the client derives them from its own position instead of
+ * being told about paths it may not have (`docs/multi-channel-access.md`).
+ */
+export declare function buildPublicAccessRoutes(options: BuildPublicAccessRoutesOptions): AccessRoute[];

package/dist/edge/reachability/RouteSetBuilder.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildRouteSet = buildRouteSet;
+exports.buildPublicAccessRoutes = buildPublicAccessRoutes;
 const DEFAULT_PRIORITY = {
     loopback: 10,
     lan: 20,
@@ -34,6 +35,44 @@ function buildRouteSet(source, options = {}) {
         routes,
     };
 }
+/**
+ * Access points a node can prove from its own configuration: the canonical public
+ * URL and the user's tunnel endpoint.
+ *
+ * Loopback and LAN are deliberately absent: whether either works depends on where
+ * the client stands, so the client derives them from its own position instead of
+ * being told about paths it may not have (`docs/multi-channel-access.md`).
+ */
+function buildPublicAccessRoutes(options) {
+    const canonicalUrl = normalizeUrlString(options.canonicalUrl);
+    const tunnelEndpoint = normalizeUrlString(options.tunnelEndpoint);
+    const routes = [];
+    if (canonicalUrl) {
+        routes.push({
+            id: 'public-direct',
+            kind: 'public-direct',
+            canonicalUrl,
+            targetUrl: canonicalUrl,
+            priority: DEFAULT_PRIORITY['public-direct'],
+            requiresManagedClient: false,
+            visibility: 'public',
+            health: options.publicRouteAvailable ? 'healthy' : 'unknown',
+        });
+    }
+    if (tunnelEndpoint && tunnelEndpoint !== canonicalUrl) {
+        routes.push({
+            id: 'user-tunnel',
+            kind: 'user-tunnel',
+            canonicalUrl: canonicalUrl ?? tunnelEndpoint,
+            targetUrl: tunnelEndpoint,
+            priority: DEFAULT_PRIORITY['user-tunnel'],
+            requiresManagedClient: false,
+            visibility: 'public',
+            health: 'healthy',
+        });
+    }
+    return routes;
+}
 function routesFromMetadata(source, canonicalUrl, metadata) {
     const rawRoutes = Array.isArray(metadata.routes) ? metadata.routes : [];
     return rawRoutes
@@ -165,6 +204,14 @@ function defaultVisibility(kind) {
     return PUBLIC_KINDS.has(kind) ? 'public' : 'authorized-client';
 }
 function isVisibleToAudience(route, audience) {
+    if (audience === 'local') {
+        return true;
+    }
+    // `local-only` means loopback: usable on the node's own host and nowhere else,
+    // so it is never offered to a client on another machine.
+    if (route.visibility === 'local-only') {
+        return false;
+    }
     if (audience === 'managed') {
         return true;
     }

package/dist/edge/reachability/RouteSetBuilder.jsonld

@@ -0,0 +1,29 @@
+{
+  "@context": [
+    "https://linkedsoftwaredependencies.org/bundles/npm/@undefineds.co/xpod/^0.0.0/components/context.jsonld"
+  ],
+  "@id": "npmd:@undefineds.co/xpod",
+  "components": [
+    {
+      "@id": "undefineds:dist/edge/reachability/RouteSetBuilder.jsonld#BuildPublicAccessRoutesOptions",
+      "@type": "AbstractClass",
+      "requireElement": "BuildPublicAccessRoutesOptions",
+      "parameters": [],
+      "memberFields": [
+        {
+          "@id": "undefineds:dist/edge/reachability/RouteSetBuilder.jsonld#BuildPublicAccessRoutesOptions__member_canonicalUrl",
+          "memberFieldName": "canonicalUrl"
+        },
+        {
+          "@id": "undefineds:dist/edge/reachability/RouteSetBuilder.jsonld#BuildPublicAccessRoutesOptions__member_publicRouteAvailable",
+          "memberFieldName": "publicRouteAvailable"
+        },
+        {
+          "@id": "undefineds:dist/edge/reachability/RouteSetBuilder.jsonld#BuildPublicAccessRoutesOptions__member_tunnelEndpoint",
+          "memberFieldName": "tunnelEndpoint"
+        }
+      ],
+      "constructorArguments": []
+    }
+  ]
+}

package/dist/edge/reachability/types.d.ts

@@ -3,7 +3,8 @@ export type AccessRouteVisibility = 'local-only' | 'same-account' | 'authorized-
 export type AccessRouteHealth = 'unknown' | 'healthy' | 'degraded' | 'unreachable';
 export interface AccessRoute {
     id: string;
-    nodeId: string;
+    /** Absent while the node has no identity yet, as on a standalone Local runtime. */
+    nodeId?: string;
     canonicalUrl: string;
     kind: AccessRouteKind;
     targetUrl: string;
@@ -21,7 +22,12 @@ export interface RouteSet {
     generatedAt: string;
     routes: AccessRoute[];
 }
-export type RouteAudience = 'public' | 'managed';
+/**
+ * Who is asking for routes. `local` is the node's own host, which is the only
+ * place a loopback access point means anything; `managed` is an authorized
+ * client elsewhere, and `public` is unauthenticated discovery.
+ */
+export type RouteAudience = 'public' | 'managed' | 'local';
 export interface BuildRouteSetSource {
     nodeId: string;
     canonicalUrl?: string;