@serve.zone/interfaces 32.58.0 → 32.60.0

package/dist_ts/requests/externalregistry.d.ts

@@ -8,7 +8,7 @@ export interface IReq_GetRegistryById extends plugins.typedrequestInterfaces.imp
         id: string;
     };
     response: {
-        registry: data.IExternalRegistry;
+        registry: data.IExternalRegistryPublic;
     };
 }
 export interface IReq_GetRegistries extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_GetRegistries> {
@@ -17,7 +17,7 @@ export interface IReq_GetRegistries extends plugins.typedrequestInterfaces.imple
         identity: userInterfaces.IIdentity;
     };
     response: {
-        registries: data.IExternalRegistry[];
+        registries: data.IExternalRegistryPublic[];
     };
 }
 export interface IReq_CreateRegistry extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_CreateRegistry> {
@@ -27,7 +27,7 @@ export interface IReq_CreateRegistry extends plugins.typedrequestInterfaces.impl
         registryData: data.IExternalRegistry['data'];
     };
     response: {
-        registry: data.IExternalRegistry;
+        registry: data.IExternalRegistryPublic;
     };
 }
 export interface IReq_UpdateRegistry extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_UpdateRegistry> {
@@ -35,10 +35,14 @@ export interface IReq_UpdateRegistry extends plugins.typedrequestInterfaces.impl
     request: {
         identity: userInterfaces.IIdentity;
         registryId: string;
-        registryData: data.IExternalRegistry['data'];
+        /**
+         * The operator fields to change; a field left out keeps its stored value. `password` is
+         * write-only: missing or empty keeps the stored credential, and `authType: 'none'` removes it.
+         */
+        registryData: Partial<data.TExternalRegistryOperatorData>;
     };
     response: {
-        resultRegistry: data.IExternalRegistry;
+        resultRegistry: data.IExternalRegistryPublic;
     };
 }
 export interface IReq_DeleteRegistryById extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_DeleteRegistryById> {
@@ -58,8 +62,10 @@ export interface IReq_VerifyRegistry extends plugins.typedrequestInterfaces.impl
         registryId: string;
     };
     response: {
+        /** True exactly for the `authenticated` and `anonymous` outcomes. */
         success: boolean;
+        outcome: data.TExternalRegistryVerifyOutcome;
         message?: string;
-        registry?: data.IExternalRegistry;
+        registry: data.IExternalRegistryPublic;
     };
 }

package/dist_ts/requests/service.d.ts

