@serve.zone/interfaces 31.7.0 → 31.8.0

package/ts/data/networklease.ts

@@ -0,0 +1,229 @@
+import type { TSha256Digest } from './immutableimage.js';
+import type { IRuntimeAuthorityReferenceV1 } from './runtimeassignment.js';
+import type { IRuntimeNetworkDnsWindow, IRuntimeNetworkNodeScopeV1 } from './networkprojection.js';
+import { snapshotRuntimeNetworkNodeScopeV1, snapshotRuntimeNetworkProjectionV1, validateRuntimeNetworkProjectionV1 } from './networkprojection.js';
+import { captureNetwork, failNetwork, networkCounter, networkDigest, networkDnsWindow, networkEffectiveDnsWindow, networkEqual,
+  networkHash, networkId, networkList, networkMaximumDnsLeaseMs, networkRecord, networkReference, networkReferenceOf,
+  networkRenewsProjection, networkSafe, networkSameScope, networkScope, networkSignature, requireNetwork } from '../private/networkcontract.js';
+
+/**
+ * A fresh DNS window for one exact admitted projection, and nothing else.
+ *
+ * A projection's window is signed content, so only a newly signed statement can extend it. A
+ * re-issued projection would do that too, but a receiver treats every new projection as new
+ * network state and applies it again; a renewal leaves the applied state alone. It names the
+ * projection by exact reference, so it never joins the projection chain and stops being
+ * admissible the moment a successor projection is admitted.
+ */
+export interface IRuntimeNetworkDnsLeaseRenewal extends IRuntimeNetworkNodeScopeV1 {
+  projection: IRuntimeAuthorityReferenceV1;
+  /** Orders the renewals of one projection. A receiver may skip sequences, never go back. */
+  sequence: number;
+  /**
+   * `issuedAt` is the start of the window's slot, not the signing instant: a controller signs a
+   * run of future windows ahead of time, and the fifteen-minute rule is measured from here.
+   */
+  dns: IRuntimeNetworkDnsWindow;
+  digest: TSha256Digest;
+}
+
+/** Names one renewal without its window: what a receiver records and what an ACK repeats. */
+export interface IRuntimeNetworkDnsLeaseRenewalReference {
+  projection: IRuntimeAuthorityReferenceV1;
+  sequence: number;
+  digest: TSha256Digest;
+}
+
+export interface ISignedRuntimeNetworkDnsLeaseRenewal {
+  /** The signing authority revision that also signs this controller's projections. */
+  authority: IRuntimeAuthorityReferenceV1;
+  renewal: IRuntimeNetworkDnsLeaseRenewal;
+  /** Ed25519 signature of the complete domain-separated envelope, lowercase hex. */
+  signature: string;
+}
+
+/**
+ * The renewals a cluster relay holds for one node it carries, replacing what it held before.
+ *
+ * The relay has no signing trust and verifies no signature: it holds signed statements and hands
+ * them to the node, which verifies each one against its own pinned authority.
+ */
+export interface IHoldRuntimeNetworkDnsLeaseRenewalsRequest {
+  /** The relay's own socket names the cluster; one relay carries every node of it, so the node is named here. */
+  nodeId: string;
+  projection: IRuntimeAuthorityReferenceV1;
+  /** Ascending by sequence. Empty holds nothing for this node. */
+  renewals: ISignedRuntimeNetworkDnsLeaseRenewal[];
+}
+
+export interface IHoldRuntimeNetworkDnsLeaseRenewalsResponse {
+  held: number;
+}
+
+export const runtimeNetworkDnsLeaseRenewalContract = Object.freeze({
+  renewalDigestDomain: 'serve.zone/runtime-network-dns-lease-renewal',
+  signatureDomain: 'serve.zone/runtime-network-dns-lease-renewal-signature',
+  maximumDnsLeaseMs: networkMaximumDnsLeaseMs,
+  maximumEscrowedRenewals: 32,
+  /** From the first held window's `issuedAt` to the last one's `expiresAt`. */
+  maximumEscrowHorizonMs: 14_400_000,
+  binding: 'exact-projection-reference',
+  supersession: 'a-successor-projection-refuses-every-renewal-of-its-predecessor',
+  sequence: 'strictly-increasing-per-projection-skipping-allowed',
+  effect: 'dns-window-only-never-applied-network-state',
+  escrowRelease: 'only-the-current-window-and-only-while-the-holder-has-no-controller-session',
+  revocationLatency: 'a-detached-cluster-keeps-dns-authority-until-its-last-held-window-ends',
+} as const);
+
+export const snapshotRuntimeNetworkDnsLeaseRenewal = (value: unknown): IRuntimeNetworkDnsLeaseRenewal => networkSafe(() => {
+  const item = networkRecord(captureNetwork(value), ['controller', 'nodeId', 'runtimeNamespace', 'projection', 'sequence', 'dns', 'digest']);
+  return { ...networkScope(item), projection: networkReference(item.projection), sequence: networkCounter(item.sequence),
+    dns: networkDnsWindow(item.dns), digest: networkDigest(item.digest) };
+});
+
+export const snapshotRuntimeNetworkDnsLeaseRenewalReference = (value: unknown): IRuntimeNetworkDnsLeaseRenewalReference => networkSafe(() => {
+  const item = networkRecord(captureNetwork(value), ['projection', 'sequence', 'digest']);
+  return { projection: networkReference(item.projection), sequence: networkCounter(item.sequence), digest: networkDigest(item.digest) };
+});
+
+export const getRuntimeNetworkDnsLeaseRenewalReference = (value: IRuntimeNetworkDnsLeaseRenewal): IRuntimeNetworkDnsLeaseRenewalReference =>
+  ({ projection: networkReferenceOf(value.projection), sequence: value.sequence, digest: value.digest });
+
+export const snapshotSignedRuntimeNetworkDnsLeaseRenewal = (value: unknown): ISignedRuntimeNetworkDnsLeaseRenewal => networkSafe(() => {
+  const item = networkRecord(captureNetwork(value), ['authority', 'renewal', 'signature']);
+  return { authority: networkReference(item.authority), renewal: snapshotRuntimeNetworkDnsLeaseRenewal(item.renewal),
+    signature: networkSignature(item.signature) };
+});
+
+export const computeRuntimeNetworkDnsLeaseRenewalDigest = (value: IRuntimeNetworkDnsLeaseRenewal): Promise<TSha256Digest> =>
+  networkHash(runtimeNetworkDnsLeaseRenewalContract.renewalDigestDomain, snapshotRuntimeNetworkDnsLeaseRenewal(value));
+
+/** Structure and digest only. A digest authenticates nothing: verify the signature with stored trust. */
+export const validateRuntimeNetworkDnsLeaseRenewal = async (value: unknown): Promise<IRuntimeNetworkDnsLeaseRenewal> => {
+  try {
+    const renewal = snapshotRuntimeNetworkDnsLeaseRenewal(value);
+    requireNetwork(renewal.digest === await computeRuntimeNetworkDnsLeaseRenewalDigest(renewal));
+    return renewal;
+  } catch { return failNetwork(); }
+};
+
+/**
+ * A later window never moves its slot back and always ends later. Windows need not touch: a
+ * receiver that missed renewals while its lease lapsed must still be able to admit the next one.
+ */
+const extendsWindow = (next: IRuntimeNetworkDnsWindow, baseline: IRuntimeNetworkDnsWindow): boolean =>
+  next.issuedAt >= baseline.issuedAt && next.expiresAt > baseline.expiresAt;
+
+/** A receiver admits only a window it can use at once: its slot has opened and it has not ended. */
+const isCurrentWindow = (window: IRuntimeNetworkDnsWindow, now: number): boolean =>
+  window.notBefore <= now && now < window.expiresAt;
+
+/**
+ * The DNS window a node may use under a projection: its admitted renewal's, else the projection's
+ * own. Controller and node derive every window-bounded fact, such as a VPN credential's expiry,
+ * from this one rule. renewalValue is the bare renewal `admitRuntimeNetworkDnsLeaseRenewal`
+ * admitted, or null; Cloudly passes `signed.renewal`. Both inputs are the caller's admitted state,
+ * so this checks structure, digests and that the renewal names exactly this projection; it
+ * verifies no signature and samples no clock.
+ */
+export const getRuntimeNetworkEffectiveDnsWindow = async (
+  projectionValue: unknown, renewalValue: unknown | null,
+): Promise<IRuntimeNetworkDnsWindow> => {
+  try {
+    const projectionInput = snapshotRuntimeNetworkProjectionV1(projectionValue);
+    const renewalInput = renewalValue === null ? null : snapshotRuntimeNetworkDnsLeaseRenewal(renewalValue);
+    const projection = await validateRuntimeNetworkProjectionV1(projectionInput);
+    const renewal = renewalInput === null ? null : await validateRuntimeNetworkDnsLeaseRenewal(renewalInput);
+    return networkEffectiveDnsWindow(projection, renewal);
+  } catch { return failNetwork(); }
+};
+
+/**
+ * Pure admission decision for a renewal whose signature the caller has already verified.
+ *
+ * currentProjectionValue is the receiver's own admitted projection and previousValue the last
+ * renewal it admitted for that exact projection, or null when there is none; neither is ever
+ * taken from the incoming message. Without a previous renewal the projection's own window is the
+ * baseline. nowValue is the caller's qualified clock: a renewal is admitted only inside its own
+ * window, because storing a window that has not opened would displace the coverage the receiver
+ * has now. A sender therefore delivers a window once its slot has opened and never before, and
+ * simply delivers it again if it was refused. Re-delivering the renewal already admitted is
+ * answered `replay` whatever the time, so re-delivery stays idempotent. The caller commits the
+ * result atomically with its trust fence and discards the stored renewal in the transaction that
+ * admits a successor projection.
+ */
+export const admitRuntimeNetworkDnsLeaseRenewal = async (
+  value: unknown, currentProjectionValue: unknown, previousValue: unknown | null, trustedScopeValue: unknown, nowValue: unknown,
+): Promise<{ status: 'accepted' | 'replay'; renewal: IRuntimeNetworkDnsLeaseRenewal }> => {
+  try {
+    // Snapshot ALL caller-owned inputs before the first asynchronous operation.
+    const incoming = snapshotRuntimeNetworkDnsLeaseRenewal(value);
+    const projectionInput = snapshotRuntimeNetworkProjectionV1(currentProjectionValue);
+    const previousInput = previousValue === null ? null : snapshotRuntimeNetworkDnsLeaseRenewal(previousValue);
+    const trusted = snapshotRuntimeNetworkNodeScopeV1(trustedScopeValue);
+    const now = networkCounter(nowValue);
+    const renewal = await validateRuntimeNetworkDnsLeaseRenewal(incoming);
+    const projection = await validateRuntimeNetworkProjectionV1(projectionInput);
+    requireNetwork(networkSameScope(projection, trusted) && networkRenewsProjection(renewal, projection));
+    const previous = previousInput === null ? null : await validateRuntimeNetworkDnsLeaseRenewal(previousInput);
+    if (previous !== null) {
+      requireNetwork(networkRenewsProjection(previous, projection));
+      if (renewal.sequence === previous.sequence) {
+        requireNetwork(networkEqual(renewal, previous)); return { status: 'replay', renewal };
+      }
+      requireNetwork(renewal.sequence > previous.sequence);
+    }
+    requireNetwork(isCurrentWindow(renewal.dns, now));
+    requireNetwork(extendsWindow(renewal.dns, previous === null ? projection.dns : previous.dns));
+    return { status: 'accepted', renewal };
+  } catch { return failNetwork(); }
+};
+
+/** Consecutive held renewals: same signer and scope, a higher sequence, a window that extends the one before. */
+const followsInRun = (next: ISignedRuntimeNetworkDnsLeaseRenewal, before: ISignedRuntimeNetworkDnsLeaseRenewal): boolean =>
+  networkEqual(next.authority, before.authority) && networkSameScope(next.renewal, before.renewal)
+    && next.renewal.sequence > before.renewal.sequence && extendsWindow(next.renewal.dns, before.renewal.dns);
+
+const heldHorizonMs = (renewals: ISignedRuntimeNetworkDnsLeaseRenewal[]): number => {
+  const first = renewals.at(0), last = renewals.at(-1);
+  return first === undefined || last === undefined ? 0 : last.renewal.dns.expiresAt - first.renewal.dns.issuedAt;
+};
+
+/**
+ * A held run is what one node could admit in order: one node, one projection, one authority,
+ * ascending sequences, each window extending the one before, inside both escrow maxima.
+ */
+export const snapshotHoldRuntimeNetworkDnsLeaseRenewalsRequest = (value: unknown): IHoldRuntimeNetworkDnsLeaseRenewalsRequest => networkSafe(() => {
+  const item = networkRecord(captureNetwork(value), ['nodeId', 'projection', 'renewals']);
+  const contract = runtimeNetworkDnsLeaseRenewalContract;
+  const request: IHoldRuntimeNetworkDnsLeaseRenewalsRequest = { nodeId: networkId(item.nodeId), projection: networkReference(item.projection),
+    renewals: networkList(item.renewals, contract.maximumEscrowedRenewals, snapshotSignedRuntimeNetworkDnsLeaseRenewal) };
+  request.renewals.forEach((signed, index) => requireNetwork(signed.renewal.nodeId === request.nodeId
+    && networkEqual(signed.renewal.projection, request.projection)
+    && (index === 0 || followsInRun(signed, request.renewals[index - 1]))));
+  requireNetwork(heldHorizonMs(request.renewals) <= contract.maximumEscrowHorizonMs);
+  return request;
+});
+
+/** The run's rules plus every renewal's digest. It verifies no signature: a relay holds no trust. */
+export const validateHoldRuntimeNetworkDnsLeaseRenewalsRequest = async (value: unknown): Promise<IHoldRuntimeNetworkDnsLeaseRenewalsRequest> => {
+  try {
+    const request = snapshotHoldRuntimeNetworkDnsLeaseRenewalsRequest(value);
+    for (const signed of request.renewals) await validateRuntimeNetworkDnsLeaseRenewal(signed.renewal);
+    return request;
+  } catch { return failNetwork(); }
+};
+
+export const snapshotHoldRuntimeNetworkDnsLeaseRenewalsResponse = (value: unknown): IHoldRuntimeNetworkDnsLeaseRenewalsResponse => networkSafe(() => {
+  const item = networkRecord(captureNetwork(value), ['held']);
+  requireNetwork(typeof item.held === 'number' && Number.isSafeInteger(item.held) && item.held >= 0
+    && item.held <= runtimeNetworkDnsLeaseRenewalContract.maximumEscrowedRenewals);
+  return { held: item.held };
+});
+
+/** Compare the answer with the exact SENT run: a relay that held fewer did not take the run over. */
+export const bindHoldRuntimeNetworkDnsLeaseRenewalsResponse = (value: unknown, sentRequestValue: unknown): IHoldRuntimeNetworkDnsLeaseRenewalsResponse => networkSafe(() => {
+  const response = snapshotHoldRuntimeNetworkDnsLeaseRenewalsResponse(value);
+  requireNetwork(response.held === snapshotHoldRuntimeNetworkDnsLeaseRenewalsRequest(sentRequestValue).renewals.length);
+  return response;
+});

