@serve.zone/interfaces 32.18.0 → 32.20.0

package/ts/data/networkprojection.ts

@@ -7,6 +7,8 @@ import { bindRuntimeNetworkHandoffLease, computeRuntimeNetworkProtectedAuthority
 import type { IPrivateNetwork, IServicePrivateNetworks, IServicePrivateNetworkDnsPolicy } from './privatenetwork.js';
 import { routerPacketGrantsOf, snapshotRouterProjection,
   type IRuntimeNetworkRouterPacketGrant, type IRuntimeNetworkRouterProjection } from './networkrouter.js';
+import { hostPacketGrantsOf, snapshotHostProjection,
+  type IRuntimeNetworkHostPacketGrant, type IRuntimeNetworkHostProjection } from './networkhost.js';
 import { buildPrivateNetworkFqdn, composeServicePrivateNetworkDnsPolicy,
   snapshotPrivateNetwork, snapshotServicePrivateNetworks } from './privatenetwork.js';
 import { captureNetwork, failNetwork, networkCanonical, networkContains, networkCounter, networkDigest,
@@ -159,6 +161,12 @@ export interface IRuntimeNetworkProjection extends IRuntimeNetworkNodeScope {
    * projection's canonical bytes and grants no router-origin flows.
    */
   router?: IRuntimeNetworkRouterProjection;
+  /**
+   * Host-origin selections of a `onebox` projection: the node's own host dials exact local workload
+   * ports (`IRuntimeNetworkHostPacketGrant`). Omitted, it keeps the canonical bytes and grants no
+   * host-origin flow; any other controller kind carrying it is refused.
+   */
+  host?: IRuntimeNetworkHostProjection;
   digest: TSha256Digest;
 }
 
@@ -313,9 +321,10 @@ export const snapshotRuntimeNetworkProjection = (value: unknown): IRuntimeNetwor
   const captured = captureNetwork(value);
   requireNetwork(new TextEncoder().encode(networkCanonical(captured)).length <= runtimeNetworkProjectionContract.maximumCanonicalBytes);
   const hasRouter = captured !== null && typeof captured === 'object' && Object.hasOwn(captured, 'router');
+  const hasHost = captured !== null && typeof captured === 'object' && Object.hasOwn(captured, 'host');
   const item = networkRecord(captured, ['id', 'generation', 'previous', 'controller', 'nodeId', 'runtimeNamespace',
     'protectedAuthority', 'allocationAuthorities', 'handoff', 'networks', 'memberships', 'endpoints', 'dns', 'withdrawals', 'retiredLeases', 'retiredHandoffs', 'digest',
-    ...(hasRouter ? ['router'] : [])]);
+    ...(hasRouter ? ['router'] : []), ...(hasHost ? ['host'] : [])]);
   return { ...networkRevision(item), ...networkScope(item),
     protectedAuthority: snapshotRuntimeNetworkProtectedAuthority(item.protectedAuthority),
     allocationAuthorities: networkSorted(networkList(item.allocationAuthorities, 16, snapshotRuntimeNetworkProtectedAuthority), refKey),
@@ -325,6 +334,7 @@ export const snapshotRuntimeNetworkProjection = (value: unknown): IRuntimeNetwor
     endpoints: networkSorted(networkList(item.endpoints, 256, endpoint), value => value.lease.id), dns: networkDnsWindow(item.dns),
     withdrawals: networkSorted(networkList(item.withdrawals, 4096, packetGrant), networkCanonical),
     ...(hasRouter ? { router: snapshotRouterProjection(item.router) } : {}),
+    ...(hasHost ? { host: snapshotHostProjection(item.host) } : {}),
     retiredLeases: sortedReferences(item.retiredLeases), retiredHandoffs: sortedReferences(item.retiredHandoffs), digest: networkDigest(item.digest) };
 });
 
