@serve.zone/interfaces 21.1.0 → 23.0.0

package/ts/data/secret.ts

@@ -1,3 +1,4 @@
+import * as plugins from '../plugins.js';
 import type { TSha256Digest } from './immutableimage.js';
 import { normalizeServiceAbsolutePath } from './service.js';
 
@@ -18,11 +19,12 @@ export type TSecretVersionLifecycleState =
 /** Retired versions remain usable only through an already-accepted manifest. */
 export const isSecretVersionMaterialIssuable = (
   lifecycleStateArg: TSecretVersionLifecycleState,
-): boolean => lifecycleStateArg === 'active' || lifecycleStateArg === 'retired';
+  referencedByAcceptedManifestArg: boolean,
+): boolean => lifecycleStateArg === 'active'
+  || (lifecycleStateArg === 'retired' && referencedByAcceptedManifestArg);
 
 export type TSecretManagementSource =
   | 'operator'
-  | 'legacy'
   | 'appstore'
   | 'mail'
   | 'oidc'
@@ -32,7 +34,6 @@ export type TSecretManagementSource =
 
 export type TSecretManagementScope =
   | 'operator'
-  | 'legacy'
   | `appstore:${string}`
   | `mail:${string}`
   | `oidc:${string}`
@@ -50,7 +51,24 @@ export interface ISecretSetSecretOwner {
   secretSetId: string;
 }
 
