@serve.zone/interfaces 21.1.0 → 23.0.0

package/ts/appstore/types.ts

@@ -1,4 +1,13 @@
-import type { IServiceSecretFile } from '../data/service.js';
+import {
+  createAppStoreInstallSecretEnvelopeContext,
+  validateSecretDelivery,
+  validateSecretValueInput,
+  validateSecretValueInputForRecipient,
+  type TSecretDelivery,
+  type TSecretGeneratedEncoding,
+  type TSecretIngressRecipient,
+  type TSecretValueInput,
+} from '../data/secret.js';
 import {
   validateHostedAppRoleDefinitions,
   type IHostedAppRoleDefinition,
@@ -36,10 +45,10 @@ export type TAppStoreTrackingMode = 'tag' | 'digest';
 export type TAppStoreUpgradeStrategy = 'semver' | 'branch' | 'dockerDigest';
 
 export const appStoreStorageFeatureIds = {
-  bindingsV1: 'storage.bindings.v1',
+  bindingsV2: 'storage.bindings.v2',
   filesystemV1: 'storage.filesystem.v1',
-  objectStorageV1: 'storage.object-storage.v1',
-  objectStorageSecretFileV1: 'storage.object-storage.secret-file.v1',
+  objectStorageV2: 'storage.object-storage.v2',
+  objectStorageFileV2: 'storage.object-storage.file.v2',
 } as const;
 
 export type TAppStoreStorageFeatureId =
@@ -140,21 +149,36 @@ export interface IAppStoreResolvedSource {
   resolvedAt: string;
 }
 
-export interface IAppStoreEnvVar {
+interface IAppStoreEnvironmentDeclarationBase {
   key: string;
-  value?: string;
   description: string;
   required?: boolean;
-  /** Store the submitted value in the service-owned Cloudly secret bundle, never in service environment data. */
-  secret?: boolean;
-  /** Generate a value server-side when the installer does not submit one. Generation is allowed only for secrets. */
+}
+
+export interface IAppStorePublicEnvironmentDeclaration
+extends IAppStoreEnvironmentDeclarationBase {
+  secret?: false;
+  /** Public nonsecret default. */
+  value?: string;
+  delivery?: never;
+  generate?: never;
+}
+
+export interface IAppStoreSecretEnvironmentDeclaration
+extends IAppStoreEnvironmentDeclarationBase {
+  secret: true;
+  value?: never;
+  delivery: TSecretDelivery;
   generate?: {
-    type: 'randomHex';
-    /** Number of random bytes before hexadecimal encoding. */
+    encoding: TSecretGeneratedEncoding;
     bytes: number;
   };
 }
 
+export type TAppStoreEnvironmentDeclaration =
+  | IAppStorePublicEnvironmentDeclaration
+  | IAppStoreSecretEnvironmentDeclaration;
+
 export interface IAppStoreVolume {
   /** Stable Docker volume name. If omitted, the runtime derives one from service name and mount path. */
   name?: string;
@@ -251,7 +275,10 @@ export const validateAppStoreVersionPlatformOidc = (
     return ['appstore config must be an object'];
   }
   const config = configArg as Record<string, unknown>;
-  const errors = validateAppStorePlatformOidcCapability(config.platformOidc);
+  const errors = [
+    ...validateAppStorePlatformOidcCapability(config.platformOidc),
+    ...validateAppStoreEnvironmentDeclarations(config.envVars),
+  ];
   if (!config.platformOidc || typeof config.platformOidc !== 'object'
     || Array.isArray(config.platformOidc)) return errors;
   const capability = config.platformOidc as Record<string, unknown>;
@@ -266,14 +293,7 @@ export const validateAppStoreVersionPlatformOidc = (
           : undefined
       )).filter((valueArg): valueArg is string => typeof valueArg === 'string')
     : [];
-  const secretFileKeys = Array.isArray(config.secretFiles)
-    ? config.secretFiles.map((fileArg) => (
-        fileArg && typeof fileArg === 'object' && !Array.isArray(fileArg)
-          ? (fileArg as Record<string, unknown>).sourceKey
-          : undefined
-      )).filter((valueArg): valueArg is string => typeof valueArg === 'string')
-    : [];
-  for (const key of [...ordinaryEnvKeys, ...secretFileKeys]) {
+  for (const key of ordinaryEnvKeys) {
     if (oidcKeys.has(key)) {
       errors.push(`platformOidc environment key '${key}' collides with app runtime input`);
     }
@@ -327,13 +347,11 @@ export interface IAppStoreVersionConfig {
   port?: number;
   /** Exact OCI/Docker argument vector appended after the image entrypoint. */
   containerArgs?: string[];
-  /** Secret-bundle keys delivered only through Docker's read-only secret tmpfs. */
-  secretFiles?: IServiceSecretFile[];
   targetPorts?: IServiceTargetPort[];
   domains?: IServiceDomainRoute[];
   /** Edge/coretraffic public TCP/UDP exposure, distinct from Docker publishedPorts. */
   publicPortMappings?: IServicePublicPortMapping[];
-  envVars?: IAppStoreEnvVar[];
+  envVars?: TAppStoreEnvironmentDeclaration[];
   /**
    * @deprecated Legacy volume syntax. New templates use storageClasses and
    * storageRequests. Resolver normalization must reject legacy physical driver
@@ -407,17 +425,225 @@ export interface IServezoneAppStoreManifest {
 }
 
 export interface IAppStoreInstallRequest {
+  mutationId: string;
   appId: string;
-  version?: string;
+  version: string;
+  serviceId: string;
   serviceName: string;
   domain?: string;
   /** Legacy install-time override for the web target port. */
   port?: number;
   publishedPorts?: IAppStorePublishedPort[];
   publicPortMappings?: IServicePublicPortMapping[];
-  envVars?: Record<string, string>;
+  publicEnvironment: Record<string, string>;
+  secretInputs: Array<{ key: string; valueInput: TSecretValueInput }>;
 }
 
+const appStoreMutationIdRegex = /^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/;
+
+export const validateAppStoreEnvironmentDeclarations = (
+  declarationsArg: unknown,
+): string[] => {
+  if (declarationsArg === undefined) return [];
+  if (!Array.isArray(declarationsArg) || declarationsArg.length > 256) {
+    return ['envVars must be a bounded array'];
+  }
+  const errors: string[] = [];
+  const keys: string[] = [];
+  declarationsArg.forEach((declarationArg, indexArg) => {
+    if (!declarationArg || typeof declarationArg !== 'object' || Array.isArray(declarationArg)) {
+      errors.push(`envVars[${indexArg}] must be an object`);
+      return;
+    }
+    const declaration = declarationArg as Record<string, unknown>;
+    const allowedKeys = declaration.secret === true
+      ? new Set(['key', 'description', 'required', 'secret', 'delivery', 'generate'])
+      : new Set(['key', 'description', 'required', 'secret', 'value']);
+    if (Object.keys(declaration).some((keyArg) => !allowedKeys.has(keyArg))) {
+      errors.push(`envVars[${indexArg}] contains fields outside its exact channel schema`);
+    }
+    if (typeof declaration.key !== 'string' || !appStoreEnvKeyRegex.test(declaration.key)) {
+      errors.push(`envVars[${indexArg}].key must be canonical`);
+    } else {
+      keys.push(declaration.key);
+    }
+    if (typeof declaration.description !== 'string' || declaration.description.length > 1000) {
+      errors.push(`envVars[${indexArg}].description must be bounded`);
+    }
+    if (declaration.required !== undefined && typeof declaration.required !== 'boolean') {
+      errors.push(`envVars[${indexArg}].required must be boolean`);
+    }
+    if (declaration.secret === true) {
+      if ('value' in declaration) errors.push(`envVars[${indexArg}] secret declaration forbids value`);
+      if (!('delivery' in declaration)) {
+        errors.push(`envVars[${indexArg}] secret declaration requires delivery`);
+      } else {
+        errors.push(...validateSecretDelivery(declaration.delivery)
+          .map((errorArg) => `envVars[${indexArg}].${errorArg}`));
+      }
+      if (declaration.generate !== undefined) {
+        errors.push(...validateSecretValueInput({
+          mode: 'generated',
+          ...(declaration.generate as Record<string, unknown>),
+        }).map((errorArg) => `envVars[${indexArg}].generate ${errorArg}`));
+      }
+    } else {
+      if (declaration.secret !== undefined && declaration.secret !== false) {
+        errors.push(`envVars[${indexArg}].secret must be true or false`);
+      }
+      if ('delivery' in declaration) errors.push(`envVars[${indexArg}] public declaration forbids delivery`);
+      if ('generate' in declaration) errors.push(`envVars[${indexArg}] public declaration forbids generate`);
+      if (declaration.value !== undefined && typeof declaration.value !== 'string') {
+        errors.push(`envVars[${indexArg}].value must be a public string default`);
+      }
+    }
+  });
+  if (new Set(keys).size !== keys.length) errors.push('envVars keys must be unique');
+  return errors;
+};
+
+export const validateAppStoreInstallRequest = async (
+  requestArg: unknown,
+  configArg: IAppStoreVersionConfig,
+  activeIngressRecipientArg: TSecretIngressRecipient,
+): Promise<string[]> => {
+  if (!requestArg || typeof requestArg !== 'object' || Array.isArray(requestArg)) {
+    return ['install request must be an object'];
+  }
+  const request = requestArg as Record<string, unknown>;
+  const rawDeclarations = configArg && typeof configArg === 'object'
+    ? configArg.envVars
+    : undefined;
+  const errors = validateAppStoreEnvironmentDeclarations(rawDeclarations);
+  const allowedRequestKeys = new Set([
+    'mutationId',
+    'appId',
+    'version',
+    'serviceId',
+    'serviceName',
+    'domain',
+    'port',
+    'publishedPorts',
+    'publicPortMappings',
+    'publicEnvironment',
+    'secretInputs',
+  ]);
+  if (Object.keys(request).some((keyArg) => !allowedRequestKeys.has(keyArg))) {
+    errors.push('install request contains fields outside its schema');
+  }
+  if (typeof request.mutationId !== 'string'
+    || !appStoreMutationIdRegex.test(request.mutationId)) {
+    errors.push('install mutationId must be canonical');
+  }
+  for (const field of ['appId', 'version', 'serviceId', 'serviceName'] as const) {
+    if (typeof request[field] !== 'string' || !(request[field] as string).trim()) {
+      errors.push(`install ${field} must be non-empty`);
+    }
+  }
+  const publicEnvironment = request.publicEnvironment;
+  if (!publicEnvironment || typeof publicEnvironment !== 'object'
+    || Array.isArray(publicEnvironment)
+    || Object.entries(publicEnvironment).some(([keyArg, valueArg]) => (
+      !appStoreEnvKeyRegex.test(keyArg) || typeof valueArg !== 'string'
+    ))) {
+    errors.push('install publicEnvironment must be a canonical string map');
+  }
+  const secretInputs = Array.isArray(request.secretInputs) ? request.secretInputs : [];
+  if (!Array.isArray(request.secretInputs) || secretInputs.length > 256) {
+    errors.push('install secretInputs must be a bounded array');
+  }
+  const inputKeys: string[] = [];
+  const inputsByKey = new Map<string, Record<string, unknown>>();
+  const declarations = Array.isArray(rawDeclarations) && rawDeclarations.length <= 256
+    ? rawDeclarations.filter((entryArg): entryArg is TAppStoreEnvironmentDeclaration => (
+        validateAppStoreEnvironmentDeclarations([entryArg]).length === 0
+      ))
+    : [];
+  const publicDeclarations = new Map(declarations
+    .filter((entryArg): entryArg is IAppStorePublicEnvironmentDeclaration => entryArg.secret !== true)
+    .map((entryArg) => [entryArg.key, entryArg]));
+  const secretDeclarations = new Map(declarations
+    .filter((entryArg): entryArg is IAppStoreSecretEnvironmentDeclaration => entryArg.secret === true)
+    .map((entryArg) => [entryArg.key, entryArg]));
+  for (const [indexArg, inputArg] of secretInputs.entries()) {
+    if (!inputArg || typeof inputArg !== 'object' || Array.isArray(inputArg)) {
+      errors.push(`install secretInputs[${indexArg}] must be an object`);
+      continue;
+    }
+    const input = inputArg as Record<string, unknown>;
+    if (JSON.stringify(Object.keys(input).sort()) !== JSON.stringify(['key', 'valueInput'])) {
+      errors.push(`install secretInputs[${indexArg}] must use its exact schema`);
+    }
+    if (typeof input.key !== 'string' || !appStoreEnvKeyRegex.test(input.key)) {
+      errors.push(`install secretInputs[${indexArg}].key must be canonical`);
+      continue;
+    }
+    inputKeys.push(input.key);
+    inputsByKey.set(input.key, input);
+    const declaration = secretDeclarations.get(input.key);
+    const canBuildContext = declaration
+      && typeof request.mutationId === 'string'
+      && appStoreMutationIdRegex.test(request.mutationId)
+      && typeof request.appId === 'string'
+      && Boolean(request.appId.trim())
+      && typeof request.version === 'string'
+      && Boolean(request.version.trim())
+      && typeof request.serviceId === 'string'
+      && Boolean(request.serviceId.trim());
+    const expectedContext = canBuildContext
+      ? createAppStoreInstallSecretEnvelopeContext({
+          mutationId: request.mutationId as string,
+          appId: request.appId as string,
+          appVersion: request.version as string,
+          serviceId: request.serviceId as string,
+          key: input.key,
+          delivery: declaration.delivery,
+          generation: declaration.generate,
+        })
+      : new Uint8Array();
+    errors.push(...(await validateSecretValueInputForRecipient(
+      input.valueInput,
+      activeIngressRecipientArg,
+      expectedContext,
+    ))
+      .map((errorArg) => `install secretInputs[${indexArg}].${errorArg}`));
+  }
+  if (new Set(inputKeys).size !== inputKeys.length) {
+    errors.push('install secretInputs keys must be unique');
+  }
+  for (const key of Object.keys((publicEnvironment || {}) as Record<string, unknown>)) {
+    if (!publicDeclarations.has(key)) errors.push(`install public key '${key}' is not declared public`);
+    if (inputsByKey.has(key)) errors.push(`install key '${key}' appears in both channels`);
+  }
+  for (const [key, input] of inputsByKey) {
+    const declaration = secretDeclarations.get(key);
+    if (!declaration) {
+      errors.push(`install secret key '${key}' is not declared secret`);
+      continue;
+    }
+    const valueInput = input.valueInput as TSecretValueInput;
+    if (valueInput?.mode === 'generated'
+      && (!declaration.generate
+        || declaration.generate.encoding !== valueInput.encoding
+        || declaration.generate.bytes !== valueInput.bytes)) {
+      errors.push(`install secret key '${key}' generation does not match its declaration`);
+    }
+  }
+  for (const declaration of publicDeclarations.values()) {
+    if (declaration.required
+      && declaration.value === undefined
+      && !Object.hasOwn((publicEnvironment || {}) as object, declaration.key)) {
+      errors.push(`install required public key '${declaration.key}' is missing`);
+    }
+  }
+  for (const declaration of secretDeclarations.values()) {
+    if (declaration.required && !declaration.generate && !inputsByKey.has(declaration.key)) {
+      errors.push(`install required secret key '${declaration.key}' is missing`);
+    }
+  }
+  return errors;
+};
+
 export interface IUpgradeableAppStoreService {
   serviceId?: string;
   serviceName: string;