@@ -402,6 +412,8 @@ export const validateRuntimeNetworkProjection = async (value: unknown): Promise<
     const assignments = new Set<string>(), attempts = new Set<string>(), readyReplicas = new Set<string>(), hostPorts = new Set<string>();
     for (const endpoint of projection.endpoints) {
       const lease = endpoint.lease, authority = allocationAuthority(lease.protectedAuthority);
+      // A controller on the node itself has no other node: every endpoint it projects is local.
+      requireNetwork(projection.controller.kind !== 'onebox' || networkSameScope(lease, projection));
       requireNetwork(networkEqual(lease.controller, projection.controller) && members.has(ownerKey(lease))
         && !assignments.has(lease.assignmentId) && !attempts.has(attemptKey(lease)));
       assignments.add(lease.assignmentId); attempts.add(attemptKey(lease));
@@ -430,6 +442,8 @@ export const validateRuntimeNetworkProjection = async (value: unknown): Promise<
     requireNetwork(projection.withdrawals.every(grant => !grants.has(networkCanonical(grant))));
     const routerGrants = new Set(routerPacketGrantsOf(projection).map(networkCanonical));
     requireNetwork((projection.router?.withdrawals ?? []).every(grant => !routerGrants.has(networkCanonical(grant))));
+    const hostGrants = new Set(hostPacketGrantsOf(projection).map(networkCanonical));
+    requireNetwork((projection.host?.withdrawals ?? []).every(grant => !hostGrants.has(networkCanonical(grant))));
     requireNetwork(projection.digest === await computeRuntimeNetworkProjectionDigest(projection));
     return projection;
   } catch { return failNetwork(); }
@@ -443,6 +457,10 @@ export const getRuntimeNetworkProjectionPacketGrants = async (value: unknown): P
 export const getRuntimeNetworkProjectionRouterPacketGrants = async (value: unknown): Promise<IRuntimeNetworkRouterPacketGrant[]> =>
   routerPacketGrantsOf(await validateRuntimeNetworkProjection(value));
 
+/** Host-origin authority comes only from explicit signed `onebox` selections of local workload ports. */
+export const getRuntimeNetworkProjectionHostPacketGrants = async (value: unknown): Promise<IRuntimeNetworkHostPacketGrant[]> =>
+  hostPacketGrantsOf(await validateRuntimeNetworkProjection(value));
+
 /** Complete offline DNS material, including authorized names never previously queried. */
 /** Select exact local receivers before expansion; all targets still come from
  * the complete validated projection. Selection supplies no attachment authority. */
