@serve.zone/interfaces 32.3.0 → 32.4.0

package/ts/data/cluster.ts

@@ -5,6 +5,7 @@ import type { IClusterNode } from './clusternode.js';
 import { isPlausibleUnicastIpv4 } from '../private/ipv4.js';
 import { validateProtocolOfferOn, type IProtocolOffer } from '../protocol.js';
 import { hasExactKeys } from '../private/dataproperties.js';
+import { networkNoiseKey } from '../private/networkcontract.js';
 
 export interface ICluster {
   id: string;
@@ -62,6 +63,25 @@ export interface IClusterRelay {
   origin: string;
 }
 
+/**
+ * The managed VPN hub a cluster relay bound for its own cluster.
+ *
+ * The relay is its cluster's packet relay: every node of the cluster dials this hub and no
+ * inter-node packet leaves the cluster. It reports what it bound, exactly like `listenAddress` and
+ * `listenPort`, and Cloudly composes the platform endpoints from it — a relay names no endpoint id
+ * and no TLS name of its own. `publicKey` is the hub's Noise public key in the one canonical
+ * 32-byte base64 encoding every Noise key of this contract is read with; it is public material and
+ * authenticates nothing by itself. A hub that bound only one transport reports the other port as
+ * `null`.
+ */
+export interface IClusterRelayVpnHub {
+  publicKey: string;
+  /** The address the hub bound, as an IPv4 literal inside the address plan's `vpn.hubPrefix`. */
+  address: string;
+  quicPort: number | null;
+  websocketPort: number | null;
+}
+
 /**
  * What a cluster relay tells Cloudly about itself once its socket is authenticated.
  *
@@ -88,6 +108,11 @@ export interface IRegisterClusterRelayRequest {
      */
     listenAddress: string;
     listenPort: number;
+    /**
+     * Absent on a relay that serves no managed VPN hub, which registers exactly as it did before.
+     * Cloudly selects no hub for such a cluster and states `relay-vpn-hub-absent` instead.
+     */
+    vpnHub?: IClusterRelayVpnHub;
   };
   /** Monotonic within one relay process; it restarts at 0 when the process restarts. */
   registrationSequence: number;
@@ -234,9 +259,56 @@ const validateClusterRelayNonNegativeInteger = (valueArg: unknown, pathArg: stri
     : [`${pathArg} must be a non-negative safe integer`]
 );
 
+/**
+ * The one canonical 32-byte base64 reading every Noise key of this contract passes, stated as a
+ * refusal this validator's callers can collect: a hub key is the same key material the managed VPN
+ * credential carries, so it is never read by a second rule that could drift from it.
+ */
+const validateClusterRelayVpnKey = (valueArg: unknown, pathArg: string): string[] => {
+  try {
+    networkNoiseKey(valueArg);
+    return [];
+  } catch {
+    return [`${pathArg} must be a canonical 32-byte base64 public key`];
+  }
+};
+
+/** A port the hub bound, or `null` for a transport it did not bind. */
+const validateClusterRelayHubPort = (valueArg: unknown, pathArg: string): string[] => (
+  valueArg === null || validateClusterRelayListenPort(valueArg, pathArg).length === 0
+    ? []
+    : [`${pathArg} must be null or an integer from 1 to 65535`]
+);
+
+/**
+ * Validates one hub advertisement and names every reason it is refused.
+ *
+ * Shape only: whether the address sits inside the address plan's `vpn.hubPrefix` is Cloudly's to
+ * decide against the plan it stores, and the endpoints themselves are composed there.
+ */
+export const validateClusterRelayVpnHub = (
+  valueArg: unknown,
+  pathArg = 'cluster relay vpn hub',
+): string[] => {
+  if (!isRecord(valueArg)
+    || !hasExactKeys(valueArg, ['publicKey', 'address', 'quicPort', 'websocketPort'])) {
+    return [`${pathArg} must use its exact schema`];
+  }
+  const errors = [
+    ...validateClusterRelayVpnKey(valueArg.publicKey, `${pathArg} publicKey`),
+    ...validateClusterRelayListenAddress(valueArg.address, `${pathArg} address`),
+    ...validateClusterRelayHubPort(valueArg.quicPort, `${pathArg} quicPort`),
+    ...validateClusterRelayHubPort(valueArg.websocketPort, `${pathArg} websocketPort`),
+  ];
+  if (valueArg.quicPort === null && valueArg.websocketPort === null) {
+    errors.push(`${pathArg} must bind at least one of quicPort and websocketPort`);
+  }
+  return errors;
+};
+
 const validateClusterRelayEndpoint = (valueArg: unknown, pathArg: string): string[] => {
   if (!isRecord(valueArg)
-    || !hasExactKeys(valueArg, ['version', 'nodeId', 'listenAddress', 'listenPort'])) {
+    || !hasExactKeys(valueArg, ['version', 'nodeId', 'listenAddress', 'listenPort'], ['vpnHub'])) {
     return [`${pathArg} must use its exact schema`];
   }
   return [
@@ -244,6 +316,9 @@ const validateClusterRelayEndpoint = (valueArg: unknown, pathArg: string): strin
     ...validateClusterRelayIdentifier(valueArg.nodeId, `${pathArg} nodeId`),
     ...validateClusterRelayListenAddress(valueArg.listenAddress, `${pathArg} listenAddress`),
     ...validateClusterRelayListenPort(valueArg.listenPort, `${pathArg} listenPort`),
+    ...(Object.keys(valueArg).includes('vpnHub')
+      ? validateClusterRelayVpnHub(valueArg.vpnHub, `${pathArg} vpnHub`)
+      : []),
   ];
 };
 

