@serve.zone/interfaces 32.3.0 → 32.5.0

package/readme.md

@@ -31,6 +31,34 @@ import { appstore, data, platform, platformservice, protocol, requests } from '@
 
 This package intentionally has no service implementation logic. It is a stable vocabulary for services that need to agree on payload shape, method names, and response types.
 
+### Identifier Vocabularies
+
+Two vocabularies name things in these contracts, and which one a member uses is part of the
+contract.
+
+| Vocabulary | Rule | Members |
+| --- | --- | --- |
+| Canonical identifier | `^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$` — first character alphanumeric, up to 200 characters | organizations, clusters, services, namespaces, sessions, assignments, attempts, authorities, pools, endpoints and every content id derived from them |
+| Node id | `^[A-Za-z0-9_-]{1,128}$` — the URL alphabet, a leading `-` or `_` included, up to 128 characters | every member that names a node of a cluster |
+
+A node may be named `-abc` or `_abc`: enrollment, the runtime session registration and the Spark
+wire admit a node id that begins with a separator, so every member that names the same node admits
+one too. `data.isClusterNodeId(value)` is that rule, and it is the rule at every node-bearing member:
+`nodeId` on a session binding, a registration, an enrollment, a Spark heartbeat, a relay block, an
+assignment, a workload lease, a handoff lease, a DNS-lease renewal run, a protection receipt, an
+egress authority, a cluster VPN node, an ingress registration, a traffic bucket, a Corestore
+inventory and an isolated-restore node control; `id` on a router incarnation and on a node
+retirement; `cloudlyNodeId` on a cluster runtime target and on a secret runtime target; and
+`placement.nodeIds` on a service runtime spec. A service that stores or forwards a node id
+should judge it with the same reader rather than with the canonical one, which would refuse a node
+these contracts themselves enrolled and registered.
+
+A replica id is the one composed name: a producer names a replica slot `<node id>.<index>`, counted
+from zero. `data.isRuntimeReplicaId(value)` reads it by decomposition — the part before the last dot
+in the node vocabulary, the index on its own and never zero-padded — and reads a name that carries
+no such index, a zero-padded `node-a.01` among them, as an opaque slot name in the canonical
+identifier vocabulary.
+
 WorkloadInit release verifiers should use the dedicated Node-compatible subpath:
 
 ```typescript
@@ -490,17 +518,25 @@ The `getRuntimeManagedVpnCredential` method contract in `requests.runtimesession
 uses `IGetRuntimeManagedVpnCredentialRequest` and
 `IGetRuntimeManagedVpnCredentialResponse`. Its request carries the exact current
 session and signed projection reference. The secret response repeats those