@@ -507,7 +525,7 @@ export const admitRuntimeNetworkProjection = async (
     requireNetwork(networkSameScope(projection, trusted));
     if (previousInput === null) {
       requireNetwork(projection.generation === 1 && applied === null && projection.withdrawals.length === 0
-        && (projection.router?.withdrawals.length ?? 0) === 0
+        && (projection.router?.withdrawals.length ?? 0) === 0 && (projection.host?.withdrawals.length ?? 0) === 0
         && projection.retiredLeases.length === 0 && projection.retiredHandoffs.length === 0);
       return { status: 'accepted', projection };
     }
@@ -543,6 +561,12 @@ export const admitRuntimeNetworkProjection = async (
     for (const grant of previousRouterGrants) requireNetwork(routerGrants.has(networkCanonical(grant)) || routerWithdrawals.has(networkCanonical(grant)));
     const knownRouterWithdrawals = new Set([...previousRouterGrants, ...(previous.router?.withdrawals ?? [])].map(networkCanonical));
     requireNetwork((projection.router?.withdrawals ?? []).every(grant => knownRouterWithdrawals.has(networkCanonical(grant))));
+    const hostGrants = new Set(hostPacketGrantsOf(projection).map(networkCanonical));
+    const hostWithdrawals = new Set((projection.host?.withdrawals ?? []).map(networkCanonical));
+    const previousHostGrants = hostPacketGrantsOf(previous);
+    for (const grant of previousHostGrants) requireNetwork(hostGrants.has(networkCanonical(grant)) || hostWithdrawals.has(networkCanonical(grant)));
+    const knownHostWithdrawals = new Set([...previousHostGrants, ...(previous.host?.withdrawals ?? [])].map(networkCanonical));
+    requireNetwork((projection.host?.withdrawals ?? []).every(grant => knownHostWithdrawals.has(networkCanonical(grant))));
     const knownLeases = [...previous.endpoints.map(endpoint => networkReferenceOf(endpoint.lease)), ...previous.retiredLeases];
     const knownHandoffs = [...(previous.handoff ? [networkReferenceOf(previous.handoff)] : []), ...previous.retiredHandoffs];
     requireNetwork(projection.retiredLeases.every(retired => knownLeases.some(known => networkEqual(known, retired)))
@@ -553,6 +577,7 @@ export const admitRuntimeNetworkProjection = async (
     if (applied === null) {
       for (const grant of previous.withdrawals) requireNetwork(withdrawn.has(networkCanonical(grant)));
       for (const grant of previous.router?.withdrawals ?? []) requireNetwork(routerWithdrawals.has(networkCanonical(grant)));
+      for (const grant of previous.host?.withdrawals ?? []) requireNetwork(hostWithdrawals.has(networkCanonical(grant)));
       requireCarried(previous.retiredLeases, projection.retiredLeases); requireCarried(previous.retiredHandoffs, projection.retiredHandoffs);
     }
     for (const old of previous.endpoints) {

package/ts/data/noderuntimebinding.ts

@@ -4,9 +4,10 @@ import type { IClusterRuntimeReference } from './clusterruntime.js';
 import { snapshotClusterRuntimeReference } from './clusterruntime.js';
 import type { IPalletNodeEnrollmentActive } from './nodeenrollment.js';
 import { snapshotPalletNodeEnrollmentConfirmation } from './nodeenrollment.js';
-import type { IRuntimeController } from './runtimeassignment.js';
-import { deepFreezeValue } from '../private/canonicaljson.js';
-import { readExactDataRecord } from '../private/dataproperties.js';
+import type { IRuntimeAssignment, IRuntimeController } from './runtimeassignment.js';
+import { isCanonicalRegistryHost } from './immutableimage.js';
+import { compareWireTokens, deepFreezeValue } from '../private/canonicaljson.js';
+import { isPlainRecord, readDataElements, readDataProperty, readExactDataRecord } from '../private/dataproperties.js';
 import { isClusterNodeId } from '../private/nodeidentifier.js';
 import { networkController, networkId } from '../private/networkcontract.js';
 
@@ -48,6 +49,70 @@ export const nodeRuntimeBindingContract = Object.freeze({
   runtimeAuthority: 'fresh-authenticated-controller-session-only',
 } as const);
 
+/**
+ * Durable routing identity for one Pallet node driven by a controller on the same host.
+ *
+ * The local counterpart of `INodeRuntimeRoutingBinding`. It names no Cloudly origin and no relay:
+ * the controller reaches Pallet over Pallet's root-only Unix socket
+ * (`nodeRuntimeLocalControllerContract.socketPath`), whose file permissions authenticate the peer.
+ * A node carries a Cloudly binding or a local one, never both. Like the Cloudly binding it grants
+ * nothing by itself; runtime authority still comes only from a fresh session on that socket.
+ */
+export interface INodeRuntimeLocalRoutingBinding {
+  nodeId: string;
+  clusterId: string;
+  controller: IRuntimeController & { kind: 'onebox' };
+  runtimeNamespace: string;
+  /**
+   * The registries whose pull credential this controller issues, as canonical `host[:port]`,
+   * strictly increasing. A local controller has no Cloudly origin to stand for its registry, so a
+   * node asks it for a credential only for an image whose `registryHost`, and `pullEndpoint` when
+   * one is stated, are both listed here (`isNodeRuntimeLocalRegistryWorkload`).
+   */
+  registryHosts: string[];
+}
+
+/**
+ * The credential a node registers its local session with, as the controller may pin it.
+ * Pallet generates the bearer and keeps it; the controller only ever learns its hash.
+ */
+export interface INodeRuntimeLocalCredentialAcknowledgement {
+  generation: number;
+  /** Lowercase hex SHA-256 of the bearer's UTF-8 bytes. Sensitive transport field: never log it. */
+  tokenHash: string;
+}
+
+/** Pallet's answer to a local bind: the exact persisted binding and the credential behind it. */
+export interface INodeRuntimeLocalBindingConfirmation {
+  binding: INodeRuntimeLocalRoutingBinding;
+  credential: INodeRuntimeLocalCredentialAcknowledgement;
+}
+
+/**
+ * How a controller on the node's own host reaches Pallet.
+ *
+ * The controller is the TypedSocket client and Pallet the server, but the request directions of the
+ * runtime session family are unchanged: Pallet still registers (`registerPalletRuntimeSession`, fired
+ * at the connected controller) and reports, and the controller still applies. The first request on
+ * a connection is `bindPalletLocalRuntimeController`: the first bind persists the binding and a
+ * freshly generated bearer, every later bind must be the exact same binding and answers the same
+ * credential. The controller pins that credential at its first bind and refuses a different one
+ * afterwards, because a node that answers another credential for the same binding has lost the
+ * state this controller enrolled.
+ */
+export const nodeRuntimeLocalControllerContract = Object.freeze({
+  socketPath: '/run/serve.zone/pallet/controller.sock',
+  socketMode: 0o600,
+  /** TypedSocket server URL over the socket: it supplies only the Host header and request path. */
+  serverUrl: 'http://localhost',
+  transport: 'controller-initiated-typedsocket-on-root-only-unix-socket',
+  localMutation: 'first-bind-or-exact-replay',
+  exclusivity: 'cloudly-or-local-controller-never-both',
+  credential: 'pallet-generated-bearer-controller-pins-hash-at-first-bind',
+  registryAuthority: 'listed-registry-hosts-only',
+  maximumRegistryHosts: 16,
+} as const);
+
 const fail = (): never => { throw new Error('Node runtime binding contract rejected.'); };
 function requireValue(conditionArg: unknown): asserts conditionArg {
   if (!conditionArg) fail();
@@ -78,6 +143,26 @@ const relay = (valueArg: unknown): IClusterRelay => {
   return { origin: value.origin as string };
 };
 const cloudlyOrigin = (valueArg: unknown): string => relay({ origin: valueArg }).origin;
+const registryHosts = (valueArg: unknown): string[] => {
+  const elements = readDataElements(valueArg, nodeRuntimeLocalControllerContract.maximumRegistryHosts);
+  requireValue(elements !== null && elements.length > 0);
+  elements.forEach((hostArg, indexArg) => requireValue(isCanonicalRegistryHost(hostArg)
+    && (indexArg === 0 || compareWireTokens(elements[indexArg - 1] as string, hostArg) < 0)));
+  return elements as string[];
+};
+const localController = (valueArg: unknown): IRuntimeController & { kind: 'onebox' } => {
+  const controller = networkController(record(valueArg, ['kind', 'id', 'epoch']));
+  requireValue(controller.kind === 'onebox');
+  return { kind: 'onebox', id: controller.id, epoch: controller.epoch };
+};
+const tokenHash = (valueArg: unknown): string => {
+  requireValue(typeof valueArg === 'string' && /^[a-f0-9]{64}$/.test(valueArg));
+  return valueArg;
+};
+const localCredential = (valueArg: unknown): INodeRuntimeLocalCredentialAcknowledgement => {
+  const value = record(valueArg, ['generation', 'tokenHash']);
+  return { generation: positive(value.generation), tokenHash: tokenHash(value.tokenHash) };
+};
 const activeEnrollment = (valueArg: unknown): IPalletNodeEnrollmentActive => {
   const value = snapshotPalletNodeEnrollmentConfirmation(valueArg);
   requireValue(value.phase === 'active');
@@ -189,3 +274,78 @@ export const bindPalletNodeRuntimeBindingRead = (
     && requestedOrigin === active.cloudlyOrigin && requestedNodeId === active.nodeId);
   return response;
 };
+
+/** Exact detached snapshot of a local routing binding; shape checks are not authentication. */
+export const snapshotNodeRuntimeLocalRoutingBinding = (
+  valueArg: unknown,
+): INodeRuntimeLocalRoutingBinding => {
+  try {
+    const value = record(valueArg,
+      ['nodeId', 'clusterId', 'controller', 'runtimeNamespace', 'registryHosts']);
+    return deepFreezeValue({
+      nodeId: nodeId(value.nodeId), clusterId: networkId(value.clusterId),
+      controller: localController(value.controller), runtimeNamespace: networkId(value.runtimeNamespace),
+      registryHosts: registryHosts(value.registryHosts),
+    });
+  } catch {
+    return fail();
+  }
+};
+
+/** Exact detached snapshot of Pallet's answer to a local bind. */
+export const snapshotNodeRuntimeLocalBindingConfirmation = (
+  valueArg: unknown,
+): INodeRuntimeLocalBindingConfirmation => {
+  try {
+    const value = record(valueArg, ['binding', 'credential']);
+    return deepFreezeValue({ binding: snapshotNodeRuntimeLocalRoutingBinding(value.binding),
+      credential: localCredential(value.credential) });
+  } catch {
+    return fail();
+  }
+};
+
+/**
+ * Controller-side binding of Pallet's answer to the exact binding it sent. `pinnedArg` must come
+ * from the controller's own durable state: the credential it pinned at its first bind, or null for
+ * that first bind. A different credential for the same binding is refused, never adopted.
+ */
+export const bindNodeRuntimeLocalBindingConfirmation = (
+  responseArg: unknown,
+  requestArg: unknown,
+  pinnedArg: unknown,
+): INodeRuntimeLocalBindingConfirmation => {
+  try {
+    const response = snapshotNodeRuntimeLocalBindingConfirmation(responseArg);
+    const request = snapshotNodeRuntimeLocalRoutingBinding(requestArg);
+    requireValue(JSON.stringify(response.binding) === JSON.stringify(request));
+    if (pinnedArg !== null) {
+      const pinned = localCredential(pinnedArg);
+      requireValue(pinned.generation === response.credential.generation
+        && pinned.tokenHash === response.credential.tokenHash);
+    }
+    return response;
+  } catch {
+    return fail();
+  }
+};
+
+/**
+ * Whether a local controller may issue the pull credential for this workload's image: its
+ * `registryHost`, and its `pullEndpoint` when one is stated, are both listed in the binding.
+ * The workload is read as a wire value; anything this cannot read is not authorized.
+ */
+export const isNodeRuntimeLocalRegistryWorkload = (
+  bindingArg: unknown,
+  workloadArg: IRuntimeAssignment['workload'],
+): boolean => {
+  try {
+    const binding = snapshotNodeRuntimeLocalRoutingBinding(bindingArg);
+    const listed = (propertyArg: { value: unknown } | null): boolean => propertyArg !== null
+      && typeof propertyArg.value === 'string' && binding.registryHosts.includes(propertyArg.value);
+    return isPlainRecord(workloadArg) && listed(readDataProperty(workloadArg, 'registryHost'))
+      && (!Object.hasOwn(workloadArg, 'pullEndpoint') || listed(readDataProperty(workloadArg, 'pullEndpoint')));
+  } catch {
+    return false;
+  }
+};

package/ts/data/runtimesession.ts

@@ -11,7 +11,8 @@ import {
 import { negotiateProtocol, readProtocolOffer, type IProtocolOffer } from '../protocol.js';
 import type { IRuntimeConfig } from './runtimeconfig.js';
 import { bindRuntimeConfigToAssignment, snapshotRuntimeConfig } from './runtimeconfig.js';
-import { canonicalizeStrictJson } from '../private/canonicaljson.js';
+import { snapshotNodeRuntimeLocalBindingConfirmation, snapshotNodeRuntimeLocalRoutingBinding } from './noderuntimebinding.js';
+import { canonicalizeStrictJson, createSha256Hex } from '../private/canonicaljson.js';
 import { isClusterNodeId } from '../private/nodeidentifier.js';
 
 /**
@@ -32,7 +33,11 @@ export interface IRuntimeSessionBinding {
   runtimeNamespace: string;
 }
 
-/** Pallet-initiated WSS on its configured Cloudly HTTPS origin; never HTTP RPC. */
+/**
+ * Pallet-initiated WSS on its configured Cloudly HTTPS origin; never HTTP RPC. A node bound to a
+ * local controller fires the same request at the controller connected to its root-only Unix socket
+ * (`nodeRuntimeLocalControllerContract`), with the bearer whose hash its local bind answered.
+ */
 export interface IRegisterPalletRuntimeSessionRequest {
   nodeId: string;
   credentialGeneration: number;
@@ -395,6 +400,49 @@ export const bindRegisterPalletRuntimeSessionResponse = (
   return response;
 });
 
+/**
+ * Bind a local controller's registration reply to the node's own local routing binding.
+ *
+ * The counterpart of `bindRegisterPalletRuntimeSessionResponse` for a node bound to a controller on
+ * its own host: the answered session must name exactly the binding's controller, node, cluster and
+ * runtime namespace, the credential generation sent, and an offer compatible with the one sent.
+ * `bindingArg` must come from the node's own durable state, never from the reply.
+ */
+export const bindRegisterPalletLocalRuntimeSessionResponse = (
+  valueArg: unknown, requestArg: unknown, bindingArg: unknown,
+): IRegisterPalletRuntimeSessionResponse => safe(() => {
+  const response = snapshotRegisterPalletRuntimeSessionResponse(valueArg);
+  const request = snapshotRegisterPalletRuntimeSessionRequest(requestArg);
+  const binding = snapshotNodeRuntimeLocalRoutingBinding(bindingArg);
+  requireValue(canonical(response.session.controller) === canonical(binding.controller)
+    && request.nodeId === binding.nodeId && response.session.nodeId === binding.nodeId
+    && response.session.clusterId === binding.clusterId
+    && response.session.runtimeNamespace === binding.runtimeNamespace
+    && response.session.credentialGeneration === request.credentialGeneration
+    && negotiateProtocol(request.protocol, response.protocol).compatible);
+  return response;
+});
+
+/**
+ * Controller-side check of a local node's registration against the credential this controller
+ * pinned at its first local bind. `confirmationArg` must come from the controller's own durable
+ * state, never from the request. This proves the bearer is the one that bind acknowledged; the
+ * socket's file permissions remain the peer authentication, and session admission stays the
+ * controller's.
+ */
+export const bindRegisterPalletLocalRuntimeSessionRequest = async (
+  valueArg: unknown, confirmationArg: unknown,
+): Promise<IRegisterPalletRuntimeSessionRequest> => {
+  try {
+    const request = snapshotRegisterPalletRuntimeSessionRequest(valueArg);
+    const confirmation = snapshotNodeRuntimeLocalBindingConfirmation(confirmationArg);
+    requireValue(request.nodeId === confirmation.binding.nodeId
+      && request.credentialGeneration === confirmation.credential.generation);
+    requireValue(await createSha256Hex(encoder.encode(request.bearer), fail) === confirmation.credential.tokenHash);
+    return request;
+  } catch { return fail(); }
+};
+
 /** Reject already expired material; issuance policy and current assignment authority remain server-owned. */
 export const bindGetRuntimeRegistryCredentialResponse = (
   valueArg: unknown, nowArg: number,

package/ts/requests/runtimesession.ts

@@ -1,5 +1,6 @@
 import * as plugins from '../plugins.js';
 import type * as data from '../data/runtimesession.js';
+import type * as binding from '../data/noderuntimebinding.js';
 import type * as terminal from '../data/runtimeterminalreceipt.js';
 import type * as network from '../data/networkdelivery.js';
 import type * as protection from '../data/networkprotection.js';
@@ -136,6 +137,22 @@ export interface IReq_Pallet_Cloudly_RegisterPalletRuntimeSession extends plugin
   response: data.IRegisterPalletRuntimeSessionResponse;
 }
 
+/**
+ * A local controller's first request on Pallet's root-only Unix socket, before any session:
+ * first bind or exact replay of the node's local routing binding (`nodeRuntimeLocalControllerContract`).
+ * Pallet answers the exact persisted binding and the credential it will register with, then fires
+ * `registerPalletRuntimeSession` at this connection. A node bound to Cloudly refuses it. The
+ * response carries a token hash: exclude it from hooks and logs.
+ */
+export interface IReq_Onebox_Pallet_BindLocalRuntimeController extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Onebox_Pallet_BindLocalRuntimeController
+> {
+  method: 'bindPalletLocalRuntimeController';
+  request: binding.INodeRuntimeLocalRoutingBinding;
+  response: binding.INodeRuntimeLocalBindingConfirmation;
+}
+
 /** Controller push over the already authenticated Pallet-initiated connection. */
 export interface IReq_Controller_Pallet_ApplyRuntimeAssignment extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,