@serve.zone/interfaces 32.16.0 → 32.17.0

package/ts/data/cluster.ts

@@ -2,11 +2,23 @@ import * as plugins from '../plugins.js';
 
 import { type IDockerRegistryInfo } from '../data/docker.js';
 import type { IClusterNode } from './clusternode.js';
+import type { IFleetCutoverAcceptedEvidenceReference } from './fleetcutover.js';
+import type { TSha256Digest } from './immutableimage.js';
+import type { IRuntimeAuthorityReference } from './runtimeassignment.js';
 import { isPlausibleUnicastIpv4 } from '../private/ipv4.js';
 import { validateProtocolOfferOn, type IProtocolOffer } from '../protocol.js';
 import { hasExactKeys } from '../private/dataproperties.js';
 import { isClusterNodeId } from '../private/nodeidentifier.js';
-import { networkNoiseKey } from '../private/networkcontract.js';
+import {
+  captureNetwork,
+  networkCounter,
+  networkDigest,
+  networkHash,
+  networkId,
+  networkNoiseKey,
+  networkRecord,
+  networkReference,
+} from '../private/networkcontract.js';
 
 export interface ICluster {
   id: string;
@@ -137,6 +149,16 @@ export interface IRegisterClusterRelayResponse {
   origin: string;
   /** Cloudly's own offer, so an accepted relay judges the session it just registered into. */
   protocol: IProtocolOffer;
+  /**
+   * The relay credential generation Cloudly authenticated this socket as.
+   *
+   * Read from Cloudly's own record and never from the registration: a relay that stated its own
+   * generation would be asserting its own rank. It is how a relay learns the exact generation its
+   * readiness is bound to.
+   */
+  credential: IRuntimeAuthorityReference;
+  /** The accepted registration record this answer wrote, as a retirement record later cites it. */
+  acceptedRegistration: IFleetCutoverAcceptedEvidenceReference;
 }
 
 /**
@@ -155,6 +177,13 @@ export const clusterRelayUndispatchedRefusals = Object.freeze([
   'relay-node-foreign',
   /** A registration of this relay identity at the same or a higher sequence is already recorded. */
   'relay-sequence-not-advancing',
+  /**
+   * The credential this socket authenticated with is no longer the cluster's current generation.
+   *
+   * Rotation has no overlap, so another relay may already hold the current one: this relay is not
+   * the one Cloudly dispatches to, which `relay-identity-unverified` never states.
+   */
+  'relay-credential-generation-stale',
 ] as const);
 
 /** One of the reasons Cloudly states that it does not dispatch to a relay. */
@@ -342,14 +371,12 @@ export const validateRegisterClusterRelayRequest = (
 };
 
 /**
- * One cluster's relay as Cloudly serves it to an administrator.
+ * What one accepted relay registration states about the relay that sent it.
  *
- * This is the read shape, not the registration a relay sends: `IRegisterClusterRelayRequest` is
- * what the relay puts on the wire, and this is what Cloudly answers with after it accepted one.
- * `clusterId` names the cluster the relay serves, and `acceptedAt` is Cloudly's own acceptance
- * time, which is what orders two registrations of one cluster.
+ * The part the served read shape and the accepted record share: no record identity, no digest and
+ * no liveness, so neither shape restates the other's fields.
  */