package/ts/data/clustervpn.ts

@@ -0,0 +1,248 @@
+import { captureNetwork, failNetwork, networkCanonical, networkCounter, networkEqual, networkId, networkIpv4, networkList,
+  networkNoiseKey, networkPrivatePrefix, networkRecord, networkSafe, networkSorted,
+  requireNetwork } from '../private/networkcontract.js';
+
+/**
+ * One workload prefix a node owns inside its cluster's managed VPN, and the policy domain that
+ * names it in a grant. Both are Cloudly's words: the relay matches them, it never invents one.
+ */
+export interface IClusterVpnNetworkPrefix {
+  cidr: string;
+  policyDomain: string;
+}
+
+/**
+ * One member of a cluster's managed VPN.
+ *
+ * Membership is presence: a node the network does not list is not a member, so there is no
+ * disabled state to carry. `publicKey` is the node's own Noise public key, the one Cloudly issued
+ * the node's credential for, and `expiresAt` is that credential's expiry in Unix milliseconds — the
+ * hub stops relaying for a member whose window ended even if nothing pushes a new network.
+ */
+export interface IClusterVpnNetworkNode {
+  nodeId: string;
+  publicKey: string;
+  controlAddress: string;
+  expiresAt: number;
+  workloadPrefixes: IClusterVpnNetworkPrefix[];
+}
+
+/** One directed relay permission between two workload policy domains of two different nodes. */
+export interface IClusterVpnNetworkGrant {
+  sourceDomain: string;
+  destinationDomain: string;
+}
+
+/**
+ * The complete managed VPN of one cluster, as Cloudly states it to that cluster's relay.
+ *
+ * Complete, never a patch: a relay applies it as the whole authority its hub serves, so a member or
+ * a grant that is missing is withdrawn. `revision` is Cloudly's own counter for this authority and
+ * only ever rises; `authorityId` names the authority the hub is bound to, so a network compiled for
+ * another cluster is refused rather than applied.
+ */
+export interface IClusterVpnNetwork {
+  authorityId: string;
+  revision: number;
+  nodes: IClusterVpnNetworkNode[];
+  grants: IClusterVpnNetworkGrant[];
+}
+
+export const clusterVpnNetworkContract = Object.freeze({
+  /** The policy domain of a node's control address; the hub relays no grant between control domains. */
+  controlPolicyDomainPrefix: 'control:',
+  /** The policy domain of one workload lease, named by that lease's digest. */
+  workloadPolicyDomainPrefix: 'workload:',
+  maximumNodes: 256,
+  /** Per node; one workload lease the node's signed projection carries. */
+  maximumWorkloadPrefixes: 128,
+  maximumGrants: 4096,
+  maximumCanonicalBytes: 917_504,
+  completeness: 'whole-authority-never-a-patch',
+  membership: 'presence-only-an-absent-node-is-withdrawn',
+} as const);
+
+/**
+ * Every reason a relay refuses a pushed network, in the words the refusal leads with.
+ *
+ * A push is applied to a daemon whose lifetime Cloudly cannot see, so the refusal is the only
+ * statement about whether the cluster's hub carries this authority. The relay writes
+ * `<name>: <reason>` and Cloudly matches the name, which is why the names are stated here instead
+ * of being spelled out on both sides.
+ */
+export const applyClusterVpnNetworkRefusals = Object.freeze([
+  /** The network names another authority than the one this cluster's hub is bound to. */
+  'vpn-network-authority-foreign',
+  /** A revision the hub has already passed, or the same revision with different content. */
+  'vpn-network-revision-stale',
+] as const);
+
+/** One of the reasons a relay states that its hub did not take a network over. */
+export type TApplyClusterVpnNetworkRefusal = typeof applyClusterVpnNetworkRefusals[number];
+
+/**
+ * Every reason Cloudly states that a cluster has no managed VPN to push.
+ *
+ * Both are Cloudly reading its own records: a hub it cannot select, and a grant it cannot compile
+ * because hubs are per cluster and a grant whose two ends sit in different clusters has no path
+ * through any one of them.
+ */
+export const clusterVpnNetworkSelectionRefusals = Object.freeze([
+  /** The cluster's relay registered no hub, so no node of it may be sent to one. */
+  'relay-vpn-hub-absent',
+  /** The grant's two workloads are placed on two clusters; hub federation is a later lane. */
+  'grant-cross-cluster-unsupported',
+] as const);
+
+/** One of the reasons Cloudly states that it compiled no managed VPN for a cluster. */
+export type TClusterVpnNetworkSelectionRefusal = typeof clusterVpnNetworkSelectionRefusals[number];
+
+/** What a pushed network did to the cluster's hub, in the hub's own words. */
+export type TClusterVpnNetworkState = 'idle' | 'applying' | 'failed';
+
+export interface IApplyClusterVpnNetworkRequest {
+  network: IClusterVpnNetwork;
+}
+
+/**
+ * What the relay answers: the revision its hub has applied, or `null` while it has applied none,
+ * and what the hub is doing. `idle` means the pushed revision is the applied one.
+ */
+export interface IApplyClusterVpnNetworkResponse {
+  appliedRevision: number | null;
+  state: TClusterVpnNetworkState;
+}
+
+/**
+ * The pull carries no body. The relay's own socket names the cluster, and a hub daemon that just
+ * started holds nothing it could state about what it is missing.
+ */
+export type TGetClusterVpnNetworkRequest = Record<string, never>;
+
+/** `null` while the cluster has no managed VPN: no address plan, or no hub selected for it yet. */
+export interface IGetClusterVpnNetworkResponse {
+  network: IClusterVpnNetwork | null;
+}
+
+/** The policy domain of one node's control address. One rule, so both sides name it identically. */
+export const clusterVpnControlPolicyDomain = (addressValue: unknown): string => networkSafe(() =>
+  `${clusterVpnNetworkContract.controlPolicyDomainPrefix}${networkIpv4(addressValue)}`);
+
+/** The policy domain of one workload lease, from that lease's canonical digest. */
+export const clusterVpnWorkloadPolicyDomain = (digestValue: unknown): string => networkSafe(() => {
+  requireNetwork(typeof digestValue === 'string' && /^sha256:[a-f0-9]{64}$/.test(digestValue));
+  return `${clusterVpnNetworkContract.workloadPolicyDomainPrefix}${(digestValue as string).slice(7)}`;
+});
+
+const workloadPolicyDomain = (value: unknown): string => {
+  requireNetwork(typeof value === 'string'
+    && value.startsWith(clusterVpnNetworkContract.workloadPolicyDomainPrefix)
+    && /^[a-f0-9]{64}$/.test(value.slice(clusterVpnNetworkContract.workloadPolicyDomainPrefix.length)));
+  return value as string;
+};
+
+const prefixOf = (value: unknown): IClusterVpnNetworkPrefix => {
+  const item = networkRecord(value, ['cidr', 'policyDomain']);
+  return { cidr: networkPrivatePrefix(item.cidr), policyDomain: workloadPolicyDomain(item.policyDomain) };
+};
+
+const nodeOf = (value: unknown): IClusterVpnNetworkNode => {
+  const item = networkRecord(value, ['nodeId', 'publicKey', 'controlAddress', 'expiresAt', 'workloadPrefixes']);
+  return { nodeId: networkId(item.nodeId), publicKey: networkNoiseKey(item.publicKey), controlAddress: networkIpv4(item.controlAddress),
+    expiresAt: networkCounter(item.expiresAt),
+    workloadPrefixes: networkSorted(networkList(item.workloadPrefixes, clusterVpnNetworkContract.maximumWorkloadPrefixes, prefixOf),
+      prefix => prefix.cidr) };
+};
+
+const grantOf = (value: unknown): IClusterVpnNetworkGrant => {
+  const item = networkRecord(value, ['sourceDomain', 'destinationDomain']);
+  return { sourceDomain: workloadPolicyDomain(item.sourceDomain), destinationDomain: workloadPolicyDomain(item.destinationDomain) };
+};
+
+const grantKey = (grant: IClusterVpnNetworkGrant): string => `${grant.sourceDomain}\0${grant.destinationDomain}`;
+
+/**
+ * Structural snapshot of a complete cluster network.
+ *
+ * Every node, prefix and grant is stated once and in canonical order, and every grant names a
+ * workload domain this network itself carries, on two different nodes. That last rule is what a
+ * per-cluster hub means: a grant whose other end sits on another cluster's hub cannot be expressed
+ * here at all, which is why Cloudly refuses it by name while it compiles instead of pushing it.
+ */
+export const snapshotClusterVpnNetwork = (value: unknown): IClusterVpnNetwork => networkSafe(() => {
+  const captured = captureNetwork(value);
+  requireNetwork(new TextEncoder().encode(networkCanonical(captured)).length <= clusterVpnNetworkContract.maximumCanonicalBytes);
+  const item = networkRecord(captured, ['authorityId', 'revision', 'nodes', 'grants']);
+  const nodes = networkSorted(networkList(item.nodes, clusterVpnNetworkContract.maximumNodes, nodeOf), node => node.nodeId);
+  const grants = networkSorted(networkList(item.grants, clusterVpnNetworkContract.maximumGrants, grantOf), grantKey);
+  const domainOwners = new Map<string, string>();
+  const addresses = new Set<string>(), keys = new Set<string>(), cidrs = new Set<string>();
+  for (const node of nodes) {
+    requireNetwork(!keys.has(node.publicKey) && !addresses.has(node.controlAddress));
+    keys.add(node.publicKey); addresses.add(node.controlAddress);
+    for (const prefix of node.workloadPrefixes) {
+      requireNetwork(!cidrs.has(prefix.cidr) && !domainOwners.has(prefix.policyDomain));
+      cidrs.add(prefix.cidr); domainOwners.set(prefix.policyDomain, node.nodeId);
+    }
+  }
+  for (const grant of grants) {
+    const source = domainOwners.get(grant.sourceDomain), destination = domainOwners.get(grant.destinationDomain);
+    requireNetwork(source && destination && source !== destination);
+  }
+  return { authorityId: networkId(item.authorityId), revision: networkCounter(item.revision), nodes, grants };
+});
+
+export type TClusterVpnNetworkAdmission =
+  | { status: 'accepted' }
+  | { status: 'replay' }
+  | { status: 'refused'; reason: TApplyClusterVpnNetworkRefusal };
+
+/**
+ * The pure decision a relay makes about a pushed network against the one its hub holds, or null
+ * when the hub holds none — which is every hub that just started, because a daemon restart starts
+ * empty. A repeat of the held network is a replay the relay may apply again without effect; a lower
+ * revision, or the same revision with different content, is stale and refused by name.
+ */
+export const admitClusterVpnNetwork = (heldValue: unknown | null, nextValue: unknown): TClusterVpnNetworkAdmission =>
+  networkSafe(() => {
+    const next = snapshotClusterVpnNetwork(nextValue);
+    if (heldValue === null) return { status: 'accepted' };
+    const held = snapshotClusterVpnNetwork(heldValue);
+    if (held.authorityId !== next.authorityId) return { status: 'refused', reason: 'vpn-network-authority-foreign' };
+    if (next.revision > held.revision) return { status: 'accepted' };
+    return networkEqual(held, next) ? { status: 'replay' } : { status: 'refused', reason: 'vpn-network-revision-stale' };
+  });
+
+export const snapshotApplyClusterVpnNetworkRequest = (value: unknown): IApplyClusterVpnNetworkRequest => networkSafe(() => {
+  const item = networkRecord(captureNetwork(value), ['network']);
+  return { network: snapshotClusterVpnNetwork(item.network) };
+});
+
+export const snapshotApplyClusterVpnNetworkResponse = (value: unknown): IApplyClusterVpnNetworkResponse => networkSafe(() => {
+  const item = networkRecord(captureNetwork(value), ['appliedRevision', 'state']);
+  requireNetwork(item.state === 'idle' || item.state === 'applying' || item.state === 'failed');
+  return { appliedRevision: item.appliedRevision === null ? null : networkCounter(item.appliedRevision), state: item.state };
+});
+
+/**
+ * Compare the answer with the exact SENT network: a hub that reports itself idle has applied the
+ * revision it was sent, and no hub can report having applied a later one than exists.
+ */
+export const bindApplyClusterVpnNetworkResponse = (value: unknown, sentRequestValue: unknown): IApplyClusterVpnNetworkResponse =>
+  networkSafe(() => {
+    const response = snapshotApplyClusterVpnNetworkResponse(value);
+    const sent = snapshotApplyClusterVpnNetworkRequest(sentRequestValue);
+    requireNetwork(response.appliedRevision === null || response.appliedRevision <= sent.network.revision);
+    requireNetwork(response.state !== 'idle' || response.appliedRevision === sent.network.revision);
+    return response;
+  });
+
+export const snapshotGetClusterVpnNetworkRequest = (value: unknown): TGetClusterVpnNetworkRequest => networkSafe(() => {
+  networkRecord(captureNetwork(value), []);
+  return {};
+});
+
+export const snapshotGetClusterVpnNetworkResponse = (value: unknown): IGetClusterVpnNetworkResponse => networkSafe(() => {
+  const item = networkRecord(captureNetwork(value), ['network']);
+  return { network: item.network === null ? null : snapshotClusterVpnNetwork(item.network) };
+});

