@serve.zone/interfaces 32.20.1 → 32.22.0

package/dist_ts/requests/clusteringress.js

@@ -1,3 +1,3 @@
 import * as clusterIngressInterfaces from '../data/clusteringress.js';
 import * as plugins from '../plugins.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2x1c3RlcmluZ3Jlc3MuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9yZXF1ZXN0cy9jbHVzdGVyaW5ncmVzcy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssd0JBQXdCLE1BQU0sMkJBQTJCLENBQUM7QUFFdEUsT0FBTyxLQUFLLE9BQU8sTUFBTSxlQUFlLENBQUMifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2x1c3RlcmluZ3Jlc3MuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9yZXF1ZXN0cy9jbHVzdGVyaW5ncmVzcy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssd0JBQXdCLE1BQU0sMkJBQTJCLENBQUM7QUFRdEUsT0FBTyxLQUFLLE9BQU8sTUFBTSxlQUFlLENBQUMifQ==

package/dist_ts/requests/gateway.d.ts

@@ -1,5 +1,5 @@
 import * as plugins from '../plugins.js';
-import type { IGatewayCapabilities, IGatewayClient, IGatewayClientCredential, IGatewayClientProvisioningSpec, IGatewayClientContext, IGatewayClientOwnership, IGatewayClientRoute, IGatewayDnsRecord, IGatewayDomain, IGatewayIdentity, IGatewayRouteConfig, IGatewayRouteSyncResult, TGatewayRouteDnsMode, TGatewayClientProvisioningAction } from '../data/gateway.js';
+import type { IGatewayCapabilities, IGatewayClient, IGatewayClientCredential, IGatewayClientProvisioningSpec, IGatewayClientContext, IGatewayClientDnsRecord, IGatewayClientDnsRecordSyncResult, IGatewayClientHostnameOwnership, IGatewayClientOwnership, IGatewayClientRoute, IGatewayDnsRecord, IGatewayDomain, IGatewayIdentity, IGatewayRouteConfig, IGatewayRouteSyncResult, TGatewayRouteDnsMode, TGatewayClientCertificateReleaseResult, TGatewayClientCertificateResult, TGatewayClientProvisioningAction } from '../data/gateway.js';
 import type { IMailOverviewDomain, IMailOverviewEmail } from './mail.js';
 /**
  * Gateway client contracts: the machine-facing API a gateway (dcrouter)
@@ -172,6 +172,63 @@ export interface IReq_SyncGatewayClientRoute extends plugins.typedrequestInterfa
     };
     response: IGatewayRouteSyncResult;
 }
+/**
+ * Publishes, replaces or withdraws the one address record a gateway-client ownership holds.
+ *
+ * Gateway-client credentials only, with the `syncDnsRecords` capability; the hostname must match
+ * the client's `hostnamePatterns`. Idempotent: the same record again answers `managed-unchanged`,
+ * and deleting a record the ownership does not hold answers `managed-deleted`. The value must lie
+ * inside the client's `allowedDnsRecordAddresses` (`target-invalid` otherwise). A hostname held by
+ * anything else is `record-conflict` and stays untouched. Requires `dns.clientRecords`.
+ */
+export interface IReq_SyncGatewayClientDnsRecord extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_SyncGatewayClientDnsRecord> {
+    method: 'syncGatewayClientDnsRecord';
+    request: {
+        apiToken: string;
+        identity?: never;
+        ownership: IGatewayClientHostnameOwnership;
+    } & ({
+        record: IGatewayClientDnsRecord;
+        delete?: never;
+    } | {
+        delete: true;
+        record?: never;
+    });
+    response: IGatewayClientDnsRecordSyncResult;
+}
+/**
+ * Answers the exact certificate for one owned hostname, starting its issuance when none is valid.
+ *
+ * Gateway-client credentials only, with `requestCertificates` and `readCertificates`; the hostname
+ * must match the client's `hostnamePatterns`. No gateway route is needed. The certificate is issued
+ * for exactly this one identifier in the client's own namespace, and asking again after
+ * `renewAfter` answers a renewed one. The `ready` answer carries the private key. Requires
+ * `certificates.exactIssuance`.
+ */
+export interface IReq_GetGatewayClientCertificate extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_GetGatewayClientCertificate> {
+    method: 'getGatewayClientCertificate';
+    request: {
+        apiToken: string;
+        identity?: never;
+        ownership: IGatewayClientHostnameOwnership;
+    };
+    response: TGatewayClientCertificateResult;
+}
+/**
+ * Removes the certificate material and any issuance an ownership holds, releasing its certificate claim; an address record under the same ownership is unaffected.
+ *
+ * Gateway-client credentials only, with `requestCertificates`. Idempotent: an ownership that holds
+ * nothing answers `unchanged`. Requires `certificates.exactIssuance`.
+ */
+export interface IReq_ReleaseGatewayClientCertificate extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_ReleaseGatewayClientCertificate> {
+    method: 'releaseGatewayClientCertificate';
+    request: {
+        apiToken: string;
+        identity?: never;
+        ownership: IGatewayClientHostnameOwnership;
+    };
+    response: TGatewayClientCertificateReleaseResult;
+}
 export interface IReq_ReprovisionCertificateDomain extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_ReprovisionCertificateDomain> {
     method: 'reprovisionCertificateDomain';
     request: {

package/dist_ts/requests/runtimesession.d.ts

@@ -8,6 +8,7 @@ import type * as credential from '../data/networkcredential.js';
 import type * as assignmentSecret from '../runtime.assignmentsecret.js';
 import type * as fleet from '../data/fleetcutover.js';
 import type { IRuntimeStorageClaim } from '../data/runtimestorageclaim.js';
+import type * as localStorage from '../data/runtimelocalstorageclaim.js';
 /** Current-peer, exact-projection authorization; response contains secret keys. */
 export interface IReq_Pallet_Controller_GetRuntimeManagedVpnCredential extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Pallet_Controller_GetRuntimeManagedVpnCredential> {
     method: 'getRuntimeManagedVpnCredential';
@@ -125,6 +126,17 @@ export interface IReq_Controller_Pallet_ApplyRuntimeAssignment extends plugins.t
     request: data.IApplyRuntimeAssignmentRequest;
     response: data.IApplyRuntimeAssignmentResponse;
 }
+/**
+ * Controller push of one local storage claim over the already authenticated Pallet-initiated
+ * connection; `bindApplyRuntimeLocalStorageClaimRequest` binds it to that session. The answer is a
+ * durable admission acknowledgement plus the volume's state; it grants no mount by itself, which
+ * only an assignment that seals the claim's reference does.
+ */
+export interface IReq_Controller_Pallet_ApplyRuntimeLocalStorageClaim extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Controller_Pallet_ApplyRuntimeLocalStorageClaim> {
+    method: 'applyRuntimeLocalStorageClaim';
+    request: localStorage.IApplyRuntimeLocalStorageClaimRequest;
+    response: localStorage.IApplyRuntimeLocalStorageClaimResponse;
+}
 /** Current-peer report, including exact historical outbox recovery after reconnect. */
 export interface IReq_Pallet_Controller_ReportRuntimeAssignmentObservation extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Pallet_Controller_ReportRuntimeAssignmentObservation> {
     method: 'reportRuntimeAssignmentObservation';

package/package.json

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

package/readme.md

@@ -572,6 +572,41 @@ overlapping current grants reject, and up to 4,096 retained withdrawals carry
 forward until the caller supplies its exact joined application of the preceding
 projection.
 
+The optional `IRuntimeNetworkProjection.workloadIngress` member exists only on
+`cloudly` projections; any other controller kind carrying it rejects. It is how
+the cluster ingress workload reaches the workloads it routes to without a
+published host port: each `grants` entry names the exact lease reference of the
+ingress workload (`source`), the exact lease reference of the target workload
+(`destination`), a protocol, the target's own listening port and an
+`authorization` reference. Unlike the full-mesh workload grants, it needs neither
+the same organization nor a shared private network, it opens exactly one port,
+and it is one-way: nothing flows back except the replies of a connection the
+ingress opened. Both leases must be endpoints of the projection, they must
+differ, and at least one of them must be placed on the projection's own node.
+Entries are unique and strictly ordered by `[source.id, destination.id, protocol,
+port]`; at most 1,024 are allowed (`runtimeNetworkWorkloadIngressContract`). The
+authorization is signed content, not grant identity. A projection that omits the
+member retains its exact canonical bytes, digest and signature.
+`getRuntimeNetworkProjectionWorkloadIngressPacketGrants` validates the complete
+projection and returns detached `IRuntimeNetworkWorkloadIngressPacketGrant`s
+(`{ source, destination: { lease, protocol, port } }`). Their withdrawals follow
+the host rules: an omitted grant needs its exact withdrawal, unknown or current
+denials reject, and up to 4,096 retained withdrawals carry forward until the
+exact joined application of the preceding projection is supplied. Cloudly routes
+a cluster ingress route to the target lease address and port once the grant
+exists.
+
+The optional `IRuntimeNetworkProjection.hostPlatformEndpointIds` lists the ids of
+the protected authority's platform endpoints whose address the projection's
+node's own host carries, such as a relay listener or a Corestore beside the node
+on one machine. A node delivers workload flows to those endpoints locally instead
+of forwarding them. The list is sorted, unique, never empty when present, and
+every id must be a current platform endpoint; omitting it keeps the canonical
+bytes and states that no endpoint is local. It grants nothing: a workload still
+reaches only the endpoints it selects. The platform endpoint contract itself
+(`{ id, address, protocol, port }`) names no node, which is why this statement is
+per projection.
+
 `admitRuntimeNetworkProjection` checks exact predecessor/replay identity and
 rejects changed same-generation content, regressed membership/readiness evidence,
 changed immutable address/DNS keys, and omitted packet grants without explicit
@@ -811,6 +846,15 @@ named once; an empty `hubs` composes the authority of a runtime network whose cl
 yet. One hub costs one of the authority's 64 platform endpoints, so 64 clusters fit one
 authority.
 
+A single host that carries both a cluster's hub and platform endpoints, for example the relay
+listener and a Corestore, holds more than one address. The hub address sits inside `vpn.hubPrefix`,
+as every hub's does. The plan's own platform endpoints may not: they sit on another address of the
+same host, inside `prefixes`, outside every pool and outside both VPN prefixes. Several endpoints may
+share that one address on distinct ports, because the authority requires only each
+`address:port:protocol` to be unique. For example, with `hubPrefix` `192.0.2.0/28`, the hub binds
+`192.0.2.1` and the plan lists the relay listener and Corestore on `192.0.2.17` with two ports. The
+node's projection then names those endpoints in `hostPlatformEndpointIds`.
+
 `admitRuntimeNetworkAddressPlanChange(previous | null, next)` is the pure decision for a plan write at
 the following revision; any other revision is a contract violation. Leases and the managed VPN
 outlive a plan revision, so it answers:
@@ -1373,12 +1417,18 @@ phase, settlement, release or authority booleans or evidence.
 `data.IServiceRuntimeStatus { id, specRevision, state, reason, changedAt }` is the producer's verdict
 on one spec revision, and each reason belongs to exactly one state. `converged` and `converging`
 carry `reason: null`. `waiting` carries a `TServiceRuntimeWaitingReason`: `node-network-pending`,
-`conflict` or `failure-backoff`. `refused` carries a `TServiceRuntimeRefusal`:
+`conflict`, `failure-backoff`, `storage-import-pending` (an `import` local storage claim whose bytes
+have not arrived on its node) or `bindings-pending` (the secret manifest does not cover every enabled
+binding of the service yet). `refused` carries a `TServiceRuntimeRefusal`:
 `cluster-runtime-missing`, `organization-missing`, `image-plan-missing`, `platform-unsupported`,
 `secrets-unsupported`, `volumes-unsupported`, `port-protocol-unsupported`, `ports-too-many`,
 `readiness-target-undeclared`, `environment-too-large`, `no-eligible-node`, `replica-limit`,
 `node-authority-unsupported`, `network-policy-missing`, `network-policy-mismatch`,
-`network-workload-pool-missing` or `network-workload-pool-exhausted`. `ports-too-many` is a service declaring more target ports than the
+`network-workload-pool-missing`, `network-workload-pool-exhausted`, `volume-driver-unsupported`,
+`volume-options-unsupported`, `volume-shared-unsupported` or `volume-placement-unsupported`. The 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. `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
@@ -1881,6 +1931,47 @@ storage provider's binding identity/generation, selected policy, matching observ
 join: callers still authenticate Cloudly and the provider, check current readiness and retain the
 native fence.
 
+### Runtime local storage claims
+
+`data.IRuntimeLocalStorageClaim` is a controller's authority for one retained, node-local volume of
+one service. Cloudly and Onebox issue it alike (`controller.kind` is `cloudly` or `onebox`). It names
+the claim revision (`id`, `generation`, `previous`), the organization, cluster, node, runtime
+namespace, service and the service's own `volumeId`, and it states:
+
+- `source`: `{ kind: 'directory' }`, a node-local directory the node derives from the claim's
+  identity under a root only the node knows. Network filesystems join this union later as further
+  kinds, with their credentials delivered as secrets and never inside a claim;
+- `initialization`: `empty` creates an empty root with `initialOwnership { uid, gid, mode }`, which
+  an `empty` claim must state, so a workload without `runAs` never meets a root-owned directory by
+  accident; `import` waits for the volume's bytes to be imported and states `initialOwnership: null`,
+  because an imported tree keeps its own ownership. `mode` holds directory permission bits only
+  (`runtimeLocalStorageClaimContract.directoryModeBits`, `0o3777`; setuid is refused);
+- `mount { mountPath, readOnly }`, judged by the storage request's own mount path rule: canonical,
+  absolute, not `/`, and never overlapping `/run/secrets`;
+- `accessMode: 'ReadWriteOnce'`, `reclaimPolicy: 'retain'`, and `lifecycle`: `bound` keeps the
+  volume, `purge` orders its bytes deleted and always follows a bound generation of the same claim.
+
+The claim carries no host path, device, mount option or credential.
+`snapshotRuntimeLocalStorageClaim` makes a detached exact-schema snapshot,
+`computeRuntimeLocalStorageClaimDigest` hashes it under `serve.zone/runtime-local-storage-claim`,
+`validateRuntimeLocalStorageClaim` verifies the stated digest, and
+`getRuntimeLocalStorageClaimReference` is the `{ id, generation, digest }` an assignment seals in
+`workload.storage`. `bindRuntimeLocalStorageClaimToAssignment(claim, assignment, expectedClusterId)`
+checks that reference and the exact controller, organization, node, runtime namespace, service and
+cluster; a `purge` claim binds to no assignment, because no workload may mount a volume being deleted.
+
+`requests.runtimesession.IReq_Controller_Pallet_ApplyRuntimeLocalStorageClaim`
+(`applyRuntimeLocalStorageClaim`) pushes one claim over the node's authenticated session:
+`{ session, claim }` → `{ status, state, claim }`. `status` is `accepted`, `replay` or `historical`;
+`state` is `ready`, `import-required`, `purged` or `uncertain` (a volume the node can vouch for
+neither way, which it neither mounts nor deletes until an operator decides); `claim` is the sent
+claim's reference. `bindApplyRuntimeLocalStorageClaimRequest(request, trustedSession)` requires the
+request's session to equal the node's current one and the claim to name its controller, cluster,
+node and runtime namespace. `bindApplyRuntimeLocalStorageClaimResponse(response, request)` binds the
+answer to the sent claim and, for `accepted` and `replay`, to a state the claim can be in: a bound
+claim is `ready`, `import-required` (an `import` claim only) or `uncertain`, a purge is `purged` or
+`uncertain`. A `historical` answer describes the newer generation the node holds.
+
 `platform.storagemigration` defines the provider-neutral cutover contract for a
 named object-storage binding. Corestore atomically owns and fences the source
 binding after validating a distinct, unfenced active-object snapshot. Onebox
@@ -2440,6 +2531,9 @@ credential is excluded.
 | `registerClusterIngress` | ingress → relay → Cloudly | `{ bearer, version, nodeId, capabilities?, protocol }` → `{ accepted: true, revision \| null, protocol }` |
 | `getClusterIngressRouteTable` | ingress → relay | `{ knownRevision \| null }` → `{ table \| null }` |
 | `getClusterTrafficStatistics` | Cloudly → relay → ingress | `{ fromDayUtc, toDayUtc, cursor?, limit }` → `{ statistics, nextCursor? }` |
+| `pushClusterIngressRouteTableChanged` | relay → ingress | `{ revision }` → `{}` |
+| `designateClusterIngress` | admin → Cloudly | `{ identity, designation }` → `{ designation, spec, replayed }` |
+| `getClusterIngressDesignation` | admin → Cloudly | `{ identity, clusterId }` → `{ designation \| null }` |
 
 `null` for a table means Cloudly has computed none yet — a fact, not an empty table, and an
 ingress must not serve it as one. An ingress announces itself with a **method**, not a connection
@@ -2465,6 +2559,45 @@ the body in the one server order `protocol.readProtocolOffer` states — the off
 before this shape check and before the bearer — so a relay refuses a peer it cannot serve without
 asking Cloudly, and an accepted registration carries the accepting side's own offer back.
 
+A refused registration is named. A protocol mismatch stays the `IProtocolRefusal` every hop already
+carries; every other refusal travels as `IClusterIngressRegistrationRefusal { code:
+'cluster-ingress-registration-refused', reason, retryAfterMs }` in `TypedResponseError.errorData`,
+forwarded by the relay untouched. `clusterIngressRegistrationRefusalReasons` lists the reasons in
+the order Cloudly judges them: `not-ready` (Cloudly cannot judge registrations yet), `registration-invalid`
+(the body fails `validateClusterIngressRegistration`), `relay-not-connected` (the forwarding relay is
+not the connection Cloudly elected for its cluster), `ingress-not-designated`, `node-mismatch` (the
+node is not one the designation lets the ingress run on), `assignment-not-running` (no ready
+assignment of the ingress service runs on that node under its current session, or it does not carry
+the designation's current credential), `bearer-refused` and `conflict` (the designation, assignment
+or session changed while the registration was judged). `retryAfterMs` is how long the ingress waits
+before it registers again, 1 s to 300 s (`clusterIngressRegistrationContract`).
+`validateClusterIngressRegistrationRefusal` names every violation and
+`readClusterIngressRegistrationRefusal(errorData)` answers the refusal or `null`, reading plain data
+only, as `protocol.readProtocolRefusal` does. No refusal quotes the bearer.
+
+`pushClusterIngressRouteTableChanged` is the relay's hint that it holds a newer table. It carries the
+revision alone (`IClusterIngressRouteTableChange`, `validateClusterIngressRouteTableChange`) and
+nothing secret; the ingress answers it by pulling `getClusterIngressRouteTable` with the revision it
+already applied and ignores a hint that is not newer, so a lost or repeated hint costs nothing.
+
+`clusterIngressEnvironmentNames` spells the ingress workload's environment once for both sides:
+`SERVEZONE_CLUSTER_INGRESS_BEARER` (the registration bearer, delivered as a secret),
+`SERVEZONE_CLUSTER_RELAY_ORIGIN` (the exact `IClusterRelay.origin`) and `SERVEZONE_CLUSTER_NODE_ID`
+(the node the assignment runs on). Cloudly writes them; the ingress reads them.
+
+A cluster born on Pallet has no cutover scope, census or target set, so its ingress is designated by
+`IClusterIngressDesignation { id, generation, previous, clusterId, runtime, ingressServiceId,
+preparedSpecRevision, credential, actorId, acceptedAt, digest }` instead of the fleet-cutover
+designation. `runtime` is the cluster's `pallet` phase reference and `credential`
+(`IClusterIngressCredentialReference`) the public identity of the managed bearer, never its value.
+`snapshotClusterIngressDesignation`, `computeClusterIngressDesignationDigest` (domain
+`serve.zone/cluster-ingress-designation`) and `validateClusterIngressDesignation` judge it, and
+`snapshotClusterIngressDesignationRequest` the administrator's compare-and-swap intent
+(`IClusterIngressDesignationRequest { mutationId, clusterId, ingressServiceId, currentRuntime,
+expectedSpecRevision, expectedDesignation }`). **A cluster holds exactly one kind of designation**:
+Cloudly refuses to designate a cluster that holds a fleet-cutover ingress designation, and the
+reverse. Which nodes the ingress runs on is the ingress service's runtime spec placement.
+
 `IClusterTrafficStatistics` is one UTC day of one hostname's traffic on one node —
 `requests`, `bytesIn`, `bytesOut`, `connections` and the backend failures the proxy can observe
 (`connect`, `handshake`, `request`). Day buckets rather than rates: a rate answers "how busy is it
@@ -2684,6 +2817,38 @@ 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`.
 
+### Gateway Client Hostname Records and Certificates
+
+A gateway client can hold an exact hostname without a gateway route: an address record at a value it chooses, and an exact certificate for that one name. Cloudly uses this for its cluster relay names, whose A record must carry the relay node's own address and whose certificate the relay serves itself. All three requests accept only a gateway-client credential (`identity` is `never`). The gateway resolves the client from that credential, and the hostname must match the client's `hostnamePatterns`. `data.IGatewayClientHostnameOwnership` names only `{ appId, hostname }`. One ownership holds at most one address record and one certificate. A hostname held by another ownership, by a gateway route claim, or by a record the gateway does not manage is a conflict. The gateway never overwrites or adopts it.
+
+- `syncGatewayClientDnsRecord` (`requests.gateway.IReq_SyncGatewayClientDnsRecord`) publishes, replaces or withdraws the ownership's `A` or `AAAA` record. It needs the token capability `syncDnsRecords`, and the gateway advertises it as `capabilities.dns.clientRecords`. The value must be a canonical unicast literal inside the client's policy field `allowedDnsRecordAddresses`, a list of canonical CIDR prefixes. An absent or empty list allows no record. The result reuses the route DNS vocabulary (`data.TGatewayClientDnsRecordStatus`): `target-invalid` for an address outside the allowance, `record-conflict` with `conflictingRecords` as evidence, and `zone-unavailable` or `mutation-failed` when retryable. Records are never proxied.
+- `getGatewayClientCertificate` (`requests.gateway.IReq_GetGatewayClientCertificate`) answers `ready` with `data.IGatewayClientCertificate` (PEM chain, PEM private key, `validFrom`, `validUntil`, `renewAfter`), `pending` with `retryAfterMs` while an issuance runs, or `refused` with a `data.TGatewayClientCertificateRefusal`. Asking again after `renewAfter` yields a renewed certificate. It needs `requestCertificates` and `readCertificates`, and the gateway advertises it as `capabilities.certificates.exactIssuance`. The `ready` answer carries a private key; keep it sealed and never log it.
+- `releaseGatewayClientCertificate` (`requests.gateway.IReq_ReleaseGatewayClientCertificate`) removes the ownership's certificate material and any issuance in flight. It is idempotent and answers `released` or `unchanged`.
+
+Both sides judge values with the same helpers:
+
+- `data.validateGatewayClientHostnameOwnership`
+- `data.validateGatewayClientDnsRecord`
+- `data.validateGatewayAllowedDnsRecordAddresses`
+- `data.isGatewayClientDnsRecordAllowed`
+- `data.isGatewayAddressPrefix`
+- `data.isGatewayClientHostname`
+
+Only one spelling of each address is accepted: the dotted quad, or RFC 5952 text for IPv6. `data.gatewayClientHostnameContract` states the bounds: TTL 60 to 86400 seconds with a default of 300, at most 64 allowance prefixes, an `appId` of at most 128 characters, and a hostname of at most 253 characters.
+
+```typescript
+import { data, requests } from '@serve.zone/interfaces';
+
+const record: data.IGatewayClientDnsRecord = { type: 'A', value: '198.51.100.85', ttl: 60 };
+data.isGatewayClientDnsRecordAllowed(record, ['198.51.100.0/24']); // true
+
+const request: requests.gateway.IReq_SyncGatewayClientDnsRecord['request'] = {
+  apiToken: gatewayClientToken,
+  ownership: { appId: 'cluster-relay:clusterexample', hostname: 'relay.clusterexample.example.com' },
+  record,
+};
+```
+
 ### CoreMail contracts
 
 `requests.coremail` is the shared contract boundary for authenticated workload

package/ts/00_commitinfo_data.ts

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

package/ts/data/clusteringress.ts

@@ -1,7 +1,7 @@
 import { isPlausibleUnicastIpv4 } from '../private/ipv4.js';
 import { isUtcCalendarDay } from '../private/utccalendarday.js';
 import { validateProtocolOfferOn } from '../protocol.js';
-import { hasExactKeys } from '../private/dataproperties.js';
+import { hasExactKeys, readExactDataRecord } from '../private/dataproperties.js';
 import { isClusterNodeId } from '../private/nodeidentifier.js';
 
 /**
@@ -424,3 +424,138 @@ export const validateClusterIngressRegistration = (
   }
   return errors;
 };
+
+/**
+ * The environment variable names of the cluster ingress workload.
+ *
+ * Cloudly writes them into the ingress workload's assignment environment and the ingress reads
+ * them, so both sides spell each name once, here. `bearer` is the credential the ingress presents
+ * to `registerClusterIngress`; it is a secret and is delivered as one. `relayOrigin` is the exact
+ * `IClusterRelay.origin` of the cluster's relay, and `nodeId` is the node the assignment runs on,
+ * which the registration's `nodeId` repeats.
+ */
+export const clusterIngressEnvironmentNames = Object.freeze({
+  bearer: 'SERVEZONE_CLUSTER_INGRESS_BEARER',
+  relayOrigin: 'SERVEZONE_CLUSTER_RELAY_ORIGIN',
+  nodeId: 'SERVEZONE_CLUSTER_NODE_ID',
+} as const);
+
+/**
+ * Every reason Cloudly refuses a cluster ingress registration, in the order it judges them.
+ *
+ * A protocol mismatch is not among them: it is refused first, as the `IProtocolRefusal` every
+ * TypedRequest hop already carries, and a second name for it would be a second answer to one fact.
+ */
+export const clusterIngressRegistrationRefusalReasons = Object.freeze([
+  /** Cloudly cannot judge registrations yet: it is starting, stopping or missing its environment. */
+  'not-ready',
+  /** The body fails `validateClusterIngressRegistration`. */
+  'registration-invalid',
+  /** The relay that forwarded the registration is not the connection Cloudly elected for its cluster. */
+  'relay-not-connected',
+  /** The cluster holds no current ingress designation. */
+  'ingress-not-designated',
+  /** The named node is not one the designation lets the ingress run on. */
+  'node-mismatch',
+  /**
+   * No ready assignment of the designated ingress service runs on the named node under that node's
+   * current session, or the one that runs does not carry the designation's current credential.
+   */
+  'assignment-not-running',
+  /** The bearer is not the designation's current credential. */
+  'bearer-refused',
+  /** The designation, the assignment or the session changed while the registration was judged. */
+  'conflict',
+] as const);
+
+export type TClusterIngressRegistrationRefusalReason = typeof clusterIngressRegistrationRefusalReasons[number];
+
+export const clusterIngressRegistrationContract = Object.freeze({
+  refusalCode: 'cluster-ingress-registration-refused',
+  minimumRetryAfterMs: 1_000,
+  maximumRetryAfterMs: 300_000,
+} as const);
+
+/**
+ * The named refusal of `registerClusterIngress`, carried as `TypedResponseError.errorData` from
+ * Cloudly and forwarded by the relay untouched. `retryAfterMs` is how long the ingress waits before
+ * it registers again; it never quotes the bearer or anything derived from it.
+ */
+export interface IClusterIngressRegistrationRefusal {
+  code: 'cluster-ingress-registration-refused';
+  reason: TClusterIngressRegistrationRefusalReason;
+  retryAfterMs: number;
+}
+
+const isRetryAfterMs = (valueArg: unknown): valueArg is number => (
+  Number.isSafeInteger(valueArg)
+  && (valueArg as number) >= clusterIngressRegistrationContract.minimumRetryAfterMs
+  && (valueArg as number) <= clusterIngressRegistrationContract.maximumRetryAfterMs
+);
+
+/** Validates one registration refusal and names every reason it is refused. */
+export const validateClusterIngressRegistrationRefusal = (
+  valueArg: unknown,
+  pathArg = 'cluster ingress registration refusal',
+): string[] => {
+  if (!isRecord(valueArg) || !hasExactKeys(valueArg, ['code', 'reason', 'retryAfterMs'])) {
+    return [`${pathArg} must use its exact schema`];
+  }
+  const errors: string[] = [];
+  if (valueArg.code !== clusterIngressRegistrationContract.refusalCode) {
+    errors.push(`${pathArg} code must be ${clusterIngressRegistrationContract.refusalCode}`);
+  }
+  if (!(clusterIngressRegistrationRefusalReasons as readonly unknown[]).includes(valueArg.reason)) {
+    errors.push(`${pathArg} reason must be a cluster ingress registration refusal reason`);
+  }
+  if (!isRetryAfterMs(valueArg.retryAfterMs)) {
+    errors.push(`${pathArg} retryAfterMs must be an integer from `
+      + `${clusterIngressRegistrationContract.minimumRetryAfterMs} to `
+      + `${clusterIngressRegistrationContract.maximumRetryAfterMs}`);
+  }
+  return errors;
+};
+
+/**
+ * The refusal inside an error payload, or `null` when the value is not one.
+ *
+ * It reads a value that survived serialization, the way `protocol.readProtocolRefusal` does, so an
+ * ingress tells a named registration refusal apart from a protocol refusal and every other error.
+ */
+export const readClusterIngressRegistrationRefusal = (
+  valueArg: unknown,
+): IClusterIngressRegistrationRefusal | null => {
+  const refusal = readExactDataRecord(valueArg, ['code', 'reason', 'retryAfterMs']);
+  if (refusal === null || validateClusterIngressRegistrationRefusal(refusal).length > 0) {
+    return null;
+  }
+  return Object.freeze({
+    code: clusterIngressRegistrationContract.refusalCode,
+    reason: refusal.reason as TClusterIngressRegistrationRefusalReason,
+    retryAfterMs: refusal.retryAfterMs as number,
+  });
+};
+
+/**
+ * The relay's hint that it holds a newer route table.
+ *
+ * It carries the revision alone and no route, certificate or key, so it is safe to log; the
+ * ingress answers it by pulling `getClusterIngressRouteTable` with the revision it already applied,
+ * and ignores a hint whose revision is not greater than that one.
+ */
+export interface IClusterIngressRouteTableChange {
+  revision: number;
+}
+
+/** Validates one route-table change hint. */
+export const validateClusterIngressRouteTableChange = (
+  valueArg: unknown,
+  pathArg = 'cluster ingress route table change',
+): string[] => {
+  if (!isRecord(valueArg) || !hasExactKeys(valueArg, ['revision'])) {
+    return [`${pathArg} must use its exact schema`];
+  }
+  return isCounter(valueArg.revision)
+    ? []
+    : [`${pathArg} revision must be a non-negative safe integer`];
+};

package/ts/data/clusteringressdesignation.ts

@@ -0,0 +1,141 @@
+import type { TSha256Digest } from './immutableimage.js';
+import type { IClusterRuntimeReference } from './clusterruntime.js';
+import { snapshotClusterRuntimeReference } from './clusterruntime.js';
+import type { IRuntimeAuthorityReference } from './runtimeassignment.js';
+import type { ISecretVersionReference } from './secret.js';
+import { captureNetwork, networkCounter, networkDigest, networkHash, networkId, networkRecord, networkReference,
+  networkRevision, requireNetwork } from '../private/networkcontract.js';
+
+/**
+ * The ingress designation of a cluster born on Pallet.
+ *
+ * A cluster that never ran Swarm has no cutover scope, census or target set, so its ingress is
+ * designated by this record instead of `IFleetCutoverIngressDesignation`. A cluster holds exactly
+ * one kind of designation at a time: Cloudly refuses to designate a cluster that holds the other
+ * kind. Which nodes the ingress runs on is the ingress service's runtime spec placement; the
+ * designation names the service and the credential, and nothing else.
+ */
+
+/** Public identity of the active ingress credential generation; it contains no credential value. */
+export interface IClusterIngressCredentialReference {
+  credentialId: string;
+  generation: number;
+  secretVersion: ISecretVersionReference;
+}
+
+/**
+ * Cloudly's accepted designation of one service as a Pallet cluster's ingress. It grants no
+ * assignment, session or registration: the ingress still registers with the credential it names.
+ */
+export interface IClusterIngressDesignation {
+  id: string;
+  generation: number;
+  previous: IRuntimeAuthorityReference | null;
+  clusterId: string;
+  runtime: IClusterRuntimeReference & { phase: 'pallet' };
+  ingressServiceId: string;
+  /** The ingress service's runtime spec revision the designation was accepted against. */
+  preparedSpecRevision: number;
+  credential: IClusterIngressCredentialReference;
+  actorId: string;
+  acceptedAt: number;
+  digest: TSha256Digest;
+}
+
+/**
+ * Administrator intent to designate one service as the cluster's ingress. The caller supplies only
+ * compare-and-swap inputs; Cloudly owns credential generation and acceptance.
+ */
+export interface IClusterIngressDesignationRequest {
+  mutationId: string;
+  clusterId: string;
+  ingressServiceId: string;
+  currentRuntime: IClusterRuntimeReference & { phase: 'pallet' };
+  expectedSpecRevision: number;
+  /** Null for creation; the exact current designation for rotation or a change of service. */
+  expectedDesignation: IRuntimeAuthorityReference | null;
+}
+
+export const clusterIngressDesignationContract = Object.freeze({
+  digestDomain: 'serve.zone/cluster-ingress-designation',
+  error: 'Cluster ingress designation contract rejected.',
+} as const);
+
+const fail = (): never => { throw new Error(clusterIngressDesignationContract.error); };
+const safe = <T>(operationArg: () => T): T => { try { return operationArg(); } catch { return fail(); } };
+
+const palletRuntime = (valueArg: unknown, clusterIdArg: string): IClusterRuntimeReference & { phase: 'pallet' } => {
+  const runtime = snapshotClusterRuntimeReference(valueArg);
+  requireNetwork(runtime.id === clusterIdArg && runtime.phase === 'pallet');
+  return { id: runtime.id, phase: 'pallet', generation: runtime.generation };
+};
+
+const credentialOf = (valueArg: unknown): IClusterIngressCredentialReference => {
+  const value = networkRecord(valueArg, ['credentialId', 'generation', 'secretVersion']);
+  const secretVersion = networkRecord(value.secretVersion, ['secretId', 'secretVersionId']);
+  return {
+    credentialId: networkId(value.credentialId),
+    generation: networkCounter(value.generation),
+    secretVersion: {
+      secretId: networkId(secretVersion.secretId),
+      secretVersionId: networkId(secretVersion.secretVersionId),
+    },
+  };
+};
+
+/** Detached exact-schema snapshot of a designation request. */
+export const snapshotClusterIngressDesignationRequest = (
+  valueArg: unknown,
+): IClusterIngressDesignationRequest => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['mutationId', 'clusterId', 'ingressServiceId',
+    'currentRuntime', 'expectedSpecRevision', 'expectedDesignation']);
+  const clusterId = networkId(value.clusterId);
+  return {
+    mutationId: networkId(value.mutationId),
+    clusterId,
+    ingressServiceId: networkId(value.ingressServiceId),
+    currentRuntime: palletRuntime(value.currentRuntime, clusterId),
+    expectedSpecRevision: networkCounter(value.expectedSpecRevision),
+    expectedDesignation: value.expectedDesignation === null ? null : networkReference(value.expectedDesignation),
+  };
+});
+
+/** Detached exact-schema snapshot. The digest is a separate check. */
+export const snapshotClusterIngressDesignation = (valueArg: unknown): IClusterIngressDesignation => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['id', 'generation', 'previous', 'clusterId', 'runtime',
+    'ingressServiceId', 'preparedSpecRevision', 'credential', 'actorId', 'acceptedAt', 'digest']);
+  const { id, generation, previous } = networkRevision(value);
+  const clusterId = networkId(value.clusterId);
+  return {
+    id,
+    generation,
+    previous,
+    clusterId,
+    runtime: palletRuntime(value.runtime, clusterId),
+    ingressServiceId: networkId(value.ingressServiceId),
+    preparedSpecRevision: networkCounter(value.preparedSpecRevision),
+    credential: credentialOf(value.credential),
+    actorId: networkId(value.actorId),
+    acceptedAt: networkCounter(value.acceptedAt),
+    digest: networkDigest(value.digest),
+  };
+});
+
+export const computeClusterIngressDesignationDigest = async (valueArg: unknown): Promise<TSha256Digest> => {
+  const designation = snapshotClusterIngressDesignation(valueArg);
+  try {
+    return await networkHash(clusterIngressDesignationContract.digestDomain, designation);
+  } catch {
+    return fail();
+  }
+};
+
+export const validateClusterIngressDesignation = async (valueArg: unknown): Promise<string[]> => {
+  try {
+    const designation = snapshotClusterIngressDesignation(valueArg);
+    return designation.digest === await computeClusterIngressDesignationDigest(designation)
+      ? [] : ['cluster ingress designation digest does not match'];
+  } catch {
+    return ['cluster ingress designation must use its exact canonical schema'];
+  }
+};