-export interface IClusterRelayRegistration {
+export interface IClusterRelayRegistrationFacts {
   clusterId: string;
   nodeId: string;
   listenAddress: string;
@@ -357,6 +384,17 @@ export interface IClusterRelayRegistration {
   version: string;
   registrationSequence: number;
   acceptedAt: number;
+}
+
+/**
+ * One cluster's relay as Cloudly serves it to an administrator.
+ *
+ * This is the read shape, not the registration a relay sends: `IRegisterClusterRelayRequest` is
+ * what the relay puts on the wire, and this is what Cloudly answers with after it accepted one.
+ * `clusterId` names the cluster the relay serves, and `acceptedAt` is Cloudly's own acceptance
+ * time, which is what orders two registrations of one cluster.
+ */
+export interface IClusterRelayRegistration extends IClusterRelayRegistrationFacts {
   /**
    * Whether a verified socket carries this relay at this instant.
    *
@@ -367,6 +405,26 @@ export interface IClusterRelayRegistration {
   live: boolean;
 }
 
+const clusterRelayRegistrationFactKeys = [
+  'clusterId', 'nodeId', 'listenAddress', 'listenPort', 'version', 'registrationSequence',
+  'acceptedAt',
+] as const;
+
+/** The one format rule of every registration fact, whichever shape carries it. */
+const validateClusterRelayRegistrationFacts = (
+  valueArg: Record<string, unknown>,
+  pathArg: string,
+): string[] => [
+  ...validateClusterRelayIdentifier(valueArg.clusterId, `${pathArg} clusterId`),
+  ...validateClusterRelayIdentifier(valueArg.nodeId, `${pathArg} nodeId`),
+  ...validateClusterRelayListenAddress(valueArg.listenAddress, `${pathArg} listenAddress`),
+  ...validateClusterRelayListenPort(valueArg.listenPort, `${pathArg} listenPort`),
+  ...validateClusterRelayVersion(valueArg.version, `${pathArg} version`),
+  ...validateClusterRelayNonNegativeInteger(valueArg.registrationSequence,
+    `${pathArg} registrationSequence`),
+  ...validateClusterRelayNonNegativeInteger(valueArg.acceptedAt, `${pathArg} acceptedAt`),
+];
+
 /**
  * Validates one served relay registration and names every reason it is refused.
  *
@@ -378,23 +436,95 @@ export const validateClusterRelayRegistration = (
   valueArg: unknown,
   pathArg = 'cluster relay registration',
 ): string[] => {
-  if (!isRecord(valueArg) || !hasExactKeys(valueArg, ['clusterId', 'nodeId', 'listenAddress',
-    'listenPort', 'version', 'registrationSequence', 'acceptedAt', 'live'])) {
+  if (!isRecord(valueArg)
+    || !hasExactKeys(valueArg, [...clusterRelayRegistrationFactKeys, 'live'])) {
     return [`${pathArg} must use its exact schema`];
   }
   return [
-    ...validateClusterRelayIdentifier(valueArg.clusterId, `${pathArg} clusterId`),
-    ...validateClusterRelayIdentifier(valueArg.nodeId, `${pathArg} nodeId`),
-    ...validateClusterRelayListenAddress(valueArg.listenAddress, `${pathArg} listenAddress`),
-    ...validateClusterRelayListenPort(valueArg.listenPort, `${pathArg} listenPort`),
-    ...validateClusterRelayVersion(valueArg.version, `${pathArg} version`),
-    ...validateClusterRelayNonNegativeInteger(valueArg.registrationSequence,
-      `${pathArg} registrationSequence`),
-    ...validateClusterRelayNonNegativeInteger(valueArg.acceptedAt, `${pathArg} acceptedAt`),
+    ...validateClusterRelayRegistrationFacts(valueArg, pathArg),
     ...(typeof valueArg.live === 'boolean' ? [] : [`${pathArg} live must be a boolean`]),
   ];
 };
 
+/**
+ * Cloudly's accepted registration record: the thing an evidence reference names.
+ *
+ * `credential` is the exact relay credential generation the registering socket authenticated as,
+ * so a reader can tell a registration made under the current credential from one made under a
+ * superseded one. Liveness is deliberately absent: a live socket is not a fact a record can hold,
+ * and a digest that covered it would change without anything having been registered.
+ */
+export interface IClusterRelayAcceptedRegistration extends IClusterRelayRegistrationFacts {
+  id: string;
+  /** Advances by one per accepted registration, so a reference to a superseded one fails closed. */
+  generation: number;
+  credential: IRuntimeAuthorityReference;
+  digest: TSha256Digest;
+}
+
+export const clusterRelayContract = Object.freeze({
+  acceptedRegistrationDigestDomain: 'serve.zone/cluster-relay-accepted-registration',
+} as const);
+
+const failClusterRelayRecord = (): never => {
+  throw new Error('Cluster relay contract rejected.');
+};
+
+/** The facts of an already exact-keyed record, refused unless each passes its one format rule. */
+const readClusterRelayRegistrationFacts = (
+  valueArg: Record<string, unknown>,
+): IClusterRelayRegistrationFacts => {
+  if (validateClusterRelayRegistrationFacts(valueArg, 'cluster relay registration').length > 0) {
+    failClusterRelayRecord();
+  }
+  const {
+    clusterId, nodeId, listenAddress, listenPort, version, registrationSequence, acceptedAt,
+  } = valueArg;
+  // Each member passed its format rule above, which is what the assertion states.
+  return {
+    clusterId, nodeId, listenAddress, listenPort, version, registrationSequence, acceptedAt,
+  } as IClusterRelayRegistrationFacts;
+};
+
+/** Structural copy only; whether the record is the cluster's current one is Cloudly's to decide. */
+export const snapshotClusterRelayAcceptedRegistration = (
+  valueArg: unknown,
+): IClusterRelayAcceptedRegistration => {
+  try {
+    const value = networkRecord(captureNetwork(valueArg), [
+      ...clusterRelayRegistrationFactKeys, 'id', 'generation', 'credential', 'digest',
+    ]);
+    return {
+      ...readClusterRelayRegistrationFacts(value),
+      id: networkId(value.id),
+      generation: networkCounter(value.generation),
+      credential: networkReference(value.credential),
+      digest: networkDigest(value.digest),
+    };
+  } catch {
+    return failClusterRelayRecord();
+  }
+};
+
+export const computeClusterRelayAcceptedRegistrationDigest = async (
+  valueArg: unknown,
+): Promise<TSha256Digest> => networkHash(
+  clusterRelayContract.acceptedRegistrationDigestDomain,
+  snapshotClusterRelayAcceptedRegistration(valueArg),
+);
+
+export const validateClusterRelayAcceptedRegistration = async (
+  valueArg: unknown,
+): Promise<string[]> => {
+  try {
+    const value = snapshotClusterRelayAcceptedRegistration(valueArg);
+    return value.digest === await computeClusterRelayAcceptedRegistrationDigest(value)
+      ? [] : ['cluster relay accepted registration digest does not match'];
+  } catch {
+    return ['cluster relay accepted registration must use its exact canonical schema'];
+  }
+};
+
 /**
  * The name the relay's certificate is issued for, and the A record Cloudly
  * owns for it. Derived from the origin so every consumer derives it

package/ts/data/clusternode.ts

@@ -20,6 +20,10 @@ import {
   type IFleetCutoverPreparedVolumeHandoffIntent,
   type IFleetCutoverPreparedVolumeHandoffPage,
 } from './fleetcutover.js';
+import {
+  validateSparkLegacyRuntimeRetirement,
+  type ISparkLegacyRuntimeRetirement,
+} from './sparklegacyretirement.js';
 import { protocolRefusalHttpStatus, validateProtocolOfferOn, type IProtocolOffer } from '../protocol.js';
 import {
   canonicalizeStrictJson,
@@ -242,6 +246,8 @@ interface ISparkSwarmObservationBase {
   observedAt: number;
   /** Available in every observation state; exact page membership proves an empty node subset. */
   fleetCutoverHeldVolumeFences?: IFleetCutoverHeldVolumeFenceEvidencePage;
+  /** Available in every observation state too: this describes the host, not its Docker daemon. */
+  fleetCutoverLegacyRetirement?: ISparkLegacyRuntimeRetirement;
 }
 
 export type TSparkSwarmObservation =
@@ -628,6 +634,8 @@ export const validateSparkSwarmObservation = async (
       'state',
       ...(observation.fleetCutoverHeldVolumeFences === undefined
         ? [] : ['fleetCutoverHeldVolumeFences']),
+      ...(observation.fleetCutoverLegacyRetirement === undefined
+        ? [] : ['fleetCutoverLegacyRetirement']),
     ];
     const expectedKeys = observation.state === 'unknown'
       ? [...commonKeys, 'reason']
@@ -676,6 +684,11 @@ export const validateSparkSwarmObservation = async (
         errorArg => `Spark Swarm observation ${errorArg}`,
       ));
     }
