@serve.zone/interfaces 31.7.0 → 31.9.0

package/ts/data/networkcredential.ts

@@ -1,8 +1,9 @@
 import type { IRuntimeAuthorityReferenceV1 } from './runtimeassignment.js';
 import { snapshotRuntimeSessionBindingV1, type IRuntimeSessionBindingV1 } from './runtimesession.js';
 import { validateRuntimeNetworkProjectionV1, type IRuntimeNetworkProjectionV1 } from './networkprojection.js';
-import { captureNetwork, failNetwork, networkCounter, networkEqual, networkId, networkIpv4,
-  networkRecord, networkReference, networkReferenceOf, networkSafe, requireNetwork } from '../private/networkcontract.js';
+import { snapshotRuntimeNetworkDnsLeaseRenewal, validateRuntimeNetworkDnsLeaseRenewal } from './networklease.js';
+import { captureNetwork, failNetwork, networkCounter, networkEffectiveDnsWindow, networkEqual, networkId, networkIpv4,
+  networkRecord, networkReference, networkReferenceOf, networkSafe, networkSameScope, requireNetwork } from '../private/networkcontract.js';
 
 export interface IGetRuntimeManagedVpnCredentialRequestV1 {
   session: IRuntimeSessionBindingV1;
@@ -19,7 +20,10 @@ export interface IGetRuntimeManagedVpnCredentialResponseV1 extends IGetRuntimeMa
   serverPublicKey: string;
   clientPublicKey: string;
   clientPrivateKey: string;
-  /** Unix milliseconds; cannot outlive the referenced projection's DNS lease. */
+  /**
+   * Unix milliseconds; cannot outlive the referenced projection's effective DNS window: its
+   * admitted lease renewal's, else its own.
+   */
   expiresAt: number;
 }
 
@@ -50,8 +54,7 @@ export const snapshotGetRuntimeManagedVpnCredentialResponseV1 = (value: unknown)
 const bindRequest = (request: IGetRuntimeManagedVpnCredentialRequestV1,
   projection: IRuntimeNetworkProjectionV1, trusted: IRuntimeSessionBindingV1): void => {
   requireNetwork(networkEqual(request.session, trusted) && networkEqual(request.projection, networkReferenceOf(projection))
-    && networkEqual(projection.controller, trusted.controller) && projection.nodeId === trusted.nodeId
-    && projection.runtimeNamespace === trusted.runtimeNamespace && projection.handoff);
+    && networkSameScope(projection, trusted) && projection.handoff);
 };
 
 /** Content binding only. The caller must resolve the exact current projection
@@ -68,21 +71,28 @@ export const bindGetRuntimeManagedVpnCredentialRequestV1 = async (value: unknown
 };
 
 /** Bind the secret response to the original request and exact selected router
- * UDP endpoint. Time is caller-qualified; this helper does not sample a clock,
- * authenticate a transport, admit policy or prove a running managed connection. */
+ * UDP endpoint, inside the projection's effective DNS window. renewalValue is the
+ * bare lease renewal the caller already verified and admitted for this exact
+ * projection, or null; this helper verifies no signature. Time is caller-qualified;
+ * this helper does not sample a clock, authenticate a transport, admit policy or
+ * prove a running managed connection. */
 export const bindGetRuntimeManagedVpnCredentialResponseV1 = async (value: unknown, requestValue: unknown,
-  projectionValue: unknown, trustedSessionValue: unknown, nowValue: unknown): Promise<IGetRuntimeManagedVpnCredentialResponseV1> => {
+  projectionValue: unknown, trustedSessionValue: unknown, nowValue: unknown,
+  renewalValue: unknown | null = null): Promise<IGetRuntimeManagedVpnCredentialResponseV1> => {
   try {
     const response = snapshotGetRuntimeManagedVpnCredentialResponseV1(value);
     const request = snapshotGetRuntimeManagedVpnCredentialRequestV1(requestValue);
     const trusted = snapshotRuntimeSessionBindingV1(trustedSessionValue), now = networkCounter(nowValue);
+    const renewalInput = renewalValue === null ? null : snapshotRuntimeNetworkDnsLeaseRenewal(renewalValue);
     const projection = await validateRuntimeNetworkProjectionV1(projectionValue);
+    const renewal = renewalInput === null ? null : await validateRuntimeNetworkDnsLeaseRenewal(renewalInput);
+    const window = networkEffectiveDnsWindow(projection, renewal);
     bindRequest(request, projection, trusted);
     requireNetwork(networkEqual(response.session, request.session) && networkEqual(response.projection, request.projection));
     requireNetwork(projection.router?.platformEndpointIds.includes(response.relay.id));
     const endpoint = projection.protectedAuthority.platformEndpoints.find(item => item.id === response.relay.id);
     requireNetwork(endpoint && endpoint.protocol === 'udp' && endpoint.address === response.relay.address && endpoint.port === response.relay.port);
-    requireNetwork(projection.dns.notBefore <= now && now < response.expiresAt && response.expiresAt <= projection.dns.expiresAt);
+    requireNetwork(window.notBefore <= now && now < response.expiresAt && response.expiresAt <= window.expiresAt);
     return response;
   } catch { return failNetwork(); }
 };

