@serve.zone/interfaces 22.0.0 → 23.0.0

package/ts/data/immutableimage.ts

@@ -67,7 +67,31 @@ export interface ICoreflowRuntimeCapabilities {
   /** Coreflow can answer the versioned, node-scoped Corestore inventory probe. */
   corestoreInventoryVersion?: 1;
   /** Coreflow can consume exact, cluster-scoped resolved secret manifests. */
-  secretManifestVersion?: 1;
+  secretManifestVersion: 2;
+  sealedSecretMaterialVersion: 1;
+  secretRecipientEnrollmentVersion: 1;
+  workloadInitEnvironmentVersion: 1;
+}
+
+export type TImmutableContainerPlatform = 'linux/amd64' | 'linux/arm64';
+
+export interface IImmutableContainerInvocationPlatformEvidenceV1 {
+  platform: TImmutableContainerPlatform;
+  platformManifestDigest: TSha256Digest;
+  imageConfigDigest: TSha256Digest;
+  /** Effective non-empty OCI argv after applying the deployment containerArgs. */
+  effectiveArgv: string[];
+}
+
+export interface IImmutableContainerInvocationV1 {
+  schemaVersion: 1;
+  /** Sorted, unique, non-empty and limited to the authoritative platform union. */
+  targetPlatforms: TImmutableContainerPlatform[];
+  /** The one effective argv shared by every target platform. */
+  argv: string[];
+  /** Sorted exact one-to-one platform evidence. */
+  evidence: IImmutableContainerInvocationPlatformEvidenceV1[];
+  digest: TSha256Digest;
 }
 
 /**
@@ -221,6 +245,8 @@ export interface IImmutableImageDeploymentPlan {
   requestedDigest: TSha256Digest;
   digestPinnedImageReference: string;
   manifestMediaType: TOciManifestMediaType;
+  /** Mandatory immutable command/config evidence for every target platform. */
+  containerInvocation: IImmutableContainerInvocationV1;
   createdAt: number;
   mode: TImmutableImageRolloutMode;
   /** Full pre-adoption service configuration fence, required only for adoption. */
