@serve.zone/interfaces 13.0.1 → 15.0.0

package/ts/data/deploymentpreflight.ts

@@ -2,14 +2,34 @@ import type {
   TOciManifestMediaType,
   TSha256Digest,
 } from './immutableimage.js';
-import { normalizeSha256Digest } from './immutableimage.js';
+import { normalizeImmutableReleaseTag, normalizeSha256Digest } from './immutableimage.js';
 import type { TServiceDeploymentCapability } from './user.js';
+import type {
+  IDeploymentRouteRequest,
+  IServiceDeploymentOperation,
+  TDeploymentOperationMode,
+  TDeploymentOperationPhase,
+} from './deploymentoperation.js';
+import {
+  canonicalizeDeploymentHostname,
+  getDeploymentRouteVerificationHostname,
+  normalizeDeploymentReadinessPath,
+  validateDeploymentProposedConfiguration,
+} from './deploymentoperation.js';
 
 export type TDeploymentPreflightDecision = 'GO' | 'NO-GO';
 
 export type TDeploymentPreflightBlockerCode =
   | 'INVALID_REQUEST'
   | 'AUTHORIZATION_MISSING'
+  | 'ORGANIZATION_SCOPE_MISSING'
+  | 'SERVICE_OWNERSHIP_MISMATCH'
+  | 'DEPLOYMENT_OPERATION_NOT_FOUND'
+  | 'DEPLOYMENT_OPERATION_CONFLICT'
+  | 'DEPLOY_ON_PUSH_MUST_BE_DISABLED'
+  | 'REGISTRY_AUTHENTICATION_UNAVAILABLE'
+  | 'REGISTRY_REPOSITORY_MISMATCH'
+  | 'REGISTRY_TAG_CONFLICT'
   | 'SOURCE_REVISION_INVALID'
   | 'SOURCE_WORKTREE_DIRTY'
   | 'VERSION_NOT_RESERVED'
@@ -31,13 +51,19 @@ export type TDeploymentPreflightBlockerCode =
   | 'IMMUTABLE_RELEASE_TAG_NOT_RESERVED'
   | 'RELEASE_EVIDENCE_MISSING'
   | 'RELEASE_EVIDENCE_INVALID'
+  | 'RELEASE_EVIDENCE_AMBIGUOUS'
   | 'RELEASE_NOT_AUTHORIZED'
   | 'GREENFIELD_EXECUTION_UNAVAILABLE'
   | 'ROUTE_PROMOTION_FENCE_UNAVAILABLE'
   | 'POST_DEPLOYMENT_VERIFICATION_UNAVAILABLE'
   | 'WOULD_REPLACE_EXISTING_STATE'
   | 'CORESTORE_INVENTORY_UNAVAILABLE'
