@serve.zone/interfaces 19.8.0 → 20.1.0

package/ts/data/secret.ts

@@ -0,0 +1,835 @@
+import type { TSha256Digest } from './immutableimage.js';
+import { normalizeServiceAbsolutePath } from './service.js';
+
+export type TSecretEnvironment = string;
+
+export type TSecretLifecycleState =
+  | 'active'
+  | 'retired'
+  | 'revoked'
+  | 'deleted';
+
+export type TSecretVersionLifecycleState =
+  | 'active'
+  | 'retired'
+  | 'revoked'
+  | 'purged';
+
+/** Retired versions remain usable only through an already-accepted manifest. */
+export const isSecretVersionMaterialIssuable = (
+  lifecycleStateArg: TSecretVersionLifecycleState,
+): boolean => lifecycleStateArg === 'active' || lifecycleStateArg === 'retired';
+
+export type TSecretManagementSource =
+  | 'operator'
+  | 'legacy'
+  | 'appstore'
+  | 'mail'
+  | 'oidc'
+  | 'webpush'
+  | 'platform'
+  | 'system';
+
+export type TSecretManagementScope =
+  | 'operator'
+  | 'legacy'
+  | `appstore:${string}`
+  | `mail:${string}`
+  | `oidc:${string}`
+  | `webpush:${string}`
+  | `platform:${string}`
+  | `system:${string}`;
+
+export interface IServiceSecretOwner {
+  kind: 'service';
+  serviceId: string;
+}
+
+export interface ISecretSetSecretOwner {
+  kind: 'secret-set';
+  secretSetId: string;
+}
+
+export type TSecretOwner = IServiceSecretOwner | ISecretSetSecretOwner;
+
+export interface ISecretVersionReference {
+  secretId: string;
+  secretVersionId: string;
+}
+
+export type TSecretVersionRetentionReferenceKind =
+  | 'desired-manifest'
+  | 'applied-manifest'
+  | 'previous-accepted-manifest'
+  | 'rollback-manifest'
+  | 'backup'
+  | 'retention-window';
+
+export interface ISecretVersionRetentionReference {
+  kind: TSecretVersionRetentionReferenceKind;
+  resourceId: string;
+  expiresAt?: number;
+}
+
+/** Browser-safe logical secret metadata. It never contains value material. */
+export interface ISecretMetadata {
+  id: string;
+  organizationId: string;
+  owner: TSecretOwner;
+  key: string;
+  environment: TSecretEnvironment;
+  name: string;
+  description?: string;
+  tags: Array<{ key: string; value: string }>;
+  managementSource: TSecretManagementSource;
+  /** Exact reconciliation owner, for example operator or appstore:<appId>. */
+  managementScope: TSecretManagementScope;
+  defaultDelivery: TSecretDelivery;
+  lifecycleState: TSecretLifecycleState;
+  activeVersion?: ISecretVersionReference;
+  versionCount: number;
+  revision: number;
+  createdAt: number;
+  updatedAt: number;
+  lastRotatedAt?: number;
+}
+
+/** Browser-safe immutable-version metadata. It never contains an encrypted envelope. */
+export interface ISecretVersionMetadata {
+  id: string;
+  secretId: string;
+  lifecycleState: TSecretVersionLifecycleState;
+  createdAt: number;
+  createdBy: string;
+  source: TSecretManagementSource;
+  retiredAt?: number;
+  revokedAt?: number;
+  purgedAt?: number;
+}
+
+export interface ISecretSetMetadata {
+  id: string;
+  organizationId: string;
+  name: string;
+  description?: string;
+  lifecycleState: 'active' | 'retired' | 'deleted';
+  revision: number;
+  /** Dedicated CAS revision for secrets owned by this set. */
+  secretsRevision: number;
+  currentConsumerRollout?: ISecretSetConsumerRolloutSummary;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export type TSecretSetConsumerRolloutStatus =
+  | 'pending'
+  | 'published'
+  | 'applied'
+  | 'failed';
+
+export interface ISecretSetConsumerRolloutSummary {
+  rolloutId: string;
+  secretId: string;
+  secretVersionId: string;
+  totalConsumers: number;
+  pendingConsumers: number;
+  failedConsumers: number;
+  updatedAt: number;
+}
+
+export interface ISecretSetConsumerRolloutStatus {
+  serviceId: string;
+  status: TSecretSetConsumerRolloutStatus;
+  desiredManifestIds: string[];
+  appliedManifestIds: string[];
+  errorCode?: string;
+  updatedAt: number;
+}
+
+export interface ISecretEnvironmentDelivery {
+  type: 'environment';
+  variableName: string;
+}
+
+export interface ISecretFileDelivery {
+  type: 'file';
+  targetPath: string;
+  uid: number;
+  gid: number;
+  mode: number;
+}
+
+export type TSecretDelivery = ISecretEnvironmentDelivery | ISecretFileDelivery;
+
+export interface ISecretSetAttachmentMapping {
+  /** Source key in the attached SecretSet. */
+  sourceKey: string;
+  /** Final service key. Defaults to sourceKey. */
+  targetKey?: string;
+  /** Optional service-specific delivery override. */
+  delivery?: TSecretDelivery;
+}
+
+export interface ISecretSetAttachment {
+  id: string;
+  secretSetId: string;
+  environment: TSecretEnvironment;
+  mappings?: ISecretSetAttachmentMapping[];
+}
+
+/**
+ * Caller-managed value-free inputs to service secret resolution.
+ * Cloudly verifies organization ownership when resolving the referenced sets.
+ */
+export interface IServiceSecretConfiguration {
+  schemaVersion: 1;
+  /** Dedicated CAS revision for SecretSet attachments. */
+  revision: number;
+  /** Dedicated CAS revision for service-owned secret membership. */
+  secretsRevision: number;
+  secretSetAttachments: ISecretSetAttachment[];
+}
+
+export interface IResolvedSecretManifestEntry {
+  secretId: string;
+  secretVersionId: string;
+  key: string;
+  environment: TSecretEnvironment;
+  owner: TSecretOwner;
+  delivery: TSecretDelivery;
+}
+
+/** Immutable, value-free runtime snapshot. */
+export interface IResolvedSecretManifest {
+  schemaVersion: 1;
+  id: string;
+  digest: TSha256Digest;
+  organizationId: string;
+  serviceId: string;
+  clusterId: string;
+  secretRolloutId: string;
+  secretRolloutGeneration: number;
+  entries: IResolvedSecretManifestEntry[];
+  createdAt: number;
+}
+
+export interface IResolvedSecretManifestReference {
+  manifestId: string;
+  manifestDigest: TSha256Digest;
+  clusterId: string;
+  secretRolloutId: string;
+  secretRolloutGeneration: number;
+}
+
+export interface IAcceptedPreviousSecretManifest {
+  manifest: IResolvedSecretManifestReference;
+  /** Exclusive material-issuance deadline for tasks draining the previous rollout. */
+  acceptedUntil: number;
+}
+
+export type TClusterSecretDeploymentStatus =
+  | 'pending'
+  | 'applying'
+  | 'applied'
+  | 'drifted'
+  | 'failed';
+
+export interface IClusterSecretDeploymentState {
+  clusterId: string;
+  desiredManifest: IResolvedSecretManifestReference;
+  appliedManifest?: IResolvedSecretManifestReference;
+  previousAcceptedManifest?: IAcceptedPreviousSecretManifest;
+  status: TClusterSecretDeploymentStatus;
+  updatedAt: number;
+}
+
+/** Server-managed per-cluster authority switched with an expected revision CAS. */
+export interface IServiceSecretDeploymentPlan {
+  schemaVersion: 1;
+  revision: number;
+  clusterStates: IClusterSecretDeploymentState[];
+  updatedAt: number;
+}
+
+export const resolvedSecretManifestReferencesEqual = (
+  leftArg: IResolvedSecretManifestReference | undefined,
+  rightArg: IResolvedSecretManifestReference | undefined,
+): boolean => (
+  Boolean(leftArg)
+  && Boolean(rightArg)
+  && leftArg?.manifestId === rightArg?.manifestId
+  && leftArg?.manifestDigest === rightArg?.manifestDigest
+  && leftArg?.clusterId === rightArg?.clusterId
+  && leftArg?.secretRolloutId === rightArg?.secretRolloutId
+  && leftArg?.secretRolloutGeneration === rightArg?.secretRolloutGeneration
+);
+
+export const isResolvedSecretManifestReferenceAccepted = (
+  stateArg: IClusterSecretDeploymentState,
+  referenceArg: IResolvedSecretManifestReference,
+  nowArg: number,
+): boolean => (
+  resolvedSecretManifestReferencesEqual(stateArg.desiredManifest, referenceArg)
+  || resolvedSecretManifestReferencesEqual(stateArg.appliedManifest, referenceArg)
+  || (
+    Boolean(stateArg.previousAcceptedManifest)
+    && nowArg < stateArg.previousAcceptedManifest!.acceptedUntil
+    && resolvedSecretManifestReferencesEqual(
+      stateArg.previousAcceptedManifest!.manifest,
+      referenceArg,
+    )
+  )
+);
+
+const secretIdentifierRegex = /^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/;
+const secretEnvironmentRegex = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const secretKeyRegex = /^[A-Z_][A-Z0-9_]{0,252}$/;
+const secretDigestRegex = /^sha256:[a-f0-9]{64}$/;
+const secretManagementScopeRegex =
+  /^(appstore|mail|oidc|webpush|platform|system):[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/;
+
+const isRecord = (valueArg: unknown): valueArg is Record<string, unknown> => (
+  Boolean(valueArg) && typeof valueArg === 'object' && !Array.isArray(valueArg)
+);
+
+const isSecretIdentifier = (valueArg: unknown): valueArg is string => (
+  typeof valueArg === 'string' && secretIdentifierRegex.test(valueArg)
+);
+
+const isSecretKey = (valueArg: unknown): valueArg is string => (
+  typeof valueArg === 'string' && secretKeyRegex.test(valueArg)
+);
+
+const isSecretEnvironment = (valueArg: unknown): valueArg is string => (
+  typeof valueArg === 'string' && secretEnvironmentRegex.test(valueArg)
+);
+
+export const validateSecretManagementScope = (
+  sourceArg: TSecretManagementSource,
+  scopeArg: unknown,
+): string[] => {
+  if (scopeArg === 'operator') {
+    return sourceArg === 'operator'
+      ? []
+      : ['operator management scope requires operator source'];
+  }
+  if (scopeArg === 'legacy') {
+    return sourceArg === 'legacy'
+      ? []
+      : ['legacy management scope requires legacy source'];
+  }
+  if (typeof scopeArg !== 'string' || !secretManagementScopeRegex.test(scopeArg)) {
+    return ['management scope must be canonical'];
+  }
+  return scopeArg.startsWith(`${sourceArg}:`)
+    ? []
+    : ['management scope prefix must match management source'];
+};
+
+export const validateSecretDelivery = (deliveryArg: unknown): string[] => {
+  if (!isRecord(deliveryArg)) return ['delivery must be an object'];
+  if (deliveryArg.type === 'environment') {
+    return isSecretKey(deliveryArg.variableName)
+      ? []
+      : ['environment delivery variableName must be a canonical environment key'];
+  }
+  if (deliveryArg.type !== 'file') {
+    return ['delivery type must be environment or file'];
+  }
+  const errors: string[] = [];
+  if (typeof deliveryArg.targetPath !== 'string'
+    || normalizeServiceAbsolutePath(deliveryArg.targetPath) !== deliveryArg.targetPath
+    || !/^\/run\/secrets\/[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(deliveryArg.targetPath)
+    || deliveryArg.targetPath === '/run/secrets/secret.json') {
+    errors.push('file delivery targetPath must be a canonical file below /run/secrets');
+  }
+  for (const field of ['uid', 'gid'] as const) {
+    const value = deliveryArg[field];
+    if (!Number.isSafeInteger(value)
+      || (value as number) < 0
+      || (value as number) > 2_147_483_647) {
+      errors.push(`file delivery ${field} must be a bounded numeric identity`);
+    }
+  }
+  if (deliveryArg.mode !== 0o400 && deliveryArg.mode !== 0o440) {
+    errors.push('file delivery mode must be 0400 or 0440');
+  }
+  return errors;
+};
+
+/**
+ * One shared precedence rule for resolution and runtime verification.
+ * A manifest is authoritative once published; before publication an attachment
+ * override wins over the Secret default.
+ */
+export const resolveSecretDelivery = (deliveryArg: {
+  secretDefault: TSecretDelivery;
+  attachmentOverride?: TSecretDelivery;
+  manifestDelivery?: TSecretDelivery;
+}): TSecretDelivery => (
+  deliveryArg.manifestDelivery
+  ?? deliveryArg.attachmentOverride
+  ?? deliveryArg.secretDefault
+);
+
+export const validateServiceSecretConfiguration = (
+  configurationArg: unknown,
+): string[] => {
+  if (!isRecord(configurationArg)) {
+    return ['secretConfiguration must be an object'];
+  }
+  if (configurationArg.schemaVersion !== 1) {
+    return ['secretConfiguration schemaVersion must be 1'];
+  }
+  if (!Array.isArray(configurationArg.secretSetAttachments)) {
+    return ['secretSetAttachments must be an array'];
+  }
+  if (configurationArg.secretSetAttachments.length > 64) {
+    return ['secretSetAttachments must contain at most 64 entries'];
+  }
+  const errors: string[] = [];
+  if (!Number.isSafeInteger(configurationArg.revision)
+    || (configurationArg.revision as number) < 0) {
+    errors.push('secretConfiguration revision must be a non-negative integer');
+  }
+  if (!Number.isSafeInteger(configurationArg.secretsRevision)
+    || (configurationArg.secretsRevision as number) < 0) {
+    errors.push('secretConfiguration secretsRevision must be a non-negative integer');
+  }
+  const attachmentIds: string[] = [];
+  const setEnvironmentKeys: string[] = [];
+  for (const [attachmentIndex, candidate] of configurationArg.secretSetAttachments.entries()) {
+    if (!isRecord(candidate)) {
+      errors.push(`secretSetAttachments[${attachmentIndex}] must be an object`);
+      continue;
+    }
+    if (!isSecretIdentifier(candidate.id)) {
+      errors.push(`secretSetAttachments[${attachmentIndex}].id must be a canonical identifier`);
+    } else {
+      attachmentIds.push(candidate.id);
+    }
+    if (!isSecretIdentifier(candidate.secretSetId)) {
+      errors.push(
+        `secretSetAttachments[${attachmentIndex}].secretSetId must be a canonical identifier`,
+      );
+    }
+    if (!isSecretEnvironment(candidate.environment)) {
+      errors.push(
+        `secretSetAttachments[${attachmentIndex}].environment must be a canonical environment`,
+      );
+    }
+    if (isSecretIdentifier(candidate.secretSetId)
+      && isSecretEnvironment(candidate.environment)) {
+      setEnvironmentKeys.push(`${candidate.secretSetId}\0${candidate.environment}`);
+    }
+    if (candidate.mappings === undefined) continue;
+    if (!Array.isArray(candidate.mappings) || candidate.mappings.length > 128) {
+      errors.push(`secretSetAttachments[${attachmentIndex}].mappings must be a bounded array`);
+      continue;
+    }
+    const sourceKeys: string[] = [];
+    const targetKeys: string[] = [];
+    for (const [mappingIndex, mappingCandidate] of candidate.mappings.entries()) {
+      if (!isRecord(mappingCandidate)) {
+        errors.push(
+          `secretSetAttachments[${attachmentIndex}].mappings[${mappingIndex}] must be an object`,
+        );
+        continue;
+      }
+      if (!isSecretKey(mappingCandidate.sourceKey)) {
+        errors.push(
+          `secretSetAttachments[${attachmentIndex}].mappings[${mappingIndex}].sourceKey must be canonical`,
+        );
+      } else {
+        sourceKeys.push(mappingCandidate.sourceKey);
+      }
+      const finalKey = mappingCandidate.targetKey ?? mappingCandidate.sourceKey;
+      if (!isSecretKey(finalKey)) {
+        errors.push(
+          `secretSetAttachments[${attachmentIndex}].mappings[${mappingIndex}].targetKey must be canonical`,
+        );
+      } else {
+        targetKeys.push(finalKey);
+      }
+      if (mappingCandidate.delivery !== undefined) {
+        errors.push(...validateSecretDelivery(mappingCandidate.delivery).map(
+          (errorArg) => (
+            `secretSetAttachments[${attachmentIndex}].mappings[${mappingIndex}].${errorArg}`
+          ),
+        ));
+      }
+    }
+    if (new Set(sourceKeys).size !== sourceKeys.length) {
+      errors.push(`secretSetAttachments[${attachmentIndex}] has duplicate source mappings`);
+    }
+    if (new Set(targetKeys).size !== targetKeys.length) {
+      errors.push(`secretSetAttachments[${attachmentIndex}] has duplicate target mappings`);
+    }
+  }
+  if (new Set(attachmentIds).size !== attachmentIds.length) {
+    errors.push('secretSetAttachments ids must be unique');
+  }
+  if (new Set(setEnvironmentKeys).size !== setEnvironmentKeys.length) {
+    errors.push('a SecretSet may be attached only once per environment');
+  }
+  return errors;
+};
+
+export const validateServiceSecretMode = (serviceDataArg: unknown): string[] => {
+  if (!isRecord(serviceDataArg)) return ['service data must be an object'];
+  const hasLegacyPrimary = typeof serviceDataArg.secretBundleId === 'string'
+    && serviceDataArg.secretBundleId.length > 0;
+  const hasLegacyAdditional = Array.isArray(serviceDataArg.additionalSecretBundleIds)
+    && serviceDataArg.additionalSecretBundleIds.length > 0;
+  if (serviceDataArg.secretConfiguration !== undefined
+    && (hasLegacyPrimary || hasLegacyAdditional)) {
+    return ['legacy SecretBundle references cannot be mixed with secretConfiguration'];
+  }
+  return serviceDataArg.secretConfiguration === undefined
+    ? []
+    : validateServiceSecretConfiguration(serviceDataArg.secretConfiguration);
+};
+
+export const validateSecretSetAttachmentOwnership = (
+  configurationArg: IServiceSecretConfiguration,
+  serviceOrganizationIdArg: string,
+  secretSetsArg: ISecretSetMetadata[],
+): string[] => {
+  const errors = validateServiceSecretConfiguration(configurationArg);
+  const secretSetsById = new Map(secretSetsArg.map((secretSetArg) => [
+    secretSetArg.id,
+    secretSetArg,
+  ]));
+  for (const attachment of configurationArg.secretSetAttachments || []) {
+    const secretSet = secretSetsById.get(attachment.secretSetId);
+    if (!secretSet) {
+      errors.push(`SecretSet ${attachment.secretSetId} does not exist`);
+    } else if (secretSet.organizationId !== serviceOrganizationIdArg) {
+      errors.push(`SecretSet ${attachment.secretSetId} belongs to another organization`);
+    } else if (secretSet.lifecycleState !== 'active') {
+      errors.push(`SecretSet ${attachment.secretSetId} is not active`);
+    }
+  }
+  return errors;
+};
+
+export const createResolvedSecretManifestDigestInput = (
+  manifestArg: IResolvedSecretManifest,
+): string => JSON.stringify({
+  schemaVersion: manifestArg.schemaVersion,
+  id: manifestArg.id,
+  organizationId: manifestArg.organizationId,
+  serviceId: manifestArg.serviceId,
+  clusterId: manifestArg.clusterId,
+  secretRolloutId: manifestArg.secretRolloutId,
+  secretRolloutGeneration: manifestArg.secretRolloutGeneration,
+  entries: manifestArg.entries.map((entryArg) => ({
+    secretId: entryArg.secretId,
+    secretVersionId: entryArg.secretVersionId,
+    key: entryArg.key,
+    environment: entryArg.environment,
+    owner: entryArg.owner.kind === 'service'
+      ? {
+          kind: 'service',
+          serviceId: entryArg.owner.serviceId,
+        }
+      : {
+          kind: 'secret-set',
+          secretSetId: entryArg.owner.secretSetId,
+        },
+    delivery: entryArg.delivery.type === 'environment'
+      ? {
+          type: 'environment',
+          variableName: entryArg.delivery.variableName,
+        }
+      : {
+          type: 'file',
+          targetPath: entryArg.delivery.targetPath,
+          uid: entryArg.delivery.uid,
+          gid: entryArg.delivery.gid,
+          mode: entryArg.delivery.mode,
+        },
+  })),
+  createdAt: manifestArg.createdAt,
+});
+
+/** Shared canonical digest; the digest field itself is excluded from the input. */
+export const computeResolvedSecretManifestDigest = async (
+  manifestArg: IResolvedSecretManifest,
+): Promise<TSha256Digest> => {
+  const encoded = new TextEncoder().encode(createResolvedSecretManifestDigestInput(manifestArg));
+  const digestBuffer = await globalThis.crypto.subtle.digest('SHA-256', encoded);
+  const digestHex = [...new Uint8Array(digestBuffer)]
+    .map((byteArg) => byteArg.toString(16).padStart(2, '0'))
+    .join('');
+  return `sha256:${digestHex}` as TSha256Digest;
+};
+
+export const verifyResolvedSecretManifestDigest = async (
+  manifestArg: IResolvedSecretManifest,
+): Promise<boolean> => (
+  manifestArg.digest === await computeResolvedSecretManifestDigest(manifestArg)
+);
+
+export const validateResolvedSecretManifest = (
+  manifestArg: unknown,
+): string[] => {
+  if (!isRecord(manifestArg)) return ['secret manifest must be an object'];
+  const errors: string[] = [];
+  if (manifestArg.schemaVersion !== 1) errors.push('secret manifest schemaVersion must be 1');
+  for (const field of [
+    'id',
+    'organizationId',
+    'serviceId',
+    'clusterId',
+    'secretRolloutId',
+  ] as const) {
+    if (!isSecretIdentifier(manifestArg[field])) {
+      errors.push(`secret manifest ${field} must be a canonical identifier`);
+    }
+  }
+  if (typeof manifestArg.digest !== 'string' || !secretDigestRegex.test(manifestArg.digest)) {
+    errors.push('secret manifest digest must be a canonical sha256 digest');
+  }
+  if (!Number.isSafeInteger(manifestArg.secretRolloutGeneration)
+    || (manifestArg.secretRolloutGeneration as number) < 1) {
+    errors.push('secret manifest rollout generation must be a positive integer');
+  }
+  if (!Number.isSafeInteger(manifestArg.createdAt) || (manifestArg.createdAt as number) < 0) {
+    errors.push('secret manifest createdAt must be a non-negative integer');
+  }
+  if (!Array.isArray(manifestArg.entries) || manifestArg.entries.length > 256) {
+    errors.push('secret manifest entries must be a bounded array');
+    return errors;
+  }
+  const keyScopes: string[] = [];
+  const secretIds: string[] = [];
+  const versionIds: string[] = [];
+  const environmentDeliveryTargets: string[] = [];
+  const fileDeliveryTargets: string[] = [];
+  let previousSortKey: string | undefined;
+  for (const [index, candidate] of manifestArg.entries.entries()) {
+    if (!isRecord(candidate)) {
+      errors.push(`secret manifest entries[${index}] must be an object`);
+      continue;
+    }
+    if (!isSecretIdentifier(candidate.secretId)) {
+      errors.push(`secret manifest entries[${index}].secretId must be canonical`);
+    } else {
+      secretIds.push(candidate.secretId);
+    }
+    if (!isSecretIdentifier(candidate.secretVersionId)) {
+      errors.push(`secret manifest entries[${index}].secretVersionId must be canonical`);
+    } else {
+      versionIds.push(candidate.secretVersionId);
+    }
+    if (!isSecretKey(candidate.key)) {
+      errors.push(`secret manifest entries[${index}].key must be canonical`);
+    }
+    if (!isSecretEnvironment(candidate.environment)) {
+      errors.push(`secret manifest entries[${index}].environment must be canonical`);
+    } else if (isSecretKey(candidate.key)) {
+      keyScopes.push(`${candidate.environment}\0${candidate.key}`);
+    }
+    if (!isRecord(candidate.owner)
+      || (
+        candidate.owner.kind !== 'service'
+        && candidate.owner.kind !== 'secret-set'
+      )
+      || (
+        candidate.owner.kind === 'service'
+        && !isSecretIdentifier(candidate.owner.serviceId)
+      )
+      || (
+        candidate.owner.kind === 'secret-set'
+        && !isSecretIdentifier(candidate.owner.secretSetId)
+    )) {
+      errors.push(`secret manifest entries[${index}].owner must be canonical`);
+    } else if (
+      candidate.owner.kind === 'service'
+      && isSecretIdentifier(manifestArg.serviceId)
+      && candidate.owner.serviceId !== manifestArg.serviceId
+    ) {
+      errors.push(
+        `secret manifest entries[${index}].owner serviceId must match the manifest serviceId`,
+      );
+    }
+    errors.push(...validateSecretDelivery(candidate.delivery).map(
+      (errorArg) => `secret manifest entries[${index}].${errorArg}`,
+    ));
+    if (isRecord(candidate.delivery)) {
+      if (
+        candidate.delivery.type === 'environment'
+        && isSecretKey(candidate.delivery.variableName)
+      ) {
+        environmentDeliveryTargets.push(candidate.delivery.variableName);
+      } else if (
+        candidate.delivery.type === 'file'
+        && typeof candidate.delivery.targetPath === 'string'
+        && validateSecretDelivery(candidate.delivery).length === 0
+      ) {
+        fileDeliveryTargets.push(candidate.delivery.targetPath);
+      }
+    }
+    if (isSecretKey(candidate.key) && isSecretEnvironment(candidate.environment)) {
+      const sortKey = `${candidate.environment}\0${candidate.key}`;
+      if (previousSortKey !== undefined && sortKey <= previousSortKey) {
+        errors.push('secret manifest entries must be uniquely sorted by environment and key');
+      }
+      previousSortKey = sortKey;
+    }
+  }
+  if (new Set(keyScopes).size !== keyScopes.length) {
+    errors.push('secret manifest final keys must be unique per environment');
+  }
+  if (new Set(secretIds).size !== secretIds.length) {
+    errors.push('secret manifest logical secret references must be unique');
+  }
+  if (new Set(versionIds).size !== versionIds.length) {
+    errors.push('secret manifest version references must be unique');
+  }
+  if (new Set(environmentDeliveryTargets).size !== environmentDeliveryTargets.length) {
+    errors.push('secret manifest environment delivery targets must be globally unique');
+  }
+  if (new Set(fileDeliveryTargets).size !== fileDeliveryTargets.length) {
+    errors.push('secret manifest file delivery targets must be globally unique');
+  }
+  return errors;
+};
+
+const validateResolvedSecretManifestReference = (
+  referenceArg: unknown,
+  expectedClusterIdArg: string,
+  pathArg: string,
+): string[] => {
+  if (!isRecord(referenceArg)
+    || !isSecretIdentifier(referenceArg.manifestId)
+    || typeof referenceArg.manifestDigest !== 'string'
+    || !secretDigestRegex.test(referenceArg.manifestDigest)
+    || referenceArg.clusterId !== expectedClusterIdArg
+    || !isSecretIdentifier(referenceArg.secretRolloutId)
+    || !Number.isSafeInteger(referenceArg.secretRolloutGeneration)
+    || (referenceArg.secretRolloutGeneration as number) < 1) {
+    return [`${pathArg} must be canonical and match its cluster`];
+  }
+  return [];
+};
+
+export const validateServiceSecretDeploymentPlan = (
+  planArg: unknown,
+  expectedTargetClusterIdsArg?: string[],
+): string[] => {
+  if (!isRecord(planArg)) return ['secret deployment plan must be an object'];
+  const errors: string[] = [];
+  if (planArg.schemaVersion !== 1) errors.push('secret deployment plan schemaVersion must be 1');
+  if (!Number.isSafeInteger(planArg.revision) || (planArg.revision as number) < 1) {
+    errors.push('secret deployment plan revision must be a positive integer');
+  }
+  if (!Number.isSafeInteger(planArg.updatedAt) || (planArg.updatedAt as number) < 0) {
+    errors.push('secret deployment plan updatedAt must be a non-negative integer');
+  }
+  if (!Array.isArray(planArg.clusterStates)
+    || planArg.clusterStates.length === 0
+    || planArg.clusterStates.length > 128) {
+    errors.push('secret deployment plan clusterStates must be a non-empty bounded array');
+    return errors;
+  }
+  const clusterIds: string[] = [];
+  const manifestReferencesById = new Map<string, IResolvedSecretManifestReference>();
+  const validateAndTrackManifestReference = (
+    referenceArg: unknown,
+    expectedClusterIdArg: string,
+    pathArg: string,
+  ): void => {
+    const referenceErrors = validateResolvedSecretManifestReference(
+      referenceArg,
+      expectedClusterIdArg,
+      pathArg,
+    );
+    errors.push(...referenceErrors);
+    if (referenceErrors.length > 0) return;
+    const reference = referenceArg as IResolvedSecretManifestReference;
+    const existingReference = manifestReferencesById.get(reference.manifestId);
+    if (
+      existingReference
+      && !resolvedSecretManifestReferencesEqual(existingReference, reference)
+    ) {
+      errors.push(
+        `${pathArg}.manifestId must identify one immutable manifest reference throughout the plan`,
+      );
+      return;
+    }
+    manifestReferencesById.set(reference.manifestId, reference);
+  };
+  for (const [index, candidate] of planArg.clusterStates.entries()) {
+    const path = `secret deployment plan clusterStates[${index}]`;
+    if (!isRecord(candidate) || !isSecretIdentifier(candidate.clusterId)) {
+      errors.push(`${path}.clusterId must be canonical`);
+      continue;
+    }
+    clusterIds.push(candidate.clusterId);
+    validateAndTrackManifestReference(
+      candidate.desiredManifest,
+      candidate.clusterId,
+      `${path}.desiredManifest`,
+    );
+    if (candidate.appliedManifest !== undefined) {
+      validateAndTrackManifestReference(
+        candidate.appliedManifest,
+        candidate.clusterId,
+        `${path}.appliedManifest`,
+      );
+    }
+    if (candidate.previousAcceptedManifest !== undefined) {
+      if (!isRecord(candidate.previousAcceptedManifest)
+        || !Number.isSafeInteger(candidate.previousAcceptedManifest.acceptedUntil)
+        || (candidate.previousAcceptedManifest.acceptedUntil as number) < 0) {
+        errors.push(`${path}.previousAcceptedManifest acceptedUntil must be non-negative`);
+      } else {
+        validateAndTrackManifestReference(
+          candidate.previousAcceptedManifest.manifest,
+          candidate.clusterId,
+          `${path}.previousAcceptedManifest.manifest`,
+        );
+        if (
+          Number.isSafeInteger(candidate.updatedAt)
+          && (candidate.previousAcceptedManifest.acceptedUntil as number)
+            < (candidate.updatedAt as number)
+        ) {
+          errors.push(`${path}.previousAcceptedManifest acceptedUntil predates its state`);
+        }
+      }
+    }
+    if (![
+      'pending',
+      'applying',
+      'applied',
+      'drifted',
+      'failed',
+    ].includes(candidate.status as string)) {
+      errors.push(`${path}.status must be canonical`);
+    }
+    if (!Number.isSafeInteger(candidate.updatedAt) || (candidate.updatedAt as number) < 0) {
+      errors.push(`${path}.updatedAt must be a non-negative integer`);
+    }
+    if (
+      candidate.status === 'applied'
+      && !resolvedSecretManifestReferencesEqual(
+        candidate.appliedManifest as unknown as IResolvedSecretManifestReference,
+        candidate.desiredManifest as unknown as IResolvedSecretManifestReference,
+      )
+    ) {
+      errors.push(`${path} applied status requires the desired manifest to be applied`);
+    }
+  }
+  if (new Set(clusterIds).size !== clusterIds.length) {
+    errors.push('secret deployment plan clusterStates must contain each cluster once');
+  }
+  if (expectedTargetClusterIdsArg) {
+    const expected = [...new Set(expectedTargetClusterIdsArg)].sort();
+    if (JSON.stringify([...clusterIds].sort()) !== JSON.stringify(expected)) {
+      errors.push('secret deployment plan target clusters do not match the service rollout scope');
+    }
+  }
+  return errors;
+};