@serve.zone/interfaces 31.1.0 → 31.2.0

package/changelog.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 2026-09-16 - 31.2.0
+
+### Features
+
+- Add the optional `ICluster.data.relay` block, `IClusterRelayV1 { schemaVersion: 1; origin: string }`:
+  how cluster-side components reach this cluster's relay, absent on a cluster whose nodes still
+  target Cloudly directly, so its presence is what marks a cluster as relayed. `origin` is the
+  exact value a Pallet node stores as its `relayOrigin` — `https:`, an explicit port allowed, no
+  path, query, fragment, userinfo or trailing slash, so `new URL(origin).origin === origin`; a
+  default `:443` and a cased host are therefore not canonical, because `URL` drops the one and
+  lowercases the other. `validateClusterRelayV1(value, pathArg?)` returns one named reason per
+  violation and an empty array for a valid block, following the package's value-free validator
+  shape. The certificate subject is deliberately not a second field: every consumer derives it
+  from the origin with `clusterRelayCertificateDomainName(relay)`, which returns the origin's
+  hostname — the name Cloudly issues the certificate for and owns the A record for — so two
+  fields can never disagree. An origin naming an address literal consequently has no issuable
+  certificate. Additive only: a cluster document without `relay` is unchanged, and nothing was
+  removed or renamed.
+
 ## 2026-09-16 - 31.1.0
 
 ### Features

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@serve.zone/interfaces',
-    version: '31.1.0',
+    version: '31.2.0',
     description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSx3QkFBd0I7SUFDOUIsT0FBTyxFQUFFLFFBQVE7SUFDakIsV0FBVyxFQUFFLHVGQUF1RjtDQUNyRyxDQUFBIn0=

package/dist_ts/data/cluster.d.ts

@@ -28,5 +28,38 @@ export interface ICluster {
             serverSecret: string;
         };
         sshKeys: plugins.tsclass.network.ISshKey[];
+        /**
+         * How cluster-side components reach this cluster's relay. Absent on a
+         * cluster whose nodes still target Cloudly directly.
+         */
+        relay?: IClusterRelayV1;
     };
 }
+/**
+ * How cluster-side components reach this cluster's relay.
+ *
+ * `origin` is the exact value a Pallet node stores as its `relayOrigin`: an
+ * `https:` origin, an explicit port allowed, with no path, no query, no
+ * fragment, no userinfo and no trailing slash, so that
+ * `new URL(origin).origin === origin`. A default `:443` is therefore written
+ * implicitly, because `URL` drops it from the origin it computes.
+ */
+export interface IClusterRelayV1 {
+    schemaVersion: 1;
+    origin: string;
+}
+/**
+ * Validates one cluster relay block and names every reason it is refused.
+ *
+ * A relay whose origin cannot be trusted verbatim must never reach a node's
+ * identity store: it is the transport authority the node's runtime session
+ * registers over.
+ */
+export declare const validateClusterRelayV1: (valueArg: unknown, pathArg?: string) => string[];
+/**
+ * The name the relay's certificate is issued for, and the A record Cloudly
+ * owns for it. Derived from the origin so every consumer derives it
+ * identically; an origin that names an address literal instead of a domain
+ * therefore has no issuable certificate.
+ */
+export declare const clusterRelayCertificateDomainName: (relayArg: IClusterRelayV1) => string;

package/dist_ts/data/cluster.js

@@ -1,3 +1,72 @@
 import * as plugins from '../plugins.js';
 import {} from '../data/docker.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2x1c3Rlci5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL2RhdGEvY2x1c3Rlci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGVBQWUsQ0FBQztBQUV6QyxPQUFPLEVBQTRCLE1BQU0sbUJBQW1CLENBQUMifQ==