package/ts/data/networkdelivery.ts

@@ -3,7 +3,11 @@ import type { IRuntimeSessionBindingV1 } from './runtimesession.js';
 import { snapshotRuntimeSessionBindingV1 } from './runtimesession.js';
 import type { IRuntimeNetworkSigningAuthorityV1, ISignedRuntimeNetworkProjectionV1 } from './networksigning.js';
 import { snapshotRuntimeNetworkSigningAuthorityV1, snapshotSignedRuntimeNetworkProjectionV1 } from './networksigning.js';
-import { captureNetwork, networkEqual, networkRecord, networkReference, networkReferenceOf, networkSafe, requireNetwork } from '../private/networkcontract.js';
+import type { IRuntimeNetworkDnsLeaseRenewalReference, ISignedRuntimeNetworkDnsLeaseRenewal } from './networklease.js';
+import { getRuntimeNetworkDnsLeaseRenewalReference, snapshotRuntimeNetworkDnsLeaseRenewal,
+  snapshotRuntimeNetworkDnsLeaseRenewalReference, snapshotSignedRuntimeNetworkDnsLeaseRenewal } from './networklease.js';
+import { captureNetwork, networkEqual, networkRecord, networkReference, networkReferenceOf, networkSafe, networkSameScope,
+  requireNetwork } from '../private/networkcontract.js';
 
 export interface IApplyRuntimeNetworkSigningAuthorityRequestV1 {
   session: IRuntimeSessionBindingV1;
@@ -18,6 +22,19 @@ export interface IApplyRuntimeNetworkAuthorityResponseV1 {
   status: 'accepted' | 'replay';
   authority: IRuntimeAuthorityReferenceV1;
 }
+export interface IApplyRuntimeNetworkDnsLeaseRenewalRequest {
+  session: IRuntimeSessionBindingV1;
+  signed: ISignedRuntimeNetworkDnsLeaseRenewal;
+}
+/** Durable admission only. It does not assert that the node converted the window or serves DNS. */
+export interface IApplyRuntimeNetworkDnsLeaseRenewalResponse {
+  status: 'accepted' | 'replay';
+  renewal: IRuntimeNetworkDnsLeaseRenewalReference;
+}
+
+const admissionStatus = (value: unknown): 'accepted' | 'replay' => {
+  requireNetwork(value === 'accepted' || value === 'replay'); return value;
+};
 
 export const snapshotApplyRuntimeNetworkSigningAuthorityRequestV1 = (value: unknown): IApplyRuntimeNetworkSigningAuthorityRequestV1 => networkSafe(() => {
   const item = networkRecord(captureNetwork(value), ['session', 'authority']);
@@ -29,8 +46,16 @@ export const snapshotApplyRuntimeNetworkProjectionRequestV1 = (value: unknown):
 });
 export const snapshotApplyRuntimeNetworkAuthorityResponseV1 = (value: unknown): IApplyRuntimeNetworkAuthorityResponseV1 => networkSafe(() => {
   const item = networkRecord(captureNetwork(value), ['status', 'authority']);
-  requireNetwork(item.status === 'accepted' || item.status === 'replay');
-  return { status: item.status, authority: networkReference(item.authority) };
+  return { status: admissionStatus(item.status), authority: networkReference(item.authority) };
+});
+
+export const snapshotApplyRuntimeNetworkDnsLeaseRenewalRequest = (value: unknown): IApplyRuntimeNetworkDnsLeaseRenewalRequest => networkSafe(() => {
+  const item = networkRecord(captureNetwork(value), ['session', 'signed']);
+  return { session: snapshotRuntimeSessionBindingV1(item.session), signed: snapshotSignedRuntimeNetworkDnsLeaseRenewal(item.signed) };
+});
+export const snapshotApplyRuntimeNetworkDnsLeaseRenewalResponse = (value: unknown): IApplyRuntimeNetworkDnsLeaseRenewalResponse => networkSafe(() => {
+  const item = networkRecord(captureNetwork(value), ['status', 'renewal']);
+  return { status: admissionStatus(item.status), renewal: snapshotRuntimeNetworkDnsLeaseRenewalReference(item.renewal) };
 });
 
 /** trustedSessionValue must come from the receiving CURRENT physical connection. */
@@ -43,9 +68,7 @@ export const bindApplyRuntimeNetworkSigningAuthorityRequestV1 = (value: unknown,
 /** Content binding only. Verify signature with stored trust and atomically fence admission. */
 export const bindApplyRuntimeNetworkProjectionRequestV1 = (value: unknown, trustedSessionValue: unknown): IApplyRuntimeNetworkProjectionRequestV1 => networkSafe(() => {
   const request = snapshotApplyRuntimeNetworkProjectionRequestV1(value), session = snapshotRuntimeSessionBindingV1(trustedSessionValue);
-  const projection = request.signed.projection;
-  requireNetwork(networkEqual(request.session, session) && networkEqual(projection.controller, session.controller)
-    && projection.nodeId === session.nodeId && projection.runtimeNamespace === session.runtimeNamespace);
+  requireNetwork(networkEqual(request.session, session) && networkSameScope(request.signed.projection, session));
   return request;
 });
 
@@ -56,3 +79,23 @@ export const bindApplyRuntimeNetworkAuthorityResponseV1 = (value: unknown, sentR
   requireNetwork(networkEqual(response.authority, networkReferenceOf(expected)));
   return response;
 });
+
+/**
+ * Content binding only; trustedSessionValue must come from the receiving CURRENT physical
+ * connection. A relay pushes a held renewal under the binding the node obtained itself, so this
+ * comparison is what makes the push admissible, never who sent it. Verify the signature with
+ * stored trust, then admit and fence atomically.
+ */
+export const bindApplyRuntimeNetworkDnsLeaseRenewalRequest = (value: unknown, trustedSessionValue: unknown): IApplyRuntimeNetworkDnsLeaseRenewalRequest => networkSafe(() => {
+  const request = snapshotApplyRuntimeNetworkDnsLeaseRenewalRequest(value), session = snapshotRuntimeSessionBindingV1(trustedSessionValue);
+  requireNetwork(networkEqual(request.session, session) && networkSameScope(request.signed.renewal, session));
+  return request;
+});
+
+/** Compare the ACK with the exact SENT renewal, never with a response-derived value. */
+export const bindApplyRuntimeNetworkDnsLeaseRenewalResponse = (value: unknown, sentRenewalValue: unknown): IApplyRuntimeNetworkDnsLeaseRenewalResponse => networkSafe(() => {
+  const response = snapshotApplyRuntimeNetworkDnsLeaseRenewalResponse(value);
+  const sent = getRuntimeNetworkDnsLeaseRenewalReference(snapshotRuntimeNetworkDnsLeaseRenewal(sentRenewalValue));
+  requireNetwork(networkEqual(response.renewal, sent));
+  return response;
+});

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/networknode.ts

@@ -0,0 +1,37 @@
+import type { IRuntimeNetworkProtectedAuthorityV1 } from './networkauthority.js';
+import { captureNetwork, networkCounter, networkId, networkRecord, networkSafe } from '../private/networkcontract.js';
+
+type TEgressOwner = IRuntimeNetworkProtectedAuthorityV1['egressAuthorities'][number];
+
+/**
+ * One unmet condition of a node's runtime network readiness, in the order the node producer meets
+ * them: the node joins the protected authority's egress, every egress owner reports current
+ * protection, a handoff is reserved, the router selection carries it, the node's acknowledged
+ * projection carries it, and the node is a managed VPN member. `protection-receipts-pending` names
+ * the egress owners whose current receipts are still missing.
+ */
+export type TRuntimeNetworkNodeReadinessGap =
+  | { condition: 'egress-pending' | 'handoff-pending' | 'selection-pending' | 'projection-pending' | 'vpn-member-pending' }
+  | { condition: 'protection-receipts-pending'; owners: [TEgressOwner, ...TEgressOwner[]] };
+
+/** A node is ready exactly when nothing is missing. */
+export type IRuntimeNetworkNodeReadiness = { nodeId: string } & (
+  | { ready: true; missing: [] }
+  | { ready: false; missing: [TRuntimeNetworkNodeReadinessGap, ...TRuntimeNetworkNodeReadinessGap[]] }
+);
+
+/**
+ * The router incarnation of one node. A handoff's id and router incarnation id derive from it, so
+ * advancing it is the only way to give a node's router a fresh handoff.
+ */
+export interface IRuntimeRouterIncarnation {
+  /** The node id. */
+  id: string;
+  /** Starts at 1 with the node's first handoff; every reincarnation advances it by one. */
+  incarnation: number;
+}
+
+export const snapshotRuntimeRouterIncarnation = (value: unknown): IRuntimeRouterIncarnation => networkSafe(() => {
+  const item = networkRecord(captureNetwork(value), ['id', 'incarnation']);
+  return { id: networkId(item.id), incarnation: networkCounter(item.incarnation) };
+});

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) };
 });
 
 /**