@serve.zone/interfaces 32.5.0 → 32.7.0

package/ts/data/clustervpn.ts

@@ -1,6 +1,7 @@
-import { captureNetwork, failNetwork, networkCanonical, networkCounter, networkEqual, networkId, networkIpv4, networkList,
-  networkNodeId, networkNoiseKey, networkPrivatePrefix, networkRecord, networkSafe, networkSorted,
-  requireNetwork } from '../private/networkcontract.js';
+import { runtimeNetworkVpnControlPrefix } from './networkaddressplan.js';
+import { captureNetwork, failNetwork, networkAuthorityId, networkCanonical, networkContains, networkCounter, networkEqual,
+  networkIpv4, networkList, networkMaximumAuthorityIdBytes, 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
@@ -39,10 +40,18 @@ export interface IClusterVpnNetworkGrant {
  * Complete, never a patch: a relay applies it as the whole authority its hub serves, so a member or
  * a grant that is missing is withdrawn. `revision` is Cloudly's own counter for this authority and
  * only ever rises; `authorityId` names the authority the hub is bound to, so a network compiled for
- * another cluster is refused rather than applied.
+ * another cluster is refused rather than applied. It is bounded by
+ * `clusterVpnNetworkContract.maximumAuthorityIdBytes`, the same bound the hub daemon holds.
+ *
+ * `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[];
@@ -57,6 +66,11 @@ export const clusterVpnNetworkContract = Object.freeze({
   /** Per node; one workload lease the node's signed projection carries. */
   maximumWorkloadPrefixes: 128,
   maximumGrants: 4096,
+  /**
+   * UTF-8 bytes, matching what the hub daemon admits for the authority it binds: an id above this
+   * is refused where the network is compiled rather than by the daemon at apply time.
+   */
+  maximumAuthorityIdBytes: networkMaximumAuthorityIdBytes,
   maximumCanonicalBytes: 917_504,
   completeness: 'whole-authority-never-a-patch',
   membership: 'presence-only-an-absent-node-is-withdrawn',
@@ -168,20 +182,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 +210,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: networkAuthorityId(item.authorityId), controlPrefix, revision: networkCounter(item.revision), nodes, grants };
 });
 
 export type TClusterVpnNetworkAdmission =
@@ -208,7 +229,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/deploymentpreflight.ts

@@ -5,6 +5,7 @@ import type {
 } from './immutableimage.js';
 import { normalizeImmutableReleaseTag, normalizeSha256Digest } from './immutableimage.js';
 import type { TServiceDeploymentCapability } from './user.js';
+import { validateProtocolOfferOn, type IProtocolOffer } from '../protocol.js';
 import type {
   IDeploymentRouteRequest,
   IServiceDeploymentOperation,
@@ -190,6 +191,26 @@ export interface IDeploymentPreflightRequestData {
   routes?: IDeploymentRouteRequest[];
   /** Legacy v14 discriminator. Equivalent to mode: 'greenfield'. */
   greenfield?: true;
+  /**
+   * The deploying build's protocol offer, read and negotiated before this request is validated.
+   *
+   * This is the one request that opens a deployment, which is why the offer rides here and on no
+   * mutating deployment carrier: Cloudly derives `reserveServiceDeployment`'s `requestDigest` from
+   * the whole request body, so an offer inside one of those would bind an operation's identity to
+   * the interfaces release the deployer happened to have installed, and an in-flight deployment
+   * would stop being resumable across a deployer upgrade. Naming the skew on the read that opens
+   * the flow costs nothing durable and refuses it before anything is reserved.
+   *
+   * Optional, because a peer that speaks this release states nothing by offering and older
+   * deployers send none: absence is a valid request, not a refusal. A member stated as `undefined`
+   * is absent too, like every other optional member of this shape, so a caller that spreads an
+   * offer it may not hold states no offer rather than a malformed one. When an offer is stated it
+   * is exact-key, exactly like every other offer in this package —
+   * `validateDeploymentPreflightRequest` judges it with the same reader
+   * `protocol.readProtocolOffer` negotiates from, so a body cannot pass this validator with an
+   * offer the server's own read would refuse.
+   */
+  protocol?: IProtocolOffer;
 }
 
 export interface IDeploymentPreflightReport {
@@ -412,6 +433,23 @@ export const validateDeploymentPreflightRequest = (
   )) {
     blockers.push({ code: 'INVALID_REQUEST', message: 'Deployment route declaration is malformed.' });
   }
+  // Presence is decided from the own property alone: reading `requestArg.protocol` would run an
+  // accessor a caller attached to the body, and the offer a validator judges has to be the value
+  // the server negotiates from. A data property holding `undefined` states no offer, exactly as
+  // the optional members above read an omitted value, so spreading an offer a caller may not hold
+  // is not a malformed one. An accessor is neither of those: it is refused, and never invoked —
+  // the check reads a descriptor, and `validateProtocolOfferOn` reads the key as data as well.
+  const protocolProperty = Object.getOwnPropertyDescriptor(requestArg, 'protocol');
+  const statedProtocolOffer = protocolProperty !== undefined
+    && !(Object.hasOwn(protocolProperty, 'value') && protocolProperty.value === undefined)
+    ? validateProtocolOfferOn(requestArg, 'deployment preflight protocol offer')
+    : [];
+  if (statedProtocolOffer.length > 0) {
+    blockers.push({
+      code: 'INVALID_REQUEST',
+      message: `The stated protocol offer is malformed: ${statedProtocolOffer.join('; ')}.`,
+    });
+  }
   if (mode === 'greenfield' && Array.isArray(requestArg.routes)
     && JSON.stringify([...new Set(requestArg.routes.map((routeArg) => (
       isRecord(routeArg) && typeof routeArg.hostname === 'string' ? routeArg.hostname : ''

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/networkcredential.ts

@@ -3,9 +3,9 @@ import { runtimeNetworkAddressPlanContract, type TRuntimeNetworkVpnTransport } f
 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,
-  networkNoiseKey, networkRecord, networkReference, networkReferenceOf, networkSafe, networkSameScope,
-  requireNetwork } from '../private/networkcontract.js';
+import { captureNetwork, failNetwork, networkAuthorityId, networkCounter, networkEffectiveDnsWindow, networkEqual,
+  networkId, networkIpv4, networkNoiseKey, networkRecord, networkReference, networkReferenceOf, networkSafe,
+  networkSameScope, requireNetwork } from '../private/networkcontract.js';
 
 export interface IGetRuntimeManagedVpnCredentialRequest {
   session: IRuntimeSessionBinding;
@@ -19,13 +19,7 @@ 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;
+  /** The hub's managed authority, under the one bound the hub daemon holds for it. */
   authorityId: string;
   serverPublicKey: string;
   clientPublicKey: string;
@@ -42,21 +36,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,15 +43,12 @@ 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),
+    authorityId: networkAuthorityId(item.authorityId), serverPublicKey: networkNoiseKey(item.serverPublicKey),
     clientPublicKey: networkNoiseKey(item.clientPublicKey), clientPrivateKey: networkNoiseKey(item.clientPrivateKey),
     expiresAt: networkCounter(item.expiresAt) };
 });

package/ts/private/networkcontract.ts

@@ -80,6 +80,26 @@ 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;
 };
+/**
+ * The longest managed VPN authority id any contract of this package admits, in UTF-8 bytes.
+ *
+ * SmartVPN's managed registry refuses an authority id longer than 128 bytes, and it is the daemon
+ * that applies a pushed network, so an id between that bound and the generic identifier bound
+ * above would pass every contract on the way and be refused only at apply time, on the far side of
+ * a push, as a hub reporting `state: 'failed'`. Bounding it where the id is admitted moves that
+ * refusal to where Cloudly compiles the network, on its own stack, before anything is pushed.
+ *
+ * Bytes, because that is what the daemon counts. The identifier grammar admits ASCII alone, so a
+ * byte and a code point are the same thing for every id that gets this far; measuring bytes keeps
+ * the bound equal to the daemon's the day the grammar admits anything wider.
+ */
+export const networkMaximumAuthorityIdBytes = 128;
+/** A managed VPN authority id: a canonical identifier the cluster's hub daemon also admits. */
+export const networkAuthorityId = (value: unknown): string => {
+  const id = networkId(value);
+  requireNetwork(new TextEncoder().encode(id).length <= networkMaximumAuthorityIdBytes);
+  return id;
+};
 /** 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;

package/ts/requests/service.ts

@@ -16,6 +16,7 @@ import type {
   IServiceDeploymentStatus,
 } from '../data/deploymentoperation.js';
 import type { TSha256Digest } from '../data/immutableimage.js';
+import type { IProtocolOffer } from '../protocol.js';
 import type {
   IServiceRuntimeAssignmentView,
   IServiceRuntimeSpec,
@@ -113,6 +114,18 @@ extends plugins.typedrequestInterfaces.implementsTR<
   request: {
     identity: IIdentity;
     serviceId: string;
+    /**
+     * The calling build's protocol offer, read and negotiated before the request is served.
+     *
+     * The read that opens a deployment adoption, and the only other deployment carrier that
+     * carries an offer: the mutating ones stay byte-exact because Cloudly derives a deployment
+     * operation's `requestDigest` from the whole request body, and an offer there would bind that
+     * operation's identity to the caller's interfaces release. Optional, because a peer of this
+     * release states nothing by offering and a caller that opens no deployment sends none —
+     * absence is a valid request. A stated offer is exact-key, judged by
+     * `protocol.readProtocolOffer` / `protocol.validateProtocolOfferOn` like every other offer.
+     */
+    protocol?: IProtocolOffer;
   };
   response: {
     service: IService;