@undefineds.co/xpod 0.4.13 → 0.4.15

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,
@@ -1967,6 +1925,15 @@
           "options_locations": {
             "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService_options_locations"
           },
+          "options_resolveAddresses": {
+            "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService_options_resolveAddresses"
+          },
+          "options_headRequest": {
+            "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService_options_headRequest"
+          },
+          "options_maxRedirects": {
+            "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService_options_maxRedirects"
+          },
           "repository": {
             "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService_options_repository"
           },
@@ -1981,6 +1948,15 @@
           },
           "locations": {
             "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService_options_locations"
+          },
+          "resolveAddresses": {
+            "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService_options_resolveAddresses"
+          },
+          "headRequest": {
+            "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService_options_headRequest"
+          },
+          "maxRedirects": {
+            "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService_options_maxRedirects"
           }
         }
       },
@@ -2029,6 +2005,9 @@
           "options_p2pTargetBaseUrl": {
             "@id": "undefineds:dist/edge/EdgeNodeAgentInitializer.jsonld#EdgeNodeAgentInitializer_options_p2pTargetBaseUrl"
           },
+          "options_p2pLanBaseUrl": {
+            "@id": "undefineds:dist/edge/EdgeNodeAgentInitializer.jsonld#EdgeNodeAgentInitializer_options_p2pLanBaseUrl"
+          },
           "options_p2pLabel": {
             "@id": "undefineds:dist/edge/EdgeNodeAgentInitializer.jsonld#EdgeNodeAgentInitializer_options_p2pLabel"
           },
@@ -2118,6 +2097,9 @@
           "p2pTargetBaseUrl": {
             "@id": "undefineds:dist/edge/EdgeNodeAgentInitializer.jsonld#EdgeNodeAgentInitializer_options_p2pTargetBaseUrl"
           },
+          "p2pLanBaseUrl": {
+            "@id": "undefineds:dist/edge/EdgeNodeAgentInitializer.jsonld#EdgeNodeAgentInitializer_options_p2pLanBaseUrl"
+          },
           "p2pLabel": {
             "@id": "undefineds:dist/edge/EdgeNodeAgentInitializer.jsonld#EdgeNodeAgentInitializer_options_p2pLabel"
           },
@@ -2959,6 +2941,9 @@
           "options_cloudflaredPath": {
             "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider_options_cloudflaredPath"
           },
+          "options_connectTimeoutMs": {
+            "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider_options_connectTimeoutMs"
+          },
           "tunnelToken": {
             "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider_options_tunnelToken"
           },
@@ -2967,6 +2952,9 @@
           },
           "cloudflaredPath": {
             "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider_options_cloudflaredPath"
+          },
+          "connectTimeoutMs": {
+            "@id": "undefineds:dist/tunnel/LocalTunnelProvider.jsonld#LocalTunnelProvider_options_connectTimeoutMs"
           }
         }
       },
@@ -3994,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

@@ -47,6 +47,12 @@ export interface EdgeNodeAgentOptions {
     p2p?: {
         enabled?: boolean | string;
         targetBaseUrl: string | URL;
+        /**
+         * Address this node advertises as its LAN route. Defaults to `targetBaseUrl`,
+         * and must be set when the forwarding target is a loopback-only listener that
+         * other devices on the LAN cannot reach.
+         */
+        lanBaseUrl?: string | URL;
         label?: string;
         host?: string;
         address?: string;
@@ -85,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,12 +246,60 @@ 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) {
             return [];
         }
-        const endpoint = this.resolveLanGatewayEndpoint(p2p.targetBaseUrl);
+        const endpoint = this.resolveLanGatewayEndpoint(p2p.lanBaseUrl ?? p2p.targetBaseUrl);
         if (!endpoint) {
             return [];
         }

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

@@ -16,6 +16,8 @@ export interface EdgeNodeAgentInitializerOptions {
     intervalMs?: number | string;
     p2pEnabled?: boolean | string;
     p2pTargetBaseUrl?: string;
+    /** LAN-facing address; defaults to `p2pTargetBaseUrl` inside the agent. */
+    p2pLanBaseUrl?: string;
     p2pLabel?: string;
     p2pAcceptIntervalMs?: number | string;
     p2pConnectTimeoutMs?: number | string;

package/dist/edge/EdgeNodeAgentInitializer.js

@@ -86,6 +86,7 @@ class EdgeNodeAgentInitializer extends community_server_1.Initializer {
                 p2p: {
                     enabled: true,
                     targetBaseUrl: options.p2pTargetBaseUrl,
+                    ...(options.p2pLanBaseUrl ? { lanBaseUrl: options.p2pLanBaseUrl } : {}),
                     label: options.p2pLabel,
                     acceptIntervalMs: this.normalizePositiveInteger(options.p2pAcceptIntervalMs),
                     connectTimeoutMs: this.normalizePositiveInteger(options.p2pConnectTimeoutMs),

package/dist/edge/EdgeNodeAgentInitializer.jsonld

@@ -185,6 +185,19 @@
             ]
           }
         },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeAgentInitializer.jsonld#EdgeNodeAgentInitializer_options_p2pLanBaseUrl",
+          "range": {
+            "@type": "ParameterRangeUnion",
+            "parameterRangeElements": [
+              "xsd:string",
+              {
+                "@type": "ParameterRangeUndefined"
+              }
+            ]
+          },
+          "comment": "LAN-facing address; defaults to `p2pTargetBaseUrl` inside the agent."
+        },
         {
           "@id": "undefineds:dist/edge/EdgeNodeAgentInitializer.jsonld#EdgeNodeAgentInitializer_options_p2pLabel",
           "range": {
@@ -555,6 +568,12 @@
                 "@id": "undefineds:dist/edge/EdgeNodeAgentInitializer.jsonld#EdgeNodeAgentInitializer_options_p2pTargetBaseUrl"
               }
             },
