@serve.zone/interfaces 22.0.0 → 23.0.1

package/ts/00_commitinfo_data.ts

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

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;

package/ts/data/coremail.runtime.ts

@@ -80,16 +80,25 @@ export const coreMailContractLimits = Object.freeze({
 } as const);
 
 export class CoreMailContractError extends Error {
-  public constructor(reasonArg: string) {
+  public readonly code: TCoreMailErrorCode;
+
+  public constructor(
+    reasonArg: string,
+    codeArg: TCoreMailErrorCode = 'INVALID_REQUEST',
+  ) {
     super(`CoreMail contract error: ${reasonArg}`);
     this.name = 'CoreMailContractError';
+    this.code = codeArg;
   }
 }
 
 type TStrictRecord = Record<string, unknown>;
 
-const fail = (reasonArg: string): never => {
-  throw new CoreMailContractError(reasonArg);
+const fail = (
+  reasonArg: string,
+  codeArg: TCoreMailErrorCode = 'INVALID_REQUEST',
+): never => {
+  throw new CoreMailContractError(reasonArg, codeArg);
 };
 
 const compareStrings = (leftArg: string, rightArg: string): number =>
@@ -637,9 +646,14 @@ const normalizeContentDescriptor = (
       record.lengthBytes,
       `${pathArg}.lengthBytes`,
       0,
-      maximumBytes,
     ),
   };
+  if (normalized.lengthBytes > maximumBytes) {
+    fail(
+      `${pathArg}.lengthBytes exceeds the ${kind} content budget of ${maximumBytes}`,
+      'PAYLOAD_LIMIT_EXCEEDED',
+    );
+  }
   if (Object.hasOwn(record, 'filename')) {
     normalized.filename = requireDisplayText(
       record.filename,

package/ts/data/deploymentoperation.ts

@@ -3,7 +3,7 @@ import type { IGatewayRouteDnsResult } from './gateway.js';
 import type { IImageRolloutStatus, IImmutableImageDeploymentPlan, TSha256Digest } from './immutableimage.js';
 import { normalizeImmutableReleaseTag, normalizeSha256Digest } from './immutableimage.js';
 import type { IRegistryTarget } from './registry.js';
-import { normalizeServiceAbsolutePath, validateServiceContainerArgs, validateServiceSecretFiles } from './service.js';
+import { normalizeServiceAbsolutePath, validateServiceContainerArgs } from './service.js';
 import type { TServiceTargetPortRef } from './serviceports.js';
 
 export type TDeploymentOperationMode = 'existing-service' | 'greenfield';
@@ -162,10 +162,12 @@ export const validateDeploymentProposedConfiguration = (
     || configurationArg.projectName.length > 200) {
     errors.push('projectName must be bounded and non-empty');
   }
-  if (!validateStringArray(configurationArg.targetPlatforms, 8, (platformArg) => (
-    /^[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*$/.test(platformArg)
-  ))) {
-    errors.push('targetPlatforms must be unique canonical platform identifiers');
+  if (!validateStringArray(configurationArg.targetPlatforms, 2, (platformArg) => (
+    platformArg === 'linux/amd64' || platformArg === 'linux/arm64'
+  )) || (configurationArg.targetPlatforms as string[]).length === 0
+    || JSON.stringify(configurationArg.targetPlatforms)
+      !== JSON.stringify([...(configurationArg.targetPlatforms as string[])].sort())) {
+    errors.push('targetPlatforms must be a sorted non-empty supported platform set');
   }
   if (!validateStringArray(configurationArg.publicDomains, 32, (domainArg) => (
     canonicalizeDeploymentHostname(domainArg) === domainArg
@@ -177,33 +179,7 @@ export const validateDeploymentProposedConfiguration = (
   ))) {
     errors.push('environmentVariableNames must be unique canonical names');
   }
-  if (!validateStringArray(configurationArg.secretReferenceIds, 64, (idArg) => (
-    idArg.length <= 253 && /^[A-Za-z0-9][A-Za-z0-9:._-]*$/.test(idArg)
-  ))) {
-    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(...validateServiceContainerArgs(configurationArg.containerArgs));
-  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)

package/ts/data/deploymentpreflight.ts

@@ -1,10 +1,10 @@
 import type {
+  TImmutableContainerPlatform,
   TOciManifestMediaType,
   TSha256Digest,
 } 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,
@@ -145,14 +145,11 @@ export interface IDeploymentPreflightProposedConfiguration {
   schemaVersion: 1;
   declarationComplete: boolean;
   projectName: string;
-  targetPlatforms: string[];
+  targetPlatforms: TImmutableContainerPlatform[];
   publicDomains: string[];
   environmentVariableNames: string[];
-  secretReferenceIds: string[];
   /** Exact OCI/Docker argument vector appended after the image entrypoint. */
   containerArgs?: string[];
-  /** Secret-bundle keys that must be delivered only as Docker secret files. */
-  secretFiles?: IServiceSecretFile[];
   containerPorts: number[];
   volumeMounts: IDeploymentPreflightProposedVolumeMount[];
   requiredCapabilities: Array<'database' | 'objectstorage' | 'pushnotification'>;

package/ts/data/hostedapp.ts

@@ -2,6 +2,58 @@ export type THostedAppHostType = 'onebox' | 'cloudly' | string;
 
 export const hostedAppOidcRoleClaim = 'roles' as const;
 export const hostedAppOidcAppInstanceIdClaim = 'servezone_app_instance_id' as const;
+export const hostedAppMachineServiceIdClaim = 'servezone_service_id' as const;
+export const hostedAppMachineAudience = 'serve.zone/hosted-app-lifecycle' as const;
+
+export interface IHostedAppMachineClaims {
+  sub: string;
+  aud: typeof hostedAppMachineAudience;
+  iat: number;
+  exp: number;
+  [hostedAppOidcAppInstanceIdClaim]: string;
+  [hostedAppMachineServiceIdClaim]: string;
+}
+
+export const createHostedAppMachineSubject = (appInstanceIdArg: string): string => (
+  `urn:serve.zone:hosted-app:${appInstanceIdArg}`
+);
+
+export const validateHostedAppMachineClaims = (
+  claimsArg: unknown,
+  expectedArg: {
+    appInstanceId: string;
+    serviceId: string;
+    nowEpochSeconds?: number;
+  },
+): string[] => {
+  if (!claimsArg || typeof claimsArg !== 'object' || Array.isArray(claimsArg)) {
+    return ['hosted app machine claims must be an object'];
+  }
+  const claims = claimsArg as Record<string, unknown>;
+  const errors: string[] = [];
+  if (claims.sub !== createHostedAppMachineSubject(expectedArg.appInstanceId)) {
+    errors.push('hosted app machine subject does not match');
+  }
+  if (claims.aud !== hostedAppMachineAudience) {
+    errors.push('hosted app machine audience does not match');
+  }
+  if (claims[hostedAppOidcAppInstanceIdClaim] !== expectedArg.appInstanceId) {
+    errors.push('hosted app machine app instance does not match');
+  }
+  if (claims[hostedAppMachineServiceIdClaim] !== expectedArg.serviceId) {
+    errors.push('hosted app machine service does not match');
+  }
+  const now = expectedArg.nowEpochSeconds ?? Math.floor(Date.now() / 1000);
+  if (!Number.isSafeInteger(claims.iat) || (claims.iat as number) < 0
+    || (claims.iat as number) > now) {
+    errors.push('hosted app machine issued-at time is malformed');
+  }
+  if (!Number.isSafeInteger(claims.exp) || (claims.exp as number) <= now
+    || (Number.isSafeInteger(claims.iat) && (claims.exp as number) <= (claims.iat as number))) {
+    errors.push('hosted app machine expiry is malformed or expired');
+  }
+  return errors;
+};
 
 export interface IHostedAppRoleDefinition {
   /** Stable role identifier emitted in the hosted app's audience-scoped token. */
@@ -276,7 +328,7 @@ export type THostedAppRuntimeStatus =
   | 'stopped'
   | 'unknown';
 
-export type THostedAppBootstrapActionType = 'setupLink' | 'credentials' | 'message';
+export type THostedAppBootstrapActionType = 'setupRoute' | 'message';
 
 export type THostedAppBootstrapActionStatus =
   | 'requested'
@@ -293,21 +345,12 @@ export type THostedAppUpgradeStatus =
   | 'success'
   | 'failed';
 
-export interface IHostedAppRuntimeIdentity {
-  appInstanceId: string;
-  appControlToken: string;
-  hostType?: THostedAppHostType;
-}
-
-export interface IHostedAppBootstrapAction {
+interface IHostedAppBootstrapActionBase {
   id: string;
-  type: THostedAppBootstrapActionType;
+  /** Server-managed CAS revision incremented on every action transition. */
+  revision: number;
   status: THostedAppBootstrapActionStatus;
   label: string;
-  url?: string;
-  username?: string;
-  password?: string;
-  message?: string;
   expiresAt?: number;
   createdAt: number;
   updatedAt: number;
@@ -315,6 +358,18 @@ export interface IHostedAppBootstrapAction {
   dismissedAt?: number;
 }
 
+export type IHostedAppBootstrapAction =
+  | (IHostedAppBootstrapActionBase & {
+      type: 'setupRoute';
+      route: string;
+      message?: never;
+    })
+  | (IHostedAppBootstrapActionBase & {
+      type: 'message';
+      route?: never;
+      message: string;
+    });
+
 export interface IHostedAppUpgradeState {
   status: THostedAppUpgradeStatus;
   appTemplateId?: string;
@@ -347,9 +402,80 @@ export interface IHostedAppLifecycleState extends IHostedAppLifecycleReport {
   upgradeState?: IHostedAppUpgradeState;
 }
 
-export type IHostedAppBootstrapActionRequest = Omit<
-  IHostedAppBootstrapAction,
-  'id' | 'status' | 'createdAt' | 'updatedAt' | 'completedAt' | 'dismissedAt'
-> & {
-  id?: string;
+type THostedAppBootstrapActionServerFields =
+  | 'id'
+  | 'revision'
+  | 'status'
+  | 'createdAt'
+  | 'updatedAt'
+  | 'completedAt'
+  | 'dismissedAt';
+
+export type IHostedAppBootstrapActionRequest =
+  | (Omit<
+      Extract<IHostedAppBootstrapAction, { type: 'setupRoute' }>,
+      THostedAppBootstrapActionServerFields
+    > & { id?: string })
+  | (Omit<
+      Extract<IHostedAppBootstrapAction, { type: 'message' }>,
+      THostedAppBootstrapActionServerFields
+    > & { id?: string });
+
+export const normalizeHostedAppSetupRoute = (routeArg: unknown): string | undefined => {
+  if (typeof routeArg !== 'string'
+    || !routeArg.startsWith('/')
+    || routeArg.startsWith('//')
+    || /[\\?#\s]/.test(routeArg)
+    || /%5c/i.test(routeArg)) {
+    return undefined;
+  }
+  const parsed = new URL(routeArg, 'https://app.invalid');
+  return parsed.pathname === routeArg ? routeArg : undefined;
+};
+
+export const validateHostedAppBootstrapActionRequest = (
+  actionArg: unknown,
+): string[] => {
+  if (!actionArg || typeof actionArg !== 'object' || Array.isArray(actionArg)) {
+    return ['hosted app bootstrap action must be an object'];
+  }
+  const action = actionArg as Record<string, unknown>;
+  const errors: string[] = [];
+  const allowedKeys = action.type === 'setupRoute'
+    ? new Set(['id', 'type', 'label', 'route', 'expiresAt'])
+    : action.type === 'message'
+      ? new Set(['id', 'type', 'label', 'message', 'expiresAt'])
+      : new Set(['id', 'type', 'label', 'expiresAt']);
+  if (Object.keys(action).some((keyArg) => !allowedKeys.has(keyArg))) {
+    errors.push('hosted app bootstrap action contains fields outside its schema');
+  }
+  if (action.id !== undefined
+    && (typeof action.id !== 'string'
+      || !/^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/.test(action.id))) {
+    errors.push('hosted app bootstrap action id must be canonical');
+  }
+  if (action.expiresAt !== undefined
+    && (!Number.isSafeInteger(action.expiresAt) || (action.expiresAt as number) < 1)) {
+    errors.push('hosted app bootstrap action expiresAt must be a positive integer');
+  }
+  if (action.type !== 'setupRoute' && action.type !== 'message') {
+    errors.push('hosted app bootstrap action type is unsupported');
+  }
+  if (typeof action.label !== 'string' || !action.label.trim() || action.label.length > 200) {
+    errors.push('hosted app bootstrap action label must be bounded');
+  }
+  if (action.type === 'setupRoute') {
+    if (normalizeHostedAppSetupRoute(action.route) !== action.route) {
+      errors.push('hosted app setup route must be a canonical same-origin absolute path');
+    }
+    if ('message' in action) errors.push('hosted app setup route forbids message');
+  }
+  if (action.type === 'message') {
+    if (typeof action.message !== 'string' || !action.message.trim()
+      || action.message.length > 4000) {
+      errors.push('hosted app bootstrap message must be bounded');
+    }
+    if ('route' in action) errors.push('hosted app message forbids route');
+  }
+  return errors;
 };