@serve.zone/interfaces 31.7.0 → 31.9.0

package/ts/requests/network.ts

@@ -1,5 +1,7 @@
 import * as plugins from '../plugins.js';
-import type { IIdentityCredential } from '../data/user.js';
+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 {
   IPrivateNetworkV1, IServicePrivateNetworksV1, ISetServicePrivateNetworksV1,
   TPrivateNetworkMutationV1,
@@ -98,3 +100,50 @@ export interface IRequest_Any_Cloudly_GetNetworkNodes {
     networkNodes: plugins.tsclass.network.INetworkNode[];
   };
 }
+
+/**
+ * Writes the runtime network's address plan.
+ *
+ * `expectedRevision` is the revision the caller read, or `null` when no plan exists yet. Cloudly
+ * 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.
+ */
+export interface IReq_Any_Cloudly_SetRuntimeNetworkAddressPlan extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_SetRuntimeNetworkAddressPlan
+> {
+  method: 'setRuntimeNetworkAddressPlan';
+  request: { identity: IIdentity; expectedRevision: number | null; plan: TRuntimeNetworkAddressPlanWritableData };
+  response: { plan: IRuntimeNetworkAddressPlan };
+}
+
+/** `null` until an administrator sets the first plan; the runtime network stays unconfigured until then. */
+export interface IReq_Any_Cloudly_GetRuntimeNetworkAddressPlan extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_GetRuntimeNetworkAddressPlan
+> {
+  method: 'getRuntimeNetworkAddressPlan';
+  request: { identity: IIdentity };
+  response: { plan: IRuntimeNetworkAddressPlan | null };
+}
+
+/** Whether one node's runtime network is ready for workloads, and every condition still missing. */
+export interface IReq_Any_Cloudly_GetRuntimeNetworkNodeReadiness extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_GetRuntimeNetworkNodeReadiness
+> {
+  method: 'getRuntimeNetworkNodeReadiness';
+  request: { identity: IIdentity; nodeId: string };
+  response: IRuntimeNetworkNodeReadiness;
+}
+
+/**
+ * Advances one node's router incarnation, so the node producer reserves the router a fresh handoff.
+ * `expectedIncarnation` is the incarnation the caller read; any other refuses the request.
+ */
+export interface IReq_Any_Cloudly_ReincarnateRuntimeNetworkRouter extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_ReincarnateRuntimeNetworkRouter
+> {
+  method: 'reincarnateRuntimeNetworkRouter';
+  request: { identity: IIdentity; nodeId: string; expectedIncarnation: number };
+  response: { incarnation: IRuntimeRouterIncarnation };
+}

package/ts/requests/runtimesession.ts

@@ -41,6 +41,23 @@ export interface IReq_Controller_Pallet_ApplyRuntimeNetworkProjectionV1 extends
   response: network.IApplyRuntimeNetworkAuthorityResponseV1;
 }
 
