@serve.zone/interfaces 32.32.0 → 32.34.0

package/ts/data/corestorelegacyadoption.ts

@@ -29,6 +29,12 @@ import { isClusterNodeId } from '../private/nodeidentifier.js';
  *    answers the plan (`ICorestoreLegacyResourceAdoptionPlanEntry[]`).
  * 3. The operator stops Corestore and runs its `legacy-resource-adoption` migration with that plan.
  *    Until then Corestore refuses the binding, which reports `legacy-adoption-pending`.
+ *
+ * A resource is adopted by a binding of the service that owns it, or, when the selection names a
+ * `successorServiceId`, by a binding of that successor: a fresh service of the same organization
+ * that replaces the legacy one and takes over its data. The successor's binding records the legacy
+ * owner as `corestoreLegacyAdoption.legacyServiceId`, and the plan entry carries the successor, so
+ * Corestore moves the resource from the legacy owner's manifest entry to the successor's binding.
  */
 
 export type TCorestoreLegacyCapability = 'database' | 'objectstorage';
@@ -100,21 +106,30 @@ export type TClusterCorestoreLegacyResourceInventory =
       errorCode: 'CORESTORE_ENDPOINT_UNKNOWN' | 'CORESTORE_UNREACHABLE';
     };
 
-/** One resource an administrator selects for adoption. */
+/**
+ * One resource an administrator selects for adoption: the legacy resource `serviceId` owns of
+ * `capability`. Without `successorServiceId` a binding of `serviceId` adopts it; with it, a binding of
+ * that other service does, which must be a greenfield service of the same organization.
+ */
 export interface ICorestoreLegacyResourceSelection {
   serviceId: string;
   capability: TCorestoreLegacyCapability;
+  /** The service whose binding adopts the resource, when it is not `serviceId`; never `serviceId`. */
+  successorServiceId?: string;
 }
 
 /**
  * One entry of Corestore's offline adoption plan, exactly the object its
- * `legacy-resource-adoption` migration reads: the service, the capability and the binding that may
- * adopt its legacy resource. The legacy identity is Corestore's own and is not restated here.
+ * `legacy-resource-adoption` migration reads: the service that owns the legacy resource, the
+ * capability, the binding that may adopt it and, when that binding belongs to another service, that
+ * successor service. The legacy identity is Corestore's own and is not restated here.
  */
 export interface ICorestoreLegacyResourceAdoptionPlanEntry {
   serviceId: string;
   capability: TCorestoreLegacyCapability;
   bindingId: string;
+  /** The service `bindingId` belongs to, when it is not `serviceId`; never `serviceId`. */
+  successorServiceId?: string;
 }
 
 /**
@@ -126,9 +141,17 @@ export interface ICorestoreLegacyResourceAdoptionPlanEntry {
  * - `legacy-resource-blocked`: a selected resource is unadopted with a blocker;
  * - `legacy-resource-authorized-elsewhere`: a selected resource is authorized for a binding Cloudly
  *   does not hold as that resource's adoption;
- * - `service-absent`: Cloudly has no such service;
- * - `binding-exists`: the service already has a binding of that capability that adopts nothing,
- *   or adopts another resource.
+ * - `legacy-resource-adopted-elsewhere`: Cloudly already holds a binding of another service as a
+ *   selected resource's adoption;
+ * - `service-absent`: Cloudly has no such service, legacy owner or successor;
+ * - `binding-exists`: the adopting service already has a binding of that capability that adopts
+ *   nothing, or adopts another resource;
+ * - `successor-organization-mismatch`: the successor belongs to another organization than the
+ *   legacy owner, or either names none;
+ * - `successor-not-greenfield`: the successor is not an immutable-deployment service (it deploys on
+ *   push, or does not require an immutable image);
+ * - `successor-owns-legacy-resource`: the successor owns a legacy resource of that capability
+ *   itself, which Corestore would keep beside the adopted one.
  */
 export type TCorestoreLegacyAdoptionRefusal =
   | 'legacy-inventory-unreachable'
@@ -136,8 +159,12 @@ export type TCorestoreLegacyAdoptionRefusal =
   | 'legacy-resource-absent'
   | 'legacy-resource-blocked'
   | 'legacy-resource-authorized-elsewhere'