-bindings and supplies a QUIC relay tuple, managed authority ID, Noise server
-public key, client keypair and expiry in Unix milliseconds. Keep the response
-process-local; never persist, hash, log or embed it in a signed projection.
+bindings and supplies the `hub` tuple the node dials, the `transport` it dials it
+over (`quic` or `websocket`), the managed authority ID, the Noise server public
+key, the client keypair and the expiry in Unix milliseconds. `serverName` is present
+exactly when the transport is `websocket` — the TLS name that hub is dialled under,
+which the node cross-checks against the relay origin it stores — and absent for
+`quic`, which is dialled on the address alone. The hub is the node's own cluster's
+relay (see [Cluster VPN Hub And Network](#cluster-vpn-hub-and-network)). Keep the
+response process-local; never persist, hash, log or embed it in a signed projection.
 
 `snapshotGetRuntimeManagedVpnCredentialRequest` and its response counterpart
 capture closed detached JSON shapes and canonical 32-byte key encodings.
 `bindGetRuntimeManagedVpnCredentialRequest(request, projection, trustedSession)`
 validates the complete projection digest and binds node, controller, namespace,
 physical-session identity and projection reference. The response binder takes
-`(response, request, projection, trustedSession, now, renewal = null)` and additionally requires
-the relay's exact UDP tuple to be selected in `router.platformEndpointIds`.
+`(response, request, projection, trustedSession, now, renewal = null)` and additionally requires the
+hub's exact tuple to be selected in `router.platformEndpointIds`, carrying the protocol of the
+credential's transport — `udp` for `quic` and `tcp` for `websocket`, as
+`runtimeNetworkAddressPlanContract.hubTransports` states. A relay therefore cannot name itself: the
+endpoint has to be one the node's **signed** projection already selected.
 Expiry must be after the caller-qualified time and no later than the referenced
 projection's effective DNS window (see [DNS Lease Renewals](#dns-lease-renewals));
 acceptance before that window starts rejects.
@@ -650,30 +686,45 @@ const window = await data.getRuntimeNetworkEffectiveDnsWindow(admittedProjection
 
 `data.IRuntimeNetworkAddressPlan` is the address space an administrator gives the runtime network,
 and the single input Cloudly composes the protected authority from:
-`{ id: 'address-plan', revision, prefixes, pools, resolvers, platformEndpoints, vpn: { controlPrefix, relay } }`.
-Pools, resolvers and platform endpoints use the protected authority's own element shapes, and the
-relay uses the managed-VPN credential's `{ id, address, port }`. `platformEndpoints` never lists the
-relay: the composed authority adds it, in id order, as the UDP platform endpoint every node dials.
+`{ id: 'address-plan', revision, prefixes, pools, resolvers, platformEndpoints, vpn: { controlPrefix, hubPrefix } }`.
+Pools, resolvers and platform endpoints use the protected authority's own element shapes.
+`controlPrefix` is the private prefix VPN control addresses are allocated from, and `hubPrefix` is
+the protected prefix every cluster's VPN hub binds inside. The hub endpoints themselves are no
+administrator's input: each cluster's relay reports what it bound, and the composition turns that
+into platform endpoints, so `platformEndpoints` never lists one.
 
 `snapshotRuntimeNetworkAddressPlan` refuses any plan that could describe an authority the authority
-contract refuses. It runs `snapshotRuntimeNetworkProtectedAuthority` twice, once over the plan's
-own sets and once with the relay added, so overlapping pools, more than 16 resolvers, a resolver or
-endpoint outside `prefixes` or inside a pool, and a relay that `prefixes` do not cover are all
-refused by that one validator. On top it requires the VPN `controlPrefix` to be a private prefix no
-longer than /30 (`runtimeNetworkAddressPlanContract.maximumControlPrefixLength`) inside `prefixes`
-that overlaps no pool and holds no resolver or platform endpoint, the relay included. No minimum
-length is stated: the private-range rule already keeps it at /8 or longer.
-`composeRuntimeNetworkProtectedAuthority(plan, frame)` is the composition itself: the producer
+contract refuses: it runs `snapshotRuntimeNetworkProtectedAuthority` over the plan's own sets, so
+overlapping pools, more than 16 resolvers and a resolver or endpoint outside `prefixes` or inside a
+pool are all refused by that one validator. On top it requires both VPN prefixes to sit inside
+`prefixes`, to overlap no pool, to hold no resolver or platform endpoint, and never to overlap each
+other — control addresses live inside the tunnel, hub endpoints on the underlay. `controlPrefix` is
+additionally a private prefix no longer than /30
+(`runtimeNetworkAddressPlanContract.maximumControlPrefixLength`); no minimum length is stated,
+because the private-range rule already keeps it at /8 or longer.
+
+`data.IRuntimeNetworkVpnHub { clusterId, address, quicPort, websocketPort }` is one cluster's hub as
+its relay bound it, with `null` for a transport it did not bind and at least one of the two bound.
+`runtimeNetworkVpnHubEndpoints(hub)` is the one derivation of what it contributes:
+`<clusterId>:quic` on `udp` and `<clusterId>:ws` on `tcp`, in id order, as
+`runtimeNetworkAddressPlanContract.hubTransports` states. Every reader calls it — the composition
+that seals the authority and the router selection that names which endpoint a node may dial — so
+two readers can never derive two ids for one hub.
+`composeRuntimeNetworkProtectedAuthority(plan, frame, hubs)` is the composition itself: the producer
 supplies the frame (`TRuntimeNetworkProtectedAuthorityFrame`: authority id, generation, controller,
-previous reference and egress authorities) and receives the complete authority with its digest, so
-the validator and the protection producer can never compose differently.
+previous reference and egress authorities) and the hubs of the clusters that registered one, and
+receives the complete authority with its digest, so the validator and the protection producer can
+never compose differently. Each hub's address must sit inside `vpn.hubPrefix` and one cluster is
+named once; an empty `hubs` composes the authority of a runtime network whose clusters have no hub
+yet. One hub costs up to two of the authority's 64 platform endpoints, so 32 clusters fit one
+authority.
 
 `admitRuntimeNetworkAddressPlanChange(previous | null, next)` is the pure decision for a plan write at
 the following revision; any other revision is a contract violation. Leases and the managed VPN
 outlive a plan revision, so it answers:
 
 - `unchanged` when the content equals the stored plan; Cloudly writes nothing;
-- `refused` with `plan-vpn-immutable` when the VPN differs, `plan-pool-removed` when any pool is gone
+- `refused` with `plan-vpn-immutable` when either VPN prefix differs, `plan-pool-removed` when any pool is gone
   or changed its purpose or prefix, and `plan-prefix-shrunk` when the new prefixes, however split,
   no longer cover every address the old ones did;
 - `accepted` with the ids of the resolvers and platform endpoints the change removes or changes. An
@@ -722,7 +773,19 @@ rule read the other way, for a receiver checking a list it was sent. Canonical i
 strictly increasing in the code-unit order of the names themselves — a rule a peer
 in another language implements from the vocabulary alone, rather than from the
 order this package happens to declare it in — and both directions compare through
-that one rule, so neither can drift from the other. All fields except the digest itself participate in a domain-separated
+that one rule, so neither can drift from the other.
+
+`workload.registryHost` is the registry that published the image, which is the publication identity
+the image release is bound to, and it is never rewritten. `workload.pullEndpoint` is the optional
+`host[:port]` the node fetches the bytes from instead — a cluster whose relay forwards the registry
+states the relay's own origin, so a node pulls inside its cluster and nothing cluster-side dials the
+control plane. `data.buildRuntimeAssignmentImageReference(workload)` is the one place that choice is
+made: `pullEndpoint ?? registryHost`, digest-pinned either way, so the endpoint decides reachability
+and never content, and a controller and a node cannot disagree about the reference. Absence stays
+absence: an assignment that states no endpoint is different content, and so a different digest, from
+one that does.
+
+All fields except the digest itself participate in a domain-separated
 SHA-256 digest. Digests provide integrity and compare-and-swap identity;
 authentication must separately establish the trusted controller/node scope.
 
@@ -1666,6 +1729,54 @@ const registrationReasons = data.validateRegisterClusterRelayRequest(registratio
 How the relay reaches each node's Corestore is part of the same document: see
 [Corestore Through The Relay](#corestore-through-the-relay).
 
+### Cluster VPN Hub And Network
+
+A cluster's relay is also that cluster's managed VPN hub: every node of the cluster dials it, and
+an inter-node workload packet is relayed inside the cluster instead of crossing the control plane.
+Cloudly keeps every authority — it compiles the network and issues each node's credential — and
+carries no packet.
+
+A relay that bound a hub says so in its registration, in `relay.vpnHub`:
+`data.IClusterRelayVpnHub { publicKey, address, quicPort, websocketPort }`. It reports what it
+bound, exactly like `listenAddress` and `listenPort`: `address` is an IPv4 literal inside the
+address plan's `vpn.hubPrefix`, a transport it did not bind is `null`, and at least one of the two
+is bound. `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 — this advertisement, the managed VPN credential's
+keys and a cluster network's nodes all pass the same reader. A relay names no endpoint id and no
+TLS name of its own: Cloudly composes the endpoints with `runtimeNetworkVpnHubEndpoints` (see
+[Runtime Network Address Plan](#runtime-network-address-plan)) and states the TLS name from the
+origin it published for that relay. The member is optional — a relay that serves no hub registers
+exactly as before, and Cloudly selects no hub for that cluster, stating `relay-vpn-hub-absent`.
+`validateClusterRelayVpnHub(value, path?)` returns one named reason per violation.
+
+`data.IClusterVpnNetwork { authorityId, revision, nodes, grants }` is the whole managed VPN of one
+cluster. It is never a patch: a node or a grant the network does not carry is withdrawn, and
+membership is presence, so there is no enabled flag. Each node states `{ nodeId, publicKey,
+controlAddress, expiresAt, workloadPrefixes }`, where `expiresAt` is that node's credential expiry
+in Unix milliseconds and each prefix is `{ cidr, policyDomain }`. Each grant is one directed
+`{ sourceDomain, destinationDomain }` pair. `clusterVpnControlPolicyDomain(address)` and
+`clusterVpnWorkloadPolicyDomain(leaseDigest)` state the domain names once for both sides.
+
+`snapshotClusterVpnNetwork` requires sorted, unique members, prefixes and grants, and requires
+every grant to join two workload domains the network itself carries, on two different nodes. That
+is what a per-cluster hub means: a grant whose other end sits on another cluster's hub cannot be
+expressed at all, which is why Cloudly refuses it while it compiles, by name, with
+`grant-cross-cluster-unsupported` from `data.clusterVpnNetworkSelectionRefusals`.
+`clusterVpnNetworkContract` bounds a network at 256 nodes, 128 workload prefixes per node, 4096
+grants and 917 504 canonical bytes.
+
+`applyClusterVpnNetwork { network }` is Cloudly's push over the relay's already registered session;
+the relay answers `{ appliedRevision, state }`, where `state` is `idle`, `applying` or `failed` and
+`idle` means the pushed revision is the applied one — which is what
+`bindApplyClusterVpnNetworkResponse(response, sentRequest)` checks. `admitClusterVpnNetwork(held |
+null, next)` is the pure decision the relay makes against what its hub holds: `accepted` for a
+higher revision or an empty hub, `replay` for a repeat, and `refused` with
+`vpn-network-revision-stale` or `vpn-network-authority-foreign` from
+`data.applyClusterVpnNetworkRefusals`. `getClusterVpnNetwork` is the pull the other way, with no
+request body — the relay's socket names the cluster — answering `{ network }` or `{ network: null }`
+while the cluster has none. A hub daemon starts empty and its lifetime is the relay's own, so a
+relay that just bound one pulls instead of waiting for the next push.
+
 ### Cluster Ingress
 
 A cluster's ingress terminates TLS for the hostnames its services publish and forwards to the

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/interfaces',
-  version: '32.3.0',
+  version: '32.5.0',
   description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 }

package/ts/data/cluster.ts

@@ -5,6 +5,8 @@ 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 { isClusterNodeId } from '../private/nodeidentifier.js';
+import { networkNoiseKey } from '../private/networkcontract.js';
 
 export interface ICluster {
   id: string;
@@ -62,6 +64,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 +109,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;
@@ -202,7 +228,7 @@ const validateClusterRelayVersion = (valueArg: unknown, pathArg: string): string
 
 /** The same identifier rule a node's own runtime session registers under. */
 const validateClusterRelayIdentifier = (valueArg: unknown, pathArg: string): string[] => (
-  typeof valueArg === 'string' && /^[A-Za-z0-9_-]{1,128}$/.test(valueArg)
+  isClusterNodeId(valueArg)
     ? []
     : [`${pathArg} must be 1 to 128 characters of letters, digits, underscore or hyphen`]
 );
@@ -234,9 +260,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 +317,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/clusteringress.ts

@@ -2,6 +2,7 @@ import { isPlausibleUnicastIpv4 } from '../private/ipv4.js';
 import { isUtcCalendarDay } from '../private/utccalendarday.js';
 import { validateProtocolOfferOn } from '../protocol.js';
 import { hasExactKeys } from '../private/dataproperties.js';
+import { isClusterNodeId } from '../private/nodeidentifier.js';
 
 /**
  * The cluster ingress contracts.
@@ -310,11 +311,11 @@ export const validateClusterTrafficStatistics = (
     return [`${pathArg} must use its exact schema`];
   }
   const errors: string[] = [];
-  for (const key of ['serviceId', 'nodeId'] as const) {
-    const value = valueArg[key];
-    if (typeof value !== 'string' || !identifierPattern.test(value)) {
-      errors.push(`${pathArg} ${key} must be a bounded identifier`);
-    }
+  if (typeof valueArg.serviceId !== 'string' || !identifierPattern.test(valueArg.serviceId)) {
+    errors.push(`${pathArg} serviceId must be a bounded identifier`);
+  }
+  if (!isClusterNodeId(valueArg.nodeId)) {
+    errors.push(`${pathArg} nodeId must be a node id`);
   }
   if (!isClusterIngressHostName(valueArg.hostName)) {
     errors.push(`${pathArg} hostName must be a lowercase dotted hostname`);
@@ -409,8 +410,8 @@ export const validateClusterIngressRegistration = (
   if (typeof valueArg.version !== 'string' || !identifierPattern.test(valueArg.version)) {
     errors.push(`${pathArg} version must be a bounded identifier`);
   }
-  if (typeof valueArg.nodeId !== 'string' || !identifierPattern.test(valueArg.nodeId)) {
-    errors.push(`${pathArg} nodeId must be a bounded identifier`);
+  if (!isClusterNodeId(valueArg.nodeId)) {
+    errors.push(`${pathArg} nodeId must be a node id`);
   }
   if (valueArg.capabilities !== undefined
     && (!Array.isArray(valueArg.capabilities)

package/ts/data/clusternode.ts

@@ -11,6 +11,13 @@ import {
   readDataElements,
   readDataProperties,
 } from '../private/dataproperties.js';
+import { isClusterNodeId } from '../private/nodeidentifier.js';
+
+/**
+ * The vocabulary every node id in this package is read in, published here beside `IClusterNode`
+ * so a service that stores or forwards a node id judges it exactly as these contracts do.
+ */
+export { isClusterNodeId };
 
 export interface IClusterNodeMetrics {
   cpuUsagePercent: number;
@@ -625,8 +632,8 @@ const validateSparkReporterIdentity = (
   labelArg: string,
 ): string[] => {
   const errors: string[] = [];
-  if (!isRuntimeIdentifier(requestArg.nodeId)) {
-    errors.push(`${labelArg} nodeId must be canonical`);
+  if (!isClusterNodeId(requestArg.nodeId)) {
+    errors.push(`${labelArg} nodeId must be a node id`);
   }
   if (typeof requestArg.nodeToken !== 'string'
     || requestArg.nodeToken.length < 1
@@ -922,6 +929,11 @@ const createSparkFieldErrors = (
         errors.push(`${labelArg} ${keyArg} must be canonical`);
       }
     },
+    nodeIdentifier: (keyArg: string): void => {
+      if (!isClusterNodeId(recordArg[keyArg])) {
+        errors.push(`${labelArg} ${keyArg} must be a node id`);
+      }
+    },
     boolean: (keyArg: string): void => {
       if (typeof recordArg[keyArg] !== 'boolean') {
         errors.push(`${labelArg} ${keyArg} must be a boolean`);
@@ -1054,7 +1066,7 @@ const validateSparkNodeRuntimeInfo = (valueArg: unknown, labelArg: string): stri
   if (runtimeInfo.runtime !== 'spark') {
     field.errors.push(`${labelArg} runtime must be spark`);
   }
-  field.identifier('nodeId');
+  field.nodeIdentifier('nodeId');
   field.text('platform');
   field.text('arch');
   field.text('sparkVersion');
@@ -1118,6 +1130,17 @@ export const validateSparkSwarmNodeHeartbeatRequest = async (
       envelope.record.runtimeInfo,
       `${label} runtimeInfo`,
     ));
+    // One body, one node. The bearer authenticates the sender named by `nodeId`, so a runtime info
+    // that names another node would report that node's Docker, Cloudly connection and services
+    // under a credential it never held. Only the pair is checked here: an unreadable member of
+    // either has already named itself above.
+    const runtimeInfo = envelope.record.runtimeInfo;
+    if (isClusterNodeId(envelope.record.nodeId)
+      && isRuntimeRecord(runtimeInfo)
+      && isClusterNodeId(runtimeInfo.nodeId)
+      && runtimeInfo.nodeId !== envelope.record.nodeId) {
+      envelope.errors.push(`${label} runtimeInfo nodeId must name the request nodeId`);
+    }
     return envelope.errors;
   } catch {
     return [`${label} must be safely inspectable`];
@@ -1290,7 +1313,6 @@ export const validateClusterRuntimeTargetSet = async (
           'nodeName',
           'platform',
         ])
-        || !isRuntimeIdentifier(targetArg.cloudlyNodeId)
         || !isRuntimeIdentifier(targetArg.swarmClusterId)
         || !isRuntimeIdentifier(targetArg.swarmNodeId)
         || !isRuntimeIdentifier(targetArg.nodeName)
@@ -1299,6 +1321,12 @@ export const validateClusterRuntimeTargetSet = async (
         errors.push(`cluster runtime target set targets[${index}] must be canonical`);
         continue;
       }
+      // The node this target names is judged in the node vocabulary, so it states that and not
+      // the canonical rule the Swarm identities beside it are held to.
+      if (!isClusterNodeId(targetArg.cloudlyNodeId)) {
+        errors.push(`cluster runtime target set targets[${index}].cloudlyNodeId must be a node id`);
+        continue;
+      }
       const sortKey = `${targetArg.cloudlyNodeId}\0${targetArg.swarmClusterId}\0${
         targetArg.swarmNodeId
       }\0${targetArg.nodeName}\0${targetArg.platform}`;