+            {
+              "keyRaw": "p2pLanBaseUrl",
+              "value": {
+                "@id": "undefineds:dist/edge/EdgeNodeAgentInitializer.jsonld#EdgeNodeAgentInitializer_options_p2pLanBaseUrl"
+              }
+            },
             {
               "keyRaw": "p2pLabel",
               "value": {

package/dist/edge/EdgeNodeDnsCoordinator.d.ts

@@ -19,7 +19,17 @@ export declare class EdgeNodeDnsCoordinator {
     private readonly ttl?;
     private readonly enabled;
     constructor(options: EdgeNodeDnsCoordinatorOptions);
-    synchronize(nodeId: string, metadata: Record<string, unknown>): Promise<void>;
+    /**
+     * Reconciles the DNS record owned by one node.
+     *
+     * `binding` is the control plane's subdomain assignment for that node. When it is
+     * supplied it is authoritative, including when it carries no subdomain: that means the
+     * node owns no record and nothing may be written or deleted. Node-reported metadata is
+     * still consulted for callers whose subdomain is local (`LocalNetworkManager`).
+     */
+    synchronize(nodeId: string, metadata: Record<string, unknown>, binding?: {
+        subdomain?: string;
+    }): Promise<void>;
     private extractDnsHints;
     private extractTunnelEntrypoint;
     private extractString;

package/dist/edge/EdgeNodeDnsCoordinator.js

@@ -11,12 +11,22 @@ class EdgeNodeDnsCoordinator {
         this.ttl = this.normalizeTtl(options.ttl);
         this.enabled = Boolean(this.rootDomain);
     }
-    async synchronize(nodeId, metadata) {
+    /**
+     * Reconciles the DNS record owned by one node.
+     *
+     * `binding` is the control plane's subdomain assignment for that node. When it is
+     * supplied it is authoritative, including when it carries no subdomain: that means the
+     * node owns no record and nothing may be written or deleted. Node-reported metadata is
+     * still consulted for callers whose subdomain is local (`LocalNetworkManager`).
+     */
+    async synchronize(nodeId, metadata, binding) {
         if (!this.enabled) {
             return;
         }
         const hints = this.extractDnsHints(metadata);
-        const subdomain = this.extractString(metadata.subdomain) ?? hints?.subdomain;
+        const subdomain = binding
+            ? this.extractString(binding.subdomain)
+            : this.extractString(metadata.subdomain) ?? hints?.subdomain;
         if (!subdomain) {
             this.logger.debug(`Node ${nodeId} 未提供 subdomain，跳过 DNS 同步。`);
             return;

package/dist/edge/EdgeNodeHealthProbeService.d.ts

@@ -1,10 +1,17 @@
 import { EdgeNodeRepository } from '../identity/drizzle/EdgeNodeRepository';
+import { type HeadProbeRequest, type ResolveAddresses } from './ProbeTargetGuard';
 interface EdgeNodeHealthProbeServiceOptions {
     repository?: EdgeNodeRepository;
     identityDbUrl?: string;
     enabled?: boolean | string;
     timeoutMs?: number | string;
     locations?: string | string[];
+    /** DNS resolution used to validate probe targets; injected in tests. */
+    resolveAddresses?: ResolveAddresses;
+    /** Transport for the direct HEAD probe; injected in tests. */
+    headRequest?: HeadProbeRequest;
+    /** Redirect hops followed while re-validating every target. */
+    maxRedirects?: number;
 }
 export declare class EdgeNodeHealthProbeService {
     private readonly logger;
@@ -12,6 +19,9 @@ export declare class EdgeNodeHealthProbeService {
     private readonly enabled;
     private readonly timeoutMs;
     private readonly locations;
+    private readonly resolveAddresses?;
+    private readonly headRequest;
+    private readonly maxRedirects;
     constructor(options: EdgeNodeHealthProbeServiceOptions);
     probeNode(nodeId: string): Promise<void>;
     private collectCandidates;
@@ -19,6 +29,11 @@ export declare class EdgeNodeHealthProbeService {
     private extractManagedTunnelEndpoint;
     private extractNonEmptyString;
     private ping;
+    /**
+     * Follows redirects by hand so every hop is validated again: a public entry point must
+     * not be able to bounce the probe into a private address.
+     */
+    private probePublicCandidate;
     private toUrl;
     private createRepository;
     private normalizeBoolean;

package/dist/edge/EdgeNodeHealthProbeService.js

@@ -4,6 +4,7 @@ exports.EdgeNodeHealthProbeService = void 0;
 const global_logger_factory_1 = require("global-logger-factory");
 const db_1 = require("../identity/drizzle/db");
 const EdgeNodeRepository_1 = require("../identity/drizzle/EdgeNodeRepository");
+const ProbeTargetGuard_1 = require("./ProbeTargetGuard");
 class EdgeNodeHealthProbeService {
     constructor(options) {
         this.logger = (0, global_logger_factory_1.getLoggerFor)(this);
@@ -11,6 +12,9 @@ class EdgeNodeHealthProbeService {
         this.enabled = this.normalizeBoolean(options.enabled) && Boolean(this.repository);
         this.timeoutMs = this.normalizeTimeout(options.timeoutMs) ?? 3_000;
         this.locations = this.normalizeLocations(options.locations);
+        this.resolveAddresses = options.resolveAddresses;
+        this.headRequest = options.headRequest ?? (0, ProbeTargetGuard_1.createPinnedHeadProbeRequest)();
+        this.maxRedirects = Math.max(0, Math.trunc(options.maxRedirects ?? 3));
     }
     async probeNode(nodeId) {
         if (!this.enabled) {
@@ -87,8 +91,20 @@ class EdgeNodeHealthProbeService {
         if (!url) {
             return { candidate, success: false, error: 'invalid-url', location: location.name, checkedAt: new Date().toISOString() };
         }
-        const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        // The candidate comes from node metadata, so Cloud only contacts public targets:
+        // private, loopback, link-local and metadata addresses stay with clients that can
+        // actually reach them.
+        const decision = await (0, ProbeTargetGuard_1.assertPublicProbeTarget)(url, this.resolveAddresses);
+        if (!decision.allowed) {
+            this.logger.debug(`跳过非公网探测目标 ${candidate}: ${decision.reason}`);
+            return {
+                candidate,
+                success: false,
+                error: `blocked-target:${decision.reason}`,
+                location: location.name,
+                checkedAt: new Date().toISOString(),
+            };
+        }
         const started = Date.now();
         try {
             if (location.endpoint) {
@@ -96,10 +112,9 @@ class EdgeNodeHealthProbeService {
                 probeUrl.searchParams.set('target', url.toString());
                 const response = await fetch(probeUrl.toString(), {
                     method: 'GET',
-                    signal: controller.signal,
                     headers: { 'accept': 'application/json' },
+                    signal: AbortSignal.timeout(this.timeoutMs),
                 });
-                clearTimeout(timer);
                 const latencyMs = Date.now() - started;
                 if (!response.ok) {
                     return {
@@ -133,23 +148,18 @@ class EdgeNodeHealthProbeService {
                     };
                 }
             }
-            const response = await fetch(url.toString(), {
-                method: 'HEAD',
-                signal: controller.signal,
-            });
-            clearTimeout(timer);
+            const probe = await this.probePublicCandidate(url, decision.address);
             const latencyMs = Date.now() - started;
             return {
                 candidate,
                 location: location.name,
-                success: response.ok,
+                success: probe.status >= 200 && probe.status < 400,
                 latencyMs,
-                error: response.ok ? undefined : `status:${response.status}`,
+                error: probe.error ?? (probe.status >= 200 && probe.status < 400 ? undefined : `status:${probe.status}`),
                 checkedAt: new Date().toISOString(),
             };
         }
         catch (error) {
-            clearTimeout(timer);
             return {
                 candidate,
                 location: location.name,
@@ -159,6 +169,28 @@ class EdgeNodeHealthProbeService {
             };
         }
     }
+    /**
+     * Follows redirects by hand so every hop is validated again: a public entry point must
+     * not be able to bounce the probe into a private address.
+     */
+    async probePublicCandidate(startUrl, startAddress) {
+        let url = startUrl;
+        let address = startAddress;
+        for (let hop = 0; hop <= this.maxRedirects; hop += 1) {
+            const response = await this.headRequest(url, { address, timeoutMs: this.timeoutMs });
+            if (response.status < 300 || response.status >= 400 || !response.location) {
+                return { status: response.status };
+            }
+            const next = new URL(response.location, url);
+            const decision = await (0, ProbeTargetGuard_1.assertPublicProbeTarget)(next, this.resolveAddresses);
+            if (!decision.allowed) {
+                return { status: 0, error: `blocked-redirect:${decision.reason}` };
+            }
+            url = next;
+            address = decision.address;
+        }
+        return { status: 0, error: 'blocked-redirect:too-many-redirects' };
+    }
     toUrl(value) {
         try {
             return new URL(value);

package/dist/edge/EdgeNodeHealthProbeService.jsonld

@@ -74,6 +74,49 @@
               }
             ]
           }
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService_options_resolveAddresses",
+          "range": {
+            "@type": "ParameterRangeUnion",
+            "parameterRangeElements": [
+              {
+                "@type": "ParameterRangeWildcard"
+              },
+              {
+                "@type": "ParameterRangeUndefined"
+              }
+            ]
+          },
+          "comment": "DNS resolution used to validate probe targets; injected in tests."
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService_options_headRequest",
+          "range": {
+            "@type": "ParameterRangeUnion",
+            "parameterRangeElements": [
+              {
+                "@type": "ParameterRangeWildcard"
+              },
+              {
+                "@type": "ParameterRangeUndefined"
+              }
+            ]
+          },
+          "comment": "Transport for the direct HEAD probe; injected in tests."
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService_options_maxRedirects",
+          "range": {
+            "@type": "ParameterRangeUnion",
+            "parameterRangeElements": [
+              "xsd:number",
+              {
+                "@type": "ParameterRangeUndefined"
+              }
+            ]
+          },
+          "comment": "Redirect hops followed while re-validating every target."
         }
       ],
       "memberFields": [
@@ -97,6 +140,18 @@
           "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService__member_locations",
           "memberFieldName": "locations"
         },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService__member_resolveAddresses",
+          "memberFieldName": "resolveAddresses"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService__member_headRequest",
+          "memberFieldName": "headRequest"
+        },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService__member_maxRedirects",
+          "memberFieldName": "maxRedirects"
+        },
         {
           "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService__member_constructor",
           "memberFieldName": "constructor"
@@ -125,6 +180,10 @@
           "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService__member_ping",
           "memberFieldName": "ping"
         },
+        {
+          "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService__member_probePublicCandidate",
+          "memberFieldName": "probePublicCandidate"
+        },
         {
           "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService__member_toUrl",
           "memberFieldName": "toUrl"
@@ -179,6 +238,24 @@
               "value": {
                 "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService_options_locations"
               }
+            },
+            {
+              "keyRaw": "resolveAddresses",
+              "value": {
+                "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService_options_resolveAddresses"
+              }
+            },
+            {
+              "keyRaw": "headRequest",
+              "value": {
+                "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService_options_headRequest"
+              }
+            },
+            {
+              "keyRaw": "maxRedirects",
+              "value": {
+                "@id": "undefineds:dist/edge/EdgeNodeHealthProbeService.jsonld#EdgeNodeHealthProbeService_options_maxRedirects"
+              }
             }
           ]
         }

package/dist/edge/ProbeTargetGuard.d.ts

@@ -0,0 +1,35 @@
+export type ResolveAddresses = (hostname: string) => Promise<string[]>;
+export type ProbeTargetDecision = {
+    allowed: true;
+    address: string;
+} | {
+    allowed: false;
+    reason: string;
+};
+/** Whether an address is a public unicast address a Cloud probe may contact. */
+export declare function isPublicIpAddress(address: string): boolean;
+/** Resolves every address of a probe hostname; injected in tests. */
+export declare function resolveHostAddresses(hostname: string): Promise<string[]>;
+/**
+ * Decides whether a probe target may be contacted.
+ *
+ * Every resolved address has to be public, so a hostname that mixes public and private
+ * records is refused instead of racing whichever record the connection picks.
+ */
+export declare function assertPublicProbeTarget(url: URL, resolveAddresses?: ResolveAddresses): Promise<ProbeTargetDecision>;
+export interface HeadProbeRequestOptions {
+    /** Address the connection is pinned to, already validated by the target policy. */
+    address: string;
+    timeoutMs: number;
+}
+export type HeadProbeRequest = (url: URL, options: HeadProbeRequestOptions) => Promise<{
+    status: number;
+    location?: string;
+}>;
+/**
+ * HEAD request pinned to a validated address.
+ *
+ * Pinning is what makes the DNS check meaningful: without it the client would resolve the
+ * hostname a second time and a rebinding answer could still reach a private address.
+ */
+export declare function createPinnedHeadProbeRequest(): HeadProbeRequest;