@serve.zone/interfaces 32.3.0 → 32.5.0

package/ts/data/clustervpn.ts

@@ -0,0 +1,248 @@
+import { captureNetwork, failNetwork, networkCanonical, networkCounter, networkEqual, networkId, networkIpv4, networkList,
+  networkNodeId, 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: networkNodeId(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/isolatedrestore.ts

@@ -12,6 +12,7 @@ import {
   strictCanonicalJsonRules,
 } from '../private/canonicaljson.js';
 import { hasExactKeys } from '../private/dataproperties.js';
+import { isClusterNodeId } from '../private/nodeidentifier.js';
 
 /** Operations carried by a short-lived, single-operation restore grant. */
 export const isolatedRestoreGrantOperations = Object.freeze([
@@ -521,6 +522,14 @@ const readIdentifier = (valueArg: unknown, fieldNameArg: string): string => {
   return valueArg;
 };
 
+/** A node of the cluster, read in the node vocabulary the controller named it in. */
+const readNodeId = (valueArg: unknown, fieldNameArg: string): string => {
+  if (!isClusterNodeId(valueArg)) {
+    return fail(`${fieldNameArg} must be a node id`);
+  }
+  return valueArg;
+};
+
 const readScopedId = (valueArg: unknown, fieldNameArg: string): string => {
   if (typeof valueArg !== 'string' || !canonicalScopedIdPattern.test(valueArg)) {
     return fail(`${fieldNameArg} must be a canonical scoped identifier`);
@@ -1469,7 +1478,7 @@ export const normalizeIsolatedRestoreNodeControl = <TControlGeneric>(
   const request = readRecord(valueArg, 'node control request');
   assertExactKeys(request, ['nodeId', 'control'], 'node control request');
   return Object.freeze({
-    nodeId: readIdentifier(request.nodeId, 'node control request.nodeId'),
+    nodeId: readNodeId(request.nodeId, 'node control request.nodeId'),
     control: normalizeControlArg(request.control),
   });
 };
@@ -1656,7 +1665,7 @@ export const normalizeIsolatedRestoreProgress = (
   );
   const preparedAt = readSafeInteger(progress.preparedAt, 'restore progress.preparedAt', 1);
   const normalized: IIsolatedRestoreProgress = {
-    nodeId: readIdentifier(progress.nodeId, 'restore progress.nodeId'),
+    nodeId: readNodeId(progress.nodeId, 'restore progress.nodeId'),
     restoreId: readScopedId(progress.restoreId, 'restore progress.restoreId'),
     stagingArchiveId: readScopedId(
       progress.stagingArchiveId,
@@ -1737,7 +1746,7 @@ export const bindIsolatedRestoreProgressToNode = (
 ): Readonly<IIsolatedRestoreProgress> => {
   const expectation = readRecord(expectationArg, 'restore progress expectation');
   assertExactKeys(expectation, ['nodeId', 'restoreId'], 'restore progress expectation');
-  const nodeId = readIdentifier(expectation.nodeId, 'restore progress expectation.nodeId');
+  const nodeId = readNodeId(expectation.nodeId, 'restore progress expectation.nodeId');
   const restoreId = readScopedId(
     expectation.restoreId,
     'restore progress expectation.restoreId',

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(); }
 };

package/ts/data/networkauthority.ts

@@ -2,6 +2,7 @@ import type { TSha256Digest } from './immutableimage.js';
 import type { IRuntimeAuthorityReference, IRuntimeController } from './runtimeassignment.js';
 import { canonicalizeStrictJson, createCanonicalJsonSha256Hex } from '../private/canonicaljson.js';
 import { networkPrefix, networkPrivatePrefix } from '../private/networkcontract.js';
+import { isClusterNodeId } from '../private/nodeidentifier.js';
 
 /** Controller declaration; a digest does not authenticate completeness or activate a pool. */
 export interface IRuntimeNetworkProtectedAuthority {
@@ -91,6 +92,11 @@ const id = (value: unknown): string => {
   requireValue(typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/.test(value));
   return value;
 };
+/** A node id, in the node vocabulary every other contract reads it in. */
+const nodeId = (value: unknown): string => {
+  requireValue(isClusterNodeId(value));
+  return value as string;
+};
 const integer = (value: unknown, maximum = Number.MAX_SAFE_INTEGER - 1): number => {
   requireValue(typeof value === 'number' && Number.isSafeInteger(value) && value > 0 && value <= maximum);
   return value;
@@ -185,7 +191,7 @@ export const snapshotRuntimeNetworkProtectedAuthority = (value: unknown): IRunti
   requireValue(new Set(allEndpointKeys).size === allEndpointKeys.length);
   const egressAuthorities = sorted(list(item.egressAuthorities, runtimeNetworkAuthorityContract.maximumEgressAuthorities, value => {
     const authority = record(value, ['nodeId', 'runtimeNamespace']);
-    return { nodeId: id(authority.nodeId), runtimeNamespace: id(authority.runtimeNamespace) };
+    return { nodeId: nodeId(authority.nodeId), runtimeNamespace: id(authority.runtimeNamespace) };
   }), value => canonical([value.nodeId, value.runtimeNamespace]));
   requireValue(egressAuthorities.length > 0);
   return { id: identity, generation, controller: controller(item.controller), previous,
@@ -217,7 +223,7 @@ export const snapshotRuntimeNetworkHandoffLease = (value: unknown): IRuntimeNetw
   requireValue(typeof item.conntrackLabel === 'string' && /^[a-f0-9]{32}$/.test(item.conntrackLabel)
     && item.conntrackLabel !== '0'.repeat(32));
   return { id: id(item.id), generation: integer(item.generation), controller: controller(item.controller),
-    nodeId: id(item.nodeId), runtimeNamespace: id(item.runtimeNamespace), protectedAuthority: reference(item.protectedAuthority),
+    nodeId: nodeId(item.nodeId), runtimeNamespace: id(item.runtimeNamespace), protectedAuthority: reference(item.protectedAuthority),
     routerIncarnationId: id(item.routerIncarnationId), transit: { poolId: id(transit.poolId), prefix: transitPrefix, routerAddress, hostAddress },
     sourcePortRanges, conntrackZone: integer(item.conntrackZone, 65535), conntrackLabel: item.conntrackLabel, digest: digest(item.digest) };
 });