package/ts/data/networkprojection.ts

@@ -9,10 +9,10 @@ import { routerPacketGrantsOf, snapshotRouterProjection,
   type IRuntimeNetworkRouterPacketGrantV1, type IRuntimeNetworkRouterProjectionV1 } from './networkrouter.js';
 import { buildPrivateNetworkFqdnV1, composeServicePrivateNetworkDnsPolicyV1,
   snapshotPrivateNetworkV1, snapshotServicePrivateNetworksV1 } from './privatenetwork.js';
-import { captureNetwork, failNetwork, networkCanonical, networkContains, networkController, networkCounter,
-  networkDigest, networkEqual, networkHash, networkId, networkIpv4, networkIpv4Number, networkList,
-  networkOverlaps, networkPrefixBounds, networkRecord, networkReference, networkReferenceOf, networkRevision,
-  networkSafe, networkSorted, requireNetwork } from '../private/networkcontract.js';
+import { captureNetwork, failNetwork, networkCanonical, networkContains, networkCounter, networkDigest,
+  networkDnsWindow, networkEqual, networkHash, networkId, networkIpv4, networkIpv4Number, networkList, networkMaximumDnsLeaseMs,
+  networkOverlaps, networkPrefixBounds, networkRecord, networkReference, networkReferenceOf, networkRevision, networkSafe,
+  networkSameScope, networkScope, networkSorted, requireNetwork } from '../private/networkcontract.js';
 
 export interface IRuntimeNetworkNodeScopeV1 {
   controller: IRuntimeControllerV1;
@@ -20,6 +20,16 @@ export interface IRuntimeNetworkNodeScopeV1 {
   runtimeNamespace: string;
 }
 
+/**
+ * One signed DNS window, on a projection or on a renewal of it: the start of the slot it was
+ * issued for, the instant a receiver may use it, and the instant it stops being usable.
+ */
+export interface IRuntimeNetworkDnsWindow {
+  issuedAt: number;
+  notBefore: number;
+  expiresAt: number;
+}
+
 /** Immutable per-attempt address material. Membership and projection revisions are independent. */
 export interface IRuntimeNetworkWorkloadLeaseV1 extends IRuntimeNetworkNodeScopeV1 {
   schemaVersion: 1;
@@ -143,7 +153,7 @@ export interface IRuntimeNetworkProjectionV1 extends IRuntimeNetworkNodeScopeV1
   networks: IPrivateNetworkV1[];
   memberships: IServicePrivateNetworksV1[];
   endpoints: IRuntimeNetworkEndpointV1[];
-  dns: { issuedAt: number; notBefore: number; expiresAt: number };
+  dns: IRuntimeNetworkDnsWindow;
   /** Explicit denial intent. Carry until the exact predecessor's application is proven. */
   withdrawals: IRuntimeNetworkPacketGrantV1[];
   retiredLeases: IRuntimeAuthorityReferenceV1[];
@@ -173,7 +183,7 @@ export const runtimeNetworkProjectionV1Contract = Object.freeze({
   maximumGrants: 4096,
   maximumRouterGrants: 96,
   maximumRouterWithdrawals: 4096,
-  maximumDnsLeaseMs: 900_000,
+  maximumDnsLeaseMs: networkMaximumDnsLeaseMs,
   positiveTtlSeconds: 5,
   negativeTtlSeconds: 1,
   omission: 'no-effect-without-explicit-withdrawal',
@@ -182,11 +192,6 @@ export const runtimeNetworkProjectionV1Contract = Object.freeze({
   allocationReuse: 'requires-controller-quarantine-and-all-affected-authority-fences',
 } as const);
 
-const scope = (item: Record<string, unknown>): IRuntimeNetworkNodeScopeV1 => ({
-  controller: networkController(item.controller), nodeId: networkId(item.nodeId), runtimeNamespace: networkId(item.runtimeNamespace),
-});
-const sameScope = (left: IRuntimeNetworkNodeScopeV1, right: IRuntimeNetworkNodeScopeV1): boolean =>
-  networkEqual(left.controller, right.controller) && left.nodeId === right.nodeId && left.runtimeNamespace === right.runtimeNamespace;
 const ownerKey = (value: { organizationId: string; serviceId: string }): string => networkCanonical([value.organizationId, value.serviceId]);
 const attemptKey = (value: IRuntimeNetworkWorkloadLeaseV1): string =>
   networkCanonical([value.organizationId, value.serviceId, value.replicaId, value.attemptId]);
@@ -195,7 +200,7 @@ const sortedReferences = (value: unknown): IRuntimeAuthorityReferenceV1[] =>
   networkSorted(networkList(value, 256, networkReference), refKey);
 
 export const snapshotRuntimeNetworkNodeScopeV1 = (value: unknown): IRuntimeNetworkNodeScopeV1 => networkSafe(() =>
-  scope(networkRecord(captureNetwork(value), ['controller', 'nodeId', 'runtimeNamespace'])));
+  networkScope(networkRecord(captureNetwork(value), ['controller', 'nodeId', 'runtimeNamespace'])));
 
 export const snapshotRuntimeNetworkWorkloadLeaseV1 = (value: unknown): IRuntimeNetworkWorkloadLeaseV1 => networkSafe(() => {
   const item = networkRecord(captureNetwork(value), ['schemaVersion', 'id', 'generation', 'controller', 'nodeId', 'runtimeNamespace',
@@ -215,7 +220,7 @@ export const snapshotRuntimeNetworkWorkloadLeaseV1 = (value: unknown): IRuntimeN
     requireNetwork(number >= low && number <= high && (high - low === 1 || (number !== low && number !== high)));
   }
   requireNetwork(item.dnsServer === gateway);
-  return { schemaVersion: 1, id: networkId(item.id), generation: networkCounter(item.generation), ...scope(item),
+  return { schemaVersion: 1, id: networkId(item.id), generation: networkCounter(item.generation), ...networkScope(item),
     organizationId: networkId(item.organizationId), assignmentId: networkId(item.assignmentId), serviceId: networkId(item.serviceId),
     replicaId: networkId(item.replicaId), attemptId: networkId(item.attemptId), protectedAuthority: networkReference(item.protectedAuthority),
     routerIncarnationId: networkId(item.routerIncarnationId), ipv4: { poolId: networkId(ip.poolId), linkSubnet: ip.linkSubnet,
@@ -312,16 +317,13 @@ export const snapshotRuntimeNetworkProjectionV1 = (value: unknown): IRuntimeNetw
     'protectedAuthority', 'allocationAuthorities', 'handoff', 'networks', 'memberships', 'endpoints', 'dns', 'withdrawals', 'retiredLeases', 'retiredHandoffs', 'digest',
     ...(hasRouter ? ['router'] : [])]);
   requireNetwork(item.schemaVersion === 1);
-  const dns = networkRecord(item.dns, ['issuedAt', 'notBefore', 'expiresAt']);
-  const window = { issuedAt: networkCounter(dns.issuedAt), notBefore: networkCounter(dns.notBefore), expiresAt: networkCounter(dns.expiresAt) };
-  requireNetwork(window.notBefore >= window.issuedAt && window.expiresAt > window.notBefore && window.expiresAt - window.issuedAt <= 900_000);
-  return { schemaVersion: 1, ...networkRevision(item), ...scope(item),
+  return { schemaVersion: 1, ...networkRevision(item), ...networkScope(item),
     protectedAuthority: snapshotRuntimeNetworkProtectedAuthorityV1(item.protectedAuthority),
     allocationAuthorities: networkSorted(networkList(item.allocationAuthorities, 16, snapshotRuntimeNetworkProtectedAuthorityV1), refKey),
     handoff: item.handoff === null ? null : snapshotRuntimeNetworkHandoffLeaseV1(item.handoff),
     networks: networkSorted(networkList(item.networks, 128, snapshotPrivateNetworkV1), value => value.id),
     memberships: networkSorted(networkList(item.memberships, 256, snapshotServicePrivateNetworksV1), ownerKey),
-    endpoints: networkSorted(networkList(item.endpoints, 256, endpoint), value => value.lease.id), dns: window,
+    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) } : {}),
     retiredLeases: sortedReferences(item.retiredLeases), retiredHandoffs: sortedReferences(item.retiredHandoffs), digest: networkDigest(item.digest) };
@@ -336,14 +338,14 @@ const grantsOf = (projection: IRuntimeNetworkProjectionV1): IRuntimeNetworkPacke
   for (const source of projection.endpoints) {
     const member = memberships.get(ownerKey(source.lease)); requireNetwork(member);
     for (const destination of projection.endpoints) {
-      if (source === destination || (!sameScope(source.lease, projection) && !sameScope(destination.lease, projection))) continue;
+      if (source === destination || (!networkSameScope(source.lease, projection) && !networkSameScope(destination.lease, projection))) continue;
       const target = memberships.get(ownerKey(destination.lease)); requireNetwork(target);
       if (member.organizationId === target.organizationId && member.attachments.some(attachment =>
         target.attachments.some(other => other.networkId === attachment.networkId))) {
         append({ source: networkReferenceOf(source.lease), destination: { kind: 'workload', lease: networkReferenceOf(destination.lease) } });
       }
     }
-    if (!sameScope(source.lease, projection)) continue;
+    if (!networkSameScope(source.lease, projection)) continue;
     if (source.publicEgress) append({ source: networkReferenceOf(source.lease), destination: { kind: 'public' } });
     for (const id of source.platformEndpointIds) {
       const platform = projection.protectedAuthority.platformEndpoints.find(item => item.id === id); requireNetwork(platform);
@@ -373,7 +375,7 @@ export const validateRuntimeNetworkProjectionV1 = async (value: unknown): Promis
     };
     if (projection.handoff !== null) {
       await bindRuntimeNetworkHandoffLeaseV1(projection.handoff, allocationAuthority(projection.handoff.protectedAuthority));
-      requireNetwork(sameScope(projection.handoff, projection));
+      requireNetwork(networkSameScope(projection.handoff, projection));
       requireNetwork(current.pools.some(pool => pool.id === projection.handoff!.transit.poolId && pool.purpose === 'transit'
         && networkContains(pool.prefix, projection.handoff!.transit.prefix)));
     }
@@ -413,7 +415,7 @@ export const validateRuntimeNetworkProjectionV1 = async (value: unknown): Promis
         && current.egressAuthorities.some(owner => owner.nodeId === lease.nodeId && owner.runtimeNamespace === lease.runtimeNamespace));
       for (const protection of [authority, current]) requireNetwork(protection.pools.some(pool =>
         pool.id === lease.ipv4.poolId && pool.purpose === 'workload' && networkContains(pool.prefix, lease.ipv4.linkSubnet)));
-      if (sameScope(lease, projection)) requireNetwork(projection.handoff !== null && lease.routerIncarnationId === projection.handoff.routerIncarnationId);
+      if (networkSameScope(lease, projection)) requireNetwork(projection.handoff !== null && lease.routerIncarnationId === projection.handoff.routerIncarnationId);
       for (const id of endpoint.platformEndpointIds) requireNetwork(current.platformEndpoints.some(platform => platform.id === id));
       for (const port of endpoint.publishedPorts ?? []) {
         const claim = networkCanonical([lease.nodeId, port.protocol, port.hostPort]);
@@ -450,7 +452,7 @@ export const composeRuntimeNetworkProjectionDnsViewsV1 = async (
 ): Promise<IRuntimeNetworkDnsViewV1[]> => {
   const selected = sourcesValue === undefined ? null : networkList(captureNetwork(sourcesValue), 256, networkReference);
   const projection = await validateRuntimeNetworkProjectionV1(value);
-  const local = projection.endpoints.filter(endpoint => sameScope(endpoint.lease, projection));
+  const local = projection.endpoints.filter(endpoint => networkSameScope(endpoint.lease, projection));
   if (selected !== null) {
     requireNetwork(new Set(selected.map(source => source.id)).size === selected.length);
     for (const source of selected) requireNetwork(local.some(endpoint => networkEqual(networkReferenceOf(endpoint.lease), source)));
@@ -479,7 +481,7 @@ export const composeRuntimeNetworkProjectionDnsViewsV1 = async (
 export const bindRuntimeNetworkWorkloadLeaseToAssignmentV1 = async (leaseValue: unknown, assignmentValue: unknown): Promise<IRuntimeNetworkWorkloadLeaseV1> => {
   try {
     const lease = snapshotRuntimeNetworkWorkloadLeaseV1(leaseValue), assignment = snapshotRuntimeAssignmentV1(assignmentValue);
-    requireNetwork((await validateRuntimeAssignmentV1(assignment)).length === 0 && sameScope(lease, assignment)
+    requireNetwork((await validateRuntimeAssignmentV1(assignment)).length === 0 && networkSameScope(lease, assignment)
       && lease.organizationId === assignment.organizationId && lease.assignmentId === assignment.assignmentId
       && lease.serviceId === assignment.serviceId && lease.replicaId === assignment.replicaId && lease.attemptId === assignment.attemptId
       && networkEqual(networkReferenceOf(lease), assignment.workload.network)
@@ -503,7 +505,7 @@ export const admitRuntimeNetworkProjectionV1 = async (
     const trusted = snapshotRuntimeNetworkNodeScopeV1(trustedScopeValue);
     const applied = appliedPreviousValue === null ? null : networkReference(captureNetwork(appliedPreviousValue));
     const projection = await validateRuntimeNetworkProjectionV1(incoming);
-    requireNetwork(sameScope(projection, trusted));
+    requireNetwork(networkSameScope(projection, trusted));
     if (previousInput === null) {
       requireNetwork(projection.generation === 1 && applied === null && projection.withdrawals.length === 0
         && (projection.router?.withdrawals.length ?? 0) === 0
@@ -511,7 +513,7 @@ export const admitRuntimeNetworkProjectionV1 = async (
       return { status: 'accepted', projection };
     }
     const previous = await validateRuntimeNetworkProjectionV1(previousInput);
-    requireNetwork(sameScope(previous, trusted) && previous.id === projection.id);
+    requireNetwork(networkSameScope(previous, trusted) && previous.id === projection.id);
     requireNetwork(applied === null || networkEqual(applied, networkReferenceOf(previous)));
     if (projection.generation === previous.generation) {
       requireNetwork(networkEqual(previous, projection)); return { status: 'replay', projection };

package/ts/data/networksigning.ts

@@ -3,8 +3,8 @@ import type { IRuntimeAuthorityReferenceV1, IRuntimeControllerV1 } from './runti
 import type { IRuntimeNetworkProjectionV1 } from './networkprojection.js';
 import { snapshotRuntimeNetworkProjectionV1 } from './networkprojection.js';
 import { snapshotRuntimeSessionBindingV1 } from './runtimesession.js';
-import { captureNetwork, failNetwork, networkController, networkDigest, networkEqual, networkHash,
-  networkRecord, networkReference, networkReferenceOf, networkRevision, networkSafe, requireNetwork } from '../private/networkcontract.js';
+import { captureNetwork, failNetwork, networkController, networkDigest, networkEqual, networkHash, networkRecord,
+  networkReference, networkReferenceOf, networkRevision, networkSafe, networkSignature, requireNetwork } from '../private/networkcontract.js';
 
 export interface ISignedRuntimeNetworkProjectionV1 {
   schemaVersion: 1;
@@ -16,8 +16,9 @@ export interface ISignedRuntimeNetworkProjectionV1 {
 
 export const snapshotSignedRuntimeNetworkProjectionV1 = (value: unknown): ISignedRuntimeNetworkProjectionV1 => networkSafe(() => {
   const item = networkRecord(captureNetwork(value), ['schemaVersion', 'authority', 'projection', 'signature']);
-  requireNetwork(item.schemaVersion === 1 && typeof item.signature === 'string' && /^[a-f0-9]{128}$/.test(item.signature));
-  return { schemaVersion: 1, authority: networkReference(item.authority), projection: snapshotRuntimeNetworkProjectionV1(item.projection), signature: item.signature };
+  requireNetwork(item.schemaVersion === 1);
+  return { schemaVersion: 1, authority: networkReference(item.authority), projection: snapshotRuntimeNetworkProjectionV1(item.projection),
+    signature: networkSignature(item.signature) };
 });
 
 /**

package/ts/private/networkcontract.ts

@@ -1,5 +1,7 @@
 import type { TSha256Digest } from '../data/immutableimage.js';
 import type { IRuntimeAuthorityReferenceV1, IRuntimeControllerV1 } from '../data/runtimeassignment.js';
+import type { IRuntimeNetworkDnsLeaseRenewal } from '../data/networklease.js';
+import type { IRuntimeNetworkDnsWindow, IRuntimeNetworkNodeScopeV1, IRuntimeNetworkProjectionV1 } from '../data/networkprojection.js';
 import { canonicalizeStrictJson, createCanonicalJsonSha256Hex } from './canonicaljson.js';
 
 export const failNetwork = (): never => { throw new Error('Runtime network projection contract rejected.'); };
@@ -83,17 +85,49 @@ export const networkCounter = (value: unknown, maximum = Number.MAX_SAFE_INTEGER
 export const networkDigest = (value: unknown): TSha256Digest => {
   requireNetwork(typeof value === 'string' && /^sha256:[a-f0-9]{64}$/.test(value)); return value as TSha256Digest;
 };
+/** One encoding for every Ed25519 signature this contract carries: lowercase hex, 64 bytes. */
+export const networkSignature = (value: unknown): string => {
+  requireNetwork(typeof value === 'string' && /^[a-f0-9]{128}$/.test(value)); return value;
+};
 export const networkController = (value: unknown): IRuntimeControllerV1 => {
   const item = networkRecord(value, ['kind', 'id', 'epoch']);
   requireNetwork(item.kind === 'cloudly' || item.kind === 'onebox');
   return { kind: item.kind, id: networkId(item.id), epoch: networkId(item.epoch) };
 };
+export const networkScope = (item: Record<string, unknown>): IRuntimeNetworkNodeScopeV1 => ({
+  controller: networkController(item.controller), nodeId: networkId(item.nodeId), runtimeNamespace: networkId(item.runtimeNamespace),
+});
+export const networkSameScope = (left: IRuntimeNetworkNodeScopeV1, right: IRuntimeNetworkNodeScopeV1): boolean =>
+  networkEqual(left.controller, right.controller) && left.nodeId === right.nodeId && left.runtimeNamespace === right.runtimeNamespace;
+export const networkMaximumDnsLeaseMs = 900_000;
+/** One rule for every signed DNS window, projection or renewal: ordered, non-empty, at most fifteen minutes. */
+export const networkDnsWindow = (value: unknown): IRuntimeNetworkDnsWindow => {
+  const item = networkRecord(value, ['issuedAt', 'notBefore', 'expiresAt']);
+  const window = { issuedAt: networkCounter(item.issuedAt), notBefore: networkCounter(item.notBefore), expiresAt: networkCounter(item.expiresAt) };
+  requireNetwork(window.notBefore >= window.issuedAt && window.expiresAt > window.notBefore
+    && window.expiresAt - window.issuedAt <= networkMaximumDnsLeaseMs);
+  return window;
+};
 export const networkReference = (value: unknown): IRuntimeAuthorityReferenceV1 => {
   const item = networkRecord(value, ['id', 'generation', 'digest']);
   return { id: networkId(item.id), generation: networkCounter(item.generation), digest: networkDigest(item.digest) };
 };
 export const networkReferenceOf = (value: IRuntimeAuthorityReferenceV1): IRuntimeAuthorityReferenceV1 =>
   ({ id: value.id, generation: value.generation, digest: value.digest });
+/** A renewal renews exactly one projection: the same node scope and that projection's exact reference. */
+export const networkRenewsProjection = (renewal: IRuntimeNetworkDnsLeaseRenewal, projection: IRuntimeNetworkProjectionV1): boolean =>
+  networkSameScope(renewal, projection) && networkEqual(renewal.projection, networkReferenceOf(projection));
+/**
+ * The one rule for the DNS window a node may use under a projection: its admitted renewal's, else
+ * the projection's own. Both inputs are already validated caller state; this verifies no signature.
+ */
+export const networkEffectiveDnsWindow = (
+  projection: IRuntimeNetworkProjectionV1, renewal: IRuntimeNetworkDnsLeaseRenewal | null,
+): IRuntimeNetworkDnsWindow => {
+  if (renewal === null) return projection.dns;
+  requireNetwork(networkRenewsProjection(renewal, projection));
+  return renewal.dns;
+};
 export const networkRevision = (item: Record<string, unknown>) => {
   const id = networkId(item.id), generation = networkCounter(item.generation);
   const previous = item.previous === null ? null : networkReference(item.previous);

package/ts/requests/cluster.ts

@@ -1,5 +1,6 @@
 import * as userInterfaces from '../data/user.js';
 import * as clusterInterfaces from '../data/cluster.js';
+import type * as leaseInterfaces from '../data/networklease.js';
 import * as plugins from '../plugins.js';
 
 /**
@@ -146,6 +147,25 @@ export interface IReq_Relay_Cloudly_RegisterClusterRelayV1 extends plugins.typed
   response: clusterInterfaces.IClusterRelayRegistrationResponseV1;
 }
 
+/**
+ * Cloudly hands the cluster relay the DNS lease renewals it has signed ahead of time for one node.
+ *
+ * A cluster is outbound-only, so a node that loses Cloudly loses the only signer of its DNS
+ * window. The relay holds this run in memory, replacing whatever it held for that node, and
+ * releases from it only the renewal whose window is current (`notBefore <= now < expiresAt`), and
+ * only while it has no Cloudly session: a node refuses a window that is not current. It signs nothing and verifies
+ * nothing: each renewal is Cloudly's statement and the node verifies it against its own pinned
+ * authority.
+ */
+export interface IReq_Cloudly_Relay_HoldRuntimeNetworkDnsLeaseRenewals extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Cloudly_Relay_HoldRuntimeNetworkDnsLeaseRenewals
+> {
+  method: 'holdRuntimeNetworkDnsLeaseRenewals';
+  request: leaseInterfaces.IHoldRuntimeNetworkDnsLeaseRenewalsRequest;
+  response: leaseInterfaces.IHoldRuntimeNetworkDnsLeaseRenewalsResponse;
+}
+
 /**
  * deletes a cluster
  */

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