-export type TSecretOwner = IServiceSecretOwner | ISecretSetSecretOwner;
+export interface IPlatformProviderSecretOwner {
+  kind: 'platform-provider';
+  providerConfigId: string;
+}
+
+export interface ISystemSecretOwner {
+  kind: 'system';
+  systemId: string;
+}
+
+export type TSecretOwner =
+  | IServiceSecretOwner
+  | ISecretSetSecretOwner
+  | IPlatformProviderSecretOwner
+  | ISystemSecretOwner;
+
+export type TSecretMutationTarget = TSecretOwner;
+export type TWorkloadSecretOwner = IServiceSecretOwner | ISecretSetSecretOwner;
 
 export interface ISecretVersionReference {
   secretId: string;
@@ -146,9 +164,12 @@ export interface ISecretSetConsumerRolloutStatus {
   updatedAt: number;
 }
 
-export interface ISecretEnvironmentDelivery {
-  type: 'environment';
+export interface ISecretLauncherEnvironmentDelivery {
+  type: 'launcher-environment';
   variableName: string;
+  uid: number;
+  gid: number;
+  mode: 0o400 | 0o440;
 }
 
 export interface ISecretFileDelivery {
@@ -156,10 +177,29 @@ export interface ISecretFileDelivery {
   targetPath: string;
   uid: number;
   gid: number;
-  mode: number;
+  mode: 0o400 | 0o440;
 }
 
-export type TSecretDelivery = ISecretEnvironmentDelivery | ISecretFileDelivery;
+export type TSecretDelivery = ISecretLauncherEnvironmentDelivery | ISecretFileDelivery;
+
+export const secretValueLimits = Object.freeze({
+  maximumBytes: 500 * 1024,
+  minimumGeneratedBytes: 16,
+  maximumGeneratedBytes: 64,
+});
+
+export type TSecretGeneratedEncoding = 'hex' | 'base64url';
+
+export type TSecretValueInput =
+  | {
+      mode: 'sealed';
+      envelope: plugins.smartcrypto.IX25519EnvelopeV1;
+    }
+  | {
+      mode: 'generated';
+      encoding: TSecretGeneratedEncoding;
+      bytes: number;
+    };
 
 export interface ISecretSetAttachmentMapping {
   /** Source key in the attached SecretSet. */
@@ -182,7 +222,7 @@ export interface ISecretSetAttachment {
  * Cloudly verifies organization ownership when resolving the referenced sets.
  */
 export interface IServiceSecretConfiguration {
-  schemaVersion: 1;
+  schemaVersion: 2;
   /** Dedicated CAS revision for SecretSet attachments. */
   revision: number;
   /** Dedicated CAS revision for service-owned secret membership. */
@@ -195,18 +235,22 @@ export interface IResolvedSecretManifestEntry {
   secretVersionId: string;
   key: string;
   environment: TSecretEnvironment;
-  owner: TSecretOwner;
+  owner: TWorkloadSecretOwner;
   delivery: TSecretDelivery;
 }
 
 /** Immutable, value-free runtime snapshot. */
 export interface IResolvedSecretManifest {
-  schemaVersion: 1;
+  schemaVersion: 2;
   id: string;
   digest: TSha256Digest;
   organizationId: string;
   serviceId: string;
   clusterId: string;
+  imageRolloutId: string;
+  imageRolloutGeneration: number;
+  requestedImageDigest: TSha256Digest;
+  invocationDigest: TSha256Digest;
   secretRolloutId: string;
   secretRolloutGeneration: number;
   entries: IResolvedSecretManifestEntry[];
@@ -217,6 +261,10 @@ export interface IResolvedSecretManifestReference {
   manifestId: string;
   manifestDigest: TSha256Digest;
   clusterId: string;
+  imageRolloutId: string;
+  imageRolloutGeneration: number;
+  requestedImageDigest: TSha256Digest;
+  invocationDigest: TSha256Digest;
   secretRolloutId: string;
   secretRolloutGeneration: number;
 }
@@ -245,7 +293,7 @@ export interface IClusterSecretDeploymentState {
 
 /** Server-managed per-cluster authority switched with an expected revision CAS. */
 export interface IServiceSecretDeploymentPlan {
-  schemaVersion: 1;
+  schemaVersion: 2;
   revision: number;
   clusterStates: IClusterSecretDeploymentState[];
   updatedAt: number;
@@ -260,6 +308,10 @@ export const resolvedSecretManifestReferencesEqual = (
   && leftArg?.manifestId === rightArg?.manifestId
   && leftArg?.manifestDigest === rightArg?.manifestDigest
   && leftArg?.clusterId === rightArg?.clusterId
+  && leftArg?.imageRolloutId === rightArg?.imageRolloutId
+  && leftArg?.imageRolloutGeneration === rightArg?.imageRolloutGeneration
+  && leftArg?.requestedImageDigest === rightArg?.requestedImageDigest
+  && leftArg?.invocationDigest === rightArg?.invocationDigest
   && leftArg?.secretRolloutId === rightArg?.secretRolloutId
   && leftArg?.secretRolloutGeneration === rightArg?.secretRolloutGeneration
 );
@@ -292,6 +344,20 @@ const isRecord = (valueArg: unknown): valueArg is Record<string, unknown> => (
   Boolean(valueArg) && typeof valueArg === 'object' && !Array.isArray(valueArg)
 );
 
+const hasExactKeys = (
+  valueArg: Record<string, unknown>,
+  keysArg: string[],
+): boolean => {
+  const actual = Object.keys(valueArg).sort();
+  const expected = [...keysArg].sort();
+  return JSON.stringify(actual) === JSON.stringify(expected);
+};
+
+const hasOnlyKeys = (
+  valueArg: Record<string, unknown>,
+  keysArg: string[],
+): boolean => Object.keys(valueArg).every((keyArg) => keysArg.includes(keyArg));
+
 const isSecretIdentifier = (valueArg: unknown): valueArg is string => (
   typeof valueArg === 'string' && secretIdentifierRegex.test(valueArg)
 );
@@ -304,6 +370,30 @@ const isSecretEnvironment = (valueArg: unknown): valueArg is string => (
   typeof valueArg === 'string' && secretEnvironmentRegex.test(valueArg)
 );
 
+export const validateSecretMutationId = (mutationIdArg: unknown): string[] => (
+  isSecretIdentifier(mutationIdArg)
+    ? []
+    : ['mutationId must be a canonical identifier']
+);
+
+export const validateSecretOwner = (ownerArg: unknown): string[] => {
+  if (!isRecord(ownerArg)) return ['secret owner must be an object'];
+  const shapeByKind = {
+    service: ['kind', 'serviceId'],
+    'secret-set': ['kind', 'secretSetId'],
+    'platform-provider': ['kind', 'providerConfigId'],
+    system: ['kind', 'systemId'],
+  } as const;
+  const keys = shapeByKind[ownerArg.kind as keyof typeof shapeByKind];
+  if (!keys || !hasExactKeys(ownerArg, [...keys])) {
+    return ['secret owner must use an exact supported owner schema'];
+  }
+  const idField = keys[1];
+  return isSecretIdentifier(ownerArg[idField])
+    ? []
+    : [`secret owner ${idField} must be canonical`];
+};
+
 export const validateSecretManagementScope = (
   sourceArg: TSecretManagementSource,
   scopeArg: unknown,
@@ -313,11 +403,6 @@ export const validateSecretManagementScope = (
       ? []
       : ['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'];
   }
@@ -328,19 +413,23 @@ export const validateSecretManagementScope = (
 
 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'];
+  const isLauncher = deliveryArg.type === 'launcher-environment';
+  if (!isLauncher && deliveryArg.type !== 'file') {
+    return ['delivery type must be launcher-environment or file'];
   }
-  if (deliveryArg.type !== 'file') {
-    return ['delivery type must be environment or file'];
+  const expectedKeys = isLauncher
+    ? ['type', 'variableName', 'uid', 'gid', 'mode']
+    : ['type', 'targetPath', 'uid', 'gid', 'mode'];
+  if (!hasExactKeys(deliveryArg, expectedKeys)) {
+    return ['delivery must use its exact schema'];
   }
   const errors: string[] = [];
-  if (typeof deliveryArg.targetPath !== 'string'
+  if (isLauncher && !isSecretKey(deliveryArg.variableName)) {
+    errors.push('launcher delivery variableName must be a canonical environment key');
+  }
+  if (!isLauncher && (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') {
+    || !/^\/run\/secrets\/[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(deliveryArg.targetPath))) {
     errors.push('file delivery targetPath must be a canonical file below /run/secrets');
   }
   for (const field of ['uid', 'gid'] as const) {
@@ -348,15 +437,97 @@ export const validateSecretDelivery = (deliveryArg: unknown): string[] => {
     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`);
+      errors.push(`${isLauncher ? 'launcher' : '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');
+    errors.push(`${isLauncher ? 'launcher' : 'file'} delivery mode must be 0400 or 0440`);
   }
   return errors;
 };
 
+export const validateSecretValueInput = (valueInputArg: unknown): string[] => {
+  if (!isRecord(valueInputArg)) return ['valueInput must be an object'];
+  if (valueInputArg.mode === 'sealed') {
+    if (!hasExactKeys(valueInputArg, ['mode', 'envelope'])) {
+      return ['sealed valueInput must use its exact schema'];
+    }
+    try {
+      const envelope = plugins.smartcrypto.parseX25519Envelope(valueInputArg.envelope);
+      return envelope.ciphertext.length
+        <= Math.ceil(secretValueLimits.maximumBytes * 4 / 3)
+        ? []
+        : [`sealed secret material must not exceed ${secretValueLimits.maximumBytes} bytes`];
+    } catch {
+      return ['sealed valueInput envelope must be a strict X25519 envelope'];
+    }
+  }
+  if (valueInputArg.mode === 'generated') {
+    if (!hasExactKeys(valueInputArg, ['mode', 'encoding', 'bytes'])) {
+      return ['generated valueInput must use its exact schema'];
+    }
+    const errors: string[] = [];
+    if (valueInputArg.encoding !== 'hex' && valueInputArg.encoding !== 'base64url') {
+      errors.push('generated valueInput encoding must be hex or base64url');
+    }
+    if (!Number.isSafeInteger(valueInputArg.bytes)
+      || (valueInputArg.bytes as number) < secretValueLimits.minimumGeneratedBytes
+      || (valueInputArg.bytes as number) > secretValueLimits.maximumGeneratedBytes) {
+      errors.push('generated valueInput bytes are outside the supported bounds');
+    }
+    return errors;
+  }
+  return ['valueInput mode must be sealed or generated'];
+};
+
+const encodeBase64Url = (bytesArg: Uint8Array): string => {
+  let binary = '';
+  for (const byte of bytesArg) binary += String.fromCharCode(byte);
+  return globalThis.btoa(binary)
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+};
+
+/** Checks the SmartCrypto context digest without opening or decrypting the envelope. */
+export const verifySecretEnvelopeContext = async (
+  envelopeArg: unknown,
+  contextArg: unknown,
+): Promise<boolean> => {
+  if (!(contextArg instanceof Uint8Array)) return false;
+  let envelope: plugins.smartcrypto.IX25519EnvelopeV1;
+  try {
+    envelope = plugins.smartcrypto.parseX25519Envelope(envelopeArg);
+  } catch {
+    return false;
+  }
+  const contextDigest = new Uint8Array(await globalThis.crypto.subtle.digest(
+    'SHA-256',
+    new Uint8Array(contextArg),
+  ));
+  return envelope.contextDigest === encodeBase64Url(contextDigest);
+};
+
+/** Files accept arbitrary bytes; launcher values must be valid UTF-8 without NUL. */
+export const validateSecretValueBytes = (
+  valueBytesArg: unknown,
+  deliveryArg: TSecretDelivery,
+): string[] => {
+  if (!(valueBytesArg instanceof Uint8Array)) return ['secret material must be bytes'];
+  if (valueBytesArg.byteLength > secretValueLimits.maximumBytes) {
+    return [`secret material must not exceed ${secretValueLimits.maximumBytes} bytes`];
+  }
+  if (deliveryArg.type === 'file') return [];
+  try {
+    const decoded = new TextDecoder('utf-8', { fatal: true }).decode(valueBytesArg);
+    return decoded.includes('\0')
+      ? ['launcher secret material must not contain NUL']
+      : [];
+  } catch {
+    return ['launcher secret material must be valid UTF-8'];
+  }
+};
+
 /**
  * One shared precedence rule for resolution and runtime verification.
  * A manifest is authoritative once published; before publication an attachment
@@ -378,16 +549,26 @@ export const validateServiceSecretConfiguration = (
   if (!isRecord(configurationArg)) {
     return ['secretConfiguration must be an object'];
   }
-  if (configurationArg.schemaVersion !== 1) {
-    return ['secretConfiguration schemaVersion must be 1'];
+  const errors: string[] = [];
+  if (!hasExactKeys(configurationArg, [
+    'schemaVersion',
+    'revision',
+    'secretsRevision',
+    'secretSetAttachments',
+  ])) {
+    errors.push('secretConfiguration must use its exact schema');
+  }
+  if (configurationArg.schemaVersion !== 2) {
+    errors.push('secretConfiguration schemaVersion must be 2');
   }
   if (!Array.isArray(configurationArg.secretSetAttachments)) {
-    return ['secretSetAttachments must be an array'];
+    errors.push('secretSetAttachments must be an array');
+    return errors;
   }
   if (configurationArg.secretSetAttachments.length > 64) {
-    return ['secretSetAttachments must contain at most 64 entries'];
+    errors.push('secretSetAttachments must contain at most 64 entries');
+    return errors;
   }
-  const errors: string[] = [];
   if (!Number.isSafeInteger(configurationArg.revision)
     || (configurationArg.revision as number) < 0) {
     errors.push('secretConfiguration revision must be a non-negative integer');
@@ -403,6 +584,9 @@ export const validateServiceSecretConfiguration = (
       errors.push(`secretSetAttachments[${attachmentIndex}] must be an object`);
       continue;
     }
+    if (!hasOnlyKeys(candidate, ['id', 'secretSetId', 'environment', 'mappings'])) {
+      errors.push(`secretSetAttachments[${attachmentIndex}] contains unsupported fields`);
+    }
     if (!isSecretIdentifier(candidate.id)) {
       errors.push(`secretSetAttachments[${attachmentIndex}].id must be a canonical identifier`);
     } else {
@@ -436,6 +620,11 @@ export const validateServiceSecretConfiguration = (
         );
         continue;
       }
+      if (!hasOnlyKeys(mappingCandidate, ['sourceKey', 'targetKey', 'delivery'])) {
+        errors.push(
+          `secretSetAttachments[${attachmentIndex}].mappings[${mappingIndex}] contains unsupported fields`,
+        );
+      }
       if (!isSecretKey(mappingCandidate.sourceKey)) {
         errors.push(
           `secretSetAttachments[${attachmentIndex}].mappings[${mappingIndex}].sourceKey must be canonical`,
@@ -475,21 +664,6 @@ export const validateServiceSecretConfiguration = (
   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,
@@ -521,6 +695,10 @@ export const createResolvedSecretManifestDigestInput = (
   organizationId: manifestArg.organizationId,
   serviceId: manifestArg.serviceId,
   clusterId: manifestArg.clusterId,
+  imageRolloutId: manifestArg.imageRolloutId,
+  imageRolloutGeneration: manifestArg.imageRolloutGeneration,
+  requestedImageDigest: manifestArg.requestedImageDigest,
+  invocationDigest: manifestArg.invocationDigest,
   secretRolloutId: manifestArg.secretRolloutId,
   secretRolloutGeneration: manifestArg.secretRolloutGeneration,
   entries: manifestArg.entries.map((entryArg) => ({
@@ -537,10 +715,13 @@ export const createResolvedSecretManifestDigestInput = (
           kind: 'secret-set',
           secretSetId: entryArg.owner.secretSetId,
         },
-    delivery: entryArg.delivery.type === 'environment'
+    delivery: entryArg.delivery.type === 'launcher-environment'
       ? {
-          type: 'environment',
+          type: 'launcher-environment',
           variableName: entryArg.delivery.variableName,
+          uid: entryArg.delivery.uid,
+          gid: entryArg.delivery.gid,
+          mode: entryArg.delivery.mode,
         }
       : {
           type: 'file',
@@ -576,12 +757,31 @@ export const validateResolvedSecretManifest = (
 ): 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');
+  if (!hasExactKeys(manifestArg, [
+    'schemaVersion',
+    'id',
+    'digest',
+    'organizationId',
+    'serviceId',
+    'clusterId',
+    'imageRolloutId',
+    'imageRolloutGeneration',
+    'requestedImageDigest',
+    'invocationDigest',
+    'secretRolloutId',
+    'secretRolloutGeneration',
+    'entries',
+    'createdAt',
+  ])) {
+    errors.push('secret manifest must use its exact schema');
+  }
+  if (manifestArg.schemaVersion !== 2) errors.push('secret manifest schemaVersion must be 2');
   for (const field of [
     'id',
     'organizationId',
     'serviceId',
     'clusterId',
+    'imageRolloutId',
     'secretRolloutId',
   ] as const) {
     if (!isSecretIdentifier(manifestArg[field])) {
@@ -591,6 +791,15 @@ export const validateResolvedSecretManifest = (
   if (typeof manifestArg.digest !== 'string' || !secretDigestRegex.test(manifestArg.digest)) {
     errors.push('secret manifest digest must be a canonical sha256 digest');
   }
+  for (const field of ['requestedImageDigest', 'invocationDigest'] as const) {
+    if (typeof manifestArg[field] !== 'string' || !secretDigestRegex.test(manifestArg[field])) {
+      errors.push(`secret manifest ${field} must be a canonical sha256 digest`);
+    }
+  }
+  if (!Number.isSafeInteger(manifestArg.imageRolloutGeneration)
+    || (manifestArg.imageRolloutGeneration as number) < 1) {
+    errors.push('secret manifest image rollout generation must be a positive integer');
+  }
   if (!Number.isSafeInteger(manifestArg.secretRolloutGeneration)
     || (manifestArg.secretRolloutGeneration as number) < 1) {
     errors.push('secret manifest rollout generation must be a positive integer');
@@ -613,6 +822,16 @@ export const validateResolvedSecretManifest = (
       errors.push(`secret manifest entries[${index}] must be an object`);
       continue;
     }
+    if (!hasExactKeys(candidate, [
+      'secretId',
+      'secretVersionId',
+      'key',
+      'environment',
+      'owner',
+      'delivery',
+    ])) {
+      errors.push(`secret manifest entries[${index}] must use its exact schema`);
+    }
     if (!isSecretIdentifier(candidate.secretId)) {
       errors.push(`secret manifest entries[${index}].secretId must be canonical`);
     } else {
@@ -636,6 +855,12 @@ export const validateResolvedSecretManifest = (
         candidate.owner.kind !== 'service'
         && candidate.owner.kind !== 'secret-set'
       )
+      || !hasExactKeys(
+        candidate.owner,
+        candidate.owner.kind === 'service'
+          ? ['kind', 'serviceId']
+          : ['kind', 'secretSetId'],
+      )
       || (
         candidate.owner.kind === 'service'
         && !isSecretIdentifier(candidate.owner.serviceId)
@@ -659,7 +884,7 @@ export const validateResolvedSecretManifest = (
     ));
     if (isRecord(candidate.delivery)) {
       if (
-        candidate.delivery.type === 'environment'
+        candidate.delivery.type === 'launcher-environment'
         && isSecretKey(candidate.delivery.variableName)
       ) {
         environmentDeliveryTargets.push(candidate.delivery.variableName);
@@ -703,10 +928,28 @@ const validateResolvedSecretManifestReference = (
   pathArg: string,
 ): string[] => {
   if (!isRecord(referenceArg)
+    || !hasExactKeys(referenceArg, [
+      'manifestId',
+      'manifestDigest',
+      'clusterId',
+      'imageRolloutId',
+      'imageRolloutGeneration',
+      'requestedImageDigest',
+      'invocationDigest',
+      'secretRolloutId',
+      'secretRolloutGeneration',
+    ])
     || !isSecretIdentifier(referenceArg.manifestId)
     || typeof referenceArg.manifestDigest !== 'string'
     || !secretDigestRegex.test(referenceArg.manifestDigest)
     || referenceArg.clusterId !== expectedClusterIdArg
+    || !isSecretIdentifier(referenceArg.imageRolloutId)
+    || !Number.isSafeInteger(referenceArg.imageRolloutGeneration)
+    || (referenceArg.imageRolloutGeneration as number) < 1
+    || typeof referenceArg.requestedImageDigest !== 'string'
+    || !secretDigestRegex.test(referenceArg.requestedImageDigest)
+    || typeof referenceArg.invocationDigest !== 'string'
+    || !secretDigestRegex.test(referenceArg.invocationDigest)
     || !isSecretIdentifier(referenceArg.secretRolloutId)
     || !Number.isSafeInteger(referenceArg.secretRolloutGeneration)
     || (referenceArg.secretRolloutGeneration as number) < 1) {
@@ -721,7 +964,15 @@ export const validateServiceSecretDeploymentPlan = (
 ): 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 (!hasExactKeys(planArg, [
+    'schemaVersion',
+    'revision',
+    'clusterStates',
+    'updatedAt',
+  ])) {
+    errors.push('secret deployment plan must use its exact schema');
+  }
+  if (planArg.schemaVersion !== 2) errors.push('secret deployment plan schemaVersion must be 2');
   if (!Number.isSafeInteger(planArg.revision) || (planArg.revision as number) < 1) {
     errors.push('secret deployment plan revision must be a positive integer');
   }
@@ -767,6 +1018,16 @@ export const validateServiceSecretDeploymentPlan = (
       errors.push(`${path}.clusterId must be canonical`);
       continue;
     }
+    if (!hasOnlyKeys(candidate, [
+      'clusterId',
+      'desiredManifest',
+      'appliedManifest',
+      'previousAcceptedManifest',
+      'status',
+      'updatedAt',
+    ])) {
+      errors.push(`${path} contains unsupported fields`);
+    }
     clusterIds.push(candidate.clusterId);
     validateAndTrackManifestReference(
       candidate.desiredManifest,
@@ -782,6 +1043,7 @@ export const validateServiceSecretDeploymentPlan = (
     }
     if (candidate.previousAcceptedManifest !== undefined) {
       if (!isRecord(candidate.previousAcceptedManifest)
+        || !hasExactKeys(candidate.previousAcceptedManifest, ['manifest', 'acceptedUntil'])
         || !Number.isSafeInteger(candidate.previousAcceptedManifest.acceptedUntil)
         || (candidate.previousAcceptedManifest.acceptedUntil as number) < 0) {
         errors.push(`${path}.previousAcceptedManifest acceptedUntil must be non-negative`);
@@ -833,3 +1095,463 @@ export const validateServiceSecretDeploymentPlan = (
   }
   return errors;
 };
+
+export const dockerSecretResourceNameDomain = 'serve.zone/docker-secret-resource/v1' as const;
+export const workloadInitEnvironmentMapPath = '/run/serve.zone/workloadinit-map-v1.json' as const;
+export const workloadRuntimeAssetRoot = '/opt/serve.zone/runtime-assets' as const;
+export const workloadInitExecutablePath =
+  '/opt/serve.zone/runtime-assets/workloadinit/v1/workloadinit' as const;
+export const workloadInitEnvironmentMapMode = 0o444 as const;
+export const workloadRuntimeAssetsReadOnly = true as const;
+
+const encodeLowercaseBase32 = (bytesArg: Uint8Array): string => {
+  const alphabet = 'abcdefghijklmnopqrstuvwxyz234567';
+  let output = '';
+  let accumulator = 0;
+  let bitCount = 0;
+  for (const byte of bytesArg) {
+    accumulator = (accumulator << 8) | byte;
+    bitCount += 8;
+    while (bitCount >= 5) {
+      bitCount -= 5;
+      output += alphabet[(accumulator >>> bitCount) & 31];
+    }
+    accumulator &= (1 << bitCount) - 1;
+  }
+  if (bitCount > 0) output += alphabet[(accumulator << (5 - bitCount)) & 31];
+  return output;
+};
+
+/** Stable resource name; no logical key or value material appears in Docker. */
+export const createDockerSecretResourceName = async (
+  secretVersionIdArg: string,
+): Promise<`szsv-${string}`> => {
+  if (!isSecretIdentifier(secretVersionIdArg)) {
+    throw new Error('secretVersionId must be a canonical identifier');
+  }
+  const digest = new Uint8Array(await globalThis.crypto.subtle.digest(
+    'SHA-256',
+    new TextEncoder().encode(`${dockerSecretResourceNameDomain}\0${secretVersionIdArg}`),
+  ));
+  const encoded = encodeLowercaseBase32(digest);
+  if (encoded.length !== 52) throw new Error('unexpected SHA-256 base32 length');
+  return `szsv-${encoded}`;
+};
+
+export const createLauncherSecretSourcePath = (
+  resourceArg: string,
+): `/run/serve.zone/secrets/${string}` => {
+  if (!/^szsv-[a-z2-7]{52}$/.test(resourceArg)) {
+    throw new Error('resource must be a canonical serve.zone secret resource name');
+  }
+  return `/run/serve.zone/secrets/${resourceArg}`;
+};
+
+export interface IWorkloadInitEnvironmentMapEntryV1 {
+  variableName: string;
+  resource: string;
+  source: string;
+}
+
+export interface IWorkloadInitEnvironmentMapV1 {
+  schemaVersion: 1;
+  manifestId: string;
+  manifestDigest: TSha256Digest;
+  entries: IWorkloadInitEnvironmentMapEntryV1[];
+}
+
+/**
+ * The nonsecret map is generated only from launcher deliveries. Direct file
+ * deliveries mount their version resource at the declared target without the
+ * launcher. Runtime assets are mounted read-only; no shell, symlink, or
+ * aggregate material file participates in delivery.
+ */
+export const createWorkloadInitEnvironmentMap = async (
+  manifestArg: IResolvedSecretManifest,
+): Promise<IWorkloadInitEnvironmentMapV1> => {
+  if (validateResolvedSecretManifest(manifestArg).length > 0
+    || !await verifyResolvedSecretManifestDigest(manifestArg)) {
+    throw new Error('workload init map requires a valid digest-verified manifest');
+  }
+  const entries = await Promise.all(manifestArg.entries
+    .filter((entryArg) => entryArg.delivery.type === 'launcher-environment')
+    .map(async (entryArg) => {
+      const resource = await createDockerSecretResourceName(entryArg.secretVersionId);
+      return {
+        variableName: (entryArg.delivery as ISecretLauncherEnvironmentDelivery).variableName,
+        resource,
+        source: createLauncherSecretSourcePath(resource),
+      };
+    }));
+  entries.sort((leftArg, rightArg) => (
+    leftArg.variableName < rightArg.variableName
+      ? -1
+      : leftArg.variableName > rightArg.variableName ? 1 : 0
+  ));
+  if (new Set(entries.map((entryArg) => entryArg.variableName)).size !== entries.length
+    || new Set(entries.map((entryArg) => entryArg.resource)).size !== entries.length
+    || new Set(entries.map((entryArg) => entryArg.source)).size !== entries.length) {
+    throw new Error('workload init map entries must have unique variable, resource, and source fields');
+  }
+  return {
+    schemaVersion: 1,
+    manifestId: manifestArg.id,
+    manifestDigest: manifestArg.digest,
+    entries,
+  };
+};
+
+export const verifyWorkloadInitEnvironmentMap = async (
+  mapArg: unknown,
+  manifestArg: IResolvedSecretManifest,
+): Promise<boolean> => {
+  if (!isRecord(mapArg)
+    || !hasExactKeys(mapArg, ['schemaVersion', 'manifestId', 'manifestDigest', 'entries'])) {
+    return false;
+  }
+  try {
+    const expected = await createWorkloadInitEnvironmentMap(manifestArg);
+    return JSON.stringify(mapArg) === JSON.stringify(expected);
+  } catch {
+    return false;
+  }
+};
+
+export interface IWorkloadInitWrappedInvocation {
+  command: [typeof workloadInitExecutablePath];
+  args: string[];
+}
+
+export const createWorkloadInitWrappedInvocation = (
+  originalArgvArg: string[],
+): IWorkloadInitWrappedInvocation => {
+  if (!Array.isArray(originalArgvArg)
+    || originalArgvArg.length === 0
+    || originalArgvArg.some((argumentArg) => typeof argumentArg !== 'string'
+      || argumentArg.length === 0
+      || argumentArg.includes('\0'))) {
+    throw new Error('original argv must be a non-empty canonical argument vector');
+  }
+  return {
+    command: [workloadInitExecutablePath],
+    args: ['run', '--map', workloadInitEnvironmentMapPath, '--', ...originalArgvArg],
+  };
+};
+
+/**
+ * A Docker secret resource and its nonsecret map remain while any desired,
+ * applied, or previous-accepted retained manifest references them. Deletion is
+ * allowed only after no retained reference exists and Docker confirms the
+ * corresponding rollout or service removal.
+ */
+export interface ISecretRuntimeResourceRetention {
+  resource: string;
+  retainedManifestIds: string[];
+  dockerRemovalConfirmed: boolean;
+}
+
+export type TSecretRecipientLifecycleState = 'active' | 'retiring' | 'revoked';
+
+interface ISecretRecipientMetadataBase {
+  schemaVersion: 1;
+  recipientKeyId: string;
+  /** Canonical unpadded base64url raw 32-byte X25519 public key. */
+  publicKey: string;
+  generation: number;
+  activatedAt: number;
+}
+
+export interface IActiveSecretRecipientMetadata extends ISecretRecipientMetadataBase {
+  lifecycleState: 'active';
+  acceptUntil?: never;
+  revokedAt?: never;
+}
+
+export interface IRetiringSecretRecipientMetadata extends ISecretRecipientMetadataBase {
+  lifecycleState: 'retiring';
+  acceptUntil: number;
+  revokedAt?: never;
+}
+
+export interface IRevokedSecretRecipientMetadata extends ISecretRecipientMetadataBase {
+  lifecycleState: 'revoked';
+  acceptUntil?: never;
+  revokedAt: number;
+}
+
+export type TSecretRecipientMetadata =
+  | IActiveSecretRecipientMetadata
+  | IRetiringSecretRecipientMetadata
+  | IRevokedSecretRecipientMetadata;
+
+export type TSecretIngressRecipient = TSecretRecipientMetadata;
+
+export const secretRecipientLimits = Object.freeze({
+  maximumRecipients: 64,
+});
+
+const rawX25519PublicKeyRegex = /^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$/;
+
+export const validateSecretRecipientMetadata = (
+  recipientArg: unknown,
+): string[] => {
+  if (!isRecord(recipientArg)) return ['secret recipient must be an object'];
+  const lifecycleState = recipientArg.lifecycleState;
+  const requiredKeys = lifecycleState === 'active'
+    ? ['schemaVersion', 'recipientKeyId', 'publicKey', 'generation', 'activatedAt', 'lifecycleState']
+    : lifecycleState === 'retiring'
+      ? ['schemaVersion', 'recipientKeyId', 'publicKey', 'generation', 'activatedAt', 'lifecycleState', 'acceptUntil']
+      : lifecycleState === 'revoked'
+        ? ['schemaVersion', 'recipientKeyId', 'publicKey', 'generation', 'activatedAt', 'lifecycleState', 'revokedAt']
+        : [];
+  if (requiredKeys.length === 0 || !hasExactKeys(recipientArg, requiredKeys)) {
+    return ['secret recipient must use its exact lifecycle schema'];
+  }
+  const errors: string[] = [];
+  if (recipientArg.schemaVersion !== 1) errors.push('secret recipient schemaVersion must be 1');
+  if (!isSecretIdentifier(recipientArg.recipientKeyId)) {
+    errors.push('secret recipient key id must be canonical');
+  }
+  if (typeof recipientArg.publicKey !== 'string'
+    || !rawX25519PublicKeyRegex.test(recipientArg.publicKey)) {
+    errors.push('secret recipient public key must be canonical base64url raw X25519 material');
+  }
+  for (const field of ['generation', 'activatedAt'] as const) {
+    if (!Number.isSafeInteger(recipientArg[field]) || (recipientArg[field] as number) < 1) {
+      errors.push(`secret recipient ${field} must be a positive integer`);
+    }
+  }
+  if (lifecycleState === 'retiring'
+    && (!Number.isSafeInteger(recipientArg.acceptUntil)
+      || (recipientArg.acceptUntil as number) <= (recipientArg.activatedAt as number))) {
+    errors.push('retiring secret recipient acceptUntil must follow activation');
+  }
+  if (lifecycleState === 'revoked'
+    && (!Number.isSafeInteger(recipientArg.revokedAt)
+      || (recipientArg.revokedAt as number) < (recipientArg.activatedAt as number))) {
+    errors.push('revoked secret recipient revokedAt must not precede activation');
+  }
+  return errors;
+};
+
+export const validateSecretRecipientSet = (
+  recipientsArg: unknown,
+): string[] => {
+  if (!Array.isArray(recipientsArg)
+    || recipientsArg.length === 0
+    || recipientsArg.length > secretRecipientLimits.maximumRecipients) {
+    return [
+      `secret recipient set must contain between 1 and ${secretRecipientLimits.maximumRecipients} entries`,
+    ];
+  }
+  const errors = recipientsArg.flatMap((recipientArg, indexArg) => (
+    validateSecretRecipientMetadata(recipientArg)
+      .map((errorArg) => `recipients[${indexArg}].${errorArg}`)
+  ));
+  const recipients = recipientsArg.filter(isRecord);
+  if (recipients.filter((recipientArg) => recipientArg.lifecycleState === 'active').length !== 1) {
+    errors.push('secret recipient set must contain exactly one active recipient');
+  }
+  const keyIds = recipients.map((recipientArg) => recipientArg.recipientKeyId);
+  const generations = recipients.map((recipientArg) => recipientArg.generation);
+  if (new Set(keyIds).size !== keyIds.length) errors.push('secret recipient key ids must be unique');
+  if (new Set(generations).size !== generations.length) {
+    errors.push('secret recipient generations must be unique');
+  }
+  const activeRecipient = recipients.find((recipientArg) => recipientArg.lifecycleState === 'active');
+  const numericGenerations = generations.filter((generationArg): generationArg is number => (
+    Number.isSafeInteger(generationArg)
+  ));
+  if (activeRecipient
+    && Number.isSafeInteger(activeRecipient.generation)
+    && numericGenerations.length > 0
+    && activeRecipient.generation !== Math.max(...numericGenerations)) {
+    errors.push('the active secret recipient must have the greatest generation');
+  }
+  return errors;
+};
+
+/** New envelopes target only active recipients. */
+export const canIssueNewSecretEnvelope = (
+  recipientArg: TSecretRecipientMetadata,
+): boolean => recipientArg.lifecycleState === 'active';
+
+export const validateSecretValueInputForRecipient = async (
+  valueInputArg: unknown,
+  recipientArg: TSecretRecipientMetadata,
+  expectedContextArg: Uint8Array,
+): Promise<string[]> => {
+  const errors = validateSecretValueInput(valueInputArg);
+  if (errors.length > 0 || !isRecord(valueInputArg) || valueInputArg.mode !== 'sealed') {
+    return errors;
+  }
+  if (!canIssueNewSecretEnvelope(recipientArg)) {
+    errors.push('new sealed inputs require the active ingress recipient');
+  }
+  try {
+    const envelope = plugins.smartcrypto.parseX25519Envelope(valueInputArg.envelope);
+    if (envelope.recipientKeyId !== recipientArg.recipientKeyId) {
+      errors.push('sealed input recipient does not match the active ingress recipient');
+    }
+    if (!await verifySecretEnvelopeContext(envelope, expectedContextArg)) {
+      errors.push('sealed input context does not match the request');
+    }
+  } catch {
+    // validateSecretValueInput already reports malformed envelopes.
+  }
+  return errors;
+};
+
+/** Retiring recipients open only already-issued envelopes before their deadline. */
+export const canOpenIssuedSecretEnvelope = (
+  recipientArg: TSecretRecipientMetadata,
+  issuedAtArg: number,
+  nowArg: number,
+): boolean => Number.isSafeInteger(issuedAtArg)
+  && Number.isSafeInteger(nowArg)
+  && issuedAtArg >= recipientArg.activatedAt
+  && issuedAtArg <= nowArg
+  && (recipientArg.lifecycleState === 'active'
+  || (recipientArg.lifecycleState === 'retiring'
+    && issuedAtArg < recipientArg.acceptUntil
+    && nowArg < recipientArg.acceptUntil));
+
+const canonicalSecretOwner = (ownerArg: TSecretOwner): Record<string, string> => {
+  switch (ownerArg.kind) {
+    case 'service': return { kind: ownerArg.kind, serviceId: ownerArg.serviceId };
+    case 'secret-set': return { kind: ownerArg.kind, secretSetId: ownerArg.secretSetId };
+    case 'platform-provider': return {
+      kind: ownerArg.kind,
+      providerConfigId: ownerArg.providerConfigId,
+    };
+    case 'system': return { kind: ownerArg.kind, systemId: ownerArg.systemId };
+  }
+};
+
+const canonicalSecretDelivery = (deliveryArg: TSecretDelivery): Record<string, unknown> => (
+  deliveryArg.type === 'launcher-environment'
+    ? {
+        type: deliveryArg.type,
+        variableName: deliveryArg.variableName,
+        uid: deliveryArg.uid,
+        gid: deliveryArg.gid,
+        mode: deliveryArg.mode,
+      }
+    : {
+        type: deliveryArg.type,
+        targetPath: deliveryArg.targetPath,
+        uid: deliveryArg.uid,
+        gid: deliveryArg.gid,
+        mode: deliveryArg.mode,
+      }
+);
+
+const contextBytes = (valueArg: Record<string, unknown>): Uint8Array => (
+  new TextEncoder().encode(JSON.stringify(valueArg))
+);
+
+export const createSecretCreateEnvelopeContext = (contextArg: {
+  mutationId: string;
+  target: TSecretMutationTarget;
+  key: string;
+  environment: TSecretEnvironment;
+  delivery: TSecretDelivery;
+  expectedTargetSecretsRevision: number;
+}): Uint8Array => contextBytes({
+  schemaVersion: 1,
+  purpose: 'serve.zone/secret-create',
+  mutationId: contextArg.mutationId,
+  target: canonicalSecretOwner(contextArg.target),
+  key: contextArg.key,
+  environment: contextArg.environment,
+  delivery: canonicalSecretDelivery(contextArg.delivery),
+  expectedTargetSecretsRevision: contextArg.expectedTargetSecretsRevision,
+});
+
+export const createSecretRotateEnvelopeContext = (contextArg: {
+  mutationId: string;
+  secretId: string;
+  expectedSecretRevision: number;
+  expectedActiveVersionId: string;
+  expectedTargetSecretsRevision: number;
+}): Uint8Array => contextBytes({
+  schemaVersion: 1,
+  purpose: 'serve.zone/secret-rotate',
+  mutationId: contextArg.mutationId,
+  secretId: contextArg.secretId,
+  expectedSecretRevision: contextArg.expectedSecretRevision,
+  expectedActiveVersionId: contextArg.expectedActiveVersionId,
+  expectedTargetSecretsRevision: contextArg.expectedTargetSecretsRevision,
+});
+
+export const createAppStoreInstallSecretEnvelopeContext = (contextArg: {
+  mutationId: string;
+  appId: string;
+  appVersion: string;
+  serviceId: string;
+  key: string;
+  delivery: TSecretDelivery;
+  generation?: { encoding: TSecretGeneratedEncoding; bytes: number };
+}): Uint8Array => contextBytes({
+  schemaVersion: 1,
+  purpose: 'serve.zone/app-install-secret',
+  mutationId: contextArg.mutationId,
+  appId: contextArg.appId,
+  appVersion: contextArg.appVersion,
+  serviceId: contextArg.serviceId,
+  key: contextArg.key,
+  delivery: canonicalSecretDelivery(contextArg.delivery),
+  generation: contextArg.generation
+    ? { encoding: contextArg.generation.encoding, bytes: contextArg.generation.bytes }
+    : null,
+});
+
+export const createResolvedSecretMaterialEnvelopeContext = (contextArg: {
+  recipientKeyId: string;
+  organizationId: string;
+  clusterId: string;
+  serviceId: string;
+  imageRolloutId: string;
+  imageRolloutGeneration: number;
+  requestedImageDigest: TSha256Digest;
+  secretRolloutId: string;
+  secretRolloutGeneration: number;
+  manifestId: string;
+  manifestDigest: TSha256Digest;
+  secretId: string;
+  secretVersionId: string;
+}): Uint8Array => contextBytes({
+  schemaVersion: 1,
+  purpose: 'serve.zone/resolved-secret-material',
+  recipientKeyId: contextArg.recipientKeyId,
+  organizationId: contextArg.organizationId,
+  clusterId: contextArg.clusterId,
+  serviceId: contextArg.serviceId,
+  imageRolloutId: contextArg.imageRolloutId,
+  imageRolloutGeneration: contextArg.imageRolloutGeneration,
+  requestedImageDigest: contextArg.requestedImageDigest,
+  secretRolloutId: contextArg.secretRolloutId,
+  secretRolloutGeneration: contextArg.secretRolloutGeneration,
+  manifestId: contextArg.manifestId,
+  manifestDigest: contextArg.manifestDigest,
+  secretId: contextArg.secretId,
+  secretVersionId: contextArg.secretVersionId,
+});
+
+export const createSecretRecipientEnrollmentChallengeContext = (contextArg: {
+  enrollmentId: string;
+  clusterId: string;
+  recipientKeyId: string;
+  publicKey: string;
+  generation: number;
+  expiresAt: number;
+}): Uint8Array => contextBytes({
+  schemaVersion: 1,
+  purpose: 'serve.zone/secret-recipient-enrollment-challenge',
+  enrollmentId: contextArg.enrollmentId,
+  clusterId: contextArg.clusterId,
+  recipientKeyId: contextArg.recipientKeyId,
+  publicKey: contextArg.publicKey,
+  generation: contextArg.generation,
+  expiresAt: contextArg.expiresAt,
+});