@serve.zone/interfaces 31.2.0 → 31.4.0

package/ts/data/clusteringress.ts

@@ -0,0 +1,425 @@
+import { isPlausibleUnicastIpv4 } from '../private/ipv4.js';
+import { isUtcCalendarDay } from '../private/utccalendarday.js';
+
+/**
+ * The cluster ingress contracts.
+ *
+ * A cluster's ingress terminates TLS for the hostnames its services publish and
+ * forwards to the host ports Pallet published for the workloads behind them.
+ * Cloudly computes the table — it is the only party that knows every service,
+ * every ready endpoint and every certificate — and the relay carries it to the
+ * ingress and the ingress's counters back.
+ *
+ * Names here carry no version suffix and no schema field: the protocol version
+ * is the installed `@serve.zone/interfaces` version.
+ */
+
+export const clusterIngressLimits = Object.freeze({
+  minimumIngressBearerLength: 16,
+  maximumIngressBearerLength: 4096,
+  maximumHostNameLength: 253,
+  maximumRoutes: 4096,
+  maximumPortRoutes: 1024,
+  maximumDestinationsPerRoute: 64,
+  maximumStatisticsPageSize: 1000,
+  maximumCursorLength: 512,
+  maximumIdentifierLength: 200,
+  maximumIngressCapabilities: 32,
+});
+
+/** One backend a route forwards to: an address a node answers on, and its port. */
+export interface IClusterRouteDestination {
+  address: string;
+  port: number;
+}
+
+/** Basic authentication for a route, as the proxy has always expressed it. */
+export interface IClusterRouteAuthentication {
+  type: 'Basic';
+  user: string;
+  pass: string;
+}
+
+/**
+ * One hostname the ingress serves.
+ *
+ * `certificate` carries the private key the ingress needs to terminate TLS for
+ * `hostName`. A route table is therefore secret-bearing end to end: it is never
+ * logged, never journaled, never written to disk, and no validation reason
+ * derived from it ever quotes it.
+ */
+export interface IClusterHttpRoute {
+  hostName: string;
+  destinations: IClusterRouteDestination[];
+  certificate: {
+    publicKey: string;
+    privateKey: string;
+  };
+  authentication?: IClusterRouteAuthentication;
+}
+
+/** One TCP or UDP port the ingress forwards without terminating anything. */
+export interface IClusterPortRoute {
+  name: string;
+  listenPort: number;
+  transport: 'tcp' | 'udp';
+  destinations: IClusterRouteDestination[];
+}
+
+/**
+ * Everything a cluster's ingress serves, as one table.
+ *
+ * `revision` is the only idempotency the feed has: an ingress and a relay apply
+ * a table whose revision is greater than the one they hold and ignore anything
+ * else, so a repeated push, a replayed push and a push that crossed a newer one
+ * all settle the same way.
+ */
+export interface IClusterRouteTable {
+  revision: number;
+  issuedAt: number;
+  routes: IClusterHttpRoute[];
+  portRoutes: IClusterPortRoute[];
+}
+
+/**
+ * One day of one hostname's traffic on one node, as the ingress counted it.
+ *
+ * Day buckets rather than rates: a rate answers "how busy is it now", which the
+ * live proxy already answers, while a bucket survives a restart, a poll that
+ * straddles midnight and a Cloudly outage.
+ */
+export interface IClusterTrafficStatistics {
+  serviceId: string;
+  hostName: string;
+  nodeId: string;
+  /** UTC calendar day, `YYYY-MM-DD`. */
+  dayUtc: string;
+  requests: number;
+  bytesIn: number;
+  bytesOut: number;
+  connections: number;
+  /**
+   * What the proxy could observe about its backends. HTTP status classes are
+   * deliberately absent: the proxy exposes no status counters today, and a
+   * number this contract cannot source would be a guess.
+   */
+  backendErrors: {
+    connect: number;
+    handshake: number;
+    request: number;
+  };
+  updatedAt: number;
+}
+
+const isRecord = (valueArg: unknown): valueArg is Record<string, unknown> => (
+  Boolean(valueArg)
+  && typeof valueArg === 'object'
+  && !Array.isArray(valueArg)
+  && (Object.getPrototypeOf(valueArg) === Object.prototype
+    || Object.getPrototypeOf(valueArg) === null)
+);
+
+const hasExactKeys = (
+  valueArg: Record<string, unknown>,
+  keysArg: readonly string[],
+  optionalKeysArg: readonly string[] = [],
+): boolean => {
+  const actualKeys = Object.keys(valueArg);
+  return keysArg.every((keyArg) => actualKeys.includes(keyArg))
+    && actualKeys.every((keyArg) => keysArg.includes(keyArg) || optionalKeysArg.includes(keyArg));
+};
+
+const isCounter = (valueArg: unknown): valueArg is number => (
+  Number.isSafeInteger(valueArg) && (valueArg as number) >= 0
+);
+
+const isPort = (valueArg: unknown): valueArg is number => (
+  Number.isSafeInteger(valueArg) && (valueArg as number) >= 1 && (valueArg as number) <= 65_535
+);
+
+const hostLabelPattern = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+// Built from the limit rather than beside it, so the two can never disagree.
+const identifierPattern = new RegExp(
+  `^[A-Za-z0-9][A-Za-z0-9:._-]{0,${clusterIngressLimits.maximumIdentifierLength - 1}}$`,
+);
+
+/**
+ * A hostname a certificate can be issued for and a browser can present.
+ *
+ * Lowercase labels only, because a certificate names the lowercase form and a
+ * table that carried both would serve one of them without a certificate.
+ */
+export const isClusterIngressHostName = (valueArg: unknown): valueArg is string => {
+  if (typeof valueArg !== 'string'
+    || valueArg.length === 0
+    || valueArg.length > clusterIngressLimits.maximumHostNameLength) {
+    return false;
+  }
+  const labels = valueArg.split('.');
+  return labels.length >= 2 && labels.every((labelArg) => hostLabelPattern.test(labelArg));
+};
+
+const validateDestinations = (valueArg: unknown, pathArg: string): string[] => {
+  if (!Array.isArray(valueArg)
+    || valueArg.length === 0
+    || valueArg.length > clusterIngressLimits.maximumDestinationsPerRoute) {
+    return [`${pathArg} must list 1 to `
+      + `${clusterIngressLimits.maximumDestinationsPerRoute} destinations`];
+  }
+  const errors: string[] = [];
+  for (const [index, destination] of valueArg.entries()) {
+    const destinationPath = `${pathArg}[${index}]`;
+    if (!isRecord(destination) || !hasExactKeys(destination, ['address', 'port'])) {
+      errors.push(`${destinationPath} must use its exact schema`);
+      continue;
+    }
+    if (!isPlausibleUnicastIpv4(destination.address)) {
+      errors.push(`${destinationPath} address must be a unicast IPv4 literal`);
+    }
+    if (!isPort(destination.port)) {
+      errors.push(`${destinationPath} port must be an integer from 1 to 65535`);
+    }
+  }
+  return errors;
+};
+
+const validateCertificate = (valueArg: unknown, pathArg: string): string[] => {
+  // Presence and shape only. The material itself is never described in a reason:
+  // a validation message travels into logs, and this one would carry a key.
+  if (!isRecord(valueArg) || !hasExactKeys(valueArg, ['publicKey', 'privateKey'])) {
+    return [`${pathArg} must use its exact schema`];
+  }
+  const errors: string[] = [];
+  if (typeof valueArg.publicKey !== 'string' || valueArg.publicKey.length === 0) {
+    errors.push(`${pathArg} publicKey must be a non-empty PEM string`);
+  }
+  if (typeof valueArg.privateKey !== 'string' || valueArg.privateKey.length === 0) {
+    errors.push(`${pathArg} privateKey must be a non-empty PEM string`);
+  }
+  return errors;
+};
+
+const validateAuthentication = (valueArg: unknown, pathArg: string): string[] => {
+  if (!isRecord(valueArg) || !hasExactKeys(valueArg, ['type', 'user', 'pass'])) {
+    return [`${pathArg} must use its exact schema`];
+  }
+  return valueArg.type === 'Basic'
+    && typeof valueArg.user === 'string' && valueArg.user.length > 0
+    && typeof valueArg.pass === 'string' && valueArg.pass.length > 0
+    ? []
+    : [`${pathArg} must be Basic authentication with a user and a pass`];
+};
+
+const validateHttpRoute = (valueArg: unknown, pathArg: string): string[] => {
+  if (!isRecord(valueArg)
+    || !hasExactKeys(valueArg, ['hostName', 'destinations', 'certificate'], ['authentication'])) {
+    return [`${pathArg} must use its exact schema`];
+  }
+  const errors: string[] = [];
+  if (!isClusterIngressHostName(valueArg.hostName)) {
+    errors.push(`${pathArg} hostName must be a lowercase dotted hostname a certificate can name`);
+  }
+  errors.push(...validateDestinations(valueArg.destinations, `${pathArg} destinations`));
+  errors.push(...validateCertificate(valueArg.certificate, `${pathArg} certificate`));
+  if (valueArg.authentication !== undefined) {
+    errors.push(...validateAuthentication(valueArg.authentication, `${pathArg} authentication`));
+  }
+  return errors;
+};
+
+const validatePortRoute = (valueArg: unknown, pathArg: string): string[] => {
+  if (!isRecord(valueArg)
+    || !hasExactKeys(valueArg, ['name', 'listenPort', 'transport', 'destinations'])) {
+    return [`${pathArg} must use its exact schema`];
+  }
+  const errors: string[] = [];
+  if (typeof valueArg.name !== 'string' || !identifierPattern.test(valueArg.name)) {
+    errors.push(`${pathArg} name must be a bounded identifier`);
+  }
+  if (!isPort(valueArg.listenPort)) {
+    errors.push(`${pathArg} listenPort must be an integer from 1 to 65535`);
+  }
+  if (valueArg.transport !== 'tcp' && valueArg.transport !== 'udp') {
+    errors.push(`${pathArg} transport must be tcp or udp`);
+  }
+  errors.push(...validateDestinations(valueArg.destinations, `${pathArg} destinations`));
+  return errors;
+};
+
+/**
+ * Validates one route table and names every reason it is refused.
+ *
+ * Shape only. Whether a hostname belongs to the cluster, whether a certificate
+ * matches it, and whether a destination is a node of this cluster are decisions
+ * for the party that computed the table; a table that passes here has claimed
+ * none of them. No reason ever quotes certificate material.
+ */
+export const validateClusterRouteTable = (
+  valueArg: unknown,
+  pathArg = 'cluster route table',
+): string[] => {
+  if (!isRecord(valueArg)
+    || !hasExactKeys(valueArg, ['revision', 'issuedAt', 'routes', 'portRoutes'])) {
+    return [`${pathArg} must use its exact schema`];
+  }
+  const errors: string[] = [];
+  if (!isCounter(valueArg.revision)) {
+    errors.push(`${pathArg} revision must be a non-negative safe integer`);
+  }
+  if (!Number.isSafeInteger(valueArg.issuedAt) || (valueArg.issuedAt as number) <= 0) {
+    errors.push(`${pathArg} issuedAt must be a positive epoch millisecond timestamp`);
+  }
+  if (!Array.isArray(valueArg.routes)
+    || valueArg.routes.length > clusterIngressLimits.maximumRoutes) {
+    errors.push(`${pathArg} routes must list at most ${clusterIngressLimits.maximumRoutes} routes`);
+  } else {
+    const seenHostNames = new Set<string>();
+    for (const [index, route] of valueArg.routes.entries()) {
+      errors.push(...validateHttpRoute(route, `${pathArg} routes[${index}]`));
+      const hostName = isRecord(route) ? route.hostName : undefined;
+      if (typeof hostName === 'string') {
+        if (seenHostNames.has(hostName)) {
+          errors.push(`${pathArg} routes[${index}] repeats hostName ${hostName}`);
+        }
+        seenHostNames.add(hostName);
+      }
+    }
+  }
+  if (!Array.isArray(valueArg.portRoutes)
+    || valueArg.portRoutes.length > clusterIngressLimits.maximumPortRoutes) {
+    errors.push(`${pathArg} portRoutes must list at most `
+      + `${clusterIngressLimits.maximumPortRoutes} port routes`);
+  } else {
+    const seenPorts = new Set<string>();
+    for (const [index, portRoute] of valueArg.portRoutes.entries()) {
+      errors.push(...validatePortRoute(portRoute, `${pathArg} portRoutes[${index}]`));
+      if (!isRecord(portRoute)) {
+        continue;
+      }
+      const key = `${String(portRoute.transport)}:${String(portRoute.listenPort)}`;
+      if (seenPorts.has(key)) {
+        errors.push(`${pathArg} portRoutes[${index}] repeats ${key}`);
+      }
+      seenPorts.add(key);
+    }
+  }
+  return errors;
+};
+
+/** Validates one day bucket of ingress counters. */
+export const validateClusterTrafficStatistics = (
+  valueArg: unknown,
+  pathArg = 'cluster traffic statistics',
+): string[] => {
+  if (!isRecord(valueArg) || !hasExactKeys(valueArg, [
+    'serviceId', 'hostName', 'nodeId', 'dayUtc', 'requests', 'bytesIn', 'bytesOut',
+    'connections', 'backendErrors', 'updatedAt',
+  ])) {
+    return [`${pathArg} must use its exact schema`];
+  }
+  const errors: string[] = [];
+  for (const key of ['serviceId', 'nodeId'] as const) {
+    const value = valueArg[key];
+    if (typeof value !== 'string' || !identifierPattern.test(value)) {
+      errors.push(`${pathArg} ${key} must be a bounded identifier`);
+    }
+  }
+  if (!isClusterIngressHostName(valueArg.hostName)) {
+    errors.push(`${pathArg} hostName must be a lowercase dotted hostname`);
+  }
+  if (!isUtcCalendarDay(valueArg.dayUtc)) {
+    errors.push(`${pathArg} dayUtc must be a real YYYY-MM-DD UTC calendar day`);
+  }
+  for (const key of ['requests', 'bytesIn', 'bytesOut', 'connections'] as const) {
+    if (!isCounter(valueArg[key])) {
+      errors.push(`${pathArg} ${key} must be a non-negative safe integer`);
+    }
+  }
+  const backendErrors = valueArg.backendErrors;
+  if (!isRecord(backendErrors)
+    || !hasExactKeys(backendErrors, ['connect', 'handshake', 'request'])
+    || !isCounter(backendErrors.connect)
+    || !isCounter(backendErrors.handshake)
+    || !isCounter(backendErrors.request)) {
+    errors.push(`${pathArg} backendErrors must count connect, handshake and request failures`);
+  }
+  if (!Number.isSafeInteger(valueArg.updatedAt) || (valueArg.updatedAt as number) <= 0) {
+    errors.push(`${pathArg} updatedAt must be a positive epoch millisecond timestamp`);
+  }
+  return errors;
+};
+
+/**
+ * Validates one page of ingress counters, as a reader receives it.
+ *
+ * The cursor is opaque to everyone but the ingress that issued it: bounded and
+ * printable here, meaningful only there.
+ */
+export const validateClusterTrafficStatisticsPage = (
+  valueArg: unknown,
+  pathArg = 'cluster traffic statistics page',
+): string[] => {
+  if (!isRecord(valueArg) || !hasExactKeys(valueArg, ['statistics'], ['nextCursor'])) {
+    return [`${pathArg} must use its exact schema`];
+  }
+  const errors: string[] = [];
+  if (!Array.isArray(valueArg.statistics)
+    || valueArg.statistics.length > clusterIngressLimits.maximumStatisticsPageSize) {
+    errors.push(`${pathArg} statistics must list at most `
+      + `${clusterIngressLimits.maximumStatisticsPageSize} entries`);
+  } else {
+    for (const [index, item] of valueArg.statistics.entries()) {
+      errors.push(...validateClusterTrafficStatistics(item, `${pathArg} statistics[${index}]`));
+    }
+  }
+  if (valueArg.nextCursor !== undefined
+    && (typeof valueArg.nextCursor !== 'string'
+      || valueArg.nextCursor.length === 0
+      || valueArg.nextCursor.length > clusterIngressLimits.maximumCursorLength)) {
+    errors.push(`${pathArg} nextCursor must be 1 to `
+      + `${clusterIngressLimits.maximumCursorLength} characters when present`);
+  }
+  return errors;
+};
+
+/**
+ * Validates one cluster ingress registration and names every reason it is refused.
+ *
+ * Shape only, and deliberately so: whether the bearer is the one Cloudly minted
+ * for this cluster's ingress is Cloudly's to verify against its own records, and
+ * which cluster is speaking comes from the identity tag on the relay's session.
+ * A registration that passes here has proven nothing — and no reason it returns
+ * ever quotes the bearer, because a reason travels into logs.
+ */
+export const validateClusterIngressRegistration = (
+  valueArg: unknown,
+  pathArg = 'cluster ingress registration',
+): string[] => {
+  if (!isRecord(valueArg)
+    || !hasExactKeys(valueArg, ['bearer', 'version', 'nodeId'], ['capabilities'])) {
+    return [`${pathArg} must use its exact schema`];
+  }
+  const errors: string[] = [];
+  if (typeof valueArg.bearer !== 'string'
+    || valueArg.bearer.length < clusterIngressLimits.minimumIngressBearerLength
+    || valueArg.bearer.length > clusterIngressLimits.maximumIngressBearerLength) {
+    errors.push(`${pathArg} bearer must be ${clusterIngressLimits.minimumIngressBearerLength} to `
+      + `${clusterIngressLimits.maximumIngressBearerLength} characters`);
+  }
+  if (typeof valueArg.version !== 'string' || !identifierPattern.test(valueArg.version)) {
+    errors.push(`${pathArg} version must be a bounded identifier`);
+  }
+  if (typeof valueArg.nodeId !== 'string' || !identifierPattern.test(valueArg.nodeId)) {
+    errors.push(`${pathArg} nodeId must be a bounded identifier`);
+  }
+  if (valueArg.capabilities !== undefined
+    && (!Array.isArray(valueArg.capabilities)
+      || valueArg.capabilities.length > clusterIngressLimits.maximumIngressCapabilities
+      || !valueArg.capabilities.every((capabilityArg) => (
+        typeof capabilityArg === 'string' && identifierPattern.test(capabilityArg)
+      )))) {
+    errors.push(`${pathArg} capabilities must be at most `
+      + `${clusterIngressLimits.maximumIngressCapabilities} bounded identifiers when present`);
+  }
+  return errors;
+};

