@serve.zone/interfaces 31.2.0 → 31.4.0

package/changelog.md

@@ -1,5 +1,79 @@
 # Changelog
 
+## 2026-09-16 - 31.4.0
+
+### Features
+
+- Add the cluster ingress contracts, the first under the rule that a contract carries no version
+  suffix and no schema field: the protocol version is the installed package version.
+  `IClusterRouteTable { revision, issuedAt, routes, portRoutes }` is the whole table a cluster's
+  ingress serves, with `IClusterHttpRoute` (hostname, unicast destinations, the certificate that
+  terminates it, optional Basic authentication) and `IClusterPortRoute` (a TCP or UDP listen port
+  forwarded untouched). `revision` is the feed's only idempotency: a relay and an ingress apply a
+  greater revision and ignore anything else, so a repeated, replayed or crossed push settles the
+  same way. `validateClusterRouteTable` returns one named reason per violation, refuses a second
+  route for one hostname and a second port route for one transport and port, and never quotes
+  certificate material or a password in a reason — a reason travels into logs, and this table
+  carries the private key of every hostname the ingress serves.
+- Add the five methods the feed and its counters travel on: `pushClusterRouteTable` (Cloudly →
+  relay), `getClusterRouteTable` (relay → Cloudly), `getClusterIngressRouteTable` (ingress →
+  relay), `registerClusterIngress` and `getClusterTrafficStatistics` (both one body for two hops:
+  ingress → relay → Cloudly, and Cloudly → relay → ingress). An ingress announces itself through a
+  method rather than a connection tag, so what a relay knows about its ingress is what a server
+  owns. A `null` table means Cloudly has computed none yet — a fact, not an empty table.
+- Authorize the ingress where the authority is. The ingress shares the relay's node listener, so
+  anything reaching it could ask to register and a relay cannot tell an ingress from anything
+  else: `registerClusterIngress` carries the `bearer` Cloudly minted into the ingress workload's
+  assignment environment, the relay forwards it untouched, and Cloudly verifies it and derives the
+  cluster from the identity tag on the relay's own session. The bearer is sensitive ephemeral
+  input on every hop and is never quoted in a reason. Isolation on the shared listener is by
+  authorization, not routing: only the connection whose registration Cloudly accepted is the
+  ingress, and every other connection is refused by name.
+  `validateClusterIngressRegistration` checks shape only.
+- Add `IClusterTrafficStatistics`: one UTC day of one hostname's traffic on one node — requests,
+  bytes in and out, connections and the backend connect, handshake and request failures the proxy
+  can observe — paged exactly like CoreMail's mail statistics, down to the `{ statistics,
+  nextCursor? }` response and the `fromDayUtc`/`toDayUtc`/`cursor`/`limit` request, with `dayUtc`
+  checked against the real calendar through the now-shared UTC calendar-day rule (`2026-13-45` is
+  refused rather than stored; CoreMail's own day check consumes the same helper). Day buckets survive a restart, a
+  poll across midnight and a Cloudly outage, which a rate does not. HTTP status classes are
+  deliberately absent: the proxy exposes no status counters today, and a number the contract
+  cannot source would be a guess.
+- Carry the node's own uplink address on the network report it already sends:
+  `IReportRuntimeNetworkProtectionRequestV1` gains the optional `uplinkAddress`, validated by
+  `runtimeNodeUplinkAddress` as a unicast IPv4 literal that is neither loopback nor link-local.
+  A route to that node's published ports uses exactly this address, and only the node can prove
+  it. Absence stays absent, so a node that states none is told apart from one that states a value,
+  and nothing downstream defaults or infers one. Additive: `networkRecord` now admits declared
+  optional keys, and every existing caller passes none.
+
+## 2026-09-16 - 31.3.0
+
+### Features
+
+- Add the cluster relay enable, disable and registration contracts. `enableClusterRelayV1` and
+  `disableClusterRelayV1` take only an identity and a cluster id and answer with the published
+  `IClusterRelayV1` block or an explicit `relay: null`: Cloudly derives the origin from the
+  cluster and its own public hostname and refuses when no DNS zone it manages matches the derived
+  name, so no caller can name a relay origin. `registerClusterRelayV1` is what the relay sends
+  over its own socket after `registerCloudlyClientSessionV1`, carrying
+  `IClusterRelayRegistrationV1 { schemaVersion: 1; relay: { version; nodeId; listenAddress;
+  listenPort }; registrationSequence }` and answered with
+  `IClusterRelayRegistrationResponseV1 { accepted: true; origin: string | null }` — the origin
+  Cloudly published, so the relay can check the certificate it holds against the name its nodes
+  are given, and `null` while the cluster carries no relay block.
+  `validateClusterRelayRegistrationV1(value, pathArg?)` returns one named reason per violation in
+  the package's value-free validator shape, and checks shape only: `listenAddress` must be a
+  unicast IPv4 literal, because Cloudly publishes it verbatim as an A record, and a loopback or
+  link-local address is refused by its own name because a relay that bound one can never serve
+  its cluster; `nodeId` follows the same rule a node's own runtime session registers under;
+  `registrationSequence` is a non-negative safe integer, so a relay process's first registration
+  at `0` is a registration. Which cluster a relay speaks for, whether its node belongs to that
+  cluster, and which of two live peers is the relay all stay Cloudly's decisions, made from the
+  verified identity on the socket and its own records. Additive only: the dotted-quad rule the
+  private network upstream validator already applied moved into one shared internal predicate
+  with unchanged semantics, and nothing was removed or renamed.
+
 ## 2026-09-16 - 31.2.0
 
 ### Features

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@serve.zone/interfaces',
-    version: '31.2.0',
+    version: '31.4.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

@@ -48,6 +48,48 @@ export interface IClusterRelayV1 {
     schemaVersion: 1;
     origin: string;
 }
+/**
+ * What a cluster relay tells Cloudly about itself once its socket is authenticated.
+ *
+ * The relay sends this after `registerCloudlyClientSessionV1`, so the cluster it registers for
+ * is the one its verified machine identity names and is never a field here. `relay.nodeId` is
+ * the cluster node the relay process runs on, `listenAddress` and `listenPort` are the exact
+ * endpoint it bound for the Pallet nodes of its cluster, and `registrationSequence` counts up
+ * once per registration within one relay process, so Cloudly can tell a newer registration from
+ * a replayed older one while both peers are live.
+ */
+export interface IClusterRelayRegistrationV1 {
+    schemaVersion: 1;
+    relay: {
+        /** The relay build that is registering; a bounded label for operators and logs. */
+        version: string;
+        nodeId: string;
+        /**
+         * The address the relay bound, as an IPv4 literal.
+         *
+         * Cloudly publishes this value verbatim as the A record of the relay's certificate domain
+         * name, so the contract admits exactly what that record can carry: a hostname would need a
+         * `CNAME` and an IPv6 address an `AAAA` record, and neither is published today. Admitting
+         * either is an additive change once Cloudly publishes it.
+         */
+        listenAddress: string;
+        listenPort: number;
+    };
+    /** Monotonic within one relay process; it restarts at 0 when the process restarts. */
+    registrationSequence: number;
+}
+/**
+ * What Cloudly tells the relay back.
+ *
+ * `origin` is the origin Cloudly has published for this cluster, so a relay can check that the
+ * certificate it holds and the name its nodes are told to reach are the same one. It is `null`
+ * while the cluster carries no relay block, which a relay must treat as "not enabled yet"
+ * rather than as an origin it may invent.
+ */
+export interface IClusterRelayRegistrationResponseV1 {
+    accepted: true;
+    origin: string | null;
+}
 /**
  * Validates one cluster relay block and names every reason it is refused.
  *
@@ -56,6 +98,16 @@ export interface IClusterRelayV1 {
  * registers over.
  */
 export declare const validateClusterRelayV1: (valueArg: unknown, pathArg?: string) => string[];
+/**
+ * Validates one cluster relay registration and names every reason it is refused.
+ *
+ * Shape only, exactly like every other validator here: which cluster the relay speaks for comes
+ * from the verified identity on its socket, whether `relay.nodeId` is a node of that cluster is
+ * Cloudly's to decide against its own records, and whether this registration supersedes a live
+ * one is Cloudly's comparison of `registrationSequence` between peers. A registration that
+ * passes here has claimed nothing.
+ */
+export declare const validateClusterRelayRegistrationV1: (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

package/dist_ts/data/cluster.js

@@ -1,6 +1,8 @@
 import * as plugins from '../plugins.js';
 import {} from '../data/docker.js';
+import { isPlausibleUnicastIpv4 } from '../private/ipv4.js';
 const maximumClusterRelayOriginLength = 2048;
+const maximumClusterRelayVersionLength = 64;
 const isRecord = (valueArg) => (Boolean(valueArg)
     && typeof valueArg === 'object'
     && !Array.isArray(valueArg)
@@ -56,6 +58,71 @@ export const validateClusterRelayV1 = (valueArg, pathArg = 'cluster relay') => {
     errors.push(...validateClusterRelayOrigin(valueArg.origin, `${pathArg} origin`));
     return errors;
 };
+const validateClusterRelayVersion = (valueArg, pathArg) => (typeof valueArg === 'string'
+    && valueArg.length <= maximumClusterRelayVersionLength
+    && /^[0-9A-Za-z][0-9A-Za-z.+_-]*$/.test(valueArg)
+    ? []
+    : [`${pathArg} must be 1 to ${maximumClusterRelayVersionLength} characters of letters, `
+            + 'digits, dot, plus, underscore or hyphen, starting with a letter or digit']);
+/** The same node id rule a node's own runtime session registers under. */
+const validateClusterRelayNodeId = (valueArg, pathArg) => (typeof valueArg === 'string' && /^[A-Za-z0-9_-]{1,128}$/.test(valueArg)
+    ? []
+    : [`${pathArg} must be 1 to 128 characters of letters, digits, underscore or hyphen`]);
+const validateClusterRelayListenAddress = (valueArg, pathArg) => {
+    if (!isPlausibleUnicastIpv4(valueArg)) {
+        return [`${pathArg} must be a unicast IPv4 literal`];
+    }
+    // A relay that bound one of these can never serve the nodes of its cluster, and publishing
+    // it would put an unreachable address into every node's relay origin.
+    if (valueArg.startsWith('127.')) {
+        return [`${pathArg} must not be a loopback address`];
+    }
+    if (valueArg.startsWith('169.254.')) {
+        return [`${pathArg} must not be a link-local address`];
+    }
+    return [];
+};
+const validateClusterRelayListenPort = (valueArg, pathArg) => (typeof valueArg === 'number' && Number.isSafeInteger(valueArg) && valueArg >= 1 && valueArg <= 65535
+    ? []
+    : [`${pathArg} must be an integer from 1 to 65535`]);
+const validateClusterRelayEndpoint = (valueArg, pathArg) => {
+    if (!isRecord(valueArg)
+        || !hasExactKeys(valueArg, ['version', 'nodeId', 'listenAddress', 'listenPort'])) {
+        return [`${pathArg} must use its exact schema`];
+    }
+    return [
+        ...validateClusterRelayVersion(valueArg.version, `${pathArg} version`),
+        ...validateClusterRelayNodeId(valueArg.nodeId, `${pathArg} nodeId`),
+        ...validateClusterRelayListenAddress(valueArg.listenAddress, `${pathArg} listenAddress`),
+        ...validateClusterRelayListenPort(valueArg.listenPort, `${pathArg} listenPort`),
+    ];
+};
+/**
+ * Validates one cluster relay registration and names every reason it is refused.
+ *
+ * Shape only, exactly like every other validator here: which cluster the relay speaks for comes
+ * from the verified identity on its socket, whether `relay.nodeId` is a node of that cluster is
+ * Cloudly's to decide against its own records, and whether this registration supersedes a live
+ * one is Cloudly's comparison of `registrationSequence` between peers. A registration that
+ * passes here has claimed nothing.
+ */
+export const validateClusterRelayRegistrationV1 = (valueArg, pathArg = 'cluster relay registration') => {
+    if (!isRecord(valueArg)
+        || !hasExactKeys(valueArg, ['schemaVersion', 'relay', 'registrationSequence'])) {
+        return [`${pathArg} must use its exact schema`];
+    }
+    const errors = [];
+    if (valueArg.schemaVersion !== 1) {
+        errors.push(`${pathArg} schemaVersion must be 1`);
+    }
+    errors.push(...validateClusterRelayEndpoint(valueArg.relay, `${pathArg} relay`));
+    if (typeof valueArg.registrationSequence !== 'number'
+        || !Number.isSafeInteger(valueArg.registrationSequence)
+        || valueArg.registrationSequence < 0) {
+        errors.push(`${pathArg} registrationSequence must be a non-negative safe integer`);
+    }
+    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
@@ -69,4 +136,4 @@ export const clusterRelayCertificateDomainName = (relayArg) => {
     }
     return new URL(relayArg.origin).hostname;
 };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2x1c3Rlci5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL2RhdGEvY2x1c3Rlci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGVBQWUsQ0FBQztBQUV6QyxPQUFPLEVBQTRCLE1BQU0sbUJBQW1CLENBQUM7QUE0RDdELE1BQU0sK0JBQStCLEdBQUcsSUFBSSxDQUFDO0FBRTdDLE1BQU0sUUFBUSxHQUFHLENBQUMsUUFBaUIsRUFBdUMsRUFBRSxDQUFDLENBQzNFLE9BQU8sQ0FBQyxRQUFRLENBQUM7T0FDZCxPQUFPLFFBQVEsS0FBSyxRQUFRO09BQzVCLENBQUMsS0FBSyxDQUFDLE9BQU8sQ0FBQyxRQUFRLENBQUM7T0FDeEIsQ0FBQyxNQUFNLENBQUMsY0FBYyxDQUFDLFFBQVEsQ0FBQyxLQUFLLE1BQU0sQ0FBQyxTQUFTO1dBQ25ELE1BQU0sQ0FBQyxjQUFjLENBQUMsUUFBUSxDQUFDLEtBQUssSUFBSSxDQUFDLENBQy9DLENBQUM7QUFFRixNQUFNLFlBQVksR0FBRyxDQUNuQixRQUFpQyxFQUNqQyxPQUEwQixFQUNqQixFQUFFO0lBQ1gsTUFBTSxVQUFVLEdBQUcsTUFBTSxDQUFDLElBQUksQ0FBQyxRQUFRLENBQUMsQ0FBQyxJQUFJLEVBQUUsQ0FBQztJQUNoRCxNQUFNLFlBQVksR0FBRyxDQUFDLEdBQUcsT0FBTyxDQUFDLENBQUMsSUFBSSxFQUFFLENBQUM7SUFDekMsT0FBTyxVQUFVLENBQUMsTUFBTSxLQUFLLFlBQVksQ0FBQyxNQUFNO1dBQzNDLFVBQVUsQ0FBQyxLQUFLLENBQUMsQ0FBQyxNQUFNLEVBQUUsUUFBUSxFQUFFLEVBQUUsQ0FBQyxNQUFNLEtBQUssWUFBWSxDQUFDLFFBQVEsQ0FBQyxDQUFDLENBQUM7QUFDakYsQ0FBQyxDQUFDO0FBRUYsTUFBTSwwQkFBMEIsR0FBRyxDQUFDLFFBQWlCLEVBQUUsT0FBZSxFQUFZLEVBQUU7SUFDbEYsSUFBSSxPQUFPLFFBQVEs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
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2x1c3Rlci5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL2RhdGEvY2x1c3Rlci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGVBQWUsQ0FBQztBQUV6QyxPQUFPLEVBQTRCLE1BQU0sbUJBQW1CLENBQUM7QUFFN0QsT0FBTyxFQUFFLHNCQUFzQixFQUFFLE1BQU0sb0JBQW9CLENBQUM7QUF1RzVELE1BQU0sK0JBQStCLEdBQUcsSUFBSSxDQUFDO0FBQzdDLE1BQU0sZ0NBQWdDLEdBQUcsRUFBRSxDQUFDO0FBRTVDLE1BQU0sUUFBUSxHQUFHLENBQUMsUUFBaUIsRUFBdUMsRUFBRSxDQUFDLENBQzNFLE9BQU8sQ0FBQyxRQUFRLENBQUM7T0FDZCxPQUFPLFFBQVEsS0FBSyxRQUFRO09BQzVCLENBQUMsS0FBSyxDQUFDLE9BQU8sQ0FBQyxRQUFRLENBQUM7T0FDeEIsQ0FBQyxNQUFNLENBQUMsY0FBYyxDQUFDLFFBQVEsQ0FBQyxLQUFLLE1BQU0sQ0FBQyxTQUFTO1dBQ25ELE1BQU0sQ0FBQyxjQUFjLENBQUMsUUFBUSxDQUFDLEtBQUssSUFBSSxDQUFDLENBQy9DLENBQUM7QUFFRixNQUFNLFlBQVksR0FBRyxDQUNuQixRQUFpQyxFQUNqQyxPQUEwQixFQUNqQixFQUFFO0lBQ1gsTUFBTSxVQUFVLEdBQUcsTUFBTSxDQUFDLElBQUksQ0FBQyxRQUFRLENBQUMsQ0FBQyxJQUFJLEVBQUUsQ0FBQztJQUNoRCxNQUFNLFlBQVksR0FBRyxDQUFDLEdBQUcsT0FBTyxDQUFDLENBQUMsSUFBSSxFQUFFLENBQUM7SUFDekMsT0FBTyxVQUFVLENBQUMsTUFBTSxLQUFLLFlBQVksQ0FBQyxNQUFNO1dBQzNDLFVBQVUsQ0FBQyxLQUFLLENBQUMsQ0FBQyxNQUFNLEVBQUUsUUFBUSxFQUFFLEVBQUUsQ0FBQyxNQUFNLEtBQUssWUFBWSxDQUFDLFFBQVEsQ0FBQyxDQUFDLENBQUM7QUFDakYsQ0FBQyxD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

package/dist_ts/data/clusteringress.d.ts

@@ -0,0 +1,137 @@
+/**
+ * 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 declare const clusterIngressLimits: Readonly<{
+    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;
+}
+/**
+ * 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 declare const isClusterIngressHostName: (valueArg: unknown) => valueArg is string;
+/**
+ * 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 declare const validateClusterRouteTable: (valueArg: unknown, pathArg?: string) => string[];
+/** Validates one day bucket of ingress counters. */
+export declare const validateClusterTrafficStatistics: (valueArg: unknown, pathArg?: string) => string[];
+/**
+ * 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 declare const validateClusterTrafficStatisticsPage: (valueArg: unknown, pathArg?: string) => string[];
+/**
+ * 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 declare const validateClusterIngressRegistration: (valueArg: unknown, pathArg?: string) => string[];