@serve.zone/interfaces 32.4.0 → 32.6.0

package/ts/data/clustervpn.ts

@@ -1,6 +1,7 @@
-import { captureNetwork, failNetwork, networkCanonical, networkCounter, networkEqual, networkId, networkIpv4, networkList,
-  networkNoiseKey, networkPrivatePrefix, networkRecord, networkSafe, networkSorted,
-  requireNetwork } from '../private/networkcontract.js';
+import { runtimeNetworkVpnControlPrefix } from './networkaddressplan.js';
+import { captureNetwork, failNetwork, networkCanonical, networkContains, networkCounter, networkEqual, networkId, networkIpv4,
+  networkList, networkNodeId, networkNoiseKey, networkOverlaps, 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
@@ -40,9 +41,16 @@ export interface IClusterVpnNetworkGrant {
  * 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.
+ *
+ * `controlPrefix` is the subnet the hub's control plane serves: the address plan's
+ * `vpn.controlPrefix`, which the plan contract never lets change, stated here because a hub fixes
+ * its control subnet when it binds and no other carrier hands a relay the plan. Without it a relay
+ * could only infer a subnet from the members it was sent, which is how a hub comes to disagree with
+ * the plan it serves.
  */
 export interface IClusterVpnNetwork {
   authorityId: string;
+  controlPrefix: string;
   revision: number;
   nodes: IClusterVpnNetworkNode[];
   grants: IClusterVpnNetworkGrant[];
@@ -148,7 +156,7 @@ const prefixOf = (value: unknown): IClusterVpnNetworkPrefix => {
 
 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),
+  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) };
@@ -168,20 +176,27 @@ const grantKey = (grant: IClusterVpnNetworkGrant): string => `${grant.sourceDoma
  * 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.
+ *
+ * Every control address lies inside `controlPrefix` and no workload prefix meets it — the two rules
+ * a hub enforces against the subnet it bound. Checking them while the network is compiled turns a
+ * push the hub could only refuse into a network Cloudly never states.
  */
 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 item = networkRecord(captured, ['authorityId', 'controlPrefix', 'revision', 'nodes', 'grants']);
+  const controlPrefix = runtimeNetworkVpnControlPrefix(item.controlPrefix);
   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));
+    requireNetwork(!keys.has(node.publicKey) && !addresses.has(node.controlAddress)
+      && networkContains(controlPrefix, `${node.controlAddress}/32`));
     keys.add(node.publicKey); addresses.add(node.controlAddress);
     for (const prefix of node.workloadPrefixes) {
-      requireNetwork(!cidrs.has(prefix.cidr) && !domainOwners.has(prefix.policyDomain));
+      requireNetwork(!cidrs.has(prefix.cidr) && !domainOwners.has(prefix.policyDomain)
+        && !networkOverlaps(controlPrefix, prefix.cidr));
       cidrs.add(prefix.cidr); domainOwners.set(prefix.policyDomain, node.nodeId);
     }
   }
@@ -189,7 +204,7 @@ export const snapshotClusterVpnNetwork = (value: unknown): IClusterVpnNetwork =>
     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 };
+  return { authorityId: networkId(item.authorityId), controlPrefix, revision: networkCounter(item.revision), nodes, grants };
 });
 
 export type TClusterVpnNetworkAdmission =
@@ -208,7 +223,11 @@ export const admitClusterVpnNetwork = (heldValue: unknown | null, nextValue: unk
     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' };
+    // A hub binds one control subnet for its lifetime, so a network that moves the prefix under the
+    // same authority is as foreign to this hub as one that names another authority.
+    if (held.authorityId !== next.authorityId || held.controlPrefix !== next.controlPrefix) {
+      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' };
   });

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

@@ -39,14 +39,13 @@ export interface IRuntimeNetworkAddressPlan {
  * 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`.
+ * that may select it, and `address` is an underlay address inside the plan's `vpn.hubPrefix`.
+ * `quicPort` is the port it bound for the one transport a managed hub serves.
  */
 export interface IRuntimeNetworkVpnHub {
   clusterId: string;
   address: string;
-  quicPort: number | null;
-  websocketPort: number | null;
+  quicPort: number;
 }
 
 /** What an administrator writes; Cloudly supplies the id and the revision. */
@@ -80,50 +79,60 @@ export const runtimeNetworkAddressPlanContract = Object.freeze({
    */
   maximumControlPrefixLength: 30,
   /**
-   * Every transport a hub may offer, in the order a node prefers them.
+   * Every transport a managed hub serves, 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.
+   * contributes one endpoint of its address per row, so a transport added here is added once for
+   * the id derivation, the composition and the credential binder alike.
+   *
+   * QUIC is the one row: a managed hub terminates TLS on its QUIC listener alone, so no other
+   * transport of it can be dialled over a protected connection.
    */
   hubTransports: Object.freeze([
     Object.freeze({ transport: 'quic', endpointSuffix: 'quic', protocol: 'udp' }),
-    Object.freeze({ transport: 'websocket', endpointSuffix: 'ws', protocol: 'tcp' }),
   ]),
 } as const);
 
+/**
+ * The one reader for a managed VPN control prefix: a canonical private prefix no longer than
+ * `maximumControlPrefixLength`. The plan states it for the whole runtime network and a cluster's
+ * network repeats it for the hub that binds it, so both read it here and neither can admit a
+ * subnet the other would refuse.
+ */
+export const runtimeNetworkVpnControlPrefix = (value: unknown): string => networkSafe(() => {
+  const prefix = networkPrivatePrefix(value);
+  requireNetwork(Number(prefix.split('/')[1]) <= runtimeNetworkAddressPlanContract.maximumControlPrefixLength);
+  return prefix;
+});
+
 /** 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;
+/** The port a hub bound for one transport; one entry per row of the transport table. */
+const hubPort = (hub: IRuntimeNetworkVpnHub, transport: TRuntimeNetworkVpnTransport): number =>
+  ({ quic: hub.quicPort })[transport];
 
 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;
+  const item = networkRecord(value, ['clusterId', 'address', 'quicPort']);
+  return { clusterId: networkId(item.clusterId), address: networkIpv4(item.address),
+    quicPort: networkCounter(item.quicPort, 65535) };
 };
 
 /**
- * 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.
+ * The platform endpoints one hub contributes to a protected authority: one per transport a managed
+ * hub serves, 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 }))
+        protocol: row.protocol, port: hubPort(hub, row.transport) }))
       .sort(byEndpointId);
   });
 
@@ -154,9 +163,7 @@ const setsWithHubs = (plan: IRuntimeNetworkAddressPlan, hubs: IRuntimeNetworkVpn
 
 const vpnOf = (value: unknown): IRuntimeNetworkAddressPlan['vpn'] => {
   const item = networkRecord(value, ['controlPrefix', 'hubPrefix']);
-  const controlPrefix = networkPrivatePrefix(item.controlPrefix);
-  requireNetwork(Number(controlPrefix.split('/')[1]) <= runtimeNetworkAddressPlanContract.maximumControlPrefixLength);
-  return { controlPrefix, hubPrefix: networkPrefix(item.hubPrefix) };
+  return { controlPrefix: runtimeNetworkVpnControlPrefix(item.controlPrefix), hubPrefix: networkPrefix(item.hubPrefix) };
 };
 
 /**

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

package/ts/data/networkcredential.ts

@@ -19,13 +19,6 @@ export interface IGetRuntimeManagedVpnCredentialResponse extends IGetRuntimeMana
   transport: TRuntimeNetworkVpnTransport;
   /** The cluster hub endpoint this node dials, named by the id its signed projection selected. */
   hub: { id: string; address: string; port: number };
