@serve.zone/interfaces 32.3.0 → 32.5.0

package/ts/data/networkcredential.ts

@@ -1,9 +1,11 @@
 import type { IRuntimeAuthorityReference } from './runtimeassignment.js';
+import { runtimeNetworkAddressPlanContract, type TRuntimeNetworkVpnTransport } from './networkaddressplan.js';
 import { snapshotRuntimeSessionBinding, type IRuntimeSessionBinding } from './runtimesession.js';
 import { validateRuntimeNetworkProjection, type IRuntimeNetworkProjection } from './networkprojection.js';
 import { snapshotRuntimeNetworkDnsLeaseRenewal, validateRuntimeNetworkDnsLeaseRenewal } from './networklease.js';
 import { captureNetwork, failNetwork, networkCounter, networkEffectiveDnsWindow, networkEqual, networkId, networkIpv4,
-  networkRecord, networkReference, networkReferenceOf, networkSafe, networkSameScope, requireNetwork } from '../private/networkcontract.js';
+  networkNoiseKey, networkRecord, networkReference, networkReferenceOf, networkSafe, networkSameScope,
+  requireNetwork } from '../private/networkcontract.js';
 
 export interface IGetRuntimeManagedVpnCredentialRequest {
   session: IRuntimeSessionBinding;
@@ -14,8 +16,16 @@ export interface IGetRuntimeManagedVpnCredentialRequest {
  * persist, hash, log, or include it in a signed network projection. The native
  * Noise owner validates and uses the keys; these shapes confer no TUN readiness. */
 export interface IGetRuntimeManagedVpnCredentialResponse extends IGetRuntimeManagedVpnCredentialRequest {
-  transport: 'quic';
-  relay: { id: string; address: string; port: number };
+  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;
@@ -27,28 +37,44 @@ export interface IGetRuntimeManagedVpnCredentialResponse extends IGetRuntimeMana
   expiresAt: number;
 }
 
-/** Canonical 32-byte key encoding only. Cryptographic key agreement and pair
- * validation belong to the native Noise implementation, not this JSON parser. */
-const key = (value: unknown): string => {
-  requireNetwork(typeof value === 'string' && /^[A-Za-z0-9+/]{43}=$/.test(value));
-  const decoded = atob(value);
-  requireNetwork(decoded.length === 32 && btoa(decoded) === value && [...decoded].some(byte => byte.charCodeAt(0) !== 0));
-  return value;
-};
-
 export const snapshotGetRuntimeManagedVpnCredentialRequest = (value: unknown): IGetRuntimeManagedVpnCredentialRequest => networkSafe(() => {
   const item = networkRecord(captureNetwork(value), ['session', 'projection']);
   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;
+};
+
 export const snapshotGetRuntimeManagedVpnCredentialResponse = (value: unknown): IGetRuntimeManagedVpnCredentialResponse => networkSafe(() => {
-  const item = networkRecord(captureNetwork(value), ['session', 'projection', 'transport', 'relay', 'authorityId',
-    'serverPublicKey', 'clientPublicKey', 'clientPrivateKey', 'expiresAt']);
-  const relay = networkRecord(item.relay, ['id', 'address', 'port']); requireNetwork(item.transport === 'quic');
-  return { session: snapshotRuntimeSessionBinding(item.session), projection: networkReference(item.projection), transport: 'quic',
-    relay: { id: networkId(relay.id), address: networkIpv4(relay.address), port: networkCounter(relay.port, 65535) },
-    authorityId: networkId(item.authorityId), serverPublicKey: key(item.serverPublicKey), clientPublicKey: key(item.clientPublicKey),
-    clientPrivateKey: key(item.clientPrivateKey), expiresAt: networkCounter(item.expiresAt) };
+  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,
+    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) };
 });
 
 const bindRequest = (request: IGetRuntimeManagedVpnCredentialRequest,
@@ -70,8 +96,8 @@ export const bindGetRuntimeManagedVpnCredentialRequest = async (value: unknown,
   } catch { return failNetwork(); }
 };
 
-/** Bind the secret response to the original request and exact selected router
- * UDP endpoint, inside the projection's effective DNS window. renewalValue is the
+/** Bind the secret response to the original request and the exact selected router
+ * endpoint of the credential's transport, inside the projection's effective DNS window. renewalValue is the
  * bare lease renewal the caller already verified and admitted for this exact
  * projection, or null; this helper verifies no signature. Time is caller-qualified;
  * this helper does not sample a clock, authenticate a transport, admit policy or
@@ -89,9 +115,11 @@ export const bindGetRuntimeManagedVpnCredentialResponse = async (value: unknown,
     const window = networkEffectiveDnsWindow(projection, renewal);
     bindRequest(request, projection, trusted);
     requireNetwork(networkEqual(response.session, request.session) && networkEqual(response.projection, request.projection));
-    requireNetwork(projection.router?.platformEndpointIds.includes(response.relay.id));
-    const endpoint = projection.protectedAuthority.platformEndpoints.find(item => item.id === response.relay.id);
-    requireNetwork(endpoint && endpoint.protocol === 'udp' && endpoint.address === response.relay.address && endpoint.port === response.relay.port);
+    requireNetwork(projection.router?.platformEndpointIds.includes(response.hub.id));
+    const endpoint = projection.protectedAuthority.platformEndpoints.find(item => item.id === response.hub.id);
+    const expected = runtimeNetworkAddressPlanContract.hubTransports.find(row => row.transport === response.transport);
+    requireNetwork(endpoint && expected && endpoint.protocol === expected.protocol
+      && endpoint.address === response.hub.address && endpoint.port === response.hub.port);
     requireNetwork(window.notBefore <= now && now < response.expiresAt && response.expiresAt <= window.expiresAt);
     return response;
   } catch { return failNetwork(); }

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 {
@@ -55,7 +56,20 @@ export interface IRuntimeAssignment extends IRuntimeAssignmentScope {
   /** No automatic relocation or expiry-based claim of a stopped writer. */
   offlinePolicy: 'continue-node-bound';
   workload: {
+    /**
+     * The registry that published this image, which is the publication identity the image release
+     * is bound to. It is never rewritten: only `pullEndpoint` decides where the bytes are fetched.
+     */
     registryHost: string;
+    /**
+     * Where this node fetches the image instead of `registryHost`, as `host[:port]`.
+     *
+     * A cluster whose relay forwards the registry states the relay's own origin here, so a node
+     * pulls inside its cluster and nothing cluster-side dials the control plane. Absent when the
+     * node pulls from the publishing registry itself. The reference stays digest-pinned either
+     * way, so the endpoint decides reachability and never content.
+     */
+    pullEndpoint?: string;
     repository: string;
     imageDigest: TSha256Digest;
     platform: TImmutableContainerPlatform;
@@ -99,7 +113,7 @@ const workloadAuthorityDemands: Readonly<Record<
 export const requiredWorkloadAuthorities = (
   workloadArg: IRuntimeAssignment['workload'],
 ): TRuntimeWorkloadAuthority[] => {
-  if (!isExactRecord(workloadArg, workloadKeys) || !Array.isArray(workloadArg.storage)) {
+  if (!isExactRecord(workloadArg, workloadKeys, optionalWorkloadKeys) || !Array.isArray(workloadArg.storage)) {
     fail(workloadSchemaMessage);
   }
   return runtimeWorkloadAuthorities
@@ -107,6 +121,30 @@ export const requiredWorkloadAuthorities = (
     .sort(compareWireTokens);
 };
 
+/**
+ * The digest-pinned image reference a node pulls this workload by.
+ *
+ * One function decides where the bytes come from: the stated `pullEndpoint`, else the publishing
+ * `registryHost`. The digest is the same either way, so a node that pulls through its cluster's
+ * relay fetches exactly the content the publishing registry named, and a controller and a node can
+ * never disagree about the reference. The workload is read as a wire value, so one whose members
+ * this contract refuses is refused here rather than by a member read.
+ */
+export const buildRuntimeAssignmentImageReference = (
+  workloadArg: IRuntimeAssignment['workload'],
+): string => {
+  if (!isExactRecord(workloadArg, workloadKeys, optionalWorkloadKeys)) {
+    fail(workloadSchemaMessage);
+  }
+  const endpoint = Object.hasOwn(workloadArg, 'pullEndpoint')
+    ? workloadArg.pullEndpoint : workloadArg.registryHost;
+  if (typeof endpoint !== 'string' || typeof workloadArg.repository !== 'string'
+    || !isDigest(workloadArg.imageDigest)) {
+    fail(workloadSchemaMessage);
+  }
+  return buildDigestPinnedImageReference(endpoint, workloadArg.repository, workloadArg.imageDigest);
+};
+
 /** True when a value is exactly a canonical authority list drawn from the authority vocabulary. */
 export const isResolvedWorkloadAuthorities = (
   valueArg: unknown,
@@ -147,23 +185,50 @@ 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 =>
   typeof valueArg === 'string' && isSha256Digest(valueArg);
 
-/** Reject accessors before reading any fields; do not run input-owned code. */
+/**
+ * Reject accessors before reading any fields; do not run input-owned code.
+ *
+ * Absence stays absence: a stated optional key is read, an omitted one is not defaulted, so a
+ * controller that stated nothing is distinguishable from one that stated a value.
+ */
 const isExactRecord = (
   valueArg: unknown,
   keysArg: readonly string[],
+  optionalKeysArg: readonly string[] = [],
 ): valueArg is Record<string, unknown> => {
   if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)) return false;
   const prototype = Object.getPrototypeOf(valueArg);
   if (prototype !== Object.prototype && prototype !== null) return false;
   const keys = Reflect.ownKeys(valueArg);
-  return keys.length === keysArg.length && keys.every((keyArg) => {
+  return keysArg.every((keyArg) => keys.includes(keyArg)) && keys.every((keyArg) => {
     const descriptor = Object.getOwnPropertyDescriptor(valueArg, keyArg);
-    return typeof keyArg === 'string' && keysArg.includes(keyArg)
+    return typeof keyArg === 'string' && (keysArg.includes(keyArg) || optionalKeysArg.includes(keyArg))
       && descriptor?.enumerable === true && Object.hasOwn(descriptor, 'value');
   });
 };
@@ -183,6 +248,8 @@ const isAssignmentReference = (valueArg: unknown): valueArg is IRuntimeAssignmen
 /** The workload's exact members, read by the authority vocabulary and by the snapshot alike. */
 const workloadKeys = ['registryHost', 'repository', 'imageDigest', 'platform',
   'config', 'network', 'secrets', 'storage'] as const;
+/** Stated only by a controller that sends the node somewhere else for the image bytes. */
+const optionalWorkloadKeys = ['pullEndpoint'] as const;
 const workloadSchemaMessage = 'runtime assignment workload must use exact immutable references';
 
 const assignmentKeys = [
@@ -199,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');
   }
@@ -213,8 +281,10 @@ const assertAssignment = (valueArg: unknown): IRuntimeAssignment => {
     fail('runtime assignment must bind its exact preceding generation');
   }
   const workload = valueArg.workload;
-  if (!isExactRecord(workload, workloadKeys)
+  if (!isExactRecord(workload, workloadKeys, optionalWorkloadKeys)
     || typeof workload.registryHost !== 'string' || workload.registryHost.length > 253
+    || (Object.hasOwn(workload, 'pullEndpoint')
+      && (typeof workload.pullEndpoint !== 'string' || workload.pullEndpoint.length > 253))
     || typeof workload.repository !== 'string' || workload.repository.length > 255
     || !isDigest(workload.imageDigest)
     || !['linux/amd64', 'linux/arm64'].includes(workload.platform as string)
@@ -227,6 +297,12 @@ const assertAssignment = (valueArg: unknown): IRuntimeAssignment => {
   }
   buildDigestPinnedImageReference(workload.registryHost as string,
     workload.repository as string, workload.imageDigest as TSha256Digest);
+  // The pull endpoint is an OCI registry host like the publishing one, so the same reference the
+  // node builds proves it: an endpoint no reference can name is refused where it is written.
+  if (Object.hasOwn(workload, 'pullEndpoint')) {
+    buildDigestPinnedImageReference(workload.pullEndpoint as string,
+      workload.repository as string, workload.imageDigest as TSha256Digest);
+  }
   let previousId = '';
   for (let index = 0; index < (workload.storage as unknown[]).length; index++) {
     const descriptor = Object.getOwnPropertyDescriptor(workload.storage, String(index));
@@ -304,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;
 };
@@ -89,13 +94,24 @@ export const networkDigest = (value: unknown): TSha256Digest => {
 export const networkSignature = (value: unknown): string => {
   requireNetwork(typeof value === 'string' && /^[a-f0-9]{128}$/.test(value)); return value;
 };
+/**
+ * One encoding for every Noise key this contract carries — the managed VPN credential's, a relay's
+ * hub advertisement and a cluster's VPN network: canonical 32-byte base64, never the all-zero key.
+ * Key agreement and key-pair validation belong to the native Noise implementation, not to a reader.
+ */
+export const networkNoiseKey = (value: unknown): string => {
+  requireNetwork(typeof value === 'string' && /^[A-Za-z0-9+/]{43}=$/.test(value));
+  const decoded = atob(value as string);
+  requireNetwork(decoded.length === 32 && btoa(decoded) === value && [...decoded].some(byte => byte.charCodeAt(0) !== 0));
+  return value as string;
+};
 export const networkController = (value: unknown): IRuntimeController => {
   const item = networkRecord(value, ['kind', 'id', 'epoch']);
   requireNetwork(item.kind === 'cloudly' || item.kind === 'onebox');
   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;

package/ts/private/nodeidentifier.ts

@@ -0,0 +1,25 @@
+/**
+ * The one vocabulary a node of a cluster is named in.
+ *
+ * It lives beside the canonical JSON and data-property helpers rather than in a contract module
+ * because every family reads it — the node's enrollment, its runtime session, the Spark wire, its
+ * assignments, the private network contract and the relay block — and a second spelling of the rule
+ * is a second answer to which nodes exist.
+ */
+
+/**
+ * True when a value is exactly a node id: the URL alphabet, a leading `-` or `_` included,
+ * one to 128 characters.
+ *
+ * These contracts disagreed with themselves about what a node may be called: enrollment, the
+ * session registration and the Spark wire admit a separator-led node id, which makes this the
+ * vocabulary a stored node id is written in, while the assignment and the network members read
+ * that same id by the canonical identifier vocabulary — whose first character must be
+ * alphanumeric — and refuse it, and with it the assignment, the runtime network and, because one
+ * refused egress owner fails the whole pass, its entire cluster's protected authority. A
+ * controller now keeps the first character alphanumeric where it mints, so the ids this one
+ * vocabulary serves are the ones already stored under the members that admit them.
+ */
+export const isClusterNodeId = (valueArg: unknown): valueArg is string => (
+  typeof valueArg === 'string' && /^[A-Za-z0-9_-]{1,128}$/.test(valueArg)
+);

package/ts/requests/cluster.ts

@@ -1,5 +1,6 @@
 import * as userInterfaces from '../data/user.js';
 import * as clusterInterfaces from '../data/cluster.js';
+import type * as clusterVpnInterfaces from '../data/clustervpn.js';
 import type { IClusterRuntime, TClusterRuntimeBlocker } from '../data/clusterruntime.js';
 import type { IServiceRuntimeAssignmentView } from '../data/serviceruntime.js';
 import type * as leaseInterfaces from '../data/networklease.js';
@@ -168,6 +169,40 @@ export interface IReq_Cloudly_Relay_HoldRuntimeNetworkDnsLeaseRenewals extends p
   response: leaseInterfaces.IHoldRuntimeNetworkDnsLeaseRenewalsResponse;
 }
 
+/**
+ * Cloudly pushes one cluster's complete managed VPN to that cluster's relay.
+ *
+ * The relay is its cluster's own hub: it runs the managed VPN server every node of the cluster
+ * dials, so this is the whole authority that hub serves, never a patch. It rides the relay's
+ * already registered session, which is why no cluster is named — the socket names it. The relay
+ * answers with what its hub applied, and refuses a network for another authority or a revision it
+ * has passed with one of `data.applyClusterVpnNetworkRefusals`.
+ */
+export interface IReq_Cloudly_Relay_ApplyClusterVpnNetwork extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Cloudly_Relay_ApplyClusterVpnNetwork
+> {
+  method: 'applyClusterVpnNetwork';
+  request: clusterVpnInterfaces.IApplyClusterVpnNetworkRequest;
+  response: clusterVpnInterfaces.IApplyClusterVpnNetworkResponse;
+}
+
+/**
+ * The relay asks Cloudly for its cluster's current managed VPN.
+ *
+ * A hub daemon starts empty and its lifetime is the relay's own, invisible to Cloudly, so a relay
+ * that just bound its hub pulls the current network instead of waiting for the next push. The
+ * answer is `null` while the cluster has none.
+ */
+export interface IReq_Relay_Cloudly_GetClusterVpnNetwork extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Relay_Cloudly_GetClusterVpnNetwork
+> {
+  method: 'getClusterVpnNetwork';
+  request: clusterVpnInterfaces.TGetClusterVpnNetworkRequest;
+  response: clusterVpnInterfaces.IGetClusterVpnNetworkResponse;
+}
+
 /**
  * deletes a cluster
  */

package/ts/requests/corestore.ts

@@ -1,6 +1,7 @@
 import * as plugins from '../plugins.js';
 import type { IIdentity } from '../data/user.js';
 import { hasExactKeys } from '../private/dataproperties.js';
+import { isClusterNodeId } from '../private/nodeidentifier.js';
 
 /**
  * A provisioned corestore resource (NoSQLDB database or ObjectStorage bucket)
@@ -189,9 +190,8 @@ export const validateClusterCorestoreInventory = (
     return [`${pathArg} must use its exact schema`];
   }
   const errors: string[] = [];
-  if (typeof valueArg.nodeId !== 'string'
-    || !clusterCorestoreInventoryIdentifierPattern.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 (!Number.isSafeInteger(valueArg.checkedAt) || (valueArg.checkedAt as number) < 0) {
     errors.push(`${pathArg} checkedAt must be a non-negative safe integer`);