@serve.zone/interfaces 16.1.0 → 16.3.0

package/dist_ts/data/service.js

@@ -1,2 +1,100 @@
-export {};
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2VydmljZS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL2RhdGEvc2VydmljZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiIn0=
+export const serviceSecretFileLimits = {
+    maximumFiles: 32,
+    maximumValueBytes: 500 * 1024,
+    maximumIdentity: 2_147_483_647,
+};
+export const normalizeServiceAbsolutePath = (pathArg) => {
+    if (typeof pathArg !== 'string'
+        || !pathArg.startsWith('/')
+        || pathArg.includes('\0')
+        || pathArg.length > 255) {
+        return undefined;
+    }
+    const segments = [];
+    for (const segment of pathArg.split('/')) {
+        if (!segment || segment === '.')
+            continue;
+        if (segment === '..') {
+            if (segments.length === 0)
+                return undefined;
+            segments.pop();
+            continue;
+        }
+        if (!/^[A-Za-z0-9._-]+$/.test(segment))
+            return undefined;
+        segments.push(segment);
+    }
+    return `/${segments.join('/')}`;
+};
+const isCanonicalSecretTargetPath = (targetPathArg) => (normalizeServiceAbsolutePath(targetPathArg) === targetPathArg
+    && /^\/run\/secrets\/[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(targetPathArg)
+    && targetPathArg !== '/run/secrets/secret.json');
+const pathsOverlap = (leftArg, rightArg) => {
+    const left = normalizeServiceAbsolutePath(leftArg);
+    const right = normalizeServiceAbsolutePath(rightArg);
+    if (!left || !right)
+        return false;
+    if (left === '/' || right === '/')
+        return true;
+    return left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`);
+};
+/** Pure, secret-value-free validation shared by Cloudly and Coreflow. */
+export const validateServiceSecretFiles = (secretFilesArg, volumeMountPathsArg = []) => {
+    if (secretFilesArg === undefined)
+        return [];
+    if (!Array.isArray(secretFilesArg))
+        return ['secretFiles must be an array'];
+    if (secretFilesArg.length > serviceSecretFileLimits.maximumFiles) {
+        return [`secretFiles must contain at most ${serviceSecretFileLimits.maximumFiles} entries`];
+    }
+    const errors = [];
+    if (volumeMountPathsArg.some((mountPathArg) => (normalizeServiceAbsolutePath(mountPathArg) !== mountPathArg))) {
+        errors.push('volume mount paths must be canonical absolute paths');
+    }
+    const sourceKeys = [];
+    const targetPaths = [];
+    for (const [index, candidate] of secretFilesArg.entries()) {
+        if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) {
+            errors.push(`secretFiles[${index}] must be an object`);
+            continue;
+        }
+        const mapping = candidate;
+        if (typeof mapping.sourceKey !== 'string'
+            || mapping.sourceKey.length > 253
+            || !/^[A-Z_][A-Z0-9_]*$/.test(mapping.sourceKey)) {
+            errors.push(`secretFiles[${index}].sourceKey must be a canonical environment key`);
+        }
+        else {
+            sourceKeys.push(mapping.sourceKey);
+        }
+        if (typeof mapping.targetPath !== 'string'
+            || !isCanonicalSecretTargetPath(mapping.targetPath)) {
+            errors.push(`secretFiles[${index}].targetPath must be a unique canonical file below /run/secrets and may not be secret.json`);
+        }
+        else {
+            targetPaths.push(mapping.targetPath);
+            if (volumeMountPathsArg.some((mountPathArg) => (typeof mountPathArg === 'string' && pathsOverlap(mapping.targetPath, mountPathArg)))) {
+                errors.push(`secretFiles[${index}].targetPath overlaps a declared volume mount`);
+            }
+        }
+        for (const identityField of ['uid', 'gid']) {
+            const identity = mapping[identityField];
+            if (!Number.isSafeInteger(identity)
+                || identity < 0
+                || identity > serviceSecretFileLimits.maximumIdentity) {
+                errors.push(`secretFiles[${index}].${identityField} must be a bounded numeric identity`);
+            }
+        }
+        if (mapping.mode !== 0o400 && mapping.mode !== 0o440) {
+            errors.push(`secretFiles[${index}].mode must be 0400 or 0440`);
+        }
+    }
+    if (new Set(sourceKeys).size !== sourceKeys.length) {
+        errors.push('secretFiles sourceKey values must be unique');
+    }
+    if (new Set(targetPaths).size !== targetPaths.length) {
+        errors.push('secretFiles targetPath values must be unique');
+    }
+    return errors;
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2VydmljZS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL2RhdGEvc2VydmljZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFpREEsTUFBTSxDQUFDLE1BQU0sdUJBQXVCLEdBQUc7SUFDckMsWUFBWSxFQUFFLEVBQUU7SUFDaEIsaUJBQWlCLEVBQUUsR0FBRyxHQUFHLElBQUk7SUFDN0IsZUFBZSxFQUFFLGFBQWE7Q0FDdEIsQ0FBQztBQUVYLE1BQU0sQ0FBQyxNQUFNLDRCQUE0QixHQUFHLENBQUMsT0FBZSxFQUFzQixFQUFFO0lBQ2xGLElBQUksT0FBTyxPQUFPLEtBQUssUUFBUTtXQUMxQixDQUFDLE9BQU8sQ0FBQyxVQUFVLENBQUMsR0FBRyxDQUFDO1dBQ3hCLE9BQU8sQ0FBQyxRQUFRLENBQUMsSUFBSSxDQUFDO1dBQ3RCLE9BQU8sQ0FBQyxNQUFNLEdBQUcsR0FBRyxFQUFFLENBQUM7UUFDMUIsT0FBTyxTQUFTLENBQUM7SUFDbkIsQ0FBQztJQUNELE1BQU0sUUFBUSxHQUFhLEVBQUUsQ0FBQztJQUM5QixLQUFLLE1BQU0sT0FBTyxJQUFJLE9BQU8sQ0FBQyxLQUFLLENBQUMsR0FBRyxDQUFDLEVBQUUsQ0FBQztRQUN6QyxJQUFJLENBQUMsT0FBTyxJQUFJLE9BQU8sS0FBSyxHQUFHO1lBQUUsU0FBUztRQUMxQyxJQUFJLE9BQU8sS0FBSyxJQUFJLEVBQUUsQ0FBQztZQUNyQixJQUFJLFFBQVEsQ0FBQyxNQUFNLEtBQUssQ0FBQztnQkFBRSxPQUFPLFNBQVMsQ0FBQztZQUM1QyxRQUFRLENBQUMsR0FBRyxFQUFFLENBQUM7WUFDZixTQUFTO1FBQ1gsQ0FBQztRQUNELElBQUksQ0FBQyxtQkFBbUIsQ0FBQyxJQUFJLENBQUMsT0FBTyxDQUFDO1lBQUUsT0FBTyxTQUFTLENBQUM7UUFDekQsUUFBUSxDQUFDLElBQUksQ0FBQyxPQUFPLENBQUMsQ0FBQztJQUN6QixDQUFDO0lBQ0QsT0FBTyxJQUFJLFFBQVEsQ0FBQyxJ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

package/dist_ts/requests/service.d.ts

@@ -7,7 +7,25 @@ import type { IImageRelease } from '../data/immutableimage.js';
 import type { IDeploymentPreflightReport, IDeploymentPreflightRequestData } from '../data/deploymentpreflight.js';
 import type { IDeploymentReservationInput, IServiceDeploymentOperation, IServiceDeploymentStatus } from '../data/deploymentoperation.js';
 import type { TSha256Digest } from '../data/immutableimage.js';
-import type { IServiceDeploymentAdoptionInput, IServiceDeploymentAdoptionPreflightInput, IServiceDeploymentAdoptionReport, IServiceDeploymentAdoptionResult } from '../data/deploymentadoption.js';
+import type { IServiceDeploymentAdoptionInput, IServiceDeploymentAdoptionImagePromotionInput, IServiceDeploymentAdoptionImagePromotionResult, IServiceDeploymentAdoptionRolloutInput, IServiceDeploymentAdoptionRolloutResult, IServiceDeploymentAdoptionPreflightInput, IServiceDeploymentAdoptionReport, IServiceDeploymentAdoptionResult } from '../data/deploymentadoption.js';
+export interface IRequest_Any_Cloudly_BootstrapServiceDeploymentAdoptionRollout extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IRequest_Any_Cloudly_BootstrapServiceDeploymentAdoptionRollout> {
+    method: 'bootstrapServiceDeploymentAdoptionRollout';
+    request: IServiceDeploymentAdoptionRolloutInput & {
+        identity: IIdentityCredential;
+    };
+    response: {
+        result: IServiceDeploymentAdoptionRolloutResult;
+    };
+}
+export interface IRequest_Any_Cloudly_PromoteServiceDeploymentAdoptionImage extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IRequest_Any_Cloudly_PromoteServiceDeploymentAdoptionImage> {
+    method: 'promoteServiceDeploymentAdoptionImage';
+    request: IServiceDeploymentAdoptionImagePromotionInput & {
+        identity: IIdentityCredential;
+    };
+    response: {
+        result: IServiceDeploymentAdoptionImagePromotionResult;
+    };
+}
 export interface IRequest_Any_Cloudly_GetServiceDeploymentAdoptionPreflight extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IRequest_Any_Cloudly_GetServiceDeploymentAdoptionPreflight> {
     method: 'getServiceDeploymentAdoptionPreflight';
     request: IServiceDeploymentAdoptionPreflightInput & {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/interfaces",
-  "version": "16.1.0",
+  "version": "16.3.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.",
   "exports": {

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/interfaces',
-  version: '16.1.0',
+  version: '16.3.0',
   description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 }

package/ts/data/deploymentadoption.ts

@@ -4,13 +4,19 @@ import type {
 } from './deploymentpreflight.js';
 import type { IDeployment } from './deployment.js';
 import type {
+  IImageRolloutStatus,
   IImmutableImageDeploymentPlan,
   IImmutableRolloutReportEnvelope,
   IImmutableImageTargetScope,
   TOciManifestMediaType,
   TSha256Digest,
 } from './immutableimage.js';
-import { normalizeImmutableReleaseTag, normalizeSha256Digest } from './immutableimage.js';
+import {
+  normalizeImmutableReleaseTag,
+  normalizeSha256Digest,
+  validateImageRolloutStatus,
+  validateImmutableImageDeploymentPlan,
+} from './immutableimage.js';
 import type { IRegistryTarget } from './registry.js';
 
 export type TServiceDeploymentAdoptionDecision = 'GO' | 'NO-GO';
@@ -58,6 +64,56 @@ extends IServiceDeploymentAdoptionPreflightInput {
   expectedAdoptionDigest: TServiceDeploymentAdoptionDigest;
 }
 
+export interface IServiceDeploymentAdoptionImagePromotionInput
+extends IServiceDeploymentAdoptionPreflightInput {
+  targetReleaseTag: string;
+  expectedSourceImageDigest?: TSha256Digest;
+  idempotencyKey: string;
+}
+
+export interface IServiceDeploymentAdoptionImagePromotionResult {
+  status: 'promoted' | 'already-promoted';
+  organizationId: string;
+  serviceId: string;
+  sourceTag: string;
+  releaseTag: string;
+  registryHost: string;
+  repository: string;
+  digest: TSha256Digest;
+  mediaType:
+    | 'application/vnd.oci.image.index.v1+json'
+    | 'application/vnd.docker.distribution.manifest.list.v2+json';
+  platforms: IOciPlatformDescriptorSummary[];
+  releaseId: string;
+  digestPinnedImageReference: string;
+}
+
+export interface IServiceDeploymentAdoptionRolloutInput
+extends IServiceDeploymentAdoptionPreflightInput {
+  releaseTag: string;
+  expectedTargetImageDigest: TSha256Digest;
+  idempotencyKey: string;
+}
+
+export interface IServiceDeploymentAdoptionRolloutResult {
+  status:
+    | 'rollout-started'
+    | 'rollout-in-progress'
+    | 'rollout-succeeded'
+    | 'rollout-failed';
+  idempotentReplay: boolean;
+  operationId: string;
+  organizationId: string;
+  serviceId: string;
+  registryHost: string;
+  repository: string;
+  releaseTag: string;
+  digest: TSha256Digest;
+  releaseId: string;
+  plan: IImmutableImageDeploymentPlan;
+  rolloutStatus: IImageRolloutStatus;
+}
+
 interface IServiceDeploymentAdoptionReportBase {
   schemaVersion: 1;
   mutationPerformed: false;
@@ -194,6 +250,7 @@ export const validateServiceDeploymentAdoptionRetentionAttestation = (
 };
 
 const boundaryIdentifierRegex = /^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/;
+const immutableSemverReleaseTagRegex = /^(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)(?:-(?:0|[1-9][0-9]*|[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9][0-9]*|[A-Za-z-][0-9A-Za-z-]*))*)?$/;
 const indexMediaTypes = new Set<TOciManifestMediaType>([
   'application/vnd.oci.image.index.v1+json',
   'application/vnd.docker.distribution.manifest.list.v2+json',
@@ -229,6 +286,15 @@ const isCanonicalDigest = (valueArg: unknown): valueArg is TSha256Digest =>
 const isNonNegativeInteger = (valueArg: unknown): valueArg is number =>
   Number.isSafeInteger(valueArg) && (valueArg as number) >= 0;
 
+export const normalizeServiceDeploymentAdoptionReleaseTag = (
+  tagArg: unknown,
+): string | undefined => {
+  const normalizedTag = normalizeImmutableReleaseTag(tagArg);
+  return normalizedTag && immutableSemverReleaseTagRegex.test(normalizedTag)
+    ? normalizedTag
+    : undefined;
+};
+
 export const validateServiceDeploymentAdoptionPreflightInput = (
   inputArg: unknown,
 ): string[] => {
@@ -257,6 +323,183 @@ export const validateServiceDeploymentAdoptionInput = (inputArg: unknown): strin
   return errors;
 };
 
+export const validateServiceDeploymentAdoptionImagePromotionInput = (
+  inputArg: unknown,
+): string[] => {
+  const errors = validateServiceDeploymentAdoptionPreflightInput(inputArg);
+  if (!isRecord(inputArg)) return errors;
+  if (!normalizeServiceDeploymentAdoptionReleaseTag(inputArg.targetReleaseTag)) {
+    errors.push('targetReleaseTag must be a canonical OCI-safe semantic version tag');
+  }
+  if (!isBoundedIdentifier(inputArg.idempotencyKey)) {
+    errors.push('idempotencyKey must be a bounded canonical identifier');
+  }
+  if (inputArg.expectedSourceImageDigest !== undefined
+    && !isCanonicalDigest(inputArg.expectedSourceImageDigest)) {
+    errors.push('expectedSourceImageDigest must be a canonical sha256 digest when provided');
+  }
+  return errors;
+};
+
+export const validateServiceDeploymentAdoptionImagePromotionResult = (
+  resultArg: unknown,
+): string[] => {
+  if (!isRecord(resultArg)) return ['adoption image promotion result must be an object'];
+  const errors: string[] = [];
+  if (resultArg.status !== 'promoted' && resultArg.status !== 'already-promoted') {
+    errors.push('status must identify a promoted or already-promoted result');
+  }
+  for (const key of ['organizationId', 'serviceId', 'releaseId'] as const) {
+    if (!isBoundedIdentifier(resultArg[key])) {
+      errors.push(`${key} must be a bounded canonical identifier`);
+    }
+  }
+  if (typeof resultArg.sourceTag !== 'string'
+    || resultArg.sourceTag.trim() !== resultArg.sourceTag
+    || resultArg.sourceTag.length < 1
+    || resultArg.sourceTag.length > 128) {
+    errors.push('sourceTag must be a bounded canonical registry tag');
+  }
+  if (!normalizeServiceDeploymentAdoptionReleaseTag(resultArg.releaseTag)) {
+    errors.push('releaseTag must be a canonical OCI-safe semantic version tag');
+  }
+  if (typeof resultArg.registryHost !== 'string'
+    || resultArg.registryHost.trim() !== resultArg.registryHost
+    || !resultArg.registryHost) {
+    errors.push('registryHost must be a non-empty canonical string');
+  }
+  if (typeof resultArg.repository !== 'string'
+    || resultArg.repository.trim() !== resultArg.repository
+    || !resultArg.repository) {
+    errors.push('repository must be a non-empty canonical string');
+  }
+  if (!isCanonicalDigest(resultArg.digest)) {
+    errors.push('digest must be a canonical sha256 digest');
+  }
+  if (!indexMediaTypes.has(resultArg.mediaType as TOciManifestMediaType)) {
+    errors.push('mediaType must identify an OCI image index');
+  }
+  if (!Array.isArray(resultArg.platforms)) {
+    errors.push('platforms must contain OCI platform evidence');
+  } else {
+    for (const architecture of ['amd64', 'arm64']) {
+      if (!resultArg.platforms.some((platformArg) => isRecord(platformArg)
+        && platformArg.os === 'linux'
+        && platformArg.architecture === architecture
+        && platformArg.runnable === true
+        && platformArg.manifestPresent === true
+        && isCanonicalDigest(platformArg.digest))) {
+        errors.push(`platforms must contain runnable linux/${architecture} evidence`);
+      }
+    }
+  }
+  if (isCanonicalDigest(resultArg.digest)
+    && typeof resultArg.registryHost === 'string'
+    && typeof resultArg.repository === 'string'
+    && resultArg.digestPinnedImageReference
+      !== `${resultArg.registryHost}/${resultArg.repository}@${resultArg.digest}`) {
+    errors.push('digestPinnedImageReference must bind the exact registry digest');
+  }
+  return errors;
+};
+
+export const validateServiceDeploymentAdoptionRolloutInput = (
+  inputArg: unknown,
+): string[] => {
+  const errors = validateServiceDeploymentAdoptionPreflightInput(inputArg);
+  if (!isRecord(inputArg)) return errors;
+  if (!normalizeServiceDeploymentAdoptionReleaseTag(inputArg.releaseTag)) {
+    errors.push('releaseTag must be a canonical OCI-safe semantic version tag');
+  }
+  if (!isCanonicalDigest(inputArg.expectedTargetImageDigest)) {
+    errors.push('expectedTargetImageDigest must be a canonical sha256 digest');
+  }
+  if (!isBoundedIdentifier(inputArg.idempotencyKey)) {
+    errors.push('idempotencyKey must be a bounded canonical identifier');
+  }
+  return errors;
+};
+
+export const validateServiceDeploymentAdoptionRolloutResult = (
+  resultArg: unknown,
+): string[] => {
+  if (!isRecord(resultArg)) return ['adoption rollout result must be an object'];
+  const errors: string[] = [];
+  if (![
+    'rollout-started',
+    'rollout-in-progress',
+    'rollout-succeeded',
+    'rollout-failed',
+  ].includes(resultArg.status as string)) {
+    errors.push('status must identify a supported adoption rollout state');
+  }
+  if (typeof resultArg.idempotentReplay !== 'boolean') {
+    errors.push('idempotentReplay must be boolean');
+  }
+  for (const key of ['operationId', 'organizationId', 'serviceId', 'releaseId'] as const) {
+    if (!isBoundedIdentifier(resultArg[key])) errors.push(`${key} must be a bounded identifier`);
+  }
+  if (!normalizeServiceDeploymentAdoptionReleaseTag(resultArg.releaseTag)) {
+    errors.push('releaseTag must be a canonical OCI-safe semantic version tag');
+  }
+  if (!isCanonicalDigest(resultArg.digest)) {
+    errors.push('digest must be a canonical sha256 digest');
+  }
+  if (!isRecord(resultArg.plan)) {
+    errors.push('plan must be present');
+  } else {
+    errors.push(...validateImmutableImageDeploymentPlan(
+      resultArg.plan as unknown as IImmutableImageDeploymentPlan,
+    ).map((errorArg) => `plan: ${errorArg}`));
+    if (resultArg.plan.operationId !== resultArg.operationId
+      || resultArg.plan.releaseId !== resultArg.releaseId
+      || resultArg.plan.releaseTag !== resultArg.releaseTag
+      || resultArg.plan.requestedDigest !== resultArg.digest
+      || resultArg.plan.registryHost !== resultArg.registryHost
+      || resultArg.plan.repository !== resultArg.repository
+      || resultArg.plan.mode !== 'promotion'
+      || resultArg.plan.rolloutGeneration !== 1) {
+      errors.push('plan must bind the exact generation-one adoption rollout result');
+    }
+  }
+  if (!isRecord(resultArg.rolloutStatus)) {
+    errors.push('rolloutStatus must be present');
+  } else {
+    errors.push(...validateImageRolloutStatus(
+      resultArg.rolloutStatus as unknown as IImageRolloutStatus,
+    ).map((errorArg) => `rolloutStatus: ${errorArg}`));
+    if (isRecord(resultArg.plan)
+      && (resultArg.rolloutStatus.rolloutId !== resultArg.plan.rolloutId
+        || resultArg.rolloutStatus.rolloutGeneration !== resultArg.plan.rolloutGeneration
+        || resultArg.rolloutStatus.expectedDigest !== resultArg.digest)) {
+      errors.push('rolloutStatus must bind the exact adoption rollout plan');
+    }
+  }
+  if (isRecord(resultArg.rolloutStatus)) {
+    const rolloutStatus = resultArg.rolloutStatus.status;
+    const successful = rolloutStatus === 'succeeded';
+    const failed = rolloutStatus === 'failed'
+      || rolloutStatus === 'mismatched'
+      || rolloutStatus === 'rolling-back'
+      || rolloutStatus === 'rolled-back';
+    if ((resultArg.status === 'rollout-succeeded') !== successful) {
+      errors.push('rollout-succeeded must exactly match a succeeded rolloutStatus');
+    }
+    if ((resultArg.status === 'rollout-failed') !== failed) {
+      errors.push('rollout-failed must exactly match a failed or mismatched rolloutStatus');
+    }
+    if ((resultArg.status === 'rollout-started' || resultArg.status === 'rollout-in-progress')
+      && (successful || failed)) {
+      errors.push('an active rollout result must not contain a terminal rolloutStatus');
+    }
+  }
+  if (typeof resultArg.registryHost !== 'string' || !resultArg.registryHost
+    || typeof resultArg.repository !== 'string' || !resultArg.repository) {
+    errors.push('registryHost and repository must be non-empty strings');
+  }
+  return errors;
+};
+
 export const validateServiceDeploymentAdoptionReport = (reportArg: unknown): string[] => {
   if (!isRecord(reportArg)) return ['adoption report must be an object'];
   const errors: string[] = [];

package/ts/data/deploymentoperation.ts

@@ -2,6 +2,7 @@ import type { IDeploymentPreflightProposedConfiguration, IDeploymentPreflightRun
 import type { IImageRolloutStatus, IImmutableImageDeploymentPlan, TSha256Digest } from './immutableimage.js';
 import { normalizeImmutableReleaseTag, normalizeSha256Digest } from './immutableimage.js';
 import type { IRegistryTarget } from './registry.js';
+import { normalizeServiceAbsolutePath, validateServiceSecretFiles } from './service.js';
 import type { TServiceTargetPortRef } from './serviceports.js';
 
 export type TDeploymentOperationMode = 'existing-service' | 'greenfield';
@@ -178,6 +179,27 @@ export const validateDeploymentProposedConfiguration = (
   ))) {
     errors.push('secretReferenceIds must be unique canonical identifiers');
   }
+  const volumeMountPaths = Array.isArray(configurationArg.volumeMounts)
+    ? configurationArg.volumeMounts.flatMap((mountArg) => (
+      isRecord(mountArg) && typeof mountArg.mountPath === 'string' ? [mountArg.mountPath] : []
+    ))
+    : [];
+  errors.push(...validateServiceSecretFiles(configurationArg.secretFiles, volumeMountPaths));
+  if (Array.isArray(configurationArg.secretFiles)
+    && Array.isArray(configurationArg.environmentVariableNames)) {
+    const publicEnvironmentNames = new Set(
+      configurationArg.environmentVariableNames.filter((nameArg): nameArg is string => (
+        typeof nameArg === 'string'
+      )),
+    );
+    if (configurationArg.secretFiles.some((fileArg) => (
+      isRecord(fileArg)
+      && typeof fileArg.sourceKey === 'string'
+      && publicEnvironmentNames.has(fileArg.sourceKey)
+    ))) {
+      errors.push('secretFiles source keys must not be declared as environment variables');
+    }
+  }
   if (!Array.isArray(configurationArg.containerPorts)
     || configurationArg.containerPorts.length > 64
     || configurationArg.containerPorts.some((portArg) => !Number.isSafeInteger(portArg)
@@ -190,6 +212,7 @@ export const validateDeploymentProposedConfiguration = (
     || configurationArg.volumeMounts.some((mountArg) => !isRecord(mountArg)
       || typeof mountArg.mountPath !== 'string'
       || !/^\/[A-Za-z0-9._/-]{0,254}$/.test(mountArg.mountPath)
+      || normalizeServiceAbsolutePath(mountArg.mountPath) !== mountArg.mountPath
       || (mountArg.storageClass !== 'corestore' && mountArg.storageClass !== 'ephemeral')
       || (mountArg.capability !== undefined
         && mountArg.capability !== 'database'

package/ts/data/deploymentpreflight.ts

@@ -4,6 +4,7 @@ import type {
 } from './immutableimage.js';
 import { normalizeImmutableReleaseTag, normalizeSha256Digest } from './immutableimage.js';
 import type { TServiceDeploymentCapability } from './user.js';
+import type { IServiceSecretFile } from './service.js';
 import type {
   IDeploymentRouteRequest,
   IServiceDeploymentOperation,
@@ -131,6 +132,8 @@ export interface IDeploymentPreflightProposedConfiguration {
   publicDomains: string[];
   environmentVariableNames: string[];
   secretReferenceIds: string[];
+  /** Secret-bundle keys that must be delivered only as Docker secret files. */
+  secretFiles?: IServiceSecretFile[];
   containerPorts: number[];
   volumeMounts: IDeploymentPreflightProposedVolumeMount[];
   requiredCapabilities: Array<'database' | 'objectstorage'>;

package/ts/data/service.ts

@@ -29,6 +29,130 @@ export interface IServiceVolume {
   options?: Record<string, string>;
 }
 
+/**
+ * A single secret-bundle key delivered as a file instead of an environment
+ * variable. Targets are intentionally restricted to Docker's secret tmpfs so
+ * a deployment declaration cannot overwrite application or system files.
+ */
+export interface IServiceSecretFile {
+  /** Key in the service's merged secret bundles. */
+  sourceKey: string;
+  /** Absolute file path below /run/secrets/. */
+  targetPath: string;
+  /** Numeric container user identity. */
+  uid: number;
+  /** Numeric container group identity. */
+  gid: number;
+  /** Read-only POSIX mode. Supported values are 0400 and 0440. */
+  mode: number;
+}
+
+export const serviceSecretFileLimits = {
+  maximumFiles: 32,
+  maximumValueBytes: 500 * 1024,
+  maximumIdentity: 2_147_483_647,
+} as const;
+
+export const normalizeServiceAbsolutePath = (pathArg: string): string | undefined => {
+  if (typeof pathArg !== 'string'
+    || !pathArg.startsWith('/')
+    || pathArg.includes('\0')
+    || pathArg.length > 255) {
+    return undefined;
+  }
+  const segments: string[] = [];
+  for (const segment of pathArg.split('/')) {
+    if (!segment || segment === '.') continue;
+    if (segment === '..') {
+      if (segments.length === 0) return undefined;
+      segments.pop();
+      continue;
+    }
+    if (!/^[A-Za-z0-9._-]+$/.test(segment)) return undefined;
+    segments.push(segment);
+  }
+  return `/${segments.join('/')}`;
+};
+
+const isCanonicalSecretTargetPath = (targetPathArg: string): boolean => (
+  normalizeServiceAbsolutePath(targetPathArg) === targetPathArg
+  && /^\/run\/secrets\/[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(targetPathArg)
+  && targetPathArg !== '/run/secrets/secret.json'
+);
+
+const pathsOverlap = (leftArg: string, rightArg: string): boolean => {
+  const left = normalizeServiceAbsolutePath(leftArg);
+  const right = normalizeServiceAbsolutePath(rightArg);
+  if (!left || !right) return false;
+  if (left === '/' || right === '/') return true;
+  return left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`);
+};
+
+/** Pure, secret-value-free validation shared by Cloudly and Coreflow. */
+export const validateServiceSecretFiles = (
+  secretFilesArg: unknown,
+  volumeMountPathsArg: string[] = [],
+): string[] => {
+  if (secretFilesArg === undefined) return [];
+  if (!Array.isArray(secretFilesArg)) return ['secretFiles must be an array'];
+  if (secretFilesArg.length > serviceSecretFileLimits.maximumFiles) {
+    return [`secretFiles must contain at most ${serviceSecretFileLimits.maximumFiles} entries`];
+  }
+  const errors: string[] = [];
+  if (volumeMountPathsArg.some((mountPathArg) => (
+    normalizeServiceAbsolutePath(mountPathArg) !== mountPathArg
+  ))) {
+    errors.push('volume mount paths must be canonical absolute paths');
+  }
+  const sourceKeys: string[] = [];
+  const targetPaths: string[] = [];
+  for (const [index, candidate] of secretFilesArg.entries()) {
+    if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) {
+      errors.push(`secretFiles[${index}] must be an object`);
+      continue;
+    }
+    const mapping = candidate as Partial<IServiceSecretFile>;
+    if (typeof mapping.sourceKey !== 'string'
+      || mapping.sourceKey.length > 253
+      || !/^[A-Z_][A-Z0-9_]*$/.test(mapping.sourceKey)) {
+      errors.push(`secretFiles[${index}].sourceKey must be a canonical environment key`);
+    } else {
+      sourceKeys.push(mapping.sourceKey);
+    }
+    if (typeof mapping.targetPath !== 'string'
+      || !isCanonicalSecretTargetPath(mapping.targetPath)) {
+      errors.push(
+        `secretFiles[${index}].targetPath must be a unique canonical file below /run/secrets and may not be secret.json`,
+      );
+    } else {
+      targetPaths.push(mapping.targetPath);
+      if (volumeMountPathsArg.some((mountPathArg) => (
+        typeof mountPathArg === 'string' && pathsOverlap(mapping.targetPath as string, mountPathArg)
+      ))) {
+        errors.push(`secretFiles[${index}].targetPath overlaps a declared volume mount`);
+      }
+    }
+    for (const identityField of ['uid', 'gid'] as const) {
+      const identity = mapping[identityField];
+      if (!Number.isSafeInteger(identity)
+        || (identity as number) < 0
+        || (identity as number) > serviceSecretFileLimits.maximumIdentity) {
+        errors.push(`secretFiles[${index}].${identityField} must be a bounded numeric identity`);
+      }
+    }
+    if (mapping.mode !== 0o400 && mapping.mode !== 0o440) {
+      errors.push(`secretFiles[${index}].mode must be 0400 or 0440`);
+    }
+  }
+  if (new Set(sourceKeys).size !== sourceKeys.length) {
+    errors.push('secretFiles sourceKey values must be unique');
+  }
+  if (new Set(targetPaths).size !== targetPaths.length) {
+    errors.push('secretFiles targetPath values must be unique');
+  }
+  return errors;
+};
+
 /**
  * Where a service is allowed to run.
  * - absent or mode 'replicated': the service runs on every node (legacy
@@ -105,6 +229,8 @@ export interface IService {
      * and thus live past the service lifecycle
      */
     additionalSecretBundleIds?: string[];
+    /** Secret keys mounted as files and excluded from Env and secret.json. */
+    secretFiles?: IServiceSecretFile[];
     
     /**
      * Service category determines deployment behavior