-  /**
-   * The TLS name the hub's WebSocket transport is dialled under, present exactly when `transport`
-   * is `websocket` and absent otherwise: QUIC is dialled on the address alone. It is the hub
-   * relay's own origin hostname, which the node cross-checks against the relay origin it stores,
-   * so a name the node does not already trust ends the handshake before any native effect.
-   */
-  serverName?: string;
   authorityId: string;
   serverPublicKey: string;
   clientPublicKey: string;
@@ -42,21 +35,6 @@ export const snapshotGetRuntimeManagedVpnCredentialRequest = (value: unknown): I
   return { session: snapshotRuntimeSessionBinding(item.session), projection: networkReference(item.projection) };
 });
 
-/**
- * The TLS name a WebSocket hub is dialled under: a lower-case domain name of at least two labels,
- * which is what a relay origin's hostname is and what a certificate can be issued for. An address
- * literal is not one, so a node can never be sent to a name nothing vouches for.
- */
-const serverName = (value: unknown): string => {
-  requireNetwork(typeof value === 'string' && value.length <= 253);
-  const labels = (value as string).split('.');
-  // The last label starts with a letter, which is what makes this a name and not an address
-  // literal: a hub reached by address is reached over QUIC, which needs no name at all.
-  requireNetwork(labels.length >= 2 && labels.every(label => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label))
-    && /^[a-z]/.test(labels[labels.length - 1]));
-  return value as string;
-};
-
 const transportOf = (value: unknown): TRuntimeNetworkVpnTransport => {
   const row = runtimeNetworkAddressPlanContract.hubTransports.find(candidate => candidate.transport === value);
   requireNetwork(row); return row.transport;
@@ -64,14 +42,11 @@ const transportOf = (value: unknown): TRuntimeNetworkVpnTransport => {
 
 export const snapshotGetRuntimeManagedVpnCredentialResponse = (value: unknown): IGetRuntimeManagedVpnCredentialResponse => networkSafe(() => {
   const item = networkRecord(captureNetwork(value), ['session', 'projection', 'transport', 'hub', 'authorityId',
-    'serverPublicKey', 'clientPublicKey', 'clientPrivateKey', 'expiresAt'], ['serverName']);
-  const hub = networkRecord(item.hub, ['id', 'address', 'port']), transport = transportOf(item.transport);
-  // A name belongs to the one transport that is dialled by name; stating it for QUIC would name a
-  // trust the node never checks, and omitting it for WebSocket leaves the TLS identity unstated.
-  requireNetwork(Object.hasOwn(item, 'serverName') === (transport === 'websocket'));
-  return { session: snapshotRuntimeSessionBinding(item.session), projection: networkReference(item.projection), transport,
+    'serverPublicKey', 'clientPublicKey', 'clientPrivateKey', 'expiresAt']);
+  const hub = networkRecord(item.hub, ['id', 'address', 'port']);
+  return { session: snapshotRuntimeSessionBinding(item.session), projection: networkReference(item.projection),
+    transport: transportOf(item.transport),
     hub: { id: networkId(hub.id), address: networkIpv4(hub.address), port: networkCounter(hub.port, 65535) },
-    ...(transport === 'websocket' ? { serverName: serverName(item.serverName) } : {}),
     authorityId: networkId(item.authorityId), serverPublicKey: networkNoiseKey(item.serverPublicKey),
     clientPublicKey: networkNoiseKey(item.clientPublicKey), clientPrivateKey: networkNoiseKey(item.clientPrivateKey),
     expiresAt: networkCounter(item.expiresAt) };

package/ts/data/networklease.ts

@@ -3,7 +3,7 @@ import type { IRuntimeAuthorityReference } from './runtimeassignment.js';
 import type { IRuntimeNetworkDnsWindow, IRuntimeNetworkNodeScope } from './networkprojection.js';
 import { snapshotRuntimeNetworkNodeScope, snapshotRuntimeNetworkProjection, validateRuntimeNetworkProjection } from './networkprojection.js';
 import { captureNetwork, failNetwork, networkCounter, networkDigest, networkDnsWindow, networkEffectiveDnsWindow, networkEqual,
-  networkHash, networkId, networkList, networkMaximumDnsLeaseMs, networkRecord, networkReference, networkReferenceOf,
+  networkHash, networkId, networkList, networkMaximumDnsLeaseMs, networkNodeId, networkRecord, networkReference, networkReferenceOf,
   networkRenewsProjection, networkSafe, networkSameScope, networkScope, networkSignature, requireNetwork } from '../private/networkcontract.js';
 
 /**
@@ -223,7 +223,7 @@ const heldHorizonMs = (renewals: ISignedRuntimeNetworkDnsLeaseRenewal[]): number
 export const snapshotHoldRuntimeNetworkDnsLeaseRenewalsRequest = (value: unknown): IHoldRuntimeNetworkDnsLeaseRenewalsRequest => networkSafe(() => {
   const item = networkRecord(captureNetwork(value), ['nodeId', 'projection', 'renewals']);
   const contract = runtimeNetworkDnsLeaseRenewalContract;
-  const request: IHoldRuntimeNetworkDnsLeaseRenewalsRequest = { nodeId: networkId(item.nodeId), projection: networkReference(item.projection),
+  const request: IHoldRuntimeNetworkDnsLeaseRenewalsRequest = { nodeId: networkNodeId(item.nodeId), projection: networkReference(item.projection),
     renewals: networkList(item.renewals, contract.maximumEscrowedRenewals, snapshotSignedRuntimeNetworkDnsLeaseRenewal) };
   request.renewals.forEach((signed, index) => requireNetwork(signed.renewal.nodeId === request.nodeId
     && networkEqual(signed.renewal.projection, request.projection)

package/ts/data/networknode.ts

@@ -1,5 +1,5 @@
 import type { IRuntimeNetworkProtectedAuthority } from './networkauthority.js';
-import { captureNetwork, networkCounter, networkId, networkRecord, networkSafe } from '../private/networkcontract.js';
+import { captureNetwork, networkCounter, networkNodeId, networkRecord, networkSafe } from '../private/networkcontract.js';
 
 type TEgressOwner = IRuntimeNetworkProtectedAuthority['egressAuthorities'][number];
 
@@ -33,5 +33,5 @@ export interface IRuntimeRouterIncarnation {
 
 export const snapshotRuntimeRouterIncarnation = (value: unknown): IRuntimeRouterIncarnation => networkSafe(() => {
   const item = networkRecord(captureNetwork(value), ['id', 'incarnation']);
-  return { id: networkId(item.id), incarnation: networkCounter(item.incarnation) };
+  return { id: networkNodeId(item.id), incarnation: networkCounter(item.incarnation) };
 });

package/ts/data/networkprojection.ts

@@ -1,6 +1,6 @@
 import type { TSha256Digest } from './immutableimage.js';
 import type { IRuntimeAssignmentReference, IRuntimeAuthorityReference, IRuntimeController } from './runtimeassignment.js';
-import { snapshotRuntimeAssignment, validateRuntimeAssignment } from './runtimeassignment.js';
+import { isRuntimeReplicaId, snapshotRuntimeAssignment, validateRuntimeAssignment } from './runtimeassignment.js';
 import type { IRuntimeNetworkHandoffLease, IRuntimeNetworkProtectedAuthority } from './networkauthority.js';
 import { bindRuntimeNetworkHandoffLease, computeRuntimeNetworkProtectedAuthorityDigest,
   snapshotRuntimeNetworkHandoffLease, snapshotRuntimeNetworkProtectedAuthority } from './networkauthority.js';
@@ -191,6 +191,10 @@ export const runtimeNetworkProjectionContract = Object.freeze({
   allocationReuse: 'requires-controller-quarantine-and-all-affected-authority-fences',
 } as const);
 
+/** The assignment contract owns the replica rule; a lease names the same slot by the same name. */
+const replicaId = (value: unknown): string => {
+  requireNetwork(isRuntimeReplicaId(value)); return value as string;
+};
 const ownerKey = (value: { organizationId: string; serviceId: string }): string => networkCanonical([value.organizationId, value.serviceId]);
 const attemptKey = (value: IRuntimeNetworkWorkloadLease): string =>
   networkCanonical([value.organizationId, value.serviceId, value.replicaId, value.attemptId]);
@@ -220,7 +224,7 @@ export const snapshotRuntimeNetworkWorkloadLease = (value: unknown): IRuntimeNet
   requireNetwork(item.dnsServer === gateway);
   return { id: networkId(item.id), generation: networkCounter(item.generation), ...networkScope(item),
     organizationId: networkId(item.organizationId), assignmentId: networkId(item.assignmentId), serviceId: networkId(item.serviceId),
-    replicaId: networkId(item.replicaId), attemptId: networkId(item.attemptId), protectedAuthority: networkReference(item.protectedAuthority),
+    replicaId: replicaId(item.replicaId), attemptId: networkId(item.attemptId), protectedAuthority: networkReference(item.protectedAuthority),
     routerIncarnationId: networkId(item.routerIncarnationId), ipv4: { poolId: networkId(ip.poolId), linkSubnet: ip.linkSubnet,
       address, sourcePrefix: ip.sourcePrefix, gateway }, dnsServer: gateway, digest: networkDigest(item.digest) };
 });

package/ts/data/nodeenrollment.ts

@@ -8,6 +8,7 @@ import {
 import {
   readDataElements, readDataProperty, readExactDataRecord,
 } from '../private/dataproperties.js';
+import { isClusterNodeId } from '../private/nodeidentifier.js';
 
 export interface INodeEnrollmentCredentialProposal {
   purpose: TNodeCredentialPurpose;
@@ -139,9 +140,10 @@ const pair = (valueArg: unknown): [unknown, unknown] => {
   requireValue(elements !== null && elements.length === 2);
   return [elements[0], elements[1]];
 };
+/** Enrollment names the node, its installations and its mutations in the node's own vocabulary. */
 const id = (valueArg: unknown): string => {
-  requireValue(typeof valueArg === 'string' && /^[A-Za-z0-9_-]{1,128}$/.test(valueArg));
-  return valueArg;
+  requireValue(isClusterNodeId(valueArg));
+  return valueArg as string;
 };
 const hash = (valueArg: unknown): string => {
   requireValue(typeof valueArg === 'string' && /^[a-f0-9]{64}$/.test(valueArg));

package/ts/data/noderetirement.ts

@@ -1,4 +1,4 @@
-import { captureNetwork, networkCounter, networkId, networkRecord, requireNetwork } from '../private/networkcontract.js';
+import { captureNetwork, networkCounter, networkId, networkNodeId, networkRecord, requireNetwork } from '../private/networkcontract.js';
 import { isOneOf, producerSafe } from '../private/producercontract.js';
 
 const nodeRuntimeRetirementStates = ['retiring', 'retired'] as const;
@@ -58,6 +58,6 @@ export type TNodeRuntimeRetirementRefusal = typeof nodeRuntimeRetirementRefusals
 export const snapshotNodeRuntimeRetirement = (value: unknown): INodeRuntimeRetirement => producerSafe(() => {
   const item = networkRecord(captureNetwork(value), ['id', 'clusterId', 'state', 'actorId', 'since']);
   requireNetwork(isOneOf(nodeRuntimeRetirementStates, item.state));
-  return { id: networkId(item.id), clusterId: networkId(item.clusterId), state: item.state,
+  return { id: networkNodeId(item.id), clusterId: networkId(item.clusterId), state: item.state,
     actorId: networkId(item.actorId), since: networkCounter(item.since) };
 });

package/ts/data/runtimeassignment.ts

@@ -3,6 +3,7 @@ import { buildDigestPinnedImageReference, isSha256Digest } from './immutableimag
 import {
   canonicalizeStrictJson, compareWireTokens, createCanonicalJsonSha256Hex,
 } from '../private/canonicaljson.js';
+import { isClusterNodeId } from '../private/nodeidentifier.js';
 import { isCanonicalTokenList } from '../private/tokenlist.js';
 
 export interface IRuntimeController {
@@ -184,6 +185,27 @@ export const runtimeAssignmentContract = Object.freeze({
 const fail: (messageArg: string) => never = (messageArg) => { throw new Error(messageArg); };
 const isIdentifier = (valueArg: unknown): valueArg is string =>
   typeof valueArg === 'string' && /^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/.test(valueArg);
+/** The index of a replica slot: counted from zero by its producer, never zero-padded. */
+const isReplicaIndex = (valueArg: string): boolean => /^(?:0|[1-9][0-9]{0,8})$/.test(valueArg);
+
+/**
+ * True when a value is exactly a replica id.
+ *
+ * A producer names a replica slot after the node that runs it — `<node id>.<index>`, counted from
+ * zero — so a replica id that carries an index is read by decomposition: the part before the last
+ * dot in the node vocabulary, the index on its own. Reading the composed form as one canonical
+ * identifier would refuse every replica of a node whose id begins with `-` or `_`, a node these
+ * contracts themselves enrol and register. A name that carries no such index — a zero-padded index
+ * among them — is an opaque slot name and is read whole in the canonical identifier vocabulary, as
+ * it always was.
+ */
+export const isRuntimeReplicaId = (valueArg: unknown): valueArg is string => {
+  if (typeof valueArg !== 'string') return false;
+  const separator = valueArg.lastIndexOf('.');
+  return separator > 0 && isReplicaIndex(valueArg.slice(separator + 1))
+    ? isClusterNodeId(valueArg.slice(0, separator))
+    : isIdentifier(valueArg);
+};
 const isPositiveInteger = (valueArg: unknown): valueArg is number =>
   typeof valueArg === 'number' && Number.isSafeInteger(valueArg) && valueArg > 0;
 const isDigest = (valueArg: unknown): valueArg is TSha256Digest =>
@@ -244,10 +266,11 @@ const assertAssignment = (valueArg: unknown): IRuntimeAssignment => {
     || !['run', 'stop-preserve', 'remove-runtime-preserve-storage'].includes(
       valueArg.disposition as string,
     )) fail('runtime assignment must use its exact schema');
-  for (const key of ['organizationId', 'nodeId', 'runtimeNamespace', 'assignmentId',
-    'serviceId', 'replicaId', 'attemptId']) {
+  for (const key of ['organizationId', 'runtimeNamespace', 'assignmentId', 'serviceId', 'attemptId']) {
     if (!isIdentifier(valueArg[key])) fail(`runtime assignment ${key} must be a canonical identifier`);
   }
+  if (!isClusterNodeId(valueArg.nodeId)) fail('runtime assignment nodeId must be a node id');
+  if (!isRuntimeReplicaId(valueArg.replicaId)) fail('runtime assignment replicaId must be a replica id');
   for (const key of ['workerGroupId', 'siteId']) {
     if (valueArg[key] !== null && !isIdentifier(valueArg[key])) fail('invalid runtime topology ID');
   }
@@ -357,7 +380,7 @@ export const evaluateRuntimeAssignment = async (
     acceptedArg = acceptedArg === null ? null : snapshotRuntimeAssignment(acceptedArg);
     if (!isExactRecord(trustedScopeArg, ['controller', 'organizationId', 'nodeId', 'runtimeNamespace'])
       || !isController(trustedScopeArg.controller)
-      || !isIdentifier(trustedScopeArg.organizationId) || !isIdentifier(trustedScopeArg.nodeId)
+      || !isIdentifier(trustedScopeArg.organizationId) || !isClusterNodeId(trustedScopeArg.nodeId)
       || !isIdentifier(trustedScopeArg.runtimeNamespace)) return { status: 'reject', reason: 'invalid' };
     trustedScopeArg = JSON.parse(canonical(trustedScopeArg)) as IRuntimeAssignmentScope;
   } catch {

package/ts/data/runtimesession.ts

@@ -12,6 +12,7 @@ import { negotiateProtocol, readProtocolOffer, type IProtocolOffer } from '../pr
 import type { IRuntimeConfig } from './runtimeconfig.js';
 import { bindRuntimeConfigToAssignment, snapshotRuntimeConfig } from './runtimeconfig.js';
 import { canonicalizeStrictJson } from '../private/canonicaljson.js';
+import { isClusterNodeId } from '../private/nodeidentifier.js';
 
 /**
  * Server-issued public binding for the current authenticated physical connection.
@@ -178,8 +179,8 @@ const identifier = (valueArg: unknown): string => {
   return valueArg;
 };
 const nodeId = (valueArg: unknown): string => {
-  requireValue(typeof valueArg === 'string' && /^[A-Za-z0-9_-]{1,128}$/.test(valueArg));
-  return valueArg;
+  requireValue(isClusterNodeId(valueArg));
+  return valueArg as string;
 };
 /** One node process, in the same canonical form as the native boot UUID. */
 const nodeInstanceNonce = (valueArg: unknown): string => {

package/ts/data/serviceruntime.ts

@@ -3,7 +3,7 @@ import type {
 } from './runtimeassignment.js';
 import type { IRuntimeConfigLogPolicy, TRuntimeConfigReadiness } from './runtimeconfig.js';
 import { runtimeNetworkAuthorityContract } from './networkauthority.js';
-import { captureNetwork, networkCanonical, networkCounter, networkId, networkList, networkRecord, networkSorted,
+import { captureNetwork, networkCanonical, networkCounter, networkId, networkList, networkNodeId, networkRecord, networkSorted,
   requireNetwork } from '../private/networkcontract.js';
 import { failProducer, isOneOf, producerSafe, variantOf } from '../private/producercontract.js';
 import { assertRuntimeReadiness, isBoundedInteger, isRuntimeCpuMillis, isRuntimeIdentityNumber, isRuntimeLogPolicy,
@@ -138,8 +138,9 @@ export interface IServiceRuntimeAssignmentView {
   delivery: TServiceRuntimeAssignmentDelivery;
 }
 
-const sortedIds = (value: unknown, maximum: number): string[] =>
-  networkSorted(networkList(value, maximum, networkId), id => id);
+/** Sorted, duplicate-free and read by the vocabulary the ids belong to: a node's, or the canonical one. */
+const sortedIds = (value: unknown, maximum: number, read: (item: unknown) => string): string[] =>
+  networkSorted(networkList(value, maximum, read), id => id);
 
 const placementOf = (value: unknown): TServiceRuntimePlacement => {
   const kind = variantOf(value, 'kind');
@@ -148,7 +149,7 @@ const placementOf = (value: unknown): TServiceRuntimePlacement => {
     return { kind };
   }
   requireNetwork(kind === 'nodes');
-  const nodeIds = sortedIds(networkRecord(value, ['kind', 'nodeIds']).nodeIds, serviceRuntimeContract.maximumPinnedNodes);
+  const nodeIds = sortedIds(networkRecord(value, ['kind', 'nodeIds']).nodeIds, serviceRuntimeContract.maximumPinnedNodes, networkNodeId);
   requireNetwork(nodeIds.length > 0);
   return { kind, nodeIds };
 };
@@ -182,7 +183,7 @@ const networkOf = (value: unknown): TServiceRuntimeNetwork => {
   const item = networkRecord(value, ['mode', 'publicEgress', 'platformEndpointIds']);
   requireNetwork(typeof item.publicEgress === 'boolean');
   return { mode, publicEgress: item.publicEgress,
-    platformEndpointIds: sortedIds(item.platformEndpointIds, serviceRuntimeContract.maximumPlatformEndpoints) };
+    platformEndpointIds: sortedIds(item.platformEndpointIds, serviceRuntimeContract.maximumPlatformEndpoints, networkId) };
 };
 
 /**

package/ts/data/sparknodereport.ts

@@ -1,5 +1,6 @@
 import { isReleaseVersion } from '../private/releaseversion.js';
 import { readExactDataRecord } from '../private/dataproperties.js';
+import { isClusterNodeId } from '../private/nodeidentifier.js';
 import { protocolRefusalHttpStatus, readProtocolOffer, type IProtocolOffer } from '../protocol.js';
 
 /** Host observations only. Container and workload readiness belong to Pallet. */
@@ -80,6 +81,10 @@ const text = (valueArg: unknown, patternArg: RegExp, maxLengthArg: number): stri
     && valueArg.match(patternArg)?.[0] === valueArg);
   return valueArg;
 };
+// The shared vocabulary, not a copy of it: the id on this wire is the id the node enrolled under.
+const nodeId = (valueArg: unknown): string => (
+  isClusterNodeId(valueArg) ? valueArg : fail()
+);
 // The shared grammar, not a copy of it: a stored bundle version has to be one the release
 // comparison can order, and a second rule here would be a second answer to that question.
 const releaseVersion = (valueArg: unknown): string => (
@@ -131,7 +136,7 @@ export const snapshotSparkNodeReport = (valueArg: unknown): ISparkNodeReport =>
 export const snapshotSparkNodeHeartbeatRequest = (valueArg: unknown): ISparkNodeHeartbeatRequest => {
   const value = record(valueArg, ['nodeId', 'nodeToken', 'protocol', 'report']);
   return Object.freeze({
-    nodeId: text(value.nodeId, /^[A-Za-z0-9_-]+$/, 128),
+    nodeId: nodeId(value.nodeId),
     // Both freshly enrolled and explicitly adopted credentials use this bearer format.
     nodeToken: text(value.nodeToken, /^secureToken[a-f0-9]{64}$/, 75),
     protocol: readProtocolOffer(value),
@@ -144,7 +149,7 @@ export const snapshotSparkNodeHeartbeatReceipt = (valueArg: unknown): ISparkNode
     'sessionEpoch', 'acceptedAt', 'protocol']);
   requireValue(value.accepted === true);
   return Object.freeze({
-    accepted: true, nodeId: text(value.nodeId, /^[A-Za-z0-9_-]+$/, 128),
+    accepted: true, nodeId: nodeId(value.nodeId),
     credentialGeneration: integer(value.credentialGeneration, 1),
     sessionEpoch: integer(value.sessionEpoch, 0), acceptedAt: integer(value.acceptedAt, 1),
     protocol: readProtocolOffer(value),

package/ts/private/networkcontract.ts

@@ -3,6 +3,7 @@ import type { IRuntimeAuthorityReference, IRuntimeController } from '../data/run
 import type { IRuntimeNetworkDnsLeaseRenewal } from '../data/networklease.js';
 import type { IRuntimeNetworkDnsWindow, IRuntimeNetworkNodeScope, IRuntimeNetworkProjection } from '../data/networkprojection.js';
 import { canonicalizeStrictJson, createCanonicalJsonSha256Hex } from './canonicaljson.js';
+import { isClusterNodeId } from './nodeidentifier.js';
 
 export const failNetwork = (): never => { throw new Error('Runtime network projection contract rejected.'); };
 export function requireNetwork(value: unknown): asserts value { if (!value) failNetwork(); }
@@ -79,6 +80,10 @@ export const networkSorted = <T>(values: T[], key: (item: T) => string): T[] =>
 export const networkId = (value: unknown): string => {
   requireNetwork(typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/.test(value)); return value;
 };
+/** A node id is read in the node vocabulary here as everywhere else, never in the canonical one. */
+export const networkNodeId = (value: unknown): string => {
+  requireNetwork(isClusterNodeId(value)); return value as string;
+};
 export const networkCounter = (value: unknown, maximum = Number.MAX_SAFE_INTEGER - 1): number => {
   requireNetwork(typeof value === 'number' && Number.isSafeInteger(value) && value > 0 && value <= maximum); return value;
 };
@@ -106,7 +111,7 @@ export const networkController = (value: unknown): IRuntimeController => {
   return { kind: item.kind, id: networkId(item.id), epoch: networkId(item.epoch) };
 };
 export const networkScope = (item: Record<string, unknown>): IRuntimeNetworkNodeScope => ({
-  controller: networkController(item.controller), nodeId: networkId(item.nodeId), runtimeNamespace: networkId(item.runtimeNamespace),
+  controller: networkController(item.controller), nodeId: networkNodeId(item.nodeId), runtimeNamespace: networkId(item.runtimeNamespace),
 });
 export const networkSameScope = (left: IRuntimeNetworkNodeScope, right: IRuntimeNetworkNodeScope): boolean =>
   networkEqual(left.controller, right.controller) && left.nodeId === right.nodeId && left.runtimeNamespace === right.runtimeNamespace;