-  | 'RUNTIME_ATTESTATION_MISMATCH';
+  | 'RUNTIME_ATTESTATION_MISMATCH'
+  | 'ROLLOUT_ACTIVE_CONFLICT'
+  | 'ROLLOUT_NOT_SUCCEEDED'
+  | 'ROUTE_UNAVAILABLE'
+  | 'ROUTE_VERIFICATION_FAILED'
+  | 'TLS_VERIFICATION_FAILED';
 
 export interface IDeploymentPreflightBlocker {
   code: TDeploymentPreflightBlockerCode;
@@ -64,6 +90,7 @@ export interface IDeploymentPreflightRuntimeTask {
   status: string;
   healthStatus?: string;
   imageReference?: string;
+  observedDigest?: TSha256Digest;
   reportedDigest?: TSha256Digest;
   verificationStatus?: 'not-required' | 'pending' | 'verified' | 'missing' | 'mismatched';
 }
@@ -130,6 +157,10 @@ export interface IDeploymentReleaseEvidence {
 export interface IDeploymentPreflightRequestData {
   requestId: string;
   serviceId: string;
+  organizationId?: string;
+  mode?: TDeploymentOperationMode;
+  phase?: TDeploymentOperationPhase;
+  operationId?: string;
   sourceRevision: string;
   sourceDirty: boolean;
   version: string;
@@ -138,7 +169,9 @@ export interface IDeploymentPreflightRequestData {
   ociIndexDigest?: string;
   releaseTag?: string;
   releaseEvidence?: IDeploymentReleaseEvidence;
-  greenfield: true;
+  routes?: IDeploymentRouteRequest[];
+  /** Legacy v14 discriminator. Equivalent to mode: 'greenfield'. */
+  greenfield?: true;
 }
 
 export interface IDeploymentPreflightReport {
@@ -147,6 +180,7 @@ export interface IDeploymentPreflightReport {
   mutationPerformed: false;
   generatedAt: number;
   service: {
+    organizationId?: string;
     serviceId: string;
     serviceName: string;
     workspaceIdentity: string;
@@ -154,6 +188,9 @@ export interface IDeploymentPreflightReport {
     registryRepository: string;
     deployOnPush: boolean;
   };
+  mode?: TDeploymentOperationMode;
+  phase?: TDeploymentOperationPhase;
+  operation?: IServiceDeploymentOperation;
   source: {
     revision: string;
     dirty: boolean;
@@ -182,6 +219,8 @@ export interface IDeploymentPreflightReport {
     observedReplicaCount: number;
     healthyReplicaCount: number;
     verifiedReplicaCount: number;
+    observedDigestReplicaCount: number;
+    observedDigestConsistent: boolean;
     consistentDigest: boolean;
   };
   platformBindings: IDeploymentPreflightPlatformBinding[];
@@ -209,30 +248,8 @@ export interface IGreenfieldDeploymentFence {
   targetNamespace: string;
 }
 
-export interface IGreenfieldDeploymentOperation {
-  id: string;
-  data: {
-    idempotencyKey: string;
-    requestDigest: TSha256Digest;
-    fence: IGreenfieldDeploymentFence;
-    candidateServiceId?: string;
-    state:
-      | 'reserved'
-      | 'provisioning'
-      | 'deploying'
-      | 'verifying'
-      | 'ready-for-promotion'
-      | 'promoting'
-      | 'promoted'
-      | 'rolling-back'
-      | 'rolled-back'
-      | 'failed';
-    routeGeneration?: number;
-    createdAt: number;
-    updatedAt: number;
-    failureCode?: string;
-  };
-}
+/** @deprecated Use IServiceDeploymentOperation. */
+export type IGreenfieldDeploymentOperation = IServiceDeploymentOperation;
 
 const fullGitRevisionRegex = /^[a-f0-9]{40}$/;
 const semanticVersionRegex = /^(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)(?:-(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
@@ -290,48 +307,15 @@ export const validateDeploymentPreflightRequest = (
   const configuration = isRecord(requestArg.proposedConfiguration)
     ? requestArg.proposedConfiguration
     : undefined;
-  const stringArrayValid = (
-    valueArg: unknown,
-    maxItemsArg: number,
-    patternArg: RegExp,
-  ): valueArg is string[] => Array.isArray(valueArg)
-    && valueArg.length <= maxItemsArg
-    && valueArg.every((itemArg) => typeof itemArg === 'string'
-      && itemArg.length > 0
-      && itemArg.length <= 253
-      && patternArg.test(itemArg))
-    && new Set(valueArg).size === valueArg.length;
-  const capabilities = configuration?.requiredCapabilities;
-  const volumeMounts = configuration?.volumeMounts;
-  if (
-    !configuration
-    || configuration.schemaVersion !== 1
-    || typeof configuration.declarationComplete !== 'boolean'
-    || typeof configuration.projectName !== 'string'
-    || !configuration.projectName.trim()
-    || configuration.projectName.length > 200
-    || !stringArrayValid(configuration.targetPlatforms, 8, /^[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*$/)
-    || !stringArrayValid(configuration.publicDomains, 32, /^[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/)
-    || !stringArrayValid(configuration.environmentVariableNames, 256, /^[A-Z_][A-Z0-9_]*$/)
-    || !stringArrayValid(configuration.secretReferenceIds, 64, /^[A-Za-z0-9][A-Za-z0-9:._-]*$/)
-    || !Array.isArray(configuration.containerPorts)
-    || configuration.containerPorts.length > 64
-    || configuration.containerPorts.some((portArg) => !Number.isSafeInteger(portArg) || portArg < 1 || portArg > 65535)
-    || new Set(configuration.containerPorts).size !== configuration.containerPorts.length
-    || !Array.isArray(volumeMounts)
-    || volumeMounts.length > 32
-    || volumeMounts.some((mountArg) => !isRecord(mountArg)
-      || typeof mountArg.mountPath !== 'string'
-      || !/^\/[A-Za-z0-9._/-]{0,254}$/.test(mountArg.mountPath)
-      || (mountArg.storageClass !== 'corestore' && mountArg.storageClass !== 'ephemeral')
-      || (mountArg.capability !== undefined
-        && mountArg.capability !== 'database'
-        && mountArg.capability !== 'objectstorage'))
-    || !Array.isArray(capabilities)
-    || capabilities.length > 2
-    || capabilities.some((capabilityArg) => capabilityArg !== 'database' && capabilityArg !== 'objectstorage')
-    || new Set(capabilities).size !== capabilities.length
-  ) {
+  const configurationContainerPorts = Array.isArray(configuration?.containerPorts)
+    ? configuration.containerPorts
+    : [];
+  const configurationPublicDomains = Array.isArray(configuration?.publicDomains)
+    ? configuration.publicDomains.filter((domainArg): domainArg is string => (
+      typeof domainArg === 'string'
+    ))
+    : [];
+  if (validateDeploymentProposedConfiguration(configuration).length > 0) {
     blockers.push({ code: 'INVALID_REQUEST', message: 'The proposed deployment configuration is malformed.' });
   }
   if (requestArg.ociIndexDigest !== undefined
@@ -340,12 +324,83 @@ export const validateDeploymentPreflightRequest = (
     blockers.push({ code: 'INVALID_REQUEST', message: 'OCI index digest is malformed.' });
   }
   if (requestArg.releaseTag !== undefined
-    && (typeof requestArg.releaseTag !== 'string'
-      || !/^[A-Za-z0-9_][A-Za-z0-9._-]{0,127}$/.test(requestArg.releaseTag))) {
+    && !normalizeImmutableReleaseTag(requestArg.releaseTag)) {
     blockers.push({ code: 'INVALID_REQUEST', message: 'Release tag is malformed.' });
   }
-  if (requestArg.greenfield !== true) {
-    blockers.push({ code: 'WOULD_REPLACE_EXISTING_STATE', message: 'Only greenfield deployment preflight is supported.' });
+  const mode = requestArg.mode === undefined && requestArg.greenfield === true
+    ? 'greenfield'
+    : requestArg.mode;
+  if (mode !== 'greenfield' && mode !== 'existing-service') {
+    blockers.push({ code: 'INVALID_REQUEST', message: 'A supported deployment mode is required.' });
+  }
+  if (requestArg.greenfield !== undefined
+    && (requestArg.greenfield !== true || mode !== 'greenfield')) {
+    blockers.push({ code: 'INVALID_REQUEST', message: 'Legacy greenfield mode is contradictory.' });
+  }
+  if (requestArg.phase !== undefined
+    && requestArg.phase !== 'reserve'
+    && requestArg.phase !== 'promote'
+    && requestArg.phase !== 'route') {
+    blockers.push({ code: 'INVALID_REQUEST', message: 'Deployment preflight phase is invalid.' });
+  }
+  if (requestArg.organizationId !== undefined
+    && (typeof requestArg.organizationId !== 'string'
+      || !/^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/.test(requestArg.organizationId))) {
+    blockers.push({ code: 'INVALID_REQUEST', message: 'Deployment organization identifier is malformed.' });
+  }
+  if (requestArg.operationId !== undefined
+    && (typeof requestArg.operationId !== 'string'
+      || !/^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/.test(requestArg.operationId))) {
+    blockers.push({ code: 'INVALID_REQUEST', message: 'Deployment operation identifier is malformed.' });
+  }
+  const routeHostnames = Array.isArray(requestArg.routes)
+    ? requestArg.routes.map((routeArg) => (
+      isRecord(routeArg) && typeof routeArg.hostname === 'string'
+        ? routeArg.hostname
+        : undefined
+    ))
+    : [];
+  if (requestArg.routes !== undefined && (
+    !Array.isArray(requestArg.routes)
+    || requestArg.routes.length > 32
+    || new Set(routeHostnames).size !== routeHostnames.length
+    || requestArg.routes.some((routeArg) => !isRecord(routeArg)
+      || typeof routeArg.hostname !== 'string'
+      || canonicalizeDeploymentHostname(routeArg.hostname) !== routeArg.hostname
+      || !Number.isSafeInteger(routeArg.targetPort)
+      || (typeof routeArg.targetPort === 'number'
+        && (routeArg.targetPort < 1 || routeArg.targetPort > 65535))
+      || !configurationContainerPorts.includes(routeArg.targetPort)
+      || (routeArg.verificationHostname !== undefined
+        && (typeof routeArg.verificationHostname !== 'string'
+          || canonicalizeDeploymentHostname(routeArg.verificationHostname)
+            !== routeArg.verificationHostname))
+      || getDeploymentRouteVerificationHostname(
+        routeArg as unknown as IDeploymentRouteRequest,
+      ) === undefined
+      || (routeArg.readinessPath !== undefined
+        && (typeof routeArg.readinessPath !== 'string'
+          || normalizeDeploymentReadinessPath(routeArg.readinessPath) !== routeArg.readinessPath))
+      || (routeArg.expectedStatusCodes !== undefined
+        && (!Array.isArray(routeArg.expectedStatusCodes)
+          || routeArg.expectedStatusCodes.length < 1
+          || routeArg.expectedStatusCodes.length > 16
+          || new Set(routeArg.expectedStatusCodes).size !== routeArg.expectedStatusCodes.length
+          || routeArg.expectedStatusCodes.some((statusArg) => (
+            !Number.isSafeInteger(statusArg) || statusArg < 200 || statusArg > 299
+          )))))
+  )) {
+    blockers.push({ code: 'INVALID_REQUEST', message: 'Deployment route declaration is malformed.' });
+  }
+  if (mode === 'greenfield' && Array.isArray(requestArg.routes)
+    && JSON.stringify([...new Set(requestArg.routes.map((routeArg) => (
+      isRecord(routeArg) && typeof routeArg.hostname === 'string' ? routeArg.hostname : ''
+    )))].sort())
+      !== JSON.stringify([...new Set(configurationPublicDomains)].sort())) {
+    blockers.push({
+      code: 'INVALID_REQUEST',
+      message: 'Greenfield routes must exactly match proposed public domains.',
+    });
   }
   return blockers;
 };

package/ts/data/immutableimage.ts

@@ -76,12 +76,114 @@ export interface IImageRelease {
     firstObservedAt: number;
     lastObservedAt: number;
     observationCount: number;
+    /** Cloudly-created evidence from an authenticated exact-tag registry PUT. */
+    trustedEvidence: IImageReleaseTrustedEvidence[];
     acceptedAt?: number;
     lastPromotedAt?: number;
     promotionCount?: number;
   };
 }
 
+export interface IImageReleaseTrustedEvidence {
+  source: 'cloudly-registry';
+  /** Deterministic ID for an authenticated registry acceptance event/retry. */
+  evidenceId: string;
+  operationId: string;
+  actorUserId: string;
+  registryHost: string;
+  repository: string;
+  tag: string;
+  registryRootDigest: TSha256Digest;
+  manifestMediaType: TOciManifestMediaType;
+  recordedAt: number;
+}
+
+export const selectTrustedImageReleaseEvidence = (argsArg: {
+  release: IImageRelease;
+  operationId: string;
+  actorUserId: string;
+  serviceId: string;
+  imageId: string;
+  registryHost: string;
+  repository: string;
+  tag: string;
+  digest: TSha256Digest;
+}): { evidence?: IImageReleaseTrustedEvidence; errors: string[] } => {
+  const evidenceFingerprint = (evidenceArg: IImageReleaseTrustedEvidence) => [
+    evidenceArg.source,
+    evidenceArg.evidenceId,
+    evidenceArg.operationId,
+    evidenceArg.actorUserId,
+    evidenceArg.registryHost,
+    evidenceArg.repository,
+    evidenceArg.tag,
+    evidenceArg.registryRootDigest,
+    evidenceArg.manifestMediaType,
+    evidenceArg.recordedAt,
+  ].join('\u0000');
+  const uniqueEvidence = new Map<string, IImageReleaseTrustedEvidence>();
+  const errors: string[] = [];
+  for (const evidence of argsArg.release.data.trustedEvidence || []) {
+    const existing = uniqueEvidence.get(evidence.evidenceId);
+    if (existing && evidenceFingerprint(existing) !== evidenceFingerprint(evidence)) {
+      errors.push('trusted release evidence identity is contradictory');
+    } else {
+      uniqueEvidence.set(evidence.evidenceId, evidence);
+    }
+  }
+  const evidenceMatches = [...uniqueEvidence.values()].filter((evidenceArg) => (
+    evidenceArg.source === 'cloudly-registry'
+    && evidenceArg.operationId === argsArg.operationId
+    && evidenceArg.actorUserId === argsArg.actorUserId
+    && evidenceArg.registryHost === argsArg.registryHost
+    && evidenceArg.repository === argsArg.repository
+    && evidenceArg.tag === argsArg.tag
+    && evidenceArg.registryRootDigest === argsArg.digest
+  ));
+  if (argsArg.release.data.serviceId !== argsArg.serviceId
+    || argsArg.release.data.imageId !== argsArg.imageId
+    || argsArg.release.data.registryHost !== argsArg.registryHost
+    || argsArg.release.data.repository !== argsArg.repository
+    || argsArg.release.data.registryRootDigest !== argsArg.digest) {
+    errors.push('release target or root digest does not match the deployment fence');
+  }
+  if (!argsArg.release.data.observedTags.includes(argsArg.tag)) {
+    errors.push('release has not observed the exact deployment tag');
+  }
+  if (evidenceMatches.length === 0) {
+    errors.push('trusted release evidence is missing');
+  } else if (evidenceMatches.length > 1) {
+    errors.push('trusted release evidence is ambiguous');
+  }
+  const evidence = evidenceMatches.length === 1 ? evidenceMatches[0] : undefined;
+  if (evidence && evidence.manifestMediaType !== argsArg.release.data.manifestMediaType) {
+    errors.push('trusted release and release root media types disagree');
+  }
+  if (![
+    'application/vnd.oci.image.index.v1+json',
+    'application/vnd.docker.distribution.manifest.list.v2+json',
+  ].includes(argsArg.release.data.manifestMediaType)
+    || (evidence && ![
+      'application/vnd.oci.image.index.v1+json',
+      'application/vnd.docker.distribution.manifest.list.v2+json',
+    ].includes(evidence.manifestMediaType))) {
+    errors.push('trusted release evidence must identify an OCI image index');
+  }
+  return { evidence, errors };
+};
+
+const immutableReleaseTagRegex = /^[A-Za-z0-9_][A-Za-z0-9._-]{0,127}$/;
+
+export const normalizeImmutableReleaseTag = (tagArg: unknown): string | undefined => {
+  if (typeof tagArg !== 'string'
+    || tagArg.trim() !== tagArg
+    || !immutableReleaseTagRegex.test(tagArg)
+    || tagArg.toLowerCase() === 'latest') {
+    return undefined;
+  }
+  return tagArg;
+};
+
 export interface IImmutableImageTargetScope {
   targetClusterIds: string[];
   targetNodeNames: string[];
@@ -95,6 +197,8 @@ export interface IImmutableImageDeploymentPlan {
   rolloutId: string;
   rolloutGeneration: number;
   releaseId: string;
+  operationId: string;
+  releaseTag: string;
   registryHost: string;
   repository: string;
   requestedDigest: TSha256Digest;
@@ -116,6 +220,8 @@ interface IRuntimeImageEvidenceBase {
   taskReportedDigest?: TSha256Digest;
   containerImageId?: string;
   containerConfigImageReference?: string;
+  /** Digest observed from local Docker image state without implying rollout verification. */
+  observedDigest?: TSha256Digest;
   resolvedDigest?: TSha256Digest;
   platformManifestDigest?: TSha256Digest;
   repoDigests?: string[];
@@ -199,7 +305,8 @@ export interface IImageRolloutStatus {
 
 const sha256DigestRegex = /^sha256:[a-f0-9]{64}$/;
 
-export const normalizeSha256Digest = (digest: string): TSha256Digest | undefined => {
+export const normalizeSha256Digest = (digest: unknown): TSha256Digest | undefined => {
+  if (typeof digest !== 'string') return undefined;
   const normalizedDigest = digest.trim().toLowerCase();
   return sha256DigestRegex.test(normalizedDigest)
     ? (normalizedDigest as TSha256Digest)
@@ -246,6 +353,18 @@ export const validateImmutableImageDeploymentPlan = (
   if (!Number.isSafeInteger(planArg.createdAt) || planArg.createdAt < 1) {
     errors.push('createdAt must be a positive safe integer');
   }
+  if (!planArg.operationId || planArg.operationId.length > 200) {
+    errors.push('operationId must be a bounded non-empty identifier');
+  }
+  if (!normalizeImmutableReleaseTag(planArg.releaseTag)) {
+    errors.push('releaseTag must be a non-latest canonical OCI tag');
+  }
+  if (![
+    'application/vnd.oci.image.index.v1+json',
+    'application/vnd.docker.distribution.manifest.list.v2+json',
+  ].includes(planArg.manifestMediaType)) {
+    errors.push('immutable rollout root must be an OCI image index');
+  }
   let expectedReference: string | undefined;
   try {
     expectedReference = buildDigestPinnedImageReference(

package/ts/data/index.ts

@@ -2,6 +2,7 @@ export * from './cloudlyconfig.js';
 export * from './cluster.js';
 export * from './config.js';
 export * from './deployment.js';
+export * from './deploymentoperation.js';
 export * from './deploymentpreflight.js';
 export * from './migration.js';
 export * from './dns.js';

package/ts/data/service.ts

@@ -68,6 +68,8 @@ export interface IServiceReconciliationStatus {
 export interface IService {
   id: string;
   data: {
+    /** Server-managed deployment ownership boundary. */
+    organizationId?: string;
     name: string;
     description: string;
     imageId: string;
@@ -165,5 +167,5 @@ export interface IService {
 /** Caller-writable service data. Immutable policy and rollout fields are server-managed. */
 export type TServiceWritableData = Omit<
   IService['data'],
-  'immutableImageRequired' | 'imageDeployment' | 'imageRolloutStatus'
+  'organizationId' | 'immutableImageRequired' | 'imageDeployment' | 'imageRolloutStatus'
 >;

package/ts/data/user.ts

@@ -6,20 +6,103 @@ export interface IToken {
 
 export type TServiceDeploymentCapability =
   | 'deployment:preflight'
+  | 'deployment:reserve'
+  | 'deployment:registry-push'
+  | 'deployment:release-read'
+  | 'deployment:promote-image'
+  | 'deployment:status'
   | 'deployment:create-greenfield'
   | 'deployment:promote-route'
-  | 'deployment:rollback-route';
+  | 'deployment:rollback-image'
+  | 'deployment:rollback-route'
+  | 'deployment:retry'
+  | 'deployment:cleanup';
 
 /**
  * Server-persisted authority for one logical service. These grants are never
  * accepted from the identity payload supplied by a caller; Cloudly reloads
  * the owning user from the verified JWT before evaluating them.
  */
-export interface IServiceDeploymentGrant {
+interface IServiceDeploymentGrantBase {
+  organizationId: string;
   serviceId: string;
   capabilities: TServiceDeploymentCapability[];
 }
 
+/** Authority over one service that already exists and has the same owner. */
+export interface IExistingServiceDeploymentGrant extends IServiceDeploymentGrantBase {
+  scope: 'service';
+}
+
+/** Authority to create one exact, not-yet-existing service ID in an organization. */
+export interface IOrganizationServiceSlotDeploymentGrant extends IServiceDeploymentGrantBase {
+  scope: 'organization-service-slot';
+}
+
+export type IServiceDeploymentGrant =
+  | IExistingServiceDeploymentGrant
+  | IOrganizationServiceSlotDeploymentGrant;
+
+const serviceDeploymentCapabilities = new Set<TServiceDeploymentCapability>([
+  'deployment:preflight',
+  'deployment:reserve',
+  'deployment:registry-push',
+  'deployment:release-read',
+  'deployment:promote-image',
+  'deployment:status',
+  'deployment:create-greenfield',
+  'deployment:promote-route',
+  'deployment:rollback-image',
+  'deployment:rollback-route',
+  'deployment:retry',
+  'deployment:cleanup',
+]);
+
+const deploymentBoundaryIdentifierRegex = /^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/;
+
+export const validateServiceDeploymentGrant = (
+  grantArg: unknown,
+): string[] => {
+  const errors: string[] = [];
+  if (!grantArg || typeof grantArg !== 'object' || Array.isArray(grantArg)) {
+    return ['grant must be an object'];
+  }
+  const grant = grantArg as Record<string, unknown>;
+  if (grant.scope !== 'service' && grant.scope !== 'organization-service-slot') {
+    errors.push('scope must identify an existing service or an exact future service slot');
+  }
+  if (typeof grant.organizationId !== 'string'
+    || !deploymentBoundaryIdentifierRegex.test(grant.organizationId)) {
+    errors.push('organizationId must be a bounded canonical identifier');
+  }
+  if (typeof grant.serviceId !== 'string'
+    || !deploymentBoundaryIdentifierRegex.test(grant.serviceId)) {
+    errors.push('serviceId must be a bounded canonical identifier');
+  }
+  const capabilities = Array.isArray(grant.capabilities)
+    ? grant.capabilities
+    : undefined;
+  if (!capabilities
+    || capabilities.length < 1
+    || capabilities.length > serviceDeploymentCapabilities.size
+    || new Set(capabilities).size !== capabilities.length
+    || capabilities.some((capabilityArg) => (
+      typeof capabilityArg !== 'string'
+      || !serviceDeploymentCapabilities.has(capabilityArg as TServiceDeploymentCapability)
+    ))) {
+    errors.push('capabilities must be a non-empty unique set of supported deployment capabilities');
+  }
+  if (capabilities && grant.scope === 'service'
+    && capabilities.includes('deployment:create-greenfield')) {
+    errors.push('an existing-service grant cannot authorize greenfield creation');
+  }
+  if (capabilities && grant.scope === 'organization-service-slot'
+    && !capabilities.includes('deployment:create-greenfield')) {
+    errors.push('an organization-service-slot grant must authorize greenfield creation');
+  }
+  return errors;
+};
+
 export interface IIdentityCredential {
   jwt: string;
 }

package/ts/requests/admin.ts

@@ -1,5 +1,5 @@
 import * as plugins from '../plugins.js';
-import type { IIdentity, TServiceDeploymentCapability } from '../data/user.js';
+import type { IIdentity, IIdentityCredential, IServiceDeploymentGrant } from '../data/user.js';
 
 export interface IReq_Admin_LoginWithUsernameAndPassword extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
@@ -22,15 +22,13 @@ extends plugins.typedrequestInterfaces.implementsTR<
 > {
   method: 'configureServiceDeploymentMachineUser';
   request: {
-    identity: IIdentity;
+    identity: IIdentityCredential;
     userId: string;
-    serviceId: string;
-    capabilities: TServiceDeploymentCapability[];
+    grant: IServiceDeploymentGrant;
   };
   response: {
     userId: string;
-    serviceId: string;
-    capabilities: TServiceDeploymentCapability[];
+    grant: IServiceDeploymentGrant;
     tokenRolesNormalized: true;
   };
 }