package/ts/data/index.ts

@@ -1,6 +1,7 @@
 export * from './cloudlyconfig.js';
 export * from './cluster.js';
 export * from './clusterruntime.js';
+export * from './clustervpn.js';
 export * from './clusteringress.js';
 export * from './config.js';
 export * from './corestore.js';

package/ts/data/networkaddressplan.ts

@@ -1,9 +1,10 @@
 import type { TSha256Digest } from './immutableimage.js';
 import type { IRuntimeNetworkProtectedAuthority } from './networkauthority.js';
-import { computeRuntimeNetworkProtectedAuthorityDigest, snapshotRuntimeNetworkProtectedAuthority } from './networkauthority.js';
-import type { IGetRuntimeManagedVpnCredentialResponse } from './networkcredential.js';
-import { captureNetwork, failNetwork, networkContains, networkCounter, networkEqual, networkId, networkIpv4, networkOverlaps,
-  networkPrefixBounds, networkPrivatePrefix, networkRecord, networkSafe, requireNetwork } from '../private/networkcontract.js';
+import { computeRuntimeNetworkProtectedAuthorityDigest, runtimeNetworkAuthorityContract,
+  snapshotRuntimeNetworkProtectedAuthority } from './networkauthority.js';
+import { captureNetwork, failNetwork, networkContains, networkCounter, networkEqual, networkId, networkIpv4, networkList,
+  networkOverlaps, networkPrefix, networkPrefixBounds, networkPrivatePrefix, networkRecord, networkSafe,
+  requireNetwork } from '../private/networkcontract.js';
 
 /**
  * The address space an administrator gives the runtime network, and the one input the protected
@@ -18,16 +19,36 @@ export interface IRuntimeNetworkAddressPlan {
   prefixes: string[];
   pools: IRuntimeNetworkProtectedAuthority['pools'];
   resolvers: IRuntimeNetworkProtectedAuthority['resolvers'];
-  /** Without the VPN relay, which the composed authority adds as a UDP platform endpoint. */
+  /** Without the cluster hubs, which the composed authority adds from the hubs it is given. */
   platformEndpoints: IRuntimeNetworkProtectedAuthority['platformEndpoints'];
   vpn: {
     /** The private prefix VPN control addresses are allocated from. */
     controlPrefix: string;
-    /** The endpoint every node dials for the managed VPN. */
-    relay: IGetRuntimeManagedVpnCredentialResponse['relay'];
+    /**
+     * The protected prefix every cluster hub binds inside.
+     *
+     * The endpoints themselves are no administrator's input: a cluster's relay reports the one it
+     * bound and the composition turns it into platform endpoints, so this prefix is what an
+     * administrator reserves for them.
+     */
+    hubPrefix: string;
   };
 }
 