+  | 'legacy-resource-adopted-elsewhere'
   | 'service-absent'
-  | 'binding-exists';
+  | 'binding-exists'
+  | 'successor-organization-mismatch'
+  | 'successor-not-greenfield'
+  | 'successor-owns-legacy-resource';
 
 /** The named refusal of `adoptCorestoreLegacyResources`, sent as `TypedResponseError.errorData`. */
 export interface ICorestoreLegacyAdoptionErrorData {
@@ -327,7 +354,29 @@ export const computeClusterCorestoreLegacyResourceInventorySha256 = async (
 const selectionKey = (entryArg: { serviceId: string; capability: string }): string =>
   `${entryArg.serviceId}\u0000${entryArg.capability}`;
 
-/** Validates an administrator's selection: 1..4096 exact entries, sorted by service then capability. */
+/** The service capability whose binding adopts the entry's resource: the successor's, or the owner's. */
+const adoptingKey = (entryArg: { serviceId: string; capability: string; successorServiceId?: string }): string =>
+  selectionKey({ serviceId: entryArg.successorServiceId ?? entryArg.serviceId, capability: entryArg.capability });
+
+/**
+ * Whether an entry has exactly `baseKeysArg`, and `successorServiceId` at most: `shape` when not,
+ * `successor` when its successor is not a canonical identifier other than its `serviceId`.
+ */
+const successorShape = (
+  entryArg: Record<string, unknown>,
+  baseKeysArg: readonly string[],
+): 'exact' | 'shape' | 'successor' => {
+  if (!hasExactKeys(entryArg, baseKeysArg, ['successorServiceId'])) return 'shape';
+  return !Object.keys(entryArg).includes('successorServiceId')
+    || (isIdentifier(entryArg.successorServiceId) && entryArg.successorServiceId !== entryArg.serviceId)
+    ? 'exact'
+    : 'successor';
+};
+
+/**
+ * Validates an administrator's selection: 1..4096 exact entries, sorted by service then capability,
+ * and no service capability adopting twice, whether as legacy owner or as successor.
+ */
 export const validateCorestoreLegacyResourceSelections = (
   valueArg: unknown,
   pathArg = 'corestore legacy resource selection',
@@ -338,24 +387,36 @@ export const validateCorestoreLegacyResourceSelections = (
   }
   const errors: string[] = [];
   let previous: string | undefined;
+  const adopting = new Set<string>();
   for (const [index, entry] of valueArg.entries()) {
-    if (!isPlainRecord(entry) || !hasExactKeys(entry, ['serviceId', 'capability'])
-      || !isIdentifier(entry.serviceId) || !isCapability(entry.capability)) {
+    const shape = isPlainRecord(entry) ? successorShape(entry, ['serviceId', 'capability']) : 'shape';
+    if (shape === 'shape' || !isIdentifier((entry as Record<string, unknown>).serviceId)
+      || !isCapability((entry as Record<string, unknown>).capability)) {
       errors.push(`${pathArg}[${index}] must be an exact { serviceId, capability }`);
       continue;
     }
-    const key = selectionKey(entry as unknown as ICorestoreLegacyResourceSelection);
+    if (shape === 'successor') {
+      errors.push(`${pathArg}[${index}] successorServiceId must name another service`);
+      continue;
+    }
+    const selection = entry as ICorestoreLegacyResourceSelection;
+    const key = selectionKey(selection);
     if (previous !== undefined && compareWireTokens(previous, key) >= 0) {
       errors.push(`${pathArg} must be sorted by serviceId then capability without repeats`);
     }
     previous = key;
+    if (adopting.has(adoptingKey(selection))) {
+      errors.push(`${pathArg}[${index}] adopts into a service capability another entry adopts into`);
+    }
+    adopting.add(adoptingKey(selection));
   }
   return errors;
 };
 
 /**
  * Validates an adoption plan by the rules Corestore's migration applies: a non-empty array of at
- * most 4096 exact `{ serviceId, capability, bindingId }` entries, canonical identifiers, and no
+ * most 4096 exact `{ serviceId, capability, bindingId }` entries, each with `successorServiceId`
+ * when it names another service, canonical identifiers, and no legacy service capability, adopting
  * service capability or binding id twice. Order is free.
  */
 export const validateCorestoreLegacyResourceAdoptionPlan = (
@@ -368,19 +429,30 @@ export const validateCorestoreLegacyResourceAdoptionPlan = (
   }
   const errors: string[] = [];
   const serviceCapabilities = new Set<string>();
+  const adoptingCapabilities = new Set<string>();
   const bindingIds = new Set<string>();
   for (const [index, entry] of valueArg.entries()) {
-    if (!isPlainRecord(entry) || !hasExactKeys(entry, ['serviceId', 'capability', 'bindingId'])
-      || !isIdentifier(entry.serviceId) || !isIdentifier(entry.bindingId) || !isCapability(entry.capability)) {
+    const shape = isPlainRecord(entry) ? successorShape(entry, ['serviceId', 'capability', 'bindingId']) : 'shape';
+    const record = entry as Record<string, unknown>;
+    if (shape === 'shape' || !isIdentifier(record.serviceId) || !isIdentifier(record.bindingId)
+      || !isCapability(record.capability)) {
       errors.push(`${pathArg} entry ${index} must be an exact { serviceId, capability, bindingId }`);
       continue;
     }
-    const serviceCapability = selectionKey(entry as unknown as ICorestoreLegacyResourceSelection);
-    if (serviceCapabilities.has(serviceCapability) || bindingIds.has(entry.bindingId as string)) {
+    if (shape === 'successor') {
+      errors.push(`${pathArg} entry ${index} successorServiceId must name another service`);
+      continue;
+    }
+    const planEntry = entry as ICorestoreLegacyResourceAdoptionPlanEntry;
+    const serviceCapability = selectionKey(planEntry);
+    const adoptingCapability = adoptingKey(planEntry);
+    if (serviceCapabilities.has(serviceCapability) || adoptingCapabilities.has(adoptingCapability)
+      || bindingIds.has(planEntry.bindingId)) {
       errors.push(`${pathArg} entry ${index} repeats a service capability or binding id`);
     }
     serviceCapabilities.add(serviceCapability);
-    bindingIds.add(entry.bindingId as string);
+    adoptingCapabilities.add(adoptingCapability);
+    bindingIds.add(planEntry.bindingId);
   }
   return errors;
 };
@@ -392,16 +464,27 @@ export interface ICorestoreLegacyAdoptionBindingView {
   capability: string;
   objectstorageBucketName?: string;
   objectstorageRetention?: { intent: IObjectStorageRetentionIntent };
-  corestoreLegacyAdoption?: { nodeId: string; resourceName: string; inventorySha256: string };
+  corestoreLegacyAdoption?: {
+    nodeId: string;
+    resourceName: string;
+    inventorySha256: string;
+    legacyServiceId?: string;
+  };
 }
 
+/** The service that owns the legacy resource a binding adopts: its `legacyServiceId`, else its own. */
+const legacyOwnerOf = (bindingArg: ICorestoreLegacyAdoptionBindingView): string =>
+  bindingArg.corestoreLegacyAdoption?.legacyServiceId ?? bindingArg.serviceId;
+
 /**
  * Content check of one adopting binding against the inventory it was adopted at, and the one rule
  * that lets a binding carry a legacy bucket name: the binding names this node, this inventory
- * digest and the legacy resource's name; the resource is unadopted without a blocker or authorized
- * for exactly this binding; an adopted bucket's `objectstorageBucketName` is the legacy bucket and
- * its retention intent the legacy intent exactly, absent when the legacy bucket has none; a
- * database binding carries neither. Whether the digest is current is the caller's to check.
+ * digest and the legacy resource's name; the resource belongs to `legacyServiceId` when the binding
+ * names one, and then its own service owns no legacy resource of the capability, otherwise to its
+ * own service; the resource is unadopted without a blocker or authorized for exactly this binding;
+ * an adopted bucket's `objectstorageBucketName` is the legacy bucket and its retention intent the
+ * legacy intent exactly, absent when the legacy bucket has none; a database binding carries
+ * neither. Whether the digest is current is the caller's to check.
  */
 export const validatePlatformBindingCorestoreLegacyAdoption = (
   bindingArg: ICorestoreLegacyAdoptionBindingView,
@@ -414,16 +497,27 @@ export const validatePlatformBindingCorestoreLegacyAdoption = (
     return [`${pathArg} needs a valid reachable inventory and its digest`];
   }
   const adoption = bindingArg.corestoreLegacyAdoption;
-  if (!isPlainRecord(adoption) || !hasExactKeys(adoption, ['nodeId', 'resourceName', 'inventorySha256'])) {
+  if (!isPlainRecord(adoption)
+    || !hasExactKeys(adoption, ['nodeId', 'resourceName', 'inventorySha256'], ['legacyServiceId'])) {
     return [`${pathArg} must use its exact schema`];
   }
+  if (Object.keys(adoption).includes('legacyServiceId')
+    && (!isIdentifier(adoption.legacyServiceId) || adoption.legacyServiceId === bindingArg.serviceId)) {
+    return [`${pathArg} legacyServiceId must name another service than the binding's`];
+  }
   if (adoption.nodeId !== inventoryArg.nodeId || adoption.inventorySha256 !== inventorySha256Arg) {
     return [`${pathArg} must name the inventory's node and digest`];
   }
   if (!isCapability(bindingArg.capability)) return [`${pathArg} needs a database or objectstorage binding`];
-  const resource = inventoryArg.services.find((serviceArg) => serviceArg.serviceId === bindingArg.serviceId)
+  const resourceOf = (serviceIdArg: string) => inventoryArg.services
+    .find((serviceArg) => serviceArg.serviceId === serviceIdArg)
     ?.resources.find((resourceArg) => resourceArg.capability === bindingArg.capability);
+  const legacyOwner = legacyOwnerOf(bindingArg);
+  const resource = resourceOf(legacyOwner);
   if (!resource) return [`${pathArg} names no legacy resource of the service and capability`];
+  if (legacyOwner !== bindingArg.serviceId && resourceOf(bindingArg.serviceId)) {
+    return [`${pathArg} names a successor that owns a legacy resource of the capability itself`];
+  }
   const errors: string[] = [];
   const legacyName = resource.capability === 'database' ? resource.databaseName : resource.bucketName;
   if (adoption.resourceName !== legacyName) errors.push(`${pathArg} resourceName must be the legacy resource's name`);
@@ -447,18 +541,27 @@ export const validatePlatformBindingCorestoreLegacyAdoption = (
 };
 
 /**
- * The plan for every adopting binding, sorted by service then capability, in the exact entry shape
- * Corestore's migration reads. Throws unless every binding adopts a legacy resource and the result
- * is a valid plan.
+ * The plan for every adopting binding, sorted by legacy service then capability, in the exact entry
+ * shape Corestore's migration reads: a binding adopting another service's resource names that
+ * service as `serviceId` and its own as `successorServiceId`. Throws unless every binding adopts a
+ * legacy resource and the result is a valid plan.
  */
 export const createCorestoreLegacyResourceAdoptionPlan = (
   bindingsArg: readonly ICorestoreLegacyAdoptionBindingView[],
 ): ICorestoreLegacyResourceAdoptionPlanEntry[] => {
-  const plan = bindingsArg.map((bindingArg) => {
+  const plan = bindingsArg.map((bindingArg): ICorestoreLegacyResourceAdoptionPlanEntry => {
     if (bindingArg.corestoreLegacyAdoption === undefined || !isCapability(bindingArg.capability)) {
       throw new Error(`binding ${bindingArg.id} adopts no legacy Corestore resource`);
     }
-    return { serviceId: bindingArg.serviceId, capability: bindingArg.capability, bindingId: bindingArg.id };
+    const legacyServiceId = bindingArg.corestoreLegacyAdoption.legacyServiceId;
+    return legacyServiceId === undefined
+      ? { serviceId: bindingArg.serviceId, capability: bindingArg.capability, bindingId: bindingArg.id }
+      : {
+          serviceId: legacyServiceId,
+          capability: bindingArg.capability,
+          bindingId: bindingArg.id,
+          successorServiceId: bindingArg.serviceId,
+        };
   }).sort((leftArg, rightArg) => compareWireTokens(selectionKey(leftArg), selectionKey(rightArg)));
   const errors = validateCorestoreLegacyResourceAdoptionPlan(plan);
   if (errors.length > 0) throw new Error(errors[0]);

package/ts/data/deploymentmachineuser.ts

@@ -0,0 +1,174 @@
+import { readDataElements, readDataProperty, readExactDataRecord } from '../private/dataproperties.js';
+import { validateServiceDeploymentGrant, type IServiceDeploymentGrant } from './user.js';
+
+/**
+ * A deployment machine user is the identity a deployer such as `@git.zone/tsdeploy` authenticates
+ * as: an API machine user that carries a bearer token and the deployment grants an administrator
+ * attaches with `configureServiceDeploymentMachineUser`. An administrator creates one, rotates or
+ * revokes its token, and lists them; nothing else mints one.
+ */
+export const deploymentMachineUserContract = Object.freeze({
+  /** A token lives at most one year from the mutation that issued it, like every machine token. */
+  maximumTokenLifetimeMs: 365 * 24 * 60 * 60 * 1000,
+  /**
+   * The longest username a created user may take. The username is also the registry login name
+   * a deployer states, so it stays short, lowercase and free of `:` and `/`.
+   */
+  maximumCreatedUsernameLength: 64,
+  /** The longest stored username a listing reports, the bound Cloudly has always stored. */
+  maximumUsernameLength: 200,
+  /** Grants one user carries at most. */
+  maximumGrants: 64,
+  /** Tokens one listed user reports at most. */
+  maximumTokens: 64,
+});
+
+/** One token of a deployment machine user, without its value. */
+export interface IDeploymentMachineTokenMetadata {
+  expiresAt: number;
+}
+
+/** Value-free metadata of one deployment machine user. No token value is ever part of it. */
+export interface IDeploymentMachineUserMetadata {
+  userId: string;
+  username: string;
+  /** Ascending by expiry; empty after `revoke-token`. */
+  tokens: IDeploymentMachineTokenMetadata[];
+  /** Sorted by `organizationId:serviceId`, as Cloudly stores them. */
+  grants: IServiceDeploymentGrant[];
+}
+
+interface IDeploymentMachineUserMutationBase {
+  /** Retain the complete mutation and this ID across retries. */
+  mutationId: string;
+}
+
+/**
+ * `create` makes a new user with one token; the username must not be taken by any user.
+ * `rotate-token` replaces every token of the user with one new token. `revoke-token` removes every
+ * token, which ends the user's authentication while keeping its grants for a later rotation.
+ */
+export type TDeploymentMachineUserMutation = IDeploymentMachineUserMutationBase & (
+  | { operation: 'create'; username: string; expiresAt: number }
+  | { operation: 'rotate-token'; userId: string; expiresAt: number }
+  | { operation: 'revoke-token'; userId: string }
+);
+
+export interface IDeploymentMachineUserMutationResult {
+  /** Historical on replay; read `getDeploymentMachineUsers` for current state. */
+  user: IDeploymentMachineUserMetadata;
+  /**
+   * The new token, answered exactly once: on the first answer to `create` or `rotate-token`.
+   * `revoke-token` and every replay answer `null`; a lost token is replaced by a rotation.
+   */
+  token: string | null;
+  replayed: boolean;
+}
+
+/**
+ * Every refusal the deployment machine user requests name, as `IDeploymentMachineUserErrorData`.
+ *
+ * - `ADMIN_AUTHORIZATION_REQUIRED`: the caller is not an administrator.
+ * - `DEPLOYMENT_MACHINE_USER_REQUEST_INVALID`: the request does not satisfy this contract.
+ * - `DEPLOYMENT_MACHINE_USERNAME_TAKEN`: another user already has the username.
+ * - `DEPLOYMENT_MACHINE_USER_INVALID`: the user is not a deployment machine user (it does not
+ *   exist, or it is a human, cluster, administrator or service workload identity).
+ * - `DEPLOYMENT_MACHINE_TOKEN_EXPIRY_INVALID`: the expiry is not in the future, or is more than
+ *   `maximumTokenLifetimeMs` away (`isDeploymentMachineTokenExpiryAdmissible`).
+ * - `DEPLOYMENT_MACHINE_USER_MUTATION_CONFLICT`: the mutation ID was used for a different mutation
+ *   or by a different administrator.
+ */
+export const deploymentMachineUserRefusals = [
+  'ADMIN_AUTHORIZATION_REQUIRED',
+  'DEPLOYMENT_MACHINE_USER_REQUEST_INVALID',
+  'DEPLOYMENT_MACHINE_USERNAME_TAKEN',
+  'DEPLOYMENT_MACHINE_USER_INVALID',
+  'DEPLOYMENT_MACHINE_TOKEN_EXPIRY_INVALID',
+  'DEPLOYMENT_MACHINE_USER_MUTATION_CONFLICT',
+] as const;
+
+export type TDeploymentMachineUserRefusal = typeof deploymentMachineUserRefusals[number];
+
+export interface IDeploymentMachineUserErrorData {
+  code: TDeploymentMachineUserRefusal;
+  retryable: false;
+}
+
+const fail = (): never => { throw new Error('Deployment machine user contract rejected.'); };
+function requireValue(value: unknown): asserts value { if (!value) fail(); }
+const safe = <T>(operation: () => T): T => { try { return operation(); } catch { return fail(); } };
+/** Exactly this shape's keys, read once as data; an accessor is refused, never invoked. */
+const object = (value: unknown, keys: readonly string[]): Record<string, unknown> => {
+  const copy = readExactDataRecord(value, keys);
+  requireValue(copy !== null);
+  return copy;
+};
+const identifier = (value: unknown): string => {
+  requireValue(typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/.test(value));
+  return value;
+};
+const timestamp = (value: unknown): number => {
+  requireValue(typeof value === 'number' && Number.isSafeInteger(value) && value > 0);
+  return value;
+};
+const createdUsernamePattern = /^[a-z0-9](?:[a-z0-9._-]{0,62}[a-z0-9])?$/;
+
+/** Whether a username may be given to a new deployment machine user. */
+export const isDeploymentMachineUsername = (value: unknown): value is string => (
+  typeof value === 'string' && createdUsernamePattern.test(value)
+);
+
+/** Whether a token expiry is in the future and at most `maximumTokenLifetimeMs` after `now`. */
+export const isDeploymentMachineTokenExpiryAdmissible = (expiresAt: number, now: number): boolean => (
+  Number.isSafeInteger(expiresAt) && Number.isSafeInteger(now) && expiresAt > now
+  && expiresAt <= now + deploymentMachineUserContract.maximumTokenLifetimeMs
+);
+
+/** Structural copy only; the backend authorizes the administrator and the target user. */
+export const snapshotDeploymentMachineUserMutation = (value: unknown): TDeploymentMachineUserMutation => safe(() => {
+  const operation = readDataProperty(value, 'operation')?.value;
+  requireValue(operation === 'create' || operation === 'rotate-token' || operation === 'revoke-token');
+  if (operation === 'create') {
+    const request = object(value, ['mutationId', 'operation', 'username', 'expiresAt']);
+    requireValue(isDeploymentMachineUsername(request.username));
+    return { mutationId: identifier(request.mutationId), operation, username: request.username,
+      expiresAt: timestamp(request.expiresAt) };
+  }
+  if (operation === 'rotate-token') {
+    const request = object(value, ['mutationId', 'operation', 'userId', 'expiresAt']);
+    return { mutationId: identifier(request.mutationId), operation, userId: identifier(request.userId),
+      expiresAt: timestamp(request.expiresAt) };
+  }
+  const request = object(value, ['mutationId', 'operation', 'userId']);
+  return { mutationId: identifier(request.mutationId), operation, userId: identifier(request.userId) };
+});
+
+/** Structural copy of listed metadata: a stored username, tokens by expiry, valid sorted grants. */
+export const snapshotDeploymentMachineUserMetadata = (value: unknown): IDeploymentMachineUserMetadata => safe(() => {
+  const metadata = object(value, ['userId', 'username', 'tokens', 'grants']);
+  requireValue(typeof metadata.username === 'string' && metadata.username.length > 0
+    && metadata.username.length <= deploymentMachineUserContract.maximumUsernameLength
+    && metadata.username.trim() === metadata.username && !/[\u0000-\u001f\u007f]/.test(metadata.username));
+  const tokenEntries = readDataElements(metadata.tokens, deploymentMachineUserContract.maximumTokens);
+  requireValue(tokenEntries !== null);
+  const tokens = tokenEntries.map((entry) => ({ expiresAt: timestamp(object(entry, ['expiresAt']).expiresAt) }));
+  for (let index = 1; index < tokens.length; index++) {
+    requireValue(tokens[index - 1].expiresAt <= tokens[index].expiresAt);
+  }
+  const grantEntries = readDataElements(metadata.grants, deploymentMachineUserContract.maximumGrants);
+  requireValue(grantEntries !== null);
+  const grants = grantEntries.map((entry) => {
+    const grant = object(entry, ['scope', 'organizationId', 'serviceId', 'capabilities']);
+    const capabilities = readDataElements(grant.capabilities, 64);
+    requireValue(capabilities !== null);
+    const copy = { scope: grant.scope, organizationId: grant.organizationId, serviceId: grant.serviceId,
+      capabilities: [...capabilities] };
+    requireValue(validateServiceDeploymentGrant(copy).length === 0);
+    return copy as IServiceDeploymentGrant;
+  });
+  const grantKeys = grants.map((grant) => `${grant.organizationId}:${grant.serviceId}`);
+  for (let index = 1; index < grantKeys.length; index++) {
+    requireValue(grantKeys[index - 1].localeCompare(grantKeys[index]) < 0);
+  }
+  return { userId: identifier(metadata.userId), username: metadata.username, tokens, grants };
+});

package/ts/data/deploymentpreflight.ts

@@ -29,6 +29,12 @@ export type TDeploymentPreflightDecision = 'GO' | 'NO-GO';
 export const deploymentPreflightBlockerCodes = [
   'INVALID_REQUEST',
   'AUTHORIZATION_MISSING',
+  /**
+   * A reservation is made by a deployment machine user (an API machine user with a deployment
+   * grant) and never by an administrator, whose registry push is not bound to any operation; the
+   * reserve request refuses such an actor with the same code.
+   */
+  'DEPLOYMENT_MACHINE_IDENTITY_REQUIRED',
   'ORGANIZATION_SCOPE_MISSING',
   'SERVICE_OWNERSHIP_MISMATCH',
   'DEPLOYMENT_OPERATION_NOT_FOUND',

package/ts/data/index.ts

@@ -12,6 +12,7 @@ export * from './coremail.js';
 export * from './coremail.runtime.js';
 export * from './deployment.js';
 export * from './deploymentadoption.js';
+export * from './deploymentmachineuser.js';
 export * from './deploymentoperation.js';
 export * from './deploymentpreflight.js';
 export * from './migration.js';

package/ts/platform/types.ts

@@ -116,14 +116,18 @@ export interface IPlatformServiceEndpoint {
  * the binding, and Cloudly refuses it (and `objectstorageBucketName`) on `upsertPlatformBinding`.
  * `nodeId` is the node whose Corestore holds the resource, so the binding is placed there and
  * nowhere else; `resourceName` is the legacy database or bucket name; `inventorySha256` is the
- * legacy inventory the adoption was checked against. An adopted bucket's
- * `objectstorageBucketName` is the legacy bucket and its `objectstorageRetention.intent` the legacy
- * intent exactly, or absent when the legacy bucket has none.
+ * legacy inventory the adoption was checked against; `legacyServiceId` is the service that owned the
+ * legacy resource when that is not the binding's own service (a successor adopting its
+ * predecessor's data), absent otherwise. An adopted bucket's `objectstorageBucketName` is the legacy
+ * bucket and its `objectstorageRetention.intent` the legacy intent exactly, or absent when the
+ * legacy bucket has none.
  */
 export interface IPlatformBindingCorestoreLegacyAdoption {
   nodeId: string;
   resourceName: string;
   inventorySha256: string;
+  /** The legacy resource's owner, when it is another service than the binding's; never its own. */
+  legacyServiceId?: string;
 }
 
 export interface IPlatformBinding {

package/ts/requests/admin.ts

@@ -4,6 +4,10 @@ import type {
   IServiceMachineCredentialMetadata, IServiceMachineCredentialMutationResult,
   TServiceMachineCredentialMutation,
 } from '../data/servicecredential.js';
+import type {
+  IDeploymentMachineUserMetadata, IDeploymentMachineUserMutationResult,
+  TDeploymentMachineUserMutation,
+} from '../data/deploymentmachineuser.js';
 
 export interface IReq_Admin_GetServiceMachineCredential extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest, IReq_Admin_GetServiceMachineCredential
@@ -84,6 +88,39 @@ export interface IReq_Admin_LoginWithUsernameAndPassword extends plugins.typedre
   }
 }
 
+/**
+ * Lists every deployment machine user, value-free: no token value is ever answered here.
+ * Requires an administrator; refusals travel as `IDeploymentMachineUserErrorData`.
+ */
+export interface IReq_Admin_GetDeploymentMachineUsers extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Admin_GetDeploymentMachineUsers
+> {
+  method: 'getDeploymentMachineUsers';
+  request: { identity: IIdentityCredential };
+  response: { users: IDeploymentMachineUserMetadata[] };
+}
+
+/**
+ * Creates a deployment machine user, or rotates or revokes its token.
+ *
+ * Requires an administrator. The token is answered exactly once, on the first answer to `create`
+ * or `rotate-token`; a replay of the same mutation ID by the same administrator answers the
+ * historical metadata with `token: null` and never issues another token. Grants are attached with
+ * `configureServiceDeploymentMachineUser`. Refusals travel as `IDeploymentMachineUserErrorData`.
+ */
+export interface IReq_Admin_MutateDeploymentMachineUser extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Admin_MutateDeploymentMachineUser
+> {
+  method: 'mutateDeploymentMachineUser';
+  request: { identity: IIdentityCredential; mutation: TDeploymentMachineUserMutation };
+  response: IDeploymentMachineUserMutationResult;
+}
+
+/**
+ * Attaches one deployment grant to a deployment machine user that holds a token, replacing the
+ * grant it held for the same organization and service. `mutateDeploymentMachineUser` creates such
+ * a user.
+ */
 export interface IReq_Admin_ConfigureServiceDeploymentMachineUser
 extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,

package/ts/requests/corestore.ts

@@ -332,8 +332,12 @@ extends plugins.typedrequestInterfaces.implementsTR<
  * Cloudly reads the node's legacy inventory again, requires `expectedInventorySha256`, and for
  * each selected resource creates the adopting binding in one transaction: enabled, placed on
  * `nodeId`, with `corestoreLegacyAdoption`, and for a bucket the legacy bucket name and retention
- * intent (`validatePlatformBindingCorestoreLegacyAdoption`). A resource whose adopting binding
- * already exists is answered unchanged. The response lists the adopting bindings and the plan
+ * intent (`validatePlatformBindingCorestoreLegacyAdoption`). A selection naming a
+ * `successorServiceId` creates the binding on that successor instead, with
+ * `corestoreLegacyAdoption.legacyServiceId` naming the legacy owner; the successor must exist, share
+ * the legacy owner's organization, be an immutable-deployment service, own no legacy resource of
+ * that capability and hold no other binding of it. A legacy resource is adopted by one service
+ * only. A resource whose adopting binding already exists is answered unchanged. The response lists the adopting bindings and the plan
  * (`createCorestoreLegacyResourceAdoptionPlan`) the operator hands to Corestore's offline
  * `legacy-resource-adoption` migration. Refusals travel as `ICorestoreLegacyAdoptionErrorData`.
  */

package/ts/requests/service.ts

@@ -231,6 +231,14 @@ extends plugins.typedrequestInterfaces.implementsTR<
   };
 }
 
+/**
+ * Reserves one immutable deployment for the authenticated deployment machine user.
+ *
+ * Only an API machine user can complete the operation it reserves, because only its registry
+ * push is bound to that operation. An actor that is not an API machine user, an administrator
+ * included, is refused with the code `DEPLOYMENT_MACHINE_IDENTITY_REQUIRED` before anything is
+ * reserved.
+ */
 export interface IRequest_Any_Cloudly_ReserveServiceDeployment
 extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,