@serve.zone/interfaces 32.60.0 → 32.62.0

package/ts/data/coremail.runtime.ts

@@ -48,6 +48,10 @@ import {
   type TCoreMailWorkloadOperation,
 } from './coremail.js';
 import type { IMailConnectionInfo } from './mail.js';
+import {
+  validateWorkloadReplicaIdentity,
+  type IWorkloadReplicaIdentity,
+} from './workloadreplicaidentity.js';
 
 export const coreMailCanonicalJsonRules = strictCanonicalJsonRules;
 
@@ -1889,11 +1893,32 @@ export const normalizeCoreMailDesiredState = (
   return deepFreezeValue(normalized);
 };
 
+/**
+ * The replica a CoreMail reports, read exactly as one of two closed shapes.
+ *
+ * CoreMail 34 and later report `IWorkloadReplicaIdentity`, the identity its runtime injects, and
+ * it is read by that contract's own rules (`validateWorkloadReplicaIdentity`). A CoreMail before
+ * 34 reports the deprecated `ICoreMailReplicaIdentity`, recognised by its `taskId`, and it is read
+ * as before. Neither shape admits a member of the other.
+ */
 export const normalizeCoreMailReplicaIdentity = (
   valueArg: unknown,
   pathArg = 'replica',
-): ICoreMailReplicaIdentity => {
+): IWorkloadReplicaIdentity | ICoreMailReplicaIdentity => {
   const record = readRecord(valueArg, pathArg);
+  if (!Object.hasOwn(record, 'taskId')) {
+    assertKeys(record, pathArg, ['serviceId', 'replicaId', 'attemptId', 'imageDigest']);
+    const errors = validateWorkloadReplicaIdentity(record);
+    if (errors.length > 0) {
+      fail(`${pathArg}.${errors[0]}`);
+    }
+    return deepFreezeValue({
+      serviceId: record.serviceId as string,
+      replicaId: record.replicaId as string,
+      attemptId: record.attemptId as string,
+      imageDigest: record.imageDigest as IWorkloadReplicaIdentity['imageDigest'],
+    });
+  }
   assertKeys(
     record,
     pathArg,

package/ts/data/coremail.ts

@@ -7,6 +7,10 @@
  * binding authority.
  */
 
+import type { IWorkloadReplicaIdentity } from './workloadreplicaidentity.js';
+import type { TCorestoreDatabaseCredentialKey, TCorestoreObjectStorageCredentialSecretKey } from '../runtime.corestore.js';
+import type { TObjectStorageEndpointEnvironmentKey } from '../platform/objectstorage.js';
+
 export type TCoreMailSha256 = `sha256:${string}`;
 
 export type TCoreMailCapability = 'outbound' | 'inbound';
@@ -293,6 +297,15 @@ export interface ICoreMailDesiredState {
   cursorKeys: ICoreMailRuntimeKeyReference[];
 }
 
+/**
+ * The replica identity CoreMail before 34 reports, read from the `COREMAIL_*` variables its
+ * provisioner fabricated.
+ *
+ * @deprecated CoreMail 34 and later report `IWorkloadReplicaIdentity`, which its runtime injects
+ * (`workloadReplicaIdentityEnvironmentNames`); `taskId` is that identity's `attemptId`.
+ * `normalizeCoreMailReplicaIdentity` still reads this shape, exactly, from a CoreMail before 34;
+ * removed in the next major.
+ */
 export interface ICoreMailReplicaIdentity {
   taskId: string;
   serviceId: string;
@@ -314,7 +327,11 @@ export interface ICoreMailBindingReconciliationStatus {
 }
 
 export interface ICoreMailReconciliationStatus {
-  replica: ICoreMailReplicaIdentity;
+  /**
+   * The reporting replica: `IWorkloadReplicaIdentity` from CoreMail 34 on, the deprecated
+   * `ICoreMailReplicaIdentity` from an earlier CoreMail. Each is read exactly.
+   */
+  replica: IWorkloadReplicaIdentity | ICoreMailReplicaIdentity;
   state: TCoreMailReconciliationState;
   appliedConfigEpoch: number;
   appliedDesiredStateDigest: TCoreMailSha256;
@@ -495,4 +512,28 @@ export const coreMailRuntimeKeys = Object.freeze({
   controlBootstrap: 'COREMAIL_CONTROL_BOOTSTRAP',
   controlCredentialSecret: 'COREMAIL_CONTROL_CREDENTIAL_SECRET',
   gatewayCredentialSecret: 'COREMAIL_GATEWAY_CREDENTIAL',
+  /** Optional listener port inside the workload. */
+  port: 'COREMAIL_PORT',
+  /** Optional comma-separated canonical hostname list. */
+  hostnames: 'COREMAIL_HOSTNAMES',
+  /** Optional MongoDB connection pool bound. */
+  mongoDbMaxPoolSize: 'COREMAIL_MONGODB_MAX_POOL_SIZE',
 } as const);
+
+/**
+ * The storage CoreMail 34 and later read, under the names its platform bindings deliver: the
+ * Corestore database binding's `MONGODB_URL` and `MONGODB_DATABASE`, the object-storage binding's
+ * `S3_ENDPOINT`, `S3_REGION` and `S3_BUCKET`, and that binding's `S3_ACCESS_KEY` and
+ * `S3_SECRET_KEY` secrets. They replace `COREMAIL_MONGODB_URL`, `COREMAIL_MONGODB_NAME`,
+ * `COREMAIL_STORAGE_DESCRIPTOR` and `COREMAIL_BUCKET_NAME`.
+ */
+export const coreMailStorageEnvironmentNames = Object.freeze({
+  databaseUrl: 'MONGODB_URL',
+  databaseName: 'MONGODB_DATABASE',
+  objectStorageEndpoint: 'S3_ENDPOINT',
+  objectStorageRegion: 'S3_REGION',
+  objectStorageBucket: 'S3_BUCKET',
+  objectStorageAccessKey: 'S3_ACCESS_KEY',
+  objectStorageSecretKey: 'S3_SECRET_KEY',
+} as const satisfies Readonly<Record<string,
+  TCorestoreDatabaseCredentialKey | TObjectStorageEndpointEnvironmentKey | TCorestoreObjectStorageCredentialSecretKey>>);

package/ts/data/delegatedadmintoken.ts

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

package/ts/data/gateway.ts

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

package/ts/data/index.ts

@@ -9,6 +9,7 @@ export * from './config.js';
 export * from './corestore.js';
 export * from './corestorecontroltoken.js';
 export * from './corestorelegacyadoption.js';
+export * from './delegatedadmintoken.js';
 export * from './coremail.js';
 export * from './coremail.runtime.js';
 export * from './deployment.js';
@@ -90,3 +91,4 @@ export * from './traffic.js';
 export * from './user.js';
 export * from './version.js';
 export * from './webpush.js';
+export * from './workloadreplicaidentity.js';

package/ts/data/mail.ts

@@ -338,6 +338,54 @@ export interface IServiceMailConfig {
 /** Caller-writable mail configuration. CoreMail binding metadata is excluded. */
 export type TServiceMailWritableConfig = Omit<IServiceMailConfig, 'coreMail'>;
 
+/**
+ * The environment names a service's default sender is delivered under, one spelling for the
+ * provisioners (Cloudly, Onebox) and the reader (`@serve.zone/platformclient`).
+ *
+ * Three groups, each delivered whole: the typed dcrouter-direct binding (`from`, `typedUrl`,
+ * `apiCredentialId`, `apiCredentialSecret`; `typedUrl` is `ICloudlySettings.dcrouterMailEndpointUrl`),
+ * its SMTP compatibility surface (`smtp*`), and a CoreMail binding (`coreMail*`, with `from`).
+ * `apiCredentialSecret`, `smtpPassword` and `coreMailCredentialSecret` are secrets and are
+ * delivered as secrets. Every further sender address uses the same names scoped to its address
+ * token (`createServiceMailAddressEnvironmentNames`).
+ */
+export const serviceMailEnvironmentNames = Object.freeze({
+  from: 'MAIL_FROM',
+  typedUrl: 'MAIL_TYPED_URL',
+  apiCredentialId: 'MAIL_API_CREDENTIAL_ID',
+  apiCredentialSecret: 'MAIL_API_CREDENTIAL_SECRET',
+  smtpHost: 'SMTP_HOST',
+  smtpPort: 'SMTP_PORT',
+  smtpTlsMode: 'SMTP_TLS_MODE',
+  smtpUsername: 'SMTP_USERNAME',
+  smtpPassword: 'SMTP_PASSWORD',
+  coreMailUrl: 'MAIL_COREMAIL_URL',
+  coreMailBindingId: 'MAIL_COREMAIL_BINDING_ID',
+  coreMailCredentialId: 'MAIL_COREMAIL_CREDENTIAL_ID',
+  coreMailCredentialVersionNumber: 'MAIL_COREMAIL_CREDENTIAL_VERSION',
+  coreMailCredentialSecret: 'MAIL_COREMAIL_CREDENTIAL_SECRET',
+} as const);
+
+export type TServiceMailEnvironmentNames = Readonly<Record<keyof typeof serviceMailEnvironmentNames, string>>;
+
+/**
+ * The names one further sender address is delivered under: each of `serviceMailEnvironmentNames`
+ * with `MAIL_<token>_` in place of its `MAIL_` prefix, or before it where it has none
+ * (`MAIL_<token>_FROM`, `MAIL_<token>_TYPED_URL`, `MAIL_<token>_SMTP_HOST`,
+ * `MAIL_<token>_COREMAIL_URL`). The token is the address's upper-case token
+ * (`^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$`); any other token is the caller's error and is thrown.
+ */
+export const createServiceMailAddressEnvironmentNames = (addressTokenArg: string): TServiceMailEnvironmentNames => {
+  if (typeof addressTokenArg !== 'string' || !/^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*$/.test(addressTokenArg)) {
+    throw new Error('service mail address token must be an upper-case address token');
+  }
+  const scoped: Record<string, string> = {};
+  for (const [key, name] of Object.entries(serviceMailEnvironmentNames)) {
+    scoped[key] = `MAIL_${addressTokenArg}_${name.startsWith('MAIL_') ? name.slice('MAIL_'.length) : name}`;
+  }
+  return Object.freeze(scoped) as TServiceMailEnvironmentNames;
+};
+
 export interface IServiceMailTargetAddressSummary {
   address: string;
   inbound: {

package/ts/data/runtimeassignment.ts

@@ -168,7 +168,10 @@ export type TRuntimeImagePullRefusalReason = typeof runtimeImagePullRefusalReaso
  * Why a node refused to start a run before any runtime effect of it, as the node names it:
  * `unsupported-readiness` a readiness probe the run's network cannot carry (a TCP or HTTP probe of
  * a run without network authority), `unresolved-authority` a workload authority the node cannot
- * resolve, and `invalid` an assignment or configuration the node cannot read.
+ * resolve, and `invalid` an assignment or configuration the node cannot read or cannot run as stated,
+ * such as a config environment that states a name the runtime injects
+ * (`composeWorkloadReplicaEnvironment` answering `workload-identity-environment-conflict`, a
+ * service-status reason only Cloudly states).
  */
 export const runtimeAssignmentRefusalReasons = ['unsupported-readiness', 'unresolved-authority', 'invalid'] as const;
 export type TRuntimeAssignmentRefusalReason = typeof runtimeAssignmentRefusalReasons[number];

package/ts/data/secret.ts

@@ -276,6 +276,44 @@ export type TSecretDelivery = ISecretLauncherEnvironmentDelivery | ISecretFileDe
 /** 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,

package/ts/data/serviceruntime.ts

@@ -93,7 +93,7 @@ const serviceRuntimeRefusals = [
   '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',
-  'cluster-relay-missing', 'cluster-ingress-environment-conflict',
+  'cluster-relay-missing', 'cluster-ingress-environment-conflict', 'workload-identity-environment-conflict',
 ] as const;
 
 /**
@@ -183,6 +183,19 @@ export type TServiceRuntimeWaitingReason = typeof serviceRuntimeWaitingReasons[n
  * `cluster-ingress-environment-conflict` is an ingress service whose own environment already sets
  * one of `clusterIngressEnvironmentNames`: Cloudly owns those names, and a service value would
  * otherwise silently replace Cloudly's or be replaced by it.
+ *
+ * `workload-identity-environment-conflict` is a service whose effective environment, or one of
+ * whose launcher-environment secrets, states one of `workloadReplicaIdentityEnvironmentNames`
+ * (`findWorkloadReplicaIdentityEnvironmentConflicts`): every runtime injects those names into every
+ * workload (`composeWorkloadReplicaEnvironment`), so a service value would silently replace the
+ * replica's identity or be replaced by it. Cloudly alone states it, and only in this status, which
+ * it stores and answers on `getServiceRuntimeSpec`, `getServiceRuntimeSpecForCluster` and
+ * `getServiceRuntimeSpecs`. Those requests carry no protocol offer, so the reason cannot be gated
+ * on a peer's version, and no other refusal names this check. A reader built before the release
+ * that added it refuses such a status whole, so every reader of 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 it: a Pallet whose composition refuses reports the run as the existing
+ * `TRuntimeAssignmentFailureCause` `refused` with `invalid`.
  */
 export type TServiceRuntimeRefusal = typeof serviceRuntimeRefusals[number];