+const maximumClusterRelayOriginLength = 2048;
+const isRecord = (valueArg) => (Boolean(valueArg)
+    && typeof valueArg === 'object'
+    && !Array.isArray(valueArg)
+    && (Object.getPrototypeOf(valueArg) === Object.prototype
+        || Object.getPrototypeOf(valueArg) === null));
+const hasExactKeys = (valueArg, keysArg) => {
+    const actualKeys = Object.keys(valueArg).sort();
+    const expectedKeys = [...keysArg].sort();
+    return actualKeys.length === expectedKeys.length
+        && actualKeys.every((keyArg, indexArg) => keyArg === expectedKeys[indexArg]);
+};
+const validateClusterRelayOrigin = (valueArg, pathArg) => {
+    if (typeof valueArg !== 'string'
+        || valueArg.length === 0
+        || valueArg.length > maximumClusterRelayOriginLength) {
+        return [`${pathArg} must be a string of 1 to ${maximumClusterRelayOriginLength} characters`];
+    }
+    let parsedOrigin;
+    try {
+        parsedOrigin = new URL(valueArg);
+    }
+    catch {
+        return [`${pathArg} must be a parsable URL`];
+    }
+    const errors = [];
+    if (parsedOrigin.protocol !== 'https:') {
+        errors.push(`${pathArg} must use the https scheme`);
+    }
+    if (parsedOrigin.username || parsedOrigin.password) {
+        errors.push(`${pathArg} must not carry userinfo`);
+    }
+    if (parsedOrigin.origin !== valueArg) {
+        errors.push(`${pathArg} must be the canonical origin ${parsedOrigin.origin}, `
+            + 'without a path, query, fragment, trailing slash or default port');
+    }
+    return errors;
+};
+/**
+ * Validates one cluster relay block and names every reason it is refused.
+ *
+ * A relay whose origin cannot be trusted verbatim must never reach a node's
+ * identity store: it is the transport authority the node's runtime session
+ * registers over.
+ */
+export const validateClusterRelayV1 = (valueArg, pathArg = 'cluster relay') => {
+    if (!isRecord(valueArg) || !hasExactKeys(valueArg, ['schemaVersion', 'origin'])) {
+        return [`${pathArg} must use its exact schema`];
+    }
+    const errors = [];
+    if (valueArg.schemaVersion !== 1) {
+        errors.push(`${pathArg} schemaVersion must be 1`);
+    }
+    errors.push(...validateClusterRelayOrigin(valueArg.origin, `${pathArg} origin`));
+    return errors;
+};
+/**
+ * The name the relay's certificate is issued for, and the A record Cloudly
+ * owns for it. Derived from the origin so every consumer derives it
+ * identically; an origin that names an address literal instead of a domain
+ * therefore has no issuable certificate.
+ */
+export const clusterRelayCertificateDomainName = (relayArg) => {
+    const errors = validateClusterRelayV1(relayArg);
+    if (errors.length > 0) {
+        throw new Error(errors[0]);
+    }
+    return new URL(relayArg.origin).hostname;
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2x1c3Rlci5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL2RhdGEvY2x1c3Rlci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGVBQWUsQ0FBQztBQUV6QyxPQUFPLEVBQTRCLE1BQU0sbUJBQW1CLENBQUM7QUE0RDdELE1BQU0sK0JBQStCLEdBQUcsSUFBSSxDQUFDO0FBRTdDLE1BQU0sUUFBUSxHQUFHLENBQUMsUUFBaUIsRUFBdUMsRUFBRSxDQUFDLENBQzNFLE9BQU8sQ0FBQyxRQUFRLENBQUM7T0FDZCxPQUFPLFFBQVEsS0FBSyxRQUFRO09BQzVCLENBQUMsS0FBSyxDQUFDLE9BQU8sQ0FBQyxRQUFRLENBQUM7T0FDeEIsQ0FBQyxNQUFNLENBQUMsY0FBYyxDQUFDLFFBQVEsQ0FBQyxLQUFLLE1BQU0sQ0FBQyxTQUFTO1dBQ25ELE1BQU0sQ0FBQyxjQUFjLENBQUMsUUFBUSxDQUFDLEtBQUssSUFBSSxDQUFDLENBQy9DLENBQUM7QUFFRixNQUFNLFlBQVksR0FBRyxDQUNuQixRQUFpQyxFQUNqQyxPQUEwQixFQUNqQixFQUFFO0lBQ1gsTUFBTSxVQUFVLEdBQUcsTUFBTSxDQUFDLElBQUksQ0FBQyxRQUFRLENBQUMsQ0FBQyxJQUFJLEVBQUUsQ0FBQztJQUNoRCxNQUFNLFlBQVksR0FBRyxDQUFDLEdBQUcsT0FBTyxDQUFDLENBQUMsSUFBSSxFQUFFLENBQUM7SUFDekMsT0FBTyxVQUFVLENBQUMsTUFBTSxLQUFLLFlBQVksQ0FBQyxNQUFNO1dBQzNDLFVBQVUsQ0FBQyxLQUFLLENBQUMsQ0FBQyxNQUFNLEVBQUUsUUFBUSxFQUFFLEVBQUUsQ0FBQyxNQUFNLEtBQUssWUFBWSxDQUFDLFFBQVEsQ0FBQyxDQUFDLENBQUM7QUFDakYsQ0FBQyxDQUFDO0FBRUYsTUFBTSwwQkFBMEIsR0FBRyxDQUFDLFFBQWlCLEVBQUUsT0FBZSxFQUFZLEVBQUU7SUFDbEYsSUFBSSxPQUFPLFFBQVEs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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/interfaces",
-  "version": "31.1.0",
+  "version": "31.2.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.",
   "exports": {

package/readme.md

@@ -523,7 +523,9 @@ Existing numeric configurations retain their exact meaning and digest.
 `requests.runtimesession` defines `registerPalletRuntimeSessionV1`,
 `applyRuntimeAssignmentV1`, `reportRuntimeAssignmentObservationV1`, and
 `getRuntimeRegistryCredentialV1`. Pallet initiates WSS through its configured
-Cloudly HTTPS origin. The receiver derives the physical peer, process instance
+Cloudly HTTPS origin, or, on a relayed cluster, through the relay origin its
+cluster publishes in [`ICluster.data.relay`](#cluster-relay-block) while Cloudly
+remains the credential authority. The receiver derives the physical peer, process instance
 and registration idempotency; callers cannot supply those authorities. A serialized
 `IRuntimeSessionBindingV1` provides content to compare with authenticated peer
 state and does not itself authenticate a connection. Registry credentials are
@@ -1054,7 +1056,8 @@ const service: data.IService = {
 
 Common data contracts include:
 
-- `ICluster` and `IClusterNode` for cluster membership and provisioning state.
+- `ICluster` and `IClusterNode` for cluster membership and provisioning state, including the
+  optional `ICluster.data.relay` block described below.
 - `IService`, `IDeployment`, `IImage`, `IRegistryTarget`, and `IExternalRegistry` for workload delivery.
 - Service port contracts including `IServiceTargetPort`, `IServiceDomainRoute`, and `IServicePublicPortMapping` for canonical backend targets, domain target references, and edge/Coretraffic TCP/UDP public exposure.
 - `IDomain`, `IDnsEntry`, and traffic contracts for routing and DNS management.
@@ -1080,6 +1083,36 @@ Common data contracts include:
 - `IUser`, JWT-only `IIdentityCredential`, full `IIdentity`, and token-related contracts for authentication context. `IIdentity` extends `IIdentityCredential` with server-issued user metadata.
 - `ICloudlyConfig`, `ICloudlySettings`, status, server, bare-metal, BaseOS, backup, and task execution interfaces for control-plane state.
 
+### Cluster Relay Block
+
+`ICluster.data.relay` is the optional `IClusterRelayV1 { schemaVersion: 1; origin: string }`
+that states how cluster-side components reach this cluster's relay. It is absent on a cluster
+whose nodes still target Cloudly directly, so its presence is what marks a cluster as relayed.
+
+`origin` is the exact value a Pallet node stores as its `relayOrigin` — the origin its runtime
+session registers over, as described in [Authenticated Runtime Sessions](#authenticated-runtime-sessions).
+It must be an `https:` origin with no path, query, fragment, userinfo or trailing slash, so that
+`new URL(origin).origin === origin`; an explicit port is allowed, and because `URL` drops a
+default port and lowercases the host, `https://relay.example:443` and `https://Relay.example`
+are not canonical origins. `validateClusterRelayV1(value, path?)` returns one named reason per
+violation and an empty array for a valid block.
+
+The relay's certificate subject is not a second field: every consumer derives it from the origin
+with `clusterRelayCertificateDomainName(relay)`, which returns the origin's hostname — the name
+Cloudly issues the certificate for and owns the A record for. An origin naming an address literal
+therefore has no issuable certificate.
+
+```typescript
+const relay: data.IClusterRelayV1 = {
+  schemaVersion: 1,
+  origin: 'https://relay.cluster-a.serve.zone:8443',
+};
+
+const reasons = data.validateClusterRelayV1(relay); // []
+const certificateDomainName = data.clusterRelayCertificateDomainName(relay);
+// 'relay.cluster-a.serve.zone'
+```
+
 Shared service port helpers are exported from `data` so Cloudly, App Store resolution, Coreflow, Coretraffic, Onebox, and dcrouter agree on the same normalization rules:
 
 ```typescript

package/ts/00_commitinfo_data.ts

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

package/ts/data/cluster.ts

@@ -37,5 +37,109 @@ export interface ICluster {
     };
 
     sshKeys: plugins.tsclass.network.ISshKey[];
+
+    /**
+     * How cluster-side components reach this cluster's relay. Absent on a
+     * cluster whose nodes still target Cloudly directly.
+     */
+    relay?: IClusterRelayV1;
   };
 }
+
+/**
+ * How cluster-side components reach this cluster's relay.
+ *
+ * `origin` is the exact value a Pallet node stores as its `relayOrigin`: an
+ * `https:` origin, an explicit port allowed, with no path, no query, no
+ * fragment, no userinfo and no trailing slash, so that
+ * `new URL(origin).origin === origin`. A default `:443` is therefore written
+ * implicitly, because `URL` drops it from the origin it computes.
+ */
+export interface IClusterRelayV1 {
+  schemaVersion: 1;
+  origin: string;
+}
+
+const maximumClusterRelayOriginLength = 2048;
+
+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[],
+): boolean => {
+  const actualKeys = Object.keys(valueArg).sort();
+  const expectedKeys = [...keysArg].sort();
+  return actualKeys.length === expectedKeys.length
+    && actualKeys.every((keyArg, indexArg) => keyArg === expectedKeys[indexArg]);
+};
+
+const validateClusterRelayOrigin = (valueArg: unknown, pathArg: string): string[] => {
+  if (typeof valueArg !== 'string'
+    || valueArg.length === 0
+    || valueArg.length > maximumClusterRelayOriginLength) {
+    return [`${pathArg} must be a string of 1 to ${maximumClusterRelayOriginLength} characters`];
+  }
+  let parsedOrigin: URL;
+  try {
+    parsedOrigin = new URL(valueArg);
+  } catch {
+    return [`${pathArg} must be a parsable URL`];
+  }
+  const errors: string[] = [];
+  if (parsedOrigin.protocol !== 'https:') {
+    errors.push(`${pathArg} must use the https scheme`);
+  }
+  if (parsedOrigin.username || parsedOrigin.password) {
+    errors.push(`${pathArg} must not carry userinfo`);
+  }
+  if (parsedOrigin.origin !== valueArg) {
+    errors.push(
+      `${pathArg} must be the canonical origin ${parsedOrigin.origin}, `
+        + 'without a path, query, fragment, trailing slash or default port',
+    );
+  }
+  return errors;
+};
+
+/**
+ * Validates one cluster relay block and names every reason it is refused.
+ *
+ * A relay whose origin cannot be trusted verbatim must never reach a node's
+ * identity store: it is the transport authority the node's runtime session
+ * registers over.
+ */
+export const validateClusterRelayV1 = (
+  valueArg: unknown,
+  pathArg = 'cluster relay',
+): string[] => {
+  if (!isRecord(valueArg) || !hasExactKeys(valueArg, ['schemaVersion', 'origin'])) {
+    return [`${pathArg} must use its exact schema`];
+  }
+  const errors: string[] = [];
+  if (valueArg.schemaVersion !== 1) {
+    errors.push(`${pathArg} schemaVersion must be 1`);
+  }
+  errors.push(...validateClusterRelayOrigin(valueArg.origin, `${pathArg} origin`));
+  return errors;
+};
+
+/**
+ * The name the relay's certificate is issued for, and the A record Cloudly
+ * owns for it. Derived from the origin so every consumer derives it
+ * identically; an origin that names an address literal instead of a domain
+ * therefore has no issuable certificate.
+ */
+export const clusterRelayCertificateDomainName = (relayArg: IClusterRelayV1): string => {
+  const errors = validateClusterRelayV1(relayArg);
+  if (errors.length > 0) {
+    throw new Error(errors[0]);
+  }
+  return new URL(relayArg.origin).hostname;
+};