+/**
+ * A fresh DNS window for the node's exact admitted projection; an ACK asserts admission only.
+ *
+ * The controller sends it while it is reachable. A cluster relay sends the renewals it holds
+ * while it has no controller session, under the binding the node obtained itself, which is why
+ * a node admits it from whoever holds its current connection and trusts only the signature.
+ * Either sender delivers a window once its slot has opened and never before, because a node
+ * refuses a renewal it could not use at once; delivering it again once the slot opens is enough.
+ */
+export interface IReq_Controller_Pallet_ApplyRuntimeNetworkDnsLeaseRenewal extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Controller_Pallet_ApplyRuntimeNetworkDnsLeaseRenewal
+> {
+  method: 'applyRuntimeNetworkDnsLeaseRenewal';
+  request: network.IApplyRuntimeNetworkDnsLeaseRenewalRequest;
+  response: network.IApplyRuntimeNetworkDnsLeaseRenewalResponse;
+}
+
 /**
  * WSS-only Pallet bootstrap. Derive physical peer/idempotency server-side; the registering
  * node process is named by `request.nodeInstanceNonce`, because one relay socket may carry

package/ts/requests/service.ts

@@ -16,6 +16,12 @@ import type {
   IServiceDeploymentStatus,
 } from '../data/deploymentoperation.js';
 import type { TSha256Digest } from '../data/immutableimage.js';
+import type {
+  IServiceRuntimeAssignmentView,
+  IServiceRuntimeSpec,
+  IServiceRuntimeStatus,
+  TServiceRuntimeSpecWritableData,
+} from '../data/serviceruntime.js';
 import type {
   IServiceDeploymentAdoptionInput,
   IServiceDeploymentAdoptionImagePromotionInput,
@@ -370,3 +376,78 @@ extends plugins.typedrequestInterfaces.implementsTR<
     success: boolean;
   };
 }
+
+/**
+ * Writes the complete runtime spec of one service.
+ *
+ * `expectedRevision` is the revision the caller read, or `null` when the service has never had a
+ * spec; any other stored revision refuses the write. Cloudly copies the organization from the
+ * service and answers with the stored spec at its new revision.
+ */
+export interface IRequest_Any_Cloudly_SetServiceRuntimeSpec
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IRequest_Any_Cloudly_SetServiceRuntimeSpec
+> {
+  method: 'setServiceRuntimeSpec';
+  request: {
+    identity: IIdentity;
+    serviceId: string;
+    expectedRevision: number | null;
+    spec: TServiceRuntimeSpecWritableData;
+  };
+  response: {
+    spec: IServiceRuntimeSpec;
+  };
+}
+
+/**
+ * A service's runtime spec and the producer's verdict on it. Both are `null` before the first spec;
+ * a spec's status is `null` until the producer first decides it.
+ */
+export interface IRequest_Any_Cloudly_GetServiceRuntimeSpec
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IRequest_Any_Cloudly_GetServiceRuntimeSpec
+> {
+  method: 'getServiceRuntimeSpec';
+  request: {
+    identity: IIdentity;
+    serviceId: string;
+  };
+  response:
+    | { spec: null; status: null }
+    | { spec: IServiceRuntimeSpec; status: IServiceRuntimeStatus | null };
+}
+
+/** Every current runtime assignment of one service, one per replica slot. */
+export interface IRequest_Any_Cloudly_GetServiceRuntimeAssignments
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IRequest_Any_Cloudly_GetServiceRuntimeAssignments
+> {
+  method: 'getServiceRuntimeAssignments';
+  request: {
+    identity: IIdentity;
+    serviceId: string;
+  };
+  response: {
+    assignments: IServiceRuntimeAssignmentView[];
+  };
+}
+
+/**
+ * Cloudly -> admin UIs: a service's runtime spec, status or assignments changed. It carries no
+ * state, so a late or repeated push can never overwrite a newer read; the UI reads the views again.
+ */
+export interface IReq_Cloudly_Any_PushServiceRuntimeChanged
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Cloudly_Any_PushServiceRuntimeChanged
+> {
+  method: 'pushServiceRuntimeChanged';
+  request: {
+    serviceId: string;
+  };
+  response: Record<string, never>;
+}

package/ts/runtime.networkprojection.ts

@@ -1,11 +1,15 @@
 import * as plugins from './plugins.runtime.js';
-import type { IRuntimeAuthorityReferenceV1 } from './data/runtimeassignment.js';
+import type { IRuntimeAuthorityReferenceV1, IRuntimeControllerV1 } from './data/runtimeassignment.js';
 import type { IRuntimeNetworkProjectionV1 } from './data/networkprojection.js';
 import { snapshotRuntimeNetworkNodeScopeV1, snapshotRuntimeNetworkProjectionV1, validateRuntimeNetworkProjectionV1 } from './data/networkprojection.js';
 import type { IRuntimeNetworkSigningAuthorityV1, ISignedRuntimeNetworkProjectionV1 } from './data/networksigning.js';
 import { computeRuntimeNetworkSigningAuthorityV1Digest, runtimeNetworkSigningV1Contract,
   snapshotRuntimeNetworkSigningAuthorityV1, snapshotSignedRuntimeNetworkProjectionV1 } from './data/networksigning.js';