package/ts/data/coremail.runtime.ts

@@ -1,3 +1,4 @@
+import { isRealUtcCalendarDay, utcCalendarDayPattern } from '../private/utccalendarday.js';
 import {
   canonicalizeStrictJson,
   createCanonicalJsonSha256Hex,
@@ -2047,20 +2048,12 @@ export const normalizeCoreMailGatewayPeerDesiredState = (
   });
 };
 
-const utcCalendarDayRegex = /^[0-9]{4}-[0-9]{2}-[0-9]{2}$/;
-
 const requireUtcCalendarDay = (valueArg: unknown, pathArg: string): string => {
   const value = requireString(valueArg, pathArg, 10);
-  if (!utcCalendarDayRegex.test(value)) {
+  if (!utcCalendarDayPattern.test(value)) {
     fail(`${pathArg} must be a canonical YYYY-MM-DD UTC day`);
   }
-  const [year, month, day] = value.split('-').map(Number);
-  const parsed = new Date(Date.UTC(year, month - 1, day));
-  if (
-    parsed.getUTCFullYear() !== year
-    || parsed.getUTCMonth() + 1 !== month
-    || parsed.getUTCDate() !== day
-  ) {
+  if (!isRealUtcCalendarDay(value)) {
     fail(`${pathArg} must be a real UTC calendar day`);
   }
   return value;

package/ts/data/index.ts

@@ -1,5 +1,6 @@
 export * from './cloudlyconfig.js';
 export * from './cluster.js';
+export * from './clusteringress.js';
 export * from './config.js';
 export * from './coremail.js';
 export * from './coremail.runtime.js';

package/ts/data/networkprotection.ts

@@ -1,3 +1,4 @@
+import { isPlausibleUnicastIpv4 } from '../private/ipv4.js';
 import type { TSha256Digest } from './immutableimage.js';
 import type { IRuntimeAuthorityReferenceV1 } from './runtimeassignment.js';
 import type { IRuntimeNetworkNodeScopeV1 } from './networkprojection.js';
@@ -32,6 +33,16 @@ export interface IRuntimeNetworkProtectionReceiptV1 extends IRuntimeNetworkNodeS
 export interface IReportRuntimeNetworkProtectionRequestV1 {
   session: IRuntimeSessionBindingV1;
   receipt: IRuntimeNetworkProtectionReceiptV1;
+  /**
+   * The address this node answers on, as the node itself observed it.
+   *
+   * A route to one of this node's published host ports uses exactly this
+   * address. Only the node can prove it — it holds the uplink observation the
+   * address belongs to — so it states it here, on the report it already sends
+   * about its own network, and Cloudly stores it rather than inferring one.
+   * Absent from a node that has not stated one; never defaulted, never guessed.
+   */
+  uplinkAddress?: string;
 }
 export interface IReportRuntimeNetworkProtectionResponseV1 {
   status: 'accepted' | 'replay';
@@ -113,10 +124,31 @@ export const admitRuntimeNetworkProtectionReceiptV1 = async (
 };
 
 export const snapshotReportRuntimeNetworkProtectionRequestV1 = (value: unknown): IReportRuntimeNetworkProtectionRequestV1 => networkSafe(() => {
-  const item = networkRecord(captureNetwork(value), ['session', 'receipt']);
-  return { session: snapshotRuntimeSessionBindingV1(item.session), receipt: snapshotRuntimeNetworkProtectionReceiptV1(item.receipt) };
+  const item = networkRecord(captureNetwork(value), ['session', 'receipt'], ['uplinkAddress']);
+  const request: IReportRuntimeNetworkProtectionRequestV1 = {
+    session: snapshotRuntimeSessionBindingV1(item.session),
+    receipt: snapshotRuntimeNetworkProtectionReceiptV1(item.receipt),
+  };
+  if (Object.hasOwn(item, 'uplinkAddress')) {
+    request.uplinkAddress = runtimeNodeUplinkAddress(item.uplinkAddress);
+  }
+  return request;
 });
 
+/**
+ * The address a route to this node's published ports uses.
+ *
+ * A unicast IPv4 literal that is neither loopback nor link-local: a node that
+ * stated one of those would publish an address no other node can reach, and a
+ * route table built from it would send every request nowhere.
+ */
+export const runtimeNodeUplinkAddress = (value: unknown): string => {
+  requireNetwork(isPlausibleUnicastIpv4(value)
+    && !value.startsWith('127.')
+    && !value.startsWith('169.254.'));
+  return value;
+};
+
 /** Both trusted bindings come from the receiver's fenced physical-session/history owner. */
 export const bindReportRuntimeNetworkProtectionRequestV1 = (
   value: unknown, trustedCurrentSessionValue: unknown, trustedReporterSessionValue: unknown,

package/ts/data/privatenetwork.ts

@@ -1,3 +1,5 @@
+import { isPlausibleUnicastIpv4 } from '../private/ipv4.js';
+
 /** Cloudly owns these definitions. Membership never follows node placement. */
 export interface IPrivateNetworkPolicyV1 {
   connectivity: 'member-full-mesh';
@@ -133,10 +135,7 @@ const sorted = (values: string[]): string[] => {
   return values;
 };
 const ipv4 = (value: unknown): string => {
-  requireValue(typeof value === 'string');
-  const parts = value.split('.');
-  requireValue(parts.length === 4 && parts.every(part => /^(?:0|[1-9][0-9]{0,2})$/.test(part) && Number(part) <= 255));
-  requireValue(Number(parts[0]) > 0 && Number(parts[0]) < 224 && value !== '255.255.255.255');
+  requireValue(isPlausibleUnicastIpv4(value));
   return value;
 };
 const publicSuffix = (value: unknown): string => {

package/ts/private/ipv4.ts

@@ -0,0 +1,24 @@
+/**
+ * The dotted-quad IPv4 form every consumer of this package agrees on.
+ *
+ * Shape only: an address that passes here is still neither routable, owned, reachable nor
+ * authorized. The rule refuses what can never be a unicast host address — a quad that is not
+ * canonical, the `0.0.0.0/8` unspecified block, and everything from `224.0.0.0` up, which is
+ * multicast and reserved space and therefore also covers the all-ones broadcast address.
+ */
+export const isPlausibleUnicastIpv4 = (valueArg: unknown): valueArg is string => {
+  if (typeof valueArg !== 'string') {
+    return false;
+  }
+  const octets = valueArg.split('.');
+  if (octets.length !== 4) {
+    return false;
+  }
+  if (!octets.every((octetArg) => (
+    /^(?:0|[1-9][0-9]{0,2})$/.test(octetArg) && Number(octetArg) <= 255
+  ))) {
+    return false;
+  }
+  const leadingOctet = Number(octets[0]);
+  return leadingOctet > 0 && leadingOctet < 224;
+};

package/ts/private/networkcontract.ts

@@ -56,10 +56,16 @@ export const captureNetwork = (value: unknown): unknown => networkSafe(() => {
   return result;
 });
 
-export const networkRecord = (value: unknown, keys: string[]): Record<string, unknown> => {
+export const networkRecord = (
+  value: unknown, keys: string[], optionalKeys: string[] = [],
+): Record<string, unknown> => {
   requireNetwork(value !== null && typeof value === 'object' && !Array.isArray(value));
   const actual = Object.keys(value);
-  requireNetwork(actual.length === keys.length && keys.every(key => Object.hasOwn(value, key)));
+  // Absence stays absent: a stated optional key is read, an omitted one is not
+  // defaulted, so a receiver can tell a sender that stated nothing from one that
+  // stated a value.
+  requireNetwork(keys.every(key => Object.hasOwn(value, key))
+    && actual.every(key => keys.includes(key) || optionalKeys.includes(key)));
   return value as Record<string, unknown>;
 };
 export const networkList = <T>(value: unknown, maximum: number, read: (item: unknown) => T): T[] => {

package/ts/private/utccalendarday.ts

@@ -0,0 +1,30 @@
+/**
+ * The UTC calendar day every consumer of this package agrees on.
+ *
+ * Two facts, deliberately separate: whether a value has the canonical shape, and whether that
+ * shape names a day that exists. `2026-13-45` passes the first and fails the second, and a
+ * caller that only checked the pattern would store a day no clock can ever produce.
+ */
+export const utcCalendarDayPattern = /^[0-9]{4}-[0-9]{2}-[0-9]{2}$/;
+
+/**
+ * Whether a canonical `YYYY-MM-DD` string names a real day.
+ *
+ * Round-trips through `Date.UTC`, which normalises an impossible day into a neighbouring one:
+ * a value that survives the round trip unchanged is the day it claims to be.
+ */
+export const isRealUtcCalendarDay = (valueArg: string): boolean => {
+  if (!utcCalendarDayPattern.test(valueArg)) {
+    return false;
+  }
+  const [year, month, day] = valueArg.split('-').map(Number);
+  const parsed = new Date(Date.UTC(year, month - 1, day));
+  return parsed.getUTCFullYear() === year
+    && parsed.getUTCMonth() + 1 === month
+    && parsed.getUTCDate() === day;
+};
+
+/** Both facts at once, for a caller that reports one reason. */
+export const isUtcCalendarDay = (valueArg: unknown): valueArg is string => (
+  typeof valueArg === 'string' && isRealUtcCalendarDay(valueArg)
+);

package/ts/requests/cluster.ts

@@ -66,6 +66,65 @@ export interface IReq_Any_Cloudly_UpdateCluster extends plugins.typedrequestInte
   };
 }
 
+/**
+ * Enables this cluster's relay.
+ *
+ * Cloudly derives the relay origin itself from the cluster and its own public hostname, so a
+ * caller cannot name one, and refuses the request when no managed DNS zone matches that name.
+ * The response carries the block Cloudly published, which is the same block every cluster-side
+ * component then reads from `ICluster.data.relay`.
+ */
+export interface IReq_Any_Cloudly_EnableClusterRelayV1 extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_EnableClusterRelayV1
+> {
+  method: 'enableClusterRelayV1';
+  request: {
+    identity: userInterfaces.IIdentity;
+    clusterId: string;
+  };
+  response: {
+    relay: clusterInterfaces.IClusterRelayV1;
+  };
+}
+
+/**
+ * Disables this cluster's relay, removing the block from the cluster document.
+ *
+ * The nodes of the cluster target Cloudly directly again, so `relay` is explicitly `null` in
+ * the response rather than absent: the caller learns that the block is gone, not that the
+ * response forgot it.
+ */
+export interface IReq_Any_Cloudly_DisableClusterRelayV1 extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_DisableClusterRelayV1
+> {
+  method: 'disableClusterRelayV1';
+  request: {
+    identity: userInterfaces.IIdentity;
+    clusterId: string;
+  };
+  response: {
+    relay: null;
+  };
+}
+
+/**
+ * The cluster relay tells Cloudly where it listens, over its own authenticated socket.
+ *
+ * Sent after `registerCloudlyClientSessionV1`, so the cluster is the one the verified machine
+ * identity on that socket names and is never a request field. `Relay` names the role, not a
+ * component: whichever process fills it for a cluster sends this.
+ */
+export interface IReq_Relay_Cloudly_RegisterClusterRelayV1 extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Relay_Cloudly_RegisterClusterRelayV1
+> {
+  method: 'registerClusterRelayV1';
+  request: clusterInterfaces.IClusterRelayRegistrationV1;
+  response: clusterInterfaces.IClusterRelayRegistrationResponseV1;
+}
+
 /**
  * deletes a cluster
  */