@serve.zone/interfaces 32.60.0 → 32.62.0

package/dist_ts/data/workloadreplicaidentity.d.ts

@@ -0,0 +1,101 @@
+import type { TSha256Digest } from './immutableimage.js';
+import type { IRuntimeAssignment } from './runtimeassignment.js';
+import type { TServiceRuntimeRefusal } from './serviceruntime.js';
+/**
+ * Which replica of which workload a process is, as its runtime states it.
+ *
+ * Every member is the runtime assignment's own (`buildWorkloadReplicaIdentity`), so a workload, its
+ * runtime and its controller name a replica with the same four values. `attemptId` is the one
+ * execution attempt: a rollout, a replacement or a restart onto another attempt is a new attempt,
+ * so the attempt is what a workload reports to correlate itself with the controller's roster.
+ */
+export interface IWorkloadReplicaIdentity {
+    /** The service the replica runs (`IRuntimeAssignment.serviceId`). */
+    serviceId: string;
+    /** The stable logical replica (`IRuntimeAssignment.replicaId`), a `isRuntimeReplicaId` name. */
+    replicaId: string;
+    /** The one execution attempt (`IRuntimeAssignment.attemptId`). */
+    attemptId: string;
+    /** The root descriptor digest the replica runs (`IRuntimeAssignment.workload.imageDigest`). */
+    imageDigest: TSha256Digest;
+}
+/**
+ * The environment variable names every runtime injects into every workload it runs, one per
+ * identity member. The one spelling Pallet, Onebox, Cloudly's composition refusal and every
+ * workload that reads its identity share.
+ */
+export declare const workloadReplicaIdentityEnvironmentNames: Readonly<{
+    readonly serviceId: 'SERVEZONE_WORKLOAD_SERVICE_ID';
+    readonly replicaId: 'SERVEZONE_WORKLOAD_REPLICA_ID';
+    readonly attemptId: 'SERVEZONE_WORKLOAD_ATTEMPT_ID';
+    readonly imageDigest: 'SERVEZONE_WORKLOAD_IMAGE_DIGEST';
+}>;
+export type TWorkloadReplicaIdentityEnvironmentName = typeof workloadReplicaIdentityEnvironmentNames[keyof IWorkloadReplicaIdentity];
+/**
+ * The bounds the injection adds to a runtime config's own.
+ *
+ * `IRuntimeConfig.environment` keeps its own bound (`runtimeConfigContract.maximumEnvironmentEntries`),
+ * so a service states at most that many entries. A runtime's executor admits the config's entries
+ * plus the injected identity, `maximumExecutorEnvironmentEntries`, computed from both, never a
+ * literal of its own.
+ */
+export declare const workloadReplicaIdentityContract: Readonly<{
+    injectedEnvironmentEntries: number;
+    maximumExecutorEnvironmentEntries: number;
+}>;
+/** Every reason a value is not exactly a workload replica identity; empty when it is one. */
+export declare const validateWorkloadReplicaIdentity: (valueArg: unknown) => string[];
+/** A detached, frozen copy of exactly a workload replica identity; throws naming every violation. */
+export declare const snapshotWorkloadReplicaIdentity: (valueArg: unknown) => IWorkloadReplicaIdentity;
+/**
+ * The identity of the replica one runtime assignment runs.
+ *
+ * Read from the assignment the runtime admitted, through its exact schema, so the answer always
+ * satisfies `validateWorkloadReplicaIdentity`. It proves nothing about the assignment's digest or
+ * admission; the runtime has judged those before it runs anything.
+ */
+export declare const buildWorkloadReplicaIdentity: (assignmentArg: IRuntimeAssignment) => IWorkloadReplicaIdentity;
+/**
+ * The injected names among `namesArg`, sorted and unique: empty when none collides.
+ *
+ * Cloudly's composition refusal passes the keys of a replica's effective environment together with
+ * the variable names of its launcher-environment secrets, because WorkloadInit sets a secret over a
+ * plain variable of the same name and so would replace the injected identity just as silently.
+ */
+export declare const findWorkloadReplicaIdentityEnvironmentConflicts: (namesArg: readonly string[]) => TWorkloadReplicaIdentityEnvironmentName[];
+/** The one reason a workload environment cannot carry its replica identity. */
+export type TWorkloadReplicaEnvironmentRefusal = Extract<TServiceRuntimeRefusal, 'workload-identity-environment-conflict'>;
+/** What a replica runs with, or the one reason its identity cannot be injected. */
+export type TWorkloadReplicaEnvironmentComposition = {
+    status: 'composed';
+    environment: Record<string, string>;
+} | {
+    status: 'refused';
+    reason: TWorkloadReplicaEnvironmentRefusal;
+    message: string;
+};
+/**
+ * The environment one replica runs with: its runtime config's environment with the replica's
+ * identity added under `workloadReplicaIdentityEnvironmentNames`.
+ *
+ * Every runtime injects the identity into every workload, whether the workload reads it or not. A
+ * config environment that already states one of the names is refused
+ * `workload-identity-environment-conflict`, naming every such key and none of their values, rather
+ * than having one value silently replace the other. The reason stays inside the runtime: only
+ * Cloudly states it on the wire, in a service's status. A Pallet reports the refused run as the
+ * existing `TRuntimeAssignmentFailureCause` `{ kind: 'refused', reason: 'invalid' }`, which every
+ * reader since 32.45.0 reads and a controller never re-places with an identical configuration. An
+ * identity that is not exactly one is the caller's error and is thrown. The inputs are not
+ * changed. A config within
+ * `runtimeConfigContract.maximumEnvironmentEntries` composes to at most
+ * `workloadReplicaIdentityContract.maximumExecutorEnvironmentEntries` entries.
+ */
+export declare const composeWorkloadReplicaEnvironment: (environmentArg: Readonly<Record<string, string>>, identityArg: IWorkloadReplicaIdentity) => TWorkloadReplicaEnvironmentComposition;
+/**
+ * The replica identity a workload reads from its own environment (`process.env`).
+ *
+ * Reads the four injected names only, as own data properties, and nothing else of the environment.
+ * Throws naming every name that is missing and every name whose value is not a valid member, never
+ * a value, so a workload refuses to start with the exact variable its runtime did not inject.
+ */
+export declare const readWorkloadReplicaIdentityEnvironment: (environmentArg: Readonly<Record<string, string | undefined>>) => IWorkloadReplicaIdentity;