@@ -324,6 +350,122 @@ export interface IImageRolloutStatus {
 
 const sha256DigestRegex = /^sha256:[a-f0-9]{64}$/;
 
+const immutableContainerPlatforms = new Set<TImmutableContainerPlatform>([
+  'linux/amd64',
+  'linux/arm64',
+]);
+
+const validateImmutableArgv = (argvArg: unknown): argvArg is string[] => (
+  Array.isArray(argvArg)
+  && argvArg.length > 0
+  && argvArg.length <= 128
+  && argvArg.every((argumentArg) => typeof argumentArg === 'string'
+    && argumentArg.length > 0
+    && !/[\u0000-\u001f\u007f]/.test(argumentArg)
+    && new TextEncoder().encode(argumentArg).byteLength <= 4096)
+);
+
+export const createImmutableContainerInvocationDigestInput = (
+  invocationArg: Omit<IImmutableContainerInvocationV1, 'digest'> | IImmutableContainerInvocationV1,
+): string => JSON.stringify({
+  schemaVersion: invocationArg.schemaVersion,
+  targetPlatforms: invocationArg.targetPlatforms,
+  argv: invocationArg.argv,
+  evidence: invocationArg.evidence.map((entryArg) => ({
+    platform: entryArg.platform,
+    platformManifestDigest: entryArg.platformManifestDigest,
+    imageConfigDigest: entryArg.imageConfigDigest,
+    effectiveArgv: entryArg.effectiveArgv,
+  })),
+});
+
+export const computeImmutableContainerInvocationDigest = async (
+  invocationArg: Omit<IImmutableContainerInvocationV1, 'digest'> | IImmutableContainerInvocationV1,
+): Promise<TSha256Digest> => {
+  const input = new TextEncoder().encode(createImmutableContainerInvocationDigestInput(invocationArg));
+  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 const verifyImmutableContainerInvocationDigest = async (
+  invocationArg: IImmutableContainerInvocationV1,
+): Promise<boolean> => invocationArg.digest
+  === await computeImmutableContainerInvocationDigest(invocationArg);
+
+export const validateImmutableContainerInvocation = (
+  invocationArg: unknown,
+): string[] => {
+  if (!invocationArg || typeof invocationArg !== 'object' || Array.isArray(invocationArg)) {
+    return ['containerInvocation must be an object'];
+  }
+  const invocation = invocationArg as Record<string, unknown>;
+  const errors: string[] = [];
+  if (JSON.stringify(Object.keys(invocation).sort()) !== JSON.stringify([
+    'argv',
+    'digest',
+    'evidence',
+    'schemaVersion',
+    'targetPlatforms',
+  ])) {
+    errors.push('containerInvocation must use its exact schema');
+  }
+  if (invocation.schemaVersion !== 1) errors.push('containerInvocation schemaVersion must be 1');
+  const platforms = Array.isArray(invocation.targetPlatforms)
+    ? invocation.targetPlatforms
+    : [];
+  if (platforms.length === 0
+    || platforms.some((platformArg) => typeof platformArg !== 'string'
+      || !immutableContainerPlatforms.has(platformArg as TImmutableContainerPlatform))
+    || new Set(platforms).size !== platforms.length
+    || JSON.stringify(platforms) !== JSON.stringify([...platforms].sort())) {
+    errors.push('containerInvocation targetPlatforms must be sorted unique supported platforms');
+  }
+  if (!validateImmutableArgv(invocation.argv)) {
+    errors.push('containerInvocation argv must be a non-empty canonical argument vector');
+  }
+  const evidence = Array.isArray(invocation.evidence) ? invocation.evidence : [];
+  const evidencePlatforms: unknown[] = [];
+  for (const [index, entryArg] of evidence.entries()) {
+    if (!entryArg || typeof entryArg !== 'object' || Array.isArray(entryArg)) {
+      errors.push(`containerInvocation evidence[${index}] must be an object`);
+      continue;
+    }
+    const entry = entryArg as Record<string, unknown>;
+    if (JSON.stringify(Object.keys(entry).sort()) !== JSON.stringify([
+      'effectiveArgv',
+      'imageConfigDigest',
+      'platform',
+      'platformManifestDigest',
+    ])) {
+      errors.push(`containerInvocation evidence[${index}] must use its exact schema`);
+    }
+    evidencePlatforms.push(entry.platform);
+    if (!immutableContainerPlatforms.has(entry.platform as TImmutableContainerPlatform)) {
+      errors.push(`containerInvocation evidence[${index}].platform is unsupported`);
+    }
+    if (!isSha256Digest(entry.platformManifestDigest as string)
+      || !isSha256Digest(entry.imageConfigDigest as string)) {
+      errors.push(`containerInvocation evidence[${index}] digests must be canonical`);
+    }
+    if (!validateImmutableArgv(entry.effectiveArgv)
+      || JSON.stringify(entry.effectiveArgv) !== JSON.stringify(invocation.argv)) {
+      errors.push(`containerInvocation evidence[${index}] effective argv must match`);
+    }
+  }
+  if (JSON.stringify(evidencePlatforms) !== JSON.stringify(platforms)) {
+    errors.push('containerInvocation evidence must exactly cover targetPlatforms in order');
+  }
+  if (typeof invocation.digest !== 'string' || !isSha256Digest(invocation.digest)) {
+    errors.push('containerInvocation digest must be canonical');
+  }
+  return errors;
+};
+
 export const normalizeSha256Digest = (digest: unknown): TSha256Digest | undefined => {
   if (typeof digest !== 'string') return undefined;
   const normalizedDigest = digest.trim().toLowerCase();
@@ -396,6 +538,7 @@ export const validateImmutableImageDeploymentPlan = (
   ].includes(planArg.manifestMediaType)) {
     errors.push('immutable rollout root must be an OCI image index');
   }
+  errors.push(...validateImmutableContainerInvocation(planArg.containerInvocation));
   let expectedReference: string | undefined;
   try {
     expectedReference = buildDigestPinnedImageReference(
@@ -443,6 +586,12 @@ export const validateImmutableImageDeploymentPlan = (
   return errors;
 };
 
+/** Coreflow uses this async verifier before resolving or opening secret material. */
+export const verifyImmutableImageDeploymentPlan = async (
+  planArg: IImmutableImageDeploymentPlan,
+): Promise<boolean> => validateImmutableImageDeploymentPlan(planArg).length === 0
+  && await verifyImmutableContainerInvocationDigest(planArg.containerInvocation);
+
 export const validateImageRolloutStatus = (statusArg: IImageRolloutStatus): string[] => {
   const errors: string[] = [];
   if (!isImmutableIdentifier(statusArg.rolloutId)) {

package/ts/data/index.ts

@@ -22,8 +22,6 @@ export * from './isolatedrestore.golden.js';
 export * from './mail.js';
 export * from './registry.js';
 export * from './secret.js';
-export * from './secretbundle.js';
-export * from './secretgroup.js';
 export * from './baremetal.js';
 export * from './baseos.js';
 export * from './backup.js';