@serve.zone/interfaces 32.28.0 → 32.30.0

package/dist_ts/requests/network.d.ts

@@ -3,7 +3,7 @@ import type { IIdentity, IIdentityCredential } from '../data/user.js';
 import type { IRuntimeNetworkAddressPlan, TRuntimeNetworkAddressPlanWritableData } from '../data/networkaddressplan.js';
 import type { IRuntimeNetworkNodeReadiness, IRuntimeRouterIncarnation } from '../data/networknode.js';
 import type { IPrivateNetwork, IServicePrivateNetworks, ISetServicePrivateNetworks, TPrivateNetworkMutation } from '../data/privatenetwork.js';
-import type { IServicePublishedPorts, ISetServicePublishedPorts } from '../data/networkprojection.js';
+import type { IServiceNetworkEgress, IServicePublishedPorts, ISetServiceNetworkEgress, ISetServicePublishedPorts } from '../data/networkprojection.js';
 /** Current organization picker data. Entries are never cached authorization grants. */
 export interface IReq_Cloudly_ListOwnedOrganizations extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Cloudly_ListOwnedOrganizations> {
     method: 'listOwnedOrganizations';
@@ -97,7 +97,7 @@ export interface IReq_Cloudly_SetServicePrivateNetworks extends plugins.typedreq
         replayed: boolean;
     };
 }
-/** null means the service has never had an authorized published-port policy. */
+/** null means the service has never had a policy document, neither published ports nor egress. */
 export interface IReq_Cloudly_GetServicePublishedPorts extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Cloudly_GetServicePublishedPorts> {
     method: 'getServicePublishedPorts';
     request: {
@@ -109,6 +109,17 @@ export interface IReq_Cloudly_GetServicePublishedPorts extends plugins.typedrequ
         publishedPorts: IServicePublishedPorts | null;
     };
 }
+/**
+ * Writes the published-port half of one service's policy document, carrying its egress forward.
+ *
+ * One document per service holds its published ports and its egress under one `revision`. The
+ * first accepted write of either (`expectedRevision: null`) creates it: `setServicePublishedPorts`
+ * with egress `publicEgress: false` and `platformEndpointIds: []`, `setServiceNetworkEgress` with
+ * no published ports. From then on both reads return it, never null. It is an explicit policy: an
+ * attached spec stating `publicEgress: false` and `platformEndpointIds: []` matches it and reaches
+ * no public address and no platform endpoint; `network-policy-missing` means the service has no
+ * document at all.
+ */
 export interface IReq_Cloudly_SetServicePublishedPorts extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Cloudly_SetServicePublishedPorts> {
     method: 'setServicePublishedPorts';
     request: {
@@ -125,6 +136,53 @@ export interface IReq_Cloudly_SetServicePublishedPorts extends plugins.typedrequ
         replayed: boolean;
     };
 }