package/dist_ts/data/workloadreplicaidentity.js

@@ -0,0 +1,159 @@
+import { isSha256Digest } from './immutableimage.js';
+import { isRuntimeReplicaId, snapshotRuntimeAssignment } from './runtimeassignment.js';
+import { runtimeConfigContract } from './runtimeconfig.js';
+import { hasExactKeys, readDataProperties } from '../private/dataproperties.js';
+/**
+ * The environment variable names every runtime injects into every workload it runs, one per
+ * identity member. The one spelling Pallet, Onebox, Cloudly's composition refusal and every
+ * workload that reads its identity share.
+ */
+export const workloadReplicaIdentityEnvironmentNames = Object.freeze({
+    serviceId: 'SERVEZONE_WORKLOAD_SERVICE_ID',
+    replicaId: 'SERVEZONE_WORKLOAD_REPLICA_ID',
+    attemptId: 'SERVEZONE_WORKLOAD_ATTEMPT_ID',
+    imageDigest: 'SERVEZONE_WORKLOAD_IMAGE_DIGEST',
+});
+const identityKeys = Object.freeze(Object.keys(workloadReplicaIdentityEnvironmentNames));
+const identityEnvironmentNames = Object.freeze(Object.values(workloadReplicaIdentityEnvironmentNames));
+/**
+ * The bounds the injection adds to a runtime config's own.
+ *
+ * `IRuntimeConfig.environment` keeps its own bound (`runtimeConfigContract.maximumEnvironmentEntries`),
+ * so a service states at most that many entries. A runtime's executor admits the config's entries
+ * plus the injected identity, `maximumExecutorEnvironmentEntries`, computed from both, never a
+ * literal of its own.
+ */
+export const workloadReplicaIdentityContract = Object.freeze({
+    injectedEnvironmentEntries: identityKeys.length,
+    maximumExecutorEnvironmentEntries: runtimeConfigContract.maximumEnvironmentEntries + identityKeys.length,
+});
+const isIdentifier = (valueArg) => typeof valueArg === 'string' && /^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/.test(valueArg);
+/** What each member must hold, in the runtime assignment's own vocabulary. */
+const memberRules = Object.freeze({
+    serviceId: { accepts: isIdentifier, requirement: 'a canonical identifier' },
+    replicaId: { accepts: isRuntimeReplicaId, requirement: 'a replica id' },
+    attemptId: { accepts: isIdentifier, requirement: 'a canonical identifier' },
+    imageDigest: {
+        accepts: (valueArg) => typeof valueArg === 'string' && isSha256Digest(valueArg),
+        requirement: 'a sha256 digest',
+    },
+});
+const judgeIdentity = (valueArg) => {
+    const record = readDataProperties(valueArg);
+    if (record === null) {
+        return { record, errors: ['workload replica identity must be a plain record of data properties'] };
+    }
+    const errors = [];
+    if (!hasExactKeys(record, identityKeys)) {
+        errors.push(`workload replica identity must state exactly ${identityKeys.join(', ')}`);
+    }
+    for (const key of identityKeys) {
+        if (Object.hasOwn(record, key) && !memberRules[key].accepts(record[key])) {
+            errors.push(`${key} must be ${memberRules[key].requirement}`);
+        }
+    }
+    return { record, errors };
+};
+/** Every reason a value is not exactly a workload replica identity; empty when it is one. */
+export const validateWorkloadReplicaIdentity = (valueArg) => judgeIdentity(valueArg).errors;
+/** A detached, frozen copy of exactly a workload replica identity; throws naming every violation. */
+export const snapshotWorkloadReplicaIdentity = (valueArg) => {
+    const { record, errors } = judgeIdentity(valueArg);
+    if (record === null || errors.length > 0) {
+        throw new Error(`workload replica identity refused: ${errors.join('; ')}`);
+    }
+    return Object.freeze({
+        serviceId: record.serviceId,
+        replicaId: record.replicaId,
+        attemptId: record.attemptId,
+        imageDigest: record.imageDigest,
+    });
+};
+/**
+ * The identity of the replica one runtime assignment runs.
+ *
+ * Read from the assignment the runtime admitted, through its exact schema, so the answer always
+ * satisfies `validateWorkloadReplicaIdentity`. It proves nothing about the assignment's digest or
+ * admission; the runtime has judged those before it runs anything.
+ */
+export const buildWorkloadReplicaIdentity = (assignmentArg) => {
+    const assignment = snapshotRuntimeAssignment(assignmentArg);
+    return Object.freeze({
+        serviceId: assignment.serviceId,
+        replicaId: assignment.replicaId,
+        attemptId: assignment.attemptId,
+        imageDigest: assignment.workload.imageDigest,
+    });
+};
+/**
+ * The injected names among `namesArg`, sorted and unique: empty when none collides.
+ *
+ * Cloudly's composition refusal passes the keys of a replica's effective environment together with
+ * the variable names of its launcher-environment secrets, because WorkloadInit sets a secret over a
+ * plain variable of the same name and so would replace the injected identity just as silently.
+ */
+export const findWorkloadReplicaIdentityEnvironmentConflicts = (namesArg) => identityEnvironmentNames
+    .filter((nameArg) => namesArg.includes(nameArg))
+    .sort();
+/**
+ * The environment one replica runs with: its runtime config's environment with the replica's
+ * identity added under `workloadReplicaIdentityEnvironmentNames`.
+ *
+ * Every runtime injects the identity into every workload, whether the workload reads it or not. A
+ * config environment that already states one of the names is refused
+ * `workload-identity-environment-conflict`, naming every such key and none of their values, rather
+ * than having one value silently replace the other. The reason stays inside the runtime: only
+ * Cloudly states it on the wire, in a service's status. A Pallet reports the refused run as the
+ * existing `TRuntimeAssignmentFailureCause` `{ kind: 'refused', reason: 'invalid' }`, which every
+ * reader since 32.45.0 reads and a controller never re-places with an identical configuration. An
+ * identity that is not exactly one is the caller's error and is thrown. The inputs are not
+ * changed. A config within
+ * `runtimeConfigContract.maximumEnvironmentEntries` composes to at most
+ * `workloadReplicaIdentityContract.maximumExecutorEnvironmentEntries` entries.
+ */
+export const composeWorkloadReplicaEnvironment = (environmentArg, identityArg) => {
+    const identity = snapshotWorkloadReplicaIdentity(identityArg);
+    const conflicts = findWorkloadReplicaIdentityEnvironmentConflicts(Object.keys(environmentArg));
+    if (conflicts.length > 0) {
+        return { status: 'refused', reason: 'workload-identity-environment-conflict',
+            message: `workload environment already states ${conflicts.join(', ')}, which the runtime injects` };
+    }
+    const injected = {};
+    for (const key of identityKeys) {
+        injected[workloadReplicaIdentityEnvironmentNames[key]] = identity[key];
+    }
+    return { status: 'composed', environment: { ...environmentArg, ...injected } };
+};
+/**
+ * The replica identity a workload reads from its own environment (`process.env`).
+ *
+ * Reads the four injected names only, as own data properties, and nothing else of the environment.
+ * Throws naming every name that is missing and every name whose value is not a valid member, never
+ * a value, so a workload refuses to start with the exact variable its runtime did not inject.
+ */
+export const readWorkloadReplicaIdentityEnvironment = (environmentArg) => {
+    const missing = [];
+    const invalid = [];
+    const identity = {};
+    for (const key of identityKeys) {
+        const name = workloadReplicaIdentityEnvironmentNames[key];
+        const descriptor = Object.getOwnPropertyDescriptor(environmentArg, name);
+        if (descriptor === undefined || !Object.hasOwn(descriptor, 'value') || typeof descriptor.value !== 'string') {
+            missing.push(name);
+        }
+        else if (!memberRules[key].accepts(descriptor.value)) {
+            invalid.push(name);
+        }
+        else {
+            identity[key] = descriptor.value;
+        }
+    }
+    if (missing.length > 0 || invalid.length > 0) {
+        throw new Error(`workload replica identity environment ${[
+            ...missing.length > 0 ? [`lacks ${missing.join(', ')}`] : [],
+            ...invalid.length > 0 ? [`states an invalid ${invalid.join(', ')}`] : [],
+        ].join('; ')}`);
+    }
+    return snapshotWorkloadReplicaIdentity(identity);
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoid29ya2xvYWRyZXBsaWNhaWRlbnRpdHkuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL3dvcmtsb2FkcmVwbGljYWlkZW50aXR5LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUNBLE9BQU8sRUFBRSxjQUFjLEVBQUUsTUFBTSxxQkFBcUIsQ0FBQztBQUVyRCxPQUFPLEVBQUUsa0JBQWtCLEVBQUUseUJBQXlCLEVBQUUsTUFBTSx3QkFBd0IsQ0FBQztBQUN2RixPQUFPLEVBQUUscUJBQXFCLEVBQUUsTUFBTSxvQkFBb0IsQ0FBQztBQUUzRCxPQUFPLEVBQUUsWUFBWSxFQUFFLGtCQUFrQixFQUFFLE1BQU0sOEJBQThCLENBQUM7QUFxQmhGOzs7O0dBSUc7QUFDSCxNQUFNLENBQUMsTUFBTSx1Q0FBdUMsR0FBRyxNQUFNLENBQUMsTUFBTSxDQUFDO0lBQ25FLFNBQVMsRUFBRSwrQkFBK0I7SUFDMUMsU0FBUyxFQUFFLCtCQUErQjtJQUMxQyxTQUFTLEVBQUUsK0JBQStCO0lBQzFDLFdBQVcsRUFBRSxpQ0FBaUM7Q0FDNkIsQ0FBQyxDQUFDO0FBSy9FLE1BQU0sWUFBWSxHQUFHLE1BQU0sQ0FBQyxNQUFNLENBQ2hDLE1BQU0sQ0FBQyxJQUFJLENBQUMsdUNBQXVDLENBQXVDLENBQzNGLENBQUM7QUFDRixNQUFNLHdCQUF3QixHQUFzQixNQUFNLENBQUMsTUFBTSxDQUMvRCxNQUFNLENBQUMsTUFBTSxDQUFDLHVDQUF1QyxDQUFDLENBQ3ZELENBQUM7QUFFRjs7Ozs7OztHQU9HO0FBQ0gsTUFBTSxDQUFDLE1BQU0sK0JBQStCLEdBQUcsTUFBTSxDQUFDLE1BQU0sQ0FBQztJQUMzRCwwQkFBMEIsRUFBRSxZQUFZLENBQUMsTUFBTTtJQUMvQyxpQ0FBaUMsRUFBRSxxQkFBcUIsQ0FBQyx5QkFBeUIsR0FBRyxZQUFZLENBQUMsTUFBTTtDQUN6RyxDQUFDLENBQUM7QUFFSCxNQUFNLFlBQVksR0FBRyxDQUFDLFFBQWlCLEVBQXNC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

package/dist_ts/requests/admin.d.ts

@@ -2,6 +2,7 @@ import * as plugins from '../plugins.js';
 import type { IIdentity, IIdentityCredential, IServiceDeploymentGrant } from '../data/user.js';
 import type { IServiceMachineCredentialMetadata, IServiceMachineCredentialMutationResult, TServiceMachineCredentialMutation } from '../data/servicecredential.js';
 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> {
     method: 'getServiceMachineCredential';
     request: {
@@ -175,3 +176,54 @@ 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/dist_ts/requests/coremail.d.ts

@@ -1,6 +1,7 @@
 import type * as plugins from '../plugins.js';
 import type { ICoreMailEnvelope, ICoreMailInboundDeliveryPage, ICoreMailDownloadGrant, ICoreMailGatewayMessageDescriptor, ICoreMailGatewayOutboundStatus, ICoreMailInboundDelivery, ICoreMailOutboundMessageDescriptor, ICoreMailRecipientResolution, ICoreMailReconciliationStatus, ICoreMailReplicaIdentity, ICoreMailServiceMailStatistics, ICoreMailSubmission, ICoreMailUploadGrant, TCoreMailInboundAckOutcome, TCoreMailSha256, TCoreMailWorkloadOperation } from '../data/coremail.js';
 import type { IMailConnectionInfo } from '../data/mail.js';
+import type { IWorkloadReplicaIdentity } from '../data/workloadreplicaidentity.js';
 export interface IReq_CoreMailAuthenticateWorkload extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_CoreMailAuthenticateWorkload> {
     method: 'coreMailAuthenticateWorkload';
     request: {
@@ -125,7 +126,11 @@ export interface IReq_CoreMailAuthenticateControl extends plugins.typedrequestIn
         authenticated: true;
         credentialId: string;
         credentialVersion: number;
-        replica: ICoreMailReplicaIdentity;
+        /**
+         * The authenticated replica: `IWorkloadReplicaIdentity` from CoreMail 34 on, the deprecated
+         * `ICoreMailReplicaIdentity` from an earlier CoreMail (`normalizeCoreMailReplicaIdentity`).
+         */
+        replica: IWorkloadReplicaIdentity | ICoreMailReplicaIdentity;
     };
 }
 export interface IReq_CoreMailPrepareDesiredStateUpload extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_CoreMailPrepareDesiredStateUpload> {

package/dist_ts/requests/identity.d.ts

@@ -2,6 +2,10 @@ import * as plugins from '../plugins.js';
 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<plugins.typedrequestInterfaces.ITypedRequest, IRequest_Any_Cloudly_CoreflowManager_GetIdentityByToken> {
     method: 'getIdentityByToken';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/interfaces",
-  "version": "32.60.0",
+  "version": "32.62.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.",
   "exports": {
@@ -27,10 +27,7 @@
     "@tsclass/tsclass": "^9.5.1"
   },
   "devDependencies": {
-    "@git.zone/tsbuild": "^6.0.2",
-    "@git.zone/tsdoc": "^3.0.2",
-    "@git.zone/tsrun": "^3.0.3",
-    "@git.zone/tstest": "^8.0.0",
+    "@git.zone/tsrepo": "^1.1.1",
     "@types/node": "26.6.5",
     "typescript": "^6.0.3"
   },
@@ -64,8 +61,8 @@
     "last 1 chrome versions"
   ],
   "scripts": {
-    "test": "tstest test/ --verbose --logfile --timeout 60",
-    "build": "tsbuild tsfolders",
-    "buildDocs": "tsdoc"
+    "test": "tsrepo test test/ --verbose --logfile --timeout 60",
+    "build": "tsrepo build tsfolders",
+    "buildDocs": "tsrepo docs"
   }
 }

package/readme.md

@@ -1370,6 +1370,60 @@ Version 29 widens these numeric TypeScript fields to include those explicit null
 policies; consumers must handle them before accepting configurations from v29.
 Existing numeric configurations retain their exact meaning and digest.
 
+### Workload Replica Identity
+
+Every runtime (Pallet, Onebox) injects the identity of the replica it runs into every workload,
+whether the workload reads it or not. `data.IWorkloadReplicaIdentity` is exactly
+`{ serviceId, replicaId, attemptId, imageDigest }`, the runtime assignment's own values:
+`data.buildWorkloadReplicaIdentity(assignment)` reads them from the admitted assignment through its
+exact schema, so the answer always validates. `attemptId` is the one execution attempt; a rollout or
+a replacement is a new attempt, and the controller's `attemptId` already binds the admitting
+rollout, so no rollout name or generation travels. `data.validateWorkloadReplicaIdentity` names
+every violation and `data.snapshotWorkloadReplicaIdentity` answers a detached frozen copy or throws.
+
+`data.workloadReplicaIdentityEnvironmentNames` is the one spelling of the injected names:
+`SERVEZONE_WORKLOAD_SERVICE_ID`, `SERVEZONE_WORKLOAD_REPLICA_ID`, `SERVEZONE_WORKLOAD_ATTEMPT_ID` and
+`SERVEZONE_WORKLOAD_IMAGE_DIGEST`. They sit under the platform-reserved `SERVEZONE_` prefix
+(`platformReservedSecretKeyPrefixes`). A runtime composes what a replica runs with through
+`data.composeWorkloadReplicaEnvironment(configEnvironment, identity)`: the config's environment
+with the four names added, or `refused` with `workload-identity-environment-conflict` and a message
+naming every colliding key and no value (`TWorkloadReplicaEnvironmentComposition`). An identity that
+is not exactly one is thrown. A workload reads its identity with
+`data.readWorkloadReplicaIdentityEnvironment(process.env)`, which reads the four names only and
+throws naming every missing or invalid variable, never a value, so a workload refuses to start
+naming the variable its runtime did not inject.
+
+Cloudly refuses a service whose effective environment (image and service values) or one of whose
+launcher-environment secrets states an injected name, before any runtime sees it:
+`data.findWorkloadReplicaIdentityEnvironmentConflicts(names)` answers the colliding names among
+the environment's keys and the secrets' variable names, and the service's status reads
+`workload-identity-environment-conflict`. Secrets count because WorkloadInit sets a secret over a
+plain variable of the same name.
+
+Only Cloudly states `workload-identity-environment-conflict` on the wire, in the service status it
+stores and answers on `getServiceRuntimeSpec`, `getServiceRuntimeSpecForCluster` and
+`getServiceRuntimeSpecs`. Those requests carry no protocol offer, so the reason cannot be gated on
+a reader's version, and no other refusal names this check. A reader built before the interfaces
+release that introduced this contract refuses such a status whole, so every client that reads
+statuses moves to that release before Cloudly does, and a Cloudly that has stored one is not rolled
+back below it. A node never states the reason: a Pallet whose composition refuses (only a Cloudly
+before this contract places such a run) reports the run as the existing
+`TRuntimeAssignmentFailureCause` `{ kind: 'refused', reason: 'invalid' }`, which every reader since
+32.45.0 reads and a controller never re-places with an identical configuration.
+
+`IRuntimeConfig.environment` keeps its bound, `runtimeConfigContract.maximumEnvironmentEntries`
+(128). A runtime's executor admits the config's entries plus the injected ones:
+`data.workloadReplicaIdentityContract.maximumExecutorEnvironmentEntries`, computed as that bound
+plus `injectedEnvironmentEntries` (4), never a literal of the runtime's own. Pallet's native
+invocation check (`rust/src/execution.rs`, today a literal 128) admits exactly this value, and its
+TypeScript execution owner hands the composed environment to it in place of `config.environment`.
+
+Injection is gated by the release, not per peer: a Pallet moves to the interfaces release that
+introduced this contract together with the injection, so a Pallet speaking it injects. Cloudly
+raises the `minimumPeerVersion` of its Pallet runtime sessions to that release (peers first, see
+`IProtocolOffer`) in the commit that first deploys a workload requiring its identity, such as
+CoreMail 34. No controller or runtime keeps a per-version send branch.
+
 ### Authenticated Runtime Sessions
 
 `requests.runtimesession` defines `registerPalletRuntimeSession`,
@@ -2106,7 +2160,8 @@ evidence has not arrived). `refused` carries a `TServiceRuntimeRefusal`:
 `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`.
+`cluster-relay-missing`, `cluster-ingress-environment-conflict` or
+`workload-identity-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
@@ -2123,7 +2178,10 @@ designated ingress service, whose environment `composeClusterIngressEnvironment`
 [Cluster Ingress](#cluster-ingress): `cluster-relay-missing` is a cluster that states no valid
 relay, which an administrator enables with `enableClusterRelay`, and
 `cluster-ingress-environment-conflict` an ingress service whose own environment already sets one of
-`clusterIngressEnvironmentNames`. `ports-too-many` is a service declaring more target ports than the
+`clusterIngressEnvironmentNames`. `workload-identity-environment-conflict` is a service whose
+effective environment, or one of whose launcher-environment secrets, states one of the names every
+runtime injects, see [Workload Replica Identity](#workload-replica-identity), which also states why
+every reader of statuses moves to its release before Cloudly does. `ports-too-many` is a service declaring more target ports than the
 `runtimeConfigContract.maximumTargetPorts` (64) a config carries, where `port-protocol-unsupported`
 is about one port's protocol; `node-authority-unsupported` is a node whose session resolved fewer
 workload authorities than the spec needs, refused at the admit step rather than handed to a node
@@ -4158,11 +4216,70 @@ per-task authentication and readiness, then mark the previous verifier
 `retiring` with `acceptUntil`. Remove the previous verifier and secret only
 after its acceptance window has elapsed and no session uses that composite
 credential identity.
-Reconciliation status carries the exact CoreMail task, rollout generation, and
-image digest so Coreflow can correlate every response with its authoritative
-current task roster. Apply `data.normalizeCoreMailReconciliationStatus` before
-using pending-inbound or composite active-session counts for drain and rotation
-decisions.
+Reconciliation status and the `coreMailAuthenticateControl` response carry the
+reporting replica so Coreflow can correlate every response with its
+authoritative current roster. CoreMail 34 and later report
+`data.IWorkloadReplicaIdentity` (`serviceId`, `replicaId`, `attemptId`,
+`imageDigest`), the identity its runtime injects; the attempt is what the roster
+correlates by. A CoreMail before 34 reports the deprecated
+`data.ICoreMailReplicaIdentity` (`taskId`, `serviceId`, `rolloutId`,
+`rolloutGeneration`, `imageDigest`), whose `taskId` is that attempt. Both types
+accept either shape, and `data.normalizeCoreMailReplicaIdentity` reads each
+exactly: a record stating `taskId` is the deprecated shape, any other the
+workload identity, and neither admits a member of the other. The deprecated
+shape is removed in the next major. Apply
+`data.normalizeCoreMailReconciliationStatus` before using pending-inbound or
+composite active-session counts for drain and rotation decisions.
+
+#### CoreMail runtime environment (CoreMail 34 and later)
+
+CoreMail 34 reads:
+
+- its replica identity from `data.workloadReplicaIdentityEnvironmentNames`
+  (`SERVEZONE_WORKLOAD_SERVICE_ID`, `SERVEZONE_WORKLOAD_REPLICA_ID`,
+  `SERVEZONE_WORKLOAD_ATTEMPT_ID`, `SERVEZONE_WORKLOAD_IMAGE_DIGEST`) through
+  `data.readWorkloadReplicaIdentityEnvironment`, and refuses to start naming a
+  missing variable;
+- its database and object storage under the names its platform bindings deliver,
+  `data.coreMailStorageEnvironmentNames`: `MONGODB_URL` and `MONGODB_DATABASE`
+  (the Corestore database binding), `S3_ENDPOINT`, `S3_REGION` and `S3_BUCKET`
+  (the object-storage binding) and `S3_ACCESS_KEY` and `S3_SECRET_KEY` (that
+  binding's credential secrets);
+- `COREMAIL_CONTROL_BOOTSTRAP` (`data.coreMailRuntimeKeys.controlBootstrap`), and
+  optionally `COREMAIL_PORT`, `COREMAIL_HOSTNAMES` and
+  `COREMAIL_MONGODB_MAX_POOL_SIZE` (`port`, `hostnames`, `mongoDbMaxPoolSize`);
+- the secrets its desired state references by name, as before.
+
+It no longer reads `COREMAIL_SERVICE_ID`, `COREMAIL_TASK_ID`,
+`COREMAIL_ROLLOUT_ID`, `COREMAIL_ROLLOUT_GENERATION`, `COREMAIL_IMAGE_DIGEST`,
+`COREMAIL_MONGODB_URL`, `COREMAIL_MONGODB_NAME`, `COREMAIL_STORAGE_DESCRIPTOR`
+or `COREMAIL_BUCKET_NAME`, and a provisioner stops writing them. CoreMail 34
+runs only on a runtime that injects its identity, see
+[Workload Replica Identity](#workload-replica-identity).
+
+Readers first. A reader built before the interfaces release that introduced
+`data.IWorkloadReplicaIdentity` refuses CoreMail 34's replica whole, in the
+`coreMailAuthenticateControl` response and in reconciliation status alike: its
+`normalizeCoreMailReplicaIdentity` requires `taskId`, `rolloutId` and
+`rolloutGeneration`. The `minimumPeerVersion` of Pallet runtime sessions does not
+reach these readers, so the order is fixed: `@serve.zone/api`'s
+`CoreMailControlClient`, and with it Cloudly's CoreMail manager and Onebox's
+CoreMail provider, move to that interfaces release before any CoreMail 34 runs.
+Cloudly deploys CoreMail 34 only once its own reader is on that release, and
+Onebox moves its CoreMail pin to 34 only in the release that carries the
+upgraded reader. A CoreMail before 34 keeps writing the deprecated shape, which
+every reader reads as before.
+
+In source, both carrying types and the normalizer's return value are
+`data.IWorkloadReplicaIdentity | data.ICoreMailReplicaIdentity`, a type-level
+change shipped in a 32.x minor. The consumers that read the replica,
+`@serve.zone/api` (`CoreMailControlClient`), Cloudly (CoreMail manager), Onebox
+(CoreMail provider) and CoreMail, narrow by `taskId`:
+
+```typescript
+const replica = data.normalizeCoreMailReplicaIdentity(response.replica);
+const attemptId = 'taskId' in replica ? replica.taskId : replica.attemptId;
+```
 
 #### CoreMail control-plane settings and operator RPCs
 
@@ -4276,6 +4393,35 @@ request fence, and the trusted local organization/cluster expectation. It never
 decrypts. Organization and cluster are derived from the verified cluster JWT
 and cannot be selected by request fields.
 
+### Service Mail Environment
+
+`data.serviceMailEnvironmentNames` spells the environment a service's default
+sender is delivered under, once for the provisioners (Cloudly, Onebox) and the
+reader (`@serve.zone/platformclient`). It has three groups, each delivered
+whole: the typed dcrouter-direct binding (`MAIL_FROM`, `MAIL_TYPED_URL`,
+`MAIL_API_CREDENTIAL_ID`, `MAIL_API_CREDENTIAL_SECRET`), its SMTP compatibility
+surface (`SMTP_HOST`, `SMTP_PORT`, `SMTP_TLS_MODE`, `SMTP_USERNAME`,
+`SMTP_PASSWORD`) and a CoreMail binding (`MAIL_COREMAIL_URL`,
+`MAIL_COREMAIL_BINDING_ID`, `MAIL_COREMAIL_CREDENTIAL_ID`,
+`MAIL_COREMAIL_CREDENTIAL_VERSION`, `MAIL_COREMAIL_CREDENTIAL_SECRET`, with
+`MAIL_FROM`). The credential secrets and passwords are delivered as secrets.
+`data.createServiceMailAddressEnvironmentNames(token)` answers the same names
+for a further sender address, scoped to its upper-case address token
+(`MAIL_<TOKEN>_FROM`, `MAIL_<TOKEN>_TYPED_URL`, `MAIL_<TOKEN>_SMTP_HOST`,
+`MAIL_<TOKEN>_COREMAIL_URL`, …); any other token is thrown.
+
+`MAIL_TYPED_URL` and every `MAIL_<TOKEN>_TYPED_URL` carry
+`ICloudlySettings.dcrouterMailEndpointUrl`, the canonical HTTPS URL of
+dcrouter's tenant mail listener, and nothing else: never `dcrouterGatewayUrl`,
+which is Cloudly's own gateway-client endpoint, and never a CoreMail endpoint,
+which travels as `MAIL_COREMAIL_URL`. `data.validateDcrouterMailEndpointUrl`
+accepts an `https:` URL without credentials, query or fragment, at most
+`data.dcrouterMailEndpointUrlMaximumLength` (2,048) characters, written exactly
+as `new URL(value).href` spells it, and names every violation without quoting
+the value. When the setting is absent, Cloudly refuses to provision a typed
+dcrouter-direct mail binding and names `dcrouterMailEndpointUrl` in the refusal;
+it falls back to no other endpoint.
+
 ### Corestore Runtime Credentials
 
 The Node-only `/runtime` export defines
@@ -4845,7 +4991,7 @@ pnpm test
 pnpm run buildDocs
 ```
 
-The package is authored as ESM TypeScript and built with `tsbuild tsfolders`.
+The package is authored as ESM TypeScript and built with `tsrepo build tsfolders`.
 
 ## License and Legal Information
 

package/ts/00_commitinfo_data.ts

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