@serve.zone/interfaces 32.59.0 → 32.61.0

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,50 @@ 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;
+
+/**
+ * Prefixes of the names the platform injects into a workload itself (`SERVEZONE_*`): a secret of
+ * such a name would replace what the platform delivers.
+ */
+export const platformReservedSecretKeyPrefixes = Object.freeze(['SERVEZONE_'] as const);
+
+/**
+ * Prefixes of the names a loader, language runtime, package manager or library reads to change
+ * what a process loads, runs or trusts (`LD_PRELOAD`, `NODE_OPTIONS`, `PYTHONPATH`, `OPENSSL_CONF`,
+ * `DOTNET_STARTUP_HOOKS`, `NPM_CONFIG_REGISTRY`, …). Matched as plain prefixes, so `PYTHON`, `PERL`,
+ * `RUBY` and `PHP` cover every name that starts with them.
+ */
+export const runtimeInjectionSecretKeyPrefixes = Object.freeze([
+  'LD_', 'DYLD_', 'NODE_', 'DENO_', 'BUN_', 'PYTHON', 'PERL', 'RUBY', 'PHP', 'JAVA_', 'JDK_', '_JAVA_', 'DOTNET_',
+  'CORECLR_', 'LUA_', 'GEM_', 'BUNDLE_', 'NPM_CONFIG_', 'PIP_', 'GLIBC_', 'MALLOC_', 'GCONV_', 'OPENSSL_', 'SSL_',
+  'CURL_', 'REQUESTS_', 'GIT_',
+] as const);
+
+/**
+ * Exact names a shell, loader, runtime or HTTP client reads to change where a process looks,
+ * connects or what it trusts or records (`CLASSPATH`, `AWS_CA_BUNDLE`, `SSLKEYLOGFILE`).
+ */
+export const runtimeInjectionSecretKeys = Object.freeze([
+  'PATH', 'HOME', 'SHELL', 'ENV', 'BASH_ENV', 'IFS', 'TMPDIR', 'LOCPATH', 'NLSPATH', 'CLASSPATH', 'HTTP_PROXY',
+  'HTTPS_PROXY', 'ALL_PROXY', 'NO_PROXY', 'FTP_PROXY', 'AWS_CA_BUNDLE', 'SSLKEYLOGFILE',
+] as const);
+
+/**
+ * Whether a secret key, or a name a secret is delivered under, is reserved: one of
+ * `runtimeInjectionSecretKeys`, or starting with an entry of `platformReservedSecretKeyPrefixes`
+ * or `runtimeInjectionSecretKeyPrefixes`. A delegated administrator token never writes such a name.
+ */
+export const isReservedSecretKey = (keyArg: string): boolean => (
+  (runtimeInjectionSecretKeys as readonly string[]).includes(keyArg)
+  || platformReservedSecretKeyPrefixes.some((prefixArg) => keyArg.startsWith(prefixArg))
+  || runtimeInjectionSecretKeyPrefixes.some((prefixArg) => keyArg.startsWith(prefixArg))
+);
+
 export const secretValueLimits = Object.freeze({
   maximumBytes: 500 * 1024,
   minimumGeneratedBytes: 16,
@@ -299,7 +367,7 @@ export interface IResolvedSecretManifestEntry {
   key: string;
   environment: TSecretEnvironment;
   owner: TWorkloadSecretOwner;
-  delivery: TSecretDelivery;
+  delivery: TSecretResolvedDelivery;
 }
 
 /** Immutable, value-free runtime snapshot. */
@@ -709,14 +777,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 +800,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 +814,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 +1363,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 +1375,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 +1678,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 +1912,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'
     ? {

package/ts/data/serviceruntime.ts

@@ -89,6 +89,7 @@ const serviceRuntimeRefusals = [
   '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',
+  'launcher-secret-ownership-unknown',
   'objectstorage-endpoint-missing', 'objectstorage-binding-invalid', 'objectstorage-environment-conflict',
   'objectstorage-endpoint-unselected', 'database-endpoint-missing', 'database-endpoint-unselected',
   'published-port-reserved', 'published-port-symmetric-without-egress', 'readiness-network-unsupported',
@@ -128,11 +129,18 @@ export type TServiceRuntimeWaitingReason = typeof serviceRuntimeWaitingReasons[n
  * `volume-ownership-unknown` a `run-as` ownership under `runAs: null`
  * (`deriveServiceVolumeClaimInitialization`); neither is defaulted.
  *
+ * `launcher-secret-ownership-unknown` is a service with launcher-environment secrets whose runtime
+ * spec runs the image's own user (`runAs: null`) while that user's numeric owner is not known: a
+ * named non-root user, a numeric part above the identity bound, a group a `0o440` delivery would grant that the image does not state
+ * numerically, or platforms of the pinned index that derive different owners
+ * (`deriveLauncherSecretDeliveryOwner`). WorkloadInit could not read secret files owned by a guess.
+ *
  * The object-storage refusals name why a binding's environment cannot be composed
  * (`composeObjectStorageServiceEnvironment`): `objectstorage-endpoint-missing` a binding whose node
  * states no valid `corestoreObjectStorage`, `objectstorage-binding-invalid` a binding
  * `createObjectStorageBindingEnvironment` refuses, and `objectstorage-environment-conflict` a name
- * the service's own environment or another binding already sets.
+ * the service's own environment, one of its launcher-environment secrets or another binding already
+ * sets.
  *
  * `database-endpoint-missing` is an enabled database binding placed on a node that states no valid
  * `corestoreDatabase`: its credential cannot be addressed to any host a workload reaches, so it is

package/ts/platform/objectstorageenvironment.ts

@@ -201,10 +201,17 @@ const findEnvironmentCollisions = (
   keysArg: readonly string[],
 ): string[] => keysArg.filter((keyArg) => claimedKeysArg.has(keyArg)).sort();
 
-const describeEnvironmentCollisions = (collisionsArg: readonly string[]): string => (
-  `objectstorage binding environment collides with ${collisionsArg.join(', ')} already set on the `
-    + 'workload'
-);
+const describeEnvironmentCollisions = (
+  collisionsArg: readonly string[],
+  secretNamesArg: ReadonlySet<string> = new Set(),
+): string => {
+  const secretCollisions = collisionsArg.filter((keyArg) => secretNamesArg.has(keyArg));
+  return `objectstorage binding environment collides with ${collisionsArg.join(', ')} already set on `
+    + 'the workload' + (secretCollisions.length > 0
+      ? `; ${secretCollisions.join(', ')} reaches it as a launcher-environment secret, which would `
+        + 'replace the binding\'s value'
+      : '');
+};
 
 /**
  * A workload environment with one binding's environment added.
@@ -252,8 +259,8 @@ export type TObjectStorageEnvironmentWaitingReason = Extract<
  * `corestoreObjectStorage`; `objectstorage-binding-invalid` a binding
  * `createObjectStorageBindingEnvironment()` refuses (not `objectstorage`, no canonical bucket, no
  * canonical retention intent, or evidence that does not prove this binding);
- * `objectstorage-environment-conflict` a name the service's own environment or another binding
- * already sets.
+ * `objectstorage-environment-conflict` a name the service's own environment, one of its
+ * launcher-environment secrets or another binding already sets.
  */
 export type TObjectStorageEnvironmentRefusal = Extract<
   TServiceRuntimeRefusal,
@@ -285,16 +292,27 @@ export type TObjectStorageServiceEnvironmentComposition =
  * already claims all twenty of its names, so a collision with it is refused now, not once its
  * evidence arrives. The first refusal is answered, otherwise the first wait, otherwise the
  * composed environment. The inputs are not changed.
+ *
+ * `secretEnvironmentNamesArg` names the variables the workload receives as launcher-environment
+ * secrets (each `ISecretResolvedLauncherEnvironmentDelivery.variableName` of its desired
+ * manifest), names only, never a value. The launcher sets a secret over a plain variable of the same name, so a
+ * secret named like one of a binding's names would silently replace the binding's value: such a
+ * name claims the binding's name exactly as the service's own environment does, and is refused as
+ * `objectstorage-environment-conflict`. A secret by any other name is not this composition's
+ * concern, and neither are a binding's credential names (`corestoreObjectStorageCredentialSecretKeys`),
+ * which the binding itself delivers as secrets and never as plain names.
  */
 export const composeObjectStorageServiceEnvironment = async (
   serviceEnvironmentArg: Readonly<Record<string, string>>,
   sourcesArg: readonly IObjectStorageBindingEnvironmentSource[],
+  secretEnvironmentNamesArg: readonly string[] = [],
 ): Promise<TObjectStorageServiceEnvironmentComposition> => {
   const sources = [...sourcesArg].sort((leftArg, rightArg) => (
     leftArg.binding.id < rightArg.binding.id ? -1 : leftArg.binding.id > rightArg.binding.id ? 1 : 0
   ));
   let environment: Record<string, string> = { ...serviceEnvironmentArg };
-  const claimedKeys = new Set(Object.keys(environment));
+  const secretNames: ReadonlySet<string> = new Set(secretEnvironmentNamesArg);
+  const claimedKeys = new Set([...Object.keys(environment), ...secretNames]);
   let wait: Extract<TObjectStorageServiceEnvironmentComposition, { status: 'waiting' }> | null = null;
   for (const source of sources) {
     const bindingId = source.binding.id;
@@ -308,7 +326,7 @@ export const composeObjectStorageServiceEnvironment = async (
     const collisions = findEnvironmentCollisions(claimedKeys, keys);
     if (collisions.length > 0) {
       return { status: 'refused', reason: 'objectstorage-environment-conflict', bindingId,
-        message: describeEnvironmentCollisions(collisions) };
+        message: describeEnvironmentCollisions(collisions, secretNames) };
     }
     for (const key of keys) claimedKeys.add(key);
     if (resolution.status === 'composed') {

package/ts/requests/admin.ts

@@ -8,6 +8,9 @@ import type {
   IDeploymentMachineUserMetadata, IDeploymentMachineUserMutationResult,
   TDeploymentMachineUserMutation,
 } from '../data/deploymentmachineuser.js';
+import type {
+  IDelegatedAdminTokenMetadata, IDelegatedAdminTokenMint, IDelegatedAdminTokenMintResult,
+} from '../data/delegatedadmintoken.js';
 
 export interface IReq_Admin_GetServiceMachineCredential extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest, IReq_Admin_GetServiceMachineCredential
@@ -198,3 +201,51 @@ export interface IReq_Cloudly_Coreflow_ReconcileBaseServices extends plugins.typ
     routingProof?: ICoreflowRoutingProofResult;
   };
 }
+
+/**
+ * Mints one delegated admin token (`delegatedAdminTokenContract`) for what the request states
+ * (`IDelegatedAdminTokenMint`: its scopes, optional `lifetimeMs` and `secretKeyPrefixes`). Requires
+ * a human administrator who signed in within five minutes; a delegated session is refused. The
+ * plaintext token is answered on this answer only and is never retrievable again, so the request is
+ * sent once and its answer goes past every traffic hook. `lifetimeMs` absent is
+ * `defaultLifetimeMs`; Cloudly refuses any lifetime above `maximumLifetimeMs`. Refusals travel as
+ * `IDelegatedAdminTokenErrorData`.
+ */
+export interface IReq_Admin_MintDelegatedAdminToken extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Admin_MintDelegatedAdminToken
+> {
+  method: 'mintDelegatedAdminToken';
+  request: { identity: IIdentityCredential } & IDelegatedAdminTokenMint;
+  response: IDelegatedAdminTokenMintResult;
+}
+
+/**
+ * Lists the active delegated admin tokens, value-free, newest first: not expired, not revoked,
+ * and their administrator still a human administrator at the credential generation each was
+ * minted under. At most `delegatedAdminTokenContract.maximumListedTokens` are answered;
+ * `truncated` is true exactly when active tokens beyond them were left out, so no token that
+ * needs revoking is hidden without notice. Requires an administrator; a delegated session is
+ * refused. Refusals travel as `IDelegatedAdminTokenErrorData`.
+ */
+export interface IReq_Admin_GetDelegatedAdminTokens extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Admin_GetDelegatedAdminTokens
+> {
+  method: 'getDelegatedAdminTokens';
+  request: { identity: IIdentityCredential };
+  response: { tokens: IDelegatedAdminTokenMetadata[]; truncated: boolean };
+}
+
+/**
+ * Revokes one active delegated admin token; once the revocation commits, no use of the token
+ * commits after it, and every session exchanged for it is refused. A success has committed.
+ * Requires an administrator, the minting one or any other; a delegated session is refused.
+ * Refusals travel as `IDelegatedAdminTokenErrorData`: a token that already does not act (revoked,
+ * expired, or its administrator's credential or role changed) is `DELEGATED_ADMIN_TOKEN_INACTIVE`.
+ */
+export interface IReq_Admin_RevokeDelegatedAdminToken extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Admin_RevokeDelegatedAdminToken
+> {
+  method: 'revokeDelegatedAdminToken';
+  request: { identity: IIdentityCredential; tokenId: string };
+  response: { metadata: IDelegatedAdminTokenMetadata };
+}

package/ts/requests/externalregistry.ts

@@ -12,7 +12,7 @@ export interface IReq_GetRegistryById extends plugins.typedrequestInterfaces.imp
     id: string;
   };
   response: {
-    registry: data.IExternalRegistry;
+    registry: data.IExternalRegistryPublic;
   };
 }
 
@@ -25,7 +25,7 @@ export interface IReq_GetRegistries extends plugins.typedrequestInterfaces.imple
     identity: userInterfaces.IIdentity;
   };
   response: {
-    registries: data.IExternalRegistry[];
+    registries: data.IExternalRegistryPublic[];
   };
 }
 
@@ -39,7 +39,7 @@ export interface IReq_CreateRegistry extends plugins.typedrequestInterfaces.impl
     registryData: data.IExternalRegistry['data'];
   };
   response: {
-    registry: data.IExternalRegistry;
+    registry: data.IExternalRegistryPublic;
   };
 }
 
@@ -51,10 +51,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;
   };
 }
 
@@ -82,8 +86,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/ts/requests/identity.ts

@@ -7,6 +7,10 @@ import * as userInterfaces from '../data/user.js'
 
 /**
  * get the identity that then will be used to get the config
+ *
+ * A delegated admin token (`delegatedAdminTokenContract`) is exchanged here too. Its identity is
+ * `type: 'machine'`, `role: 'api'`, `userId: 'delegated-admin-token:<tokenId>'`, expiring with the
+ * token; only the requests of the token's scopes admit it, and each re-reads the token.
  */
 export interface IRequest_Any_Cloudly_CoreflowManager_GetIdentityByToken
 extends plugins.typedrequestInterfaces.implementsTR<

package/ts/requests/service.ts

@@ -455,7 +455,22 @@ extends plugins.typedrequestInterfaces.implementsTR<
   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;