+/**
+ * One cluster's managed VPN hub, as the cluster's relay bound it.
+ *
+ * The hub is its cluster's own packet relay, so `clusterId` names both the hub and the authority
+ * that may select it, and `address` is an underlay address inside the plan's `vpn.hubPrefix`. A hub
+ * offers at least one transport; the port of a transport it did not bind is `null`.
+ */
+export interface IRuntimeNetworkVpnHub {
+  clusterId: string;
+  address: string;
+  quicPort: number | null;
+  websocketPort: number | null;
+}
+
 /** What an administrator writes; Cloudly supplies the id and the revision. */
 export type TRuntimeNetworkAddressPlanWritableData = Omit<IRuntimeNetworkAddressPlan, 'id' | 'revision'>;
 
@@ -58,9 +79,54 @@ export const runtimeNetworkAddressPlanContract = Object.freeze({
    * is stated: the private-range rule already keeps the control prefix at /8 or longer.
    */
   maximumControlPrefixLength: 30,
-  relayProtocol: 'udp',
+  /**
+   * Every transport a hub may offer, in the order a node prefers them.
+   *
+   * One row states all three facts that belong together: the transport a credential names, the
+   * suffix its platform endpoint id carries, and the protocol the endpoint is composed with. A hub
+   * that bound both transports therefore contributes exactly two endpoints of one address.
+   */
+  hubTransports: Object.freeze([
+    Object.freeze({ transport: 'quic', endpointSuffix: 'quic', protocol: 'udp' }),
+    Object.freeze({ transport: 'websocket', endpointSuffix: 'ws', protocol: 'tcp' }),
+  ]),
 } as const);
 
