@serve.zone/interfaces 32.59.0 → 32.61.0

package/ts/data/delegatedadmintoken.ts

@@ -0,0 +1,282 @@
+import { readDataElements, readDataProperty, readExactDataRecord } from '../private/dataproperties.js';
+import {
+  isReservedSecretKey, platformReservedSecretKeyPrefixes, runtimeInjectionSecretKeyPrefixes,
+  runtimeInjectionSecretKeys,
+} from './secret.js';
+
+/**
+ * A delegated administrator token (a "temp token") hands an agent a narrow, short-lived slice of
+ * one human administrator's authority, without the administrator's password or session.
+ *
+ * - Only a human administrator who signed in within five minutes mints one
+ *   (`mintDelegatedAdminToken`), for scopes named explicitly from `delegatedAdminTokenScopes`.
+ *   The plaintext token is answered exactly once; Cloudly stores only its hash.
+ * - It is exchanged with `getIdentityByToken` for a session that only the requests of its scopes
+ *   (`delegatedAdminTokenScopeRequests`) admit. Every such request re-reads the token, so the
+ *   session carries no validity of its own, and acts as `<administrator> via temp token <id>`.
+ * - It ends at its expiry, at most `maximumLifetimeMs` after the mint and never extended; when any
+ *   administrator revokes it; or when the minting administrator's credential generation changes.
+ * - A delegated session never mints, lists or revokes tokens, and no scope reaches users, roles,
+ *   human credentials, deployment tokens, authority records or organization membership.
+ */
+export const delegatedAdminTokenContract = Object.freeze({
+  /** The lifetime a mint that names none receives. */
+  defaultLifetimeMs: 60 * 60 * 1000,
+  /** The hard cap: a token lives at most one hour from its mint and is never extended. */
+  maximumLifetimeMs: 60 * 60 * 1000,
+  minimumLifetimeMs: 60 * 1000,
+  /** Every token is `delegatedAdminToken_<tokenId>_<secret>`, both parts 64 lowercase hex. */
+  tokenPrefix: 'delegatedAdminToken_',
+  /** Tokens one listing reports at most, newest first; a listing that leaves any out says so. */
+  maximumListedTokens: 256,
+  /** Secret key prefixes one token is granted at most. */
+  maximumSecretKeyPrefixes: 16,
+});
+
+/**
+ * What a token may be minted for. Each scope admits exactly the requests
+ * `delegatedAdminTokenScopeRequests` names for it, and nothing else does.
+ *
+ * - `secrets`: the operator-managed secrets of services and SecretSets: list and read their
+ *   metadata and read the ingress recipient a value is sealed to; create, rotate, retire and revoke
+ *   those whose key starts with a prefix the token was granted (`secretKeyPrefixes`, see
+ *   `isDelegatedSecretKey`; `changeSecretLifecycle` only with the actions
+ *   `delegatedAdminTokenSecretLifecycleActions` names, never `delete`). A token creates a secret
+ *   only as a launcher-environment variable, never as a file. A token minted without prefixes
+ *   creates, rotates, retires and revokes nothing.
+ * - `serviceCredentials`: a service's platform credential (`SERVEZONE_PLATFORM_AUTHORIZATION`):
+ *   inspect, ensure, rotate and revoke it.
+ */
+export const delegatedAdminTokenScopes = ['secrets', 'serviceCredentials'] as const;
+
+export type TDelegatedAdminTokenScope = typeof delegatedAdminTokenScopes[number];
+
+/** The exact requests each scope admits a delegated session on, by their wire method names. */
+export const delegatedAdminTokenScopeRequests = Object.freeze({
+  secrets: Object.freeze([
+    'getSecretIngressRecipient', 'listSecrets', 'getSecretMetadata', 'createSecret', 'rotateSecret',
+    'changeSecretLifecycle',
+  ] as const),
+  serviceCredentials: Object.freeze(['getServiceMachineCredential', 'mutateServiceMachineCredential'] as const),
+}) satisfies Readonly<Record<TDelegatedAdminTokenScope, readonly string[]>>;
+
+/** A request one scope admits, by its wire method name. */
+export type TDelegatedAdminTokenScopeRequest<TScope extends TDelegatedAdminTokenScope = TDelegatedAdminTokenScope> =
+  (typeof delegatedAdminTokenScopeRequests)[TScope][number];
+
+/** Whether `scopeArg` admits the request a wire method names. */
+export const isDelegatedAdminTokenScopeRequest = <TScope extends TDelegatedAdminTokenScope>(
+  scopeArg: TScope,
+  methodArg: unknown,
+): methodArg is TDelegatedAdminTokenScopeRequest<TScope> => (
+  (delegatedAdminTokenScopeRequests[scopeArg] as readonly unknown[]).includes(methodArg)
+);
+
+/**
+ * The `changeSecretLifecycle` actions the `secrets` scope delegates, each only for a secret whose key
+ * the token's grant covers (`isDelegatedSecretKey`). Deleting a secret stays with a human
+ * administrator: a delegated session asking for it is refused like a request outside its scope.
+ */
+export const delegatedAdminTokenSecretLifecycleActions = Object.freeze(['retire', 'revoke'] as const);
+
+/** One token, value-free. Neither the token nor its hash is ever part of it. */
+export interface IDelegatedAdminTokenMetadata {
+  /** 64 lowercase hex; the part of the token that names it. */
+  tokenId: string;
+  /** The human administrator who minted the token and whom every use acts for. */
+  userId: string;
+  /** Distinct, in `delegatedAdminTokenScopes` order. */
+  scopes: TDelegatedAdminTokenScope[];
+  /**
+   * The secret key prefixes the token creates, rotates, retires and revokes secrets under, sorted
+   * and distinct; empty when it was granted none. Only a token with the `secrets` scope carries any.
+   */
+  secretKeyPrefixes: string[];
+  createdAt: number;
+  expiresAt: number;
+  /** When an administrator revoked the token; `null` while it was never revoked. */
+  revokedAt: number | null;
+  /** The administrator who revoked it; `null` exactly when `revokedAt` is. */
+  revokedBy: string | null;
+}
+
+/** What a mint states besides the administrator's identity. */
+export interface IDelegatedAdminTokenMint {
+  scopes: TDelegatedAdminTokenScope[];
+  /** Absent: `defaultLifetimeMs`. Otherwise within `minimumLifetimeMs` and `maximumLifetimeMs`. */
+  lifetimeMs?: number;
+  /**
+   * The secret key prefixes the token may create, rotate, retire and revoke secrets under, each
+   * `isDelegatableSecretKeyPrefix`, distinct, at most `maximumSecretKeyPrefixes`; only with the
+   * `secrets` scope. Prefixes must be application-specific (`GITSYNC_`): a prefix that overlaps a
+   * reserved name is refused. Absent or empty: the token creates, rotates, retires and revokes
+   * nothing.
+   */
+  secretKeyPrefixes?: string[];
+}
+
+export interface IDelegatedAdminTokenMintResult {
+  /** The plaintext token, answered on this answer only; Cloudly keeps only its hash. */
+  token: string;
+  metadata: IDelegatedAdminTokenMetadata;
+}
+
+/**
+ * Every refusal the token requests name, as `IDelegatedAdminTokenErrorData`.
+ *
+ * - `ADMIN_AUTHORIZATION_REQUIRED`: a mint by anyone but a human administrator who signed in
+ *   within five minutes, or a listing or revocation by anyone but an administrator. A delegated
+ *   session is refused here on every request.
+ * - `DELEGATED_ADMIN_TOKEN_REQUEST_INVALID`: the request does not satisfy this contract.
+ * - `DELEGATED_ADMIN_TOKEN_NOT_FOUND`: no token has that id.
+ * - `DELEGATED_ADMIN_TOKEN_INACTIVE`: the token already ended: it expired, was revoked, or its
+ *   administrator is no longer a human administrator at the credential generation it was minted
+ *   under.
+ */
+export const delegatedAdminTokenRefusals = [
+  'ADMIN_AUTHORIZATION_REQUIRED',
+  'DELEGATED_ADMIN_TOKEN_REQUEST_INVALID',
+  'DELEGATED_ADMIN_TOKEN_NOT_FOUND',
+  'DELEGATED_ADMIN_TOKEN_INACTIVE',
+] as const;
+
+export type TDelegatedAdminTokenRefusal = typeof delegatedAdminTokenRefusals[number];
+
+export interface IDelegatedAdminTokenErrorData {
+  code: TDelegatedAdminTokenRefusal;
+  retryable: false;
+}
+
+const fail = (): never => { throw new Error('Delegated admin token 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 tokenIdPattern = /^[a-f0-9]{64}$/;
+const tokenPattern = /^delegatedAdminToken_[a-f0-9]{64}_[a-f0-9]{64}$/;
+
+/** Whether a value is a delegated admin token in its exact form; it proves nothing else. */
+export const isDelegatedAdminToken = (value: unknown): value is string => (
+  typeof value === 'string' && tokenPattern.test(value)
+);
+
+/** Whether a value names a token: 64 lowercase hex. */
+export const isDelegatedAdminTokenId = (value: unknown): value is string => (
+  typeof value === 'string' && tokenIdPattern.test(value)
+);
+
+const secretKeyPrefixPattern = /^[A-Z][A-Z0-9]*_$/;
+
+/**
+ * Whether a prefix may be granted: `^[A-Z][A-Z0-9]*_$`, and overlapping no reserved name in
+ * either direction: it neither starts with nor is the start of an entry of
+ * `platformReservedSecretKeyPrefixes` or `runtimeInjectionSecretKeyPrefixes`, and no entry of
+ * `runtimeInjectionSecretKeys` starts with it. So a granted prefix is application-specific:
+ * `GIT_`, `NODE_`, `NPM_` and `AWS_` (`AWS_CA_BUNDLE`) are refused; `GITSYNC_` is not.
+ */
+export const isDelegatableSecretKeyPrefix = (value: unknown): value is string => (
+  typeof value === 'string' && value.length <= 64 && secretKeyPrefixPattern.test(value)
+  && [...platformReservedSecretKeyPrefixes, ...runtimeInjectionSecretKeyPrefixes]
+    .every((reservedArg) => !value.startsWith(reservedArg) && !reservedArg.startsWith(value))
+  && runtimeInjectionSecretKeys.every((reservedArg) => !reservedArg.startsWith(value))
+);
+
+/**
+ * Whether a token granted `prefixesArg` creates, rotates, retires or revokes a secret of key
+ * `keyArg`, or delivers a launcher variable of that name: the key starts with a granted prefix and
+ * is not reserved (`isReservedSecretKey`).
+ */
+export const isDelegatedSecretKey = (prefixesArg: readonly string[], keyArg: string): boolean => (
+  prefixesArg.some((prefixArg) => keyArg.startsWith(prefixArg)) && !isReservedSecretKey(keyArg)
+);
+
+/** Whether a lifetime is one a mint may state. */
+export const isDelegatedAdminTokenLifetime = (value: unknown): value is number => (
+  typeof value === 'number' && Number.isSafeInteger(value)
+  && value >= delegatedAdminTokenContract.minimumLifetimeMs
+  && value <= delegatedAdminTokenContract.maximumLifetimeMs
+);
+
+/** Distinct known scopes, at least one, answered in `delegatedAdminTokenScopes` order. */
+const scopes = (value: unknown, canonical: boolean): TDelegatedAdminTokenScope[] => {
+  const entries = readDataElements(value, delegatedAdminTokenScopes.length);
+  requireValue(entries !== null && entries.length > 0 && new Set(entries).size === entries.length
+    && entries.every((entry) => delegatedAdminTokenScopes.some((scope) => scope === entry)));
+  const ordered = delegatedAdminTokenScopes.filter((scope) => entries.includes(scope));
+  requireValue(!canonical || ordered.every((scope, index) => entries[index] === scope));
+  return ordered;
+};
+
+/** Distinct grantable prefixes, at most the cap, answered sorted; `canonical` requires them sorted. */
+const secretKeyPrefixes = (value: unknown, canonical: boolean): string[] => {
+  const entries = readDataElements(value, delegatedAdminTokenContract.maximumSecretKeyPrefixes);
+  requireValue(entries !== null && new Set(entries).size === entries.length
+    && entries.every((entry) => isDelegatableSecretKeyPrefix(entry)));
+  const prefixes = (entries as string[]).slice().sort();
+  requireValue(!canonical || prefixes.every((prefix, index) => entries[index] === prefix));
+  return prefixes;
+};
+
+/** Structural copy of a mint; the backend authorizes the administrator and enforces the cap. */
+export const snapshotDelegatedAdminTokenMint = (value: unknown): IDelegatedAdminTokenMint => safe(() => {
+  const namesLifetime = readDataProperty(value, 'lifetimeMs') !== null;
+  const namesPrefixes = readDataProperty(value, 'secretKeyPrefixes') !== null;
+  const mint = object(value, ['scopes', ...(namesLifetime ? ['lifetimeMs'] : []),
+    ...(namesPrefixes ? ['secretKeyPrefixes'] : [])]);
+  const copy: IDelegatedAdminTokenMint = { scopes: scopes(mint.scopes, false) };
+  if (namesLifetime) {
+    requireValue(isDelegatedAdminTokenLifetime(mint.lifetimeMs));
+    copy.lifetimeMs = mint.lifetimeMs;
+  }
+  if (namesPrefixes) {
+    const prefixes = secretKeyPrefixes(mint.secretKeyPrefixes, false);
+    requireValue(prefixes.length === 0 || copy.scopes.includes('secrets'));
+    copy.secretKeyPrefixes = prefixes;
+  }
+  return copy;
+});
+
+/** Structural copy of listed or answered metadata. */
+export const snapshotDelegatedAdminTokenMetadata = (value: unknown): IDelegatedAdminTokenMetadata => safe(() => {
+  const metadata = object(value, ['tokenId', 'userId', 'scopes', 'secretKeyPrefixes', 'createdAt', 'expiresAt',
+    'revokedAt', 'revokedBy']);
+  requireValue(isDelegatedAdminTokenId(metadata.tokenId));
+  const createdAt = timestamp(metadata.createdAt);
+  const expiresAt = timestamp(metadata.expiresAt);
+  requireValue(expiresAt > createdAt
+    && expiresAt - createdAt <= delegatedAdminTokenContract.maximumLifetimeMs);
+  const revoked = metadata.revokedAt !== null;
+  requireValue(revoked === (metadata.revokedBy !== null));
+  const revokedAt = revoked ? timestamp(metadata.revokedAt) : null;
+  requireValue(revokedAt === null || revokedAt >= createdAt);
+  const tokenScopes = scopes(metadata.scopes, true);
+  const prefixes = secretKeyPrefixes(metadata.secretKeyPrefixes, true);
+  requireValue(prefixes.length === 0 || tokenScopes.includes('secrets'));
+  return {
+    tokenId: metadata.tokenId, userId: identifier(metadata.userId), scopes: tokenScopes,
+    secretKeyPrefixes: prefixes, createdAt, expiresAt, revokedAt,
+    revokedBy: revoked ? identifier(metadata.revokedBy) : null,
+  };
+});
+
+/** Structural copy of a mint's answer: a token in its exact form and the metadata that names it. */
+export const snapshotDelegatedAdminTokenMintResult = (value: unknown): IDelegatedAdminTokenMintResult => safe(() => {
+  const result = object(value, ['token', 'metadata']);
+  requireValue(isDelegatedAdminToken(result.token));
+  const metadata = snapshotDelegatedAdminTokenMetadata(result.metadata);
+  requireValue(result.token.slice(delegatedAdminTokenContract.tokenPrefix.length,
+    delegatedAdminTokenContract.tokenPrefix.length + 64) === metadata.tokenId && metadata.revokedAt === null);
+  return { token: result.token, metadata };
+});

package/ts/data/externalregistry.ts

@@ -1,5 +1,9 @@
 import * as plugins from '../plugins.js';
 
+/**
+ * An external registry as Cloudly stores it, credential included. Never answered: every external
+ * registry response carries `IExternalRegistryPublic`.
+ */
 export interface IExternalRegistry {
   id: string;
   data: {
@@ -24,7 +28,10 @@ export interface IExternalRegistry {
     username?: string;
     
     /**
-     * Password, access token, or API key for authentication (optional for public registries)
+     * Password, access token or API key for authentication (optional for public registries).
+     *
+     * Write-only: Cloudly stores it and uses it server-side, and never answers it. Reads carry
+     * `IExternalRegistryPublic.passwordConfigured` instead.
      */
     password?: string;
     
@@ -107,4 +114,55 @@ export interface IExternalRegistry {
      */
     updatedAt?: number;
   };
-}
+}
+
+/**
+ * An external registry as Cloudly answers it: the stored registry without its credential, and
+ * whether one is stored.
+ */
+export interface IExternalRegistryPublic {
+  id: string;
+  data: Omit<IExternalRegistry['data'], 'password'>;
+  /** Whether a password, access token or API key is stored for the registry. */
+  passwordConfigured: boolean;
+}
+
+/** The registry fields an operator writes; Cloudly owns status, errors and timestamps. */
+export type TExternalRegistryOperatorField =
+  | 'type'
+  | 'name'
+  | 'url'
+  | 'username'
+  | 'password'
+  | 'description'
+  | 'isDefault'
+  | 'authType'
+  | 'insecure'
+  | 'namespace'
+  | 'proxy'
+  | 'config';
+
+export type TExternalRegistryOperatorData = Pick<IExternalRegistry['data'], TExternalRegistryOperatorField>;
+
+/**
+ * What a registry verification proved.
+ *
+ * - `authenticated`: the registry admitted the stored credentials (Basic, or a token its Bearer
+ *   realm issued for them).
+ * - `anonymous`: the registry answers without authentication and none is configured.
+ * - `credentials-not-exercised`: credentials are configured, but the registry answers without
+ *   authentication, so they were never checked.
+ * - `authentication-failed`: the registry, or its token realm, refused the credentials, or it
+ *   requires authentication and none is configured.
+ * - `unreachable`: no usable answer (connection, TLS, timeout or an unexpected HTTP status).
+ * - `unsupported`: the registry or its configuration cannot be verified (an npm registry, OAuth2,
+ *   an unknown or missing authentication challenge, a redirect, or credentials over plain HTTP
+ *   without `insecure`).
+ */
+export type TExternalRegistryVerifyOutcome =
+  | 'authenticated'
+  | 'anonymous'
+  | 'credentials-not-exercised'
+  | 'authentication-failed'
+  | 'unreachable'
+  | 'unsupported';

package/ts/data/gateway.ts

@@ -20,8 +20,16 @@ export type TManagedRouteKind = 'letsencrypt-http01-forward';
 /**
  * DNS handling requested alongside a gateway route synchronization.
  *
- * - 'reconcile' claims or replaces exact-host manual A, AAAA, and CNAME
- *   records, including already-correct records, with gateway-managed state.
+ * - 'reconcile' creates, updates and deletes the exact-host A or AAAA record
+ *   the route's gateway DNS ownership holds. It never adopts, replaces or
+ *   deletes a record without gateway DNS ownership. The route is satisfied by
+ *   manual records only when no record at the name is owned and every manual A
+ *   or AAAA record there matches the desired type, value and proxied flag (TTL
+ *   ignored); anything else (a differing record, any CNAME, owned and manual
+ *   records together) and an operator-protected hostname is a non-retryable
+ *   `record-conflict` with no mutation. When the route stops claiming the
+ *   hostname while another enabled route on the gateway serves it, the owned
+ *   record is released to manual ownership instead of deleted.
  * - 'observe' reports DNS state without mutating it.
  * - 'skip' bypasses DNS inspection and mutation and is the default when omitted.
  */
@@ -29,6 +37,14 @@ export type TGatewayRouteDnsMode = 'reconcile' | 'observe' | 'skip';
 
 /**
  * Detailed DNS outcome reported by a gateway route synchronization.
+ *
+ * - `manual-satisfied`: every manual A or AAAA record at the name matches the desired type,
+ *   value and proxied flag; the gateway changes and claims nothing and reports them in
+ *   `records` with `managed: false`.
+ * - `managed-released`: the route no longer claims the hostname, but another enabled route on
+ *   the gateway still serves it, so the gateway released its record to manual ownership instead
+ *   of deleting it; the released record is reported in `records` with `managed: false`.
+ * - `managed-overwrote-manual` and `managed-orphan-deleted`: deprecated; no gateway reports them.
  */
 export type TGatewayRouteDnsStatus =
   | 'not-applicable'
@@ -37,8 +53,10 @@ export type TGatewayRouteDnsStatus =
   | 'managed-updated'
   | 'managed-overwrote-manual'
   | 'managed-unchanged'
+  | 'manual-satisfied'
   | 'observed-satisfied'
   | 'managed-deleted'
+  | 'managed-released'
   | 'managed-orphan-deleted'
   | 'record-missing'
   | 'target-invalid'
@@ -77,7 +95,10 @@ export interface IGatewayRouteDnsResult {
   zoneName?: string;
   nameservers?: string[];
   records?: IGatewayRouteDnsRecord[];
-  /** Prior manual records replaced by this reconciliation, preserved as evidence. */
+  /**
+   * Prior manual records replaced by this reconciliation, preserved as evidence.
+   * @deprecated No gateway replaces manual records; it accompanied `managed-overwrote-manual`.
+   */
   overwrittenRecords?: IGatewayRouteDnsRecord[];
   /** Time at which the gateway checked the DNS state, as Unix epoch milliseconds. */
   checkedAt: number;

package/ts/data/index.ts

@@ -9,6 +9,7 @@ export * from './config.js';
 export * from './corestore.js';
 export * from './corestorecontroltoken.js';
 export * from './corestorelegacyadoption.js';
+export * from './delegatedadmintoken.js';
 export * from './coremail.js';
 export * from './coremail.runtime.js';
 export * from './deployment.js';
@@ -82,6 +83,7 @@ export * from './servicecredential.js';
 export * from './serviceplatformownership.js';
 export * from './serviceports.js';
 export * from './serviceruntime.js';
+export * from './launchersecretowner.js';
 export * from './servicevolumeinitialization.js';
 export * from './status.js';
 export * from './taskexecution.js';

package/ts/data/launchersecretowner.ts

@@ -0,0 +1,145 @@
+import type { ISecretLauncherEnvironmentDelivery } from './secret.js';
+import type { IServiceRuntimeProfile, TServiceRuntimeRefusal } from './serviceruntime.js';
+import { hasExactKeys, isPlainRecord } from '../private/dataproperties.js';
+import { isRuntimeIdentityNumber, runtimePolicyLimits } from '../private/runtimepolicy.js';
+
+/** What the owner of a workload's launcher-environment secret files derives from. */
+export interface ILauncherSecretDeliveryOwnerInput {
+  /** The runtime spec's `profile.runAs`; null runs the image's own OCI user. */
+  runAs: IServiceRuntimeProfile['runAs'];
+  /**
+   * The unresolved OCI `config.User` of the pinned digest's image config in Cloudly's canonical
+   * form (what its registry manager's `parseCanonicalImageUser` answers, never the raw registry
+   * value): `user` or `user:group`, each part a numeric identity or a name, and null for an image
+   * that states none or an empty `User`. One entry for a single-platform manifest, one per
+   * platform of a multi-platform index; never empty.
+   */
+  imageUsers: (string | null)[];
+  /**
+   * Every launcher-environment delivery the workload receives, as its caller states it. A `0o440`
+   * delivery grants the derived group, so that group has to be one the image states numerically.
+   */
+  launcherDeliveries: Pick<ISecretLauncherEnvironmentDelivery, 'variableName' | 'mode'>[];
+}
+
+/**
+ * The numeric owner of a workload's launcher-environment secret files, or why it derives none.
+ *
+ * `not-required` is a workload without launcher-environment deliveries: no file needs an owner, so
+ * nothing about the image refuses it.
+ *
+ * `launcher-secret-ownership-unknown` is a runtime spec that runs the image's own user
+ * (`runAs: null`) while that user's numeric owner is not known: a named user other than `root`, a
+ * numeric part above the runtime identity bound, a group-readable (`0o440`) delivery whose group
+ * the image does not state numerically, or platforms of a multi-platform index that derive
+ * different owners. `variableName` names the group-readable delivery that caused it (the first by
+ * name), null for the others; `message` states the cause.
+ */
+export type TLauncherSecretDeliveryOwner =
+  | { status: 'derived'; uid: number; gid: number }
+  | { status: 'not-required' }
+  | {
+    status: 'refused';
+    reason: Extract<TServiceRuntimeRefusal, 'launcher-secret-ownership-unknown'>;
+    variableName: string | null;
+    message: string;
+  };
+
+const imageUserPartPattern = /^[^:\u0000-\u001f\u007f]+$/;
+
+/**
+ * One part of an image user: a numeric identity (`root` is `0`), a numeric part above the runtime
+ * identity bound, or a name only the image's root filesystem resolves.
+ */
+type TImageUserPart = number | 'unbounded' | 'named';
+
+const imageUserPart = (partArg: string): TImageUserPart => {
+  if (partArg === 'root') return 0;
+  if (!/^[0-9]+$/.test(partArg)) return 'named';
+  const identity = Number(partArg);
+  return isRuntimeIdentityNumber(identity) ? identity : 'unbounded';
+};
+
+/** One platform's user and group; an absent group is `undefined`. A malformed image user throws. */
+const imageUserParts = (imageUserArg: unknown): { user: TImageUserPart; group: TImageUserPart | undefined } => {
+  if (imageUserArg === null) return { user: 0, group: 0 };
+  const parts = typeof imageUserArg === 'string' ? imageUserArg.split(':') : [];
+  if (parts.length === 0 || parts.length > 2 || !parts.every((partArg) => imageUserPartPattern.test(partArg))) {
+    throw new Error('image user must be null, user or user:group');
+  }
+  return { user: imageUserPart(parts[0]), group: parts[1] === undefined ? undefined : imageUserPart(parts[1]) };
+};
+
+/** The names of the group-readable (`0o440`) deliveries, sorted; a malformed delivery throws. */
+const groupReadableVariableNames = (deliveriesArg: unknown): string[] => {
+  if (!Array.isArray(deliveriesArg)) throw new Error('launcherDeliveries must list the launcher deliveries');
+  const names: string[] = [];
+  for (const delivery of deliveriesArg) {
+    if (!isPlainRecord(delivery) || typeof delivery.variableName !== 'string' || delivery.variableName === ''
+      || (delivery.mode !== 0o400 && delivery.mode !== 0o440)) {
+      throw new Error('a launcher delivery must state its variableName and a 0400 or 0440 mode');
+    }
+    if (delivery.mode === 0o440) names.push(delivery.variableName);
+  }
+  return names.sort();
+};
+
+const refusal = (variableNameArg: string | null, messageArg: string): TLauncherSecretDeliveryOwner => ({
+  status: 'refused', reason: 'launcher-secret-ownership-unknown', variableName: variableNameArg, message: messageArg,
+});
+
+/**
+ * The owner Cloudly gives every launcher-environment secret file of a workload, which WorkloadInit
+ * reads as the workload's own process identity before it starts the image.
+ *
+ * Without launcher deliveries it is `not-required`. A `runAs` pair wins over the image. Under
+ * `runAs: null` an image without a user runs as root (`0:0`, the runtime config's own default), a
+ * numeric `user:group` is taken as stated and `root` stands for `0` in either part. A numeric user
+ * without a group, or with a named group, is `user:0` while every delivery is owner-readable
+ * (`0o400`), which grants the group nothing; a `0o440` delivery would grant it, so it refuses and
+ * names that delivery. A named user, or a numeric part above the runtime identity bound, refuses.
+ * Every platform of a multi-platform index must derive
+ * the same owner, or it refuses: a workload gets one delivery, never one per platform. Nothing is
+ * guessed. A structurally malformed input throws, whatever it would answer.
+ */
+export const deriveLauncherSecretDeliveryOwner = (
+  inputArg: ILauncherSecretDeliveryOwnerInput,
+): TLauncherSecretDeliveryOwner => {
+  const { runAs, imageUsers, launcherDeliveries } = inputArg;
+  if (runAs !== null && !(isPlainRecord(runAs) && hasExactKeys(runAs, ['user', 'group'])
+    && isRuntimeIdentityNumber(runAs.user) && isRuntimeIdentityNumber(runAs.group))) {
+    throw new Error('runAs must be null or an exact user and group');
+  }
+  if (!Array.isArray(imageUsers) || imageUsers.length === 0) {
+    throw new Error('imageUsers must name the user of every platform');
+  }
+  const platforms = imageUsers.map(imageUserParts);
+  const groupReadable = groupReadableVariableNames(launcherDeliveries);
+  if (launcherDeliveries.length === 0) return { status: 'not-required' };
+  if (runAs !== null) return { status: 'derived', uid: runAs.user, gid: runAs.group };
+  const userOf = (predicateArg: (platformArg: typeof platforms[number]) => boolean): string | null | undefined => (
+    imageUsers.find((_imageUserArg, indexArg) => predicateArg(platforms[indexArg])));
+  const unbounded = userOf((platformArg) => platformArg.user === 'unbounded' || platformArg.group === 'unbounded');
+  if (unbounded !== undefined) {
+    return refusal(null, `image user '${unbounded}' states an identity above `
+      + `${runtimePolicyLimits.maximumIdentityNumber}`);
+  }
+  const namedUser = userOf((platformArg) => platformArg.user === 'named');
+  if (namedUser !== undefined) {
+    return refusal(null, `image user '${namedUser}' names a user only the image's root filesystem resolves`);
+  }
+  const ungrouped = userOf((platformArg) => typeof platformArg.group !== 'number');
+  if (ungrouped !== undefined && groupReadable.length > 0) {
+    return refusal(groupReadable[0], `launcher-environment secret ${groupReadable.join(', ')} is group-readable `
+      + `(0440), but image user '${ungrouped}' states no numeric group`);
+  }
+  // Every part is now a bounded number, or a group that an owner-readable file does not grant.
+  const [first, ...rest] = platforms.map((platformArg) => ({
+    uid: platformArg.user as number, gid: typeof platformArg.group === 'number' ? platformArg.group : 0,
+  }));
+  if (rest.some((ownerArg) => ownerArg.uid !== first.uid || ownerArg.gid !== first.gid)) {
+    const users = imageUsers.map((userArg) => userArg === null ? 'none' : `'${userArg}'`).join(', ');
+    return refusal(null, `the platforms' image users ${users} derive different owners`);
+  }
+  return { status: 'derived', uid: first.uid, gid: first.gid };
+};