-import { failNetwork, networkCanonical, networkEqual, networkReferenceOf, requireNetwork } from './private/networkcontract.js';
+import type { IRuntimeNetworkDnsLeaseRenewal, ISignedRuntimeNetworkDnsLeaseRenewal } from './data/networklease.js';
+import { runtimeNetworkDnsLeaseRenewalContract, snapshotRuntimeNetworkDnsLeaseRenewal,
+  snapshotSignedRuntimeNetworkDnsLeaseRenewal, validateRuntimeNetworkDnsLeaseRenewal } from './data/networklease.js';
+import { captureNetwork, failNetwork, networkCanonical, networkEqual, networkReference, networkReferenceOf,
+  networkSameScope, requireNetwork } from './private/networkcontract.js';
 
 /** The private KeyObject is process-local. Persist only through the controller's encrypted secret store. */
 export const createRuntimeNetworkSigningKeyV1 = (): { publicKey: string; privateKey: plugins.crypto.KeyObject } => {
@@ -15,11 +19,47 @@ export const createRuntimeNetworkSigningKeyV1 = (): { publicKey: string; private
   return { publicKey: Buffer.from(jwk.x, 'base64url').toString('hex'), privateKey: pair.privateKey };
 };
 
-const signatureBytes = (authority: IRuntimeAuthorityReferenceV1, projection: IRuntimeNetworkProjectionV1): Uint8Array =>
-  new TextEncoder().encode(networkCanonical({ domain: runtimeNetworkSigningV1Contract.signatureDomain, schemaVersion: 1, authority, projection }));
-const validateAuthority = async (authority: IRuntimeNetworkSigningAuthorityV1, projection: IRuntimeNetworkProjectionV1): Promise<void> => {
-  requireNetwork(authority.publicKey !== null && networkEqual(authority.controller, projection.controller)
+/** What every signed network statement carries besides its content. */
+interface IAuthoritySignature {
+  authority: IRuntimeAuthorityReferenceV1;
+  signature: string;
+}
+
+const projectionEnvelope = (authority: IRuntimeAuthorityReferenceV1, projection: IRuntimeNetworkProjectionV1) =>
+  ({ domain: runtimeNetworkSigningV1Contract.signatureDomain, schemaVersion: 1, authority, projection });
+const renewalEnvelope = (authority: IRuntimeAuthorityReferenceV1, renewal: IRuntimeNetworkDnsLeaseRenewal) =>
+  ({ domain: runtimeNetworkDnsLeaseRenewalContract.signatureDomain, authority, renewal });
+const envelopeBytes = (envelope: object): Uint8Array => new TextEncoder().encode(networkCanonical(envelope));
+
+/** A revoked revision has no key; any other must be intact and belong to the controller that owns the content. */
+const liveKeyOf = async (authority: IRuntimeNetworkSigningAuthorityV1, contentController: IRuntimeControllerV1): Promise<string> => {
+  const { publicKey } = authority;
+  requireNetwork(publicKey !== null && networkEqual(authority.controller, contentController)
     && authority.digest === await computeRuntimeNetworkSigningAuthorityV1Digest(authority));
+  return publicKey;
+};
+
+/** Sign as the authority's revision, and only with the private half of its live key. */
+const signAs = async (
+  authority: IRuntimeNetworkSigningAuthorityV1, privateKey: plugins.crypto.KeyObject, contentController: IRuntimeControllerV1,
+  envelopeOf: (reference: IRuntimeAuthorityReferenceV1) => object,
+): Promise<IAuthoritySignature> => {
+  requireNetwork(privateKey instanceof plugins.crypto.KeyObject && privateKey.type === 'private' && privateKey.asymmetricKeyType === 'ed25519');
+  const derived = plugins.crypto.createPublicKey(privateKey).export({ format: 'jwk' });
+  const publicKey = await liveKeyOf(authority, contentController);
+  requireNetwork(typeof derived.x === 'string' && Buffer.from(derived.x, 'base64url').toString('hex') === publicKey);
+  const reference = networkReferenceOf(authority);
+  return { authority: reference, signature: plugins.crypto.sign(null, envelopeBytes(envelopeOf(reference)), privateKey).toString('hex') };
+};
+
+/** The receiver's own trusted revision decides; the envelope only names which revision it claims. */
+const requireSignedBy = async (
+  trusted: IRuntimeNetworkSigningAuthorityV1, signed: IAuthoritySignature, contentController: IRuntimeControllerV1, envelope: object,
+): Promise<void> => {
+  requireNetwork(networkEqual(signed.authority, networkReferenceOf(trusted)));
+  const key = plugins.crypto.createPublicKey({ format: 'jwk', key: { kty: 'OKP', crv: 'Ed25519',
+    x: Buffer.from(await liveKeyOf(trusted, contentController), 'hex').toString('base64url') } });
+  requireNetwork(plugins.crypto.verify(null, envelopeBytes(envelope), key, Buffer.from(signed.signature, 'hex')));
 };
 
 /** Sign only validated complete state and a matching dedicated private key. */
@@ -28,14 +68,9 @@ export const signRuntimeNetworkProjectionV1 = async (
 ): Promise<ISignedRuntimeNetworkProjectionV1> => {
   try {
     const input = snapshotRuntimeNetworkProjectionV1(projectionValue), authority = snapshotRuntimeNetworkSigningAuthorityV1(authorityValue);
-    requireNetwork(privateKey instanceof plugins.crypto.KeyObject && privateKey.type === 'private' && privateKey.asymmetricKeyType === 'ed25519');
-    const publicKey = plugins.crypto.createPublicKey(privateKey).export({ format: 'jwk' });
-    requireNetwork(typeof publicKey.x === 'string' && Buffer.from(publicKey.x, 'base64url').toString('hex') === authority.publicKey);
     const projection = await validateRuntimeNetworkProjectionV1(input);
-    await validateAuthority(authority, projection);
-    const reference = networkReferenceOf(authority);
-    const signature = plugins.crypto.sign(null, signatureBytes(reference, projection), privateKey).toString('hex');
-    return { schemaVersion: 1, authority: reference, projection, signature };
+    const signed = await signAs(authority, privateKey, projection.controller, reference => projectionEnvelope(reference, projection));
+    return { schemaVersion: 1, authority: signed.authority, projection, signature: signed.signature };
   } catch { return failNetwork(); }
 };
 
@@ -51,14 +86,46 @@ export const verifyRuntimeNetworkProjectionV1 = async (
     const signed = snapshotSignedRuntimeNetworkProjectionV1(value);
     const authority = snapshotRuntimeNetworkSigningAuthorityV1(trustedAuthorityValue);
     const trusted = snapshotRuntimeNetworkNodeScopeV1(trustedScopeValue);
-    requireNetwork(networkEqual(signed.authority, networkReferenceOf(authority))
-      && signed.projection.nodeId === trusted.nodeId && signed.projection.runtimeNamespace === trusted.runtimeNamespace
-      && networkEqual(signed.projection.controller, trusted.controller));
-    await validateAuthority(authority, signed.projection);
-    const key = plugins.crypto.createPublicKey({ format: 'jwk', key: { kty: 'OKP', crv: 'Ed25519',
-      x: Buffer.from(authority.publicKey!, 'hex').toString('base64url') } });
-    requireNetwork(plugins.crypto.verify(null, signatureBytes(signed.authority, signed.projection), key, Buffer.from(signed.signature, 'hex')));
+    requireNetwork(networkSameScope(signed.projection, trusted));
+    await requireSignedBy(authority, signed, signed.projection.controller, projectionEnvelope(signed.authority, signed.projection));
     await validateRuntimeNetworkProjectionV1(signed.projection);
     return signed;
   } catch { return failNetwork(); }
 };
+
+/** Sign only a validated renewal, with the same authority and key that sign this controller's projections. */
+export const signRuntimeNetworkDnsLeaseRenewal = async (
+  renewalValue: unknown, authorityValue: unknown, privateKey: plugins.crypto.KeyObject,
+): Promise<ISignedRuntimeNetworkDnsLeaseRenewal> => {
+  try {
+    const input = snapshotRuntimeNetworkDnsLeaseRenewal(renewalValue), authority = snapshotRuntimeNetworkSigningAuthorityV1(authorityValue);
+    const renewal = await validateRuntimeNetworkDnsLeaseRenewal(input);
+    const signed = await signAs(authority, privateKey, renewal.controller, reference => renewalEnvelope(reference, renewal));
+    return { authority: signed.authority, renewal, signature: signed.signature };
+  } catch { return failNetwork(); }
+};
+
+/**
+ * trustedAuthorityValue is receiver-owned persisted trust, NEVER envelope material, and a relay
+ * that delivers the renewal adds no trust to it. projectionAuthorityValue is the authority
+ * reference that signed the projection this renewal extends, which the receiver kept when it
+ * admitted that projection: a renewal is only ever valid under the exact revision that signed its
+ * projection, so a rotated key renews nothing and DNS still waits for a newly signed projection.
+ * This verifies content, scope and signature only: the owner still admits it against its own
+ * admitted projection with `admitRuntimeNetworkDnsLeaseRenewal`, fences the live session and
+ * converts the window with a qualified clock.
+ */
+export const verifyRuntimeNetworkDnsLeaseRenewal = async (
+  value: unknown, trustedAuthorityValue: unknown, trustedScopeValue: unknown, projectionAuthorityValue: unknown,
+): Promise<ISignedRuntimeNetworkDnsLeaseRenewal> => {
+  try {
+    const signed = snapshotSignedRuntimeNetworkDnsLeaseRenewal(value);
+    const authority = snapshotRuntimeNetworkSigningAuthorityV1(trustedAuthorityValue);
+    const trusted = snapshotRuntimeNetworkNodeScopeV1(trustedScopeValue);
+    const projectionAuthority = networkReference(captureNetwork(projectionAuthorityValue));
+    requireNetwork(networkSameScope(signed.renewal, trusted) && networkEqual(signed.authority, projectionAuthority));
+    await requireSignedBy(authority, signed, signed.renewal.controller, renewalEnvelope(signed.authority, signed.renewal));
+    await validateRuntimeNetworkDnsLeaseRenewal(signed.renewal);
+    return signed;
+  } catch { return failNetwork(); }
+};