+    if (observation.fleetCutoverLegacyRetirement !== undefined) {
+      errors.push(...validateSparkLegacyRuntimeRetirement(
+        observation.fleetCutoverLegacyRetirement,
+      ).map(errorArg => `Spark Swarm observation ${errorArg}`));
+    }
     if (observation.state === 'member') {
       if (!isRuntimeIdentifier(observation.localSwarmNodeId)
         || typeof observation.controlAvailable !== 'boolean') {

package/ts/data/clusterrelaycredential.ts

@@ -0,0 +1,361 @@
+import type { IClusterRelayAcceptedRegistration } from './cluster.js';
+import {
+  snapshotClusterRelayAcceptedRegistration,
+  validateClusterRelayAcceptedRegistration,
+} from './cluster.js';
+import type { IFleetCutoverAcceptedEvidenceReference } from './fleetcutover.js';
+import type { TSha256Digest } from './immutableimage.js';
+import type { IRuntimeAuthorityReference } from './runtimeassignment.js';
+import type { ISecretVersionReference } from './secret.js';
+import {
+  captureNetwork,
+  networkCounter,
+  networkDigest,
+  networkEqual,
+  networkHash,
+  networkId,
+  networkRecord,
+  networkReference,
+  networkReferenceOf,
+  requireNetwork,
+} from '../private/networkcontract.js';
+
+/**
+ * The relay authority Cloudly mints for one cluster. Public metadata only: never a bearer or hash.
+ *
+ * It authenticates the cluster's whole control-plane session, exactly what the shared cluster
+ * authority authenticated before it, so the relay changes one credential and keeps every call it
+ * makes. What it adds is a generation Cloudly fences each socket against and an authority it can
+ * rotate without touching the shared one; its scope is not narrower. One cluster has one relay and
+ * therefore one such record, and rotation is its whole lifecycle: it never expires by itself.
+ */
+export interface IClusterRelayCredential {
+  id: string;
+  clusterId: string;
+  /** Monotonic state: one accepted mint or rotation advances it by exactly one. */
+  generation: number;
+  /** The machine identity this credential authenticates as; Cloudly's own, never caller-chosen. */
+  userId: string;
+  /** The immutable encrypted version the bearer was delivered as. */
+  delivery: ISecretVersionReference;
+  actorId: string;
+  acceptedAt: number;
+  digest: TSha256Digest;
+}
+
+interface IClusterRelayCredentialMutationBase {
+  clusterId: string;
+  /** Retain the complete request and this ID across retries; a changed body with it fails closed. */
+  mutationId: string;
+}
+
+/**
+ * Creation is absent-only; rotation requires the exact current generation, never a minimum.
+ *
+ * There is no revocation: a rotation already ends the previous generation at commit, so it covers a
+ * compromised credential without a state in which the cluster has no relay authority at all.
+ */
+export type TClusterRelayCredentialMutation = IClusterRelayCredentialMutationBase & (
+  | { operation: 'ensure'; expectedGeneration: null }
+  | { operation: 'rotate'; expectedGeneration: number }
+);
+
+export interface IClusterRelayCredentialMutationResult {
+  credential: IClusterRelayCredential;
+  /** The shared pre-relay authority this cluster still carries; null when no record names one. */
+  legacy: IClusterLegacyRelayCredential | null;
+  /** A replay returns the original result without renewing delivery, generation or authority. */
+  replayed: boolean;
+}
+
+/**
+ * Cloudly's record of the shared cluster authority that predates the relay credential, so it can
+ * be named and retired. It is the machine identity every cluster-side component authenticated as;
+ * like the relay credential it carries no bearer and no hash.
+ */
+export interface IClusterLegacyRelayCredential {
+  id: string;
+  clusterId: string;
+  userId: string;
+  generation: number;
+  state: 'active' | 'revoked';
+  /**
+   * The accepted invalidation that revoked it; null exactly while it is still accepted.
+   *
+   * The invalidation names this record at the generation before the revocation and this record
+   * names the invalidation at the generation after it, so neither digest covers the other's.
+   */
+  invalidation: IFleetCutoverAcceptedEvidenceReference | null;
+  recordedAt: number;
+  digest: TSha256Digest;
+}
+
+/**
+ * Caller intent only. Both references are compare-and-swap inputs: Cloudly dereferences them
+ * against its own current records and checks the relay's live socket itself.
+ */
+export interface IClusterLegacyRelayCredentialRetirementRequest {
+  /** Retain the complete request and this ID across retries; a changed body with it fails closed. */
+  mutationId: string;
+  clusterId: string;
+  expectedLegacyGeneration: number;
+  /** The exact replacement relay credential generation the caller observed as current. */
+  replacement: IRuntimeAuthorityReference;
+  /** The exact accepted registration the caller observed as current. */
+  acceptedRegistration: IFleetCutoverAcceptedEvidenceReference;
+}
+
+/** The accepted receipt that one shared cluster authority stopped being accepted; written once. */
+export interface IClusterLegacyRelayCredentialInvalidation {
+  id: string;
+  generation: 1;
+  clusterId: string;
+  /** The exact legacy generation this invalidated, read before the record advanced. */
+  credential: IRuntimeAuthorityReference;
+  /** The relay credential generation that was current when this was accepted. */
+  replacement: IRuntimeAuthorityReference;
+  /** The registration that was current, made under `replacement`, and live when this was accepted. */
+  acceptedRegistration: IFleetCutoverAcceptedEvidenceReference;
+  actorId: string;
+  acceptedAt: number;
+  digest: TSha256Digest;
+}
+
+export interface IClusterLegacyRelayCredentialRetirementResult {
+  credential: IClusterLegacyRelayCredential;
+  invalidation: IClusterLegacyRelayCredentialInvalidation;
+  /** A replay returns the recorded invalidation; nothing is revoked twice. */
+  replayed: boolean;
+}
+
+export const clusterRelayCredentialContract = Object.freeze({
+  credentialDigestDomain: 'serve.zone/cluster-relay-credential',
+  legacyCredentialDigestDomain: 'serve.zone/cluster-relay-legacy-credential',
+  legacyInvalidationDigestDomain: 'serve.zone/cluster-relay-legacy-credential-invalidation',
+} as const);
+
+/** Every reason Cloudly answers instead of mutating or retiring a cluster relay authority. */
+export const clusterRelayCredentialRefusals = Object.freeze([
+  /** A rotation named a cluster that has no relay credential yet. */
+  'relay-credential-absent',
+  /** A retirement named a cluster whose shared authority no record names. */
+  'legacy-credential-absent',
+  /** The shared authority is already revoked; its invalidation is written once. */
+  'legacy-credential-already-retired',
+  /** The named replacement is not the cluster's relay credential at its current generation. */
+  'legacy-retirement-replacement-not-current',
+  /** The named registration is not current, or it was made under another credential generation. */
+  'legacy-retirement-registration-not-current',
+  /** No verified socket carries the named registration at the instant of acceptance. */
+  'legacy-retirement-relay-not-live',
+  /** An expected generation was not the exact current one, or a mutation ID met a changed body. */
+  'conflict',
+] as const);
+
+export type TClusterRelayCredentialRefusal = typeof clusterRelayCredentialRefusals[number];
+
+const fail = (): never => { throw new Error('Cluster relay credential contract rejected.'); };
+const safe = <T>(operationArg: () => T): T => {
+  try { return operationArg(); } catch { return fail(); }
+};
+
+const secretVersionReference = (valueArg: unknown): ISecretVersionReference => {
+  const value = networkRecord(valueArg, ['secretId', 'secretVersionId']);
+  return {
+    secretId: networkId(value.secretId),
+    secretVersionId: networkId(value.secretVersionId),
+  };
+};
+
+/** Structural copy only; whether the record is the cluster's current one is Cloudly's to decide. */
+export const snapshotClusterRelayCredential = (
+  valueArg: unknown,
+): IClusterRelayCredential => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), [
+    'id', 'clusterId', 'generation', 'userId', 'delivery', 'actorId', 'acceptedAt', 'digest',
+  ]);
+  return {
+    id: networkId(value.id),
+    clusterId: networkId(value.clusterId),
+    generation: networkCounter(value.generation),
+    userId: networkId(value.userId),
+    delivery: secretVersionReference(value.delivery),
+    actorId: networkId(value.actorId),
+    acceptedAt: networkCounter(value.acceptedAt),
+    digest: networkDigest(value.digest),
+  };
+});
+
+export const computeClusterRelayCredentialDigest = async (
+  valueArg: unknown,
+): Promise<TSha256Digest> => networkHash(
+  clusterRelayCredentialContract.credentialDigestDomain,
+  snapshotClusterRelayCredential(valueArg),
+);
+
+export const validateClusterRelayCredential = async (valueArg: unknown): Promise<string[]> => {
+  try {
+    const value = snapshotClusterRelayCredential(valueArg);
+    return value.digest === await computeClusterRelayCredentialDigest(value)
+      ? [] : ['cluster relay credential digest does not match'];
+  } catch { return ['cluster relay credential must use its exact canonical schema']; }
+};
+
+export const snapshotClusterRelayCredentialMutation = (
+  valueArg: unknown,
+): TClusterRelayCredentialMutation => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), [
+    'clusterId', 'mutationId', 'operation', 'expectedGeneration',
+  ]);
+  const base = { clusterId: networkId(value.clusterId), mutationId: networkId(value.mutationId) };
+  const operation = value.operation;
+  requireNetwork(operation === 'ensure' || operation === 'rotate');
+  if (operation === 'ensure') {
+    requireNetwork(value.expectedGeneration === null);
+    return { ...base, operation, expectedGeneration: null };
+  }
+  return { ...base, operation, expectedGeneration: networkCounter(value.expectedGeneration) };
+});
+
+export const snapshotClusterLegacyRelayCredential = (
+  valueArg: unknown,
+): IClusterLegacyRelayCredential => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), [
+    'id', 'clusterId', 'userId', 'generation', 'state', 'invalidation', 'recordedAt', 'digest',
+  ]);
+  const state = value.state;
+  requireNetwork(state === 'active' || state === 'revoked');
+  const generation = networkCounter(value.generation);
+  const invalidation = value.invalidation === null ? null : networkReference(value.invalidation);
+  // Revoked exactly when an invalidation names it, and only as the successor of an active record.
+  requireNetwork(state === 'active'
+    ? invalidation === null
+    : invalidation !== null && invalidation.generation === 1 && generation > 1);
+  return {
+    id: networkId(value.id),
+    clusterId: networkId(value.clusterId),
+    userId: networkId(value.userId),
+    generation,
+    state,
+    invalidation,
+    recordedAt: networkCounter(value.recordedAt),
+    digest: networkDigest(value.digest),
+  };
+});
+
+export const computeClusterLegacyRelayCredentialDigest = async (
+  valueArg: unknown,
+): Promise<TSha256Digest> => networkHash(
+  clusterRelayCredentialContract.legacyCredentialDigestDomain,
+  snapshotClusterLegacyRelayCredential(valueArg),
+);
+
+export const validateClusterLegacyRelayCredential = async (
+  valueArg: unknown,
+): Promise<string[]> => {
+  try {
+    const value = snapshotClusterLegacyRelayCredential(valueArg);
+    return value.digest === await computeClusterLegacyRelayCredentialDigest(value)
+      ? [] : ['cluster legacy relay credential digest does not match'];
+  } catch { return ['cluster legacy relay credential must use its exact canonical schema']; }
+};
+
+export const snapshotClusterLegacyRelayCredentialRetirementRequest = (
+  valueArg: unknown,
+): IClusterLegacyRelayCredentialRetirementRequest => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), [
+    'mutationId', 'clusterId', 'expectedLegacyGeneration', 'replacement', 'acceptedRegistration',
+  ]);
+  return {
+    mutationId: networkId(value.mutationId),
+    clusterId: networkId(value.clusterId),
+    expectedLegacyGeneration: networkCounter(value.expectedLegacyGeneration),
+    replacement: networkReference(value.replacement),
+    acceptedRegistration: networkReference(value.acceptedRegistration),
+  };
+});
+
+export const snapshotClusterLegacyRelayCredentialInvalidation = (
+  valueArg: unknown,
+): IClusterLegacyRelayCredentialInvalidation => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), [
+    'id', 'generation', 'clusterId', 'credential', 'replacement', 'acceptedRegistration',
+    'actorId', 'acceptedAt', 'digest',
+  ]);
+  requireNetwork(value.generation === 1);
+  return {
+    id: networkId(value.id),
+    generation: 1,
+    clusterId: networkId(value.clusterId),
+    credential: networkReference(value.credential),
+    replacement: networkReference(value.replacement),
+    acceptedRegistration: networkReference(value.acceptedRegistration),
+    actorId: networkId(value.actorId),
+    acceptedAt: networkCounter(value.acceptedAt),
+    digest: networkDigest(value.digest),
+  };
+});
+
+export const computeClusterLegacyRelayCredentialInvalidationDigest = async (
+  valueArg: unknown,
+): Promise<TSha256Digest> => networkHash(
+  clusterRelayCredentialContract.legacyInvalidationDigestDomain,
+  snapshotClusterLegacyRelayCredentialInvalidation(valueArg),
+);
+
+export const validateClusterLegacyRelayCredentialInvalidation = async (
+  valueArg: unknown,
+): Promise<string[]> => {
+  try {
+    const value = snapshotClusterLegacyRelayCredentialInvalidation(valueArg);
+    return value.digest === await computeClusterLegacyRelayCredentialInvalidationDigest(value)
+      ? [] : ['cluster legacy relay credential invalidation digest does not match'];
+  } catch {
+    return ['cluster legacy relay credential invalidation must use its exact canonical schema'];
+  }
+};
+
+/**
+ * The active record is named exactly. The revoked one is that record's successor, so it is named
+ * by identity and the generation before it, and it names the invalidation back.
+ */
+const invalidationNamesLegacyCredential = (
+  invalidationArg: IClusterLegacyRelayCredentialInvalidation,
+  legacyCredentialArg: IClusterLegacyRelayCredential,
+): boolean => legacyCredentialArg.state === 'active'
+  ? networkEqual(invalidationArg.credential, networkReferenceOf(legacyCredentialArg))
+  : invalidationArg.credential.id === legacyCredentialArg.id
+    && invalidationArg.credential.generation === legacyCredentialArg.generation - 1
+    && networkEqual(legacyCredentialArg.invalidation, networkReferenceOf(invalidationArg));
+
+/**
+ * Joins an invalidation to the shared authority it revoked and to the registration that justified
+ * it, which must have been made under the very replacement the invalidation names.
+ *
+ * Content join only. Cloudly must still dereference each record as its cluster's current one and
+ * require a live verified socket for the registration while holding its compare-and-swap.
+ */
+export const bindClusterLegacyRelayCredentialInvalidation = async (
+  invalidationArg: unknown,
+  legacyCredentialArg: unknown,
+  acceptedRegistrationArg: unknown,
+): Promise<{
+  invalidation: IClusterLegacyRelayCredentialInvalidation;
+  legacyCredential: IClusterLegacyRelayCredential;
+  acceptedRegistration: IClusterRelayAcceptedRegistration;
+}> => {
+  try {
+    const invalidation = snapshotClusterLegacyRelayCredentialInvalidation(invalidationArg);
+    const legacyCredential = snapshotClusterLegacyRelayCredential(legacyCredentialArg);
+    const acceptedRegistration = snapshotClusterRelayAcceptedRegistration(acceptedRegistrationArg);
+    if ((await validateClusterLegacyRelayCredentialInvalidation(invalidation)).length
+      || (await validateClusterLegacyRelayCredential(legacyCredential)).length
+      || (await validateClusterRelayAcceptedRegistration(acceptedRegistration)).length) fail();
+    requireNetwork(legacyCredential.clusterId === invalidation.clusterId
+      && acceptedRegistration.clusterId === invalidation.clusterId
+      && invalidationNamesLegacyCredential(invalidation, legacyCredential)
+      && networkEqual(invalidation.acceptedRegistration, networkReferenceOf(acceptedRegistration))
+      && networkEqual(invalidation.replacement, acceptedRegistration.credential));
+    return { invalidation, legacyCredential, acceptedRegistration };
+  } catch { return fail(); }
+};

package/ts/data/index.ts

@@ -3,6 +3,7 @@ export * from './cluster.js';
 export * from './clusterruntime.js';
 export * from './clustervpn.js';
 export * from './clusteringress.js';
+export * from './clusterrelaycredential.js';
 export * from './config.js';
 export * from './corestore.js';
 export * from './coremail.js';
@@ -52,6 +53,7 @@ export * from './baseos.js';
 export * from './backup.js';
 export * from './clusternode.js';
 export * from './settings.js';
+export * from './sparklegacyretirement.js';
 export * from './sparknodereport.js';
 export * from './service.js';
 export * from './servicecredential.js';