@@ -317,7 +317,22 @@ export interface IRequest_Any_Cloudly_UpdateService extends plugins.typedrequest
     request: {
         identity: IIdentity;
         serviceId: string;
-        serviceData: TServiceUpdateWritableData;
+        /**
+         * The fields to change, merged over the stored service one key deep: a key the update omits
+         * keeps its stored value, and a key it states replaces the stored value whole (a stated
+         * `ports`, `mail` or `domains` is the complete new value, not a patch of the old one).
+         * `containerArgs: null` removes the stored argument vector; no other field takes `null`.
+         * `registryTarget` is the exception to "replaces": Cloudly derives it from the service and
+         * its image version, so a stated one only makes Cloudly derive it again and is never stored.
+         * An optional field cannot be cleared yet: a key whose value is `undefined` is dropped in
+         * transit, so it reads as omitted (explicit `null` removal for optional fields is a follow-up).
+         *
+         * Cloudly's guards ask which keys an update states, so send only the fields that change: a
+         * service with a runtime spec refuses any update stating `placement` or `scaleFactor`, and an
+         * immutable service refuses `imageId`, `imageVersion`, `registryTarget`, `scaleFactor` and
+         * `placement`, even when the stated value repeats the stored one.
+         */
+        serviceData: Partial<TServiceUpdateWritableData>;
     };
     response: {
         service: IService;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/interfaces",
-  "version": "32.58.0",
+  "version": "32.60.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.",
   "exports": {

package/readme.md

@@ -2103,15 +2103,17 @@ evidence has not arrived). `refused` carries a `TServiceRuntimeRefusal`:
 `node-authority-unsupported`, `network-policy-missing`, `network-policy-mismatch`,
 `network-workload-pool-missing`, `network-workload-pool-exhausted`, `volume-driver-unsupported`,
 `volume-options-unsupported`, `volume-shared-unsupported`, `volume-placement-unsupported`,
-`volume-initialization-unknown`, `volume-ownership-unknown`, `objectstorage-endpoint-missing`,
-`objectstorage-binding-invalid`, `objectstorage-environment-conflict`,
+`volume-initialization-unknown`, `volume-ownership-unknown`, `launcher-secret-ownership-unknown`,
+`objectstorage-endpoint-missing`, `objectstorage-binding-invalid`, `objectstorage-environment-conflict`,
 `objectstorage-endpoint-unselected`, `database-endpoint-missing`, `database-endpoint-unselected`,
 `cluster-relay-missing` or `cluster-ingress-environment-conflict`.
 The first four volume
 refusals name what a local storage claim cannot express: a volume driver other than a node-local
 directory, driver or mount options, one volume mounted by more than one replica or service, and a
 placement that does not pin each volume to one node. The other two name what Cloudly will not guess,
-see [Service Volume Initialization](#service-volume-initialization). Of the four object-storage
+see [Service Volume Initialization](#service-volume-initialization).
+`launcher-secret-ownership-unknown` is a launcher-environment secret file owner Cloudly cannot know,
+see [Launcher Secret Ownership](#launcher-secret-ownership). Of the four object-storage
 refusals, `objectstorage-endpoint-missing`, `objectstorage-binding-invalid` and
 `objectstorage-environment-conflict` name why a binding's environment cannot be composed, see
 [Object-Storage Binding Environment](#object-storage-binding-environment), and
@@ -2194,6 +2196,48 @@ Cloudly knows. The rule decides the first generation of a claim only: every late
 that claim's own initialization and ownership, whatever `runAs` says by then, since the node refuses
 a claim whose initial ownership changed.
 
+### Launcher Secret Ownership
+
+WorkloadInit reads a workload's launcher-environment secret files as the workload's own process
+identity, so their owner comes from that identity and never from a fixed `0:0`.
+`deriveLauncherSecretDeliveryOwner({ runAs, imageUsers, launcherDeliveries })` is the one rule, and
+answers `TLauncherSecretDeliveryOwner`: `derived` with `{ uid, gid }`, `not-required` for a workload
+without launcher deliveries, or `refused` with `reason: 'launcher-secret-ownership-unknown'`,
+`variableName` (the group-readable delivery that caused it, else `null`) and a `message`.
+
+`runAs` is the runtime spec's `profile.runAs`. `imageUsers` holds the image user of the pinned
+digest's image config in Cloudly's canonical form (the registry manager's `parseCanonicalImageUser`
+answer, `null` for an image without a user or with an empty `User`, never the raw registry value):
+one entry for a single-platform manifest, one per platform of a multi-platform index.
+`launcherDeliveries` are the workload's launcher deliveries as their callers state them
+(`variableName` and `mode`); group readability is computed from them, never passed in.
+
+| `runAs` | Image user | Owner |
+| --- | --- | --- |
+| `{ user, group }` | any | `user:group` |
+| `null` | none | `0:0`, the runtime config's root default |
+| `null` | numeric `u:g` (`root` is `0`) | `u:g` |
+| `null` | numeric `u`, or `u:<name>` | `u:0` while every delivery is `0o400`; refused, naming the first `0o440` delivery by variable name, otherwise |
+| `null` | a named user other than `root` | refused |
+| `null` | a numeric part above `2147483647` | refused |
+
+An owner-readable (`0o400`) file grants its group nothing, so an unstated group is `0`; a `0o440`
+file would grant group `0` instead of the image's own group, so it refuses. Every platform of a
+multi-platform index must derive the same owner, or the workload is refused: it gets one delivery,
+never one per platform. Without launcher deliveries nothing about the image refuses. Only a
+structurally malformed input throws.
+
+The owner travels in the resolved manifest, not in what a caller states. `TSecretDelivery`
+(`ISecretLauncherEnvironmentDelivery | ISecretFileDelivery`) is a caller's delivery: a Secret's
+`defaultDelivery`, a SecretSet attachment override, a create request, an App Store declaration. Its
+launcher member's `uid` and `gid` are optional and deprecated: the resolver ignores them, and
+`validateSecretDelivery` prefers neither and tolerates both (bounded) until the next major removes
+them. `TSecretResolvedDelivery` (`ISecretResolvedLauncherEnvironmentDelivery | ISecretFileDelivery`)
+is `IResolvedSecretManifestEntry.delivery`: its launcher member requires `uid` and `gid` under the
+same keys, so the manifest's wire format and digest are unchanged for every node.
+`createResolvedSecretDelivery(delivery, owner)` builds it from a caller's delivery and the derived
+owner, and `validateSecretResolvedDelivery` checks it. File deliveries keep their stated owner.
+
 ### Runtime Assignment Views
 
 `data.IServiceRuntimeAssignmentView` is one replica slot's current assignment as an administrator
@@ -2998,8 +3042,17 @@ Common data contracts include:
   `proposeClusterNodeName`) and the named `clusterNodeHostnameRefusals` of
   `setClusterNodeHostname` and `resetClusterNodeHostname`.
 - `IService`, `IDeployment`, `IImage`, `IRegistryTarget`, and `IExternalRegistry` for workload delivery.
+- External registries: `IExternalRegistry` is the stored registry, credential included, and is
+  never answered. Every `requests.externalRegistry` response carries `IExternalRegistryPublic`: the
+  registry without `data.password` and with `passwordConfigured`. `data.password` (a password, access
+  token or API key) is write-only: create stores it; an update (`registryData`, a `Partial` of
+  `TExternalRegistryOperatorData`, never status, errors or timestamps) keeps the stored one when it
+  is missing or empty, and `authType: 'none'` removes it. `verifyExternalRegistry` answers a
+  `TExternalRegistryVerifyOutcome`: only `authenticated` proves the credentials;
+  `credentials-not-exercised` means the registry answered anonymously although credentials are
+  configured.
 - Service port contracts including `IServiceTargetPort`, `IServiceDomainRoute`, and `IServicePublicPortMapping` for canonical backend targets, domain target references, and edge/Coretraffic TCP/UDP public exposure.
-- `IDomain`, `IDnsEntry`, and traffic contracts for routing and DNS management.
+- `IDomain`, `IDnsEntry`, and traffic contracts for routing and DNS management. `IDomain.data.gatewayListedAt` records when the dcrouter gateway last listed the domain to this Cloudly and is absent while the gateway does not list it; it is separate from the operator's `activationState`.
 - Traffic and gateway route contracts including `ICoretrafficPortRouteConfig`, routing `portRoutes`, and `IGatewayClientRoute` client-owned route views. Gateway route intent supports optional match `domains`, `transport`, and `remoteIngress`, plus explicit route `priority` and `managedRouteKind`. Ownership can combine `hostname` with `routeRef` so a normal route and a path-specific managed route for the same hostname reconcile independently.
 - Value-free `ISecretMetadata`, `ISecretVersionMetadata`, and `ISecretSetMetadata`
   contracts for operator views, plus exact-version
@@ -4612,12 +4665,20 @@ to a workload environment and refuses, naming every key, a name that is already
 service itself or by a second object-storage binding — instead of letting one value replace
 another.
 
-**Reporting.** `composeObjectStorageServiceEnvironment(serviceEnvironment, sources)` composes a
-whole service and answers in the service runtime vocabulary, so a producer never classifies the
-errors above. Each `IObjectStorageBindingEnvironmentSource { binding, endpoint }` is an enabled
-object-storage binding and the `corestoreObjectStorage` of the node it is placed on, `null` when
-that node states none; a binding placed on no node is not a source, and its service waits as
-`bindings-pending`. The answer is a `TObjectStorageServiceEnvironmentComposition`:
+**Reporting.** `composeObjectStorageServiceEnvironment(serviceEnvironment, sources,
+secretEnvironmentNames?)` composes a whole service and answers in the service runtime vocabulary,
+so a producer never classifies the errors above. Each
+`IObjectStorageBindingEnvironmentSource { binding, endpoint }` is an enabled object-storage binding
+and the `corestoreObjectStorage` of the node it is placed on, `null` when that node states none; a
+binding placed on no node is not a source, and its service waits as `bindings-pending`.
+`secretEnvironmentNames` names, without values, the variables the workload receives as
+launcher-environment secrets (the `variableName` of each `launcher-environment` delivery in its
+desired secret manifest; none when omitted). The launcher sets a secret over a plain variable of
+the same name, so a secret named like a binding's name would silently replace the binding's
+endpoint: it claims the name exactly as the service's own environment does. Secrets by any other
+name, including the binding's own credentials (`corestoreObjectStorageCredentialSecretKeys`, never
+plain names), do not concern the composition. `secretEnvironmentNames` becomes required in the
+coordinated major. The answer is a `TObjectStorageServiceEnvironmentComposition`:
 
 | `status` | `reason` | When |
 | --- | --- | --- |
@@ -4625,7 +4686,7 @@ that node states none; a binding placed on no node is not a source, and its serv
 | `waiting` | `objectstorage-retention-pending` | A binding declares compliance retention whose evidence has not arrived. |
 | `refused` | `objectstorage-endpoint-missing` | The binding's node states no valid `corestoreObjectStorage`. |
 | `refused` | `objectstorage-binding-invalid` | `createObjectStorageBindingEnvironment()` refuses the binding: not `objectstorage`, no canonical bucket, no canonical retention intent, or evidence that does not prove this binding. |
-| `refused` | `objectstorage-environment-conflict` | The service's own environment or another binding already sets one of the binding's names. |
+| `refused` | `objectstorage-environment-conflict` | The service's own environment, one of its launcher-environment secrets or another binding already sets one of the binding's names. |
 
 `waiting` and `refused` carry the `bindingId` and the contract's `message`. Bindings are taken in
 id order, so the verdict does not depend on the order of the sources, and a refusal outranks a
@@ -4682,7 +4743,10 @@ object-storage endpoint. What they are addressed to is a fact about the node, ow
 ### Launcher Environment Delivery
 
 Launcher environment delivery uses stable `szsv-<base32-sha256>` Docker
-resource names and `/run/serve.zone/secrets/<resource>` source paths. The
+resource names and `/run/serve.zone/secrets/<resource>` source paths. Each
+source file is owned by the workload identity the resolved manifest states,
+derived by `deriveLauncherSecretDeliveryOwner` (see
+[Launcher Secret Ownership](#launcher-secret-ownership)). The
 nonsecret map is written to `/run/serve.zone/workloadinit-map.json` with mode
 0444. Runtime assets under `/opt/serve.zone/runtime-assets` are read-only, the
 wrapper itself lives at

package/ts/00_commitinfo_data.ts

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

package/ts/data/domain.ts

@@ -105,7 +105,14 @@ export interface IDomain {
      */
     syncSource?: 'cloudflare' | 'manual' | null;
     lastSyncAt?: number;
-    
+
+    /**
+     * When the dcrouter gateway last listed this domain to this Cloudly (timestamp).
+     * Absent while the gateway does not list the domain. The gateway sync owns this
+     * member; it is independent of the operator's `activationState`.
+     */
+    gatewayListedAt?: number;
+
     /**
      * Whether domain is managed externally
      */

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/index.ts

@@ -82,6 +82,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 };
+};

package/ts/data/secret.ts

@@ -228,7 +228,33 @@ export interface ISecretSetConsumerRolloutStatus {
   updatedAt: number;
 }
 
+/**
+ * A launcher-environment delivery as a caller states it: on a Secret's `defaultDelivery`, a
+ * SecretSet attachment override, a create request or an App Store declaration. The owner of the
+ * file WorkloadInit reads is not the caller's to state; the resolver derives it.
+ */
 export interface ISecretLauncherEnvironmentDelivery {
+  type: 'launcher-environment';
+  variableName: string;
+  /**
+   * @deprecated Derived by the resolver from the workload identity
+   * (`deriveLauncherSecretDeliveryOwner`); ignored; removed in the next major.
+   */
+  uid?: number;
+  /**
+   * @deprecated Derived by the resolver from the workload identity
+   * (`deriveLauncherSecretDeliveryOwner`); ignored; removed in the next major.
+   */
+  gid?: number;
+  mode: 0o400 | 0o440;
+}
+
+/**
+ * A launcher-environment delivery of a resolved secret manifest. `uid` and `gid` are the owner the
+ * resolver derived from the workload identity (`deriveLauncherSecretDeliveryOwner`), written by
+ * `createResolvedSecretDelivery`; the node mounts the file with them.
+ */
+export interface ISecretResolvedLauncherEnvironmentDelivery {
   type: 'launcher-environment';
   variableName: string;
   uid: number;
@@ -244,8 +270,12 @@ export interface ISecretFileDelivery {
   mode: 0o400 | 0o440;
 }
 
+/** A delivery as a caller states it. */
 export type TSecretDelivery = ISecretLauncherEnvironmentDelivery | ISecretFileDelivery;
 
+/** A delivery of a resolved secret manifest: every owner is stated. */
+export type TSecretResolvedDelivery = ISecretResolvedLauncherEnvironmentDelivery | ISecretFileDelivery;
+
 export const secretValueLimits = Object.freeze({
   maximumBytes: 500 * 1024,
   minimumGeneratedBytes: 16,
@@ -299,7 +329,7 @@ export interface IResolvedSecretManifestEntry {
   key: string;
   environment: TSecretEnvironment;
   owner: TWorkloadSecretOwner;
-  delivery: TSecretDelivery;
+  delivery: TSecretResolvedDelivery;
 }
 
 /** Immutable, value-free runtime snapshot. */
@@ -709,14 +739,16 @@ export const validateSecretManagementScope = (
     : ['management scope prefix must match management source'];
 };
 
-export const validateSecretDelivery = (deliveryArg: unknown): string[] => {
+const validateDelivery = (deliveryArg: unknown, launcherOwnerArg: 'tolerated' | 'required'): string[] => {
   if (!isRecord(deliveryArg)) return ['delivery must be an object'];
   const isLauncher = deliveryArg.type === 'launcher-environment';
   if (!isLauncher && deliveryArg.type !== 'file') {
     return ['delivery type must be launcher-environment or file'];
   }
+  const statesOwner = !isLauncher || launcherOwnerArg === 'required'
+    || deliveryArg.uid !== undefined || deliveryArg.gid !== undefined;
   const expectedKeys = isLauncher
-    ? ['type', 'variableName', 'uid', 'gid', 'mode']
+    ? ['type', 'variableName', ...(statesOwner ? ['uid', 'gid'] : []), 'mode']
     : ['type', 'targetPath', 'uid', 'gid', 'mode'];
   if (!hasExactKeys(deliveryArg, expectedKeys)) {
     return ['delivery must use its exact schema'];
@@ -730,7 +762,7 @@ export const validateSecretDelivery = (deliveryArg: unknown): string[] => {
     || !/^\/run\/secrets\/[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(deliveryArg.targetPath))) {
     errors.push('file delivery targetPath must be a canonical file below /run/secrets');
   }
-  for (const field of ['uid', 'gid'] as const) {
+  for (const field of statesOwner ? ['uid', 'gid'] as const : []) {
     const value = deliveryArg[field];
     if (!Number.isSafeInteger(value)
       || (value as number) < 0
@@ -744,6 +776,30 @@ export const validateSecretDelivery = (deliveryArg: unknown): string[] => {
   return errors;
 };
 
+/**
+ * Validates a delivery as a caller states it. A launcher delivery should state no owner; one that
+ * states the deprecated `uid` and `gid` (both, bounded) is tolerated until the next major.
+ */
+export const validateSecretDelivery = (deliveryArg: unknown): string[] => validateDelivery(deliveryArg, 'tolerated');
+
+/** Validates a resolved manifest's delivery: a launcher delivery states its derived owner. */
+export const validateSecretResolvedDelivery = (deliveryArg: unknown): string[] => validateDelivery(
+  deliveryArg, 'required');
+
+/**
+ * The resolved manifest delivery of a caller's delivery: a launcher delivery takes the owner the
+ * resolver derived (`deriveLauncherSecretDeliveryOwner`) and drops any deprecated owner the caller
+ * stated; a file delivery keeps its own.
+ */
+export const createResolvedSecretDelivery = (
+  deliveryArg: TSecretDelivery,
+  ownerArg: { uid: number; gid: number },
+): TSecretResolvedDelivery => (deliveryArg.type === 'launcher-environment'
+  ? { type: 'launcher-environment', variableName: deliveryArg.variableName, uid: ownerArg.uid, gid: ownerArg.gid,
+    mode: deliveryArg.mode }
+  : { type: 'file', targetPath: deliveryArg.targetPath, uid: deliveryArg.uid, gid: deliveryArg.gid,
+    mode: deliveryArg.mode });
+
 export const validateSecretMetadata = (secretArg: unknown): string[] => {
   if (!isRecord(secretArg)) return ['secret metadata must be an object'];
   const expectedKeys = [
@@ -1269,7 +1325,7 @@ export const validateResolvedSecretManifest = (
         `secret manifest entries[${index}].owner serviceId must match the manifest serviceId`,
       );
     }
-    errors.push(...validateSecretDelivery(candidate.delivery).map(
+    errors.push(...validateSecretResolvedDelivery(candidate.delivery).map(
       (errorArg) => `secret manifest entries[${index}].${errorArg}`,
     ));
     if (isRecord(candidate.delivery)) {
@@ -1281,7 +1337,7 @@ export const validateResolvedSecretManifest = (
       } else if (
         candidate.delivery.type === 'file'
         && typeof candidate.delivery.targetPath === 'string'
-        && validateSecretDelivery(candidate.delivery).length === 0
+        && validateSecretResolvedDelivery(candidate.delivery).length === 0
       ) {
         fileDeliveryTargets.push(candidate.delivery.targetPath);
       }
@@ -1584,7 +1640,7 @@ export const createWorkloadInitEnvironmentMap = async (
     .map(async (entryArg) => {
       const resource = await createDockerSecretResourceName(entryArg.secretVersionId);
       return {
-        variableName: (entryArg.delivery as ISecretLauncherEnvironmentDelivery).variableName,
+        variableName: (entryArg.delivery as ISecretResolvedLauncherEnvironmentDelivery).variableName,
         resource,
         source: createLauncherSecretSourcePath(resource),
       };
@@ -1818,6 +1874,8 @@ const canonicalSecretOwner = (ownerArg: TSecretOwner): Record<string, string> =>
   }
 };
 
+// A launcher delivery that still states the deprecated owner keeps the context it was sealed
+// under; JSON leaves an absent owner out.
 const canonicalSecretDelivery = (deliveryArg: TSecretDelivery): Record<string, unknown> => (
   deliveryArg.type === 'launcher-environment'
     ? {