@serve.zone/interfaces 23.0.4 → 23.2.0

package/ts/runtime.ts

@@ -1,18 +1,27 @@
 import * as plugins from './plugins.js';
 import type {
+  IActiveSecretRecipientMetadata,
+  IClusterSecretDeploymentState,
+  ICoreflowRuntimeCapabilities,
   IIdentityCredential,
   IResolvedSecretManifest,
+  IResolvedSecretManifestReference,
   TSha256Digest,
+  TImmutableContainerPlatform,
   TSecretRecipientMetadata,
 } from './data/index.js';
 import {
   createResolvedSecretMaterialEnvelopeContext,
   createSecretRecipientEnrollmentChallengeContext,
+  resolvedSecretManifestReferencesEqual,
   validateResolvedSecretManifest,
+  validateResolvedSecretManifestReference,
   validateSecretRecipientMetadata,
+  validateSecretRecipientSet,
   verifySecretEnvelopeContext,
   verifyResolvedSecretManifestDigest,
 } from './data/secret.js';
+import { isSha256Digest } from './data/immutableimage.js';
 
 export interface ISealedResolvedSecretMaterialEntry {
   secretVersionId: string;
@@ -351,3 +360,766 @@ export const validateCompleteSecretRecipientEnrollmentRequest = (
 };
 
 export { validateSecretRecipientMetadata };
+
+const runtimeIdentifierRegex = /^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/;
+const runtimeFailureCodeRegex = /^[A-Z][A-Z0-9_]{0,127}$/;
+const runtimePlatforms = new Set<TImmutableContainerPlatform>([
+  'linux/amd64',
+  'linux/arm64',
+]);
+const maximumRuntimeNodes = 1024;
+
+const isRuntimeRecord = (valueArg: unknown): valueArg is Record<string, unknown> => (
+  Boolean(valueArg) && typeof valueArg === 'object' && !Array.isArray(valueArg)
+);
+
+const hasExactRuntimeKeys = (
+  valueArg: Record<string, unknown>,
+  keysArg: string[],
+): boolean => JSON.stringify(Object.keys(valueArg).sort()) === JSON.stringify([...keysArg].sort());
+
+const hasOnlyRuntimeKeys = (
+  valueArg: Record<string, unknown>,
+  keysArg: string[],
+): boolean => Object.keys(valueArg).every((keyArg) => keysArg.includes(keyArg));
+
+const isRuntimeIdentifier = (valueArg: unknown): valueArg is string => (
+  typeof valueArg === 'string' && runtimeIdentifierRegex.test(valueArg)
+);
+
+const isPositiveSafeInteger = (valueArg: unknown): valueArg is number => (
+  Number.isSafeInteger(valueArg) && (valueArg as number) > 0
+);
+
+const computeRuntimeSha256 = async (inputArg: string): Promise<TSha256Digest> => {
+  const input = new TextEncoder().encode(inputArg);
+  const digest = new Uint8Array(await globalThis.crypto.subtle.digest(
+    'SHA-256',
+    input.buffer as ArrayBuffer,
+  ));
+  return `sha256:${[...digest]
+    .map((byteArg) => byteArg.toString(16).padStart(2, '0'))
+    .join('')}` as TSha256Digest;
+};
+
+export type TSecretRecipientEnrollmentStateV1 =
+  | {
+    schemaVersion: 1;
+    generation: 0;
+    recipients: [];
+  }
+  | {
+    schemaVersion: 1;
+    generation: number;
+    recipients: TSecretRecipientMetadata[];
+  };
+
+/** Cluster scope is derived exclusively from the verified cluster JWT. */
+export interface IReq_GetSecretRecipientEnrollmentState
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_GetSecretRecipientEnrollmentState
+> {
+  method: 'getSecretRecipientEnrollmentState';
+  request: {
+    identity: IIdentityCredential;
+  };
+  response: TSecretRecipientEnrollmentStateV1;
+}
+
+export const validateGetSecretRecipientEnrollmentStateRequest = (
+  requestArg: unknown,
+): string[] => {
+  try {
+    if (!isRuntimeRecord(requestArg)
+      || !hasExactRuntimeKeys(requestArg, ['identity'])
+      || !isRuntimeRecord(requestArg.identity)
+      || !hasExactRuntimeKeys(requestArg.identity, ['jwt'])
+      || typeof requestArg.identity.jwt !== 'string'
+      || requestArg.identity.jwt.length === 0) {
+      return ['secret recipient enrollment state request must contain only a JWT identity'];
+    }
+    return [];
+  } catch {
+    return ['secret recipient enrollment state request must be safely inspectable'];
+  }
+};
+
+export const validateSecretRecipientEnrollmentState = (
+  stateArg: unknown,
+): string[] => {
+  try {
+    if (!isRuntimeRecord(stateArg)
+      || !hasExactRuntimeKeys(stateArg, ['schemaVersion', 'generation', 'recipients'])) {
+      return ['secret recipient enrollment state must use its exact schema'];
+    }
+    const errors: string[] = [];
+    if (stateArg.schemaVersion !== 1) {
+      errors.push('secret recipient enrollment state schemaVersion must be 1');
+    }
+    if (stateArg.generation === 0) {
+      if (!Array.isArray(stateArg.recipients) || stateArg.recipients.length !== 0) {
+        errors.push('generation-zero enrollment state must have no recipients');
+      }
+      return errors;
+    }
+    if (!isPositiveSafeInteger(stateArg.generation)) {
+      errors.push('secret recipient enrollment state generation must be zero or positive');
+    }
+    const recipientErrors = validateSecretRecipientSet(stateArg.recipients);
+    errors.push(...recipientErrors.map((errorArg) => `enrollment state ${errorArg}`));
+    if (recipientErrors.length === 0) {
+      const recipients = stateArg.recipients as TSecretRecipientMetadata[];
+      const greatestGeneration = Math.max(...recipients.map((recipientArg) => recipientArg.generation));
+      if (stateArg.generation !== greatestGeneration) {
+        errors.push('secret recipient enrollment state generation must match the active generation');
+      }
+    }
+    return errors;
+  } catch {
+    return ['secret recipient enrollment state must be safely inspectable'];
+  }
+};
+
+export interface ICoreflowSecretRuntimeNodeTargetV1 {
+  nodeId: string;
+  nodeName: string;
+  platform: TImmutableContainerPlatform;
+}
+
+export interface ICoreflowSecretRuntimeNodeEvidenceV1
+extends ICoreflowSecretRuntimeNodeTargetV1 {
+  workloadInitPlatformManifestDigest: TSha256Digest;
+  workloadInitExecutableDigest: TSha256Digest;
+}
+
+export interface ICoreflowSecretRuntimeArtifactV1 {
+  platform: TImmutableContainerPlatform;
+  workloadInitPlatformManifestDigest: TSha256Digest;
+  workloadInitExecutableDigest: TSha256Digest;
+}
+
+export interface ICoreflowSecretRuntimeRegistrationExpectationV1 {
+  expectationVersion: 1;
+  reporterSessionId: string;
+  targets: ICoreflowSecretRuntimeNodeTargetV1[];
+  workloadInitImageIndexDigest: TSha256Digest;
+  workloadInitArtifacts: ICoreflowSecretRuntimeArtifactV1[];
+  activeRecipient: IActiveSecretRecipientMetadata;
+}
+
+/** Dedicated TypedSocket tag carrying ICoreflowSecretRuntimeRegistrationV1. */
+export const coreflowSecretRuntimeRegistrationTagId =
+  'coreflowSecretRuntimeRegistration' as const;
+
+/** Cluster scope is derived exclusively from the verified cluster JWT. */
+export interface IReq_GetCoreflowSecretRuntimeRegistrationExpectation
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_GetCoreflowSecretRuntimeRegistrationExpectation
+> {
+  method: 'getCoreflowSecretRuntimeRegistrationExpectation';
+  request: {
+    identity: IIdentityCredential;
+  };
+  response: {
+    expectation: ICoreflowSecretRuntimeRegistrationExpectationV1;
+  };
+}
+
+export const validateGetCoreflowSecretRuntimeRegistrationExpectationRequest = (
+  requestArg: unknown,
+): string[] => {
+  try {
+    if (!isRuntimeRecord(requestArg)
+      || !hasExactRuntimeKeys(requestArg, ['identity'])
+      || !isRuntimeRecord(requestArg.identity)
+      || !hasExactRuntimeKeys(requestArg.identity, ['jwt'])
+      || typeof requestArg.identity.jwt !== 'string'
+      || requestArg.identity.jwt.length === 0) {
+      return ['secret runtime registration expectation request must contain only a JWT identity'];
+    }
+    return [];
+  } catch {
+    return ['secret runtime registration expectation request must be safely inspectable'];
+  }
+};
+
+export interface ICoreflowSecretRuntimeRegistrationV1 {
+  registrationVersion: 1;
+  reporterSessionId: string;
+  registeredAt: number;
+  targets: ICoreflowSecretRuntimeNodeTargetV1[];
+  nodeSetDigest: TSha256Digest;
+  nodeEvidence: ICoreflowSecretRuntimeNodeEvidenceV1[];
+  capabilities: ICoreflowRuntimeCapabilities;
+  activeRecipient: IActiveSecretRecipientMetadata;
+  workloadInitImageIndexDigest: TSha256Digest;
+  workloadInitApprovedAt: number;
+}
+
+const compareRuntimeTargets = (
+  leftArg: ICoreflowSecretRuntimeNodeTargetV1,
+  rightArg: ICoreflowSecretRuntimeNodeTargetV1,
+): number => {
+  for (const [left, right] of [
+    [leftArg.nodeId, rightArg.nodeId],
+    [leftArg.nodeName, rightArg.nodeName],
+    [leftArg.platform, rightArg.platform],
+  ]) {
+    if (left < right) return -1;
+    if (left > right) return 1;
+  }
+  return 0;
+};
+
+const canonicalRuntimeTarget = (
+  targetArg: ICoreflowSecretRuntimeNodeTargetV1,
+): ICoreflowSecretRuntimeNodeTargetV1 => ({
+  nodeId: targetArg.nodeId,
+  nodeName: targetArg.nodeName,
+  platform: targetArg.platform,
+});
+
+export const createCoreflowSecretRuntimeNodeSetDigestInput = (
+  targetsArg: ICoreflowSecretRuntimeNodeTargetV1[],
+): string => JSON.stringify({
+  schemaVersion: 1,
+  targets: targetsArg.map(canonicalRuntimeTarget),
+});
+
+export const computeCoreflowSecretRuntimeNodeSetDigest = async (
+  targetsArg: ICoreflowSecretRuntimeNodeTargetV1[],
+): Promise<TSha256Digest> => computeRuntimeSha256(
+  createCoreflowSecretRuntimeNodeSetDigestInput(targetsArg),
+);
+
+const validateRuntimeTargets = (
+  targetsArg: unknown,
+  pathArg: string,
+): string[] => {
+  if (!Array.isArray(targetsArg)
+    || targetsArg.length === 0
+    || targetsArg.length > maximumRuntimeNodes) {
+    return [`${pathArg} must be a non-empty bounded array`];
+  }
+  const errors: string[] = [];
+  let previous: ICoreflowSecretRuntimeNodeTargetV1 | undefined;
+  const nodeIds = new Set<string>();
+  const nodeNames = new Set<string>();
+  for (const [index, targetArg] of targetsArg.entries()) {
+    if (!isRuntimeRecord(targetArg)
+      || !hasExactRuntimeKeys(targetArg, ['nodeId', 'nodeName', 'platform'])) {
+      errors.push(`${pathArg}[${index}] must use its exact schema`);
+      continue;
+    }
+    if (!isRuntimeIdentifier(targetArg.nodeId) || !isRuntimeIdentifier(targetArg.nodeName)) {
+      errors.push(`${pathArg}[${index}] node identity must be canonical`);
+    }
+    if (!runtimePlatforms.has(targetArg.platform as TImmutableContainerPlatform)) {
+      errors.push(`${pathArg}[${index}].platform must be supported`);
+    }
+    if (isRuntimeIdentifier(targetArg.nodeId)
+      && isRuntimeIdentifier(targetArg.nodeName)
+      && runtimePlatforms.has(targetArg.platform as TImmutableContainerPlatform)) {
+      const target = targetArg as unknown as ICoreflowSecretRuntimeNodeTargetV1;
+      if (previous && compareRuntimeTargets(previous, target) >= 0) {
+        errors.push(`${pathArg} must be uniquely sorted by nodeId, nodeName, and platform`);
+      }
+      previous = target;
+      if (nodeIds.has(target.nodeId)) errors.push(`${pathArg} nodeIds must be unique`);
+      if (nodeNames.has(target.nodeName)) errors.push(`${pathArg} nodeNames must be unique`);
+      nodeIds.add(target.nodeId);
+      nodeNames.add(target.nodeName);
+    }
+  }
+  return errors;
+};
+
+const validateRuntimeArtifacts = (
+  artifactsArg: unknown,
+  pathArg: string,
+): string[] => {
+  if (!Array.isArray(artifactsArg)
+    || artifactsArg.length === 0
+    || artifactsArg.length > runtimePlatforms.size) {
+    return [`${pathArg} must be a non-empty bounded array`];
+  }
+  const errors: string[] = [];
+  const platforms: string[] = [];
+  for (const [index, artifactArg] of artifactsArg.entries()) {
+    if (!isRuntimeRecord(artifactArg)
+      || !hasExactRuntimeKeys(artifactArg, [
+        'platform',
+        'workloadInitPlatformManifestDigest',
+        'workloadInitExecutableDigest',
+      ])) {
+      errors.push(`${pathArg}[${index}] must use its exact schema`);
+      continue;
+    }
+    platforms.push(artifactArg.platform as string);
+    if (!runtimePlatforms.has(artifactArg.platform as TImmutableContainerPlatform)) {
+      errors.push(`${pathArg}[${index}].platform must be supported`);
+    }
+    if (typeof artifactArg.workloadInitPlatformManifestDigest !== 'string'
+      || !isSha256Digest(artifactArg.workloadInitPlatformManifestDigest)
+      || typeof artifactArg.workloadInitExecutableDigest !== 'string'
+      || !isSha256Digest(artifactArg.workloadInitExecutableDigest)) {
+      errors.push(`${pathArg}[${index}] digests must be canonical`);
+    }
+  }
+  if (new Set(platforms).size !== platforms.length
+    || JSON.stringify(platforms) !== JSON.stringify([...platforms].sort())) {
+    errors.push(`${pathArg} must be uniquely sorted by platform`);
+  }
+  return errors;
+};
+
+const activeRecipientFingerprint = (recipientArg: IActiveSecretRecipientMetadata): string => (
+  JSON.stringify({
+    schemaVersion: recipientArg.schemaVersion,
+    recipientKeyId: recipientArg.recipientKeyId,
+    publicKey: recipientArg.publicKey,
+    generation: recipientArg.generation,
+    activatedAt: recipientArg.activatedAt,
+    lifecycleState: recipientArg.lifecycleState,
+  })
+);
+
+/**
+ * Consumers discard this registration on transport disconnect, tag
+ * removal/replacement, reporter-session change, or any expectation change.
+ */
+export const validateCoreflowSecretRuntimeRegistration = async (
+  registrationArg: unknown,
+  expectationArg: unknown,
+): Promise<string[]> => {
+  try {
+    const errors: string[] = [];
+    if (!isRuntimeRecord(expectationArg)
+      || !hasExactRuntimeKeys(expectationArg, [
+        'expectationVersion',
+        'reporterSessionId',
+        'targets',
+        'workloadInitImageIndexDigest',
+        'workloadInitArtifacts',
+        'activeRecipient',
+      ])) {
+      return ['secret runtime registration expectation must use its exact schema'];
+    }
+    if (expectationArg.expectationVersion !== 1) {
+      errors.push('secret runtime registration expectationVersion must be 1');
+    }
+    if (!isRuntimeIdentifier(expectationArg.reporterSessionId)) {
+      errors.push('expected secret runtime reporterSessionId must be canonical');
+    }
+    const expectedTargetErrors = validateRuntimeTargets(expectationArg.targets, 'expected targets');
+    errors.push(...expectedTargetErrors);
+    errors.push(...validateRuntimeArtifacts(
+      expectationArg.workloadInitArtifacts,
+      'expected WorkloadInit artifacts',
+    ));
+    if (typeof expectationArg.workloadInitImageIndexDigest !== 'string'
+      || !isSha256Digest(expectationArg.workloadInitImageIndexDigest)) {
+      errors.push('expected WorkloadInit image index digest must be canonical');
+    }
+    const expectedRecipientErrors = validateSecretRecipientMetadata(expectationArg.activeRecipient);
+    if (expectedRecipientErrors.length > 0
+      || !isRuntimeRecord(expectationArg.activeRecipient)
+      || expectationArg.activeRecipient.lifecycleState !== 'active') {
+      errors.push('expected secret recipient must be canonical and active');
+    }
+    if (!isRuntimeRecord(registrationArg)
+      || !hasExactRuntimeKeys(registrationArg, [
+        'registrationVersion',
+        'reporterSessionId',
+        'registeredAt',
+        'targets',
+        'nodeSetDigest',
+        'nodeEvidence',
+        'capabilities',
+        'activeRecipient',
+        'workloadInitImageIndexDigest',
+        'workloadInitApprovedAt',
+      ])) {
+      errors.push('secret runtime registration must use its exact schema');
+      return errors;
+    }
+    if (registrationArg.registrationVersion !== 1) {
+      errors.push('secret runtime registrationVersion must be 1');
+    }
+    if (!isRuntimeIdentifier(registrationArg.reporterSessionId)) {
+      errors.push('secret runtime reporterSessionId must be canonical');
+    } else if (registrationArg.reporterSessionId !== expectationArg.reporterSessionId) {
+      errors.push('secret runtime reporterSessionId does not match the live session');
+    }
+    if (!isPositiveSafeInteger(registrationArg.registeredAt)
+      || !isPositiveSafeInteger(registrationArg.workloadInitApprovedAt)) {
+      errors.push('secret runtime registration timestamps must be positive integers');
+    }
+    const registrationTargetErrors = validateRuntimeTargets(
+      registrationArg.targets,
+      'registration targets',
+    );
+    errors.push(...registrationTargetErrors);
+    if (typeof registrationArg.nodeSetDigest !== 'string'
+      || !isSha256Digest(registrationArg.nodeSetDigest)) {
+      errors.push('secret runtime nodeSetDigest must be canonical');
+    }
+    if (typeof registrationArg.workloadInitImageIndexDigest !== 'string'
+      || !isSha256Digest(registrationArg.workloadInitImageIndexDigest)) {
+      errors.push('secret runtime WorkloadInit image index digest must be canonical');
+    }
+    const registrationRecipientErrors = validateSecretRecipientMetadata(registrationArg.activeRecipient);
+    if (registrationRecipientErrors.length > 0
+      || !isRuntimeRecord(registrationArg.activeRecipient)
+      || registrationArg.activeRecipient.lifecycleState !== 'active') {
+      errors.push('secret runtime registration recipient must be canonical and active');
+    }
+    if (!isRuntimeRecord(registrationArg.capabilities)
+      || !hasOnlyRuntimeKeys(registrationArg.capabilities, [
+        'immutableImageDeploymentVersion',
+        'corestoreInventoryVersion',
+        'secretManifestVersion',
+        'sealedSecretMaterialVersion',
+        'secretRecipientEnrollmentVersion',
+        'workloadInitEnvironmentVersion',
+        'secretDeploymentReportVersion',
+      ])
+      || registrationArg.capabilities.immutableImageDeploymentVersion !== 1
+      || registrationArg.capabilities.secretManifestVersion !== 2
+      || registrationArg.capabilities.sealedSecretMaterialVersion !== 1
+      || registrationArg.capabilities.secretRecipientEnrollmentVersion !== 1
+      || registrationArg.capabilities.workloadInitEnvironmentVersion !== 1
+      || registrationArg.capabilities.secretDeploymentReportVersion !== 1
+      || (registrationArg.capabilities.corestoreInventoryVersion !== undefined
+        && registrationArg.capabilities.corestoreInventoryVersion !== 1)) {
+      errors.push('secret runtime registration capabilities are incomplete or unsupported');
+    }
+    if (!Array.isArray(registrationArg.nodeEvidence)
+      || registrationArg.nodeEvidence.length === 0
+      || registrationArg.nodeEvidence.length > maximumRuntimeNodes) {
+      errors.push('secret runtime node evidence must be a non-empty bounded array');
+    } else {
+      const evidenceTargets: ICoreflowSecretRuntimeNodeTargetV1[] = [];
+      const evidenceArtifacts: ICoreflowSecretRuntimeArtifactV1[] = [];
+      for (const [index, evidenceArg] of registrationArg.nodeEvidence.entries()) {
+        if (!isRuntimeRecord(evidenceArg)
+          || !hasExactRuntimeKeys(evidenceArg, [
+            'nodeId',
+            'nodeName',
+            'platform',
+            'workloadInitPlatformManifestDigest',
+            'workloadInitExecutableDigest',
+          ])) {
+          errors.push(`secret runtime nodeEvidence[${index}] must use its exact schema`);
+          continue;
+        }
+        evidenceTargets.push({
+          nodeId: evidenceArg.nodeId as string,
+          nodeName: evidenceArg.nodeName as string,
+          platform: evidenceArg.platform as TImmutableContainerPlatform,
+        });
+        evidenceArtifacts.push({
+          platform: evidenceArg.platform as TImmutableContainerPlatform,
+          workloadInitPlatformManifestDigest:
+            evidenceArg.workloadInitPlatformManifestDigest as TSha256Digest,
+          workloadInitExecutableDigest: evidenceArg.workloadInitExecutableDigest as TSha256Digest,
+        });
+        if (typeof evidenceArg.workloadInitPlatformManifestDigest !== 'string'
+          || !isSha256Digest(evidenceArg.workloadInitPlatformManifestDigest)
+          || typeof evidenceArg.workloadInitExecutableDigest !== 'string'
+          || !isSha256Digest(evidenceArg.workloadInitExecutableDigest)) {
+          errors.push(`secret runtime nodeEvidence[${index}] digests must be canonical`);
+        }
+      }
+      errors.push(...validateRuntimeTargets(evidenceTargets, 'secret runtime evidence targets'));
+      if (JSON.stringify(evidenceTargets) !== JSON.stringify(registrationArg.targets)) {
+        errors.push('secret runtime node evidence must exactly cover registration targets in order');
+      }
+      const expectedArtifacts = new Map<
+        TImmutableContainerPlatform,
+        ICoreflowSecretRuntimeArtifactV1
+      >((expectationArg.workloadInitArtifacts as ICoreflowSecretRuntimeArtifactV1[])
+        .map((artifactArg) => [artifactArg.platform, artifactArg]));
+      for (const [index, artifactArg] of evidenceArtifacts.entries()) {
+        const expectedArtifact = expectedArtifacts.get(artifactArg.platform);
+        if (!expectedArtifact
+          || expectedArtifact.workloadInitPlatformManifestDigest
+            !== artifactArg.workloadInitPlatformManifestDigest
+          || expectedArtifact.workloadInitExecutableDigest
+            !== artifactArg.workloadInitExecutableDigest) {
+          errors.push(`secret runtime nodeEvidence[${index}] does not match the approved artifact`);
+        }
+      }
+    }
+    if (JSON.stringify(registrationArg.targets) !== JSON.stringify(expectationArg.targets)) {
+      errors.push('secret runtime registration must exactly cover authoritative target nodes');
+    }
+    if (expectedTargetErrors.length === 0 && registrationTargetErrors.length === 0) {
+      const expectedNodeSetDigest = await computeCoreflowSecretRuntimeNodeSetDigest(
+        expectationArg.targets as ICoreflowSecretRuntimeNodeTargetV1[],
+      );
+      if (registrationArg.nodeSetDigest !== expectedNodeSetDigest) {
+        errors.push('secret runtime nodeSetDigest does not match authoritative target nodes');
+      }
+    }
+    if (registrationArg.workloadInitImageIndexDigest
+      !== expectationArg.workloadInitImageIndexDigest) {
+      errors.push('secret runtime WorkloadInit image index is not approved');
+    }
+    if (registrationRecipientErrors.length === 0 && expectedRecipientErrors.length === 0
+      && activeRecipientFingerprint(
+        registrationArg.activeRecipient as unknown as IActiveSecretRecipientMetadata,
+      ) !== activeRecipientFingerprint(
+        expectationArg.activeRecipient as unknown as IActiveSecretRecipientMetadata,
+      )) {
+      errors.push('secret runtime registration recipient does not match the active recipient');
+    }
+    return errors;
+  } catch {
+    return ['secret runtime registration and expectation must be safely inspectable'];
+  }
+};
+
+interface ISecretDeploymentReportBaseV1 {
+  schemaVersion: 1;
+  reporterSessionId: string;
+  reportSequence: number;
+  serviceId: string;
+  expectedPlanRevision: number;
+  desiredManifest: IResolvedSecretManifestReference;
+  reportedAt: number;
+  reportDigest: TSha256Digest;
+}
+
+export interface ISecretDeploymentApplyingReportV1 extends ISecretDeploymentReportBaseV1 {
+  status: 'applying';
+}
+
+export interface ISecretDeploymentAppliedReportV1 extends ISecretDeploymentReportBaseV1 {
+  status: 'applied';
+  appliedManifest: IResolvedSecretManifestReference;
+}
+
+export interface ISecretDeploymentDriftedReportV1 extends ISecretDeploymentReportBaseV1 {
+  status: 'drifted';
+  observedManifest?: IResolvedSecretManifestReference;
+  failureCode: string;
+}
+
+export interface ISecretDeploymentFailedReportV1 extends ISecretDeploymentReportBaseV1 {
+  status: 'failed';
+  failureCode: string;
+}
+
+export type TSecretDeploymentReportV1 =
+  | ISecretDeploymentApplyingReportV1
+  | ISecretDeploymentAppliedReportV1
+  | ISecretDeploymentDriftedReportV1
+  | ISecretDeploymentFailedReportV1;
+
+export type TSecretDeploymentReportWithoutDigestV1 =
+  | Omit<ISecretDeploymentApplyingReportV1, 'reportDigest'>
+  | Omit<ISecretDeploymentAppliedReportV1, 'reportDigest'>
+  | Omit<ISecretDeploymentDriftedReportV1, 'reportDigest'>
+  | Omit<ISecretDeploymentFailedReportV1, 'reportDigest'>;
+
+export interface ISecretDeploymentReportResponseV1 {
+  schemaVersion: 1;
+  acceptedSequence: number;
+  planRevision: number;
+  clusterState: IClusterSecretDeploymentState;
+}
+
+export interface IReq_ReportSecretDeploymentState
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_ReportSecretDeploymentState
+> {
+  method: 'reportSecretDeploymentState';
+  request: TSecretDeploymentReportV1 & {
+    identity: IIdentityCredential;
+  };
+  response: ISecretDeploymentReportResponseV1;
+}
+
+const canonicalManifestReference = (
+  referenceArg: IResolvedSecretManifestReference,
+): IResolvedSecretManifestReference => ({
+  manifestId: referenceArg.manifestId,
+  manifestDigest: referenceArg.manifestDigest,
+  clusterId: referenceArg.clusterId,
+  imageRolloutId: referenceArg.imageRolloutId,
+  imageRolloutGeneration: referenceArg.imageRolloutGeneration,
+  requestedImageDigest: referenceArg.requestedImageDigest,
+  invocationDigest: referenceArg.invocationDigest,
+  secretRolloutId: referenceArg.secretRolloutId,
+  secretRolloutGeneration: referenceArg.secretRolloutGeneration,
+});
+
+export const createSecretDeploymentReportDigestInput = (
+  reportArg: TSecretDeploymentReportWithoutDigestV1 | TSecretDeploymentReportV1,
+): string => {
+  const common = {
+    schemaVersion: reportArg.schemaVersion,
+    reporterSessionId: reportArg.reporterSessionId,
+    reportSequence: reportArg.reportSequence,
+    serviceId: reportArg.serviceId,
+    expectedPlanRevision: reportArg.expectedPlanRevision,
+    desiredManifest: canonicalManifestReference(reportArg.desiredManifest),
+    status: reportArg.status,
+  };
+  if (reportArg.status === 'applied') {
+    return JSON.stringify({
+      ...common,
+      appliedManifest: canonicalManifestReference(reportArg.appliedManifest),
+      reportedAt: reportArg.reportedAt,
+    });
+  }
+  if (reportArg.status === 'drifted') {
+    return JSON.stringify({
+      ...common,
+      ...(reportArg.observedManifest
+        ? { observedManifest: canonicalManifestReference(reportArg.observedManifest) }
+        : {}),
+      failureCode: reportArg.failureCode,
+      reportedAt: reportArg.reportedAt,
+    });
+  }
+  if (reportArg.status === 'failed') {
+    return JSON.stringify({
+      ...common,
+      failureCode: reportArg.failureCode,
+      reportedAt: reportArg.reportedAt,
+    });
+  }
+  return JSON.stringify({ ...common, reportedAt: reportArg.reportedAt });
+};
+
+export const computeSecretDeploymentReportDigest = async (
+  reportArg: TSecretDeploymentReportWithoutDigestV1 | TSecretDeploymentReportV1,
+): Promise<TSha256Digest> => computeRuntimeSha256(
+  createSecretDeploymentReportDigestInput(reportArg),
+);
+
+export const verifySecretDeploymentReportDigest = async (
+  reportArg: unknown,
+): Promise<boolean> => {
+  try {
+    if (!isRuntimeRecord(reportArg)
+      || typeof reportArg.reportDigest !== 'string'
+      || !isSha256Digest(reportArg.reportDigest)) {
+      return false;
+    }
+    return reportArg.reportDigest === await computeSecretDeploymentReportDigest(
+      reportArg as unknown as TSecretDeploymentReportV1,
+    );
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * The expected cluster and reporter session come from the consumer's verified
+ * live connection authority and are deliberately not accepted from the wire.
+ */
+export const validateSecretDeploymentReportRequest = async (
+  requestArg: unknown,
+  expectedClusterIdArg: string,
+  expectedReporterSessionIdArg: string,
+): Promise<string[]> => {
+  try {
+    if (!isRuntimeIdentifier(expectedClusterIdArg)) {
+      return ['trusted expected cluster id must be canonical'];
+    }
+    if (!isRuntimeIdentifier(expectedReporterSessionIdArg)) {
+      return ['trusted expected reporter session id must be canonical'];
+    }
+    if (!isRuntimeRecord(requestArg)) {
+      return ['secret deployment report request must be an object'];
+    }
+    const status = requestArg.status;
+    const commonKeys = [
+      'identity',
+      'schemaVersion',
+      'reporterSessionId',
+      'reportSequence',
+      'serviceId',
+      'expectedPlanRevision',
+      'desiredManifest',
+      'status',
+      'reportedAt',
+      'reportDigest',
+    ];
+    const expectedKeys = status === 'applied'
+      ? [...commonKeys, 'appliedManifest']
+      : status === 'drifted'
+        ? [...commonKeys, 'failureCode', ...(requestArg.observedManifest === undefined
+          ? []
+          : ['observedManifest'])]
+        : status === 'failed'
+          ? [...commonKeys, 'failureCode']
+          : commonKeys;
+    const errors: string[] = [];
+    if (!['applying', 'applied', 'drifted', 'failed'].includes(status as string)
+      || !hasExactRuntimeKeys(requestArg, expectedKeys)) {
+      errors.push('secret deployment report must use its exact status schema');
+    }
+    if (!isRuntimeRecord(requestArg.identity)
+      || !hasExactRuntimeKeys(requestArg.identity, ['jwt'])
+      || typeof requestArg.identity.jwt !== 'string'
+      || requestArg.identity.jwt.length === 0) {
+      errors.push('secret deployment report requires a JWT identity');
+    }
+    if (requestArg.schemaVersion !== 1) {
+      errors.push('secret deployment report schemaVersion must be 1');
+    }
+    if (!isRuntimeIdentifier(requestArg.reporterSessionId)
+      || !isRuntimeIdentifier(requestArg.serviceId)) {
+      errors.push('secret deployment report identity fields must be canonical');
+    } else if (requestArg.reporterSessionId !== expectedReporterSessionIdArg) {
+      errors.push('secret deployment report reporterSessionId does not match the live session');
+    }
+    if (!isPositiveSafeInteger(requestArg.reportSequence)
+      || !isPositiveSafeInteger(requestArg.expectedPlanRevision)
+      || !isPositiveSafeInteger(requestArg.reportedAt)) {
+      errors.push('secret deployment report revisions, sequence, and timestamp must be positive integers');
+    }
+    errors.push(...validateResolvedSecretManifestReference(
+      requestArg.desiredManifest,
+      expectedClusterIdArg,
+    ).map((errorArg) => `desiredManifest: ${errorArg}`));
+    if (status === 'applied') {
+      errors.push(...validateResolvedSecretManifestReference(
+        requestArg.appliedManifest,
+        expectedClusterIdArg,
+      ).map((errorArg) => `appliedManifest: ${errorArg}`));
+      if (!resolvedSecretManifestReferencesEqual(
+        requestArg.appliedManifest as IResolvedSecretManifestReference,
+        requestArg.desiredManifest as IResolvedSecretManifestReference,
+      )) {
+        errors.push('applied secret deployment report must apply the desired manifest');
+      }
+    }
+    if (status === 'drifted' && requestArg.observedManifest !== undefined) {
+      errors.push(...validateResolvedSecretManifestReference(
+        requestArg.observedManifest,
+        expectedClusterIdArg,
+      ).map((errorArg) => `observedManifest: ${errorArg}`));
+    }
+    if ((status === 'drifted' || status === 'failed')
+      && (typeof requestArg.failureCode !== 'string'
+        || !runtimeFailureCodeRegex.test(requestArg.failureCode))) {
+      errors.push('secret deployment report failureCode must be canonical');
+    }
+    if (typeof requestArg.reportDigest !== 'string'
+      || !isSha256Digest(requestArg.reportDigest)
+      || !await verifySecretDeploymentReportDigest(requestArg)) {
+      errors.push('secret deployment report digest does not match its canonical payload');
+    }
+    return errors;
+  } catch {
+    return ['secret deployment report request must be safely inspectable'];
+  }
+};