@serve.zone/interfaces 32.19.0 → 32.20.1

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,