+/** How a node reaches its cluster's hub, read off the one table that states the transports. */
+export type TRuntimeNetworkVpnTransport = typeof runtimeNetworkAddressPlanContract.hubTransports[number]['transport'];
+
+/** The port a hub bound for one transport, or null when it did not bind that transport. */
+const hubPort = (hub: IRuntimeNetworkVpnHub, transport: TRuntimeNetworkVpnTransport): number | null =>
+  transport === 'quic' ? hub.quicPort : hub.websocketPort;
+
+const byEndpointId = <T extends { id: string }>(left: T, right: T): number =>
+  left.id < right.id ? -1 : left.id > right.id ? 1 : 0;
+
+const hubOf = (value: unknown): IRuntimeNetworkVpnHub => {
+  const item = networkRecord(value, ['clusterId', 'address', 'quicPort', 'websocketPort']);
+  const port = (value: unknown): number | null => value === null ? null : networkCounter(value, 65535);
+  const hub: IRuntimeNetworkVpnHub = { clusterId: networkId(item.clusterId), address: networkIpv4(item.address),
+    quicPort: port(item.quicPort), websocketPort: port(item.websocketPort) };
+  // A hub that bound no transport is not reachable, so it is not a hub a node could be sent to.
+  requireNetwork(runtimeNetworkAddressPlanContract.hubTransports.some(row => hubPort(hub, row.transport) !== null));
+  return hub;
+};
+
+/**
+ * The platform endpoints one hub contributes to a protected authority: one per transport it bound,
+ * in id order. Every reader derives the same ids from this one function — the composition that seals
+ * the authority, and the router selection that names which of them a node may dial.
+ */
+export const runtimeNetworkVpnHubEndpoints = (hubValue: unknown): IRuntimeNetworkProtectedAuthority['platformEndpoints'] =>
+  networkSafe(() => {
+    const hub = hubOf(captureNetwork(hubValue));
+    return runtimeNetworkAddressPlanContract.hubTransports
+      .filter(row => hubPort(hub, row.transport) !== null)
+      .map(row => ({ id: `${hub.clusterId}:${row.endpointSuffix}`, address: hub.address,
+        protocol: row.protocol, port: hubPort(hub, row.transport) as number }))
+      .sort(byEndpointId);
+  });
+
 /**
  * The structural authority validator reads a frame's shape and nothing else, and a plan fixes none of
  * the frame, so every valid frame decides a plan the same way. The digest is a well-formed
@@ -81,31 +147,36 @@ const authorityOf = (
   generation: frame.generation, controller: frame.controller, previous: frame.previous, egressAuthorities: frame.egressAuthorities,
   prefixes: sets.prefixes, pools: sets.pools, resolvers: sets.resolvers, platformEndpoints: sets.platformEndpoints, digest: unsealedDigest });
 
-const setsWithRelay = (plan: IRuntimeNetworkAddressPlan): TAuthoritySets => ({
+const setsWithHubs = (plan: IRuntimeNetworkAddressPlan, hubs: IRuntimeNetworkVpnHub[]): TAuthoritySets => ({
   prefixes: plan.prefixes, pools: plan.pools, resolvers: plan.resolvers,
-  platformEndpoints: [...plan.platformEndpoints, { ...plan.vpn.relay, protocol: runtimeNetworkAddressPlanContract.relayProtocol }]
-    .sort((left, right) => left.id < right.id ? -1 : left.id > right.id ? 1 : 0),
+  platformEndpoints: [...plan.platformEndpoints, ...hubs.flatMap(runtimeNetworkVpnHubEndpoints)].sort(byEndpointId),
 });
 
 const vpnOf = (value: unknown): IRuntimeNetworkAddressPlan['vpn'] => {
-  const item = networkRecord(value, ['controlPrefix', 'relay']);
-  const relay = networkRecord(item.relay, ['id', 'address', 'port']);
+  const item = networkRecord(value, ['controlPrefix', 'hubPrefix']);
   const controlPrefix = networkPrivatePrefix(item.controlPrefix);
   requireNetwork(Number(controlPrefix.split('/')[1]) <= runtimeNetworkAddressPlanContract.maximumControlPrefixLength);
-  return { controlPrefix, relay: { id: networkId(relay.id), address: networkIpv4(relay.address), port: networkCounter(relay.port, 65535) } };
+  return { controlPrefix, hubPrefix: networkPrefix(item.hubPrefix) };
 };
 
-/** The control prefix is protected, and no pool, resolver or platform endpoint, the relay included, sits inside it. */
-const requireVpnProtected = (authority: IRuntimeNetworkProtectedAuthority, controlPrefix: string): void => {
-  requireNetwork(authority.prefixes.some(prefix => networkContains(prefix, controlPrefix))
-    && authority.pools.every(pool => !networkOverlaps(pool.prefix, controlPrefix))
-    && [...authority.resolvers, ...authority.platformEndpoints].every(endpoint => !networkContains(controlPrefix, `${endpoint.address}/32`)));
+/**
+ * Both VPN prefixes are protected, they hold none of the plan's own pools, resolvers or platform
+ * endpoints, and they do not overlap each other: control addresses live inside the tunnel and hub
+ * endpoints on the underlay, so one prefix can never contain the other's addresses.
+ */
+const requireVpnProtected = (authority: IRuntimeNetworkProtectedAuthority, vpn: IRuntimeNetworkAddressPlan['vpn']): void => {
+  const endpoints = [...authority.resolvers, ...authority.platformEndpoints];
+  requireNetwork([vpn.controlPrefix, vpn.hubPrefix].every(prefix =>
+    authority.prefixes.some(range => networkContains(range, prefix))
+      && authority.pools.every(pool => !networkOverlaps(pool.prefix, prefix))
+      && endpoints.every(endpoint => !networkContains(prefix, `${endpoint.address}/32`)))
+    && !networkOverlaps(vpn.controlPrefix, vpn.hubPrefix));
 };
 
 /**
- * Structural snapshot for exact persistence and for a plan write. A plan passes only when both
- * authorities it can describe pass the protected authority's own validator: its sets alone, and
- * its sets with the relay added, so no plan can compose an authority that contract refuses.
+ * Structural snapshot for exact persistence and for a plan write. The plan's own sets pass the
+ * protected authority's own validator, so no plan can describe an authority that contract refuses,
+ * and both VPN prefixes are reserved inside the protected space the plan states.
  */
 export const snapshotRuntimeNetworkAddressPlan = (value: unknown): IRuntimeNetworkAddressPlan => networkSafe(() => {
   const item = networkRecord(captureNetwork(value), ['id', 'revision', 'prefixes', 'pools', 'resolvers', 'platformEndpoints', 'vpn']);
@@ -114,22 +185,27 @@ export const snapshotRuntimeNetworkAddressPlan = (value: unknown): IRuntimeNetwo
     platformEndpoints: item.platformEndpoints }, validationFrame);
   const plan: IRuntimeNetworkAddressPlan = { id: runtimeNetworkAddressPlanContract.id, revision: networkCounter(item.revision),
     prefixes: own.prefixes, pools: own.pools, resolvers: own.resolvers, platformEndpoints: own.platformEndpoints, vpn: vpnOf(item.vpn) };
-  requireVpnProtected(authorityOf(setsWithRelay(plan), validationFrame), plan.vpn.controlPrefix);
+  requireVpnProtected(own, plan.vpn);
   return plan;
 });
 
 /**
  * The protected authority a plan describes inside a producer's frame, digest included: the plan's
- * sets with the VPN relay as the UDP platform endpoint every node dials. Both inputs are read before
- * the digest is computed.
+ * sets plus the endpoints of every cluster hub it is given, each bound inside `vpn.hubPrefix`. One
+ * cluster contributes one hub, so `hubs` never names a cluster twice. All inputs are read before the
+ * digest is computed; an empty `hubs` composes the authority of a runtime network whose clusters
+ * have not registered a hub yet.
  */
 export const composeRuntimeNetworkProtectedAuthority = async (
-  planValue: unknown, frameValue: unknown,
+  planValue: unknown, frameValue: unknown, hubsValue: unknown,
 ): Promise<IRuntimeNetworkProtectedAuthority> => {
   try {
     const plan = snapshotRuntimeNetworkAddressPlan(planValue);
     const frame = networkRecord(captureNetwork(frameValue), ['id', 'generation', 'controller', 'previous', 'egressAuthorities']);
-    const authority = authorityOf(setsWithRelay(plan), frame);
+    const hubs = networkList(captureNetwork(hubsValue), runtimeNetworkAuthorityContract.maximumPlatformEndpoints, hubOf);
+    requireNetwork(new Set(hubs.map(hub => hub.clusterId)).size === hubs.length
+      && hubs.every(hub => networkContains(plan.vpn.hubPrefix, `${hub.address}/32`)));
+    const authority = authorityOf(setsWithHubs(plan, hubs), frame);
     return { ...authority, digest: await computeRuntimeNetworkProtectedAuthorityDigest(authority) };
   } catch { return failNetwork(); }
 };