+/**
+ * The egress half of one service's policy document; null means the service has never had a policy
+ * document. Only a verified administrator reads it: platform endpoints are platform authority.
+ */
+export interface IReq_Admin_Cloudly_GetServiceNetworkEgress extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Admin_Cloudly_GetServiceNetworkEgress> {
+    method: 'getServiceNetworkEgress';
+    request: {
+        identity: IIdentityCredential;
+        organizationId: string;
+        serviceId: string;
+    };
+    response: {
+        networkEgress: IServiceNetworkEgress | null;
+    };
+}
+/**
+ * Writes the egress half of one service's policy document, carrying its published ports forward.
+ *
+ * Only a verified administrator writes it, as only an administrator writes the runtime spec whose
+ * attached network must state the same values. `expectedRevision` is the revision of the one
+ * document shared with the published ports; any other stored revision refuses the write, and an id
+ * that names no current platform endpoint refuses it. A retry of the exact body under the same
+ * `mutationId` answers the stored document with `replayed: true`.
+ *
+ * One document per service holds its published ports and its egress under one `revision`. The
+ * first accepted write of either (`expectedRevision: null`) creates it: `setServicePublishedPorts`
+ * with egress `publicEgress: false` and `platformEndpointIds: []`, `setServiceNetworkEgress` with
+ * no published ports. From then on both reads return it, never null. It is an explicit policy: an
+ * attached spec stating `publicEgress: false` and `platformEndpointIds: []` matches it and reaches
+ * no public address and no platform endpoint; `network-policy-missing` means the service has no
+ * document at all.
+ */
+export interface IReq_Admin_Cloudly_SetServiceNetworkEgress extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Admin_Cloudly_SetServiceNetworkEgress> {
+    method: 'setServiceNetworkEgress';
+    request: {
+        identity: IIdentityCredential;
+        mutation: ISetServiceNetworkEgress;
+    };
+    /**
+     * The accepted document including its `revision`; historical on replay. Acceptance is neither an
+     * admitted workload nor applied packet state.
+     */
+    response: {
+        networkEgress: IServiceNetworkEgress;
+        replayed: boolean;
+    };
+}
 export interface IRequest_Any_Cloudly_GetNetworkNodes {
     method: 'getNetworkNodes';
     request: {};
@@ -139,7 +197,8 @@ export interface IRequest_Any_Cloudly_GetNetworkNodes {
  * validates the plan with `snapshotRuntimeNetworkAddressPlan`, decides the change with
  * `admitRuntimeNetworkAddressPlanChange`, refuses the change while a resolver or platform endpoint
  * it removes or changes is still referenced, and answers with the stored plan: at its new revision,
- * or unchanged.
+ * or unchanged. A list stated out of its canonical order (see `IRuntimeNetworkAddressPlan`) is
+ * refused `plan-unsorted`, naming the list as the refusal's reference; the plan is never reordered.
  */
 export interface IReq_Any_Cloudly_SetRuntimeNetworkAddressPlan extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_SetRuntimeNetworkAddressPlan> {
     method: 'setRuntimeNetworkAddressPlan';

package/dist_ts/requests/settings.d.ts

@@ -1,6 +1,7 @@
 import * as plugins from '../plugins.js';
-import type { ICloudlySettings } from '../data/settings.js';
-import type { IIdentity } from '../data/user.js';
+import type { IActiveSecretRecipientMetadata } from '../data/secret.js';
+import type { ICloudlySettings, IExternalGatewayEnrollmentState } from '../data/settings.js';
+import type { IIdentity, IIdentityCredential } from '../data/user.js';
 export interface IRequest_GetSettings extends plugins.typedrequestInterfaces.ITypedRequest {
     method: 'getSettings';
     request: {
@@ -54,3 +55,56 @@ export interface IRequest_GetSetting extends plugins.typedrequestInterfaces.ITyp
         value: ICloudlySettings[keyof ICloudlySettings] | undefined;
     };
 }
+/** A dcrouter admin bootstrap token, sealed to Cloudly's active secret ingress recipient. */
+export interface IExternalGatewayBootstrapTokenInput {
+    mode: 'sealed';
+    /** Sealed under `data.createGatewayBootstrapEnvelopeContext` for the request's expected target. */
+    envelope: plugins.smartcrypto.IX25519EnvelopeV1;
+}
+/**
+ * Enrolls Cloudly as its dcrouter gateway client with a dcrouter admin token an administrator
+ * hands in once.
+ *
+ * Cloudly opens the token, checks the target the request names against its own settings, asks
+ * dcrouter whether the token is an admin token, and provisions, finalizes and stores its own
+ * least-privilege gateway-client credential with it — under the policy its settings and the runtime
+ * network address plan state now. The admin token is used for this one call and never stored; the
+ * administrator revokes it at dcrouter afterwards. A refusal leaves the credential Cloudly already
+ * holds unchanged and is answered with one of `data.externalGatewayBootstrapRefusals`.
+ *
+ * This is the one way a gateway credential enters Cloudly, for a first enrollment and for the
+ * re-bootstrap a changed address plan or gateway setting asks for (`admin-bootstrap-required`).
+ */
+export interface IReq_Any_Cloudly_BootstrapExternalGatewayCredential extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_BootstrapExternalGatewayCredential> {
+    method: 'bootstrapExternalGatewayCredential';
+    request: {
+        identity: IIdentityCredential;
+        /** The `dcrouterGatewayUrl` the administrator read from Cloudly's settings. */
+        expectedGatewayUrl: string;
+        /** The `dcrouterGatewayClientId` the administrator read from Cloudly's settings. */
+        expectedGatewayClientId: string;
+        bootstrapToken: IExternalGatewayBootstrapTokenInput;
+    };
+    response: {
+        /** The enrollment after the bootstrap: `ready` when the new credential is Cloudly's runtime authority. */
+        state: IExternalGatewayEnrollmentState;
+    };
+}
+/** Cloudly's gateway-client enrollment state, for an administrator; it never carries a credential. */
+export interface IReq_Any_Cloudly_GetExternalGatewayEnrollmentState extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_GetExternalGatewayEnrollmentState> {
+    method: 'getExternalGatewayEnrollmentState';
+    request: {
+        identity: IIdentityCredential;
+    };
+    response: {
+        state: IExternalGatewayEnrollmentState;
+    };
+}
+/**
+ * Checks a bootstrap request against its schema and the active ingress recipient, without opening
+ * the envelope: the recipient, the context digest of the named target and the ciphertext bound of
+ * `data.externalGatewayBootstrapContract.maximumTokenBytes`. Every problem is named.
+ */
+export declare const validateBootstrapExternalGatewayCredentialRequest: (requestArg: unknown, activeIngressRecipientArg: IActiveSecretRecipientMetadata) => Promise<string[]>;
+/** Checks an enrollment state read; every problem is named. */
+export declare const validateGetExternalGatewayEnrollmentStateRequest: (requestArg: unknown) => string[];

package/dist_ts/requests/settings.js

@@ -1,2 +1,92 @@
 import * as plugins from '../plugins.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2V0dGluZ3MuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9yZXF1ZXN0cy9zZXR0aW5ncy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGVBQWUsQ0FBQyJ9
+import * as secretData from '../data/secret.js';
+import * as settingsData from '../data/settings.js';
+import { readDataProperties, hasExactKeys } from '../private/dataproperties.js';
+const hasJwtIdentity = (valueArg) => {
+    const identity = readDataProperties(valueArg);
+    return identity !== null && typeof identity.jwt === 'string' && identity.jwt.length > 0;
+};
+/** Structural check of the target a bootstrap request names; empty when both are well formed. */
+const validateExpectedGatewayTarget = (urlArg, clientIdArg) => {
+    const errors = [];
+    let url;
+    if (typeof urlArg === 'string'
+        && urlArg.length > 0
+        && urlArg.length <= settingsData.externalGatewayBootstrapContract.maximumGatewayUrlLength) {
+        try {
+            url = new URL(urlArg);
+        }
+        catch {
+            url = undefined;
+        }
+    }
+    if (!url
+        || url.protocol !== 'https:'
+        || url.username !== ''
+        || url.password !== ''
+        || url.search !== ''
+        || url.hash !== '') {
+        errors.push('bootstrap expectedGatewayUrl must be an HTTPS URL without credentials, query or fragment');
+    }
+    if (typeof clientIdArg !== 'string'
+        || clientIdArg.length === 0
+        || clientIdArg.length > settingsData.externalGatewayBootstrapContract.maximumGatewayClientIdLength
+        || !/^[\x21-\x7e]+$/.test(clientIdArg)) {
+        errors.push('bootstrap expectedGatewayClientId must be a bounded identifier without whitespace');
+    }
+    return errors;
+};
+/**
+ * Checks a bootstrap request against its schema and the active ingress recipient, without opening
+ * the envelope: the recipient, the context digest of the named target and the ciphertext bound of
+ * `data.externalGatewayBootstrapContract.maximumTokenBytes`. Every problem is named.
+ */
+export const validateBootstrapExternalGatewayCredentialRequest = async (requestArg, activeIngressRecipientArg) => {
+    const request = readDataProperties(requestArg);
+    if (request === null)
+        return ['bootstrap request must be a plain record'];
+    const errors = [];
+    if (!hasExactKeys(request, ['identity', 'expectedGatewayUrl', 'expectedGatewayClientId', 'bootstrapToken'])) {
+        errors.push('bootstrap request contains fields outside its schema');
+    }
+    if (!hasJwtIdentity(request.identity)) {
+        errors.push('bootstrap identity must be a JWT credential');
+    }
+    const targetErrors = validateExpectedGatewayTarget(request.expectedGatewayUrl, request.expectedGatewayClientId);
+    errors.push(...targetErrors);
+    const tokenInput = readDataProperties(request.bootstrapToken);
+    if (tokenInput === null || tokenInput.mode !== 'sealed') {
+        errors.push('bootstrap token must be a sealed input');
+        return errors;
+    }
+    const expectedContext = targetErrors.length === 0
+        ? secretData.createGatewayBootstrapEnvelopeContext({
+            gatewayUrl: request.expectedGatewayUrl,
+            gatewayClientId: request.expectedGatewayClientId,
+        })
+        : new Uint8Array();
+    errors.push(...await secretData.validateSecretValueInputForRecipient(tokenInput, activeIngressRecipientArg, expectedContext));
+    const envelope = readDataProperties(tokenInput.envelope);
+    if (envelope !== null
+        && typeof envelope.ciphertext === 'string'
+        && envelope.ciphertext.length
+            > Math.ceil(settingsData.externalGatewayBootstrapContract.maximumTokenBytes * 4 / 3)) {
+        errors.push(`bootstrap token must not exceed ${settingsData.externalGatewayBootstrapContract.maximumTokenBytes} bytes`);
+    }
+    return errors;
+};
+/** Checks an enrollment state read; every problem is named. */
+export const validateGetExternalGatewayEnrollmentStateRequest = (requestArg) => {
+    const request = readDataProperties(requestArg);
+    if (request === null)
+        return ['enrollment state request must be a plain record'];
+    const errors = [];
+    if (!hasExactKeys(request, ['identity'])) {
+        errors.push('enrollment state request contains fields outside its schema');
+    }
+    if (!hasJwtIdentity(request.identity)) {
+        errors.push('enrollment state identity must be a JWT credential');
+    }
+    return errors;
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2V0dGluZ3MuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9yZXF1ZXN0cy9zZXR0aW5ncy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGVBQWUsQ0FBQztBQUN6QyxPQUFPLEtBQUssVUFBVSxNQUFNLG1CQUFtQixDQUFDO0FBQ2hELE9BQU8sS0FBSyxZQUFZLE1BQU0scUJBQXFCLENBQUM7QUFJcEQsT0FBTyxFQUFFLGtCQUFrQixFQUFFLFlBQVksRUFBRSxNQUFNLDhCQUE4QixDQUFDO0FBeUhoRixNQUFNLGNBQWMsR0FBRyxDQUFDLFFBQWlCLEVBQVcsRUFBRTtJQUNwRCxNQUFNLFFBQVEsR0FBRyxrQkFBa0IsQ0FBQyxRQUFRLENBQUMsQ0FBQztJQUM5QyxPQUFPLFFBQVEsS0FBSyxJQUFJLElBQUksT0FBTyxRQUFRLENBQUMsR0FBRyxLQUFLLFFBQVEsSUFBSSxRQUFRLENBQUMsR0FBRyxDQUFDLE1BQU0sR0FBRyxDQUFDLENBQUM7QUFDMUYsQ0FBQyxDQUFDO0FBRUYsaUdBQWlHO0FBQ2pHLE1BQU0sNkJBQTZCLEdBQUcsQ0FBQyxNQUFlLEVBQUUsV0FBb0IsRUFBWSxFQUFFO0lBQ3hGLE1BQU0sTUFBTSxHQUFhLEVBQUUsQ0FBQztJQUM1QixJQUFJLEdBQW9CLENBQUM7SUFDekIsSUFBSSxPQUFPLE1BQU0sS0FBSyxRQUFRO1dBQ3pCLE1BQU0sQ0FBQyxNQUFNLEdBQUcsQ0FBQztXQUNqQixNQUFNLENBQUMsTUFBTSxJQUFJLFlBQVksQ0FBQyxnQ0FBZ0MsQ0FBQyx1QkFBdUIsRUFBRSxDQUFDO1FBQzVGLElBQUksQ0FBQztZQUNILEdBQUcsR0FBRyxJQUFJLEdBQUcsQ0FBQyxNQUFNLENBQUMsQ0FBQztRQUN4QixDQUFDO1FBQUMsTUFBTSxDQUFDO1lBQ1AsR0FBRyxHQUFHLFNBQVMsQ0FBQztRQUNsQixDQUFDO0lBQ0gsQ0FBQztJQUNELElBQUksQ0FBQyxHQUFHO1dBQ0gs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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/interfaces",
-  "version": "32.28.0",
+  "version": "32.30.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.",
   "exports": {
@@ -29,8 +29,8 @@
   "devDependencies": {
     "@git.zone/tsbuild": "^5.0.0",
     "@git.zone/tsdoc": "^2.2.2",
-    "@git.zone/tsrun": "^3.0.0",
-    "@git.zone/tstest": "6.3.0",
+    "@git.zone/tsrun": "^3.0.1",
+    "@git.zone/tstest": "6.3.2",
     "@types/node": "26.6.2"
   },
   "files": [

package/readme.md

@@ -482,7 +482,7 @@ canonical bytes and digest; a present member is never an empty list, so
 Operators author that authorization through `getServicePublishedPorts` and
 `setServicePublishedPorts`, modelled on the private-network membership pair.
 `IServicePublishedPorts` returns the current authorized list with its policy
-`revision`, or null when a service never had one. `ISetServicePublishedPorts`
+`revision`, or null when a service never had a policy document. `ISetServicePublishedPorts`
 returns the accepted `IServicePublishedPorts` document with its new
 `revision` and a `replayed` flag, and carries `expectedRevision` (null for the first document), a retained
 `mutationId` for replay, and `IRuntimeNetworkPublishedPortRequest` entries of
@@ -493,6 +493,39 @@ policy meaning the service publishes nothing. Callers never supply an
 from the accepted policy revision and digest, and node-level host-port placement
 stays Cloudly's decision.
 
+Every endpoint's `publicEgress` and `platformEndpointIds` come from the same
+service policy document. A verified administrator authors them through
+`getServiceNetworkEgress` and `setServiceNetworkEgress`
+(`requests.network.IReq_Admin_Cloudly_GetServiceNetworkEgress` /
+`IReq_Admin_Cloudly_SetServiceNetworkEgress`): platform endpoints are platform
+authority, and only an administrator writes the runtime spec whose attached
+network has to state the same values. `IServiceNetworkEgress` returns
+`publicEgress` and the selected `platformEndpointIds` (sorted, unique, at most
+`runtimeNetworkAuthorityContract.maximumPlatformEndpoints`) with the document's
+`revision`, or null when a service never had a policy document.
+`ISetServiceNetworkEgress` carries `expectedRevision` (null for the first
+document), a retained `mutationId` for replay and the exact desired values, and
+returns the accepted `IServiceNetworkEgress` with a `replayed` flag; Cloudly
+carries the published ports forward unchanged, and refuses an id that names no
+current platform endpoint. Published ports and egress are two halves of one
+document with one `revision`, so `expectedRevision` of either request is the
+revision the caller read from either answer, and an accepted write of either
+advances it.
+
+One document per service holds its published ports and its egress under one `revision`. The
+first accepted write of either (`expectedRevision: null`) creates it: `setServicePublishedPorts`
+with egress `publicEgress: false` and `platformEndpointIds: []`, `setServiceNetworkEgress` with
+no published ports. From then on both reads return it, never null. It is an explicit policy: an
+attached spec stating `publicEgress: false` and `platformEndpointIds: []` matches it and reaches
+no public address and no platform endpoint; `network-policy-missing` means the service has no
+document at all.
+
+`snapshotServiceNetworkEgress` and `snapshotSetServiceNetworkEgress`
+check the shapes. An attached runtime spec is admitted only while it states the
+document's values (`network-policy-mismatch`), and nothing else grants a
+workload egress: a Corestore endpoint on the node's own host is delivered
+locally, but only to a workload that selects it.
+
 `getRuntimeNetworkProjectionPacketGrants` derives directed member connectivity
 and explicit local public/platform egress independently of DNS readiness.
 `composeRuntimeNetworkProjectionDnsViews` builds one union view per local
@@ -829,6 +862,27 @@ because the private-range rule already keeps it at /8 or longer.
 `data.runtimeNetworkVpnControlPrefix(value)` is that reader on its own, exported because a
 cluster's VPN network repeats the prefix its hub binds and has to read it exactly as the plan does.
 
+Every list of a plan is stated in one canonical order, and a plan is never reordered for its
+writer: `prefixes` strictly ascending by the prefix text, and `pools`, `resolvers` and
+`platformEndpoints` strictly ascending by `id`. Both compare as strings, so the order is
+lexicographic, not numeric — `100.64.0.0/10` comes before `20.0.0.0/8`, and `resolver-10` before
+`resolver-9` — and a value stated twice breaks it as well. A list out of order is the one plan
+refusal the contract names: `snapshotRuntimeNetworkAddressPlan` (and
+`admitRuntimeNetworkAddressPlanChange` through it) throws
+`data.RuntimeNetworkAddressPlanStructureError`, whose `violation` is
+`{ field: 'prefixes' | 'pools' | 'resolvers' | 'platformEndpoints', rule: 'order' }` and whose
+message quotes nothing from the plan. Every other refusal stays the contract's generic rejection.
+
+```typescript
+try {
+  data.snapshotRuntimeNetworkAddressPlan(plan);
+} catch (error) {
+  if (error instanceof data.RuntimeNetworkAddressPlanStructureError) {
+    error.violation; // { field: 'prefixes', rule: 'order' }
+  }
+}
+```
+
 `data.IRuntimeNetworkVpnHub { clusterId, address, quicPort }` is one cluster's hub as its relay
 bound it. `runtimeNetworkVpnHubEndpoints(hub)` is the one derivation of what it contributes:
 `<clusterId>:quic` on `udp`, one endpoint per row of
@@ -868,7 +922,9 @@ outlive a plan revision, so it answers:
   reference check as removing it.
 
 `TRuntimeNetworkAddressPlanRefusal` adds `plan-resolver-referenced` and `plan-endpoint-referenced`,
-which only Cloudly can decide against live references, so every plan refusal has one type.
+which only Cloudly can decide against live references, and `plan-unsorted`, which Cloudly answers
+for a `RuntimeNetworkAddressPlanStructureError` with the list as its reference, so every plan
+refusal has one type.
 `requests.network` carries `setRuntimeNetworkAddressPlan { identity, expectedRevision, plan }`
 (`expectedRevision: null` when no plan exists yet) and `getRuntimeNetworkAddressPlan`, which answers
 `null` until the first plan is set.
@@ -1431,19 +1487,39 @@ evidence has not arrived). `refused` carries a `TServiceRuntimeRefusal`:
 `network-workload-pool-missing`, `network-workload-pool-exhausted`, `volume-driver-unsupported`,
 `volume-options-unsupported`, `volume-shared-unsupported`, `volume-placement-unsupported`,
 `volume-initialization-unknown`, `volume-ownership-unknown`, `objectstorage-endpoint-missing`,
-`objectstorage-binding-invalid` or `objectstorage-environment-conflict`. The first four volume
+`objectstorage-binding-invalid`, `objectstorage-environment-conflict`,
+`objectstorage-endpoint-unselected`, `database-endpoint-missing` or `database-endpoint-unselected`.
+The first four volume
 refusals name what a local storage claim cannot express: a volume driver other than a node-local
 directory, driver or mount options, one volume mounted by more than one replica or service, and a
 placement that does not pin each volume to one node. The other two name what Cloudly will not guess,
-see [Service Volume Initialization](#service-volume-initialization). The three object-storage
-refusals name why a binding's environment cannot be composed, see
-[Object-Storage Binding Environment](#object-storage-binding-environment). `ports-too-many` is a service declaring more target ports than the
+see [Service Volume Initialization](#service-volume-initialization). Of the four object-storage
+refusals, `objectstorage-endpoint-missing`, `objectstorage-binding-invalid` and
+`objectstorage-environment-conflict` name why a binding's environment cannot be composed, see
+[Object-Storage Binding Environment](#object-storage-binding-environment), and
+`objectstorage-endpoint-unselected`, like `database-endpoint-unselected`, names an endpoint the
+workload's network does not select (below). `ports-too-many` is a service declaring more target ports than the
 `runtimeConfigContract.maximumTargetPorts` (64) a config carries, where `port-protocol-unsupported`
 is about one port's protocol; `node-authority-unsupported` is a node whose session resolved fewer
 workload authorities than the spec needs, refused at the admit step rather than handed to a node
-that would silently park it. An attached network requires an explicit service policy: its absence
+that would silently park it. An attached network requires an explicit service policy
+(`IServiceNetworkEgress`): its absence
 is `network-policy-missing`, and a disagreement with the requested egress or platform endpoints is
-`network-policy-mismatch`. A missing workload address pool in the current protected authority is
+`network-policy-mismatch`. A binding endpoint the workload's network does not select would leave its
+connection dark, so it is refused instead: `database-endpoint-unselected` for an enabled database
+binding whose node's valid `corestoreDatabase` is not selected, and `objectstorage-endpoint-unselected`
+for an enabled object-storage binding whose node's valid `corestoreObjectStorage` is not. An endpoint
+is selected when one of the spec's `platformEndpointIds` names a platform endpoint of the current
+protected authority with the endpoint's host as its `address`, `tcp` as its `protocol` and the
+endpoint's port as its `port` — for object storage the origin's port, or 80 for `http:` and 443 for
+`https:` when it states none. An `isolated` network selects nothing, and platform endpoints are
+IPv4, so a DNS-name or IPv6 host is never selected. Both are judged only for a valid endpoint: a node
+stating none, or an invalid one, stays `database-endpoint-missing` or `objectstorage-endpoint-missing`.
+`platform.findUnselectedCorestoreEndpoints({ database, objectStorage, platformEndpoints, network })`
+is that rule: given one node's `corestoreDatabase` and `corestoreObjectStorage` (each `null` when no
+enabled binding of that kind is placed on the node), the current protected authority's
+`platformEndpoints` and the spec's `network`, it returns the `TCorestoreEndpointSelectionRefusal`s
+that apply, sorted, or an empty list. A missing workload address pool in the current protected authority is
 `network-workload-pool-missing`; existing eligible pools without a free workload subnet are
 `network-workload-pool-exhausted`. Neither policy nor pool is silently defaulted. A refusal never
 retires running slots.
@@ -2319,9 +2395,13 @@ with `clusterRelayCertificateDomainName(relay)`, which returns the origin's host
 Cloudly issues the certificate for and owns the A record for. An origin naming an address literal
 therefore has no issuable certificate.
 
-`data.clusterRelayUndispatchedRefusals` names the four registration refusals that end a relay's
-custody — `relay-cluster-not-enabled`, `relay-node-foreign`, `relay-sequence-not-advancing` and
-`relay-credential-generation-stale` — with `data.TClusterRelayUndispatchedRefusal` as their union.
+`data.clusterRelayUndispatchedRefusals` names the five registration refusals that end a relay's
+custody — `relay-cluster-not-enabled`, `relay-node-foreign`, `relay-node-unknown`,
+`relay-sequence-not-advancing` and `relay-credential-generation-stale` — with
+`data.TClusterRelayUndispatchedRefusal` as their union. `relay-node-foreign` names a node of another
+cluster; `relay-node-unknown` names a node Cloudly does not hold at all, because no Spark
+enrollment has created it yet, so the node a relay's `COREFLOW_NODE_ID` names is enrolled before
+the relay registers.
 Each is Cloudly reading its own records and stating that it does not dispatch to this relay, so a
 relay that hears one drops what it holds for its nodes instead of waiting. A refusal that only
 says Cloudly could not verify the relay states nothing about dispatch and is deliberately not in
@@ -2941,7 +3021,62 @@ const provisioning: requests.gateway.IReq_ProvisionGatewayClientCredential['requ
 };
 ```
 
-`getGatewayClientContext` returns effective live policy. A `gatewayClient` role necessarily includes the credential ID, bound client ID/type, and `policyGeneration`; consumers should reject admin/operator or mismatched contexts rather than falling back to a caller-supplied owner ID. `getGatewayClientMailOverview` provides an owner-scoped domain and recent-message summary. `getGatewayClientMailDomainCount` derives ownership exclusively from the authenticating gateway credential and returns `{ count: number }` for its distinct configured mail domains. Cloudly therefore uses only `dcrouterGatewayApiToken`; the former `dcrouterOpsApiToken` setting is not part of `data.ICloudlySettings`.
+`getGatewayClientContext` returns effective live policy. A `gatewayClient` role necessarily includes the credential ID, bound client ID/type, and `policyGeneration`; consumers should reject admin/operator or mismatched contexts rather than falling back to a caller-supplied owner ID. `getGatewayClientMailOverview` provides an owner-scoped domain and recent-message summary. `getGatewayClientMailDomainCount` derives ownership exclusively from the authenticating gateway credential and returns `{ count: number }` for its distinct configured mail domains. Cloudly therefore holds only its gateway-client credential, as the system secret `DCROUTER_GATEWAY_API_TOKEN` (see Cloudly Gateway Credential Bootstrap below); neither it nor the former `dcrouterOpsApiToken` is part of `data.ICloudlySettings`.
+
+### Cloudly Gateway Credential Bootstrap
+
+Cloudly enrolls itself at dcrouter as one least-privilege gateway client. The only way a gateway
+credential enters Cloudly is a dcrouter admin token an administrator hands in once, for the first
+enrollment and for every re-bootstrap a stale policy asks for — a changed gateway setting, or a
+runtime network address plan whose DNS record allowance moved.
+
+- `requests.settings.IReq_Any_Cloudly_BootstrapExternalGatewayCredential`
+  (`bootstrapExternalGatewayCredential`): `{ identity, expectedGatewayUrl, expectedGatewayClientId,
+  bootstrapToken: { mode: 'sealed', envelope } }` → `{ state }`. The token is sealed to Cloudly's
+  active secret ingress recipient (`requests.secret.IReq_GetSecretIngressRecipient`) under
+  `data.createGatewayBootstrapEnvelopeContext({ gatewayUrl, gatewayClientId })`, so it opens only
+  for a request naming the same dcrouter URL (HTTPS only, since an admin token is on the wire) and
+  client id, and Cloudly compares both with its own
+  settings before the token leaves it. Cloudly asks dcrouter whether the token is an admin token,
+  provisions, finalizes and stores its own gateway-client credential with it, and answers the
+  enrollment that results. The admin token is used for that one call and never stored; revoke it at
+  dcrouter afterwards. A refusal leaves the held credential unchanged and is one of
+  `data.externalGatewayBootstrapRefusals`: `gateway-unconfigured`, `gateway-target-mismatch`,
+  `bootstrap-token-invalid`, `bootstrap-token-rejected`, `bootstrap-token-not-admin`,
+  `bootstrap-candidate-pending`, `gateway-unreachable` and `bootstrap-provisioning-refused`.
+- `requests.settings.IReq_Any_Cloudly_GetExternalGatewayEnrollmentState`
+  (`getExternalGatewayEnrollmentState`): `{ identity }` → `{ state }`.
+
+`data.IExternalGatewayEnrollmentState { status, reason?, lastCheckedAt?, nextRetryAt?,
+cachedValidationProof, finalizationPending }` never carries a credential. `status` is one of
+`data.externalGatewayEnrollmentStatuses`: `unconfigured`, `checking`, `ready`, `degraded` (dcrouter
+unreachable; Cloudly retries) and `admin-bootstrap-required`. Both sides judge values with
+`requests.settings.validateBootstrapExternalGatewayCredentialRequest(request, recipient)` (schema,
+recipient, context digest and the ciphertext bound, without opening anything),
+`requests.settings.validateGetExternalGatewayEnrollmentStateRequest`,
+`data.validateExternalGatewayEnrollmentState` and `data.isExternalGatewayBootstrapToken(bytes)`,
+which accepts 1 to 1024 bytes of visible ASCII (`data.externalGatewayBootstrapContract`).
+
+```typescript
+import * as smartcrypto from '@push.rocks/smartcrypto';
+import { data, requests } from '@serve.zone/interfaces';
+
+const target = { gatewayUrl: 'https://gateway.example.com', gatewayClientId: 'cloudly.example.com' };
+const request: requests.settings.IReq_Any_Cloudly_BootstrapExternalGatewayCredential['request'] = {
+  identity: { jwt: adminJwt },
+  expectedGatewayUrl: target.gatewayUrl,
+  expectedGatewayClientId: target.gatewayClientId,
+  bootstrapToken: {
+    mode: 'sealed',
+    envelope: await smartcrypto.sealX25519Envelope({
+      plaintext: adminTokenBytes,
+      recipientPublicKey: ingressPublicKey,
+      recipientKeyId: ingressRecipient.recipientKeyId,
+      context: data.createGatewayBootstrapEnvelopeContext(target),
+    }),
+  },
+};
+```
 
 ### Gateway Client Hostname Records and Certificates
 
@@ -3642,6 +3777,10 @@ object-storage endpoint. What they are addressed to is a fact about the node, ow
 - `TServiceRuntimeRefusal` gains `database-endpoint-missing`: an enabled database binding placed on
   a node that states no valid `corestoreDatabase` is neither granted nor published, and its workload
   is refused rather than started with a guessed host.
+- A workload reaches that endpoint only when its attached network selects it as a platform endpoint;
+  an unselected valid endpoint is refused as `database-endpoint-unselected` (see
+  [Service Runtime Specs And Status](#service-runtime-specs-and-status) for the matching rule), as an object-storage endpoint is as
+  `objectstorage-endpoint-unselected`.
 
 ### Launcher Environment Delivery
 

package/ts/00_commitinfo_data.ts

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

package/ts/data/cluster.ts

@@ -175,6 +175,11 @@ export const clusterRelayUndispatchedRefusals = Object.freeze([
   'relay-cluster-not-enabled',
   /** The node the relay names belongs to another cluster than the one its identity names. */
   'relay-node-foreign',
+  /**
+   * The node the relay names does not exist: no Spark enrollment has created it yet. The relay's
+   * `COREFLOW_NODE_ID` must name a node Cloudly already holds, so the node is enrolled first.
+   */
+  'relay-node-unknown',
   /** A registration of this relay identity at the same or a higher sequence is already recorded. */
   'relay-sequence-not-advancing',
   /**

package/ts/data/networkaddressplan.ts

@@ -4,7 +4,15 @@ import { computeRuntimeNetworkProtectedAuthorityDigest, runtimeNetworkAuthorityC
   snapshotRuntimeNetworkProtectedAuthority } from './networkauthority.js';
 import { captureNetwork, failNetwork, networkContains, networkCounter, networkEqual, networkId, networkIpv4, networkList,
   networkOverlaps, networkPrefix, networkPrefixBounds, networkPrivatePrefix, networkRecord, networkSafe,
-  requireNetwork } from '../private/networkcontract.js';
+  requireNetwork, RuntimeNetworkAddressPlanStructureError, type TRuntimeNetworkAddressPlanOrderedField,
+} from '../private/networkcontract.js';
+
+export { RuntimeNetworkAddressPlanStructureError } from '../private/networkcontract.js';
+export type {
+  IRuntimeNetworkAddressPlanStructureViolation,
+  TRuntimeNetworkAddressPlanOrderedField,
+  TRuntimeNetworkAddressPlanStructureRule,
+} from '../private/networkcontract.js';
 
 /**
  * The address space an administrator gives the runtime network, and the one input the protected
@@ -15,11 +23,25 @@ export interface IRuntimeNetworkAddressPlan {
   id: 'address-plan';
   /** Compare-and-swap counter; every accepted change advances it by one. */
   revision: number;
-  /** Every protected prefix: they cover the pools, resolvers, platform endpoints and the VPN. */
+  /**
+   * Every protected prefix: they cover the pools, resolvers, platform endpoints and the VPN.
+   *
+   * Stated in strictly ascending string order of the prefix text. The order is lexicographic, not
+   * numeric: `10.10.0.0/16` comes before `10.2.0.0/16`, and `100.64.0.0/10` before `20.0.0.0/8`.
+   * A list out of that order, or one naming a prefix twice, is refused with
+   * `RuntimeNetworkAddressPlanStructureError` `{ field: 'prefixes', rule: 'order' }`.
+   */
   prefixes: string[];
+  /** Stated in strictly ascending string order of `id`; otherwise `{ field: 'pools', rule: 'order' }`. */
   pools: IRuntimeNetworkProtectedAuthority['pools'];
+  /** Stated in strictly ascending string order of `id`; otherwise `{ field: 'resolvers', rule: 'order' }`. */
   resolvers: IRuntimeNetworkProtectedAuthority['resolvers'];
-  /** Without the cluster hubs, which the composed authority adds from the hubs it is given. */
+  /**
+   * Without the cluster hubs, which the composed authority adds from the hubs it is given.
+   *
+   * Stated in strictly ascending string order of `id`; otherwise
+   * `{ field: 'platformEndpoints', rule: 'order' }`.
+   */
   platformEndpoints: IRuntimeNetworkProtectedAuthority['platformEndpoints'];
   vpn: {
     /** The private prefix VPN control addresses are allocated from. */
@@ -63,7 +85,12 @@ export type TRuntimeNetworkAddressPlanChangeRefusal = 'plan-vpn-immutable' | 'pl
  * platform endpoint the change removes or changes while a router selection or a service still names it.
  */
 export type TRuntimeNetworkAddressPlanRefusal =
-  | TRuntimeNetworkAddressPlanChangeRefusal | 'plan-resolver-referenced' | 'plan-endpoint-referenced';
+  | TRuntimeNetworkAddressPlanChangeRefusal | 'plan-resolver-referenced' | 'plan-endpoint-referenced'
+  /**
+   * A list of the plan is not in its canonical order; `RuntimeNetworkAddressPlanStructureError`
+   * names which one, and a refusal carries that field as its reference.
+   */
+  | 'plan-unsorted';
 
 export type TRuntimeNetworkAddressPlanChange =
   | { status: 'unchanged' }
@@ -180,14 +207,49 @@ const requireVpnProtected = (authority: IRuntimeNetworkProtectedAuthority, vpn:
     && !networkOverlaps(vpn.controlPrefix, vpn.hubPrefix));
 };
 
+/** The key each ordered list of a plan is sorted by, or `undefined` for an entry no key can be read from. */
+const planOrderKeys: Record<TRuntimeNetworkAddressPlanOrderedField, (entry: unknown) => string | undefined> = {
+  prefixes: entry => typeof entry === 'string' ? entry : undefined,
+  pools: entry => entryId(entry),
+  resolvers: entry => entryId(entry),
+  platformEndpoints: entry => entryId(entry),
+};
+
+function entryId(entry: unknown): string | undefined {
+  if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) return undefined;
+  const id = (entry as Record<string, unknown>).id;
+  return typeof id === 'string' ? id : undefined;
+}
+
+/**
+ * Refuses a plan list out of its canonical order by name: strictly ascending by the list's key, in
+ * JavaScript string order, which is the order the protected authority contract reads it in. A list
+ * whose keys cannot all be read is left to the structural check, which refuses it without a name.
+ */
+const requirePlanOrder = (item: Record<string, unknown>): void => {
+  for (const field of ['prefixes', 'pools', 'resolvers', 'platformEndpoints'] as const) {
+    const list = item[field];
+    if (!Array.isArray(list)) continue;
+    const keys = list.map(planOrderKeys[field]);
+    if (keys.some(key => key === undefined)) continue;
+    if (!keys.every((key, index) => index === 0 || (keys[index - 1] as string) < (key as string))) {
+      throw new RuntimeNetworkAddressPlanStructureError({ field, rule: 'order' });
+    }
+  }
+};
+
 /**
  * Structural snapshot for exact persistence and for a plan write. The plan's own sets pass the
  * protected authority's own validator, so no plan can describe an authority that contract refuses,
  * and both VPN prefixes are reserved inside the protected space the plan states.
+ *
+ * A list out of its canonical order is refused with `RuntimeNetworkAddressPlanStructureError`,
+ * which names the list; every other refusal is the contract's generic rejection.
  */
 export const snapshotRuntimeNetworkAddressPlan = (value: unknown): IRuntimeNetworkAddressPlan => networkSafe(() => {
   const item = networkRecord(captureNetwork(value), ['id', 'revision', 'prefixes', 'pools', 'resolvers', 'platformEndpoints', 'vpn']);
   requireNetwork(item.id === runtimeNetworkAddressPlanContract.id);
+  requirePlanOrder(item);
   const own = authorityOf({ prefixes: item.prefixes, pools: item.pools, resolvers: item.resolvers,
     platformEndpoints: item.platformEndpoints }, validationFrame);
   const plan: IRuntimeNetworkAddressPlan = { id: runtimeNetworkAddressPlanContract.id, revision: networkCounter(item.revision),