@serve.zone/interfaces 32.15.0 → 32.17.0

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(); }
+};